diff --git a/quest/m2/README.md b/quest/m2/README.md index 86bb7a1ffb7..48fe14c7f6c 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -44,9 +44,8 @@ Decided 2026-11-12 (maintainer, /quest-audit before the cut): [auth key validation](/quest/m2/auth-key-validation.md); the [RTMPS connect](/quest/m2/rtmp-rtmps-tcurl.md) signature; [usage's derived settings](/quest/m2/usage-derive-settings.md); - [first-publish versions](/quest/m2/first-publish-versions.md); and three - API fences: [mesh enrollment](/quest/m2/api-mesh-enrollment.md), - [the capture selections](/quest/m2/api-capture-fences.md), and + [first-publish versions](/quest/m2/first-publish-versions.md); and two + API fences: [the capture selections](/quest/m2/api-capture-fences.md) and [the acknowledgment hook's trait](/quest/m2/api-ack-hook-trait.md). None is on the routes chain, which stays the critical path. - ✅ Under the path rule a route keeps one sticky down-only flag beside its diff --git a/quest/m2/api-mesh-enrollment.md b/quest/m2/api-mesh-enrollment.md deleted file mode 100644 index 3c9722bb737..00000000000 --- a/quest/m2/api-mesh-enrollment.md +++ /dev/null @@ -1,24 +0,0 @@ -# [XS] A mesh enrollment reply can grow - -## Goal - -`moq_auth::mesh::Enrollment` and the other reply and request structs the mesh -module exports are `#[non_exhaustive]` with constructors where a caller builds -one, so a later field (a certificate, a revocation hint) is additive. The cut -publishes the module for the first time, and today `Enrollment` is a plain -struct with a public `token: String`. - -## Plan - -Decided 2026-11-12 (maintainer, /quest-audit before the cut): - -- ✅ Fence the structs now (rejected: publishing them open and breaking - later). -- ✅ The mesh [relay node](/quest/m3/mesh/node.md) takes a credential handle - and the application enrolls however it likes (rejected: the coordinator and - `Enrollment` learning to issue certificates; deferring). So this quest adds - no certificate field; it only keeps one possible. - -Sweep `rs/moq-auth/src/mesh/` for every public struct and enum a caller -matches or builds, and fence each the same way. Public API: breaking for a -caller that builds or exhaustively destructures one. Wire: none. diff --git a/quest/m2/mesh-grant-shape.md b/quest/m2/mesh-grant-shape.md index 12e234606d1..529a3a86ad7 100644 --- a/quest/m2/mesh-grant-shape.md +++ b/quest/m2/mesh-grant-shape.md @@ -40,4 +40,3 @@ signature does. Wire: none. ## Related - [Mesh enrollment is bounded](/quest/m2/mesh-device-bounds.md) - the other mesh contract change before the cut -- [Mesh enrollment can grow](/quest/m2/api-mesh-enrollment.md) - fences the enrollment reply diff --git a/quest/m3/mesh/README.md b/quest/m3/mesh/README.md index 268b1d25a54..3929900eac6 100644 --- a/quest/m3/mesh/README.md +++ b/quest/m3/mesh/README.md @@ -119,8 +119,8 @@ Decided 2026-11-12 (maintainer, /quest-audit before the cut): - ✅ The relay node takes a credential handle and the application enrolls however it likes (rejected: the coordinator issuing certificates; deferring). `moq_auth::mesh`'s token enrollment stays one way to get a - handle. [Mesh enrollment can grow](/quest/m2/api-mesh-enrollment.md) - fences the reply before the cut publishes it. + handle. The enrollment reply is `#[non_exhaustive]` before the cut + publishes it. - ✅ The contract changes land in m2, because the cut publishes `moq_auth::mesh` for the first time: the [grant shape](/quest/m2/mesh-grant-shape.md) and the diff --git a/rs/moq-auth/src/mesh/client.rs b/rs/moq-auth/src/mesh/client.rs index 10cdaf8c869..e294c18b359 100644 --- a/rs/moq-auth/src/mesh/client.rs +++ b/rs/moq-auth/src/mesh/client.rs @@ -60,11 +60,8 @@ impl Client { /// name the device already has. pub async fn enroll(&self, key: &str, name: Option<&str>) -> crate::Result { let proof = self.proof().await?; - let request = EnrollRequest { - proof, - key: key.into(), - name: name.map(Into::into), - }; + let mut request = EnrollRequest::new(proof, key); + request.name = name.map(Into::into); match self.post("enroll", &request).await { Err(Error::Mesh(refused)) if refused.error == ErrorCode::InvalidGrant => match self.refresh().await { // Not enrolled after all, so the key's refusal is the answer. diff --git a/rs/moq-auth/src/mesh/coordinator.rs b/rs/moq-auth/src/mesh/coordinator.rs index cee6b7e5206..2123d9295f4 100644 --- a/rs/moq-auth/src/mesh/coordinator.rs +++ b/rs/moq-auth/src/mesh/coordinator.rs @@ -233,10 +233,10 @@ impl Coordinator { challenge.extend_from_slice(&self.sequence.fetch_add(1, Ordering::Relaxed).to_be_bytes()); let tag = self.tag(&challenge); challenge.extend_from_slice(&tag); - Challenge { + Challenge::new( challenge, - expires: kio::clock::Wall::UNIX_EPOCH.saturating_add(Duration::from_secs(expires)), - } + kio::clock::Wall::UNIX_EPOCH.saturating_add(Duration::from_secs(expires)), + ) } /// Enroll with an enrollment key. @@ -491,22 +491,19 @@ impl Coordinator { .iter() .find(|device| device.endpoint == endpoint) .expect("admitted before it is issued"); - Ok(Enrollment { - token, - expires, - relays: self.config.relays.clone(), - name: device.name.clone(), - members: store - .devices - .iter() - .filter(|device| !device.revoked) - .map(|device| Member { - endpoint: device.endpoint, - name: device.name.clone(), - tags: device.tags.clone(), - }) - .collect(), - }) + let mut enrollment = Enrollment::new(token, expires, device.name.clone()); + enrollment.relays = self.config.relays.clone(); + enrollment.members = store + .devices + .iter() + .filter(|device| !device.revoked) + .map(|device| { + let mut member = Member::new(device.endpoint, device.name.clone()); + member.tags = device.tags.clone(); + member + }) + .collect(); + Ok(enrollment) } /// Write the store atomically: a temporary file beside it, renamed over it. diff --git a/rs/moq-auth/src/mesh/mod.rs b/rs/moq-auth/src/mesh/mod.rs index ae832bbb42f..cf777465a79 100644 --- a/rs/moq-auth/src/mesh/mod.rs +++ b/rs/moq-auth/src/mesh/mod.rs @@ -18,6 +18,10 @@ //! | `POST {base}/refresh` | [`Proof`] | [`Enrollment`] | //! //! Every refusal is a 4xx with an [`ErrorReply`]. +//! +//! The request and reply structs are `#[non_exhaustive]` so the contract can gain a field +//! without a breaking change: build one with its `new` (or [`Proof::sign`]) and set the +//! optional fields, and match one with `..`. use std::fmt; @@ -74,6 +78,7 @@ fn audience(base: &url::Url) -> &str { /// A fresh, single-use challenge from `POST {base}/challenge`. #[serde_as] #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[non_exhaustive] pub struct Challenge { /// 32 bytes, opaque to the device, base64url without padding. #[serde_as(as = "serde_with::base64::Base64")] @@ -83,6 +88,13 @@ pub struct Challenge { pub expires: kio::clock::Wall, } +impl Challenge { + /// A challenge of `challenge` bytes that stops being accepted at `expires`. + pub fn new(challenge: Vec, expires: kio::clock::Wall) -> Self { + Self { challenge, expires } + } +} + /// Proof that the caller holds `endpoint`'s secret key: its signature over a challenge the /// coordinator issued and has not yet seen used. /// @@ -90,6 +102,7 @@ pub struct Challenge { /// the device addressed it without a trailing slash, a zero byte, then the raw challenge. #[serde_as] #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[non_exhaustive] pub struct Proof { /// The endpoint ID, which is the key that signed. pub endpoint: PublicKey, @@ -155,6 +168,7 @@ impl Signer for rind::signature::Ed25519KeyPair { /// `POST {base}/enroll`: join with a pre-authorized enrollment key. #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[non_exhaustive] pub struct EnrollRequest { /// Proof of the endpoint key. #[serde(flatten)] @@ -167,9 +181,22 @@ pub struct EnrollRequest { pub name: Option, } +impl EnrollRequest { + /// A request to join with `key`, proving the endpoint key with `proof` and asking for no + /// particular name; set [`name`](Self::name) to ask for one. + pub fn new(proof: Proof, key: impl Into) -> Self { + Self { + proof, + key: key.into(), + name: None, + } + } +} + /// What a device needs to join: the relays to dial and the token to present. #[serde_as] #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[non_exhaustive] pub struct Enrollment { /// A JWT granting publish on `mesh//**` and subscribe on `mesh/**`, rooted at `/`. pub token: String, @@ -184,8 +211,23 @@ pub struct Enrollment { pub members: Vec, } +impl Enrollment { + /// An enrollment of the device `name` presenting `token` until `expires`, with no relays + /// and no members; set [`relays`](Self::relays) and [`members`](Self::members). + pub fn new(token: impl Into, expires: kio::clock::Wall, name: impl Into) -> Self { + Self { + token: token.into(), + expires, + relays: Vec::new(), + name: name.into(), + members: Vec::new(), + } + } +} + /// One enrolled device, as listed in an [`Enrollment`]. #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[non_exhaustive] pub struct Member { /// Its endpoint ID. pub endpoint: PublicKey, @@ -196,6 +238,17 @@ pub struct Member { pub tags: Vec, } +impl Member { + /// A member with `endpoint` and `name` and no tags; set [`tags`](Self::tags). + pub fn new(endpoint: PublicKey, name: impl Into) -> Self { + Self { + endpoint, + name: name.into(), + tags: Vec::new(), + } + } +} + /// Why the coordinator refused, in the shape of an OAuth error response (RFC 6749 §5.2). #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, thiserror::Error)] #[error("{error}{}", description.as_deref().map(|d| format!(": {d}")).unwrap_or_default())]