Repository navigation
quest(auth): restore request-token's scope and split its standalone pieces #5104
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| # [S] A side declares which Setup extensions it offers | ||
|
|
||
| ## Goal | ||
|
|
||
| A moq-net client or server, moq-tokio's dial and listen `Config`, and js/net's | ||
| `connect` and `accept` declare which Setup extensions they offer with one | ||
| positive `#[non_exhaustive] setup::Extensions { auth, solicit }`, all on by | ||
| default, so an application can decline the AUTH or solicit extension. Later | ||
| extensions join the same struct. | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided 2026-10-01 (Q2 on [#4675](https://github.com/moq-dev/moq/pull/4675)), | ||
| which built it; carve it out so it lands before | ||
| [Request tokens](/quest/m1/auth/request-token.md). | ||
|
|
||
| - `setup::Extensions` in `rs/moq-net/src/setup.rs`, set through | ||
| `Client::with_extensions` and `Server::with_extensions`. It folds in the | ||
| private bools `run_setup` takes in `rs/moq-net/src/ietf/session.rs`. | ||
| - moq-tokio: an `extensions` field on `connect::Config` and `listen::Config`, | ||
| serde, omitted when default. | ||
| - js/net: `extensions` on `ConnectProps` and `AcceptProps`. | ||
| - A side serves an inbound AUTH only when it offered AUTH itself. | ||
| - Wire: a draft-17+ server now omits AUTH from its SETUP when the client did | ||
| not offer it, where it always sent it before. List this in the PR. | ||
| - Tests, Rust and JS: declining each extension keeps it out of SETUP, and an | ||
| inbound AUTH on a side that declined it is refused. | ||
|
|
||
| Public API: additive, `setup::Extensions`, `Client::with_extensions`, | ||
| `Server::with_extensions`, the moq-tokio `extensions` fields, and JS | ||
| `Extensions`. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| # [M] moq-relay honors a request token with its own lease | ||
|
|
||
| ## Goal | ||
|
|
||
| moq-relay verifies a moq-transport request token through `moq_auth::Client`, | ||
| each request getting a lease of its own that is never counted as a session | ||
| grant and ends when the request ends. Until this lands the relay has no | ||
| `requests()` consumer, so it refuses every request token `Unsupported`, even | ||
| once [Request tokens](/quest/m1/auth/request-token.md) merges. | ||
|
|
||
| ## Plan | ||
|
|
||
| An application acceptor built on moq-net answers request tokens through | ||
| `requests()` itself and does not need this; it is the relay's half of | ||
| [Request tokens](/quest/m1/auth/request-token.md). | ||
|
|
||
| - A per-request call on `moq_auth::Client`, not the `Client::attach` that | ||
| [Relay tokens](/quest/m1/auth/relay-refresh.md) builds. `attach` connects | ||
| with the connection's id, and the auth server treats that as one more grant | ||
| on the session that never POSTs `end`, so a request token would widen the | ||
| whole connection for its life. The per-request call carries the token in | ||
| `moq_auth::Request.token` with its kind and the request's path, is never | ||
| counted as a session grant, and ends when the request ends. Two requests | ||
| carrying the same bytes get two leases. Name the call while implementing. | ||
| - The request is resolved against the origin with the path checked against | ||
| that lease's grant, not through the session's scoped origin handle. | ||
| - Docs: `doc/bin/relay/auth.md` states the order (session grant, then the | ||
| request's token, then `UNAUTHORIZED`) and that a request token covers only | ||
| its request. | ||
| - Tests: through the relay, the auth server never counts a request token as a | ||
| session grant and sees its lease end with the request. | ||
|
|
||
| Public API: additive on `moq_auth::Client`. Wire: none. | ||
|
|
||
| ## Required | ||
|
|
||
| - [Request tokens](/quest/m1/auth/request-token.md) - the per-request grant | ||
| this lease backs | ||
| - [Relay tokens](/quest/m1/auth/relay-refresh.md) - supplies the lease | ||
| revalidation this reuses |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
| # [S] A token on a request decodes by the draft's rules | ||
|
|
||
| ## Goal | ||
|
|
||
| The `AUTHORIZATION TOKEN` parameter (`0x03`) on a moq-transport request | ||
| (SUBSCRIBE, REQUEST_UPDATE, PUBLISH, FETCH, PUBLISH_NAMESPACE, | ||
| SUBSCRIBE_NAMESPACE, TRACK_STATUS, or any other request that carries | ||
| parameters) decodes with the same structure and rules as the SETUP option. | ||
| A token the draft says must close the session closes it with the draft's | ||
| code; a `USE_VALUE` token is read and, for now, grants nothing, so a request | ||
| outside the session grant is still refused `UNAUTHORIZED`. Today every | ||
| request decodes the key and ignores it. | ||
|
|
||
| ## Plan | ||
|
|
||
| Carve this from [#4675](https://github.com/moq-dev/moq/pull/4675) so it | ||
| lands first; [Request tokens](/quest/m1/auth/request-token.md) then gives a | ||
| `USE_VALUE` token meaning. The decode needs neither [Relay | ||
| tokens](/quest/m1/auth/relay-refresh.md) nor a lease. | ||
|
|
||
| - Decode with the SETUP option's structure and rules | ||
| (`rs/moq-net/src/ietf/token.rs`, `js/net/src/ietf/token.ts`): `USE_VALUE` yields the token. `REGISTER` closes the session with | ||
| `AUTH_TOKEN_CACHE_OVERFLOW` (0x13): we | ||
| advertise no `MAX_AUTH_TOKEN_CACHE_SIZE`, so the limit is 0, and draft-21 | ||
| §8.9 says overflowing it MUST close the session. Only SETUP falls back to | ||
| USE_VALUE (§9.1.4). `DELETE` or `USE_ALIAS` closes with | ||
| `UNKNOWN_AUTH_TOKEN_ALIAS` (0x17): a cache size of 0 "prohibits the use | ||
| of token Aliases" (§9.1.3), so no alias is ever registered. §8.9 says to | ||
| reject the message, but 0x17 exists only as a Session Termination Code | ||
| (§12.2), not a Request Error Code. Record that close as a deviation | ||
| under "moq-transport" in `doc/concept/standard.md`. A token structure that does not | ||
| decode closes with `KEY_VALUE_FORMATTING_ERROR`. Paul Gregoire's | ||
| validator checks the REGISTER and malformed-token codes (decided | ||
| 2026-10-04; aliases decided 2026-10-05). Both decoder families change: the strict | ||
| `decode_params!` path, where each request reads the repeatable key into an | ||
| ignored `Vec<Opaque>`, and draft-14's `Parameters::skip`, which consumes it | ||
| unread. `js/net` keeps every instance in `Parameters` and reads none. | ||
| Every instance decodes by these rules, and a repeat stays accepted, as | ||
| the drafts allow; decoding 0x03 as an `Option` would refuse it. | ||
| - The SETUP option's `DELETE` and `USE_ALIAS` move from `PROTOCOL_VIOLATION` | ||
| to `UNKNOWN_AUTH_TOKEN_ALIAS` too, so both paths close the same way. | ||
| - Build on #5028's per-draft parameter decode (merged), which reworked the | ||
| same per-message decode. | ||
| - 0x13 and 0x17 join the shared session registry: `SessionError` | ||
| (`rs/moq-net/src/error.rs`) and `SessionCode` (`js/net/src/error.ts`). | ||
| That registry is moq-lite's too, and lite codes below 32 carry | ||
| moq-transport's meaning, so add both rows to the Session Error Codes table | ||
| in `drafts/draft-lcurley-moq-lite.md` and to the | ||
| `session_codes_round_trip` test. No per-version mapping. That adds two | ||
| codes to moq-lite's wire registry. | ||
| - `js/net` mirrors the decode. | ||
| - Tests, one legacy and one strict draft, Rust and JS: a `REGISTER` token on | ||
| a request closes with `AUTH_TOKEN_CACHE_OVERFLOW`, a `DELETE` or | ||
| `USE_ALIAS` one with `UNKNOWN_AUTH_TOKEN_ALIAS`, a malformed request token | ||
| with `KEY_VALUE_FORMATTING_ERROR`, and a `USE_VALUE` token on a request | ||
| outside the session grant is still refused `UNAUTHORIZED`. | ||
|
|
||
| Public API: none beyond the two session codes. Wire: session codes 0x13 and | ||
| 0x17 are named; the parameter already exists in every supported draft. | ||
|
|
||
| ## Related | ||
|
|
||
| - [Request tokens](/quest/m1/auth/request-token.md) - gives a decoded request token its grant |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,64 +1,108 @@ | ||
| # [S] A token on a request decodes by the draft's rules | ||
| # [L] A token on a request authorizes that request | ||
|
|
||
| ## Goal | ||
|
|
||
| The `AUTHORIZATION TOKEN` parameter (`0x03`) on a moq-transport request | ||
| (SUBSCRIBE, REQUEST_UPDATE, PUBLISH, FETCH, PUBLISH_NAMESPACE, | ||
| SUBSCRIBE_NAMESPACE, TRACK_STATUS, or any other request that carries | ||
| parameters) decodes with the same structure and rules as the SETUP option. | ||
| A token the draft says must close the session closes it with the draft's | ||
| code; a `USE_VALUE` token is read and, for now, grants nothing, so a request | ||
| outside the session grant is still refused `UNAUTHORIZED`. Today every | ||
| request decodes the key and ignores it. | ||
| A moq-transport peer authorizes a SUBSCRIBE or PUBLISH_NAMESPACE with the | ||
| `AUTHORIZATION TOKEN` parameter (`0x03`) on that request, and refreshes it in | ||
| band with an update (SUBSCRIBE_UPDATE on drafts 14 and 15, REQUEST_UPDATE | ||
| from 16), on every supported draft. A request is authorized | ||
| by the session's grant first; when that does not cover it, by the token on the | ||
| request; with neither it is refused `UNAUTHORIZED`. The token's grant covers | ||
| only the request it rode on, never joins the session union, and ends with that | ||
| request. On any other request the token is ignored. | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided 2026-10-08: this quest is the decode-and-close change only. A | ||
| request token authorizing its own request (the fallback after the session | ||
| grant, refresh by REQUEST_UPDATE, and a per-request relay lease on | ||
| `moq_auth::Client`) is deferred until a moq-transport peer needs it; re-plan | ||
| it then from [#4675](https://github.com/moq-dev/moq/pull/4675), which built | ||
| it. #4675 was too large to review as one change and closed unmerged; its | ||
| branch is gone, so the grant and lease work survives only at its head commit | ||
| `29ed74e78`. The decode-and-close part lands as this quest. The decode needs neither [Relay tokens](/quest/m1/auth/relay-refresh.md) | ||
| nor a lease. | ||
| [#4675](https://github.com/moq-dev/moq/pull/4675) builds this and is in manual | ||
| maintainer review. Decided 2026-10-09: an external moq-transport deployment | ||
| needs per-request tokens with in-band renewal, so this quest keeps its full | ||
| scope, reversing the 2026-10-08 shrink. The pieces that stand alone land first | ||
| as the quests under Required; #4675 then rebases onto them and onto the line, | ||
| which already routes draft-14/15/16 updates to their target (#4961), and drops | ||
| its own copies. | ||
|
|
||
| - Decode with the SETUP option's structure and rules | ||
| (`rs/moq-net/src/ietf/token.rs`, `js/net/src/ietf/token.ts`): `USE_VALUE` yields the token. `REGISTER` closes the session with | ||
| `AUTH_TOKEN_CACHE_OVERFLOW` (0x13): we | ||
| advertise no `MAX_AUTH_TOKEN_CACHE_SIZE`, so the limit is 0, and draft-21 | ||
| §8.9 says overflowing it MUST close the session. Only SETUP falls back to | ||
| USE_VALUE (§9.1.4). `DELETE` or `USE_ALIAS` closes with | ||
| `UNKNOWN_AUTH_TOKEN_ALIAS` (0x17): a cache size of 0 "prohibits the use | ||
| of token Aliases" (§9.1.3), so no alias is ever registered. §8.9 says to | ||
| reject the message, but 0x17 exists only as a Session Termination Code | ||
| (§12.2), not a Request Error Code. Record that close as a deviation | ||
| under "moq-transport" in `doc/concept/standard.md`. A token structure that does not | ||
| decode closes with `KEY_VALUE_FORMATTING_ERROR`. Paul Gregoire's | ||
| validator checks the REGISTER and malformed-token codes (decided | ||
| 2026-10-04; aliases decided 2026-10-05). Both decoder families change: the strict | ||
| `decode_params!` path, where each request reads the repeatable key into an | ||
| ignored `Vec<Opaque>`, and draft-14's `Parameters::skip`, which consumes it | ||
| unread. `js/net` keeps every instance in `Parameters` and reads none. | ||
| - Build on #5028's per-draft parameter decode (merged), which reworked the | ||
| same per-message decode. | ||
| - 0x13 and 0x17 join the shared session registry: `SessionError` | ||
| (`rs/moq-net/src/error.rs`) and `SessionCode` (`js/net/src/error.ts`). | ||
| That registry is moq-lite's too, and lite codes below 32 carry | ||
| moq-transport's meaning, so add both rows to the Session Error Codes table | ||
| in `drafts/draft-lcurley-moq-lite.md` and to the | ||
| `session_codes_round_trip` test. No per-version mapping. That adds two | ||
| codes to moq-lite's wire registry. | ||
| - `js/net` mirrors the decode. | ||
| - Tests, one legacy and one strict draft, Rust and JS: a `REGISTER` token on | ||
| a request closes with `AUTH_TOKEN_CACHE_OVERFLOW`, a `DELETE` or | ||
| `USE_ALIAS` one with `UNKNOWN_AUTH_TOKEN_ALIAS`, a malformed request token | ||
| with `KEY_VALUE_FORMATTING_ERROR`, and a `USE_VALUE` token on a request | ||
| outside the session grant is still refused `UNAUTHORIZED`. | ||
| Decided, so review does not relitigate them: | ||
|
|
||
| Public API: none beyond the two session codes. Wire: session codes 0x13 and | ||
| 0x17 are named; the parameter already exists in every supported draft. | ||
| - **Admission.** A request the session grant covers is served without | ||
| verifying its token. Otherwise the token becomes an `auth::Request` on the | ||
| session's `auth::Handle`, marked with the request's path and kind, and the | ||
| acceptor's `Grant` is checked against that request alone. With no | ||
| `requests()` consumer a non-empty token is refused `Unsupported`. | ||
| - **Scope.** Honored on SUBSCRIBE, PUBLISH_NAMESPACE, and an update renewing | ||
| one, SUBSCRIBE_UPDATE included; ignored on every other request (2026-10-05). | ||
| - **Refused renewal** follows drafts 16 section 9.11.1 and 18 section 10.9.1: | ||
| REQUEST_ERROR ends only that request, with PUBLISH_DONE `UPDATE_FAILED` for | ||
| a subscription or a closed stream for a namespace. The session stays up and | ||
| the old grant does not survive. A lapse or acceptor revoke also ends only | ||
| that request (2026-10-05). | ||
| - **Client credential.** `auth::Handle::set_request_token`, beside session | ||
| tokens, with no `Client` methods. moq-tokio's `Connection` owns the token | ||
| across reconnects: `Connection::auth()` renews it on a live connection and | ||
| `connect::Config::with_request_token` seeds it. Setting a new token | ||
| re-presents it on live requests. This owns the request-token slice of | ||
| `Connection::auth()`, so it does not wait on | ||
| [Relay tokens](/quest/m1/auth/relay-refresh.md): whichever lands first adds | ||
| the handle (2026-10-01 Q1 and Q3, 2026-10-05). | ||
| - **Update credit.** Draft-19+ advertises and enforces MAX_REQUEST_UPDATES, | ||
| closing with TOO_MANY_REQUEST_UPDATES (0x1B); earlier drafts keep a local | ||
| guard that ends only the request. 0x1B joins the shared session registry as | ||
| [Request-token decode](/quest/m1/auth/request-token-decode.md) does for 0x13 | ||
| and 0x17: `SessionCode` in `js/net`, moq-lite's Session Error Codes table, | ||
| and `session_codes_round_trip`. The sender keeps one renewal in flight per | ||
| subscription on drafts that answer an update. Draft-14 never answers an | ||
| accepted SUBSCRIBE_UPDATE, so its sender does not wait for one; test two | ||
| successive replacements with no answers. | ||
| - **Drafts.** Renewal works on every supported draft, 14 through 16 included | ||
| (2026-10-09), tested with SUBSCRIBE_UPDATE on 14 and 15. | ||
| - `EXPIRED_AUTH_TOKEN` and `MALFORMED_AUTH_TOKEN` are not this quest's; they | ||
| land with [Expired token error](/quest/m1/auth/expired-error.md), which | ||
| does not block it (2026-10-01 Q4). | ||
|
|
||
| Fix in #4675 before it merges, each with a regression test. Found by a | ||
| 2026-10-09 read of head `29ed74e78`, not yet reproduced: | ||
|
|
||
| - The publisher answers a token-less REQUEST_UPDATE while a renewal's verdict | ||
| is still pending (`handle_renewal_update`), so on draft-17+, where answers | ||
| are unkeyed, they go out of order. | ||
| - The new 0x03 fields decode as `Option`, refusing a repeat the drafts allow; | ||
| [Request-token decode](/quest/m1/auth/request-token-decode.md) settles the | ||
| rule. | ||
| - The admission sequence appears four times and the receiver renewal state | ||
| machine twice (publisher and subscriber); each becomes one helper. | ||
| - `set_request_token` takes `setup::Token`, not encoded bytes, so a caller | ||
| cannot send an alias form. `auth::Request`'s `path`, `kind`, and | ||
| `token_kind` become one `Option`. | ||
| - Setting a request token on a moq-lite session fails loud instead of doing | ||
| nothing. | ||
| - Drop the outbound update sniffer in `ietf/adapter.rs`, which re-parses an ID | ||
| the sender already holds, and the unread `Peer::max_request_updates` and | ||
| `token::decode_value`. | ||
|
|
||
| Open for review: one `requests()` consumer receives both session and request | ||
| tokens, so an acceptor written for session tokens also answers request tokens. | ||
|
|
||
| Public API: additive. moq-net gains `auth::RequestKind`, the request a | ||
| `auth::Request` belongs to, `auth::Handle::set_request_token`, and | ||
| `SessionError::TooManyRequestUpdates`, mirrored as a `js/net` `SessionCode`. | ||
| moq-tokio gains `Auth`, | ||
| `Connection::auth`, `connect::Config::with_request_token`, and | ||
| `server::Request::auth`. Wire: MAX_REQUEST_UPDATES (0x08) on draft-19+ and | ||
| TOO_MANY_REQUEST_UPDATES (0x1B), which also joins moq-lite's registry; the | ||
| parameter already exists in every | ||
| supported draft. | ||
|
|
||
| Follow-ups, planned when a consumer needs them: a JS request-token setter and | ||
| accept-side `requests()`, a moq-cli `--request-token`, and the setter through | ||
| moq-ffi in [Bindings](/quest/m1/auth/bindings.md). | ||
|
|
||
| ## Required | ||
|
|
||
| - [Request-token decode](/quest/m1/auth/request-token-decode.md) - a request | ||
| token decodes by the draft's rules and its forbidden forms close the session | ||
| - [Setup extensions](/quest/m1/auth/extensions.md) - a side declares which | ||
| Setup extensions it offers with one `Extensions` struct | ||
|
Comment on lines
+98
to
+103
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
This quest says every standalone piece under Useful? React with 👍 / 👎.
Collaborator
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Disagree that either blocks this quest; clarified the wording in f42bdaa instead.
(Written by Claude Opus 5.5) |
||
|
|
||
| ## Related | ||
|
|
||
| - [Relay tokens](/quest/m1/auth/relay-refresh.md) - the lease a deferred per-request grant would reuse | ||
| - [Request leases](/quest/m1/auth/request-lease.md) - moq-relay honors a | ||
| request token with a lease of its own | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The quest adds Rust's
SessionError::TooManyRequestUpdatesand wire code 0x1B but omits the correspondingjs/netSessionCode, moq-lite Session Error Codes row, andsession_codes_round_tripcoverage. Since this repository deliberately shares sub-32 moq-transport codes with moq-lite, implementing the plan as written would make JS treat this close as unspecified and leave lite using an undocumented code. Include the cross-language registry and draft work, as the new decode quest already does for 0x13 and 0x17.AGENTS.md reference: AGENTS.md:L99-L102
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agreed. Fixed in f42bdaa: the Update credit decision now has 0x1B join the shared registry the way the decode quest does for 0x13 and 0x17 (
js/netSessionCode, moq-lite's Session Error Codes table,session_codes_round_trip), and the Public API/Wire line names both.(Written by Claude Opus 5.5)