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)
- Hello (client → server): wire version, the peer’s
did:at9pDID, its Ed25519 verifying key, and a fresh randomclient_nonce. - Challenge (server → client): a fresh random
server_nonceplus the client’s current accepted-stateepochandhead_digest, and the server identity pinned by the signedStreamInforesponse. - Response (client → server): a nested composite signature over the
transcript — the inner Ed25519 layer signs the transcript
T, the outer ML-DSA-65 layer signsT ‖ ed_sig(the same inner→outer nesting the at9p record composite uses,hyprstream-pds::at9p_sign). - 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:at9paccepted-state identity; any other DID method (including adid:keyencoding 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
(
subjectKeysis 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§
- Accepted
Identity State - The accepted current state for one
did:at9pidentity, projected for admission decisions. This is the admission-relevant slice of the daemon’sAcceptedAt9pState(hyprstream-pds::at9p_duplicity); the projection lives at the daemon boundary so this crate keeps no pds dependency. - Accepted
Subject Key - One accepted current subject key: an atomic Ed25519 ↔ ML-DSA-65 pair as
published in the accepted
subjectKeysset. - Admission
Challenge - Challenge (server → client): server freshness + currentness claim.
- Admission
Confirmation - 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.
- Admission
Hello - Hello (client → server): claimed identity + freshness contribution.
- Admission
Response - Response (client → server): the nested composite proof.
- Admitted
MoqPeer - The outcome of a successful admission: a typed admitted subject and tenant from current accepted Ed25519 + ML-DSA-65 evidence.
- Moql
Admission Authenticator - Moql
Admission Proof - Client-side proof material for
moqladmission: the peer’s accepteddid:at9pidentity and both private halves of one of its accepted current subject keys. The carrier (iroh secret key / NodeId) plays no part. - Moql
Server Identity Proof - Inside-carrier admission authenticator for the
moqlaccept path.
Enums§
- Moql
Admission Error - 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
moqlconnection 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§
- Accepted
State Authority - 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 aweb_transport_iroh::Sessionfor the moq handshake; on failure the server has closed (or will close) the connection and the caller MUST NOT proceed.