From 362c6dbf10f1f574b59ff039a781ddb8b3b0b04a Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 13:06:28 -0700 Subject: [PATCH 1/4] chore: claim refusal reason quest From 0a7b42259e34cd44fcd6849cbf9503b0cd1755ec Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 13:16:26 -0700 Subject: [PATCH 2/4] feat(auth): carry typed refusal reasons and verified attribution Share refusal reasons and optional verified root/tier across HTTP auth and embedded admission. Keep legacy refusals unattributed, and count expired credentials in relay metrics and stats. Co-Authored-By: GPT-6.1-Sol --- doc/bin/relay/auth.md | 14 +- doc/concept/stats.md | 11 +- doc/lib/rs/moq-auth.md | 1 + js/auth/src/contract.test.ts | 15 +- js/auth/src/contract.ts | 16 +- quest/m1/README.md | 1 - quest/m1/refusal-reason.md | 56 ----- rs/moq-auth/MIGRATE.md | 6 + rs/moq-auth/src/client.rs | 105 +++++++-- rs/moq-auth/src/error.rs | 4 +- rs/moq-auth/src/key.rs | 11 +- rs/moq-auth/src/lib.rs | 4 +- rs/moq-auth/src/refusal.rs | 42 ++++ rs/moq-auth/src/serve.rs | 217 +++++++++++++++--- rs/moq-auth/src/set.rs | 11 +- rs/moq-net/src/stats/outcomes.rs | 12 + rs/moq-relay/MIGRATE.md | 6 + rs/moq-relay/benches/auth.rs | 5 +- rs/moq-relay/src/auth.rs | 42 +++- rs/moq-relay/src/auth/refresh.rs | 2 +- rs/moq-relay/src/cluster.rs | 4 +- rs/moq-relay/src/refusals.rs | 55 ++++- rs/moq-relay/src/shutdown.rs | 2 +- .../tests/integration/auth_embedder.rs | 47 +++- .../tests/integration/auth_lifetime.rs | 2 +- rs/moq-relay/tests/integration/refusals.rs | 50 ++++ 26 files changed, 596 insertions(+), 145 deletions(-) delete mode 100644 quest/m1/refusal-reason.md create mode 100644 rs/moq-auth/src/refusal.rs diff --git a/doc/bin/relay/auth.md b/doc/bin/relay/auth.md index 1b1c48e0928..25d59388048 100644 --- a/doc/bin/relay/auth.md +++ b/doc/bin/relay/auth.md @@ -33,7 +33,15 @@ mark another relay and an [upstream link](/bin/relay/cluster#upstream-links). The fields are documented on `moq_auth::Request` and `moq_auth::Grant` ([Rust](/lib/rs/moq-auth), [TypeScript](/lib/js/auth)). -**Connect.** A 2xx with a grant admits. A 401 or 403 refuses. Anything else, +**Connect.** A 2xx with a grant admits. A 403 can carry JSON such as +`{"reason":"expired","root":"rooms/123","tier":"edge"}`. The reason is +`refused`, `forbidden`, or `expired`; unknown reason strings read as `refused`. +A legacy plain-text 401 or 403 still reads as `refused`. Optional `root` and +`tier` attribute refusal counters, with an absent tier using the default. +Only name a root from a verified credential, including an expired token whose +signature and key scope were verified. Never copy the unverified dialed path +into `root`: that would let callers create unbounded stats entries. +Anything else, including a timeout or an unparseable body, refuses and logs an error, so nothing is admitted because the server was down. A grant that names nothing refuses, and so does one already expired: expiry is exact, with no grace for @@ -361,7 +369,9 @@ An application that [embeds](/bin/relay/#embed) the relay can decide admissions itself, without the HTTP: leave `[auth]` empty and take `relay.admissions()` before `run`. Each `Admission` carries the same `moq_auth::Request` a server would read, and is answered with a lease or a -refusal. A fixed lease never changes; a `lease::Producer` the application keeps +refusal. Pass the shared `moq_auth::Refusal` in `auth::Error::Refused` to +`Admission::refuse`, using the same verified-root rule as an HTTP server. +A fixed lease never changes; a `lease::Producer` the application keeps re-checks, updates, and revokes on its own clock. The relay still closes the session at the grant's `expires`, and an admission left unanswered for ten seconds is refused. `Admission::attached()` marks a token presented diff --git a/doc/concept/stats.md b/doc/concept/stats.md index 52a82d2e233..062e3358e2c 100644 --- a/doc/concept/stats.md +++ b/doc/concept/stats.md @@ -281,10 +281,13 @@ qmux counter source; unavailable counters are never estimated from payload. Readers default missing wire fields to zero for older relays. `sessions_refused` counts sessions turned away before admission, by reason. -They never start a session. The relay's own refusals have no resolved label, so -they count under the empty label on the default tier; an embedder can count one -it refuses itself with `stats::Handle::refuse`, under the label and tier it -resolved. +They never start a session. `expired` counts a verified credential that expired +before admission. An auth-server or embedded refusal can name a root from a +verified credential and an optional tier; that root is the refusal's stats label, +with an absent tier using the default. A refusal without a verified root counts +under the empty label, never the dialed path. An embedder can also count a refusal +with `stats::Handle::refuse`, under the label and tier it resolved. Older readers +ignore `expired`; newer readers default a missing counter to zero. `sessions_failed` counts admitted sessions that ended abnormally, by kind: a subset of `sessions_ended`, so the live count is unchanged. A clean close by diff --git a/doc/lib/rs/moq-auth.md b/doc/lib/rs/moq-auth.md index 143182e5f1d..43ea26f6224 100644 --- a/doc/lib/rs/moq-auth.md +++ b/doc/lib/rs/moq-auth.md @@ -15,6 +15,7 @@ accept loop that decides in process. - **Request and grant.** `Request` is the JSON a relay POSTs on each session event (`connect`, `revalidate`, `end`), carrying everything it knows about the session. `Grant` is the answer: publish and subscribe [`Pattern`](https://docs.rs/moq-pattern) unions, an expiry, a revalidation cadence, optional stats tier and label, and whether the session is a cluster peer or an [upstream link](/bin/relay/cluster#upstream-links). `Grant::validate` checks the grant contract; the accept loop must enforce its caps or refuse it. Expiry is exact, with no allowance for clock skew. - **Lease.** `lease::Producer` and `lease::Consumer` are the handle a session holds for its grant: read it, wait for a change, revoke it, and learn why it ended. Whoever runs the accept loop builds the producer, so an embedder can decide in process with no HTTP. +- **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. - **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, preserving optional per-connection bitrate caps in each role's `Access`. The relay currently refuses capped grants; a gateway embedder must enforce them or refuse them too. See [relay authentication](/bin/relay/auth#claims) before minting capped tokens. diff --git a/js/auth/src/contract.test.ts b/js/auth/src/contract.test.ts index ac19cbbe018..5fd6ae6ae1f 100644 --- a/js/auth/src/contract.test.ts +++ b/js/auth/src/contract.test.ts @@ -1,5 +1,5 @@ import { expect, test } from "bun:test"; -import { GrantSchema, RequestSchema, TokenSchema } from "./contract.ts"; +import { GrantSchema, RefusalSchema, RequestSchema, TokenSchema } from "./contract.ts"; // The fixtures below are what the Rust `moq_auth::Request` and `Grant` serialize to, // so a server written against these schemas reads what a relay sends. @@ -127,3 +127,16 @@ test("an auth endpoint grant accepts a capped role", () => { const grant = GrantSchema.parse({ publish: { path: "alice/**", rate: 8_000_000 } }); expect(grant).toHaveProperty("publish.rate", 8_000_000); }); + +test("refusal reasons preserve verified attribution and accept future reasons", () => { + for (const reason of ["refused", "forbidden", "expired"] as const) { + expect(RefusalSchema.parse({ reason, root: "tenant", tier: "edge" })).toEqual({ + reason, + root: "tenant", + tier: "edge", + }); + expect(RefusalSchema.parse({ reason })).toEqual({ reason }); + } + expect(RefusalSchema.parse({ reason: "future" })).toEqual({ reason: "refused" }); + expect(RefusalSchema.safeParse({ reason: 42 }).success).toBe(false); +}); diff --git a/js/auth/src/contract.ts b/js/auth/src/contract.ts index 82d1a4ad96a..85b8aee9624 100644 --- a/js/auth/src/contract.ts +++ b/js/auth/src/contract.ts @@ -1,7 +1,7 @@ /** - * The JSON a relay POSTs to an auth server per session event, and the grant it answers with. + * The JSON a relay POSTs to an auth server per session event, and the grant or refusal it answers with. * - * Mirrors `moq_auth::Request` and `moq_auth::Grant` in the Rust crate: a server written + * Mirrors `moq_auth::Request`, `moq_auth::Grant`, and `moq_auth::Refusal` in the Rust crate: a server written * in TypeScript validates a request and builds a grant with these schemas. * * @module @@ -187,3 +187,15 @@ export const GrantSchema = z }), ); export type Grant = z.infer; + +/** The reason and verified attribution an auth server returns with HTTP 403. */ +export const RefusalSchema = z.object({ + /** Unknown reason strings read as `refused`. */ + reason: z.pipe(z.string(), z.catch(z.enum(["refused", "forbidden", "expired"]), "refused")), + /** A root named by a verified credential, never an unverified request path. */ + root: z.optional(PathSchema), + /** The tier resolved by the decider; absent uses the default tier. */ + tier: z.optional(z.string()), +}); +/** A typed refusal returned by an admission decider. */ +export type Refusal = z.infer; diff --git a/quest/m1/README.md b/quest/m1/README.md index 18f4bd1d617..241fb164ee1 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -90,7 +90,6 @@ lands before the cut. - [Redundant ingest guide](/quest/m1/redundant-ingest-guide.md) - a setup page on redundant ingest over multiple routes, for any publisher - [Generated C bindings](/quest/m1/c/README.md) - C generated from moq-ffi ships as `moq-c` 0.8.0 and replaces the hand-written libmoq - [moq-ffi reports why a first dial fails](/quest/m1/ffi-first-dial-failure.md) - OBS names the reason while the first dial retries, as moq-c already can -- [Typed refusal reason](/quest/m1/refusal-reason.md) - an auth server's 403 names the reason (including `expired`) and the root and tier, so the relay's session outcomes count and attribute refusals - [JS track handover](/quest/m1/js-group-handover.md) - a JS track subscription resumes across a route swap from the first frame it lacks, so `test/drain` passes at zero latency budget - [Scope track priority](/quest/m1/track-priority-scope.md) - priority orders one owner's streams, and a shared cluster session is fair across tenants - [Audio jitter target](/quest/m1/audio-jitter-target/README.md) - the playout target is default in both languages; a manual browser proof and a native trace replay remain diff --git a/quest/m1/refusal-reason.md b/quest/m1/refusal-reason.md deleted file mode 100644 index 08b2e4fb282..00000000000 --- a/quest/m1/refusal-reason.md +++ /dev/null @@ -1,56 +0,0 @@ -# [M] Typed refusal reason - -## Goal - -A refusal tells the relay why and for whom. `moq auth serve` answers a 403 -with a JSON body carrying the reason (including `expired`) and, optionally, -the root and tier it resolved, and `moq_auth::Client` parses it into a typed -error. A legacy plain-text 403 (or 401) still reads as -`refused`. An embedder's decider can refuse with the same root and tier. The -relay's session outcomes then count `expired` refusals and attribute a -refusal to that root and tier. - -## Plan - -Decided 2026-10-08: moved out of the auth line to m1, since it extends -session outcomes and the HTTP auth contract, not in-band AUTH. - -Decided 2026-10-08: - -- **Why.** `TokenExpired` is raised only in moq-auth's key check - (`rs/moq-auth/src/key.rs`), on the auth server. `serve.rs` sends every - refusal as a plain-text 403, `client.rs` maps 401/403 to `Error::Refused` - and discards the body, and the relay verifies no token itself. So neither - the reason nor the resolved root reaches the relay today. -- **Contract.** A refusal body names a reason (`refused`, `forbidden`, or - `expired`; the relay's other reasons are its own), an optional root, and an - optional tier. Unknown reasons read as `refused`, so the set can grow. The - root and tier are the auth server's claim, trusted like a grant's. A - third-party auth server is a consumer of this contract: document it in - `doc/bin/relay/auth.md` and `doc/lib/rs/moq-auth.md`. -- **Serve.** `verify` folds `TokenExpired` into `Refusal::InvalidToken`'s - string today (`rs/moq-auth/src/serve.rs`); add an expired refusal and map - serve's `Refusal` variants onto the three reasons. -- **Bounded attribution.** A body names a root only when a verified token - named it, never the dialed path (`NoAccess { path }` is attacker-chosen), so - a client cannot mint a stats entry per random path. -- **Embedder.** An embedder deciding admission (moq.pro's edge) refuses - through `Admission::refuse` (`rs/moq-relay/src/auth.rs`), whose - `auth::Error` has no `expired` and carries no root or tier. Give the HTTP - path and `Admission::refuse` one refusal shape (reason, optional root and - tier), under the same bound, and update `From`, which sends - anything but `Refused` to `Unavailable` today. A refusal an embedder - records through `stats::Handle::refuse` takes `expired` too. -- **Relay.** Map the typed error to a `Refusal` reason (adding `expired`) in - `/metrics`, and count it in the root's `Presence` on that tier, or the - default tier when the body names none. A refusal without a root stays - unattributed. -- Tests: the serve/client round trip for each reason with and without root - and tier; a legacy plain-text 403 reads as `refused`; an expired token, an - auth server refusal on a named tier, an embedder `expired` refusal, and an - embedder refusal on a named tier each count under the right root, tier, and - reason; a refusal for an - unverified token stays unattributed. - -Public API: moq-auth's refusal error and the HTTP refusal body. Wire: the -auth HTTP contract only, not MoQ. diff --git a/rs/moq-auth/MIGRATE.md b/rs/moq-auth/MIGRATE.md index 16cc316e515..daa4182e819 100644 --- a/rs/moq-auth/MIGRATE.md +++ b/rs/moq-auth/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Typed admission refusals + +`Error::Refused` now carries a `Refusal`; construct `Error::Refused(Refusal::default())` for an unattributed refusal and match `Error::Refused(refusal)` to read `reason`, `root`, and `tier`. +HTTP auth servers can return that JSON shape with 403; legacy plain-text 401/403 still refuses without attribution. +`serve::Refusal::{NoAccess,TokenLimit,RemoteLimit}` now carry an optional verified `root`, and `Expired` carries the verified root. + ### `Grant` reads the ambient clock `Grant::deadline` returns a `moq_clock::Instant` instead of a `tokio::time::Instant`, and no longer needs the `tokio` feature. diff --git a/rs/moq-auth/src/client.rs b/rs/moq-auth/src/client.rs index 9c8463dc3f6..038e62c13ec 100644 --- a/rs/moq-auth/src/client.rs +++ b/rs/moq-auth/src/client.rs @@ -77,7 +77,7 @@ impl Client { /// Verify another credential for this connection without owning its end event. pub async fn attach(&self, connection: &lease::Consumer, request: Request) -> crate::Result { - let context = connection.context().ok_or(Error::Refused)?; + let context = connection.context().ok_or(Error::Refused(Default::default()))?; let context = context.attach(&request, &self.identity)?; admit(self.clone(), request, context).await } @@ -135,16 +135,16 @@ impl Context { fn attach(&self, request: &Request, issuer: &Arc<()>) -> crate::Result { if !self.owner || !Arc::ptr_eq(issuer, &self.connection.issuer) || self.connection.request.tls.is_some() { - return Err(Error::Refused); + return Err(Error::Refused(Default::default())); } let mut expected = self.connection.request.clone(); expected.query = request.query.clone(); expected.token = request.token.clone(); if &expected != request { - return Err(Error::Refused); + return Err(Error::Refused(Default::default())); } if self.connection.lifecycle.read().ended.is_some() { - return Err(Error::Refused); + return Err(Error::Refused(Default::default())); } Ok(Self { connection: self.connection.clone(), @@ -158,7 +158,7 @@ impl Context { } let mut lifecycle = self.connection.lifecycle.lock(); if lifecycle.ended.is_some() { - return Err(Error::Refused); + return Err(Error::Refused(Default::default())); } lifecycle.pending += 1; Ok(Some(Admission(self.connection.clone()))) @@ -226,12 +226,13 @@ trait Post: Clone + Send + Sync + 'static { impl Post for Client { /// A 2xx carries the grant, a 401 or 403 refuses, and everything else is an - /// outage the caller decides about. + /// outage the caller decides about. A JSON refusal carries its reason and verified attribution; + /// legacy bodies refuse without attribution. async fn post(&self, request: &Request) -> crate::Result { let response = self.http.post(self.url.clone()).json(request).send().await?; let status = response.status(); if status == reqwest::StatusCode::UNAUTHORIZED || status == reqwest::StatusCode::FORBIDDEN { - return Err(Error::Refused); + return Err(Error::Refused(response.json().await.unwrap_or_default())); } if !status.is_success() { return Err(Error::Unavailable(format!("auth server answered {status}"))); @@ -257,7 +258,7 @@ async fn admit(server: S, mut request: Request, context: Context) -> cr let grant = ask(&server, &request).await?; if context.connection.lifecycle.read().ended.is_some() { - return Err(Error::Refused); + return Err(Error::Refused(Default::default())); } let (producer, mut consumer) = lease::Producer::new(grant.clone()); consumer.set_context(context.clone()); @@ -281,7 +282,7 @@ async fn ask(server: &S, request: &Request) -> crate::Result { let grant = server.post(request).await?; grant.validate().map_err(|err| match err { // An empty grant is a refusal, not a malformed answer. - Error::UselessGrant => Error::Refused, + Error::UselessGrant => Error::Refused(Default::default()), other => other, })?; Ok(grant) @@ -358,7 +359,13 @@ impl Driver { inflight = None; match result { Ok(fresh) => producer.update(fresh), - Err(Error::Refused) => break producer.finish(Reason::Refused, Bytes::default()), + Err(Error::Refused(refusal)) => { + let reason = match refusal.reason { + crate::refusal::Reason::Expired => Reason::Expired, + _ => Reason::Refused, + }; + break producer.finish(reason, Bytes::default()); + }, Err(Error::GrantExpired | Error::UnboundedRevalidate | Error::ZeroRevalidate) => { break producer.finish(Reason::Invalid, Bytes::default()); }, @@ -485,7 +492,7 @@ mod tests { async fn attach(&self, owner: &lease::Consumer, request: Request) -> crate::Result { let context = owner .context() - .ok_or(Error::Refused)? + .ok_or(Error::Refused(Default::default()))? .attach(&request, &self.identity)?; admit(self.clone(), request, context).await } @@ -708,7 +715,7 @@ mod tests { "end overtook an in-flight connect for the same id" ); server.release.notify_one(); - assert!(matches!(pending.await.unwrap(), Err(Error::Refused))); + assert!(matches!(pending.await.unwrap(), Err(Error::Refused(_)))); assert!(matches!( log.end().await.event, Event::End { @@ -735,13 +742,13 @@ mod tests { 2 => request.role = Some(crate::Role::Publisher), _ => request.node = "another".into(), } - assert!(matches!(script.attach(&owner, request).await, Err(Error::Refused))); + assert!(matches!(script.attach(&owner, request).await, Err(Error::Refused(_)))); } let other = Script::new(log.clone(), |_| Some(Ok(grant(None, None)))); - assert!(matches!(other.attach(&owner, request()).await, Err(Error::Refused))); + assert!(matches!(other.attach(&owner, request()).await, Err(Error::Refused(_)))); assert_eq!(log.events(), [Event::Connect]); owner.clone().close("done", Bytes::default()); - assert!(matches!(script.attach(&owner, request()).await, Err(Error::Refused))); + assert!(matches!(script.attach(&owner, request()).await, Err(Error::Refused(_)))); } #[tokio::test] @@ -771,7 +778,7 @@ mod tests { let server = server(Log::default(), move |_| ResponseTemplate::new(status)).await; let err = client(&server).connect(request()).await.unwrap_err(); match status { - 401 | 403 => assert!(matches!(err, Error::Refused), "{status}: {err}"), + 401 | 403 => assert!(matches!(err, Error::Refused(_)), "{status}: {err}"), _ => assert!(matches!(err, Error::Unavailable(_)), "{status}: {err}"), } } @@ -785,7 +792,71 @@ mod tests { }) .await; let err = client(¬hing).connect(request()).await.unwrap_err(); - assert!(matches!(err, Error::Refused), "{err}"); + assert!(matches!(err, Error::Refused(_)), "{err}"); + } + + #[tokio::test] + async fn typed_refusal_preserves_reason_root_and_tier() { + use crate::refusal::Reason; + for reason in [Reason::Refused, Reason::Forbidden, Reason::Expired] { + for root in [None, Some("tenant")] { + for tier in [None, Some("edge")] { + let expected = crate::Refusal { + reason, + root: root.map(str::to_owned), + tier: tier.map(str::to_owned), + }; + let body = expected.clone(); + let server = server(Log::default(), move |_| ResponseTemplate::new(403).set_body_json(&body)).await; + let Error::Refused(actual) = client(&server).connect(request()).await.unwrap_err() else { + panic!("expected typed refusal") + }; + assert_eq!(actual, expected); + } + } + } + } + + #[tokio::test] + async fn legacy_and_future_refusals_are_bounded() { + for status in [401, 403] { + let server = server(Log::default(), move |_| { + ResponseTemplate::new(status).set_body_string("legacy refusal") + }) + .await; + let Error::Refused(actual) = client(&server).connect(request()).await.unwrap_err() else { + panic!("expected refusal") + }; + assert_eq!(actual, crate::Refusal::default()); + } + let server = server(Log::default(), |_| { + ResponseTemplate::new(403) + .set_body_json(serde_json::json!({"reason":"future","root":"tenant","tier":"edge"})) + }) + .await; + let Error::Refused(actual) = client(&server).connect(request()).await.unwrap_err() else { + panic!("expected refusal") + }; + assert_eq!(actual.reason, crate::refusal::Reason::Refused); + assert_eq!(actual.root.as_deref(), Some("tenant")); + assert_eq!(actual.tier.as_deref(), Some("edge")); + } + + #[tokio::test] + async fn expired_refusal_ends_a_rechecked_lease_as_expired() { + tokio::time::pause(); + let server = Script::new(Log::default(), |request| { + Some(match request.event { + Event::Connect => Ok(grant(Some(Duration::from_secs(3600)), Some(Duration::from_secs(1)))), + _ => Err(crate::Refusal { + reason: crate::refusal::Reason::Expired, + ..Default::default() + } + .into()), + }) + }); + let lease = server.connect().await.unwrap(); + assert_eq!(lease.closed().await, Reason::Expired); } #[tokio::test] diff --git a/rs/moq-auth/src/error.rs b/rs/moq-auth/src/error.rs index d0b00e99184..097124bbbf5 100644 --- a/rs/moq-auth/src/error.rs +++ b/rs/moq-auth/src/error.rs @@ -120,8 +120,8 @@ pub enum Error { #[error("invalid stats label: {0}")] InvalidLabel(moq_pattern::InvalidPattern), - #[error("the auth server refused the session")] - Refused, + #[error(transparent)] + Refused(#[from] crate::Refusal), #[error("auth server unavailable: {0}")] Unavailable(String), diff --git a/rs/moq-auth/src/key.rs b/rs/moq-auth/src/key.rs index 30a56d69901..072bac88aae 100644 --- a/rs/moq-auth/src/key.rs +++ b/rs/moq-auth/src/key.rs @@ -561,6 +561,15 @@ impl Key { Ok(claims) } + /// Verify the signature, claims, and key scope before reading expiry for attribution. + #[cfg(feature = "serve")] + pub(crate) fn verify_claims(&self, token: &str) -> crate::Result { + let claims: Claims = self.decode(token)?; + claims.validate()?; + self.validate_scope(&claims)?; + Ok(claims) + } + /// Sign the claims with this key, returning the encoded token. pub fn sign(&self, payload: &Claims) -> crate::Result { if !self.operations.contains(&KeyOperation::Sign) { @@ -611,7 +620,7 @@ impl Key { } /// Refuse claims expired at `now` (`exp <= now`) or not yet valid (`nbf > now`), as `jose` does. -fn validate_times(claims: &Claims, now: std::time::SystemTime) -> crate::Result<()> { +pub(crate) fn validate_times(claims: &Claims, now: std::time::SystemTime) -> crate::Result<()> { if claims.expires.is_some_and(|exp| exp <= now) { return Err(crate::Error::TokenExpired); } diff --git a/rs/moq-auth/src/lib.rs b/rs/moq-auth/src/lib.rs index ae274347297..b1d85f8edb6 100644 --- a/rs/moq-auth/src/lib.rs +++ b/rs/moq-auth/src/lib.rs @@ -3,7 +3,7 @@ //! A relay asks one question per session, "may this connect?", and this crate holds //! every piece of the answer: //! -//! - [`Request`] and [`Grant`]: the JSON a relay POSTs to an auth server on +//! - [`Request`], [`Grant`], and [`Refusal`]: the JSON a relay POSTs to an auth server on //! [`Event::Connect`], [`Event::Revalidate`], and [`Event::End`], and what comes back. //! - [`lease::Producer`] / [`lease::Consumer`]: the handle a session holds for its //! grant, so whoever runs the accept loop decides how, in process or over HTTP. @@ -31,6 +31,8 @@ mod set; mod wire; pub mod lease; +pub mod refusal; +pub use refusal::Refusal; #[cfg(feature = "serve")] pub mod serve; diff --git a/rs/moq-auth/src/refusal.rs b/rs/moq-auth/src/refusal.rs new file mode 100644 index 00000000000..e5671bbf738 --- /dev/null +++ b/rs/moq-auth/src/refusal.rs @@ -0,0 +1,42 @@ +//! The refusal an auth server or embedded decider answers. + +use serde::{Deserialize, Serialize}; + +/// A bounded reason an admission decider refuses a session. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +#[non_exhaustive] +pub enum Reason { + /// The credential does not allow the requested access. + Forbidden, + /// The verified credential has expired. + Expired, + /// The decider refused the credential or session. + #[default] + #[serde(other)] + Refused, +} + +impl std::fmt::Display for Reason { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(match self { + Self::Refused => "refused", + Self::Forbidden => "forbidden", + Self::Expired => "expired", + }) + } +} + +/// A refusal's reason and optional attribution, returned as JSON with HTTP 403. +#[serde_with::skip_serializing_none] +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, thiserror::Error)] +#[error("the admission decider refused the session: {reason}")] +#[non_exhaustive] +pub struct Refusal { + /// Why admission was refused; unknown JSON reasons read as `refused`. + pub reason: Reason, + /// A root named by a verified credential, never an unverified request path. + pub root: Option, + /// The tier resolved by the decider; absent uses the default tier. + pub tier: Option, +} diff --git a/rs/moq-auth/src/serve.rs b/rs/moq-auth/src/serve.rs index bbda75dcacc..17ea5c4952d 100644 --- a/rs/moq-auth/src/serve.rs +++ b/rs/moq-auth/src/serve.rs @@ -100,7 +100,7 @@ pub struct Policy { pub limits: Limits, } -/// Why a session was refused; the body of the 403. +/// The policy failure mapped to the typed refusal in the 403 body. #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] #[non_exhaustive] pub enum Refusal { @@ -115,15 +115,15 @@ pub enum Refusal { #[error("the token root `{root}` does not overlap the dialed path `{path}`")] RootMismatch { root: String, path: String }, #[error("nothing is granted at `{path}`")] - NoAccess { path: String }, + NoAccess { path: String, root: Option }, #[error("a certificate was presented but nothing is granted to certificates")] NoMtlsGrant, #[error("anonymous access is not granted")] NoPublicGrant, #[error("too many live sessions for this token")] - TokenLimit, + TokenLimit { root: Option }, #[error("too many live sessions from this address")] - RemoteLimit, + RemoteLimit { root: Option }, #[error("a SETUP token and a different `jwt` query were presented; present one")] TwoTokens, #[error("SETUP token type {0:#x} is not supported; only type 0 (a JWT) is")] @@ -132,36 +132,63 @@ pub enum Refusal { TokenAndCertificate, #[error("the policy's grant bound reaches past the system clock's range")] ExpiresOutOfRange, + #[error("the token has expired")] + Expired { root: String }, +} + +impl Refusal { + /// The shared refusal contract, with attribution only from a verified token. + fn body(&self, tier: Option) -> crate::Refusal { + use crate::refusal::Reason; + let reason = match self { + Self::Expired { .. } => Reason::Expired, + Self::RootMismatch { .. } | Self::NoAccess { .. } => Reason::Forbidden, + _ => Reason::Refused, + }; + let root = match self { + Self::Expired { root } | Self::RootMismatch { root, .. } => Some(root.clone()), + Self::NoAccess { root, .. } | Self::TokenLimit { root } | Self::RemoteLimit { root } => root.clone(), + _ => None, + }; + crate::Refusal { reason, root, tier } + } } impl Policy { /// Decide `request` by the policy alone, ignoring session limits. pub async fn decide(&self, request: &Request) -> Result { + Ok(self.decide_root(request).await?.0) + } + + async fn decide_root(&self, request: &Request) -> Result<(Grant, Option), Refusal> { let jwt = jwt(request)?; if jwt.is_some() && request.tls.is_some() { return Err(Refusal::TokenAndCertificate); } - let (permissions, expires, certificate) = if let Some(jwt) = jwt { + let (permissions, expires, certificate, root) = if let Some(jwt) = jwt { let claims = self.verify(jwt).await?; let permissions = claims.authorize(&request.path).map_err(|err| match err { crate::Error::RootMismatch(path) => Refusal::RootMismatch { root: claims.root.clone(), path, }, - crate::Error::NoAccess(path) => Refusal::NoAccess { path }, + crate::Error::NoAccess(path) => Refusal::NoAccess { + path, + root: Some(claims.root.clone()), + }, other => Refusal::InvalidToken(other.to_string()), })?; - (permissions, claims.expires, false) + (permissions, claims.expires, false, Some(claims.root)) } else if let Some(peer) = &request.tls { if self.mtls.is_empty() { return Err(Refusal::NoMtlsGrant); } - (authorize(&self.mtls, &request.path)?, peer.expires, true) + (authorize(&self.mtls, &request.path)?, peer.expires, true, None) } else { if self.public.is_empty() { return Err(Refusal::NoPublicGrant); } - (authorize(&self.public, &request.path)?, None, false) + (authorize(&self.public, &request.path)?, None, false, None) }; let mut grant = Grant::new(permissions.publish, permissions.subscribe); @@ -174,7 +201,7 @@ impl Policy { grant.tier = self.tier.clone(); grant.peer = certificate && self.mtls_peer; grant.upstream = certificate && self.mtls_upstream; - Ok(grant) + Ok((grant, root)) } async fn verify(&self, jwt: &str) -> Result { @@ -183,7 +210,7 @@ impl Policy { Keys::File(path) => Key::from_file_async(path) .await .map_err(|_| Refusal::UnknownKey)? - .verify(jwt), + .verify_claims(jwt), Keys::Dir(dir) => { let header = jsonwebtoken::decode_header(jwt).map_err(|err| Refusal::InvalidToken(err.to_string()))?; let kid = header.kid.ok_or(Refusal::MissingKeyId)?; @@ -191,20 +218,28 @@ impl Policy { Key::from_file_async(dir.join(format!("{kid}.jwk"))) .await .map_err(|_| Refusal::UnknownKey)? - .verify(jwt) + .verify_claims(jwt) } Keys::Set(path) => { let json = tokio::fs::read_to_string(path).await.map_err(|_| Refusal::UnknownKey)?; KeySet::from_str(&json) .map_err(|err| Refusal::InvalidToken(err.to_string()))? - .verify(jwt) + .key(jwt) + .and_then(|key| key.verify_claims(jwt)) } }; - claims.map_err(|err| match err { + let claims = claims.map_err(|err| match err { crate::Error::Key(crate::KeyError::MissingKid) => Refusal::MissingKeyId, crate::Error::Key(crate::KeyError::KeyNotFound(_)) => Refusal::UnknownKey, other => Refusal::InvalidToken(other.to_string()), - }) + })?; + crate::key::validate_times(&claims, SystemTime::now()).map_err(|err| match err { + crate::Error::TokenExpired => Refusal::Expired { + root: claims.root.clone(), + }, + other => Refusal::InvalidToken(other.to_string()), + })?; + Ok(claims) } } @@ -219,6 +254,7 @@ fn authorize(rules: &Permissions, path: &str) -> Result { // An empty root overlaps every path, so the only refusal is reaching nothing. claims.authorize(path).map_err(|_| Refusal::NoAccess { path: crate::path::normalize(path), + root: None, }) } @@ -279,7 +315,7 @@ impl Sessions { /// Admit a `connect`, refusing over the cap. A known id is the same session /// attaching another credential: it holds no new remote slot, but a JWT new to /// it counts against that JWT's cap until the session ends. - fn connect(&mut self, request: &Request, limits: Limits) -> Result<(), Refusal> { + fn connect(&mut self, request: &Request, limits: Limits, root: Option) -> Result<(), Refusal> { // Decided before counting, so the credential is already known to be one JWT. let token = jwt(request).ok().flatten().map(hash); let known = self.slots.get(&request.id); @@ -287,7 +323,7 @@ impl Sessions { if let (Some(cap), Some(token)) = (limits.token, new_token) && self.slots.values().filter(|slot| slot.tokens.contains(&token)).count() >= cap { - return Err(Refusal::TokenLimit); + return Err(Refusal::TokenLimit { root }); } if let Some(slot) = self.slots.get_mut(&request.id) { slot.tokens.extend(new_token); @@ -298,7 +334,7 @@ impl Sessions { if let (Some(cap), Some(remote)) = (limits.remote, remote) && self.slots.values().filter(|slot| slot.remote == Some(remote)).count() >= cap { - return Err(Refusal::RemoteLimit); + return Err(Refusal::RemoteLimit { root }); } self.slots.insert( request.id.clone(), @@ -388,11 +424,11 @@ impl Server { pub async fn answer(&self, request: &Request) -> Result, Refusal> { match request.event { Event::Connect => { - let grant = self.policy.decide(request).await?; + let (grant, root) = self.policy.decide_root(request).await?; if let Some(cadence) = self.cadence() { let mut sessions = self.sessions.lock().unwrap(); sessions.sweep(cadence); - sessions.connect(request, self.policy.limits)?; + sessions.connect(request, self.policy.limits, root)?; } Ok(Some(grant)) } @@ -437,7 +473,7 @@ async fn handle(State(server): State, Json(request): Json) -> R // which rule refused without the server saying anything to the client. Err(refusal) => { tracing::debug!(id = %request.id, path = %request.path, %refusal, "refused"); - (StatusCode::FORBIDDEN, refusal.to_string()).into_response() + (StatusCode::FORBIDDEN, Json(refusal.body(server.policy.tier.clone()))).into_response() } } } @@ -600,7 +636,7 @@ mod tests { Some(SystemTime::now() - Duration::from_secs(1)), ); let err = policy.decide(&with_token(request("/demo"), &jwt)).await.unwrap_err(); - assert!(matches!(err, Refusal::InvalidToken(_)), "{err}"); + assert!(matches!(err, Refusal::Expired { .. }), "{err}"); // Signed by a stranger. let stranger = Key::generate(Algorithm::HS256, Some(KeyId::decode("kid1").unwrap())).unwrap(); @@ -708,7 +744,10 @@ mod tests { assert!(server.answer(&first).await.unwrap().is_some()); let mut second = request("/room"); second.transport = transport; - assert_eq!(server.answer(&second).await.unwrap_err(), Refusal::RemoteLimit); + assert_eq!( + server.answer(&second).await.unwrap_err(), + Refusal::RemoteLimit { root: None } + ); first.event = Event::End { reason: Reason::Shutdown, duration: Duration::ZERO, @@ -957,7 +996,8 @@ mod tests { assert_eq!( policy.decide(&request(path)).await.unwrap_err(), Refusal::NoAccess { - path: path.trim_start_matches('/').into() + path: path.trim_start_matches('/').into(), + root: None }, ); } @@ -988,11 +1028,17 @@ mod tests { let third = request("/"); server.answer(&first).await.unwrap(); server.answer(&second).await.unwrap(); - assert_eq!(server.answer(&third).await.unwrap_err(), Refusal::RemoteLimit); + assert_eq!( + server.answer(&third).await.unwrap_err(), + Refusal::RemoteLimit { root: None } + ); // A repeated connect for a known id refreshes rather than double-counting. server.answer(&first).await.unwrap(); - assert_eq!(server.answer(&third).await.unwrap_err(), Refusal::RemoteLimit); + assert_eq!( + server.answer(&third).await.unwrap_err(), + Refusal::RemoteLimit { root: None } + ); // Another address is unaffected. let mut elsewhere = request("/"); @@ -1018,7 +1064,10 @@ mod tests { // `third` is 180s old and gone; `second` was seen 90s ago and holds its slot. let fourth = request("/"); server.answer(&fourth).await.unwrap(); - assert_eq!(server.answer(&request("/")).await.unwrap_err(), Refusal::RemoteLimit); + assert_eq!( + server.answer(&request("/")).await.unwrap_err(), + Refusal::RemoteLimit { root: None } + ); } /// The re-check a session table ages out by, which every limit needs. @@ -1081,7 +1130,10 @@ mod tests { }) .unwrap(); server.answer(&request("/")).await.unwrap(); - assert_eq!(server.answer(&request("/")).await.unwrap_err(), Refusal::RemoteLimit); + assert_eq!( + server.answer(&request("/")).await.unwrap_err(), + Refusal::RemoteLimit { root: None } + ); } /// With no limit to count against, nothing is kept per session, so a relay that @@ -1116,7 +1168,12 @@ mod tests { server.answer(&with_token(request("/demo"), &jwt)).await.unwrap(); let mut mapped = with_token(request("/demo"), &jwt); mapped.remote = Some("[::ffff:203.0.113.9]:9".parse().unwrap()); - assert_eq!(server.answer(&mapped).await.unwrap_err(), Refusal::TokenLimit); + assert_eq!( + server.answer(&mapped).await.unwrap_err(), + Refusal::TokenLimit { + root: Some("demo".into()) + } + ); let other = sign( &key, @@ -1127,7 +1184,12 @@ mod tests { ); let mut same_host = with_token(request("/demo"), &other); same_host.remote = Some("[::ffff:203.0.113.9]:9".parse().unwrap()); - assert_eq!(server.answer(&same_host).await.unwrap_err(), Refusal::RemoteLimit); + assert_eq!( + server.answer(&same_host).await.unwrap_err(), + Refusal::RemoteLimit { + root: Some("demo".into()) + } + ); } /// An in-band credential arrives as a `connect` for a live session id. It takes @@ -1170,7 +1232,12 @@ mod tests { server.answer(&attach(&first)).await.unwrap(); // Re-presenting a JWT the session already holds is not another use of it. server.answer(&attach(&first)).await.unwrap(); - assert_eq!(server.answer(&attach(&second)).await.unwrap_err(), Refusal::TokenLimit); + assert_eq!( + server.answer(&attach(&second)).await.unwrap_err(), + Refusal::TokenLimit { + root: Some("demo".into()) + } + ); assert_eq!(server.sessions.lock().unwrap().slots.len(), 2); } @@ -1190,7 +1257,7 @@ mod tests { assert_eq!(consumer.grant().publish, patterns(&["**"]).into()); let err = client.connect(request("/demo")).await.unwrap_err(); - assert!(matches!(err, Error::Refused), "{err}"); + assert!(matches!(err, Error::Refused(_)), "{err}"); // The end frees the slot for the next session. consumer.close("done", Bytes::default()); @@ -1198,6 +1265,92 @@ mod tests { client.connect(request("/demo")).await.unwrap(); } + #[tokio::test] + async fn serve_client_refusals_attribute_only_verified_roots() { + use crate::refusal::Reason; + let (dir, key) = key_dir(); + let stranger = Key::generate(Algorithm::HS256, key.kid.clone()).unwrap(); + let expired = Some(SystemTime::UNIX_EPOCH + Duration::from_secs(1)); + for tier in [None, Some("edge")] { + let (client, _) = serve(Policy { + keys: Some(Keys::Dir(dir.path().into())), + tier: tier.map(str::to_owned), + ..Default::default() + }) + .await; + let expired_jwt = sign(&key, "tenant", &["media/**"], &[], expired); + let valid_jwt = sign(&key, "tenant", &["media/**"], &[], None); + let forged_jwt = sign(&stranger, "forged", &["**"], &[], expired); + for (path, token, reason, root) in [ + ( + "/attacker/path", + Some(expired_jwt.as_str()), + Reason::Expired, + Some("tenant"), + ), + ( + "/attacker/path", + Some(valid_jwt.as_str()), + Reason::Forbidden, + Some("tenant"), + ), + ( + "/tenant/no-access", + Some(valid_jwt.as_str()), + Reason::Forbidden, + Some("tenant"), + ), + ("/attacker/path", Some(forged_jwt.as_str()), Reason::Refused, None), + ("/attacker/path", None, Reason::Refused, None), + ] { + let mut request = request(path); + if let Some(jwt) = token { + request = with_token(request, jwt); + } + let Error::Refused(refusal) = client.connect(request).await.unwrap_err() else { + panic!("expected refusal") + }; + assert_eq!(refusal.reason, reason); + assert_eq!(refusal.root.as_deref(), root); + assert_eq!(refusal.tier.as_deref(), tier); + } + } + } + + #[tokio::test] + async fn expired_out_of_scope_claims_are_never_attributed() { + let (dir, key) = key_dir(); + let scoped = key + .clone() + .with_scope(crate::Scope { + root: "tenant".into(), + publish: patterns(&["allowed/**"]), + subscribe: Patterns::default(), + }) + .unwrap(); + scoped.to_file(dir.path().join("kid1.jwk")).unwrap(); + let (client, _) = serve(Policy { + keys: Some(Keys::Dir(dir.path().into())), + ..Default::default() + }) + .await; + let token = sign( + &key, + "attacker", + &["**"], + &[], + Some(SystemTime::UNIX_EPOCH + Duration::from_secs(1)), + ); + let Error::Refused(refusal) = client + .connect(with_token(request("/attacker"), &token)) + .await + .unwrap_err() + else { + panic!("expected refusal") + }; + assert_eq!(refusal, crate::Refusal::default()); + } + #[cfg(unix)] #[tokio::test] async fn serves_on_a_unix_socket() { diff --git a/rs/moq-auth/src/set.rs b/rs/moq-auth/src/set.rs index 48e4db1a4b5..c86fe27096c 100644 --- a/rs/moq-auth/src/set.rs +++ b/rs/moq-auth/src/set.rs @@ -110,9 +110,12 @@ impl KeySet { /// /// A token without a `kid` is accepted only when the set holds exactly one key and that key has no `kid`. pub fn verify(&self, token: &str) -> crate::Result { - let header = jsonwebtoken::decode_header(token)?; + self.key(token)?.verify(token) + } - let key = match header.kid { + pub(crate) fn key(&self, token: &str) -> crate::Result> { + let header = jsonwebtoken::decode_header(token)?; + match header.kid { Some(kid) => self .find_key(kid.as_str()) .ok_or_else(|| crate::Error::from(KeyError::KeyNotFound(kid))), @@ -124,9 +127,7 @@ impl KeySet { Err(KeyError::MissingKid.into()) } } - }?; - - key.verify(token) + } } } diff --git a/rs/moq-net/src/stats/outcomes.rs b/rs/moq-net/src/stats/outcomes.rs index 86cb3567ef1..0ed219342c6 100644 --- a/rs/moq-net/src/stats/outcomes.rs +++ b/rs/moq-net/src/stats/outcomes.rs @@ -17,6 +17,8 @@ pub enum Refusal { Forbidden, /// The LAN membership proof was missing or invalid. Lan, + /// The verified credential expired before admission. + Expired, } impl Refusal { @@ -27,6 +29,7 @@ impl Refusal { Self::Request, Self::Forbidden, Self::Lan, + Self::Expired, ]; /// The stable stats and metrics name. pub const fn as_str(self) -> &'static str { @@ -36,6 +39,7 @@ impl Refusal { Self::Request => "request", Self::Forbidden => "forbidden", Self::Lan => "lan", + Self::Expired => "expired", } } } @@ -55,6 +59,8 @@ pub struct Refusals { pub forbidden: u64, /// The LAN membership proof was missing or invalid. pub lan: u64, + /// The verified credential expired before admission. + pub expired: u64, } impl Refusals { @@ -66,6 +72,7 @@ impl Refusals { Refusal::Request => self.request, Refusal::Forbidden => self.forbidden, Refusal::Lan => self.lan, + Refusal::Expired => self.expired, } } /// Add every kind from another readout. @@ -75,6 +82,7 @@ impl Refusals { self.request += other.request; self.forbidden += other.forbidden; self.lan += other.lan; + self.expired += other.expired; } /// Whether any cumulative count went backwards. pub fn regressed(&self, previous: &Self) -> bool { @@ -83,6 +91,7 @@ impl Refusals { || self.request < previous.request || self.forbidden < previous.forbidden || self.lan < previous.lan + || self.expired < previous.expired } } @@ -93,6 +102,7 @@ pub(super) struct RefusalCounters { request: AtomicU64, forbidden: AtomicU64, lan: AtomicU64, + expired: AtomicU64, } impl RefusalCounters { @@ -103,6 +113,7 @@ impl RefusalCounters { Refusal::Request => &self.request, Refusal::Forbidden => &self.forbidden, Refusal::Lan => &self.lan, + Refusal::Expired => &self.expired, } } pub(super) fn snapshot(&self) -> Refusals { @@ -112,6 +123,7 @@ impl RefusalCounters { request: self.request.load(Ordering::Relaxed), forbidden: self.forbidden.load(Ordering::Relaxed), lan: self.lan.load(Ordering::Relaxed), + expired: self.expired.load(Ordering::Relaxed), } } } diff --git a/rs/moq-relay/MIGRATE.md b/rs/moq-relay/MIGRATE.md index 46e3d1da268..b7ba6ee085d 100644 --- a/rs/moq-relay/MIGRATE.md +++ b/rs/moq-relay/MIGRATE.md @@ -5,6 +5,12 @@ Rolling a cluster across a release also follows the [upgrade guide](https://moq. ## Unreleased +### Typed admission refusals + +`auth::Error::Refused` now carries the shared `moq_auth::Refusal`. +Pass `auth::Error::Refused(moq_auth::Refusal::default())` to `Admission::refuse` for an unattributed refusal, or set its `reason`, optional verified `root`, and `tier`. +Match `auth::Error::Refused(refusal)` to inspect it; never use the dialed path as refusal attribution. + ### Cluster dials build from a template (#5674) `Relay::client()` and `Cluster::with_client` are removed. diff --git a/rs/moq-relay/benches/auth.rs b/rs/moq-relay/benches/auth.rs index 4458d6f89bc..0dd360d2458 100644 --- a/rs/moq-relay/benches/auth.rs +++ b/rs/moq-relay/benches/auth.rs @@ -223,7 +223,10 @@ impl Queue { } async fn round(&mut self) { - self.held.pop_front().unwrap().refuse(auth::Error::Refused); + self.held + .pop_front() + .unwrap() + .refuse(auth::Error::Refused(Default::default())); self.present(); let admission = self.admissions.next().await.unwrap(); self.held.push_back(admission); diff --git a/rs/moq-relay/src/auth.rs b/rs/moq-relay/src/auth.rs index 6c31ade1071..4cf43917d77 100644 --- a/rs/moq-relay/src/auth.rs +++ b/rs/moq-relay/src/auth.rs @@ -353,8 +353,8 @@ impl Config { #[non_exhaustive] pub enum Error { /// The auth server answered and the answer was no. - #[error("the auth server refused the session")] - Refused, + #[error(transparent)] + Refused(moq_auth::Refusal), /// The auth server could not be asked, or answered nonsense; nothing is /// admitted because the server was down. @@ -373,7 +373,8 @@ pub enum Error { impl From for Error { fn from(err: moq_auth::Error) -> Self { match err { - moq_auth::Error::Refused | moq_auth::Error::UselessGrant => Self::Refused, + moq_auth::Error::Refused(refusal) => Self::Refused(refusal), + moq_auth::Error::UselessGrant => Self::Refused(Default::default()), other => Self::Unavailable(other.to_string()), } } @@ -386,6 +387,9 @@ impl From<&Error> for http::StatusCode { Error::Unavailable(_) => http::StatusCode::BAD_GATEWAY, Error::Request(_) => http::StatusCode::BAD_REQUEST, Error::Forbidden(_) => http::StatusCode::FORBIDDEN, + Error::Refused(refusal) if refusal.reason == moq_auth::refusal::Reason::Forbidden => { + http::StatusCode::FORBIDDEN + } _ => http::StatusCode::UNAUTHORIZED, } } @@ -796,7 +800,7 @@ impl Decider { // its holder expects it to count, and the public grant is not what it says. Self::Public(_) if presents_token(&admission.request) => { tracing::debug!(path = %admission.request.path, "a token was presented to public rules"); - admission.refuse(Error::Refused); + admission.refuse(Error::Refused(Default::default())); } Self::Public(rules) => match rules.authorize(&admission.request.path) { Ok(access) => { @@ -807,10 +811,10 @@ impl Decider { // client would retry. Err(err) => { tracing::debug!(path = %admission.request.path, %err, "public rules refused"); - admission.refuse(Error::Refused); + admission.refuse(Error::Refused(Default::default())); } }, - Self::Refuse => admission.refuse(Error::Refused), + Self::Refuse => admission.refuse(Error::Refused(Default::default())), } } }); @@ -1163,6 +1167,20 @@ mod tests { assert!(lease.token().label.is_empty(), "the label never applied"); } + #[test] + fn typed_refusal_preserves_transport_status() { + for (reason, status) in [ + (moq_auth::refusal::Reason::Refused, http::StatusCode::UNAUTHORIZED), + (moq_auth::refusal::Reason::Expired, http::StatusCode::UNAUTHORIZED), + (moq_auth::refusal::Reason::Forbidden, http::StatusCode::FORBIDDEN), + ] { + let mut refusal = moq_auth::Refusal::default(); + refusal.reason = reason; + let error = Error::from(moq_auth::Error::Refused(refusal)); + assert_eq!(http::StatusCode::from(&error), status); + } + } + #[test] fn every_transport_has_an_auth_name() { use moq_tokio::Transport as T; @@ -1255,7 +1273,7 @@ mod tests { let Err(err) = auth.admit(auth.request(moq_auth::Transport::Quic, path)).await else { panic!("{path} was admitted"); }; - assert!(matches!(err, Error::Refused), "{path}: {err}"); + assert!(matches!(err, Error::Refused(_)), "{path}: {err}"); assert_eq!(http::StatusCode::from(&err), http::StatusCode::UNAUTHORIZED); } } @@ -1280,7 +1298,7 @@ mod tests { let Err(err) = auth.admit(request).await else { panic!("a token was admitted on the public grant"); }; - assert!(matches!(err, Error::Refused), "{err}"); + assert!(matches!(err, Error::Refused(_)), "{err}"); } // An empty `jwt=` is no token. @@ -1360,7 +1378,7 @@ mod tests { assert_eq!(admission.request.path, "/anon/room"); admission.grant(lease::Consumer::fixed(Grant::new(patterns(&["**"]), patterns(&["**"])))); let admission = admissions.next().await.expect("an admission"); - admission.refuse(Error::Refused); + admission.refuse(Error::Refused(Default::default())); // A grant that admits nothing is the decider's mistake, refused like a server's. let admission = admissions.next().await.expect("an admission"); admission.grant(lease::Consumer::fixed(Grant::new(Patterns::new(), Patterns::new()))); @@ -1371,8 +1389,8 @@ mod tests { let admit = async { let lease = auth.admit(request()).await.expect("granted"); assert_eq!(lease.token().root, Path::new("anon/room").to_owned()); - assert!(matches!(auth.admit(request()).await, Err(Error::Refused))); - assert!(matches!(auth.admit(request()).await, Err(Error::Refused))); + assert!(matches!(auth.admit(request()).await, Err(Error::Refused(_)))); + assert!(matches!(auth.admit(request()).await, Err(Error::Refused(_)))); assert!(matches!(auth.admit(request()).await, Err(Error::Unavailable(_)))); }; let (admissions, ()) = tokio::join!(decide, admit); @@ -1399,7 +1417,7 @@ mod tests { async fn refuse_answers_the_admission_queue() { let auth = Auth::refuse("relay-1"); let request = auth.request(moq_auth::Transport::Quic, "/anon/room"); - assert!(matches!(auth.admit(request).await, Err(Error::Refused))); + assert!(matches!(auth.admit(request).await, Err(Error::Refused(_)))); } /// The session supervisor re-polls `ended` on every nudge; that must not diff --git a/rs/moq-relay/src/auth/refresh.rs b/rs/moq-relay/src/auth/refresh.rs index 0668d3c78de..1e03db153f4 100644 --- a/rs/moq-relay/src/auth/refresh.rs +++ b/rs/moq-relay/src/auth/refresh.rs @@ -944,7 +944,7 @@ mod tests { other.publish = Default::default(); admission.grant(lease::Consumer::fixed(other)); } else { - admission.refuse(super::super::Error::Refused); + admission.refuse(super::super::Error::Refused(Default::default())); } }); assert!(result.is_err()); diff --git a/rs/moq-relay/src/cluster.rs b/rs/moq-relay/src/cluster.rs index cd5949b448f..1f64f92134e 100644 --- a/rs/moq-relay/src/cluster.rs +++ b/rs/moq-relay/src/cluster.rs @@ -1268,7 +1268,7 @@ impl Cluster { self.scope(lease, &request) } .await; - result.inspect_err(|err| self.refusals.record(err.into())) + result.inspect_err(|err| self.refusals.record_auth(err)) } /// Network sessions enforce changing grants in AUTH, within a fixed root and SETUP role. @@ -1282,7 +1282,7 @@ impl Cluster { self.scope_session(lease, &request) } .await; - result.inspect_err(|err| self.refusals.record(err.into())) + result.inspect_err(|err| self.refusals.record_auth(err)) } pub(crate) fn scope_session( diff --git a/rs/moq-relay/src/refusals.rs b/rs/moq-relay/src/refusals.rs index 1d498c3c63f..07d9c65b5ca 100644 --- a/rs/moq-relay/src/refusals.rs +++ b/rs/moq-relay/src/refusals.rs @@ -8,7 +8,11 @@ impl From<&auth::Error> for Refusal { // Exhaustive on purpose: a new `auth::Error` variant must pick its reason here. fn from(err: &auth::Error) -> Self { match err { - auth::Error::Refused => Refusal::Refused, + auth::Error::Refused(refusal) => match refusal.reason { + moq_auth::refusal::Reason::Forbidden => Refusal::Forbidden, + moq_auth::refusal::Reason::Expired => Refusal::Expired, + _ => Refusal::Refused, + }, auth::Error::Unavailable(_) => Refusal::Unavailable, auth::Error::Forbidden(_) => Refusal::Forbidden, auth::Error::Request(_) => Refusal::Request, @@ -37,6 +41,15 @@ impl Refusals { pub(crate) fn record(&self, reason: Refusal) { self.0.tier(Tier::default()).refuse("", reason); } + pub(crate) fn record_auth(&self, err: &auth::Error) { + if let auth::Error::Refused(refusal) = err { + self.0 + .tier(refusal.tier.clone().map(Tier::new).unwrap_or_default()) + .refuse(refusal.root.as_deref().unwrap_or(""), err.into()); + } else { + self.record(err.into()); + } + } pub(crate) fn snapshot(&self) -> moq_net::stats::Refusals { let mut counts = moq_net::stats::Refusals::default(); for (_, presence) in self.0.snapshot().sessions() { @@ -49,3 +62,43 @@ impl Refusals { self.snapshot().count(reason) } } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn typed_refusals_keep_only_decider_attribution() { + let registry = Registry::new(Default::default()); + let refusals = Refusals::new(®istry); + for reason in [ + moq_auth::refusal::Reason::Refused, + moq_auth::refusal::Reason::Forbidden, + moq_auth::refusal::Reason::Expired, + ] { + for root in [None, Some("tenant")] { + for tier in [None, Some("edge")] { + let mut refusal = moq_auth::Refusal::default(); + refusal.reason = reason; + refusal.root = root.map(str::to_owned); + refusal.tier = tier.map(str::to_owned); + let error = auth::Error::Refused(refusal); + refusals.record_auth(&error); + } + } + } + let mut report = moq_net::stats::Report::default(); + registry.report(&mut report); + assert_eq!(report.sessions.len(), 4); + for entry in report.sessions { + assert!(["", "tenant"].contains(&entry.label.as_str())); + assert!(["", "edge"].contains(&entry.tier.as_str())); + let presence = entry.presence; + assert_eq!(presence.sessions_started, 0); + assert_eq!(presence.sessions_refused.refused, 1); + assert_eq!(presence.sessions_refused.forbidden, 1); + assert_eq!(presence.sessions_refused.expired, 1); + } + assert_eq!(refusals.count(Refusal::Expired), 4); + } +} diff --git a/rs/moq-relay/src/shutdown.rs b/rs/moq-relay/src/shutdown.rs index e9f6ade656a..8b0183662be 100644 --- a/rs/moq-relay/src/shutdown.rs +++ b/rs/moq-relay/src/shutdown.rs @@ -276,7 +276,7 @@ mod tests { let admission = admissions.next().await.unwrap(); trigger.start(); let waited = shutdown.drained().now_or_never().is_none(); - admission.refuse(crate::auth::Error::Refused); + admission.refuse(crate::auth::Error::Refused(Default::default())); drop(connecting.await.unwrap()); running.await.unwrap().unwrap(); assert!(waited, "drain completed while auth admission is pending"); diff --git a/rs/moq-relay/tests/integration/auth_embedder.rs b/rs/moq-relay/tests/integration/auth_embedder.rs index 94421e466cf..ce2101783a5 100644 --- a/rs/moq-relay/tests/integration/auth_embedder.rs +++ b/rs/moq-relay/tests/integration/auth_embedder.rs @@ -158,10 +158,14 @@ async fn gateway_admission_refuses_once_in_the_shared_stats_registry() { let (result, ()) = tokio::join!( cluster.admit(&auth, auth.request(Transport::Srt, "/unattributed")), async { - admissions.next().await.unwrap().refuse(auth::Error::Refused); + admissions + .next() + .await + .unwrap() + .refuse(auth::Error::Refused(Default::default())); } ); - assert!(matches!(result, Err(auth::Error::Refused))); + assert!(matches!(result, Err(auth::Error::Refused(_)))); let values = registry.snapshot().sessions(); assert_eq!(values.len(), 1); assert_eq!(values[0].0, moq_net::stats::Tier::default()); @@ -175,3 +179,42 @@ async fn gateway_admission_refuses_once_in_the_shared_stats_registry() { "a refused admission counts under the empty label" ); } + +#[tokio::test] +async fn embedded_expired_refusals_keep_verified_root_and_tier() { + tokio::time::pause(); + let cluster = cluster::Cluster::new(cluster::Options::default()).unwrap(); + let mut config = moq_relay::stats::Config::default(); + config.enabled = true; + let producer = config.build(cluster.origin.clone()); + let registry = producer.registry().clone(); + let cluster = cluster.with_stats(producer); + let (auth, mut admissions) = auth::Auth::embedded("edge"); + for tier in [None, Some("edge")] { + let mut refusal = moq_auth::Refusal::default(); + refusal.reason = moq_auth::refusal::Reason::Expired; + refusal.root = Some("verified/tenant".into()); + refusal.tier = tier.map(str::to_owned); + let expected = refusal.clone(); + let (result, ()) = tokio::join!( + cluster.admit(&auth, auth.request(Transport::Rtmp, "/attacker/path")), + async { + admissions.next().await.unwrap().refuse(auth::Error::Refused(refusal)); + } + ); + let Err(auth::Error::Refused(actual)) = result else { + panic!("expected typed refusal") + }; + assert_eq!(actual, expected); + } + let mut report = moq_net::stats::Report::default(); + registry.report(&mut report); + assert_eq!(report.sessions.len(), 2); + for entry in report.sessions { + assert!(["", "edge"].contains(&entry.tier.as_str())); + assert_eq!(entry.label.as_str(), "verified/tenant"); + let presence = entry.presence; + assert_eq!(presence.sessions_started, 0); + assert_eq!(presence.sessions_refused.expired, 1); + } +} diff --git a/rs/moq-relay/tests/integration/auth_lifetime.rs b/rs/moq-relay/tests/integration/auth_lifetime.rs index 0268b9b43dc..7de653ee3dc 100644 --- a/rs/moq-relay/tests/integration/auth_lifetime.rs +++ b/rs/moq-relay/tests/integration/auth_lifetime.rs @@ -1236,7 +1236,7 @@ async fn an_embedded_decider_admits_and_revokes() { let (refusing, mut refusals) = moq_relay::auth::Auth::embedded("test-relay"); tokio::spawn(async move { while let Some(admission) = refusals.next().await { - admission.refuse(moq_relay::auth::Error::Refused); + admission.refuse(moq_relay::auth::Error::Refused(Default::default())); } }); let (refused_port, refusing_relay) = spawn_relay(refusing).await; diff --git a/rs/moq-relay/tests/integration/refusals.rs b/rs/moq-relay/tests/integration/refusals.rs index b1c75998b54..ede5bec86e0 100644 --- a/rs/moq-relay/tests/integration/refusals.rs +++ b/rs/moq-relay/tests/integration/refusals.rs @@ -370,3 +370,53 @@ async fn explicit_auth_server_refusal_counts_once() { stop.send(()).unwrap(); server.await.unwrap(); } + +#[tokio::test] +async fn expired_verified_tokens_count_under_the_token_root_and_auth_tier() { + let keys = tempfile::tempdir().unwrap(); + let key = moq_auth::Key::generate(moq_auth::Algorithm::HS256, None).unwrap(); + let key_path = keys.path().join("key.jwk"); + key.to_file(&key_path).unwrap(); + let mut claims = moq_auth::Claims::default() + .with_root("verified/tenant") + .with_subscribe(moq_auth::Pattern::all()); + claims.expires = Some(std::time::SystemTime::UNIX_EPOCH + Duration::from_secs(1)); + let token = key.sign(&claims).unwrap(); + for tier in [None, Some("edge")] { + let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let mut policy = moq_auth::serve::Policy::default(); + policy.keys = Some(moq_auth::serve::Keys::File(key_path.clone())); + policy.tier = tier.map(str::to_owned); + let server = moq_auth::serve::Server::new(policy).unwrap(); + let auth_url = format!("http://{}/", listener.local_addr().unwrap()); + let running = tokio::spawn(async move { + server.serve(listener).await.unwrap(); + }); + let dir = tempfile::tempdir().unwrap(); + let mut config = config(dir.path(), false); + config.auth.url = Some(auth_url.parse().unwrap()); + config.stats.enabled = true; + let relay = start(config).await; + assert_refused( + format!("https://{}/attacker/path?jwt={token}", relay.quic) + .parse() + .unwrap(), + false, + ) + .await; + assert_eq!(relay.refused("expired").await, 1); + assert_eq!(relay.refused("refused").await, 0); + let mut report = moq_net::stats::Report::default(); + relay.stats.report(&mut report); + assert_eq!(report.sessions.len(), 1); + let entry = &report.sessions[0]; + assert_eq!(entry.tier.as_str(), tier.unwrap_or("")); + assert_eq!(entry.label.as_str(), "verified/tenant"); + let presence = entry.presence; + assert_eq!(presence.sessions_started, 0); + assert_eq!(presence.sessions_refused.expired, 1); + relay.stop().await; + running.abort(); + assert!(running.await.unwrap_err().is_cancelled()); + } +} From 4b50a4f7194a441fb2c6f4097ced8f736d48b54e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 16:42:06 -0700 Subject: [PATCH 3/4] refactor(auth): verify a token's times on top of verify_claims Co-Authored-By: Claude Opus 5.5 --- rs/moq-auth/src/key.rs | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/rs/moq-auth/src/key.rs b/rs/moq-auth/src/key.rs index 072bac88aae..18360aeeead 100644 --- a/rs/moq-auth/src/key.rs +++ b/rs/moq-auth/src/key.rs @@ -554,15 +554,13 @@ impl Key { /// Scoping the claims to a connection path is a separate step; see /// [`Claims::authorize`]. pub fn verify(&self, token: &str) -> crate::Result { - let claims: Claims = self.decode(token)?; + let claims = self.verify_claims(token)?; validate_times(&claims, std::time::SystemTime::now())?; - claims.validate()?; - self.validate_scope(&claims)?; Ok(claims) } - /// Verify the signature, claims, and key scope before reading expiry for attribution. - #[cfg(feature = "serve")] + /// Verify the signature, claims, and key scope but not the times, so an expired + /// token's root is still known to be genuine. pub(crate) fn verify_claims(&self, token: &str) -> crate::Result { let claims: Claims = self.decode(token)?; claims.validate()?; From 05ae3924dae6c948af882066f141ab3e521f519e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 18:26:55 -0700 Subject: [PATCH 4/4] fix(relay): attribute HTTP fetch and announced refusals to the decider's root and tier Co-Authored-By: Claude Opus 5.5 --- rs/moq-relay/src/web.rs | 59 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 58 insertions(+), 1 deletion(-) diff --git a/rs/moq-relay/src/web.rs b/rs/moq-relay/src/web.rs index fdd8b9bd165..ce57894e5d3 100644 --- a/rs/moq-relay/src/web.rs +++ b/rs/moq-relay/src/web.rs @@ -988,7 +988,7 @@ async fn admit_http( .auth .admit(request) .await - .inspect_err(|err| state.cluster.refusals.record(err.into()))?; + .inspect_err(|err| state.cluster.refusals.record_auth(err))?; let token = lease.token(); let Some(origin) = state.cluster.subscriber(token) else { state.cluster.refusals.record(crate::refusals::Refusal::Forbidden); @@ -1247,6 +1247,63 @@ mod tests { } } + #[tokio::test(start_paused = true)] + async fn http_refusals_keep_the_deciders_root_and_tier() { + use moq_net::stats::{Registry, Report}; + let dir = TempDir::new().unwrap(); + let (_, cert, _) = make_certs(&dir); + let certificates = moq_tokio::tls::Certificates::from_pem(&std::fs::read(cert).unwrap()).unwrap(); + let (auth, mut admissions) = auth::Auth::embedded("test"); + let decider = tokio::spawn(async move { + for _ in 0..2 { + let mut refusal = moq_auth::Refusal::default(); + refusal.reason = moq_auth::refusal::Reason::Expired; + refusal.root = Some("tenant".into()); + refusal.tier = Some("edge".into()); + admissions.next().await.unwrap().refuse(auth::Error::Refused(refusal)); + } + }); + let registry = Registry::new(Default::default()); + let mut cluster = cluster::Cluster::new(crate::cluster::Options::default()).unwrap(); + cluster.refusals = crate::refusals::Refusals::new(®istry); + let state = Web::new(auth, cluster, certificates, Config::default()).state; + let fetched = serve_fetch( + Path("room/video".to_owned()), + Query(FetchParams { + auth: AuthQuery { jwt: None }, + group: FetchGroup::Latest, + }), + None, + ConnectInfo(crate::listener::Peer("127.0.0.1:1234".parse().unwrap())), + "/fetch/room/video".parse().unwrap(), + http::HeaderMap::new(), + State(state.clone()), + ) + .await; + assert!(fetched.is_err(), "fetch was admitted"); + let announced = serve_announced( + Some(Path("room".to_owned())), + Query(AuthQuery { jwt: None }), + None, + ConnectInfo(crate::listener::Peer("127.0.0.1:1234".parse().unwrap())), + "/announced/room".parse().unwrap(), + http::HeaderMap::new(), + State(state.clone()), + ) + .await; + assert!(announced.is_err(), "announced was admitted"); + decider.await.unwrap(); + + let mut report = Report::default(); + registry.report(&mut report); + let [entry] = report.sessions.as_slice() else { + panic!("expected one attributed entry: {:?}", report.sessions); + }; + assert_eq!(entry.label.as_str(), "tenant"); + assert_eq!(entry.tier.as_str(), "edge"); + assert_eq!(entry.presence.sessions_refused.expired, 2); + } + #[tokio::test(start_paused = true)] async fn http_fetch_meters_bytes_without_session_presence() { use moq_net::stats::{Registry, Report, Tier};