Skip to main content

Module did_plc

Module did_plc 

Source
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 PlcResolverConfig at 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, prev link, and ECDSA signature is verified before the directory’s current document is accepted.
  • TTL cache. The native resolver constructs HttpPlcFetcher from its one PlcResolverConfig, 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 DidDocFetcher trait (shared with did:web) keeps the parse/validate path testable without a live network; HttpPlcFetcher is the native allowlisted implementation.
  • Validate (validate_plc_document) — doc.id subject binding and recognized-member validation, applied before a native document enters the cache or any document is returned to its consumer.

Structs§

DidPlcResolver
Resolves a did:plc identifier to its validated DID document.
HttpPlcFetcher
Native HTTPS did:plc document fetcher.
PlcResolverConfig
Configuration for a did:plc resolver: the PLC directory base URL and the document-cache TTL.

Constants§

DID_PLC_PREFIX
The did:plc: method prefix.

Traits§

PlcAuditFetcher
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:plc identifier beneath base_url: {base_url}/{full-did}.
is_did_plc
Whether did is a did:plc identifier (the federation-intake arm, #1161).
validate_plc_document
Validate that doc is a DID document for did — 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.