Repository navigation
quest: plan proofs and nightly checks for moq-net #8472
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,54 @@ | ||
| # [L] The route rules hold from any state, not only the runs TLC reaches | ||
|
|
||
| ## Goal | ||
|
|
||
| An inductive invariant of the route model implies `LoopFree`, `NoRevival`, | ||
| `NoFalseEnd`, `NoRegression`, and `Truthful`. Apalache checks in Nightly that | ||
| it holds initially and that every step preserves it from any state satisfying | ||
| it, on each mesh shape of up to five relays. The rules then hold for runs of | ||
| any length and any number of changes, where TLC's pass covers one claim, two | ||
| revisions, and two session opens or closes. | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided 2026-11-10 (maintainer, /quest-plan on what could be proved about | ||
| moq-net): | ||
|
|
||
| - ✅ An inductive invariant checked by Apalache (rejected: a TLAPS proof for | ||
| every mesh size, whose hand-written steps break on each model change, until | ||
| this invariant has settled; verifying the Rust itself in Verus or Lean, | ||
| which needs the code rewritten around the prover). | ||
| - ✅ m1 (rejected: m4), because a flaw in the routing design is cheapest to | ||
| fix before lite-07 is cut. It does not gate the cut: a flaw it finds becomes | ||
| a fix quest that joins [Finalize moq-lite-07](/quest/m2/lite07-finalize.md) | ||
| then. | ||
|
|
||
| What it removes is the bound on the run, not on the mesh: sequence numbers, | ||
| revisions, and churn are unbounded, while the relay count and queue lengths | ||
| stay constants the config states. Say both bounds in the `verify-route` skill. | ||
|
|
||
| - Start from the argument Babel and DUAL rest on: along selected next hops the | ||
| (seqno, distance) pair strictly improves, and every message in flight carries | ||
| a value no better than its sender's feasibility distance when it was sent. | ||
| Strengthen until Apalache finds no counterexample to induction. | ||
| - A counterexample to induction starts from a state that may be unreachable. | ||
| If TLC cannot reach it, the invariant is too weak: strengthen it. If it can, | ||
| replay it on `route::tests::Sim` as the skill says before calling it a bug. | ||
| - Apalache needs type annotations. Add them to the spec TLC already checks, | ||
| so both tools read one file and neither drifts. | ||
| - `NoCountToInfinity` stays out until | ||
| [the echo fix](/quest/m2/cluster-routing/routes/echo-order.md) lands; expect | ||
| the search for the invariant to find that path again. | ||
| - Run it through the `tla` recipes with Apalache from the flake. If five | ||
| relays does not fit Nightly, record the largest mesh that does and its time. | ||
|
|
||
| Public API: none. Wire: none. | ||
|
|
||
| ## Required | ||
|
|
||
| - [The route model covers a mesh with clients and an announce budget](/quest/m1/route-mesh-model.md) - the spec parametrised over mesh shapes that this invariant is stated on | ||
|
|
||
| ## Related | ||
|
|
||
| - [The TLA+ models run nightly and reviews resync them](/quest/m1/model-checks-nightly.md) - the Nightly job this check joins | ||
| - [Route sweeps are checked against the TLA+ model](/quest/m1/route-trace-validation.md) - ties the same spec to the code |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,55 @@ | ||
| # [M] A symbolic model proves a route key proof binds to its session and side | ||
|
|
||
| ## Goal | ||
|
|
||
| A Tamarin model of lite-07's Route Key Parameter proves that when an endpoint | ||
| accepts a key on a session, the holder of that key signed for that session | ||
| and that side of it. The attacker controls the network, runs its own sessions | ||
| with both endpoints, and holds other route keys. The draft states what each | ||
| transport binding's exporter must guarantee for the proof to hold, each | ||
| binding in Rust and JS is checked against that, and the model runs in Nightly. | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided 2026-11-10 (maintainer, /quest-plan on what could be proved about | ||
| moq-net): | ||
|
|
||
| - ✅ Tamarin (rejected: no formal analysis; the proof is a hand-rolled | ||
| construction, the kind symbolic provers find reflection and relaying | ||
| attacks in). | ||
| - ✅ m1 and it gates the cut (rejected: ungated like the TLA+ models; m4). | ||
| The signed transcript freezes when lite-07 is cut, and a flaw in it can | ||
| only be fixed on the wire, so | ||
| [Finalize moq-lite-07](/quest/m2/lite07-finalize.md) lists this quest. | ||
|
|
||
| The proof (`rs/moq-net/src/route/proof.rs`, `js/net/src/lite/`, the draft's | ||
| Route Key Parameter section) is an Ed25519 signature over the domain string, | ||
| one byte for the sender's side, and 32 bytes exported from the session. | ||
|
|
||
| - Model the handshake as a session whose exporter secret only its two | ||
| endpoints know and no other session shares. That assumption is the result | ||
| to pin down: state it in the draft, then check each binding against it. | ||
| Cover at least TLS 1.3 only (an older TLS without extended master secret | ||
| lets one party give two sessions the same secret), resumption and 0-RTT, the | ||
| WebTransport session exporter, and a session reached through an intermediary | ||
| that terminates TLS. | ||
| - Lemmas: the protocol can run; an accepted proof implies its key's holder | ||
| signed on that session as that side (injective agreement); no reflection to | ||
| the sender; no replay on another session; a proof the attacker relays | ||
| between two sessions it terminates is rejected. | ||
| - Out of scope: an endpoint whose own key is compromised, and relays that | ||
| share one key on purpose, which the draft allows. | ||
| - A lemma that fails is a finding: fix the transcript in Rust, JS, and the | ||
| draft in this PR when the fix is clear, and bring the maintainer the wire | ||
| change when it is not. | ||
| - Keep the model beside the others (`rs/moq-net/verify/`), with a `verify-*` | ||
| skill in their shape and Tamarin run from the flake as the `tla` recipe | ||
| runs TLC. | ||
|
|
||
| Public API: none unless a finding changes the proof. Wire: none unless a | ||
| finding changes the signed transcript. | ||
|
|
||
| ## Related | ||
|
|
||
| - [The TLA+ models run nightly and reviews resync them](/quest/m1/model-checks-nightly.md) - the Nightly job and Coverage-table check this model joins | ||
| - [Routes and announces](/quest/m2/cluster-routing/routes/README.md) - files a peer's routes under the key this proves | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,55 @@ | ||
| # [L] A hostile peer's session cannot panic, leak, or disturb another broadcast | ||
|
|
||
| ## Goal | ||
|
|
||
| A fuzz target per protocol drives a whole moq-net session, as a relay runs | ||
| it, against a peer that does anything: any message in any order, on any | ||
| stream, with resets, stalls, and closes. It asserts that the session never | ||
| panics, that what it holds returns to its baseline once the peer is gone, and | ||
| that a bystander's broadcast on another session of the same origin delivers | ||
| every group unchanged. Nightly runs both targets, and `just check` replays | ||
| their regressions. | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided 2026-11-10 (maintainer, /quest-plan on what could be proved about | ||
| moq-net). Today's fuzz targets stop at the codecs and stream framing; nothing | ||
| tests the rule in `AGENTS.md` that a misbehaving peer must never panic, cost | ||
| unbounded work, or affect other broadcasts. | ||
|
|
||
| - ✅ moq-lite and moq-transport (rejected: moq-lite only). A relay accepts | ||
| both from untrusted peers, and a hostile peer picks the weaker one. The | ||
| input picks the version from those a server accepts. | ||
| - ✅ m1 (rejected: m4), since what it finds is in code that ships with the | ||
| cut. | ||
|
|
||
| Shape: | ||
|
|
||
| - The input decodes to a script of peer actions: open a stream of a type, | ||
| write a well-formed message with fuzzed fields or raw bytes, FIN, reset or | ||
| stop with a code, send a datagram, advance the clock, close. Run it over | ||
| the in-memory transport doubles on the mocked clock, single-threaded, so a | ||
| failing input replays exactly. | ||
| - The victim is one origin serving two sessions: the fuzzed peer, and a | ||
| bystander publishing and subscribing to its own broadcast. | ||
| - Oracles: no panic; the bystander's subscriber reads every group, in order, | ||
| byte for byte; after the peer closes and the clock runs past every timeout, | ||
| the origin's pool charges, live tasks, and open streams are back to what the | ||
| bystander alone accounts for. Unbounded work shows as libFuzzer's per-input | ||
| timeout, set low. | ||
| - Seed with transcripts recorded from the integration tests (announce, | ||
| subscribe, a group, a fetch), so the fuzzer starts deep in the state | ||
| machine instead of at SETUP. | ||
| - Follow `rs/moq-net/fuzz/README.md`: bodies in the `fuzz` module, a one-line | ||
| shim each, committed regressions, a row in `nightly.yml`'s matrix. Measure | ||
| whether five minutes reaches past setup and say what budget it needs. | ||
|
|
||
| Out of scope: `js/net`, where a hostile server can only hurt the tab that | ||
| dialed it. | ||
|
|
||
| Public API: none. Wire: none. | ||
|
|
||
| ## Related | ||
|
|
||
| - [Wire fuzz coverage](/quest/m4/wire-fuzz-coverage.md) - the socket-level unsafe a peer reaches | ||
| - [Peer grant bound](/quest/m4/peer-grant-bound.md) - one known cost a peer's message can impose |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,44 @@ | ||
| # [M] Kani proves the varint codecs and length arithmetic for every input | ||
|
|
||
| ## Goal | ||
|
|
||
| Kani proves, for every input within a stated size and not a sampled few, that | ||
| moq-net's varint codecs never panic, never read past their input, and | ||
| round-trip every value, and that the length and bound arithmetic a peer's | ||
| numbers reach cannot overflow. The proofs run in Nightly on the same bodies | ||
| the fuzz targets run. | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided 2026-11-10 (maintainer, /quest-plan on what could be proved about | ||
| moq-net). Milestone m4: it hardens code whose design is not in question. | ||
|
|
||
| Kani is a bounded model checker for Rust (s2n-quic, Firecracker, and the | ||
| standard library use it). It runs the real code, so it cannot drift from it | ||
| the way a model can. | ||
|
|
||
| - Scope: both varint codecs in `rs/moq-net/src/coding/varint.rs` (every `u64` | ||
| encodes and decodes back to itself at the length the draft gives; every | ||
|
Comment on lines
+20
to
+21
Contributor
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. The QUIC form caps at Technical details# The varint proof obligation needs per-form ranges
## Affected sites
- `quest/m4/codec-kani.md:20` — "every `u64` encodes and decodes back to itself at the length the draft gives"
- `rs/moq-net/src/coding/varint.rs:18` — `MAX_QUIC = (1 << 62) - 1`
- `rs/moq-net/src/coding/varint.rs:234` — `decode_quic`, `encode_quic` returns `BoundsExceeded` above the cap
- `rs/moq-net/src/coding/varint.rs:26` — `Form::{Quic, LeadingOnes}`
## Required outcome
- The scope sentence names the admitted range per form (QUIC up to `2^62 - 1`, leading ones up to `u64::MAX`) and the round-trip property within each. |
||
| byte string up to the longest encoding either needs more input or decodes to | ||
| a value whose encoding is a prefix of it), the decoder's length-prefix and | ||
| cap checks, and the 2^61 - 1 timestamp bound. Add other integer arithmetic | ||
| a peer's numbers reach, such as stream credit and byte accounting, only | ||
| where a proof finishes in minutes. | ||
| - Whole message decoders stay with the fuzzers: Kani scales badly through | ||
| `Bytes`, `Vec`, and `HashMap`. | ||
| - ✅ Plain `#[kani::proof]` harnesses that call the existing `fuzz` module | ||
| bodies with `kani::any()` bytes (rejected: the Bolero framework, a | ||
| dependency whose one job here a ten-line harness does). | ||
| - Cost to the tree: one `cfg(kani)` check-cfg entry, and no shims around | ||
| anything, unlike loom. Only Nightly compiles the harnesses, so its job is | ||
| what keeps them building. | ||
| - A `just rs kani` recipe and a Nightly row, installing Kani as the fuzz job | ||
| installs cargo-fuzz. Each harness states its unwind bound. A proof that | ||
| stops finishing is narrowed in the open, never dropped or given a longer | ||
| timeout to hide it. | ||
|
|
||
| Public API: none. Wire: none. | ||
|
|
||
| ## Related | ||
|
|
||
| - [Wire fuzz coverage](/quest/m4/wire-fuzz-coverage.md) - the fuzz targets and Miri run beside these proofs | ||
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.
quest/README.mdsays "The cut waits on m2 alone" andquest/m1/README.mdsays "The cut no longer waits on m1", yet this new m1 quest is listed in the cut'sRequiredand says it "gates the cut". The only other m1 entry in that list (stream-credit/takeover) is held by an open claim, which is the tree's stated mechanism; this one has none. Either move it to m2 (its finding can change the frozen wire) or record the exception in m1's Plan.Technical details