From 678173b36138622e257c4ae03c158e58ad7851c9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 29 Oct 2026 23:56:47 -0700 Subject: [PATCH 1/9] chore(quest): claim quest/m2/mesh/enroll.md Quest-Claim: ce1b51fe94cf9fa2 From 0ffe09922953cb570f7c97c9b4bdd14b72c2998f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 06:54:48 -0700 Subject: [PATCH 2/9] feat(auth): mesh enrollment in moq auth serve A device proves its Ed25519 endpoint key against a fresh, coordinator-bound challenge and receives relay URLs plus a JWT publishing mesh//** and subscribing mesh/**, by enrollment key or RFC 8628 device grant, and refreshes it by proving the key again until revoked. - moq_auth::mesh: the JSON contract, Coordinator (serve), Client (client) - moq auth serve --mesh-url/--mesh-listen/--mesh-key/--mesh-relay/--mesh-state - moq auth mesh create-key|keys|revoke-key|devices|revoke|pending|approve|deny - Closes the enrollment quest Co-Authored-By: Claude Opus 5.5 --- doc/bin/relay/auth.md | 35 + doc/lib/rs/moq-auth.md | 1 + quest/m2/mesh/README.md | 1 - quest/m2/mesh/daemon.md | 4 +- quest/m2/mesh/dns.md | 3 +- quest/m2/mesh/enroll.md | 30 - rs/moq-auth/Cargo.toml | 2 +- rs/moq-auth/src/error.rs | 8 + rs/moq-auth/src/fs.rs | 4 +- rs/moq-auth/src/lib.rs | 1 + rs/moq-auth/src/mesh/client.rs | 179 +++++ rs/moq-auth/src/mesh/contract_tests.rs | 243 +++++++ rs/moq-auth/src/mesh/coordinator.rs | 936 +++++++++++++++++++++++++ rs/moq-auth/src/mesh/mod.rs | 415 +++++++++++ rs/moq-auth/src/serve.rs | 18 +- rs/moq-cli/src/auth.rs | 285 +++++++- 16 files changed, 2110 insertions(+), 55 deletions(-) delete mode 100644 quest/m2/mesh/enroll.md create mode 100644 rs/moq-auth/src/mesh/client.rs create mode 100644 rs/moq-auth/src/mesh/contract_tests.rs create mode 100644 rs/moq-auth/src/mesh/coordinator.rs create mode 100644 rs/moq-auth/src/mesh/mod.rs diff --git a/doc/bin/relay/auth.md b/doc/bin/relay/auth.md index de40300e735..527b27c9799 100644 --- a/doc/bin/relay/auth.md +++ b/doc/bin/relay/auth.md @@ -359,6 +359,41 @@ they gate admission without revoking. loopback address needs `--listen-public`: the server has no authentication of its own. See `moq auth serve --help` for the rest. +### Mesh enrollment + +`--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 +lowercase hex. It is verified like any other token, so the verifying keys +(`--key`, `--key-dir`, or `--key-set`) must include `--mesh-key`'s public half. + +```bash +moq auth serve --key-dir /etc/moq/keys \ + --mesh-url https://mesh.example.com --mesh-listen 127.0.0.1:4441 \ + --mesh-key /etc/moq/mesh.jwk --mesh-state /var/lib/moq/mesh.json \ + --mesh-relay https://relay.example.com +moq auth mesh create-key --tag robot --reusable --expires 7d # headless fleets +moq auth mesh approve BCDF-GHJK # a human's device grant +moq auth mesh revoke +``` + +Every request proves the endpoint key by signing a fresh, single-use +challenge bound to `--mesh-url`, so no token is issued for a key the caller +does not hold. A device joins with an enrollment key (single-use unless +`--reusable`; revoked or expired keys enroll nothing) or through an RFC 8628 +device grant the owner approves by its user code. It refreshes its token +two thirds of the way through `--mesh-token-ttl` (default 1h) by proving +the key again, so a revoked device is cut off within one token lifetime. A +revoked device cannot enroll again. Each enrollment and refresh also returns +every member's unique, DNS-safe name, defaulting to the device's hostname. + +The device-facing API on `--mesh-listen` is meant to be public behind a TLS +proxy, since devices refuse plain `http://` beyond loopback. The owner's +commands go to `--listen`, which stays private. A hosted coordinator implements +the same JSON contract, documented in +[`moq_auth::mesh`](https://docs.rs/moq-auth/latest/moq_auth/mesh/); it adds +no token claims. + ### Migrating from the relay flags The 0.14 relay's auth flags moved to `moq auth serve`, and the relay points diff --git a/doc/lib/rs/moq-auth.md b/doc/lib/rs/moq-auth.md index ab5ec626e1a..b80bd8411e3 100644 --- a/doc/lib/rs/moq-auth.md +++ b/doc/lib/rs/moq-auth.md @@ -18,6 +18,7 @@ accept loop that decides in process. - **Refusals.** `Refusal` carries a `refusal::Reason` (`Refused`, `Forbidden`, or `Expired`) and optional `root` and `tier`. An auth server returns it as JSON with HTTP 403; `Client` returns `Error::Refused(refusal)`. Legacy plain-text 401/403 bodies and unknown reason strings read as `Refused`. Set `root` only from a verified credential, never the dialed path. Embedded relay deciders pass the same shape in `auth::Error::Refused`. - **Client.** `Client` drives a lease against an auth server over `https://`, `unix://`, or loopback `http://`. It revalidates on cadence and retries through an outage until the grant expires, revokes on a 401, 403, or invalid grant, and reports `end` with the session's byte totals. - **Server** (feature `serve`). `serve::Server` is the reference auth server behind `moq auth serve`: JWTs from the query or the moq-transport SETUP token, certificate grants, anonymous rules, tiers, and session caps. `Server::router` mounts it in your own axum service. +- **Mesh enrollment.** `mesh` holds the [enrollment contract](/bin/relay/auth#mesh-enrollment): a device proves its Ed25519 endpoint key against a fresh challenge and receives relay URLs and a scoped token. `mesh::Client` (feature `client`) enrolls by key or device grant and renews before expiry; `mesh::Coordinator` (feature `serve`) answers it. - **Keys and claims.** Generate HMAC, RSA, ECDSA, or EdDSA keys as JWKs, sign `Claims` (`root`, `publish`, `subscribe`, `exp`), and verify them. `Claims::authorize(path)` scopes verified claims to the path a client dialed, exactly as `moq auth serve` does. Roles hold path pattern unions directly. ```bash diff --git a/quest/m2/mesh/README.md b/quest/m2/mesh/README.md index 14bd6da1f24..d580d7d7286 100644 --- a/quest/m2/mesh/README.md +++ b/quest/m2/mesh/README.md @@ -61,7 +61,6 @@ relay path to the third, surviving a relay restart. - [Outbound federation](/quest/m1/cluster-routing/federation.md) - a local relay dials its relays and prefers LAN peers - [Byte streams](/quest/m2/stream/README.md) - lossless TCP-level streams over MoQ -- [Enrollment](/quest/m2/mesh/enroll.md) - a device proves its key and gets a relay URL and a scoped token, by device grant or a pre-authorized key - [Signed broadcasts](/quest/m2/mesh/sign.md) - endpoint keys, per-frame signatures, and per-broadcast protection levels - [Endpoint API](/quest/m2/mesh/endpoint.md) - an iroh-shaped `Endpoint` that connects to an endpoint ID and service and accepts byte streams - [Daemon](/quest/m2/mesh/daemon.md) - `moq mesh up`, `serve`, `pipe`, and `install`, with SSH by ID on two hosts diff --git a/quest/m2/mesh/daemon.md b/quest/m2/mesh/daemon.md index 3130ec2de5b..40b3979bfd9 100644 --- a/quest/m2/mesh/daemon.md +++ b/quest/m2/mesh/daemon.md @@ -22,10 +22,12 @@ the epic's first shippable outcome. configure. - Nothing is served unless `serve` names it. A restart keeps the endpoint key and enrollment, so a node never re-enrolls on its own. +- Enroll and renew with `moq_auth::mesh::Client`, signing with the endpoint key + through its `Signer` trait, and pass the hostname as the default name. The + contract is in `doc/bin/relay/auth.md#mesh-enrollment`. - Update `doc/bin/cli.md` inline. ## Required - [Outbound federation](/quest/m1/cluster-routing/federation.md) - upstream links and LAN preference -- [Enrollment](/quest/m2/mesh/enroll.md) - the relay URLs and token the daemon runs on - [Endpoint API](/quest/m2/mesh/endpoint.md) - the streams `serve` and `pipe` use diff --git a/quest/m2/mesh/dns.md b/quest/m2/mesh/dns.md index 89f8a282725..ae64f55e4ce 100644 --- a/quest/m2/mesh/dns.md +++ b/quest/m2/mesh/dns.md @@ -9,7 +9,8 @@ that peer's served ports, forwarding each connection as a byte stream. ## Plan Decided 2026-10-25 (maintainer): loopback addresses per peer, no TUN device. -Names come from [enrollment](/quest/m2/mesh/enroll.md). Settle how the +Names come from enrollment: every `moq_auth::mesh::Enrollment` lists each +member's unique, DNS-safe name, refreshed with the token. Settle how the resolver is installed per OS (split DNS through systemd-resolved, macOS `/etc/resolver`) and how the loopback range is chosen and kept stable across restarts, and record both here. `install` sets it up; uninstalling removes it. diff --git a/quest/m2/mesh/enroll.md b/quest/m2/mesh/enroll.md deleted file mode 100644 index 8b2de4069aa..00000000000 --- a/quest/m2/mesh/enroll.md +++ /dev/null @@ -1,30 +0,0 @@ -# [M] Enrollment - -## Goal - -A device with an endpoint key joins a mesh and receives the relay URLs to dial -and a token granting publish on `mesh//**` and subscribe on `mesh/**`, -refreshed before it expires. A human enrolls a device through the OAuth device -grant (RFC 8628); a fleet of robots enrolls headlessly with a pre-authorized -enrollment key. `moq auth` serves the contract for self-hosters. - -## Plan - -See the [epic](/quest/m2/mesh/README.md) for the decisions. - -- Enrollment proves possession of the endpoint key against a fresh server - challenge, so a token is never issued for a key the caller does not hold. -- Enrollment keys are created by the mesh owner, may carry tags and an expiry, - and are single-use or reusable; a revoked key enrolls nothing new. -- Revoking a device makes its next refresh fail; the relay refuses the - expired token as it does today. -- A device has a name (defaulting to its hostname) used by - [MagicDNS](/quest/m2/mesh/dns.md); the contract returns every member's name - through the announcement metadata or a mesh-scoped track, settled here. -- Write the contract as a doc page section in the [guide](/quest/m2/mesh/guide.md) - so a hosted service can implement it. Report the public API and any token - claim it adds. - -Tests: device grant approve and deny, a reused enrollment key refused when -single-use, a challenge signed by the wrong key refused, refresh, and -revocation. diff --git a/rs/moq-auth/Cargo.toml b/rs/moq-auth/Cargo.toml index 90e4990e932..054ecd5e76e 100644 --- a/rs/moq-auth/Cargo.toml +++ b/rs/moq-auth/Cargo.toml @@ -37,7 +37,7 @@ serde_with = { workspace = true, features = ["base64"] } thiserror = { workspace = true } tokio = { workspace = true, features = ["fs", "macros", "rt", "time", "sync"], optional = true } tracing = { workspace = true, optional = true } -url = { workspace = true } +url = { workspace = true, features = ["serde"] } [dev-dependencies] anyhow = { workspace = true } diff --git a/rs/moq-auth/src/error.rs b/rs/moq-auth/src/error.rs index 60e3f608f7d..eb6eafb9ea7 100644 --- a/rs/moq-auth/src/error.rs +++ b/rs/moq-auth/src/error.rs @@ -203,6 +203,14 @@ pub enum Error { /// Fetching a remote JWKS failed. #[error("{0}")] Other(String), + + /// A mesh coordinator refused the request. + #[error("mesh coordinator refused: {0}")] + Mesh(#[from] crate::mesh::ErrorReply), + + /// The mesh coordinator's state file could not be read, parsed, or written. + #[error("mesh state: {0}")] + MeshState(String), } // Dependency errors are flattened to their message so their crates stay out of this crate's diff --git a/rs/moq-auth/src/fs.rs b/rs/moq-auth/src/fs.rs index 9ea7bcff02b..18ed78b35b2 100644 --- a/rs/moq-auth/src/fs.rs +++ b/rs/moq-auth/src/fs.rs @@ -20,7 +20,7 @@ pub(crate) fn write(path: &Path, contents: &str, private: bool) -> io::Result<() } #[cfg(unix)] -fn write_private(path: &Path, contents: &str) -> io::Result<()> { +pub(crate) fn write_private(path: &Path, contents: &str) -> io::Result<()> { use std::io::Write; use std::os::unix::fs::{OpenOptionsExt, PermissionsExt}; @@ -40,6 +40,6 @@ fn write_private(path: &Path, contents: &str) -> io::Result<()> { /// Windows has no cheap equivalent of the Unix mode bits, so the file inherits the directory's ACL. #[cfg(not(unix))] -fn write_private(path: &Path, contents: &str) -> io::Result<()> { +pub(crate) fn write_private(path: &Path, contents: &str) -> io::Result<()> { std::fs::write(path, contents) } diff --git a/rs/moq-auth/src/lib.rs b/rs/moq-auth/src/lib.rs index b238ed38c39..80b84dab3d7 100644 --- a/rs/moq-auth/src/lib.rs +++ b/rs/moq-auth/src/lib.rs @@ -32,6 +32,7 @@ mod set; mod wire; pub mod lease; +pub mod mesh; pub mod refusal; pub use refusal::Refusal; #[cfg(feature = "serve")] diff --git a/rs/moq-auth/src/mesh/client.rs b/rs/moq-auth/src/mesh/client.rs new file mode 100644 index 00000000000..32d982d2aa9 --- /dev/null +++ b/rs/moq-auth/src/mesh/client.rs @@ -0,0 +1,179 @@ +//! The device side of the contract: enroll, then keep the token fresh. + +use std::sync::Arc; +use std::time::Duration; + +use url::Url; + +use super::{ + Challenge, DeviceAuthorization, DeviceRequest, DeviceTokenRequest, EnrollRequest, Enrollment, ErrorCode, + ErrorReply, Proof, Signer, +}; +use crate::Error; + +/// Every request is bounded so a hung coordinator fails rather than parks the device. +const TIMEOUT: Duration = Duration::from_secs(10); + +/// The largest reply read from the coordinator; a mesh's member list fits easily. +const MAX_REPLY: usize = 4 << 20; + +/// How much a `slow_down` adds to the polling interval (RFC 8628 §3.5). +const SLOW_DOWN: Duration = Duration::from_secs(5); + +/// The longest wait between refresh attempts while the coordinator is unreachable. +const MAX_BACKOFF: Duration = Duration::from_secs(60); + +/// A device's client for one coordinator, proving `signer`'s key on every request that +/// needs it. +#[derive(Clone)] +pub struct Client { + http: reqwest::Client, + base: Url, + signer: Arc, +} + +impl Client { + /// A client for the coordinator at `base`, the URL the contract's paths hang off. + /// + /// `https://` is required, except `http://` to a loopback host, since the token rides + /// the reply. + pub fn new(base: Url, signer: Arc) -> crate::Result { + let loopback = match base.host() { + Some(url::Host::Ipv4(ip)) => ip.is_loopback(), + Some(url::Host::Ipv6(ip)) => ip.is_loopback(), + Some(url::Host::Domain(host)) => host == "localhost", + None => false, + }; + match base.scheme() { + "https" => {} + "http" if loopback => {} + "http" => return Err(Error::InsecureUrl(base.to_string())), + _ => return Err(Error::InvalidUrl(base.to_string())), + } + // A redirect would resend a proof or device code to wherever it points. + let http = reqwest::Client::builder() + .redirect(reqwest::redirect::Policy::none()) + .timeout(TIMEOUT) + .build()?; + Ok(Self { http, base, signer }) + } + + /// Join with a pre-authorized enrollment key, asking for `name`. + 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), + }; + self.post("enroll", &request).await + } + + /// Start a device grant, asking for `name`. Show the human its `user_code` and + /// `verification_uri`, then [`poll`](Self::poll). + pub async fn device(&self, name: Option<&str>) -> crate::Result { + let proof = self.proof().await?; + let request = DeviceRequest { + proof, + name: name.map(Into::into), + }; + self.post("device", &request).await + } + + /// Wait for a human to approve the device grant, polling at its interval. Fails with + /// [`ErrorCode::AccessDenied`] when denied and [`ErrorCode::ExpiredToken`] when it + /// times out. + pub async fn poll(&self, authorization: &DeviceAuthorization) -> crate::Result { + let mut interval = Duration::from_secs(authorization.interval); + let request = DeviceTokenRequest { + device_code: authorization.device_code.clone(), + }; + loop { + moq_clock::sleep(interval).await; + match self.post("device/token", &request).await { + Err(Error::Mesh(ErrorReply { + error: ErrorCode::AuthorizationPending, + .. + })) => {} + Err(Error::Mesh(ErrorReply { + error: ErrorCode::SlowDown, + .. + })) => interval += SLOW_DOWN, + other => return other, + } + } + } + + /// Prove the key again for a fresh token. Fails with [`ErrorCode::AccessDenied`] once + /// the device is revoked. + pub async fn refresh(&self) -> crate::Result { + let proof = self.proof().await?; + self.post("refresh", &proof).await + } + + /// Wait until `current` is two thirds through its remaining life, then refresh it, + /// retrying through an outage until it expires. A refusal is returned at once, so a + /// revoked device stops rather than retrying. + pub async fn renew(&self, current: &Enrollment) -> crate::Result { + let remaining = || { + current + .expires + .checked_duration_since(moq_clock::wall()) + .unwrap_or_default() + }; + moq_clock::sleep(remaining() * 2 / 3).await; + + let mut backoff = Duration::from_secs(1); + loop { + match self.refresh().await { + Err(Error::Mesh(reply)) if reply.error != ErrorCode::ServerError => return Err(Error::Mesh(reply)), + Ok(enrollment) => return Ok(enrollment), + Err(err) if remaining().is_zero() => return Err(err), + Err(err) => { + tracing::warn!(%err, "mesh refresh failed; retrying"); + moq_clock::sleep(backoff.min(remaining())).await; + backoff = (backoff * 2).min(MAX_BACKOFF); + } + } + } + } + + async fn proof(&self) -> crate::Result { + let challenge: Challenge = self.post("challenge", &serde_json::Value::Null).await?; + Ok(Proof::sign(self.signer.as_ref(), &self.base, challenge.challenge)) + } + + async fn post( + &self, + path: &str, + body: &T, + ) -> crate::Result { + let mut url = self.base.clone(); + let joined = format!("{}/{path}", url.path().trim_end_matches('/')); + url.set_path(&joined); + + let request = self.http.post(url); + let request = match serde_json::to_value(body)? { + serde_json::Value::Null => request, + body => request.json(&body), + }; + let mut response = request.send().await?; + let status = response.status(); + + let mut bytes = Vec::new(); + while let Some(chunk) = response.chunk().await? { + if bytes.len() + chunk.len() > MAX_REPLY { + return Err(Error::Unavailable("the coordinator's reply is too large".into())); + } + bytes.extend_from_slice(&chunk); + } + + if status.is_success() { + return Ok(serde_json::from_slice(&bytes)?); + } + match serde_json::from_slice::(&bytes) { + Ok(reply) => Err(Error::Mesh(reply)), + Err(_) => Err(Error::Unavailable(format!("the coordinator answered {status}"))), + } + } +} diff --git a/rs/moq-auth/src/mesh/contract_tests.rs b/rs/moq-auth/src/mesh/contract_tests.rs new file mode 100644 index 00000000000..ab7794d34e7 --- /dev/null +++ b/rs/moq-auth/src/mesh/contract_tests.rs @@ -0,0 +1,243 @@ +//! The contract end to end: a [`Client`] against a [`Coordinator`] over HTTP. + +use std::sync::Arc; +use std::time::Duration; + +use aws_lc_rs::signature::Ed25519KeyPair; + +use super::*; +use crate::{Algorithm, Error, Key, KeyId}; + +struct Mesh { + coordinator: Coordinator, + base: url::Url, + key: Key, +} + +impl Mesh { + async fn new() -> Self { + Self::with_ttl(Duration::from_secs(3600)).await + } + + async fn with_ttl(ttl: Duration) -> Self { + let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let base: url::Url = format!("http://{}/mesh", listener.local_addr().unwrap()) + .parse() + .unwrap(); + let key = Key::generate(Algorithm::HS256, Some(KeyId::decode("mesh").unwrap())).unwrap(); + let mut config = Config::new(base.clone(), key.clone()); + config.relays = vec!["https://relay.example".parse().unwrap()]; + config.device_interval = Duration::ZERO; + config.token_ttl = ttl; + let coordinator = Coordinator::new(config).unwrap(); + let router = axum::Router::new().nest("/mesh", coordinator.router()); + tokio::spawn(async move { axum::serve(listener, router).await }); + Self { coordinator, base, key } + } + + fn device(&self) -> Client { + let signer = Arc::new(Ed25519KeyPair::generate().unwrap()); + Client::new(self.base.clone(), signer).unwrap() + } + + fn key(&self, reusable: bool) -> String { + let new = NewKey { + reusable, + tags: vec!["robot".into()], + ..Default::default() + }; + self.coordinator.create_key(&new).unwrap().key.unwrap() + } + + /// The code a refusal carries. + fn refused(err: Error) -> ErrorCode { + match err { + Error::Mesh(reply) => reply.error, + other => panic!("expected a refusal, got {other}"), + } + } +} + +#[tokio::test] +async fn an_enrollment_key_grants_the_endpoints_subtree() { + let mesh = Mesh::new().await; + let device = mesh.device(); + let enrollment = device.enroll(&mesh.key(false), Some("Robot 1")).await.unwrap(); + + assert_eq!(enrollment.name, "robot-1"); + assert_eq!( + enrollment.relays, + vec!["https://relay.example".parse::().unwrap()] + ); + assert_eq!(enrollment.members.len(), 1); + assert_eq!(enrollment.members[0].tags, vec!["robot".to_string()]); + + 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()); + assert!(claims.authorize("elsewhere").is_err()); +} + +#[tokio::test] +async fn a_single_use_key_enrolls_once() { + let mesh = Mesh::new().await; + let key = mesh.key(false); + mesh.device().enroll(&key, None).await.unwrap(); + let err = mesh.device().enroll(&key, None).await.unwrap_err(); + assert_eq!(Mesh::refused(err), ErrorCode::InvalidGrant); + + let reusable = mesh.key(true); + let first = mesh.device().enroll(&reusable, Some("bot")).await.unwrap(); + let second = mesh.device().enroll(&reusable, Some("bot")).await.unwrap(); + assert_eq!(first.name, "bot"); + assert_eq!(second.name, "bot-2"); + assert_eq!(second.members.len(), 3); +} + +#[tokio::test] +async fn a_revoked_or_unknown_key_enrolls_nothing() { + let mesh = Mesh::new().await; + let key = mesh.key(true); + let id = key.split_once('.').unwrap().0; + assert!(mesh.coordinator.revoke_key(id).unwrap()); + let err = mesh.device().enroll(&key, None).await.unwrap_err(); + assert_eq!(Mesh::refused(err), ErrorCode::InvalidGrant); + + let err = mesh.device().enroll(&format!("{id}.wrong"), None).await.unwrap_err(); + assert_eq!(Mesh::refused(err), ErrorCode::InvalidGrant); +} + +#[tokio::test] +async fn a_proof_from_the_wrong_key_is_refused() { + let mesh = Mesh::new().await; + let challenge = mesh.coordinator.challenge(); + let holder = Ed25519KeyPair::generate().unwrap(); + let victim = Ed25519KeyPair::generate().unwrap(); + let mut proof = Proof::sign(&holder, &mesh.base, challenge.challenge); + proof.endpoint = victim.endpoint(); + let request = EnrollRequest { + proof, + key: mesh.key(true), + name: None, + }; + assert_eq!( + mesh.coordinator.enroll(&request).unwrap_err().error, + ErrorCode::InvalidSignature + ); + + // The challenge is spent, so even the honest retry needs a new one. + let mut request = request; + request.proof = Proof::sign(&holder, &mesh.base, request.proof.challenge); + assert_eq!( + mesh.coordinator.enroll(&request).unwrap_err().error, + ErrorCode::InvalidChallenge + ); + + // A proof made for another coordinator does not verify here. + let challenge = mesh.coordinator.challenge(); + request.proof = Proof::sign( + &holder, + &"https://other.example/mesh".parse().unwrap(), + challenge.challenge, + ); + assert_eq!( + mesh.coordinator.enroll(&request).unwrap_err().error, + ErrorCode::InvalidSignature + ); +} + +#[tokio::test] +async fn a_device_grant_waits_for_approval() { + let mesh = Mesh::new().await; + let device = mesh.device(); + let authorization = device.device(Some("laptop")).await.unwrap(); + assert_eq!(authorization.verification_uri.path(), "/mesh/device"); + + let pending = mesh.coordinator.pending(); + assert_eq!(pending.len(), 1); + assert_eq!(pending[0].user_code, authorization.user_code); + + let poll = tokio::spawn({ + let device = device.clone(); + let authorization = authorization.clone(); + async move { device.poll(&authorization).await } + }); + moq_clock::sleep(Duration::from_millis(50)).await; + assert!(!poll.is_finished()); + + assert!(mesh.coordinator.decide(&authorization.user_code.to_lowercase(), true)); + let enrollment = poll.await.unwrap().unwrap(); + assert_eq!(enrollment.name, "laptop"); + assert!(mesh.coordinator.pending().is_empty()); + + // The device code is spent once it is exchanged. + let err = device.poll(&authorization).await.unwrap_err(); + assert_eq!(Mesh::refused(err), ErrorCode::ExpiredToken); +} + +#[tokio::test] +async fn a_denied_device_grant_enrolls_nothing() { + let mesh = Mesh::new().await; + let device = mesh.device(); + let authorization = device.device(None).await.unwrap(); + assert!(mesh.coordinator.decide(&authorization.user_code, false)); + assert!(!mesh.coordinator.decide(&authorization.user_code, true)); + let err = device.poll(&authorization).await.unwrap_err(); + assert_eq!(Mesh::refused(err), ErrorCode::AccessDenied); + assert!(mesh.coordinator.devices().is_empty()); +} + +#[tokio::test] +async fn refresh_issues_a_new_token_until_revoked() { + let mesh = Mesh::new().await; + let device = mesh.device(); + + // Refreshing before enrolling proves a key the mesh does not know. + let err = device.refresh().await.unwrap_err(); + assert_eq!(Mesh::refused(err), ErrorCode::AccessDenied); + + let enrollment = device.enroll(&mesh.key(true), Some("pi")).await.unwrap(); + let refreshed = device.refresh().await.unwrap(); + assert_eq!(refreshed.name, "pi"); + assert!(mesh.key.verify(&refreshed.token).is_ok()); + + let id = enrollment.members[0].endpoint; + assert!(mesh.coordinator.revoke_device(id).unwrap()); + let err = device.refresh().await.unwrap_err(); + assert_eq!(Mesh::refused(err), ErrorCode::AccessDenied); + + // A reusable key cannot bring a revoked device back. + let err = device.enroll(&mesh.key(true), None).await.unwrap_err(); + assert_eq!(Mesh::refused(err), ErrorCode::AccessDenied); +} + +#[tokio::test] +async fn renew_refreshes_before_expiry() { + let mesh = Mesh::with_ttl(Duration::from_secs(3)).await; + let device = mesh.device(); + let enrollment = device.enroll(&mesh.key(true), None).await.unwrap(); + let renewed = device.renew(&enrollment).await.unwrap(); + assert!(moq_clock::wall() < enrollment.expires); + assert!(renewed.expires > enrollment.expires); +} + +#[tokio::test] +async fn a_malformed_body_is_an_oauth_error() { + let mesh = Mesh::new().await; + let url = format!("{}/enroll", mesh.base); + let response = reqwest::Client::new() + .post(url) + .header("content-type", "application/json") + .body("{}") + .send() + .await + .unwrap(); + assert_eq!(response.status(), reqwest::StatusCode::BAD_REQUEST); + let reply: ErrorReply = response.json().await.unwrap(); + assert_eq!(reply.error, ErrorCode::InvalidRequest); +} diff --git a/rs/moq-auth/src/mesh/coordinator.rs b/rs/moq-auth/src/mesh/coordinator.rs new file mode 100644 index 00000000000..4909f0171cf --- /dev/null +++ b/rs/moq-auth/src/mesh/coordinator.rs @@ -0,0 +1,936 @@ +//! The reference coordinator behind `moq auth serve --mesh-url`. +//! +//! [`Coordinator::router`] answers the device-facing contract; [`Coordinator::admin_router`] +//! is the owner's API, mounted on the auth server's own listener, which has no +//! authentication and stays on loopback. Enrollment keys and devices persist to a JSON +//! state file; challenges and pending device grants live in memory, so a restart only +//! makes a device fetch a new challenge or start its grant again. + +use std::collections::HashMap; +use std::path::PathBuf; +use std::sync::{Arc, Mutex}; +use std::time::Duration; + +use axum::extract::{Path, State}; +use axum::http::StatusCode; +use axum::response::{IntoResponse, Response}; +use axum::routing::{delete, get, post}; +use axum::{Json, Router}; +use moq_clock::Instant; +use serde::{Deserialize, Serialize}; +use serde_with::serde_as; + +use super::{ + CHALLENGE_LEN, Challenge, DeviceAuthorization, DeviceRequest, DeviceTokenRequest, EndpointId, EnrollRequest, + Enrollment, ErrorCode, ErrorReply, Member, Proof, +}; +use crate::{Claims, Key, Pattern}; + +/// How long a challenge stays valid. +const CHALLENGE_TTL: Duration = Duration::from_secs(60); + +/// The most challenges outstanding at once, so an unauthenticated caller cannot grow the +/// table without bound; the oldest is dropped first. +const MAX_CHALLENGES: usize = 4096; + +/// The most device grants pending at once, for the same reason. +const MAX_PENDING: usize = 256; + +/// The alphabet of a user code: no vowels, so a code spells no word, and no +/// look-alikes (RFC 8628 §6.1). +const USER_CODE_ALPHABET: &[u8] = b"BCDFGHJKLMNPQRSTVWXZ"; + +/// The longest a device name may be: one DNS label. +const MAX_NAME: usize = 63; + +/// What the coordinator issues, and where it keeps its state. +/// +/// `#[non_exhaustive]`, so build it with [`Config::new`] and set the fields. +#[derive(Clone, Debug)] +#[non_exhaustive] +pub struct Config { + /// The public base URL devices reach the contract at, which every proof is bound to. + pub url: url::Url, + /// The key that signs mesh tokens; the relays must verify it. + pub key: Key, + /// The relays an [`Enrollment`] tells a device to dial. + pub relays: Vec, + /// The JSON file enrollment keys and devices persist to; `None` keeps them in memory. + pub state: Option, + /// How long an issued token lasts. + pub token_ttl: Duration, + /// How long a device grant waits for a human. + pub device_ttl: Duration, + /// The seconds a device waits between device grant polls. + pub device_interval: Duration, +} + +impl Config { + /// A coordinator at `url` signing with `key`, with hour-long tokens, ten-minute device + /// grants polled every five seconds, no relays, and no state file. + pub fn new(url: url::Url, key: Key) -> Self { + Self { + url, + key, + relays: Vec::new(), + state: None, + token_ttl: Duration::from_secs(3600), + device_ttl: Duration::from_secs(600), + device_interval: Duration::from_secs(5), + } + } +} + +/// The state that survives a restart. +#[derive(Default, Serialize, Deserialize)] +struct Store { + #[serde(default)] + keys: Vec, + #[serde(default)] + devices: Vec, +} + +/// An enrollment key, holding only the SHA-256 of its secret. +#[serde_as] +#[derive(Clone, Serialize, Deserialize)] +struct StoredKey { + id: String, + /// Hex, so the file stays readable. + hash: String, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + tags: Vec, + #[serde_as(as = "Option")] + #[serde(default, skip_serializing_if = "Option::is_none")] + expires: Option, + reusable: bool, + #[serde(default)] + used: bool, + #[serde(default)] + revoked: bool, +} + +/// An enrolled device. A revoked one stays recorded so a reusable key cannot re-enroll it. +#[serde_as] +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[non_exhaustive] +pub struct Device { + /// Its endpoint ID. + pub endpoint: EndpointId, + /// Its unique, DNS-safe name. + pub name: String, + /// The tags of the enrollment key it joined with. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub tags: Vec, + /// When it first enrolled, unix seconds. + #[serde_as(as = "moq_clock::serde::UnixSeconds")] + pub enrolled: moq_clock::Wall, + /// Whether the owner revoked it; its next refresh fails. + #[serde(default)] + pub revoked: bool, +} + +/// An enrollment key as the owner sees it, without its secret. +#[serde_as] +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[non_exhaustive] +pub struct KeyInfo { + /// The ID the owner revokes it by. + pub id: String, + /// The tags every device it enrolls carries. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub tags: Vec, + /// When it stops enrolling, unix seconds. + #[serde_as(as = "Option")] + #[serde(default, skip_serializing_if = "Option::is_none")] + pub expires: Option, + /// Whether it enrolls more than one device. + pub reusable: bool, + /// Whether a single-use key has enrolled its device. + pub used: bool, + /// Whether the owner revoked it. + pub revoked: bool, + /// The key itself, returned only when it is created. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub key: Option, +} + +impl From<&StoredKey> for KeyInfo { + fn from(key: &StoredKey) -> Self { + Self { + id: key.id.clone(), + tags: key.tags.clone(), + expires: key.expires, + reusable: key.reusable, + used: key.used, + revoked: key.revoked, + key: None, + } + } +} + +/// `POST /mesh/keys` on the admin API: what the new enrollment key allows. +#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] +#[serde(default)] +#[non_exhaustive] +pub struct NewKey { + /// Tags every device it enrolls carries. + pub tags: Vec, + /// Seconds until it stops enrolling; `None` never expires. + pub expires_in: Option, + /// Whether it enrolls more than one device. + pub reusable: bool, +} + +/// A device grant waiting for a human, as the owner sees it. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[non_exhaustive] +pub struct PendingDevice { + /// The code the device shows its human. + pub user_code: String, + /// The endpoint the grant would enroll. + pub endpoint: EndpointId, + /// The name the device asked for. + pub name: Option, +} + +#[derive(Clone, Copy, PartialEq, Eq)] +enum Decision { + Waiting, + Approved, + Denied, +} + +struct Pending { + user_code: String, + endpoint: EndpointId, + name: Option, + expires: Instant, + polled: Option, + decision: Decision, +} + +#[derive(Default)] +struct Inner { + store: Store, + /// Outstanding challenges and when each was issued. + challenges: HashMap, Instant>, + /// Pending device grants, by the SHA-256 of their device code. + pending: HashMap, Pending>, +} + +/// The mesh coordinator: issues challenges, enrolls devices, and refreshes their tokens. +#[derive(Clone)] +pub struct Coordinator { + config: Arc, + inner: Arc>, +} + +type Reply = Result; + +impl Coordinator { + /// A coordinator for `config`, loading its state file if one exists. + pub fn new(config: Config) -> crate::Result { + let store = match &config.state { + Some(path) => match std::fs::read_to_string(path) { + Ok(json) => serde_json::from_str(&json).map_err(|err| crate::Error::MeshState(err.to_string()))?, + Err(err) if err.kind() == std::io::ErrorKind::NotFound => Store::default(), + Err(err) => return Err(crate::Error::MeshState(err.to_string())), + }, + None => Store::default(), + }; + Ok(Self { + config: Arc::new(config), + inner: Arc::new(Mutex::new(Inner { + store, + ..Default::default() + })), + }) + } + + /// Issue a fresh challenge. + pub fn challenge(&self) -> Challenge { + let challenge = random(CHALLENGE_LEN); + let mut inner = self.inner.lock().unwrap(); + let now = Instant::now(); + inner + .challenges + .retain(|_, issued| now.saturating_duration_since(*issued) < CHALLENGE_TTL); + if inner.challenges.len() >= MAX_CHALLENGES + && let Some(oldest) = inner + .challenges + .iter() + .min_by_key(|(_, issued)| **issued) + .map(|(challenge, _)| challenge.clone()) + { + inner.challenges.remove(&oldest); + } + inner.challenges.insert(challenge.clone(), now); + Challenge { + challenge, + expires: moq_clock::wall() + CHALLENGE_TTL, + } + } + + /// Enroll with an enrollment key. + pub fn enroll(&self, request: &EnrollRequest) -> Reply { + let mut inner = self.inner.lock().unwrap(); + self.check(&mut inner, &request.proof)?; + + let (id, secret) = request + .key + .split_once('.') + .ok_or_else(|| ErrorReply::new(ErrorCode::InvalidGrant, "unknown enrollment key"))?; + let hash = hex(&sha256(secret.as_bytes())); + let now = moq_clock::wall(); + let key = inner + .store + .keys + .iter() + .find(|key| key.id == id && constant_eq(key.hash.as_bytes(), hash.as_bytes())) + .ok_or_else(|| ErrorReply::new(ErrorCode::InvalidGrant, "unknown enrollment key"))?; + if key.revoked { + return Err(ErrorReply::new( + ErrorCode::InvalidGrant, + "the enrollment key is revoked", + )); + } + if key.expires.is_some_and(|expires| expires <= now) { + return Err(ErrorReply::new( + ErrorCode::InvalidGrant, + "the enrollment key has expired", + )); + } + if !key.reusable && key.used { + return Err(ErrorReply::new( + ErrorCode::InvalidGrant, + "the enrollment key was already used", + )); + } + let tags = key.tags.clone(); + let reusable = key.reusable; + let id = id.to_string(); + + let endpoint = request.proof.endpoint; + self.admit(&mut inner, endpoint, request.name.as_deref(), tags)?; + if !reusable && let Some(key) = inner.store.keys.iter_mut().find(|key| key.id == id) { + key.used = true; + } + self.save(&inner)?; + self.issue(&inner, endpoint) + } + + /// Start a device grant for a human to approve. + pub fn device(&self, request: &DeviceRequest) -> Reply { + let mut inner = self.inner.lock().unwrap(); + self.check(&mut inner, &request.proof)?; + self.refuse_revoked(&inner, request.proof.endpoint)?; + + let now = Instant::now(); + inner.pending.retain(|_, pending| pending.expires > now); + if inner.pending.len() >= MAX_PENDING { + return Err(ErrorReply::new( + ErrorCode::SlowDown, + "too many device grants are pending; try again later", + )); + } + + let device_code = encode(&random(32)); + let user_code = loop { + let code = user_code(); + if !inner.pending.values().any(|pending| pending.user_code == code) { + break code; + } + }; + inner.pending.insert( + sha256(device_code.as_bytes()), + Pending { + user_code: user_code.clone(), + endpoint: request.proof.endpoint, + name: request.name.clone(), + expires: now + self.config.device_ttl, + polled: None, + decision: Decision::Waiting, + }, + ); + + Ok(DeviceAuthorization { + device_code, + user_code, + verification_uri: self.verification_uri(), + expires_in: self.config.device_ttl.as_secs(), + interval: self.config.device_interval.as_secs(), + }) + } + + /// Poll a device grant: the enrollment once a human approves, a refusal until then. + pub fn device_token(&self, request: &DeviceTokenRequest) -> Reply { + let mut inner = self.inner.lock().unwrap(); + let hash = sha256(request.device_code.as_bytes()); + let now = Instant::now(); + let pending = inner + .pending + .get_mut(&hash) + .ok_or_else(|| ErrorReply::new(ErrorCode::ExpiredToken, "unknown or expired device code"))?; + if pending.expires <= now { + inner.pending.remove(&hash); + return Err(ErrorReply::new(ErrorCode::ExpiredToken, "the device grant expired")); + } + let fast = pending + .polled + .is_some_and(|polled| now.saturating_duration_since(polled) < self.config.device_interval); + pending.polled = Some(now); + match pending.decision { + Decision::Waiting if fast => Err(ErrorReply::new(ErrorCode::SlowDown, "polling faster than the interval")), + Decision::Waiting => Err(ErrorReply::new(ErrorCode::AuthorizationPending, "waiting for approval")), + Decision::Denied => { + inner.pending.remove(&hash); + Err(ErrorReply::new(ErrorCode::AccessDenied, "the device grant was denied")) + } + Decision::Approved => { + let pending = inner.pending.remove(&hash).expect("found above"); + self.admit(&mut inner, pending.endpoint, pending.name.as_deref(), Vec::new())?; + self.save(&inner)?; + self.issue(&inner, pending.endpoint) + } + } + } + + /// Refresh an enrolled device's token, refusing a revoked or unknown one. + pub fn refresh(&self, proof: &Proof) -> Reply { + let mut inner = self.inner.lock().unwrap(); + self.check(&mut inner, proof)?; + match inner + .store + .devices + .iter() + .find(|device| device.endpoint == proof.endpoint) + { + Some(device) if !device.revoked => self.issue(&inner, proof.endpoint), + Some(_) => Err(ErrorReply::new(ErrorCode::AccessDenied, "the device is revoked")), + None => Err(ErrorReply::new(ErrorCode::AccessDenied, "the device is not enrolled")), + } + } + + /// Create an enrollment key, returning it with its secret, which is never shown again. + pub fn create_key(&self, new: &NewKey) -> crate::Result { + let mut inner = self.inner.lock().unwrap(); + let id = hex(&random(8)); + let secret = encode(&random(32)); + let stored = StoredKey { + id: id.clone(), + hash: hex(&sha256(secret.as_bytes())), + tags: new.tags.clone(), + expires: new + .expires_in + .map(|secs| moq_clock::wall().saturating_add(Duration::from_secs(secs))), + reusable: new.reusable, + used: false, + revoked: false, + }; + let mut info = KeyInfo::from(&stored); + info.key = Some(format!("{id}.{secret}")); + inner.store.keys.push(stored); + self.save(&inner) + .map_err(|err| crate::Error::MeshState(err.to_string()))?; + Ok(info) + } + + /// Every enrollment key, without secrets. + pub fn keys(&self) -> Vec { + self.inner + .lock() + .unwrap() + .store + .keys + .iter() + .map(KeyInfo::from) + .collect() + } + + /// Revoke an enrollment key so it enrolls nothing new. Devices it enrolled stay. + /// Returns whether the key exists. + pub fn revoke_key(&self, id: &str) -> crate::Result { + let mut inner = self.inner.lock().unwrap(); + let Some(key) = inner.store.keys.iter_mut().find(|key| key.id == id) else { + return Ok(false); + }; + key.revoked = true; + self.save(&inner) + .map_err(|err| crate::Error::MeshState(err.to_string()))?; + Ok(true) + } + + /// Every device, revoked ones included. + pub fn devices(&self) -> Vec { + self.inner.lock().unwrap().store.devices.clone() + } + + /// Revoke a device: its next refresh fails, and it cannot enroll again. + /// Returns whether the device exists. + pub fn revoke_device(&self, endpoint: EndpointId) -> crate::Result { + let mut inner = self.inner.lock().unwrap(); + let Some(device) = inner + .store + .devices + .iter_mut() + .find(|device| device.endpoint == endpoint) + else { + return Ok(false); + }; + device.revoked = true; + self.save(&inner) + .map_err(|err| crate::Error::MeshState(err.to_string()))?; + Ok(true) + } + + /// The device grants waiting for a human. + pub fn pending(&self) -> Vec { + let mut inner = self.inner.lock().unwrap(); + let now = Instant::now(); + inner.pending.retain(|_, pending| pending.expires > now); + inner + .pending + .values() + .filter(|pending| pending.decision == Decision::Waiting) + .map(|pending| PendingDevice { + user_code: pending.user_code.clone(), + endpoint: pending.endpoint, + name: pending.name.clone(), + }) + .collect() + } + + /// Approve or deny the waiting device grant showing `user_code`. Returns whether one + /// was waiting. + pub fn decide(&self, user_code: &str, approve: bool) -> bool { + let user_code = normalize_user_code(user_code); + let mut inner = self.inner.lock().unwrap(); + let now = Instant::now(); + let Some(pending) = inner.pending.values_mut().find(|pending| { + pending.user_code == user_code && pending.decision == Decision::Waiting && pending.expires > now + }) else { + return false; + }; + pending.decision = if approve { Decision::Approved } else { Decision::Denied }; + true + } + + /// The device-facing contract, to serve at [`Config::url`]. + pub fn router(&self) -> Router { + Router::new() + .route("/challenge", post(challenge_handler)) + .route("/enroll", post(enroll_handler)) + .route("/device", post(device_handler).get(verification_handler)) + .route("/device/token", post(device_token_handler)) + .route("/refresh", post(refresh_handler)) + .with_state(self.clone()) + } + + /// The owner's API under `/mesh`, with no authentication of its own: mount it only on + /// a listener the owner alone reaches. + pub fn admin_router(&self) -> Router { + Router::new() + .route("/mesh/keys", get(keys_handler).post(create_key_handler)) + .route("/mesh/keys/{id}", delete(revoke_key_handler)) + .route("/mesh/devices", get(devices_handler)) + .route("/mesh/devices/{endpoint}", delete(revoke_device_handler)) + .route("/mesh/pending", get(pending_handler)) + .route("/mesh/pending/{code}/approve", post(approve_handler)) + .route("/mesh/pending/{code}/deny", post(deny_handler)) + .with_state(self.clone()) + } + + /// Serve the device-facing contract on a TCP listener until the task is dropped. + pub async fn serve(&self, listener: tokio::net::TcpListener) -> std::io::Result<()> { + axum::serve(listener, self.router()).await + } + + fn verification_uri(&self) -> url::Url { + let mut url = self.config.url.clone(); + let path = format!("{}/device", url.path().trim_end_matches('/')); + url.set_path(&path); + url + } + + /// Consume the proof's challenge and verify its signature. + fn check(&self, inner: &mut Inner, proof: &Proof) -> Reply<()> { + // Consumed even when the signature fails, so one challenge is one attempt. + let issued = inner + .challenges + .remove(&proof.challenge) + .ok_or_else(|| ErrorReply::new(ErrorCode::InvalidChallenge, "unknown or used challenge"))?; + if Instant::now().saturating_duration_since(issued) >= CHALLENGE_TTL { + return Err(ErrorReply::new(ErrorCode::InvalidChallenge, "the challenge expired")); + } + if !proof.verify(&self.config.url) { + return Err(ErrorReply::new( + ErrorCode::InvalidSignature, + "the signature does not verify against the endpoint ID", + )); + } + Ok(()) + } + + fn refuse_revoked(&self, inner: &Inner, endpoint: EndpointId) -> Reply<()> { + if inner + .store + .devices + .iter() + .any(|device| device.endpoint == endpoint && device.revoked) + { + return Err(ErrorReply::new(ErrorCode::AccessDenied, "the device is revoked")); + } + Ok(()) + } + + /// Record `endpoint` as enrolled, or update its name and tags if it already is. + fn admit(&self, inner: &mut Inner, endpoint: EndpointId, name: Option<&str>, tags: Vec) -> Reply<()> { + self.refuse_revoked(inner, endpoint)?; + let devices = &mut inner.store.devices; + let current = devices.iter().position(|device| device.endpoint == endpoint); + let name = match (name, current) { + (None, Some(index)) => devices[index].name.clone(), + (name, _) => unique_name(devices, endpoint, &sanitize(name.unwrap_or_default())), + }; + match current { + Some(index) => { + devices[index].name = name; + devices[index].tags = tags; + } + None => devices.push(Device { + endpoint, + name, + tags, + enrolled: moq_clock::wall(), + revoked: false, + }), + } + Ok(()) + } + + /// Sign a token for an enrolled `endpoint` and list the mesh. + fn issue(&self, inner: &Inner, endpoint: EndpointId) -> Reply { + let internal = |err: crate::Error| ErrorReply::new(ErrorCode::ServerError, err.to_string()); + let now = moq_clock::wall(); + // `exp` is whole seconds on the wire; truncate so the reply matches the token. + let secs = now + .checked_duration_since(moq_clock::Wall::UNIX_EPOCH) + .unwrap_or_default() + .as_secs(); + let expires = moq_clock::Wall::UNIX_EPOCH.saturating_add(Duration::from_secs(secs) + self.config.token_ttl); + let claims = Claims::default() + .with_publish([endpoint.publish()]) + .with_subscribe([Pattern::subtree("mesh").expect("a valid path")]) + .with_issued(now) + .with_expires(expires); + let token = self.config.key.sign(&claims).map_err(internal)?; + let device = inner + .store + .devices + .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: inner + .store + .devices + .iter() + .filter(|device| !device.revoked) + .map(|device| Member { + endpoint: device.endpoint, + name: device.name.clone(), + tags: device.tags.clone(), + }) + .collect(), + }) + } + + /// Write the store atomically: a temporary file beside it, renamed over it. + fn save(&self, inner: &Inner) -> Reply<()> { + let Some(path) = &self.config.state else { + return Ok(()); + }; + let failed = |err: std::io::Error| { + tracing::error!(path = %path.display(), %err, "failed to save the mesh state"); + ErrorReply::new(ErrorCode::ServerError, "the coordinator could not save its state") + }; + let json = serde_json::to_string_pretty(&inner.store).expect("the store serializes"); + let tmp = path.with_extension("tmp"); + crate::fs::write_private(&tmp, &json).map_err(failed)?; + std::fs::rename(&tmp, path).map_err(failed) + } +} + +/// `name` as one DNS label: lowercase ASCII letters, digits, and inner hyphens, at most +/// 63 bytes, `device` when nothing is left. +fn sanitize(name: &str) -> String { + let mut out = String::with_capacity(name.len().min(MAX_NAME)); + for c in name.chars() { + let c = c.to_ascii_lowercase(); + let c = if c.is_ascii_alphanumeric() { c } else { '-' }; + if c == '-' && (out.is_empty() || out.ends_with('-')) { + continue; + } + out.push(c); + } + out.truncate(MAX_NAME); + let out = out.trim_end_matches('-'); + if out.is_empty() { "device".into() } else { out.into() } +} + +/// `name`, or `name-2`, `name-3`, ... when another endpoint holds it. +fn unique_name(devices: &[Device], endpoint: EndpointId, name: &str) -> String { + let taken = |candidate: &str| { + devices + .iter() + .any(|device| device.endpoint != endpoint && device.name == candidate) + }; + if !taken(name) { + return name.into(); + } + (2..) + .map(|n| { + let suffix = format!("-{n}"); + let base = &name[..name.len().min(MAX_NAME - suffix.len())]; + format!("{}{suffix}", base.trim_end_matches('-')) + }) + .find(|candidate| !taken(candidate)) + .expect("an unbounded search finds a free name") +} + +/// Eight characters from [`USER_CODE_ALPHABET`] as `XXXX-XXXX`. +fn user_code() -> String { + let bytes = random(8); + let mut code = String::with_capacity(9); + for (i, byte) in bytes.iter().enumerate() { + if i == 4 { + code.push('-'); + } + // 256 is not a multiple of 20; the slight bias costs a fraction of a bit. + code.push(USER_CODE_ALPHABET[*byte as usize % USER_CODE_ALPHABET.len()] as char); + } + code +} + +/// A user code as typed: case and separators ignored, as RFC 8628 §6.1 advises. +fn normalize_user_code(code: &str) -> String { + let letters: String = code + .chars() + .filter(char::is_ascii_alphanumeric) + .map(|c| c.to_ascii_uppercase()) + .collect(); + if letters.len() == 8 { + format!("{}-{}", &letters[..4], &letters[4..]) + } else { + letters + } +} + +/// base64url without padding, the encoding of every random secret in the contract. +fn encode(bytes: &[u8]) -> String { + use base64::Engine; + base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(bytes) +} + +fn random(len: usize) -> Vec { + let mut bytes = vec![0u8; len]; + aws_lc_rs::rand::fill(&mut bytes).expect("system randomness"); + bytes +} + +fn sha256(bytes: &[u8]) -> Vec { + aws_lc_rs::digest::digest(&aws_lc_rs::digest::SHA256, bytes) + .as_ref() + .to_vec() +} + +fn constant_eq(a: &[u8], b: &[u8]) -> bool { + aws_lc_rs::constant_time::verify_slices_are_equal(a, b).is_ok() +} + +fn hex(bytes: &[u8]) -> String { + bytes.iter().map(|byte| format!("{byte:02x}")).collect() +} + +impl IntoResponse for ErrorReply { + fn into_response(self) -> Response { + // RFC 6749 §5.2: 400 for every OAuth error except a failed client authentication. + let status = match self.error { + ErrorCode::ServerError => StatusCode::INTERNAL_SERVER_ERROR, + _ => StatusCode::BAD_REQUEST, + }; + (status, Json(self)).into_response() + } +} + +/// A JSON body that refuses with the contract's error shape rather than axum's text. +struct Body(T); + +impl axum::extract::FromRequest for Body { + type Rejection = ErrorReply; + + async fn from_request(request: axum::extract::Request, state: &S) -> Result { + Json::::from_request(request, state) + .await + .map(|Json(body)| Self(body)) + .map_err(|err| ErrorReply::new(ErrorCode::InvalidRequest, err.body_text())) + } +} + +async fn challenge_handler(State(coordinator): State) -> Json { + Json(coordinator.challenge()) +} + +async fn enroll_handler( + State(coordinator): State, + Body(request): Body, +) -> Reply> { + coordinator.enroll(&request).map(Json) +} + +async fn device_handler( + State(coordinator): State, + Body(request): Body, +) -> Reply> { + coordinator.device(&request).map(Json) +} + +async fn verification_handler() -> &'static str { + "Ask the mesh owner to approve your device: moq auth mesh approve \n" +} + +async fn device_token_handler( + State(coordinator): State, + Body(request): Body, +) -> Reply> { + coordinator.device_token(&request).map(Json) +} + +async fn refresh_handler(State(coordinator): State, Body(proof): Body) -> Reply> { + coordinator.refresh(&proof).map(Json) +} + +fn admin_error(err: crate::Error) -> Response { + (StatusCode::INTERNAL_SERVER_ERROR, err.to_string()).into_response() +} + +async fn keys_handler(State(coordinator): State) -> Json> { + Json(coordinator.keys()) +} + +async fn create_key_handler(State(coordinator): State, Body(new): Body) -> Response { + match coordinator.create_key(&new) { + Ok(info) => (StatusCode::CREATED, Json(info)).into_response(), + Err(err) => admin_error(err), + } +} + +async fn revoke_key_handler(State(coordinator): State, Path(id): Path) -> Response { + match coordinator.revoke_key(&id) { + Ok(true) => StatusCode::NO_CONTENT.into_response(), + Ok(false) => (StatusCode::NOT_FOUND, "not found").into_response(), + Err(err) => admin_error(err), + } +} + +async fn devices_handler(State(coordinator): State) -> Json> { + Json(coordinator.devices()) +} + +async fn revoke_device_handler(State(coordinator): State, Path(endpoint): Path) -> Response { + let Ok(endpoint) = endpoint.parse() else { + return (StatusCode::BAD_REQUEST, "invalid endpoint ID").into_response(); + }; + match coordinator.revoke_device(endpoint) { + Ok(true) => StatusCode::NO_CONTENT.into_response(), + Ok(false) => (StatusCode::NOT_FOUND, "not found").into_response(), + Err(err) => admin_error(err), + } +} + +async fn pending_handler(State(coordinator): State) -> Json> { + Json(coordinator.pending()) +} + +async fn approve_handler(State(coordinator): State, Path(code): Path) -> Response { + decide(&coordinator, &code, true) +} + +async fn deny_handler(State(coordinator): State, Path(code): Path) -> Response { + decide(&coordinator, &code, false) +} + +/// A known route's miss carries a body, so the CLI can tell it from a missing route. +fn decide(coordinator: &Coordinator, code: &str, approve: bool) -> Response { + if coordinator.decide(code, approve) { + StatusCode::NO_CONTENT.into_response() + } else { + (StatusCode::NOT_FOUND, "not found").into_response() + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::{Algorithm, KeyId}; + + #[test] + fn names_are_dns_labels() { + assert_eq!(sanitize("Luke's MacBook Pro"), "luke-s-macbook-pro"); + assert_eq!(sanitize("--robot_01.local--"), "robot-01-local"); + assert_eq!(sanitize("日本"), "device"); + assert_eq!(sanitize(&"a".repeat(100)).len(), MAX_NAME); + } + + #[test] + fn names_stay_unique() { + let device = |byte, name: &str| Device { + endpoint: EndpointId::from_bytes([byte; 32]), + name: name.into(), + tags: Vec::new(), + enrolled: moq_clock::wall(), + revoked: false, + }; + let devices = vec![device(1, "robot"), device(2, "robot-2")]; + assert_eq!(unique_name(&devices, EndpointId::from_bytes([1; 32]), "robot"), "robot"); + assert_eq!( + unique_name(&devices, EndpointId::from_bytes([3; 32]), "robot"), + "robot-3" + ); + let long = "a".repeat(MAX_NAME); + let devices = vec![device(1, &long)]; + let name = unique_name(&devices, EndpointId::from_bytes([3; 32]), &long); + assert_eq!(name.len(), MAX_NAME); + assert!(name.ends_with("-2")); + } + + #[test] + fn user_codes_read_back_however_typed() { + let code = user_code(); + assert_eq!(code.len(), 9); + assert_eq!(normalize_user_code(&code.to_lowercase().replace('-', " ")), code); + } + + #[test] + fn state_survives_a_restart() { + let dir = tempfile::tempdir().unwrap(); + let mut config = Config::new( + "https://mesh.example".parse().unwrap(), + Key::generate(Algorithm::HS256, Some(KeyId::decode("mesh").unwrap())).unwrap(), + ); + config.state = Some(dir.path().join("mesh.json")); + let coordinator = Coordinator::new(config.clone()).unwrap(); + let key = coordinator.create_key(&NewKey::default()).unwrap(); + assert!(coordinator.revoke_key(&key.id).unwrap()); + + let restarted = Coordinator::new(config).unwrap(); + let keys = restarted.keys(); + assert_eq!(keys.len(), 1); + assert!(keys[0].revoked); + assert_eq!(keys[0].key, None); + } +} diff --git a/rs/moq-auth/src/mesh/mod.rs b/rs/moq-auth/src/mesh/mod.rs new file mode 100644 index 00000000000..0c89899a0c1 --- /dev/null +++ b/rs/moq-auth/src/mesh/mod.rs @@ -0,0 +1,415 @@ +//! Mesh enrollment: how a device with an endpoint key joins a mesh. +//! +//! A device proves it holds its Ed25519 endpoint key by signing a fresh challenge from +//! the coordinator, and presents a credential: a pre-authorized enrollment key, or a +//! device grant (RFC 8628) a human approved. The coordinator answers with an +//! [`Enrollment`]: the relays to dial and a JWT granting publish on `mesh//**` 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. +//! +//! These types are the JSON contract. [`Coordinator`] (feature `serve`) answers it behind +//! `moq auth serve`; [`Client`] (feature `client`) drives it from a device. A hosted +//! service implements the same contract with its own accounts. +//! +//! | Request | Body | Reply | +//! |---|---|---| +//! | `POST {base}/challenge` | none | [`Challenge`] | +//! | `POST {base}/enroll` | [`EnrollRequest`] | [`Enrollment`] | +//! | `POST {base}/device` | [`DeviceRequest`] | [`DeviceAuthorization`] | +//! | `POST {base}/device/token` | [`DeviceTokenRequest`] | [`Enrollment`] | +//! | `POST {base}/refresh` | [`Proof`] | [`Enrollment`] | +//! +//! Every refusal is a 4xx with an [`ErrorReply`]. + +use std::fmt; +use std::str::FromStr; + +use serde::{Deserialize, Serialize}; +use serde_with::serde_as; + +#[cfg(feature = "client")] +mod client; +#[cfg(all(test, feature = "client", feature = "serve"))] +mod contract_tests; +#[cfg(feature = "serve")] +mod coordinator; + +#[cfg(feature = "client")] +pub use client::*; +#[cfg(feature = "serve")] +pub use coordinator::*; + +/// The context string every [`Proof`] signature starts with, so a signature made for +/// enrollment can never be replayed as anything else the endpoint key signs. +pub const PROOF_CONTEXT: &[u8] = b"moq-mesh-enroll-00"; + +/// The length of a challenge in bytes. +pub const CHALLENGE_LEN: usize = 32; + +const KEY_LEN: usize = 32; +const SIGNATURE_LEN: usize = 64; + +/// An endpoint's Ed25519 public key, which is also its endpoint ID. +/// +/// Its text form is the 64-character lowercase hex of the key, the form iroh displays. +/// Parsing accepts only that form, so one key names exactly one `mesh/` path. +#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)] +pub struct EndpointId([u8; KEY_LEN]); + +impl EndpointId { + /// The ID of the raw 32-byte Ed25519 public key. + pub fn from_bytes(bytes: [u8; KEY_LEN]) -> Self { + Self(bytes) + } + + /// The raw 32-byte Ed25519 public key. + pub fn as_bytes(&self) -> &[u8; KEY_LEN] { + &self.0 + } + + /// Whether `signature` is this key's Ed25519 signature over `message`. + pub fn verify(&self, message: &[u8], signature: &[u8]) -> bool { + use aws_lc_rs::signature::{ED25519, UnparsedPublicKey}; + UnparsedPublicKey::new(&ED25519, &self.0) + .verify(message, signature) + .is_ok() + } + + /// The broadcasts this endpoint may publish: `mesh//**`. + pub fn publish(&self) -> crate::Pattern { + crate::Pattern::subtree(&format!("mesh/{self}")).expect("a hex segment is a valid path") + } +} + +/// The text is not the 64-character lowercase hex of a 32-byte key. +#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)] +#[error("invalid endpoint ID: expected 64 lowercase hex characters")] +#[non_exhaustive] +pub struct InvalidEndpoint; + +impl FromStr for EndpointId { + type Err = InvalidEndpoint; + + fn from_str(text: &str) -> Result { + // Uppercase is refused so a key has one text form. + if text.len() != KEY_LEN * 2 || !text.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f')) { + return Err(InvalidEndpoint); + } + let mut out = [0u8; KEY_LEN]; + for (i, byte) in out.iter_mut().enumerate() { + *byte = u8::from_str_radix(&text[i * 2..i * 2 + 2], 16).map_err(|_| InvalidEndpoint)?; + } + Ok(Self(out)) + } +} + +impl fmt::Display for EndpointId { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + for byte in self.0 { + write!(f, "{byte:02x}")?; + } + Ok(()) + } +} + +impl fmt::Debug for EndpointId { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_tuple("EndpointId").field(&format_args!("{self}")).finish() + } +} + +impl Serialize for EndpointId { + fn serialize(&self, serializer: S) -> Result { + serializer.collect_str(self) + } +} + +impl<'de> Deserialize<'de> for EndpointId { + fn deserialize>(deserializer: D) -> Result { + let text = >::deserialize(deserializer)?; + text.parse().map_err(serde::de::Error::custom) + } +} + +/// The message a [`Proof`] signs: [`PROOF_CONTEXT`], a zero byte, the coordinator's base +/// URL as the device addressed it, a zero byte, then the raw challenge. +/// +/// The URL binds the proof to one coordinator, so a coordinator the device trusts cannot +/// relay another's challenge and enroll the device's key there. +pub fn proof_message(base: &url::Url, challenge: &[u8]) -> Vec { + let base = audience(base); + let mut message = Vec::with_capacity(PROOF_CONTEXT.len() + base.len() + challenge.len() + 2); + message.extend_from_slice(PROOF_CONTEXT); + message.push(0); + message.extend_from_slice(base.as_bytes()); + message.push(0); + message.extend_from_slice(challenge); + message +} + +/// The base URL without a trailing slash, the form both sides sign over. +fn audience(base: &url::Url) -> &str { + base.as_str().trim_end_matches('/') +} + +/// A fresh, single-use challenge from `POST {base}/challenge`. +#[serde_as] +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[non_exhaustive] +pub struct Challenge { + /// [`CHALLENGE_LEN`] random bytes, base64url without padding. + #[serde_as(as = "serde_with::base64::Base64")] + pub challenge: Vec, + /// When the coordinator stops accepting a proof over it, unix seconds. + #[serde_as(as = "moq_clock::serde::UnixSeconds")] + pub expires: moq_clock::Wall, +} + +/// Proof that the caller holds `endpoint`'s secret key: its signature over +/// [`proof_message`] for a challenge the coordinator issued and has not yet seen used. +#[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: EndpointId, + /// The challenge, as issued. + #[serde_as(as = "serde_with::base64::Base64")] + pub challenge: Vec, + /// The Ed25519 signature over [`proof_message`]. + #[serde_as(as = "serde_with::base64::Base64")] + pub signature: Vec, +} + +impl Proof { + /// A proof for `challenge` at the coordinator `base`, signed by `signer`. + pub fn sign(signer: &dyn Signer, base: &url::Url, challenge: Vec) -> Self { + let signature = signer.sign(&proof_message(base, &challenge)).to_vec(); + Self { + endpoint: signer.endpoint(), + challenge, + signature, + } + } + + /// Whether the signature verifies for the coordinator `base`. The challenge's + /// freshness is the coordinator's to check. + pub fn verify(&self, base: &url::Url) -> bool { + self.signature.len() == SIGNATURE_LEN + && self + .endpoint + .verify(&proof_message(base, &self.challenge), &self.signature) + } +} + +/// An endpoint's secret key, held by whatever stores it. +/// +/// Implemented for [`aws_lc_rs::signature::Ed25519KeyPair`]; a daemon implements it for +/// its own key type. +pub trait Signer: Send + Sync { + /// The endpoint ID: this key's public half. + fn endpoint(&self) -> EndpointId; + /// The Ed25519 signature over `message`. + fn sign(&self, message: &[u8]) -> [u8; SIGNATURE_LEN]; +} + +impl Signer for aws_lc_rs::signature::Ed25519KeyPair { + fn endpoint(&self) -> EndpointId { + use aws_lc_rs::signature::KeyPair; + EndpointId( + self.public_key() + .as_ref() + .try_into() + .expect("a 32-byte Ed25519 public key"), + ) + } + + fn sign(&self, message: &[u8]) -> [u8; SIGNATURE_LEN] { + aws_lc_rs::signature::Ed25519KeyPair::sign(self, message) + .as_ref() + .try_into() + .expect("a 64-byte Ed25519 signature") + } +} + +/// `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)] + pub proof: Proof, + /// The enrollment key the mesh owner created. + pub key: String, + /// The device's requested name, usually its hostname. The coordinator may change it to + /// keep names unique and DNS-safe; the [`Enrollment`] carries the one it assigned. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub name: Option, +} + +/// `POST {base}/device`: start a device grant (RFC 8628) for a human to approve. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[non_exhaustive] +pub struct DeviceRequest { + /// Proof of the endpoint key, which the grant is bound to. + #[serde(flatten)] + pub proof: Proof, + /// The device's requested name, as in [`EnrollRequest::name`]. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub name: Option, +} + +/// The device authorization response of RFC 8628 §3.2. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[non_exhaustive] +pub struct DeviceAuthorization { + /// The secret the device polls `POST {base}/device/token` with. + pub device_code: String, + /// The code the human enters or reads out to approve the device. + pub user_code: String, + /// Where the human approves it. + pub verification_uri: url::Url, + /// Seconds until the codes expire. + pub expires_in: u64, + /// Seconds the device waits between polls. + pub interval: u64, +} + +/// `POST {base}/device/token`: poll a device grant. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[non_exhaustive] +pub struct DeviceTokenRequest { + /// The code from the [`DeviceAuthorization`]. + pub device_code: String, +} + +/// 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, + /// When the token expires, unix seconds. Refresh before then. + #[serde_as(as = "moq_clock::serde::UnixSeconds")] + pub expires: moq_clock::Wall, + /// The relays to dial, presenting the token. + pub relays: Vec, + /// The name the coordinator assigned this device. + pub name: String, + /// Every enrolled member of the mesh, this device included. + pub members: Vec, +} + +/// 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: EndpointId, + /// Its unique, DNS-safe name. + pub name: String, + /// The tags of the enrollment key it joined with. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub tags: Vec, +} + +/// 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())] +#[non_exhaustive] +pub struct ErrorReply { + /// The machine-readable reason. + pub error: ErrorCode, + /// A human-readable detail. + #[serde(rename = "error_description", default, skip_serializing_if = "Option::is_none")] + pub description: Option, +} + +impl ErrorReply { + /// A refusal for `error` with a human-readable detail. + pub fn new(error: ErrorCode, description: impl Into) -> Self { + Self { + error, + description: Some(description.into()), + } + } +} + +/// The reasons a coordinator refuses, the device grant ones from RFC 8628 §3.5. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +#[non_exhaustive] +pub enum ErrorCode { + /// The body did not parse. + InvalidRequest, + /// The challenge is unknown, used, or expired; fetch a new one. + InvalidChallenge, + /// The signature does not verify against the endpoint ID. + InvalidSignature, + /// The enrollment key is unknown, used, revoked, or expired. + InvalidGrant, + /// The human has not yet approved the device grant; poll again. + AuthorizationPending, + /// Polling too fast; wait longer between polls. + SlowDown, + /// The human denied the device grant, or the device is revoked or not enrolled. + AccessDenied, + /// The device grant expired; start a new one. + ExpiredToken, + /// The coordinator failed on its side; retry later. + ServerError, + /// A reason this version does not know. + #[serde(other)] + Unknown, +} + +impl fmt::Display for ErrorCode { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + let value = serde_json::to_value(self).expect("an enum serializes"); + f.write_str(value.as_str().unwrap_or("unknown")) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn signer() -> aws_lc_rs::signature::Ed25519KeyPair { + aws_lc_rs::signature::Ed25519KeyPair::generate().unwrap() + } + + #[test] + fn endpoint_ids_have_one_text_form() { + let id = signer().endpoint(); + let text = id.to_string(); + assert_eq!(text.len(), 64); + assert_eq!(text.parse::().unwrap(), id); + assert!(text.to_uppercase().parse::().is_err()); + assert!(text[..62].parse::().is_err()); + assert_eq!(id.publish().as_str(), format!("mesh/{text}/**")); + } + + #[test] + fn a_proof_is_bound_to_its_coordinator() { + let key = signer(); + let base: url::Url = "https://a.example/mesh".parse().unwrap(); + let proof = Proof::sign(&key, &base, vec![7; CHALLENGE_LEN]); + assert!(proof.verify(&base)); + assert!(proof.verify(&"https://a.example/mesh/".parse().unwrap())); + assert!(!proof.verify(&"https://b.example/mesh".parse().unwrap())); + + let mut forged = proof.clone(); + forged.endpoint = signer().endpoint(); + assert!(!forged.verify(&base)); + } + + #[test] + fn error_replies_read_unknown_codes() { + let reply: ErrorReply = serde_json::from_str(r#"{"error":"authorization_pending"}"#).unwrap(); + assert_eq!(reply.error, ErrorCode::AuthorizationPending); + let reply: ErrorReply = serde_json::from_str(r#"{"error":"new_thing","error_description":"x"}"#).unwrap(); + assert_eq!(reply.error, ErrorCode::Unknown); + assert_eq!(ErrorCode::SlowDown.to_string(), "slow_down"); + } +} diff --git a/rs/moq-auth/src/serve.rs b/rs/moq-auth/src/serve.rs index 9c7a090554d..75b2b57bc49 100644 --- a/rs/moq-auth/src/serve.rs +++ b/rs/moq-auth/src/serve.rs @@ -455,6 +455,7 @@ fn hash(token: &str) -> u64 { pub struct Server { policy: Arc, sessions: Arc>, + mesh: Option, } impl Server { @@ -481,9 +482,17 @@ impl Server { Ok(Self { policy: Arc::new(policy), sessions: Default::default(), + mesh: None, }) } + /// Also answer the mesh owner's API under `/mesh` with `coordinator`. Like `POST /`, + /// it has no authentication of its own. + pub fn with_mesh(mut self, coordinator: crate::mesh::Coordinator) -> Self { + self.mesh = Some(coordinator); + self + } + /// The cadence the session table ages out by, or `None` when no limit needs a table. fn cadence(&self) -> Option { let limits = self.policy.limits; @@ -520,9 +529,14 @@ impl Server { } } - /// The router: `POST /` reading a [`Request`] and writing a [`Grant`]. + /// The router: `POST /` reading a [`Request`] and writing a [`Grant`], plus the mesh + /// owner's API when [`with_mesh`](Self::with_mesh) set one. pub fn router(&self) -> Router { - Router::new().route("/", post(handle)).with_state(self.clone()) + let router = Router::new().route("/", post(handle)).with_state(self.clone()); + match &self.mesh { + Some(mesh) => router.merge(mesh.admin_router()), + None => router, + } } /// Serve on a TCP listener until the task is dropped. diff --git a/rs/moq-cli/src/auth.rs b/rs/moq-cli/src/auth.rs index e50445bb213..b672eb7186a 100644 --- a/rs/moq-cli/src/auth.rs +++ b/rs/moq-cli/src/auth.rs @@ -116,6 +116,7 @@ impl Args { println!("{payload:#?}"); } + Command::Mesh(mesh) => mesh.run().await?, Command::Sessions(filter) => filter.get("/sessions").await?, Command::Revalidate(filter) => filter.post("/sessions/revalidate").await?, } @@ -198,6 +199,9 @@ enum Command { /// Answer a relay's auth requests with keys, public rules, an mTLS grant, tiers, and session limits. Serve(Serve), + /// Manage a mesh served by `moq auth serve --mesh-url`: enrollment keys, devices, and device grants. + Mesh(Mesh), + /// List live sessions on a relay's internal listener. Sessions(SessionFilter), @@ -426,6 +430,31 @@ pub struct Serve { /// The most live sessions from one remote address. Needs `--revalidate`. #[usage(long)] limit_remote: Option, + + /// Coordinate a mesh: the public base URL devices enroll at, which every enrollment + /// proof is bound to. Serve it behind TLS; devices refuse plain `http://` beyond loopback. + #[usage(long)] + mesh_url: Option, + + /// Where to answer devices at `--mesh-url`, usually behind a TLS-terminating proxy. + #[usage(long, default = "127.0.0.1:4441", requires = "--mesh-url")] + mesh_listen: SocketAddr, + + /// The private key that signs mesh tokens; the relays verify it like any other. + #[usage(long, requires = "--mesh-url", value_hint = usage_rs::ValueHint::FilePath, extensions("jwk", "json"))] + mesh_key: Option, + + /// A relay URL enrolled devices dial (repeatable). + #[usage(long, requires = "--mesh-url")] + mesh_relay: Vec, + + /// The JSON file enrollment keys and devices persist to. Without one, a restart forgets them. + #[usage(long, requires = "--mesh-url", value_hint = usage_rs::ValueHint::FilePath)] + mesh_state: Option, + + /// How long a mesh token lasts; devices refresh it two thirds of the way through. + #[usage(long, default = "1h", requires = "--mesh-url")] + mesh_token_ttl: moq_tokio::cli::Duration, } impl Serve { @@ -512,30 +541,197 @@ impl Serve { Ok(Listen::Tcp(addr)) } + /// The mesh coordinator these flags describe, if `--mesh-url` asks for one. + fn coordinator(&self) -> anyhow::Result> { + let Some(url) = &self.mesh_url else { + return Ok(None); + }; + let path = self + .mesh_key + .as_ref() + .context("--mesh-url needs --mesh-key to sign tokens")?; + let key = moq_auth::Key::from_file(path).with_context(|| format!("failed to read {}", path.display()))?; + let ttl = std::time::Duration::from(self.mesh_token_ttl); + if ttl.is_zero() { + anyhow::bail!("--mesh-token-ttl must be longer than 0s"); + } + let mut config = moq_auth::mesh::Config::new(url.clone(), key); + config.relays = self.mesh_relay.clone(); + config.state = self.mesh_state.clone(); + config.token_ttl = ttl; + Ok(Some(moq_auth::mesh::Coordinator::new(config)?)) + } + async fn run(self) -> anyhow::Result<()> { let listen = self.listener()?; - let server = moq_auth::serve::Server::new(self.policy()?)?; - match listen { - Listen::Tcp(addr) => { - let listener = tokio::net::TcpListener::bind(addr) - .await - .with_context(|| format!("failed to bind {addr}"))?; - tracing::info!(%addr, "auth server listening"); - server.serve(listener).await?; + let mut server = moq_auth::serve::Server::new(self.policy()?)?; + // The device-facing contract runs beside the auth server; either stopping ends both. + let mut mesh = None; + if let Some(coordinator) = self.coordinator()? { + let addr = self.mesh_listen; + let listener = tokio::net::TcpListener::bind(addr) + .await + .with_context(|| format!("failed to bind {addr}"))?; + tracing::info!(%addr, url = ?self.mesh_url, "mesh coordinator listening"); + mesh = Some((coordinator.clone(), listener)); + server = server.with_mesh(coordinator); + } + let mesh = async move { + match mesh { + Some((coordinator, listener)) => coordinator.serve(listener).await, + None => std::future::pending().await, } - #[cfg(unix)] - Listen::Unix(path) => { - unlink_socket(&path)?; - let listener = tokio::net::UnixListener::bind(&path) - .with_context(|| format!("failed to bind {}", path.display()))?; - tracing::info!(path = %path.display(), "auth server listening"); - server.serve_unix(listener).await?; + }; + let auth = async move { + match listen { + Listen::Tcp(addr) => { + let listener = tokio::net::TcpListener::bind(addr) + .await + .with_context(|| format!("failed to bind {addr}"))?; + tracing::info!(%addr, "auth server listening"); + server.serve(listener).await?; + } + #[cfg(unix)] + Listen::Unix(path) => { + unlink_socket(&path)?; + let listener = tokio::net::UnixListener::bind(&path) + .with_context(|| format!("failed to bind {}", path.display()))?; + tracing::info!(path = %path.display(), "auth server listening"); + server.serve_unix(listener).await?; + } + #[cfg(not(unix))] + Listen::Unix(path) => anyhow::bail!("unix sockets are not supported here: {}", path.display()), } - #[cfg(not(unix))] - Listen::Unix(path) => anyhow::bail!("unix sockets are not supported here: {}", path.display()), + anyhow::Ok(()) + }; + tokio::select! { + res = auth => res, + res = mesh => res.context("the mesh coordinator stopped"), + } + } +} + +/// `moq auth mesh`: the mesh owner's commands, sent to the auth server's own listener. +#[derive(usage_rs::Args, Clone, Debug)] +#[usage(unknown_flags = "error", args_override_self = false)] +pub struct Mesh { + /// The auth server's listener, which serves the owner's API alongside `POST /`. + #[usage(long, default = "http://127.0.0.1:4440")] + url: url::Url, + + #[usage(subcommand)] + command: MeshCommand, +} + +#[derive(usage_rs::Subcommands, Clone, Debug)] +enum MeshCommand { + /// Create an enrollment key, printing it once. + CreateKey { + /// A tag every device it enrolls carries (repeatable). + #[usage(long)] + tag: Vec, + + /// How long until it stops enrolling. Never, by default. + #[usage(long)] + expires: Option, + + /// Enroll any number of devices, instead of one. + #[usage(long)] + reusable: bool, + }, + + /// List enrollment keys, without their secrets. + Keys, + + /// Revoke an enrollment key so it enrolls nothing new. Its devices stay. + RevokeKey { + /// The key's ID: the part before the dot. + id: String, + }, + + /// List enrolled devices. + Devices, + + /// Revoke a device: its next refresh fails, and it cannot enroll again. + Revoke { + /// The device's endpoint ID. + endpoint: String, + }, + + /// List device grants waiting for approval. + Pending, + + /// Approve the device grant showing this user code. + Approve { + /// The code the device shows, e.g. `BCDF-GHJK`. + code: String, + }, + + /// Deny the device grant showing this user code. + Deny { + /// The code the device shows. + code: String, + }, +} + +impl Mesh { + async fn run(self) -> anyhow::Result<()> { + let client = reqwest::Client::new(); + let request = match &self.command { + MeshCommand::CreateKey { tag, expires, reusable } => { + let body = serde_json::json!({ + "tags": tag, + "expires_in": expires.map(|expires| std::time::Duration::from(expires).as_secs()), + "reusable": reusable, + }); + client.post(self.url("/mesh/keys", &[])).json(&body) + } + MeshCommand::Keys => client.get(self.url("/mesh/keys", &[])), + MeshCommand::RevokeKey { id } => client.delete(self.url("/mesh/keys", &[id])), + MeshCommand::Devices => client.get(self.url("/mesh/devices", &[])), + MeshCommand::Revoke { endpoint } => client.delete(self.url("/mesh/devices", &[endpoint])), + MeshCommand::Pending => client.get(self.url("/mesh/pending", &[])), + MeshCommand::Approve { code } => client.post(self.url("/mesh/pending", &[code, "approve"])), + MeshCommand::Deny { code } => client.post(self.url("/mesh/pending", &[code, "deny"])), + }; + let response = request + .send() + .await + .with_context(|| format!("failed to reach {}", self.url))?; + let status = response.status(); + let body = response.text().await.context("failed to read the reply")?; + if status == reqwest::StatusCode::NOT_FOUND { + // The routes exist only with `--mesh-url`, so a miss there is the likelier cause. + anyhow::bail!(match self.command { + MeshCommand::RevokeKey { .. } if !body.is_empty() => "no enrollment key has that ID", + MeshCommand::Revoke { .. } if !body.is_empty() => "no device has that endpoint ID", + MeshCommand::Approve { .. } | MeshCommand::Deny { .. } if !body.is_empty() => { + "no device grant is waiting with that code" + } + _ => "not found; is the server running with --mesh-url?", + }); + } + if !status.is_success() { + anyhow::bail!("{status}: {body}"); + } + match serde_json::from_str::(&body) { + Ok(value) => println!("{}", serde_json::to_string_pretty(&value)?), + Err(_) if body.is_empty() => println!("ok"), + Err(_) => println!("{body}"), } Ok(()) } + + /// `path` under the server's URL, with `segments` appended percent-encoded. + fn url(&self, path: &str, segments: &[&str]) -> url::Url { + let mut url = self.url.clone(); + let base = url.path().trim_end_matches('/').to_string(); + url.set_path(&format!("{base}{path}")); + if let Ok(mut parts) = url.path_segments_mut() { + parts.extend(segments); + } + url + } } #[derive(Debug)] @@ -657,6 +853,61 @@ mod tests { } } + #[test] + fn mesh_flags_need_a_mesh_url_and_key() { + let err = parse(&["moq", "auth", "serve", "--mesh-relay", "https://relay.example"]).unwrap_err(); + assert!(err.to_string().contains("--mesh-url"), "{err}"); + + let flags = serve(&["moq", "auth", "serve", "--mesh-url", "https://mesh.example"]); + let err = flags.coordinator().err().expect("no signing key"); + assert!(err.to_string().contains("--mesh-key"), "{err}"); + + let dir = tempfile::tempdir().unwrap(); + let key = dir.path().join("mesh.jwk"); + moq_auth::Key::generate(Algorithm::HS256, None) + .unwrap() + .to_file(&key) + .unwrap(); + let flags = serve(&[ + "moq", + "auth", + "serve", + "--mesh-url", + "https://mesh.example", + "--mesh-key", + key.to_str().unwrap(), + "--mesh-relay", + "https://a.example", + "--mesh-relay", + "https://b.example", + ]); + assert_eq!(flags.mesh_relay.len(), 2); + assert!(flags.mesh_listen.ip().is_loopback()); + assert!(flags.coordinator().unwrap().is_some()); + assert!(serve(&["moq", "auth", "serve"]).coordinator().unwrap().is_none()); + } + + #[test] + fn mesh_commands_parse() { + for args in [ + &[ + "moq", + "auth", + "mesh", + "create-key", + "--tag", + "robot", + "--reusable", + "--expires", + "1d", + ][..], + &["moq", "auth", "mesh", "approve", "BCDF-GHJK"], + &["moq", "auth", "mesh", "--url", "http://127.0.0.1:9000", "revoke", "ab"], + ] { + assert!(matches!(parse(args).unwrap().command, Command::Mesh(_)), "{args:?}"); + } + } + #[test] fn serve_refuses_a_public_bind_without_saying_so() { let err = serve(&["moq", "auth", "serve", "--listen", "0.0.0.0:4440"]) From f72c8a27cb16e14b7ce986027062c98b2da1c398 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 07:15:06 -0700 Subject: [PATCH 3/9] fix(auth): commit mesh state only once saved, check the signing key at startup, mount at the URL path Co-Authored-By: Claude Opus 5.5 --- rs/moq-auth/src/mesh/contract_tests.rs | 37 +++++- rs/moq-auth/src/mesh/coordinator.rs | 149 ++++++++++++++----------- 2 files changed, 121 insertions(+), 65 deletions(-) diff --git a/rs/moq-auth/src/mesh/contract_tests.rs b/rs/moq-auth/src/mesh/contract_tests.rs index ab7794d34e7..c060b14ffa8 100644 --- a/rs/moq-auth/src/mesh/contract_tests.rs +++ b/rs/moq-auth/src/mesh/contract_tests.rs @@ -30,7 +30,7 @@ impl Mesh { config.device_interval = Duration::ZERO; config.token_ttl = ttl; let coordinator = Coordinator::new(config).unwrap(); - let router = axum::Router::new().nest("/mesh", coordinator.router()); + let router = coordinator.router(); tokio::spawn(async move { axum::serve(listener, router).await }); Self { coordinator, base, key } } @@ -226,6 +226,41 @@ async fn renew_refreshes_before_expiry() { assert!(renewed.expires > enrollment.expires); } +#[test] +fn a_key_that_cannot_sign_refuses_to_start() { + let key = Key::generate(Algorithm::ES256, None).unwrap().to_public().unwrap(); + let config = Config::new("https://mesh.example".parse().unwrap(), key); + assert!(Coordinator::new(config).is_err()); +} + +#[test] +fn a_failed_save_spends_nothing() { + let dir = tempfile::tempdir().unwrap(); + let key = Key::generate(Algorithm::HS256, None).unwrap(); + let mut config = Config::new("https://mesh.example".parse().unwrap(), key); + config.state = Some(dir.path().join("mesh.json")); + let coordinator = Coordinator::new(config).unwrap(); + let secret = coordinator.create_key(&NewKey::default()).unwrap().key.unwrap(); + + // A directory where the temporary file goes makes every save fail. + std::fs::create_dir(dir.path().join("mesh.tmp")).unwrap(); + let signer = Ed25519KeyPair::generate().unwrap(); + let base: url::Url = "https://mesh.example".parse().unwrap(); + let enroll = |coordinator: &Coordinator| EnrollRequest { + proof: Proof::sign(&signer, &base, coordinator.challenge().challenge), + key: secret.clone(), + name: None, + }; + let err = coordinator.enroll(&enroll(&coordinator)).unwrap_err(); + assert_eq!(err.error, ErrorCode::ServerError); + assert!(coordinator.devices().is_empty()); + assert!(!coordinator.keys()[0].used); + + std::fs::remove_dir(dir.path().join("mesh.tmp")).unwrap(); + coordinator.enroll(&enroll(&coordinator)).unwrap(); + assert!(coordinator.keys()[0].used); +} + #[tokio::test] async fn a_malformed_body_is_an_oauth_error() { let mesh = Mesh::new().await; diff --git a/rs/moq-auth/src/mesh/coordinator.rs b/rs/moq-auth/src/mesh/coordinator.rs index 4909f0171cf..435e5c6a7f6 100644 --- a/rs/moq-auth/src/mesh/coordinator.rs +++ b/rs/moq-auth/src/mesh/coordinator.rs @@ -82,7 +82,7 @@ impl Config { } /// The state that survives a restart. -#[derive(Default, Serialize, Deserialize)] +#[derive(Clone, Default, Serialize, Deserialize)] struct Store { #[serde(default)] keys: Vec, @@ -238,6 +238,11 @@ impl Coordinator { }, None => Store::default(), }; + // Sign once now, so a key that cannot sign these claims fails at startup rather + // than after an enrollment key is spent. + config + .key + .sign(&claims(EndpointId::from_bytes([0; 32]), moq_clock::wall(), None))?; Ok(Self { config: Arc::new(config), inner: Arc::new(Mutex::new(Inner { @@ -311,19 +316,20 @@ impl Coordinator { let id = id.to_string(); let endpoint = request.proof.endpoint; - self.admit(&mut inner, endpoint, request.name.as_deref(), tags)?; - if !reusable && let Some(key) = inner.store.keys.iter_mut().find(|key| key.id == id) { - key.used = true; - } - self.save(&inner)?; - self.issue(&inner, endpoint) + self.commit(&mut inner, |store| { + self.admit(store, endpoint, request.name.as_deref(), tags)?; + if !reusable && let Some(key) = store.keys.iter_mut().find(|key| key.id == id) { + key.used = true; + } + self.issue(store, endpoint) + }) } /// Start a device grant for a human to approve. pub fn device(&self, request: &DeviceRequest) -> Reply { let mut inner = self.inner.lock().unwrap(); self.check(&mut inner, &request.proof)?; - self.refuse_revoked(&inner, request.proof.endpoint)?; + refuse_revoked(&inner.store, request.proof.endpoint)?; let now = Instant::now(); inner.pending.retain(|_, pending| pending.expires > now); @@ -387,10 +393,14 @@ impl Coordinator { Err(ErrorReply::new(ErrorCode::AccessDenied, "the device grant was denied")) } Decision::Approved => { - let pending = inner.pending.remove(&hash).expect("found above"); - self.admit(&mut inner, pending.endpoint, pending.name.as_deref(), Vec::new())?; - self.save(&inner)?; - self.issue(&inner, pending.endpoint) + let (endpoint, name) = (pending.endpoint, pending.name.clone()); + // The grant stays redeemable until its enrollment is saved. + let enrollment = self.commit(&mut inner, |store| { + self.admit(store, endpoint, name.as_deref(), Vec::new())?; + self.issue(store, endpoint) + })?; + inner.pending.remove(&hash); + Ok(enrollment) } } } @@ -405,7 +415,7 @@ impl Coordinator { .iter() .find(|device| device.endpoint == proof.endpoint) { - Some(device) if !device.revoked => self.issue(&inner, proof.endpoint), + Some(device) if !device.revoked => self.issue(&inner.store, proof.endpoint), Some(_) => Err(ErrorReply::new(ErrorCode::AccessDenied, "the device is revoked")), None => Err(ErrorReply::new(ErrorCode::AccessDenied, "the device is not enrolled")), } @@ -429,9 +439,10 @@ impl Coordinator { }; let mut info = KeyInfo::from(&stored); info.key = Some(format!("{id}.{secret}")); - inner.store.keys.push(stored); - self.save(&inner) - .map_err(|err| crate::Error::MeshState(err.to_string()))?; + self.commit(&mut inner, |store| { + store.keys.push(stored); + Ok(()) + })?; Ok(info) } @@ -451,13 +462,11 @@ impl Coordinator { /// Returns whether the key exists. pub fn revoke_key(&self, id: &str) -> crate::Result { let mut inner = self.inner.lock().unwrap(); - let Some(key) = inner.store.keys.iter_mut().find(|key| key.id == id) else { - return Ok(false); - }; - key.revoked = true; - self.save(&inner) - .map_err(|err| crate::Error::MeshState(err.to_string()))?; - Ok(true) + let found = self.commit(&mut inner, |store| { + let key = store.keys.iter_mut().find(|key| key.id == id); + Ok(key.map(|key| key.revoked = true).is_some()) + })?; + Ok(found) } /// Every device, revoked ones included. @@ -469,18 +478,11 @@ impl Coordinator { /// Returns whether the device exists. pub fn revoke_device(&self, endpoint: EndpointId) -> crate::Result { let mut inner = self.inner.lock().unwrap(); - let Some(device) = inner - .store - .devices - .iter_mut() - .find(|device| device.endpoint == endpoint) - else { - return Ok(false); - }; - device.revoked = true; - self.save(&inner) - .map_err(|err| crate::Error::MeshState(err.to_string()))?; - Ok(true) + let found = self.commit(&mut inner, |store| { + let device = store.devices.iter_mut().find(|device| device.endpoint == endpoint); + Ok(device.map(|device| device.revoked = true).is_some()) + })?; + Ok(found) } /// The device grants waiting for a human. @@ -515,15 +517,19 @@ impl Coordinator { true } - /// The device-facing contract, to serve at [`Config::url`]. + /// The device-facing contract, mounted at [`Config::url`]'s path. pub fn router(&self) -> Router { - Router::new() + let router = Router::new() .route("/challenge", post(challenge_handler)) .route("/enroll", post(enroll_handler)) .route("/device", post(device_handler).get(verification_handler)) .route("/device/token", post(device_token_handler)) .route("/refresh", post(refresh_handler)) - .with_state(self.clone()) + .with_state(self.clone()); + match self.config.url.path().trim_end_matches('/') { + "" => router, + base => Router::new().nest(base, router), + } } /// The owner's API under `/mesh`, with no authentication of its own: mount it only on @@ -571,22 +577,20 @@ impl Coordinator { Ok(()) } - fn refuse_revoked(&self, inner: &Inner, endpoint: EndpointId) -> Reply<()> { - if inner - .store - .devices - .iter() - .any(|device| device.endpoint == endpoint && device.revoked) - { - return Err(ErrorReply::new(ErrorCode::AccessDenied, "the device is revoked")); - } - Ok(()) + /// Apply `change` to a copy of the store and save it, adopting the copy only once it + /// is on disk, so a failed save leaves no credential spent and no device admitted. + fn commit(&self, inner: &mut Inner, change: impl FnOnce(&mut Store) -> Reply) -> Reply { + let mut store = inner.store.clone(); + let out = change(&mut store)?; + self.save(&store)?; + inner.store = store; + Ok(out) } /// Record `endpoint` as enrolled, or update its name and tags if it already is. - fn admit(&self, inner: &mut Inner, endpoint: EndpointId, name: Option<&str>, tags: Vec) -> Reply<()> { - self.refuse_revoked(inner, endpoint)?; - let devices = &mut inner.store.devices; + fn admit(&self, store: &mut Store, endpoint: EndpointId, name: Option<&str>, tags: Vec) -> Reply<()> { + refuse_revoked(store, endpoint)?; + let devices = &mut store.devices; let current = devices.iter().position(|device| device.endpoint == endpoint); let name = match (name, current) { (None, Some(index)) => devices[index].name.clone(), @@ -609,7 +613,7 @@ impl Coordinator { } /// Sign a token for an enrolled `endpoint` and list the mesh. - fn issue(&self, inner: &Inner, endpoint: EndpointId) -> Reply { + fn issue(&self, store: &Store, endpoint: EndpointId) -> Reply { let internal = |err: crate::Error| ErrorReply::new(ErrorCode::ServerError, err.to_string()); let now = moq_clock::wall(); // `exp` is whole seconds on the wire; truncate so the reply matches the token. @@ -618,14 +622,12 @@ impl Coordinator { .unwrap_or_default() .as_secs(); let expires = moq_clock::Wall::UNIX_EPOCH.saturating_add(Duration::from_secs(secs) + self.config.token_ttl); - let claims = Claims::default() - .with_publish([endpoint.publish()]) - .with_subscribe([Pattern::subtree("mesh").expect("a valid path")]) - .with_issued(now) - .with_expires(expires); - let token = self.config.key.sign(&claims).map_err(internal)?; - let device = inner - .store + let token = self + .config + .key + .sign(&claims(endpoint, now, Some(expires))) + .map_err(internal)?; + let device = store .devices .iter() .find(|device| device.endpoint == endpoint) @@ -635,8 +637,7 @@ impl Coordinator { expires, relays: self.config.relays.clone(), name: device.name.clone(), - members: inner - .store + members: store .devices .iter() .filter(|device| !device.revoked) @@ -650,7 +651,7 @@ impl Coordinator { } /// Write the store atomically: a temporary file beside it, renamed over it. - fn save(&self, inner: &Inner) -> Reply<()> { + fn save(&self, store: &Store) -> Reply<()> { let Some(path) = &self.config.state else { return Ok(()); }; @@ -658,13 +659,33 @@ impl Coordinator { tracing::error!(path = %path.display(), %err, "failed to save the mesh state"); ErrorReply::new(ErrorCode::ServerError, "the coordinator could not save its state") }; - let json = serde_json::to_string_pretty(&inner.store).expect("the store serializes"); + let json = serde_json::to_string_pretty(store).expect("the store serializes"); let tmp = path.with_extension("tmp"); crate::fs::write_private(&tmp, &json).map_err(failed)?; std::fs::rename(&tmp, path).map_err(failed) } } +fn refuse_revoked(store: &Store, endpoint: EndpointId) -> Reply<()> { + if store + .devices + .iter() + .any(|device| device.endpoint == endpoint && device.revoked) + { + return Err(ErrorReply::new(ErrorCode::AccessDenied, "the device is revoked")); + } + Ok(()) +} + +/// The grant every mesh token carries: publish under its own ID, subscribe to the mesh. +fn claims(endpoint: EndpointId, issued: moq_clock::Wall, expires: Option) -> Claims { + Claims::default() + .with_publish([endpoint.publish()]) + .with_subscribe([Pattern::subtree("mesh").expect("a valid path")]) + .with_issued(issued) + .with_expires(expires) +} + /// `name` as one DNS label: lowercase ASCII letters, digits, and inner hyphens, at most /// 63 bytes, `device` when nothing is left. fn sanitize(name: &str) -> String { From 5c29a2cce6969eeebbee0727c600125deb9f66d9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 12:53:12 -0700 Subject: [PATCH 4/9] feat(auth): z-base-32 endpoint IDs Endpoint IDs share one text form with moq-sign (moq-dev/moq#7092): 52 lowercase z-base-32 characters, the form pkarr and iroh's DNS discovery use, which is also a valid DNS label. Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 1 + Cargo.toml | 1 + doc/bin/relay/auth.md | 2 +- rs/moq-auth/Cargo.toml | 1 + rs/moq-auth/src/mesh/mod.rs | 52 ++++++++++++++++++++++++------------- 5 files changed, 38 insertions(+), 19 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index d268b93829b..5de4351132c 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -5179,6 +5179,7 @@ dependencies = [ "aws-lc-rs", "axum", "base64 0.23.1", + "data-encoding", "jsonwebtoken", "kio 0.6.2", "moq-auth 0.2.1", diff --git a/Cargo.toml b/Cargo.toml index de4f1c52b45..0762c8a7be9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -106,6 +106,7 @@ clap = { version = "4", features = ["derive"] } # CUDA driver bindings for the NVENC/NVDEC path. dlopen'd at runtime # (`fallback-dynamic-loading`), so nothing links against libcuda at build time. cudarc = { version = "0.19", default-features = false, features = ["driver", "fallback-dynamic-loading", "cuda-12020"] } +data-encoding = "2.11" dispatch2 = "0.3.1" ebml-iterable = "0.7.1" flate2 = { version = "1.1", default-features = false } diff --git a/doc/bin/relay/auth.md b/doc/bin/relay/auth.md index 527b27c9799..785a752d199 100644 --- a/doc/bin/relay/auth.md +++ b/doc/bin/relay/auth.md @@ -364,7 +364,7 @@ its own. 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 -lowercase hex. It is verified like any other token, so the verifying keys +z-base-32 (52 characters, the form pkarr and iroh's DNS discovery use). It is verified like any other token, so the verifying keys (`--key`, `--key-dir`, or `--key-set`) must include `--mesh-key`'s public half. ```bash diff --git a/rs/moq-auth/Cargo.toml b/rs/moq-auth/Cargo.toml index 054ecd5e76e..24e016446e7 100644 --- a/rs/moq-auth/Cargo.toml +++ b/rs/moq-auth/Cargo.toml @@ -20,6 +20,7 @@ serve = ["dep:axum", "dep:tokio", "dep:tracing", "tokio/net"] aws-lc-rs = { workspace = true } axum = { workspace = true, optional = true } base64 = { workspace = true } +data-encoding = { workspace = true } jsonwebtoken = { workspace = true, features = ["aws_lc_rs"] } kio = { workspace = true } moq-clock = { version = "0.11.0", path = "../moq-clock", default-features = false, features = ["serde"] } diff --git a/rs/moq-auth/src/mesh/mod.rs b/rs/moq-auth/src/mesh/mod.rs index 0c89899a0c1..bf476e1880f 100644 --- a/rs/moq-auth/src/mesh/mod.rs +++ b/rs/moq-auth/src/mesh/mod.rs @@ -49,10 +49,20 @@ pub const CHALLENGE_LEN: usize = 32; const KEY_LEN: usize = 32; const SIGNATURE_LEN: usize = 64; +/// z-base-32: most significant bit first, no padding, trailing bits must be zero. +static ZBASE32: std::sync::LazyLock = std::sync::LazyLock::new(|| { + let mut spec = data_encoding::Specification::new(); + spec.symbols.push_str("ybndrfg8ejkmcpqxot1uwisza345h769"); + spec.encoding().expect("a valid z-base-32 specification") +}); + /// An endpoint's Ed25519 public key, which is also its endpoint ID. /// -/// Its text form is the 64-character lowercase hex of the key, the form iroh displays. -/// Parsing accepts only that form, so one key names exactly one `mesh/` path. +/// Its text form is the 52-character [z-base-32] of the key, the form pkarr and iroh's DNS +/// discovery use, which is also a valid DNS label. Parsing accepts only that form (lowercase, +/// zero trailing bits), so one key names exactly one `mesh/` path. +/// +/// [z-base-32]: https://philzimmermann.com/docs/human-oriented-base-32-encoding.txt #[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)] pub struct EndpointId([u8; KEY_LEN]); @@ -77,13 +87,13 @@ impl EndpointId { /// The broadcasts this endpoint may publish: `mesh//**`. pub fn publish(&self) -> crate::Pattern { - crate::Pattern::subtree(&format!("mesh/{self}")).expect("a hex segment is a valid path") + crate::Pattern::subtree(&format!("mesh/{self}")).expect("a z-base-32 segment is a valid path") } } -/// The text is not the 64-character lowercase hex of a 32-byte key. +/// The text is not the 52-character z-base-32 of a 32-byte key. #[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)] -#[error("invalid endpoint ID: expected 64 lowercase hex characters")] +#[error("invalid endpoint ID: expected 52 z-base-32 characters")] #[non_exhaustive] pub struct InvalidEndpoint; @@ -91,24 +101,19 @@ impl FromStr for EndpointId { type Err = InvalidEndpoint; fn from_str(text: &str) -> Result { - // Uppercase is refused so a key has one text form. - if text.len() != KEY_LEN * 2 || !text.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f')) { - return Err(InvalidEndpoint); - } + // The alphabet is lowercase-only and nonzero trailing bits are refused, so a key has one text form. let mut out = [0u8; KEY_LEN]; - for (i, byte) in out.iter_mut().enumerate() { - *byte = u8::from_str_radix(&text[i * 2..i * 2 + 2], 16).map_err(|_| InvalidEndpoint)?; - } + match ZBASE32.decode_len(text.len()) { + Ok(KEY_LEN) => ZBASE32.decode_mut(text.as_bytes(), &mut out).map_err(|_| InvalidEndpoint)?, + _ => return Err(InvalidEndpoint), + }; Ok(Self(out)) } } impl fmt::Display for EndpointId { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - for byte in self.0 { - write!(f, "{byte:02x}")?; - } - Ok(()) + f.write_str(&ZBASE32.encode(&self.0)) } } @@ -383,13 +388,24 @@ mod tests { fn endpoint_ids_have_one_text_form() { let id = signer().endpoint(); let text = id.to_string(); - assert_eq!(text.len(), 64); + assert_eq!(text.len(), 52); assert_eq!(text.parse::().unwrap(), id); assert!(text.to_uppercase().parse::().is_err()); - assert!(text[..62].parse::().is_err()); + assert!(text[..51].parse::().is_err()); + assert!(format!("{text}y").parse::().is_err()); + assert!(data_encoding::HEXLOWER.encode(id.as_bytes()).parse::().is_err()); assert_eq!(id.publish().as_str(), format!("mesh/{text}/**")); } + #[test] + fn endpoint_ids_are_z_base_32() { + assert_eq!(EndpointId::from_bytes([0; KEY_LEN]).to_string(), "y".repeat(52)); + let ones = EndpointId::from_bytes([0xff; KEY_LEN]); + assert_eq!(ones.to_string(), format!("{}o", "9".repeat(51))); + // The last character carries 4 padding bits, which must be zero. + assert!(format!("{}9", "9".repeat(51)).parse::().is_err()); + } + #[test] fn a_proof_is_bound_to_its_coordinator() { let key = signer(); From f1b9fef68fbde2a68a2b3155476a743376a553e5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 12:56:16 -0700 Subject: [PATCH 5/9] style(auth): rustfmt the endpoint ID parser Co-Authored-By: Claude Opus 5.5 --- rs/moq-auth/src/mesh/mod.rs | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/rs/moq-auth/src/mesh/mod.rs b/rs/moq-auth/src/mesh/mod.rs index bf476e1880f..0e9ab8b0a86 100644 --- a/rs/moq-auth/src/mesh/mod.rs +++ b/rs/moq-auth/src/mesh/mod.rs @@ -104,7 +104,9 @@ impl FromStr for EndpointId { // The alphabet is lowercase-only and nonzero trailing bits are refused, so a key has one text form. let mut out = [0u8; KEY_LEN]; match ZBASE32.decode_len(text.len()) { - Ok(KEY_LEN) => ZBASE32.decode_mut(text.as_bytes(), &mut out).map_err(|_| InvalidEndpoint)?, + Ok(KEY_LEN) => ZBASE32 + .decode_mut(text.as_bytes(), &mut out) + .map_err(|_| InvalidEndpoint)?, _ => return Err(InvalidEndpoint), }; Ok(Self(out)) @@ -393,7 +395,12 @@ mod tests { assert!(text.to_uppercase().parse::().is_err()); assert!(text[..51].parse::().is_err()); assert!(format!("{text}y").parse::().is_err()); - assert!(data_encoding::HEXLOWER.encode(id.as_bytes()).parse::().is_err()); + assert!( + data_encoding::HEXLOWER + .encode(id.as_bytes()) + .parse::() + .is_err() + ); assert_eq!(id.publish().as_str(), format!("mesh/{text}/**")); } From 017e31835af02d358eeeecfa3d34de9abe68b0a3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 13:42:42 -0700 Subject: [PATCH 6/9] fix(auth): retry a refresh whose challenge was evicted Challenges and device grants are public and bounded in memory, so a flood can evict a device's challenge before its proof lands. renew now retries invalid_challenge and slow_down like a server error, and the docs ask the fronting proxy to rate-limit each client. Co-Authored-By: Claude Opus 5.5 --- doc/bin/relay/auth.md | 4 ++- rs/moq-auth/src/mesh/client.rs | 12 +++++++-- rs/moq-auth/src/mesh/contract_tests.rs | 36 ++++++++++++++++++++++++++ 3 files changed, 49 insertions(+), 3 deletions(-) diff --git a/doc/bin/relay/auth.md b/doc/bin/relay/auth.md index 785a752d199..3556c979ba1 100644 --- a/doc/bin/relay/auth.md +++ b/doc/bin/relay/auth.md @@ -388,7 +388,9 @@ revoked device cannot enroll again. Each enrollment and refresh also returns every member's unique, DNS-safe name, defaulting to the device's hostname. The device-facing API on `--mesh-listen` is meant to be public behind a TLS -proxy, since devices refuse plain `http://` beyond loopback. The owner's +proxy, since devices refuse plain `http://` beyond loopback. Challenges and +device grants are issued without a credential and bounded in memory (4096 +challenges, 256 pending grants), so the proxy should rate-limit each client. The owner's commands go to `--listen`, which stays private. A hosted coordinator implements the same JSON contract, documented in [`moq_auth::mesh`](https://docs.rs/moq-auth/latest/moq_auth/mesh/); it adds diff --git a/rs/moq-auth/src/mesh/client.rs b/rs/moq-auth/src/mesh/client.rs index 32d982d2aa9..a7ef870dda1 100644 --- a/rs/moq-auth/src/mesh/client.rs +++ b/rs/moq-auth/src/mesh/client.rs @@ -113,7 +113,8 @@ impl Client { /// Wait until `current` is two thirds through its remaining life, then refresh it, /// retrying through an outage until it expires. A refusal is returned at once, so a - /// revoked device stops rather than retrying. + /// revoked device stops rather than retrying, except a transient one: a server error, + /// `slow_down`, or a challenge that expired or was evicted before the proof arrived. pub async fn renew(&self, current: &Enrollment) -> crate::Result { let remaining = || { current @@ -126,7 +127,14 @@ impl Client { let mut backoff = Duration::from_secs(1); loop { match self.refresh().await { - Err(Error::Mesh(reply)) if reply.error != ErrorCode::ServerError => return Err(Error::Mesh(reply)), + Err(Error::Mesh(reply)) + if !matches!( + reply.error, + ErrorCode::ServerError | ErrorCode::SlowDown | ErrorCode::InvalidChallenge + ) => + { + return Err(Error::Mesh(reply)); + } Ok(enrollment) => return Ok(enrollment), Err(err) if remaining().is_zero() => return Err(err), Err(err) => { diff --git a/rs/moq-auth/src/mesh/contract_tests.rs b/rs/moq-auth/src/mesh/contract_tests.rs index c060b14ffa8..107392ec390 100644 --- a/rs/moq-auth/src/mesh/contract_tests.rs +++ b/rs/moq-auth/src/mesh/contract_tests.rs @@ -226,6 +226,42 @@ async fn renew_refreshes_before_expiry() { assert!(renewed.expires > enrollment.expires); } +#[tokio::test] +async fn renew_retries_an_evicted_challenge() { + use wiremock::matchers::{method, path}; + use wiremock::{Mock, MockServer, ResponseTemplate}; + + let mesh = Mesh::with_ttl(Duration::from_secs(3)).await; + let signer = Arc::new(Ed25519KeyPair::generate().unwrap()); + let device = Client::new(mesh.base.clone(), signer.clone()).unwrap(); + let enrollment = device.enroll(&mesh.key(true), None).await.unwrap(); + let fresh = device.refresh().await.unwrap(); + + // A coordinator whose challenge is evicted before the first refresh arrives. + let server = MockServer::start().await; + Mock::given(method("POST")) + .and(path("/mesh/challenge")) + .respond_with(ResponseTemplate::new(200).set_body_json(mesh.coordinator.challenge())) + .mount(&server) + .await; + Mock::given(method("POST")) + .and(path("/mesh/refresh")) + .respond_with(ResponseTemplate::new(400).set_body_json(ErrorReply::new(ErrorCode::InvalidChallenge, "evicted"))) + .up_to_n_times(1) + .with_priority(1) + .mount(&server) + .await; + Mock::given(method("POST")) + .and(path("/mesh/refresh")) + .respond_with(ResponseTemplate::new(200).set_body_json(&fresh)) + .mount(&server) + .await; + + let device = Client::new(format!("{}/mesh", server.uri()).parse().unwrap(), signer).unwrap(); + let renewed = device.renew(&enrollment).await.unwrap(); + assert_eq!(renewed, fresh); +} + #[test] fn a_key_that_cannot_sign_refuses_to_start() { let key = Key::generate(Algorithm::ES256, None).unwrap().to_public().unwrap(); From 132cac5b9dfe5dc4d1ad4208c1451d76ddfc38de Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 14:26:52 -0700 Subject: [PATCH 7/9] feat(auth)!: enroll by key only, with stateless challenges Maintainer decision 2026-10-30: mesh enrollment is automated with no human in the loop, so the RFC 8628 device grant goes: its endpoints, pending table, user codes, client methods, and the `moq auth mesh pending|approve|deny` commands. Challenges are now sealed with an in-memory HMAC secret instead of stored, so unauthenticated requests cannot evict one a device is still signing. A used challenge is remembered until it expires; when that table is full, proofs get slow_down rather than dropping anything. Co-Authored-By: Claude Opus 5.5 --- doc/bin/relay/auth.md | 20 +- doc/lib/rs/moq-auth.md | 2 +- quest/m2/mesh/README.md | 4 + quest/m2/mesh/daemon.md | 5 +- rs/moq-auth/src/mesh/client.rs | 45 +--- rs/moq-auth/src/mesh/contract_tests.rs | 77 +++--- rs/moq-auth/src/mesh/coordinator.rs | 354 ++++++------------------- rs/moq-auth/src/mesh/mod.rs | 58 +--- rs/moq-cli/src/auth.rs | 25 +- 9 files changed, 138 insertions(+), 452 deletions(-) diff --git a/doc/bin/relay/auth.md b/doc/bin/relay/auth.md index 3556c979ba1..ff9cc88e1ea 100644 --- a/doc/bin/relay/auth.md +++ b/doc/bin/relay/auth.md @@ -364,33 +364,33 @@ its own. 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 verified like any other token, so the verifying keys -(`--key`, `--key-dir`, or `--key-set`) must include `--mesh-key`'s public half. +z-base-32 (52 characters, the form pkarr and iroh's DNS discovery use). It is +verified like any other token, so the verifying keys (`--key`, `--key-dir`, +or `--key-set`) must include `--mesh-key`'s public half. ```bash moq auth serve --key-dir /etc/moq/keys \ --mesh-url https://mesh.example.com --mesh-listen 127.0.0.1:4441 \ --mesh-key /etc/moq/mesh.jwk --mesh-state /var/lib/moq/mesh.json \ --mesh-relay https://relay.example.com -moq auth mesh create-key --tag robot --reusable --expires 7d # headless fleets -moq auth mesh approve BCDF-GHJK # a human's device grant +moq auth mesh create-key --tag robot --reusable --expires 7d moq auth mesh revoke ``` Every request proves the endpoint key by signing a fresh, single-use challenge bound to `--mesh-url`, so no token is issued for a key the caller -does not hold. A device joins with an enrollment key (single-use unless -`--reusable`; revoked or expired keys enroll nothing) or through an RFC 8628 -device grant the owner approves by its user code. It refreshes its token +does not hold. A device joins with an enrollment key, with no human in the +loop (single-use unless `--reusable`; revoked or expired keys enroll +nothing). It refreshes its token two thirds of the way through `--mesh-token-ttl` (default 1h) by proving the key again, so a revoked device is cut off within one token lifetime. A revoked device cannot enroll again. Each enrollment and refresh also returns every member's unique, DNS-safe name, defaulting to the device's hostname. The device-facing API on `--mesh-listen` is meant to be public behind a TLS -proxy, since devices refuse plain `http://` beyond loopback. Challenges and -device grants are issued without a credential and bounded in memory (4096 -challenges, 256 pending grants), so the proxy should rate-limit each client. The owner's +proxy, since devices refuse plain `http://` beyond loopback. A challenge holds +no state until a proof uses it, so unauthenticated requests cannot crowd out a +device's; the proxy should still rate-limit each client. The owner's commands go to `--listen`, which stays private. A hosted coordinator implements the same JSON contract, documented in [`moq_auth::mesh`](https://docs.rs/moq-auth/latest/moq_auth/mesh/); it adds diff --git a/doc/lib/rs/moq-auth.md b/doc/lib/rs/moq-auth.md index b80bd8411e3..d3b3e3488ad 100644 --- a/doc/lib/rs/moq-auth.md +++ b/doc/lib/rs/moq-auth.md @@ -18,7 +18,7 @@ accept loop that decides in process. - **Refusals.** `Refusal` carries a `refusal::Reason` (`Refused`, `Forbidden`, or `Expired`) and optional `root` and `tier`. An auth server returns it as JSON with HTTP 403; `Client` returns `Error::Refused(refusal)`. Legacy plain-text 401/403 bodies and unknown reason strings read as `Refused`. Set `root` only from a verified credential, never the dialed path. Embedded relay deciders pass the same shape in `auth::Error::Refused`. - **Client.** `Client` drives a lease against an auth server over `https://`, `unix://`, or loopback `http://`. It revalidates on cadence and retries through an outage until the grant expires, revokes on a 401, 403, or invalid grant, and reports `end` with the session's byte totals. - **Server** (feature `serve`). `serve::Server` is the reference auth server behind `moq auth serve`: JWTs from the query or the moq-transport SETUP token, certificate grants, anonymous rules, tiers, and session caps. `Server::router` mounts it in your own axum service. -- **Mesh enrollment.** `mesh` holds the [enrollment contract](/bin/relay/auth#mesh-enrollment): a device proves its Ed25519 endpoint key against a fresh challenge and receives relay URLs and a scoped token. `mesh::Client` (feature `client`) enrolls by key or device grant and renews before expiry; `mesh::Coordinator` (feature `serve`) answers it. +- **Mesh enrollment.** `mesh` holds the [enrollment contract](/bin/relay/auth#mesh-enrollment): a device proves its Ed25519 endpoint key against a fresh challenge and receives relay URLs and a scoped token. `mesh::Client` (feature `client`) enrolls with an enrollment key and renews before expiry; `mesh::Coordinator` (feature `serve`) answers it. - **Keys and claims.** Generate HMAC, RSA, ECDSA, or EdDSA keys as JWKs, sign `Claims` (`root`, `publish`, `subscribe`, `exp`), and verify them. `Claims::authorize(path)` scopes verified claims to the path a client dialed, exactly as `moq auth serve` does. Roles hold path pattern unions directly. ```bash diff --git a/quest/m2/mesh/README.md b/quest/m2/mesh/README.md index d580d7d7286..039848b3b0a 100644 --- a/quest/m2/mesh/README.md +++ b/quest/m2/mesh/README.md @@ -44,6 +44,10 @@ Decided 2026-10-25 with the maintainer (planning interview): already runs as a relay node. - Services are opt-in and named; nothing is exposed by default and sshd's own authentication still applies. +- Enrollment is automated, with no human in the loop (decided 2026-10-30): a + device presents an enrollment key the owner created (single-use or reusable, + tagged, expiring) and then refreshes by proving its key. There is no OAuth + device grant. - Robots are a primary use case: aarch64 builds, headless enrollment, and flapping uplinks are acceptance criteria, not follow-ups. - Upstream exposes an iroh-shaped Rust API (not wire-compatible with iroh), and diff --git a/quest/m2/mesh/daemon.md b/quest/m2/mesh/daemon.md index 40b3979bfd9..f6e6643ab73 100644 --- a/quest/m2/mesh/daemon.md +++ b/quest/m2/mesh/daemon.md @@ -22,8 +22,9 @@ the epic's first shippable outcome. configure. - Nothing is served unless `serve` names it. A restart keeps the endpoint key and enrollment, so a node never re-enrolls on its own. -- Enroll and renew with `moq_auth::mesh::Client`, signing with the endpoint key - through its `Signer` trait, and pass the hostname as the default name. The +- Enroll with an enrollment key and renew with `moq_auth::mesh::Client`, + signing with the endpoint key through its `Signer` trait, and pass the + hostname as the default name. The contract is in `doc/bin/relay/auth.md#mesh-enrollment`. - Update `doc/bin/cli.md` inline. diff --git a/rs/moq-auth/src/mesh/client.rs b/rs/moq-auth/src/mesh/client.rs index a7ef870dda1..ede600020ea 100644 --- a/rs/moq-auth/src/mesh/client.rs +++ b/rs/moq-auth/src/mesh/client.rs @@ -5,10 +5,7 @@ use std::time::Duration; use url::Url; -use super::{ - Challenge, DeviceAuthorization, DeviceRequest, DeviceTokenRequest, EnrollRequest, Enrollment, ErrorCode, - ErrorReply, Proof, Signer, -}; +use super::{Challenge, EnrollRequest, Enrollment, ErrorCode, ErrorReply, Proof, Signer}; use crate::Error; /// Every request is bounded so a hung coordinator fails rather than parks the device. @@ -17,9 +14,6 @@ const TIMEOUT: Duration = Duration::from_secs(10); /// The largest reply read from the coordinator; a mesh's member list fits easily. const MAX_REPLY: usize = 4 << 20; -/// How much a `slow_down` adds to the polling interval (RFC 8628 §3.5). -const SLOW_DOWN: Duration = Duration::from_secs(5); - /// The longest wait between refresh attempts while the coordinator is unreachable. const MAX_BACKOFF: Duration = Duration::from_secs(60); @@ -69,41 +63,6 @@ impl Client { self.post("enroll", &request).await } - /// Start a device grant, asking for `name`. Show the human its `user_code` and - /// `verification_uri`, then [`poll`](Self::poll). - pub async fn device(&self, name: Option<&str>) -> crate::Result { - let proof = self.proof().await?; - let request = DeviceRequest { - proof, - name: name.map(Into::into), - }; - self.post("device", &request).await - } - - /// Wait for a human to approve the device grant, polling at its interval. Fails with - /// [`ErrorCode::AccessDenied`] when denied and [`ErrorCode::ExpiredToken`] when it - /// times out. - pub async fn poll(&self, authorization: &DeviceAuthorization) -> crate::Result { - let mut interval = Duration::from_secs(authorization.interval); - let request = DeviceTokenRequest { - device_code: authorization.device_code.clone(), - }; - loop { - moq_clock::sleep(interval).await; - match self.post("device/token", &request).await { - Err(Error::Mesh(ErrorReply { - error: ErrorCode::AuthorizationPending, - .. - })) => {} - Err(Error::Mesh(ErrorReply { - error: ErrorCode::SlowDown, - .. - })) => interval += SLOW_DOWN, - other => return other, - } - } - } - /// Prove the key again for a fresh token. Fails with [`ErrorCode::AccessDenied`] once /// the device is revoked. pub async fn refresh(&self) -> crate::Result { @@ -114,7 +73,7 @@ impl Client { /// Wait until `current` is two thirds through its remaining life, then refresh it, /// retrying through an outage until it expires. A refusal is returned at once, so a /// revoked device stops rather than retrying, except a transient one: a server error, - /// `slow_down`, or a challenge that expired or was evicted before the proof arrived. + /// `slow_down`, or a challenge that expired or outlived a coordinator restart. pub async fn renew(&self, current: &Enrollment) -> crate::Result { let remaining = || { current diff --git a/rs/moq-auth/src/mesh/contract_tests.rs b/rs/moq-auth/src/mesh/contract_tests.rs index 107392ec390..11478efb0d3 100644 --- a/rs/moq-auth/src/mesh/contract_tests.rs +++ b/rs/moq-auth/src/mesh/contract_tests.rs @@ -27,7 +27,6 @@ impl Mesh { let key = Key::generate(Algorithm::HS256, Some(KeyId::decode("mesh").unwrap())).unwrap(); let mut config = Config::new(base.clone(), key.clone()); config.relays = vec!["https://relay.example".parse().unwrap()]; - config.device_interval = Duration::ZERO; config.token_ttl = ttl; let coordinator = Coordinator::new(config).unwrap(); let router = coordinator.router(); @@ -130,9 +129,10 @@ async fn a_proof_from_the_wrong_key_is_refused() { ErrorCode::InvalidSignature ); - // The challenge is spent, so even the honest retry needs a new one. + // A forged proof spends nothing, so the holder can still use the challenge, once. let mut request = request; request.proof = Proof::sign(&holder, &mesh.base, request.proof.challenge); + mesh.coordinator.enroll(&request).unwrap(); assert_eq!( mesh.coordinator.enroll(&request).unwrap_err().error, ErrorCode::InvalidChallenge @@ -151,47 +151,6 @@ async fn a_proof_from_the_wrong_key_is_refused() { ); } -#[tokio::test] -async fn a_device_grant_waits_for_approval() { - let mesh = Mesh::new().await; - let device = mesh.device(); - let authorization = device.device(Some("laptop")).await.unwrap(); - assert_eq!(authorization.verification_uri.path(), "/mesh/device"); - - let pending = mesh.coordinator.pending(); - assert_eq!(pending.len(), 1); - assert_eq!(pending[0].user_code, authorization.user_code); - - let poll = tokio::spawn({ - let device = device.clone(); - let authorization = authorization.clone(); - async move { device.poll(&authorization).await } - }); - moq_clock::sleep(Duration::from_millis(50)).await; - assert!(!poll.is_finished()); - - assert!(mesh.coordinator.decide(&authorization.user_code.to_lowercase(), true)); - let enrollment = poll.await.unwrap().unwrap(); - assert_eq!(enrollment.name, "laptop"); - assert!(mesh.coordinator.pending().is_empty()); - - // The device code is spent once it is exchanged. - let err = device.poll(&authorization).await.unwrap_err(); - assert_eq!(Mesh::refused(err), ErrorCode::ExpiredToken); -} - -#[tokio::test] -async fn a_denied_device_grant_enrolls_nothing() { - let mesh = Mesh::new().await; - let device = mesh.device(); - let authorization = device.device(None).await.unwrap(); - assert!(mesh.coordinator.decide(&authorization.user_code, false)); - assert!(!mesh.coordinator.decide(&authorization.user_code, true)); - let err = device.poll(&authorization).await.unwrap_err(); - assert_eq!(Mesh::refused(err), ErrorCode::AccessDenied); - assert!(mesh.coordinator.devices().is_empty()); -} - #[tokio::test] async fn refresh_issues_a_new_token_until_revoked() { let mesh = Mesh::new().await; @@ -227,7 +186,31 @@ async fn renew_refreshes_before_expiry() { } #[tokio::test] -async fn renew_retries_an_evicted_challenge() { +async fn only_an_issued_challenge_is_accepted() { + let mesh = Mesh::new().await; + let holder = Ed25519KeyPair::generate().unwrap(); + let enroll = |challenge: Vec| { + let request = EnrollRequest { + proof: Proof::sign(&holder, &mesh.base, challenge), + key: mesh.key(true), + name: None, + }; + mesh.coordinator.enroll(&request).unwrap_err().error + }; + + // Made up, tampered with, or issued before a restart (another secret). + assert_eq!(enroll(vec![7; CHALLENGE_LEN]), ErrorCode::InvalidChallenge); + let mut tampered = mesh.coordinator.challenge().challenge; + tampered[0] ^= 1; + assert_eq!(enroll(tampered), ErrorCode::InvalidChallenge); + let mut config = Config::new(mesh.base.clone(), mesh.key.clone()); + config.relays = vec!["https://relay.example".parse().unwrap()]; + let restarted = Coordinator::new(config).unwrap(); + assert_eq!(enroll(restarted.challenge().challenge), ErrorCode::InvalidChallenge); +} + +#[tokio::test] +async fn renew_retries_a_transient_refusal() { use wiremock::matchers::{method, path}; use wiremock::{Mock, MockServer, ResponseTemplate}; @@ -237,7 +220,7 @@ async fn renew_retries_an_evicted_challenge() { let enrollment = device.enroll(&mesh.key(true), None).await.unwrap(); let fresh = device.refresh().await.unwrap(); - // A coordinator whose challenge is evicted before the first refresh arrives. + // A coordinator that restarts between issuing the challenge and seeing the proof. let server = MockServer::start().await; Mock::given(method("POST")) .and(path("/mesh/challenge")) @@ -246,7 +229,9 @@ async fn renew_retries_an_evicted_challenge() { .await; Mock::given(method("POST")) .and(path("/mesh/refresh")) - .respond_with(ResponseTemplate::new(400).set_body_json(ErrorReply::new(ErrorCode::InvalidChallenge, "evicted"))) + .respond_with( + ResponseTemplate::new(400).set_body_json(ErrorReply::new(ErrorCode::InvalidChallenge, "unknown challenge")), + ) .up_to_n_times(1) .with_priority(1) .mount(&server) diff --git a/rs/moq-auth/src/mesh/coordinator.rs b/rs/moq-auth/src/mesh/coordinator.rs index 435e5c6a7f6..0df600f8329 100644 --- a/rs/moq-auth/src/mesh/coordinator.rs +++ b/rs/moq-auth/src/mesh/coordinator.rs @@ -3,8 +3,8 @@ //! [`Coordinator::router`] answers the device-facing contract; [`Coordinator::admin_router`] //! is the owner's API, mounted on the auth server's own listener, which has no //! authentication and stays on loopback. Enrollment keys and devices persist to a JSON -//! state file; challenges and pending device grants live in memory, so a restart only -//! makes a device fetch a new challenge or start its grant again. +//! state file. Challenges are sealed with a secret held in memory, so a restart only makes +//! a device fetch a new challenge. use std::collections::HashMap; use std::path::PathBuf; @@ -16,29 +16,22 @@ use axum::http::StatusCode; use axum::response::{IntoResponse, Response}; use axum::routing::{delete, get, post}; use axum::{Json, Router}; -use moq_clock::Instant; use serde::{Deserialize, Serialize}; use serde_with::serde_as; -use super::{ - CHALLENGE_LEN, Challenge, DeviceAuthorization, DeviceRequest, DeviceTokenRequest, EndpointId, EnrollRequest, - Enrollment, ErrorCode, ErrorReply, Member, Proof, -}; +use super::{CHALLENGE_LEN, Challenge, EndpointId, EnrollRequest, Enrollment, ErrorCode, ErrorReply, Member, Proof}; use crate::{Claims, Key, Pattern}; /// How long a challenge stays valid. const CHALLENGE_TTL: Duration = Duration::from_secs(60); -/// The most challenges outstanding at once, so an unauthenticated caller cannot grow the -/// table without bound; the oldest is dropped first. -const MAX_CHALLENGES: usize = 4096; +/// The most unexpired challenges remembered as used. Past it, proofs are refused with +/// `slow_down` until the oldest expire; an outstanding challenge is never dropped. +const MAX_SPENT: usize = 65536; -/// The most device grants pending at once, for the same reason. -const MAX_PENDING: usize = 256; - -/// The alphabet of a user code: no vowels, so a code spells no word, and no -/// look-alikes (RFC 8628 §6.1). -const USER_CODE_ALPHABET: &[u8] = b"BCDFGHJKLMNPQRSTVWXZ"; +/// A challenge is its expiry (unix seconds), a nonce, then a truncated HMAC over both. +const NONCE_LEN: usize = 8; +const TAG_LEN: usize = CHALLENGE_LEN - 8 - NONCE_LEN; /// The longest a device name may be: one DNS label. const MAX_NAME: usize = 63; @@ -59,15 +52,11 @@ pub struct Config { pub state: Option, /// How long an issued token lasts. pub token_ttl: Duration, - /// How long a device grant waits for a human. - pub device_ttl: Duration, - /// The seconds a device waits between device grant polls. - pub device_interval: Duration, } impl Config { - /// A coordinator at `url` signing with `key`, with hour-long tokens, ten-minute device - /// grants polled every five seconds, no relays, and no state file. + /// A coordinator at `url` signing with `key`, with hour-long tokens, no relays, and no + /// state file. pub fn new(url: url::Url, key: Key) -> Self { Self { url, @@ -75,8 +64,6 @@ impl Config { relays: Vec::new(), state: None, token_ttl: Duration::from_secs(3600), - device_ttl: Duration::from_secs(600), - device_interval: Duration::from_secs(5), } } } @@ -181,47 +168,19 @@ pub struct NewKey { pub reusable: bool, } -/// A device grant waiting for a human, as the owner sees it. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] -#[non_exhaustive] -pub struct PendingDevice { - /// The code the device shows its human. - pub user_code: String, - /// The endpoint the grant would enroll. - pub endpoint: EndpointId, - /// The name the device asked for. - pub name: Option, -} - -#[derive(Clone, Copy, PartialEq, Eq)] -enum Decision { - Waiting, - Approved, - Denied, -} - -struct Pending { - user_code: String, - endpoint: EndpointId, - name: Option, - expires: Instant, - polled: Option, - decision: Decision, -} - #[derive(Default)] struct Inner { store: Store, - /// Outstanding challenges and when each was issued. - challenges: HashMap, Instant>, - /// Pending device grants, by the SHA-256 of their device code. - pending: HashMap, Pending>, + /// Challenges a valid proof already used, until each expires. + spent: HashMap, moq_clock::Wall>, } /// The mesh coordinator: issues challenges, enrolls devices, and refreshes their tokens. #[derive(Clone)] pub struct Coordinator { config: Arc, + /// Seals challenges, so an outstanding one needs no state. + secret: Arc, inner: Arc>, } @@ -245,6 +204,7 @@ impl Coordinator { .sign(&claims(EndpointId::from_bytes([0; 32]), moq_clock::wall(), None))?; Ok(Self { config: Arc::new(config), + secret: Arc::new(aws_lc_rs::hmac::Key::new(aws_lc_rs::hmac::HMAC_SHA256, &random(32))), inner: Arc::new(Mutex::new(Inner { store, ..Default::default() @@ -252,27 +212,21 @@ impl Coordinator { }) } - /// Issue a fresh challenge. + /// Issue a fresh challenge. It holds no state until a proof uses it, so no number of + /// requests can crowd out one a device is still signing. pub fn challenge(&self) -> Challenge { - let challenge = random(CHALLENGE_LEN); - let mut inner = self.inner.lock().unwrap(); - let now = Instant::now(); - inner - .challenges - .retain(|_, issued| now.saturating_duration_since(*issued) < CHALLENGE_TTL); - if inner.challenges.len() >= MAX_CHALLENGES - && let Some(oldest) = inner - .challenges - .iter() - .min_by_key(|(_, issued)| **issued) - .map(|(challenge, _)| challenge.clone()) - { - inner.challenges.remove(&oldest); - } - inner.challenges.insert(challenge.clone(), now); + let now = moq_clock::wall(); + let expires = + now.checked_duration_since(moq_clock::Wall::UNIX_EPOCH) + .unwrap_or_default() + .as_secs() + CHALLENGE_TTL.as_secs(); + let mut challenge = expires.to_be_bytes().to_vec(); + challenge.extend_from_slice(&random(NONCE_LEN)); + let tag = self.tag(&challenge); + challenge.extend_from_slice(&tag); Challenge { challenge, - expires: moq_clock::wall() + CHALLENGE_TTL, + expires: moq_clock::Wall::UNIX_EPOCH.saturating_add(Duration::from_secs(expires)), } } @@ -325,86 +279,6 @@ impl Coordinator { }) } - /// Start a device grant for a human to approve. - pub fn device(&self, request: &DeviceRequest) -> Reply { - let mut inner = self.inner.lock().unwrap(); - self.check(&mut inner, &request.proof)?; - refuse_revoked(&inner.store, request.proof.endpoint)?; - - let now = Instant::now(); - inner.pending.retain(|_, pending| pending.expires > now); - if inner.pending.len() >= MAX_PENDING { - return Err(ErrorReply::new( - ErrorCode::SlowDown, - "too many device grants are pending; try again later", - )); - } - - let device_code = encode(&random(32)); - let user_code = loop { - let code = user_code(); - if !inner.pending.values().any(|pending| pending.user_code == code) { - break code; - } - }; - inner.pending.insert( - sha256(device_code.as_bytes()), - Pending { - user_code: user_code.clone(), - endpoint: request.proof.endpoint, - name: request.name.clone(), - expires: now + self.config.device_ttl, - polled: None, - decision: Decision::Waiting, - }, - ); - - Ok(DeviceAuthorization { - device_code, - user_code, - verification_uri: self.verification_uri(), - expires_in: self.config.device_ttl.as_secs(), - interval: self.config.device_interval.as_secs(), - }) - } - - /// Poll a device grant: the enrollment once a human approves, a refusal until then. - pub fn device_token(&self, request: &DeviceTokenRequest) -> Reply { - let mut inner = self.inner.lock().unwrap(); - let hash = sha256(request.device_code.as_bytes()); - let now = Instant::now(); - let pending = inner - .pending - .get_mut(&hash) - .ok_or_else(|| ErrorReply::new(ErrorCode::ExpiredToken, "unknown or expired device code"))?; - if pending.expires <= now { - inner.pending.remove(&hash); - return Err(ErrorReply::new(ErrorCode::ExpiredToken, "the device grant expired")); - } - let fast = pending - .polled - .is_some_and(|polled| now.saturating_duration_since(polled) < self.config.device_interval); - pending.polled = Some(now); - match pending.decision { - Decision::Waiting if fast => Err(ErrorReply::new(ErrorCode::SlowDown, "polling faster than the interval")), - Decision::Waiting => Err(ErrorReply::new(ErrorCode::AuthorizationPending, "waiting for approval")), - Decision::Denied => { - inner.pending.remove(&hash); - Err(ErrorReply::new(ErrorCode::AccessDenied, "the device grant was denied")) - } - Decision::Approved => { - let (endpoint, name) = (pending.endpoint, pending.name.clone()); - // The grant stays redeemable until its enrollment is saved. - let enrollment = self.commit(&mut inner, |store| { - self.admit(store, endpoint, name.as_deref(), Vec::new())?; - self.issue(store, endpoint) - })?; - inner.pending.remove(&hash); - Ok(enrollment) - } - } - } - /// Refresh an enrolled device's token, refusing a revoked or unknown one. pub fn refresh(&self, proof: &Proof) -> Reply { let mut inner = self.inner.lock().unwrap(); @@ -485,45 +359,11 @@ impl Coordinator { Ok(found) } - /// The device grants waiting for a human. - pub fn pending(&self) -> Vec { - let mut inner = self.inner.lock().unwrap(); - let now = Instant::now(); - inner.pending.retain(|_, pending| pending.expires > now); - inner - .pending - .values() - .filter(|pending| pending.decision == Decision::Waiting) - .map(|pending| PendingDevice { - user_code: pending.user_code.clone(), - endpoint: pending.endpoint, - name: pending.name.clone(), - }) - .collect() - } - - /// Approve or deny the waiting device grant showing `user_code`. Returns whether one - /// was waiting. - pub fn decide(&self, user_code: &str, approve: bool) -> bool { - let user_code = normalize_user_code(user_code); - let mut inner = self.inner.lock().unwrap(); - let now = Instant::now(); - let Some(pending) = inner.pending.values_mut().find(|pending| { - pending.user_code == user_code && pending.decision == Decision::Waiting && pending.expires > now - }) else { - return false; - }; - pending.decision = if approve { Decision::Approved } else { Decision::Denied }; - true - } - /// The device-facing contract, mounted at [`Config::url`]'s path. pub fn router(&self) -> Router { let router = Router::new() .route("/challenge", post(challenge_handler)) .route("/enroll", post(enroll_handler)) - .route("/device", post(device_handler).get(verification_handler)) - .route("/device/token", post(device_token_handler)) .route("/refresh", post(refresh_handler)) .with_state(self.clone()); match self.config.url.path().trim_end_matches('/') { @@ -540,9 +380,6 @@ impl Coordinator { .route("/mesh/keys/{id}", delete(revoke_key_handler)) .route("/mesh/devices", get(devices_handler)) .route("/mesh/devices/{endpoint}", delete(revoke_device_handler)) - .route("/mesh/pending", get(pending_handler)) - .route("/mesh/pending/{code}/approve", post(approve_handler)) - .route("/mesh/pending/{code}/deny", post(deny_handler)) .with_state(self.clone()) } @@ -551,22 +388,22 @@ impl Coordinator { axum::serve(listener, self.router()).await } - fn verification_uri(&self) -> url::Url { - let mut url = self.config.url.clone(); - let path = format!("{}/device", url.path().trim_end_matches('/')); - url.set_path(&path); - url - } - - /// Consume the proof's challenge and verify its signature. + /// Verify the proof's challenge and signature, then spend the challenge. fn check(&self, inner: &mut Inner, proof: &Proof) -> Reply<()> { - // Consumed even when the signature fails, so one challenge is one attempt. - let issued = inner - .challenges - .remove(&proof.challenge) - .ok_or_else(|| ErrorReply::new(ErrorCode::InvalidChallenge, "unknown or used challenge"))?; - if Instant::now().saturating_duration_since(issued) >= CHALLENGE_TTL { - return Err(ErrorReply::new(ErrorCode::InvalidChallenge, "the challenge expired")); + let invalid = |reason: &str| ErrorReply::new(ErrorCode::InvalidChallenge, reason); + let challenge = &proof.challenge; + if challenge.len() != CHALLENGE_LEN + || !constant_eq( + &self.tag(&challenge[..CHALLENGE_LEN - TAG_LEN]), + &challenge[CHALLENGE_LEN - TAG_LEN..], + ) { + return Err(invalid("unknown challenge")); + } + let expires = u64::from_be_bytes(challenge[..8].try_into().expect("8 bytes")); + let expires = moq_clock::Wall::UNIX_EPOCH.saturating_add(Duration::from_secs(expires)); + let now = moq_clock::wall(); + if expires <= now { + return Err(invalid("the challenge expired")); } if !proof.verify(&self.config.url) { return Err(ErrorReply::new( @@ -574,9 +411,25 @@ impl Coordinator { "the signature does not verify against the endpoint ID", )); } + inner.spent.retain(|_, until| *until > now); + if inner.spent.contains_key(challenge) { + return Err(invalid("the challenge was already used")); + } + if inner.spent.len() >= MAX_SPENT { + return Err(ErrorReply::new( + ErrorCode::SlowDown, + "too many proofs at once; retry shortly", + )); + } + inner.spent.insert(challenge.clone(), expires); Ok(()) } + /// The truncated HMAC sealing a challenge's expiry and nonce. + fn tag(&self, body: &[u8]) -> Vec { + aws_lc_rs::hmac::sign(&self.secret, body).as_ref()[..TAG_LEN].to_vec() + } + /// Apply `change` to a copy of the store and save it, adopting the copy only once it /// is on disk, so a failed save leaves no credential spent and no device admitted. fn commit(&self, inner: &mut Inner, change: impl FnOnce(&mut Store) -> Reply) -> Reply { @@ -723,34 +576,6 @@ fn unique_name(devices: &[Device], endpoint: EndpointId, name: &str) -> String { .expect("an unbounded search finds a free name") } -/// Eight characters from [`USER_CODE_ALPHABET`] as `XXXX-XXXX`. -fn user_code() -> String { - let bytes = random(8); - let mut code = String::with_capacity(9); - for (i, byte) in bytes.iter().enumerate() { - if i == 4 { - code.push('-'); - } - // 256 is not a multiple of 20; the slight bias costs a fraction of a bit. - code.push(USER_CODE_ALPHABET[*byte as usize % USER_CODE_ALPHABET.len()] as char); - } - code -} - -/// A user code as typed: case and separators ignored, as RFC 8628 §6.1 advises. -fn normalize_user_code(code: &str) -> String { - let letters: String = code - .chars() - .filter(char::is_ascii_alphanumeric) - .map(|c| c.to_ascii_uppercase()) - .collect(); - if letters.len() == 8 { - format!("{}-{}", &letters[..4], &letters[4..]) - } else { - letters - } -} - /// base64url without padding, the encoding of every random secret in the contract. fn encode(bytes: &[u8]) -> String { use base64::Engine; @@ -813,24 +638,6 @@ async fn enroll_handler( coordinator.enroll(&request).map(Json) } -async fn device_handler( - State(coordinator): State, - Body(request): Body, -) -> Reply> { - coordinator.device(&request).map(Json) -} - -async fn verification_handler() -> &'static str { - "Ask the mesh owner to approve your device: moq auth mesh approve \n" -} - -async fn device_token_handler( - State(coordinator): State, - Body(request): Body, -) -> Reply> { - coordinator.device_token(&request).map(Json) -} - async fn refresh_handler(State(coordinator): State, Body(proof): Body) -> Reply> { coordinator.refresh(&proof).map(Json) } @@ -873,27 +680,6 @@ async fn revoke_device_handler(State(coordinator): State, Path(endp } } -async fn pending_handler(State(coordinator): State) -> Json> { - Json(coordinator.pending()) -} - -async fn approve_handler(State(coordinator): State, Path(code): Path) -> Response { - decide(&coordinator, &code, true) -} - -async fn deny_handler(State(coordinator): State, Path(code): Path) -> Response { - decide(&coordinator, &code, false) -} - -/// A known route's miss carries a body, so the CLI can tell it from a missing route. -fn decide(coordinator: &Coordinator, code: &str, approve: bool) -> Response { - if coordinator.decide(code, approve) { - StatusCode::NO_CONTENT.into_response() - } else { - (StatusCode::NOT_FOUND, "not found").into_response() - } -} - #[cfg(test)] mod tests { use super::*; @@ -930,10 +716,24 @@ mod tests { } #[test] - fn user_codes_read_back_however_typed() { - let code = user_code(); - assert_eq!(code.len(), 9); - assert_eq!(normalize_user_code(&code.to_lowercase().replace('-', " ")), code); + fn a_full_spent_table_refuses_without_forgetting() { + let key = Key::generate(Algorithm::HS256, None).unwrap(); + let base: url::Url = "https://mesh.example".parse().unwrap(); + let coordinator = Coordinator::new(Config::new(base.clone(), key)).unwrap(); + let signer = aws_lc_rs::signature::Ed25519KeyPair::generate().unwrap(); + let proof = Proof::sign(&signer, &base, coordinator.challenge().challenge); + + let later = moq_clock::wall() + CHALLENGE_TTL; + let mut inner = coordinator.inner.lock().unwrap(); + inner.spent = (0..MAX_SPENT as u64) + .map(|n| (n.to_be_bytes().to_vec(), later)) + .collect(); + let err = coordinator.check(&mut inner, &proof).unwrap_err(); + assert_eq!(err.error, ErrorCode::SlowDown); + + // Its challenge stays good once room frees up. + inner.spent.clear(); + coordinator.check(&mut inner, &proof).unwrap(); } #[test] diff --git a/rs/moq-auth/src/mesh/mod.rs b/rs/moq-auth/src/mesh/mod.rs index 0e9ab8b0a86..043146e6be8 100644 --- a/rs/moq-auth/src/mesh/mod.rs +++ b/rs/moq-auth/src/mesh/mod.rs @@ -1,8 +1,8 @@ //! Mesh enrollment: how a device with an endpoint key joins a mesh. //! //! A device proves it holds its Ed25519 endpoint key by signing a fresh challenge from -//! the coordinator, and presents a credential: a pre-authorized enrollment key, or a -//! device grant (RFC 8628) a human approved. The coordinator answers with an +//! 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 //! subscribe on `mesh/**`. The device refreshes it before it expires by proving its key //! again, so revoking a device makes its next refresh fail. @@ -15,8 +15,6 @@ //! |---|---|---| //! | `POST {base}/challenge` | none | [`Challenge`] | //! | `POST {base}/enroll` | [`EnrollRequest`] | [`Enrollment`] | -//! | `POST {base}/device` | [`DeviceRequest`] | [`DeviceAuthorization`] | -//! | `POST {base}/device/token` | [`DeviceTokenRequest`] | [`Enrollment`] | //! | `POST {base}/refresh` | [`Proof`] | [`Enrollment`] | //! //! Every refusal is a 4xx with an [`ErrorReply`]. @@ -164,7 +162,7 @@ fn audience(base: &url::Url) -> &str { #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] #[non_exhaustive] pub struct Challenge { - /// [`CHALLENGE_LEN`] random bytes, base64url without padding. + /// [`CHALLENGE_LEN`] bytes, opaque to the device, base64url without padding. #[serde_as(as = "serde_with::base64::Base64")] pub challenge: Vec, /// When the coordinator stops accepting a proof over it, unix seconds. @@ -254,42 +252,6 @@ pub struct EnrollRequest { pub name: Option, } -/// `POST {base}/device`: start a device grant (RFC 8628) for a human to approve. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] -#[non_exhaustive] -pub struct DeviceRequest { - /// Proof of the endpoint key, which the grant is bound to. - #[serde(flatten)] - pub proof: Proof, - /// The device's requested name, as in [`EnrollRequest::name`]. - #[serde(default, skip_serializing_if = "Option::is_none")] - pub name: Option, -} - -/// The device authorization response of RFC 8628 §3.2. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] -#[non_exhaustive] -pub struct DeviceAuthorization { - /// The secret the device polls `POST {base}/device/token` with. - pub device_code: String, - /// The code the human enters or reads out to approve the device. - pub user_code: String, - /// Where the human approves it. - pub verification_uri: url::Url, - /// Seconds until the codes expire. - pub expires_in: u64, - /// Seconds the device waits between polls. - pub interval: u64, -} - -/// `POST {base}/device/token`: poll a device grant. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] -#[non_exhaustive] -pub struct DeviceTokenRequest { - /// The code from the [`DeviceAuthorization`]. - pub device_code: String, -} - /// What a device needs to join: the relays to dial and the token to present. #[serde_as] #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] @@ -343,7 +305,7 @@ impl ErrorReply { } } -/// The reasons a coordinator refuses, the device grant ones from RFC 8628 §3.5. +/// The reasons a coordinator refuses. #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] #[non_exhaustive] @@ -356,14 +318,10 @@ pub enum ErrorCode { InvalidSignature, /// The enrollment key is unknown, used, revoked, or expired. InvalidGrant, - /// The human has not yet approved the device grant; poll again. - AuthorizationPending, - /// Polling too fast; wait longer between polls. + /// The coordinator is busy; retry shortly. SlowDown, - /// The human denied the device grant, or the device is revoked or not enrolled. + /// The device is revoked or not enrolled. AccessDenied, - /// The device grant expired; start a new one. - ExpiredToken, /// The coordinator failed on its side; retry later. ServerError, /// A reason this version does not know. @@ -429,8 +387,8 @@ mod tests { #[test] fn error_replies_read_unknown_codes() { - let reply: ErrorReply = serde_json::from_str(r#"{"error":"authorization_pending"}"#).unwrap(); - assert_eq!(reply.error, ErrorCode::AuthorizationPending); + let reply: ErrorReply = serde_json::from_str(r#"{"error":"access_denied"}"#).unwrap(); + assert_eq!(reply.error, ErrorCode::AccessDenied); let reply: ErrorReply = serde_json::from_str(r#"{"error":"new_thing","error_description":"x"}"#).unwrap(); assert_eq!(reply.error, ErrorCode::Unknown); assert_eq!(ErrorCode::SlowDown.to_string(), "slow_down"); diff --git a/rs/moq-cli/src/auth.rs b/rs/moq-cli/src/auth.rs index b672eb7186a..2d98441e1b1 100644 --- a/rs/moq-cli/src/auth.rs +++ b/rs/moq-cli/src/auth.rs @@ -199,7 +199,7 @@ enum Command { /// Answer a relay's auth requests with keys, public rules, an mTLS grant, tiers, and session limits. Serve(Serve), - /// Manage a mesh served by `moq auth serve --mesh-url`: enrollment keys, devices, and device grants. + /// Manage a mesh served by `moq auth serve --mesh-url`: enrollment keys and devices. Mesh(Mesh), /// List live sessions on a relay's internal listener. @@ -657,21 +657,6 @@ enum MeshCommand { /// The device's endpoint ID. endpoint: String, }, - - /// List device grants waiting for approval. - Pending, - - /// Approve the device grant showing this user code. - Approve { - /// The code the device shows, e.g. `BCDF-GHJK`. - code: String, - }, - - /// Deny the device grant showing this user code. - Deny { - /// The code the device shows. - code: String, - }, } impl Mesh { @@ -690,9 +675,6 @@ impl Mesh { MeshCommand::RevokeKey { id } => client.delete(self.url("/mesh/keys", &[id])), MeshCommand::Devices => client.get(self.url("/mesh/devices", &[])), MeshCommand::Revoke { endpoint } => client.delete(self.url("/mesh/devices", &[endpoint])), - MeshCommand::Pending => client.get(self.url("/mesh/pending", &[])), - MeshCommand::Approve { code } => client.post(self.url("/mesh/pending", &[code, "approve"])), - MeshCommand::Deny { code } => client.post(self.url("/mesh/pending", &[code, "deny"])), }; let response = request .send() @@ -705,9 +687,6 @@ impl Mesh { anyhow::bail!(match self.command { MeshCommand::RevokeKey { .. } if !body.is_empty() => "no enrollment key has that ID", MeshCommand::Revoke { .. } if !body.is_empty() => "no device has that endpoint ID", - MeshCommand::Approve { .. } | MeshCommand::Deny { .. } if !body.is_empty() => { - "no device grant is waiting with that code" - } _ => "not found; is the server running with --mesh-url?", }); } @@ -901,7 +880,7 @@ mod tests { "--expires", "1d", ][..], - &["moq", "auth", "mesh", "approve", "BCDF-GHJK"], + &["moq", "auth", "mesh", "devices"], &["moq", "auth", "mesh", "--url", "http://127.0.0.1:9000", "revoke", "ab"], ] { assert!(matches!(parse(args).unwrap().command, Command::Mesh(_)), "{args:?}"); From 56824a18d9e651c63852b17579c33301bbfba18a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 14:34:05 -0700 Subject: [PATCH 8/9] fix(auth): spend a challenge only once its request is granted A refused proof no longer takes room in the replay table, so callers with unenrolled keys cannot fill it and push enrolled devices into slow_down. The table is pruned only when full, not scanned per proof. Co-Authored-By: Claude Opus 5.5 --- rs/moq-auth/src/mesh/coordinator.rs | 50 ++++++++++++++++++----------- 1 file changed, 32 insertions(+), 18 deletions(-) diff --git a/rs/moq-auth/src/mesh/coordinator.rs b/rs/moq-auth/src/mesh/coordinator.rs index 0df600f8329..953b0f72598 100644 --- a/rs/moq-auth/src/mesh/coordinator.rs +++ b/rs/moq-auth/src/mesh/coordinator.rs @@ -25,8 +25,8 @@ use crate::{Claims, Key, Pattern}; /// How long a challenge stays valid. const CHALLENGE_TTL: Duration = Duration::from_secs(60); -/// The most unexpired challenges remembered as used. Past it, proofs are refused with -/// `slow_down` until the oldest expire; an outstanding challenge is never dropped. +/// The most challenges remembered as used by a granted request. Past it, proofs are +/// refused with `slow_down` until some expire; an outstanding challenge is never dropped. const MAX_SPENT: usize = 65536; /// A challenge is its expiry (unix seconds), a nonce, then a truncated HMAC over both. @@ -171,7 +171,7 @@ pub struct NewKey { #[derive(Default)] struct Inner { store: Store, - /// Challenges a valid proof already used, until each expires. + /// Challenges a granted request already used, until each expires. spent: HashMap, moq_clock::Wall>, } @@ -233,7 +233,7 @@ impl Coordinator { /// Enroll with an enrollment key. pub fn enroll(&self, request: &EnrollRequest) -> Reply { let mut inner = self.inner.lock().unwrap(); - self.check(&mut inner, &request.proof)?; + let spent = self.check(&mut inner, &request.proof)?; let (id, secret) = request .key @@ -270,29 +270,33 @@ impl Coordinator { let id = id.to_string(); let endpoint = request.proof.endpoint; - self.commit(&mut inner, |store| { + let enrollment = self.commit(&mut inner, |store| { self.admit(store, endpoint, request.name.as_deref(), tags)?; if !reusable && let Some(key) = store.keys.iter_mut().find(|key| key.id == id) { key.used = true; } self.issue(store, endpoint) - }) + })?; + inner.spent.insert(request.proof.challenge.clone(), spent); + Ok(enrollment) } /// Refresh an enrolled device's token, refusing a revoked or unknown one. pub fn refresh(&self, proof: &Proof) -> Reply { let mut inner = self.inner.lock().unwrap(); - self.check(&mut inner, proof)?; - match inner + let spent = self.check(&mut inner, proof)?; + let enrollment = match inner .store .devices .iter() .find(|device| device.endpoint == proof.endpoint) { - Some(device) if !device.revoked => self.issue(&inner.store, proof.endpoint), - Some(_) => Err(ErrorReply::new(ErrorCode::AccessDenied, "the device is revoked")), - None => Err(ErrorReply::new(ErrorCode::AccessDenied, "the device is not enrolled")), - } + Some(device) if !device.revoked => self.issue(&inner.store, proof.endpoint)?, + Some(_) => return Err(ErrorReply::new(ErrorCode::AccessDenied, "the device is revoked")), + None => return Err(ErrorReply::new(ErrorCode::AccessDenied, "the device is not enrolled")), + }; + inner.spent.insert(proof.challenge.clone(), spent); + Ok(enrollment) } /// Create an enrollment key, returning it with its secret, which is never shown again. @@ -388,8 +392,11 @@ impl Coordinator { axum::serve(listener, self.router()).await } - /// Verify the proof's challenge and signature, then spend the challenge. - fn check(&self, inner: &mut Inner, proof: &Proof) -> Reply<()> { + /// Verify the proof's challenge and signature, returning when the challenge expires. + /// + /// The caller records the challenge in `spent` only once the request succeeds, so + /// only an authorized device or enrollment key takes room there. + fn check(&self, inner: &mut Inner, proof: &Proof) -> Reply { let invalid = |reason: &str| ErrorReply::new(ErrorCode::InvalidChallenge, reason); let challenge = &proof.challenge; if challenge.len() != CHALLENGE_LEN @@ -411,18 +418,19 @@ impl Coordinator { "the signature does not verify against the endpoint ID", )); } - inner.spent.retain(|_, until| *until > now); if inner.spent.contains_key(challenge) { return Err(invalid("the challenge was already used")); } + if inner.spent.len() >= MAX_SPENT { + inner.spent.retain(|_, until| *until > now); + } if inner.spent.len() >= MAX_SPENT { return Err(ErrorReply::new( ErrorCode::SlowDown, "too many proofs at once; retry shortly", )); } - inner.spent.insert(challenge.clone(), expires); - Ok(()) + Ok(expires) } /// The truncated HMAC sealing a challenge's expiry and nonce. @@ -716,13 +724,18 @@ mod tests { } #[test] - fn a_full_spent_table_refuses_without_forgetting() { + fn only_a_granted_proof_takes_room_in_the_spent_table() { let key = Key::generate(Algorithm::HS256, None).unwrap(); let base: url::Url = "https://mesh.example".parse().unwrap(); let coordinator = Coordinator::new(Config::new(base.clone(), key)).unwrap(); let signer = aws_lc_rs::signature::Ed25519KeyPair::generate().unwrap(); let proof = Proof::sign(&signer, &base, coordinator.challenge().challenge); + // A refused request records nothing, so unknown callers cannot fill the table. + let err = coordinator.refresh(&proof).unwrap_err(); + assert_eq!(err.error, ErrorCode::AccessDenied); + assert!(coordinator.inner.lock().unwrap().spent.is_empty()); + let later = moq_clock::wall() + CHALLENGE_TTL; let mut inner = coordinator.inner.lock().unwrap(); inner.spent = (0..MAX_SPENT as u64) @@ -734,6 +747,7 @@ mod tests { // Its challenge stays good once room frees up. inner.spent.clear(); coordinator.check(&mut inner, &proof).unwrap(); + assert!(inner.spent.is_empty(), "checking alone spends nothing"); } #[test] From fc89cc6e44306481581ffce5c07ba79f8d486f2f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 31 Oct 2026 01:04:33 -0700 Subject: [PATCH 9/9] fix(auth): per-endpoint replay state, private owner API, unix mesh admin - A challenge carries a sequence number; an endpoint's proof is accepted only over a challenge newer than its last granted one. The replay state is one number per enrolled device, so no endpoint can fill room another needs. - `--mesh-url` refuses `--listen-public`: the owner API on `--listen` has no authentication and mints enrollment keys. - `moq auth mesh --url` accepts `unix:///path` and sends a typed `NewKey`, whose `expires_in` is now a `Duration`. - `Client::enroll` refreshes when the key is refused but the endpoint is already enrolled, so a lost reply does not strand a single-use key's device. - The contract's request and reply records drop `#[non_exhaustive]` so a hosted coordinator can construct them. Co-Authored-By: Claude Opus 5.5 --- doc/bin/relay/auth.md | 4 +- rs/moq-auth/src/mesh/client.rs | 15 ++- rs/moq-auth/src/mesh/contract_tests.rs | 8 +- rs/moq-auth/src/mesh/coordinator.rs | 129 ++++++++++++++----------- rs/moq-auth/src/mesh/mod.rs | 5 - rs/moq-cli/src/auth.rs | 101 +++++++++++++++---- 6 files changed, 175 insertions(+), 87 deletions(-) diff --git a/doc/bin/relay/auth.md b/doc/bin/relay/auth.md index ff9cc88e1ea..34c347f3c86 100644 --- a/doc/bin/relay/auth.md +++ b/doc/bin/relay/auth.md @@ -391,7 +391,9 @@ The device-facing API on `--mesh-listen` is meant to be public behind a TLS proxy, since devices refuse plain `http://` beyond loopback. A challenge holds no state until a proof uses it, so unauthenticated requests cannot crowd out a device's; the proxy should still rate-limit each client. The owner's -commands go to `--listen`, which stays private. A hosted coordinator implements +commands go to `--listen` (`moq auth mesh --url`, `unix:///path` for a +socket), which has no authentication, so `--mesh-url` refuses +`--listen-public`. A hosted coordinator implements the same JSON contract, documented in [`moq_auth::mesh`](https://docs.rs/moq-auth/latest/moq_auth/mesh/); it adds no token claims. diff --git a/rs/moq-auth/src/mesh/client.rs b/rs/moq-auth/src/mesh/client.rs index ede600020ea..ef9fbdfc54d 100644 --- a/rs/moq-auth/src/mesh/client.rs +++ b/rs/moq-auth/src/mesh/client.rs @@ -44,7 +44,7 @@ impl Client { "http" => return Err(Error::InsecureUrl(base.to_string())), _ => return Err(Error::InvalidUrl(base.to_string())), } - // A redirect would resend a proof or device code to wherever it points. + // A redirect would resend a proof or enrollment key to wherever it points. let http = reqwest::Client::builder() .redirect(reqwest::redirect::Policy::none()) .timeout(TIMEOUT) @@ -53,6 +53,10 @@ impl Client { } /// Join with a pre-authorized enrollment key, asking for `name`. + /// + /// When the coordinator refuses the key but this endpoint is already enrolled, such as + /// a retry after a single-use key's reply was lost, this refreshes instead, keeping the + /// 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 { @@ -60,7 +64,14 @@ impl Client { key: key.into(), name: name.map(Into::into), }; - self.post("enroll", &request).await + 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. + Err(Error::Mesh(reply)) if reply.error == ErrorCode::AccessDenied => Err(Error::Mesh(refused)), + res => res, + }, + res => res, + } } /// Prove the key again for a fresh token. Fails with [`ErrorCode::AccessDenied`] once diff --git a/rs/moq-auth/src/mesh/contract_tests.rs b/rs/moq-auth/src/mesh/contract_tests.rs index 11478efb0d3..f63b7e6cd5b 100644 --- a/rs/moq-auth/src/mesh/contract_tests.rs +++ b/rs/moq-auth/src/mesh/contract_tests.rs @@ -86,10 +86,16 @@ async fn an_enrollment_key_grants_the_endpoints_subtree() { async fn a_single_use_key_enrolls_once() { let mesh = Mesh::new().await; let key = mesh.key(false); - mesh.device().enroll(&key, None).await.unwrap(); + let device = mesh.device(); + let first = device.enroll(&key, Some("pi")).await.unwrap(); let err = mesh.device().enroll(&key, None).await.unwrap_err(); assert_eq!(Mesh::refused(err), ErrorCode::InvalidGrant); + // The device it enrolled can retry, as after a lost reply, and keeps its name. + let retried = device.enroll(&key, Some("other")).await.unwrap(); + assert_eq!(retried.name, first.name); + assert!(mesh.key.verify(&retried.token).is_ok()); + let reusable = mesh.key(true); let first = mesh.device().enroll(&reusable, Some("bot")).await.unwrap(); let second = mesh.device().enroll(&reusable, Some("bot")).await.unwrap(); diff --git a/rs/moq-auth/src/mesh/coordinator.rs b/rs/moq-auth/src/mesh/coordinator.rs index 953b0f72598..9c48418242d 100644 --- a/rs/moq-auth/src/mesh/coordinator.rs +++ b/rs/moq-auth/src/mesh/coordinator.rs @@ -5,9 +5,14 @@ //! authentication and stays on loopback. Enrollment keys and devices persist to a JSON //! state file. Challenges are sealed with a secret held in memory, so a restart only makes //! a device fetch a new challenge. +//! +//! A challenge is single-use per endpoint: each carries a sequence number, and an endpoint's +//! proof is accepted only over a challenge newer than the last one it was granted with. The +//! replay state is one number per enrolled device, so no caller can spend another's room. use std::collections::HashMap; use std::path::PathBuf; +use std::sync::atomic::{AtomicU64, Ordering}; use std::sync::{Arc, Mutex}; use std::time::Duration; @@ -25,13 +30,9 @@ use crate::{Claims, Key, Pattern}; /// How long a challenge stays valid. const CHALLENGE_TTL: Duration = Duration::from_secs(60); -/// The most challenges remembered as used by a granted request. Past it, proofs are -/// refused with `slow_down` until some expire; an outstanding challenge is never dropped. -const MAX_SPENT: usize = 65536; - -/// A challenge is its expiry (unix seconds), a nonce, then a truncated HMAC over both. -const NONCE_LEN: usize = 8; -const TAG_LEN: usize = CHALLENGE_LEN - 8 - NONCE_LEN; +/// A challenge is its expiry (unix seconds), its sequence number, then a truncated HMAC +/// over both. The HMAC makes it unpredictable; the sequence makes it single-use. +const TAG_LEN: usize = CHALLENGE_LEN - 16; /// The longest a device name may be: one DNS label. const MAX_NAME: usize = 63; @@ -156,14 +157,16 @@ impl From<&StoredKey> for KeyInfo { } /// `POST /mesh/keys` on the admin API: what the new enrollment key allows. +#[serde_as] #[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] #[serde(default)] #[non_exhaustive] pub struct NewKey { /// Tags every device it enrolls carries. pub tags: Vec, - /// Seconds until it stops enrolling; `None` never expires. - pub expires_in: Option, + /// How long until it stops enrolling; `None` never expires. Whole seconds on the wire. + #[serde_as(as = "Option>")] + pub expires_in: Option, /// Whether it enrolls more than one device. pub reusable: bool, } @@ -171,8 +174,9 @@ pub struct NewKey { #[derive(Default)] struct Inner { store: Store, - /// Challenges a granted request already used, until each expires. - spent: HashMap, moq_clock::Wall>, + /// The sequence of the last challenge each endpoint was granted with. Only an + /// enrolled device gets an entry, so it grows with the devices and nothing else. + used: HashMap, } /// The mesh coordinator: issues challenges, enrolls devices, and refreshes their tokens. @@ -181,6 +185,9 @@ pub struct Coordinator { config: Arc, /// Seals challenges, so an outstanding one needs no state. secret: Arc, + /// The next challenge's sequence number. It restarts with the secret, which voids + /// every earlier challenge. + sequence: Arc, inner: Arc>, } @@ -205,6 +212,7 @@ impl Coordinator { Ok(Self { config: Arc::new(config), secret: Arc::new(aws_lc_rs::hmac::Key::new(aws_lc_rs::hmac::HMAC_SHA256, &random(32))), + sequence: Default::default(), inner: Arc::new(Mutex::new(Inner { store, ..Default::default() @@ -221,7 +229,7 @@ impl Coordinator { .unwrap_or_default() .as_secs() + CHALLENGE_TTL.as_secs(); let mut challenge = expires.to_be_bytes().to_vec(); - challenge.extend_from_slice(&random(NONCE_LEN)); + 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 { @@ -233,7 +241,7 @@ impl Coordinator { /// Enroll with an enrollment key. pub fn enroll(&self, request: &EnrollRequest) -> Reply { let mut inner = self.inner.lock().unwrap(); - let spent = self.check(&mut inner, &request.proof)?; + let sequence = self.check(&inner, &request.proof)?; let (id, secret) = request .key @@ -277,14 +285,14 @@ impl Coordinator { } self.issue(store, endpoint) })?; - inner.spent.insert(request.proof.challenge.clone(), spent); + inner.used.insert(endpoint, sequence); Ok(enrollment) } /// Refresh an enrolled device's token, refusing a revoked or unknown one. pub fn refresh(&self, proof: &Proof) -> Reply { let mut inner = self.inner.lock().unwrap(); - let spent = self.check(&mut inner, proof)?; + let sequence = self.check(&inner, proof)?; let enrollment = match inner .store .devices @@ -295,7 +303,7 @@ impl Coordinator { Some(_) => return Err(ErrorReply::new(ErrorCode::AccessDenied, "the device is revoked")), None => return Err(ErrorReply::new(ErrorCode::AccessDenied, "the device is not enrolled")), }; - inner.spent.insert(proof.challenge.clone(), spent); + inner.used.insert(proof.endpoint, sequence); Ok(enrollment) } @@ -308,9 +316,7 @@ impl Coordinator { id: id.clone(), hash: hex(&sha256(secret.as_bytes())), tags: new.tags.clone(), - expires: new - .expires_in - .map(|secs| moq_clock::wall().saturating_add(Duration::from_secs(secs))), + expires: new.expires_in.map(|ttl| moq_clock::wall().saturating_add(ttl)), reusable: new.reusable, used: false, revoked: false, @@ -392,11 +398,11 @@ impl Coordinator { axum::serve(listener, self.router()).await } - /// Verify the proof's challenge and signature, returning when the challenge expires. + /// Verify the proof's challenge and signature, returning the challenge's sequence. /// - /// The caller records the challenge in `spent` only once the request succeeds, so - /// only an authorized device or enrollment key takes room there. - fn check(&self, inner: &mut Inner, proof: &Proof) -> Reply { + /// The caller records the sequence as the endpoint's last only once the request is + /// granted, so a refused proof changes nothing. + fn check(&self, inner: &Inner, proof: &Proof) -> Reply { let invalid = |reason: &str| ErrorReply::new(ErrorCode::InvalidChallenge, reason); let challenge = &proof.challenge; if challenge.len() != CHALLENGE_LEN @@ -408,8 +414,7 @@ impl Coordinator { } let expires = u64::from_be_bytes(challenge[..8].try_into().expect("8 bytes")); let expires = moq_clock::Wall::UNIX_EPOCH.saturating_add(Duration::from_secs(expires)); - let now = moq_clock::wall(); - if expires <= now { + if expires <= moq_clock::wall() { return Err(invalid("the challenge expired")); } if !proof.verify(&self.config.url) { @@ -418,19 +423,11 @@ impl Coordinator { "the signature does not verify against the endpoint ID", )); } - if inner.spent.contains_key(challenge) { - return Err(invalid("the challenge was already used")); - } - if inner.spent.len() >= MAX_SPENT { - inner.spent.retain(|_, until| *until > now); + let sequence = u64::from_be_bytes(challenge[8..16].try_into().expect("8 bytes")); + if inner.used.get(&proof.endpoint).is_some_and(|last| sequence <= *last) { + return Err(invalid("the endpoint already used this challenge or a newer one")); } - if inner.spent.len() >= MAX_SPENT { - return Err(ErrorReply::new( - ErrorCode::SlowDown, - "too many proofs at once; retry shortly", - )); - } - Ok(expires) + Ok(sequence) } /// The truncated HMAC sealing a challenge's expiry and nonce. @@ -724,30 +721,46 @@ mod tests { } #[test] - fn only_a_granted_proof_takes_room_in_the_spent_table() { + fn a_challenge_is_single_use_per_endpoint() { let key = Key::generate(Algorithm::HS256, None).unwrap(); let base: url::Url = "https://mesh.example".parse().unwrap(); let coordinator = Coordinator::new(Config::new(base.clone(), key)).unwrap(); - let signer = aws_lc_rs::signature::Ed25519KeyPair::generate().unwrap(); - let proof = Proof::sign(&signer, &base, coordinator.challenge().challenge); - - // A refused request records nothing, so unknown callers cannot fill the table. - let err = coordinator.refresh(&proof).unwrap_err(); - assert_eq!(err.error, ErrorCode::AccessDenied); - assert!(coordinator.inner.lock().unwrap().spent.is_empty()); - - let later = moq_clock::wall() + CHALLENGE_TTL; - let mut inner = coordinator.inner.lock().unwrap(); - inner.spent = (0..MAX_SPENT as u64) - .map(|n| (n.to_be_bytes().to_vec(), later)) - .collect(); - let err = coordinator.check(&mut inner, &proof).unwrap_err(); - assert_eq!(err.error, ErrorCode::SlowDown); - - // Its challenge stays good once room frees up. - inner.spent.clear(); - coordinator.check(&mut inner, &proof).unwrap(); - assert!(inner.spent.is_empty(), "checking alone spends nothing"); + let secret = coordinator + .create_key(&NewKey { + reusable: true, + ..Default::default() + }) + .unwrap() + .key + .unwrap(); + let a = aws_lc_rs::signature::Ed25519KeyPair::generate().unwrap(); + let b = aws_lc_rs::signature::Ed25519KeyPair::generate().unwrap(); + let enroll = |signer: &aws_lc_rs::signature::Ed25519KeyPair, challenge: &Challenge| EnrollRequest { + proof: Proof::sign(signer, &base, challenge.challenge.clone()), + key: secret.clone(), + name: None, + }; + let older = coordinator.challenge(); + let newer = coordinator.challenge(); + + // A refused proof records nothing, so an unknown caller holds no state. + assert_eq!( + coordinator.refresh(&enroll(&a, &older).proof).unwrap_err().error, + ErrorCode::AccessDenied + ); + assert!(coordinator.inner.lock().unwrap().used.is_empty()); + + // Once `a` uses the newer challenge, its own older one is spent too. + coordinator.enroll(&enroll(&a, &newer)).unwrap(); + for challenge in [&newer, &older] { + let err = coordinator.enroll(&enroll(&a, challenge)).unwrap_err(); + assert_eq!(err.error, ErrorCode::InvalidChallenge); + } + + // Another endpoint's state is its own: `a` spending challenges costs `b` nothing. + coordinator.enroll(&enroll(&b, &older)).unwrap(); + coordinator.enroll(&enroll(&b, &newer)).unwrap(); + assert_eq!(coordinator.inner.lock().unwrap().used.len(), 2); } #[test] diff --git a/rs/moq-auth/src/mesh/mod.rs b/rs/moq-auth/src/mesh/mod.rs index 043146e6be8..cd00171ce93 100644 --- a/rs/moq-auth/src/mesh/mod.rs +++ b/rs/moq-auth/src/mesh/mod.rs @@ -160,7 +160,6 @@ 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 { /// [`CHALLENGE_LEN`] bytes, opaque to the device, base64url without padding. #[serde_as(as = "serde_with::base64::Base64")] @@ -174,7 +173,6 @@ pub struct Challenge { /// [`proof_message`] for a challenge the coordinator issued and has not yet seen used. #[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: EndpointId, @@ -239,7 +237,6 @@ impl Signer for aws_lc_rs::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)] @@ -255,7 +252,6 @@ pub struct EnrollRequest { /// 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, @@ -272,7 +268,6 @@ pub struct Enrollment { /// 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: EndpointId, diff --git a/rs/moq-cli/src/auth.rs b/rs/moq-cli/src/auth.rs index 2d98441e1b1..5e44a9725fa 100644 --- a/rs/moq-cli/src/auth.rs +++ b/rs/moq-cli/src/auth.rs @@ -546,6 +546,11 @@ impl Serve { let Some(url) = &self.mesh_url else { return Ok(None); }; + if self.listen_public { + anyhow::bail!( + "--mesh-url serves the mesh owner's API on --listen, which has no authentication, so it cannot be combined with --listen-public" + ); + } let path = self .mesh_key .as_ref() @@ -615,7 +620,8 @@ impl Serve { #[derive(usage_rs::Args, Clone, Debug)] #[usage(unknown_flags = "error", args_override_self = false)] pub struct Mesh { - /// The auth server's listener, which serves the owner's API alongside `POST /`. + /// The auth server's listener, which serves the owner's API alongside `POST /`: + /// `http://` for a TCP `--listen`, or `unix:///path` for a unix socket. #[usage(long, default = "http://127.0.0.1:4440")] url: url::Url, @@ -661,20 +667,28 @@ enum MeshCommand { impl Mesh { async fn run(self) -> anyhow::Result<()> { - let client = reqwest::Client::new(); + let (client, base) = self.client()?; + let url = |path: &str, segments: &[&str]| { + let mut url = base.clone(); + let prefix = url.path().trim_end_matches('/').to_string(); + url.set_path(&format!("{prefix}{path}")); + if let Ok(mut parts) = url.path_segments_mut() { + parts.extend(segments); + } + url + }; let request = match &self.command { MeshCommand::CreateKey { tag, expires, reusable } => { - let body = serde_json::json!({ - "tags": tag, - "expires_in": expires.map(|expires| std::time::Duration::from(expires).as_secs()), - "reusable": reusable, - }); - client.post(self.url("/mesh/keys", &[])).json(&body) + let mut new = moq_auth::mesh::NewKey::default(); + new.tags = tag.clone(); + new.expires_in = expires.map(std::time::Duration::from); + new.reusable = *reusable; + client.post(url("/mesh/keys", &[])).json(&new) } - MeshCommand::Keys => client.get(self.url("/mesh/keys", &[])), - MeshCommand::RevokeKey { id } => client.delete(self.url("/mesh/keys", &[id])), - MeshCommand::Devices => client.get(self.url("/mesh/devices", &[])), - MeshCommand::Revoke { endpoint } => client.delete(self.url("/mesh/devices", &[endpoint])), + MeshCommand::Keys => client.get(url("/mesh/keys", &[])), + MeshCommand::RevokeKey { id } => client.delete(url("/mesh/keys", &[id])), + MeshCommand::Devices => client.get(url("/mesh/devices", &[])), + MeshCommand::Revoke { endpoint } => client.delete(url("/mesh/devices", &[endpoint])), }; let response = request .send() @@ -701,15 +715,23 @@ impl Mesh { Ok(()) } - /// `path` under the server's URL, with `segments` appended percent-encoded. - fn url(&self, path: &str, segments: &[&str]) -> url::Url { - let mut url = self.url.clone(); - let base = url.path().trim_end_matches('/').to_string(); - url.set_path(&format!("{base}{path}")); - if let Ok(mut parts) = url.path_segments_mut() { - parts.extend(segments); + /// The HTTP client for `--url` and the URL its requests target: a `unix://` URL names + /// the socket, and the requests go to the server's root over it. + fn client(&self) -> anyhow::Result<(reqwest::Client, url::Url)> { + let builder = reqwest::Client::builder(); + match self.url.scheme() { + "http" | "https" => Ok((builder.build()?, self.url.clone())), + #[cfg(unix)] + "unix" => { + let path = self + .url + .to_file_path() + .map_err(|()| anyhow::anyhow!("--url {} names no socket path", self.url))?; + let target = url::Url::parse("http://localhost/").expect("a constant URL parses"); + Ok((builder.unix_socket(path).build()?, target)) + } + _ => anyhow::bail!("--url expects http://, https://, or unix://, got {}", self.url), } - url } } @@ -864,6 +886,45 @@ mod tests { assert!(flags.mesh_listen.ip().is_loopback()); assert!(flags.coordinator().unwrap().is_some()); assert!(serve(&["moq", "auth", "serve"]).coordinator().unwrap().is_none()); + + // The owner's API rides --listen, so a public one would hand out enrollment keys. + let flags = serve(&[ + "moq", + "auth", + "serve", + "--listen", + "0.0.0.0:4440", + "--listen-public", + "--mesh-url", + "https://mesh.example", + "--mesh-key", + key.to_str().unwrap(), + ]); + let err = flags.coordinator().err().expect("a public owner API"); + assert!(err.to_string().contains("--listen-public"), "{err}"); + } + + #[cfg(unix)] + #[tokio::test] + async fn mesh_commands_reach_a_unix_listener() { + let dir = tempfile::tempdir().unwrap(); + let key = moq_auth::Key::generate(Algorithm::HS256, None).unwrap(); + let config = moq_auth::mesh::Config::new("https://mesh.example".parse().unwrap(), key); + let coordinator = moq_auth::mesh::Coordinator::new(config).unwrap(); + let server = moq_auth::serve::Server::new(Policy::default()) + .unwrap() + .with_mesh(coordinator.clone()); + let path = dir.path().join("auth.sock"); + let listener = tokio::net::UnixListener::bind(&path).unwrap(); + tokio::spawn(async move { server.serve_unix(listener).await }); + + let url = format!("unix://{}", path.display()); + run(&["moq", "auth", "mesh", "--url", &url, "create-key", "--expires", "1d"]) + .await + .unwrap(); + let keys = coordinator.keys(); + assert_eq!(keys.len(), 1); + assert!(keys[0].expires.is_some()); } #[test]