From 4729e6e2ebdd1bb5009fbe1c58ba3c7dfd40c8e7 Mon Sep 17 00:00:00 2001 From: Jaron Rosenau Date: Sat, 1 Aug 2026 19:09:18 -0700 Subject: [PATCH 1/4] Add Handshake Resource Manifests HIP --- HIP-xxxx-HRM.md | 1128 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1128 insertions(+) create mode 100644 HIP-xxxx-HRM.md diff --git a/HIP-xxxx-HRM.md b/HIP-xxxx-HRM.md new file mode 100644 index 0000000..32782b5 --- /dev/null +++ b/HIP-xxxx-HRM.md @@ -0,0 +1,1128 @@ +# HIP-xxxx: Handshake Resource Manifests + +```text +Number: HIP-xxxx +Title: Handshake Resource Manifests +Type: Standards Track +Status: Draft +Authors: Jaron Rosenau <@denuoweb> +Created: 2026-08-01 +Related: HIP-0015, HIP-0016, Handshake P2P Rendezvous and + Authenticated Service Relay (draft HIP) +Follow-ons: Handshake IP and Routing Resource Profile (planned HIP) + Handshake Service and Transport Resource Profile (planned HIP) + Handshake Link and Overlay Resource Profile (planned HIP) +``` + +## Abstract + +This document specifies Handshake Resource Manifests (HRMs), an optional +protocol for binding a Handshake name to a signed, content-addressed description +of Internet resources, delegations, controller keys, and validity constraints. + +An HRM separates authorization from transport. Handshake authenticates a small +commitment published by the current name owner. The committed manifest may be +retrieved from any untrusted storage or transport. Resource-specific profiles +then determine whether a claimed resource was originated legitimately, whether +a child resource is contained by a parent resource, and which actions a +delegation permits. + +Version 1 uses ordinary Handshake `TXT` resource records and does not change +Handshake consensus, DNS resolution, covenant validation, or the interpretation +of any globally assigned number. It does not make an IP prefix routable, create +an Autonomous System Number (ASN), assign a port or protocol number, or replace +the policies of IANA, the Regional Internet Registries (RIRs), the IETF, or +IEEE. Globally coordinated resources require a proof profile rooted in an +authority already accepted for that resource. HNS-local overlay resources may +use profiles that explicitly permit origination by an HNS controller. + +The initial protocol is deliberately limited to a reusable manifest, +commitment, signature, delegation, and verification format. IPv4/IPv6, ASN, +routing, service, and link-layer semantics are specified by separate profiles. +This allows independent implementations to agree on the security boundary +before any HRM data is used to generate RPKI objects, routing policy, service +configuration, or other operational output. + +## Plain-language summary + +Handshake currently proves who controls a name. It does not provide a standard +way for that owner to say: + +```text +this key operates my network +this IPv6 prefix was legitimately delegated to me +this smaller prefix is delegated to this community +this service key may accept connections for this service +this authorization expires at this time +``` + +An HRM adds that common language. + +The name owner places a small hash on Handshake. The larger document is stored +elsewhere and can be copied by anyone. A client retrieves the document, checks +that its hash matches Handshake, verifies its controller signature, and then +verifies the authority proof or parent delegation for the resource it needs. + +The design has two important limits: + +1. Owning an HNS name does not prove ownership of an unrelated public IP + prefix, ASN, port, EtherType, or other externally coordinated resource. +2. A valid HRM is authorization evidence, not a command to a router, operating + system, certificate implementation, or network operator. + +Adapters may translate a successfully verified HRM into ordinary configuration, +but those adapters remain subject to local policy and the rules of the protocol +or registry they affect. + +## Motivation + +Internet resource control is recorded across many systems. IP prefixes and ASNs +are distributed hierarchically through IANA and the RIRs. Protocol parameters +are defined through IETF processes and recorded in IANA registries. Link-layer +identifiers may be coordinated by IEEE. Service keys, overlay identifiers, and +internal delegations are often kept in private databases. + +These systems solve different problems and should not be treated as one policy +domain. They nevertheless repeat several operational functions: + +- associate a resource with a controller; +- delegate a subset or a limited right; +- rotate operational keys; +- publish validity periods; +- revoke previous authority; +- provide an audit trail; +- expose current data to relying software. + +Handshake can provide a common, independently verifiable control plane for +those functions without redefining the resources carried in packet headers. +The desired division is: + +```text +resource policy and initial authority + | + v +recognized external proof or HNS-local origin rule + | + v +Handshake-anchored resource manifest + | + v +signed subdelegations and controller keys + | + v +opt-in adapters for RPKI, routing, services, overlays, and applications +``` + +This division is useful even if IANA, an RIR, IEEE, or another existing body +remains the source of the parent allocation. HRM can make later delegations +portable, auditable, and verifiable without requiring every resource holder to +operate a bespoke registry database or trusted API. + +## Scope + +This HIP defines: + +- an on-chain HRM commitment carried by an existing HNS `TXT` record; +- a deterministic CBOR envelope and payload; +- controller signatures; +- resource entries and stable resource identifiers; +- external, HNS-local, and parent-delegated authority modes; +- parent-to-child delegations; +- current-state, expiry, transfer, and revocation behavior; +- a profile interface for resource-specific validation; +- a verification algorithm and minimum implementation limits. + +This HIP does not define: + +- allocation policy for any existing public registry; +- a complete IPv4, IPv6, ASN, RPKI, BGP, port, protocol, TLS, or IEEE profile; +- transient peer routes or relay reservations; +- a mandatory storage or retrieval network; +- automatic router or operating-system configuration; +- an HNS consensus change or new namestate data version; +- a new Handshake P2P message, service bit, port, or protocol number; +- economic policy for allocating HNS-local resources. + +## Four-HIP program and dependency order + +This document is the first of four intended, independently reviewed HIPs. The +three companion HIPs are not optional sections of HRM Core and do not receive a +HIP number through this document. Each must be proposed, implemented, tested, +reviewed, and assigned its own number separately. + +```text +1. Handshake Resource Manifests (this HIP) + common commitment, envelope, controller, delegation, and validation + | + +--> 2. Handshake IP and Routing Resource Profile + | IPv4/IPv6, ASN, RPKI proofs, prefix containment, + | routing rights, and read-only routing adapters + | + +--> 3. Handshake Service and Transport Resource Profile + | service identifiers, TCP/UDP/QUIC bindings, TLS and + | WireGuard keys, endpoint rights, and HNSR authorization + | + +--> 4. Handshake Link and Overlay Resource Profile + virtual link identifiers, device/controller keys, + overlay segments, and explicitly scoped link-layer use +``` + +The companion HIPs stack on the data model and verification algorithm defined +here. They MUST NOT weaken HRM Core's distinction between an HNS-local resource +and an externally coordinated public resource. + +### Planned HIP 2: IP and routing + +The second HIP should define canonical IPv4, IPv6, and ASN resource encodings; +RPKI-based external origin proofs; prefix containment; routing and +subdelegation rights; proof refresh and revocation; and an audit-only adapter +that compares HRM results with current RPKI and registry state. + +It must not claim that an HNS name, auction, or transaction creates a routable +prefix or ASN. Any production route-generation behavior requires a later, +explicit deployment decision after multi-operator testing. + +### Planned HIP 3: Services and transports + +The third HIP should define HNS-local service identifiers, bindings to existing +TCP, UDP, QUIC, TLS, WireGuard, and similar transports, controller-key roles, +endpoint rights, and the relationship between long-lived HRM authority and +short-lived HNSR route records. + +It must distinguish HNS-local service identifiers from IANA-assigned ports, +protocol numbers, TLS parameters, and other public wire values. Use of a public +wire value requires an existing assignment or coordination with its responsible +standards community. + +### Planned HIP 4: Links and overlays + +The fourth HIP should define identifiers and delegations for explicitly opt-in +virtual links and overlay networks, including virtual segments, device or +controller keys, membership rights, and containment between overlay authorities. + +It must not reinterpret globally coordinated IEEE identifiers on ordinary +Ethernet. Any EtherType, OUI, or other public link-layer assignment must come +from the responsible registry or operate inside a formally assigned extension +space. + +The ordering above is a review sequence, not a requirement that every +implementation support every profile. An implementation may support HRM Core +and any accepted subset of companion profiles. + +## Requirements language + +The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, +**SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **NOT RECOMMENDED**, **MAY**, and +**OPTIONAL** in this document are to be interpreted as described in BCP 14 when, +and only when, they appear in all capitals. + +## Terminology + +**HNS name owner** +: The controller of the current Handshake name covenant output. + +**Subject** +: The Handshake name identified by the 32-byte name hash in an HRM. + +**Manifest controller** +: The key that signs the HRM payload. The manifest controller may be operationally + separate from the HNS name owner. + +**Commitment** +: The HRM `TXT` record in current authenticated Handshake namestate. It contains + the manifest sequence, envelope hash, and retrieval locators. + +**Envelope** +: Deterministic CBOR containing the encoded payload and its signature set. + +**Resource** +: An identifier or authority described by a resource profile. Examples may + include an IPv6 prefix, an ASN, an HNS-local service identifier, or an overlay + network identifier. + +**Resource profile** +: A separate specification that defines the canonical identifier, origination + proof, containment relation, rights, constraints, and adapter behavior for one + resource family. + +**Origin proof** +: Evidence accepted by a resource profile that starts an authority chain. It is + either an external proof rooted in a configured trust anchor or an HNS-local + origin explicitly permitted by the profile. + +**Parent delegation** +: A current entry in a valid parent HRM authorizing a child subject and + controller to exercise rights over a resource or valid subset. + +**Relying implementation** +: Software that validates HRMs or uses validated output. Examples include a + wallet, resolver, HNSR service, RPKI adapter, network controller, or auditor. + +## Trust model + +HRM has two independent authorization gates: + +```text +current HNS name owner commits the envelope hash + AND +manifest controller signs the committed payload +``` + +The current authenticated HNS commitment selects the exact envelope. Only the +current name owner can replace or remove that commitment. The controller +signature proves continuity of the operational key and allows parent +delegations to bind authority to a key rather than silently following a name +sale. + +Neither gate proves that a public resource originated legitimately. A resource +entry is valid only when its selected profile also validates one of: + +- an accepted external origin proof; +- an HNS-local origin rule defined by that profile; or +- a complete parent-delegation chain ending in one of those origins. + +A relying implementation chooses which profiles and external trust anchors it +accepts. Unsupported profiles and unrecognized proof types MUST fail closed. + +## Protocol overview + +Publishing an HRM consists of these steps: + +1. Construct a payload for one HNS subject. +2. Encode it using deterministic CBOR. +3. Sign the domain-separated payload with the manifest controller key. +4. Construct and deterministically encode the envelope. +5. Hash the complete envelope with SHA-256. +6. Store the envelope at one or more retrievable locations. +7. Publish an `hrm1` `TXT` commitment containing the sequence, hash, and + locators in the current HNS namestate. + +Verification reverses those steps: + +1. Authenticate current HNS namestate and select its current HRM commitment. +2. Retrieve an envelope from any advertised or locally discovered source. +3. Verify the envelope hash against the commitment. +4. Decode the envelope and payload using deterministic CBOR rules. +5. Match the subject, sequence, network, and validity interval. +6. Verify the controller signature. +7. Validate the requested resource using its selected profile. +8. Recursively validate any parent delegation to a recognized origin. +9. Apply local policy before producing operational output. + +## HNS commitment record + +### Existing namestate version + +Version 1 commitments use the existing version `0` Handshake resource data +format and its `TXT` record. This permits an HRM commitment to coexist with +ordinary `NS`, `DS`, glue, synthesis, and other supported Handshake records. + +This HIP does not allocate a new namestate data version under HIP-0015. A future +HIP may define a binary commitment if deployment experience shows that the +existing `TXT` representation is inadequate. + +### Record form + +An HRM commitment is one HNS `TXT` record whose first character-string is +exactly `hrm1` and whose remaining character-strings contain one field each. + +The diagnostic JSON form is: + +```json +{ + "type": "TXT", + "txt": [ + "hrm1", + "seq=7", + "hash=sha256:47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU", + "uri=https://registry.example/hrm/47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU" + ] +} +``` + +The example digest is illustrative and does not commit to a valid example +envelope. + +The fields are: + +`seq` +: An unsigned 64-bit decimal integer without leading zeroes, except that zero + is encoded as `0`. + +`hash` +: Exactly `sha256:` followed by the unpadded base64url encoding of the 32-byte + SHA-256 digest of the complete deterministic-CBOR envelope. + +`uri` +: A retrieval URI. At least one `uri` field MUST be present for a self-contained + publication. Additional `uri` fields MAY provide replicas. A relying + implementation MAY use an envelope learned out of band after matching its + hash. + +All commitment character-strings MUST contain printable ASCII. An individual +string MUST NOT exceed the existing HNS `TXT` string limit, and the complete +Handshake resource data MUST remain within the existing 512-byte consensus +limit. + +The order of `uri` fields has no security meaning. Unknown fields MUST be +ignored only when their key begins with `x-`. Any other unknown or duplicate +singleton field makes that commitment invalid. + +### Commitment selection + +A name SHOULD publish no more than one current `hrm1` record. + +If authenticated current namestate contains multiple syntactically valid +`hrm1` records, a verifier MUST select the record with the greatest `seq`. If +two records have the same greatest sequence and different hashes, the HRM state +is ambiguous and verification MUST fail closed. Duplicate records with the same +sequence and hash are equivalent; their locator sets MAY be combined. + +Sequence numbers are for cache invalidation and replay resistance. They are not +enforced by Handshake consensus. A publisher MUST increase `seq` for every new +envelope under a subject. A verifier that has previously accepted a greater +sequence at equal or greater chain work SHOULD reject a lower sequence unless +it has detected and accepted a Handshake reorganization according to local +finality policy. + +### Authenticated retrieval + +An ordinary unauthenticated DNS response containing an HRM commitment is not +sufficient. The relying implementation MUST authenticate the record using one +of: + +- locally validated Handshake full-node state; +- a Handshake light-client name proof anchored in accepted chain headers; or +- DNSSEC validation anchored in a locally accepted Handshake root trust path. + +The retrieval URI and retrieval server are untrusted. Integrity comes from the +on-chain envelope hash, not from HTTPS, a gateway, a relay, or a content host. + +## Deterministic CBOR + +The envelope and payload MUST use deterministic CBOR as specified by RFC 8949, +Section 4.2, with these additional restrictions: + +- maps MUST use the integer keys assigned by this document or a profile; +- map keys MUST be unique; +- indefinite-length items MUST NOT be used; +- floating-point values MUST NOT be used; +- text strings MUST be valid UTF-8; +- profile identifiers MUST contain only lowercase ASCII letters, digits, + hyphen, period, and slash; +- decoders MUST reject trailing data after the top-level CBOR item; +- an encoder MUST produce the preferred serialization of every integer and + length. + +An implementation MUST re-encode a decoded object and compare it byte-for-byte +with the received encoding before treating it as canonical. This prevents two +encodings of the same logical object from producing different security +interpretations. + +## Envelope format + +The envelope is the following CBOR map: + +| Key | Name | Type | Required | Meaning | +| ---: | --- | --- | :---: | --- | +| `0` | `payload` | byte string | yes | Complete deterministic-CBOR payload | +| `1` | `signatures` | array | yes | One or more signature objects | + +A version 1 envelope MUST contain no other top-level keys. + +Each signature object is a CBOR map: + +| Key | Name | Type | Required | Meaning | +| ---: | --- | --- | :---: | --- | +| `0` | `algorithm` | unsigned integer | yes | Signature algorithm identifier | +| `1` | `public_key` | byte string | yes | Encoded public key | +| `2` | `signature` | byte string | yes | Signature bytes | + +Version 1 assigns algorithm `1` to deterministic secp256k1 ECDSA. For algorithm +`1`, `public_key` MUST be a valid compressed 33-byte secp256k1 public key and +`signature` MUST use strict DER encoding with low-S normalization. Unknown +algorithms MUST NOT be accepted as satisfying a required controller signature. + +The signature digest is: + +```text +BLAKE2b-256( + ASCII("HNS-HRM-v1") || 0x00 + || network_magic_u32le + || payload +) +``` + +`network_magic_u32le` is the four-byte little-endian encoding of the active +Handshake network magic. This prevents a signature created for mainnet, +testnet, regtest, or another configured network from being replayed as valid on +a different network. + +The envelope MUST contain a valid signature made by the controller key declared +in the payload. Extra signatures MAY be present for transition experiments but +have no version 1 authority unless a resource profile assigns them meaning. + +## Payload format + +The payload is a CBOR map: + +| Key | Name | Type | Required | Meaning | +| ---: | --- | --- | :---: | --- | +| `0` | `version` | unsigned integer | yes | Must equal `1` | +| `1` | `subject` | byte string | yes | 32-byte Handshake name hash | +| `2` | `sequence` | unsigned integer | yes | Must equal commitment `seq` | +| `3` | `issued_at` | unsigned integer | yes | Unix time in seconds | +| `4` | `expires_at` | unsigned integer | yes | Unix time in seconds | +| `5` | `controller` | map | yes | Algorithm and public key | +| `6` | `resources` | array | yes | Resource entry objects | +| `7` | `delegations` | array | yes | Delegation objects | +| `8` | `extensions` | map | no | Profile-defined, non-critical data | + +`subject` MUST equal the consensus Handshake name hash for the name from which +the commitment was obtained. + +`issued_at` MUST be less than `expires_at`. A verifier MUST reject the payload +before `issued_at` or at and after `expires_at`, subject to a locally configured +clock-skew allowance. Profiles MAY impose shorter maximum lifetimes. + +`controller` is a CBOR map with key `0` containing the signature algorithm and +key `1` containing the public key. Version 1 requires algorithm `1` and a valid +compressed 33-byte secp256k1 public key. + +`resources` and `delegations` are complete current snapshots. Removing an entry +and publishing a greater sequence revokes that entry after the new Handshake +state reaches the verifier's required finality. + +## Resource entries + +A resource entry is a CBOR map: + +| Key | Name | Type | Required | Meaning | +| ---: | --- | --- | :---: | --- | +| `0` | `profile` | text string | yes | Resource-profile identifier | +| `1` | `resource_id` | byte string | yes | 32-byte stable identifier | +| `2` | `identifier` | byte string | yes | Profile-defined canonical resource | +| `3` | `authority` | map | yes | Origin or parent authority object | +| `4` | `not_before` | unsigned integer | yes | Earliest valid Unix time | +| `5` | `expires_at` | unsigned integer | yes | Exclusive expiry Unix time | +| `6` | `attributes` | map | no | Profile-defined attributes | + +The profile MUST define: + +- canonical encoding of `identifier`; +- calculation and validation of `resource_id`; +- whether HNS-local origination is permitted; +- accepted external authority proof types; +- the subset or containment relation; +- recognized rights and constraints; +- maximum validity periods; +- whether multiple simultaneous authorities are meaningful; +- behavior expected from operational adapters. + +The resource validity interval MUST be contained by the payload validity +interval. An implementation MUST NOT assign semantics to an unknown profile. + +### Authority objects + +The `authority` map has key `0`, `kind`, with one of these values: + +| Kind | Name | Meaning | +| ---: | --- | --- | +| `0` | HNS-local origin | The profile permits controller origination | +| `1` | External origin | An external proof establishes origin authority | +| `2` | Parent delegation | A current HRM delegates the resource | + +#### HNS-local origin + +An HNS-local authority object is `{0: 0}`. + +It is valid only if the selected resource profile explicitly permits HNS-local +origination and derives a collision-resistant namespace from the subject name +hash and controller key. A public IPv4 prefix, IPv6 prefix, ASN, IANA protocol +number, IANA port, or IEEE EtherType MUST NOT be originated this way. + +#### External origin + +An external authority object contains: + +| Key | Name | Type | Required | +| ---: | --- | --- | :---: | +| `0` | `kind` | unsigned integer equal to `1` | yes | +| `1` | `proof_profile` | text string | yes | +| `2` | `proof_hash` | 32-byte string | yes | +| `3` | `proof_uris` | array of text strings | yes | + +`proof_hash` is the SHA-256 digest of the exact external proof object. The proof +may be retrieved from any source. The resource profile defines its format, +trust anchors, revocation behavior, and how it binds the resource, subject, +controller key, and validity interval. + +Merely displaying matching RDAP, WHOIS, registry, or web-page text MUST NOT be +treated as a cryptographic origin proof unless a future profile defines and +secures that exact trust model. + +#### Parent delegation + +A parent-delegation authority object contains: + +| Key | Name | Type | Required | +| ---: | --- | --- | :---: | +| `0` | `kind` | unsigned integer equal to `2` | yes | +| `1` | `parent_subject` | 32-byte string | yes | +| `2` | `parent_resource_id` | 32-byte string | yes | +| `3` | `delegation_id` | 32-byte string | yes | + +The verifier MUST retrieve and validate the current HRM for `parent_subject`, +validate `parent_resource_id`, and locate the current `delegation_id`. The +parent delegation must exactly authorize the child subject, child controller, +child resource, requested right, and current time. + +## Delegations + +A delegation object is a CBOR map: + +| Key | Name | Type | Required | Meaning | +| ---: | --- | --- | :---: | --- | +| `0` | `delegation_id` | byte string | yes | 32-byte identifier | +| `1` | `parent_resource_id` | byte string | yes | Controlled parent resource | +| `2` | `child_profile` | text string | yes | Child resource profile | +| `3` | `child_resource_id` | byte string | yes | Child resource identifier | +| `4` | `child_identifier` | byte string | yes | Canonical child resource | +| `5` | `child_subject` | byte string | yes | 32-byte child HNS name hash | +| `6` | `child_controller` | map | yes | Required child algorithm and key | +| `7` | `rights` | array of text strings | yes | Profile-defined rights | +| `8` | `not_before` | unsigned integer | yes | Earliest valid Unix time | +| `9` | `expires_at` | unsigned integer | yes | Exclusive expiry Unix time | +| `10` | `may_subdelegate` | boolean | yes | Child may delegate further | +| `11` | `constraints` | map | no | Profile-defined restrictions | + +The delegation interval MUST be contained by both the payload interval and the +parent resource interval. The child resource MUST be equal to or a valid subset +of the parent resource according to the parent profile. Cross-profile +delegation is invalid unless the parent profile explicitly defines the mapping. + +`child_controller` uses the same algorithm/key map as the payload controller. +Binding the delegation to both `child_subject` and `child_controller` prevents a +sale or compromise of only one identity component from silently transferring +the delegated resource. + +The profile defines the canonical calculation of `delegation_id`. It SHOULD be +the SHA-256 digest of a domain-separated deterministic encoding of every +security-relevant delegation field except `delegation_id` itself. + +Removing the delegation from a later parent manifest revokes it. A child copy +of an older delegation never overrides current parent state. + +## Name ownership, transfer, and key rotation + +An HRM binds a current HNS commitment and a manifest controller key. They serve +different purposes: + +- the HNS owner chooses which envelope is current; +- the controller signs the resource state; +- a parent delegation may require that exact controller key. + +Ordinary HNS `UPDATE`, `RENEW`, and `TRANSFER` processing does not invalidate an +otherwise current HRM when the exact commitment remains in current namestate. +This matches ordinary DNS-resource continuity and the HNSR root-key model. A new +name owner can remove the commitment, but cannot forge a replacement under the +existing controller key. + +A name transfer alone does not give the new owner an externally originated or +parent-delegated resource. Those authority chains remain bound to the manifest +controller. The new owner can leave that controller's exact committed manifest +available or withdraw it, but cannot change its signed contents. + +An HNS-local profile MAY define a resource as following current control of the +HNS name. A profile requiring transfer-sensitive invalidation MUST define the +extra binding and its validation rule explicitly; HRM Core does not infer +external resource ownership from a name transfer. + +Controller-key rotation has the same rule: HNS-local resources may select a new +controller through a new owner-committed envelope, but external and +parent-delegated resources require a refreshed proof or parent delegation that +binds the new controller. + +If the Handshake name is revoked, expired, or has no current owner, its HRM is +invalid. + +## Verification algorithm + +To authorize action `A` over resource `R` for subject `S`, a version 1 verifier +MUST perform the following steps. + +1. Obtain authenticated current Handshake namestate for `S` under a locally + accepted chain-finality policy. +2. Confirm the name has a current owner and is not revoked or expired. +3. Parse all `hrm1` commitment records and select the current commitment. +4. Retrieve an envelope whose SHA-256 digest matches the commitment. +5. Enforce deterministic CBOR and all envelope structural limits. +6. Decode the payload and confirm: + 1. `version` is `1`; + 2. `subject` equals `S`; + 3. `sequence` equals commitment `seq`; + 4. the signature is evaluated with the active network magic; + 5. the payload is currently within its validity interval. +7. Verify the required controller signature over the exact payload bytes. +8. Locate `R`, reject duplicate resource identifiers, and validate its profile, + canonical identifier, resource identifier, attributes, and validity. +9. Validate its authority: + 1. for HNS-local origin, confirm the profile permits origination and derives + the resource namespace correctly; + 2. for external origin, retrieve and verify the exact proof under configured + trust anchors and current revocation state; + 3. for parent delegation, recursively validate the current parent resource + and exact current delegation. +10. Confirm every link authorizes action `A`, every child is contained by its + parent, every time interval is contained by its parent, and every required + constraint is satisfied. +11. Apply local operational policy before returning authorization. + +A verifier MUST detect subject/resource cycles. It MUST impose a recursion limit +of no more than 32 parent links and SHOULD permit operators to configure a lower +limit. A cycle, exceeded limit, unavailable required parent, ambiguous state, +unknown critical profile, failed proof, or expired link MUST fail closed. + +## Current state and revocation + +HRM is a current-state protocol. Handshake history provides an audit trail but +does not keep removed authority active. + +To revoke a resource or delegation, the publisher increments the sequence, +removes the entry from the complete snapshot, signs the new payload, publishes +the new envelope, and updates the commitment. The revocation takes effect for a +verifier when that verifier accepts the new Handshake state under local finality +policy. + +Short emergency expiry periods can reduce exposure when a publisher cannot +immediately update the chain. Resource profiles SHOULD define maximum validity +periods appropriate to their operational risk. + +A verifier MAY cache a successful result only until the earliest of: + +- payload expiry; +- resource expiry; +- delegation expiry; +- external-proof expiry or revocation refresh; +- locally configured cache limit; +- observation of a new commitment or relevant Handshake reorganization. + +## Availability and retrieval + +Handshake commits to HRM integrity but does not guarantee delivery of the +envelope or external proofs. + +Publishers SHOULD provide multiple independent locators. Content-addressed +storage, HTTPS, HNSR, peer-to-peer storage, local operator mirrors, or other +transports MAY be used. A mirror does not need publisher permission because the +committed hash authenticates the bytes. + +Failure to retrieve a current required object means the authorization is +unavailable and MUST NOT be treated as valid. An implementation MUST NOT fall +back to an older envelope merely because the current object cannot be fetched. + +Transient HNSR route records, relay reservations, live socket addresses, and +similar presence data SHOULD NOT be placed in HRM. HRM establishes longer-lived +controller and resource authority; a rendezvous protocol may use that authority +to authenticate its own short-lived records. + +## Resource profiles + +Profiles are separate specifications so a defect or policy dispute in one +resource family does not redefine the HRM core. + +A profile specification MUST provide: + +1. A stable lowercase profile identifier. +2. Canonical resource encoding. +3. Resource-ID calculation. +4. Origin modes and accepted proof profiles. +5. Parent-child containment rules. +6. Rights, constraints, and subdelegation rules. +7. Time and expiry requirements. +8. Conflict and multiple-origin behavior. +9. At least one positive and negative deterministic test vector. +10. Security, privacy, and operational-adapter considerations. + +The planned companion HIPs are expected to define profiles including: + +`hns.overlay.service/v1` +: HNS-local, collision-resistant service identifiers and controller keys. + +`hns.overlay.network/v1` +: HNS-local identifiers for explicitly opt-in virtual networks. + +`rpki.ip-prefix/v1` +: IPv4/IPv6 resources rooted in a cryptographically validated RPKI proof, with + canonical prefix containment and subdelegation. + +`rpki.asn/v1` +: ASN authority rooted in an accepted RPKI proof. + +`hnsr.service/v1` +: Longer-lived authorization keys and rights consumed by HNSR named-service + rendezvous. Short-lived HNSR routes remain in HNSR. + +Names above are illustrative and are not allocated by this HIP. The three +companion documents identified in the four-HIP program must assign their exact +profile identifiers and semantics. + +## Operational adapters + +An adapter consumes a verified HRM result and produces output for another +system. Examples might include: + +- a proposed RPKI certificate or routing authorization; +- a BGP import-policy input; +- a network-controller configuration fragment; +- an HNSR named-service authorization; +- a WireGuard or TLS trust configuration; +- an overlay network membership decision; +- an audit report comparing HRM and an existing registry. + +Version 1 adapters MUST be opt-in and SHOULD default to audit or dry-run mode. +An adapter MUST NOT treat an HNS commitment alone as authority over a public +resource. It MUST report the complete validated proof chain and the local policy +decision that caused operational output. + +No adapter should directly change public routing, filtering, certificate trust, +or another security-sensitive system without an additional operator policy and +an explicit deployment specification. + +## Security considerations + +### False public-resource claims + +Any HNS owner can publish arbitrary bytes. Therefore an HRM without a valid +profile-specific authority chain is only a claim. Public-resource profiles MUST +validate a recognized external origin or complete parent delegation. + +### Name squatting + +Similarity between an HNS name and an organization, registry entry, domain, or +resource label does not establish authority. Validation is based on the +resource proof chain, not human-readable resemblance. + +### Name transfer + +An unchanged commitment may survive a name transfer, but externally originated +and parent-delegated authority remains bound to the manifest controller. The new +name owner may withdraw the manifest and cause denial of service; it cannot +alter the signed state or satisfy a controller-bound authority chain. HNS-local +profiles must state explicitly whether their resources follow the name. + +### Controller compromise + +A compromised controller can sign malicious manifests only if the HNS owner +also commits them, but an entity may operate both keys. Publishers SHOULD keep +the HNS owner key and manifest controller key in separate security domains. +High-risk profiles SHOULD use short expiry and explicit recovery procedures. + +### HNS owner compromise + +A compromised name owner can withdraw or replace the commitment and cause +denial of service. It cannot satisfy a controller-bound parent delegation or +external proof without the required controller authority. Operational systems +must nevertheless plan for the resulting unavailability. + +### Replay and rollback + +Sequence, current authenticated namestate, validity intervals, and local +chain-finality policy limit replay. Implementations must distinguish a genuine +Handshake reorganization from an envelope replay at equal or lower chain work. + +### Locator equivocation + +Locators may return different bytes, track clients, refuse service, or serve +malware. Hash validation prevents undetected content substitution but not +denial of service or metadata collection. + +### External proof revocation + +An unchanged HRM may outlive an external allocation or proof. Every external +profile MUST define current revocation and refresh behavior. A cached HRM result +must not outlive the proof state on which it depends. + +### Delegation cycles and exhaustion + +Attackers may construct cycles, deep graphs, large manifests, repeated +locators, or expensive proof chains. Implementations MUST bound object size, +retrieval count, redirects, total bytes, signature operations, recursion depth, +and validation time. + +Suggested default limits for an initial implementation are: + +| Item | Default maximum | +| --- | ---: | +| Envelope bytes | 1 MiB | +| Resources per manifest | 1,024 | +| Delegations per manifest | 4,096 | +| Locators attempted per object | 4 | +| Parent depth | 16 | +| Total fetched objects per decision | 64 | +| Total fetched bytes per decision | 8 MiB | + +Implementations MAY impose smaller limits. A profile requiring larger values +must justify them explicitly. + +### Parser differentials + +Security depends on independent implementations hashing and interpreting the +same bytes identically. Deterministic CBOR restrictions, byte-for-byte +re-encoding, strict profile canonicalization, and shared negative test vectors +are REQUIRED before a profile is used for operational authorization. + +### Unsafe automation + +A cryptographically valid statement can still violate an operator's business, +safety, routing, or abuse policy. HRM validation and operational acceptance are +separate decisions. Adapters must preserve that boundary. + +## Privacy considerations + +HRMs are public or publicly retrievable metadata. They may reveal network +structure, customer relationships, service inventory, controller rotation, +organizational hierarchy, and planned expiry times. + +Publishers SHOULD disclose only information needed for verification. Private +addresses, personal device identifiers, internal topology, transient routes, +and individual customer data SHOULD NOT be published unless the profile and +participants explicitly accept that disclosure. + +Retrieval can reveal which resource a client is interested in. Mirrors, +content-addressed caches, privacy relays, or locally synchronized datasets may +reduce that leakage. + +## Backwards compatibility + +This proposal uses existing valid HNS version `0` resource data and `TXT` +records. Legacy HNS nodes, miners, resolvers, and wallets require no consensus +change and may ignore `hrm1` records. + +HRM-aware software is an optional consumer. Names may continue using ordinary +DNS records. The 512-byte HNS resource limit remains unchanged. + +An implementation MUST NOT reinterpret unrelated TXT records as HRM data. Only +a record beginning with the exact `hrm1` marker is in scope. + +## Relationship to HIP-0015 and HIP-0016 + +HIP-0015 describes Handshake name updates as authenticated update chains and +allows future application-defined namestate versions. HRM uses the same general +idea of an HNS name anchoring changing application state, but version 1 remains +inside the existing DNS resource format for compatibility. + +HIP-0016 demonstrates how an off-chain authenticated data structure may commit +its root through HNS while light clients verify selected data. A future HRM +scaling proposal may replace the single-envelope snapshot with a provable map +or accumulator. That is not required for HRM version 1. + +## Relationship to HNSR + +The draft Handshake P2P Rendezvous and Authenticated Service Relay protocol +defines short-lived discovery and relay routes. HRM and HNSR are independent: + +```text +HRM + who controls a resource or long-lived service authority + +HNSR + where an authorized endpoint is reachable right now +``` + +A future `hnsr.service/v1` profile may allow HNSR to consume HRM controller and +delegation proofs. HRM does not require HNSR for retrieval, and HNSR does not +require HRM for unnamed node rendezvous. + +## Implementation plan + +The first reference implementation should be a small library and CLI, not a +consensus patch. + +Recommended components are: + +1. A Rust crate that encodes, signs, decodes, and validates HRM Core objects. +2. A command-line tool with `create`, `sign`, `publish`, `fetch`, `inspect`, and + `verify` operations. +3. An HNS adapter that reads and writes the version `0` commitment record. +4. Deterministic positive and negative vectors shared with a JavaScript + implementation. +5. A first HNS-local overlay-service profile. +6. A read-only experimental IP-prefix profile that compares HRM results with + existing RPKI state and never changes routing. + +`hsd` and `hnsd` need no consensus modification for the core experiment. Wallet +support may improve publication ergonomics but is not required for validation. + +## Deployment gates + +HRM should advance in independently reviewed stages. + +### Stage 0: Core vectors + +- finalize CBOR encodings; +- publish controller-signature and commitment vectors; +- test malformed and non-canonical inputs across implementations. + +### Stage 1: HNS-local pilot + +- use only identifiers whose profiles are explicitly scoped to opt-in HNS + overlays; +- test owner transfer, controller rotation, revocation, expiry, reorganization, + data loss, and parent delegation; +- run on regtest and testnet before mainnet publication. + +### Stage 2: Multi-operator retrieval + +- replicate envelopes over independent transports; +- measure availability, latency, cache behavior, and denial-of-service cost; +- perform independent security review. + +### Stage 3: External-resource audit + +- use legitimately allocated test resources; +- validate but do not originate routing or registry changes; +- compare HRM delegation results with RPKI and registry state; +- document conflicts and revocation latency. + +### Stage 4: Profile and adapter proposals + +- submit each operational profile separately; +- require multi-operator evidence and negative test vectors; +- coordinate any wire-level assignment with the responsible standards and + registry community; +- keep production-changing adapters opt-in until their own threat models and + rollback procedures are accepted. + +No permanent IANA, IEEE, HNS P2P, or other wire assignment is requested by this +HIP. + +## Test requirements + +Before this proposal can move beyond Draft, the repository should contain +deterministic vectors covering at least: + +- canonical payload and envelope encoding; +- valid and invalid deterministic secp256k1 controller signatures; +- commitment-hash match and mismatch; +- HNS subject and active-network match and mismatch; +- commitment/payload sequence match and mismatch; +- selection among multiple commitments; +- equal-sequence conflicting commitments; +- payload, resource, and delegation expiry; +- name transfer with commitment retention, removal, and replacement; +- controller-key mismatch; +- valid one-level and multi-level delegation; +- invalid containment, rights escalation, and forbidden subdelegation; +- missing and revoked parent delegation; +- cycle and recursion-limit rejection; +- valid and invalid external proof stubs; +- corrupt, unavailable, and equivocating retrieval sources; +- accepted and rejected Handshake reorganization cases. + +External-resource profiles require their own additional vectors. + +## Rationale + +### Why use an on-chain hash instead of placing the manifest on chain? + +Handshake resource data is limited to 512 bytes. Internet resource proofs, +delegation graphs, certificates, and metadata can be substantially larger. +Committing only a hash keeps consensus state bounded and allows untrusted +replication. + +### Why use `TXT` instead of a new namestate version? + +`TXT` works under current consensus and can coexist with ordinary name +resolution. A new version would require ecosystem coordination before the core +security model has deployment evidence. + +### Why require a controller signature when HNS already commits the hash? + +The second key separates durable name custody from operational resource control +and gives parent delegations a stable cryptographic target. It also prevents a +name transfer alone from silently acquiring delegated infrastructure authority. +Version 1 uses the same key and signature family as the draft HNSR protocol so +an HRM service profile can reuse an existing HNSR root key. + +### Why not accept any resource claimed by an HNS owner? + +Many public resources already have globally coordinated meanings. Treating an +HNS auction as ownership of an existing IP prefix, ASN, port, protocol number, +or EtherType would create collisions that browsers and application gateways +cannot repair. + +### Why separate resource profiles? + +An IPv6 prefix has containment semantics; an ASN usually does not. A port has +different policy and operational consequences from a virtual service ID. A +single generic validator cannot safely guess these rules. + +### Why make manifests complete snapshots? + +Current snapshots make removal an unambiguous revocation and avoid requiring a +client to replay an unbounded off-chain log. Handshake history remains +available for auditing. + +## Alternatives considered + +### Independently allocate public wire values through HNS + +Rejected for HRM Core. Existing routers, switches, kernels, and protocol +implementations require coordinated meanings. HNS-local profiles may allocate +values only inside explicit overlays or formally delegated extension spaces. + +### Store unverified claims in plain TXT records + +Rejected as an authorization protocol. Plain text is useful for discovery but +does not define canonical encoding, controller continuity, authority proofs, +delegation containment, expiry, or revocation. + +### Put every resource and delegation directly on Handshake + +Rejected for version 1 because of the 512-byte limit, chain growth, privacy, +proof size, and the burden placed on unrelated full nodes. + +### Require a single HRM storage network + +Rejected. Content addressing makes storage replaceable. Mandating one delivery +network would recreate the availability dependency HRM is intended to avoid. + +### Make HRM immediately authoritative for router configuration + +Rejected. Verification formats, external trust roots, operational policy, +rollback, and multi-operator experience must be established first. + +## Open questions + +The following items should be resolved during Draft review: + +- whether a later version should register Ed25519 or another optional controller + algorithm in addition to mandatory secp256k1; +- whether one retrieval URI should be required or out-of-band retrieval should + be valid without an advertised URI; +- whether a future compact binary commitment should replace or supplement TXT; +- exact default clock-skew and Handshake-finality guidance; +- registry and review process for resource-profile identifiers; +- whether controller rotation should gain a cross-signature mechanism in Core; +- which HNS-local profile is small enough to serve as the first complete pilot; +- whether future selective disclosure should use an authenticated map based on + HIP-0016, another accumulator, or independent signed objects. + +## References + +1. RFC 2119, *Key words for use in RFCs to Indicate Requirement Levels*. +2. RFC 8174, *Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words*. +3. RFC 8949, *Concise Binary Object Representation (CBOR)*. +4. RFC 4648, *The Base16, Base32, and Base64 Data Encodings*. +5. RFC 7020, *The Internet Numbers Registry System*. +6. RFC 6480, *An Infrastructure to Support Secure Internet Routing*. +7. RFC 9323, *A Profile for RPKI Signed Checklists (RSCs)*. +8. RFC 8126, *Guidelines for Writing an IANA Considerations Section in RFCs*. +9. HIP-0015, *Update Chains*. +10. HIP-0016, *Escher Update Chains for decentralized subdomains*. +11. Draft HIP, *Handshake P2P Rendezvous and Authenticated Service Relay*. +12. Handshake developer documentation, *Resource Records*. +13. IANA, *Governance of the IANA Functions*. +14. IANA, *Number-related Registries*. +15. IANA, *Protocol Parameter Assignments*. From c0487e5af779158cbef0591ac363b7e956255c7d Mon Sep 17 00:00:00 2001 From: Jaron Rosenau Date: Sat, 1 Aug 2026 19:43:57 -0700 Subject: [PATCH 2/4] Narrow HIP to named service authority --- HIP-xxxx-HNSA.md | 924 +++++++++++++++++++++++++++++++++++++ HIP-xxxx-HRM.md | 1128 ---------------------------------------------- 2 files changed, 924 insertions(+), 1128 deletions(-) create mode 100644 HIP-xxxx-HNSA.md delete mode 100644 HIP-xxxx-HRM.md diff --git a/HIP-xxxx-HNSA.md b/HIP-xxxx-HNSA.md new file mode 100644 index 0000000..25340f7 --- /dev/null +++ b/HIP-xxxx-HNSA.md @@ -0,0 +1,924 @@ +# HIP-xxxx: Named Service Authority for Handshake + +```text +Number: HIP-xxxx +Title: Named Service Authority for Handshake +Type: Standards Track +Status: Draft +Authors: Jaron Rosenau <@denuoweb> +Created: 2026-08-01 +Related: Handshake P2P Rendezvous and Authenticated Service Relay + (draft HIP) +``` + +## Abstract + +This document specifies Handshake Named Service Authority (HNSA), an optional +protocol that allows the owner of a Handshake name to authorize separate keys +for named application services without transferring the name or exposing its +wallet key to an online service. + +A name opts in by publishing one service-authority root key and epoch in its +existing HNS `TXT` resource data. The root key signs bounded service +authorizations. A service key may then authorize short-lived endpoint keys used +by a transport or discovery profile such as HNSR, direct QUIC, HTTPS, messaging, +or another HNS-aware application. + +The authority chain is: + +```text +current authenticated HNS name state + | + v +service-authority root key and epoch + | + v +root-signed named service authorization + | + v +service-signed endpoint delegation + | + v +profile-specific endpoint or route record +``` + +HNSA defines identity and delegation, not transport. It does not define relay +routing, DNS resolution, HTTP framing, browser UI, IP-address allocation, +routing policy, or a general registry for non-service resources. Those concerns +remain in the service profile or protocol that consumes the authorization. + +Version 1 uses current Handshake resource records and requires no consensus +change, hard fork, new namestate version, permanent P2P message assignment, or +new public Internet number. + +## Plain-language summary + +An HNS name is normally controlled by a wallet key that should remain private +and mostly offline. A website, chat service, mobile endpoint, or hosting +provider needs a different key that can be used by online software. + +HNSA gives the name owner a standard way to say: + +```text +this root key may authorize services for my HNS name +this service key operates my web service +these endpoint keys may serve that service for a limited time +``` + +A client retrieves those signed objects from any discovery mechanism and +verifies the complete chain against current HNS name state. A relay, hosting +provider, directory, or endpoint cannot substitute its own service key without +an authorization from the HNS name. + +## User stories + +### Mobile or home hosting + +As the owner of `alice/`, Alice authorizes a `web` service key and one or more +endpoint keys for her phone, home server, and optional VPS. An HNS-aware browser +can reach any currently available endpoint while treating them as the same +named service. + +### Provider delegation + +Alice authorizes a hosting provider to operate `web` without giving the provider +her HNS wallet key or control of `alice/`. She can replace the provider by +publishing a new service authorization under her service-authority root. + +### Key rotation after compromise + +Alice replaces a compromised service key while keeping the HNS name and browser +identity unchanged. Clients reject endpoint records that do not lead to a +currently valid service authorization. + +### Multiple services under one name + +Alice authorizes `web`, `chat`, and `files` with independent keys, profiles, and +lifetimes. Compromise or migration of one service does not require rotating the +keys for every other service or transferring the HNS name. + +### Stable browser identity + +A user opens an HNS service whose direct address, relay, or provider has +changed. The browser preserves the same origin and permissions because identity +is based on the HNS name, service name, and profile rather than the selected +network path. + +## Motivation + +Handshake authenticates root names and DNS resource data. It does not currently +provide an implementation-independent authorization format for application +services operated beneath those names. + +Without a separate service-authority layer, an application tends to choose one +of these designs: + +- use the name wallet key directly in online service software; +- invent a new TXT key format for every application; +- trust the endpoint returned by a directory or relay; +- equate an IP address or hosting account with service identity; +- place provider-specific credentials in name data; +- define a complete authorization chain inside each transport proposal. + +These approaches either expose durable name custody, duplicate security rules, +or bind identity to infrastructure that changes more frequently than the HNS +name. + +HNSA introduces two deliberate delegation boundaries: + +```text +name custody service operation +HNS wallet -> root key root key -> service key + +service operation endpoint reachability +service key -> endpoint key endpoint key -> route or transport record +``` + +The name wallet only needs to update HNS when the root key or authority epoch +changes. The root key may remain offline and sign relatively long-lived service +authorizations. Service keys and endpoint keys can rotate on shorter schedules +without exposing the name wallet. + +## Scope + +This HIP defines: + +- a canonical HNS `TXT` record for the service-authority root key and epoch; +- canonical service names; +- the stable identity tuple for a named service; +- `ServiceAuthorizationV1`; +- `EndpointDelegationV1`; +- signature domains and canonical encodings; +- expiry, sequence, replacement, and emergency revocation behavior; +- validation rules and implementation limits; +- the interface between HNSA and service profiles; +- browser-origin and permission requirements for profile specifications. + +This HIP does not define: + +- an endpoint discovery or storage network; +- HNSR rendezvous, relay tickets, circuits, or transport frames; +- DNS, HTTP, TLS, QUIC, WireGuard, or messaging wire behavior; +- an application-specific endpoint record; +- a generic Internet resource manifest; +- IP prefixes, ASNs, RPKI, BGP, ports, protocol numbers, or EtherTypes; +- automatic operating-system or network configuration; +- allocation policy or economic rules for services; +- unnamed Handshake peer authority. + +## Requirements language + +The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, +**SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **NOT RECOMMENDED**, **MAY**, and +**OPTIONAL** in this document are to be interpreted as described in BCP 14 when, +and only when, they appear in all capitals. + +## Terminology + +**HNS name owner** +: The controller of the current Handshake name covenant output. + +**Root key** +: The service-authority key committed in current authenticated HNS name data. + It signs service authorizations and should normally remain offline. + +**Authority epoch** +: An integer in current HNS name data. Changing it invalidates all service + authorizations issued under a previous epoch, even if the root key is reused. + +**Named service** +: An application service identified by an HNS name hash, canonical service + name, and profile ID. + +**Service key** +: A profile-specific operational key authorized by the root key for exactly one + named service. + +**Endpoint key** +: A short-lived or device-specific key authorized by a service key. A service + profile defines how the endpoint key authenticates its route or transport. + +**Service profile** +: A separate specification defining the meaning of a profile ID, endpoint + records, capabilities, constraints, discovery, transport, and browser + behavior. + +**Authorization ID** +: The BLAKE2b-256 hash of a complete canonical service authorization, including + its root signature. + +**Delegation ID** +: The BLAKE2b-256 hash of a complete canonical endpoint delegation, including + its service signature. + +## Design principles + +### The HNS name remains the root of identity + +A client starts with current authenticated Handshake name state. A service +authorization learned from a relay, web server, peer, QR code, cache, or other +untrusted source has no authority unless it validates under the root key and +epoch currently published by that name. + +### Name custody is separate from service operation + +The name wallet key does not sign ordinary service or endpoint messages. An HNS +update selects a service-authority root key; that key delegates online work to +service keys. + +### Service identity is independent of network path + +An IP address, relay, transport connection, hosting provider, or endpoint key is +not the named service identity. Those details may change while the HNS name, +service name, and profile remain stable. + +### Profiles define transport semantics + +HNSA verifies who may operate a named service. It does not decide how a client +finds or reaches the endpoint. HNSR, direct web, messaging, and future profiles +may carry the same authorization objects over different transports. + +### Authorization is bounded + +Root-key changes and epoch increments provide an on-chain emergency boundary. +Service and endpoint authorizations also have finite validity periods so stale +objects eventually stop working without a further HNS transaction. + +## Service identity + +A named service is identified by this tuple: + +```text +Handshake network magic +HNS name hash +canonical service name +service profile ID +``` + +The tuple is stable across root-key rotation, service-key rotation, endpoint +rotation, provider migration, and transport failover. + +Version 1 service names: + +- are 1 through 63 ASCII bytes; +- contain only lowercase `a-z`, digits, and hyphen; +- MUST NOT begin or end with a hyphen; +- MUST NOT contain period, slash, underscore, whitespace, or percent escapes; +- are compared byte-for-byte without locale processing. + +Examples include `web`, `chat`, `files`, `node`, and `p2p-site`. + +The service name is an application namespace beneath the HNS root. It is not a +second-level DNS registration and is not independently owned on chain. + +## HNS root-key record + +### Record form + +A name opts into HNSA by publishing exactly one canonical `TXT` record: + +```text +hsa1 k= e= +``` + +Diagnostic Handshake resource JSON: + +```json +{ + "type": "TXT", + "txt": [ + "hsa1 k=ak3m... e=4" + ] +} +``` + +The abbreviated key above is illustrative and is not a test vector. + +Requirements: + +- the complete record is one printable ASCII character-string; +- fields are separated by exactly one ASCII space; +- fields appear in the order shown; +- `hsa1` is lowercase and exact; +- `k` is an unpadded lowercase base32 encoding of a valid compressed 33-byte + secp256k1 public key; +- `e` is an unsigned 32-bit decimal integer without leading zeroes, except zero + is encoded as `0`; +- unknown, missing, duplicated, or reordered fields make the record invalid; +- more than one syntactically valid `hsa1` record is ambiguous and MUST fail + closed. + +The record uses existing version `0` Handshake resource data and may coexist +with supported `NS`, `DS`, glue, synthesis, and unrelated `TXT` records. + +### Authentication + +An ordinary unauthenticated DNS response is insufficient. A relying client MUST +authenticate the root-key record using one of: + +- locally validated Handshake full-node state; +- a Handshake light-client name proof anchored in accepted chain headers; or +- DNSSEC validation anchored in a locally accepted Handshake root trust path. + +### Update, transfer, and revocation + +An HNS `UPDATE` that changes or removes the `hsa1` record replaces or revokes the +service-authority root after the client accepts the new safe name state. + +Incrementing the epoch invalidates every service authorization containing a +lower epoch. This permits emergency revocation while retaining the same root +key. + +A name transfer that leaves the resource data unchanged leaves the existing +root key and epoch in effect until the new owner updates them. This preserves +service continuity while giving the new owner the ability to replace or remove +the authority record. + +## Cryptographic primitives + +Version 1 uses: + +- BLAKE2b-256; +- compressed 33-byte secp256k1 public keys; +- deterministic secp256k1 ECDSA signatures; +- strict DER signature encoding; +- low-S normalization; +- four-byte little-endian Handshake network magic in every signature domain. + +A verifier MUST reject invalid public keys, noncanonical DER, high-S +signatures, wrong network magic, unsupported versions, and signatures over any +noncanonical encoding. + +All unsigned integer fields use little-endian encoding. Every variable-length +field is preceded by the length shown in its structure. No field may contain +trailing bytes or an alternative encoding. + +## Service authorization + +The root key authorizes one named service with: + +```text +ServiceAuthorizationV1 { + version: u8 + network_magic: u32 + name_hash: u8[32] + authority_epoch: u32 + service_name_length: u8 + service_name: u8[service_name_length] + profile_id: u16 + service_key: u8[33] + flags: u16 + serial: u64 + valid_from_height: u32 + valid_until_height: u32 + max_endpoint_lifetime: u32 + root_signature_length: u8 + root_signature: u8[root_signature_length] +} +``` + +The root-signature digest is: + +```text +BLAKE2b-256( + "HNS-SERVICE-AUTH-V1\0" + || network_magic_u32le + || all remaining unsigned canonical fields +) +``` + +The `network_magic` field appears in the object and signature input exactly +once. The phrase `remaining unsigned canonical fields` starts with `name_hash` +and ends with `max_endpoint_lifetime`. + +Rules: + +- `version` MUST equal `1`; +- `network_magic` MUST match the active Handshake network; +- `name_hash` MUST match the name containing the current `hsa1` record; +- `authority_epoch` MUST equal the current `hsa1` epoch; +- `service_name` MUST be canonical; +- `profile_id` MUST be recognized by the relying client; +- `service_key` MUST be a valid compressed secp256k1 public key; +- `flags` MUST contain only bits defined by the selected profile; +- `serial` MUST increase when the root key replaces an authorization for the + same service identity; +- `valid_until_height` MUST be greater than `valid_from_height`; +- an authorization MUST be rejected outside that block-height interval; +- `max_endpoint_lifetime` MUST be 300 through 604,800 seconds; +- the root signature MUST verify under the current HNSA root key; +- unknown trailing data MUST be rejected. + +The profile MAY impose a shorter authorization span or endpoint lifetime. + +The authorization ID is: + +```text +authorization_id = BLAKE2b-256( + "HNS-SERVICE-AUTH-ID-V1\0" + || complete_canonical_service_authorization +) +``` + +This includes the canonical root signature. + +## Endpoint delegation + +A service key authorizes an endpoint key with: + +```text +EndpointDelegationV1 { + version: u8 + network_magic: u32 + authorization_id: u8[32] + endpoint_key: u8[33] + endpoint_sequence: u64 + issued_at: u64 + expires_at: u64 + capabilities: u32 + constraints_hash: u8[32] + service_signature_length:u8 + service_signature: u8[service_signature_length] +} +``` + +The service-signature digest is: + +```text +BLAKE2b-256( + "HNS-ENDPOINT-DELEGATION-V1\0" + || network_magic_u32le + || all remaining unsigned canonical fields +) +``` + +Rules: + +- `version` MUST equal `1`; +- `network_magic` MUST match the active Handshake network; +- `authorization_id` MUST identify the validated service authorization; +- `endpoint_key` MUST be a valid compressed secp256k1 public key; +- `endpoint_sequence` MUST increase for replacement of the same logical + endpoint under a profile-defined endpoint identifier; +- `issued_at` MUST be less than `expires_at`; +- lifetime MUST NOT exceed the service authorization's + `max_endpoint_lifetime`; +- the delegation MUST NOT remain valid after the service authorization's + block-height expiry; +- `capabilities` MUST contain only bits defined by the selected profile; +- `constraints_hash` is all zeroes when the profile defines no detached + constraints; +- a nonzero constraints hash MUST commit to the exact canonical profile object; +- the service signature MUST verify under the authorized service key; +- unknown trailing data MUST be rejected. + +The delegation ID is: + +```text +delegation_id = BLAKE2b-256( + "HNS-ENDPOINT-DELEGATION-ID-V1\0" + || complete_canonical_endpoint_delegation +) +``` + +A service may authorize several endpoints concurrently for redundancy, +geographic distribution, device migration, or transport choice. + +## Profile-specific endpoint records + +HNSA stops at the endpoint key. A service profile defines the next object used +for discovery or transport. + +A profile-specific endpoint or route record MUST bind at least: + +- active network magic; +- service authorization ID; +- endpoint delegation ID; +- endpoint sequence; +- endpoint or route expiry; +- profile ID; +- profile-specific locator, route, or session data. + +It MUST be signed by the endpoint key and MUST NOT remain valid beyond the +endpoint delegation. + +Examples include: + +- an HNSR signed route with one or more active relay tickets; +- a direct QUIC endpoint with an authenticated transport key; +- an HTTPS endpoint with profile-defined TLS or DANE binding; +- a messaging endpoint with a delivery key and discovery locator. + +Those objects and their wire behavior are outside this HIP. + +## Validation algorithm + +To validate an endpoint record for named service `S`, a client MUST: + +1. Obtain authenticated current HNS state for the root name under local chain + finality policy. +2. Parse the `hsa1` record and reject missing or ambiguous authority. +3. Parse the service authorization using bounded canonical decoding. +4. Confirm network magic, HNS name hash, authority epoch, service name, profile, + flags, height interval, and endpoint-lifetime limit. +5. Verify the root signature under the current `hsa1` key. +6. Calculate and match the service authorization ID. +7. Parse the endpoint delegation using bounded canonical decoding. +8. Confirm its authorization ID, capabilities, constraints, sequence, time + interval, and profile rules. +9. Verify the service signature under the authorized service key. +10. Calculate and match the endpoint delegation ID. +11. Validate the profile-specific endpoint record and its endpoint signature. +12. Apply local browser or application policy before connecting. + +A failure at any step MUST fail closed for HNSA authorization. A client MUST NOT +silently replace a failed HNSA chain with an endpoint learned from an +unauthenticated directory, relay, DNS response, or legacy fallback. + +## Replacement and freshness + +### Root authority + +The current authenticated HNS `hsa1` record is authoritative. A key change or +epoch increment invalidates older service authorizations once the new HNS state +is accepted under local finality policy. + +### Service authorization replacement + +Service authorizations are finite. When several otherwise valid +authorizations for the same service identity are available, a client MUST +select the greatest `serial`. Equal serials with different canonical bytes are +ambiguous and MUST fail closed. + +A client cannot know about an unavailable higher serial merely from an older +object. Profiles MUST therefore define discovery replication and maximum +service-authorization lifetimes appropriate to their risk. Immediate global +revocation uses an HNS root-key change or epoch increment. + +### Endpoint delegation replacement + +Endpoint delegations are short-lived and may overlap for failover. Profiles +must define the logical endpoint identifier used when comparing +`endpoint_sequence` and must bound replay through short route or endpoint +record expiry. + +### Caching + +A client MAY cache a validated chain only until the earliest of: + +- observation of changed HNS name data or a relevant chain reorganization; +- service authorization height expiry; +- endpoint delegation time expiry; +- endpoint or route record expiry; +- profile-specific cache limit. + +## Service profiles + +A service profile assigns a `profile_id` and MUST specify: + +1. User-visible purpose and at least one concrete user story. +2. Meaning of the service authorization `flags`. +3. Meaning of endpoint `capabilities` and detached constraints. +4. Endpoint or route record encoding and signature domain. +5. Discovery and replication behavior. +6. Direct, relayed, and fallback connection policy. +7. Maximum authorization, delegation, and endpoint-record lifetimes. +8. Browser origin, cookies, storage, permissions, and mixed-content behavior + when the profile is web-facing. +9. Resource, parser, and network limits. +10. Positive and negative deterministic test vectors. +11. Privacy, abuse, and denial-of-service considerations. + +Profile IDs are not assigned by this HIP. A profile proposal SHOULD use private +experimental values until its specification, implementations, and test vectors +are accepted. + +## Browser behavior + +This HIP does not require a URI scheme or browser interface. A web-facing +profile must nevertheless preserve these properties. + +### Stable origin + +Browser identity and storage MUST be scoped to at least: + +```text +Handshake network +HNS name hash +canonical service name +profile ID +``` + +They MUST NOT be scoped only to an IP address, relay, endpoint key, or hosting +provider. Transport failover must not create a new origin or share storage with +another named service. + +### Identity indication + +A browser may indicate that the endpoint is authorized by current HNS state. +That indication must not claim that the operator, content, or service is honest +or safe. HNSA authenticates control, not reputation. + +### Failure behavior + +If the authority chain expires, is ambiguous, changes unexpectedly, or fails a +signature check, the browser must stop before sending application data. Any +legacy or conventional-web fallback must be separately identified and require +explicit profile and user policy. + +### Network permissions + +A profile that requests VPN, overlay, local-network, device, or persistent +background access must use an explicit browser or operating-system permission. +An HNSA authorization alone does not grant those capabilities. + +## Relationship to HNSR + +The draft Handshake P2P Rendezvous and Authenticated Service Relay protocol +contains a named-service authorization chain developed for HNSR routes. HNSA +extracts that concept into a transport-independent layer. + +The relationship is: + +```text +HNSA + authorizes the named service key and endpoint key + +HNSR + discovers a currently online endpoint and relays its traffic +``` + +Unnamed HNSR node rendezvous remains independent and does not require an HNS +name or HNSA. + +The current HNSR draft uses an `hnsr1` root record and HNSR-specific service and +endpoint signature domains. Adoption of this HIP would require a separate HNSR +revision that either consumes `hsa1` authority directly or defines an explicit +compatibility transition. This HIP does not silently change the existing HNSR +draft or claim wire compatibility before that revision. + +## Backwards compatibility + +The `hsa1` record is valid existing HNS `TXT` data. Legacy full nodes, miners, +resolvers, wallets, and applications may ignore it. + +HNSA-aware clients are optional consumers. Names without a valid `hsa1` record +continue operating under existing Handshake and DNS rules. + +The proposal does not reinterpret `hnsr1`, unrelated TXT records, DNSSEC keys, +TLS certificates, or wallet addresses. + +## Security considerations + +### Wallet-key exposure + +Implementations MUST NOT use the HNS name wallet key as a root, service, or +endpoint key merely for convenience. The separation of custody and operation is +a primary security property of this protocol. + +### Root-key compromise + +A compromised root key can authorize malicious services until the HNS owner +changes the key or increments the epoch. The root key should remain offline or +in hardware-backed storage and should not sign endpoint or transport messages. + +### Service-key compromise + +A compromised service key can authorize endpoints only for its named service, +profile, validity interval, flags, and endpoint-lifetime limit. It cannot modify +the HNS name or authorize a different service identity. + +### Endpoint-key compromise + +A compromised endpoint key can impersonate one endpoint until its delegation +and profile records expire. Endpoint lifetimes should reflect how securely the +device can protect its key. + +### Replay and stale authorization + +Network magic, HNS state, epochs, serials, sequences, finite validity, and +profile record expiry limit replay. Clients must validate current HNS state and +must not accept an older object merely because a current object is unavailable. + +### Name transfer + +An unchanged HNSA root survives name transfer until the new owner updates the +record. This supports service continuity, but participants must recognize that +the new owner can revoke or replace the entire service authority. + +### Ambiguous authority + +Multiple valid `hsa1` records, equal service serials with different bytes, +noncanonical names, unknown profiles, or conflicting required constraints must +fail closed. + +### Untrusted discovery + +Discovery peers, relays, directories, and content hosts may omit, replay, or +reorder authorization objects. They cannot forge the signature chain, but they +can deny service or attempt to keep clients on older still-valid state. + +### Downgrade + +A failed HNSA connection must not silently become an unauthenticated connection +to the same presentation name. Profiles must define explicit downgrade and +fallback behavior. + +### Parser and resource exhaustion + +Implementations MUST bound all lengths before allocation and signature work. +Recommended initial maximums are: + +| Item | Maximum | +| --- | ---: | +| Service name | 63 bytes | +| Signature | 80 bytes | +| Service authorization | 256 bytes | +| Endpoint delegation | 256 bytes | +| Concurrent service candidates | 16 | +| Concurrent endpoint candidates | 32 | +| Detached constraint object | 64 KiB | + +A profile may impose smaller limits. A larger limit requires explicit +justification and tests in that profile. + +## Privacy considerations + +Service names, service keys, provider changes, endpoint keys, capabilities, and +validity intervals may reveal how a name owner's infrastructure is organized. + +Profiles should avoid publishing personal device labels, private addresses, +internal topology, or long-lived correlatable endpoint keys when they are not +required for verification. Short-lived endpoint keys and privacy-preserving +discovery may reduce correlation. + +Clients should consider that fetching a service authorization or endpoint +record can reveal which HNS service they intend to use. + +## Reference implementation plan + +The first implementation should extract the authority objects and validators +from the HNSR research implementation into a transport-independent library. + +Recommended deliverables are: + +1. Shared canonical encoders and decoders for JavaScript and Rust. +2. Root, service, and endpoint signing and validation APIs. +3. Wallet support for creating and updating the `hsa1` record. +4. A command-line inspection and verification tool. +5. Deterministic positive and negative vectors. +6. An HNSR named-service adapter using HNSA objects. +7. A mobile-browser diagnostic that displays the validated authority chain and + preserves origin across direct and relayed endpoints. + +No `hsd` consensus change is required. HNSR integration, wallet ergonomics, and +browser support remain separate implementation changes. + +## Deployment gates + +### Stage 0: Canonical vectors + +- finalize all binary encodings and signature domains; +- verify byte-identical JavaScript and Rust implementations; +- publish malformed, ambiguous, replayed, and cross-network negative vectors. + +### Stage 1: Regtest authority chain + +- publish `hsa1` in authenticated name state; +- authorize multiple independent named services; +- rotate service and endpoint keys; +- increment the epoch and verify immediate invalidation; +- transfer the name with and without changing the root record. + +### Stage 2: HNSR integration + +- carry HNSA service authorization and endpoint delegation with named HNSR + routes; +- demonstrate direct and relayed endpoints under one stable service identity; +- test route expiry, relay failover, stale authorization, and no legacy + fallback contact. + +### Stage 3: Independent clients and operators + +- run multi-operator testnet trials; +- validate the same objects in independent JavaScript and Rust clients; +- measure authorization freshness, retrieval availability, mobile lifecycle, + and abuse limits; +- complete browser-origin and permission review for any web profile. + +No permanent wire assignment or mainnet-default behavior is requested by this +HIP. + +## Test requirements + +Before this proposal can move beyond Draft, deterministic tests must cover: + +- canonical `hsa1` parsing and ambiguity rejection; +- valid and invalid root signatures; +- wrong name hash, epoch, profile, network magic, and height interval; +- valid service replacement and equal-serial conflict; +- valid and invalid endpoint signatures; +- endpoint lifetime beyond the service maximum; +- invalid capabilities and detached constraint hashes; +- root-key rotation and epoch-only revocation; +- service-key and endpoint-key rotation; +- name transfer with retained and replaced root records; +- concurrent endpoints and failover; +- expired and replayed endpoint records; +- malformed lengths, DER signatures, public keys, and trailing bytes; +- stable browser origin across endpoint, relay, and provider changes; +- rejection without unauthenticated fallback. + +## Rationale + +### Why store a root key in HNS instead of every endpoint? + +Endpoint state changes frequently and may exceed the 512-byte HNS resource-data +limit. A root key creates a bounded delegation hierarchy while keeping name +state small and durable. + +### Why not use the HNS wallet key directly? + +Wallet keys control valuable names and coins and should not be exposed to +online service processes. A separate root key permits service authorization +without weakening name custody. + +### Why have both service and endpoint keys? + +A service may run on several devices, providers, or relays. The service key +represents the operator role, while short-lived endpoint keys limit the impact +of one device compromise and allow independent rotation. + +### Why include an on-chain epoch? + +Service authorizations may be replicated through untrusted discovery systems. +An epoch increment gives the HNS owner one current, authenticated mechanism for +invalidating every authorization under an old epoch without relying on those +systems to distribute a revocation list. + +### Why use block height for service authorization and time for endpoints? + +The service root is verified against Handshake chain state, so block height +provides a consistent validity boundary. Endpoint records are short-lived +network objects whose transports already depend on wall-clock expiry. + +### Why keep transport behavior out of this HIP? + +Rendezvous, direct web, messaging, and other transports have different routing, +privacy, availability, and abuse models. Combining them with the authority core +would make one proposal responsible for unrelated deployment risks. + +## Alternatives considered + +### Generic Internet resource manifests + +Not included. IP prefixes, ASNs, routing policy, link-layer identifiers, and +other public resources have separate authority systems and no immediate role in +the named-service chain defined here. + +### Application-specific TXT keys + +Not selected as the general model. A separate key record for every application +duplicates rotation, transfer, expiry, and validation rules and consumes scarce +HNS resource data. + +### One online key for all services + +Not selected. Independent service keys contain compromise and allow providers +or devices to be changed without replacing unrelated services. + +### On-chain endpoint records + +Not selected. Mobile and relayed endpoints change too frequently for name +transactions and may require multiple concurrent records. + +### A mandatory manifest server + +Not selected. Authorization objects are signed and can be carried by any +profile-defined discovery system. Requiring one server would create a new +availability and metadata dependency. + +## Open questions + +The following items remain for Draft review and implementation evidence: + +- exact private profile-ID range for regtest and acknowledged testnet use; +- whether service authorizations need a core maximum block-height span; +- whether service-specific revocation needs an optional on-chain commitment in + addition to bounded lifetime and global epoch revocation; +- whether a future version should support threshold or hardware-backed root + keys; +- exact transition from the HNSR draft's `hnsr1` record to `hsa1`; +- whether direct web and HNSR should share one web profile or use separate + profile IDs with explicit origin relationships; +- default browser presentation for HNS-authorized service identity. + +## References + +1. RFC 2119, *Key words for use in RFCs to Indicate Requirement Levels*. +2. RFC 8174, *Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words*. +3. RFC 6979, *Deterministic Usage of the Digital Signature Algorithm*. +4. SEC 1, *Elliptic Curve Cryptography*. +5. Handshake developer documentation, *Resource Records*. +6. Draft HIP, *Handshake P2P Rendezvous and Authenticated Service Relay*. +7. Handshake `hsd` authenticated name-proof and resource validation behavior. diff --git a/HIP-xxxx-HRM.md b/HIP-xxxx-HRM.md deleted file mode 100644 index 32782b5..0000000 --- a/HIP-xxxx-HRM.md +++ /dev/null @@ -1,1128 +0,0 @@ -# HIP-xxxx: Handshake Resource Manifests - -```text -Number: HIP-xxxx -Title: Handshake Resource Manifests -Type: Standards Track -Status: Draft -Authors: Jaron Rosenau <@denuoweb> -Created: 2026-08-01 -Related: HIP-0015, HIP-0016, Handshake P2P Rendezvous and - Authenticated Service Relay (draft HIP) -Follow-ons: Handshake IP and Routing Resource Profile (planned HIP) - Handshake Service and Transport Resource Profile (planned HIP) - Handshake Link and Overlay Resource Profile (planned HIP) -``` - -## Abstract - -This document specifies Handshake Resource Manifests (HRMs), an optional -protocol for binding a Handshake name to a signed, content-addressed description -of Internet resources, delegations, controller keys, and validity constraints. - -An HRM separates authorization from transport. Handshake authenticates a small -commitment published by the current name owner. The committed manifest may be -retrieved from any untrusted storage or transport. Resource-specific profiles -then determine whether a claimed resource was originated legitimately, whether -a child resource is contained by a parent resource, and which actions a -delegation permits. - -Version 1 uses ordinary Handshake `TXT` resource records and does not change -Handshake consensus, DNS resolution, covenant validation, or the interpretation -of any globally assigned number. It does not make an IP prefix routable, create -an Autonomous System Number (ASN), assign a port or protocol number, or replace -the policies of IANA, the Regional Internet Registries (RIRs), the IETF, or -IEEE. Globally coordinated resources require a proof profile rooted in an -authority already accepted for that resource. HNS-local overlay resources may -use profiles that explicitly permit origination by an HNS controller. - -The initial protocol is deliberately limited to a reusable manifest, -commitment, signature, delegation, and verification format. IPv4/IPv6, ASN, -routing, service, and link-layer semantics are specified by separate profiles. -This allows independent implementations to agree on the security boundary -before any HRM data is used to generate RPKI objects, routing policy, service -configuration, or other operational output. - -## Plain-language summary - -Handshake currently proves who controls a name. It does not provide a standard -way for that owner to say: - -```text -this key operates my network -this IPv6 prefix was legitimately delegated to me -this smaller prefix is delegated to this community -this service key may accept connections for this service -this authorization expires at this time -``` - -An HRM adds that common language. - -The name owner places a small hash on Handshake. The larger document is stored -elsewhere and can be copied by anyone. A client retrieves the document, checks -that its hash matches Handshake, verifies its controller signature, and then -verifies the authority proof or parent delegation for the resource it needs. - -The design has two important limits: - -1. Owning an HNS name does not prove ownership of an unrelated public IP - prefix, ASN, port, EtherType, or other externally coordinated resource. -2. A valid HRM is authorization evidence, not a command to a router, operating - system, certificate implementation, or network operator. - -Adapters may translate a successfully verified HRM into ordinary configuration, -but those adapters remain subject to local policy and the rules of the protocol -or registry they affect. - -## Motivation - -Internet resource control is recorded across many systems. IP prefixes and ASNs -are distributed hierarchically through IANA and the RIRs. Protocol parameters -are defined through IETF processes and recorded in IANA registries. Link-layer -identifiers may be coordinated by IEEE. Service keys, overlay identifiers, and -internal delegations are often kept in private databases. - -These systems solve different problems and should not be treated as one policy -domain. They nevertheless repeat several operational functions: - -- associate a resource with a controller; -- delegate a subset or a limited right; -- rotate operational keys; -- publish validity periods; -- revoke previous authority; -- provide an audit trail; -- expose current data to relying software. - -Handshake can provide a common, independently verifiable control plane for -those functions without redefining the resources carried in packet headers. -The desired division is: - -```text -resource policy and initial authority - | - v -recognized external proof or HNS-local origin rule - | - v -Handshake-anchored resource manifest - | - v -signed subdelegations and controller keys - | - v -opt-in adapters for RPKI, routing, services, overlays, and applications -``` - -This division is useful even if IANA, an RIR, IEEE, or another existing body -remains the source of the parent allocation. HRM can make later delegations -portable, auditable, and verifiable without requiring every resource holder to -operate a bespoke registry database or trusted API. - -## Scope - -This HIP defines: - -- an on-chain HRM commitment carried by an existing HNS `TXT` record; -- a deterministic CBOR envelope and payload; -- controller signatures; -- resource entries and stable resource identifiers; -- external, HNS-local, and parent-delegated authority modes; -- parent-to-child delegations; -- current-state, expiry, transfer, and revocation behavior; -- a profile interface for resource-specific validation; -- a verification algorithm and minimum implementation limits. - -This HIP does not define: - -- allocation policy for any existing public registry; -- a complete IPv4, IPv6, ASN, RPKI, BGP, port, protocol, TLS, or IEEE profile; -- transient peer routes or relay reservations; -- a mandatory storage or retrieval network; -- automatic router or operating-system configuration; -- an HNS consensus change or new namestate data version; -- a new Handshake P2P message, service bit, port, or protocol number; -- economic policy for allocating HNS-local resources. - -## Four-HIP program and dependency order - -This document is the first of four intended, independently reviewed HIPs. The -three companion HIPs are not optional sections of HRM Core and do not receive a -HIP number through this document. Each must be proposed, implemented, tested, -reviewed, and assigned its own number separately. - -```text -1. Handshake Resource Manifests (this HIP) - common commitment, envelope, controller, delegation, and validation - | - +--> 2. Handshake IP and Routing Resource Profile - | IPv4/IPv6, ASN, RPKI proofs, prefix containment, - | routing rights, and read-only routing adapters - | - +--> 3. Handshake Service and Transport Resource Profile - | service identifiers, TCP/UDP/QUIC bindings, TLS and - | WireGuard keys, endpoint rights, and HNSR authorization - | - +--> 4. Handshake Link and Overlay Resource Profile - virtual link identifiers, device/controller keys, - overlay segments, and explicitly scoped link-layer use -``` - -The companion HIPs stack on the data model and verification algorithm defined -here. They MUST NOT weaken HRM Core's distinction between an HNS-local resource -and an externally coordinated public resource. - -### Planned HIP 2: IP and routing - -The second HIP should define canonical IPv4, IPv6, and ASN resource encodings; -RPKI-based external origin proofs; prefix containment; routing and -subdelegation rights; proof refresh and revocation; and an audit-only adapter -that compares HRM results with current RPKI and registry state. - -It must not claim that an HNS name, auction, or transaction creates a routable -prefix or ASN. Any production route-generation behavior requires a later, -explicit deployment decision after multi-operator testing. - -### Planned HIP 3: Services and transports - -The third HIP should define HNS-local service identifiers, bindings to existing -TCP, UDP, QUIC, TLS, WireGuard, and similar transports, controller-key roles, -endpoint rights, and the relationship between long-lived HRM authority and -short-lived HNSR route records. - -It must distinguish HNS-local service identifiers from IANA-assigned ports, -protocol numbers, TLS parameters, and other public wire values. Use of a public -wire value requires an existing assignment or coordination with its responsible -standards community. - -### Planned HIP 4: Links and overlays - -The fourth HIP should define identifiers and delegations for explicitly opt-in -virtual links and overlay networks, including virtual segments, device or -controller keys, membership rights, and containment between overlay authorities. - -It must not reinterpret globally coordinated IEEE identifiers on ordinary -Ethernet. Any EtherType, OUI, or other public link-layer assignment must come -from the responsible registry or operate inside a formally assigned extension -space. - -The ordering above is a review sequence, not a requirement that every -implementation support every profile. An implementation may support HRM Core -and any accepted subset of companion profiles. - -## Requirements language - -The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, -**SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **NOT RECOMMENDED**, **MAY**, and -**OPTIONAL** in this document are to be interpreted as described in BCP 14 when, -and only when, they appear in all capitals. - -## Terminology - -**HNS name owner** -: The controller of the current Handshake name covenant output. - -**Subject** -: The Handshake name identified by the 32-byte name hash in an HRM. - -**Manifest controller** -: The key that signs the HRM payload. The manifest controller may be operationally - separate from the HNS name owner. - -**Commitment** -: The HRM `TXT` record in current authenticated Handshake namestate. It contains - the manifest sequence, envelope hash, and retrieval locators. - -**Envelope** -: Deterministic CBOR containing the encoded payload and its signature set. - -**Resource** -: An identifier or authority described by a resource profile. Examples may - include an IPv6 prefix, an ASN, an HNS-local service identifier, or an overlay - network identifier. - -**Resource profile** -: A separate specification that defines the canonical identifier, origination - proof, containment relation, rights, constraints, and adapter behavior for one - resource family. - -**Origin proof** -: Evidence accepted by a resource profile that starts an authority chain. It is - either an external proof rooted in a configured trust anchor or an HNS-local - origin explicitly permitted by the profile. - -**Parent delegation** -: A current entry in a valid parent HRM authorizing a child subject and - controller to exercise rights over a resource or valid subset. - -**Relying implementation** -: Software that validates HRMs or uses validated output. Examples include a - wallet, resolver, HNSR service, RPKI adapter, network controller, or auditor. - -## Trust model - -HRM has two independent authorization gates: - -```text -current HNS name owner commits the envelope hash - AND -manifest controller signs the committed payload -``` - -The current authenticated HNS commitment selects the exact envelope. Only the -current name owner can replace or remove that commitment. The controller -signature proves continuity of the operational key and allows parent -delegations to bind authority to a key rather than silently following a name -sale. - -Neither gate proves that a public resource originated legitimately. A resource -entry is valid only when its selected profile also validates one of: - -- an accepted external origin proof; -- an HNS-local origin rule defined by that profile; or -- a complete parent-delegation chain ending in one of those origins. - -A relying implementation chooses which profiles and external trust anchors it -accepts. Unsupported profiles and unrecognized proof types MUST fail closed. - -## Protocol overview - -Publishing an HRM consists of these steps: - -1. Construct a payload for one HNS subject. -2. Encode it using deterministic CBOR. -3. Sign the domain-separated payload with the manifest controller key. -4. Construct and deterministically encode the envelope. -5. Hash the complete envelope with SHA-256. -6. Store the envelope at one or more retrievable locations. -7. Publish an `hrm1` `TXT` commitment containing the sequence, hash, and - locators in the current HNS namestate. - -Verification reverses those steps: - -1. Authenticate current HNS namestate and select its current HRM commitment. -2. Retrieve an envelope from any advertised or locally discovered source. -3. Verify the envelope hash against the commitment. -4. Decode the envelope and payload using deterministic CBOR rules. -5. Match the subject, sequence, network, and validity interval. -6. Verify the controller signature. -7. Validate the requested resource using its selected profile. -8. Recursively validate any parent delegation to a recognized origin. -9. Apply local policy before producing operational output. - -## HNS commitment record - -### Existing namestate version - -Version 1 commitments use the existing version `0` Handshake resource data -format and its `TXT` record. This permits an HRM commitment to coexist with -ordinary `NS`, `DS`, glue, synthesis, and other supported Handshake records. - -This HIP does not allocate a new namestate data version under HIP-0015. A future -HIP may define a binary commitment if deployment experience shows that the -existing `TXT` representation is inadequate. - -### Record form - -An HRM commitment is one HNS `TXT` record whose first character-string is -exactly `hrm1` and whose remaining character-strings contain one field each. - -The diagnostic JSON form is: - -```json -{ - "type": "TXT", - "txt": [ - "hrm1", - "seq=7", - "hash=sha256:47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU", - "uri=https://registry.example/hrm/47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU" - ] -} -``` - -The example digest is illustrative and does not commit to a valid example -envelope. - -The fields are: - -`seq` -: An unsigned 64-bit decimal integer without leading zeroes, except that zero - is encoded as `0`. - -`hash` -: Exactly `sha256:` followed by the unpadded base64url encoding of the 32-byte - SHA-256 digest of the complete deterministic-CBOR envelope. - -`uri` -: A retrieval URI. At least one `uri` field MUST be present for a self-contained - publication. Additional `uri` fields MAY provide replicas. A relying - implementation MAY use an envelope learned out of band after matching its - hash. - -All commitment character-strings MUST contain printable ASCII. An individual -string MUST NOT exceed the existing HNS `TXT` string limit, and the complete -Handshake resource data MUST remain within the existing 512-byte consensus -limit. - -The order of `uri` fields has no security meaning. Unknown fields MUST be -ignored only when their key begins with `x-`. Any other unknown or duplicate -singleton field makes that commitment invalid. - -### Commitment selection - -A name SHOULD publish no more than one current `hrm1` record. - -If authenticated current namestate contains multiple syntactically valid -`hrm1` records, a verifier MUST select the record with the greatest `seq`. If -two records have the same greatest sequence and different hashes, the HRM state -is ambiguous and verification MUST fail closed. Duplicate records with the same -sequence and hash are equivalent; their locator sets MAY be combined. - -Sequence numbers are for cache invalidation and replay resistance. They are not -enforced by Handshake consensus. A publisher MUST increase `seq` for every new -envelope under a subject. A verifier that has previously accepted a greater -sequence at equal or greater chain work SHOULD reject a lower sequence unless -it has detected and accepted a Handshake reorganization according to local -finality policy. - -### Authenticated retrieval - -An ordinary unauthenticated DNS response containing an HRM commitment is not -sufficient. The relying implementation MUST authenticate the record using one -of: - -- locally validated Handshake full-node state; -- a Handshake light-client name proof anchored in accepted chain headers; or -- DNSSEC validation anchored in a locally accepted Handshake root trust path. - -The retrieval URI and retrieval server are untrusted. Integrity comes from the -on-chain envelope hash, not from HTTPS, a gateway, a relay, or a content host. - -## Deterministic CBOR - -The envelope and payload MUST use deterministic CBOR as specified by RFC 8949, -Section 4.2, with these additional restrictions: - -- maps MUST use the integer keys assigned by this document or a profile; -- map keys MUST be unique; -- indefinite-length items MUST NOT be used; -- floating-point values MUST NOT be used; -- text strings MUST be valid UTF-8; -- profile identifiers MUST contain only lowercase ASCII letters, digits, - hyphen, period, and slash; -- decoders MUST reject trailing data after the top-level CBOR item; -- an encoder MUST produce the preferred serialization of every integer and - length. - -An implementation MUST re-encode a decoded object and compare it byte-for-byte -with the received encoding before treating it as canonical. This prevents two -encodings of the same logical object from producing different security -interpretations. - -## Envelope format - -The envelope is the following CBOR map: - -| Key | Name | Type | Required | Meaning | -| ---: | --- | --- | :---: | --- | -| `0` | `payload` | byte string | yes | Complete deterministic-CBOR payload | -| `1` | `signatures` | array | yes | One or more signature objects | - -A version 1 envelope MUST contain no other top-level keys. - -Each signature object is a CBOR map: - -| Key | Name | Type | Required | Meaning | -| ---: | --- | --- | :---: | --- | -| `0` | `algorithm` | unsigned integer | yes | Signature algorithm identifier | -| `1` | `public_key` | byte string | yes | Encoded public key | -| `2` | `signature` | byte string | yes | Signature bytes | - -Version 1 assigns algorithm `1` to deterministic secp256k1 ECDSA. For algorithm -`1`, `public_key` MUST be a valid compressed 33-byte secp256k1 public key and -`signature` MUST use strict DER encoding with low-S normalization. Unknown -algorithms MUST NOT be accepted as satisfying a required controller signature. - -The signature digest is: - -```text -BLAKE2b-256( - ASCII("HNS-HRM-v1") || 0x00 - || network_magic_u32le - || payload -) -``` - -`network_magic_u32le` is the four-byte little-endian encoding of the active -Handshake network magic. This prevents a signature created for mainnet, -testnet, regtest, or another configured network from being replayed as valid on -a different network. - -The envelope MUST contain a valid signature made by the controller key declared -in the payload. Extra signatures MAY be present for transition experiments but -have no version 1 authority unless a resource profile assigns them meaning. - -## Payload format - -The payload is a CBOR map: - -| Key | Name | Type | Required | Meaning | -| ---: | --- | --- | :---: | --- | -| `0` | `version` | unsigned integer | yes | Must equal `1` | -| `1` | `subject` | byte string | yes | 32-byte Handshake name hash | -| `2` | `sequence` | unsigned integer | yes | Must equal commitment `seq` | -| `3` | `issued_at` | unsigned integer | yes | Unix time in seconds | -| `4` | `expires_at` | unsigned integer | yes | Unix time in seconds | -| `5` | `controller` | map | yes | Algorithm and public key | -| `6` | `resources` | array | yes | Resource entry objects | -| `7` | `delegations` | array | yes | Delegation objects | -| `8` | `extensions` | map | no | Profile-defined, non-critical data | - -`subject` MUST equal the consensus Handshake name hash for the name from which -the commitment was obtained. - -`issued_at` MUST be less than `expires_at`. A verifier MUST reject the payload -before `issued_at` or at and after `expires_at`, subject to a locally configured -clock-skew allowance. Profiles MAY impose shorter maximum lifetimes. - -`controller` is a CBOR map with key `0` containing the signature algorithm and -key `1` containing the public key. Version 1 requires algorithm `1` and a valid -compressed 33-byte secp256k1 public key. - -`resources` and `delegations` are complete current snapshots. Removing an entry -and publishing a greater sequence revokes that entry after the new Handshake -state reaches the verifier's required finality. - -## Resource entries - -A resource entry is a CBOR map: - -| Key | Name | Type | Required | Meaning | -| ---: | --- | --- | :---: | --- | -| `0` | `profile` | text string | yes | Resource-profile identifier | -| `1` | `resource_id` | byte string | yes | 32-byte stable identifier | -| `2` | `identifier` | byte string | yes | Profile-defined canonical resource | -| `3` | `authority` | map | yes | Origin or parent authority object | -| `4` | `not_before` | unsigned integer | yes | Earliest valid Unix time | -| `5` | `expires_at` | unsigned integer | yes | Exclusive expiry Unix time | -| `6` | `attributes` | map | no | Profile-defined attributes | - -The profile MUST define: - -- canonical encoding of `identifier`; -- calculation and validation of `resource_id`; -- whether HNS-local origination is permitted; -- accepted external authority proof types; -- the subset or containment relation; -- recognized rights and constraints; -- maximum validity periods; -- whether multiple simultaneous authorities are meaningful; -- behavior expected from operational adapters. - -The resource validity interval MUST be contained by the payload validity -interval. An implementation MUST NOT assign semantics to an unknown profile. - -### Authority objects - -The `authority` map has key `0`, `kind`, with one of these values: - -| Kind | Name | Meaning | -| ---: | --- | --- | -| `0` | HNS-local origin | The profile permits controller origination | -| `1` | External origin | An external proof establishes origin authority | -| `2` | Parent delegation | A current HRM delegates the resource | - -#### HNS-local origin - -An HNS-local authority object is `{0: 0}`. - -It is valid only if the selected resource profile explicitly permits HNS-local -origination and derives a collision-resistant namespace from the subject name -hash and controller key. A public IPv4 prefix, IPv6 prefix, ASN, IANA protocol -number, IANA port, or IEEE EtherType MUST NOT be originated this way. - -#### External origin - -An external authority object contains: - -| Key | Name | Type | Required | -| ---: | --- | --- | :---: | -| `0` | `kind` | unsigned integer equal to `1` | yes | -| `1` | `proof_profile` | text string | yes | -| `2` | `proof_hash` | 32-byte string | yes | -| `3` | `proof_uris` | array of text strings | yes | - -`proof_hash` is the SHA-256 digest of the exact external proof object. The proof -may be retrieved from any source. The resource profile defines its format, -trust anchors, revocation behavior, and how it binds the resource, subject, -controller key, and validity interval. - -Merely displaying matching RDAP, WHOIS, registry, or web-page text MUST NOT be -treated as a cryptographic origin proof unless a future profile defines and -secures that exact trust model. - -#### Parent delegation - -A parent-delegation authority object contains: - -| Key | Name | Type | Required | -| ---: | --- | --- | :---: | -| `0` | `kind` | unsigned integer equal to `2` | yes | -| `1` | `parent_subject` | 32-byte string | yes | -| `2` | `parent_resource_id` | 32-byte string | yes | -| `3` | `delegation_id` | 32-byte string | yes | - -The verifier MUST retrieve and validate the current HRM for `parent_subject`, -validate `parent_resource_id`, and locate the current `delegation_id`. The -parent delegation must exactly authorize the child subject, child controller, -child resource, requested right, and current time. - -## Delegations - -A delegation object is a CBOR map: - -| Key | Name | Type | Required | Meaning | -| ---: | --- | --- | :---: | --- | -| `0` | `delegation_id` | byte string | yes | 32-byte identifier | -| `1` | `parent_resource_id` | byte string | yes | Controlled parent resource | -| `2` | `child_profile` | text string | yes | Child resource profile | -| `3` | `child_resource_id` | byte string | yes | Child resource identifier | -| `4` | `child_identifier` | byte string | yes | Canonical child resource | -| `5` | `child_subject` | byte string | yes | 32-byte child HNS name hash | -| `6` | `child_controller` | map | yes | Required child algorithm and key | -| `7` | `rights` | array of text strings | yes | Profile-defined rights | -| `8` | `not_before` | unsigned integer | yes | Earliest valid Unix time | -| `9` | `expires_at` | unsigned integer | yes | Exclusive expiry Unix time | -| `10` | `may_subdelegate` | boolean | yes | Child may delegate further | -| `11` | `constraints` | map | no | Profile-defined restrictions | - -The delegation interval MUST be contained by both the payload interval and the -parent resource interval. The child resource MUST be equal to or a valid subset -of the parent resource according to the parent profile. Cross-profile -delegation is invalid unless the parent profile explicitly defines the mapping. - -`child_controller` uses the same algorithm/key map as the payload controller. -Binding the delegation to both `child_subject` and `child_controller` prevents a -sale or compromise of only one identity component from silently transferring -the delegated resource. - -The profile defines the canonical calculation of `delegation_id`. It SHOULD be -the SHA-256 digest of a domain-separated deterministic encoding of every -security-relevant delegation field except `delegation_id` itself. - -Removing the delegation from a later parent manifest revokes it. A child copy -of an older delegation never overrides current parent state. - -## Name ownership, transfer, and key rotation - -An HRM binds a current HNS commitment and a manifest controller key. They serve -different purposes: - -- the HNS owner chooses which envelope is current; -- the controller signs the resource state; -- a parent delegation may require that exact controller key. - -Ordinary HNS `UPDATE`, `RENEW`, and `TRANSFER` processing does not invalidate an -otherwise current HRM when the exact commitment remains in current namestate. -This matches ordinary DNS-resource continuity and the HNSR root-key model. A new -name owner can remove the commitment, but cannot forge a replacement under the -existing controller key. - -A name transfer alone does not give the new owner an externally originated or -parent-delegated resource. Those authority chains remain bound to the manifest -controller. The new owner can leave that controller's exact committed manifest -available or withdraw it, but cannot change its signed contents. - -An HNS-local profile MAY define a resource as following current control of the -HNS name. A profile requiring transfer-sensitive invalidation MUST define the -extra binding and its validation rule explicitly; HRM Core does not infer -external resource ownership from a name transfer. - -Controller-key rotation has the same rule: HNS-local resources may select a new -controller through a new owner-committed envelope, but external and -parent-delegated resources require a refreshed proof or parent delegation that -binds the new controller. - -If the Handshake name is revoked, expired, or has no current owner, its HRM is -invalid. - -## Verification algorithm - -To authorize action `A` over resource `R` for subject `S`, a version 1 verifier -MUST perform the following steps. - -1. Obtain authenticated current Handshake namestate for `S` under a locally - accepted chain-finality policy. -2. Confirm the name has a current owner and is not revoked or expired. -3. Parse all `hrm1` commitment records and select the current commitment. -4. Retrieve an envelope whose SHA-256 digest matches the commitment. -5. Enforce deterministic CBOR and all envelope structural limits. -6. Decode the payload and confirm: - 1. `version` is `1`; - 2. `subject` equals `S`; - 3. `sequence` equals commitment `seq`; - 4. the signature is evaluated with the active network magic; - 5. the payload is currently within its validity interval. -7. Verify the required controller signature over the exact payload bytes. -8. Locate `R`, reject duplicate resource identifiers, and validate its profile, - canonical identifier, resource identifier, attributes, and validity. -9. Validate its authority: - 1. for HNS-local origin, confirm the profile permits origination and derives - the resource namespace correctly; - 2. for external origin, retrieve and verify the exact proof under configured - trust anchors and current revocation state; - 3. for parent delegation, recursively validate the current parent resource - and exact current delegation. -10. Confirm every link authorizes action `A`, every child is contained by its - parent, every time interval is contained by its parent, and every required - constraint is satisfied. -11. Apply local operational policy before returning authorization. - -A verifier MUST detect subject/resource cycles. It MUST impose a recursion limit -of no more than 32 parent links and SHOULD permit operators to configure a lower -limit. A cycle, exceeded limit, unavailable required parent, ambiguous state, -unknown critical profile, failed proof, or expired link MUST fail closed. - -## Current state and revocation - -HRM is a current-state protocol. Handshake history provides an audit trail but -does not keep removed authority active. - -To revoke a resource or delegation, the publisher increments the sequence, -removes the entry from the complete snapshot, signs the new payload, publishes -the new envelope, and updates the commitment. The revocation takes effect for a -verifier when that verifier accepts the new Handshake state under local finality -policy. - -Short emergency expiry periods can reduce exposure when a publisher cannot -immediately update the chain. Resource profiles SHOULD define maximum validity -periods appropriate to their operational risk. - -A verifier MAY cache a successful result only until the earliest of: - -- payload expiry; -- resource expiry; -- delegation expiry; -- external-proof expiry or revocation refresh; -- locally configured cache limit; -- observation of a new commitment or relevant Handshake reorganization. - -## Availability and retrieval - -Handshake commits to HRM integrity but does not guarantee delivery of the -envelope or external proofs. - -Publishers SHOULD provide multiple independent locators. Content-addressed -storage, HTTPS, HNSR, peer-to-peer storage, local operator mirrors, or other -transports MAY be used. A mirror does not need publisher permission because the -committed hash authenticates the bytes. - -Failure to retrieve a current required object means the authorization is -unavailable and MUST NOT be treated as valid. An implementation MUST NOT fall -back to an older envelope merely because the current object cannot be fetched. - -Transient HNSR route records, relay reservations, live socket addresses, and -similar presence data SHOULD NOT be placed in HRM. HRM establishes longer-lived -controller and resource authority; a rendezvous protocol may use that authority -to authenticate its own short-lived records. - -## Resource profiles - -Profiles are separate specifications so a defect or policy dispute in one -resource family does not redefine the HRM core. - -A profile specification MUST provide: - -1. A stable lowercase profile identifier. -2. Canonical resource encoding. -3. Resource-ID calculation. -4. Origin modes and accepted proof profiles. -5. Parent-child containment rules. -6. Rights, constraints, and subdelegation rules. -7. Time and expiry requirements. -8. Conflict and multiple-origin behavior. -9. At least one positive and negative deterministic test vector. -10. Security, privacy, and operational-adapter considerations. - -The planned companion HIPs are expected to define profiles including: - -`hns.overlay.service/v1` -: HNS-local, collision-resistant service identifiers and controller keys. - -`hns.overlay.network/v1` -: HNS-local identifiers for explicitly opt-in virtual networks. - -`rpki.ip-prefix/v1` -: IPv4/IPv6 resources rooted in a cryptographically validated RPKI proof, with - canonical prefix containment and subdelegation. - -`rpki.asn/v1` -: ASN authority rooted in an accepted RPKI proof. - -`hnsr.service/v1` -: Longer-lived authorization keys and rights consumed by HNSR named-service - rendezvous. Short-lived HNSR routes remain in HNSR. - -Names above are illustrative and are not allocated by this HIP. The three -companion documents identified in the four-HIP program must assign their exact -profile identifiers and semantics. - -## Operational adapters - -An adapter consumes a verified HRM result and produces output for another -system. Examples might include: - -- a proposed RPKI certificate or routing authorization; -- a BGP import-policy input; -- a network-controller configuration fragment; -- an HNSR named-service authorization; -- a WireGuard or TLS trust configuration; -- an overlay network membership decision; -- an audit report comparing HRM and an existing registry. - -Version 1 adapters MUST be opt-in and SHOULD default to audit or dry-run mode. -An adapter MUST NOT treat an HNS commitment alone as authority over a public -resource. It MUST report the complete validated proof chain and the local policy -decision that caused operational output. - -No adapter should directly change public routing, filtering, certificate trust, -or another security-sensitive system without an additional operator policy and -an explicit deployment specification. - -## Security considerations - -### False public-resource claims - -Any HNS owner can publish arbitrary bytes. Therefore an HRM without a valid -profile-specific authority chain is only a claim. Public-resource profiles MUST -validate a recognized external origin or complete parent delegation. - -### Name squatting - -Similarity between an HNS name and an organization, registry entry, domain, or -resource label does not establish authority. Validation is based on the -resource proof chain, not human-readable resemblance. - -### Name transfer - -An unchanged commitment may survive a name transfer, but externally originated -and parent-delegated authority remains bound to the manifest controller. The new -name owner may withdraw the manifest and cause denial of service; it cannot -alter the signed state or satisfy a controller-bound authority chain. HNS-local -profiles must state explicitly whether their resources follow the name. - -### Controller compromise - -A compromised controller can sign malicious manifests only if the HNS owner -also commits them, but an entity may operate both keys. Publishers SHOULD keep -the HNS owner key and manifest controller key in separate security domains. -High-risk profiles SHOULD use short expiry and explicit recovery procedures. - -### HNS owner compromise - -A compromised name owner can withdraw or replace the commitment and cause -denial of service. It cannot satisfy a controller-bound parent delegation or -external proof without the required controller authority. Operational systems -must nevertheless plan for the resulting unavailability. - -### Replay and rollback - -Sequence, current authenticated namestate, validity intervals, and local -chain-finality policy limit replay. Implementations must distinguish a genuine -Handshake reorganization from an envelope replay at equal or lower chain work. - -### Locator equivocation - -Locators may return different bytes, track clients, refuse service, or serve -malware. Hash validation prevents undetected content substitution but not -denial of service or metadata collection. - -### External proof revocation - -An unchanged HRM may outlive an external allocation or proof. Every external -profile MUST define current revocation and refresh behavior. A cached HRM result -must not outlive the proof state on which it depends. - -### Delegation cycles and exhaustion - -Attackers may construct cycles, deep graphs, large manifests, repeated -locators, or expensive proof chains. Implementations MUST bound object size, -retrieval count, redirects, total bytes, signature operations, recursion depth, -and validation time. - -Suggested default limits for an initial implementation are: - -| Item | Default maximum | -| --- | ---: | -| Envelope bytes | 1 MiB | -| Resources per manifest | 1,024 | -| Delegations per manifest | 4,096 | -| Locators attempted per object | 4 | -| Parent depth | 16 | -| Total fetched objects per decision | 64 | -| Total fetched bytes per decision | 8 MiB | - -Implementations MAY impose smaller limits. A profile requiring larger values -must justify them explicitly. - -### Parser differentials - -Security depends on independent implementations hashing and interpreting the -same bytes identically. Deterministic CBOR restrictions, byte-for-byte -re-encoding, strict profile canonicalization, and shared negative test vectors -are REQUIRED before a profile is used for operational authorization. - -### Unsafe automation - -A cryptographically valid statement can still violate an operator's business, -safety, routing, or abuse policy. HRM validation and operational acceptance are -separate decisions. Adapters must preserve that boundary. - -## Privacy considerations - -HRMs are public or publicly retrievable metadata. They may reveal network -structure, customer relationships, service inventory, controller rotation, -organizational hierarchy, and planned expiry times. - -Publishers SHOULD disclose only information needed for verification. Private -addresses, personal device identifiers, internal topology, transient routes, -and individual customer data SHOULD NOT be published unless the profile and -participants explicitly accept that disclosure. - -Retrieval can reveal which resource a client is interested in. Mirrors, -content-addressed caches, privacy relays, or locally synchronized datasets may -reduce that leakage. - -## Backwards compatibility - -This proposal uses existing valid HNS version `0` resource data and `TXT` -records. Legacy HNS nodes, miners, resolvers, and wallets require no consensus -change and may ignore `hrm1` records. - -HRM-aware software is an optional consumer. Names may continue using ordinary -DNS records. The 512-byte HNS resource limit remains unchanged. - -An implementation MUST NOT reinterpret unrelated TXT records as HRM data. Only -a record beginning with the exact `hrm1` marker is in scope. - -## Relationship to HIP-0015 and HIP-0016 - -HIP-0015 describes Handshake name updates as authenticated update chains and -allows future application-defined namestate versions. HRM uses the same general -idea of an HNS name anchoring changing application state, but version 1 remains -inside the existing DNS resource format for compatibility. - -HIP-0016 demonstrates how an off-chain authenticated data structure may commit -its root through HNS while light clients verify selected data. A future HRM -scaling proposal may replace the single-envelope snapshot with a provable map -or accumulator. That is not required for HRM version 1. - -## Relationship to HNSR - -The draft Handshake P2P Rendezvous and Authenticated Service Relay protocol -defines short-lived discovery and relay routes. HRM and HNSR are independent: - -```text -HRM - who controls a resource or long-lived service authority - -HNSR - where an authorized endpoint is reachable right now -``` - -A future `hnsr.service/v1` profile may allow HNSR to consume HRM controller and -delegation proofs. HRM does not require HNSR for retrieval, and HNSR does not -require HRM for unnamed node rendezvous. - -## Implementation plan - -The first reference implementation should be a small library and CLI, not a -consensus patch. - -Recommended components are: - -1. A Rust crate that encodes, signs, decodes, and validates HRM Core objects. -2. A command-line tool with `create`, `sign`, `publish`, `fetch`, `inspect`, and - `verify` operations. -3. An HNS adapter that reads and writes the version `0` commitment record. -4. Deterministic positive and negative vectors shared with a JavaScript - implementation. -5. A first HNS-local overlay-service profile. -6. A read-only experimental IP-prefix profile that compares HRM results with - existing RPKI state and never changes routing. - -`hsd` and `hnsd` need no consensus modification for the core experiment. Wallet -support may improve publication ergonomics but is not required for validation. - -## Deployment gates - -HRM should advance in independently reviewed stages. - -### Stage 0: Core vectors - -- finalize CBOR encodings; -- publish controller-signature and commitment vectors; -- test malformed and non-canonical inputs across implementations. - -### Stage 1: HNS-local pilot - -- use only identifiers whose profiles are explicitly scoped to opt-in HNS - overlays; -- test owner transfer, controller rotation, revocation, expiry, reorganization, - data loss, and parent delegation; -- run on regtest and testnet before mainnet publication. - -### Stage 2: Multi-operator retrieval - -- replicate envelopes over independent transports; -- measure availability, latency, cache behavior, and denial-of-service cost; -- perform independent security review. - -### Stage 3: External-resource audit - -- use legitimately allocated test resources; -- validate but do not originate routing or registry changes; -- compare HRM delegation results with RPKI and registry state; -- document conflicts and revocation latency. - -### Stage 4: Profile and adapter proposals - -- submit each operational profile separately; -- require multi-operator evidence and negative test vectors; -- coordinate any wire-level assignment with the responsible standards and - registry community; -- keep production-changing adapters opt-in until their own threat models and - rollback procedures are accepted. - -No permanent IANA, IEEE, HNS P2P, or other wire assignment is requested by this -HIP. - -## Test requirements - -Before this proposal can move beyond Draft, the repository should contain -deterministic vectors covering at least: - -- canonical payload and envelope encoding; -- valid and invalid deterministic secp256k1 controller signatures; -- commitment-hash match and mismatch; -- HNS subject and active-network match and mismatch; -- commitment/payload sequence match and mismatch; -- selection among multiple commitments; -- equal-sequence conflicting commitments; -- payload, resource, and delegation expiry; -- name transfer with commitment retention, removal, and replacement; -- controller-key mismatch; -- valid one-level and multi-level delegation; -- invalid containment, rights escalation, and forbidden subdelegation; -- missing and revoked parent delegation; -- cycle and recursion-limit rejection; -- valid and invalid external proof stubs; -- corrupt, unavailable, and equivocating retrieval sources; -- accepted and rejected Handshake reorganization cases. - -External-resource profiles require their own additional vectors. - -## Rationale - -### Why use an on-chain hash instead of placing the manifest on chain? - -Handshake resource data is limited to 512 bytes. Internet resource proofs, -delegation graphs, certificates, and metadata can be substantially larger. -Committing only a hash keeps consensus state bounded and allows untrusted -replication. - -### Why use `TXT` instead of a new namestate version? - -`TXT` works under current consensus and can coexist with ordinary name -resolution. A new version would require ecosystem coordination before the core -security model has deployment evidence. - -### Why require a controller signature when HNS already commits the hash? - -The second key separates durable name custody from operational resource control -and gives parent delegations a stable cryptographic target. It also prevents a -name transfer alone from silently acquiring delegated infrastructure authority. -Version 1 uses the same key and signature family as the draft HNSR protocol so -an HRM service profile can reuse an existing HNSR root key. - -### Why not accept any resource claimed by an HNS owner? - -Many public resources already have globally coordinated meanings. Treating an -HNS auction as ownership of an existing IP prefix, ASN, port, protocol number, -or EtherType would create collisions that browsers and application gateways -cannot repair. - -### Why separate resource profiles? - -An IPv6 prefix has containment semantics; an ASN usually does not. A port has -different policy and operational consequences from a virtual service ID. A -single generic validator cannot safely guess these rules. - -### Why make manifests complete snapshots? - -Current snapshots make removal an unambiguous revocation and avoid requiring a -client to replay an unbounded off-chain log. Handshake history remains -available for auditing. - -## Alternatives considered - -### Independently allocate public wire values through HNS - -Rejected for HRM Core. Existing routers, switches, kernels, and protocol -implementations require coordinated meanings. HNS-local profiles may allocate -values only inside explicit overlays or formally delegated extension spaces. - -### Store unverified claims in plain TXT records - -Rejected as an authorization protocol. Plain text is useful for discovery but -does not define canonical encoding, controller continuity, authority proofs, -delegation containment, expiry, or revocation. - -### Put every resource and delegation directly on Handshake - -Rejected for version 1 because of the 512-byte limit, chain growth, privacy, -proof size, and the burden placed on unrelated full nodes. - -### Require a single HRM storage network - -Rejected. Content addressing makes storage replaceable. Mandating one delivery -network would recreate the availability dependency HRM is intended to avoid. - -### Make HRM immediately authoritative for router configuration - -Rejected. Verification formats, external trust roots, operational policy, -rollback, and multi-operator experience must be established first. - -## Open questions - -The following items should be resolved during Draft review: - -- whether a later version should register Ed25519 or another optional controller - algorithm in addition to mandatory secp256k1; -- whether one retrieval URI should be required or out-of-band retrieval should - be valid without an advertised URI; -- whether a future compact binary commitment should replace or supplement TXT; -- exact default clock-skew and Handshake-finality guidance; -- registry and review process for resource-profile identifiers; -- whether controller rotation should gain a cross-signature mechanism in Core; -- which HNS-local profile is small enough to serve as the first complete pilot; -- whether future selective disclosure should use an authenticated map based on - HIP-0016, another accumulator, or independent signed objects. - -## References - -1. RFC 2119, *Key words for use in RFCs to Indicate Requirement Levels*. -2. RFC 8174, *Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words*. -3. RFC 8949, *Concise Binary Object Representation (CBOR)*. -4. RFC 4648, *The Base16, Base32, and Base64 Data Encodings*. -5. RFC 7020, *The Internet Numbers Registry System*. -6. RFC 6480, *An Infrastructure to Support Secure Internet Routing*. -7. RFC 9323, *A Profile for RPKI Signed Checklists (RSCs)*. -8. RFC 8126, *Guidelines for Writing an IANA Considerations Section in RFCs*. -9. HIP-0015, *Update Chains*. -10. HIP-0016, *Escher Update Chains for decentralized subdomains*. -11. Draft HIP, *Handshake P2P Rendezvous and Authenticated Service Relay*. -12. Handshake developer documentation, *Resource Records*. -13. IANA, *Governance of the IANA Functions*. -14. IANA, *Number-related Registries*. -15. IANA, *Protocol Parameter Assignments*. From a5c2e83f79a9820555eb2ac16613d093ff943ec7 Mon Sep 17 00:00:00 2001 From: Jaron Rosenau Date: Mon, 3 Aug 2026 04:22:19 -0700 Subject: [PATCH 3/4] Define HNSA named rendezvous routes --- HIP-xxxx-HNSA-HNSR.md | 342 ++++++++++++++++++++++++++++++++++++++++++ HIP-xxxx-HNSA.md | 52 ++++--- 2 files changed, 371 insertions(+), 23 deletions(-) create mode 100644 HIP-xxxx-HNSA-HNSR.md diff --git a/HIP-xxxx-HNSA-HNSR.md b/HIP-xxxx-HNSA-HNSR.md new file mode 100644 index 0000000..4a6794f --- /dev/null +++ b/HIP-xxxx-HNSA-HNSR.md @@ -0,0 +1,342 @@ +# HIP-xxxx: HNSA Profile for Handshake P2P Rendezvous + +```text +Number: HIP-xxxx +Title: HNSA Profile for Handshake P2P Rendezvous +Type: Standards Track +Status: Draft +Authors: Jaron Rosenau <@denuoweb> +Created: 2026-08-03 +Requires: Named Service Authority for Handshake (draft HIP) + Handshake P2P Rendezvous and Authenticated Service Relay (draft HIP) +``` + +## Abstract + +This document defines the named-service adapter between Handshake Named +Service Authority (HNSA) and Handshake P2P Rendezvous and Authenticated Service +Relay (HNSR). + +HNSA authenticates a stable named service and delegates short-lived endpoint +keys. HNSR discovers those endpoints and carries opaque application streams +through relays. This adapter defines a versioned named route record that binds +the two protocols without changing the existing unnamed `HNS_NODE_V1` route +format or making a relay an identity authority. + +The complete route chain is: + +```text +authenticated current HNS name state + -> hsa1 root key and epoch + -> HNSA ServiceAuthorizationV1 + -> HNSA EndpointDelegationV1 + -> HNSR NamedRouteRecordV2 + -> one or more HNSR RelayTicketV1 objects + -> endpoint-authenticated application session +``` + +The adapter introduces no consensus rule, permanent packet assignment, new +bootstrap network, browser permission, or mandatory public gateway. + +## Goals + +- use one transport-independent named-service authority chain; +- keep unnamed Handshake node reachability wire compatible; +- keep route lookup stable across endpoint, relay, and provider rotation; +- let relays forward opaque traffic without becoming service authorities; +- permit bounded route storage even when the storing peer does not resolve the + HNS name; +- require clients to validate current authenticated HNS state before use; +- support read-only mobile and browser clients that do not mine, relay, store + routes, or publish endpoints; and +- give each application profile control over capabilities, constraints, + framing, lifetimes, and browser policy. + +## Non-goals + +This document does not define an application protocol, pool-statistics schema, +HTTP gateway, TLS policy, miner control API, wallet workflow, or public profile +number. It does not make route availability proof of service honesty, uptime, +or reputation. + +## Requirements language + +The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, +**SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **NOT RECOMMENDED**, **MAY**, and +**OPTIONAL** in this document are to be interpreted as described in BCP 14 +when, and only when, they appear in all capitals. + +## Versioning and assignments + +This adapter reuses the HNSR envelope, rendezvous opcodes, relay reservation, +relay ticket, circuit, flow-control, and error encodings. It adds no packet +opcode. + +Named routes use: + +```text +route record version = 2 +authority type = 1 +``` + +Unnamed `HNS_NODE_V1` routes continue to use route-record version `1`, +authority type `0`, and the endpoint-key self-authorization defined by HNSR. +Implementations MUST NOT reinterpret either format as the other. + +The `profile_id` carried by an HNSR reservation, relay ticket, route, and +circuit is the same `profile_id` carried by the HNSA service authorization. +Profile ID zero is invalid. Profile ID `1` remains reserved for unnamed +`HNS_NODE_V1` and MUST NOT be used by a named route. Application profiles MUST +use private values during development until an assignment is accepted. + +## Stable named route key + +The rendezvous key for a named service is: + +```text +BLAKE2b-256( + "HNSR-NAMED-ROUTE-V1\0" + || network_magic_u32le + || name_hash + || service_name_length_u8 + || canonical_service_name + || profile_id_u16le +) +``` + +The inputs are the exact HNSA `ServiceIdentity` fields. The route key therefore +does not change when a service authorization, endpoint key, relay, reservation, +address, or hosting provider changes. It is a lookup key, not an authentication +key, and reveals only a deterministic hash of an identity a requester already +knows. + +For the deterministic regtest identity used by the Rust implementation: + +```text +network_magic = 0xae3895cf +name_hash = 0f repeated 32 times +service_name = pool-stats +profile_id = 0xff00 +route_key = 7e1a513c71518f69164fdcc754202a769 + e8cbd2dd980da3fd231b9b0de90e60b +``` + +The implementation fixture also pins the complete canonical route record and +every signature. Independent implementations MUST reproduce that complete +vector before interoperating. + +## Named route record + +```text +NamedRouteRecordV2 { + version: u8 + authority_type: u8 + route_key: u8[32] + profile_id: u16 + record_sequence: u64 + issued_at: u64 + expires_at: u64 + authorization_length: u16 + service_authorization: u8[authorization_length] + endpoint_delegation_length: u16 + endpoint_delegation: u8[endpoint_delegation_length] + ticket_count: u8 + tickets: RelayTicketV1[ticket_count] + endpoint_signature_length: u8 + endpoint_signature: u8[endpoint_signature_length] +} +``` + +`service_authorization` is the complete canonical HNSA +`ServiceAuthorizationV1`, including its root signature. +`endpoint_delegation` is the complete canonical HNSA +`EndpointDelegationV1`, including its service signature. + +The endpoint-signature digest is: + +```text +BLAKE2b-256( + "HNSR-HNSA-ROUTE-RECORD-V2\0" + || all preceding canonical NamedRouteRecordV2 fields +) +``` + +The signature MUST be canonical strict-DER, low-S secp256k1 and MUST verify +under the endpoint key in the embedded HNSA delegation. + +## Canonical and resource limits + +- `version` MUST equal `2` and `authority_type` MUST equal `1`; +- `record_sequence` MUST be nonzero; +- `issued_at` MUST be less than `expires_at`; +- a route lifetime MUST be at most 7,200 seconds and MAY be reduced by the + application profile; +- the route MUST NOT begin before the endpoint delegation; +- the route MUST NOT expire after the endpoint delegation; +- `ticket_count` MUST be 1 through 8; +- duplicate canonical tickets are invalid; +- every ticket MUST bind the route network, profile, and endpoint key; +- every ticket MUST be active for the complete route lifetime; +- the complete encoded route MUST be at most 8,192 bytes; +- each embedded HNSA object retains its HNSA size bound; +- signatures MUST be 1 through 80 bytes; and +- noncanonical lengths, unsupported versions, unknown authority types, + malformed keys or signatures, and trailing bytes MUST be rejected. + +An application profile MUST define a maximum route lifetime no greater than +7,200 seconds, allowed service-authorization flags, allowed and required +endpoint capabilities, the expected detached constraints hash, inner-session +authentication, framing, and resource limits. + +## Client validation + +A requester MUST complete all of the following before sending application +data: + +1. Decode the route and enforce its canonical and allocation bounds. +2. Derive the HNSA service identity expected by the user or application. The + embedded object MUST NOT choose a different expected identity. +3. Recompute and match the named route key. +4. Obtain sufficiently current authenticated HNS name state under local + finality policy and select exactly one canonical `hsa1` record. +5. Validate the complete HNSA service authorization against that root key, + epoch, identity, current height, profile, and allowed flags. +6. Validate the complete HNSA endpoint delegation against that authorization, + current time, capabilities, and detached constraints. +7. Require all profile-defined capability bits. +8. Validate route sequence, time interval, profile limits, and delegation + lifetime containment. +9. Validate every relay ticket, including network, profile, endpoint key, + reservation, address, limits, time interval, relay signature, and endpoint + confirmation. Duplicate tickets are rejected. +10. Validate the endpoint signature over the complete route. +11. Establish the profile-defined endpoint-authenticated inner session before + accepting application bytes. + +Failure at any step MUST fail closed. A requester MUST NOT substitute an +unauthenticated endpoint, directory result, DNS answer, relay identity, or +conventional-web endpoint under the same HNSA identity. + +The client MUST repeat the HNSA authorization check when its accepted HNS name +state changes or advances beyond a cached authorization interval. + +## Relay and rendezvous behavior + +A relay authenticates reservations and signs tickets using the HNSR rules. It +MUST enforce an explicit allowlist of supported profile IDs before allocating +reservation or circuit state. Support for `HNS_NODE_V1` does not imply support +for any named profile, and support for one named profile does not enable +another. + +Relays forward opaque bytes and do not need the HNSA root key. A relay ticket +is reachability evidence, not authority over the named service. + +A rendezvous node MUST enforce canonical parsing, route-key derivation, +endpoint/delegation/ticket signatures, expiry, size, per-key, global, and +per-source admission limits before retaining a record. It MAY additionally +validate the HNSA root signature against local authenticated HNS state. +Allowing bounded storage without that optional root check prevents HNS name +lookups from becoming a publication bottleneck; it does not weaken requester +validation because every requester performs the complete current-state check. + +Named routes MUST NOT be returned by the unnamed `SAMPLEROUTES` operation. +They are returned only for an explicit keyed lookup. A rendezvous response is +untrusted input and does not attest that a service is authorized or online. + +## Replacement and conflict handling + +`record_sequence` is a route-publication counter scoped to: + +```text +(route_key, endpoint_key) +``` + +It is independent of the HNSA endpoint sequence so an endpoint can refresh +routes and relay tickets without issuing a new delegation. Publishers MUST +persistently reserve a new nonzero sequence before signing. Crash gaps are +safe; reuse is not. + +A storage node MUST replace a record only with a greater sequence for the same +route and endpoint key. Equal sequences with different canonical bytes are a +conflict and MUST fail closed. Several currently authorized endpoint keys MAY +coexist under one route key for redundancy. + +## Browser and read-only observer behavior + +A mobile browser, browser extension, or monitoring client MAY discover and +verify a named service without advertising an HNSR role, accepting inbound +circuits, mining, publishing a route, or storing records for other peers. + +The security origin is the HNSA tuple: + +```text +(network_magic, name_hash, canonical_service_name, profile_id) +``` + +Relay addresses, public gateways, endpoint keys, and route sequences MUST NOT +change or merge that origin. + +An application profile MAY expose a signed read-only representation through a +direct or conventional web endpoint for clients that cannot open an HNSR +circuit. Such a representation MUST carry enough canonical signed objects for +the client to validate its application payload and HNSA chain. The serving URL, +TLS connection, extension package, or downloaded script MUST NOT be treated as +the HNSA trust root. If a client only parses structure and does not perform +cryptographic and current-chain validation, its UI MUST label the data +unverified. + +HNSA/HNSR authorization does not grant local-network, VPN, device, persistent +background, wallet, or mining permission. Those remain explicit browser or +operating-system choices. + +## Privacy and abuse considerations + +Keyed lookup exposes the route key and requester-to-rendezvous relationship. +Relays observe connection timing, byte counts, and both outer peers, but cannot +authenticate or modify a correctly protected inner session. Application +profiles SHOULD minimize public fields, use short lifetimes, support several +rendezvous paths, and avoid stable identifiers not required by validation. + +Storage and signature verification are denial-of-service surfaces. Nodes MUST +bound bytes before allocation, candidate count before expensive verification, +records per key and source, total records, verification rate, and response +size. HNSR work MUST be scheduled below direct Handshake consensus and block +propagation traffic. + +## Compatibility and transition + +This adapter does not alter the unnamed route format currently implemented for +HNSR. Existing unnamed nodes can continue publishing and consuming version-1 +records while implementations add version-2 named routes. + +The earlier HNSR draft described an `hnsr1` TXT root and HNSR-specific named +authorization domains. Those objects are not HNSA objects and are not accepted +by this adapter. New named deployments use `hsa1` and the exact HNSA encodings. +Implementations may recognize the earlier experiment in a separately selected +test configuration, but MUST NOT silently convert it, use it as fallback, or +share browser identity with HNSA routes. + +No permanent mainnet assignment is requested while HNSA, this adapter, and +application profiles remain Draft. + +## Deployment gates + +1. Publish exact positive and negative vectors for route key, record encoding, + signatures, malformed lengths, wrong networks, wrong identities, expiry, + capability failures, and equal-sequence conflicts. +2. Demonstrate deterministic Rust and JavaScript decoding and verification. +3. Exercise multi-relay publication, endpoint rotation, relay failure, route + expiry, HNSA epoch rotation, and chain reorganization on regtest. +4. Demonstrate a read-only mobile client and browser extension that validate + the same signed application snapshot without taking a network role. +5. Measure lookup latency, signature-verification cost, storage churn, direct + block-propagation impact, and failure behavior under load. +6. Complete independent security and browser-origin review before requesting + public profile or wire assignments. + +## References + +1. RFC 2119, *Key words for use in RFCs to Indicate Requirement Levels*. +2. RFC 8174, *Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words*. +3. Draft HIP, *Named Service Authority for Handshake*. +4. Draft HIP, *Handshake P2P Rendezvous and Authenticated Service Relay*. diff --git a/HIP-xxxx-HNSA.md b/HIP-xxxx-HNSA.md index 25340f7..c8e05b4 100644 --- a/HIP-xxxx-HNSA.md +++ b/HIP-xxxx-HNSA.md @@ -9,6 +9,8 @@ Authors: Jaron Rosenau <@denuoweb> Created: 2026-08-01 Related: Handshake P2P Rendezvous and Authenticated Service Relay (draft HIP) + HNSA Profile for Handshake P2P Rendezvous + (draft HIP) ``` ## Abstract @@ -398,11 +400,11 @@ Rules: - `name_hash` MUST match the name containing the current `hsa1` record; - `authority_epoch` MUST equal the current `hsa1` epoch; - `service_name` MUST be canonical; -- `profile_id` MUST be recognized by the relying client; +- `profile_id` MUST be nonzero and recognized by the relying client; - `service_key` MUST be a valid compressed secp256k1 public key; - `flags` MUST contain only bits defined by the selected profile; -- `serial` MUST increase when the root key replaces an authorization for the - same service identity; +- `serial` MUST be nonzero and MUST increase when the root key replaces an + authorization for the same service identity; - `valid_until_height` MUST be greater than `valid_from_height`; - an authorization MUST be rejected outside that block-height interval; - `max_endpoint_lifetime` MUST be 300 through 604,800 seconds; @@ -458,8 +460,8 @@ Rules: - `network_magic` MUST match the active Handshake network; - `authorization_id` MUST identify the validated service authorization; - `endpoint_key` MUST be a valid compressed secp256k1 public key; -- `endpoint_sequence` MUST increase for replacement of the same logical - endpoint under a profile-defined endpoint identifier; +- `endpoint_sequence` MUST be nonzero and MUST increase for replacement of the + same logical endpoint under a profile-defined endpoint identifier; - `issued_at` MUST be less than `expires_at`; - lifetime MUST NOT exceed the service authorization's `max_endpoint_lifetime`; @@ -533,7 +535,7 @@ To validate an endpoint record for named service `S`, a client MUST: A failure at any step MUST fail closed for HNSA authorization. A client MUST NOT silently replace a failed HNSA chain with an endpoint learned from an -unauthenticated directory, relay, DNS response, or legacy fallback. +unauthenticated directory, relay, DNS response, or compatibility fallback. ## Replacement and freshness @@ -623,8 +625,8 @@ or safe. HNSA authenticates control, not reputation. If the authority chain expires, is ambiguous, changes unexpectedly, or fails a signature check, the browser must stop before sending application data. Any -legacy or conventional-web fallback must be separately identified and require -explicit profile and user policy. +conventional-web fallback must be separately identified and require explicit +profile and user policy. ### Network permissions @@ -651,16 +653,21 @@ HNSR Unnamed HNSR node rendezvous remains independent and does not require an HNS name or HNSA. -The current HNSR draft uses an `hnsr1` root record and HNSR-specific service and -endpoint signature domains. Adoption of this HIP would require a separate HNSR -revision that either consumes `hsa1` authority directly or defines an explicit -compatibility transition. This HIP does not silently change the existing HNSR -draft or claim wire compatibility before that revision. +The companion *HNSA Profile for Handshake P2P Rendezvous* draft defines that +revision. New named HNSR routes use route-record version `2`, authority type +`1`, the `hsa1` trust root, and the exact HNSA authorization and delegation +objects defined here. The route key is stable across endpoint and relay +rotation because it is derived from the HNSA service identity. + +Unnamed `HNS_NODE_V1` routes retain route-record version `1`, authority type +`0`, and endpoint-key self-authorization. No version-1 named route or `hnsr1` +object is reinterpreted as HNSA. The two formats therefore fail closed rather +than relying on an implicit conversion. -## Backwards compatibility +## Compatibility -The `hsa1` record is valid existing HNS `TXT` data. Legacy full nodes, miners, -resolvers, wallets, and applications may ignore it. +The `hsa1` record is valid existing HNS `TXT` data. Full nodes, miners, +resolvers, wallets, and applications that do not implement HNSA may ignore it. HNSA-aware clients are optional consumers. Names without a valid `hsa1` record continue operating under existing Handshake and DNS rules. @@ -757,8 +764,8 @@ record can reveal which HNS service they intend to use. ## Reference implementation plan -The first implementation should extract the authority objects and validators -from the HNSR research implementation into a transport-independent library. +The first implementation should provide the authority objects and validators +in a transport-independent library. Recommended deliverables are: @@ -771,8 +778,8 @@ Recommended deliverables are: 7. A mobile-browser diagnostic that displays the validated authority chain and preserves origin across direct and relayed endpoints. -No `hsd` consensus change is required. HNSR integration, wallet ergonomics, and -browser support remain separate implementation changes. +No Handshake consensus change is required. HNSR integration, wallet ergonomics, +and browser support remain separate implementation changes. ## Deployment gates @@ -795,7 +802,7 @@ browser support remain separate implementation changes. - carry HNSA service authorization and endpoint delegation with named HNSR routes; - demonstrate direct and relayed endpoints under one stable service identity; -- test route expiry, relay failover, stale authorization, and no legacy +- test route expiry, relay failover, stale authorization, and no unauthenticated fallback contact. ### Stage 3: Independent clients and operators @@ -908,7 +915,6 @@ The following items remain for Draft review and implementation evidence: addition to bounded lifetime and global epoch revocation; - whether a future version should support threshold or hardware-backed root keys; -- exact transition from the HNSR draft's `hnsr1` record to `hsa1`; - whether direct web and HNSR should share one web profile or use separate profile IDs with explicit origin relationships; - default browser presentation for HNS-authorized service identity. @@ -921,4 +927,4 @@ The following items remain for Draft review and implementation evidence: 4. SEC 1, *Elliptic Curve Cryptography*. 5. Handshake developer documentation, *Resource Records*. 6. Draft HIP, *Handshake P2P Rendezvous and Authenticated Service Relay*. -7. Handshake `hsd` authenticated name-proof and resource validation behavior. +7. Handshake authenticated name-proof and resource validation behavior. From c7bdd2e62926c8db791a39ebc975715ec4f0132f Mon Sep 17 00:00:00 2001 From: Jaron Rosenau Date: Wed, 12 Aug 2026 02:21:26 -0700 Subject: [PATCH 4/4] Define HNSA as an HRM resource profile --- HIP-xxxx-HNSA-HNSR.md | 305 ++++++---- HIP-xxxx-HNSA.md | 1319 ++++++++++++++++++++--------------------- HIP-xxxx-HRM.md | 1169 ++++++++++++++++++++++++++++++++++++ 3 files changed, 2006 insertions(+), 787 deletions(-) create mode 100644 HIP-xxxx-HRM.md diff --git a/HIP-xxxx-HNSA-HNSR.md b/HIP-xxxx-HNSA-HNSR.md index 4a6794f..8bdb5d5 100644 --- a/HIP-xxxx-HNSA-HNSR.md +++ b/HIP-xxxx-HNSA-HNSR.md @@ -1,36 +1,42 @@ -# HIP-xxxx: HNSA Profile for Handshake P2P Rendezvous +# HIP-xxxx: HRM/HNSA Profile for Handshake P2P Rendezvous ```text Number: HIP-xxxx -Title: HNSA Profile for Handshake P2P Rendezvous +Title: HRM/HNSA Profile for Handshake P2P Rendezvous Type: Standards Track Status: Draft Authors: Jaron Rosenau <@denuoweb> Created: 2026-08-03 -Requires: Named Service Authority for Handshake (draft HIP) +Requires: Handshake Resource Manifests (draft HIP) + Named Service Authority Profile for Handshake Resource Manifests + (draft HIP) Handshake P2P Rendezvous and Authenticated Service Relay (draft HIP) ``` ## Abstract -This document defines the named-service adapter between Handshake Named -Service Authority (HNSA) and Handshake P2P Rendezvous and Authenticated Service -Relay (HNSR). +This document defines the named-service adapter between Handshake Resource +Manifests (HRM), Handshake Named Service Authority (HNSA), and Handshake P2P +Rendezvous and Authenticated Service Relay (HNSR). -HNSA authenticates a stable named service and delegates short-lived endpoint +HRM and HNSA authenticate a stable named service, delegate that service to an +operational key, and allow the service key to authorize short-lived endpoint keys. HNSR discovers those endpoints and carries opaque application streams through relays. This adapter defines a versioned named route record that binds -the two protocols without changing the existing unnamed `HNS_NODE_V1` route -format or making a relay an identity authority. +the protocols without changing the existing unnamed `HNS_NODE_V1` route or +making a relay, rendezvous node, manifest host, or DNS server an identity +authority. The complete route chain is: ```text authenticated current HNS name state - -> hsa1 root key and epoch - -> HNSA ServiceAuthorizationV1 + -> hrm1 commitment + -> controller-signed current HRM envelope + -> hns.named-service/v1 resource + -> current HRM delegation to a service key -> HNSA EndpointDelegationV1 - -> HNSR NamedRouteRecordV2 + -> HNSR NamedRouteRecordV3 -> one or more HNSR RelayTicketV1 objects -> endpoint-authenticated application session ``` @@ -40,13 +46,17 @@ bootstrap network, browser permission, or mandatory public gateway. ## Goals -- use one transport-independent named-service authority chain; +- consume the HRM/HNSA authority chain without introducing another manifest or + on-chain root-key record; - keep unnamed Handshake node reachability wire compatible; -- keep route lookup stable across endpoint, relay, and provider rotation; +- keep route lookup stable across HRM, service-key, endpoint, relay, and + provider rotation; +- avoid embedding a potentially large complete HRM envelope in every route; - let relays forward opaque traffic without becoming service authorities; -- permit bounded route storage even when the storing peer does not resolve the - HNS name; -- require clients to validate current authenticated HNS state before use; +- permit bounded route storage when a storing peer does not resolve the HNS + name or retrieve the HRM; +- require clients to validate current authenticated HNS and HRM state before + using a route; - support read-only mobile and browser clients that do not mine, relay, store routes, or publish endpoints; and - give each application profile control over capabilities, constraints, @@ -54,8 +64,9 @@ bootstrap network, browser permission, or mandatory public gateway. ## Non-goals -This document does not define an application protocol, pool-statistics schema, -HTTP gateway, TLS policy, miner control API, wallet workflow, or public profile +This document does not define HRM Core, HNSA resource semantics, an application +protocol, username syntax, payment schema, pool-statistics schema, HTTP +gateway, TLS policy, miner control API, wallet workflow, or public profile number. It does not make route availability proof of service honesty, uptime, or reputation. @@ -72,22 +83,27 @@ This adapter reuses the HNSR envelope, rendezvous opcodes, relay reservation, relay ticket, circuit, flow-control, and error encodings. It adds no packet opcode. -Named routes use: +HRM-backed named routes use experimental values: ```text -route record version = 2 -authority type = 1 +route record version = 3 +authority type = 2 ``` +Version `2`, authority type `1`, identifies the superseded experimental +`hsa1`-backed named route. The new values prevent those bytes from being +reinterpreted as an HRM-backed chain. + Unnamed `HNS_NODE_V1` routes continue to use route-record version `1`, authority type `0`, and the endpoint-key self-authorization defined by HNSR. -Implementations MUST NOT reinterpret either format as the other. +Implementations MUST NOT reinterpret any of the three formats as another. The `profile_id` carried by an HNSR reservation, relay ticket, route, and -circuit is the same `profile_id` carried by the HNSA service authorization. +circuit is the HNSA application profile ID in the named-service identifier. Profile ID zero is invalid. Profile ID `1` remains reserved for unnamed `HNS_NODE_V1` and MUST NOT be used by a named route. Application profiles MUST -use private values during development until an assignment is accepted. +use documented private values during development until an assignment is +accepted. ## Stable named route key @@ -104,13 +120,13 @@ BLAKE2b-256( ) ``` -The inputs are the exact HNSA `ServiceIdentity` fields. The route key therefore -does not change when a service authorization, endpoint key, relay, reservation, -address, or hosting provider changes. It is a lookup key, not an authentication -key, and reveals only a deterministic hash of an identity a requester already -knows. +The inputs are the exact HNSA named-service identity fields. The route key does +not change when an HRM sequence, controller, service delegation, endpoint key, +relay, reservation, address, or hosting provider changes. It is a lookup key, +not an authentication key, and reveals only a deterministic hash of an +identity a requester already knows. -For the deterministic regtest identity used by the Rust implementation: +For the deterministic regtest identity used by the earlier implementation: ```text network_magic = 0xae3895cf @@ -121,14 +137,14 @@ route_key = 7e1a513c71518f69164fdcc754202a769 e8cbd2dd980da3fd231b9b0de90e60b ``` -The implementation fixture also pins the complete canonical route record and -every signature. Independent implementations MUST reproduce that complete -vector before interoperating. +The route-key calculation is unchanged by the HRM migration. New fixtures MUST +pin the complete version-3 route, HRM resource and delegation IDs, endpoint +delegation, tickets, and signatures. ## Named route record ```text -NamedRouteRecordV2 { +NamedRouteRecordV3 { version: u8 authority_type: u8 route_key: u8[32] @@ -136,8 +152,10 @@ NamedRouteRecordV2 { record_sequence: u64 issued_at: u64 expires_at: u64 - authorization_length: u16 - service_authorization: u8[authorization_length] + service_resource_id: u8[32] + service_delegation_id: u8[32] + service_generation: u64 + service_controller_key: u8[33] endpoint_delegation_length: u16 endpoint_delegation: u8[endpoint_delegation_length] ticket_count: u8 @@ -147,27 +165,37 @@ NamedRouteRecordV2 { } ``` -`service_authorization` is the complete canonical HNSA -`ServiceAuthorizationV1`, including its root signature. -`endpoint_delegation` is the complete canonical HNSA -`EndpointDelegationV1`, including its service signature. +All integers use little-endian encoding. `endpoint_delegation` is the complete +canonical HNSA `EndpointDelegationV1`, including its service signature. + +The route deliberately carries HRM-derived IDs, generation, and the service +controller key instead of a complete HRM envelope. The compact fields allow a +storage node to check internal bindings and signatures. They are not an HRM +proof: a requester MUST retrieve and validate the current HRM and match every +field against it. -The endpoint-signature digest is: +Let `canonical_route_body` be the exact bytes from `version` through the final +canonical relay ticket, excluding `endpoint_signature_length` and +`endpoint_signature`. The endpoint-signature digest is: ```text BLAKE2b-256( - "HNSR-HNSA-ROUTE-RECORD-V2\0" - || all preceding canonical NamedRouteRecordV2 fields + "HNSR-HRM-HNSA-ROUTE-RECORD-V3\0" + || canonical_route_body ) ``` -The signature MUST be canonical strict-DER, low-S secp256k1 and MUST verify -under the endpoint key in the embedded HNSA delegation. +The signature MUST be canonical strict-DER, low-S secp256k1 and verify under +the endpoint key in the embedded HNSA endpoint delegation. ## Canonical and resource limits -- `version` MUST equal `2` and `authority_type` MUST equal `1`; -- `record_sequence` MUST be nonzero; +- `version` MUST equal `3` and `authority_type` MUST equal `2`; +- `record_sequence` and `service_generation` MUST be nonzero; +- `service_controller_key` MUST be a valid compressed secp256k1 key; +- the service resource ID, delegation ID, generation, and controller key MUST + match the embedded endpoint delegation and its verifying key where + applicable; - `issued_at` MUST be less than `expires_at`; - a route lifetime MUST be at most 7,200 seconds and MAY be reduced by the application profile; @@ -178,14 +206,14 @@ under the endpoint key in the embedded HNSA delegation. - every ticket MUST bind the route network, profile, and endpoint key; - every ticket MUST be active for the complete route lifetime; - the complete encoded route MUST be at most 8,192 bytes; -- each embedded HNSA object retains its HNSA size bound; +- the endpoint delegation MUST satisfy HNSA's 320-byte bound; - signatures MUST be 1 through 80 bytes; and - noncanonical lengths, unsupported versions, unknown authority types, malformed keys or signatures, and trailing bytes MUST be rejected. An application profile MUST define a maximum route lifetime no greater than -7,200 seconds, allowed service-authorization flags, allowed and required -endpoint capabilities, the expected detached constraints hash, inner-session +7,200 seconds, allowed service-resource flags, allowed and required endpoint +capabilities, the expected detached constraints hash, inner-session authentication, framing, and resource limits. ## Client validation @@ -194,31 +222,42 @@ A requester MUST complete all of the following before sending application data: 1. Decode the route and enforce its canonical and allocation bounds. -2. Derive the HNSA service identity expected by the user or application. The - embedded object MUST NOT choose a different expected identity. +2. Derive the HNS name, canonical service name, and application profile ID + expected by the user or application. The route MUST NOT choose a different + expected identity. 3. Recompute and match the named route key. -4. Obtain sufficiently current authenticated HNS name state under local - finality policy and select exactly one canonical `hsa1` record. -5. Validate the complete HNSA service authorization against that root key, - epoch, identity, current height, profile, and allowed flags. -6. Validate the complete HNSA endpoint delegation against that authorization, - current time, capabilities, and detached constraints. -7. Require all profile-defined capability bits. -8. Validate route sequence, time interval, profile limits, and delegation - lifetime containment. -9. Validate every relay ticket, including network, profile, endpoint key, - reservation, address, limits, time interval, relay signature, and endpoint - confirmation. Duplicate tickets are rejected. -10. Validate the endpoint signature over the complete route. -11. Establish the profile-defined endpoint-authenticated inner session before +4. Obtain sufficiently current authenticated HNS namestate under local + finality policy and select its one current canonical `hrm1` commitment. +5. Retrieve and validate the committed current HRM envelope under HRM Core, + including its controller signature, subject, network, sequence, validity, + resources, delegations, and current-snapshot rules. +6. Construct the expected HNSA named-service identifier and resource ID, then + select and validate exactly one current `hns.named-service/v1` resource. +7. Select and validate exactly one current HNSA service-controller delegation, + including its ID, generation, controller key, rights, constraints, and + interval. +8. Match the route's profile ID, service resource ID, service delegation ID, + service generation, and service controller key to that verified HRM state. +9. Validate the complete endpoint delegation against the current service + delegation, current time, capabilities, detached constraints, and service + controller signature. +10. Validate route sequence, time interval, profile limits, and endpoint- + delegation lifetime containment. +11. Validate every relay ticket, including network, profile, endpoint key, + reservation, address, limits, time interval, relay signature, and endpoint + confirmation. Duplicate tickets are rejected. +12. Validate the endpoint signature over the complete canonical route body. +13. Establish the profile-defined endpoint-authenticated inner session before accepting application bytes. Failure at any step MUST fail closed. A requester MUST NOT substitute an -unauthenticated endpoint, directory result, DNS answer, relay identity, or -conventional-web endpoint under the same HNSA identity. +`hsa1` authorization, stale HRM, unauthenticated endpoint, directory result, +DNS answer, relay identity, or conventional-web endpoint under the same +HRM/HNSA identity. -The client MUST repeat the HNSA authorization check when its accepted HNS name -state changes or advances beyond a cached authorization interval. +The requester MUST repeat HRM/HNSA validation when its accepted HNS namestate +changes, the accepted HRM validity interval ends, or another profile-defined +cache limit expires. ## Relay and rendezvous behavior @@ -228,16 +267,23 @@ reservation or circuit state. Support for `HNS_NODE_V1` does not imply support for any named profile, and support for one named profile does not enable another. -Relays forward opaque bytes and do not need the HNSA root key. A relay ticket -is reachability evidence, not authority over the named service. +Relays forward opaque bytes and do not need the HRM. A relay ticket is +reachability evidence, not authority over the named service. + +A rendezvous node that does not retrieve current HRM state MUST still enforce: + +- canonical bounded parsing; +- route, endpoint-delegation, and ticket time limits; +- consistency of all duplicated IDs, generations, profile IDs, and keys; +- the endpoint-delegation signature under the claimed service controller key; +- relay-ticket signatures and endpoint confirmations; +- the route signature under the delegated endpoint key; and +- per-key, global, per-source, byte, and verification-rate admission limits. -A rendezvous node MUST enforce canonical parsing, route-key derivation, -endpoint/delegation/ticket signatures, expiry, size, per-key, global, and -per-source admission limits before retaining a record. It MAY additionally -validate the HNSA root signature against local authenticated HNS state. -Allowing bounded storage without that optional root check prevents HNS name -lookups from becoming a publication bottleneck; it does not weaken requester -validation because every requester performs the complete current-state check. +Those checks establish internal consistency, not name authority. A rendezvous +node MAY additionally retrieve and validate the current HRM/HNSA chain. Every +requester performs that current-state validation regardless of storage-node +policy. Named routes MUST NOT be returned by the unnamed `SAMPLEROUTES` operation. They are returned only for an explicit keyed lookup. A rendezvous response is @@ -261,35 +307,45 @@ route and endpoint key. Equal sequences with different canonical bytes are a conflict and MUST fail closed. Several currently authorized endpoint keys MAY coexist under one route key for redundancy. +An HRM sequence or service-generation change invalidates routes whose bound +resource, delegation, generation, or controller no longer matches the current +manifest, even if their local route expiry has not yet passed. + ## Browser and read-only observer behavior -A mobile browser, browser extension, or monitoring client MAY discover and -verify a named service without advertising an HNSR role, accepting inbound +A mobile browser, browser extension, wallet, or monitoring client MAY discover +and verify a named service without advertising an HNSR role, accepting inbound circuits, mining, publishing a route, or storing records for other peers. The security origin is the HNSA tuple: ```text -(network_magic, name_hash, canonical_service_name, profile_id) +(network_magic, name_hash, canonical_service_name, application_profile_id) ``` -Relay addresses, public gateways, endpoint keys, and route sequences MUST NOT -change or merge that origin. +HRM retrieval locations, relay addresses, public gateways, controller keys, +endpoint keys, and route sequences MUST NOT change or merge that origin. An application profile MAY expose a signed read-only representation through a direct or conventional web endpoint for clients that cannot open an HNSR -circuit. Such a representation MUST carry enough canonical signed objects for -the client to validate its application payload and HNSA chain. The serving URL, -TLS connection, extension package, or downloaded script MUST NOT be treated as -the HNSA trust root. If a client only parses structure and does not perform -cryptographic and current-chain validation, its UI MUST label the data -unverified. +circuit. The representation MUST carry or identify enough canonical signed +objects for the client to validate its application payload and current +HRM/HNSA chain. The serving URL, TLS connection, extension package, or +downloaded script MUST NOT be treated as the trust root. A client that only +parses structure and does not perform cryptographic and current-chain +validation MUST label the result unverified. + +HRM/HNSA/HNSR authorization does not grant local-network, VPN, device, +persistent-background, wallet-signing, mining, or value-transfer permission. +Those remain explicit application or operating-system decisions. -HNSA/HNSR authorization does not grant local-network, VPN, device, persistent -background, wallet, or mining permission. Those remain explicit browser or -operating-system choices. +## Availability, privacy, and abuse considerations -## Privacy and abuse considerations +An HNSR route may be available while the current HRM envelope is unavailable. +In that case the requester cannot complete authorization and MUST fail closed. +Publishers SHOULD replicate HRM envelopes through independent content-addressed +or authenticated retrieval paths; HNSR itself MAY be one such untrusted +transport. Keyed lookup exposes the route key and requester-to-rendezvous relationship. Relays observe connection timing, byte counts, and both outer peers, but cannot @@ -299,38 +355,47 @@ rendezvous paths, and avoid stable identifiers not required by validation. Storage and signature verification are denial-of-service surfaces. Nodes MUST bound bytes before allocation, candidate count before expensive verification, -records per key and source, total records, verification rate, and response -size. HNSR work MUST be scheduled below direct Handshake consensus and block -propagation traffic. +records per key and source, total records, verification rate, HRM retrieval, +and response size. HNSR work MUST be scheduled below direct Handshake consensus +and block-propagation traffic. ## Compatibility and transition This adapter does not alter the unnamed route format currently implemented for -HNSR. Existing unnamed nodes can continue publishing and consuming version-1 -records while implementations add version-2 named routes. +HNSR. Existing unnamed nodes can continue publishing and consuming version-1, +authority-type-0 records while implementations add version-3, +authority-type-2 named routes. + +The earlier named-route experiment used version `2`, authority type `1`, an +`hsa1` TXT root, and an embedded fixed `ServiceAuthorizationV1`. Those objects +are not HRM/HNSA objects and MUST NOT be accepted by this adapter, converted +implicitly, used as fallback, or share application/browser identity with an +HRM-backed route. An implementation MAY retain them only behind an explicitly +selected experimental compatibility mode. -The earlier HNSR draft described an `hnsr1` TXT root and HNSR-specific named -authorization domains. Those objects are not HNSA objects and are not accepted -by this adapter. New named deployments use `hsa1` and the exact HNSA encodings. -Implementations may recognize the earlier experiment in a separately selected -test configuration, but MUST NOT silently convert it, use it as fallback, or -share browser identity with HNSA routes. +An even earlier HNSR draft described an `hnsr1` TXT root and HNSR-specific +named authorization domains. Those objects are also outside this adapter and +receive no implicit conversion or fallback. -No permanent mainnet assignment is requested while HNSA, this adapter, and -application profiles remain Draft. +No permanent mainnet assignment is requested while HRM, HNSA, this adapter, +and application profiles remain Draft. ## Deployment gates -1. Publish exact positive and negative vectors for route key, record encoding, - signatures, malformed lengths, wrong networks, wrong identities, expiry, - capability failures, and equal-sequence conflicts. -2. Demonstrate deterministic Rust and JavaScript decoding and verification. -3. Exercise multi-relay publication, endpoint rotation, relay failure, route - expiry, HNSA epoch rotation, and chain reorganization on regtest. +1. Publish exact positive and negative vectors for the HRM resource and + delegation, route key, version-3 record, signatures, malformed lengths, + wrong networks, wrong identities, expiry, capability failures, and + equal-sequence conflicts. +2. Demonstrate deterministic Rust and JavaScript HRM/HNSA decoding and + verification before enabling named routes. +3. Exercise multi-relay publication, HRM replacement, service-controller and + endpoint rotation, relay failure, route expiry, and chain reorganization on + regtest. 4. Demonstrate a read-only mobile client and browser extension that validate - the same signed application snapshot without taking a network role. -5. Measure lookup latency, signature-verification cost, storage churn, direct - block-propagation impact, and failure behavior under load. + the same HRM-backed signed application snapshot without taking a network + role. +5. Measure HRM retrieval, lookup latency, signature-verification cost, storage + churn, block-propagation impact, and failure behavior under load. 6. Complete independent security and browser-origin review before requesting public profile or wire assignments. @@ -338,5 +403,7 @@ application profiles remain Draft. 1. RFC 2119, *Key words for use in RFCs to Indicate Requirement Levels*. 2. RFC 8174, *Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words*. -3. Draft HIP, *Named Service Authority for Handshake*. -4. Draft HIP, *Handshake P2P Rendezvous and Authenticated Service Relay*. +3. Draft HIP, *Handshake Resource Manifests*. +4. Draft HIP, *Named Service Authority Profile for Handshake Resource + Manifests*. +5. Draft HIP, *Handshake P2P Rendezvous and Authenticated Service Relay*. diff --git a/HIP-xxxx-HNSA.md b/HIP-xxxx-HNSA.md index c8e05b4..92858c9 100644 --- a/HIP-xxxx-HNSA.md +++ b/HIP-xxxx-HNSA.md @@ -1,30 +1,32 @@ -# HIP-xxxx: Named Service Authority for Handshake +# HIP-xxxx: Named Service Authority Profile for Handshake Resource Manifests ```text -Number: HIP-xxxx -Title: Named Service Authority for Handshake -Type: Standards Track -Status: Draft -Authors: Jaron Rosenau <@denuoweb> -Created: 2026-08-01 -Related: Handshake P2P Rendezvous and Authenticated Service Relay - (draft HIP) - HNSA Profile for Handshake P2P Rendezvous - (draft HIP) +Number: HIP-xxxx +Title: Named Service Authority Profile for Handshake Resource Manifests +Type: Standards Track +Status: Draft +Authors: Jaron Rosenau <@denuoweb> +Created: 2026-08-01 +Requires: Handshake Resource Manifests (draft HIP) +Related: HIP-0002, Handshake P2P Rendezvous and Authenticated Service Relay + (draft HIP) + HRM/HNSA Profile for Handshake P2P Rendezvous + (draft HIP) ``` ## Abstract -This document specifies Handshake Named Service Authority (HNSA), an optional -protocol that allows the owner of a Handshake name to authorize separate keys -for named application services without transferring the name or exposing its -wallet key to an online service. +This document specifies Handshake Named Service Authority (HNSA), the first +application-resource profile for Handshake Resource Manifests (HRM). -A name opts in by publishing one service-authority root key and epoch in its -existing HNS `TXT` resource data. The root key signs bounded service -authorizations. A service key may then authorize short-lived endpoint keys used -by a transport or discovery profile such as HNSR, direct QUIC, HTTPS, messaging, -or another HNS-aware application. +HNSA allows the owner of a Handshake name to create stable named application +services and delegate each service to a separate operational key without +transferring the name or exposing its wallet key to online software. The +current authenticated HNS name selects an HRM commitment. The committed, +controller-signed HRM contains HNSA named-service resources and HRM +delegations to service keys. A service key may then authorize short-lived +endpoint keys used by HNSR, HTTPS, QUIC, messaging, payment, or another +separately specified application profile. The authority chain is: @@ -32,453 +34,424 @@ The authority chain is: current authenticated HNS name state | v -service-authority root key and epoch +HRM hrm1 commitment | v -root-signed named service authorization +controller-signed current HRM envelope + | + v +hns.named-service/v1 resource + | + v +HRM delegation to the service key | v service-signed endpoint delegation | v -profile-specific endpoint or route record +profile-specific endpoint, route, or signed application record ``` -HNSA defines identity and delegation, not transport. It does not define relay -routing, DNS resolution, HTTP framing, browser UI, IP-address allocation, -routing policy, or a general registry for non-service resources. Those concerns -remain in the service profile or protocol that consumes the authorization. - -Version 1 uses current Handshake resource records and requires no consensus -change, hard fork, new namestate version, permanent P2P message assignment, or -new public Internet number. +HNSA does not define a second manifest format or a parallel on-chain authority +record. In particular, this version defines no `hsa1` record and no +root-signed `ServiceAuthorizationV1` object. The HRM envelope, resource, and +delegation encodings are the sole durable authority format. ## Plain-language summary An HNS name is normally controlled by a wallet key that should remain private -and mostly offline. A website, chat service, mobile endpoint, or hosting -provider needs a different key that can be used by online software. +and mostly offline. Application services need operational keys that can rotate, +move between devices, or be delegated to users and providers. + +HRM gives the name owner a signed, content-addressed manifest and a general +delegation model. HNSA defines how one HRM resource means: + +```text +this stable application service exists beneath my HNS name +this service key currently operates it +this endpoint key may serve it for a limited time +``` -HNSA gives the name owner a standard way to say: +For example, a future payment profile may define the user-facing identifier +`jaron@denuoweb` as the HNSA service tuple: ```text -this root key may authorize services for my HNS name -this service key operates my web service -these endpoint keys may serve that service for a limited time +HNS name = denuoweb +service name = jaron +profile = payment profile ``` -A client retrieves those signed objects from any discovery mechanism and -verifies the complete chain against current HNS name state. A relay, hosting -provider, directory, or endpoint cannot substitute its own service key without -an authorization from the HNS name. +The current HRM for `denuoweb` may delegate that service to Jaron's key. +Jaron can then publish profile-defined HNS, BTC, XMR, invoice, or dynamic +payment endpoints without holding the `denuoweb` name wallet key. The payment +syntax and payload are defined by that future payment profile, not by HNSA +Core. ## User stories ### Mobile or home hosting -As the owner of `alice/`, Alice authorizes a `web` service key and one or more -endpoint keys for her phone, home server, and optional VPS. An HNS-aware browser -can reach any currently available endpoint while treating them as the same -named service. +As the owner of `alice/`, Alice creates a `web` named-service resource and +delegates it to a service key. That service key authorizes endpoint keys for her +phone, home server, and optional VPS. An HNS-aware browser can reach any +currently valid endpoint while treating them as one service. ### Provider delegation -Alice authorizes a hosting provider to operate `web` without giving the provider -her HNS wallet key or control of `alice/`. She can replace the provider by -publishing a new service authorization under her service-authority root. +Alice delegates the `web` service to a hosting provider without giving the +provider her HNS wallet key, HRM controller key, or control of unrelated +resources. She replaces the provider by publishing a greater HRM sequence with +a replacement service delegation. + +### Application username + +A registry or community operating `example/` uses an accepted application +profile in which `jaron@example` maps to service name `jaron`. The current +HRM delegates that exact service/profile tuple to Jaron's key. Jaron controls +its profile-specific endpoints but cannot modify `example/`, another +username, or another profile. + +### External wallet destinations + +A payment profile authorizes a named service to return destinations for +multiple currencies. HNSA proves which service key may speak for the named +payment identity. The payment profile defines assets, networks, address +formats, invoices, replacement rules, and whether destinations are static +signed records or dynamic endpoint responses. ### Key rotation after compromise -Alice replaces a compromised service key while keeping the HNS name and browser -identity unchanged. Clients reject endpoint records that do not lead to a -currently valid service authorization. +Alice replaces a compromised service key in the complete current HRM snapshot. +Clients reject endpoint delegations that bind the removed service delegation, +even if an untrusted directory continues serving them. ### Multiple services under one name -Alice authorizes `web`, `chat`, and `files` with independent keys, profiles, and -lifetimes. Compromise or migration of one service does not require rotating the -keys for every other service or transferring the HNS name. +Alice creates `web`, `chat`, and `files` resources with independent +application profile IDs and service keys. A profile may instead interpret a +service name as a username or another application-local label. Compromise or +migration of one service does not authorize another tuple. ### Stable browser identity A user opens an HNS service whose direct address, relay, or provider has changed. The browser preserves the same origin and permissions because identity -is based on the HNS name, service name, and profile rather than the selected -network path. - -## Motivation - -Handshake authenticates root names and DNS resource data. It does not currently -provide an implementation-independent authorization format for application -services operated beneath those names. - -Without a separate service-authority layer, an application tends to choose one -of these designs: - -- use the name wallet key directly in online service software; -- invent a new TXT key format for every application; -- trust the endpoint returned by a directory or relay; -- equate an IP address or hosting account with service identity; -- place provider-specific credentials in name data; -- define a complete authorization chain inside each transport proposal. - -These approaches either expose durable name custody, duplicate security rules, -or bind identity to infrastructure that changes more frequently than the HNS -name. - -HNSA introduces two deliberate delegation boundaries: - -```text -name custody service operation -HNS wallet -> root key root key -> service key - -service operation endpoint reachability -service key -> endpoint key endpoint key -> route or transport record -``` - -The name wallet only needs to update HNS when the root key or authority epoch -changes. The root key may remain offline and sign relatively long-lived service -authorizations. Service keys and endpoint keys can rotate on shorter schedules -without exposing the name wallet. - -## Scope - -This HIP defines: - -- a canonical HNS `TXT` record for the service-authority root key and epoch; -- canonical service names; -- the stable identity tuple for a named service; -- `ServiceAuthorizationV1`; -- `EndpointDelegationV1`; -- signature domains and canonical encodings; -- expiry, sequence, replacement, and emergency revocation behavior; -- validation rules and implementation limits; -- the interface between HNSA and service profiles; -- browser-origin and permission requirements for profile specifications. - -This HIP does not define: - -- an endpoint discovery or storage network; -- HNSR rendezvous, relay tickets, circuits, or transport frames; -- DNS, HTTP, TLS, QUIC, WireGuard, or messaging wire behavior; -- an application-specific endpoint record; -- a generic Internet resource manifest; -- IP prefixes, ASNs, RPKI, BGP, ports, protocol numbers, or EtherTypes; -- automatic operating-system or network configuration; -- allocation policy or economic rules for services; -- unnamed Handshake peer authority. +is based on the HNS name, service name, and application profile rather than the +selected network path. + +## Goals + +HNSA version 1 is intended to: + +- be a strict HRM resource profile rather than a competing manifest system; +- separate HNS name custody, HRM control, service operation, and endpoint + reachability; +- give each named service a stable identity across key and transport rotation; +- permit the HRM controller to delegate a service to a user, provider, or + device key; +- reuse HRM current-snapshot, transfer, expiry, revocation, and parent- + delegation behavior; +- keep rapidly changing endpoint and route records outside the HRM envelope; +- allow application profiles to define usernames, payments, web, chat, files, + and future payloads without changing HRM Core; and +- support deterministic independent implementations. + +## Non-goals + +This document does not define: + +- HRM Core, its commitment, envelope, or generic delegation encoding; +- a universal username syntax; +- a payment, wallet-address, invoice, or currency schema; +- endpoint discovery or storage; +- HNSR routing, relay tickets, or circuits; +- DNS, HTTP, TLS, QUIC, messaging, or payment wire behavior; +- globally assigned IP prefixes, ASNs, ports, protocol numbers, or link-layer + identifiers; or +- automatic browser, wallet, operating-system, or network permission. + +Those semantics belong to HRM Core, another HRM resource profile, or the +application/transport profile consuming HNSA. ## Requirements language The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **NOT RECOMMENDED**, **MAY**, and -**OPTIONAL** in this document are to be interpreted as described in BCP 14 when, -and only when, they appear in all capitals. +**OPTIONAL** in this document are to be interpreted as described in BCP 14 +when, and only when, they appear in all capitals. ## Terminology -**HNS name owner** -: The controller of the current Handshake name covenant output. - -**Root key** -: The service-authority key committed in current authenticated HNS name data. - It signs service authorizations and should normally remain offline. +**HRM subject** +: The HNS name hash in the current verified HRM payload. -**Authority epoch** -: An integer in current HNS name data. Changing it invalidates all service - authorizations issued under a previous epoch, even if the root key is reused. +**HRM controller** +: The operational key declared by and signing the current HRM payload. For + HNS-local named services, it originates the resource and signs the HRM + delegation to the service controller. **Named service** -: An application service identified by an HNS name hash, canonical service - name, and profile ID. - -**Service key** -: A profile-specific operational key authorized by the root key for exactly one - named service. - -**Endpoint key** -: A short-lived or device-specific key authorized by a service key. A service - profile defines how the endpoint key authenticates its route or transport. +: An HNS-local HRM resource identified by a Handshake network, HNS name hash, + canonical service name, and application profile ID. -**Service profile** -: A separate specification defining the meaning of a profile ID, endpoint - records, capabilities, constraints, discovery, transport, and browser - behavior. +**Application profile** +: A separate specification assigning meaning to an application profile ID and + defining user-facing naming, service rights, endpoint records, capabilities, + constraints, discovery, transport, and application behavior. -**Authorization ID** -: The BLAKE2b-256 hash of a complete canonical service authorization, including - its root signature. +**Service controller** +: The key in the current HRM service delegation. It may sign bounded endpoint + delegations for exactly one named service. -**Delegation ID** -: The BLAKE2b-256 hash of a complete canonical endpoint delegation, including - its service signature. - -## Design principles - -### The HNS name remains the root of identity - -A client starts with current authenticated Handshake name state. A service -authorization learned from a relay, web server, peer, QR code, cache, or other -untrusted source has no authority unless it validates under the root key and -epoch currently published by that name. - -### Name custody is separate from service operation +**Endpoint key** +: A short-lived or device-specific key authorized by the service controller. + An application or transport profile defines how it signs or authenticates + endpoint records and sessions. -The name wallet key does not sign ordinary service or endpoint messages. An HNS -update selects a service-authority root key; that key delegates online work to -service keys. +**Service resource ID** +: The stable HRM resource ID calculated from the named-service identity. -### Service identity is independent of network path +**Service delegation ID** +: The HRM delegation ID for the current delegation of a named service to its + service controller. -An IP address, relay, transport connection, hosting provider, or endpoint key is -not the named service identity. Those details may change while the HNS name, -service name, and profile remain stable. +## Dependency on HRM Core -### Profiles define transport semantics +A relying implementation MUST validate the complete current HRM before applying +this profile. That validation includes: -HNSA verifies who may operate a named service. It does not decide how a client -finds or reaches the endpoint. HNSR, direct web, messaging, and future profiles -may carry the same authorization objects over different transports. +1. authenticated current HNS namestate; +2. current `hrm1` commitment selection; +3. exact envelope-hash matching; +4. deterministic-CBOR validation; +5. subject, network, sequence, and validity checks; +6. HRM controller signature verification; +7. resource origin or parent-delegation verification; and +8. current-snapshot and local finality policy. -### Authorization is bounded +HNSA MUST NOT duplicate, bypass, or weaken those checks. -Root-key changes and epoch increments provide an on-chain emergency boundary. -Service and endpoint authorizations also have finite validity periods so stale -objects eventually stop working without a further HNS transaction. +One HRM may contain HNSA resources alongside resources from unrelated profiles. +Adding HNSA does not prevent the same manifest and delegation graph from +supporting later routing, overlay, payment, identity, or other resource +profiles. -## Service identity +## Named-service identity -A named service is identified by this tuple: +A named service is identified by: ```text Handshake network magic HNS name hash canonical service name -service profile ID +application profile ID ``` -The tuple is stable across root-key rotation, service-key rotation, endpoint -rotation, provider migration, and transport failover. +This tuple is stable across HRM controller rotation, service-controller +rotation, endpoint rotation, provider migration, and transport failover. -Version 1 service names: +Service names: - are 1 through 63 ASCII bytes; - contain only lowercase `a-z`, digits, and hyphen; - MUST NOT begin or end with a hyphen; -- MUST NOT contain period, slash, underscore, whitespace, or percent escapes; +- MUST NOT contain a period, slash, underscore, whitespace, `@`, or percent + escape; and - are compared byte-for-byte without locale processing. -Examples include `web`, `chat`, `files`, `node`, and `p2p-site`. - -The service name is an application namespace beneath the HNS root. It is not a -second-level DNS registration and is not independently owned on chain. - -## HNS root-key record - -### Record form - -A name opts into HNSA by publishing exactly one canonical `TXT` record: - -```text -hsa1 k= e= -``` - -Diagnostic Handshake resource JSON: - -```json -{ - "type": "TXT", - "txt": [ - "hsa1 k=ak3m... e=4" - ] -} -``` - -The abbreviated key above is illustrative and is not a test vector. - -Requirements: - -- the complete record is one printable ASCII character-string; -- fields are separated by exactly one ASCII space; -- fields appear in the order shown; -- `hsa1` is lowercase and exact; -- `k` is an unpadded lowercase base32 encoding of a valid compressed 33-byte - secp256k1 public key; -- `e` is an unsigned 32-bit decimal integer without leading zeroes, except zero - is encoded as `0`; -- unknown, missing, duplicated, or reordered fields make the record invalid; -- more than one syntactically valid `hsa1` record is ambiguous and MUST fail - closed. - -The record uses existing version `0` Handshake resource data and may coexist -with supported `NS`, `DS`, glue, synthesis, and unrelated `TXT` records. - -### Authentication - -An ordinary unauthenticated DNS response is insufficient. A relying client MUST -authenticate the root-key record using one of: - -- locally validated Handshake full-node state; -- a Handshake light-client name proof anchored in accepted chain headers; or -- DNSSEC validation anchored in a locally accepted Handshake root trust path. - -### Update, transfer, and revocation - -An HNS `UPDATE` that changes or removes the `hsa1` record replaces or revokes the -service-authority root after the client accepts the new safe name state. - -Incrementing the epoch invalidates every service authorization containing a -lower epoch. This permits emergency revocation while retaining the same root -key. - -A name transfer that leaves the resource data unchanged leaves the existing -root key and epoch in effect until the new owner updates them. This preserves -service continuity while giving the new owner the ability to replace or remove -the authority record. +The service name is an application-local label beneath the HNS root. It is not +a DNS registration and is not independently owned on chain. An application +profile MAY map a user-facing local part such as `jaron@example` to canonical +service name `jaron`, but it MUST define that mapping and its collision rules. -## Cryptographic primitives +Application profile ID zero is invalid. Draft profiles MUST use an explicitly +documented private experimental value until an assignment is accepted. -Version 1 uses: +## Canonical named-service identifier -- BLAKE2b-256; -- compressed 33-byte secp256k1 public keys; -- deterministic secp256k1 ECDSA signatures; -- strict DER signature encoding; -- low-S normalization; -- four-byte little-endian Handshake network magic in every signature domain. +The `identifier` byte string of an `hns.named-service/v1` HRM resource is +the deterministic-CBOR encoding of: -A verifier MUST reject invalid public keys, noncanonical DER, high-S -signatures, wrong network magic, unsupported versions, and signatures over any -noncanonical encoding. +| Key | Name | Type | Required | +| ---: | --- | --- | :---: | +| `0` | `network_magic` | unsigned integer, at most `u32` | yes | +| `1` | `name_hash` | 32-byte byte string | yes | +| `2` | `service_name` | canonical text string | yes | +| `3` | `application_profile_id` | unsigned integer, at most `u16` | yes | -All unsigned integer fields use little-endian encoding. Every variable-length -field is preceded by the length shown in its structure. No field may contain -trailing bytes or an alternative encoding. +No other key is permitted in version 1. -## Service authorization +The network and name hash MUST match the active network and HRM subject. The +application profile ID MUST be nonzero and recognized by the relying +implementation. -The root key authorizes one named service with: +The service resource ID is: ```text -ServiceAuthorizationV1 { - version: u8 - network_magic: u32 - name_hash: u8[32] - authority_epoch: u32 - service_name_length: u8 - service_name: u8[service_name_length] - profile_id: u16 - service_key: u8[33] - flags: u16 - serial: u64 - valid_from_height: u32 - valid_until_height: u32 - max_endpoint_lifetime: u32 - root_signature_length: u8 - root_signature: u8[root_signature_length] -} +SHA-256( + ASCII("HNS-HRM-NAMED-SERVICE-ID-V1") || 0x00 + || canonical_identifier +) ``` -The root-signature digest is: +Two canonical identifiers are equal only when all four fields are equal. -```text -BLAKE2b-256( - "HNS-SERVICE-AUTH-V1\0" - || network_magic_u32le - || all remaining unsigned canonical fields -) -``` +## Named-service resource -The `network_magic` field appears in the object and signature input exactly -once. The phrase `remaining unsigned canonical fields` starts with `name_hash` -and ends with `max_endpoint_lifetime`. +An HNSA service uses the HRM resource profile identifier: -Rules: +```text +hns.named-service/v1 +``` -- `version` MUST equal `1`; -- `network_magic` MUST match the active Handshake network; -- `name_hash` MUST match the name containing the current `hsa1` record; -- `authority_epoch` MUST equal the current `hsa1` epoch; -- `service_name` MUST be canonical; -- `profile_id` MUST be nonzero and recognized by the relying client; -- `service_key` MUST be a valid compressed secp256k1 public key; -- `flags` MUST contain only bits defined by the selected profile; -- `serial` MUST be nonzero and MUST increase when the root key replaces an - authorization for the same service identity; -- `valid_until_height` MUST be greater than `valid_from_height`; -- an authorization MUST be rejected outside that block-height interval; -- `max_endpoint_lifetime` MUST be 300 through 604,800 seconds; -- the root signature MUST verify under the current HNSA root key; -- unknown trailing data MUST be rejected. - -The profile MAY impose a shorter authorization span or endpoint lifetime. - -The authorization ID is: +Its authority MUST be HNS-local origin unless a future profile explicitly +defines a compatible parent-delegation mapping. Its validity interval MUST be +contained by the HRM payload interval. + +The resource `attributes` map is: + +| Key | Name | Type | Required | Meaning | +| ---: | --- | --- | :---: | --- | +| `0` | `profile_flags` | unsigned integer, at most `u16` | yes | Application-profile flags | +| `1` | `profile_constraints_hash` | 32-byte byte string | yes | Hash of detached profile constraints, or zero | +| `2` | `presentation` | map | no | Non-authoritative profile-defined display data | + +The application profile defines allowed `profile_flags`, the detached +constraints encoding and hash domain, and any non-authoritative presentation +fields. Presentation data MUST NOT change the service identity or grant rights. + +A current HRM MUST contain at most one canonical service resource with a given +service resource ID. Duplicate or conflicting entries are invalid. + +## Delegation to the service controller + +The HRM controller delegates operation of a named service using an ordinary HRM +delegation object. + +This is a profile-defined operational delegation over the same resource, not a +claim that a second HNS subject originated a child resource. HNSA therefore +permits `child_subject` to equal the parent HRM subject and +`child_resource_id` to equal `parent_resource_id`. The delegated right is +consumed directly by HNSA endpoint validation; it does not require a separate +child HRM. This same-subject, same-resource mapping is valid only for the exact +rights and constraints below and MUST NOT be generalized to another HRM +profile without that profile defining its own mapping. + +For version 1: + +- `parent_resource_id` MUST equal the service resource ID; +- `child_profile` MUST equal `hns.named-service/v1`; +- `child_resource_id` MUST equal the service resource ID and + `child_identifier` MUST equal the service resource's canonical `identifier` + byte string; +- `child_subject` MUST equal the HRM subject; +- `child_controller` MUST use HRM algorithm 1 and a valid compressed + secp256k1 service key; +- `rights` MUST be the canonical two-element array + `["delegate-endpoint", "operate"]`; +- `may_subdelegate` MUST be false; +- the delegation interval MUST be contained by the resource and HRM payload + intervals; and +- `constraints` MUST use the map below. + +The constraints map is: + +| Key | Name | Type | Required | Meaning | +| ---: | --- | --- | :---: | --- | +| `0` | `service_generation` | nonzero unsigned integer, at most `u64` | yes | Replacement and replay generation | +| `1` | `max_endpoint_lifetime` | unsigned integer, at most `u32` | yes | Maximum seconds | +| `2` | `allowed_endpoint_capabilities` | unsigned integer, at most `u32` | yes | Profile-defined bit mask | +| `3` | `endpoint_constraints_hash` | 32-byte byte string | yes | Expected detached endpoint constraints, or zero | + +`max_endpoint_lifetime` MUST be 300 through 604,800 seconds. The application +profile MAY impose a lower maximum. + +The service generation MUST increase whenever a service controller is replaced, +withdrawn and later restored, or its authority is intentionally reset. An +unrelated HRM change does not require incrementing it. + +Exactly one current delegation may contain `operate` for a service resource. +More than one is ambiguous and MUST fail validation. Concurrent endpoint +redundancy is expressed through several endpoint delegations beneath the one +service controller. + +Let `service_delegation_body` be the deterministic-CBOR map containing the +ordinary HRM delegation fields with integer keys `1` through `11`, omitting +only key `0` (`delegation_id`). The service delegation ID is: ```text -authorization_id = BLAKE2b-256( - "HNS-SERVICE-AUTH-ID-V1\0" - || complete_canonical_service_authorization +SHA-256( + ASCII("HNS-HRM-NAMED-SERVICE-DELEGATION-ID-V1") || 0x00 + || service_delegation_body ) ``` -This includes the canonical root signature. +That digest MUST be stored as field `0` of the delegation. A verifier MUST +re-encode fields `1` through `11`, recompute the digest, and reject a mismatch. +The ID therefore commits to the service key, generation, rights, constraints, +subject, resource, and validity interval without a self-reference. ## Endpoint delegation -A service key authorizes an endpoint key with: +A current service controller may sign one or more short-lived endpoint +delegations: ```text EndpointDelegationV1 { - version: u8 - network_magic: u32 - authorization_id: u8[32] - endpoint_key: u8[33] - endpoint_sequence: u64 - issued_at: u64 - expires_at: u64 - capabilities: u32 - constraints_hash: u8[32] - service_signature_length:u8 - service_signature: u8[service_signature_length] + version: u8 + network_magic: u32 + service_resource_id: u8[32] + service_delegation_id: u8[32] + service_generation: u64 + endpoint_key: u8[33] + endpoint_sequence: u64 + issued_at: u64 + expires_at: u64 + capabilities: u32 + constraints_hash: u8[32] + service_signature_length: u8 + service_signature: u8[service_signature_length] } ``` -The service-signature digest is: +All integers in this object use little-endian encoding. Let +`canonical_endpoint_body` be the exact fixed-width bytes from `version` through +`constraints_hash`, excluding `service_signature_length` and +`service_signature`. The service-signature digest is: ```text BLAKE2b-256( - "HNS-ENDPOINT-DELEGATION-V1\0" - || network_magic_u32le - || all remaining unsigned canonical fields + "HNS-HRM-HNSA-ENDPOINT-DELEGATION-V1\0" + || canonical_endpoint_body ) ``` Rules: -- `version` MUST equal `1`; +- `version` MUST equal 1; - `network_magic` MUST match the active Handshake network; -- `authorization_id` MUST identify the validated service authorization; +- both IDs and the generation MUST match the current verified HRM service + resource and delegation; - `endpoint_key` MUST be a valid compressed secp256k1 public key; -- `endpoint_sequence` MUST be nonzero and MUST increase for replacement of the - same logical endpoint under a profile-defined endpoint identifier; +- `endpoint_sequence` MUST be nonzero and increase for replacement of the + same profile-defined logical endpoint; - `issued_at` MUST be less than `expires_at`; -- lifetime MUST NOT exceed the service authorization's - `max_endpoint_lifetime`; -- the delegation MUST NOT remain valid after the service authorization's - block-height expiry; -- `capabilities` MUST contain only bits defined by the selected profile; -- `constraints_hash` is all zeroes when the profile defines no detached - constraints; -- a nonzero constraints hash MUST commit to the exact canonical profile object; -- the service signature MUST verify under the authorized service key; -- unknown trailing data MUST be rejected. - -The delegation ID is: +- the lifetime MUST NOT exceed `max_endpoint_lifetime`; +- the interval MUST be contained by the current service resource and service + delegation intervals; +- `capabilities` MUST contain no bit outside + `allowed_endpoint_capabilities`; +- required capabilities are defined by the application profile; +- `constraints_hash` MUST match the current service-delegation constraint; +- the signature MUST use canonical strict-DER, low-S secp256k1 and verify under + the current service-controller key; and +- malformed lengths, unsupported versions, and trailing bytes MUST be rejected. + +The endpoint-delegation ID is: ```text -delegation_id = BLAKE2b-256( - "HNS-ENDPOINT-DELEGATION-ID-V1\0" +SHA-256( + ASCII("HNS-HRM-HNSA-ENDPOINT-DELEGATION-ID-V1") || 0x00 || complete_canonical_endpoint_delegation ) ``` @@ -486,445 +459,455 @@ delegation_id = BLAKE2b-256( A service may authorize several endpoints concurrently for redundancy, geographic distribution, device migration, or transport choice. -## Profile-specific endpoint records +## Profile-specific records and application payloads -HNSA stops at the endpoint key. A service profile defines the next object used -for discovery or transport. +HNSA stops after authorizing the endpoint key. An application or transport +profile defines the next object. -A profile-specific endpoint or route record MUST bind at least: +A profile-specific record MUST bind at least: - active network magic; -- service authorization ID; -- endpoint delegation ID; -- endpoint sequence; -- endpoint or route expiry; -- profile ID; -- profile-specific locator, route, or session data. - -It MUST be signed by the endpoint key and MUST NOT remain valid beyond the -endpoint delegation. - -Examples include: - -- an HNSR signed route with one or more active relay tickets; -- a direct QUIC endpoint with an authenticated transport key; -- an HTTPS endpoint with profile-defined TLS or DANE binding; -- a messaging endpoint with a delivery key and discovery locator. - -Those objects and their wire behavior are outside this HIP. +- service resource ID; +- service delegation ID and generation; +- endpoint-delegation ID and sequence; +- application profile ID; +- record sequence and validity interval; +- profile-specific payload, locator, or route data; and +- an endpoint-key signature over all preceding fields. + +A profile may define: + +- static signed application data stored with the HRM or in content-addressed + storage; +- dynamic request/response behavior through an authorized endpoint; +- direct and relayed endpoint records; +- user-facing identifiers derived from the service name; +- payment assets, networks, addresses, invoices, and expiry; +- web origins and transport authentication; +- messaging delivery keys; or +- other bounded application semantics. + +A valid HNSA chain authorizes the service and endpoint keys. It does not make +an otherwise malformed or semantically invalid application payload valid. The +application profile remains responsible for payload validation. ## Validation algorithm -To validate an endpoint record for named service `S`, a client MUST: - -1. Obtain authenticated current HNS state for the root name under local chain - finality policy. -2. Parse the `hsa1` record and reject missing or ambiguous authority. -3. Parse the service authorization using bounded canonical decoding. -4. Confirm network magic, HNS name hash, authority epoch, service name, profile, - flags, height interval, and endpoint-lifetime limit. -5. Verify the root signature under the current `hsa1` key. -6. Calculate and match the service authorization ID. -7. Parse the endpoint delegation using bounded canonical decoding. -8. Confirm its authorization ID, capabilities, constraints, sequence, time - interval, and profile rules. -9. Verify the service signature under the authorized service key. -10. Calculate and match the endpoint delegation ID. -11. Validate the profile-specific endpoint record and its endpoint signature. -12. Apply local browser or application policy before connecting. - -A failure at any step MUST fail closed for HNSA authorization. A client MUST NOT -silently replace a failed HNSA chain with an endpoint learned from an -unauthenticated directory, relay, DNS response, or compatibility fallback. +To validate a profile-specific endpoint record for expected named service +`S`, a client MUST: -## Replacement and freshness +1. Derive the expected HNS name, canonical service name, and application + profile ID from trusted application input. +2. Obtain and validate the complete current HRM under HRM Core. +3. Construct the canonical HNSA identifier and service resource ID. +4. Select exactly one current `hns.named-service/v1` resource with that ID. +5. Validate its identifier, HNS-local authority, attributes, and interval. +6. Select exactly one current HRM delegation with `operate` for that service. +7. Validate its child resource, subject, controller, rights, generation, + endpoint limits, capabilities, constraints, and interval. +8. Calculate and match the service delegation ID. +9. Decode the endpoint delegation using bounded canonical parsing. +10. Match its service resource, current service delegation, generation, + capabilities, constraints, and interval. +11. Verify its service-controller signature. +12. Calculate and match the endpoint-delegation ID. +13. Validate the profile-specific record and endpoint signature. +14. Apply application and local operational policy before using the result. -### Root authority +Untrusted objects MUST NOT select a different HNS name, service name, or +application profile from the identity requested by the user or application. -The current authenticated HNS `hsa1` record is authoritative. A key change or -epoch increment invalidates older service authorizations once the new HNS state -is accepted under local finality policy. +Failure at any step fails HNSA authorization. A client MUST NOT silently +replace a failed HRM/HNSA chain with a legacy `hsa1` object, an +unauthenticated directory result, a plain DNS record, or a conventional endpoint +under the same presentation identity. -### Service authorization replacement +## Replacement, revocation, and caching -Service authorizations are finite. When several otherwise valid -authorizations for the same service identity are available, a client MUST -select the greatest `serial`. Equal serials with different canonical bytes are -ambiguous and MUST fail closed. +### HRM and resource replacement -A client cannot know about an unavailable higher serial merely from an older -object. Profiles MUST therefore define discovery replication and maximum -service-authorization lifetimes appropriate to their risk. Immediate global -revocation uses an HNS root-key change or epoch increment. +HRM Core's current complete snapshot is authoritative. A greater accepted HRM +sequence replaces the prior resources and delegations. Removing the service +resource revokes the service. Removing or replacing its delegation revokes that +service controller. -### Endpoint delegation replacement - -Endpoint delegations are short-lived and may overlap for failover. Profiles -must define the logical endpoint identifier used when comparing -`endpoint_sequence` and must bound replay through short route or endpoint -record expiry. - -### Caching +### Service-controller replacement -A client MAY cache a validated chain only until the earliest of: +A replacement delegation MUST use a greater `service_generation`. Equal +generations with different controller, rights, constraints, or canonical bytes +are conflicting and invalid. -- observation of changed HNS name data or a relevant chain reorganization; -- service authorization height expiry; -- endpoint delegation time expiry; -- endpoint or route record expiry; -- profile-specific cache limit. +An endpoint delegation binds both the service delegation ID and generation. +Consequently an endpoint issued under a removed service controller cannot +become current under its replacement. -## Service profiles +### Endpoint replacement -A service profile assigns a `profile_id` and MUST specify: +Endpoint delegations are short-lived and may overlap. The application profile +defines the logical endpoint identifier used when comparing +`endpoint_sequence`. -1. User-visible purpose and at least one concrete user story. -2. Meaning of the service authorization `flags`. -3. Meaning of endpoint `capabilities` and detached constraints. -4. Endpoint or route record encoding and signature domain. -5. Discovery and replication behavior. -6. Direct, relayed, and fallback connection policy. -7. Maximum authorization, delegation, and endpoint-record lifetimes. -8. Browser origin, cookies, storage, permissions, and mixed-content behavior - when the profile is web-facing. -9. Resource, parser, and network limits. -10. Positive and negative deterministic test vectors. -11. Privacy, abuse, and denial-of-service considerations. +### Caching -Profile IDs are not assigned by this HIP. A profile proposal SHOULD use private -experimental values until its specification, implementations, and test vectors -are accepted. +A client may cache a validated chain only until the earliest of: + +- observation of a changed HRM commitment or relevant HNS reorganization; +- HRM payload expiry; +- named-service resource expiry; +- service delegation expiry; +- endpoint-delegation expiry; +- endpoint or application-record expiry; or +- an application-profile cache limit. + +A current object being unavailable does not authorize fallback to an older +manifest, delegation, endpoint, or application record. + +## Application profiles + +An application profile using HNSA MUST specify: + +1. A profile ID and versioning policy. +2. User-facing purpose and concrete user stories. +3. Mapping from user input to canonical HNS name and service name. +4. Meaning of service flags, capabilities, and detached constraints. +5. Service and endpoint replacement scope. +6. Application-record encoding and signature domain. +7. Discovery and replication behavior. +8. Direct, relayed, and fallback policy. +9. Maximum service, endpoint, and record lifetimes. +10. Application payload validation and resource limits. +11. Browser origin and permission behavior when applicable. +12. Positive and negative deterministic test vectors. +13. Privacy, abuse, and denial-of-service considerations. + +A payment profile must additionally define asset and network identifiers, +address and invoice validation, static versus dynamic destinations, conflict +handling, destination expiry, and transaction-intent binding. + +A username-bearing profile must define normalization, allowed characters, +display form, collision handling, and whether the local part maps directly to +the HNSA service name. ## Browser behavior -This HIP does not require a URI scheme or browser interface. A web-facing -profile must nevertheless preserve these properties. - ### Stable origin -Browser identity and storage MUST be scoped to at least: +A web-facing profile MUST scope browser identity and storage to at least: ```text Handshake network HNS name hash canonical service name -profile ID +application profile ID ``` -They MUST NOT be scoped only to an IP address, relay, endpoint key, or hosting -provider. Transport failover must not create a new origin or share storage with -another named service. +It MUST NOT scope origin only to an IP address, relay, endpoint key, retrieval +URI, or hosting provider. ### Identity indication -A browser may indicate that the endpoint is authorized by current HNS state. -That indication must not claim that the operator, content, or service is honest -or safe. HNSA authenticates control, not reputation. +A browser may indicate that an endpoint is authorized by current HNS and HRM +state. That indication must not claim that the operator, content, or service is +honest or safe. ### Failure behavior -If the authority chain expires, is ambiguous, changes unexpectedly, or fails a -signature check, the browser must stop before sending application data. Any -conventional-web fallback must be separately identified and require explicit -profile and user policy. +If the HRM or HNSA chain expires, becomes ambiguous, changes unexpectedly, or +fails validation, the browser must stop using that authority. Conventional-web +or legacy resolution is a separate identity unless an application profile +explicitly defines and secures a transition. -### Network permissions +### Permissions -A profile that requests VPN, overlay, local-network, device, or persistent -background access must use an explicit browser or operating-system permission. -An HNSA authorization alone does not grant those capabilities. +HNSA authorization does not grant local-network, VPN, device, wallet, +persistent-background, mining, or value-transfer permission. Those remain +application and operating-system decisions. -## Relationship to HNSR +## Relationship to HIP-0002 and wallet TXT conventions -The draft Handshake P2P Rendezvous and Authenticated Service Relay protocol -contains a named-service authorization chain developed for HNSR routes. HNSA -extracts that concept into a transport-independent layer. +HIP-0002 HTTP paths such as `/.well-known/wallets/` and prefixed HNS +`TXT` wallet records are application-specific publication and discovery +conventions. They are not HRM resources or HNSA delegations by themselves. -The relationship is: +A future payment profile MAY define an adapter that reads or emits either +convention. It MUST specify authenticated namestate requirements, asset and +network identifiers, address syntax, precedence, conflicts, expiry, and +fallback behavior. An HTTP response synthesized from a `TXT` record does not +gain a stronger authority chain merely because it is exposed through a +well-known URL. -```text -HNSA - authorizes the named service key and endpoint key +Such an adapter MUST NOT silently merge a legacy domain-wide wallet record with +a user-scoped HNSA identity such as `jaron@denuoweb`. The payment profile must +define the exact mapping and present it as a separately selected compatibility +mode unless the record is cryptographically bound to the expected HNSA +resource and delegation. -HNSR - discovers a currently online endpoint and relays its traffic -``` +## Relationship to DNS delegation + +DNS and DNSSEC already support child names such as `jaron.denuoweb`, including +NS delegation and TXT or HTTPS records. HNSA does not replace that mechanism. -Unnamed HNSR node rendezvous remains independent and does not require an HNS -name or HNSA. +An application may display `jaron@denuoweb` while resolving +`jaron.denuoweb`; that is a DNS-based application convention, not HNSA. -The companion *HNSA Profile for Handshake P2P Rendezvous* draft defines that -revision. New named HNSR routes use route-record version `2`, authority type -`1`, the `hsa1` trust root, and the exact HNSA authorization and delegation -objects defined here. The route key is stable across endpoint and relay -rotation because it is derived from the HNSA service identity. +HNSA instead permits an application profile to treat `jaron` as a service +label within the HRM for `denuoweb` and delegate it directly to Jaron's +service key. This does not create a DNS owner name or require Jaron to operate +an authoritative nameserver. Profiles must not silently treat these two models +as interchangeable. -Unnamed `HNS_NODE_V1` routes retain route-record version `1`, authority type -`0`, and endpoint-key self-authorization. No version-1 named route or `hnsr1` -object is reinterpreted as HNSA. The two formats therefore fail closed rather -than relying on an implicit conversion. +## Relationship to HNSR -## Compatibility +HNSA establishes the durable named-service resource and current service +controller. HNSR may discover short-lived endpoints and relay opaque +application streams. -The `hsa1` record is valid existing HNS `TXT` data. Full nodes, miners, -resolvers, wallets, and applications that do not implement HNSA may ignore it. +The companion HRM/HNSA HNSR profile defines route records that bind: -HNSA-aware clients are optional consumers. Names without a valid `hsa1` record -continue operating under existing Handshake and DNS rules. +- the stable HNSA service resource ID; +- the current HRM service delegation ID and generation; +- an HNSA endpoint delegation; and +- current HNSR relay tickets. -The proposal does not reinterpret `hnsr1`, unrelated TXT records, DNSSEC keys, -TLS certificates, or wallet addresses. +An HNSR relay or rendezvous storage node is not required to retrieve or +validate an HRM, but a client consuming an HRM/HNSA named route MUST validate +the current chain. HRM need not be retrieved over HNSR, and unnamed HNSR node +rendezvous does not require HRM or HNSA. + +## Compatibility and transition + +The `hrm1` commitment and deterministic-CBOR objects are ordinary current HNS +TXT data plus off-chain content. Nodes, miners, resolvers, wallets, and +applications that do not implement HRM or HNSA may ignore them. + +The earlier experimental HNSA draft used: + +- an on-chain `hsa1` root-key record; +- a fixed binary `ServiceAuthorizationV1`; and +- an endpoint delegation bound to that authorization ID. + +Those objects are not HRM objects and are superseded by this profile. They MUST +NOT be accepted as this version, converted implicitly, used as fallback, or +share application/browser identity with an HRM-backed HNSA service. + +Because no permanent assignment or final HIP was issued for the earlier +experiment, implementations SHOULD use a new experimental record or authority +version for HRM-backed HNSA and retain the earlier parser only in explicitly +selected compatibility tests. ## Security considerations ### Wallet-key exposure -Implementations MUST NOT use the HNS name wallet key as a root, service, or -endpoint key merely for convenience. The separation of custody and operation is -a primary security property of this protocol. +The HNS name wallet key selects the current HRM commitment through an ordinary +name update. It MUST NOT be reused as the HRM controller, service controller, or +endpoint key merely for convenience. -### Root-key compromise +### HRM-controller compromise -A compromised root key can authorize malicious services until the HNS owner -changes the key or increments the epoch. The root key should remain offline or -in hardware-backed storage and should not sign endpoint or transport messages. +A compromised HRM controller can sign malicious current manifests only while +the HNS owner continues committing their hash. The HNS owner can replace the +commitment. Parent-delegated or externally originated resources retain the +additional HRM authority requirements. -### Service-key compromise +### Service-controller compromise -A compromised service key can authorize endpoints only for its named service, -profile, validity interval, flags, and endpoint-lifetime limit. It cannot modify -the HNS name or authorize a different service identity. +A compromised service controller can authorize endpoints only for its exact +named-service resource, current delegation, generation, rights, constraints, +and interval. It cannot modify the HRM or another service. ### Endpoint-key compromise -A compromised endpoint key can impersonate one endpoint until its delegation -and profile records expire. Endpoint lifetimes should reflect how securely the -device can protect its key. - -### Replay and stale authorization +A compromised endpoint key can impersonate its endpoint until the earliest +applicable delegation or record expiry. -Network magic, HNS state, epochs, serials, sequences, finite validity, and -profile record expiry limit replay. Clients must validate current HNS state and -must not accept an older object merely because a current object is unavailable. +### External wallet destinations -### Name transfer - -An unchanged HNSA root survives name transfer until the new owner updates the -record. This supports service continuity, but participants must recognize that -the new owner can revoke or replace the entire service authority. +An HRM/HNSA chain proves which current named-service key authorized a payment +record. It does not by itself prove control of an address on BTC, XMR, HNS, or +another external network, nor that paying it is safe. A payment profile MUST +define whether asset-specific control proof is required and MUST bind the +asset, network, destination, memo or tag requirements, expiry, and transaction +intent strongly enough to prevent cross-network and substitution errors. -### Ambiguous authority +### Replay and rollback -Multiple valid `hsa1` records, equal service serials with different bytes, -noncanonical names, unknown profiles, or conflicting required constraints must -fail closed. +The current HNS commitment, HRM sequence, complete-snapshot semantics, service +generation, delegation IDs, endpoint sequence, and bounded validity intervals +limit replay. Implementations must preserve the rollback protections required +by HRM Core and the consuming profile. -### Untrusted discovery +### Name transfer -Discovery peers, relays, directories, and content hosts may omit, replay, or -reorder authorization objects. They cannot forge the signature chain, but they -can deny service or attempt to keep clients on older still-valid state. +Name transfer follows HRM Core. An unchanged current commitment preserves its +exact controller-signed manifest. The new name owner may withdraw or replace +that commitment but cannot alter its signed contents. -### Downgrade +### Untrusted retrieval -A failed HNSA connection must not silently become an unauthenticated connection -to the same presentation name. Profiles must define explicit downgrade and -fallback behavior. +HRM hosts, directories, relays, and endpoints may omit, replay, reorder, or +equivocate. They cannot forge a current hash/signature chain, but they can deny +availability. Unavailability does not make an older object current. ### Parser and resource exhaustion -Implementations MUST bound all lengths before allocation and signature work. -Recommended initial maximums are: +HRM Core bounds envelope and delegation processing. HNSA additionally requires: | Item | Maximum | | --- | ---: | | Service name | 63 bytes | -| Signature | 80 bytes | -| Service authorization | 256 bytes | -| Endpoint delegation | 256 bytes | -| Concurrent service candidates | 16 | +| Endpoint-delegation signature | 80 bytes | +| Endpoint delegation | 320 bytes | +| Concurrent service candidates per identity | 2 before ambiguity rejection | | Concurrent endpoint candidates | 32 | -| Detached constraint object | 64 KiB | +| Detached constraints object | 64 KiB | -A profile may impose smaller limits. A larger limit requires explicit -justification and tests in that profile. +Application profiles may impose smaller bounds. Larger bounds require explicit +justification and tests. ## Privacy considerations -Service names, service keys, provider changes, endpoint keys, capabilities, and -validity intervals may reveal how a name owner's infrastructure is organized. - -Profiles should avoid publishing personal device labels, private addresses, -internal topology, or long-lived correlatable endpoint keys when they are not -required for verification. Short-lived endpoint keys and privacy-preserving -discovery may reduce correlation. +A complete HRM may reveal service names, delegated users or providers, +controller changes, validity intervals, and relationships between resources. +Generic manifests make selective retrieval and disclosure an important future +HRM concern. -Clients should consider that fetching a service authorization or endpoint -record can reveal which HNS service they intend to use. +Application profiles should avoid personal device labels, private addresses, +internal topology, and long-lived correlatable endpoint keys when not required. +A username or payment profile must document the public correlation created by +its naming and discovery model. ## Reference implementation plan -The first implementation should provide the authority objects and validators -in a transport-independent library. +Implementation should proceed in this dependency order: -Recommended deliverables are: +1. Deterministic HRM Core encoders, decoders, signatures, commitment selection, + storage retrieval, and current-state validation. +2. The exact `hns.named-service/v1` resource and HRM service-delegation + validator. +3. Endpoint-delegation encoders, signers, validators, and vectors bound to HRM + IDs and generations. +4. At least one application profile. +5. The HRM/HNSA HNSR adapter. +6. Wallet tooling for creating, signing, publishing, replacing, and inspecting + HRMs. +7. Mobile and browser consumers that preserve the exact verified identity. -1. Shared canonical encoders and decoders for JavaScript and Rust. -2. Root, service, and endpoint signing and validation APIs. -3. Wallet support for creating and updating the `hsa1` record. -4. A command-line inspection and verification tool. -5. Deterministic positive and negative vectors. -6. An HNSR named-service adapter using HNSA objects. -7. A mobile-browser diagnostic that displays the validated authority chain and - preserves origin across direct and relayed endpoints. - -No Handshake consensus change is required. HNSR integration, wallet ergonomics, -and browser support remain separate implementation changes. +Existing `hsa1`-based Rust and JavaScript implementations conform to the +superseded experiment, not this draft, until their authority source and object +bindings are migrated to HRM. ## Deployment gates -### Stage 0: Canonical vectors +### Stage 0: HRM Core + +- finalize HRM deterministic CBOR and signature vectors; +- implement current HNS commitment selection and envelope validation; +- test transfer, replacement, rollback, expiry, and unavailable retrieval. -- finalize all binary encodings and signature domains; -- verify byte-identical JavaScript and Rust implementations; -- publish malformed, ambiguous, replayed, and cross-network negative vectors. +### Stage 1: Named-service profile -### Stage 1: Regtest authority chain +- publish exact resource-ID and service-delegation vectors; +- verify byte-identical Rust and JavaScript implementations; +- test service creation, controller replacement, removal, generation rollback, + ambiguity, and profile mismatch. -- publish `hsa1` in authenticated name state; -- authorize multiple independent named services; -- rotate service and endpoint keys; -- increment the epoch and verify immediate invalidation; -- transfer the name with and without changing the root record. +### Stage 2: Endpoint authority -### Stage 2: HNSR integration +- publish endpoint-delegation signature and ID vectors; +- test concurrent endpoints, capability constraints, expiry, replacement, and + removed-controller rejection. -- carry HNSA service authorization and endpoint delegation with named HNSR - routes; -- demonstrate direct and relayed endpoints under one stable service identity; -- test route expiry, relay failover, stale authorization, and no unauthenticated - fallback contact. +### Stage 3: Application and transport profiles -### Stage 3: Independent clients and operators +- implement separately reviewed web, chat, payment, or other profiles; +- demonstrate profile-specific payload validation and identity mapping; +- integrate direct and relayed transports without changing service identity. -- run multi-operator testnet trials; -- validate the same objects in independent JavaScript and Rust clients; -- measure authorization freshness, retrieval availability, mobile lifecycle, - and abuse limits; -- complete browser-origin and permission review for any web profile. +### Stage 4: Independent clients and operators -No permanent wire assignment or mainnet-default behavior is requested by this -HIP. +- run multi-operator regtest and testnet trials; +- measure retrieval, validation, storage, and denial-of-service behavior; +- complete security and browser-origin review before permanent assignments. ## Test requirements -Before this proposal can move beyond Draft, deterministic tests must cover: - -- canonical `hsa1` parsing and ambiguity rejection; -- valid and invalid root signatures; -- wrong name hash, epoch, profile, network magic, and height interval; -- valid service replacement and equal-serial conflict; -- valid and invalid endpoint signatures; -- endpoint lifetime beyond the service maximum; -- invalid capabilities and detached constraint hashes; -- root-key rotation and epoch-only revocation; -- service-key and endpoint-key rotation; -- name transfer with retained and replaced root records; -- concurrent endpoints and failover; -- expired and replayed endpoint records; -- malformed lengths, DER signatures, public keys, and trailing bytes; -- stable browser origin across endpoint, relay, and provider changes; -- rejection without unauthenticated fallback. +Deterministic positive and negative vectors MUST cover: + +- every HRM Core requirement used by HNSA; +- canonical named-service identifier and resource ID; +- wrong network, subject, service name, and application profile; +- invalid resource origin, flags, or constraints; +- valid service delegation and controller signature through the HRM envelope; +- missing, duplicate, or conflicting service delegations; +- service generation replacement and rollback; +- endpoint delegation encoding, signature, and ID; +- wrong service resource, delegation ID, generation, key, capabilities, or + constraints; +- endpoint expiry and sequence replacement; +- manifest replacement, removal, transfer, and reorganization; +- legacy `hsa1` and fixed service-authorization rejection; +- application-profile identity and payload failures; and +- no unauthenticated or cross-model fallback. ## Rationale -### Why store a root key in HNS instead of every endpoint? - -Endpoint state changes frequently and may exceed the 512-byte HNS resource-data -limit. A root key creates a bounded delegation hierarchy while keeping name -state small and durable. - -### Why not use the HNS wallet key directly? - -Wallet keys control valuable names and coins and should not be exposed to -online service processes. A separate root key permits service authorization -without weakening name custody. - -### Why have both service and endpoint keys? - -A service may run on several devices, providers, or relays. The service key -represents the operator role, while short-lived endpoint keys limit the impact -of one device compromise and allow independent rotation. - -### Why include an on-chain epoch? - -Service authorizations may be replicated through untrusted discovery systems. -An epoch increment gives the HNS owner one current, authenticated mechanism for -invalidating every authorization under an old epoch without relying on those -systems to distribute a revocation list. - -### Why use block height for service authorization and time for endpoints? - -The service root is verified against Handshake chain state, so block height -provides a consistent validity boundary. Endpoint records are short-lived -network objects whose transports already depend on wall-clock expiry. - -### Why keep transport behavior out of this HIP? - -Rendezvous, direct web, messaging, and other transports have different routing, -privacy, availability, and abuse models. Combining them with the authority core -would make one proposal responsible for unrelated deployment risks. - -## Alternatives considered - -### Generic Internet resource manifests +### Why make HNSA an HRM profile? -Not included. IP prefixes, ASNs, routing policy, link-layer identifiers, and -other public resources have separate authority systems and no immediate role in -the named-service chain defined here. +Named services need the same commitment, controller separation, complete +snapshots, delegation, transfer, expiry, and revocation behavior as other +resources. A second authority format would duplicate those rules and prevent +services from participating in a larger resource graph. -### Application-specific TXT keys +### Why keep endpoint delegations outside HRM? -Not selected as the general model. A separate key record for every application -duplicates rotation, transfer, expiry, and validation rules and consumes scarce -HNS resource data. +Service controllers may operate many mobile, residential, or relayed endpoints +whose keys and locators change more frequently than an HNS update and complete +manifest publication. The HRM delegates the durable service role; the service +key signs bounded transient endpoint authority. -### One online key for all services +### Why use a complete manifest snapshot? -Not selected. Independent service keys contain compromise and allow providers -or devices to be changed without replacing unrelated services. +It makes removal an explicit current-state revocation and lets one HNS +commitment select the coherent set of resources and delegations. Endpoint +presence remains separately short-lived. -### On-chain endpoint records +### Why distinguish application profiles from HRM resource profiles? -Not selected. Mobile and relayed endpoints change too frequently for name -transactions and may require multiple concurrent records. +`hns.named-service/v1` defines the common resource and controller chain. +Application profiles define what `web`, `chat`, `jaron`, or another +service label means and what records or sessions are valid. This permits shared +authority without pretending that every application has identical semantics. -### A mandatory manifest server +### Why not use DNS delegation alone? -Not selected. Authorization objects are signed and can be carried by any -profile-defined discovery system. Requiring one server would create a new -availability and metadata dependency. +DNS delegation already works for DNS child names and remains appropriate when +that is the desired model. HNSA provides a manifest-native application +delegation model for services that should not require a child DNS zone or bind +identity to one DNS transport. ## Open questions -The following items remain for Draft review and implementation evidence: +The following remain for Draft review: -- exact private profile-ID range for regtest and acknowledged testnet use; -- whether service authorizations need a core maximum block-height span; -- whether service-specific revocation needs an optional on-chain commitment in - addition to bounded lifetime and global epoch revocation; -- whether a future version should support threshold or hardware-backed root - keys; -- whether direct web and HNSR should share one web profile or use separate - profile IDs with explicit origin relationships; -- default browser presentation for HNS-authorized service identity. +- permanent registry and assignment policy for application profile IDs; +- whether the service-controller delegation should permit explicitly bounded + concurrent controllers; +- whether future threshold controllers should be added through HRM Core; +- whether selective disclosure should use HIP-0016, an authenticated map, or + independent committed submanifests; +- exact payment and username profile separation; +- migration tooling for experimental `hsa1` records; and +- whether direct Web and HNSR should share one application profile or use + distinct profile IDs with an explicit origin relationship. ## References -1. RFC 2119, *Key words for use in RFCs to Indicate Requirement Levels*. +1. RFC 2119, *Key words for use in RFCs*. 2. RFC 8174, *Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words*. -3. RFC 6979, *Deterministic Usage of the Digital Signature Algorithm*. -4. SEC 1, *Elliptic Curve Cryptography*. -5. Handshake developer documentation, *Resource Records*. +3. RFC 8949, *Concise Binary Object Representation (CBOR)*. +4. HIP-0002, *Well Known directory for wallets address*. +5. Draft HIP, *Handshake Resource Manifests*. 6. Draft HIP, *Handshake P2P Rendezvous and Authenticated Service Relay*. -7. Handshake authenticated name-proof and resource validation behavior. +7. Draft HIP, *HRM/HNSA Profile for Handshake P2P Rendezvous*. +8. Handshake developer documentation, *Resource Records*. diff --git a/HIP-xxxx-HRM.md b/HIP-xxxx-HRM.md new file mode 100644 index 0000000..7705fcd --- /dev/null +++ b/HIP-xxxx-HRM.md @@ -0,0 +1,1169 @@ +# HIP-xxxx: Handshake Resource Manifests + +```text +Number: HIP-xxxx +Title: Handshake Resource Manifests +Type: Standards Track +Status: Draft +Authors: Jaron Rosenau <@denuoweb> +Created: 2026-08-01 +Related: HIP-0015, HIP-0016, Handshake P2P Rendezvous and + Authenticated Service Relay (draft HIP) +Follow-ons: Named Service Authority Profile for Handshake Resource Manifests + (draft HIP) + Handshake IP and Routing Resource Profile (planned HIP) + Handshake Service and Transport Resource Profile (planned HIP) + Handshake Link and Overlay Resource Profile (planned HIP) +``` + +## Abstract + +This document specifies Handshake Resource Manifests (HRMs), an optional +protocol for binding a Handshake name to a signed, content-addressed description +of Internet resources, delegations, controller keys, and validity constraints. + +An HRM separates authorization from transport. Handshake authenticates a small +commitment published by the current name owner. The committed manifest may be +retrieved from any untrusted storage or transport. Resource-specific profiles +then determine whether a claimed resource was originated legitimately, whether +a child resource is contained by a parent resource, and which actions a +delegation permits. + +Version 1 uses ordinary Handshake `TXT` resource records and does not change +Handshake consensus, DNS resolution, covenant validation, or the interpretation +of any globally assigned number. It does not make an IP prefix routable, create +an Autonomous System Number (ASN), assign a port or protocol number, or replace +the policies of IANA, the Regional Internet Registries (RIRs), the IETF, or +IEEE. Globally coordinated resources require a proof profile rooted in an +authority already accepted for that resource. HNS-local overlay resources may +use profiles that explicitly permit origination by an HNS controller. + +The initial protocol is deliberately limited to a reusable manifest, +commitment, signature, delegation, and verification format. IPv4/IPv6, ASN, +routing, service, and link-layer semantics are specified by separate profiles. +This allows independent implementations to agree on the security boundary +before any HRM data is used to generate RPKI objects, routing policy, service +configuration, or other operational output. + +## Plain-language summary + +Handshake currently proves who controls a name. It does not provide a standard +way for that owner to say: + +```text +this key operates my network +this IPv6 prefix was legitimately delegated to me +this smaller prefix is delegated to this community +this service key may accept connections for this service +this authorization expires at this time +``` + +An HRM adds that common language. + +The name owner places a small hash on Handshake. The larger document is stored +elsewhere and can be copied by anyone. A client retrieves the document, checks +that its hash matches Handshake, verifies its controller signature, and then +verifies the authority proof or parent delegation for the resource it needs. + +The design has two important limits: + +1. Owning an HNS name does not prove ownership of an unrelated public IP + prefix, ASN, port, EtherType, or other externally coordinated resource. +2. A valid HRM is authorization evidence, not a command to a router, operating + system, certificate implementation, or network operator. + +Adapters may translate a successfully verified HRM into ordinary configuration, +but those adapters remain subject to local policy and the rules of the protocol +or registry they affect. + +## Motivation + +Internet resource control is recorded across many systems. IP prefixes and ASNs +are distributed hierarchically through IANA and the RIRs. Protocol parameters +are defined through IETF processes and recorded in IANA registries. Link-layer +identifiers may be coordinated by IEEE. Service keys, overlay identifiers, and +internal delegations are often kept in private databases. + +These systems solve different problems and should not be treated as one policy +domain. They nevertheless repeat several operational functions: + +- associate a resource with a controller; +- delegate a subset or a limited right; +- rotate operational keys; +- publish validity periods; +- revoke previous authority; +- provide an audit trail; +- expose current data to relying software. + +Handshake can provide a common, independently verifiable control plane for +those functions without redefining the resources carried in packet headers. +The desired division is: + +```text +resource policy and initial authority + | + v +recognized external proof or HNS-local origin rule + | + v +Handshake-anchored resource manifest + | + v +signed subdelegations and controller keys + | + v +opt-in adapters for RPKI, routing, services, overlays, and applications +``` + +This division is useful even if IANA, an RIR, IEEE, or another existing body +remains the source of the parent allocation. HRM can make later delegations +portable, auditable, and verifiable without requiring every resource holder to +operate a bespoke registry database or trusted API. + +## Scope + +This HIP defines: + +- an on-chain HRM commitment carried by an existing HNS `TXT` record; +- a deterministic CBOR envelope and payload; +- controller signatures; +- resource entries and stable resource identifiers; +- external, HNS-local, and parent-delegated authority modes; +- parent-to-child delegations; +- current-state, expiry, transfer, and revocation behavior; +- a profile interface for resource-specific validation; +- a verification algorithm and minimum implementation limits. + +This HIP does not define: + +- allocation policy for any existing public registry; +- a complete IPv4, IPv6, ASN, RPKI, BGP, port, protocol, TLS, or IEEE profile; +- transient peer routes or relay reservations; +- a mandatory storage or retrieval network; +- automatic router or operating-system configuration; +- an HNS consensus change or new namestate data version; +- a new Handshake P2P message, service bit, port, or protocol number; +- economic policy for allocating HNS-local resources. + +## Core and profile program + +This document defines only HRM Core. Resource profiles are independently +reviewed HIPs and do not receive a HIP number through this document. Each must +be proposed, implemented, tested, reviewed, and assigned its own number +separately. + +```text +Handshake Resource Manifests (this HIP) + common commitment, envelope, controller, delegation, and validation + | + +--> Named Service Authority Profile (draft HIP) + | hns.named-service/v1 and service-controller delegation + | + +--> Handshake IP and Routing Resource Profile (planned HIP) + | IPv4/IPv6, ASN, RPKI proofs, prefix containment, + | routing rights, and read-only routing adapters + | + +--> Handshake Service and Transport Resource Profile (planned HIP) + | TCP/UDP/QUIC bindings, TLS and WireGuard keys, + | application rights, and HNSR authorization + | + +--> Handshake Link and Overlay Resource Profile (planned HIP) + virtual link identifiers, device/controller keys, + overlay segments, and explicitly scoped link-layer use +``` + +The companion HIPs stack on the data model and verification algorithm defined +here. They MUST NOT weaken HRM Core's distinction between an HNS-local resource +and an externally coordinated public resource. + +The separate *Named Service Authority Profile for Handshake Resource +Manifests* draft is the first concrete profile built on this core. It defines +the exact `hns.named-service/v1` resource and service-controller delegation. +It is part of the services-and-transports work described below, not a parallel +commitment, manifest, root-key, or delegation system. + +### Planned IP and routing profile + +The IP and routing HIP should define canonical IPv4, IPv6, and ASN resource +encodings; +RPKI-based external origin proofs; prefix containment; routing and +subdelegation rights; proof refresh and revocation; and an audit-only adapter +that compares HRM results with current RPKI and registry state. + +It must not claim that an HNS name, auction, or transaction creates a routable +prefix or ASN. Any production route-generation behavior requires a later, +explicit deployment decision after multi-operator testing. + +### Planned services and transports profile + +The services and transports HIP should define bindings to existing TCP, UDP, +QUIC, TLS, WireGuard, and similar transports, profile-specific rights, and the +relationship between long-lived HRM/HNSA authority and short-lived HNSR route +records. + +The HNSA draft begins this work with the transport-independent named-service +resource and operational-key delegation. A broader service-and-transport HIP +may add concrete TCP, UDP, QUIC, TLS, WireGuard, or other bindings, but MUST +consume the HRM/HNSA authority chain rather than introduce another name-rooted +authority format for the same service identity. + +It must distinguish HNS-local service identifiers from IANA-assigned ports, +protocol numbers, TLS parameters, and other public wire values. Use of a public +wire value requires an existing assignment or coordination with its responsible +standards community. + +### Planned links and overlays profile + +The links and overlays HIP should define identifiers and delegations for +explicitly opt-in virtual links and overlay networks, including virtual +segments, device or controller keys, membership rights, and containment +between overlay authorities. + +It must not reinterpret globally coordinated IEEE identifiers on ordinary +Ethernet. Any EtherType, OUI, or other public link-layer assignment must come +from the responsible registry or operate inside a formally assigned extension +space. + +The diagram is a dependency structure, not a requirement that every +implementation support every profile. An implementation may support HRM Core +and any accepted subset of companion profiles. + +## Requirements language + +The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, +**SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **NOT RECOMMENDED**, **MAY**, and +**OPTIONAL** in this document are to be interpreted as described in BCP 14 when, +and only when, they appear in all capitals. + +## Terminology + +**HNS name owner** +: The controller of the current Handshake name covenant output. + +**Subject** +: The Handshake name identified by the 32-byte name hash in an HRM. + +**Manifest controller** +: The key that signs the HRM payload. The manifest controller may be operationally + separate from the HNS name owner. + +**Commitment** +: The HRM `TXT` record in current authenticated Handshake namestate. It contains + the manifest sequence, envelope hash, and retrieval locators. + +**Envelope** +: Deterministic CBOR containing the encoded payload and its signature set. + +**Resource** +: An identifier or authority described by a resource profile. Examples may + include an IPv6 prefix, an ASN, an HNS-local service identifier, or an overlay + network identifier. + +**Resource profile** +: A separate specification that defines the canonical identifier, origination + proof, containment relation, rights, constraints, and adapter behavior for one + resource family. + +**Origin proof** +: Evidence accepted by a resource profile that starts an authority chain. It is + either an external proof rooted in a configured trust anchor or an HNS-local + origin explicitly permitted by the profile. + +**Parent delegation** +: A current entry in a valid parent HRM authorizing a child subject and + controller to exercise rights over a resource or valid subset. + +**Relying implementation** +: Software that validates HRMs or uses validated output. Examples include a + wallet, resolver, HNSR service, RPKI adapter, network controller, or auditor. + +## Trust model + +HRM has two independent authorization gates: + +```text +current HNS name owner commits the envelope hash + AND +manifest controller signs the committed payload +``` + +The current authenticated HNS commitment selects the exact envelope. Only the +current name owner can replace or remove that commitment. The controller +signature proves continuity of the operational key and allows parent +delegations to bind authority to a key rather than silently following a name +sale. + +Neither gate proves that a public resource originated legitimately. A resource +entry is valid only when its selected profile also validates one of: + +- an accepted external origin proof; +- an HNS-local origin rule defined by that profile; or +- a complete parent-delegation chain ending in one of those origins. + +A relying implementation chooses which profiles and external trust anchors it +accepts. Unsupported profiles and unrecognized proof types MUST fail closed. + +## Protocol overview + +Publishing an HRM consists of these steps: + +1. Construct a payload for one HNS subject. +2. Encode it using deterministic CBOR. +3. Sign the domain-separated payload with the manifest controller key. +4. Construct and deterministically encode the envelope. +5. Hash the complete envelope with SHA-256. +6. Store the envelope at one or more retrievable locations. +7. Publish an `hrm1` `TXT` commitment containing the sequence, hash, and + locators in the current HNS namestate. + +Verification reverses those steps: + +1. Authenticate current HNS namestate and select its current HRM commitment. +2. Retrieve an envelope from any advertised or locally discovered source. +3. Verify the envelope hash against the commitment. +4. Decode the envelope and payload using deterministic CBOR rules. +5. Match the subject, sequence, network, and validity interval. +6. Verify the controller signature. +7. Validate the requested resource using its selected profile. +8. Recursively validate any parent delegation to a recognized origin. +9. Apply local policy before producing operational output. + +## HNS commitment record + +### Existing namestate version + +Version 1 commitments use the existing version `0` Handshake resource data +format and its `TXT` record. This permits an HRM commitment to coexist with +ordinary `NS`, `DS`, glue, synthesis, and other supported Handshake records. + +This HIP does not allocate a new namestate data version under HIP-0015. A future +HIP may define a binary commitment if deployment experience shows that the +existing `TXT` representation is inadequate. + +### Record form + +An HRM commitment is one HNS `TXT` record whose first character-string is +exactly `hrm1` and whose remaining character-strings contain one field each. + +The diagnostic JSON form is: + +```json +{ + "type": "TXT", + "txt": [ + "hrm1", + "seq=7", + "hash=sha256:47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU", + "uri=https://registry.example/hrm/47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU" + ] +} +``` + +The example digest is illustrative and does not commit to a valid example +envelope. + +The fields are: + +`seq` +: An unsigned 64-bit decimal integer without leading zeroes, except that zero + is encoded as `0`. + +`hash` +: Exactly `sha256:` followed by the unpadded base64url encoding of the 32-byte + SHA-256 digest of the complete deterministic-CBOR envelope. + +`uri` +: A retrieval URI. At least one `uri` field MUST be present for a self-contained + publication. Additional `uri` fields MAY provide replicas. A relying + implementation MAY use an envelope learned out of band after matching its + hash. + +All commitment character-strings MUST contain printable ASCII. An individual +string MUST NOT exceed the existing HNS `TXT` string limit, and the complete +Handshake resource data MUST remain within the existing 512-byte consensus +limit. + +The order of `uri` fields has no security meaning. Unknown fields MUST be +ignored only when their key begins with `x-`. Any other unknown or duplicate +singleton field makes that commitment invalid. + +### Commitment selection + +A name SHOULD publish no more than one current `hrm1` record. + +If authenticated current namestate contains multiple syntactically valid +`hrm1` records, a verifier MUST select the record with the greatest `seq`. If +two records have the same greatest sequence and different hashes, the HRM state +is ambiguous and verification MUST fail closed. Duplicate records with the same +sequence and hash are equivalent; their locator sets MAY be combined. + +Sequence numbers are for cache invalidation and replay resistance. They are not +enforced by Handshake consensus. A publisher MUST increase `seq` for every new +envelope under a subject. A verifier that has previously accepted a greater +sequence at equal or greater chain work SHOULD reject a lower sequence unless +it has detected and accepted a Handshake reorganization according to local +finality policy. + +### Authenticated retrieval + +An ordinary unauthenticated DNS response containing an HRM commitment is not +sufficient. The relying implementation MUST authenticate the record using one +of: + +- locally validated Handshake full-node state; +- a Handshake light-client name proof anchored in accepted chain headers; or +- DNSSEC validation anchored in a locally accepted Handshake root trust path. + +The retrieval URI and retrieval server are untrusted. Integrity comes from the +on-chain envelope hash, not from HTTPS, a gateway, a relay, or a content host. + +## Deterministic CBOR + +The envelope and payload MUST use deterministic CBOR as specified by RFC 8949, +Section 4.2, with these additional restrictions: + +- maps MUST use the integer keys assigned by this document or a profile; +- map keys MUST be unique; +- indefinite-length items MUST NOT be used; +- floating-point values MUST NOT be used; +- text strings MUST be valid UTF-8; +- profile identifiers MUST contain only lowercase ASCII letters, digits, + hyphen, period, and slash; +- decoders MUST reject trailing data after the top-level CBOR item; +- an encoder MUST produce the preferred serialization of every integer and + length. + +An implementation MUST re-encode a decoded object and compare it byte-for-byte +with the received encoding before treating it as canonical. This prevents two +encodings of the same logical object from producing different security +interpretations. + +## Envelope format + +The envelope is the following CBOR map: + +| Key | Name | Type | Required | Meaning | +| ---: | --- | --- | :---: | --- | +| `0` | `payload` | byte string | yes | Complete deterministic-CBOR payload | +| `1` | `signatures` | array | yes | One or more signature objects | + +A version 1 envelope MUST contain no other top-level keys. + +Each signature object is a CBOR map: + +| Key | Name | Type | Required | Meaning | +| ---: | --- | --- | :---: | --- | +| `0` | `algorithm` | unsigned integer | yes | Signature algorithm identifier | +| `1` | `public_key` | byte string | yes | Encoded public key | +| `2` | `signature` | byte string | yes | Signature bytes | + +Version 1 assigns algorithm `1` to deterministic secp256k1 ECDSA. For algorithm +`1`, `public_key` MUST be a valid compressed 33-byte secp256k1 public key and +`signature` MUST use strict DER encoding with low-S normalization. Unknown +algorithms MUST NOT be accepted as satisfying a required controller signature. + +The signature digest is: + +```text +BLAKE2b-256( + ASCII("HNS-HRM-v1") || 0x00 + || network_magic_u32le + || payload +) +``` + +`network_magic_u32le` is the four-byte little-endian encoding of the active +Handshake network magic. This prevents a signature created for mainnet, +testnet, regtest, or another configured network from being replayed as valid on +a different network. + +The envelope MUST contain a valid signature made by the controller key declared +in the payload. Extra signatures MAY be present for transition experiments but +have no version 1 authority unless a resource profile assigns them meaning. + +## Payload format + +The payload is a CBOR map: + +| Key | Name | Type | Required | Meaning | +| ---: | --- | --- | :---: | --- | +| `0` | `version` | unsigned integer | yes | Must equal `1` | +| `1` | `subject` | byte string | yes | 32-byte Handshake name hash | +| `2` | `sequence` | unsigned integer | yes | Must equal commitment `seq` | +| `3` | `issued_at` | unsigned integer | yes | Unix time in seconds | +| `4` | `expires_at` | unsigned integer | yes | Unix time in seconds | +| `5` | `controller` | map | yes | Algorithm and public key | +| `6` | `resources` | array | yes | Resource entry objects | +| `7` | `delegations` | array | yes | Delegation objects | +| `8` | `extensions` | map | no | Profile-defined, non-critical data | + +`subject` MUST equal the consensus Handshake name hash for the name from which +the commitment was obtained. + +`issued_at` MUST be less than `expires_at`. A verifier MUST reject the payload +before `issued_at` or at and after `expires_at`, subject to a locally configured +clock-skew allowance. Profiles MAY impose shorter maximum lifetimes. + +`controller` is a CBOR map with key `0` containing the signature algorithm and +key `1` containing the public key. Version 1 requires algorithm `1` and a valid +compressed 33-byte secp256k1 public key. + +`resources` and `delegations` are complete current snapshots. Removing an entry +and publishing a greater sequence revokes that entry after the new Handshake +state reaches the verifier's required finality. + +## Resource entries + +A resource entry is a CBOR map: + +| Key | Name | Type | Required | Meaning | +| ---: | --- | --- | :---: | --- | +| `0` | `profile` | text string | yes | Resource-profile identifier | +| `1` | `resource_id` | byte string | yes | 32-byte stable identifier | +| `2` | `identifier` | byte string | yes | Profile-defined canonical resource | +| `3` | `authority` | map | yes | Origin or parent authority object | +| `4` | `not_before` | unsigned integer | yes | Earliest valid Unix time | +| `5` | `expires_at` | unsigned integer | yes | Exclusive expiry Unix time | +| `6` | `attributes` | map | no | Profile-defined attributes | + +The profile MUST define: + +- canonical encoding of `identifier`; +- calculation and validation of `resource_id`; +- whether HNS-local origination is permitted; +- accepted external authority proof types; +- the subset or containment relation; +- recognized rights and constraints; +- maximum validity periods; +- whether multiple simultaneous authorities are meaningful; +- behavior expected from operational adapters. + +The resource validity interval MUST be contained by the payload validity +interval. An implementation MUST NOT assign semantics to an unknown profile. + +### Authority objects + +The `authority` map has key `0`, `kind`, with one of these values: + +| Kind | Name | Meaning | +| ---: | --- | --- | +| `0` | HNS-local origin | The profile permits controller origination | +| `1` | External origin | An external proof establishes origin authority | +| `2` | Parent delegation | A current HRM delegates the resource | + +#### HNS-local origin + +An HNS-local authority object is `{0: 0}`. + +It is valid only if the selected resource profile explicitly permits HNS-local +origination and derives a collision-resistant namespace from at least the +active Handshake network, subject name hash, and a profile-specific canonical +identifier. The profile MUST state whether the manifest controller key also +participates in resource identity and whether controller rotation preserves or +changes that identity. A public IPv4 prefix, IPv6 prefix, ASN, IANA protocol +number, IANA port, or IEEE EtherType MUST NOT be originated this way. + +#### External origin + +An external authority object contains: + +| Key | Name | Type | Required | +| ---: | --- | --- | :---: | +| `0` | `kind` | unsigned integer equal to `1` | yes | +| `1` | `proof_profile` | text string | yes | +| `2` | `proof_hash` | 32-byte string | yes | +| `3` | `proof_uris` | array of text strings | yes | + +`proof_hash` is the SHA-256 digest of the exact external proof object. The proof +may be retrieved from any source. The resource profile defines its format, +trust anchors, revocation behavior, and how it binds the resource, subject, +controller key, and validity interval. + +Merely displaying matching RDAP, WHOIS, registry, or web-page text MUST NOT be +treated as a cryptographic origin proof unless a future profile defines and +secures that exact trust model. + +#### Parent delegation + +A parent-delegation authority object contains: + +| Key | Name | Type | Required | +| ---: | --- | --- | :---: | +| `0` | `kind` | unsigned integer equal to `2` | yes | +| `1` | `parent_subject` | 32-byte string | yes | +| `2` | `parent_resource_id` | 32-byte string | yes | +| `3` | `delegation_id` | 32-byte string | yes | + +The verifier MUST retrieve and validate the current HRM for `parent_subject`, +validate `parent_resource_id`, and locate the current `delegation_id`. The +parent delegation must exactly authorize the child subject, child controller, +child resource, requested right, and current time. + +## Delegations + +A delegation object is a CBOR map: + +| Key | Name | Type | Required | Meaning | +| ---: | --- | --- | :---: | --- | +| `0` | `delegation_id` | byte string | yes | 32-byte identifier | +| `1` | `parent_resource_id` | byte string | yes | Controlled parent resource | +| `2` | `child_profile` | text string | yes | Child resource profile | +| `3` | `child_resource_id` | byte string | yes | Child resource identifier | +| `4` | `child_identifier` | byte string | yes | Canonical child resource | +| `5` | `child_subject` | byte string | yes | 32-byte child HNS name hash | +| `6` | `child_controller` | map | yes | Required child algorithm and key | +| `7` | `rights` | array of text strings | yes | Profile-defined rights | +| `8` | `not_before` | unsigned integer | yes | Earliest valid Unix time | +| `9` | `expires_at` | unsigned integer | yes | Exclusive expiry Unix time | +| `10` | `may_subdelegate` | boolean | yes | Child may delegate further | +| `11` | `constraints` | map | no | Profile-defined restrictions | + +The delegation interval MUST be contained by both the payload interval and the +parent resource interval. The child resource MUST be equal to or a valid subset +of the parent resource according to the parent profile. Cross-profile +delegation is invalid unless the parent profile explicitly defines the mapping. + +`child_controller` uses the same algorithm/key map as the payload controller. +Binding the delegation to both `child_subject` and `child_controller` prevents a +sale or compromise of only one identity component from silently transferring +the delegated resource. + +The profile defines the canonical calculation of `delegation_id`. It SHOULD be +the SHA-256 digest of a domain-separated deterministic encoding of every +security-relevant delegation field except `delegation_id` itself. + +Removing the delegation from a later parent manifest revokes it. A child copy +of an older delegation never overrides current parent state. + +## Name ownership, transfer, and key rotation + +An HRM binds a current HNS commitment and a manifest controller key. They serve +different purposes: + +- the HNS owner chooses which envelope is current; +- the controller signs the resource state; +- a parent delegation may require that exact controller key. + +Ordinary HNS `UPDATE`, `RENEW`, and `TRANSFER` processing does not invalidate an +otherwise current HRM when the exact commitment remains in current namestate. +This matches ordinary DNS-resource continuity and the HNSR root-key model. A new +name owner can remove the commitment, but cannot forge a replacement under the +existing controller key. + +A name transfer alone does not give the new owner an externally originated or +parent-delegated resource. Those authority chains remain bound to the manifest +controller. The new owner can leave that controller's exact committed manifest +available or withdraw it, but cannot change its signed contents. + +An HNS-local profile MAY define a resource as following current control of the +HNS name. A profile requiring transfer-sensitive invalidation MUST define the +extra binding and its validation rule explicitly; HRM Core does not infer +external resource ownership from a name transfer. + +Controller-key rotation has the same rule: HNS-local resources may select a new +controller through a new owner-committed envelope, but external and +parent-delegated resources require a refreshed proof or parent delegation that +binds the new controller. + +If the Handshake name is revoked, expired, or has no current owner, its HRM is +invalid. + +## Verification algorithm + +To authorize action `A` over resource `R` for subject `S`, a version 1 verifier +MUST perform the following steps. + +1. Obtain authenticated current Handshake namestate for `S` under a locally + accepted chain-finality policy. +2. Confirm the name has a current owner and is not revoked or expired. +3. Parse all `hrm1` commitment records and select the current commitment. +4. Retrieve an envelope whose SHA-256 digest matches the commitment. +5. Enforce deterministic CBOR and all envelope structural limits. +6. Decode the payload and confirm: + 1. `version` is `1`; + 2. `subject` equals `S`; + 3. `sequence` equals commitment `seq`; + 4. the signature is evaluated with the active network magic; + 5. the payload is currently within its validity interval. +7. Verify the required controller signature over the exact payload bytes. +8. Locate `R`, reject duplicate resource identifiers, and validate its profile, + canonical identifier, resource identifier, attributes, and validity. +9. Validate its authority: + 1. for HNS-local origin, confirm the profile permits origination and derives + the resource namespace from the network, subject, and any additional + profile-defined identity inputs correctly; + 2. for external origin, retrieve and verify the exact proof under configured + trust anchors and current revocation state; + 3. for parent delegation, recursively validate the current parent resource + and exact current delegation. +10. Confirm every link authorizes action `A`, every child is contained by its + parent, every time interval is contained by its parent, and every required + constraint is satisfied. +11. Apply local operational policy before returning authorization. + +A verifier MUST detect subject/resource cycles. It MUST impose a recursion limit +of no more than 32 parent links and SHOULD permit operators to configure a lower +limit. A cycle, exceeded limit, unavailable required parent, ambiguous state, +unknown critical profile, failed proof, or expired link MUST fail closed. + +## Current state and revocation + +HRM is a current-state protocol. Handshake history provides an audit trail but +does not keep removed authority active. + +To revoke a resource or delegation, the publisher increments the sequence, +removes the entry from the complete snapshot, signs the new payload, publishes +the new envelope, and updates the commitment. The revocation takes effect for a +verifier when that verifier accepts the new Handshake state under local finality +policy. + +Short emergency expiry periods can reduce exposure when a publisher cannot +immediately update the chain. Resource profiles SHOULD define maximum validity +periods appropriate to their operational risk. + +A verifier MAY cache a successful result only until the earliest of: + +- payload expiry; +- resource expiry; +- delegation expiry; +- external-proof expiry or revocation refresh; +- locally configured cache limit; +- observation of a new commitment or relevant Handshake reorganization. + +## Availability and retrieval + +Handshake commits to HRM integrity but does not guarantee delivery of the +envelope or external proofs. + +Publishers SHOULD provide multiple independent locators. Content-addressed +storage, HTTPS, HNSR, peer-to-peer storage, local operator mirrors, or other +transports MAY be used. A mirror does not need publisher permission because the +committed hash authenticates the bytes. + +Failure to retrieve a current required object means the authorization is +unavailable and MUST NOT be treated as valid. An implementation MUST NOT fall +back to an older envelope merely because the current object cannot be fetched. + +Transient HNSR route records, relay reservations, live socket addresses, and +similar presence data SHOULD NOT be placed in HRM. HRM establishes longer-lived +controller and resource authority; a rendezvous protocol may use that authority +to authenticate its own short-lived records. + +## Resource profiles + +Profiles are separate specifications so a defect or policy dispute in one +resource family does not redefine the HRM core. + +A profile specification MUST provide: + +1. A stable lowercase profile identifier. +2. Canonical resource encoding. +3. Resource-ID calculation. +4. Origin modes and accepted proof profiles. +5. Parent-child containment rules. +6. Rights, constraints, and subdelegation rules. +7. Time and expiry requirements. +8. Conflict and multiple-origin behavior. +9. At least one positive and negative deterministic test vector. +10. Security, privacy, and operational-adapter considerations. + +The HNSA companion draft defines the following exact profile identifier: + +`hns.named-service/v1` +: HNS-local named application-service identifiers, resource IDs, attributes, + and constrained delegation to service-controller keys. + +Other planned companion HIPs are expected to define profiles including: + +`hns.overlay.network/v1` +: HNS-local identifiers for explicitly opt-in virtual networks. + +`rpki.ip-prefix/v1` +: IPv4/IPv6 resources rooted in a cryptographically validated RPKI proof, with + canonical prefix containment and subdelegation. + +`rpki.asn/v1` +: ASN authority rooted in an accepted RPKI proof. + +Except for `hns.named-service/v1`, names above are illustrative and are not +allocated by this HIP. Companion documents must assign their exact profile +identifiers and semantics. + +## Operational adapters + +An adapter consumes a verified HRM result and produces output for another +system. Examples might include: + +- a proposed RPKI certificate or routing authorization; +- a BGP import-policy input; +- a network-controller configuration fragment; +- an HNSR named-service authorization; +- a WireGuard or TLS trust configuration; +- an overlay network membership decision; +- an audit report comparing HRM and an existing registry. + +Version 1 adapters MUST be opt-in and SHOULD default to audit or dry-run mode. +An adapter MUST NOT treat an HNS commitment alone as authority over a public +resource. It MUST report the complete validated proof chain and the local policy +decision that caused operational output. + +No adapter should directly change public routing, filtering, certificate trust, +or another security-sensitive system without an additional operator policy and +an explicit deployment specification. + +## Security considerations + +### False public-resource claims + +Any HNS owner can publish arbitrary bytes. Therefore an HRM without a valid +profile-specific authority chain is only a claim. Public-resource profiles MUST +validate a recognized external origin or complete parent delegation. + +### Name squatting + +Similarity between an HNS name and an organization, registry entry, domain, or +resource label does not establish authority. Validation is based on the +resource proof chain, not human-readable resemblance. + +### Name transfer + +An unchanged commitment may survive a name transfer, but externally originated +and parent-delegated authority remains bound to the manifest controller. The new +name owner may withdraw the manifest and cause denial of service; it cannot +alter the signed state or satisfy a controller-bound authority chain. HNS-local +profiles must state explicitly whether their resources follow the name. + +### Controller compromise + +A compromised controller can sign malicious manifests only if the HNS owner +also commits them, but an entity may operate both keys. Publishers SHOULD keep +the HNS owner key and manifest controller key in separate security domains. +High-risk profiles SHOULD use short expiry and explicit recovery procedures. + +### HNS owner compromise + +A compromised name owner can withdraw or replace the commitment and cause +denial of service. It cannot satisfy a controller-bound parent delegation or +external proof without the required controller authority. Operational systems +must nevertheless plan for the resulting unavailability. + +### Replay and rollback + +Sequence, current authenticated namestate, validity intervals, and local +chain-finality policy limit replay. Implementations must distinguish a genuine +Handshake reorganization from an envelope replay at equal or lower chain work. + +### Locator equivocation + +Locators may return different bytes, track clients, refuse service, or serve +malware. Hash validation prevents undetected content substitution but not +denial of service or metadata collection. + +### External proof revocation + +An unchanged HRM may outlive an external allocation or proof. Every external +profile MUST define current revocation and refresh behavior. A cached HRM result +must not outlive the proof state on which it depends. + +### Delegation cycles and exhaustion + +Attackers may construct cycles, deep graphs, large manifests, repeated +locators, or expensive proof chains. Implementations MUST bound object size, +retrieval count, redirects, total bytes, signature operations, recursion depth, +and validation time. + +Suggested default limits for an initial implementation are: + +| Item | Default maximum | +| --- | ---: | +| Envelope bytes | 1 MiB | +| Resources per manifest | 1,024 | +| Delegations per manifest | 4,096 | +| Locators attempted per object | 4 | +| Parent depth | 16 | +| Total fetched objects per decision | 64 | +| Total fetched bytes per decision | 8 MiB | + +Implementations MAY impose smaller limits. A profile requiring larger values +must justify them explicitly. + +### Parser differentials + +Security depends on independent implementations hashing and interpreting the +same bytes identically. Deterministic CBOR restrictions, byte-for-byte +re-encoding, strict profile canonicalization, and shared negative test vectors +are REQUIRED before a profile is used for operational authorization. + +### Unsafe automation + +A cryptographically valid statement can still violate an operator's business, +safety, routing, or abuse policy. HRM validation and operational acceptance are +separate decisions. Adapters must preserve that boundary. + +## Privacy considerations + +HRMs are public or publicly retrievable metadata. They may reveal network +structure, customer relationships, service inventory, controller rotation, +organizational hierarchy, and planned expiry times. + +Publishers SHOULD disclose only information needed for verification. Private +addresses, personal device identifiers, internal topology, transient routes, +and individual customer data SHOULD NOT be published unless the profile and +participants explicitly accept that disclosure. + +Retrieval can reveal which resource a client is interested in. Mirrors, +content-addressed caches, privacy relays, or locally synchronized datasets may +reduce that leakage. + +## Backwards compatibility + +This proposal uses existing valid HNS version `0` resource data and `TXT` +records. Legacy HNS nodes, miners, resolvers, and wallets require no consensus +change and may ignore `hrm1` records. + +HRM-aware software is an optional consumer. Names may continue using ordinary +DNS records. The 512-byte HNS resource limit remains unchanged. + +An implementation MUST NOT reinterpret unrelated TXT records as HRM data. Only +a record beginning with the exact `hrm1` marker is in scope. + +## Relationship to HIP-0015 and HIP-0016 + +HIP-0015 describes Handshake name updates as authenticated update chains and +allows future application-defined namestate versions. HRM uses the same general +idea of an HNS name anchoring changing application state, but version 1 remains +inside the existing DNS resource format for compatibility. + +HIP-0016 demonstrates how an off-chain authenticated data structure may commit +its root through HNS while light clients verify selected data. A future HRM +scaling proposal may replace the single-envelope snapshot with a provable map +or accumulator. That is not required for HRM version 1. + +## Relationship to HNSA + +The *Named Service Authority Profile for Handshake Resource Manifests* (HNSA) +is an HRM resource profile. Its durable authority chain uses the exact HRM Core +`hrm1` commitment, deterministic-CBOR envelope, resource object, and delegation +object defined here. + +HNSA does not define an `hsa1` commitment or a parallel root-signed service +authorization. It specializes HRM by defining `hns.named-service/v1`, a +profile-specific delegation ID, service-controller rights and constraints, and +a short-lived endpoint delegation signed by that service controller. Endpoint +delegations are application-profile objects and are deliberately kept outside +the complete HRM snapshot. + +## Relationship to HNSR + +The draft Handshake P2P Rendezvous and Authenticated Service Relay protocol +defines short-lived discovery and relay routes. HRM and HNSR are independent: + +```text +HRM + who controls a resource or long-lived service authority + +HNSR + where an authorized endpoint is reachable right now +``` + +The companion HRM/HNSA HNSR profile defines how an HNSR named route consumes a +verified `hns.named-service/v1` resource, its current HRM service delegation, +and a short-lived HNSA endpoint delegation. HRM does not require HNSR for +retrieval, and HNSR does not require HRM for unnamed node rendezvous. + +## Implementation plan + +The first reference implementation should be a small library and CLI, not a +consensus patch. + +Recommended components are: + +1. A Rust crate that encodes, signs, decodes, and validates HRM Core objects. +2. A command-line tool with `create`, `sign`, `publish`, `fetch`, `inspect`, and + `verify` operations. +3. An HNS adapter that reads and writes the version `0` commitment record. +4. Deterministic positive and negative vectors shared with a JavaScript + implementation. +5. The `hns.named-service/v1` HNSA profile as the first HNS-local pilot. +6. A read-only experimental IP-prefix profile that compares HRM results with + existing RPKI state and never changes routing. + +`hsd` and `hnsd` need no consensus modification for the core experiment. Wallet +support may improve publication ergonomics but is not required for validation. + +## Deployment gates + +HRM should advance in independently reviewed stages. + +### Stage 0: Core vectors + +- finalize CBOR encodings; +- publish controller-signature and commitment vectors; +- test malformed and non-canonical inputs across implementations. + +### Stage 1: HNS-local pilot + +- use only identifiers whose profiles are explicitly scoped to opt-in HNS + overlays; +- test owner transfer, controller rotation, revocation, expiry, reorganization, + data loss, and parent delegation; +- run on regtest and testnet before mainnet publication. + +### Stage 2: Multi-operator retrieval + +- replicate envelopes over independent transports; +- measure availability, latency, cache behavior, and denial-of-service cost; +- perform independent security review. + +### Stage 3: External-resource audit + +- use legitimately allocated test resources; +- validate but do not originate routing or registry changes; +- compare HRM delegation results with RPKI and registry state; +- document conflicts and revocation latency. + +### Stage 4: Profile and adapter proposals + +- submit each operational profile separately; +- require multi-operator evidence and negative test vectors; +- coordinate any wire-level assignment with the responsible standards and + registry community; +- keep production-changing adapters opt-in until their own threat models and + rollback procedures are accepted. + +No permanent IANA, IEEE, HNS P2P, or other wire assignment is requested by this +HIP. + +## Test requirements + +Before this proposal can move beyond Draft, the repository should contain +deterministic vectors covering at least: + +- canonical payload and envelope encoding; +- valid and invalid deterministic secp256k1 controller signatures; +- commitment-hash match and mismatch; +- HNS subject and active-network match and mismatch; +- commitment/payload sequence match and mismatch; +- selection among multiple commitments; +- equal-sequence conflicting commitments; +- payload, resource, and delegation expiry; +- name transfer with commitment retention, removal, and replacement; +- controller-key mismatch; +- valid one-level and multi-level delegation; +- invalid containment, rights escalation, and forbidden subdelegation; +- missing and revoked parent delegation; +- cycle and recursion-limit rejection; +- valid and invalid external proof stubs; +- corrupt, unavailable, and equivocating retrieval sources; +- accepted and rejected Handshake reorganization cases. + +External-resource profiles require their own additional vectors. + +## Rationale + +### Why use an on-chain hash instead of placing the manifest on chain? + +Handshake resource data is limited to 512 bytes. Internet resource proofs, +delegation graphs, certificates, and metadata can be substantially larger. +Committing only a hash keeps consensus state bounded and allows untrusted +replication. + +### Why use `TXT` instead of a new namestate version? + +`TXT` works under current consensus and can coexist with ordinary name +resolution. A new version would require ecosystem coordination before the core +security model has deployment evidence. + +### Why require a controller signature when HNS already commits the hash? + +The second key separates durable name custody from operational resource control +and gives parent delegations a stable cryptographic target. It also prevents a +name transfer alone from silently acquiring delegated infrastructure authority. +Version 1 uses the same key and signature family as the draft HNSR protocol so +an HRM service profile can reuse an existing HNSR root key. + +### Why not accept any resource claimed by an HNS owner? + +Many public resources already have globally coordinated meanings. Treating an +HNS auction as ownership of an existing IP prefix, ASN, port, protocol number, +or EtherType would create collisions that browsers and application gateways +cannot repair. + +### Why separate resource profiles? + +An IPv6 prefix has containment semantics; an ASN usually does not. A port has +different policy and operational consequences from a virtual service ID. A +single generic validator cannot safely guess these rules. + +### Why make manifests complete snapshots? + +Current snapshots make removal an unambiguous revocation and avoid requiring a +client to replay an unbounded off-chain log. Handshake history remains +available for auditing. + +## Alternatives considered + +### Independently allocate public wire values through HNS + +Rejected for HRM Core. Existing routers, switches, kernels, and protocol +implementations require coordinated meanings. HNS-local profiles may allocate +values only inside explicit overlays or formally delegated extension spaces. + +### Store unverified claims in plain TXT records + +Rejected as an authorization protocol. Plain text is useful for discovery but +does not define canonical encoding, controller continuity, authority proofs, +delegation containment, expiry, or revocation. + +### Put every resource and delegation directly on Handshake + +Rejected for version 1 because of the 512-byte limit, chain growth, privacy, +proof size, and the burden placed on unrelated full nodes. + +### Require a single HRM storage network + +Rejected. Content addressing makes storage replaceable. Mandating one delivery +network would recreate the availability dependency HRM is intended to avoid. + +### Make HRM immediately authoritative for router configuration + +Rejected. Verification formats, external trust roots, operational policy, +rollback, and multi-operator experience must be established first. + +## Open questions + +The following items should be resolved during Draft review: + +- whether a later version should register Ed25519 or another optional controller + algorithm in addition to mandatory secp256k1; +- whether one retrieval URI should be required or out-of-band retrieval should + be valid without an advertised URI; +- whether a future compact binary commitment should replace or supplement TXT; +- exact default clock-skew and Handshake-finality guidance; +- registry and review process for resource-profile identifiers; +- whether controller rotation should gain a cross-signature mechanism in Core; +- whether the first HNSA pilot should use a web, messaging, payment, or other + application profile; +- whether future selective disclosure should use an authenticated map based on + HIP-0016, another accumulator, or independent signed objects. + +## References + +1. RFC 2119, *Key words for use in RFCs to Indicate Requirement Levels*. +2. RFC 8174, *Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words*. +3. RFC 8949, *Concise Binary Object Representation (CBOR)*. +4. RFC 4648, *The Base16, Base32, and Base64 Data Encodings*. +5. RFC 7020, *The Internet Numbers Registry System*. +6. RFC 6480, *An Infrastructure to Support Secure Internet Routing*. +7. RFC 9323, *A Profile for RPKI Signed Checklists (RSCs)*. +8. RFC 8126, *Guidelines for Writing an IANA Considerations Section in RFCs*. +9. HIP-0015, *Update Chains*. +10. HIP-0016, *Escher Update Chains for decentralized subdomains*. +11. Draft HIP, *Named Service Authority Profile for Handshake Resource + Manifests*. +12. Draft HIP, *HRM/HNSA Profile for Handshake P2P Rendezvous*. +13. Draft HIP, *Handshake P2P Rendezvous and Authenticated Service Relay*. +14. Handshake developer documentation, *Resource Records*. +15. IANA, *Governance of the IANA Functions*. +16. IANA, *Number-related Registries*. +17. IANA, *Protocol Parameter Assignments*.