Expand description
did:plc → DID document resolution — federation intake (#1161, epic #1158 E1).
The epic #1158 decision: hyprstream mints host-form did:web, but
accepts federation from did:plc identities — the rule governs what we
mint, not what we trust. This module is the intake path that makes an
external (e.g. Bluesky) user’s DID resolvable here: it fetches the subject’s
DID document from a PLC directory and validates it before any consumer sees
it.
§Guarantees (#1161)
- Configurable base URL. The PLC directory’s base URL is required from
PlcResolverConfigat construction; this crate deliberately provides no default directory. (did:plc was rejected as a minting method for its single-operator dependency; hardcoding its host here would reintroduce that dependency on the read side.) - Self-authenticating resolution. The returned document must claim the
DID that was asked for (
validate_plc_document), and its identity-bearing fields must equal the state derived from a verified PLC audit log. Genesis binds to the DID; every operation CID,prevlink, and ECDSA signature is verified before the directory’s current document is accepted. - TTL cache. The native resolver constructs
HttpPlcFetcherfrom its onePlcResolverConfig, so validated documents are cached for exactly the configured TTL and the cache is bounded to a fixed number of entries. - Fail-closed. Resolution failure, a malformed document, an ambiguous or
invalid DID, or a failed validation all return
Err. The cache never serves an expired entry and failures are never cached — there is no cached-but-expired or partially-parsed fallback. - Egress allowlist. The fetcher issues requests only to the configured base URL’s origin; any URL whose origin is not on the allowlist is refused before a request is dispatched.
- Read-only forever. We never write to a PLC directory. This is structural: the types in this module expose no write methods — the HTTP client is private and used for GET only. Adding a write path is a protocol decision, not a refactor, and belongs in its own epic.
Full historical-time queries and independent recovery-window/fork-policy auditing remain E2 (#1174) through the C1 (#1167) verifier trait. This resolver nevertheless verifies the complete returned signature chain now; it does not trust the directory’s current document as an unsigned assertion.
§Layering
- DID → URL (
did_plc_url) — pure derivation against a validated base URL; strict method-specific-identifier validation. - Fetch + cache — the injected
DidDocFetchertrait (shared withdid:web) keeps the parse/validate path testable without a live network;HttpPlcFetcheris the native allowlisted implementation. - Validate (
validate_plc_document) —doc.idsubject binding and recognized-member validation, applied before a native document enters the cache or any document is returned to its consumer.
Structs§
- DidPlc
Resolver - Resolves a
did:plcidentifier to its validated DID document. - Http
PlcFetcher - Native HTTPS
did:plcdocument fetcher. - PlcResolver
Config - Configuration for a
did:plcresolver: the PLC directory base URL and the document-cache TTL.
Constants§
- DID_
PLC_ PREFIX - The
did:plc:method prefix.
Traits§
- PlcAudit
Fetcher - A PLC fetcher must provide both the current DID document and its audit log.
Functions§
- did_
plc_ url - Derive the DID-document URL for a
did:plcidentifier beneathbase_url:{base_url}/{full-did}. - is_
did_ plc - Whether
didis adid:plcidentifier (the federation-intake arm, #1161). - validate_
plc_ document - Validate that
docis a DID document fordid— the subject binding that prevents a substitution oracle (#1161). - verify_
plc_ audit - Verify the complete returned operation signature chain and bind the current DID document’s identity-bearing fields to the verified active head.