Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions doc/bin/relay/auth.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
11 changes: 7 additions & 4 deletions doc/concept/stats.md
Original file line number Diff line number Diff line change
Expand Up @@ -282,10 +282,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
Expand Down
1 change: 1 addition & 0 deletions doc/lib/rs/moq-auth.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
15 changes: 14 additions & 1 deletion js/auth/src/contract.test.ts
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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);
});
16 changes: 14 additions & 2 deletions js/auth/src/contract.ts
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -187,3 +187,15 @@ export const GrantSchema = z
}),
);
export type Grant = z.infer<typeof GrantSchema>;

/** 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<typeof RefusalSchema>;
1 change: 0 additions & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,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
- [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
- [A/V clock](/quest/m1/av-clock.md) - the audio playhead drives Sync.reference while audio plays, through per-track sync handles
Expand Down
56 changes: 0 additions & 56 deletions quest/m1/refusal-reason.md

This file was deleted.

6 changes: 6 additions & 0 deletions rs/moq-auth/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first.

## Unreleased

### Typed admission refusals (#5996)

`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.
Expand Down
Loading
Loading