diff --git a/doc/bin/relay/auth.md b/doc/bin/relay/auth.md index 80022a41215..1d8b629ae90 100644 --- a/doc/bin/relay/auth.md +++ b/doc/bin/relay/auth.md @@ -452,8 +452,11 @@ also guards a loopback listener. See `moq auth serve --help` for the rest. `--mesh-url URL` also makes the server a mesh coordinator: a device holding an Ed25519 endpoint key enrolls and receives the relay URLs to dial and a JWT that -publishes `mesh//**` and subscribes `mesh/**`, where `` is the key in -z-base-32 (52 characters, the form pkarr and iroh's DNS discovery use). It is +publishes `mesh/node//**` plus its own end of every service, +`mesh/service/*/.server/` and `mesh/service/*/.client/`, and subscribes +`mesh/**`, where `` is the key in z-base-32 (52 characters, the form pkarr +and iroh's DNS discovery use). Nodes and services sit under separate prefixes, so +a service named after another member cannot answer as that member. It is verified like any other token, so the verifying keys (`--key`, `--key-dir`, or `--key-set`) must include `--mesh-key`'s public half. diff --git a/js/crypto/README.md b/js/crypto/README.md index 6234988d902..8f29bcd64fd 100644 --- a/js/crypto/README.md +++ b/js/crypto/README.md @@ -35,7 +35,7 @@ import { Path } from "@moq/net"; const { Broadcast, SecretKey } = Sign; const key = await SecretKey.generate(); -const path = Path.from(`mesh/${key.public}/agent`); +const path = Path.from(`mesh/node/${key.public}/agent`); const route = origin.route(path, { hidden: true }); // Signs under the route's instance, which readers verify against. const signed = new Broadcast.Producer(route.broadcast, key, { path, instance: route.instance }); diff --git a/js/crypto/src/sign/index.ts b/js/crypto/src/sign/index.ts index 8b9e5b4704d..c501cbea6c3 100644 --- a/js/crypto/src/sign/index.ts +++ b/js/crypto/src/sign/index.ts @@ -12,7 +12,7 @@ * * ```ts * const key = await SecretKey.generate(); - * const path = Path.from(`mesh/${key.public}/agent`); + * const path = Path.from(`mesh/node/${key.public}/agent`); * const route = origin.route(path, { hidden: true }); * const signed = new Broadcast.Producer(route.broadcast, key, { path, instance: route.instance }); * const messages = signed.createTrack("messages"); diff --git a/js/crypto/src/sign/sign.test.ts b/js/crypto/src/sign/sign.test.ts index 8eaf8448b1a..f4bee4a6aad 100644 --- a/js/crypto/src/sign/sign.test.ts +++ b/js/crypto/src/sign/sign.test.ts @@ -70,7 +70,7 @@ async function payload(group: Group.Consumer | undefined): Promise { const key = await SecretKey.generate(); - const path = Path.from(`mesh/${key.public}/agent`); + const path = Path.from(`mesh/node/${key.public}/agent`); const published = await publish(key, path); const options: { timescale: Time.Timescale } = { timescale: Time.Timescale.MILLI }; const video = published.signed.createTrack("video", options); @@ -201,7 +201,7 @@ test("a group sequence is never signed twice", async () => { test("a broadcast signed under another key is refused", async () => { const impostor = await SecretKey.generate(); const victim = await SecretKey.generate(); - const path = Path.from(`mesh/${victim.public}/ssh`); + const path = Path.from(`mesh/node/${victim.public}/ssh`); const published = await publish(impostor, path); const stream = published.signed.createTrack("stream"); const group = stream.appendGroup(); diff --git a/quest/m2/README.md b/quest/m2/README.md index 86bb7a1ffb7..2697d6d870e 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -38,7 +38,7 @@ Decided 2026-11-12 (maintainer, /quest-audit before the cut): offset goes on the wire version after lite-07 (rejected for each: staying in m2). The padding and JS rung disable quests are parked in m5. - ✅ Joined m2, each a small break the cut would otherwise freeze: the mesh - [grant shape](/quest/m2/mesh-grant-shape.md) and + grant shape (landed) and [key budget](/quest/m2/mesh-device-bounds.md), since `moq_auth::mesh` publishes for the first time at this cut; [auth key validation](/quest/m2/auth-key-validation.md); the diff --git a/quest/m2/mesh-grant-shape.md b/quest/m2/mesh-grant-shape.md deleted file mode 100644 index 12e234606d1..00000000000 --- a/quest/m2/mesh-grant-shape.md +++ /dev/null @@ -1,43 +0,0 @@ -# [S] Mesh grants scope nodes and services apart - -## Goal - -A mesh member's grant publishes `mesh/node//**` and the two service -patterns `mesh/service/*/.server/` and `mesh/service/*/.client/`, in -place of `mesh//**`. A service named after another member can no longer -put `.server/` under its own grant and answer as that member. The -shape lands before the cut publishes `moq_auth::mesh` for the first time, so -no enrolled device ever holds the old grant from a release. - -## Plan - -Split from the [Endpoint API](/quest/m3/mesh/endpoint.md) on 2026-11-12 -(maintainer, /quest-audit before the cut): ✅ the grant shape lands in m2 on -its own (rejected: landing with the Endpoint after the cut, with the -coordinator issuing both shapes for one release). `rs/moq-auth/src/mesh` -exists on `main` and not on `release`, so there is nothing to migrate and no -dual-grant rollout. - -The shape was decided 2026-11-07 (maintainer, /quest-complete, from the -review of [moq-dev/moq#8214](https://github.com/moq-dev/moq/pull/8214)): -members own `mesh/node//**` and each service lives at -`mesh/service/` (rejected: `mesh/.service/`; keeping -`mesh/` and refusing service names shaped like an endpoint ID). A -service name is one path segment, so `*` in the grant covers it. - -- `moq_auth::mesh`'s coordinator issues the new patterns - (`rs/moq-auth/src/mesh/coordinator.rs`), with its docs - (`rs/moq-auth/src/mesh/mod.rs`) and contract tests. -- `doc/bin/relay/auth.md`'s mesh enrollment section names the new grant. -- moq-crypto's and `@moq/crypto`'s sign examples and tests that use - `mesh//agent` paths move to `mesh/node//agent`. -- A hosted coordinator implementing the JSON contract issues the same grant; - the PR's Impact section says so. Applications built on `main` re-enroll. - -Public API: the grant a mesh coordinator issues changes; no Rust or JS -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..62e3d6115f3 100644 --- a/quest/m3/mesh/README.md +++ b/quest/m3/mesh/README.md @@ -72,7 +72,7 @@ Decided 2026-10-25 with the maintainer (planning interview), still in force: 2026-11-03 when sockets became endpoints, 2026-11-06 when endpoints split into server and client roles, and 2026-11-07 when member and service paths were scoped apart; the [Endpoint API](/quest/m3/mesh/endpoint.md) - changes the shipped `mesh//**` grant). Relays need no new check. Membership is the coordinator's + builds on the `mesh/node//**` and `mesh/service/*` grant). Relays need no new check. Membership is the coordinator's token only; a Tailnet-Lock analog was declined. - Protection is per broadcast, with levels that nest: identity (the token only), authentication (per-frame Ed25519 signatures, the default), and @@ -123,7 +123,7 @@ Decided 2026-11-12 (maintainer, /quest-audit before the cut): fences the reply 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 + grant shape (landed) and the [key budget](/quest/m2/mesh-device-bounds.md). - The JS enrollment client and the guide are parked in m5: the application they were planned for enrolls with certificates and documents itself. diff --git a/quest/m3/mesh/endpoint.md b/quest/m3/mesh/endpoint.md index 1d9e719c8b0..c3701677ffb 100644 --- a/quest/m3/mesh/endpoint.md +++ b/quest/m3/mesh/endpoint.md @@ -52,13 +52,10 @@ member A put `.server/B` under A's own grant, so A could answer as B; the one path segment, validated when the `Endpoint` is built, so `*` in the grant covers it (`video/h264` would fall outside). -The grant change itself is its own quest, in m2, so it lands before the cut -publishes `moq_auth::mesh` (split 2026-11-12, maintainer, /quest-audit): -[mesh grants scope nodes and services apart](/quest/m2/mesh-grant-shape.md). -This quest builds the `Endpoint` on the new grant, and the dual-grant rollout +The grant change landed on its own in m2, before the cut publishes +`moq_auth::mesh` (split 2026-11-12, maintainer, /quest-audit). This quest builds the `Endpoint` on the new grant, and the dual-grant rollout question it carried is gone, since no release ever issued the old shape. ## Required - [Rust byte streams](/quest/m1/stream/rust.md) - the stream this API returns -- [Mesh grant shape](/quest/m2/mesh-grant-shape.md) - the grant that lets a member publish its service endpoints diff --git a/rs/moq-auth/src/mesh/contract_tests.rs b/rs/moq-auth/src/mesh/contract_tests.rs index 6f3f043fc5b..e8b63001bce 100644 --- a/rs/moq-auth/src/mesh/contract_tests.rs +++ b/rs/moq-auth/src/mesh/contract_tests.rs @@ -74,11 +74,30 @@ async fn an_enrollment_key_grants_the_endpoints_subtree() { let id = enrollment.members[0].endpoint; let claims = mesh.key.verify(&enrollment.token).unwrap(); assert_eq!(claims.expires, Some(enrollment.expires)); - let own = claims.authorize(&format!("mesh/{id}/ssh")).unwrap(); - assert!(!own.publish.is_empty()); - let other = claims.authorize("mesh/someone").unwrap(); - assert!(other.publish.is_empty()); - assert!(!other.subscribe.is_empty()); + let publishes = |path: &str| !claims.authorize(path).unwrap().publish.is_empty(); + assert!(publishes(&format!("mesh/node/{id}/ssh"))); + assert!(publishes(&format!("mesh/service/ssh/.server/{id}"))); + assert!(publishes(&format!("mesh/service/ssh/.client/{id}"))); + // A service named after another member cannot answer as that member. + let others = mesh + .device() + .enroll(&mesh.key(false), Some("other")) + .await + .unwrap() + .members; + let other = others + .iter() + .map(|m| m.endpoint) + .find(|e| *e != id) + .unwrap() + .to_string(); + assert!(!publishes(&format!("mesh/node/{other}/ssh"))); + assert!(!publishes(&format!("mesh/service/{id}/.server/{other}"))); + assert!(!publishes(&format!("mesh/service/ssh/.server/{other}"))); + assert!(!publishes(&format!("mesh/{id}/ssh"))); + let someone = claims.authorize("mesh/someone").unwrap(); + assert!(someone.publish.is_empty()); + assert!(!someone.subscribe.is_empty()); assert!(claims.authorize("elsewhere").is_err()); } diff --git a/rs/moq-auth/src/mesh/coordinator.rs b/rs/moq-auth/src/mesh/coordinator.rs index cee6b7e5206..f3cbf8c0f40 100644 --- a/rs/moq-auth/src/mesh/coordinator.rs +++ b/rs/moq-auth/src/mesh/coordinator.rs @@ -536,10 +536,17 @@ fn refuse_revoked(store: &Store, endpoint: PublicKey) -> Reply<()> { Ok(()) } -/// The grant every mesh token carries: publish under its own ID, subscribe to the mesh. +/// The grant every mesh token carries: publish its own node subtree and its own end of +/// any service, subscribe to the mesh. Nodes and services live under separate prefixes, +/// so a service named after another member cannot answer as that member. fn claims(endpoint: PublicKey, issued: kio::clock::Wall, expires: Option) -> Claims { + let pattern = |p: String| p.parse::().expect("a z-base-32 segment is a valid path"); Claims::default() - .with_publish([Pattern::subtree(&format!("mesh/{endpoint}")).expect("a z-base-32 segment is a valid path")]) + .with_publish([ + pattern(format!("mesh/node/{endpoint}/**")), + pattern(format!("mesh/service/*/.server/{endpoint}")), + pattern(format!("mesh/service/*/.client/{endpoint}")), + ]) .with_subscribe([Pattern::subtree("mesh").expect("a valid path")]) .with_issued(issued) .with_expires(expires) diff --git a/rs/moq-auth/src/mesh/mod.rs b/rs/moq-auth/src/mesh/mod.rs index ae832bbb42f..63b1f8abd2d 100644 --- a/rs/moq-auth/src/mesh/mod.rs +++ b/rs/moq-auth/src/mesh/mod.rs @@ -3,7 +3,8 @@ //! A device proves it holds its Ed25519 endpoint key by signing a fresh challenge from //! the coordinator, and presents an enrollment key the mesh owner created, so enrollment //! needs no human in the loop. The coordinator answers with an -//! [`Enrollment`]: the relays to dial and a JWT granting publish on `mesh//**` and +//! [`Enrollment`]: the relays to dial and a JWT granting publish on `mesh/node//**`, +//! `mesh/service/*/.server/`, and `mesh/service/*/.client/`, and //! subscribe on `mesh/**`. The device refreshes it before it expires by proving its key //! again, so revoking a device makes its next refresh fail. //! @@ -171,7 +172,8 @@ pub struct EnrollRequest { #[serde_as] #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] pub struct Enrollment { - /// A JWT granting publish on `mesh//**` and subscribe on `mesh/**`, rooted at `/`. + /// A JWT granting publish on `mesh/node//**`, `mesh/service/*/.server/`, and + /// `mesh/service/*/.client/`, and subscribe on `mesh/**`, rooted at `/`. pub token: String, /// When the token expires, unix seconds. Refresh before then. #[serde_as(as = "kio::clock::serde::UnixSeconds")] diff --git a/rs/moq-crypto/README.md b/rs/moq-crypto/README.md index 1198deb20bd..9b49a739efc 100644 --- a/rs/moq-crypto/README.md +++ b/rs/moq-crypto/README.md @@ -54,7 +54,7 @@ the instance of the route that serves the broadcast, which the route mints fresh ```rust let key = SecretKey::load_or_generate("/var/lib/moq/endpoint.key")?; -let path = moq_net::Path::new(&format!("mesh/{}/agent", key.public()))?; +let path = moq_net::Path::new(&format!("mesh/node/{}/agent", key.public()))?; let route = origin.route(&path, RouteOptions::hidden())?; let signed = broadcast::Producer::new(route.broadcast().clone(), key, path, route.instance()); let messages = signed.create_track("messages", None)?; diff --git a/rs/moq-crypto/src/sign/tests.rs b/rs/moq-crypto/src/sign/tests.rs index 8c67bf4e193..afaedcf2b48 100644 --- a/rs/moq-crypto/src/sign/tests.rs +++ b/rs/moq-crypto/src/sign/tests.rs @@ -342,7 +342,7 @@ async fn broadcast_under_another_key_is_refused() { let impostor = SecretKey::generate(); let victim = SecretKey::generate(); // The impostor publishes at the victim's path, signing with its own key. - let published = publish(&impostor, &format!("mesh/{}/ssh", victim.public())); + let published = publish(&impostor, &format!("mesh/node/{}/ssh", victim.public())); let track = published.signed.create_track("stream", None).unwrap(); let consumer = published.consume(victim.public()).await; let mut subscribed = subscribe(&consumer, "stream").await; @@ -471,7 +471,7 @@ fn sign_interop() { let mut seed = Zeroizing::new([0u8; 32]); rind::rand::fill(seed.as_mut()).unwrap(); let key = SecretKey::from_seed(&seed); - let path = moq_net::Path::new(&format!("mesh/{}/agent", key.public())).unwrap(); + let path = moq_net::Path::new(&format!("mesh/node/{}/agent", key.public())).unwrap(); let instance = moq_net::Instance::random(); let payloads: [&[u8]; 3] = [b"zero", b"", &[0xff; 300]];