Expand description
Federation admission gate over DID/key binding (#137, milestone M3).
A transport-agnostic, two-stage fail-closed gate that decides whether an
inbound federated peer may be admitted over any
crate::transport_traits::Transport-backed session (QUIC/WebTransport,
iroh, …). It is deliberately independent of the concrete transport: the
accept path supplies the peer’s already-authenticated material; this module
makes the trust decision.
§The two stages (both must pass)
-
Origin admission — is the peer’s origin (RFC 6454: scheme + host + non-default port) permitted by policy? This reuses the existing unified federation trust gate (Casbin
federation:register, the CIMD /FederationKeyResolverdecision point) via theOriginAdmissiontrait, implemented in thehyprstreamcrate overPolicyService(the lowerhyprstream-rpccrate has noPolicyServiceclient, so the live decision is injected). The gate calls it unchanged. -
Key binding — does the independently verified application-envelope signer key bind to the peer’s DID? Carrier keys are never accepted here. Two DID-method paths:
did:web— match the key against averificationMethodin the peer’s resolved DID document (for example#mesh), OR an Ed25519 key in a federation JWKS the caller supplies. The DID document is resolved via thecrate::did_web::DidWebResolverlanded in #279 (no new fetch/cache infra); the VM extraction iscrate::did_web::verification_method_ed25519_keys(#280 Multikey decode).did:key(Tiles interop, #281) — adid:keyis self-certifying: the Ed25519 key is the identity (did:key:z6Mk…=multibase(0xed01 ‖ pubkey)). There is no document to resolve and no network fetch; the gate decodes the key from the DID (crate::did_web::did_key_to_ed25519) and admits iff the application signer key equals it. Reach is resolved separately, never from this DID.
Either stage failing — or any resolution / I/O error — rejects (§4.4
fail-closed). A successful run yields an AdmittedIdentity binding the
origin to the matched key.
§What is wired vs. what is a documented seam
Stage 2’s logic (resolve DID doc → extract VM keys → constant-time-ish
membership match, with JWKS fallback) is fully implemented and unit-tested
here against fixtures. Live callers must feed stage 2 only the signer key from
a verified application envelope. A NodeId, EndpointId, TLS certificate key,
endpoint field, or caller assertion is not a VerifiedApplicationSigner. If a
network path has no verified application proof, it must not invoke this gate
as though carrier establishment supplied one.
Structs§
- Admitted
Identity - The result of a successful two-stage admission: the peer’s normalized origin bound to the authenticated key that matched its published DID-doc VM / JWKS.
- Application
Signer Key - The raw Ed25519 signer key from independently verified application proof.
- At9p
Admission - Inputs for the
did:at9padmission arm (D2/#894). - Federation
Admission Gate - The federation admission gate: stage 1 (origin) then stage 2 (key binding), fail-closed if either fails.
- Verified
Application Signer - Application signer plus the assurance actually established by envelope verification. This is crypto-derived evidence, never a DID-document claim.
Enums§
- Admission
Trust Surface - The trust boundary on which admission is being attempted.
Traits§
- DidDoc
Resolve - Resolves a peer DID identifier to its DID document JSON.
- Origin
Admission - Stage 1: origin admission decision (RFC 6454 origin → permitted?).
Functions§
- admit_
key_ against_ did - Stage 2 core, factored out so it is independently unit-testable: bind the verified application signer key to its DID’s published key material, and admit iff it matches.
- reject_
no_ application_ signer_ proof - Convenience rejection for a network path lacking verified application proof.