From e04790e17d30c9635df4bf829457a2fbd5c85817 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 11 Sep 2026 13:36:46 -0700 Subject: [PATCH 1/5] docs(quest): rank anonymous routes last and abandon the hop-0 ban A route through an anonymous hop never outranks an identified route at any cost, at any depth. Hop 0 stays in the chain as the mark and travels on the wire; the relay's minted id is local selection state for the split-horizon filter. That reverses #3060, whose quest is deleted: forwarding an assigned id published a name for a peer that declined to give one, and a chain that cannot carry 0 cannot say a route is anonymous. Co-Authored-By: Claude Fable 5.1 --- ...60-moq-net-ban-hop-id-0-from-hop-chains.md | 61 ------------------- quest/m1/README.md | 2 +- quest/m1/anonymous-route-rank.md | 61 +++++++++++++++++++ 3 files changed, 62 insertions(+), 62 deletions(-) delete mode 100644 quest/m1/3060-moq-net-ban-hop-id-0-from-hop-chains.md create mode 100644 quest/m1/anonymous-route-rank.md diff --git a/quest/m1/3060-moq-net-ban-hop-id-0-from-hop-chains.md b/quest/m1/3060-moq-net-ban-hop-id-0-from-hop-chains.md deleted file mode 100644 index 4f9a950be3c..00000000000 --- a/quest/m1/3060-moq-net-ban-hop-id-0-from-hop-chains.md +++ /dev/null @@ -1,61 +0,0 @@ -# [L] moq-net: ban Hop ID 0 from hop chains - -## Goal - -Implement and verify the behavior tracked in [#3060](https://github.com/moq-dev/moq/issues/3060) -within the issue's stated scope and boundaries. - -## Plan - -Use the public issue's scope, implementation notes, and acceptance criteria -below as the starting plan. Reconcile paths and assumptions with the current -tree before implementation. - -### Issue context - -`Origin::UNKNOWN` (Hop ID 0) is documented as "no identity", but it is currently legal *inside a hop chain*, and that is where every problem with it comes from. A chain entry that names nobody cannot be filtered on, cannot be loop-detected, and cannot be told apart from another entry that also names nobody. Ban it from chains and those problems stop being cases to handle. - -0 stays reserved and keeps its job as the absence marker in the fields that need one (`AnnounceInterest.exclude_hop`, `AnnounceOk.origin`, `RELAY_HOPS`). That reading is unambiguous precisely because no endpoint may adopt 0 as its identity, which `Origin::new` already enforces. What changes is that a chain names real hops only. - -#### What this closes - -moq-dev/moq#3053: a peer that declares 0 and sends its own HOP\_PATH cannot be filtered on the identity we assigned it. Substituting the assigned id into the chain was implemented during moq-dev/moq#3042 and reverted after producing four defects in four review rounds. With 0 illegal in a chain, a peer with no identity has nothing legal to write as its terminal entry, so that advertisement is a decode-time PROTOCOL\_VIOLATION rather than something to substitute into. The four defects were: - -1. Only the terminal entry may be substituted; earlier zeros belong to upstreams the receiver never spoke to. -2. Substituting can construct an invalid chain: `[X, 0]` from a peer assigned `X` becomes `[X, X]`, a PROTOCOL\_VIOLATION for whoever we forward it to. -3. The assigned identity must not be tested against a peer that declared one, or its ordinary traffic is discarded as a loop. -4. The check and the substitution must be gated together, or a peer assigned `Y` that sent `[Y, 0]` bypasses the check and gets rewritten anyway. - -Each was a new conditional on the same decision. None of them exist if the chain cannot carry 0. - -It also removes the privacy question substitution raised: an assigned identity is indistinguishable on the wire from a declared one, so writing it into a forwarded chain publishes our private name for a peer that asked not to be named. - -#### Scope - -**Both wire dialects.** A non-zero Hop ID appearing twice is already a PROTOCOL\_VIOLATION in `draft-lcurley-moq-cluster`; moq-dev/moq#3049 mirrors that into `draft-lcurley-moq-lite` and moves it into `OriginList` so it holds at construction rather than only at decode. This issue is the next step on the same rule: `HopPath::validate` drops the duplicate-zeros exemption, and a zero entry becomes invalid on its own. - -**moq-lite-01/02/03.** These carry no real Hop IDs. Lite-03 sends a bare hop count that `announce.rs` expands into that many `UNKNOWN` placeholders, which is the only remaining source of zeros in a chain, and lite-01/02 send nothing at all. They stay supported: the count is read as the **route cost** instead, which is what it was for before it was also made to carry loop prevention, and which the lite draft already equates to it (`An absent parameter means the default cost of 1, under which the accumulated Route Cost equals the hop count`). - -That means the loop bound has to come from the cost, since the count no longer tracks chain length: - -- charge the configured link cost, with a **mandatory floor of 1** on lite-01/02/03 links. A link priced 0 is a supported config (two relays in one datacenter) and would otherwise stop the value growing, leaving the loop unbounded. -- reject a received value above `MAX_HOPS`, reproducing today's 32-hop ceiling. -- emit the accumulated cost where `encode_hops` currently emits `hops.len()`. - -Behavior change worth calling out: a lite-03 route's stored chain drops from N entries to one (`[assigned_upstream_id]`), so cost carries the distance and hop length stops standing in for it. That shifts how lite-03 routes rank against others, and the tie-break key in `model/origin.rs` is computed over the chain. - -**Drafts.** `draft-lcurley-moq-cluster` section "The Reserved Hop ID 0" is deleted rather than amended. The rules it anchors change with it: HOP\_PATH validity becomes "no Hop ID appears twice" with no exemption, "an advertisement whose first entry is 0 has an unknown origin" goes away because every first entry now names a real publisher, and "Assigned Identities" shifts from MAY to mandatory, since a receiver has no way to spell an unnamed upstream in a chain. `RELAY_HOPS` keeps meaning "no identity" when it carries 0; what a peer may no longer do is put 0 in a HOP\_PATH. `draft-lcurley-moq-lite` gets the matching chain rule alongside the Hop Count rule. - -The section's honest summary today, `Declaring 0 therefore trades loop detection and failover for anonymity`, becomes false rather than merely narrower: a peer that declares 0 is assigned an identity and filtered on it, and gets no anonymity from the chain because it can no longer write into one. - -#### Done when - -Every `== Origin::UNKNOWN` / `!= Origin::UNKNOWN` test that exists to ask "does this chain entry name anybody" is gone, across `lite/subscriber.rs`, `ietf/{subscriber,publisher,cluster}.rs`, and `model/{origin,broadcast}.rs`. The marker survives only where it means "this field is absent". Any survivor in the first category means 0 is still special somewhere and the change is incomplete. - -Targets `dev`: it changes published `moq-net` API. The outbound validation it -builds on landed in #3066, where `Hops::push` enforces the duplicate rule -wherever a chain is built. - -## Closes - -- [#3060](https://github.com/moq-dev/moq/issues/3060) - close this issue when the quest finishes diff --git a/quest/m1/README.md b/quest/m1/README.md index 39a2a15f9d7..10ab062911e 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -70,6 +70,6 @@ with the current dev tree before starting. - [#3208](/quest/m1/3208-make-2-5-ms-opus-frame-durations-work-across-bindings.md) - Make 2.5 ms Opus frame durations work across bindings - [#2152](/quest/m1/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - libmoq: C ABI catch-up with the moq-ffi surface - [Route cold cost](/quest/m1/route-cold-cost.md) - MoqRoute carries warm and cold, so an observed route re-announces intact -- [#3060](/quest/m1/3060-moq-net-ban-hop-id-0-from-hop-chains.md) - moq-net: ban Hop ID 0 from hop chains +- [Anonymous rank](/quest/m1/anonymous-route-rank.md) - moq-net: a route through an anonymous hop ranks below every identified route at any cost, and hop 0 travels the chain to say so - [#2248](/quest/m1/2248-moq-mux-rebase-fmp4-export-timestamps-for-late-subscribers.md) - moq-mux: rebase fMP4 export timestamps for late subscribers - [Merge dev](/quest/m1/merge-dev.md) - dev lands on main with a closing keyword for every issue it fixed diff --git a/quest/m1/anonymous-route-rank.md b/quest/m1/anonymous-route-rank.md new file mode 100644 index 00000000000..3262f5f8880 --- /dev/null +++ b/quest/m1/anonymous-route-rank.md @@ -0,0 +1,61 @@ +# [M] moq-net: an anonymous route never outranks an identified one + +## Goal + +A route that passes through an anonymous hop, at any depth, ranks below every +route whose hops are all identified, whatever the costs say. If Cloudflare's +relay announces broadcast A without an identity at cost 1 and a cost-5 route +through identified relays reaches the real publisher, the cost-5 route wins, +on this relay and on every relay downstream of it. Among anonymous routes, +cost keeps ordering as it does today. On dev, where the route model lives. + +## Plan + +Today `route_order` in `rs/moq-net/src/model/origin.rs` ranks on +`(Cost, len, hash, id)` and nothing about identity enters it. An anonymous +peer's announce is stamped as a one-hop route charged the link cost +(`session_route` in `rs/moq-net/src/ietf/subscriber.rs`, default 1), so it +beats any identified route costing more, and the `cold` half of +`Cost::UNKNOWN` never fires because cold only breaks a warm tie. The doc +comment on `session_route` already names the hazard and points at +`Client::with_cost` as the workaround. + +Hop 0 in a chain is the mark, and it travels: + +- A relay bridging an anonymous upstream writes 0 for that hop on the wire, + in lite-06 HOP_PATH and the cluster extension alike, and forwards a + received 0 unchanged. Its minted per-session id stays local: `RouteEntry` + gains `via: Hop`, the announcing session's declared or assigned id, and the + split-horizon filter in `best_route` and the advertise path matches `via` + as well as the chain, so #3042's echo fix (a route is never advertised back + to the session it came from) holds without the id ever leaving the relay. + This reverses the direction of #3060, whose quest is deleted with this one: + an assigned identity is private selection state and forwarding it published + a name for a peer that declined to give one. +- `route_order` becomes `(anonymous, Cost, len, hash, id)`, where `anonymous` + is whether the chain holds a 0 anywhere. Lite-03 hop-count placeholders are + 0 entries and count as anonymous, which is what they are. `Route` exposes + `is_anonymous()` for the bindings and the announcement stream. +- Loop detection is unchanged: a 0 entry matches nothing, and a relay's own + id still appears in the chain wherever it forwarded the route. +- Drafts: `drafts/draft-lcurley-moq-cluster.md` "Assigned Identities" says + the assigned id is local selection state that MUST NOT be forwarded, and + "Bridging" writes 0 for an upstream that sent no HOP_PATH; the selection + rule prefers a HOP_PATH with no 0 entry before comparing ROUTE_COST. + `drafts/draft-lcurley-moq-lite.md` mirrors both for lite-06. Validate with + `just drafts check`. +- Tests: an anonymous cost-1 route loses to an identified cost-5 route; two + anonymous routes order by cost; a chain `[0, R1]` received from identified + peer R1 loses to `[P, R2]` at a higher cost; a relay forwards `[0, R1]` with + the 0 intact and never advertises the route back to the session it came + from; `anonymous_routes_never_resume` and the #3042 filter tests keep + passing. Run `just test smoke-full`, since the interop relays are anonymous. + +## Related + +- [Rank](/quest/m2/pop-skipping/rank.md) - warm-copy adoption, which also + refuses to treat two anonymous relays as one +- [Route cold cost](/quest/m1/route-cold-cost.md) - the cost pair the bindings + carry, which `is_anonymous()` joins +- [#3060](https://github.com/moq-dev/moq/issues/3060) - the ban on hop 0 in + chains this quest decides against From a2a61f69eb5ea8314f7e75076dca78337cd92c32 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 11 Sep 2026 13:39:11 -0700 Subject: [PATCH 2/5] docs(quest): fold the second review round on #3619 into the plans - encoder feedback diffs cumulative counters per viewer and resets on a restarted viewer - the no-revalidation warning names the credential expiry or its absence - sessions.json documented as a core moq-stats track outside the extension - an mTLS name keys an entitlement, never a certificate Co-Authored-By: Claude Fable 5.1 --- quest/m2/auth-api/revalidation-updates.md | 4 +++- quest/m2/qos/stats/encoder-feedback.md | 7 +++++-- quest/m2/qos/stats/schema.md | 5 ++++- 3 files changed, 12 insertions(+), 4 deletions(-) diff --git a/quest/m2/auth-api/revalidation-updates.md b/quest/m2/auth-api/revalidation-updates.md index fe1c66ab9f3..c475927b556 100644 --- a/quest/m2/auth-api/revalidation-updates.md +++ b/quest/m2/auth-api/revalidation-updates.md @@ -47,7 +47,9 @@ and meters, so rebuilding a local handle would retag nothing. `no-store`, or a value the relay cannot parse) is the endpoint opting out, and stays so. The relay says it once: the first such reply from an endpoint logs at WARN that sessions admitted under it are never re-checked and end - only at their credential's `exp`. One line per relay, never per session. + only when their credential expires, `exp` for a JWT and `notAfter` for a + certificate, or never for an anonymous session, and the line says which. + One line per relay, never per session. - Docs: the revalidation section of `doc/bin/relay/auth.md` gains a per-field table: tier updates in place, alias closes, and scope narrowing closes today (`covered_by` failing maps to `Recheck::Revoked`) and resizes once diff --git a/quest/m2/qos/stats/encoder-feedback.md b/quest/m2/qos/stats/encoder-feedback.md index 27c60094d58..7eb33307b49 100644 --- a/quest/m2/qos/stats/encoder-feedback.md +++ b/quest/m2/qos/stats/encoder-feedback.md @@ -17,8 +17,11 @@ prefix. Keyframe requests stay out. prefix, keeps one `moq_stats::Consumer` per `.stats` broadcast requesting `/subscriber.json`, and folds the reports into one signal, the share of viewers stalled over the last interval and their late - frame rate, weighted equally per viewer. Viewers that stop reporting age out - on the stats interval. + frame rate, weighted equally per viewer. The counters are cumulative, so + the handle keeps the previous snapshot per viewer and diffs it; a counter + that goes backwards is a restarted viewer and resets that baseline. Viewers + that stop reporting age out on the stats interval, so one stall long ago + never lowers the target forever. - `rate.rs` takes that signal beside the bandwidth estimate: a stalled share above a threshold steps the target down like a bandwidth drop, recovery follows the existing attack curve, and the estimate stays the ceiling. diff --git a/quest/m2/qos/stats/schema.md b/quest/m2/qos/stats/schema.md index 25428676cdb..d362d54857c 100644 --- a/quest/m2/qos/stats/schema.md +++ b/quest/m2/qos/stats/schema.md @@ -16,7 +16,10 @@ what a subscriber received and played, per audio and video. The relay is public with the `Copy` bound dropped; `Traffic` and `Presence` implement it as they do today. A frame is `BTreeMap>`, where `Stats` is `Traffic` with `E` flattened beside it; `TrafficFrame` becomes that - alias for `()`. + alias for `()`. `sessions.json` stays a core track outside the extension: + `[/]sessions.json[.z]`, a `BTreeMap` keyed by auth + root, read through `Consumer::sessions` whatever `E` is; a client publishes + it only when it holds sessions worth counting. - An exact-path mode. `ProducerConfig` treats its path as a prefix and advertises `/node[/]`, so a client asking for `room/alice.stats` would publish `room/alice.stats/node`, which no longer From 3e675e6582c321d1ce9ff4db6b7a5e7779ee4cda Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 11 Sep 2026 13:40:08 -0700 Subject: [PATCH 3/5] docs(quest): an mTLS name keys an entitlement, never a certificate Co-Authored-By: Claude Fable 5.1 --- quest/m2/auth-api/mtls-identity.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/quest/m2/auth-api/mtls-identity.md b/quest/m2/auth-api/mtls-identity.md index 9977fcbd92e..2516a17f05e 100644 --- a/quest/m2/auth-api/mtls-identity.md +++ b/quest/m2/auth-api/mtls-identity.md @@ -31,6 +31,9 @@ scope, because the root is the path the client dialed. 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. + Several CA-valid certificates may carry one name, by renewal or by design, + so the name keys an entitlement, never a certificate, and a deployment that + needs one grant per certificate enforces name uniqueness at its CA. 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` From b6656d924af88bfa2ed65ce6ec8e49627d7a0a88 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 11 Sep 2026 13:41:42 -0700 Subject: [PATCH 4/5] docs(quest): pin the anonymous rank key to dev and add the js/net and concept sync Co-Authored-By: Claude Fable 5.1 --- quest/m1/anonymous-route-rank.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/quest/m1/anonymous-route-rank.md b/quest/m1/anonymous-route-rank.md index 3262f5f8880..9528050ee53 100644 --- a/quest/m1/anonymous-route-rank.md +++ b/quest/m1/anonymous-route-rank.md @@ -32,10 +32,19 @@ Hop 0 in a chain is the mark, and it travels: This reverses the direction of #3060, whose quest is deleted with this one: an assigned identity is private selection state and forwarding it published a name for a peer that declined to give one. -- `route_order` becomes `(anonymous, Cost, len, hash, id)`, where `anonymous` - is whether the chain holds a 0 anywhere. Lite-03 hop-count placeholders are - 0 entries and count as anonymous, which is what they are. `Route` exposes - `is_anonymous()` for the bindings and the announcement stream. +- `route_order` becomes `(anonymous, Cost, len, hash, Reverse(id))`, where + `anonymous` is whether the chain holds a 0 anywhere; the rest of the key is + dev's as it stands. Main's leading `!announce` term and its `attach_source` + takeover gate do not exist on dev: every route in the table is announced, + routes for one prefix coexist, and `best_route` is the whole decision, so + arrival order cannot let an anonymous route replace an identified one. + Lite-03 hop-count placeholders are 0 entries and count as anonymous, which + is what they are. `Route` exposes `is_anonymous()` for the bindings and the + announcement stream. +- `js/net` keeps accepting 0 inside a received chain and exposes `anonymous` + on the announcement it yields; it ranks nothing today, and the browser hop + in [P2P](/quest/m3/p2p/README.md) forwards 0 like a relay when it lands. + `doc/concept/transport.md` states the selection rule beside route cost. - Loop detection is unchanged: a 0 entry matches nothing, and a relay's own id still appears in the chain wherever it forwarded the route. - Drafts: `drafts/draft-lcurley-moq-cluster.md` "Assigned Identities" says From 4b7f2ecac84170a8e2b4b4c0cc471e52bd5c7668 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 11 Sep 2026 13:42:38 -0700 Subject: [PATCH 5/5] docs(quest): the P2P questline exists only on dev, so name it instead of linking Co-Authored-By: Claude Fable 5.1 --- quest/m1/anonymous-route-rank.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/quest/m1/anonymous-route-rank.md b/quest/m1/anonymous-route-rank.md index 9528050ee53..f972773babf 100644 --- a/quest/m1/anonymous-route-rank.md +++ b/quest/m1/anonymous-route-rank.md @@ -43,7 +43,8 @@ Hop 0 in a chain is the mark, and it travels: announcement stream. - `js/net` keeps accepting 0 inside a received chain and exposes `anonymous` on the announcement it yields; it ranks nothing today, and the browser hop - in [P2P](/quest/m3/p2p/README.md) forwards 0 like a relay when it lands. + of the P2P questline, which lives on dev, forwards 0 like a relay when it + lands. `doc/concept/transport.md` states the selection rule beside route cost. - Loop detection is unchanged: a 0 entry matches nothing, and a relay's own id still appears in the chain wherever it forwarded the route.