diff --git a/Cargo.lock b/Cargo.lock index 2f75101dc24..d908cb23180 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -5382,6 +5382,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/doc/bin/relay/auth.md b/doc/bin/relay/auth.md index 6a4da1b9994..438c3fe2102 100644 --- a/doc/bin/relay/auth.md +++ b/doc/bin/relay/auth.md @@ -377,6 +377,45 @@ 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 +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 +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, 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. 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` (`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. + ### 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..d3b3e3488ad 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 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 5120dc100ce..ed02e78cae6 100644 --- a/quest/m2/mesh/README.md +++ b/quest/m2/mesh/README.md @@ -47,6 +47,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 @@ -87,7 +91,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 - [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 - [Address hints](/quest/m2/mesh/addr.md) - nodes publish their addresses on mesh tracks and dial each other directly where mDNS cannot find them diff --git a/quest/m2/mesh/daemon.md b/quest/m2/mesh/daemon.md index 6e624db729e..e89a213b74d 100644 --- a/quest/m2/mesh/daemon.md +++ b/quest/m2/mesh/daemon.md @@ -23,6 +23,10 @@ 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 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`. - Decided 2026-10-31 (maintainer): install defaults to a system service because macOS exempts launchd daemons and root from Local Network privacy but prompts launchd agents, and a denied prompt silently breaks LAN @@ -32,5 +36,4 @@ the epic's first shippable outcome. ## 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 01b3188f2b3..c281ea3378a 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"] } @@ -37,7 +38,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 72f2a0582f7..bf07fe2b25b 100644 --- a/rs/moq-auth/src/error.rs +++ b/rs/moq-auth/src/error.rs @@ -211,6 +211,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 0fb9b206d2d..38183768fff 100644 --- a/rs/moq-auth/src/lib.rs +++ b/rs/moq-auth/src/lib.rs @@ -35,6 +35,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..ef9fbdfc54d --- /dev/null +++ b/rs/moq-auth/src/mesh/client.rs @@ -0,0 +1,157 @@ +//! 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, 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; + +/// 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 enrollment key 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`. + /// + /// 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 { + proof, + key: key.into(), + name: name.map(Into::into), + }; + match self.post("enroll", &request).await { + Err(Error::Mesh(refused)) if refused.error == ErrorCode::InvalidGrant => match self.refresh().await { + // Not enrolled after all, so the key's refusal is the answer. + 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 + /// 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, except a transient one: a server error, + /// `slow_down`, or a challenge that expired or outlived a coordinator restart. + 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 !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) => { + 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..f63b7e6cd5b --- /dev/null +++ b/rs/moq-auth/src/mesh/contract_tests.rs @@ -0,0 +1,305 @@ +//! 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.token_ttl = ttl; + let coordinator = Coordinator::new(config).unwrap(); + let router = 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); + 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(); + 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 + ); + + // 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 + ); + + // 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 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 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}; + + 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 that restarts between issuing the challenge and seeing the proof. + 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, "unknown challenge")), + ) + .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(); + 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; + 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..9c48418242d --- /dev/null +++ b/rs/moq-auth/src/mesh/coordinator.rs @@ -0,0 +1,784 @@ +//! 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 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; + +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 serde::{Deserialize, Serialize}; +use serde_with::serde_as; + +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); + +/// 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; + +/// 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, +} + +impl Config { + /// 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, + key, + relays: Vec::new(), + state: None, + token_ttl: Duration::from_secs(3600), + } + } +} + +/// The state that survives a restart. +#[derive(Clone, 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. +#[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, + /// 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, +} + +#[derive(Default)] +struct Inner { + store: Store, + /// 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. +#[derive(Clone)] +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>, +} + +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(), + }; + // 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), + 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() + })), + }) + } + + /// 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 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(&self.sequence.fetch_add(1, Ordering::Relaxed).to_be_bytes()); + let tag = self.tag(&challenge); + challenge.extend_from_slice(&tag); + Challenge { + challenge, + expires: moq_clock::Wall::UNIX_EPOCH.saturating_add(Duration::from_secs(expires)), + } + } + + /// Enroll with an enrollment key. + pub fn enroll(&self, request: &EnrollRequest) -> Reply { + let mut inner = self.inner.lock().unwrap(); + let sequence = self.check(&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; + 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.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 sequence = self.check(&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(_) => return Err(ErrorReply::new(ErrorCode::AccessDenied, "the device is revoked")), + None => return Err(ErrorReply::new(ErrorCode::AccessDenied, "the device is not enrolled")), + }; + inner.used.insert(proof.endpoint, sequence); + Ok(enrollment) + } + + /// 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(|ttl| moq_clock::wall().saturating_add(ttl)), + reusable: new.reusable, + used: false, + revoked: false, + }; + let mut info = KeyInfo::from(&stored); + info.key = Some(format!("{id}.{secret}")); + self.commit(&mut inner, |store| { + store.keys.push(stored); + Ok(()) + })?; + 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 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. + 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 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-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("/refresh", post(refresh_handler)) + .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 + /// 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)) + .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 + } + + /// Verify the proof's challenge and signature, returning the challenge's sequence. + /// + /// 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 + || !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)); + if expires <= moq_clock::wall() { + return Err(invalid("the challenge expired")); + } + if !proof.verify(&self.config.url) { + return Err(ErrorReply::new( + ErrorCode::InvalidSignature, + "the signature does not verify against the endpoint ID", + )); + } + 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")); + } + Ok(sequence) + } + + /// 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 { + 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, 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(), + (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, 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. + 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 token = self + .config + .key + .sign(&claims(endpoint, now, Some(expires))) + .map_err(internal)?; + let device = 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: 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, store: &Store) -> 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(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 { + 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") +} + +/// 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 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), + } +} + +#[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 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 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] + 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..cd00171ce93 --- /dev/null +++ b/rs/moq-auth/src/mesh/mod.rs @@ -0,0 +1,391 @@ +//! 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 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. +//! +//! 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}/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; + +/// 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 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]); + +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 z-base-32 segment is a valid path") + } +} + +/// 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 52 z-base-32 characters")] +#[non_exhaustive] +pub struct InvalidEndpoint; + +impl FromStr for EndpointId { + type Err = InvalidEndpoint; + + fn from_str(text: &str) -> Result { + // 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)?, + _ => return Err(InvalidEndpoint), + }; + Ok(Self(out)) + } +} + +impl fmt::Display for EndpointId { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(&ZBASE32.encode(&self.0)) + } +} + +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)] +pub struct Challenge { + /// [`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. + #[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)] +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)] +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, +} + +/// What a device needs to join: the relays to dial and the token to present. +#[serde_as] +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +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)] +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. +#[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 coordinator is busy; retry shortly. + SlowDown, + /// The device is revoked or not enrolled. + AccessDenied, + /// 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(), 52); + assert_eq!(text.parse::().unwrap(), id); + 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_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(); + 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":"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-auth/src/serve.rs b/rs/moq-auth/src/serve.rs index 921d0b47824..452383a1aa6 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..5e44a9725fa 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 and devices. + 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,198 @@ 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); + }; + 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() + .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()), + } + 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 /`: + /// `http://` for a TCP `--listen`, or `unix:///path` for a unix socket. + #[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, + }, +} + +impl Mesh { + async fn run(self) -> anyhow::Result<()> { + 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 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) } - #[cfg(not(unix))] - Listen::Unix(path) => anyhow::bail!("unix sockets are not supported here: {}", path.display()), + 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() + .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", + _ => "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(()) } + + /// 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), + } + } } #[derive(Debug)] @@ -657,6 +854,100 @@ 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()); + + // 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] + fn mesh_commands_parse() { + for args in [ + &[ + "moq", + "auth", + "mesh", + "create-key", + "--tag", + "robot", + "--reusable", + "--expires", + "1d", + ][..], + &["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:?}"); + } + } + #[test] fn serve_refuses_a_public_bind_without_saying_so() { let err = serve(&["moq", "auth", "serve", "--listen", "0.0.0.0:4440"])