diff --git a/HIP-xxxx-HNSA-HNSR.md b/HIP-xxxx-HNSA-HNSR.md new file mode 100644 index 0000000..8bdb5d5 --- /dev/null +++ b/HIP-xxxx-HNSA-HNSR.md @@ -0,0 +1,409 @@ +# HIP-xxxx: HRM/HNSA Profile for Handshake P2P Rendezvous + +```text +Number: HIP-xxxx +Title: HRM/HNSA Profile for Handshake P2P Rendezvous +Type: Standards Track +Status: Draft +Authors: Jaron Rosenau <@denuoweb> +Created: 2026-08-03 +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 Resource +Manifests (HRM), Handshake Named Service Authority (HNSA), and Handshake P2P +Rendezvous and Authenticated Service Relay (HNSR). + +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 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 + -> hrm1 commitment + -> controller-signed current HRM envelope + -> hns.named-service/v1 resource + -> current HRM delegation to a service key + -> HNSA EndpointDelegationV1 + -> HNSR NamedRouteRecordV3 + -> 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 + +- 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 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 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, + framing, lifetimes, and browser policy. + +## Non-goals + +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. + +## 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. + +HRM-backed named routes use experimental values: + +```text +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 any of the three formats as another. + +The `profile_id` carried by an HNSR reservation, relay ticket, route, and +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 documented 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 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 earlier implementation: + +```text +network_magic = 0xae3895cf +name_hash = 0f repeated 32 times +service_name = pool-stats +profile_id = 0xff00 +route_key = 7e1a513c71518f69164fdcc754202a769 + e8cbd2dd980da3fd231b9b0de90e60b +``` + +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 +NamedRouteRecordV3 { + version: u8 + authority_type: u8 + route_key: u8[32] + profile_id: u16 + record_sequence: u64 + issued_at: u64 + expires_at: u64 + 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 + tickets: RelayTicketV1[ticket_count] + endpoint_signature_length: u8 + endpoint_signature: u8[endpoint_signature_length] +} +``` + +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. + +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-HRM-HNSA-ROUTE-RECORD-V3\0" + || canonical_route_body +) +``` + +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 `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; +- 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; +- 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-resource 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 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 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 +`hsa1` authorization, stale HRM, unauthenticated endpoint, directory result, +DNS answer, relay identity, or conventional-web endpoint under the same +HRM/HNSA identity. + +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 + +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 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. + +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 +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. + +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, 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, application_profile_id) +``` + +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. 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. + +## Availability, 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 +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, 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, +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. + +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 HRM, HNSA, this adapter, +and application profiles remain Draft. + +## Deployment gates + +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 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. + +## 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, *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 new file mode 100644 index 0000000..92858c9 --- /dev/null +++ b/HIP-xxxx-HNSA.md @@ -0,0 +1,913 @@ +# HIP-xxxx: Named Service Authority Profile for Handshake Resource Manifests + +```text +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), the first +application-resource profile for Handshake Resource Manifests (HRM). + +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: + +```text +current authenticated HNS name state + | + v +HRM hrm1 commitment + | + v +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, route, or signed application record +``` + +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. 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 +``` + +For example, a future payment profile may define the user-facing identifier +`jaron@denuoweb` as the HNSA service tuple: + +```text +HNS name = denuoweb +service name = jaron +profile = payment profile +``` + +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 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 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 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 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 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. + +## Terminology + +**HRM subject** +: The HNS name hash in the current verified HRM payload. + +**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 HNS-local HRM resource identified by a Handshake network, HNS name hash, + canonical service name, and application profile ID. + +**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. + +**Service controller** +: The key in the current HRM service delegation. It may sign bounded endpoint + delegations for exactly one named service. + +**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. + +**Service resource ID** +: The stable HRM resource ID calculated from the named-service identity. + +**Service delegation ID** +: The HRM delegation ID for the current delegation of a named service to its + service controller. + +## Dependency on HRM Core + +A relying implementation MUST validate the complete current HRM before applying +this profile. That validation includes: + +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. + +HNSA MUST NOT duplicate, bypass, or weaken those checks. + +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. + +## Named-service identity + +A named service is identified by: + +```text +Handshake network magic +HNS name hash +canonical service name +application profile ID +``` + +This tuple is stable across HRM controller rotation, service-controller +rotation, endpoint rotation, provider migration, and transport failover. + +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 a period, slash, underscore, whitespace, `@`, or percent + escape; and +- are compared byte-for-byte without locale processing. + +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. + +Application profile ID zero is invalid. Draft profiles MUST use an explicitly +documented private experimental value until an assignment is accepted. + +## Canonical named-service identifier + +The `identifier` byte string of an `hns.named-service/v1` HRM resource is +the deterministic-CBOR encoding of: + +| 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 | + +No other key is permitted in version 1. + +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 service resource ID is: + +```text +SHA-256( + ASCII("HNS-HRM-NAMED-SERVICE-ID-V1") || 0x00 + || canonical_identifier +) +``` + +Two canonical identifiers are equal only when all four fields are equal. + +## Named-service resource + +An HNSA service uses the HRM resource profile identifier: + +```text +hns.named-service/v1 +``` + +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 +SHA-256( + ASCII("HNS-HRM-NAMED-SERVICE-DELEGATION-ID-V1") || 0x00 + || service_delegation_body +) +``` + +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 current service controller may sign one or more short-lived endpoint +delegations: + +```text +EndpointDelegationV1 { + 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] +} +``` + +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-HRM-HNSA-ENDPOINT-DELEGATION-V1\0" + || canonical_endpoint_body +) +``` + +Rules: + +- `version` MUST equal 1; +- `network_magic` MUST match the active Handshake network; +- 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 increase for replacement of the + same profile-defined logical endpoint; +- `issued_at` MUST be less than `expires_at`; +- 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 +SHA-256( + ASCII("HNS-HRM-HNSA-ENDPOINT-DELEGATION-ID-V1") || 0x00 + || complete_canonical_endpoint_delegation +) +``` + +A service may authorize several endpoints concurrently for redundancy, +geographic distribution, device migration, or transport choice. + +## Profile-specific records and application payloads + +HNSA stops after authorizing the endpoint key. An application or transport +profile defines the next object. + +A profile-specific record MUST bind at least: + +- active network magic; +- 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 a profile-specific endpoint record for expected named service +`S`, a client MUST: + +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. + +Untrusted objects MUST NOT select a different HNS name, service name, or +application profile from the identity requested by the user or application. + +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. + +## Replacement, revocation, and caching + +### HRM and resource replacement + +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. + +### Service-controller replacement + +A replacement delegation MUST use a greater `service_generation`. Equal +generations with different controller, rights, constraints, or canonical bytes +are conflicting and invalid. + +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. + +### Endpoint replacement + +Endpoint delegations are short-lived and may overlap. The application profile +defines the logical endpoint identifier used when comparing +`endpoint_sequence`. + +### Caching + +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 + +### Stable origin + +A web-facing profile MUST scope browser identity and storage to at least: + +```text +Handshake network +HNS name hash +canonical service name +application profile ID +``` + +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 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 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. + +### Permissions + +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 HIP-0002 and wallet TXT conventions + +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. + +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. + +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. + +## 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. + +An application may display `jaron@denuoweb` while resolving +`jaron.denuoweb`; that is a DNS-based application convention, not HNSA. + +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. + +## Relationship to HNSR + +HNSA establishes the durable named-service resource and current service +controller. HNSR may discover short-lived endpoints and relay opaque +application streams. + +The companion HRM/HNSA HNSR profile defines route records that bind: + +- the stable HNSA service resource ID; +- the current HRM service delegation ID and generation; +- an HNSA endpoint delegation; and +- current HNSR relay tickets. + +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 + +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. + +### HRM-controller compromise + +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-controller compromise + +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 its endpoint until the earliest +applicable delegation or record expiry. + +### External wallet destinations + +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. + +### Replay and rollback + +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. + +### Name transfer + +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. + +### Untrusted retrieval + +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 + +HRM Core bounds envelope and delegation processing. HNSA additionally requires: + +| Item | Maximum | +| --- | ---: | +| Service name | 63 bytes | +| Endpoint-delegation signature | 80 bytes | +| Endpoint delegation | 320 bytes | +| Concurrent service candidates per identity | 2 before ambiguity rejection | +| Concurrent endpoint candidates | 32 | +| Detached constraints object | 64 KiB | + +Application profiles may impose smaller bounds. Larger bounds require explicit +justification and tests. + +## Privacy considerations + +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. + +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 + +Implementation should proceed in this dependency order: + +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. + +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: 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. + +### Stage 1: Named-service profile + +- 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. + +### Stage 2: Endpoint authority + +- publish endpoint-delegation signature and ID vectors; +- test concurrent endpoints, capability constraints, expiry, replacement, and + removed-controller rejection. + +### Stage 3: Application and transport profiles + +- 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. + +### Stage 4: Independent clients and operators + +- 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 + +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 make HNSA an HRM profile? + +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. + +### Why keep endpoint delegations outside HRM? + +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. + +### Why use a complete manifest snapshot? + +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. + +### Why distinguish application profiles from HRM resource profiles? + +`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. + +### Why not use DNS delegation alone? + +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 remain for Draft review: + +- 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*. +2. RFC 8174, *Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words*. +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. 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*.