Repository navigation
docs(quest): plan issues #3588, #3603, #3605, and #3608 #3619
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
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Some comments aren't visible on the classic Files Changed page.
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| # [M] moq-net: an anonymous publisher is parked behind its own minted id | ||
|
|
||
| ## Goal | ||
|
|
||
| On main, when an anonymous publisher's session ends without a graceful | ||
| unannounce and another anonymous session announces the same path while the | ||
| front lingers, the newcomer takes the path over and a subscriber on any other | ||
| session gets its media. Today the newcomer is parked until the linger expires | ||
| and every subscriber gets 404 `dropped` meanwhile, which costs eight cells of | ||
| the nightly interop matrix and every reconnect on a released relay. Boundary: | ||
| a newcomer arriving while the old session is still open keeps waiting for it | ||
| to end, because a relay cannot tell an anonymous handoff from an anonymous | ||
| reflection, and evicting a live incumbent on a reflected announce is a loop. | ||
| Established ids keep taking over immediately, as today. Fix on main; dev | ||
| deleted the gate. | ||
|
|
||
| ## Plan | ||
|
|
||
| #3042 mints `Origin::random()` for every accepted session that declares no | ||
| identity, so routes learned on it are not advertised back to it. That is all | ||
| `drafts/draft-lcurley-moq-cluster.md` asks of an assigned id, and the | ||
| reflection gate must keep counting it: a peer we advertised a live path to, | ||
| which then announces that path under the id we minted for it, is reflecting | ||
| our content. The defect is one step earlier. A new session is advertised the | ||
| lingering front before it announces anything, `AnnounceConsumerNotify::announce` | ||
| registers an `ExclusionGuard` for the freshly minted id in | ||
| `FrontState::excluded`, the peer's own announce is stamped `hops = [id]`, and | ||
| `attach_source` in `rs/moq-net/src/model/origin.rs` parks it as a reflection. | ||
| A front with no live route has nothing to reflect. | ||
|
|
||
| - A lingering front, one whose `routes` are empty and whose linger is what | ||
| keeps it open, is not advertised to announce consumers that attach after | ||
| its last route left, and registers no exclusion for them. It is advertised | ||
| again the moment a route joins. Consumers that were advertised it while it | ||
| was live keep their guards, so a reflection from any of them stays parked | ||
| and the linger closes the front as today. The resolve path keeps | ||
| registering guards: a subscriber is a real reader. | ||
| - With no guard for the newcomer, its announce is untainted and the existing | ||
| takeover branch closes the lingering incumbent and announces the new front, | ||
| which is the "newest publisher wins" rule main already applies to | ||
| established ids. | ||
| - Regression tests: two anonymous sessions on one relay where the publisher | ||
| session dies without unannouncing and a new one announces the same path | ||
| during the linger; a third anonymous session subscribes and gets media with | ||
| zero parking events. A reflection test in the same shape: the peer that was | ||
| advertised the path while it was live announces it back after the | ||
| publisher dies, stays parked, and the front closes when the linger expires. | ||
| `test_reflection_through_an_exposed_peer_cannot_take_over` and its rival | ||
| test in `origin.rs` keep passing unchanged. Run `just test smoke-full`; its | ||
| draft-18 clients hit this. | ||
| - dev is unaffected: #2704 removed the linger and #3225 deleted | ||
| `FrontState::excluded`, `taints_a_reader`, and parking, so a front closes | ||
| with its last source and reflection is the chain test against the relay's | ||
| own hop. Nothing to port at [merge dev](/quest/m1/merge-dev.md). | ||
|
|
||
| ## Closes | ||
|
|
||
| - [#3588](https://github.com/moq-dev/moq/issues/3588) - close this issue when the quest finishes |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
59 changes: 0 additions & 59 deletions
59
quest/m2/3087-relay-mtls-peers-bypass-auth-api-mode-so-proxy-grants.md
This file was deleted.
Oops, something went wrong.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,52 @@ | ||
| # Auth API | ||
|
|
||
| ## Goal | ||
|
|
||
| `--auth-api` decides every connection the relay admits, with one request and | ||
| reply contract for every credential kind, and the relay asks the endpoint as | ||
| rarely as it can. Today an mTLS peer is admitted to whatever it dials with | ||
| publish and subscribe unscoped, the endpoint is told only that some | ||
| certificate was verified, a revalidation reply cannot move a session's tier, | ||
| and an endpoint that names no `max-age` turns revalidation off without a | ||
| trace. This line closes those gaps on the HTTP contract; the wire side is | ||
| [In-band auth](/quest/m2/auth/README.md). | ||
|
|
||
| ## Plan | ||
|
|
||
| The caching model every quest here keeps: | ||
|
|
||
| - Token mode: the request depends on (root, `kid`, transport), so an audience | ||
| sharing a signing key is one cached request per relay, however many viewers | ||
| arrive at once. | ||
| - Proxy mode: the credential is part of the request and the reply is cached | ||
| per credential, so auth cost tracks distinct credentials, not viewers. | ||
| - mTLS: the request carries the peer's identity and the reply is cached per | ||
| (root, identity, transport). Not unrestricted by default once the endpoint | ||
| speaks v1; never revalidated, so an endpoint outage cannot partition the | ||
| mesh. | ||
| - Revalidation rides the admission cache, so a re-check can be answered from | ||
| an entry up to one `max-age` old and the revocation window is up to twice | ||
| `max-age`, floored at one second. That belongs in operator documentation, | ||
| not a doc comment. | ||
|
|
||
| `--auth-api-mode proxy` landed on dev in #3044, and the quest that planned it | ||
| is deleted. Everything here branches from dev unless a quest says main. | ||
|
|
||
| ## Quests | ||
|
|
||
| - [mTLS identity](/quest/m2/auth-api/mtls-identity.md) - an mTLS peer is | ||
| authorized through the auth API like any other connection, named by its | ||
| certificate, and a proxy grant can scope or refuse it | ||
| - [mTLS explicit scope](/quest/m2/auth-api/mtls-scope.md) - a v1 reply must | ||
| grant an mTLS peer its scope; unrestricted survives only for unversioned | ||
| endpoints | ||
| - [Revalidation updates](/quest/m2/auth-api/revalidation-updates.md) - a | ||
| re-check moves the tier in place, names an alias change, and a reply that | ||
| disables revalidation says so once | ||
|
|
||
| ## Related | ||
|
|
||
| - [Relay auth](/quest/m2/path-patterns/relay-auth.md) - versions the grant | ||
| shape and resizes a live session; mTLS explicit scope rides its v1 | ||
| - [In-band auth](/quest/m2/auth/README.md) - the AUTH stream, where a | ||
| credential can arrive after the connection |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| # [M] An mTLS peer is authorized through the auth API | ||
|
|
||
| ## Goal | ||
|
|
||
| A peer that presented a client certificate is authorized through the same | ||
| auth API request as every other connection, and the endpoint learns which | ||
| certificate: `mtls=<identity>` replaces `mtls=true`. In proxy mode the | ||
| endpoint's grant, or its absence, decides what the peer may publish and | ||
| subscribe; in token mode a certificate-authenticated peer with no grant stays | ||
| unrestricted until [mTLS explicit scope](/quest/m2/auth-api/mtls-scope.md), | ||
| so an endpoint answering `{alias, tier}` today keeps that reply shape. The | ||
| request side is a breaking change to the endpoint contract: an endpoint that | ||
| compares `mtls` to the literal `true` must accept any non-empty value before | ||
| its relays upgrade. Replies cache per identity. On dev, where the mode lives | ||
| and where breaking changes go. | ||
|
|
||
| ## Plan | ||
|
|
||
| `Auth::verify_mtls` in `rs/moq-relay/src/auth.rs` calls `resolve_mtls`, which | ||
| builds its own `AuthApiRequest` carrying `mtls: true` and nothing else about | ||
| the peer, reads only `alias` and `tier` off the reply, discards the cache | ||
| hints, and mints `AuthToken::unrestricted`. The party being scoped picks the | ||
| scope, because the root is the path the client dialed. | ||
|
|
||
| - Delete `resolve_mtls`. Build the request through `api_request` and resolve | ||
| through `authorize`, so a grant is read one way for every credential, with | ||
| `host` in proxy mode as the mode already sends it. | ||
| - `mtls=<identity>` names the peer: the leaf certificate's first SAN DNS | ||
| name, the CN when it has none, and the leaf's SHA-256 fingerprint when it | ||
| has neither, so the value is never empty. `moq_tokio::tls::PeerIdentity` | ||
|
coderabbitai[bot] marked this conversation as resolved.
Resolved
|
||
| grows `name()` beside `expiry()` and `fingerprint()`, parsed with the | ||
| `x509-parser` it already uses. The docs say the identity is a value the | ||
| endpoint matches, never proof by itself; the CA that signed the chain is. | ||
| This replaces the documented `mtls=true`, and an endpoint that compares | ||
| the literal breaks for every mTLS peer, cluster peers included, until it | ||
| accepts any non-empty value. The auth API section of `doc/bin/relay/auth.md` | ||
| states the new value, the migration (accept non-empty first, then upgrade | ||
| relays), and the release note carries it as breaking. | ||
| - The identity has to reach `verify_mtls` on every transport: QUIC keeps a | ||
| `PeerIdentity` on the request, but the HTTPS and WebSocket path reduces the | ||
| verified chain to the unit `MtlsPeer` marker in `rs/moq-relay/src/web.rs`, | ||
| so that marker carries the identity too. | ||
| - Caching: the identity is in the query, so the shared HTTP cache and the | ||
| in-flight coalescing already key on it: one request per (root, identity, | ||
| transport), however many sessions that peer opens. `revalidate` stays | ||
| `None` for mTLS peers, which the "mTLS peers must never revalidate" test | ||
| pins: a deployed endpoint sending a blanket `Cache-Control: max-age` would | ||
| otherwise arm revalidation across a relay mesh the moment this ships. Mesh | ||
| revalidation is its own change, an explicit opt-in per identity plus a | ||
| relay-side floor on the staleness window; `stale-if-error` alone is not | ||
| enough, since an endpoint that answers "no" still partitions the mesh. | ||
| - Token mode: `mtls` satisfies "has a credential" without a JWT or a `key`; | ||
| no grant means unrestricted, as today. Proxy mode: the endpoint returns a | ||
| grant like anyone else, and no grant is a refusal. | ||
| - Tests: a proxy-mode mTLS peer refused by an empty reply, scoped by a narrow | ||
| grant, and admitted unrestricted in token mode; `host` present on the proxy | ||
| request; the SAN name, the CN for a certificate with no DNS SAN, and the | ||
| fingerprint for a nameless one, over both QUIC and WebSocket; two sessions | ||
| from one identity produce one endpoint request. Update the mTLS and auth | ||
| API sections of `doc/bin/relay/auth.md`. | ||
|
|
||
| ## Closes | ||
|
|
||
| - [#3087](https://github.com/moq-dev/moq/issues/3087) - close this issue when the quest finishes | ||
|
|
||
| ## Related | ||
|
|
||
| - [mTLS explicit scope](/quest/m2/auth-api/mtls-scope.md) - removes the | ||
| unrestricted default once the endpoint speaks v1 | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.