diff --git a/quest/m3/mesh/README.md b/quest/m3/mesh/README.md index 13a97522f32..42301df4952 100644 --- a/quest/m3/mesh/README.md +++ b/quest/m3/mesh/README.md @@ -50,6 +50,12 @@ Decided 2026-10-25 with the maintainer (planning interview), still in force: process declares fresh. - Addressing is announcement: each node publishes under `mesh//...`, and reaching an ID is subscribing there. There is no separate directory. +- Certificates can stand in for the token (decided 2026-11-07, maintainer, + Kixel's planning): a downstream mesh that must admit and evict devices + with no internet issues long-lived certificates from its own signers, and + [certificate credentials](/quest/m3/mesh/cert-credentials.md) checks them + against a trust store it supplies. The coordinator's token stays the + default for `moq auth`. - The token is the binding: enrollment proves the device key, then the coordinator issues a grant to publish `mesh//**` and subscribe `mesh/**`, plus publish on its own [socket](/doc/concept/socket.md) @@ -97,6 +103,7 @@ the third, and survives a relay restart. - [Endpoint API](/quest/m3/mesh/endpoint.md) - an iroh-shaped `Endpoint` that connects to an endpoint ID and service and accepts byte streams - [Mesh relay node](/quest/m3/mesh/node.md) - a relay node enrolls into a mesh, dials its relays, and admits only enrolled LAN peers - [Mesh enrollment is bounded and revocation takes effect](/quest/m3/mesh/device-bounds.md) - a reusable key enrolls a bounded number of devices and a revoked device loses access within a bounded time +- [Certificate credentials](/quest/m3/mesh/cert-credentials.md) - a certificate chain and a proof signature stand in for a JWT, checked against a trust store the application swaps live - [Address hints](/quest/m3/mesh/addr.md) - nodes publish their addresses on mesh tracks and dial each other directly where mDNS cannot find them - [Sparse overlay](/quest/m3/mesh/overlay.md) - each node keeps about log N deterministic direct links, forwards for the rest, and falls back to relays across a partition - [JS mesh enrollment client](/quest/m3/mesh/js-enroll.md) - `@moq/auth` enrolls and refreshes from JS like `moq_auth::mesh::Client` diff --git a/quest/m3/mesh/cert-credentials.md b/quest/m3/mesh/cert-credentials.md new file mode 100644 index 00000000000..1108e7237d5 --- /dev/null +++ b/quest/m3/mesh/cert-credentials.md @@ -0,0 +1,59 @@ +# [M] Certificate credentials + +## Goal + +A client can present an X.509 certificate chain over its Ed25519 key in place +of a JWT: in the `jwt` query, as a moq-transport SETUP token, and on every +transport, browsers included. The credential is the chain plus a proof +signature over the relay's host name, the dialed path, and the current time, +so a captured chain alone admits nothing. `moq-auth` parses and verifies it +against a trust store the embedding application supplies and swaps at +runtime: its anchors, and a check for whether a certificate is revoked. A +relay or node using that store refuses a chain that fails it, and closes +sessions it admitted earlier once their certificate is revoked or the anchors +change, at its next re-check. The application turns a verified chain into a +grant, the way in-process admissions already decide. `moq_auth::mesh::Client` +can present such a credential, and `@moq/auth` builds one from a +non-extractable WebCrypto Ed25519 key. + +## Plan + +Decided 2026-11-07 (maintainer, Kixel's `/quest-plan`): a mesh whose devices +must admit and evict each other with no internet needs credentials that last +longer than a coordinator token and can be checked offline, so Kixel moved its +devices from coordinator-minted JWTs to 30-day certificates from the mesh's +own signers. Presenting the certificate as the token, rather than over mTLS, +gives one path that also crosses relays that accept only their own cluster's +client certificates, WebSocket fallbacks, and browsers, which cannot present +client certificates over WebTransport. The signer log, revocation set, and +their sync stay in Kixel; this quest is the generic format and hook. + +- Verify chains with webpki. Name constraints work only on dNSName (webpki + rejects URI constraints and lacks directoryName), so document scopes + carried as DNS names. +- The trust store is a handle the application updates, not a callback per + connection. Re-check live sessions on the relay's existing `--revalidate` + cadence. +- The time-window proof comes first. Its replay window (a relay that saw a + credential could reuse it at the same host within the skew) closes with the + [challenge proof](/quest/m4/cert-challenge.md). Settle the skew and the + signed encoding before coding, and record them in `doc/bin/relay/auth.md`. +- Browsers: WebCrypto Ed25519 keys sign in current Chrome, Firefox, and + Safari; confirm it before relying on it, and fail loud where it is missing. +- Overlaps [moq-dev/moq#8149](https://github.com/moq-dev/moq/pull/8149)'s + bounded revocation for `moq auth`'s own mesh coordinator, which keeps + JWTs; this quest does not change that coordinator's tokens. + +Tests: a valid chain admits; a revoked or unanchored one, a proof for another +host or path, and a stale proof are refused; a session admitted before its +certificate is revoked closes on the next re-check; swapping the anchors +applies without a restart; a JS client presents a credential from a WebCrypto +key and a Rust relay admits it. + +Public API: new credential types in `moq-auth` and `@moq/auth`, and a trust +store handle on the relay. Wire: a new credential form wherever a JWT is +accepted. + +## Required + +- [Mesh relay node](/quest/m3/mesh/node.md) - the node that checks these credentials for its LAN peers diff --git a/quest/m3/mesh/node.md b/quest/m3/mesh/node.md index ccc3b88c3dc..9b296129849 100644 --- a/quest/m3/mesh/node.md +++ b/quest/m3/mesh/node.md @@ -23,6 +23,10 @@ CLI verbs, service install, and UI moved to Kixel. Carried over from it: `doc/bin/relay/auth.md#mesh-enrollment`. Pass the hostname as the default name. - Nothing is served unless the embedding application names it. +- A LAN peer proves its enrollment with the coordinator token, or with a + [certificate credential](/quest/m3/mesh/cert-credentials.md) when the + embedding application supplies a trust store (decided 2026-11-07, + maintainer). Tests in network namespaces: two relay nodes enroll through `moq auth`, take the LAN link when they share a segment and the relay path otherwise, refuse diff --git a/quest/m4/README.md b/quest/m4/README.md index 217bbd487ae..bf915752153 100644 --- a/quest/m4/README.md +++ b/quest/m4/README.md @@ -23,6 +23,7 @@ deleted. - [Weekly mutation testing on critical modules](/quest/m4/mutants.md) - cargo-mutants runs weekly on moq-auth and moq-net's permission, resume, and expiry code - [P2P](/quest/m4/p2p/README.md) - application-selected peer sessions use shared priorities, routing, and same-epoch handover - [moq-auth drops the unused peer grant API](/quest/m4/auth-drop-peer-grant.md) - P2P trusts its peers, so `PeerGrant` and its `KeySet` methods go +- [Challenge proof for certificate credentials](/quest/m4/cert-challenge.md) - a relay can require a signed nonce, so a certificate credential replayed within its time window admits nothing - [Benchmark sources](/quest/m4/bench-sources.md) - every measuring nightly benchmark feeds the regression table, and none is a smoke run - [HLS and DASH browser playback](/quest/m4/hls-player-test.md) - hls.js and dash.js play, reload, switch, and survive reconfiguration nightly - [Cache fair share](/quest/m4/cache-fairness.md) - one tenant cannot crowd another out of the relay's shared group cache diff --git a/quest/m4/cert-challenge.md b/quest/m4/cert-challenge.md new file mode 100644 index 00000000000..99bdf521aa4 --- /dev/null +++ b/quest/m4/cert-challenge.md @@ -0,0 +1,28 @@ +# [S] Challenge proof for certificate credentials + +## Goal + +A relay can ask a client presenting a [certificate credential](/quest/m3/mesh/cert-credentials.md) +to sign a fresh nonce instead of a timestamp, so a credential replayed within +the time window admits nothing. Clients that support it answer the +challenge; a relay configured to require it refuses time-window proofs. + +## Plan + +Decided 2026-11-07 (maintainer, Kixel's `/quest-plan`: "plan the challenge, +but do the simple thing first"): certificate credentials ship with a +time-window proof, and this closes its replay window later. Settle where the +nonce rides (SETUP parameters on moq-transport and moq-lite, and what a +WebSocket or HTTP admission does) and what one extra round trip costs a +connect, measured, before coding. + +Tests: a replayed time-window proof is refused when the relay requires the +challenge; a client signs the nonce and is admitted; a mismatched nonce is +refused. + +Public API: a challenge option on the relay and the clients. Wire: a nonce +exchanged during setup. + +## Required + +- [Certificate credentials](/quest/m3/mesh/cert-credentials.md) - the credential this hardens