soak: a correctness and authorization suite for the P2P management channel

[edjroz]

Stacked on #33. This branch is 31 commits on top of edjroz/soak-topology, so until #33 merges
the diff below includes its 14 commits. GitHub cannot target a base branch that lives on a fork, so
the base stays main. Review #33 first; this PR's own change is the crates/soak/src/manage/
module, auth.rs, main.rs, nodes.rs, and the README section.

What

soak manage: a pass/fail evaluation of DefraDB's P2P management channel on a real multi-node
cluster with node access control enabled. The channel lets one Rust node administer another's
replicators, collection and document subscriptions, and peer connections, relayed through any node's
POST /api/v0/p2p/manage. The two-node cases are already covered by defradb.rs's integration tests;
this suite runs only what they cannot express: N-node fan-out through untrusted relays, three actors
with different grants, live grant and revoke, requests at the size bound, a target that stops
replying, ops concurrent with a write burst, and Go peers present in the mesh.

export DEFRA_RUST_BINARY=<defra built from defradb.rs main>
cargo run -q -p soak -- manage --topology 3r0g --out <dir>                      # libp2p, all cases
cargo run -q -p soak -- manage --transport iroh --topology 3r0g --out <dir>     # same table on iroh
cargo run -q -p soak -- manage --topology 2r2g --cases H1 --out <dir>           # Go peers present

About 90 s for the full libp2p table. <dir> receives summary.json (per case: outcome, per-op
latency, the target's list state after each mutate) and cases.md.

Shape

• Three actors from generate_identity: admin (every permission), operator (two permissions on
  different ops), outsider (none). Tokens are minted with aud = the target's peer id, the way the
  node's own manage_relay tests do it.
• A raw HTTP relay client, no retries, so a case controls the exact bytes on the wire and can build an
  oversized request.
• A table of 19 cases in six groups (routing, authz, state, bounds, partition, hybrid),
  each restoring what it changes, each with red-first tests against a fake client. Outcomes are
  Pass, Fail { expected, got }, Skip { reason }, or Infra { error }, so a harness fault never
  reads as a product finding.
• The runner probes every node a case will use before running it; an unreachable node yields
  Infra { <node> unreachable before <case>; last case to touch it: <name> }, and the bounds group
  runs last, so one case that wedges a node cannot turn later cases into false failures.
• --transport iroh runs the identical table on Iroh with per-transport bounds (16 MiB on libp2p,
  the frame cap, located by bisection once; 4 MiB on Iroh) and per-transport dial budgets.
• --topology NrMg on libp2p adds Go nodes as replication peers; H1 asserts every Go node converges
  after the Rust-side ops and that its replicator ids still match the mesh. Go is never a target; it
  has no management protocol.
• NAC is new for the soak harness: with_nac() on the cluster, all mesh wiring through the
  _with_identity verbs as the owner. Go nodes take the same startup identity.

Deferred with explicit refusals: --docker (so P1, the partition case, skips on the process
backend) and Go on Iroh.

What it finds on defradb.rs main (c92cc09b0)

Every Fail below reproduces a node defect; the expectations are the documented behaviour and the
suite does not bend them. Each was stable across at least three independent runs, and the suite was
reviewed adversarially twice, case by case, before this PR.

case	transport	finding
A1, A3, A4	both	per-permission NAC grants have no effect on the channel: an identity granted add-p2p-collection is refused exactly like one with no grant; only admin authorizes anything (crates/acp/src/nac/policy.rs:59-66)
R3	both	a restarted node loses every NAC relationship while its schema survives (crates/db/src/nac/mod.rs:118-127 takes the first-enable branch)
S4	iroh	a document never arrives at a node that was told to subscribe to it, though the node lists it as tracked
B1	iroh	a DocumentAdd under the 4 MiB cap parks the endpoint loop; the node accepts nothing until restart
R3 (dial half)	iroh	dialing a stopped peer takes ~30 s; the relay's 10 s connect budget is not honoured
R3 (restart half)	iroh	about one run in three, the relay cannot re-dial a peer that restarted and is answering its own HTTP; reported distinctly from the NAC finding
C1	libp2p	about one run in three, one document written during a burst concurrent with remote subscription edits is absent from the sink 20 s later

Issues for each are drafted and will be filed against defradb.rs separately; this PR carries the
reproductions, not the fixes.

Verification

cargo test -p soak 167, cargo clippy -p soak --all-targets -- -D warnings, cargo fmt --all -- check. Full-table runs: libp2p 3× identical at each of three heads, iroh 3× identical, hybrid 3×
identical; only slowest_ms moves between runs. Two case-by-case reviews of the suite itself
against its design, the second on the final head, with the review's five "passes but does not
establish the claim" findings fixed in the last eight commits.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Qy6KdB84tUcS6DxiVRmnNo

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: fd1451b7-017d-4fc3-ad6e-3d0aca94f14c

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}