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
4 changes: 4 additions & 0 deletions quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,10 @@ moves what remains of them once their claims merge.
- [The route model covers a mesh with clients and an announce budget](/quest/m1/route-mesh-model.md) - every ordering on 4-5 relay meshes with two origins and clients, with an announce budget and convergence
- [Seeded lite-07 meshes hold the route rules and an announce budget](/quest/m1/route-mesh-sweep.md) - the route rules and message budget checked on real sessions over random meshes
- [A model of a relay chain's failover delivers every group once](/quest/m1/failover-chain-model.md) - route, resume, and subscribe composed across a relay chain whose hops fail
- [Route sweeps are checked against the TLA+ model](/quest/m1/route-trace-validation.md) - each `sweep_handoff` run is a behaviour of `RouteHandoff.tla`, with a trace format the other models reuse
- [The route rules hold from any state, not only the runs TLC reaches](/quest/m1/route-inductive.md) - Apalache checks an inductive invariant behind the route rules on meshes of up to five relays
- [A symbolic model proves a route key proof binds to its session and side](/quest/m1/route-key-model.md) - Tamarin proves no replay, reflection, or relaying of lite-07's Route Key Parameter, and gates the cut
- [A hostile peer's session cannot panic, leak, or disturb another broadcast](/quest/m1/session-fuzz.md) - whole-session fuzz targets for moq-lite and moq-transport with a bystander broadcast as the oracle
- [A reused moq-transport alias refuses its track at once](/quest/m1/ietf-alias-refuse.md) - a SUBSCRIBE_OK on an alias already bound fails its readers and removes its entry without waiting on the peer's FIN acknowledgement
- [Unused crates, scripts, and files are deleted](/quest/m1/unused-code.md) - moq-room, the moq-native tombstone, demo/throttle, sh/dart/publish.sh, demo/web's Solid deps, and unpublished packages' release notes go
- [The recurring audits are fewer and carry plans, not results](/quest/m1/audit-merge.md) - m3's 13 audits become about five, each a Goal plus a short check-first list
Expand Down
12 changes: 10 additions & 2 deletions quest/m1/model-checks-nightly.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,9 @@
Every TLA+ model in the tree runs in Nightly: each passing config must pass,
and each open-finding config must still fail, so a fix that should promote
its rule is noticed. A PR that changes code a model covers gets that model
rerun and resynced in review, so no model keeps passing on code that no
longer exists.
rerun and resynced in review, and renaming or deleting a function a model
covers fails `just check` until its skill names the new one, so no model
keeps passing on code that no longer exists.

## Plan

Expand All @@ -30,5 +31,12 @@ skills.
Coverage table, and the PR updates the model and its sync commit.
- The periodic resync for changes that skipped review is a check-first item
in the [test coverage audit](/quest/m3/audit-test-coverage.md).
- ✅ `just check` also fails when a function a `verify-*` skill's Coverage
table names no longer exists in the file the row names (decided 2026-11-10,
maintainer, a later /quest-plan the same day; rejected: the review rule
alone). Unlike the touched-file check rejected above, it fires only when
modelled code is renamed or deleted, which is when the table's mapping is
already wrong. Give the tables one parseable form (a file, then its
symbols) and test the check on a renamed symbol.

Public API: none. Wire: none.
54 changes: 54 additions & 0 deletions quest/m1/route-inductive.md
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
55 changes: 55 additions & 0 deletions quest/m1/route-key-model.md
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).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

quest/README.md says "The cut waits on m2 alone" and quest/m1/README.md says "The cut no longer waits on m1", yet this new m1 quest is listed in the cut's Required and 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
# A cut gate in m1 has no mechanism

## Affected sites
- `quest/m1/route-key-model.md:20` — "✅ m1 and it gates the cut"
- `quest/m2/lite07-finalize.md:137` — listed under the cut's `Required`
- `quest/README.md:16` and `:59` — "The cut waits on m2 alone"
- `quest/m1/README.md:15` — "The cut no longer waits on m1"
- `quest/m1/README.md:25` — the held-by-open-claims mechanism
- `quest/m2/README.md:30` — held claims are the stated exception

## Required outcome
- The tree no longer states both that the cut waits on m2 alone and that a fresh m1 quest gates it without a claim.

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
Expand Up @@ -11,7 +11,20 @@ resync the model.

Decided 2026-11-10 (maintainer, /quest-plan), as the strongest guard against
the route model drifting from the code ([moq-dev/moq#8447](https://github.com/moq-dev/moq/pull/8447)).
Route only for now; judge the other models after.

Decided 2026-11-10 (maintainer, a later /quest-plan the same day):

- ✅ m1 (rejected: staying in m4). The [mesh model](/quest/m1/route-mesh-model.md),
the [inductive invariant](/quest/m1/route-inductive.md), and the
[cache-aware routing proof](/quest/m2/cache-routing-proof.md) all build on
`RouteHandoff.tla`, so drift there costs the most.
- ✅ The other three models get trace validation too, each its own m4 quest
behind this one (rejected: "route only for now; judge the other models
after", decided earlier the same day). So the recorder's trace format and
the recipe that hands a trace to TLC are built here for
[resume](/quest/m4/resume-trace-validation.md),
[reconnect](/quest/m4/reconnect-trace-validation.md), and
[subscribe](/quest/m4/subscribe-trace-validation.md) to reuse.

This is TLA+ trace validation (Cirstea, Kuppe, Loillier, Merz, 2024, used on
CCF and etcd's raft): `route::tests::Sim` records each step as the model
Expand Down
55 changes: 55 additions & 0 deletions quest/m1/session-fuzz.md
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
7 changes: 7 additions & 0 deletions quest/m2/lite07-finalize.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,12 @@ Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and r
The explicit `Oldest` anchor rides [time addressing's model](/quest/m2/time-addressing/model.md),
whose lite-07 encoding [lite-07 by start](/quest/m2/time-addressing/lite07.md) carries.

Decided 2026-11-10 (maintainer, /quest-plan on what could be proved about
moq-net): ✅ the cut waits for the symbolic model of the Route Key Parameter
(rejected: neither proof gating, as the TLA+ models do not; the inductive
routing invariant gating too, which sits behind the mesh model). The signed
transcript freezes at the cut and a flaw in it can only be fixed on the wire.

## Required

- [Routes and announces](/quest/m2/cluster-routing/routes/README.md) - lite-07 carries the route layer: ROUTE per origin node and path-less ANNOUNCE, with the native hop list gone (only the temporary lite-06 compatibility chain remains)
Expand All @@ -128,6 +134,7 @@ whose lite-07 encoding [lite-07 by start](/quest/m2/time-addressing/lite07.md) c
- [Delete the old start bookkeeping](/quest/m2/subscribe-ranges/start-bookkeeping.md) - may change START per update on lite-07
- [Prove cache-aware routing](/quest/m2/cache-routing-proof.md) - may add the warm-route message to lite-07; leaves this list if the proof places it in a SETUP extension
- [Route latency](/quest/m2/route-latency.md) - may add a latency sum to ROUTE; leaves this list if the maintainer takes the no-wire path
- [A symbolic model proves a route key proof binds to its session and side](/quest/m1/route-key-model.md) - may change what the Route Key Parameter signs, if the model finds a replay, reflection, or relaying attack

## Related

Expand Down
8 changes: 7 additions & 1 deletion quest/m4/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,4 +106,10 @@ deleted.
- [The dev shell builds Kotlin with Gradle 9](/quest/m4/kt-gradle-9.md) - `gradle_9` in the dev shell, so the Android target builds there
- [A hung Python test fails instead of hanging the suite](/quest/m4/py-test-timeouts.md) - one pytest-timeout bound covers every `py/` test
- [Chromium's Opus encoder stamps chunks from their input](/quest/m4/chromium-opus-timestamps.md) - waiting on Chromium; unlocks native `usedtx` for push-to-talk
- [Route sweeps are checked against the TLA+ model](/quest/m4/route-trace-validation.md) - each `sweep_handoff` run is a behaviour of `RouteHandoff.tla`
- [Resume sweeps are checked against the TLA+ model](/quest/m4/resume-trace-validation.md) - each resume sweep case is a behaviour of `ResumeReader.tla`
- [Reconnect runs are checked against the TLA+ model](/quest/m4/reconnect-trace-validation.md) - a seeded sweep of the connect policy whose runs are behaviours of `Handover.tla`
- [Subscription runs are checked against the TLA+ model](/quest/m4/subscribe-trace-validation.md) - a seeded sweep of one lite-07 subscription whose runs are behaviours of `SubscribeAccounting.tla`
- [Kani proves the varint codecs and length arithmetic for every input](/quest/m4/codec-kani.md) - bounded proofs of no panic, no overflow, and round-trip, nightly
- [js/net decodes the Rust fuzzers' corpus the same way](/quest/m4/fuzz-corpus-js.md) - nightly, both codecs agree on acceptance and re-encoding for every corpus input
- [No mutation of the route and resume code survives its tests](/quest/m4/mutants.md) - cargo-mutants nightly, failing on any survivor
- [Concurrent tests run under many Miri schedules and ThreadSanitizer](/quest/m4/miri-seeds-tsan.md) - shim-free race checks on kio and moq-net, nightly
44 changes: 44 additions & 0 deletions quest/m4/codec-kani.md
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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The QUIC form caps at MAX_QUIC = 2^62 - 1, so "every u64 encodes and decodes back to itself" cannot be a proof obligation for that form, and a harness over kani::any::<u64>() would fail on values above the cap. State each form's admitted range and the round-trip property inside it, next to the existing "prefix of it" decoder property.

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
Loading