Skip to main content

Module moql_admission

Module moql_admission 

Source
Expand description

Inside-carrier Ed25519 + ML-DSA-65 challenge/response admission for the iroh moql ALPN (#1027). Inside-carrier challenge/response admission for the iroh moql ALPN (#1027).

§Why this exists

crate::transport::iroh_moq::IrohMoqProtocolHandler accepts raw iroh connections. The carrier handshake authenticates only the NodeId, which is reach evidence and never identity (D3/#895, #1031). Without fresh inside-carrier proof the accept path must serve an anonymous peer, and the handler correctly refuses — which means positive native streaming is impossible by construction. This module is the smallest closed-staging completion: a challenge/response exchange on the first bidirectional stream of the moql connection, run before the connection is wrapped as a web_transport_iroh::Session and handed to moq_net::Server.

§Protocol (one bi stream, length-prefixed frames)

  1. Hello (client → server): wire version, the peer’s did:at9p DID, its Ed25519 verifying key, and a fresh random client_nonce.
  2. Challenge (server → client): a fresh random server_nonce plus the client’s current accepted-state epoch and head_digest, and the server identity pinned by the signed StreamInfo response.
  3. Response (client → server): a nested composite signature over the transcript — the inner Ed25519 layer signs the transcript T, the outer ML-DSA-65 layer signs T ‖ ed_sig (the same inner→outer nesting the at9p record composite uses, hyprstream-pds::at9p_sign).
  4. Confirmation (server → client, success only): a nested server Ed25519 + ML-DSA-65 signature covers every previous frame, including the server accepted-state witness and the client’s complete hybrid response. Only after verifying it may the client start the MoQ handshake. Any rejection instead closes the connection.

The transcript binds domain, ALPN, DID, both nonces, and the accepted-state epoch/head digest:

T = "hyprstream/moql-admission/v1" ‖ 0x00 ‖ "moql" ‖ 0x00
  ‖ u16be(did_len) ‖ did ‖ client_nonce ‖ server_nonce
  ‖ u64be(epoch) ‖ head_digest

§Admission decision (every step fail-closed)

  • The DID must be a did:at9p accepted-state identity; any other DID method (including a did:key encoding of the carrier NodeId) is rejected.
  • The authority must hold a current accepted state for the DID, unexpired at decision time (expiry class).
  • The presented Ed25519 key must be one of the accepted current subject keys (subjectKeys is a published SET, #1188/#1183); the ML-DSA-65 half verified against is the one bound to that Ed25519 key by the same entry. A key rotated out by a state advance is simply absent (rotation class).
  • The state is re-read after the response arrives; an epoch/head change mid-handshake rejects (state-advance invalidation).
  • Both signature layers must verify; a classical-only or stripped composite is a downgrade and rejects.
  • A transcript digest already consumed by a prior admission rejects (replay class); a replayed response on a new connection additionally fails signature verification because the server nonce is fresh per challenge.
  • The tenant is resolved server-side from the verified subject by the operator-controlled resolver; an unresolvable or malformed tenant rejects (never a wildcard, never caller-supplied — the #1153 rule).

The carrier NodeId is recorded in [AdmittedMoqPeer::carrier_node_id] as metadata only. It is never an admission input.

§What this module does NOT do

Open/dynamic federation contract rules remain #1536 (deferred for this closed, fixed-peer staging claim). Per-track/public-relay policy remains #276; after admission the existing tenant_scoped_consumer structural narrowing applies unchanged.

Structs§

AcceptedIdentityState
The accepted current state for one did:at9p identity, projected for admission decisions. This is the admission-relevant slice of the daemon’s AcceptedAt9pState (hyprstream-pds::at9p_duplicity); the projection lives at the daemon boundary so this crate keeps no pds dependency.
AcceptedSubjectKey
One accepted current subject key: an atomic Ed25519 ↔ ML-DSA-65 pair as published in the accepted subjectKeys set.
AdmissionChallenge
Challenge (server → client): server freshness + currentness claim.
AdmissionConfirmation
Server → client mutual confirmation. Both signature halves cover every admission frame: hello, challenge (including the server accepted-state witness), and the client’s nested hybrid response.
AdmissionHello
Hello (client → server): claimed identity + freshness contribution.
AdmissionResponse
Response (client → server): the nested composite proof.
AdmittedMoqPeer
The outcome of a successful admission: a typed admitted subject and tenant from current accepted Ed25519 + ML-DSA-65 evidence.
MoqlAdmissionAuthenticator
MoqlAdmissionProof
Client-side proof material for moql admission: the peer’s accepted did:at9p identity and both private halves of one of its accepted current subject keys. The carrier (iroh secret key / NodeId) plays no part.
MoqlServerIdentityProof
Inside-carrier admission authenticator for the moql accept path.

Enums§

MoqlAdmissionError
Why an admission attempt was rejected. Each rejection class named by the #1027 contract maps to a distinct variant so negative evidence can name the exact failing check.

Constants§

DEFAULT_ADMISSION_TIMEOUT
Default bound on the whole admission exchange. A peer that opens a moql connection and never proves is a slowloris on the accept path; the exchange must not wait indefinitely.
MOQL_ADMISSION_DOMAIN
Domain separation tag at the head of every admission transcript.
VERDICT_ADMITTED
Verdict (server → client), sent only on success: the session is admitted and the moq handshake may proceed. Rejection closes the connection without a verdict — the failure detail stays server-side (fail-closed, no oracle).

Traits§

AcceptedStateAuthority
The daemon-owned accepted-state/currentness authority.

Functions§

admission_transcript
The signed transcript both sides reconstruct byte-identically.
decode_challenge
Decode a Challenge frame payload.
decode_confirmation
Decode a hybrid server confirmation frame.
decode_hello
Decode a Hello frame payload.
decode_response
Decode a Response frame payload.
decode_verdict
Decode and check a verdict frame payload.
encode_challenge
Encode a Challenge frame payload.
encode_confirmation
Encode a hybrid server confirmation frame.
encode_hello
Encode a Hello frame payload.
encode_response
Encode a Response frame payload.
encode_verdict
Encode the admission verdict frame payload.
mutual_confirmation_transcript
The complete mutually-confirmed admission transcript. Unlike the client proof’s preface, this includes the advertised server accepted-state witness and the client’s two signature layers, so the server cannot be substituted after the client proves possession.
prove_moql_admission
Run the client half of the admission exchange on conn, consuming its first bi stream. On success the connection is ready to be wrapped as a web_transport_iroh::Session for the moq handshake; on failure the server has closed (or will close) the connection and the caller MUST NOT proceed.