Skip to main content

Module admission

Module admission 

Source
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)

  1. 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 / FederationKeyResolver decision point) via the OriginAdmission trait, implemented in the hyprstream crate over PolicyService (the lower hyprstream-rpc crate has no PolicyService client, so the live decision is injected). The gate calls it unchanged.

  2. 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 a verificationMethod in 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 the crate::did_web::DidWebResolver landed in #279 (no new fetch/cache infra); the VM extraction is crate::did_web::verification_method_ed25519_keys (#280 Multikey decode).
    • did:key (Tiles interop, #281) — a did:key is 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§

AdmittedIdentity
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.
ApplicationSignerKey
The raw Ed25519 signer key from independently verified application proof.
At9pAdmission
Inputs for the did:at9p admission arm (D2/#894).
FederationAdmissionGate
The federation admission gate: stage 1 (origin) then stage 2 (key binding), fail-closed if either fails.
VerifiedApplicationSigner
Application signer plus the assurance actually established by envelope verification. This is crypto-derived evidence, never a DID-document claim.

Enums§

AdmissionTrustSurface
The trust boundary on which admission is being attempted.

Traits§

DidDocResolve
Resolves a peer DID identifier to its DID document JSON.
OriginAdmission
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.