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
2 changes: 1 addition & 1 deletion doc/concept/moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -198,7 +198,7 @@ everywhere. On moq-transport an added token is kept even without the extension,
so an announcement can name it: it rides that `PUBLISH_NAMESPACE` as its
authorization token. The token belongs to the session that added it, so after a
reconnect the application adds it again and re-announces. moq-lite has no
per-request token yet, so there an announcement rides the session's scope.
per-request token, so there an announcement rides the session's scope.

## Subscriptions

Expand Down
79 changes: 46 additions & 33 deletions quest/m1/auth/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,9 @@ means "nobody wants it yet" instead of "nobody ever will".

This questline adds an AUTH exchange to both wires: one stream per token, a
grant per token, the union of every accepted token as the session's scope,
and a loud failure when a publish can never be honored. It ends with the
credential able to travel in band, while the URL keeps working for every peer
that predates the stream. Node-bound peer grants for direct sessions belong to
and a loud failure when a publish can never be honored. It ends with extra
credentials able to travel in band, while the first rides SETUP, or the URL
for peers that predate the SETUP token. Node-bound peer grants for direct sessions belong to
[P2P](/quest/m2/p2p/peer-grant.md), their only consumer.

## Plan
Expand All @@ -27,21 +27,32 @@ Decisions settled while planning, recorded so review does not relitigate them:
is presented, verified by the acceptor through `requests()`, and earns a
grant with a lifetime. An AUTH stream's token lives for the session and
its grant joins the session scope. A moq-transport `AUTHORIZATION TOKEN`
on a request is the same kind of auth, named by that request: it admits
only that request, never joins the scope, and ends with it. Renewal on
SUBSCRIBE_UPDATE or REQUEST_UPDATE names a new auth that replaces the old.
on a request is the same kind of auth, scoped to that request: it admits
only that request, never joins the scope, and ends with it. A
SUBSCRIBE_UPDATE or REQUEST_UPDATE carrying a new token replaces it.
Per-request tokens are moq-transport's naive form and are not surfaced as
a separate API.
- ✅ Decided 2026-10-15 (maintainer, #5148): an unnamed request is admitted
by the union of session-lifetime auths only. A named request outside its
auth's grant is refused, and ends when that auth ends.
- ✅ Decided 2026-10-15 (maintainer, #5148): the work lands in steps.
Step 1 (#5148) is incoming only: request tokens arrive on `requests()`,
named requests are held to their issued grant, renewal is renaming, and
no lite wire changes. Step 2 specs `auth=id` in the wip lite version so a
lite request names an AUTH stream instead of carrying a token. Step 3
adds outgoing request tokens through `add()` with automatic naming, sent
as `USE_VALUE` on plain moq-transport.
- ✅ Decided 2026-10-19 (maintainer, closing
[#5927](https://github.com/moq-dev/moq/pull/5927)): **no per-request auth
on moq-lite.** Lite AUTH carries no ID and lite requests no `Auth` field,
so no request spends a byte on auth. moq-transport's per-request token
stays an acceptor-side mapping onto lite's model and never becomes a lite
wire feature.
- ✅ Decided 2026-10-15 (maintainer, #5148), narrowed 2026-10-19 (#5927): a
request without its own token is admitted by the union of session-lifetime
auths only, which on moq-lite is every request. A moq-transport request
carrying a token is held to that token's grant, inside the scope or not,
and ends when the token does.
- ✅ Decided 2026-10-15 (maintainer, #5148), revised 2026-10-19 (#5927): the
work lands in steps. Step 1 (#5148) is incoming only: request tokens
arrive on `requests()`, a moq-transport request is held to its token's
grant, an update's token replaces it, and no lite wire changes. Step 2,
lite requests naming an AUTH stream, is dropped; what it would have closed,
a request racing the token it relies on, is
[A request right behind its token](/quest/m1/auth/request-race.md). Step 3
sends outgoing request tokens on moq-transport through `Route::auth` as
`USE_VALUE` ([Live requests follow their auth](/quest/m1/auth/request-update.md));
lite has nothing to send, since the token already sits in the union.
- ✅ Decided 2026-10-15 (maintainer, #5148): `auth::Handle::authorize`
keeps its name and now means the connection credential's grant; the
session adds every grant it issued to an AUTH token itself.
Expand All @@ -58,8 +69,8 @@ Decisions settled while planning, recorded so review does not relitigate them:
- **One AUTH stream per token, opened by whoever presents it.** Either side of
a session may open one; the acceptor answers with the grant that token
earns. A moq-net session opens one on both sides right after SETUP with an
empty token, meaning the credential the connection already presented (URL
`?jwt=`, mTLS, or nothing), so a publish-only client learns it may subscribe
empty token, meaning the credential the connection already presented (the
SETUP token, URL `?jwt=`, mTLS, or nothing), so a publish-only client learns it may subscribe
to nothing and a relay learns which role its peer will ever play. This is
also the answer to
[moq-wg #1854](https://github.com/moq-wg/moq-transport/issues/1854): the
Expand All @@ -84,21 +95,24 @@ Decisions settled while planning, recorded so review does not relitigate them:
grant type stays pattern-valued.
- **Fail loud by aborting the session.** A publisher whose origin announces a
broadcast outside the union aborts the session with `Unauthorized`, naming
the path. The check runs against the grants in hand once the tokens the
library itself presented at setup are answered; a token the app adds later
is the app's to await before publishing what it unlocks. The origin is
the path. The check runs against the grants in hand once every token the
session presented is answered, setup, replayed, or app-added alike
([request race](/quest/m1/auth/request-race.md)). The origin is
untouched, so a broadcast shared across sessions (P2P hops, a cluster) is
refused only where it is refused. Grant shrinkage cancels previously
authorized work on this session without aborting it or deleting the shared
origin; this is distinct from attempting a new unauthorized publication.
Apps that want to decide themselves read the grant instead.
- **Older peers keep the URL.** WebTransport negotiates the moq version as a
subprotocol of the same CONNECT request that carries the URL, so a client
cannot learn whether the peer speaks AUTH before the token has to be sent.
The client puts the connection credential in the URL as long as any
version it offers has no AUTH stream and omits it once the offered set is
AUTH-capable; extra tokens go in band and are simply absent on an old peer.
Nothing is refused and nothing is silent.
- **The first token rides SETUP.** ✅ Decided 2026-10-19 (maintainer,
#5972): the connection credential goes in the client's SETUP (a
lite-07-wip SETUP parameter, moq-transport's AUTHORIZATION TOKEN option),
which the acceptor already reads before serving the session, so it costs
no round trip and a session's first requests wait on no AUTH. The URL is
fixed before the version is negotiated, so it carries the token as a
fallback while any offered version lacks the SETUP token. Extra tokens go
in band and are simply absent on an old peer. Nothing is refused and
nothing is silent. This replaces the earlier "always in the CONNECT
request" decision and its auth-header plan.
- **Cluster peers keep mTLS.** A relay opens AUTH toward its peer with an empty
token like any client; AUTH reports the grant actually admitted in each
direction. The next mTLS scope quest can restrict or refuse it. A v1 endpoint
Expand Down Expand Up @@ -132,13 +146,12 @@ because `main` assigned 0x3A to NOT_FETCHABLE first.

- [Live requests follow their auth](/quest/m1/auth/request-update.md) - a route swaps its auth and the session sends the update, keeping the request up
- [Auth outlives its session](/quest/m1/auth/issuer.md) - one `auth::Handle` spans a connection's sessions, so a route's auth survives a reconnect
- [Requests name their auth](/quest/m1/auth/request-auth-id.md) - lite-07 AUTH carries an ID and each request names the auth that admits it
- [A request right behind its token](/quest/m1/auth/request-race.md) - a lite request relying on a just-presented token is admitted, with no auth field on any request
- [Bindings](/quest/m1/auth/bindings.md) - grants and tokens reach every
binding through moq-ffi
- [Token in band](/quest/m1/auth/token-in-band.md) - the credential can leave
the URL: a session starts on what the URL carried and its AUTH streams add
the rest, with the URL kept for peers without the AUTH stream
subscription even while its joining FETCH waits for request-ID credit
- [Token in band](/quest/m1/auth/token-in-band.md) - extra credentials ride
AUTH streams: a session starts on the token its SETUP or URL carried and its
AUTH streams add the rest

## Related

Expand Down
61 changes: 0 additions & 61 deletions quest/m1/auth/request-auth-id.md

This file was deleted.

114 changes: 114 additions & 0 deletions quest/m1/auth/request-race.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
# [S] A request right behind its token is admitted

## Goal

On moq-lite, a request that only a just-presented token admits is never
refused because it reached the acceptor before that token's AUTH settled, and
a renewal never drops a live request the new grant still covers. Lite
requests stay judged by the union of session-lifetime auths alone: no Auth ID
on AUTH, no `Auth` field on requests, no extra bytes on any request, and no
timer.

## Plan

- ✅ Decided 2026-10-19 (maintainer, closing
[#5927](https://github.com/moq-dev/moq/pull/5927)): drop the named version.
"I don't want per-request auth and I don't reaaaallly want to waste a byte
on every request." Lite AUTH carries no ID and lite requests no `Auth`
field. `main` never carried either (checked 2026-10-19 in
`drafts/draft-lcurley-moq-lite.md`, `rs/moq-net` and `js/net`), so nothing
needs removing.
- ✅ Decided 2026-10-19 (maintainer, #5972): the first token rides SETUP, a
lite-07-wip SETUP parameter and moq-transport's existing AUTHORIZATION
TOKEN option, with the URL query as the fallback. "We need to block on
SETUP anyway": the acceptor already reads the client's SETUP before serving
the session (`Server::accept_request_lite`), and a lite client sends
requests without waiting on the server's, so it costs no round trip and a
session's first requests wait on no AUTH. Further tokens join the union
through AUTH streams. [Token in band](/quest/m1/auth/token-in-band.md)
carries the parameter. This replaces the earlier "always in the CONNECT
request" decision and drops its auth-header plan.
- ✅ Decided 2026-10-19 (maintainer): moq-transport's per-request
AUTHORIZATION TOKEN stays acceptor-side as
[#5148](https://github.com/moq-dev/moq/pull/5148) modeled it and never
becomes a lite wire feature. `draft-lcurley-moq-auth` gains no request
parameter naming an AUTH, and token aliases stay unsupported (cache size 0).
- Where `main` stands (2026-10-19). A lite acceptor judges SUBSCRIBE and
FETCH against its scope when it decodes them, and a grant joins the scope
only once the acceptor accepts its token. The presenter's own gate refuses
a request its known union does not cover before sending it, and
`auth::Handle::add` (Rust) and `add` (js/net) resolve only after AUTH_OK, so
an app that awaits `add()` never races. Announcements already heal: a
broadcast withheld for falling outside the scope comes back when the scope
widens. What is left:
- the draft does not say any of this;
- nothing pins that an acceptor widens its scope no later than it sends
AUTH_OK, which the presenter relies on;
- tokens the library presents without the app awaiting them race the app's
requests on the same session: moq-tokio's reconnect replay in
`connection::auth` today, and later the extra session-start tokens of
[Auth outlives its session](/quest/m1/auth/issuer.md) and
[Token in band](/quest/m1/auth/token-in-band.md). The SETUP token never
races, so only a client with more than one token can hit it.
- ✅ Decided 2026-10-19 (maintainer, #5972): **the presenter waits**, with a
log line so we see how often it triggers. "I want to make sure we're not
adding dumb RTTs." A request its known union does not cover waits, instead
of failing locally, while any non-empty token this side presented is
unanswered, then goes out or fails against the settled union. An unknown
Comment thread
kixelated marked this conversation as resolved.
Resolved
union covers nothing for this rule, but the empty token never holds a
request, since the acceptor judges the connection credential (SETUP or URL)
before it serves the session. It costs one round trip, only for the first request relying on a new
token, which `add()` already spends; a single-credential session and a
renewal spend nothing. No wire change and no acceptor state. The rule lives
in the shared gate, so the moq-transport AUTH extension gets it too. Abuse:
an acceptor that never answers holds only our own requests, which it could
stall anyway by never answering them. No timer.
- Rejected 2026-10-19 (#5972): the acceptor waiting on that peer's unanswered
AUTHs, because AUTH and the request ride different streams, so a lost AUTH
packet still lets the request arrive first with nothing pending; and an
AUTH_WAIT prefix on the request stream, which is exact but a new message to
save a round trip nobody has measured. Revisit AUTH_WAIT only if the log
below shows the wait firing in practice.
- ✅ Decided 2026-10-19 (maintainer, #5972): observability is the log line
only, not a `stats::Session` counter. Every request that waits on an
unanswered token logs once (path and how long it waited), in Rust and
`js/net`.
- The wait only sees tokens already presented, so a replayed token must be
registered on the new session before the app can use it. Today
`Shared::connected` in moq-tokio publishes the new session before each
per-token replay task reaches `add()`, so a woken app can send a request
while nothing is pending. Present every token the connection holds on the
new session's handle (queued, not awaited) before publishing the session;
[Auth outlives its session](/quest/m1/auth/issuer.md) does this by
construction once the handle spans sessions. js/net mirrors it if its
reconnect replays tokens the same way.
- Spec in lite-07-wip that the acceptor judges a request against the union
when it reads it, that its scope includes a grant no later than it sends
that AUTH_OK, and that a presenter does not send a request only an
unanswered token admits. Hold the publish-outside-the-union check to the
same rule, so it waits on every unanswered token rather than only the setup
ones. Mirror in `js/net`.
Comment thread
kixelated marked this conversation as resolved.
Resolved
- Renewal under the union: present the new token, wait for its AUTH_OK
(`add()` already does), then drop the old one. The union never shrinks
under a live request the new grant also covers, and a narrower renewal ends
only what it no longer covers.
- Not carried from #5927: FIN-linger withdrawal, since nothing names the old
token and dropping it after the new AUTH_OK races nothing; per-token
wakeups and the `named` bench, since no request watches one token. A change
still recomputes the union, as today. Extend `rs/moq-net/benches/auth.rs`
only if the wait adds per-request work on an AUTH_OK.
- Tests that fail without the fix, in Rust and JS: a direct request made
the moment a reconnect publishes its session, relying on a replayed token,
is admitted; an acceptor's AUTH_OK
never precedes its scope; a live subscription survives a renewal.
- Docs: renewal and the wait in `doc/concept/moq-lite.md`'s Authorization
section.

Public API: none. Wire: lite-07-wip draft text only, no new bytes.

## Related

- [#5927](https://github.com/moq-dev/moq/pull/5927) - the closed named-auth
version this replaces
- [Live requests follow their auth](/quest/m1/auth/request-update.md) -
moq-transport request renewal; lite renews through the union
Loading