Skip to main content

Module did_url

Module did_url 

Source
Expand description

DID URL parser + inert dereference plan (#906, at9p epic #880 G1).

This module only parses attacker-reproducible selectors and produces a DereferencePlan. It deliberately does not resolve DID state, decode a carrier address, construct a dial target, or prove possession. Runtime dereferencing must keep these boundaries distinct:

  1. verify the immutable genesis GATE;
  2. obtain separately accepted current DID state (future #1027 work);
  3. select the requested service from that accepted state;
  4. decode the service into typed reach;
  5. establish live possession before granting authority;
  6. attach and walk using this plan’s inert selectors.

In particular, a did:key verification key is not an iroh NodeId, an endpoint, or evidence that its holder possesses any carrier.

§Grammar (ratified 2026-07-10, fable spike — #906 comment)

Recognized query params: service | relativeRef | pin.

  • pin = a CIDv1 string (base32 bafy…, validated via crate::cid), a client-verified content commitment applied at 9P READ. It asserts no authority — a DID URL is an inert, attacker-reproducible selector (#905 §7/§8); pin only lets the reader reject wrong/inconsistent bytes.
  • versionId / versionTime → W3C-registered DID-document-version resolution options. A conformant generic dereferencer MUST pass them to the resolve step, which fails (FEATURE_NOT_SUPPORTED until capsule-epoch / KERI resolution exists). We fail closed at parse time so a travelling URL can never be silently mis-resolved, and they are never interpreted as a content pin (that would poison the resolve → #ns → alsoKnownAs interop prefix these URLs rely on when carried in NameRecord.subject).
  • hl is dropped from the grammar (document-level + doubly redundant for a self-certifying DID); like any unrecognized param it is silently ignored.
  • ?service=ns selects the #ns serviceEndpoint by fragment id → Tattach(aname="ns"). Default service is DEFAULT_SERVICE ("ns").
  • path is canonical over relativeRef: when both carry a walk, the URL path wins and relativeRef is normalized away (DidUrl::walk_segments).

§DID URL form

Per W3C DID Core + RFC 3986 opaque-path (no authority — parses like mailto: everywhere, including WHATWG/browser): the DID is the scheme prefix, the path hangs off it natively.

did:<method>:<method-specific-id>[/<path>][?<query>][#<fragment>]

The DID ends at the first /, ?, or #. The fragment is a DID-document internal reference and is stripped — service selection is via ?service=, never the URL fragment. No 9p:// or moq:// scheme is accepted (#906 acceptance): only did:-prefixed URLs parse.

Structs§

DereferencePlan
Inert service/attach/walk inputs for a parsed DidUrl (#906 G1, #905 §4).
DidUrl
A parsed DID URL — the canonical, inert addressing type (#906 G1).

Constants§

DEFAULT_SERVICE
Default service fragment id (#ns) — the NinePExport entry a DID URL attaches to when ?service= is absent (#877 aname default).