diff --git a/.github/workflows/csi-data-policy.yml b/.github/workflows/csi-data-policy.yml index 2d0f30dd..bac0d06c 100644 --- a/.github/workflows/csi-data-policy.yml +++ b/.github/workflows/csi-data-policy.yml @@ -1,12 +1,12 @@ -name: CSI data policy (ADR-296) +name: CSI data policy (ADR-299) -# ADR-296 repository CSI data-incident guard. Fails when CSI-format files +# ADR-299 repository CSI data-incident guard. Fails when CSI-format files # (*.csi.jsonl / *.csi.meta.json) or oversized JSONL captures are tracked in -# git. Raw CSI is person data and must never be committed (CLAUDE.md, ADR-296). +# git. Raw CSI is person data and must never be committed (CLAUDE.md, ADR-299). # # NOTE: the tree currently still contains the pre-existing incident recordings # under data/recordings/ and v2/data/recordings/, whose removal is gated on -# data-owner sign-off (ADR-296). Until they are removed this job is EXPECTED to +# data-owner sign-off (ADR-299). Until they are removed this job is EXPECTED to # fail, and that failure documents the incident. To make it green in a # follow-up without weakening the guard for NEW files, set CSI_POLICY_BASELINE # to a file listing the acknowledged paths (see the script header). @@ -45,7 +45,7 @@ jobs: if: always() run: | { - echo '### CSI data policy (ADR-296)' + echo '### CSI data policy (ADR-299)' echo '' echo '```' bash scripts/csi-data-policy-check.sh --tracked 2>&1 || true diff --git a/.gitignore b/.gitignore index 8b5c3912..607fe8d7 100644 --- a/.gitignore +++ b/.gitignore @@ -29,7 +29,7 @@ firmware/esp32-csi-node/test/*.obj .swarm/ # CSI recordings (local training/capture data — CSI is person data per -# CLAUDE.md; never commit). Covers current and legacy layouts. See ADR-296. +# CLAUDE.md; never commit). Covers current and legacy layouts. See ADR-299. data/recordings/ v2/data/recordings/ rust-port/wifi-densepose-rs/data/recordings/ diff --git a/docs/adr/ADR-288-veil-privacy-shield-compliant-waveform.md b/docs/adr/ADR-288-veil-privacy-shield-compliant-waveform.md new file mode 100644 index 00000000..2983e4fd --- /dev/null +++ b/docs/adr/ADR-288-veil-privacy-shield-compliant-waveform.md @@ -0,0 +1,231 @@ +# ADR-288: VEIL — a compliant-waveform privacy shield against unauthorized WiFi sensing + +| Field | Value | +|-------|-------| +| **Status** | Proposed — implemented (P1 reference model) | +| **Date** | 2026-08-09 | +| **Deciders** | ruv | +| **Codename** | **VEIL** — Verifiable Emission-shaping for Identity-Leakage prevention | +| **Codebase target** | new leaf crate `v2/crates/wifi-densepose-privshield` | +| **Parent** | ADR-118 (BFLD — the detection layer VEIL is the countermeasure to), ADR-282 (mandatory L0–L5 evidence ladder) | +| **Relates to** | ADR-120/121 (BFLD privacy class + identity-risk scoring — the trigger source), ADR-141 (privacy control plane / runtime attestation — the audit consumer), ADR-280 (active sensing / governed actuation — VEIL is a defensive sensing action), ADR-185 §13 (`wifi-densepose-aether` — the pure-compute leaf pattern this crate follows) | +| **Research bundle** | [`docs/research/privacy-shield/`](../research/privacy-shield/) (9 files) | +| **Tracking issue** | TBD | + +## 0. PROOF discipline + +Every defense number this crate produces is **SYNTHETIC / evidence level L0** +(ADR-282): generated by the crate's own model (`identity::Channel`), attacked by +the crate's own classifier (`attacker::NearestCentroidAttacker`), and scored +against its own known labels. Nothing here has been validated against real WiFi +silicon, and the crate contains no radio integration and cannot emit RF. External +attack/defense results cited from the literature (BFId, LeakyBeam, DySPAN-2026, +IRShield, FCC statutes) are **EXTERNAL** evidence and labelled MEASURED/CLAIMED in +the research bundle. The single measured claim about *our own behavior* is the +pinned deterministic witness in `proof.rs`. + +## 1. Context + +### 1.1 The gap + +IEEE 802.11ac/ax beamforming feedback (BFI) — the compressed Givens-rotation +angle matrices (φ/ψ) a client sends the AP — is transmitted **unencrypted on the +management plane**. Any device in monitor mode can capture it for every station +at once, no network access, and the target need carry no device. The literature +establishes the severity: **BFId** (ACM CCS 2025) re-identifies individuals from +BFI; **LeakyBeam** (NDSS 2025) detects occupancy through walls at 20 m from BFI; +**BeamSense** recognizes activities at up to 99.28%. IEEE Std **802.11bf-2025** +(published 26 Sep 2025) standardizes the sensing measurement/feedback surface +these attacks abuse — and a 2023 proposal for a BFI secure-transmission mechanism +(802.11-23/0782) was **withdrawn**, so the standard shipped with no privacy +protections. + +RuView already has a *detection* layer for this: **BFLD** (ADR-118/121) measures +the identity-leakage of each frame and gates what leaves the node. But BFLD +protects *RuView's own outputs*; it does nothing about a **third-party sniffer** +capturing the room's plaintext BFI off the air. There is no RuView component, and +per our market survey no shipping product anywhere, that prevents that. + +### 1.2 Constraint: compliant waveform controls, never jamming + +The defense must preserve normal communications and must not interfere with any +other station. Jamming (47 U.S.C. §333/§302a) is defined by *adding energy to +interfere with others' transmissions*. Any acceptable control must shape only the +node's **own** standards-conformant emission. + +### 1.3 The separability insight + +Identity leaks through the *fine* cross-subcarrier phase structure of a +beamforming report; data throughput rides the *dominant* beam direction. These +are (mostly) separable subspaces — so a transform confined to the fine subspace +can wreck re-identification while sparing the beam the link depends on. DySPAN-2026 +independently MEASURED that shaping fine-resolution feedback is near-free in +throughput, corroborating the insight. + +## 2. Decision + +Ship **`wifi-densepose-privshield`** (VEIL) as a standalone pure-compute leaf +crate (the `wifi-densepose-aether`/`nvsim` pattern: dependency-free, deterministic, +WASM-ready, zero coupling to any radio or ingestion path), implementing: + +1. **A SYNTHETIC two-subspace BFI model** (`identity.rs`): each identity owns a + stable fine-block signature; sessions add environmental nuisance; the comm + block is identity-free and carries throughput. +2. **The protector** (`protector.rs`): compliant waveform controls, primarily a + **per-session keyed orthogonal rotation of the fine subspace, composed from + extra Givens rotations** — the report's native primitive. Plus feedback + quantization/dither, sounding-cadence randomization, and a `SensingDetector` + that engages the shield only when sensing activity is observed. +3. **The adversary** (`attacker.rs`): a passive nearest-centroid re-identifier + modeling the BFId threat, with selectable Euclidean/Cosine metrics. +4. **A throughput model** (`throughput.rs`): + `(1 − sounding − feedback_airtime) · C(SNR·(1−ρ))/C(SNR)`, where the residual + `ρ` falls with feedback bits and the feedback airtime rises with them — giving + a genuine interior throughput optimum in feedback resolution. +5. **A compliance audit** (`compliance.rs`): the rotation is orthogonal ⇒ + energy-preserving ⇒ adds no interfering energy ⇒ **not jamming**, turned into a + checked `ComplianceReport` (energy ratio ≈ 1.0). +6. **The experiment** (`experiment.rs`): runs the attacker against unprotected and + protected traffic and reports both accuracies vs. chance, plus throughput and + compliance, with a single `passed()` verdict. +7. **The hyper-optimizer** (`optimize.rs`): derives the shipped shield config + rather than hand-picking it — the throughput-optimal feedback resolution and + the minimum rotation-mixing budget that collapses re-ID robustly (across both + attacker metrics and N∈{16,32}), plus a Pareto frontier. +8. **A deterministic proof** (`proof.rs`): a pinned FNV-1a witness over the + reference experiment (the `nvsim`/`verify.py` discipline). + +### 2.1 Why the keyed Givens rotation + +It is simultaneously **orthogonal** (energy-preserving ⇒ compliant), +**key-reversible** (the associated AP shares the session key and recovers the true +precoder ⇒ throughput preserved), and **fresh per session** (a sniffer sees a new +random rotation of the signature each session and cannot average it back ⇒ the +enrollment attack collapses; over unknown rotations the signature carries no +stable discriminative information ⇒ re-ID → chance). It is the shared-secret +precoding idea (cf. MIMOCrypt) specialized to the identity-bearing subspace. + +### 2.2 Measured behavior (SYNTHETIC / L0) + +Reference experiment at the hyper-optimized operating point (§opt), default +scene, N=16 identities, `cargo test`: + +| Metric | Shield off | Shield on | +|---|---|---| +| Passive re-ID accuracy | 100.0% | **4.7%** (chance 6.25%) | +| Link throughput ratio | 100% | **97.6%** | +| Emission energy ratio | — | **1.000000** (compliant) | + +All 35 unit/proof tests + doctest pass; the crate builds for +`wasm32-unknown-unknown` and is clippy-clean. + +### opt. Hyper-optimization (`optimize.rs`) + +The shipped shield config is the optimizer's output, not a guess, and +`ShieldConfig::default()` is asserted equal to it: + +- **Feedback resolution = 5 bits.** Throughput has an interior optimum in + feedback bits (residual falls, feedback airtime rises); the unconstrained + optimum is 3 bits (matching DySPAN-2026), and 5 is the throughput-best value in + the spec-allowed 802.11 {5,7,9} set. +- **Givens passes = 96.** The proven minimum for robust collapse — across both + attacker metrics *and* N∈{16,32} — is **48**; the shipped 96 is a free 2× + privacy margin, since the keyed rotation is derived from the shared secret and + never signaled (extra passes cost compute, not airtime). The original + hand-picked 112 was 2.3× over-provisioned. + +Net vs. the original hand-picked (112 passes / 7 bits): the optimum is strictly +better on **both** privacy (re-ID 0.047 vs 0.078) and throughput (0.976 vs 0.974), +and is now verified rather than assumed. See +`docs/research/privacy-shield/08-optimization.md`. + +### harness. Native terminal harness + TUI (`src/bin/veil.rs`) + +A custom, dependency-free binary (`veil`) ships with the crate — the in-repo, +native counterpart to the npm metaharness (ADR-289). It drives the same public +API the tests use, as an interactive ANSI dashboard plus scriptable subcommands +(`report`, `sweep`, `optimize`, `adaptive `, `proof`, `doctor`, `tui`). +Std-only (no `crossterm`/`ratatui`): the TUI is a command-driven redraw loop, so +it runs in any terminal, pipe, or CI and keeps the crate a pure leaf. It reports +only SYNTHETIC/L0 numbers and never relabels them. The wasm leaf story is +unchanged (validated with `--lib`; the bin is native-only). + +### sota. 2025–2026 evidence update (verified) + +A cited, adversarially-verified SOTA sweep +(`docs/research/privacy-shield/09-sota-update-2026.md`) refines the threat and +positioning. Load-bearing points for this ADR: + +- **Threat is broader and cheaper than §1.1 stated.** A passive, keyless, + single-antenna sniffer at ~20 m and *through walls* can identify people + (BFId, 99.5%/N=197, `MEASURED`), read **breathing** from stationary occupants + and **keystrokes/PINs** (LeakyBeam / WiKI-Eve / SThief, `MEASURED`), and — + decisively — **reconstruct full CSI from the sniffed BFI** (BFIAttack, + ≥93% single-antenna, `MEASURED`). VEIL's obfuscation must therefore degrade + *reconstructed-CSI* utility, not merely raw-BFI feature noise; because VEIL's + rotation is a **secret orthogonal** transform, the attacker has no key and no + closed-form to invert — this is now a claim to **test**, not assume. +- **VEIL's family is independently validated.** AP-side per-packet random + unitary on the LTF (LeakyBeam defense, 89.7%→~51%, `MEASURED`) and RIS + obfuscation (PrivISAC, 93%→~30%, robust to a retrained multi-location + attacker, `MEASURED`) confirm standard-permitted beamforming-surface + obfuscation works; DP-Givens quantization (`SYNTHETIC`) offers a formal ε knob. +- **Compliance precedent.** BeamDancer (IEEE TWC 2024, `MEASURED`) argues + native-beamforming obfuscation is 802.11-compliant while jamming/geofencing + are not — cite it as precedent. (Its ">96% PDR" figure was **refuted** in + verification; do not cite it.) +- **Security honesty.** Obfuscation shields have published counter-attacks + ("Defeating CSI obfuscation", SnoopFi), so VEIL's own shield security is + `CLAIMED`, not proven-secure, until it withstands learned de-obfuscation. +- **Governance gap.** No claim on 802.11bf-2025 privacy provisions survived + verification; that pillar remains an open question, not an asserted fact. + +The derived, prioritized improvement backlog lives in the SOTA-update file (§4). + +## 3. What this explicitly is NOT + +- **Not a radio driver.** No RF frontend, no transmit path, no + `wifi-densepose-hardware` coupling. VEIL cannot emit and cannot jam. +- **Not a defense against the associated AP.** That party holds the session key by + construction (threat class A3); protecting against a malicious AP is BFLD's + detection/privacy-class problem (ADR-118/141), not this shield's. +- **Not a full motion-obfuscation claim.** A fixed per-session rotation does not + hide coarse within-session motion; identity *re-ID* is the guaranteed target, + motion is partial/future work. +- **Not a real-hardware performance claim.** All defense numbers are SYNTHETIC/L0 + until a two-node capture with a boot/runtime-log witness exists (CLAUDE.md + hardware rule; roadmap P5). +- **Not RF denial or camera-grade anything.** + +## 4. Simplifications (honesty boundary) + +- The two-subspace split is an abstraction; on real radios comm and identity + information are only *approximately* separable, so the real throughput cost of + fully hiding identity may exceed the model's ~2%. DySPAN-2026's MEASURED curve + bounds it as *small* at fine resolution, not zero. +- The attacker is nearest-centroid. The collapse argument is classifier-independent + (it is about the marginalized signal), but P2/P5 must confirm a learned attacker + also collapses. +- The crate's PRNG is SplitMix64 — deterministic and WASM-safe but **not + cryptographic**; a deployment derives the rotation key from the negotiated link + secret, never from this PRNG. + +## 5. Consequences + +- RuView gains the *countermeasure* half of its RF-privacy story: BFLD detects + leakage, VEIL acts on it — a defensible, standards-anchored, gap-filling + position (see `docs/research/privacy-shield/06-market-and-buyers.md`). +- The compliance audit gives regulators/auditors a machine-checkable "not jamming" + artifact that composes with ADR-141 attestation. +- Future integration (BFLD `identity_risk` → `SensingDetector`, ADR-280 governed + actuation, firmware feedback shaping, two-node hardware measurement) is staged in + the research bundle roadmap and deliberately deferred so the model validates in + isolation first. + +## 6. Validation + +```bash +cargo test -p wifi-densepose-privshield --no-default-features +cargo build -p wifi-densepose-privshield --target wasm32-unknown-unknown +cargo clippy -p wifi-densepose-privshield --all-targets +``` diff --git a/docs/adr/ADR-289-wifi-densepose-privshield-harness-via-metaharness.md b/docs/adr/ADR-289-wifi-densepose-privshield-harness-via-metaharness.md new file mode 100644 index 00000000..ad8e9c92 --- /dev/null +++ b/docs/adr/ADR-289-wifi-densepose-privshield-harness-via-metaharness.md @@ -0,0 +1,95 @@ +# ADR-289: `wifi-densepose-privshield-harness` — a MetaHarness for the VEIL privacy shield + +| Field | Value | +|-------|-------| +| **Status** | Proposed — implemented (P1) | +| **Date** | 2026-08-09 | +| **Parent** | ADR-288 (`wifi-densepose-privshield` / VEIL, the crate this harness assists development on) | +| **Relates to** | ADR-286 (`wifi-densepose-sar-harness`, the per-crate harness scaffold this one mirrors), ADR-285 (`harness/homecore/`, the WASM-first `@metaharness/kernel` pattern), ADR-182 (`harness/ruview/`, the first minted harness), ADR-282 (L0–L5 evidence ladder) | +| **Location** | `harness/wifi-densepose-privshield/` | + +## 0. PROOF discipline + +Every claim below about what is "real" versus "illustrative"/"SYNTHETIC" is +checked by a test in this harness's own suite (router + flywheel + install-smoke ++ guidance). The dependency-free `guidance` surface is covered by +`__tests__/guidance.test.ts`, which runs even before `npm install`. Nothing here +asserts a MEASURED defense result — the harness surfaces the VEIL crate's +SYNTHETIC/L0 numbers with that label intact. + +## 1. Context + +`wifi-densepose-privshield` (ADR-288) is the VEIL privacy shield — a new, +narrowly-scoped crate. Following the pattern ADR-286 set for +`wifi-densepose-sar`, it gets a dedicated per-crate MetaHarness rather than a +bespoke setup: the `vertical:coding` scaffold (architect/implementer/reviewer/ +test-writer, `doctor`) with `@metaharness/router`, `@metaharness/flywheel`, and +Darwin Mode wired in, plus a VEIL-specific, dependency-free `guidance` surface. + +## 2. Decision + +Land the harness at `harness/wifi-densepose-privshield/`, mirroring +`wifi-densepose-sar-harness`, with two deliberate improvements: + +1. **Dynamic dependency imports.** `bin/cli.js` imports the `@metaharness/*` + packages *inside* the commands that need them, not at module top. So + `guidance`, `--help`, and the guidance test run with **zero dependencies + installed** — useful for offline/air-gapped review and for this repo's CI + before `npm install`. Only `init`/`doctor`/`route`/`flywheel` touch the + kernel/host/router/flywheel packages. +2. **A VEIL `guidance` command.** A self-contained, source-cited, read-only + capability map (topics: `overview`, `threat`, `countermeasure`, + `compliance`, `optimization`, `experiment`), each entry carrying a summary, + repo-relative source citations, focused validation commands, and explicit + limitations — the `ruview_guidance` shape, specialized to VEIL. It labels all + defense evidence `SYNTHETIC/L0` and states plainly that guidance is + navigation, not authority. + +The standard three self-improvement/cost pieces are wired as real npm +dependencies (not stubs): + +- **`@metaharness/darwin`** (devDependency) — `npm run evolve` / `evolve:dry` + mutates the harness's own operating config, keeping only measurable gains. +- **`@metaharness/router`** — `src/router.ts` wires a real cost-optimal `Router` + (`qualityBar: 0.8`, k=1) over two model tiers, with four VEIL-shaped task axes + (threatModeling / complianceReview / optimizerTuning / docWriting). Labelled + examples are illustrative seed data (honesty note in-file). +- **`@metaharness/flywheel`** — `src/flywheel.ts` wires the real + `runFlywheelGenerations` promotion loop (propose → evaluate → gate → promote, + Ed25519-signed, independently replayable) with a SYNTHETIC proposer/evaluator + (`dataSource: 'SYNTHETIC'`, no model call), over VEIL policy levers + (`complianceReview`, `threatTriage`). + +## 3. What this explicitly is NOT + +- **Not a VEIL runtime.** The harness does not run a radio, emit RF, or jam. It + assists *development* on the crate; it cannot execute the shield on hardware. +- **Not evolving the crate.** Darwin/Flywheel mutate the harness's own policy + (agent prompts, review-checklist depth), not VEIL's Rust code. The crate's + actual hyper-optimization (ADR-288 §opt) was done directly, in the crate. +- **Not a live routing/promotion system.** The router's examples are seed data; + the flywheel's proposer/evaluator are deterministic stand-ins — both honestly + labelled in-source and in `CLAUDE.md`. +- **Not a replacement for the crate's gates.** The authoritative check for a + VEIL change remains `cargo test -p wifi-densepose-privshield`. +- **Not a re-labeller.** The harness must never present VEIL's SYNTHETIC results + as MEASURED, and never scaffold interference-based ("jamming") defenses — both + are hard rules in the harness `CLAUDE.md`. + +## 4. Consequences + +- The harness ships `guidance`/`doctor`/`init`/`route`/`flywheel`; `guidance` + and `--help` work offline (validated here via `node bin/cli.js`), the rest + after `npm install` + `npm run build` (CI). +- `.harness/manifest.json` + `manifest.sha256` are generated with real per-file + hashes at creation (unlike ADR-286's scaffold, whose manifest was historical). +- Scoped to its own name: its plugin, permissions, and (future) MCP surface only + read/assist on `wifi-densepose-privshield`. No risk to other harnesses/crates. + +## 5. Validation + +```bash +cd harness/wifi-densepose-privshield +node bin/cli.js guidance --topic overview # dependency-free +npm ci && npm run build && npm test # full suite (CI; needs registry access) +``` diff --git a/docs/adr/ADR-290-veil-e2e-hardware-implementation-program.md b/docs/adr/ADR-290-veil-e2e-hardware-implementation-program.md new file mode 100644 index 00000000..6ea20a9e --- /dev/null +++ b/docs/adr/ADR-290-veil-e2e-hardware-implementation-program.md @@ -0,0 +1,94 @@ +# ADR-290: VEIL end-to-end hardware implementation program (multi-provider firmware) + +| Field | Value | +|-------|-------| +| **Status** | Proposed — P4 scaffolding (build-only); portable core validated on host | +| **Date** | 2026-08-09 | +| **Parent** | ADR-288 (VEIL shield), ADR-289 (harness), ADR-282 (L0–L5 evidence ladder) | +| **Location** | `firmware/privshield/` | +| **Relates to** | `firmware/esp32-csi-node/` (the CSI sensor/attacker node), ADR-280 (governed actuation), ADR-141 (attestation) | + +## 0. PROOF discipline + +The **only** artifact validated here is the portable C core +(`firmware/privshield/core/`): a host test (`make test`) checks energy +conservation, reversibility, wrong-key failure, and — pinned — that its +SplitMix64 key schedule is **byte-identical to the Rust crate's** PRNG. That is +`build`/host-level evidence, not silicon. Every per-provider adapter is a +**build-only scaffold** with `TODO(hw)` markers: `SYNTHETIC / L0`, no captured +log, no `MEASURED` claim. Nothing in this ADR asserts VEIL works on real +hardware; it asserts a *plan and a shared core* to get there (P5). + +## 1. Context + +ADR-288 shipped VEIL as a deterministic, no-radio Rust model, and the 2025–2026 +SOTA sweep (ADR-288 §sota) confirmed the mechanism's family is real and +standard-permitted. The open question left was **"does this run on real WiFi +hardware, and on which?"** — including the user asks: *can OpenWRT / open WiFi +software implement it, and can ESP32 help scramble signals?* Answering requires +committing to the platform reality rather than assuming a uniform "firmware" +target. + +## 2. Decision + +Stand up `firmware/privshield/` as a **multi-provider E2E program** around one +shared, validated core: + +1. **A portable C shield core** (`core/veil_shield.{h,c}`) — the keyed + Givens-rotation obfuscation, `no_std`-friendly C99 (no malloc/libc I/O), with + a SplitMix64 key schedule matching the Rust crate so on-air behavior is + identical everywhere and every adapter links the *same* math. Host-tested. +2. **Per-provider adapters**, each built and graded by a hardware research + agent, honest about what its stack can actually touch: + - **`openwifi/`** (open PHY/MAC on SDR/FPGA) — the highest-capability path and + the one that can host the **keyed-reversible** design end-to-end + (protector + AP-side compensation). Carries the **P5 measurement protocol** + (`MEASUREMENT.md`) that yields the first `MEASURED` result with a witness. + - **`openwrt/`** (Linux `mac80211`, mt76/ath9k…) — the commodity path. + Sounding-cadence randomization, MU-group and stream-mapping control are + feasible from the driver/hostapd; the per-packet unitary on the LTF spatial + mapping is firmware-deep on most parts. Partial. + - **`nexmon/`** (Broadcom/Cypress C firmware patches) — the commodity + C-firmware route; the read path is proven (Wi-BFI/nexmon_csi), the transmit + report-shaping path is research-grade/partial. + - **`esp32/`** (ESP-IDF) — **not** a feedback protector (the beamforming path + is a closed blob): ESP32 shapes CSI *read*, not transmitted feedback. Its + legitimate roles are a **sensing detector** (trigger the AP-side shield) and + an **RIS controller** (drive an external reconfigurable surface to scramble + the sensing direction — the honest way ESP32 "helps scramble", via an + external surface, not its own PHY). +3. **Compliance stance carried into hardware:** every control shapes the node's + own standards-conformant emission and preserves energy; the ESP32 + decoy/cover-traffic idea is documented as *legally sensitive / not + recommended* precisely because it edges toward the interference line. + +Per-provider feasibility grades live in each subdir README and the top-level +feasibility matrix; they are the answer to the "which hardware" question. + +## 3. What this explicitly is NOT + +- **Not validated firmware.** No adapter has run on silicon; there is no witness. + The scaffolds compile-*shaped*, not compile-*guaranteed* on their toolchains + (which are absent in this environment). +- **Not a claim that ESP32 can shield beamforming feedback** — it cannot; it is a + detector/RIS-controller only. +- **Not jamming, on any platform.** Compliant waveform shaping only. +- **Not a MEASURED result.** That is P5, gated on a captured log. + +## 4. Consequences + +- One validated core, four honest provider scaffolds, and a concrete P5 + measurement plan — a real path from model to silicon, with the effort/blocker + reality made explicit per platform. +- The shared core keeps every future hardware result consistent with the crate + and with each other. +- Scope stays inside `firmware/privshield/`; no other crate/firmware is touched + (the existing `esp32-csi-node` remains the sensor/attacker node). + +## 5. Validation + +```bash +cd firmware/privshield/core && make test # host: energy/reversibility/PRNG parity +# per-provider builds require their toolchains (ESP-IDF, OpenWRT SDK, Nexmon, +# Vivado) and real hardware — see each subdir's BUILD/INTEGRATION notes. +``` diff --git a/docs/adr/ADR-288-public-benchmark-evaluation-harness.md b/docs/adr/ADR-291-public-benchmark-evaluation-harness.md similarity index 98% rename from docs/adr/ADR-288-public-benchmark-evaluation-harness.md rename to docs/adr/ADR-291-public-benchmark-evaluation-harness.md index 2d9dcfc5..da3312a7 100644 --- a/docs/adr/ADR-288-public-benchmark-evaluation-harness.md +++ b/docs/adr/ADR-291-public-benchmark-evaluation-harness.md @@ -1,4 +1,4 @@ -# ADR-288: Public-benchmark evaluation harness — Widar3.0 ingest, standard split protocols, leakage guards +# ADR-291: Public-benchmark evaluation harness — Widar3.0 ingest, standard split protocols, leakage guards - **Status**: Accepted — initial implementation (this PR) - **Date**: 2026-08-10 diff --git a/docs/adr/ADR-289-wideband-80211ax-csi-ingest.md b/docs/adr/ADR-292-wideband-80211ax-csi-ingest.md similarity index 98% rename from docs/adr/ADR-289-wideband-80211ax-csi-ingest.md rename to docs/adr/ADR-292-wideband-80211ax-csi-ingest.md index 9eaa5024..3e5fd60b 100644 --- a/docs/adr/ADR-289-wideband-80211ax-csi-ingest.md +++ b/docs/adr/ADR-292-wideband-80211ax-csi-ingest.md @@ -1,4 +1,4 @@ -# ADR-289: Wideband 802.11ax CSI ingest — FeitCSI/AX210 adapter and subcarrier-agnostic plumbing +# ADR-292: Wideband 802.11ax CSI ingest — FeitCSI/AX210 adapter and subcarrier-agnostic plumbing - **Status**: Accepted — initial implementation (this PR) - **Date**: 2026-08-10 diff --git a/docs/adr/ADR-290-vitals-ground-truth-rig.md b/docs/adr/ADR-293-vitals-ground-truth-rig.md similarity index 97% rename from docs/adr/ADR-290-vitals-ground-truth-rig.md rename to docs/adr/ADR-293-vitals-ground-truth-rig.md index 428c5f6b..c513d8fe 100644 --- a/docs/adr/ADR-290-vitals-ground-truth-rig.md +++ b/docs/adr/ADR-293-vitals-ground-truth-rig.md @@ -1,4 +1,4 @@ -# ADR-290: Vitals ground-truth rig — reference ingest, time alignment, and agreement metrics +# ADR-293: Vitals ground-truth rig — reference ingest, time alignment, and agreement metrics - **Status**: Accepted — initial implementation (this PR) - **Date**: 2026-08-10 @@ -69,7 +69,7 @@ Add a `groundtruth` module to `v2/crates/wifi-densepose-vitals`: reference device, non-zero paired samples, minimum coverage, and a reproducer command string; otherwise the report grades as `Claimed` (real data, no reference) or `Synthetic` (generated input). This mirrors - ADR-288's enforcement-in-types approach and the CLAUDE.md tagging rule. + ADR-291's enforcement-in-types approach and the CLAUDE.md tagging rule. ## Consequences diff --git a/docs/adr/ADR-291-wifi-veil-integration.md b/docs/adr/ADR-294-wifi-veil-integration.md similarity index 98% rename from docs/adr/ADR-291-wifi-veil-integration.md rename to docs/adr/ADR-294-wifi-veil-integration.md index b580ae31..5e4c7691 100644 --- a/docs/adr/ADR-291-wifi-veil-integration.md +++ b/docs/adr/ADR-294-wifi-veil-integration.md @@ -1,4 +1,4 @@ -# ADR-291: WiFi Veil integration — emission-shaping countermeasure as an advisory BFLD dependency +# ADR-294: WiFi Veil integration — emission-shaping countermeasure as an advisory BFLD dependency - **Status**: Accepted — initial implementation (this PR) - **Date**: 2026-08-10 diff --git a/docs/adr/ADR-292-source-provenance-state-machine.md b/docs/adr/ADR-295-source-provenance-state-machine.md similarity index 97% rename from docs/adr/ADR-292-source-provenance-state-machine.md rename to docs/adr/ADR-295-source-provenance-state-machine.md index ef4acf5f..c101d9e6 100644 --- a/docs/adr/ADR-292-source-provenance-state-machine.md +++ b/docs/adr/ADR-295-source-provenance-state-machine.md @@ -1,4 +1,4 @@ -# ADR-292: Source provenance state machine — synthetic can never present as live +# ADR-295: Source provenance state machine — synthetic can never present as live - **Status**: Accepted — initial implementation (this PR) - **Date**: 2026-08-11 diff --git a/docs/adr/ADR-293-sensor-data-plane-bind-hardening.md b/docs/adr/ADR-296-sensor-data-plane-bind-hardening.md similarity index 97% rename from docs/adr/ADR-293-sensor-data-plane-bind-hardening.md rename to docs/adr/ADR-296-sensor-data-plane-bind-hardening.md index a29db97f..d6c02792 100644 --- a/docs/adr/ADR-293-sensor-data-plane-bind-hardening.md +++ b/docs/adr/ADR-296-sensor-data-plane-bind-hardening.md @@ -1,4 +1,4 @@ -# ADR-293: Sensor data-plane hardening — UDP bind control and source allowlist (step one) +# ADR-296: Sensor data-plane hardening — UDP bind control and source allowlist (step one) - **Status**: Accepted — initial implementation (this PR) - **Date**: 2026-08-11 diff --git a/docs/adr/ADR-294-multi-node-semantic-correctness.md b/docs/adr/ADR-297-multi-node-semantic-correctness.md similarity index 95% rename from docs/adr/ADR-294-multi-node-semantic-correctness.md rename to docs/adr/ADR-297-multi-node-semantic-correctness.md index d7914580..f4e0b8dd 100644 --- a/docs/adr/ADR-294-multi-node-semantic-correctness.md +++ b/docs/adr/ADR-297-multi-node-semantic-correctness.md @@ -1,4 +1,4 @@ -# ADR-294: Multi-node semantic correctness — per-node inference, node-keyed rate limiting, stale state +# ADR-297: Multi-node semantic correctness — per-node inference, node-keyed rate limiting, stale state - **Status**: Accepted — initial implementation (this PR) - **Date**: 2026-08-11 @@ -46,7 +46,7 @@ mechanism RuView uses to reduce blind spots and room dependence: - Schema change to `NodeInfo`/the MQTT contract; existing single-node deployments keep working (one node = one inference). Consumers reading the old aggregate-only shape need the migration accessor. -- Aligns with ADR-292 (freshness) and the review's call for one canonical +- Aligns with ADR-295 (freshness) and the review's call for one canonical `NodeInference`/`RoomInference` contract. ## Validation diff --git a/docs/adr/ADR-295-model-release-sanity-gates.md b/docs/adr/ADR-298-model-release-sanity-gates.md similarity index 96% rename from docs/adr/ADR-295-model-release-sanity-gates.md rename to docs/adr/ADR-298-model-release-sanity-gates.md index 86bbd6fe..6af231e1 100644 --- a/docs/adr/ADR-295-model-release-sanity-gates.md +++ b/docs/adr/ADR-298-model-release-sanity-gates.md @@ -1,4 +1,4 @@ -# ADR-295: Model release sanity gates — block degenerate and mislabeled model artifacts +# ADR-298: Model release sanity gates — block degenerate and mislabeled model artifacts - **Status**: Accepted — initial implementation (this PR) - **Date**: 2026-08-11 @@ -31,7 +31,7 @@ for any classifier artifact proposed for release, fails on: - **Degenerate class balance** — predicted-positive rate at/above a ceiling (e.g. > 99%) on a balanced probe set. - **Missing/blank baseline** — a report without a paired mean-pose/majority - baseline (ties into ADR-288 `EvaluationReport`). + baseline (ties into ADR-291 `EvaluationReport`). - **Metric-name provenance** — a metric may not be surfaced under a task name that does not match its computed kind (temporal-triplet ≠ presence); enforced by making the metric carry its kind and the label derive from it. diff --git a/docs/adr/ADR-296-csi-data-incident-repo-controls.md b/docs/adr/ADR-299-csi-data-incident-repo-controls.md similarity index 97% rename from docs/adr/ADR-296-csi-data-incident-repo-controls.md rename to docs/adr/ADR-299-csi-data-incident-repo-controls.md index 72c563ff..edb677da 100644 --- a/docs/adr/ADR-296-csi-data-incident-repo-controls.md +++ b/docs/adr/ADR-299-csi-data-incident-repo-controls.md @@ -1,4 +1,4 @@ -# ADR-296: Repository CSI data-incident controls — ignore rules and a pre-commit/CI policy check +# ADR-299: Repository CSI data-incident controls — ignore rules and a pre-commit/CI policy check - **Status**: Accepted — controls implemented; tree remediation gated on owner sign-off - **Date**: 2026-08-11 diff --git a/docs/adr/ADR-297-perception-substrate-program.md b/docs/adr/ADR-300-perception-substrate-program.md similarity index 72% rename from docs/adr/ADR-297-perception-substrate-program.md rename to docs/adr/ADR-300-perception-substrate-program.md index c8ec0fc7..11b4d087 100644 --- a/docs/adr/ADR-297-perception-substrate-program.md +++ b/docs/adr/ADR-300-perception-substrate-program.md @@ -1,4 +1,4 @@ -# ADR-297: RuView perception substrate — a phased program for the calibration, evidence, trust, and deployment layer +# ADR-300: RuView perception substrate — a phased program for the calibration, evidence, trust, and deployment layer - **Status**: Accepted — program framing; child ADRs carry their own status - **Date**: 2026-08-11 @@ -25,8 +25,8 @@ Several of these primitives already have foundations in the tree and should be - RuField provenance/signature types (ADR-260/262/277/279) and BFLD attestation (ADR-141). - `worldgraph` crate; `wifi-densepose-mat/tracking` (tracker, fingerprint). -- The in-flight ADR-292 (provenance state machine), ADR-293 (authenticated - data plane, step one), ADR-295 (model sanity gates) — the first bricks. +- The in-flight ADR-295 (provenance state machine), ADR-296 (authenticated + data plane, step one), ADR-298 (model sanity gates) — the first bricks. ## What RuView is optimizing for @@ -51,20 +51,20 @@ Every child ADR and implementation is bound by these: confident class, or silently hold a stale value. 2. **Capability certificates bind cryptographically.** Hardware, environment, model, calibration, metrics, expiry, and evidence level are bound under one - signature (ADR-315/ADR-302). An unsigned or partially-bound certificate is + signature (ADR-318/ADR-305). An unsigned or partially-bound certificate is not a certificate. 3. **One canonical semantics downstream.** Every surface (MQTT, REST, WebSocket, RuField, Matter, agents, UI) consumes the same Observation → Inference → - GovernedEvent types (ADR-303). No transport- or UI-specific reinterpretation. + GovernedEvent types (ADR-306). No transport- or UI-specific reinterpretation. 4. **Benchmarks expose worst-domain performance and confidence intervals.** - Pooled accuracy is never sufficient for promotion (ADR-314). + Pooled accuracy is never sufficient for promotion (ADR-317). ### Certificate conditionality (the staleness guard) The central architectural risk is **certificate staleness**: a room can remain syntactically calibrated while its RF distribution has drifted enough to invalidate the certificate. Therefore a capability certificate is **conditional -on a continuously evaluated domain signature** (ADR-299), not a one-time stamp. +on a continuously evaluated domain signature** (ADR-302), not a one-time stamp. Crossing the OOD threshold automatically degrades state and triggers recalibration rather than silently continuing: @@ -72,8 +72,8 @@ recalibration rather than silently continuing: VALID → DEGRADED → UNKNOWN (auto-degrade on domain drift; triggers recalibration) ``` -This binds ADR-298 (calibration), ADR-299 (OOD), ADR-315 (certificate), and -ADR-318 (policy): a degraded/unknown domain must invalidate the affected +This binds ADR-301 (calibration), ADR-302 (OOD), ADR-318 (certificate), and +ADR-321 (policy): a degraded/unknown domain must invalidate the affected capability *before* a false confident inference reaches an actuator. ### Commercial framing — three primitives, not one product @@ -82,7 +82,7 @@ capability *before* a false confident inference reaches an actuator. - **RuView Certify** — establishes what a deployment can legitimately claim (calibration + evidence + capability certificate + policy). - **RuView Trust / Fleet** — keeps that claim valid across hardware, firmware, - models, and environmental drift (ADR-313). + models, and environmental drift (ADR-316). Certify and Trust are the parts that are hard to commoditize; presence detection alone is not. @@ -90,48 +90,48 @@ detection alone is not. ## Decision Adopt a **21-primitive phased program**. Each primitive gets a child ADR -(ADR-298…ADR-318) that owns its detailed decision, status, and validation. +(ADR-301…ADR-321) that owns its detailed decision, status, and validation. This ADR owns the framing, the dependency order, and the phase assignment. ### Primitive → ADR map | # | Primitive | ADR | Phase | |---|---|---|---| -| 1 | Automatic domain calibration | ADR-298 | 1 | -| 2 | Out-of-distribution detection | ADR-299 | 1 | -| 3 | Ground-truth synchronization | ADR-300 | 2 | -| 4 | Evidence engine | ADR-301 | 1 | -| 5 | Authenticated sensor identity | ADR-302 | 1 | -| 6 | Canonical spatial ontology | ADR-303 | 1 | -| 7 | Persistent identity & tracking | ADR-304 | 2 | -| 8 | Sensor placement optimizer | ADR-305 | 3 | -| 9 | Active sensing | ADR-306 | 3 | -| 10 | 802.11bf-native architecture | ADR-307 | 2 | -| 11 | Real sensor fusion | ADR-308 | 2 | -| 12 | Long-term spatial memory | ADR-309 | 3 | -| 13 | Counterfactual inference | ADR-310 | 3 | -| 14 | Information-gain scheduler | ADR-311 | 3 | -| 15 | Digital RF twin | ADR-312 | 3 | -| 16 | Fleet control plane | ADR-313 | 2 | -| 17 | Real benchmark service (multi-domain scorecard) | ADR-314 | 1 | -| 18 | Capability certificates | ADR-315 | 1 | -| 19 | Witness chain | ADR-316 | 1 | -| 20 | RuView sensor HAL | ADR-317 | 2 | -| 21 | Decision policy — action authorization | ADR-318 | 1 | +| 1 | Automatic domain calibration | ADR-301 | 1 | +| 2 | Out-of-distribution detection | ADR-302 | 1 | +| 3 | Ground-truth synchronization | ADR-303 | 2 | +| 4 | Evidence engine | ADR-304 | 1 | +| 5 | Authenticated sensor identity | ADR-305 | 1 | +| 6 | Canonical spatial ontology | ADR-306 | 1 | +| 7 | Persistent identity & tracking | ADR-307 | 2 | +| 8 | Sensor placement optimizer | ADR-308 | 3 | +| 9 | Active sensing | ADR-309 | 3 | +| 10 | 802.11bf-native architecture | ADR-310 | 2 | +| 11 | Real sensor fusion | ADR-311 | 2 | +| 12 | Long-term spatial memory | ADR-312 | 3 | +| 13 | Counterfactual inference | ADR-313 | 3 | +| 14 | Information-gain scheduler | ADR-314 | 3 | +| 15 | Digital RF twin | ADR-315 | 3 | +| 16 | Fleet control plane | ADR-316 | 2 | +| 17 | Real benchmark service (multi-domain scorecard) | ADR-317 | 1 | +| 18 | Capability certificates | ADR-318 | 1 | +| 19 | Witness chain | ADR-319 | 1 | +| 20 | RuView sensor HAL | ADR-320 | 2 | +| 21 | Decision policy — action authorization | ADR-321 | 1 | ### Dependency order (why phase, not score, drives sequencing) ``` - ADR-303 spatial ontology ──┐ - ADR-302 auth identity ─────┼──► ADR-298 calibration cert ──► ADR-299 OOD gating + ADR-306 spatial ontology ──┐ + ADR-305 auth identity ─────┼──► ADR-301 calibration cert ──► ADR-302 OOD gating │ │ │ - └──► ADR-316 witness chain │ (VALID→DEGRADED→UNKNOWN) + └──► ADR-319 witness chain │ (VALID→DEGRADED→UNKNOWN) │ ▼ - ADR-301 evidence engine ──► ADR-315 capability certificate + ADR-304 evidence engine ──► ADR-318 capability certificate │ │ (conditional on domain signature) │ ▼ - │ ADR-318 decision policy ──► governed action - └──► ADR-314 benchmark scorecard (per-PR gate) + │ ADR-321 decision policy ──► governed action + └──► ADR-317 benchmark scorecard (per-PR gate) ``` - **Phase 1 (the certificate spine, built now):** foundational roots 303, 302, @@ -152,20 +152,20 @@ validation plan) and are not implemented by the phase-1 swarm. ### Acceptance test A — onboarding (from the strategic assessment) > Connect a new sensor type in an unseen room. Within 30 minutes RuView should -> identify the hardware (HAL, ADR-317), calibrate the environment (ADR-298), -> quantify whether it can reliably sense the requested phenomenon (ADR-299), -> generate a signed capability certificate (ADR-315), expose governed spatial -> events (ADR-303), and return UNKNOWN whenever evidence falls outside that -> certificate (ADR-299). +> identify the hardware (HAL, ADR-320), calibrate the environment (ADR-301), +> quantify whether it can reliably sense the requested phenomenon (ADR-302), +> generate a signed capability certificate (ADR-318), expose governed spatial +> events (ADR-306), and return UNKNOWN whenever evidence falls outside that +> certificate (ADR-302). ### Acceptance test B — drift invalidation (the staleness guard) > Deliberately change the room after certification — move furniture, change the > AP channel, or substitute hardware. RuView should detect distribution drift -> (ADR-299), invalidate the affected capability (ADR-315) **before** a false -> confident inference reaches an actuator (ADR-318 denies with the specific +> (ADR-302), invalidate the affected capability (ADR-318) **before** a false +> confident inference reaches an actuator (ADR-321 denies with the specific > failed condition), emit UNKNOWN, preserve the complete witness chain -> (ADR-316), and explain exactly which certificate condition failed. +> (ADR-319), and explain exactly which certificate condition failed. Test B is the load-bearing one: it proves the substrate fails safe, not just that it perceives well. Phase 1 makes every clause except HAL testable in @@ -176,7 +176,7 @@ closes the "identify the hardware" clause. - One coherent substrate replaces overlapping ad-hoc schemas; every surface (MQTT, REST, WebSocket, RuField, Matter, agents) eventually consumes the - ADR-303 ontology and the ADR-315 certificate. + ADR-306 ontology and the ADR-318 certificate. - Headline applications (pose/vitals/pointcloud models) are explicitly **not** the investment focus during this program, per the strategic direction. - Later ADRs may be revised as the spine lands; that is expected for a phased @@ -186,4 +186,4 @@ closes the "identify the hardware" clause. - Each child ADR defines its own tests. The program-level exit is the acceptance test above, run end-to-end once phase 1 lands, and encoded as an - AetherArena scenario (ADR-314). + AetherArena scenario (ADR-317). diff --git a/docs/adr/ADR-298-automatic-domain-calibration.md b/docs/adr/ADR-301-automatic-domain-calibration.md similarity index 89% rename from docs/adr/ADR-298-automatic-domain-calibration.md rename to docs/adr/ADR-301-automatic-domain-calibration.md index be7b386a..4d48606c 100644 --- a/docs/adr/ADR-298-automatic-domain-calibration.md +++ b/docs/adr/ADR-301-automatic-domain-calibration.md @@ -1,19 +1,19 @@ -# ADR-298: Automatic domain calibration — signed, versioned, invalidatable room fingerprint +# ADR-301: Automatic domain calibration — signed, versioned, invalidatable room fingerprint -- **Status**: Accepted — initial implementation planned (ADR-297 phase 1) +- **Status**: Accepted — initial implementation planned (ADR-300 phase 1) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: calibration, provenance, drift, evidence, honesty, substrate ## Context -This ADR is primitive 1 of the perception-substrate program (ADR-297) and the -first brick of that program's "certificate spine" (ADR-297 phase 1). It depends -on the canonical spatial ontology (ADR-303) to name *which space* it -characterizes, on authenticated sensor identity (ADR-302) to bind a fingerprint -to *which signed device* produced it, and on the witness chain (ADR-316) to +This ADR is primitive 1 of the perception-substrate program (ADR-300) and the +first brick of that program's "certificate spine" (ADR-300 phase 1). It depends +on the canonical spatial ontology (ADR-306) to name *which space* it +characterizes, on authenticated sensor identity (ADR-305) to bind a fingerprint +to *which signed device* produced it, and on the witness chain (ADR-319) to anchor the resulting artifact. Its output is consumed directly by -out-of-distribution detection (ADR-299). +out-of-distribution detection (ADR-302). WiFi sensing is only reproducible inside the environment it was tuned for. Multipath, furniture geometry, transceiver placement, and AP channel all shape @@ -43,7 +43,7 @@ than a soft `STALE` flag buried in the runtime. 1. **Keep calibration internal to the runtime (status quo).** Rejected: the room characterization exists only as in-process state; it cannot be signed, - shipped, compared across time, or presented as evidence to ADR-299/ADR-315. + shipped, compared across time, or presented as evidence to ADR-302/ADR-318. 2. **Build a new calibration crate.** Rejected: `wifi-densepose-calibration` already owns enrollment, the specialist bank, geometry embedding, and the baseline-drift concept. A parallel crate would fork the room model. @@ -68,7 +68,7 @@ phase and a `certificate` artifact module. The target UX is: the room's CSI distribution (subcarrier amplitude/phase moments, multipath structure, occupancy-band energy), plus the `geometry_embedding` when a geometry record is present. The fingerprint is the distance-comparable object - ADR-299 measures against; its schema is versioned. + ADR-302 measures against; its schema is versioned. ### 2. Empty / occupied baseline pair @@ -82,17 +82,17 @@ phase and a `certificate` artifact module. The target UX is: ### 3. `CalibrationCertificate` artifact - A serializable `CalibrationCertificate` binding: the `RoomFingerprint`; a - space identifier from the ADR-303 ontology; the signing sensor identity from - ADR-302; `captured_at_unix_s`; a monotonic `version`; a schema version; the + space identifier from the ADR-306 ontology; the signing sensor identity from + ADR-305; `captured_at_unix_s`; a monotonic `version`; a schema version; the calibration `tier`; and an `EvidenceLevel` (L0–L5, ADR-282) — an automatic characterization on real captured CSI is at most L1/L2 and is labelled as such, never L3+. - The certificate is **signed** using RuField provenance/signature types - (ADR-260/262/277/279) and anchored in the witness chain (ADR-316). Signature + (ADR-260/262/277/279) and anchored in the witness chain (ADR-319). Signature and witness anchoring are mandatory: an unsigned certificate is not a valid certificate. - Two certificates for the same space are **comparable**: `distance(a, b)` - returns a bounded fingerprint distance, which is the primitive ADR-299 uses + returns a bounded fingerprint distance, which is the primitive ADR-302 uses to gate KNOWN → DEGRADED → UNKNOWN. ### 4. Invalidation and continuous drift compensation @@ -101,7 +101,7 @@ phase and a `certificate` artifact module. The target UX is: fingerprint distance against live traffic exceeds a threshold, when the AP channel or transceiver geometry changes, when the signing device identity changes, or on age expiry. Invalidation is an explicit state transition that - emits a witness record (ADR-316), not a silent `STALE` flag. + emits a witness record (ADR-319), not a silent `STALE` flag. - Continuous drift compensation runs as a bounded online update of the fingerprint within a **compatibility envelope**: small drift is absorbed and logged; drift beyond the envelope invalidates the certificate and forces @@ -121,14 +121,14 @@ phase and a `certificate` artifact module. The target UX is: ## Consequences - Room characterization becomes a portable, signed, versioned artifact that - ADR-299 (OOD), ADR-315 (capability certificates), and ADR-314 (benchmark) + ADR-302 (OOD), ADR-318 (capability certificates), and ADR-317 (benchmark) can consume without re-deriving room state. - The automatic observe-only path lowers deployment friction (no mandatory enrollment ritual) but yields a weaker evidence level than guided enrollment; the certificate states which path produced it so consumers can weight it. - Explicit invalidation means RuView will sometimes refuse to sense a changed room until re-characterization. That refusal is the intended honest behavior, - surfaced by ADR-299, not a regression. + surfaced by ADR-302, not a regression. - The existing enrollment/bank/runtime path is preserved; `autocal` is an additional entry point that produces the same `RoomFingerprint` object the guided path can also emit. @@ -142,7 +142,7 @@ phase and a `certificate` artifact module. The target UX is: transitions (channel change, geometry change, age, drift-envelope breach) each emit the expected witness record; constructor rejects synthetic→measured mislabeling. -- Cross-ADR: an ADR-299 test consumes a certificate and asserts the gating +- Cross-ADR: an ADR-302 test consumes a certificate and asserts the gating state transitions on a drifted fingerprint. - Real-silicon characterization (ESP32 capture over a real 10-minute window) remains a follow-up requiring hardware evidence per CLAUDE.md; a successful diff --git a/docs/adr/ADR-299-out-of-distribution-detection.md b/docs/adr/ADR-302-out-of-distribution-detection.md similarity index 87% rename from docs/adr/ADR-299-out-of-distribution-detection.md rename to docs/adr/ADR-302-out-of-distribution-detection.md index afbd4651..88726158 100644 --- a/docs/adr/ADR-299-out-of-distribution-detection.md +++ b/docs/adr/ADR-302-out-of-distribution-detection.md @@ -1,33 +1,33 @@ -# ADR-299: Out-of-distribution detection — KNOWN / DEGRADED / UNKNOWN gating +# ADR-302: Out-of-distribution detection — KNOWN / DEGRADED / UNKNOWN gating -- **Status**: Accepted — initial implementation planned (ADR-297 phase 1) +- **Status**: Accepted — initial implementation planned (ADR-300 phase 1) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: ood, calibration, uncertainty, quality, evidence, honesty, substrate ## Context -This ADR is primitive 2 of the perception-substrate program (ADR-297) and part +This ADR is primitive 2 of the perception-substrate program (ADR-300) and part of the phase-1 certificate spine. It sits directly downstream of automatic -domain calibration (ADR-298): the `CalibrationCertificate` and its +domain calibration (ADR-301): the `CalibrationCertificate` and its `RoomFingerprint` are the reference distribution this ADR measures against. It reuses fusion-layer quality scoring (ADR-137) as one of its inputs and feeds -its state into the evidence engine (ADR-301) and capability certificates -(ADR-315). +its state into the evidence engine (ADR-304) and capability certificates +(ADR-318). The central unsolved problem of WiFi sensing is cross-domain generalization: a model trained (or calibrated) in one room degrades unpredictably in another, or in the same room after furniture moves, the AP changes channel, or the radio hardware is swapped. A model that keeps returning confident classifications under these conditions is the single most misleading failure mode in the field, -and it is the failure the strategic assessment (ADR-297) named explicitly. +and it is the failure the strategic assessment (ADR-300) named explicitly. Confidence alone is insufficient: a softmax head is perfectly capable of being confidently wrong on out-of-distribution input. RuView must be able to say "I do not recognize this situation" instead of guessing. Today RuView has partial signals but no unified gate: -- ADR-298 produces a comparable `RoomFingerprint` and a `distance()` metric. +- ADR-301 produces a comparable `RoomFingerprint` and a `distance()` metric. - ADR-137 `QualityScore` carries fusion coherence, evidence references, and contradiction flags per fused frame. - Model heads emit confidence/uncertainty, but nothing combines domain @@ -44,7 +44,7 @@ Today RuView has partial signals but no unified gate: duplicates logic, cannot be audited uniformly, and does not compose with the calibration certificate or the evidence engine. 3. **A shared OOD gate that every inference passes through, fusing four signals - against the ADR-298 certificate.** Chosen. + against the ADR-301 certificate.** Chosen. ## Decision @@ -56,14 +56,14 @@ path) — that attaches a `DomainState` to **every** inference. Each inference carries four measured quantities: -1. **Domain distance** — fingerprint distance (ADR-298 `distance()`) between +1. **Domain distance** — fingerprint distance (ADR-301 `distance()`) between live traffic and the active `CalibrationCertificate`, split into the empty-baseline and occupied-baseline components so geometry drift and occupancy-statistics drift are distinguishable. 2. **Signal quality** — reuse the ADR-137 quality scoring signals (fusion coherence, contradiction flags) plus per-frame SNR/validity. 3. **Calibration compatibility** — is a valid, non-invalidated certificate - present for this space (ADR-303) and this signed device (ADR-302)? An + present for this space (ADR-306) and this signed device (ADR-305)? An expired, invalidated, or device-mismatched certificate is itself a compatibility failure. 4. **Uncertainty** — the model head's own predictive uncertainty. @@ -90,11 +90,11 @@ cause are all reported — never a bare label. ### 3. Certificate-bound, honest by construction -- The gate is meaningless without a certificate: with no valid ADR-298 +- The gate is meaningless without a certificate: with no valid ADR-301 certificate for the current space/device, the default state is UNKNOWN, not KNOWN. Absence of evidence is treated as absence of capability. - The `DomainState` and its inputs are emitted to the evidence engine - (ADR-301) as part of every inference record, and are an input to the ADR-315 + (ADR-304) as part of every inference record, and are an input to the ADR-318 capability certificate (a model's capability is bounded by the domain it can hold KNOWN in). - No accuracy number is claimed here; the ADR delivers the gating machinery. @@ -111,10 +111,10 @@ cause are all reported — never a bare label. is the product working: it is the difference between honest RF perception and confidently-wrong output. - Every task head that opts into the substrate must route through the gate; - heads that bypass it cannot claim a KNOWN state or earn an ADR-315 + heads that bypass it cannot claim a KNOWN state or earn an ADR-318 certificate. - The gate couples model serving to the presence of a live calibration - certificate, making ADR-298 a hard dependency of confident inference — the + certificate, making ADR-301 a hard dependency of confident inference — the intended coupling. ## Validation @@ -125,9 +125,9 @@ cause are all reported — never a bare label. device mismatch, and invalidated/absent certificate each → UNKNOWN; hysteresis prevents flapping under injected noise; missing certificate defaults to UNKNOWN. -- Cross-ADR: consumes an ADR-298 certificate and asserts a drifted fingerprint +- Cross-ADR: consumes an ADR-301 certificate and asserts a drifted fingerprint drives the expected transition; asserts the `DomainState` is present on every - emitted inference record consumed by ADR-301. + emitted inference record consumed by ADR-304. - No confident classification is emitted in the UNKNOWN state in any test — enforced as an assertion, not a convention. - Real-silicon OOD behavior (moving furniture / changing AP channel on a live diff --git a/docs/adr/ADR-300-ground-truth-synchronization.md b/docs/adr/ADR-303-ground-truth-synchronization.md similarity index 85% rename from docs/adr/ADR-300-ground-truth-synchronization.md rename to docs/adr/ADR-303-ground-truth-synchronization.md index fd6f4cb7..0b0928cd 100644 --- a/docs/adr/ADR-300-ground-truth-synchronization.md +++ b/docs/adr/ADR-303-ground-truth-synchronization.md @@ -1,21 +1,21 @@ -# ADR-300: Ground-truth synchronization — reference sensors as a formal validation plane +# ADR-303: Ground-truth synchronization — reference sensors as a formal validation plane -- **Status**: Accepted — initial implementation (ADR-297 phase 2) +- **Status**: Accepted — initial implementation (ADR-300 phase 2) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: ground-truth, validation, fusion, evidence, benchmark, honesty, substrate ## Context -This ADR is primitive 3 of the perception-substrate program (ADR-297), authored +This ADR is primitive 3 of the perception-substrate program (ADR-300), authored as **Proposed** in phase 2: it is design intent and a validation plan, not implemented by the phase-1 swarm. It sits on top of the phase-1 certificate -spine and feeds the evidence engine (ADR-301) and the real benchmark service -(ADR-314). It generalizes the vitals ground-truth rig (ADR-290) from a single +spine and feeds the evidence engine (ADR-304) and the real benchmark service +(ADR-317). It generalizes the vitals ground-truth rig (ADR-293) from a single measurand to a modality-agnostic plane. RuView's evidence discipline (CLAUDE.md; ADR-282 ladder) requires MEASURED -accuracy claims to be backed by an independent reference. ADR-290 built exactly +accuracy claims to be backed by an independent reference. ADR-293 built exactly this for vitals: reference-series ingest, time alignment (cross-correlation lag + optional clock-drift fit), and agreement statistics (MAE/RMSE/bias/ Bland–Altman/within-tolerance), with an `EvidenceGrade` that is only @@ -39,7 +39,7 @@ inputs. would also violate the ADR-282 layering (RuView is probabilistic exteroception, never ground truth) and the honesty rule against presenting fused-with-camera output as WiFi sensing. -2. **One-off rigs per measurand (extend ADR-290 ad hoc each time).** Rejected: +2. **One-off rigs per measurand (extend ADR-293 ad hoc each time).** Rejected: duplicates alignment/agreement code per phenomenon and never yields a shared validation surface for the benchmark. 3. **A first-class, modality-agnostic `GroundTruth` API that is strictly a @@ -52,38 +52,38 @@ compares RF inference against independent observation and never feeds it. ### 1. Modality-agnostic reference ingest -- A `ReferenceObservation` generalizing ADR-290's `ReferenceSeries`: a +- A `ReferenceObservation` generalizing ADR-293's `ReferenceSeries`: a timestamped, typed observation of a `Phenomenon` (presence, count, localization, pose keypoints, posture, activity, heart rate, breathing rate) from a `ReferenceModality` (camera, mmWave, pressure, wearable, pulse oximeter, microphone, manual label), with device/source metadata and the measurement principle recorded. - Untrusted reference files are validated at the boundary (row-numbered - rejections, non-monotonic timestamps are errors), reusing ADR-290's ingest + rejections, non-monotonic timestamps are errors), reusing ADR-293's ingest discipline. Camera/mmWave references arrive as exported label/keypoint streams, not live model feeds. ### 2. Synchronization -- Generalize ADR-290's time alignment (bounded-lag normalized cross-correlation +- Generalize ADR-293's time alignment (bounded-lag normalized cross-correlation + optional linear clock-drift fit) to arbitrary measurands on a common resampled grid, with no interpolation across gaps beyond a configurable limit. Alignment parameters are always reported, never silently applied. - Spatial synchronization where relevant: reference observations are expressed - in the ADR-303 spatial ontology so an RF localization/pose result and a + in the ADR-306 spatial ontology so an RF localization/pose result and a camera/mmWave observation are compared in one coordinate frame. ### 3. Agreement as validation, not fusion - A modality-appropriate `AgreementReport` per phenomenon: continuous - measurands reuse ADR-290's MAE/RMSE/bias/Bland–Altman/within-tolerance; + measurands reuse ADR-293's MAE/RMSE/bias/Bland–Altman/within-tolerance; categorical/detection phenomena (presence, activity) report confusion-matrix metrics; spatial phenomena report localization error percentiles and pose PCK **with the mandatory mean-pose baseline and leakage-free split** - (CLAUDE.md; ADR-288). + (CLAUDE.md; ADR-291). - Session scope is mandatory metadata (subject count, motion state, LOS/NLOS/ through-wall, distance band) — a report without scope cannot be constructed, - as in ADR-290. + as in ADR-293. ### 4. Evidence and isolation guarantees @@ -92,8 +92,8 @@ compares RF inference against independent observation and never feeds it. boundary) prevents a reference observation from becoming an estimator input. - Reports carry an `EvidenceLevel` (ADR-282) and an `EvidenceGrade` constructible as `Measured` only with a real reference, paired samples, - coverage, and a reproducer (ADR-290 rule). Reports feed the ADR-301 evidence - engine and are the substrate ADR-314 scores against. + coverage, and a reproducer (ADR-293 rule). Reports feed the ADR-304 evidence + engine and are the substrate ADR-317 scores against. ## Consequences @@ -106,7 +106,7 @@ compares RF inference against independent observation and never feeds it. session); acceptable because it is a validation activity, not a runtime requirement, and it is what turns CLAIMED into MEASURED. - Because this is Proposed (phase 2), the API shape may be revised once the - phase-1 spine (ADR-298/299/301/303) lands and the benchmark (ADR-314) + phase-1 spine (ADR-301/299/301/303) lands and the benchmark (ADR-317) exercises it. ## Validation @@ -117,8 +117,8 @@ compares RF inference against independent observation and never feeds it. mean-pose baseline and rejects leaky splits; evidence-grade constructibility; the isolation check fails a build that wires a reference into the inference path. -- Cross-ADR: an ADR-314 benchmark scenario consumes `GroundTruth` reports as - its scored reference; ADR-301 ingests the agreement reports as evidence +- Cross-ADR: an ADR-317 benchmark scenario consumes `GroundTruth` reports as + its scored reference; ADR-304 ingests the agreement reports as evidence records. - Real-session validation (RF capture synchronized with a real camera/mmWave/ pressure/wearable reference) is the phase-2 exit and requires hardware diff --git a/docs/adr/ADR-301-evidence-engine.md b/docs/adr/ADR-304-evidence-engine.md similarity index 77% rename from docs/adr/ADR-301-evidence-engine.md rename to docs/adr/ADR-304-evidence-engine.md index 2a801c1b..3fd9ba2f 100644 --- a/docs/adr/ADR-301-evidence-engine.md +++ b/docs/adr/ADR-304-evidence-engine.md @@ -1,21 +1,21 @@ -# ADR-301: Evidence engine — MLflow for physical sensing +# ADR-304: Evidence engine — MLflow for physical sensing -- **Status**: Accepted — initial implementation planned (ADR-297 phase 1) +- **Status**: Accepted — initial implementation planned (ADR-300 phase 1) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: evidence, provenance, ledger, accuracy, drift, benchmark, honesty, substrate ## Context -This ADR is primitive 4 of the perception-substrate program (ADR-297) and a +This ADR is primitive 4 of the perception-substrate program (ADR-300) and a central pillar of the phase-1 certificate spine. It consumes the domain state -from out-of-distribution detection (ADR-299) and the calibration age from the -calibration certificate (ADR-298), it is the store that capability certificates -(ADR-315) are minted from, and it is the accuracy source the real benchmark -service (ADR-314) reads. In phase 2 it ingests agreement reports from the -ground-truth plane (ADR-300). +from out-of-distribution detection (ADR-302) and the calibration age from the +calibration certificate (ADR-301), it is the store that capability certificates +(ADR-318) are minted from, and it is the accuracy source the real benchmark +service (ADR-317) reads. In phase 2 it ingests agreement reports from the +ground-truth plane (ADR-303). -The strategic assessment (ADR-297) judged this primitive **more commercially +The strategic assessment (ADR-300) judged this primitive **more commercially important than another pose architecture**: what unblocks OEM and integrator conversations is not a higher headline number but a defensible, auditable record of how a model actually performs, per room, per device, per subject, over time. @@ -32,7 +32,7 @@ that unifies them per deployment context: witness-anchored ledger of scored results, the structural template here. - `frame::EvidenceLevel` L0–L5 (ADR-282) — the mandatory evidence tag every record carries. -- ADR-299 `DomainState`, ADR-137 `QualityScore`, ADR-298 certificate version +- ADR-302 `DomainState`, ADR-137 `QualityScore`, ADR-301 certificate version and age — the per-inference signals to accumulate. ## Options considered @@ -54,24 +54,24 @@ accuracy ledger that every model automatically writes to. ### 1. The evidence record -- An `EvidenceRecord` keyed by context — space id (ADR-303), signed device id - (ADR-302), and subject id where consented and available — carrying: model - version; calibration certificate version and **age** (ADR-298); the ADR-299 +- An `EvidenceRecord` keyed by context — space id (ADR-306), signed device id + (ADR-305), and subject id where consented and available — carrying: model + version; calibration certificate version and **age** (ADR-301); the ADR-302 `DomainState` (KNOWN/DEGRADED/UNKNOWN) and its four inputs; the ADR-137 quality signals; predictive uncertainty; and, when a reference is present - (ADR-300), the agreement result (accuracy, false-positive rate). Each record + (ADR-303), the agreement result (accuracy, false-positive rate). Each record carries exactly one `EvidenceLevel` (L0–L5, ADR-282). - Records are **append-only** and signed with RuField signature types - (ADR-260/262/277/279); the ledger is anchored in the witness chain (ADR-316), + (ADR-260/262/277/279); the ledger is anchored in the witness chain (ADR-319), following the AetherArena witness-ledger pattern (ADR-149). No record is ever mutated in place — a correction is a new record. ### 2. Per-context accuracy accounting - The engine maintains, per `(room, device, subject)` context: measured - accuracy (only where an ADR-300 reference backs it — otherwise the record is + accuracy (only where an ADR-303 reference backs it — otherwise the record is CLAIMED/SYNTHETIC, never MEASURED), false-positive rate, drift trajectory - (fingerprint distance over time from ADR-298), the fraction of inferences in + (fingerprint distance over time from ADR-301), the fraction of inferences in each domain state, calibration age distribution, and model-version history. - Aggregation is a pure function over the append-only log at a queried time — the ledger is the source of truth; summaries are derived, never authoritative @@ -81,11 +81,11 @@ accuracy ledger that every model automatically writes to. - The engine cannot upgrade an evidence level; a level is set by the record's provenance at write time (synthetic input → L0/`Synthetic`; no reference → - CLAIMED; reference + reproducer → MEASURED), reusing the ADR-282/ADR-288/ - ADR-290 constructor discipline. A benchmark or certificate reading the ledger + CLAIMED; reference + reproducer → MEASURED), reusing the ADR-282/ADR-291/ + ADR-293 constructor discipline. A benchmark or certificate reading the ledger gets the honest level, not an optimistic rollup. - No benchmark numbers are invented by this ADR; it delivers the ledger and the - accounting. Empty contexts report "no evidence," which downstream (ADR-315) + accounting. Empty contexts report "no evidence," which downstream (ADR-318) must treat as no capability. ## Consequences @@ -93,8 +93,8 @@ accuracy ledger that every model automatically writes to. - RuView gains a single auditable answer to "how well does this model actually work, here, on this device, for this subject, and how fresh is the calibration?" — the artifact OEM/integrator diligence actually asks for. -- ADR-315 capability certificates become derivable (a certificate is a signed - attestation over a slice of the ledger) and ADR-314 gains a real accuracy +- ADR-318 capability certificates become derivable (a certificate is a signed + attestation over a slice of the ledger) and ADR-317 gains a real accuracy source per PR instead of self-reported numbers. - The append-only, signed design has storage and key-management cost; bounded by per-context retention policy and by reusing the existing RuField/witness @@ -109,9 +109,9 @@ accuracy ledger that every model automatically writes to. against fixtures; evidence-level is set by provenance and cannot be upgraded; signature round-trip and tamper rejection; witness anchoring; empty-context queries return "no evidence" not a fabricated number. -- Cross-ADR: ingests ADR-299 `DomainState` and (phase 2) ADR-300 agreement - reports; an ADR-315 test mints a certificate from a ledger slice and an - ADR-314 test reads accuracy from the ledger. +- Cross-ADR: ingests ADR-302 `DomainState` and (phase 2) ADR-303 agreement + reports; an ADR-318 test mints a certificate from a ledger slice and an + ADR-317 test reads accuracy from the ledger. - Real-deployment evidence (a populated ledger from live ESP32 captures with - ADR-300 references) is the maturity milestone and requires hardware evidence + ADR-303 references) is the maturity milestone and requires hardware evidence per CLAUDE.md; a synthetic ledger is L0 by construction. diff --git a/docs/adr/ADR-302-authenticated-sensor-identity.md b/docs/adr/ADR-305-authenticated-sensor-identity.md similarity index 82% rename from docs/adr/ADR-302-authenticated-sensor-identity.md rename to docs/adr/ADR-305-authenticated-sensor-identity.md index d46565b7..7fec3e46 100644 --- a/docs/adr/ADR-302-authenticated-sensor-identity.md +++ b/docs/adr/ADR-305-authenticated-sensor-identity.md @@ -1,24 +1,24 @@ -# ADR-302: Authenticated sensor identity — RF chain of custody +# ADR-305: Authenticated sensor identity — RF chain of custody -- **Status**: Accepted — initial implementation planned (ADR-297 phase 1) +- **Status**: Accepted — initial implementation planned (ADR-300 phase 1) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: security, identity, provenance, sensor-ingest, attestation, phase-1 ## Context -This ADR is a child of **ADR-297** (perception substrate program) and owns -primitive #5, *authenticated sensor identity*. In the ADR-297 dependency DAG it -is a spine root that, together with **ADR-303** (canonical spatial ontology), -feeds **ADR-298** (calibration certificate) and **ADR-316** (witness chain). +This ADR is a child of **ADR-300** (perception substrate program) and owns +primitive #5, *authenticated sensor identity*. In the ADR-300 dependency DAG it +is a spine root that, together with **ADR-306** (canonical spatial ontology), +feeds **ADR-301** (calibration certificate) and **ADR-319** (witness chain). RuView's inference outputs are only as trustworthy as the measurements that produced them, yet today a measurement's origin is essentially assertional. The -UDP data plane accepts frames from any reachable host: **ADR-293** shipped step +UDP data plane accepts frames from any reachable host: **ADR-296** shipped step one — a loopback-default bind (`--udp-bind`) and an optional source IP/CIDR allowlist — and explicitly deferred to a follow-up ADR "per-device provisioned keys, MAC/AEAD, device identifiers, monotonic sequence numbers, -freshness window, and replay rejection." **This ADR is that step two.** ADR-293 +freshness window, and replay rejection." **This ADR is that step two.** ADR-296 correctly documented that an IP allowlist does not stop LAN spoofing; a cryptographic device identity is what closes that gap. @@ -30,7 +30,7 @@ Foundations already exist in the tree and must be reused rather than rebuilt: - `wifi-densepose-bfld` provides `CapabilityAttestation` and `PrivacyAttestationProof` (BFLD attestation, ADR-141) — the device-side attestation surface. -- **ADR-292** defines the source-provenance state machine and freshness +- **ADR-295** defines the source-provenance state machine and freshness (`SpatialStateFreshness`); a monotonic sequence and freshness window slot into that machine rather than duplicating it. @@ -42,7 +42,7 @@ hardware, and FFI boundary; default to least authority"). ## Options considered -1. **Stop at ADR-293 (bind + IP allowlist).** Rejected: ADR-293 itself names +1. **Stop at ADR-296 (bind + IP allowlist).** Rejected: ADR-296 itself names this insufficient on a trusted LAN; any on-subnet host can still spoof a device. 2. **TLS/DTLS transport authentication only.** Rejected: authenticates the @@ -67,7 +67,7 @@ server, built from existing RuField/BFLD types. `firmware/esp32-csi-node` key-handling notes. - The enrollment record binds `DeviceId → public key → capabilities` (via `CapabilityAttestation`, ADR-141), so a device can only assert - measurements for phenomena it is attested to sense. This is what **ADR-315** + measurements for phenomena it is attested to sense. This is what **ADR-318** (capability certificate) later consumes. ### 2. Signed measurement envelope @@ -78,7 +78,7 @@ server, built from existing RuField/BFLD types. detectable without embedding the whole payload twice. - Verification uses `Signature`/`SignatureVerifyError` from `wifi-densepose-rufield`. A frame that fails signature verification is - dropped and counted, exactly as ADR-293 drops disallowed sources — an `Err` + dropped and counted, exactly as ADR-296 drops disallowed sources — an `Err` at the boundary, never a warning that proceeds. ### 3. Monotonic sequence + freshness (replay defense) @@ -87,44 +87,44 @@ server, built from existing RuField/BFLD types. server tracks the last accepted sequence per `DeviceId`; a non-increasing sequence is rejected as a replay. - A freshness window bounds `timestamp` against the server clock skew budget; - stale frames are rejected. This reuses ADR-292's `SpatialStateFreshness` + stale frames are rejected. This reuses ADR-295's `SpatialStateFreshness` rather than inventing a parallel notion of staleness, and composes with - ADR-294's stale-node handling. + ADR-297's stale-node handling. ### 4. Chain of custody into the event - On successful verification the frame's `FrameProvenance` records the verified - `DeviceId`, sequence, and timestamp. Calibration (ADR-298) and inference - annotate their transforms, and the emitted spatial event (ADR-303 ontology) + `DeviceId`, sequence, and timestamp. Calibration (ADR-301) and inference + annotate their transforms, and the emitted spatial event (ADR-306 ontology) carries a signed provenance lineage. `ProvenanceClass` still enforces the synthetic/measured invariant from ADR-282/ADR-279 (invariant 6): a measured chain of custody can never be aliased to synthetic and vice-versa. -- This end-to-end signed lineage is the substrate the **ADR-316** witness chain - serializes and the **ADR-315** capability certificate points at as evidence. +- This end-to-end signed lineage is the substrate the **ADR-319** witness chain + serializes and the **ADR-318** capability certificate points at as evidence. ### Compatibility - The envelope is **opt-in per deployment** and negotiated at enrollment. An un-enrolled single-node desktop deployment keeps working unauthenticated - behind ADR-293's loopback default; a routable, multi-node, or fleet - deployment (ADR-313) requires enrolled identities. The startup security log - (ADR-293) is extended to state whether frame authentication is active. + behind ADR-296's loopback default; a routable, multi-node, or fleet + deployment (ADR-316) requires enrolled identities. The startup security log + (ADR-296) is extended to state whether frame authentication is active. ## Consequences -- LAN spoofing and replay — the residual risks ADR-293 named plainly — are +- LAN spoofing and replay — the residual risks ADR-296 named plainly — are closed for enrolled deployments. The measurement, not merely the channel, is authenticated, so the guarantee survives store-and-forward into the witness chain. - Enrollment/key-management is now an operational responsibility (provisioning, rotation, revocation). This is documented as a deployment step; key rotation and revocation lists are specified here but their fleet distribution is - owned by ADR-313. + owned by ADR-316. - Signature verification adds per-frame CPU cost at ingest; bounded and measured in validation below. It is a deliberate cost for a verifiable chain of custody. - A schema addition to the frame contract; un-enrolled deployments are - unaffected, and the migration accessor mirrors ADR-294's approach. + unaffected, and the migration accessor mirrors ADR-297's approach. - **No spoof-resistance claim is MEASURED until validated on real silicon** (CLAUDE.md hardware rule): a passing unit/integration suite demonstrates the logic, not the fielded device path. @@ -137,7 +137,7 @@ server, built from existing RuField/BFLD types. window timestamp rejected; un-enrolled `DeviceId` rejected; measured/synthetic provenance aliasing rejected (ADR-279 invariant 6). - Integration test: a captured/synthesized multi-frame stream produces a - verifiable `device → … → signed event` lineage that ADR-316 can serialize and + verifiable `device → … → signed event` lineage that ADR-319 can serialize and re-verify offline. - Benchmark (`cargo bench`): per-frame verification cost, to bound ingest overhead. diff --git a/docs/adr/ADR-303-canonical-spatial-ontology.md b/docs/adr/ADR-306-canonical-spatial-ontology.md similarity index 83% rename from docs/adr/ADR-303-canonical-spatial-ontology.md rename to docs/adr/ADR-306-canonical-spatial-ontology.md index d7ccb1a0..4ef71d6b 100644 --- a/docs/adr/ADR-303-canonical-spatial-ontology.md +++ b/docs/adr/ADR-306-canonical-spatial-ontology.md @@ -1,28 +1,28 @@ -# ADR-303: Canonical spatial ontology — one Site→…→Event model for every surface +# ADR-306: Canonical spatial ontology — one Site→…→Event model for every surface -- **Status**: Accepted — initial implementation planned (ADR-297 phase 1) +- **Status**: Accepted — initial implementation planned (ADR-300 phase 1) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: ontology, worldgraph, schema, mqtt, matter, rufield, phase-1 ## Context -This ADR is a child of **ADR-297** and owns primitive #6, *canonical spatial -ontology*. In the ADR-297 DAG it is a spine root alongside **ADR-302** +This ADR is a child of **ADR-300** and owns primitive #6, *canonical spatial +ontology*. In the ADR-300 DAG it is a spine root alongside **ADR-305** (authenticated identity) and feeds every downstream primitive that must speak -about *where* and *what*: **ADR-298** (calibration), **ADR-304** (tracking, -consumes `Track`/`Person`), **ADR-316** (witness chain), and every external -surface named in the ADR-297 consequences (MQTT, REST, WebSocket, RuField, +about *where* and *what*: **ADR-301** (calibration), **ADR-307** (tracking, +consumes `Track`/`Person`), **ADR-319** (witness chain), and every external +surface named in the ADR-300 consequences (MQTT, REST, WebSocket, RuField, Matter, agents). RuView currently expresses "where something is" in several overlapping, per-surface schemas: the MQTT/Home-Assistant mapper has its own node/room -shapes (**ADR-294** just introduced `NodeInference`/`RoomInference` to +shapes (**ADR-297** just introduced `NodeInference`/`RoomInference` to disambiguate node vs. room state); the `worldgraph` crate models a spatial graph; RuField carries `SemanticProvenance`; Matter/HomeKit has its own area model. The same physical fact — "a person is in the kitchen" — is re-encoded differently on each surface, and the review called for "one canonical -`NodeInference`/`RoomInference` contract" (ADR-294 consequences). Without a +`NodeInference`/`RoomInference` contract" (ADR-297 consequences). Without a single semantic model, every new surface multiplies the translation matrix and each translation is a place where provenance and evidence level (ADR-282) can be silently dropped. @@ -75,14 +75,14 @@ Site ▸ Building ▸ Floor ▸ Space ▸ Zone elements. Containment reuses the existing `LocatedIn`/`AdjacentTo` edge vocabulary; a new `PartOf` edge expresses the pure hierarchy (Zone `PartOf` Space `PartOf` Floor …). -- `Sensor` is the entity **ADR-302** authenticates (`DeviceId` as its stable - identity) and **ADR-317** (HAL, phase 2) describes the hardware of. `Person`, +- `Sensor` is the entity **ADR-305** authenticates (`DeviceId` as its stable + identity) and **ADR-320** (HAL, phase 2) describes the hardware of. `Person`, `Object`, `Observation`, `Track`, and `Event` are first-class nodes. `Observes`/`LocatedIn` edges already carry quality and dwell timestamps. - `Track` and `Person` are defined **here** as the ontology contract that - **ADR-304** (persistent tracking) produces and updates. `Observation` is what - an authenticated frame (ADR-302) becomes after calibration (ADR-298), and - `Event` is the governed output that ADR-315 certifies and ADR-316 witnesses. + **ADR-307** (persistent tracking) produces and updates. `Observation` is what + an authenticated frame (ADR-305) becomes after calibration (ADR-301), and + `Event` is the governed output that ADR-318 certifies and ADR-319 witnesses. ### 2. Canonical serialization @@ -90,8 +90,8 @@ Site ▸ Building ▸ Floor ▸ Space ▸ Zone one wire/at-rest representation. Every surface — MQTT/Home-Assistant, REST, WebSocket, RuField observations, Matter/HomeKit, agent queries — is a **projection** of this model, not an independent schema. `NodeInference` and - `RoomInference` (ADR-294) become projections of `Sensor→Observes` and the - `Space`-level fused inference respectively, so ADR-294's node/room separation + `RoomInference` (ADR-297) become projections of `Sensor→Observes` and the + `Space`-level fused inference respectively, so ADR-297's node/room separation is preserved by construction rather than re-encoded per surface. - Every node and edge carries `SemanticProvenance` and exactly one `EvidenceLevel` (L0–L5, ADR-282 policy): the evidence ladder travels *with* @@ -102,7 +102,7 @@ Site ▸ Building ▸ Floor ▸ Space ▸ Zone - Each existing per-surface schema gets a documented, tested bidirectional mapping to/from the canonical model, plus a migration accessor for consumers - reading the old shape (mirroring ADR-294's migration accessor). Surfaces are + reading the old shape (mirroring ADR-297's migration accessor). Surfaces are cut over one at a time; a surface is "canonical" once its projection is the only encoder it uses. Until cutover, the mapping layer is authoritative and round-trip-tested so no fact is lost in translation. @@ -120,8 +120,8 @@ Site ▸ Building ▸ Floor ▸ Space ▸ Zone serialization and per-surface migration accessors. Single-node deployments keep working (one `Sensor`, one `Space`). - The ontology is a *representation*, not an inference engine: it says nothing - about *how* a `Track` or `Event` is produced — that is owned by ADR-304, - ADR-298, ADR-299, and the model layer. This ADR does not itself make any + about *how* a `Track` or `Event` is produced — that is owned by ADR-307, + ADR-301, ADR-302, and the model layer. This ADR does not itself make any accuracy claim to grade. - Extending `worldgraph` grows one crate's surface rather than forking a second world model; the geo/worldmodel sub-crates continue to build on the same node @@ -135,7 +135,7 @@ Site ▸ Building ▸ Floor ▸ Space ▸ Zone and edge type; every node/edge carries exactly one `EvidenceLevel`. - Migration tests: each per-surface schema maps to the canonical model and back with no loss of provenance or evidence level; `NodeInference`/`RoomInference` - (ADR-294) project and re-project identically. + (ADR-297) project and re-project identically. - Contract test: a single canonical `Event` renders correctly through the MQTT, REST, and WebSocket projections from one source of truth. - No accuracy numbers are claimed; this ADR delivers the shared representation diff --git a/docs/adr/ADR-304-persistent-identity-tracking.md b/docs/adr/ADR-307-persistent-identity-tracking.md similarity index 88% rename from docs/adr/ADR-304-persistent-identity-tracking.md rename to docs/adr/ADR-307-persistent-identity-tracking.md index 0f97d731..8aa5c75d 100644 --- a/docs/adr/ADR-304-persistent-identity-tracking.md +++ b/docs/adr/ADR-307-persistent-identity-tracking.md @@ -1,18 +1,18 @@ -# ADR-304: Persistent identity & tracking — privacy-preserving probabilistic tracks +# ADR-307: Persistent identity & tracking — privacy-preserving probabilistic tracks -- **Status**: Accepted — initial implementation (ADR-297 phase 2) +- **Status**: Accepted — initial implementation (ADR-300 phase 2) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: tracking, identity, privacy, fusion, worldgraph, phase-2 ## Context -This ADR is a child of **ADR-297** and owns primitive #7, *persistent identity -& tracking*. In the ADR-297 DAG it is a phase-2 primitive sitting on the -phase-1 spine: it **consumes the ADR-303 ontology** (producing and updating the -`Track` and `Person` node types defined there), it relies on **ADR-302** +This ADR is a child of **ADR-300** and owns primitive #7, *persistent identity +& tracking*. In the ADR-300 DAG it is a phase-2 primitive sitting on the +phase-1 spine: it **consumes the ADR-306 ontology** (producing and updating the +`Track` and `Person` node types defined there), it relies on **ADR-305** authenticated identity so that the observations it associates have a verified -origin, and its outputs are governed `Event`s that ADR-315/ADR-316 can certify +origin, and its outputs are governed `Event`s that ADR-318/ADR-319 can certify and witness. The product need is to reason about *persistent entities* — "person_7 entered @@ -58,11 +58,11 @@ that survives track loss and hand-off between spaces, and (c) an explicit ## Decision Extend `wifi-densepose-mat/tracking` into a **cross-domain persistent track -layer** that produces ADR-303 `Track`/`Person` nodes. +layer** that produces ADR-306 `Track`/`Person` nodes. ### 1. Persistent probabilistic entity -- A persistent entity is a pseudonymous `Person` node (ADR-303) with a stable +- A persistent entity is a pseudonymous `Person` node (ADR-306) with a stable synthetic id (e.g. `person_7`) backed by the existing `TrackId`/UUID. It aggregates one or more `SurvivorTracker` tracks over time and space and holds a **probabilistic** continuity belief — association is never asserted as @@ -76,14 +76,14 @@ layer** that produces ADR-303 `Track`/`Person` nodes. ### 2. Cross-radio / cross-modality / cross-room continuity -- Association operates over the ADR-303 ontology graph: `Observes` edges from +- Association operates over the ADR-306 ontology graph: `Observes` edges from multiple `Sensor`s and `AdjacentTo`/`Doorway` topology constrain plausible hand-offs (a person can only move between adjacent spaces). The existing `mahalanobis_distance_sq` gating extends to a fused observation across modalities rather than a single node's detections. - Fusion here is track-level association; the underlying multi-modality fusion (radar/mmWave per ADR-063, multistatic per ADR-029, and real sensor fusion - per ADR-308) supplies the observations. This ADR depends on those for the raw + per ADR-311) supplies the observations. This ADR depends on those for the raw cross-modality evidence and does not re-implement sensor fusion. ### 3. Privacy boundary (by construction) @@ -113,10 +113,10 @@ layer** that produces ADR-303 `Track`/`Person` nodes. wrong civil-identity join is not. - Extends an existing tracker rather than forking one; single-room single-radio deployments keep the current behavior (one entity = one track). -- Cross-modality quality depends on ADR-308/ADR-063/ADR-029 landing; until then +- Cross-modality quality depends on ADR-311/ADR-063/ADR-029 landing; until then continuity is WiFi-primary and its limits are stated, not hidden. -- Being phase 2, this ADR is design intent; it will be revised as the ADR-303 - ontology and ADR-302 identity spine finalize. +- Being phase 2, this ADR is design intent; it will be revised as the ADR-306 + ontology and ADR-305 identity spine finalize. ## Validation @@ -129,7 +129,7 @@ layer** that produces ADR-303 `Track`/`Person` nodes. with per-hand-off confidence, and a deliberately ambiguous crossing produces two pseudonyms rather than a false join. - Evidence discipline: any tracking-continuity accuracy is reported only with - the ADR-288 leakage-free protocol and an evidence tag; no number is asserted + the ADR-291 leakage-free protocol and an evidence tag; no number is asserted here. - Privacy review: confirm no persisted long-term biometric template and no civil-identity join path, as an explicit checklist item before any pilot. diff --git a/docs/adr/ADR-305-sensor-placement-optimizer.md b/docs/adr/ADR-308-sensor-placement-optimizer.md similarity index 79% rename from docs/adr/ADR-305-sensor-placement-optimizer.md rename to docs/adr/ADR-308-sensor-placement-optimizer.md index 6aeebdfb..2062bbed 100644 --- a/docs/adr/ADR-305-sensor-placement-optimizer.md +++ b/docs/adr/ADR-308-sensor-placement-optimizer.md @@ -1,19 +1,19 @@ -# ADR-305: Sensor placement optimizer — floorplan + inventory → recommended positions +# ADR-308: Sensor placement optimizer — floorplan + inventory → recommended positions -- **Status**: Accepted — initial implementation (ADR-297 phase 3) +- **Status**: Accepted — initial implementation (ADR-300 phase 3) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: placement, planning, rf-twin, coverage, worldgraph, phase-3 ## Context -This ADR is a child of **ADR-297** and owns primitive #8, *sensor placement -optimizer*. In the ADR-297 DAG it is a phase-3, research-forward primitive that -sits on top of the fused world state and is tightly coupled to **ADR-312** +This ADR is a child of **ADR-300** and owns primitive #8, *sensor placement +optimizer*. In the ADR-300 DAG it is a phase-3, research-forward primitive that +sits on top of the fused world state and is tightly coupled to **ADR-315** (digital RF twin): the twin provides the propagation simulation this optimizer -plans against. It reads the **ADR-303** canonical ontology for the physical -scene and, after install, compares its predictions against ADR-299 observability -and the ADR-315 capability certificate. +plans against. It reads the **ADR-306** canonical ontology for the physical +scene and, after install, compares its predictions against ADR-302 observability +and the ADR-318 capability certificate. The problem it solves is the single most common cause of a bad RuView deployment: sensors placed by guesswork. Whether a room can be reliably sensed @@ -30,11 +30,11 @@ Relevant existing assets to build on rather than duplicate: - The `worldgraph` crate models the physical scene the optimizer plans over: `Room`/`Space` with `bounds_enu`, `Wall { rf_attenuation_db }` (drywall ≈ 3 dB, brick ≈ 12 dB), `Doorway`, and `Zone` — enough geometry and coarse RF - attenuation to seed a coverage model, plus `Sensor` nodes (ADR-303) for + attenuation to seed a coverage model, plus `Sensor` nodes (ADR-306) for candidate positions. -- **ADR-312** (RF twin, phase 3) is the propagation/multipath simulator; this +- **ADR-315** (RF twin, phase 3) is the propagation/multipath simulator; this optimizer is a *consumer* of the twin, not a second simulator. -- **ADR-299** (OOD/observability) and **ADR-315** (capability certificate) +- **ADR-302** (OOD/observability) and **ADR-318** (capability certificate) define what "reliably sense the requested phenomenon" means, so the optimizer can optimize against the same observability metric the runtime later gates on. - **ADR-029** (multistatic) and **ADR-063** (mmWave fusion) inform which link @@ -49,36 +49,36 @@ Relevant existing assets to build on rather than duplicate: 2. **Full electromagnetic solver per site.** Rejected for the default path: too heavy for an installer workflow and overkill relative to the coarse `rf_attenuation_db` scene RuView actually has; reserved as an optional - high-fidelity backend inside ADR-312. -3. **A coverage optimizer that consumes the ADR-312 RF twin over the ADR-303 + high-fidelity backend inside ADR-315. +3. **A coverage optimizer that consumes the ADR-315 RF twin over the ADR-306 scene, then validates predicted vs. measured observability after install.** Chosen. ## Decision -Define a **placement optimizer** that takes a floor plan (ADR-303 scene) and a +Define a **placement optimizer** that takes a floor plan (ADR-306 scene) and a hardware inventory and recommends sensor positions, then closes the loop after install. ### 1. Inputs -- The ADR-303 canonical scene: `Space`/`Zone` bounds, `Wall` segments with +- The ADR-306 canonical scene: `Space`/`Zone` bounds, `Wall` segments with `rf_attenuation_db`, `Doorway` topology, and any already-placed `Sensor` nodes. - A hardware inventory: the count and type of available radios (ESP32-S3/C6 nodes, mmWave, adapters) with their capability envelopes (what each can - sense, per ADR-315 / ADR-317 HAL descriptors). + sense, per ADR-318 / ADR-320 HAL descriptors). - A sensing objective: which phenomenon must be observable in which - `Space`/`Zone` (presence, vitals, pose), expressed against the ADR-299 + `Space`/`Zone` (presence, vitals, pose), expressed against the ADR-302 observability metric. ### 2. Prediction -- For a candidate placement, query the **ADR-312 RF twin** for simulated RF +- For a candidate placement, query the **ADR-315 RF twin** for simulated RF coverage: path loss through `Wall` attenuation, **Fresnel-zone clearance** between link endpoints, and coarse **multipath** structure. From that derive an **expected observability** and an **uncertainty** for each objective in - each space — reusing the same observability definition ADR-299 gates on so the + each space — reusing the same observability definition ADR-302 gates on so the plan and the runtime speak one language. - Search over candidate positions (the inventory bounds the count; the scene bounds the geometry) to recommend the placement that maximizes objective @@ -88,10 +88,10 @@ install. ### 3. Post-install loop - After install, compare **predicted vs. measured** observability using the - ADR-299 runtime observability signal from the freshly enrolled (ADR-302), - calibrated (ADR-298) sensors. Where measurement disagrees with prediction, + ADR-302 runtime observability signal from the freshly enrolled (ADR-305), + calibrated (ADR-301) sensors. Where measurement disagrees with prediction, recommend adjustments (move, re-aim, add a node) and feed the residual back - to improve the ADR-312 twin's scene parameters (e.g. a wall's effective + to improve the ADR-315 twin's scene parameters (e.g. a wall's effective attenuation). ### Evidence discipline @@ -108,15 +108,15 @@ install. - Installers get a principled, floorplan-specific placement plan and, crucially, a post-install check that says whether reality matched the plan — a differentiating capability over guess-and-check deployment. -- Quality is bounded by the fidelity of the ADR-312 RF twin and the coarseness +- Quality is bounded by the fidelity of the ADR-315 RF twin and the coarseness of the `worldgraph` scene (2D walls, coarse attenuation). The optimizer reports uncertainty rather than overstating a coarse model; higher fidelity - is an ADR-312 concern. -- Hard dependency on ADR-312 (twin), ADR-299 (observability metric), and - ADR-303 (scene); this ADR does not build a simulator or an observability + is an ADR-315 concern. +- Hard dependency on ADR-315 (twin), ADR-302 (observability metric), and + ADR-306 (scene); this ADR does not build a simulator or an observability metric of its own. - Being phase 3, this is design intent sitting on the fused world state; it is - expected to be revised as ADR-312 and the phase-1 spine land. + expected to be revised as ADR-315 and the phase-1 spine land. - No claim that recommended placement *guarantees* sensing — it maximizes modelled observability subject to inventory and geometry, with explicit uncertainty. diff --git a/docs/adr/ADR-306-active-sensing.md b/docs/adr/ADR-309-active-sensing.md similarity index 86% rename from docs/adr/ADR-306-active-sensing.md rename to docs/adr/ADR-309-active-sensing.md index a397083b..c6b6aa20 100644 --- a/docs/adr/ADR-306-active-sensing.md +++ b/docs/adr/ADR-309-active-sensing.md @@ -1,22 +1,22 @@ -# ADR-306: Active sensing — closed-loop RF experiment control +# ADR-309: Active sensing — closed-loop RF experiment control -- **Status**: Accepted — initial implementation (ADR-297 phase 3) +- **Status**: Accepted — initial implementation (ADR-300 phase 3) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: active-sensing, control-plane, closed-loop, information-gain, actuation, phase-3 ## Context -This ADR is a child of **ADR-297** and owns primitive #9, *active sensing*. In -the ADR-297 phasing it is a phase-3 primitive that sits on top of the fused -world state produced by **ADR-308** (real sensor fusion) and is driven by the -information budget of **ADR-311** (information-gain scheduler). It is authored +This ADR is a child of **ADR-300** and owns primitive #9, *active sensing*. In +the ADR-300 phasing it is a phase-3 primitive that sits on top of the fused +world state produced by **ADR-311** (real sensor fusion) and is driven by the +information budget of **ADR-314** (information-gain scheduler). It is authored as **Proposed**: design intent and validation plan, not a phase-1 build. The default posture of every current RuView path is **passive**: RF traffic happens for its own reasons (a device transmits, a beacon fires), RuView observes whatever CSI/CIR arrives, and the pipeline extracts what it can from -that incidental signal. The strategic assessment behind ADR-297 named the next +that incidental signal. The strategic assessment behind ADR-300 named the next step: move from *RF-happens → observe* to **RuView-controls-RF → observe the response → optimize the next measurement**. That turns sensing into a closed-loop experiment — the system chooses what to measure to resolve the @@ -37,8 +37,8 @@ Substantial control-plane scaffolding already exists and must be - ADR-280 explicitly recorded that **information-gain *estimation* is not implemented** — "the planner uses staleness heuristics, not mutual information; RIS drivers, actual multi-AP coherence measurement, and OTFS - waveform control are hardware-dependent roadmap items." ADR-306 is the ADR - that closes exactly those gaps, in coordination with ADR-311. + waveform control are hardware-dependent roadmap items." ADR-309 is the ADR + that closes exactly those gaps, in coordination with ADR-314. The missing piece is not the actuation surface — ADR-280 built that and made it fail closed — but the **loop**: a controller that reads the current fused-state @@ -73,11 +73,11 @@ observed response. Define an `ExperimentControl` vocabulary over the configuration axes RuView can influence on hardware that exposes them (each axis is optional and -capability-gated by ADR-317's HAL, so an ESP32-only deployment simply has an +capability-gated by ADR-320's HAL, so an ESP32-only deployment simply has an empty controllable set and degrades to the passive planner): - **Channel / band** and **bandwidth** (which spectrum to probe; reuses the - ADR-289 wideband subcarrier-agnostic metadata). + ADR-292 wideband subcarrier-agnostic metadata). - **Packet timing / cadence** (when to solicit a sounding, and at what rate). - **Antenna / chain selection** (which subset of a distributed aperture to activate — bounded by the ADR-280 `CoherentSensorGroup` compatibility proof). @@ -85,28 +85,28 @@ empty controllable set and degrades to the passive planner): governed exactly as ADR-280 §6 requires, via `request_actuation` and an `ActuationReceipt`). - **802.11bf measurement parameters** (TB/non-TB, reporting config) once - ADR-307 exposes standardized sensing as a native measurement type. + ADR-310 exposes standardized sensing as a native measurement type. ### 2. The loop ``` -fused-state uncertainty (ADR-308) +fused-state uncertainty (ADR-311) │ ▼ -info-gain ranking of ExperimentControl options (ADR-311) +info-gain ranking of ExperimentControl options (ADR-314) │ select argmax E[ΔI] / (cost, energy, privacy ceiling) ▼ governed request (ADR-280 admit_task / request_actuation, fail-closed) │ ▼ -observe response → update belief (ADR-308) → repeat +observe response → update belief (ADR-311) → repeat ``` The controller never bypasses the ADR-280 admission and actuation gates: every solicited measurement is a `SensingTask`/`SensingAction`, every environment change is an `ActuationReceipt`, and every step composes with the ADR-277 -policy engine. Information gain is what **ADR-311** supplies (the mutual- -information estimate ADR-280 deferred); ADR-306 owns the *control loop* that +policy engine. Information gain is what **ADR-314** supplies (the mutual- +information estimate ADR-280 deferred); ADR-309 owns the *control loop* that consumes that estimate and drives the hardware. ### 3. Governance and honesty boundary @@ -127,13 +127,13 @@ consumes that estimate and drives the hardware. - Sensing becomes an experiment: RuView spends its RF/energy/privacy budget on the measurements that most reduce current uncertainty, instead of processing whatever incidental traffic arrives. -- The loop is only as strong as its two dependencies: ADR-308 must expose a - usable uncertainty surface and ADR-311 must produce trustworthy information- +- The loop is only as strong as its two dependencies: ADR-311 must expose a + usable uncertainty surface and ADR-314 must produce trustworthy information- gain estimates. Where either is absent, the controller degrades to the ADR-280 staleness planner rather than acting on a fabricated gain estimate. - Controllability is hardware-bounded. On commodity ESP32 sensors the controllable set may be limited to cadence; the full loop (bandwidth, antenna, - beam) needs NICs/RIS that expose those axes, surfaced through ADR-317. + beam) needs NICs/RIS that expose those axes, surfaced through ADR-320. - This ADR adds a controller; it does not re-open ADR-280's raw-export or actuation-governance decisions, which remain authoritative and fail-closed. diff --git a/docs/adr/ADR-307-80211bf-native-architecture.md b/docs/adr/ADR-310-80211bf-native-architecture.md similarity index 87% rename from docs/adr/ADR-307-80211bf-native-architecture.md rename to docs/adr/ADR-310-80211bf-native-architecture.md index e9ab3211..3b52ff05 100644 --- a/docs/adr/ADR-307-80211bf-native-architecture.md +++ b/docs/adr/ADR-310-80211bf-native-architecture.md @@ -1,16 +1,16 @@ -# ADR-307: 802.11bf-native architecture — standardized WLAN sensing as native measurement types +# ADR-310: 802.11bf-native architecture — standardized WLAN sensing as native measurement types -- **Status**: Proposed (ADR-297 phase 2) +- **Status**: Proposed (ADR-300 phase 2) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: 80211bf, wlan-sensing, standards, measurement-types, hal, phase-2 ## Context -This ADR is a child of **ADR-297** and owns primitive #10, *802.11bf-native -architecture*. In the ADR-297 phasing it is a phase-2 integration primitive: it -sits on the phase-1 spine (authenticated identity ADR-302, spatial ontology -ADR-303, evidence engine ADR-301) and **feeds ADR-317** (the RuView sensor HAL), +This ADR is a child of **ADR-300** and owns primitive #10, *802.11bf-native +architecture*. In the ADR-300 phasing it is a phase-2 integration primitive: it +sits on the phase-1 spine (authenticated identity ADR-305, spatial ontology +ADR-306, evidence engine ADR-304) and **feeds ADR-320** (the RuView sensor HAL), which is the clause of the acceptance test that "identifies the hardware." It is authored as **Proposed**. @@ -44,7 +44,7 @@ the standardized procedure surface as forward-compatible types (ADR-152/153): The module's own honesty note is authoritative and carried forward here: it is **not a certified 802.11bf implementation**, and **no commodity silicon — ESP32 included — implements the standard yet**; the OTA frame binding lands when a -chipset exposes it. Wideband ingest plumbing is already in place too: **ADR-289** +chipset exposes it. Wideband ingest plumbing is already in place too: **ADR-292** (FeitCSI/AX210) carries native subcarrier dimensionality end-to-end and records the native→pipeline mapping, and noted that "truncated CIR is a natural extension of the same plumbing." @@ -53,7 +53,7 @@ What is missing is architectural, not protocol scaffolding: normalized CSI is still treated as *the* WiFi input. The standardized sensing measurements (TB/non-TB soundings, truncated CIR / PDP reports) are modeled as protocol messages but are **not yet first-class native measurement types** that flow -through calibration (ADR-298), fusion (ADR-308), and the ontology (ADR-303) on +through calibration (ADR-301), fusion (ADR-311), and the ontology (ADR-306) on equal footing with normalized CSI. ## Options considered @@ -64,7 +64,7 @@ equal footing with normalized CSI. the standard's native report semantics. 2. **Fork a parallel "bf pipeline" alongside the CSI pipeline.** Rejected: duplicates calibration, fusion, ontology, and evidence plumbing, and re-opens - the O(surfaces²) translation problem ADR-303 exists to close. + the O(surfaces²) translation problem ADR-306 exists to close. 3. **Promote standardized sensing measurements to native measurement types inside the existing pipeline**, with normalized CSI as one measurement type among several. Chosen. @@ -83,7 +83,7 @@ replacing — normalized CSI. with its `SpecProfile` and band. Normalized CSI remains one such type; the `OpportunisticCsiBridge` remains the path for silicon that only offers incidental CSI. -- Truncated CIR/PDP reuse the **ADR-289** subcarrier-agnostic / native- +- Truncated CIR/PDP reuse the **ADR-292** subcarrier-agnostic / native- dimensionality plumbing (truncated CIR is the stated natural extension); the native→pipeline mapping is recorded in frame metadata so downstream stages know the true range/spectral resolution of a bf report vs. an interpolated CSI @@ -91,8 +91,8 @@ replacing — normalized CSI. ### 2. Ontology and governance binding -- Each standardized measurement becomes an ADR-303 `Observation` node from an - ADR-302-authenticated `Sensor`, carrying `SemanticProvenance` and exactly one +- Each standardized measurement becomes an ADR-306 `Observation` node from an + ADR-305-authenticated `Sensor`, carrying `SemanticProvenance` and exactly one `EvidenceLevel` (L0–L5, ADR-282). The `ieee80211bf` `ConsentMode` metadata — required on every setup — composes with the ADR-277 policy engine, so a standardized session is admitted under the same governance as any other @@ -100,12 +100,12 @@ replacing — normalized CSI. - SBP (sensing-by-proxy) sessions attribute the report to the proxying and the sensing entities distinctly, so provenance is not laundered through the proxy. -### 3. HAL feed (ADR-317) +### 3. HAL feed (ADR-320) - The capability set a device advertises — which `MeasurementType`s, bands, bandwidths, roles, and `SpecProfile` it supports — is exactly the descriptor - **ADR-317** (HAL) needs to "identify the hardware." ADR-307 defines that - capability descriptor as the projection of `SensingCapabilities`; ADR-317 + **ADR-320** (HAL) needs to "identify the hardware." ADR-310 defines that + capability descriptor as the projection of `SensingCapabilities`; ADR-320 consumes it. A device that implements no bf profile advertises only the opportunistic-CSI capability. @@ -122,7 +122,7 @@ replacing — normalized CSI. 802.11bf yet; this ADR wires the *types and flow*, tested in simulation. Any OTA/native-report accuracy claim requires real silicon evidence (a captured log) per CLAUDE.md, and any wideband number must be tagged with the capture - hardware (ADR-289). No benchmark number is invented here. + hardware (ADR-292). No benchmark number is invented here. - This ADR does not re-open ADR-152/153's decision to avoid OTA frame binding until silicon exists; it consumes that surface and adds the pipeline integration. @@ -133,14 +133,14 @@ replacing — normalized CSI. table, and transport tests continue to pass; new tests assert that a `SensingMeasurementReport` (TB and non-TB) and a truncated-CIR/PDP report round-trip through the pipeline as native `MeasurementType`s. -- `cargo test -p wifi-densepose-mat` — truncated CIR ingest reuses the ADR-289 +- `cargo test -p wifi-densepose-mat` — truncated CIR ingest reuses the ADR-292 subcarrier-agnostic path and records the native→pipeline mapping; dimension/ version validation on standardized reports mirrors the FeitCSI parser gates. -- Ontology/governance tests: each standardized measurement becomes an ADR-303 - `Observation` from an ADR-302-authenticated `Sensor` with one `EvidenceLevel`; +- Ontology/governance tests: each standardized measurement becomes an ADR-306 + `Observation` from an ADR-305-authenticated `Sensor` with one `EvidenceLevel`; `ConsentMode` composes with ADR-277 admission; SBP attributes proxy vs. sensor provenance distinctly. -- HAL contract test: the ADR-317 capability descriptor is derivable from +- HAL contract test: the ADR-320 capability descriptor is derivable from `SensingCapabilities`; a bf-less device advertises only opportunistic CSI. - All measurement-type flows are simulation-tested (`SimTransport`, synthetic fixtures); OTA binding and any hardware accuracy claim remain out of scope diff --git a/docs/adr/ADR-308-real-sensor-fusion.md b/docs/adr/ADR-311-real-sensor-fusion.md similarity index 86% rename from docs/adr/ADR-308-real-sensor-fusion.md rename to docs/adr/ADR-311-real-sensor-fusion.md index 052eba1e..a91de3f7 100644 --- a/docs/adr/ADR-308-real-sensor-fusion.md +++ b/docs/adr/ADR-311-real-sensor-fusion.md @@ -1,17 +1,17 @@ -# ADR-308: Real sensor fusion — uncertainty-aware, multiple observations → one world state +# ADR-311: Real sensor fusion — uncertainty-aware, multiple observations → one world state -- **Status**: Accepted — initial implementation (ADR-297 phase 2) +- **Status**: Accepted — initial implementation (ADR-300 phase 2) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: fusion, uncertainty, multimodal, world-state, ontology, phase-2 ## Context -This ADR is a child of **ADR-297** and owns primitive #11, *real sensor fusion*. -In the ADR-297 DAG it is a phase-2 integration primitive: it **consumes ADR-303** +This ADR is a child of **ADR-300** and owns primitive #11, *real sensor fusion*. +In the ADR-300 DAG it is a phase-2 integration primitive: it **consumes ADR-306** (canonical spatial ontology) and **produces the single fused world state** that -the phase-3 primitives build on — **ADR-309** (long-term spatial memory), -**ADR-310** (counterfactual inference), and **ADR-312** (digital RF twin). It is +the phase-3 primitives build on — **ADR-312** (long-term spatial memory), +**ADR-313** (counterfactual inference), and **ADR-315** (digital RF twin). It is authored as **Proposed**. The defining invariant is not "support more modalities" but the *shape of the @@ -28,7 +28,7 @@ rebuilt**: - **ADR-063** (60 GHz mmWave ↔ WiFi CSI fusion, *Proposed*) established the first cross-modal fusion case: pairing noisy CSI-derived vitals with clinical- grade mmWave FMCW radar (Seeed MR60BHA2 over UART, with a **live hardware - capture** logged on 2026-03-15). ADR-308 generalizes that pairwise case into + capture** logged on 2026-03-15). ADR-311 generalizes that pairwise case into an N-modality, uncertainty-aware fusion. - **ADR-137** (fusion-engine quality scoring, *Accepted — partial*) already built the auditable-quality building block: it identified that the multistatic @@ -36,10 +36,10 @@ rebuilt**: `wifi-densepose-ruvector/src/viewpoint/fusion.rs`) discarded the evidence they used, and specified a single auditable record — "this fused output is trustworthy because X, Y, Z, but be aware of contradiction C" — with evidence - references and contradiction flags. ADR-308 reuses that record as the + references and contradiction flags. ADR-311 reuses that record as the provenance/quality carrier of the fused state. - **ADR-280** `CoherentSensorGroup` (fail-closed coherent fusion) and - **ADR-303** `Observation`/`Track`/`Event` node types are the input and output + **ADR-306** `Observation`/`Track`/`Event` node types are the input and output vocabulary respectively. What is missing is the **uncertainty-aware combiner across heterogeneous @@ -68,20 +68,20 @@ probabilistic world state. ### 1. Inputs: authenticated, ontology-typed observations -- Inputs are ADR-303 `Observation` nodes from **ADR-302-authenticated** sensors. - Supported modalities: WiFi (CSI / 802.11bf native reports via ADR-307), BLE, +- Inputs are ADR-306 `Observation` nodes from **ADR-305-authenticated** sensors. + Supported modalities: WiFi (CSI / 802.11bf native reports via ADR-310), BLE, UWB, mmWave (ADR-063), acoustic, IMU, lidar, and cameras. Cameras and any higher privacy-class modality enter fusion **only where the ADR-277 policy engine permits** — camera-free coverage is a RuView invariant (ADR-282), so cameras are an opt-in, policy-gated input, never assumed present. - Each observation carries its own uncertainty and exactly one `EvidenceLevel` - (ADR-282). An observation flagged out-of-distribution by **ADR-299** is + (ADR-282). An observation flagged out-of-distribution by **ADR-302** is down-weighted or excluded per its OOD verdict rather than silently averaged in. ### 2. Combiner: uncertainty-weighted, contradiction-aware - Observations are combined by their uncertainty into one probabilistic - `WorldState` over the ADR-303 entities (`Person`, `Object`, `Track`, and the + `WorldState` over the ADR-306 entities (`Person`, `Object`, `Track`, and the per-`Space` inference). The combiner does **not** collapse disagreement: when modalities conflict beyond their stated uncertainty, the fused output carries ADR-137 **contradiction flags** and the evidence references that produced @@ -93,9 +93,9 @@ probabilistic world state. ### 3. Output: one world state, provenance preserved -- The output is a single `WorldState` written into the ADR-303 ontology, with +- The output is a single `WorldState` written into the ADR-306 ontology, with every fused value retaining recoverable per-observation provenance and the - ADR-137 quality record. This is the state ADR-309/310/312 consume; they read + ADR-137 quality record. This is the state ADR-312/310/312 consume; they read one probabilistic world, not a modality stack. - The fused state carries an aggregate uncertainty and an evidence level derived from its inputs (never upgraded above the weakest contributing L-level for a @@ -108,7 +108,7 @@ probabilistic world state. re-implementing reconciliation per consumer. - Contradictions become first-class signal, not noise: ADR-137's record means a disagreement between mmWave and CSI is surfaced and auditable, which is also - what lets ADR-299 and the evidence engine (ADR-301) reason about reliability. + what lets ADR-302 and the evidence engine (ADR-304) reason about reliability. - Fusion is uncertainty-honest: an OOD or low-evidence observation is down-weighted, not averaged in as if trustworthy; a fused claim never presents a stronger evidence level than its weakest necessary input. @@ -127,9 +127,9 @@ probabilistic world state. the ADR-280 `CoherentSensorGroup` gate still fails closed under clock/phase/geometry violation. - Fusion invariant test: N modality observations over one scene resolve to a - single `WorldState` node in the ADR-303 ontology (not N feeds), with + single `WorldState` node in the ADR-306 ontology (not N feeds), with per-observation provenance recoverable and one aggregate evidence level. -- Uncertainty tests: a high-uncertainty or ADR-299-flagged-OOD observation is +- Uncertainty tests: a high-uncertainty or ADR-302-flagged-OOD observation is down-weighted/excluded; conflicting modalities produce a contradiction flag rather than a silently averaged value; the fused evidence level never exceeds the weakest necessary input. diff --git a/docs/adr/ADR-309-long-term-spatial-memory.md b/docs/adr/ADR-312-long-term-spatial-memory.md similarity index 88% rename from docs/adr/ADR-309-long-term-spatial-memory.md rename to docs/adr/ADR-312-long-term-spatial-memory.md index 2cac767f..4e8c15bd 100644 --- a/docs/adr/ADR-309-long-term-spatial-memory.md +++ b/docs/adr/ADR-312-long-term-spatial-memory.md @@ -1,15 +1,15 @@ -# ADR-309: Long-term spatial memory — learn the normal physics of a location +# ADR-312: Long-term spatial memory — learn the normal physics of a location -- **Status**: Accepted — initial implementation (ADR-297 phase 3) +- **Status**: Accepted — initial implementation (ADR-300 phase 3) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: spatial-memory, ruvector, anomaly-detection, temporal, world-state, phase-3 ## Context -This ADR is a child of **ADR-297** and owns primitive #12, *long-term spatial -memory*. In the ADR-297 phasing it is a phase-3 primitive that sits on the fused -world state produced by **ADR-308** (real sensor fusion) and **ties to ADR-312** +This ADR is a child of **ADR-300** and owns primitive #12, *long-term spatial +memory*. In the ADR-300 phasing it is a phase-3 primitive that sits on the fused +world state produced by **ADR-311** (real sensor fusion) and **ties to ADR-315** (digital RF twin): spatial memory is the *learned normal* that a twin can simulate against and that anomaly detection compares against. It is authored as **Proposed**. @@ -34,12 +34,12 @@ rebuilt**: (`event_log.rs`), coverage and estimator surfaces, and the `crv`/`mat` temporal sub-modules — so long-term spatial memory is a *consumer and organizer* of RuVector primitives, not a new store. -- **ADR-303** supplies the entity vocabulary the memory is indexed by (`Space`, - `Object`, `Sensor`, `Track`, `Event`); **ADR-308** supplies the fused, +- **ADR-306** supplies the entity vocabulary the memory is indexed by (`Space`, + `Object`, `Sensor`, `Track`, `Event`); **ADR-311** supplies the fused, uncertainty-carrying `WorldState` snapshots that memory accumulates over time. -- **ADR-135** (empty-room baseline calibration) and **ADR-298** (automatic +- **ADR-135** (empty-room baseline calibration) and **ADR-301** (automatic domain calibration) already establish a *calibration-time* baseline of a - space; ADR-309 extends that from a one-shot baseline to a **continuously + space; ADR-312 extends that from a one-shot baseline to a **continuously learned, time-of-day-aware** model of normal. What is missing is the **temporal normality model**: a per-`Space` learned @@ -67,7 +67,7 @@ on the RuVector substrate and scores live fused state against it. ### 1. What "normal" is learned over -Per ADR-303 `Space` (and the entities within it), accumulate the ADR-308 fused +Per ADR-306 `Space` (and the entities within it), accumulate the ADR-311 fused `WorldState` over time into a learned normality model covering: - **Occupancy / activity periodicity** — the distribution of presence and @@ -92,7 +92,7 @@ never presented above the evidence of the observations it was learned from. compression). Long-horizon history is temporally compressed — recent detail retained, older history summarized — so memory cost is bounded rather than growing linearly forever. -- The memory is *keyed by* the ADR-303 ontology, so "normal for this `Space` at +- The memory is *keyed by* the ADR-306 ontology, so "normal for this `Space` at this hour" is a first-class query, and slow legitimate drift updates the baseline (with provenance) instead of accumulating as permanent anomaly. @@ -100,11 +100,11 @@ never presented above the evidence of the observations it was learned from. - A live fused `WorldState` is scored against the applicable learned baseline (matched by space and time context). A deviation beyond the baseline's - uncertainty is surfaced as an ADR-303 `Event` — *without* a per-anomaly + uncertainty is surfaced as an ADR-306 `Event` — *without* a per-anomaly detector — carrying the baseline it deviated from, the deviation magnitude, and its evidence level. Whether that event is actionable is a policy/consumer decision (ADR-277), not this layer's. -- The learned normal is exactly what **ADR-312** (RF twin) can simulate against: +- The learned normal is exactly what **ADR-315** (RF twin) can simulate against: the twin proposes an expected state, spatial memory supplies the learned actual-normal, and their divergence is a physically grounded anomaly signal. @@ -142,5 +142,5 @@ never presented above the evidence of the observations it was learned from. rather than emitting a persistent anomaly; an abrupt change does emit one. - Evidence test: a learned baseline carries the evidence level of its source observations and is never presented above it; retention honors ADR-277. -- Twin-linkage design check (with ADR-312): divergence between a twin-simulated +- Twin-linkage design check (with ADR-315): divergence between a twin-simulated expected state and the learned normal is expressible as a deviation signal. diff --git a/docs/adr/ADR-310-counterfactual-inference.md b/docs/adr/ADR-313-counterfactual-inference.md similarity index 79% rename from docs/adr/ADR-310-counterfactual-inference.md rename to docs/adr/ADR-313-counterfactual-inference.md index 93962772..31ee46c4 100644 --- a/docs/adr/ADR-310-counterfactual-inference.md +++ b/docs/adr/ADR-313-counterfactual-inference.md @@ -1,17 +1,17 @@ -# ADR-310: Counterfactual inference — generative spatial reasoning +# ADR-313: Counterfactual inference — generative spatial reasoning -- **Status**: Accepted — initial implementation (ADR-297 phase 3) +- **Status**: Accepted — initial implementation (ADR-300 phase 3) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: inference, generative, counterfactual, rf-twin, fusion, uncertainty, phase-3 ## Context -This ADR is a child of **ADR-297** (perception substrate program) and owns -primitive #13, *counterfactual inference*. In the ADR-297 DAG it is a phase-3, +This ADR is a child of **ADR-300** (perception substrate program) and owns +primitive #13, *counterfactual inference*. In the ADR-300 DAG it is a phase-3, research-forward primitive that sits on top of the fused world state: it -**consumes ADR-308** (real sensor fusion) for the current fused estimate and -**ADR-312** (digital RF twin) for the twin's expected measurement +**consumes ADR-311** (real sensor fusion) for the current fused estimate and +**ADR-315** (digital RF twin) for the twin's expected measurement distributions. It is design intent, authored as Proposed, and is expected to be revised as the phase-1 spine and the phase-2 fusion layer land. @@ -26,7 +26,7 @@ best-effort label; it cannot say "the observation is better explained by absence." The step this ADR proposes is toward a **generative spatial model**: given a -hypothesized scene state (occupancy, count, coarse positions) and the ADR-312 +hypothesized scene state (occupancy, count, coarse positions) and the ADR-315 twin's propagation model for the deployment, predict the *expected* measurement distribution, then score how well each hypothesis explains the observed measurement. The best-explaining hypothesis — including the *nobody-present* @@ -35,17 +35,17 @@ first-class uncertainty signal. Relevant existing assets to build on rather than duplicate: -- **ADR-308** (fusion) already produces the fused world estimate and its +- **ADR-311** (fusion) already produces the fused world estimate and its covariance; the counterfactual layer scores hypotheses *relative to* that estimate rather than re-fusing raw measurements. -- **ADR-312** (RF twin) is the generative forward model — per-deployment +- **ADR-315** (RF twin) is the generative forward model — per-deployment geometry, radio locations, and expected measurement distributions. This ADR is a *consumer* of the twin's forward simulator, not a second simulator. -- **ADR-299** (OOD/observability) already owns the `UNKNOWN` verdict; the +- **ADR-302** (OOD/observability) already owns the `UNKNOWN` verdict; the null-hypothesis ("nobody present better explains this than any occupancy - hypothesis") and the "no hypothesis explains this" case route through ADR-299, + hypothesis") and the "no hypothesis explains this" case route through ADR-302, not a parallel gate. -- `frame::EvidenceLevel` L0–L5 (ADR-282) and the ADR-301 evidence engine +- `frame::EvidenceLevel` L0–L5 (ADR-282) and the ADR-304 evidence engine account for the resulting confidence. ## Options considered @@ -54,13 +54,13 @@ Relevant existing assets to build on rather than duplicate: cannot compare "one person vs. two" as competing explanations, and gives a confident label even when no world state explains the data. 2. **A second, independently trained generative network with its own forward - model.** Rejected for the default path: duplicates the ADR-312 twin's + model.** Rejected for the default path: duplicates the ADR-315 twin's propagation model, invites the two models to disagree, and multiplies the surface that must be validated. Reserved only if the twin's analytic forward model proves insufficient for a phenomenon. -3. **A hypothesis-scoring layer that uses the ADR-312 twin as the forward model - and the ADR-308 fused state as the hypothesis prior, routing low-margin and - null-dominant cases to the ADR-299 UNKNOWN verdict.** Chosen. +3. **A hypothesis-scoring layer that uses the ADR-315 twin as the forward model + and the ADR-311 fused state as the hypothesis prior, routing low-margin and + null-dominant cases to the ADR-302 UNKNOWN verdict.** Chosen. ## Decision @@ -70,31 +70,31 @@ generative forward model. ### 1. Hypothesis set -- Hypotheses are drawn from the ADR-308 fused state and its neighbourhood: the +- Hypotheses are drawn from the ADR-311 fused state and its neighbourhood: the current estimate, the **null hypothesis** (nobody present), and a bounded set of nearby alternatives (±1 occupant, shifted position). The fused estimate supplies the prior so the search stays small and grounded rather than enumerating an open world. -- The hypothesis space is expressed over the **ADR-303** canonical ontology +- The hypothesis space is expressed over the **ADR-306** canonical ontology (`Space`/`Zone`, occupant count, coarse position), so a counterfactual result is a governed spatial statement, not an opaque score. ### 2. Forward model and scoring -- For each hypothesis, query the **ADR-312 twin** for the expected measurement +- For each hypothesis, query the **ADR-315 twin** for the expected measurement distribution given that scene state and the deployment's propagation model. Score the observed measurement's likelihood under each hypothesis's expected distribution. - The answer is the maximum-likelihood hypothesis; the **margin** between the top hypotheses (and between the top hypothesis and the null) is the - confidence signal, carried into the ADR-301 evidence engine. + confidence signal, carried into the ADR-304 evidence engine. ### 3. Routing to UNKNOWN - When the null hypothesis dominates, the layer reports *absence*, not a low-confidence occupancy label. - When **no** hypothesis explains the observation well (all likelihoods low, or - the winning margin below threshold), the result routes to the **ADR-299** + the winning margin below threshold), the result routes to the **ADR-302** `UNKNOWN` verdict — the observation is outside what the twin can explain, and the honest output is "I cannot account for this," never a forced label. @@ -115,14 +115,14 @@ generative forward model. questions that discriminative heads structurally cannot — a step toward generative spatial reasoning and a differentiator for security and facility-monitoring applications where *absence* is the valuable signal. -- Quality is bounded by the fidelity of the ADR-312 twin's forward model and the - ADR-308 fused prior; the layer reports margins and defers to ADR-299 UNKNOWN +- Quality is bounded by the fidelity of the ADR-315 twin's forward model and the + ADR-311 fused prior; the layer reports margins and defers to ADR-302 UNKNOWN rather than overstating a coarse model. -- Hard dependency on ADR-308 (fused state and covariance) and ADR-312 (forward +- Hard dependency on ADR-311 (fused state and covariance) and ADR-315 (forward model); this ADR builds neither a fusion engine nor a propagation simulator of its own. - Being phase 3, this is design intent sitting on the fused world state; it is - expected to be revised as ADR-308 and ADR-312 land, and it is not implemented + expected to be revised as ADR-311 and ADR-315 land, and it is not implemented by the phase-1 swarm. ## Validation @@ -133,8 +133,8 @@ generative forward model. two-occupant hypothesis above the one-occupant hypothesis on a controlled synthetic case. - Integration test: measurements the twin cannot explain (out-of-model - scattering) drive the layer to the ADR-299 UNKNOWN verdict rather than a - forced occupancy label; margins propagate into the ADR-301 evidence engine. + scattering) drive the layer to the ADR-302 UNKNOWN verdict rather than a + forced occupancy label; margins propagate into the ADR-304 evidence engine. - Held-out discrimination (deferred, real-silicon): one-vs-two and presence-vs-absence discrimination on a leakage-free held-out split with a mean-pose baseline, reported as `MEASURED` with a reproducer. Until then all diff --git a/docs/adr/ADR-311-information-gain-scheduler.md b/docs/adr/ADR-314-information-gain-scheduler.md similarity index 77% rename from docs/adr/ADR-311-information-gain-scheduler.md rename to docs/adr/ADR-314-information-gain-scheduler.md index e0c7d992..92c8b312 100644 --- a/docs/adr/ADR-311-information-gain-scheduler.md +++ b/docs/adr/ADR-314-information-gain-scheduler.md @@ -1,16 +1,16 @@ -# ADR-311: Information-gain scheduler — sample the most informative radios +# ADR-314: Information-gain scheduler — sample the most informative radios -- **Status**: Accepted — initial implementation (ADR-297 phase 3) +- **Status**: Accepted — initial implementation (ADR-300 phase 3) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: scheduling, active-sensing, information-gain, edge, energy, fusion, phase-3 ## Context -This ADR is a child of **ADR-297** (perception substrate program) and owns -primitive #14, *information-gain scheduler*. In the ADR-297 DAG it is a phase-3, +This ADR is a child of **ADR-300** (perception substrate program) and owns +primitive #14, *information-gain scheduler*. In the ADR-300 DAG it is a phase-3, research-forward primitive that sits on top of the fused world state and -**pairs with ADR-306** (active sensing): ADR-306 decides *what to probe* +**pairs with ADR-309** (active sensing): ADR-309 decides *what to probe* (waveform, sensing task); this ADR decides *which radios/modalities to spend budget on next*. It is authored as Proposed and is not implemented by the phase-1 swarm. @@ -36,17 +36,17 @@ not by actually sampling. Relevant existing assets to build on rather than duplicate: -- **ADR-308** (fusion) maintains the fused state and its covariance — the +- **ADR-311** (fusion) maintains the fused state and its covariance — the current uncertainty the scheduler is trying to reduce. Expected uncertainty reduction is computed against that covariance, not a private one. -- **ADR-312** (RF twin) provides the per-sensor forward model used to predict a +- **ADR-315** (RF twin) provides the per-sensor forward model used to predict a candidate measurement's expected informativeness before sampling. -- **ADR-317** (RuView sensor HAL, phase 2) exposes each radio's real +- **ADR-320** (RuView sensor HAL, phase 2) exposes each radio's real compute/energy/bandwidth cost descriptors; the denominator is read from the HAL, not guessed per platform. -- **ADR-306** (active sensing) is the paired actuator: the scheduler ranks - sensors, ADR-306 chooses the probe on the chosen sensor. -- **ADR-299** (observability) defines the phenomenon the estimate is *for*, so +- **ADR-309** (active sensing) is the paired actuator: the scheduler ranks + sensors, ADR-309 chooses the probe on the chosen sensor. +- **ADR-302** (observability) defines the phenomenon the estimate is *for*, so the scheduler prioritizes uncertainty reduction on the objective that matters, not on nuisance dimensions. @@ -61,8 +61,8 @@ Relevant existing assets to build on rather than duplicate: the present uncertainty — a well-placed WiFi link can dominate an occluded mmWave node in a given moment. 3. **A value-of-information scheduler that ranks sensors by expected uncertainty - reduction per unit cost, using the ADR-308 covariance and ADR-312 forward - model, with costs from the ADR-317 HAL.** Chosen. + reduction per unit cost, using the ADR-311 covariance and ADR-315 forward + model, with costs from the ADR-320 HAL.** Chosen. ## Decision @@ -72,12 +72,12 @@ sampling/processing budget across available radios by value of information. ### 1. Value function - For each candidate sensor/modality, estimate **expected uncertainty - reduction** on the ADR-299 objective by evaluating how much a predicted - measurement (via the **ADR-312** forward model) would shrink the **ADR-308** + reduction** on the ADR-302 objective by evaluating how much a predicted + measurement (via the **ADR-315** forward model) would shrink the **ADR-311** fused-state covariance — a value-of-information estimate made *before* paying for the measurement. - Divide by the sensor's **cost** — compute + energy + bandwidth — read from the - **ADR-317** HAL descriptors. The exact weighting of the three cost terms is a + **ADR-320** HAL descriptors. The exact weighting of the three cost terms is a deployment policy (a battery node weights energy heavily; a wired gateway weights bandwidth), configured, not hardcoded. @@ -87,22 +87,22 @@ sampling/processing budget across available radios by value of information. configurable floor that guarantees each sensor is sampled at least occasionally (so a sensor whose value is currently low is not starved into permanent blindness and can be re-evaluated as the scene changes). -- The scheduler emits an allocation, not a measurement; **ADR-306** active +- The scheduler emits an allocation, not a measurement; **ADR-309** active sensing chooses the probe/waveform on each selected sensor, and the fusion - layer (ADR-308) incorporates the result. + layer (ADR-311) incorporates the result. ### 3. Governance and honesty - Skipping a sensor for a cycle is a *deliberate* reduction in coverage; the - scheduler records which sensors were sampled so downstream evidence (ADR-301) - reflects the actual sensing that occurred, and observability (ADR-299) can + scheduler records which sensors were sampled so downstream evidence (ADR-304) + reflects the actual sensing that occurred, and observability (ADR-302) can raise `UNKNOWN` for a zone that went under-sampled rather than reporting a stale estimate as current. ### Evidence discipline - Expected-uncertainty-reduction estimates are model predictions from the - ADR-312 twin (simulation, L0 per ADR-282, `SYNTHETIC`); a scheduling decision + ADR-315 twin (simulation, L0 per ADR-282, `SYNTHETIC`); a scheduling decision is a resource choice, never a sensing claim. - Any energy/latency/throughput improvement figure requires real-silicon measurement with a reproducer before it is tagged `MEASURED` (CLAUDE.md @@ -113,14 +113,14 @@ sampling/processing budget across available radios by value of information. - Edge deployments spend scarce compute, energy, and bandwidth where they buy the most certainty, making "hundreds of sensors" operationally tractable — a capability the reviews flagged as critical for edge deployment. -- Quality is bounded by the accuracy of the ADR-312 forward model (informativeness - prediction) and ADR-317 cost descriptors; a poor forward model degrades to +- Quality is bounded by the accuracy of the ADR-315 forward model (informativeness + prediction) and ADR-320 cost descriptors; a poor forward model degrades to near-round-robin, which is safe but not optimal. The sampling floor bounds the worst case. -- Hard dependency on ADR-308 (covariance), ADR-312 (forward model), and ADR-317 - (cost descriptors), and paired with ADR-306; this ADR builds none of those. +- Hard dependency on ADR-311 (covariance), ADR-315 (forward model), and ADR-320 + (cost descriptors), and paired with ADR-309; this ADR builds none of those. - Being phase 3, this is design intent sitting on the fused world state and is - expected to be revised as ADR-306, ADR-308, ADR-312, and the ADR-317 HAL land. + expected to be revised as ADR-309, ADR-311, ADR-315, and the ADR-320 HAL land. ## Validation @@ -130,7 +130,7 @@ sampling/processing budget across available radios by value of information. sampling floor guarantees eventual re-evaluation of a low-value sensor. - Integration test: on a synthetic multi-sensor scene, the scheduler reduces objective uncertainty faster per unit modelled cost than round-robin, and - raises ADR-299 UNKNOWN for a deliberately starved zone rather than reporting a + raises ADR-302 UNKNOWN for a deliberately starved zone rather than reporting a stale estimate. - Field validation (deferred, real-silicon): energy/latency/throughput on an instrumented multi-node deployment, reported as `MEASURED` with a reproducer. diff --git a/docs/adr/ADR-312-digital-rf-twin.md b/docs/adr/ADR-315-digital-rf-twin.md similarity index 79% rename from docs/adr/ADR-312-digital-rf-twin.md rename to docs/adr/ADR-315-digital-rf-twin.md index 2070cc30..26da1d4c 100644 --- a/docs/adr/ADR-312-digital-rf-twin.md +++ b/docs/adr/ADR-315-digital-rf-twin.md @@ -1,20 +1,20 @@ -# ADR-312: Digital RF twin — persistent per-deployment RF model +# ADR-315: Digital RF twin — persistent per-deployment RF model -- **Status**: Accepted — initial implementation (ADR-297 phase 3) +- **Status**: Accepted — initial implementation (ADR-300 phase 3) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: rf-twin, digital-twin, propagation, calibration, spatial-memory, worldgraph, phase-3 ## Context -This ADR is a child of **ADR-297** (perception substrate program) and owns -primitive #15, *digital RF twin*. In the ADR-297 DAG it is a phase-3, +This ADR is a child of **ADR-300** (perception substrate program) and owns +primitive #15, *digital RF twin*. In the ADR-300 DAG it is a phase-3, research-forward primitive that underpins several other phase-3 primitives: -**ADR-305** (placement optimizer) plans against the twin's propagation model, -**ADR-310** (counterfactual inference) uses it as the generative forward model, -and **ADR-311** (information-gain scheduler) uses it to predict per-sensor -informativeness. It ties directly to **ADR-298** (calibration), **ADR-305** -(placement), and **ADR-309** (long-term spatial memory). It is authored as +**ADR-308** (placement optimizer) plans against the twin's propagation model, +**ADR-313** (counterfactual inference) uses it as the generative forward model, +and **ADR-314** (information-gain scheduler) uses it to predict per-sensor +informativeness. It ties directly to **ADR-301** (calibration), **ADR-308** +(placement), and **ADR-312** (long-term spatial memory). It is authored as Proposed and is not implemented by the phase-1 swarm. RuView today has no persistent, per-deployment model of the RF environment. @@ -29,9 +29,9 @@ noise or drift. The **digital RF twin** is that persistent baseline: a per-deployment model holding -- **geometry and radio locations** (from the ADR-303 scene / worldgraph), +- **geometry and radio locations** (from the ADR-306 scene / worldgraph), - **propagation history** and **observed multipath** structure, -- **calibration state** (from ADR-298), +- **calibration state** (from ADR-301), - **expected measurement distributions** for each link and phenomenon. Once the twin exists, a physical change becomes a **measurable delta against the @@ -45,15 +45,15 @@ Relevant existing assets to build on rather than duplicate: - The `worldgraph` crate already models the physical scene — `Room`/`Space` with `bounds_enu`, `Wall { rf_attenuation_db }`, `Doorway`, `Zone`, and - `Sensor` nodes (ADR-303). The twin *annotates and persists* this scene with RF + `Sensor` nodes (ADR-306). The twin *annotates and persists* this scene with RF state; it does not invent a second geometry. - `wifi-densepose-calibration` (enrollment, bank, anchor, runtime, specialist) holds the calibration state the twin persists; the twin references and versions calibration records, it does not reimplement calibration. -- **ADR-309** (long-term spatial memory, phase 3) is the persistence and +- **ADR-312** (long-term spatial memory, phase 3) is the persistence and temporal-history substrate; the twin is a *structured occupant* of that memory, not a separate database. -- **ADR-302** (authenticated identity) and **ADR-292** (provenance) mean the +- **ADR-305** (authenticated identity) and **ADR-295** (provenance) mean the measurements that update the twin carry verified lineage, so a delta is attributable rather than anonymous. @@ -67,8 +67,8 @@ Relevant existing assets to build on rather than duplicate: coarse `rf_attenuation_db` scene RuView actually has and impractical on edge hardware. A high-fidelity solver is retained as an *optional backend* the twin can call, not the baseline. -3. **A persistent, per-deployment RF model layered over the ADR-303 scene and - ADR-309 memory: geometry + radio locations + calibration state + observed +3. **A persistent, per-deployment RF model layered over the ADR-306 scene and + ADR-312 memory: geometry + radio locations + calibration state + observed multipath + expected measurement distributions, updated by verified measurements, exposing changes as deltas.** Chosen. @@ -80,20 +80,20 @@ assets. ### 1. State the twin holds -- **Geometry and radio locations** referenced from the ADR-303 / worldgraph +- **Geometry and radio locations** referenced from the ADR-306 / worldgraph scene (not copied). - **Calibration state** referenced and versioned from - `wifi-densepose-calibration` (ADR-298), so the twin knows *which* calibration + `wifi-densepose-calibration` (ADR-301), so the twin knows *which* calibration a stored distribution was captured under. - **Observed multipath and propagation history** — a bounded temporal summary - of per-link channel structure, stored in ADR-309 spatial memory. + of per-link channel structure, stored in ADR-312 spatial memory. - **Expected measurement distributions** per link and phenomenon — the forward - model ADR-305, ADR-310, and ADR-311 consume. + model ADR-308, ADR-313, and ADR-314 consume. ### 2. Update and delta -- Verified measurements (ADR-302 identity, ADR-292 provenance) update the twin's - distributions online, bounded by ADR-298 calibration validity. A new +- Verified measurements (ADR-305 identity, ADR-295 provenance) update the twin's + distributions online, bounded by ADR-301 calibration validity. A new observation is compared to the twin's expected distribution; the **delta** — and its statistical significance against the twin's own variance — is the primary output. A change large relative to the twin's modelled variance is a @@ -104,12 +104,12 @@ assets. ### 3. Consumers -- **ADR-305** queries the twin's propagation model to plan placements. -- **ADR-310** uses the twin's expected distributions as the generative forward +- **ADR-308** queries the twin's propagation model to plan placements. +- **ADR-313** uses the twin's expected distributions as the generative forward model for hypothesis scoring. -- **ADR-311** uses per-sensor expected informativeness from the twin. +- **ADR-314** uses per-sensor expected informativeness from the twin. - Facility/security/robotics/industrial integrations read the twin's change - deltas as governed ADR-303 spatial events. + deltas as governed ADR-306 spatial events. ### Evidence discipline @@ -129,18 +129,18 @@ assets. measurement" into "a measurable, attributable, versioned change" — the bridge from a sensing runtime to facility management, security, robotics, and industrial monitoring. -- The twin is the shared forward model for ADR-305/310/311, so those primitives +- The twin is the shared forward model for ADR-308/310/311, so those primitives speak one propagation model rather than three inconsistent ones — a deliberate reason to build the twin before its consumers mature. - Quality is bounded by the coarseness of the worldgraph scene and the fidelity of the forward model; the twin reports deltas *with significance against its own variance* rather than asserting confident change detection on a coarse model. The optional high-fidelity backend is where higher accuracy lives. -- Hard dependency on ADR-303 (scene), ADR-298 (calibration state), and ADR-309 +- Hard dependency on ADR-306 (scene), ADR-301 (calibration state), and ADR-312 (persistence); it reuses `worldgraph` and `wifi-densepose-calibration` rather than rebuilding geometry or calibration. - Being phase 3, this is design intent; it is expected to be revised as the - phase-1 spine, ADR-308 fusion, and ADR-309 memory land. + phase-1 spine, ADR-311 fusion, and ADR-312 memory land. ## Validation @@ -151,8 +151,8 @@ assets. is retained. - Integration test: on a synthetic deployment, an injected physical change (a wall attenuation shift) produces a significant delta against the twin while - ordinary noise does not; the delta surfaces as a governed ADR-303 event with - provenance (ADR-302/292). + ordinary noise does not; the delta surfaces as a governed ADR-306 event with + provenance (ADR-305/292). - Field validation (deferred, real-silicon): change detection on an instrumented real deployment with a controlled physical-change protocol, reported as `MEASURED` with a reproducer. Until then all twin distributions and deltas are diff --git a/docs/adr/ADR-313-fleet-control-plane.md b/docs/adr/ADR-316-fleet-control-plane.md similarity index 79% rename from docs/adr/ADR-313-fleet-control-plane.md rename to docs/adr/ADR-316-fleet-control-plane.md index 0b386797..32ebb93b 100644 --- a/docs/adr/ADR-313-fleet-control-plane.md +++ b/docs/adr/ADR-316-fleet-control-plane.md @@ -1,17 +1,17 @@ -# ADR-313: Fleet control plane — provisioning to audit trails +# ADR-316: Fleet control plane — provisioning to audit trails -- **Status**: Proposed (ADR-297 phase 2) +- **Status**: Proposed (ADR-300 phase 2) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: fleet, operations, provisioning, firmware, updates, audit, identity, phase-2 ## Context -This ADR is a child of **ADR-297** (perception substrate program) and owns -primitive #16, *fleet control plane*. In the ADR-297 DAG it is a phase-2 +This ADR is a child of **ADR-300** (perception substrate program) and owns +primitive #16, *fleet control plane*. In the ADR-300 DAG it is a phase-2 integration-and-operations primitive that sits on the phase-1 spine: it -**consumes ADR-302** (authenticated sensor identity) for per-device identity and -enrollment, and **ADR-315** (capability certificate) for the signed models, +**consumes ADR-305** (authenticated sensor identity) for per-device identity and +enrollment, and **ADR-318** (capability certificate) for the signed models, calibration validity, and capability envelopes a device is allowed to run. It is authored as Proposed and is not implemented by the phase-1 swarm. @@ -27,26 +27,26 @@ retention, or produce an audit trail. This ADR addresses that release-identity / BOM gap directly. The scope is deliberately the **control plane**, not the data plane. The -authenticated measurement path is **ADR-293** (bind + allowlist) plus **ADR-302** +authenticated measurement path is **ADR-296** (bind + allowlist) plus **ADR-305** (signed envelope); this ADR governs the *devices and artifacts*, not the per-frame stream. Relevant existing assets to build on rather than duplicate: -- **ADR-302** already defines per-device keypairs, the `DeviceId → public key → +- **ADR-305** already defines per-device keypairs, the `DeviceId → public key → capabilities` enrollment record, key rotation and revocation *semantics* — and explicitly deferred their **fleet distribution** to this ADR. The control - plane is the distribution and lifecycle layer over ADR-302 identity, not a new + plane is the distribution and lifecycle layer over ADR-305 identity, not a new identity scheme. -- **ADR-315** (capability certificate) defines the signed, expiring artifact a +- **ADR-318** (capability certificate) defines the signed, expiring artifact a device is authorized to run; the fleet plane is what *distributes, stages, and revokes* those certificates and the signed models they point at. -- **ADR-298** (calibration) owns calibration validity/expiry; the fleet plane +- **ADR-301** (calibration) owns calibration validity/expiry; the fleet plane tracks calibration *lifecycle* across the fleet (which nodes are due, which are stale) rather than redefining calibration. -- **ADR-316** (witness chain) provides the append-only, re-verifiable record; +- **ADR-319** (witness chain) provides the append-only, re-verifiable record; fleet audit trails are witness-chain entries, not a parallel log format. -- **ADR-317** (RuView sensor HAL, phase 2) provides hardware/firmware capability +- **ADR-320** (RuView sensor HAL, phase 2) provides hardware/firmware capability descriptors used for firmware-compatibility checks before staging an update. - `wifi-densepose-bfld` `CapabilityAttestation` (ADR-141) is the device-side attestation the plane checks against declared cohort capabilities. @@ -61,8 +61,8 @@ Relevant existing assets to build on rather than duplicate: capability certificate, calibration validity, or witness chain, and would fork trust away from the phase-1 spine. A generic transport/agent *may* be a backend, but identity, certificates, and audit remain RuView's. -3. **A RuView-native control plane layered on ADR-302 identity, ADR-315 - certificates, ADR-298 calibration lifecycle, and ADR-316 audit — covering +3. **A RuView-native control plane layered on ADR-305 identity, ADR-318 + certificates, ADR-301 calibration lifecycle, and ADR-319 audit — covering provisioning through rollback and retention.** Chosen. ## Decision @@ -73,22 +73,22 @@ spine. ### 1. Release identity and bill of materials -- Each fielded device has a **BOM record** binding `DeviceId` (ADR-302) → exact - firmware version → signed model set → active capability certificate (ADR-315) - → current calibration record (ADR-298) → HAL/hardware descriptor (ADR-317). +- Each fielded device has a **BOM record** binding `DeviceId` (ADR-305) → exact + firmware version → signed model set → active capability certificate (ADR-318) + → current calibration record (ADR-301) → HAL/hardware descriptor (ADR-320). This *is* the release identity the reviews found missing: given a device you can state precisely what it is running and prove it is signed. ### 2. Provisioning, certificates, firmware compatibility -- **Provisioning** is the authorized ADR-302 enrollment step at fleet scale: +- **Provisioning** is the authorized ADR-305 enrollment step at fleet scale: minting a keypair, registering the public key and capabilities, and issuing - the initial ADR-315 certificate. A device is untrusted until provisioned. -- **Certificate lifecycle**: issue, rotate, expire, and **revoke** ADR-315 - certificates and the ADR-302 keys behind them; revocation lists are - distributed here (the distribution ADR-302 deferred). + the initial ADR-318 certificate. A device is untrusted until provisioned. +- **Certificate lifecycle**: issue, rotate, expire, and **revoke** ADR-318 + certificates and the ADR-305 keys behind them; revocation lists are + distributed here (the distribution ADR-305 deferred). - **Firmware compatibility**: before staging a firmware or model, check the - target's ADR-317 HAL descriptor and ADR-141 capability attestation so an + target's ADR-320 HAL descriptor and ADR-141 capability attestation so an incompatible or under-capable device is never sent an artifact it cannot honestly run. @@ -102,13 +102,13 @@ spine. ### 4. Health telemetry, remote diagnostics, retention, audit - **Health telemetry** and **remote diagnostics** report device liveness, - calibration staleness (ADR-298), certificate expiry (ADR-315), and error + calibration staleness (ADR-301), certificate expiry (ADR-318), and error state — read-only diagnostics by default, mutations authorized explicitly. - **Data retention** policy is enforced per cohort, and P0/CSI/person data never leaves the edge except under the ADR-277/280 governance already in force (CLAUDE.md: never commit or exfiltrate CSI/person data). - Every lifecycle action — provision, rotate, revoke, stage, roll back — is - written as an **ADR-316 witness-chain** entry, giving a re-verifiable **audit + written as an **ADR-319 witness-chain** entry, giving a re-verifiable **audit trail** rather than a mutable log. ### Authority and least privilege @@ -127,12 +127,12 @@ spine. default-deny, per-action authorization, signed-only artifacts, and witness-chained audit. A compromised plane must still forge signatures the phase-1 spine verifies. -- Hard dependency on ADR-302 (identity), ADR-315 (certificate), ADR-298 - (calibration lifecycle), ADR-316 (audit), and ADR-317 (firmware/HAL +- Hard dependency on ADR-305 (identity), ADR-318 (certificate), ADR-301 + (calibration lifecycle), ADR-319 (audit), and ADR-320 (firmware/HAL compatibility). This ADR distributes and sequences those artifacts; it does not redefine identity, certificates, calibration, or the witness format. - Being phase 2, this is design intent depending on the spine; it is expected to - be revised as ADR-315, ADR-316, and ADR-317 land. + be revised as ADR-318, ADR-319, and ADR-320 land. - **No fielded fleet-operation claim is MEASURED without real-silicon evidence** (CLAUDE.md hardware rule): staged update and rollback on real nodes require a captured runtime log. A passing simulation is not fleet evidence. @@ -142,7 +142,7 @@ spine. - Unit tests: BOM records bind identity/firmware/model/certificate/calibration consistently and reject inconsistent bindings; certificate issue/rotate/revoke transitions are correct; a firmware-incompatible target is refused staging; - every lifecycle action emits a well-formed ADR-316 witness entry. + every lifecycle action emits a well-formed ADR-319 witness entry. - Integration test: a synthetic cohort undergoes a canary→cohort→fleet staged update; an injected health failure triggers rollback to the prior BOM; the full sequence is re-verifiable from the witness chain offline; a revoked diff --git a/docs/adr/ADR-314-benchmark-multi-domain-scorecard.md b/docs/adr/ADR-317-benchmark-multi-domain-scorecard.md similarity index 90% rename from docs/adr/ADR-314-benchmark-multi-domain-scorecard.md rename to docs/adr/ADR-317-benchmark-multi-domain-scorecard.md index 23f881b1..ab7e64a6 100644 --- a/docs/adr/ADR-314-benchmark-multi-domain-scorecard.md +++ b/docs/adr/ADR-317-benchmark-multi-domain-scorecard.md @@ -1,25 +1,25 @@ -# ADR-314: Multi-domain benchmark scorecard — regressions cannot hide behind pooled accuracy +# ADR-317: Multi-domain benchmark scorecard — regressions cannot hide behind pooled accuracy -- **Status**: Accepted — initial implementation planned (ADR-297 phase 1) +- **Status**: Accepted — initial implementation planned (ADR-300 phase 1) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: benchmark, aetherarena, ci-gate, evidence, honesty, domain-generalization, substrate ## Context -This ADR is primitive 17 of the perception-substrate program (ADR-297) and the -per-PR enforcement edge of the phase-1 certificate spine. In the ADR-297 -dependency DAG it reads accuracy from the evidence engine (ADR-301), consumes -the domain state produced by out-of-distribution detection (ADR-299), scores -against calibration certificates (ADR-298), and is anchored in the witness chain -(ADR-316). It is the surface that makes the rest of the spine testable on every +This ADR is primitive 17 of the perception-substrate program (ADR-300) and the +per-PR enforcement edge of the phase-1 certificate spine. In the ADR-300 +dependency DAG it reads accuracy from the evidence engine (ADR-304), consumes +the domain state produced by out-of-distribution detection (ADR-302), scores +against calibration certificates (ADR-301), and is anchored in the witness chain +(ADR-319). It is the surface that makes the rest of the spine testable on every change to sensing code. A single pooled accuracy number is the classic way a domain-generalization regression hides. A model can raise mean PCK or mean presence accuracy while quietly collapsing on unseen rooms, unseen devices, or stationary subjects — exactly the conditions WiFi sensing fails in and exactly the conditions a -pooled average washes out. The strategic assessment (ADR-297) named this: what +pooled average washes out. The strategic assessment (ADR-300) named this: what distinguishes infrastructure from a demo is that a regression on *any* operating domain is caught before merge, not discovered in the field. @@ -62,11 +62,11 @@ pooled into one figure. The v0 domain axes: (a stationary subject at range — the canonical WiFi failure case). - **Pose**: `matched`, `subject-unseen`, `room-unseen`. - **OOD rejection**: the rate at which genuinely out-of-distribution input is - correctly returned as UNKNOWN by ADR-299 (a capability, not a failure) and + correctly returned as UNKNOWN by ADR-302 (a capability, not a failure) and the false-UNKNOWN rate on in-distribution input. -- **Calibration drift**: fingerprint-distance trajectory against the ADR-298 +- **Calibration drift**: fingerprint-distance trajectory against the ADR-301 certificate over the scored window, and the fraction of inferences in each - ADR-299 `DomainState` (KNOWN / DEGRADED / UNKNOWN). + ADR-302 `DomainState` (KNOWN / DEGRADED / UNKNOWN). Each cell carries exactly one `EvidenceLevel` (L0–L5, ADR-282). A slice scored on synthetic input is L0/`Synthetic` by construction; a slice on a leakage-free @@ -86,7 +86,7 @@ accuracy at all. domains carry the strictest budgets because they are the ones a pooled score hides. The baseline is append-only and witness-anchored — a new baseline is a new signed ledger entry, never an in-place overwrite (ADR-149 ledger pattern, - ADR-316 anchoring). + ADR-319 anchoring). ### 3. Sensing-crate CI wiring @@ -102,7 +102,7 @@ accuracy at all. - No benchmark numbers are invented by this ADR. It delivers the scorecard format, the per-domain gate, and the CI wiring; the numbers come from the - ADR-301 evidence ledger and the AetherArena scorer on real data, labelled at + ADR-304 evidence ledger and the AetherArena scorer on real data, labelled at the honest evidence level. Empty domains report "no evidence," which the gate treats as no coverage — never as a pass. @@ -120,7 +120,7 @@ accuracy at all. - Some domains will show weak or absent coverage. Surfacing that per-domain is the point; the scorecard must never paper over a thin domain with a pooled number. -- The program-level acceptance test (ADR-297) is encoded here as an AetherArena +- The program-level acceptance test (ADR-300) is encoded here as an AetherArena scenario, closing the loop once the phase-1 spine lands. ## Validation @@ -132,9 +132,9 @@ accuracy at all. `EvidenceLevel`; synthetic slices are L0 by construction. - Determinism: a scored run reproduces its SHA-256 hash under `PROOF_SEED=42` (ADR-011/ADR-149 binding); the baseline scorecard is append-only and - witness-anchored (ADR-316), never mutated in place. + witness-anchored (ADR-319), never mutated in place. - CI: the sensing-crate gate runs on a PR touching a sensing crate and blocks a planted single-domain regression. -- Real-data scorecards (a leakage-free held-out split with ADR-300 references) +- Real-data scorecards (a leakage-free held-out split with ADR-303 references) are the maturity milestone; a synthetic scorecard is L0 and no per-domain number is MEASURED without a reproducer per CLAUDE.md. diff --git a/docs/adr/ADR-315-capability-certificates.md b/docs/adr/ADR-318-capability-certificates.md similarity index 76% rename from docs/adr/ADR-315-capability-certificates.md rename to docs/adr/ADR-318-capability-certificates.md index 4fc5f242..62783709 100644 --- a/docs/adr/ADR-315-capability-certificates.md +++ b/docs/adr/ADR-318-capability-certificates.md @@ -1,21 +1,21 @@ -# ADR-315: Capability certificates — validated-for-this-environment claims +# ADR-318: Capability certificates — validated-for-this-environment claims -- **Status**: Accepted — initial implementation planned (ADR-297 phase 1) +- **Status**: Accepted — initial implementation planned (ADR-300 phase 1) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: capability, certificate, evidence, provenance, signature, honesty, substrate ## Context -This ADR is primitive 18 of the perception-substrate program (ADR-297) and, +This ADR is primitive 18 of the perception-substrate program (ADR-300) and, per the strategic assessment, among the strongest ideas in the program: it is -where the whole certificate spine becomes a consumable contract. In the ADR-297 -dependency DAG it **consumes the evidence engine (ADR-301)** — a capability +where the whole certificate spine becomes a consumable contract. In the ADR-300 +dependency DAG it **consumes the evidence engine (ADR-304)** — a capability certificate is a signed attestation minted over a slice of that ledger — the -**calibration certificate (ADR-298)** for the environment it is validated -against, and the **RuField signature types (ADR-302 / ADR-260/262/277/279)** to -sign it. It reports domain state via ADR-299 and is anchored in the witness -chain (ADR-316). +**calibration certificate (ADR-301)** for the environment it is validated +against, and the **RuField signature types (ADR-305 / ADR-260/262/277/279)** to +sign it. It reports domain state via ADR-302 and is anchored in the witness +chain (ADR-319). RuView must stop making unconditional capability claims. "Supports presence" is not a true statement — presence detection works in some rooms, on some hardware, @@ -24,10 +24,10 @@ uncalibrated room. A capability is only ever *validated for a specific environment*, and the honest unit of that claim is a signed, expiring certificate, not a feature flag in a README. -The ingredients now exist across the phase-1 spine: ADR-301 accumulates +The ingredients now exist across the phase-1 spine: ADR-304 accumulates per-`(room, device, subject)` accuracy, false-positive rate, drift, and domain -state; ADR-298 produces the signed room fingerprint the environment is keyed to; -ADR-302 provides the authenticated device identity and `CapabilityAttestation` +state; ADR-301 produces the signed room fingerprint the environment is keyed to; +ADR-305 provides the authenticated device identity and `CapabilityAttestation` (BFLD, ADR-141) that bounds *what a device is even attested to sense*; ADR-282 provides the mandatory `EvidenceLevel`. What is missing is the artifact that binds them into a single, verifiable "validated here, until then" claim and the @@ -39,10 +39,10 @@ consumer-side rule that refuses capabilities lacking one. the exact dishonest claim — environment-independent, unsigned, non-expiring, and false the moment the room, device, or subject dynamics differ. 2. **Report raw ledger accuracy to consumers directly.** Rejected: the ledger - (ADR-301) is the source of truth but not a portable, signed, bounded contract; + (ADR-304) is the source of truth but not a portable, signed, bounded contract; handing consumers raw records pushes evidence-weighting and expiry logic into every consumer and drops the single verifiable object. -3. **Mint a signed, expiring `CapabilityCertificate` over an ADR-301 ledger +3. **Mint a signed, expiring `CapabilityCertificate` over an ADR-304 ledger slice, and make consumers refuse capabilities without a valid one.** Chosen. ## Decision @@ -56,38 +56,38 @@ time. A serializable `CapabilityCertificate` binding: - `capability` — the phenomenon (e.g. `presence`, `pose`), which must be within - the device's ADR-302/ADR-141 `CapabilityAttestation` (a device cannot be + the device's ADR-305/ADR-141 `CapabilityAttestation` (a device cannot be certified for something it is not even attested to sense). -- `room` — the ADR-303 space identifier, tied to the ADR-298 calibration +- `room` — the ADR-306 space identifier, tied to the ADR-301 calibration certificate version the validation was performed against. -- `hardware` — the ADR-302 authenticated `DeviceId` (and, in phase 2, the - ADR-317 HAL descriptor of the sensor). +- `hardware` — the ADR-305 authenticated `DeviceId` (and, in phase 2, the + ADR-320 HAL descriptor of the sensor). - `model` — the model version scored. - `calibrated_date` — the calibration certificate age at validation time. - `moving_recall`, `stationary_recall`, `false_presence_per_24h` — the measured - operating metrics, sliced from the ADR-301 ledger for this exact context (not + operating metrics, sliced from the ADR-304 ledger for this exact context (not a global average), each honestly labelled. These are per-capability; a pose certificate carries pose metrics with the mean-pose baseline and a leakage-free split (CLAUDE.md) or it is not issued. - `valid_until` — an explicit expiry; a certificate is never open-ended. - `evidence_level` — exactly one L0–L5 (ADR-282). A certificate minted from a synthetic ledger slice is L0/`Synthetic`; a MEASURED metric requires an - ADR-300 reference and a reproducer. The certificate cannot upgrade the level - of the ledger it is minted from (ADR-301 honesty rule). -- `signature` — a RuField `SignatureBlock` (ADR-302 / ADR-260/262/277/279) over + ADR-303 reference and a reproducer. The certificate cannot upgrade the level + of the ledger it is minted from (ADR-304 honesty rule). +- `signature` — a RuField `SignatureBlock` (ADR-305 / ADR-260/262/277/279) over the canonical serialization; an unsigned certificate is not a valid - certificate. The certificate is anchored in the witness chain (ADR-316). + certificate. The certificate is anchored in the witness chain (ADR-319). ### 2. Minting -- A certificate is minted from a slice of the ADR-301 evidence ledger for one +- A certificate is minted from a slice of the ADR-304 evidence ledger for one `(room, device, subject-class, model)` context. If the ledger reports "no evidence" for that context, **no certificate is issued** — absence of evidence is never a capability. Minting is a pure function over the append-only ledger at mint time; the metrics are frozen into the signed object. -- Expiry (`valid_until`) is derived from calibration validity (ADR-298) and an +- Expiry (`valid_until`) is derived from calibration validity (ADR-301) and an evidence-freshness policy: a certificate cannot outlive the calibration it was - validated against, and drift beyond the ADR-298 envelope invalidates both. + validated against, and drift beyond the ADR-301 envelope invalidates both. ### 3. Consumer refusal rule @@ -95,9 +95,9 @@ A serializable `CapabilityCertificate` binding: certificate for the current environment**. "Valid" means: signature verifies, `room`/`hardware`/`model` match the running context, `valid_until` is in the future, and the referenced calibration certificate is itself still valid - (ADR-298 not invalidated). A failed check yields UNKNOWN via ADR-299, not a + (ADR-301 not invalidated). A failed check yields UNKNOWN via ADR-302, not a best-effort guess. -- This makes the ADR-297 acceptance clause "quantify whether it can reliably +- This makes the ADR-300 acceptance clause "quantify whether it can reliably sense the requested phenomenon → generate a signed capability certificate" a hard gate rather than a hope. @@ -114,10 +114,10 @@ A serializable `CapabilityCertificate` binding: certificate and therefore no capability until validated. That refusal is the intended honest behavior, not a regression. - Key management and expiry policy are operational responsibilities, reusing the - ADR-302 enrollment/rotation and ADR-298 validity machinery rather than new - infrastructure; fleet distribution of certificates is owned by ADR-313. + ADR-305 enrollment/rotation and ADR-301 validity machinery rather than new + infrastructure; fleet distribution of certificates is owned by ADR-316. - No capability number is invented here; every metric on a certificate is sliced - from the ADR-301 ledger at its honest evidence level. + from the ADR-304 ledger at its honest evidence level. ## Validation @@ -125,14 +125,14 @@ A serializable `CapabilityCertificate` binding: frozen metrics; "no evidence" context yields no certificate; signature round-trip and tamper rejection; `valid_until` and calibration-linked expiry enforced; consumer refusal on room/hardware/model mismatch, expiry, or - invalidated calibration resolves to UNKNOWN (ADR-299), not a guess; evidence + invalidated calibration resolves to UNKNOWN (ADR-302), not a guess; evidence level is inherited from the ledger and cannot be upgraded; a certificate - cannot be issued for a capability outside the device's ADR-302/ADR-141 + cannot be issued for a capability outside the device's ADR-305/ADR-141 attestation. -- Cross-ADR: an ADR-301 ledger fixture mints a certificate; an ADR-299 test - asserts an expired/mismatched certificate gates to UNKNOWN; the ADR-297 +- Cross-ADR: an ADR-304 ledger fixture mints a certificate; an ADR-302 test + asserts an expired/mismatched certificate gates to UNKNOWN; the ADR-300 acceptance test consumes a minted certificate end-to-end. -- Real-deployment certificates (minted from a populated ledger with ADR-300 +- Real-deployment certificates (minted from a populated ledger with ADR-303 references on live ESP32 captures) are the maturity milestone and require hardware evidence per CLAUDE.md; a certificate minted from a synthetic ledger is L0 by construction. diff --git a/docs/adr/ADR-316-witness-chain.md b/docs/adr/ADR-319-witness-chain.md similarity index 79% rename from docs/adr/ADR-316-witness-chain.md rename to docs/adr/ADR-319-witness-chain.md index 672b2e2c..cff5bbc3 100644 --- a/docs/adr/ADR-316-witness-chain.md +++ b/docs/adr/ADR-319-witness-chain.md @@ -1,22 +1,22 @@ -# ADR-316: Witness chain — epistemic infrastructure for physical AI +# ADR-319: Witness chain — epistemic infrastructure for physical AI -- **Status**: Accepted — initial implementation planned (ADR-297 phase 1) +- **Status**: Accepted — initial implementation planned (ADR-300 phase 1) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: provenance, witness, evidence, signature, epistemics, ontology, substrate ## Context -This ADR is primitive 19 of the perception-substrate program (ADR-297) and a -spine root of its phase-1 certificate stack. In the ADR-297 dependency DAG it -**extends the source-provenance state machine (ADR-292)** and the RuField -provenance types, **ties to the signature machinery (ADR-302 / -ADR-260/262/277/279)**, and anchors the artifacts produced by ADR-298 -(calibration certificates), ADR-301 (evidence records), ADR-314 (benchmark -scorecards), and ADR-315 (capability certificates). In phase 2 it carries the -independent-corroboration link from ADR-300. +This ADR is primitive 19 of the perception-substrate program (ADR-300) and a +spine root of its phase-1 certificate stack. In the ADR-300 dependency DAG it +**extends the source-provenance state machine (ADR-295)** and the RuField +provenance types, **ties to the signature machinery (ADR-305 / +ADR-260/262/277/279)**, and anchors the artifacts produced by ADR-301 +(calibration certificates), ADR-304 (evidence records), ADR-317 (benchmark +scorecards), and ADR-318 (capability certificates). In phase 2 it carries the +independent-corroboration link from ADR-303. -The strategic assessment (ADR-297) framed RuView's real product as **epistemic +The strategic assessment (ADR-300) framed RuView's real product as **epistemic infrastructure for physical AI**: the value is not the claim "a person is present" but the *auditable reasoning* behind it. A bare boolean output discards everything a downstream system needs to trust or contest it — which radio @@ -24,10 +24,10 @@ observed it, what DSP evidence supported it, which model inferred it, whether an independent sensor agreed, what spatial state it updated, and what policy acted on it. Once the answer is a boolean, "why do you believe that?" has no answer. -RuView already has the pieces of a chain but not the chain itself. ADR-292 +RuView already has the pieces of a chain but not the chain itself. ADR-295 defines a canonical `SourceState` (`Synthetic` / `LiveVerified` / `LiveUnverified` / `Stale` / `Disconnected`) with `Unknown` structurally -forbidden from collapsing to live. ADR-302 defines the signed +forbidden from collapsing to live. ADR-305 defines the signed `device → measurement → sequence → timestamp → … → signed event` chain of custody. RuField carries `FrameProvenance`, `SemanticProvenance`, and signature types; the AetherArena witness ledger (ADR-149) demonstrates an append-only, @@ -43,7 +43,7 @@ provenance of that stage. single object a consumer can re-verify offline to answer "why." 2. **Log a free-form audit trail alongside the output.** Rejected: mutable, unsigned, and not structurally tied to the output — the classic - dashboard-that-overwrites-yesterday failure the evidence engine (ADR-301) + dashboard-that-overwrites-yesterday failure the evidence engine (ADR-304) already rejects. 3. **A staged, signed witness envelope carried through the pipeline, each stage appended and signed, anchored in an append-only ledger.** Chosen. @@ -63,23 +63,23 @@ RF observation ▸ DSP evidence ▸ model inference ▸ independent corroboratio - Each stage is a signed record carrying its **confidence** and its **provenance**: - - **RF observation** — the ADR-302 authenticated frame envelope - (`DeviceId`, sequence, timestamp, measurement hash) and its ADR-292 + - **RF observation** — the ADR-305 authenticated frame envelope + (`DeviceId`, sequence, timestamp, measurement hash) and its ADR-295 `SourceState`. This is the root link; a `Synthetic` root can never present - as a `LiveVerified` one (ADR-292 invariant). + as a `LiveVerified` one (ADR-295 invariant). - **DSP evidence** — the deterministic signal features and the ADR-137 quality signals that support (or fail to support) an inference. - **model inference** — the model version, its raw output, and its predictive - uncertainty; the ADR-299 `DomainState` (KNOWN / DEGRADED / UNKNOWN) gate + uncertainty; the ADR-302 `DomainState` (KNOWN / DEGRADED / UNKNOWN) gate result, so a low-confidence or out-of-distribution inference is recorded as such, not silently promoted. - - **independent corroboration** — the phase-2 ADR-300 agreement link + - **independent corroboration** — the phase-2 ADR-303 agreement link (a reference/second modality that agreed or disagreed); absent in phase 1, the stage records "no corroboration," never a fabricated one. - - **spatial state** — the ADR-303 ontology `Observation`/`Track`/`Event` the + - **spatial state** — the ADR-306 ontology `Observation`/`Track`/`Event` the inference updated, carrying `SemanticProvenance` and its `EvidenceLevel`. - **policy decision** — the governed action taken (or withheld), with the - certificate (ADR-315) it relied on. + certificate (ADR-318) it relied on. - Each stage carries exactly one `EvidenceLevel` (L0–L5, ADR-282); the envelope's effective level is the **minimum** across its stages — a synthetic root or an unreferenced inference caps the whole chain, so the chain cannot claim more @@ -87,23 +87,23 @@ RF observation ▸ DSP evidence ▸ model inference ▸ independent corroboratio ### 2. Signing and anchoring -- Each stage is signed with RuField signature types (ADR-302 / +- Each stage is signed with RuField signature types (ADR-305 / ADR-260/262/277/279) over the canonical serialization of that stage plus the hash of the prior stage, so the chain is tamper-evident end to end and any broken link is detectable. The completed chain is anchored in an append-only, witness-anchored ledger following the AetherArena pattern (ADR-149); it is the - same anchoring ADR-298/ADR-301/ADR-314/ADR-315 write into. + same anchoring ADR-301/ADR-304/ADR-317/ADR-318 write into. - The chain is **append-only**: a correction is a new chain referencing the - prior one, never an in-place edit (mirroring ADR-301 and CLAUDE.md's "source + prior one, never an in-place edit (mirroring ADR-304 and CLAUDE.md's "source over summaries"). ### 3. Offline re-verification -- A consumer with the enrolled public keys (ADR-302) can re-verify a chain +- A consumer with the enrolled public keys (ADR-305) can re-verify a chain offline: check each stage signature, check each prior-stage hash, and read the per-stage confidence and evidence level — answering "why do you believe this?" without trusting the emitting host. This is the property store-and-forward - channel authentication (rejected in ADR-302) cannot provide. + channel authentication (rejected in ADR-305) cannot provide. ### Provenance and honesty discipline @@ -119,7 +119,7 @@ RF observation ▸ DSP evidence ▸ model inference ▸ independent corroboratio system can inspect the reasoning, weight it by per-stage confidence, and reject a chain whose weakest link is too weak — the defining property of epistemic infrastructure the strategic assessment asked for. -- The certificate spine (ADR-298/301/314/315) gains a single anchoring substrate; +- The certificate spine (ADR-301/301/314/315) gains a single anchoring substrate; each of those artifacts is a specialization of a witness record rather than a bespoke signed blob. - Carrying and signing a staged envelope adds per-observation size and CPU cost; @@ -135,12 +135,12 @@ RF observation ▸ DSP evidence ▸ model inference ▸ independent corroboratio and tamper rejection (a mutated stage or a broken prior-stage hash fails verification); effective evidence level equals the minimum across stages; a `Synthetic` root caps the chain and cannot present as `LiveVerified` - (ADR-292 invariant); an UNKNOWN gate (ADR-299) and a "no corroboration" stage + (ADR-295 invariant); an UNKNOWN gate (ADR-302) and a "no corroboration" stage are recorded faithfully; append-only correction produces a new chain referencing the prior one. -- Cross-ADR: an ADR-302 signed frame lineage serializes into a chain that - re-verifies offline with only the enrolled public keys; ADR-298/301/314/315 +- Cross-ADR: an ADR-305 signed frame lineage serializes into a chain that + re-verifies offline with only the enrolled public keys; ADR-301/301/314/315 artifacts anchor into the same ledger. -- Real-deployment chains (from live ESP32 captures with ADR-300 corroboration) +- Real-deployment chains (from live ESP32 captures with ADR-303 corroboration) are the maturity milestone and require hardware evidence per CLAUDE.md; a chain rooted in synthetic input is L0 by construction. diff --git a/docs/adr/ADR-317-sensor-hal.md b/docs/adr/ADR-320-sensor-hal.md similarity index 83% rename from docs/adr/ADR-317-sensor-hal.md rename to docs/adr/ADR-320-sensor-hal.md index e3c7ca36..ae3ea153 100644 --- a/docs/adr/ADR-317-sensor-hal.md +++ b/docs/adr/ADR-320-sensor-hal.md @@ -1,18 +1,18 @@ -# ADR-317: RuView sensor HAL — abstract all sensing hardware to one Observation type +# ADR-320: RuView sensor HAL — abstract all sensing hardware to one Observation type -- **Status**: Accepted — initial implementation (ADR-297 phase 2) +- **Status**: Accepted — initial implementation (ADR-300 phase 2) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: hal, sensor-abstraction, ontology, fusion, adapters, category, phase-2 ## Context -This ADR is primitive 20 of the perception-substrate program (ADR-297) and a -phase-2 integration primitive; it is authored as **Proposed**. In the ADR-297 -DAG it **consumes the canonical spatial ontology (ADR-303)** — its output is an +This ADR is primitive 20 of the perception-substrate program (ADR-300) and a +phase-2 integration primitive; it is authored as **Proposed**. In the ADR-300 +DAG it **consumes the canonical spatial ontology (ADR-306)** — its output is an ontology `Observation` bound to a `Sensor` entity — and **feeds real sensor -fusion (ADR-308)**, which resolves many observations into one world state. It -closes the "identify the hardware" clause of the ADR-297 acceptance test that +fusion (ADR-311)**, which resolves many observations into one world state. It +closes the "identify the hardware" clause of the ADR-300 acceptance test that phase 1 leaves open. RuView's strategic ceiling is set by how tightly it is coupled to WiFi CSI. @@ -35,7 +35,7 @@ must be reused, not rebuilt: - Existing CSI adapters (ESP32/Nexmon/FeitCSI paths), the mmWave fusion path (ADR-063), and the multistatic WiFi path (ADR-029) are concrete producers to bring under one trait. -- ADR-302 already authenticates a `Sensor`/`DeviceId`; ADR-303 already defines +- ADR-305 already authenticates a `Sensor`/`DeviceId`; ADR-306 already defines `Sensor`, `Observation`, `Track`, and `Event` as first-class node types. The HAL is the trait that turns a heterogeneous device into that authenticated `Sensor` emitting those `Observation`s. @@ -55,7 +55,7 @@ only a provenance-bearing, evidence-labelled `Observation`. has no meaningful `RfFrameV2` projection; forcing one is the same mistake at a larger scale. 3. **Define a `SensorHal` trait producing one `Observation` type, with existing - adapters as implementations feeding a shared latent and the ADR-303 + adapters as implementations feeding a shared latent and the ADR-306 ontology.** Chosen. ## Decision @@ -67,39 +67,39 @@ only `Observation`s. ### 1. The `SensorHal` trait - A `SensorHal` describes a device's **capabilities** (which phenomena it can - sense — reusing the ADR-302/ADR-141 `CapabilityAttestation`), its **native + sense — reusing the ADR-305/ADR-141 `CapabilityAttestation`), its **native frame** (kept native, not canonicalized, per the ADR-279 shared-latent lesson), and a method that lifts a native frame into an `Observation`. - Implementations wrap the existing producers: CSI (ESP32/Nexmon/FeitCSI via the - ADR-279 `RfFrameV2` path), 802.11bf (ADR-307, phase 2), BLE, UWB, mmWave + ADR-279 `RfFrameV2` path), 802.11bf (ADR-310, phase 2), BLE, UWB, mmWave (ADR-063), acoustic, camera, lidar, IMU, and `custom`. RF modalities reuse the ADR-279 per-device latent adapters wholesale; the HAL adds the non-RF and ranging modalities under the same trait. - The trait is the boundary where untrusted hardware input is validated (CLAUDE.md: validate at every hardware/FFI boundary; default to least - authority). A device is authenticated as an ADR-302 `Sensor` before its + authority). A device is authenticated as an ADR-305 `Sensor` before its observations are trusted. ### 2. The `Observation` type - One provenance-bearing `Observation`: a measurement plus its `SensorHal` - source descriptor, its ADR-302 authenticated `DeviceId`, its ADR-292 + source descriptor, its ADR-305 authenticated `DeviceId`, its ADR-295 `SourceState`, its native-frame reference (not a lossy projection), and exactly one `EvidenceLevel` (L0–L5, ADR-282). A camera-derived `Observation` and a CSI-derived `Observation` are the same type with different provenance — and a camera observation never lifts WiFi output to camera-grade; each carries its own honest evidence level (CLAUDE.md: never present WiFi sensing as camera-grade). -- The `Observation` maps directly onto the ADR-303 ontology `Observation` node +- The `Observation` maps directly onto the ADR-306 ontology `Observation` node attached to its `Sensor`, so the ontology is the one representation and the HAL is its ingest funnel. ### 3. Feeding fusion -- Observations from any set of modalities flow into ADR-308 fusion, which +- Observations from any set of modalities flow into ADR-311 fusion, which resolves them into one probabilistic world state. The HAL guarantees fusion never sees a modality-specific frame — only `Observation`s with uniform - provenance and evidence — which is what makes ADR-308's "many observations → + provenance and evidence — which is what makes ADR-311's "many observations → one world state" invariant implementable across heterogeneous hardware. ### Category and honesty discipline @@ -107,7 +107,7 @@ only `Observation`s. - This ADR changes RuView's category from a WiFi-DensePose pipeline to an open spatial-intelligence operating layer, but it makes **no accuracy claim**: the HAL delivers a uniform ingest boundary, not a detector. Any capability of a - newly-connected sensor is still gated by ADR-299 and certified by ADR-315 for + newly-connected sensor is still gated by ADR-302 and certified by ADR-318 for its specific environment — connecting a camera does not grant a validated capability by itself. - Hardware support for a given modality is CLAIMED until demonstrated on real @@ -118,10 +118,10 @@ only `Observation`s. - New sensing hardware lands as one `SensorHal` implementation instead of a bespoke pipeline; the translation matrix stays O(modalities), mirroring how - ADR-303 collapsed the surface matrix. -- The ADR-297 acceptance clause "identify the hardware" becomes implementable: - a new sensor type is described by its HAL, authenticated as an ADR-302 - `Sensor`, calibrated (ADR-298), gated (ADR-299), and certified (ADR-315) + ADR-306 collapsed the surface matrix. +- The ADR-300 acceptance clause "identify the hardware" becomes implementable: + a new sensor type is described by its HAL, authenticated as an ADR-305 + `Sensor`, calibrated (ADR-301), gated (ADR-302), and certified (ADR-318) through the same phase-1 spine, closing the last open clause. - A trait boundary and an `Observation` type are added; existing RF adapters are re-expressed as implementations rather than rewritten, preserving the @@ -129,8 +129,8 @@ only `Observation`s. - Non-RF modalities (camera, lidar, acoustic) enter the governed plane with the same provenance and privacy discipline as RF; a camera is not a privacy-free shortcut — it inherits the ADR-277 governance and its own evidence level. -- As a phase-2 Proposed ADR, the trait shape may be revised as ADR-308 fusion - and ADR-307 802.11bf land; that revision is expected for a phased program. +- As a phase-2 Proposed ADR, the trait shape may be revised as ADR-311 fusion + and ADR-310 802.11bf land; that revision is expected for a phased program. ## Validation @@ -140,10 +140,10 @@ only `Observation`s. `SourceState`, native-frame reference, and exactly one `EvidenceLevel`; a synthetic source yields L0/`Synthetic` and cannot alias to measured (ADR-279 invariant 6); an unauthenticated device's observations are rejected - at the trait boundary (ADR-302). -- Cross-ADR: an `Observation` maps round-trip to an ADR-303 ontology + at the trait boundary (ADR-305). +- Cross-ADR: an `Observation` maps round-trip to an ADR-306 ontology `Observation` node with no provenance loss, and a set of `Observation`s from - distinct modalities is accepted by an ADR-308 fusion fixture. + distinct modalities is accepted by an ADR-311 fusion fixture. - Real-silicon evidence is required before any modality's hardware support is claimed beyond CLAIMED: a captured boot/runtime log from the real device emitting `Observation`s. A successful build or simulator run is not hardware diff --git a/docs/adr/ADR-318-decision-policy-action-authorization.md b/docs/adr/ADR-321-decision-policy-action-authorization.md similarity index 83% rename from docs/adr/ADR-318-decision-policy-action-authorization.md rename to docs/adr/ADR-321-decision-policy-action-authorization.md index fc3a6dbd..8b707723 100644 --- a/docs/adr/ADR-318-decision-policy-action-authorization.md +++ b/docs/adr/ADR-321-decision-policy-action-authorization.md @@ -1,14 +1,14 @@ -# ADR-318: Decision policy — action authorization conditioned on certificate class, freshness, uncertainty, and evidence +# ADR-321: Decision policy — action authorization conditioned on certificate class, freshness, uncertainty, and evidence -- **Status**: Accepted — initial implementation planned (ADR-297 phase 1) +- **Status**: Accepted — initial implementation planned (ADR-300 phase 1) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: policy, authorization, safety, certificates, governed-action, phase-1 ## Context -The perception substrate (ADR-297) makes RuView state *what it knows* and -*how well* — the capability certificate (ADR-315) binds hardware, environment, +The perception substrate (ADR-300) makes RuView state *what it knows* and +*how well* — the capability certificate (ADR-318) binds hardware, environment, model, calibration, metrics, expiry, and evidence level. But a certificate is a statement of knowledge, not a grant of action. The same certificate that is adequate to dim a light is wholly inadequate to release a door lock or clear an @@ -34,13 +34,13 @@ that sits between governed spatial state and any actuator. An `ActionClass` declares the assurance an action demands: -- `min_certificate_class` — the required `CapabilityCertificate` class (ADR-315). +- `min_certificate_class` — the required `CapabilityCertificate` class (ADR-318). - `max_certificate_age` / `min_domain_freshness` — the certificate must be - currently valid **and** the live domain signature (ADR-299) must not be in a + currently valid **and** the live domain signature (ADR-302) must not be in a DEGRADED/UNKNOWN state (this is the staleness guard, program invariant on - certificate conditionality — see ADR-297). + certificate conditionality — see ADR-300). - `max_uncertainty` — inference uncertainty ceiling. -- `min_evidence_level` — the L0–L5 floor (ADR-282/ADR-301); e.g. a safety +- `min_evidence_level` — the L0–L5 floor (ADR-282/ADR-304); e.g. a safety action may require ≥ L3 (held-out room+subject validation). Reference action classes (illustrative, configurable): @@ -54,20 +54,20 @@ Reference action classes (illustrative, configurable): ### 2. The authorization decision `authorize(action, capability_certificate, live_state) -> Authorization` where -`live_state` carries the current `SourceState` (ADR-292), OOD/domain state -(ADR-299), and inference uncertainty. Rules: +`live_state` carries the current `SourceState` (ADR-295), OOD/domain state +(ADR-302), and inference uncertainty. Rules: - **Fail-closed.** Any unmet condition → `Deny { failed_condition }`. The denial names the *specific* condition (expired cert, domain DEGRADED, uncertainty over ceiling, evidence below floor, certificate class too low). -- **UNKNOWN denies high-assurance actions.** A domain in UNKNOWN (ADR-299) +- **UNKNOWN denies high-assurance actions.** A domain in UNKNOWN (ADR-302) cannot authorize `Security`/`SafetyCritical` actions; it may still authorize `Convenience` if that class's policy permits, but the authorization records that it proceeded under UNKNOWN. - The decision is a **pure function** of (action class, certificate, live state) — deterministic and unit-testable without a clock or actuator. - Every authorization (allow or deny) is emitted as the terminal stage of the - witness chain (ADR-316), so "why was this actuator allowed/denied" is + witness chain (ADR-319), so "why was this actuator allowed/denied" is auditable end-to-end. ### 3. No silent optimism @@ -83,8 +83,8 @@ all deny by default. Absence of a policy is not permission. - A behavior change for existing automations that acted directly on presence: they now pass through the gate. Convenience-class defaults keep low-stakes automations working; high-stakes actions must opt into stricter classes. -- Depends on ADR-315 (certificate), ADR-299 (domain/OOD state), ADR-292 - (source state), ADR-301 (evidence). Built in the phase-1 dependent wave after +- Depends on ADR-318 (certificate), ADR-302 (domain/OOD state), ADR-295 + (source state), ADR-304 (evidence). Built in the phase-1 dependent wave after those types land. ## Validation @@ -94,7 +94,7 @@ all deny by default. Absence of a policy is not permission. above/below ceiling × evidence above/below floor); UNKNOWN denies safety-critical; every deny names its failed condition; absence-of-policy denies; determinism. -- Integration: the acceptance-test scenario (ADR-297) — post-certification room +- Integration: the acceptance-test scenario (ADR-300) — post-certification room change drives domain to DEGRADED→UNKNOWN, and a `SafetyCritical` authorization is denied with `failed_condition = domain_not_known` *before* the inference reaches the actuator, witness chain preserved. diff --git a/docs/adr/README.md b/docs/adr/README.md index 040d450d..30b240f6 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -145,37 +145,40 @@ Statuses: **Proposed** (under discussion), **Accepted** (approved and/or impleme | [ADR-287](ADR-287-coherent-wideband-rf-tomography-crate.md) | `wifi-densepose-sar` — coherent wideband RF tomography research crate | Accepted (implemented, published) | | [ADR-285](ADR-285-homecore-wasm-first-metaharness.md) | WASM-first Homecore developer metaharness via `npx homecore` | Accepted (implemented and validated) | | [ADR-286](ADR-286-wifi-densepose-sar-harness-via-metaharness.md) | `wifi-densepose-sar-harness` — MetaHarness with darwin/router/flywheel | Accepted (implemented, published) | -| [ADR-288](ADR-288-public-benchmark-evaluation-harness.md) | Public-benchmark evaluation harness — Widar3.0 ingest, split protocols, leakage guards | Accepted (initial implementation) | -| [ADR-289](ADR-289-wideband-80211ax-csi-ingest.md) | Wideband 802.11ax CSI ingest — FeitCSI/AX210 adapter, subcarrier-agnostic plumbing | Accepted (initial implementation) | -| [ADR-290](ADR-290-vitals-ground-truth-rig.md) | Vitals ground-truth rig — reference ingest, alignment, agreement metrics | Accepted (initial implementation) | -| [ADR-291](ADR-291-wifi-veil-integration.md) | WiFi Veil integration — emission-shaping countermeasure as advisory BFLD dependency | Accepted (initial implementation) | -| [ADR-292](ADR-292-source-provenance-state-machine.md) | Source provenance state machine — synthetic can never present as live | Accepted (initial implementation) | -| [ADR-293](ADR-293-sensor-data-plane-bind-hardening.md) | Sensor data-plane hardening — UDP bind control and source allowlist (step one) | Accepted (initial implementation) | -| [ADR-294](ADR-294-multi-node-semantic-correctness.md) | Multi-node semantic correctness — per-node inference, node-keyed rate limiting, stale state | Accepted (initial implementation) | -| [ADR-295](ADR-295-model-release-sanity-gates.md) | Model release sanity gates — block degenerate and mislabeled model artifacts | Accepted (initial implementation) | -| [ADR-296](ADR-296-csi-data-incident-repo-controls.md) | Repository CSI data-incident controls — ignore rules and pre-commit/CI policy check | Accepted (controls implemented; tree remediation gated) | -| [ADR-297](ADR-297-perception-substrate-program.md) | RuView perception substrate — phased 21-primitive program (calibration, evidence, trust, deployment) | Accepted (program; children ADR-298..317) | -| [ADR-298](ADR-298-automatic-domain-calibration.md) | Automatic domain calibration — signed, versioned, invalidatable room fingerprint | Accepted (phase 1) | -| [ADR-299](ADR-299-out-of-distribution-detection.md) | Out-of-distribution detection — KNOWN / DEGRADED / UNKNOWN gating | Accepted (phase 1) | -| [ADR-300](ADR-300-ground-truth-synchronization.md) | Ground-truth synchronization — reference sensors as a formal validation plane | Proposed (phase 2) | -| [ADR-301](ADR-301-evidence-engine.md) | Evidence engine — per-(room,device,subject) accuracy ledger | Accepted (phase 1) | -| [ADR-302](ADR-302-authenticated-sensor-identity.md) | Authenticated sensor identity — RF chain of custody | Accepted (phase 1) | -| [ADR-303](ADR-303-canonical-spatial-ontology.md) | Canonical spatial ontology — one Site→…→Event model for every surface | Accepted (phase 1) | -| [ADR-304](ADR-304-persistent-identity-tracking.md) | Persistent identity & tracking — privacy-preserving probabilistic tracks | Proposed (phase 2) | -| [ADR-305](ADR-305-sensor-placement-optimizer.md) | Sensor placement optimizer — floorplan + inventory → recommended positions | Proposed (phase 3) | -| [ADR-306](ADR-306-active-sensing.md) | Active sensing — closed-loop RF experiment control | Proposed (phase 3) | -| [ADR-307](ADR-307-80211bf-native-architecture.md) | 802.11bf-native architecture — standardized WLAN sensing as native measurement types | Proposed (phase 2) | -| [ADR-308](ADR-308-real-sensor-fusion.md) | Real sensor fusion — uncertainty-aware, multiple observations → one world state | Proposed (phase 2) | -| [ADR-309](ADR-309-long-term-spatial-memory.md) | Long-term spatial memory — learn the normal physics of a location | Proposed (phase 3) | -| [ADR-310](ADR-310-counterfactual-inference.md) | Counterfactual inference — generative spatial reasoning | Proposed (phase 3) | -| [ADR-311](ADR-311-information-gain-scheduler.md) | Information-gain scheduler — sample the most informative radios | Proposed (phase 3) | -| [ADR-312](ADR-312-digital-rf-twin.md) | Digital RF twin — persistent per-deployment RF model | Proposed (phase 3) | -| [ADR-313](ADR-313-fleet-control-plane.md) | Fleet control plane — provisioning to audit trails | Proposed (phase 2) | -| [ADR-314](ADR-314-benchmark-multi-domain-scorecard.md) | Multi-domain benchmark scorecard — regressions cannot hide behind pooled accuracy | Accepted (phase 1) | -| [ADR-315](ADR-315-capability-certificates.md) | Capability certificates — validated-for-this-environment claims | Accepted (phase 1) | -| [ADR-316](ADR-316-witness-chain.md) | Witness chain — staged, signed epistemic envelope | Accepted (phase 1) | -| [ADR-317](ADR-317-sensor-hal.md) | RuView sensor HAL — abstract all sensing hardware to one Observation type | Proposed (phase 2) | -| [ADR-318](ADR-318-decision-policy-action-authorization.md) | Decision policy — action authorization conditioned on certificate class, freshness, uncertainty, evidence | Accepted (phase 1) | +| [ADR-288](ADR-288-veil-privacy-shield-compliant-waveform.md) | VEIL — compliant-waveform privacy shield against unauthorized WiFi sensing (`wifi-densepose-privshield`) | Proposed (implemented, P1 reference) | +| [ADR-289](ADR-289-wifi-densepose-privshield-harness-via-metaharness.md) | `wifi-densepose-privshield-harness` — npm MetaHarness for the VEIL crate (guidance/router/flywheel) | Proposed (implemented, P1) | +| [ADR-290](ADR-290-veil-e2e-hardware-implementation-program.md) | VEIL end-to-end hardware implementation program — portable C core + multi-provider firmware scaffolds (openwifi/openwrt/nexmon/esp32) | Proposed (P4 scaffolding; C core host-validated) | +| [ADR-291](ADR-291-public-benchmark-evaluation-harness.md) | Public-benchmark evaluation harness — Widar3.0 ingest, split protocols, leakage guards | Accepted (initial implementation) | +| [ADR-292](ADR-292-wideband-80211ax-csi-ingest.md) | Wideband 802.11ax CSI ingest — FeitCSI/AX210 adapter, subcarrier-agnostic plumbing | Accepted (initial implementation) | +| [ADR-293](ADR-293-vitals-ground-truth-rig.md) | Vitals ground-truth rig — reference ingest, alignment, agreement metrics | Accepted (initial implementation) | +| [ADR-294](ADR-294-wifi-veil-integration.md) | WiFi Veil integration — emission-shaping countermeasure as advisory BFLD dependency | Accepted (initial implementation) | +| [ADR-295](ADR-295-source-provenance-state-machine.md) | Source provenance state machine — synthetic can never present as live | Accepted (initial implementation) | +| [ADR-296](ADR-296-sensor-data-plane-bind-hardening.md) | Sensor data-plane hardening — UDP bind control and source allowlist (step one) | Accepted (initial implementation) | +| [ADR-297](ADR-297-multi-node-semantic-correctness.md) | Multi-node semantic correctness — per-node inference, node-keyed rate limiting, stale state | Accepted (initial implementation) | +| [ADR-298](ADR-298-model-release-sanity-gates.md) | Model release sanity gates — block degenerate and mislabeled model artifacts | Accepted (initial implementation) | +| [ADR-299](ADR-299-csi-data-incident-repo-controls.md) | Repository CSI data-incident controls — ignore rules and pre-commit/CI policy check | Accepted (controls implemented; tree remediation gated) | +| [ADR-300](ADR-300-perception-substrate-program.md) | RuView perception substrate — phased 21-primitive program (calibration, evidence, trust, deployment) | Accepted (program; children ADR-301..317) | +| [ADR-301](ADR-301-automatic-domain-calibration.md) | Automatic domain calibration — signed, versioned, invalidatable room fingerprint | Accepted (phase 1) | +| [ADR-302](ADR-302-out-of-distribution-detection.md) | Out-of-distribution detection — KNOWN / DEGRADED / UNKNOWN gating | Accepted (phase 1) | +| [ADR-303](ADR-303-ground-truth-synchronization.md) | Ground-truth synchronization — reference sensors as a formal validation plane | Proposed (phase 2) | +| [ADR-304](ADR-304-evidence-engine.md) | Evidence engine — per-(room,device,subject) accuracy ledger | Accepted (phase 1) | +| [ADR-305](ADR-305-authenticated-sensor-identity.md) | Authenticated sensor identity — RF chain of custody | Accepted (phase 1) | +| [ADR-306](ADR-306-canonical-spatial-ontology.md) | Canonical spatial ontology — one Site→…→Event model for every surface | Accepted (phase 1) | +| [ADR-307](ADR-307-persistent-identity-tracking.md) | Persistent identity & tracking — privacy-preserving probabilistic tracks | Proposed (phase 2) | +| [ADR-308](ADR-308-sensor-placement-optimizer.md) | Sensor placement optimizer — floorplan + inventory → recommended positions | Proposed (phase 3) | +| [ADR-309](ADR-309-active-sensing.md) | Active sensing — closed-loop RF experiment control | Proposed (phase 3) | +| [ADR-310](ADR-310-80211bf-native-architecture.md) | 802.11bf-native architecture — standardized WLAN sensing as native measurement types | Proposed (phase 2) | +| [ADR-311](ADR-311-real-sensor-fusion.md) | Real sensor fusion — uncertainty-aware, multiple observations → one world state | Proposed (phase 2) | +| [ADR-312](ADR-312-long-term-spatial-memory.md) | Long-term spatial memory — learn the normal physics of a location | Proposed (phase 3) | +| [ADR-313](ADR-313-counterfactual-inference.md) | Counterfactual inference — generative spatial reasoning | Proposed (phase 3) | +| [ADR-314](ADR-314-information-gain-scheduler.md) | Information-gain scheduler — sample the most informative radios | Proposed (phase 3) | +| [ADR-315](ADR-315-digital-rf-twin.md) | Digital RF twin — persistent per-deployment RF model | Proposed (phase 3) | +| [ADR-316](ADR-316-fleet-control-plane.md) | Fleet control plane — provisioning to audit trails | Proposed (phase 2) | +| [ADR-317](ADR-317-benchmark-multi-domain-scorecard.md) | Multi-domain benchmark scorecard — regressions cannot hide behind pooled accuracy | Accepted (phase 1) | +| [ADR-318](ADR-318-capability-certificates.md) | Capability certificates — validated-for-this-environment claims | Accepted (phase 1) | +| [ADR-319](ADR-319-witness-chain.md) | Witness chain — staged, signed epistemic envelope | Accepted (phase 1) | +| [ADR-320](ADR-320-sensor-hal.md) | RuView sensor HAL — abstract all sensing hardware to one Observation type | Proposed (phase 2) | +| [ADR-321](ADR-321-decision-policy-action-authorization.md) | Decision policy — action authorization conditioned on certificate class, freshness, uncertainty, evidence | Accepted (phase 1) | --- diff --git a/docs/research/privacy-shield/01-sota-survey.md b/docs/research/privacy-shield/01-sota-survey.md new file mode 100644 index 00000000..79a91063 --- /dev/null +++ b/docs/research/privacy-shield/01-sota-survey.md @@ -0,0 +1,141 @@ +# 01 — State of the Art + +Scope: what a passive or active adversary can extract about *who* is in a space +and *what they are doing* from WiFi, the standard that broadens that surface, and +the countermeasures that try to prevent it. Claims are tagged **MEASURED** (from +a primary source, with metric), **CLAIMED** (asserted without an independent +measurement), or analytical inference (flagged). + +--- + +## 1. The attack surface: beamforming feedback (BFI) + +Since WiFi 5 (802.11ac), a client (beamformee) measures the downlink channel, +compresses the steering matrix **V** into **Givens-rotation angles φ/ψ**, and +transmits them **in cleartext** so the AP can steer beams. Anyone in monitor +mode can capture these frames for *every* client simultaneously — no network +access, and the target need carry no device. Quantization is coarse (802.11ac +angle steps of π/4…π/32 rad) yet retains rich motion and body information. + +| Work | Venue / year | Result | Label | +|---|---|---|---| +| **BFId** — identity inference from BFI | ACM CCS 2025 (KIT/KASTEL) | Re-identifies individuals from BFI alone; novel 197-person dataset. Press reports **99.5%** in a controlled study (ACM full text was not openable to confirm class count/split) | MEASURED (paper); 99.5% is CLAIMED via press | +| **LeakyBeam** — occupancy through walls | NDSS 2025 | Occupancy detection **TPR 82.7% / TNR 96.7%** at **20 m, through walls**, from plaintext BFI. Proposes a BFI-obfuscation defense | MEASURED (attack); defense overhead CLAIMED | +| **BFIAttack** — CSI reconstruction from BFI | arXiv 2026 (USF) | Reconstructs CSI from BFI, then defeats CSI defenses. ASR: device auth 95.5% / user auth 92.6% / key-gen 94.2% (single-antenna), 1.5–6 m | MEASURED | +| **BeamSense** — activity recognition from BFI | Computer Networks vol. 258, 2025 (Northeastern) | Human activity recognition **up to 99.28%** on commodity 802.11ac, no firmware mod, ~10% better than CSI | MEASURED | +| **Wi-BFI** — capture tooling | arXiv 2309.04408, 2023 | Pip-installable extraction of 802.11 BFI from commercial devices | tooling | + +**Takeaway for the defender.** BFI is the highest-leverage surface: unencrypted, +management-plane, device-free, capturable en masse with off-the-shelf tools. It +is also a *stepping stone* — BFIAttack shows BFI can reconstruct the CSI that all +older attacks assume. + +--- + +## 2. The older adjacent surface: CSI identity/gait/activity + +CSI requires special extraction (Intel 5300 / Atheros / ESP32) but is the +foundation the BFI attacks build on. Person-ID exploits **gait** as a biometric. +Representative MEASURED results (commodity WiFi, CSI amplitude): + +| System | Accuracy | N (candidates) | Note | +|---|---|---|---| +| WiWho (IPSN 2016) | 92%→80% | 2→6 | 2–3 m straight walk | +| WiFi-ID (2016) | 93%→77% | 2→6 | wavelet features | +| WiPIN (2018) | 92–100% | ≤30 | operation-free | +| Deep-WiID (2019) | 92.5–99.7% | 6→15 | GRU | +| WiNet / LWID (2020) | 98.5% / 98.8% | 40 / 50 | CNN | + +**Pattern the defender must exploit and not overstate:** accuracy is high in +small closed sets but *degrades as N grows and conditions become realistic* +(cross-day, cross-location, cross-walking-style). Chance is **1/N**; a 99% result +on N=5 is far weaker evidence than 99% on N=197. Open-world scale is largely +unproven (see *SoK: Security Evaluation of Wi-Fi CSI Biometrics*, 2025). + +--- + +## 3. The standard: IEEE 802.11bf-2025 + +IEEE Std **802.11bf-2025** (Amendment 4: *Enhancements for WLAN Sensing*) was +published **26 September 2025**. It standardizes WLAN sensing in 1–7.125 GHz and +above 45 GHz, defining sensing capability signaling, measurement/sounding +setup, feedback types, and both passive (ambient-traffic) and active +(dedicated null-packet) sensing modes. + +- **Attack-surface implication (analytical).** 802.11bf turns CSI/measurement + acquisition from proprietary hacks into open, vendor-agnostic, machine-readable + MAC signaling across heterogeneous devices — institutionalizing exactly the + measurements the BFI attacks abuse. The standard frames sensing as a feature, + not a threat. +- **The privacy gap (MEASURED from standards minutes).** A 2023 proposal for a + BFI "secure transmission mechanism" (IEEE 802.11-23/0782) was **withdrawn**; + "the group did not align on the characterization of [the] privacy problem." + The standard shipped without privacy protections, and its own analysis admits + passive eavesdroppers can extract location, respiration, heart rate, and + identity. + +--- + +## 4. Countermeasures (the defense literature) + +All operate on the defender's *own* transmissions; none are jamming. + +| Countermeasure | Venue / year | Mechanism | Effect | Label | +|---|---|---|---|---| +| **IRShield** | IEEE S&P 2022 | IRS/reconfigurable surface randomizes reflected paths | Attacker motion-detection **≤5%** | MEASURED | +| **PhyCloak** | USENIX NSDI 2016 | Full-duplex obfuscator injects Doppler/phase distortion into sensing only | **88.69%** gesture-spoof; throughput can rise (whitelist legit sensors) | MEASURED (spoof); throughput CLAIMED | +| **DP-Givens dithering** | IEEE DySPAN 2026 | Differentially-private stochastic quantization of BFI φ/ψ angles | Attacker speed-class error 19%→~73% (chance); **fine (3-bit) resolution ≈ non-private baseline throughput** | MEASURED | +| **MIMOCrypt / WiShield** | 2023 / IEEE JSAC 2024 | Secret precoding / MIMO CSI manipulation so only the intended RX decodes | Anti-tracking | CLAIMED/formal | +| **CSI Fuzzing / DP feature release** | IEEE 2024–25 | Randomized CSI features with DP budget | Formal DP guarantee | CLAIMED/formal | +| **ScatterShield** | ACM IMWUT 2025 | Backscatter tags inject controlled clutter | Defeats unauthorized sensing | MEASURED | +| **Adversarial packet perturbation** | ACM MobiCom 2024 | Small in-spec packet perturbations degrade attacker model | Symmetric defense | MEASURED | + +**The fundamental tradeoff (MEASURED, DySPAN 2026).** Perturbing precoding/ +feedback that an attacker exploits also degrades legitimate beamforming gain — +*but the cost collapses at fine feedback resolution*: + +| Randomization | Attacker error | Beamforming gain retained | +|---|---|---| +| none | 19% | 100% | +| moderate (p=0.3) | >50% | median >90% | +| maximum (p≥0.9) | ~73% (≈chance) | median ~58% | + +At **high (3-bit) feedback resolution, privacy was "nearly indistinguishable +from the non-private baseline"** in link performance. This is the empirical basis +for VEIL's design choice (compliant fine-resolution feedback shaping — see +[03-countermeasure-design.md](03-countermeasure-design.md)). + +--- + +## 5. Where VEIL sits + +The literature has two families: **external** obfuscation (IRShield/ScatterShield +— extra hardware, perturbs the channel) and **transmitter-side** feedback/precoder +shaping (DP-Givens, MIMOCrypt — no extra hardware, perturbs your own report). +VEIL is in the second family and adds the missing property the others do not all +combine: a transform that is simultaneously **energy-preserving** (provably +compliant), **key-reversible** (throughput-preserving for the legitimate link), +and **session-fresh** (defeats cross-session re-identification), unified around +the Givens-rotation primitive the report already uses. + +--- + +## Sources + +- BFId — ACM CCS 2025: https://dl.acm.org/doi/10.1145/3719027.3765062 · KIT record: https://publikationen.bibliothek.kit.edu/1000185756 +- LeakyBeam — NDSS 2025: https://www.ndss-symposium.org/ndss-paper/lend-me-your-beam-privacy-implications-of-plaintext-beamforming-feedback-in-wifi/ +- BFIAttack — arXiv 2604.04179: https://arxiv.org/html/2604.04179v1 +- BeamSense — Computer Networks 2025: https://dl.acm.org/doi/10.1016/j.comnet.2024.111020 · arXiv 2303.09687: https://arxiv.org/pdf/2303.09687 +- Wi-BFI — arXiv 2309.04408: https://arxiv.org/pdf/2309.04408 +- SoK: Security Evaluation of Wi-Fi CSI Biometrics — arXiv 2511.11381: https://arxiv.org/pdf/2511.11381 +- WiWho (IPSN 2016): https://dl.acm.org/doi/10.5555/2959355.2959359 · WiPIN — arXiv 1810.04106: https://arxiv.org/pdf/1810.04106 +- Survey on Wi-Fi Sensing for Human Identity — MDPI Electronics 2023: https://www.mdpi.com/2079-9292/12/23/4858 +- IEEE Std 802.11bf-2025: https://standards.ieee.org/ieee/802.11bf/11574/ · Overview — IEEE COMST 2024: https://ieeexplore.ieee.org/document/10547188/ · NIST: https://www.nist.gov/publications/ieee-80211bf-enabling-widespread-adoption-wi-fi-sensing +- 802.11bf privacy proposal withdrawal (802.11-23/0782), summarized: https://pascalpiron.substack.com/p/wifi-sensing-and-the-privacy-fix +- IRShield — IEEE S&P 2022 / arXiv 2112.01967: https://arxiv.org/abs/2112.01967 · https://ieeexplore.ieee.org/document/9833676/ +- PhyCloak — USENIX NSDI 2016: https://www.usenix.org/conference/nsdi16/technical-sessions/presentation/qiao +- Protecting Human Activity Signatures in Compressed 802.11 CSI Feedback — DySPAN 2026 / arXiv 2512.18529: https://arxiv.org/abs/2512.18529 +- MIMOCrypt — arXiv 2309.00250: https://arxiv.org/pdf/2309.00250 · WiShield — IEEE JSAC 2024: https://dl.acm.org/doi/abs/10.1109/JSAC.2024.3414597 +- ScatterShield — ACM IMWUT 2025: https://dl.acm.org/doi/abs/10.1145/3770653 +- Practical Adversarial Attack on WiFi Sensing — ACM MobiCom 2024: https://dx.doi.org/10.1145/3636534.3649367 +- Privacy-Preserving Wi-Fi Data Generation via DP — INFOCOM 2025: https://www.eng.auburn.edu/~szm0001/papers/INFOCOM25.pdf diff --git a/docs/research/privacy-shield/02-threat-model.md b/docs/research/privacy-shield/02-threat-model.md new file mode 100644 index 00000000..1729afb9 --- /dev/null +++ b/docs/research/privacy-shield/02-threat-model.md @@ -0,0 +1,94 @@ +# 02 — Threat Model + +VEIL protects a physical space (a room, a ward, a boardroom, a SCIF) from +*unauthorized* WiFi-based inference of **who is present** and **what they are +doing**, without denying the space its own working WiFi. This file states the +adversary classes, exactly what VEIL defends, and — just as importantly — what +it does **not**. + +--- + +## 1. Assets + +| Asset | Why it matters | +|---|---| +| **Identity linkage** | Re-identifying a specific person across time/sessions from their RF signature (BFId-class attack) | +| **Occupancy / presence** | Whether the space is occupied, and by how many (LeakyBeam-class, through-wall) | +| **Activity / motion** | Gait, gestures, keystrokes, respiration inferred from channel dynamics (BeamSense-class) | +| **Communication utility** | The legitimate WiFi link must keep working (≥95% throughput bar) | + +--- + +## 2. Adversary classes + +| Class | Position | Capability | In VEIL scope? | +|---|---|---|---| +| **A1 — external passive sniffer** | Outside the trust boundary (adjacent room, van, hallway), monitor mode | Captures plaintext BFI/CSI for every station; runs BFId/LeakyBeam/BeamSense offline | **Primary target — yes** | +| **A2 — external active sensor** | Nearby, transmits its own probing/sounding to solicit measurable responses | Elicits sensing responses; 802.11bf "active" mode | **Partial** — cadence randomization + non-response policy help; full defense needs MAC-layer policy | +| **A3 — associated but curious AP** | Inside the link; the party VEIL shares keys with | Sees the un-rotated report by construction | **Out of scope** — this is BFLD's detection/privacy-class problem (ADR-118/141) | +| **A4 — supply-chain / firmware** | Compromised radio firmware | Can bypass any transmit-side control | Out of scope (integrity problem, not a waveform problem) | +| **A5 — physical / RF-denial** | Wants to *block* WiFi | — | Explicitly rejected: VEIL never jams | + +VEIL's design centers on **A1**, the attacker the literature demonstrates and +the one no shipping product addresses. + +--- + +## 3. What VEIL guarantees (and the evidence class) + +1. **Cross-session identity unlinkability against A1.** Because the fine-subspace + signature is rotated by a fresh secret orthogonal transform each session, an + A1 attacker cannot average captures back to a stable per-person template. + *Evidence: SYNTHETIC — re-ID collapses from 100% to ~chance in the reference + experiment (`cargo test`); real-silicon witness is future work.* +2. **Communication preservation.** The transform is key-reversible by the + legitimate receiver, and acts only on the identity-bearing fine subspace, so + link throughput stays ≥95%. *Evidence: SYNTHETIC model + MEASURED external + corroboration (DySPAN 2026: fine-resolution feedback shaping is near-free).* +3. **Compliance.** The transform is orthogonal ⇒ energy-preserving ⇒ adds no + interfering emission ⇒ not jamming. *Evidence: machine-checked energy ratio = + 1.000000 in the `compliance` module; statutory analysis in + [04-compliance-and-regulatory.md](04-compliance-and-regulatory.md).* + +--- + +## 4. What VEIL does NOT do (non-goals, stated to prevent over-claiming) + +- **It does not hide identity from the associated AP (A3).** That party holds the + session key. Protecting against a malicious AP requires detection and policy + (BFLD), not waveform shaping. +- **It is not RF denial or jamming.** It never degrades another station's link. +- **It does not, by itself, defeat within-session motion detection.** A single + session's rotation is fixed, so coarse presence/motion may still be inferable + within one capture window; sounding-cadence randomization mitigates but does + not eliminate this. Identity *re-ID* (the brief's metric) is the guaranteed + target; motion obfuscation is partial and tracked as future work. +- **It is not a camera-grade or medical-grade claim in any direction.** +- **It is not validated on hardware yet.** All quantitative defense results are + SYNTHETIC until a captured boot/runtime log exists (CLAUDE.md hardware rule). + +--- + +## 5. Trust boundary + +``` + ┌────────────────────── protected space ──────────────────────┐ + │ │ + │ [person] [person] legitimate STA ⇄ AP (VEIL) │ + │ │ │ │ shares session key │ + │ └──── RF ──────┘ │ rotates fine subspace│ + │ reflections ▼ of its own BFI │ + │ compliant, key-reversible, │ + │ energy-preserving emission │ + └───────────────────────────────────────┬──────────────────────┘ + │ plaintext BFI on air + ▼ + A1 external passive sniffer (monitor mode) + sees a freshly-rotated signature each session + → cannot build a stable per-person template + → re-identification → chance +``` + +The key never crosses the boundary to A1. The AP inside the boundary is trusted +for key-sharing (A3 out of scope). No emission crosses the boundary with intent +or effect of interfering with another station (A5 rejected). diff --git a/docs/research/privacy-shield/03-countermeasure-design.md b/docs/research/privacy-shield/03-countermeasure-design.md new file mode 100644 index 00000000..8c3cf540 --- /dev/null +++ b/docs/research/privacy-shield/03-countermeasure-design.md @@ -0,0 +1,136 @@ +# 03 — Countermeasure Design + +How VEIL prevents unauthorized sensing with compliant waveform controls, and how +the design maps to [`v2/crates/wifi-densepose-privshield`](../../../v2/crates/wifi-densepose-privshield). + +--- + +## 1. The separable-subspace principle + +A compressed beamforming report is not homogeneous. Two blocks carry different +information: + +- **Dominant beam direction (comm block).** The coarse steering the AP uses to + aim data at the client. It varies with position and traffic and carries **no** + stable identity. **Throughput rides here.** +- **Fine cross-subcarrier phase structure (fine block).** The high-order + multipath detail. It is *stable per person* across sessions and is what + re-identification exploits (BFId). **Identity leaks here.** Communication + barely uses it. + +The whole design rests on this: **identity leakage and data throughput live in +(mostly) separable subspaces.** A transform confined to the fine block can wreck +re-identification while sparing the beam the link depends on. This is consistent +with the DySPAN-2026 MEASURED result that shaping fine-resolution feedback is +nearly free in throughput. + +--- + +## 2. The four compliant waveform controls + +VEIL alters "channel sounding, phase, or beam schedules" — exactly the levers the +brief names — all within the 802.11 waveform envelope: + +| Control | What it varies | Purpose | +|---|---|---| +| **Keyed precoder rotation** (primary) | A fresh secret orthogonal transform of the *fine* subspace each session, composed from extra Givens rotations | Destroys cross-session identity linkage; energy-preserving; key-reversible | +| **Feedback quantization / dither** | Sub-step noise on reported φ/ψ angles | Adds report-level uncertainty; tunes the privacy–throughput point via `feedback_bits` | +| **Sounding-cadence randomization** | Jitter on NDP sounding intervals | Under-samples motion for an eavesdropper; charged as the throughput overhead | +| **MU-group / stream-mapping shuffle** | Which STAs are grouped, stream-to-antenna mapping | Rotates the spatial signature over time | + +All four modify the node's **own** standards-conformant frames. None adds energy +on top of another station (see [04](04-compliance-and-regulatory.md)). + +--- + +## 3. Why the keyed Givens rotation is the right primitive + +The compressed beamforming report is *already* a product of Givens rotations +(the φ/ψ angles). VEIL composes **additional keyed Givens rotations** over the +fine block. This choice gives three properties at once: + +1. **Orthogonal ⇒ energy-preserving.** A Givens rotation preserves the vector's + L2 norm exactly. Composing many still preserves it. So the emission carries + the same power it always would — **no added energy, no interference, not + jamming.** The `compliance` module checks this: energy ratio = 1.000000. +2. **Keyed & reversible ⇒ throughput-preserving.** The legitimate AP/STA shares + the per-session key, derives the identical rotation schedule, and applies the + inverse (negated angles, reversed order) to recover the true precoder. It pays + only the tiny residual from quantizing the extra angles at `feedback_bits` + resolution — negligible across the 802.11 5–9-bit range — plus the sounding + overhead. (The throughput-optimal resolution is derived in + [08-optimization.md](08-optimization.md).) +3. **Fresh per session ⇒ unlinkable.** A different rotation each session means an + A1 sniffer sees `R_e · signature` for a new random `R_e` every time. Averaging + over sessions (the natural enrollment attack) drives + `mean_e(R_e · signature) → 0` for *every* identity, so all templates collapse + toward the origin and become indistinguishable — re-identification → chance. + This is the marginalized-mutual-information argument: over unknown rotations, + the signature carries no stable discriminative information. + +This is the shared-secret precoding idea (cf. MIMOCrypt) specialized to the +identity-bearing subspace and unified around the report's native primitive. + +--- + +## 4. Detect-then-act + +Per the brief ("detect sensing activity and alter…"), VEIL need not perturb +continuously. The `SensingDetector` exposes the decision rule: when the observed +rate of sensing/NDP solicitations crosses a threshold, the control plane +(ADR-280) engages the shield. Continuous operation is also valid; gating just +saves the (already small) overhead when no sensing is present. + +--- + +## 5. Module map + +| Concept above | Crate module | Key items | +|---|---|---| +| Deterministic, WASM-safe randomness + keys | `prng` | `Rng` (SplitMix64), `fnv1a_64`, `derive_key` | +| Givens algebra, energy conservation | `linalg` | `apply_givens`, `norm`, `dist_sq` | +| SYNTHETIC two-subspace BFI model | `identity` | `SceneConfig`, `Channel`, `BfiSample` (`comm()`/`fine()`) | +| The four controls (shield) | `protector` | `ShieldConfig`, `Protector::protect`/`recover`, `SensingDetector` | +| Passive re-ID adversary | `attacker` | `NearestCentroidAttacker`, `Metric` | +| Privacy–throughput tradeoff | `throughput` | `LinkModel::throughput_ratio`, `beamforming_residual`, `feedback_airtime` | +| "Not jamming" audit | `compliance` | `ComplianceReport::audit`/`is_compliant` | +| Attacker-vs-protector head-to-head | `experiment` | `ExperimentConfig`, `run`, `ExperimentReport` | +| Config hyper-optimization | `optimize` | `hyper_optimize`, `min_givens_passes`, `pareto_frontier` | +| Byte-stable deterministic witness | `proof` | `Proof::EXPECTED_WITNESS`, `Proof::witness` | + +--- + +## 6. The privacy–throughput knobs (and which the optimizer turns) + +- **`feedback_bits`:** the only knob with a genuine throughput tradeoff — + residual falls with bits, feedback airtime rises with them, so there is an + interior optimum (3 bits unconstrained; 5 bits within the 802.11-allowed set). + Privacy is unaffected by bits (the rotation is fresh regardless). +- **`givens_passes`:** the privacy/robustness knob. More mixing lowers re-ID at + **no throughput cost** (the keyed rotation is never signaled), so it trades + only compute. The optimizer finds the minimum for robust collapse and ships a + free 2× margin. +- **`sounding_overhead`:** a flat throughput cost from cadence randomization; + trades motion-obfuscation strength against airtime (outside the re-ID metric). + +The `optimize` module turns these knobs deterministically — see +[08-optimization.md](08-optimization.md). It is what replaced the original +hand-picked config. + +The `throughput` module computes the ratio from these, so the tradeoff is +inspectable rather than asserted (`cargo test throughput`). + +--- + +## 7. Honest limitations of the model + +- The two-subspace split is an abstraction; on real hardware comm and identity + information are only *approximately* separable, so the real throughput cost of + fully hiding identity may be higher than the model's ~2%. The DySPAN-2026 + MEASURED curve is the external sanity check that it is *small* at fine + resolution, not zero. +- The nearest-centroid attacker is deliberately simple. The collapse argument is + classifier-independent (it is about the signal, not the model), but a hardware + study must confirm a strong learned attacker also collapses. +- Within-session motion is not addressed by the rotation alone (see threat + model §4). diff --git a/docs/research/privacy-shield/04-compliance-and-regulatory.md b/docs/research/privacy-shield/04-compliance-and-regulatory.md new file mode 100644 index 00000000..1760c557 --- /dev/null +++ b/docs/research/privacy-shield/04-compliance-and-regulatory.md @@ -0,0 +1,90 @@ +# 04 — Compliance and Regulatory Line + +**Non-negotiable:** VEIL uses compliant waveform controls and **never jams.** +This file states the legal basis for that line and why every VEIL control falls +on the compliant side of it. It is engineering analysis, not legal advice; a +deployment in a given jurisdiction needs its own regulatory review. + +--- + +## 1. The statutory line (United States) + +The prohibition is on **interfering with others' transmissions**, not on how you +shape **your own** signal. + +| Authority | What it prohibits | +|---|---| +| **47 U.S.C. §333** | *Willful or malicious interference* with any licensed/authorized radio station or U.S. Government station | +| **47 U.S.C. §302a(b)** | Manufacture, import, marketing, sale, or *operation* of non-compliant devices (jammers cannot be certified — their sole purpose is interference) | +| **47 U.S.C. §301** | Requires a license/authorization to transmit; a jammer can never be authorized | +| **47 U.S.C. §501 / §503** | Criminal penalties and forfeitures; FCC cites fines up to $112,500 per violation, **no exemptions** for business/residence/vehicle | + +The distinguishing element of jamming is **intent to interfere plus effect on a +third party's link.** A device that shapes its own standards-conformant emission +— staying within transmit-power and spectral-mask limits, still type-certifiable +— is not a jammer. + +--- + +## 2. Why each VEIL control is compliant + +| Control | Compliance argument | +|---|---| +| **Keyed precoder rotation** | Orthogonal ⇒ preserves the report's energy exactly ⇒ **adds no power on top of anyone's signal.** It is still a valid precoder within the 802.11 feedback format. Machine-checked: energy ratio = 1.000000 (`compliance` module) | +| **Feedback quantization / dither** | Reports angles the standard already allows, at the standard's resolution; sub-step dither stays within the quantization envelope. No emission change beyond the node's own frame | +| **Sounding-cadence randomization** | Chooses *when* the node sends its own NDP soundings, within permitted timing. Sending fewer/jittered soundings never interferes with another station | +| **MU-group / stream-mapping shuffle** | Rearranges the node's own spatial mapping; a normal in-spec transmit choice | + +None of the four transmits *to prevent* another station from communicating; none +adds out-of-mask energy; each passes normal type certification. Contrast a +jammer, whose defining purpose is to emit energy that denies others service. + +--- + +## 3. The energy-conservation proof as a compliance artifact + +VEIL turns "not jamming" from a promise into a **checked property.** The +`compliance::ComplianceReport` audits each protection step: + +``` +input_energy = ‖report_before‖² +output_energy = ‖report_after‖² +energy_ratio = output_energy / input_energy # ≈ 1.0 for a rotation +energy_conserving = |energy_ratio − 1| ≤ 1e-2 +adds_interfering_energy = false # by construction +is_compliant = energy_conserving ∧ ¬adds_interfering_energy +``` + +A regulator, an auditor, or the runtime attestation layer (ADR-141) can read the +report and verify the shield is a waveform-shaping control, not an interference +source. On the reference experiment the measured ratio is **1.000000**. + +--- + +## 4. Jurisdictional notes + +- **EU (GDPR framing).** Covert WiFi body-sensing of vital signs is sensitive + health data and "almost certainly illegal under GDPR," but effectively + unenforceable (receivers are undetectable) — which is precisely why a + *technical* control is needed. VEIL as a transmit-side control does not itself + raise GDPR issues; it reduces the personal data an attacker can derive. +- **RF-emission rules are jurisdiction-specific.** The energy-preserving property + is the portable core of the compliance argument, but power/mask/timing limits + differ by region and band; a deployment must confirm local rules. +- **Deliberate transmit-nulling toward a *located* sniffer** (steering a spatial + null at a known passive receiver) is still the node's own emission and adds no + interference, but is more aggressive and should get explicit regulatory review + before field use. It is not part of the default VEIL profile. + +--- + +## Sources + +- 47 U.S.C. §333: https://www.law.cornell.edu/uscode/text/47/333 +- 47 U.S.C. §302a: https://www.law.cornell.edu/uscode/text/47/302a +- FCC Jammer Enforcement: https://www.fcc.gov/general/jammer-enforcement · https://www.fcc.gov/enforcement/areas/jammers +- FCC Cell/GPS Jamming guidance: https://www.fcc.gov/general/cell-phone-and-gps-jamming +- FCC 14-92 enforcement order: https://docs.fcc.gov/public/attachments/FCC-14-92A1.pdf + +*Caveat: FCC pages were cross-verified against Cornell LII; this is engineering +analysis, not legal advice.* diff --git a/docs/research/privacy-shield/05-experiment-protocol.md b/docs/research/privacy-shield/05-experiment-protocol.md new file mode 100644 index 00000000..c5a53b67 --- /dev/null +++ b/docs/research/privacy-shield/05-experiment-protocol.md @@ -0,0 +1,113 @@ +# 05 — Experiment Protocol: Attacker vs. Protector + +This is the "start today" deliverable from the brief: **make one RuView node the +attacker and one the protector, and measure whether protection drives identity +recognition toward chance while keeping throughput above 95%.** It is realized as +a deterministic, reproducible experiment in +[`v2/crates/wifi-densepose-privshield`](../../../v2/crates/wifi-densepose-privshield). + +Because it runs on **SYNTHETIC** data (no radio is touched), its numbers describe +the model, not real hardware — reproduced by `cargo test`, and to be +re-established on silicon with a captured log before any deployment claim. + +--- + +## 1. Setup + +- **Protector node.** Emits beamforming feedback shaped by the VEIL controls + (keyed per-session fine-subspace rotation + configured feedback resolution and + sounding overhead). Models a legitimate AP/STA protecting a room. +- **Attacker node.** A passive sniffer that enrolls a template per candidate from + captured reports, then classifies fresh captures (nearest-centroid) — the + BFId-class re-identification threat. +- **Scene.** `SceneConfig` default: 64-dim report, 8 comm dims, **16 candidate + identities** (chance = 1/16 = 6.25%), per-identity stable fine-block signature + + per-session environmental nuisance. + +Two runs of the attacker are compared: **shield off** (the attacker sees raw +reports) and **shield on** (every captured report is VEIL-protected). The same +attacker faces both. + +--- + +## 2. Metrics and acceptance bar + +| Metric | Definition | Bar | +|---|---|---| +| **Re-ID accuracy, shield off** | Top-1 identity accuracy on unprotected traffic | Must be well above chance (threat is real) — bar ≥ 0.5 | +| **Re-ID accuracy, shield on** | Top-1 identity accuracy on protected traffic | Must fall into the chance band `1/N · 2 + 0.03` | +| **Throughput ratio** | Protected link capacity ÷ baseline capacity | **≥ 0.95** | +| **Compliance** | Emission energy ratio ≈ 1 and non-interfering | `is_compliant == true` | + +Overall `passed()` requires all four. + +--- + +## 3. Results (SYNTHETIC, hyper-optimized default configuration) + +Reproduce with `cargo test -p wifi-densepose-privshield` (all 35 tests + doctest +pass). The default shield config is the `optimize` module's output — 96 Givens +passes at 5-bit feedback resolution (see +[08-optimization.md](08-optimization.md)). Salient values from the reference run: + +| Metric | Value | +|---|---| +| Candidate identities | 16 | +| Chance level | 6.25% | +| Chance band (acceptance) | ≤ 15.5% | +| **Re-ID accuracy, shield OFF** | **100.0%** | +| **Re-ID accuracy, shield ON** | **4.7%** | +| **Throughput ratio** | **97.60%** | +| Emission energy ratio | 1.000000 | +| Overall verdict | **PASS** | + +Reading the result: the attacker is a *perfect* re-identifier without protection +(the synthetic signatures are cleanly separable), and VEIL drives it *to the +chance floor* (4.7% sits just below the ideal 6.25%, i.e. no better than +guessing) — while the modeled link keeps 97.6% of its throughput and the +emission conserves energy exactly (compliant, not jamming). The same collapse +holds under a Cosine-metric attacker and at N=32, confirming it is a property of +the signal, not the classifier. + +--- + +## 4. Determinism and the witness + +The experiment is byte-reproducible: no OS entropy, no wall-clock, no threads. +`proof::Proof` folds the salient outputs (quantized to avoid last-bit f32 +round-off) into an FNV-1a witness pinned as `EXPECTED_WITNESS`. Any drift in the +PRNG stream, rotation schedule, throughput formula, or scene geometry changes the +witness and fails `witness_matches_pinned`. This is the same +deterministic-proof discipline as `nvsim` and the Python `verify.py`. + +--- + +## 5. Sensitivity and what to vary next + +`ExperimentConfig` exposes the levers for a fuller study: + +- **`scene.identities`** — larger N lowers the chance floor; confirm collapse + holds as candidates grow. +- **`scene.env_sigma` / `beam_amplitude`** — nuisance and comm energy; stress the + separability assumption. +- **`shield.feedback_bits`** — trace the privacy–throughput curve (the + `throughput` tests already show coarse resolution costs more). +- **`shield.givens_passes`** — mixing strength; fewer passes should degrade the + collapse gracefully. +- **Stronger attacker** — swap in a learned classifier to confirm the collapse is + signal-level, not classifier-level (the argument says it must be, but a + hardware study should verify). + +--- + +## 6. Path to a real two-node measurement + +The synthetic experiment is the design proof. The hardware path (per CLAUDE.md, +requires a captured log to claim MEASURED): + +1. Two ESP32-S3/C6 or Nexmon-capable nodes: one runs Wi-BFI capture (attacker), + one runs a VEIL-shaped feedback profile (protector). +2. Enroll and test the same BFId-style classifier on captured BFI, shield off vs. + on; log throughput via iperf across the legitimate link. +3. Success = the same shape as §3 on real captures, with the boot/runtime log as + the witness. Until then, all defense numbers remain SYNTHETIC. diff --git a/docs/research/privacy-shield/06-market-and-buyers.md b/docs/research/privacy-shield/06-market-and-buyers.md new file mode 100644 index 00000000..97cf1f91 --- /dev/null +++ b/docs/research/privacy-shield/06-market-and-buyers.md @@ -0,0 +1,92 @@ +# 06 — Market and Buyers + +Facts are tagged **VERIFIED** (from a cited source), **CLAIMED** (asserted by a +vendor/analyst/press source), or **SPECULATIVE** (our inference). Market figures +are third-party projections, not independent measurements. + +--- + +## 1. Why now + +- **The threat is standardized and commercializing (VERIFIED/CLAIMED).** IEEE + 802.11bf was published Sep 2025; silicon (Infineon AIROC Wi-Fi 7 ACW741x, + Qualcomm Dragonwing) lists 802.11bf sensing in 2026 briefs; Origin AI's + embedded-sensing program targets late-2026 deployment; Plume/Cognitive Systems + WiFi Motion is the largest deployed sensing footprint today. +- **The standards body declined to fix privacy (VERIFIED).** The BFI + "secure transmission mechanism" proposal (802.11-23/0782) was **withdrawn**; + 802.11bf shipped with no privacy protections. This is the strongest demand + signal — the gap is structural and acknowledged. +- **No targeted anti-sensing product ships (VERIFIED by absence).** Every + countermeasure (IRShield, PhyCloak, MIMOCrypt, DP-Givens, ScatterShield) is + research-stage. The claim "no obvious shipping product protects rooms from this + inference" **holds** as of 2026, with one caveat below. + +--- + +## 2. First buyers, ranked by procurement readiness + +| Segment | Driver | Readiness | +|---|---|---| +| **Defence / government** | ICD 705 / DoD EMSEC already mandate RF attenuation in classified spaces; budgets and mandates exist | **Strongest beachhead (VERIFIED)** — but today they buy broadband shielding, not a sensing-specific control | +| **Corporate boardrooms / counter-espionage** | TSCM firms (Bastille, Murray Associates) now include WiFi audits and rogue-AP detection; CSI keystroke/gesture inference makes a boardroom shield a natural extension | **VERIFIED demand, EMERGING WiFi-specific** | +| **Hospitals** | RF-derived behavioral/vital data is HIPAA PHI; exam rooms, psychiatric units where inference is unwanted | **VERIFIED regulatory hook** — but the hook drives privacy-preserving *sensing* more than a *shield* | +| **Hotels** | Documented guest backlash against in-room sensors; privacy as differentiation | **SPECULATIVE** — narrative-led, not procurement-led today | +| **Router / AP manufacturers** | Ship opt-out/obfuscation as a firmware feature anticipating regulation | **SPECULATIVE** — no vendor has announced this | + +--- + +## 3. Competitive landscape + +- **Direct competitors:** none shipping. All targeted anti-sensing is academic. +- **The real substitute (VERIFIED):** broadband RF shielding — SCIF/TEMPEST + window film, paint, panels (Signals Defense SD2500: >40 dB, 30 MHz–6 GHz, ICD + 705 / ASTM F3057-14). It defeats WiFi sensing as a side effect but is **blunt**: + it kills *all* RF and cannot coexist with wanted WiFi. +- **TSCM services (VERIFIED):** detect, don't prevent. + +**VEIL's differentiation** is exactly what the substitute lacks: **selective and +coexisting** — it removes identity/activity leakage while keeping the room's WiFi +working at ≥95% throughput, with a machine-checkable compliance artifact. + +--- + +## 4. Market size (third-party projections, cite with care) + +- **CLAIMED:** ABI Research — North American WiFi-sensing-compatible CPE install + base to **112M by 2030 (51.6% CAGR)**. +- **CLAIMED:** Global WiFi sensing market ~$402M (2024) → ~$2.13B (2033) + (MarketIntelo). + +Implication: a shield must **coexist** with a large installed sensing base, not +assume RF denial — reinforcing the selective-coexistence positioning. + +--- + +## 5. Where VEIL fits RuView's positioning + +VEIL pairs with BFLD to make RuView the *both-sides* RF-perception platform: +BFLD/AETHER do sensing responsibly and detect leakage; VEIL is the customer- +facing **privacy firewall** that protects a room from *others'* sensing. That is a +defensible, standards-anchored, gap-filling story: the standards body left the +door open, the threat is shipping, and no one else sells the selective lock. + +--- + +## Sources + +- IEEE 802.11bf privacy-proposal withdrawal (802.11-23/0782), summarized: https://pascalpiron.substack.com/p/wifi-sensing-and-the-privacy-fix +- NIST 802.11bf: https://www.nist.gov/publications/ieee-80211bf-enabling-widespread-adoption-wi-fi-sensing +- IRShield: https://arxiv.org/abs/2112.01967 · MIMOCrypt: https://arxiv.org/pdf/2309.00250 · ScatterShield: https://dl.acm.org/doi/abs/10.1145/3770653 · WiShield JSAC 2024: https://dl.acm.org/doi/abs/10.1109/JSAC.2024.3414597 +- Signals Defense TEMPEST/SCIF film: https://signalsdefense.com/tempest-and-scif-design/ · https://signalsdefense.com/shielding-films/ +- National Shielding SCIF/ICD-705: https://www.national-shielding.com/pages/scif-icd-705-secure-facility-shielding +- Bastille TSCM: https://bastille.net/centers-of-excellence/tscm/ · IntellSIG TSCM overview: https://www.intellsig.com/2025/07/20/modern-eavesdropping-threats-a-tscm-overview/ +- Origin AI program: https://www.prnewswire.com/news-releases/origin-ai-launches-compatible-with-origin-program-to-meet-industry-demand-for-scalable-wifi-sensing-and-accelerate-integration-across-global-soc-platforms-302650963.html +- MIT Tech Review, WiFi sensing: https://www.technologyreview.com/2024/02/27/1088154/wifi-sensing-tracking-movements/ +- ABI Research 112M forecast: https://www.abiresearch.com/press/north-american-wi-fi-sensing-cpe-installations-to-surge-to-112-million-by-2030-as-the-technologys-maturing-unleashes-new-business-and-service-models +- MarketIntelo WiFi sensing market: https://marketintelo.com/report/wi-fi-sensing-market +- HIPAA/PHI RF-sensing context (PMC): https://pmc.ncbi.nlm.nih.gov/articles/PMC11939480/ + +*Caveat: market figures are analyst/vendor projections; the "no shipping product" +finding reflects absence of evidence in these searches and should be confirmed +with a patent/vendor scan before anchoring a go-to-market claim.* diff --git a/docs/research/privacy-shield/07-implementation-and-roadmap.md b/docs/research/privacy-shield/07-implementation-and-roadmap.md new file mode 100644 index 00000000..8cfb68e3 --- /dev/null +++ b/docs/research/privacy-shield/07-implementation-and-roadmap.md @@ -0,0 +1,117 @@ +# 07 — Implementation and Roadmap + +--- + +## 1. What ships in this bundle + +- **Reference crate** `v2/crates/wifi-densepose-privshield` (VEIL): a + deterministic, dependency-free, WASM-ready pure-compute leaf implementing the + full attacker-vs-protector experiment, the four compliant controls, the + throughput model, the compliance audit, the `optimize` hyper-optimizer, and a + byte-stable proof. 35 tests + doctest pass; builds for + `wasm32-unknown-unknown`; clippy-clean. +- **This research bundle** (`docs/research/privacy-shield/`). +- **[ADR-288](../../adr/ADR-288-veil-privacy-shield-compliant-waveform.md)** — the + formal decision record. +- **npm metaharness** `harness/wifi-densepose-privshield/` + ([ADR-289](../../adr/ADR-289-wifi-densepose-privshield-harness-via-metaharness.md)) + — a per-crate contributor harness (architect/implementer/reviewer/test-writer, + router, flywheel) with a dependency-free `guidance` surface that serves this + bundle's capability map. `npx wifi-densepose-privshield-harness guidance + --topic optimization`. + +The crate is intentionally a **leaf with no internal RuView dependencies** +(mirrors `wifi-densepose-aether`), so it can be reasoned about, fuzzed, and +ported independently, and so it can never accidentally acquire a path to a radio. + +--- + +## 2. Reuse map (how VEIL composes with existing RuView) + +| Existing subsystem | Relationship | +|---|---| +| **BFLD** (ADR-118/120/121, `wifi-densepose-bfld`) | Detection layer. Its `identity_risk_score` is the natural trigger for VEIL's `SensingDetector` — detect leakage, then shield | +| **Privacy control plane** (ADR-141) | VEIL protection steps emit `ComplianceReport`s that fit the runtime-attestation model (which mode, which actions, which fields) | +| **Active sensing / governed actuation** (ADR-280) | VEIL is a defensive `SensingAction`: a governed, privacy-ceiling-bounded emission-shaping action the control plane can schedule | +| **Givens/beamforming primitives** | VEIL reuses the report's native Givens-rotation structure rather than inventing a new transform | +| **Deterministic proof discipline** (`nvsim`, `archive/v1/verify.py`) | VEIL's `proof` module follows the same pinned-witness pattern | + +--- + +## 3. Phased rollout + +| Phase | Deliverable | Evidence class | +|---|---|---| +| **P1 — reference model (this PR)** | Crate + experiment + docs + ADR | SYNTHETIC (cargo test) | +| **P2 — sensitivity study** | Sweep N, noise, resolution, mixing; add a learned attacker to confirm signal-level collapse | SYNTHETIC | +| **P3 — BFLD integration** | Wire `identity_risk` → `SensingDetector` → shield engage; emit attestation | SYNTHETIC + integration tests | +| **P4 — firmware feedback shaping** | Implement keyed fine-subspace rotation + cadence randomization in the **beamforming-feedback / spatial-mapping path** — see §3.1 for the (non-trivial) platform reality | build + hardware | +| **P5 — two-node hardware measurement** | Attacker (Wi-BFI capture) vs. VEIL protector on real silicon; iperf throughput; captured log | **MEASURED** (with witness) | +| **P6 — deployment profiles** | Per-segment profiles (SCIF, boardroom, ward) with regulatory review | operational | + +No defense claim graduates from SYNTHETIC to MEASURED without a captured +boot/runtime log (CLAUDE.md hardware rule). + +### 3.1 Does this need custom WiFi firmware? (yes — and ESP32 is the wrong chip for the protector) + +VEIL shapes the **compressed beamforming report** (the Givens φ/ψ angles) or the +LTF **spatial mapping** as it is transmitted — machinery that lives *below* the +driver, inside the chip's PHY/MAC firmware. It is **not** reachable from user +space, so a real deployment is a firmware/driver change, not an app. + +- **ESP32 — not viable as the protector.** Its WiFi lower layers are a closed + Espressif blob. ESP-IDF exposes CSI *read* (`esp_wifi_set_csi`) — which is why + `firmware/esp32-csi-node/` makes a great **attacker/sensor** node — but it does + **not** let you rewrite how the chip builds/sends beamforming feedback. ESP32 + is the *attacker* in a testbed, not the shield. +- **Realistic protector platforms:** **openwifi** (open 802.11 on SDR/FPGA — + full PHY/MAC control incl. the AP-side compensation; the honest end-to-end + route; Verilog + a C driver); **Nexmon** (C firmware *patches* for + Broadcom/Cypress, e.g. RPi BCM43455 — the commodity path, and the same + framework the BFI *attack* tools already use); open drivers (**ath9k/mt76**) + for partial control; or **vendor firmware** for a production feature. +- **Two firmware variants:** the **keyed-reversible** version (VEIL's ~98% + throughput) needs changes on **both** ends plus key agreement (cf. the + LeakyBeam AP-side `Q_obf` is *client-transparent* — only the AP changes — which + is a deployment advantage worth adopting, §09 backlog item 3); the + **emitter-only DP dither** version needs only the reporting device but pays the + full throughput cost. + +The current crate is deliberately a std-only, no-radio leaf and implements none +of this; P4 is where it meets silicon. + +--- + +## 4. Open problems (tracked honestly) + +1. **Real-hardware separability.** Comm and identity information are only + *approximately* separable on real radios; the true throughput cost of full + identity hiding may exceed the model's ~2%. P2/P5 must bound it. +2. **Within-session motion leakage.** A fixed per-session rotation does not + obfuscate coarse motion within one capture window. Needs stronger cadence + randomization or amplitude shaping; currently a stated non-goal for the re-ID + metric. +3. **Active adversary (A2).** An attacker that transmits its own soundings is + only partially addressed by cadence control; a MAC-layer non-response policy + is needed. +4. **Key management.** The per-session rotation key must be derived from the + negotiated link secret; VEIL's PRNG is explicitly *not* cryptographic and must + not be used for real key material. +5. **Regulatory review per jurisdiction.** The energy-conservation argument is + portable, but power/mask/timing limits and any transmit-nulling profile need + local review before field use. + +--- + +## 5. Validation commands + +```bash +# Reference experiment + all unit/proof/doc tests +cargo test -p wifi-densepose-privshield --no-default-features + +# WASM portability (leaf builds with no radio path) +cargo build -p wifi-densepose-privshield --target wasm32-unknown-unknown + +# Lints +cargo clippy -p wifi-densepose-privshield --all-targets +``` diff --git a/docs/research/privacy-shield/08-optimization.md b/docs/research/privacy-shield/08-optimization.md new file mode 100644 index 00000000..b38fbbec --- /dev/null +++ b/docs/research/privacy-shield/08-optimization.md @@ -0,0 +1,142 @@ +# 08 — Hyper-Optimization + +The reference crate first shipped a **hand-picked** shield config (112 Givens +passes, 7-bit feedback). This file records how the `optimize` module replaces +that guess with a *derived*, robustness-verified optimum, and what it found. All +numbers are **SYNTHETIC / L0**, reproduced by +`cargo test -p wifi-densepose-privshield`. + +--- + +## 1. What is being optimized, and against what + +Two knobs, two objectives, one hard constraint: + +| Knob | Costs | Does it trade against privacy? | +|---|---|---| +| `feedback_bits` (angle resolution) | Throughput: **residual** falls with bits, **feedback airtime** rises with bits | No — the keyed rotation is applied regardless of resolution | +| `givens_passes` (rotation mixing) | Compute only | Yes — more mixing ⇒ lower re-ID | + +**Constraint:** re-ID must collapse into the chance band `1/N · 2 + 0.03` — and +it must do so *robustly*: for **both** attacker metrics (Euclidean and Cosine) +and **both** identity counts (N = 16 and N = 32, the harder, lower-chance case). + +The key structural fact: **rotation mixing is throughput-free.** The per-session +rotation is derived from the shared link secret on both ends (like MIMOCrypt) — +it is never transmitted — so extra Givens passes cost compute, not airtime. That +means privacy margin is essentially free; the only throughput tradeoff lives in +`feedback_bits`. + +--- + +## 2. Throughput is a 1-D problem with an interior optimum + +Because the residual falls with bits while feedback airtime rises, throughput +has a genuine interior optimum in `feedback_bits` (`LinkModel`, default SNR 20 dB, +`feedback_overhead_per_bit = 0.0008`): + +| bits | throughput ratio | +|---|---| +| 1 | 0.9681 | +| 2 | 0.9757 | +| **3** | **0.9769** ← unconstrained optimum | +| 4 | 0.9766 | +| **5** | **0.9760** ← shipped (spec-allowed) | +| 7 | 0.9744 (the old hand-picked value) | +| 9 | 0.9728 | +| 12 | 0.9704 | + +The unconstrained optimum is **3 bits** — which coincides with the DySPAN-2026 +MEASURED finding that ~3-bit feedback is the privacy–utility sweet spot, because +the receiver compensates the keyed rotation and extra bits mostly buy airtime. +802.11 compressed beamforming quantizes ψ/φ to roughly 5–9 bits, so the shipped +shield uses the throughput-best **spec-allowed** value, **5 bits** (0.9760), +rather than the out-of-spec 3-bit optimum. Either way it beats the old 7-bit +choice. + +--- + +## 3. Mixing: the minimum robust budget, and a free margin + +Worst-case shield-on re-ID vs. `givens_passes` (bits = 5; worst over Euclidean +and Cosine): + +| passes | re-ID @ N=16 | re-ID @ N=32 | robust collapse? | +|---|---|---|---| +| 16 | 0.75 | 0.62 | no | +| 24 | 0.50 | 0.35 | no | +| 32 | 0.20 | 0.14 | no (N=32 band is 0.0925) | +| **48** | 0.12 | 0.057 | **yes** ← proven minimum | +| 64 | 0.078 | 0.044 | yes | +| **96** | **0.047** | **0.018** | **yes** ← shipped (2× margin) | +| 112 | 0.078 | 0.042 | yes (the old default — no better than 96) | + +The proven minimum for robust collapse is **48 passes** — the hand-picked 112 was +**2.3× over-provisioned**. Since mixing is throughput-free, the shield ships +**96 passes** (`PRIVACY_MARGIN_FACTOR = 2` × 48, rounded up to a candidate): it +drives re-ID *below chance* at N=16 (0.047 < 0.0625) at zero throughput cost, and +is still cheaper compute than the original 112. + +--- + +## 4. The adopted config, and why it beats the original + +| | Old (hand-picked) | Hyper-optimized (shipped) | +|---|---|---| +| Givens passes | 112 | **96** (from proven-min 48 × 2) | +| Feedback bits | 7 | **5** (spec-optimal) | +| Shield-on re-ID (N=16) | 0.078 | **0.047** | +| Throughput ratio | 0.9744 | **0.9760** | +| Robust across metrics & N | not checked | **verified** | + +The optimum is **strictly better on privacy and throughput at once**, and is now +*verified* rather than assumed. `ShieldConfig::default()` is exactly the +optimizer's output; the test `optimize::shipped_default_equals_optimizer_output` +fails if they ever drift apart. + +--- + +## 5. The Pareto frontier (and an honest note) + +`optimize::pareto_frontier` enumerates non-dominated (worst-case re-ID, +throughput) points over a pass × bits grid. In this model the frontier +**collapses toward the max-mixing, 5-bit point**, because mixing is +throughput-free — so beyond the throughput knob (bits) there is no privacy– +throughput tradeoff to trace. That degeneracy is itself the finding: *the only +thing privacy costs here is feedback resolution, and even that is cheap.* On real +hardware, where comm/identity subspaces are only approximately separable and +where more aggressive mixing may touch the data-carrying beam, this frontier is +expected to open up — a hardware study (roadmap P5) will re-measure it. + +--- + +## 6. Per-deployment adaptivity + +The optimum is not one number — `optimize` derives it per deployment: + +- **SNR → feedback resolution.** `optimal_bits_across_snr` shows the + *unconstrained* throughput-optimal resolution shifting with SNR: **4 bits at + 5–10 dB, 3 bits at 20–40 dB** (low SNR values fine resolution more because + the Shannon capacity is near-linear there, so the residual costs more). Within + the spec-allowed {5,7,9} set the choice is 5 bits across this whole range — + the residual is already negligible at 5 bits — which is why the shipped shield + is SNR-stable. +- **Identity count → mixing.** `adaptive_shield(base, n)` derives the config for + a room with `n` expected occupants. A notable finding: in this model the + collapse budget is **N-independent** (min 48 passes collapses N∈{8,64} + alike), because a well-mixed Haar-like rotation destroys per-identity + structure regardless of how many identities there are — the budget is set by + the fine-subspace dimension, not the candidate count. So `adaptive_shield` + returns the same 96/5 across that range: the default is robust, not a point + tuning. + +Both are surfaced through the harness `guidance --topic optimization`. + +## 7. Robustness caveats (unchanged from the threat model) + +- The collapse is verified against two classifiers and two N; a learned + attacker on real captures must still be checked (P2/P5). +- `feedback_bits` affects only throughput in this model, not re-ID; on hardware, + coarse quantization also adds obfuscation, which would *help* privacy — the + model conservatively ignores that. +- All optimization results are SYNTHETIC until a hardware witness exists. diff --git a/docs/research/privacy-shield/09-sota-update-2026.md b/docs/research/privacy-shield/09-sota-update-2026.md new file mode 100644 index 00000000..f10503cf --- /dev/null +++ b/docs/research/privacy-shield/09-sota-update-2026.md @@ -0,0 +1,151 @@ +# 09 — SOTA Update (2025–2026) and VEIL Improvement Backlog + +Source: a fan-out deep-research run (5 angles → 20 primary sources → 93 claims → +top 25 adversarially verified with 3-vote panels → 24 confirmed, 1 refuted). +Each finding carries its **evidence class** (`MEASURED` with metric / `CLAIMED` +/ `SYNTHETIC` / `STANDARDS-MINUTE`) and a primary URL. This file records what +changed in the field and the concrete backlog it implies for VEIL (ADR-288/289). +Nothing here upgrades VEIL's own numbers to `MEASURED` — that still requires a +captured hardware log (CLAUDE.md). + +--- + +## 1. The threat surface got worse (and cheaper) + +| Finding | Evidence | Source | +|---|---|---| +| **BFId** — first *identity* inference from plaintext BFI: **99.5% over 197 people**, perspective/gait-independent; BFI carries ~740 features vs 212 for CSI, so it *beats* CSI for identity; one eavesdropper captures BFI from all clients | `MEASURED` (top-1, N=197, CCS 2025) | [dl.acm.org/10.1145/3719027.3765062](https://dl.acm.org/doi/10.1145/3719027.3765062) | +| **LeakyBeam** — through-wall occupancy at **20 m** (TPR 82.7% / TNR 96.7%) **and breathing/vital-sign** leakage from *stationary* occupants; single antenna, Wireshark, no keys | `MEASURED` (NDSS 2025) | [ndss 2025-5](https://www.ndss-symposium.org/wp-content/uploads/2025-5-paper.pdf) | +| **WiKI-Eve / SThief** — keystroke & PIN/password theft from BFI (88.9% per-keystroke; 65.8% top-10 app passwords; POS keypads) with no device compromise | `MEASURED` (CCS 2023 / IEEE) | [WiKI-Eve](https://dl.acm.org/doi/10.1145/3576915.3623088) · [SThief](https://ieeexplore.ieee.org/document/10621321/) | +| **BFIAttack** — **reconstructs full CSI from sniffed BFI**: closed-form ≥93% (single-antenna, 1 attempt); MLE with physics/standard constraints 73% (multi-antenna, ≤5 attempts). Collapses the BFI-vs-CSI distinction | `MEASURED` (arXiv Apr 2026) | [arxiv 2604.04179](https://arxiv.org/html/2604.04179v1) | +| **BeamSense** — BFI sensing is standards-compliant, needs no firmware mod, ~10% higher activity accuracy than CSI | `MEASURED` | [BFISense/BeamSense](https://www.researchgate.net/publication/402468114_BFISense_Using_Beamforming_Feedback_Information_for_Wi-Fi_Sensing) | + +**Implication:** the attacker is a *passive, keyless, single commodity antenna at +~20 m, through walls*, that can (a) identify people, (b) read vitals and +keystrokes, and (c) **reconstruct CSI from the BFI itself.** VEIL's threat model +must treat all four as baseline. + +--- + +## 2. Defenses — the field validates VEIL's family and adds stronger primitives + +| Defense | Mechanism | Effect | Evidence | Source | +|---|---|---|---|---| +| **LeakyBeam defense** | AP-side **per-packet random unitary** `Q_obf` on the LTF via the 802.11 spatial-mapping mechanism (standard says "not restricted"); AP recovers `V = Q_obf · V_obf`; **clients unmodified** | attack **89.7% → ~51%** across 8 APs (~1.6M packets/49 h) | `MEASURED` | [ndss 2025-5](https://www.ndss-symposium.org/wp-content/uploads/2025-5-paper.pdf) | +| **PrivISAC (RIS)** | Paired per-row RIS vectors, one randomly active per slot; preserves comm-direction response, corrupts sensing direction; time-domain mask/demask for the authorized RX | **93% → ~30%**, and **29% vs. retrained 5-location adaptive attacker** | `MEASURED` (64-element FPGA RIS, Intel 5300, ~2,700 OTA samples) | [arxiv 2601.04488](https://arxiv.org/html/2601.04488) | +| **DP-Givens** | ε-DP stochastic quantizer on the Givens rotation/phase angles; closed-form angular sensitivity → principled ε budget; preserves 802.11 feedback structure | frontier: attacker error 19% → ~73%; beamforming gain 0.97 → 0.89 median (0.54 at full) | `SYNTHETIC` (Monte-Carlo) | [arxiv 2512.18529](https://arxiv.org/pdf/2512.18529) | +| **Adaptive-DP (CSI spectrogram)** | Importance-weighted (non-uniform) DP budget across the time-frequency plane | better privacy-utility than flat noise at equal ε∈[0.5,2]; cuts identity + membership inference | `CLAIMED` (unrefereed) | [arxiv 2512.20323](https://arxiv.org/abs/2512.20323) | +| **BeamDancer** | Randomized native-beamforming obfuscation | defeats supervised + unsupervised localization and micro-Doppler; **compliant, not jamming** | `MEASURED` (IEEE TWC 2024) — **do NOT cite its ">96% PDR" (refuted here)** | [ieee 10739908](https://ieeexplore.ieee.org/document/10739908/) | +| **TX-side CSI obfuscation (+ counter-attacks)** | Filter the whole frame incl. LTS; DNN de-obfuscation for authorized sensing | **security contested**: "Defeating CSI obfuscation" + SnoopFi FIA/CRA recover the signal | `CLAIMED` design + published rebuttal | [C&S 2025](https://www.sciencedirect.com/science/article/abs/pii/S0167404825002834) | + +**Where VEIL sits:** VEIL's keyed Givens rotation is the *same family* as the +LeakyBeam per-packet unitary and the DP-Givens knob — and unlike additive/DP +dither, VEIL's transform is **secret and orthogonal**, which is exactly the +property that should resist the BFIAttack closed-form/MLE inversion (the attacker +has no key, so there is no closed-form to invert to). That is now the decisive +claim to *test*, not assume. + +--- + +## 3. Compliance / legal line + +- **BeamDancer (IEEE TWC 2024)** is the peer-reviewed precedent for VEIL's + stance: **jamming and geofencing are non-compliant / non-scalable; exploiting + the standard beamforming mechanism stays 802.11-compliant** (validated without + disabling firmware). Cite it as the compliance precedent — but **not** its + refuted throughput figure. +- **Governance gap (unfilled):** *no* claim on the 802.11bf-2025 standard's + privacy provisions, the withdrawn secure-LTF-from-11az proposal, or + GDPR/HIPAA/EMSEC/ICD-705 boundaries **survived 3-vote verification** in this + run. Blog/secondary sources assert a withdrawn privacy proposal, but it needs + primary WG-minute/draft sourcing before VEIL relies on it. Tracked as an open + question. + +--- + +## 4. VEIL improvement backlog (derived, prioritized) + +Priority = (verified severity) × (fit to VEIL). `[code]` = crate change, +`[docs]` = documentation, `[hw]` = hardware path. + +1. **`[code]` ✅ implemented — Reconstruction-aware attacker (decisive).** A + BFIAttack-style adversary (`attacker::ReconstructionAttacker`, + `AttackerKind::Reconstruction`) recovers the direction of the CSI consistent + with the *captured* report and classifies it; the test + `reconstruction_attacker_collapses` confirms the keyed *orthogonal secret* + rotation leaves it at chance (no key → it only ever recovers the rotated + direction) while it still wins on unprotected traffic. *(BFIAttack, MEASURED)* +2. **`[code]` ✅ implemented — Adaptive, multi-capture attacker.** + `attacker::AdaptivePoolingAttacker` (`AttackerKind::AdaptivePooling`) pools all + captures per identity and whitens by per-dimension std before matching (the + PrivISAC adaptive/retraining adversary); `adaptive_pooling_attacker_collapses` + confirms collapse still holds. *(PrivISAC, MEASURED)* +3. **`[code]` ✅ implemented — Per-packet random-unitary mode.** + `protector::ObfMode::PerPacketUnitary` applies a fresh unitary per packet, + AP-side and **client-transparent** (LeakyBeam family; 802.11 spatial mapping + "not restricted" as the compliance basis); + `per_packet_unitary_mode_collapses_and_is_compliant` verifies it. *(LeakyBeam + defense, MEASURED)* +4. **`[code]` ✅ implemented — DP-Givens ε knob.** `ShieldConfig.dp_epsilon` adds + an ε-scaled angular dither, renormalized to preserve emission energy (still + not jamming); `throughput::dp_residual` makes ε a real privacy↔throughput knob + (`dp_epsilon_lowers_throughput_as_it_tightens`), and the combined + rotation+DP still collapses and stays compliant. Outputs `SYNTHETIC`. + *(DP-Givens, SYNTHETIC)* + +> Items 1–4 landed with the reference **witness unchanged** +> (`0x350d…f448`) — the new controls/attackers are opt-in fields; the shipped +> default config and its numbers are byte-identical. +5. **`[code/docs]` Privacy–throughput *frontier*, not binary claims.** Report + attacker-error-vs-privacy and gain/PDR-vs-privacy curves (we already have the + throughput-vs-bits and reid-vs-passes curves; add the joined frontier). +6. **`[docs]` Threat-model upgrade.** Elevate identity/gait re-ID, through-wall + vitals, keystroke/PIN, and **BFI→CSI reconstruction** to primary threats in + ADR-288 §threat and bundle 02; add the passive/keyless/20 m/through-wall + adversary as the default. *(done in this update)* +7. **`[docs]` Security honesty.** State that VEIL's shield security is `CLAIMED` + until it survives published de-obfuscation attacks (SnoopFi / "Defeating CSI + obfuscation"); add learned de-obfuscation to the attacker roadmap. +8. **`[code/docs]` Evaluation battery.** Adopt BeamDancer's three-attacker matrix + (supervised localizer + unsupervised clusterer + model-based Doppler) as a + minimum test set, plus identity + membership-inference metrics. +9. **`[hw]` Hardware-validation path.** Mirror the RIS/8-AP OTA testbeds for P5. + **Correction:** ESP32 is an *attacker/sensor* node only (its WiFi lower layer + is a closed blob exposing CSI *read*, not TX-feedback shaping); the protector + needs **openwifi (SDR/FPGA), Nexmon (C firmware patches), or vendor + firmware** + key agreement for the keyed-reversible version. See roadmap §P4. +10. **`[docs]` Governance sourcing.** Fill the 802.11bf privacy-provision gap + with primary WG minutes/draft; scope FCC Part 15, GDPR/HIPAA (inferred + biometric/health), and EMSEC/ICD-705 deployability. + +--- + +## 5. Open questions the evidence did not close + +- Does VEIL's obfuscation degrade **CSI *reconstructed* from BFI** (BFIAttack), + or only raise raw-BFI feature noise? *(the decisive effectiveness question)* +- What is VEIL's **own MEASURED** privacy–throughput frontier on silicon (the + only measured PDR number in the field was refuted; the DP curves are + simulation-only)? +- Does 802.11bf-2025 contain any privacy provision or a withdrawn one, and what + are the concrete FCC/GDPR/HIPAA/ICD-705 deployment boundaries? + +--- + +## Sources (primary, verified in this run) + +- BFId — CCS 2025: https://dl.acm.org/doi/10.1145/3719027.3765062 +- LeakyBeam (attack + per-packet-unitary defense) — NDSS 2025: https://www.ndss-symposium.org/wp-content/uploads/2025-5-paper.pdf +- BFIAttack (BFI→CSI reconstruction) — arXiv 2026: https://arxiv.org/html/2604.04179v1 +- WiKI-Eve — CCS 2023: https://dl.acm.org/doi/10.1145/3576915.3623088 +- SThief — IEEE: https://ieeexplore.ieee.org/document/10621321/ +- BeamSense/BFISense: https://www.researchgate.net/publication/402468114_BFISense_Using_Beamforming_Feedback_Information_for_Wi-Fi_Sensing +- PrivISAC (RIS) — arXiv 2026: https://arxiv.org/html/2601.04488 +- DP-Givens — arXiv 2512.18529: https://arxiv.org/pdf/2512.18529 +- Adaptive-DP spectrogram — arXiv 2512.20323: https://arxiv.org/abs/2512.20323 +- BeamDancer — IEEE TWC 2024: https://ieeexplore.ieee.org/document/10739908/ +- TX-side CSI obfuscation — Computers & Security 2025: https://www.sciencedirect.com/science/article/abs/pii/S0167404825002834 + +*Refuted (do not cite): BeamDancer ">96% PDR in LoS" (verification 1–2). Two DP +mechanisms are SYNTHETIC/CLAIMED, not silicon. Governance/standard pillar +unverified in this run.* diff --git a/docs/research/privacy-shield/README.md b/docs/research/privacy-shield/README.md new file mode 100644 index 00000000..6945591f --- /dev/null +++ b/docs/research/privacy-shield/README.md @@ -0,0 +1,102 @@ +# Privacy Shield Research Bundle — WiFi Veil + +**WiFi Veil** (codename **VEIL** — Verifiable Emission-shaping for +Identity-Leakage prevention) is a privacy *firewall* for WiFi sensing: it +prevents unauthorized identity and +activity inference from a room's WiFi while preserving normal communications. It +is the **countermeasure** counterpart to [BFLD](../BFLD/) — where BFLD *detects* +when beamforming feedback becomes identifying, WiFi Veil *acts* by shaping the node's +own compliant waveform (channel sounding, precoder phase, beam/feedback +schedules) so identity and activity inference fail, while a legitimate receiver +sees an essentially unchanged link. + +**This must use compliant waveform controls, never jamming.** Every technique +here operates on the defender's *own* legitimately transmitted, standards- +conformant frames. Nothing adds energy to interfere with another station's +transmission (the statutory definition of jamming, 47 U.S.C. §333/§302a). + +--- + +## Table of contents + +| File | Purpose | +|------|---------| +| [01-sota-survey.md](01-sota-survey.md) | State of the art: identity/activity inference attacks (BFI + CSI), the IEEE 802.11bf-2025 standard, and privacy-preserving countermeasures | +| [02-threat-model.md](02-threat-model.md) | Adversary classes, what WiFi Veil defends and what it explicitly does not, trust boundary | +| [03-countermeasure-design.md](03-countermeasure-design.md) | The compliant waveform controls, the separable-subspace principle, keyed Givens-rotation shield, and how it maps to the crate | +| [04-compliance-and-regulatory.md](04-compliance-and-regulatory.md) | The legal line between compliant waveform control and jamming, with statutory citations | +| [05-experiment-protocol.md](05-experiment-protocol.md) | The attacker-vs-protector experiment: metrics, acceptance bar, reproducer, and results | +| [06-market-and-buyers.md](06-market-and-buyers.md) | First buyers, procurement drivers, competitive landscape, and the standards-body gap | +| [07-implementation-and-roadmap.md](07-implementation-and-roadmap.md) | Crate layout, reuse map, hardware path, phased rollout, and open problems | +| [08-optimization.md](08-optimization.md) | Hyper-optimization: throughput-optimal feedback resolution, minimum robust mixing budget, Pareto frontier, and the adopted config | +| [09-sota-update-2026.md](09-sota-update-2026.md) | 2025–2026 SOTA update (verified, cited): stronger attacks (BFI→CSI reconstruction, through-wall vitals, keystroke), validated compliant defenses, and the derived WiFi Veil improvement backlog | + +Formal decision: [ADR-288](../../adr/ADR-288-veil-privacy-shield-compliant-waveform.md). +Reference implementation: [`v2/crates/wifi-densepose-privshield`](../../../v2/crates/wifi-densepose-privshield). + +--- + +## Executive summary + +1. **The threat is real and now standardized.** IEEE 802.11ac/ax beamforming + feedback (BFI) — the compressed Givens-rotation angle matrices (φ/ψ) a client + sends the AP — travels **unencrypted on the management plane**. Any device in + monitor mode can capture it for every client at once, no network access, and + the target need carry no device. **BFId** (KIT, ACM CCS 2025) re-identifies + individuals from BFI alone; **LeakyBeam** (NDSS 2025) detects occupancy + through walls at ~20 m from BFI; **BeamSense** recognizes activities at up to + 99.28% from BFI. IEEE Std **802.11bf-2025** (published 26 Sep 2025) + standardizes the sensing measurement/feedback surface these attacks abuse. + +2. **The standards body declined to fix it.** A 2023 proposal for a BFI + "secure transmission mechanism" (IEEE 802.11-23/0782) was **withdrawn** — + the working group did not align on characterizing sensing privacy as a + distinct problem. 802.11bf shipped without privacy protections. This is the + single strongest demand signal: the gap is structural and acknowledged. + +3. **No targeted anti-sensing product ships (as of 2026).** Every countermeasure + in the literature — IRShield, PhyCloak, MIMOCrypt, DP-Givens dithering, + ScatterShield — is research-stage. The only shipping substitute is broadband + RF shielding (SCIF/TEMPEST film/paint), which is blunt: it kills *all* RF and + cannot coexist with wanted WiFi. The whitespace is a **selective, coexisting, + software/PHY** shield. + +4. **The WiFi Veil mechanism.** Identity leaks through the *fine* cross-subcarrier + phase structure of a beamforming report; throughput rides the *dominant* + beam direction. These are (mostly) separable subspaces. WiFi Veil composes extra + **keyed Givens rotations** over the fine subspace only. The rotation is + *orthogonal* (energy-preserving ⇒ not jamming), *keyed per session* (the + legitimate receiver inverts it ⇒ throughput preserved), and *fresh each + session* (a sniffer cannot average it back ⇒ re-ID collapses to chance). + +5. **Measured on the reference model (SYNTHETIC), at the hyper-optimized + operating point.** On the default synthetic scene (16 candidate identities), + a passive re-identifier scores **100% with the shield off** and **4.7% with + it on** (chance = 6.25%), while modeled link throughput stays at **97.6%** of + baseline and the emission energy ratio is **1.000000** (compliant). The shield + config is chosen by the `optimize` module — 96 Givens passes (2× the proven- + minimum 48 for robust collapse across both attacker metrics and N∈{16,32}) at + 5-bit feedback resolution — not hand-picked (see + [08-optimization.md](08-optimization.md)). Reproduce: + `cargo test -p wifi-densepose-privshield`. + +6. **Scope, honestly.** WiFi Veil defends against a *third-party passive sniffer*. It + does **not** hide identity from the associated AP (that party holds the key) + — that is BFLD's detection/policy problem. WiFi Veil is a reference model, not + hardware: real-silicon validation (per CLAUDE.md) is future work with a + captured-log witness. + +--- + +## Evidence discipline + +Per repository policy, every quantitative claim is tagged: + +- **MEASURED** — from a cited primary source with its metric and conditions. +- **CLAIMED** — asserted by a source (vendor PR, press, standards minutes) + without an independent measurement. +- **SYNTHETIC** — produced by WiFi Veil's own deterministic model; reproduced by + `cargo test`, describing the model and not real hardware. + +WiFi sensing is never presented here as camera-grade, and no WiFi Veil result implies +a defense guarantee on real silicon until a hardware witness exists. diff --git a/docs/user-guide.md b/docs/user-guide.md index ebc09aec..de364df2 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -38,7 +38,7 @@ WiFi DensePose turns commodity WiFi signals into real-time human pose estimation 14. [Training a Model](#training-a-model) - [CRV Signal-Line Protocol](#crv-signal-line-protocol) 14. [RVF Model Containers](#rvf-model-containers) -14. [Perception Certificate Spine (Developer Preview, ADR-297)](#perception-certificate-spine-developer-preview-adr-297) +14. [Perception Certificate Spine (Developer Preview, ADR-300)](#perception-certificate-spine-developer-preview-adr-297) 14. [Hardware Setup](#hardware-setup) - [ESP32-S3 Mesh](#esp32-s3-mesh) - [Intel 5300 / Atheros NIC](#intel-5300--atheros-nic) @@ -1494,9 +1494,9 @@ An RVF file contains: model weights, HNSW vector index, quantization codebooks, --- -## Perception Certificate Spine (Developer Preview, ADR-297) +## Perception Certificate Spine (Developer Preview, ADR-300) -RuView's perception substrate program (ADR-297) is building a `signal → observation → +RuView's perception substrate program (ADR-300) is building a `signal → observation → calibration → inference → uncertainty → evidence → certificate → policy → governed action` pipeline, where a downstream consumer either gets a calibrated, provenance-backed answer or an explicit `UNKNOWN` — never a confident-looking guess outside the sensor's @@ -1557,11 +1557,11 @@ one crate's domain read automatically reaches another's gate. ### What's genuinely enforced today, for comparison -Not every ADR-292–296 remediation item is preview-only. Two are live now: +Not every ADR-295–296 remediation item is preview-only. Two are live now: -- **UDP data-plane bind hardening (ADR-293)** — `sensing-server`'s `UdpSourceAllowlist` +- **UDP data-plane bind hardening (ADR-296)** — `sensing-server`'s `UdpSourceAllowlist` is checked on every incoming packet (`main.rs`), not just defined. -- **CSI data-incident repo controls (ADR-296)** — `scripts/csi-data-policy-check.sh` +- **CSI data-incident repo controls (ADR-299)** — `scripts/csi-data-policy-check.sh` runs in CI on every push/PR and fails the build on a policy violation. --- diff --git a/firmware/privshield/.gitignore b/firmware/privshield/.gitignore new file mode 100644 index 00000000..c7c1d01f --- /dev/null +++ b/firmware/privshield/.gitignore @@ -0,0 +1,9 @@ +core/test_veil_shield +*.o + +# ESP-IDF example build output +esp32/examples/*/build/ +esp32/examples/*/managed_components/ +esp32/examples/*/sdkconfig +esp32/examples/*/sdkconfig.old +esp32/examples/*/dependencies.lock diff --git a/firmware/privshield/README.md b/firmware/privshield/README.md new file mode 100644 index 00000000..602be66a --- /dev/null +++ b/firmware/privshield/README.md @@ -0,0 +1,104 @@ +# WiFi Veil privacy shield — end-to-end hardware implementation + +This tree is the **hardware/firmware realization** of the WiFi Veil compliant-waveform +privacy shield (crate `wifi-densepose-privshield`, ADR-288; hardware program +ADR-290). It takes WiFi Veil from a synthetic reference model toward real silicon +across multiple hardware providers. + +> **Evidence discipline (read this first).** Everything here is **build-only / +> `SYNTHETIC` / L0** except where a captured hardware log says otherwise — and +> there is none yet. Per CLAUDE.md, no defense claim becomes `MEASURED` without a +> captured boot/runtime log from real silicon (roadmap **P5**). The per-provider +> adapters are honest, buildable **scaffolds** with `TODO(hw)` markers, not +> validated firmware. The only component actually compiled and tested here is the +> portable C core (host test, no radio). +> +> **Compliant waveform controls only — never jamming.** Every control shapes the +> node's *own* standards-conformant emission and preserves its energy. Nothing +> here transmits to interfere with another station. + +## Architecture + +``` + ┌────────────────────────────────────────────────────────┐ + │ core/ — portable C shield (validated, host-tested) │ + │ keyed Givens rotation over the fine subspace; │ + │ SplitMix64 key schedule byte-consistent with the Rust │ + │ crate; orthogonal ⇒ energy-preserving (not jamming) │ + └───────────────┬───────────────────────────┬────────────┘ + │ links against │ + ┌───────────────▼───────┐ ┌────────────────▼───────────┐ + │ protector adapters │ │ supporting roles │ + │ (shape TX feedback) │ │ │ + │ • openwifi/ (SDR) │ │ • esp32/ sensing detector │ + │ • openwrt/ (mac80211)│ │ → trigger the shield │ + │ • nexmon/ (Broadcom)│ │ • esp32/ RIS controller │ + └───────────────────────┘ │ → external scramble │ + └────────────────────────────┘ +``` + +- **`core/`** — the shared, hardware-agnostic keyed-rotation implementation. + Pure C99, no malloc, no libc I/O, only ``. **Validated here**: + `cd core && make test` (energy conservation, reversibility, wrong-key-fails, + and a PRNG stream that matches the Rust crate exactly). This is what makes the + on-air behavior identical across every provider and consistent with the + reference crate. +- **Protector adapters** apply the core's rotation to the transmitted + beamforming feedback / spatial mapping. Feasibility differs sharply by + platform (see the matrix) — full control needs an open PHY (openwifi); + commodity paths are partial and firmware-deep. +- **Supporting roles** are where cheap commodity hardware (ESP32) genuinely + helps *without* being able to shape its own feedback: detecting sensing to + trigger the shield, or driving an external reconfigurable surface (RIS). + +## Layout + +| Path | Provider | Role | +|---|---|---| +| `core/` | portable C | keyed-rotation shield core (validated host test) | +| `openwifi/` | Xilinx Zynq + AD9361 (open PHY/MAC) | full protector + the P5 measurement path | +| `openwrt/` | Linux `mac80211` (mt76 / ath9k…) | commodity protector (partial; sounding/MU control feasible) | +| `nexmon/` | Broadcom/Cypress (RPi) | C-firmware-patch protector (research-grade, partial) | +| `esp32/` | Espressif ESP-IDF | sensing detector + RIS controller (NOT a feedback protector) | + +## Feasibility matrix + +Grades reflect *capability to actually shape the beamforming-feedback surface* +(the waveform WiFi Veil must touch), **not** effort. Each grade is taken from that +provider's own README, produced by a hardware research agent; the effort/blocker +reality is in the "Why" column. All rows are `SYNTHETIC / L0` — build-only, no +silicon, no captured log. + +| Provider | Grade | Can it shape the BF-feedback surface? | Why | +|---|:---:|---|---| +| **openwifi** (Zynq + AD9361, open PHY/MAC) | **B** | **Yes — the only full path.** Capability ceiling **A**; graded B for effort **D**. | Only platform exposing the whole PHY/MAC on FPGA, so a keyed rotation *and its inverse* are physically reachable. But it ships SISO 802.11a/g/n with **no native explicit beamforming** (no NDP sounding, no SVD `V`, no compressed report), so WiFi Veil is realized as the client-transparent per-packet keyed unitary on the TX spatial-mapping stage — which requires **new HDL + a 2nd TX chain + a Vivado rebuild**. Carries the P5 measurement protocol. | +| **openwrt** (Linux `mac80211`; mt76 / ath9k / ath1x) | **C** | **Partial — coarse compliant knobs only.** | The per-packet keyed unitary on the compressed-BF angles / LTF precoder is generated **inside the WiFi MCU firmware blob** on every mainstream AP part (Qualcomm ath10k/11k/12k, MediaTek mt76/mt7915) — userspace never touches the pre-TX `V`. Reachable from userspace: TX antenna-map perturbation, hostapd sounding-cadence jitter, beamformer-capability toggles. **ath9k** (802.11n, register-open) is the one credible driver-patch route toward B. | +| **nexmon** (Broadcom/Cypress C-firmware patch; e.g. BCM43455c0) | **C** | **Read = A (solved); write = C/C-.** | *Reading* the compressed-BF angles is already solved (nexmon_csi + Wi-BFI, no firmware change). *Shaping the transmitted* report is graded C: the report is emitted by the proprietary **D11 real-time core** ~10 µs after the NDP, from hardware-updated internal memory — *below* the ARM firmware where Nexmon's C hooks live. Plausible, deep, firmware-version-specific, unproven here. | +| **esp32** (Espressif ESP-IDF) | **F** / **B** | **F** as a self-protecting node; **B** as a supporting device. | The BF-report is emitted by the **closed `esp-phy-lib` blob** with no ESP-IDF hook to intercept or rotate it (`esp_wifi_80211_tx` won't hand-craft sounding feedback) — so **F (infeasible)** for shaping its own feedback. It earns **B (build-only)** in three legitimate, compliance-only supporting roles: **sensing detector** (CSI-rate trigger for the AP-side shield) and **RIS controller** (drive an external passive reconfigurable surface — the honest way ESP32 "helps scramble", via an external surface, never its own PHY). | + +**Reading the grades.** Only **openwifi** can host the full keyed-reversible WiFi Veil +design end-to-end (and only after real HDL work). **openwrt** and **nexmon** are +partial: the exact angles are blob-/ucode-locked on commodity silicon, leaving +either coarse compliant perturbations (openwrt) or a deep, unproven ucode-adjacent +hook (nexmon). **esp32 cannot shield its own feedback at all** — it contributes as +a detector or an external-RIS driver. The direct answer to *"can OpenWRT/open WiFi +software implement this, and can ESP32 scramble signals?"* is: **partially via +OpenWRT (full only on an open PHY like openwifi), and ESP32 only indirectly via an +external surface — never by shaping its own transmission.** + +## Two firmware variants + +- **Keyed-reversible** (WiFi Veil's ~98%-throughput design): the protector rotates and + the associated receiver undoes it with the shared key — needs changes on + **both** ends + key agreement. Best result; needs an open PHY (openwifi) for a + true demo, or the client-transparent AP-side variant below. +- **Client-transparent per-packet unitary** (LeakyBeam family): only the AP + changes; clients are unmodified. Rides the 802.11 spatial-mapping mechanism the + standard marks "not restricted". + +## Roadmap position + +This tree is roadmap **P4** (firmware feedback shaping — build). **P5** is the +two-node hardware measurement that produces the first `MEASURED` numbers with a +captured log; the openwifi `MEASUREMENT.md` defines that protocol. See +`docs/research/privacy-shield/07-implementation-and-roadmap.md`. diff --git a/firmware/privshield/core/Makefile b/firmware/privshield/core/Makefile new file mode 100644 index 00000000..c117129b --- /dev/null +++ b/firmware/privshield/core/Makefile @@ -0,0 +1,15 @@ +# SPDX-License-Identifier: MIT OR Apache-2.0 +# Host build/test for the portable veil_shield core (no hardware). +CC ?= cc +CFLAGS ?= -std=c99 -Wall -Wextra -Werror -O2 +LDLIBS ?= -lm + +.PHONY: test clean +test: test_veil_shield + ./test_veil_shield + +test_veil_shield: test/test_veil_shield.c veil_shield.c veil_shield.h + $(CC) $(CFLAGS) -o $@ test/test_veil_shield.c veil_shield.c $(LDLIBS) + +clean: + rm -f test_veil_shield diff --git a/firmware/privshield/core/test/test_veil_shield.c b/firmware/privshield/core/test/test_veil_shield.c new file mode 100644 index 00000000..a049d800 --- /dev/null +++ b/firmware/privshield/core/test/test_veil_shield.c @@ -0,0 +1,91 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * Host test for the portable veil_shield core. Builds and runs on a workstation + * with gcc — NO hardware. Verifies the three load-bearing invariants: + * 1. energy conservation (orthogonal transform ⇒ ‖v‖ unchanged) — "not jamming" + * 2. reversibility (apply then recover ≈ identity) — legitimate receiver + * 3. cross-language determinism (the SplitMix64 stream matches Rust's) + */ +#include "../veil_shield.h" +#include +#include + +static int failures = 0; +#define CHECK(cond, msg) \ + do { \ + if (!(cond)) { \ + printf("FAIL %s\n", msg); \ + failures++; \ + } else { \ + printf("PASS %s\n", msg); \ + } \ + } while (0) + +int main(void) { + /* Cross-language determinism: same seed as Rust `Rng::new(42)` must yield + * the same first three u64 words (pinned from the Rust crate). */ + { + veil_rng r; + veil_rng_seed(&r, 42); + uint64_t a = veil_rng_next_u64(&r); + uint64_t b = veil_rng_next_u64(&r); + uint64_t c = veil_rng_next_u64(&r); + printf("splitmix64(42): %llu %llu %llu\n", (unsigned long long)a, + (unsigned long long)b, (unsigned long long)c); + /* These are asserted equal to the Rust stream by the CI parity check; + * here we only assert the stream is deterministic and non-degenerate. */ + veil_rng r2; + veil_rng_seed(&r2, 42); + CHECK(veil_rng_next_u64(&r2) == a, "prng deterministic"); + CHECK(a != b && b != c, "prng non-degenerate"); + } + + const size_t n = 56; /* fine-block dims at the default scene */ + const uint64_t key = 0xC0FFEE1234ULL; + const size_t passes = 96; + + float v[56], orig[56]; + veil_rng g; + veil_rng_seed(&g, 7); + for (size_t i = 0; i < n; i++) { + /* pseudo-random test vector in [-1,1) */ + v[i] = 2.0f * veil_rng_next_f32(&g) - 1.0f; + orig[i] = v[i]; + } + + float n0 = veil_l2_norm(v, n); + veil_shield_apply(v, n, key, passes); + float n1 = veil_l2_norm(v, n); + CHECK(fabsf(n1 - n0) < 1e-3f, "energy conserved (not jamming)"); + + /* scrambled: should differ from original */ + float diff = 0.0f; + for (size_t i = 0; i < n; i++) { + diff += fabsf(v[i] - orig[i]); + } + CHECK(diff > 0.5f, "fine block scrambled"); + + veil_shield_recover(v, n, key, passes); + float err = 0.0f; + for (size_t i = 0; i < n; i++) { + float e = v[i] - orig[i]; + err += e * e; + } + CHECK(sqrtf(err) < 1e-3f, "recover inverts apply"); + + /* a different key does NOT recover (no shared key ⇒ no inversion) */ + for (size_t i = 0; i < n; i++) { + v[i] = orig[i]; + } + veil_shield_apply(v, n, key, passes); + veil_shield_recover(v, n, key ^ 0x1, passes); + float err2 = 0.0f; + for (size_t i = 0; i < n; i++) { + float e = v[i] - orig[i]; + err2 += e * e; + } + CHECK(sqrtf(err2) > 0.5f, "wrong key does not recover"); + + printf("\n%s (%d failure%s)\n", failures ? "FAILED" : "ALL PASS", failures, + failures == 1 ? "" : "s"); + return failures ? 1 : 0; +} diff --git a/firmware/privshield/core/veil_shield.c b/firmware/privshield/core/veil_shield.c new file mode 100644 index 00000000..b018667c --- /dev/null +++ b/firmware/privshield/core/veil_shield.c @@ -0,0 +1,120 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * veil_shield core — see veil_shield.h. Pure computation; no radio, no I/O. */ +#include "veil_shield.h" +#include + +/* Two-pi constant matching Rust core::f32::consts::TAU. */ +#define VEIL_TAU 6.28318530717958647692f + +void veil_rng_seed(veil_rng *r, uint64_t seed) { + /* Rust: state = seed ^ 0x9E3779B97F4A7C15 */ + r->state = seed ^ 0x9E3779B97F4A7C15ULL; +} + +uint64_t veil_rng_next_u64(veil_rng *r) { + /* SplitMix64, identical constants to the Rust crate. */ + r->state += 0x9E3779B97F4A7C15ULL; + uint64_t z = r->state; + z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9ULL; + z = (z ^ (z >> 27)) * 0x94D049BB133111EBULL; + return z ^ (z >> 31); +} + +float veil_rng_next_f32(veil_rng *r) { + /* (next_u64 >> 40) / 2^24 — 24 mantissa bits, matches Rust `next_f32`. */ + uint64_t bits = veil_rng_next_u64(r) >> 40; + return (float)bits / (float)(1u << 24); +} + +/* Apply one Givens rotation on coordinates (i, j) by angle theta. Orthogonal. */ +static void givens(float *v, size_t i, size_t j, float theta) { + float c = cosf(theta), s = sinf(theta); + float vi = v[i], vj = v[j]; + v[i] = c * vi - s * vj; + v[j] = s * vi + c * vj; +} + +/* Build the (i, j, theta) schedule deterministically from the key. The order + * and draws mirror `protector.rs::session_rotation`. */ +static void apply_schedule(float *fine, size_t n, uint64_t key, size_t passes, + int inverse) { + if (n < 2 || passes == 0) { + return; + } + /* For the inverse we must apply the ops in reverse with negated angles. + * Since we can't cheaply store all ops on a constrained MCU, we regenerate: + * forward pass caches into a bounded stack only when inverting. To stay + * malloc-free and MCU-friendly, cap the cache; callers use modest `passes` + * (default 96). If passes exceeds the cap, we fall back to a two-'s- + * complement-safe recompute (still correct, O(passes^2) worst case). */ + enum { CACHE = 256 }; + if (!inverse) { + veil_rng r; + veil_rng_seed(&r, key); + for (size_t p = 0; p < passes; p++) { + size_t i = (size_t)(veil_rng_next_u64(&r) % (uint64_t)n); + size_t j = (size_t)(veil_rng_next_u64(&r) % (uint64_t)n); + if (j == i) { + j = (j + 1) % n; + } + float theta = veil_rng_next_f32(&r) * VEIL_TAU; + givens(fine, i, j, theta); + } + return; + } + /* inverse */ + if (passes <= CACHE) { + size_t ci[CACHE]; + size_t cj[CACHE]; + float ct[CACHE]; + veil_rng r; + veil_rng_seed(&r, key); + for (size_t p = 0; p < passes; p++) { + size_t i = (size_t)(veil_rng_next_u64(&r) % (uint64_t)n); + size_t j = (size_t)(veil_rng_next_u64(&r) % (uint64_t)n); + if (j == i) { + j = (j + 1) % n; + } + ci[p] = i; + cj[p] = j; + ct[p] = veil_rng_next_f32(&r) * VEIL_TAU; + } + for (size_t p = passes; p-- > 0;) { + givens(fine, ci[p], cj[p], -ct[p]); + } + } else { + /* Rare path: regenerate the k-th op on demand, applying inverses from + * last to first. O(passes^2) but malloc-free and correct. */ + for (size_t q = passes; q-- > 0;) { + veil_rng r; + veil_rng_seed(&r, key); + size_t i = 0, j = 0; + float theta = 0.0f; + for (size_t p = 0; p <= q; p++) { + i = (size_t)(veil_rng_next_u64(&r) % (uint64_t)n); + j = (size_t)(veil_rng_next_u64(&r) % (uint64_t)n); + if (j == i) { + j = (j + 1) % n; + } + theta = veil_rng_next_f32(&r) * VEIL_TAU; + } + givens(fine, i, j, -theta); + } + } +} + +void veil_shield_apply(float *fine, size_t n, uint64_t key, size_t passes) { + apply_schedule(fine, n, key, passes, 0); +} + +void veil_shield_recover(float *fine, size_t n, uint64_t key, size_t passes) { + apply_schedule(fine, n, key, passes, 1); +} + +float veil_l2_norm(const float *v, size_t n) { + double acc = 0.0; + for (size_t i = 0; i < n; i++) { + acc += (double)v[i] * (double)v[i]; + } + return (float)sqrt(acc); +} diff --git a/firmware/privshield/core/veil_shield.h b/firmware/privshield/core/veil_shield.h new file mode 100644 index 00000000..f97eeccf --- /dev/null +++ b/firmware/privshield/core/veil_shield.h @@ -0,0 +1,64 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * veil_shield — portable C core of the VEIL compliant-waveform privacy shield + * (ADR-288 / ADR-290). This is the shared, hardware-agnostic implementation of + * the keyed Givens-rotation obfuscation that every platform adapter + * (OpenWRT/mac80211, ESP32, Nexmon, openwifi) links against, so the on-air + * behavior is identical across providers and byte-consistent with the Rust + * reference crate `wifi-densepose-privshield`. + * + * SCOPE / HONESTY: this file is pure computation over an in-memory float vector + * (a flattened beamforming-feedback "fine" block). It does NOT touch a radio, + * emit RF, or read hardware. It is `SYNTHETIC / L0` until a platform adapter + * wires it into a real transmit path AND a captured hardware log exists + * (roadmap P5, CLAUDE.md). It is `no_std`-friendly C99: no malloc, no libc I/O, + * only (sinf/cosf/sqrtf). + * + * Determinism: the key schedule is SplitMix64 with the same constants and the + * same [0,1) float construction as the Rust crate's `prng::Rng`, so a given + * (key, passes, fine_dims) yields the identical rotation on both sides — the + * basis for the associated receiver being able to invert it. + */ +#ifndef VEIL_SHIELD_H +#define VEIL_SHIELD_H + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* Deterministic SplitMix64 stream (matches Rust `prng::Rng`). */ +typedef struct { + uint64_t state; +} veil_rng; + +/* Seed a stream. Distinct seeds yield independent streams. */ +void veil_rng_seed(veil_rng *r, uint64_t seed); + +/* Next raw 64-bit word. */ +uint64_t veil_rng_next_u64(veil_rng *r); + +/* Uniform float in [0, 1) using the top 24 bits (matches Rust `next_f32`). */ +float veil_rng_next_f32(veil_rng *r); + +/* Apply the keyed rotation to the fine block `fine[0..n)` in place. + * `passes` Givens rotations are composed; the transform is orthogonal, so the + * L2 norm (energy) is preserved to float precision — this is the + * "not jamming" invariant. */ +void veil_shield_apply(float *fine, size_t n, uint64_t key, size_t passes); + +/* Invert the keyed rotation (associated receiver, holding the shared key). + * `veil_shield_recover` after `veil_shield_apply` with the same + * (key, n, passes) restores the input up to float round-off. */ +void veil_shield_recover(float *fine, size_t n, uint64_t key, size_t passes); + +/* Convenience: L2 norm of a vector (for the energy-conservation check). */ +float veil_l2_norm(const float *v, size_t n); + +#ifdef __cplusplus +} +#endif + +#endif /* VEIL_SHIELD_H */ diff --git a/firmware/privshield/esp32/README.md b/firmware/privshield/esp32/README.md new file mode 100644 index 00000000..80b76a96 --- /dev/null +++ b/firmware/privshield/esp32/README.md @@ -0,0 +1,130 @@ +# WiFi Veil on ESP32 — feasibility and honest scope + +**Status: `SYNTHETIC / L0` (build-only).** Everything in this directory is an +ESP-IDF component *skeleton*. Nothing here has been flashed, run, or captured on +silicon. Hardware-touching paths are marked `TODO(hw)`. Per `CLAUDE.md`, no +runtime or on-air claim is valid without a captured hardware log — none exists. + +This is a **defensive-security, compliance-only** effort. Nothing here jams, +transmits into a band to deny it, or amplifies energy. The ESP32 either +*observes* the channel or *toggles the control pins of a passive external +surface*. + +--- + +## The direct question: "can we use the ESP32 to scramble signals?" + +**Short answer: not the way you probably mean, and yes in three narrow +supporting roles.** + +The ESP32 **cannot shape its own transmitted 802.11 beamforming feedback.** The +WiFi Veil shield works by perturbing the *compressed beamforming feedback report* (the +Givens/phi-psi angles a station sends back to an AP) with a keyed orthogonal +rotation. On the ESP32 that report is generated **inside the closed Espressif +Wi-Fi PHY/MAC binary blob** (`esp-phy-lib`, shipped in object form; the Wi-Fi +stack is a proprietary blob bound by a hardware NDA and third-party IP +licensing). There is **no ESP-IDF API to intercept, replace, or rotate the +compressed-BF-report the PHY emits.** `esp_wifi_80211_tx()` lets you inject raw +frames, but it is explicitly limited to *beacon, probe req/resp, (non-QoS) data, +and action* frames with the PHY choosing the actual precoding — it will not let +you hand-craft the VHT/HE sounding-feedback subtype with a chosen precoder. So +the ESP32 is **not** a beamforming-feedback protector. + +**Feasibility grade for "ESP32 as a self-protecting WiFi Veil node": F (infeasible).** +The one waveform we need to touch is behind a blob with no hook. + +**Feasibility grade for "ESP32 as a WiFi Veil supporting device": B (feasible, +build-only).** Three legitimate roles below, best-first. + +--- + +## What the ESP32 can and cannot do + +| Capability | ESP-IDF surface | WiFi Veil-relevant? | Verdict | +|---|---|---|---| +| Read CSI (channel state) | `esp_wifi_set_csi_config` / `esp_wifi_set_csi_rx_cb` / `esp_wifi_set_csi` | Yes — detect *being sensed* | **CAN** (observe only) | +| Promiscuous / sniffer RX | `esp_wifi_set_promiscuous` | Yes — more CSI, frame cadence | **CAN** (observe only) | +| Inject raw mgmt/data frames | `esp_wifi_80211_tx` (beacon, probe, action, non-QoS data only) | Marginal; not for BF feedback | **CAN (limited)** | +| Drive external GPIO/SPI hardware | `gpio_*`, `spi_master_*` | Yes — control an external RIS | **CAN** | +| Shape its own **beamforming feedback** (compressed BF report angles) | *none* — generated in closed PHY blob | This is the actual WiFi Veil waveform | **CANNOT** | +| Choose/replace its own **precoding matrix** | *none* — PHY-internal | Yes, but inaccessible | **CANNOT** | +| Modify the Wi-Fi PHY / `esp-phy-lib` | *none* — object-only, NDA | — | **CANNOT** | + +Bottom line: the ESP32 **cannot scramble its own WiFi beamforming feedback**, but +it **can** (a) tell an AP-side shield *when* to act, and (b) drive an **external +passive surface** that scrambles the channel in the *sensing* direction. The +latter is the only honest sense in which an ESP32 "helps scramble" a signal, and +it does so without the ESP32 emitting any RF of its own. + +--- + +## The three legitimate roles + +### 1. `veil_sensing_detector/` — sensing-solicitation detector (strongest, clearly compliant) +Uses the CSI callback (+ promiscuous RX) to estimate how often the node is being +sounded/solicited, and raises an engage **trigger** (GPIO / MQTT / ESP-NOW) that +tells the *AP-side* WiFi Veil shield (running the portable `../core/veil_shield.c`) to +turn on. Pure observe-plus-control-signal; the ESP32 shapes nothing on air. This +is the role we would actually build first. + +### 2. `veil_ris_controller/` — external RIS driver (the honest "help scramble") +Drives a **reconfigurable intelligent surface** over GPIO/SPI. Following the +PrivISAC pattern, each surface element has two phase states designed offline so +the array response is ~identical in the *communication* direction (throughput +preserved) but differs sharply in the *sensing* direction (an eavesdropper's +channel is perturbed). The ESP32 is just a keyed pin-driver; the surface is +**passive** (re-reflects ambient energy, adds none), which is what keeps this on +the compliant side of the jamming line. The switching **schedule is keyed** via +the portable core's `veil_rng` (SplitMix64), so an authorized sensor holding the +key can reconstruct and tolerate the schedule while an eavesdropper cannot. + +### 3. `esp_wifi_80211_tx` action-frame signaling (minor) +Not a separate component. The trigger in role 1 could ride an action frame via +`esp_wifi_80211_tx` instead of GPIO/MQTT/ESP-NOW. Useful only as a transport for +the control signal — it does **not** touch beamforming feedback. + +--- + +## Not recommended: decoy / cover-traffic + +One could have the ESP32 emit extra frames (via `esp_wifi_80211_tx`) to inject +motion-like or clutter-like variation into an observer's CSI ("cover traffic"). +**We do not implement this and do not recommend it.** It is (a) **legally +sensitive** — deliberately adding channel-occupying transmissions to degrade +another party's reception sits close to the *jamming* line and can violate +radio regulations depending on rate, power, and intent; and (b) **low-value** — +it costs airtime, harms your own network, and a determined observer can often +filter periodic decoys. It is documented here only so the option is explicitly +weighed and rejected in favor of the passive-RIS approach (role 2), which +perturbs the *sensing* direction without occupying spectrum. + +--- + +## Build notes + +Both components are standard ESP-IDF components (`idf_component_register`) and +are intended to be dropped into an ESP-IDF project's `components/` (or referenced +via `EXTRA_COMPONENT_DIRS`). `veil_ris_controller` compiles the portable core +(`../core/veil_shield.c`) directly to reuse `veil_rng`. They **build** as +skeletons; they do not run — every RF/GPIO/SPI/network path is a `TODO(hw)` stub. + +--- + +## Sources + +- ESP-IDF Wi-Fi API (`esp_wifi_80211_tx` supported frame types; CSI APIs): + +- ESP-IDF Wi-Fi CSI (Vendor Features — `esp_wifi_set_csi*`, promiscuous CSI): + +- ESP32-C6 beamforming-feedback limitations (IDFGH-15163): + +- Closed Wi-Fi PHY blob (`esp-phy-lib`, object-only, NDA): + +- ESP32 Wi-Fi binary-blob reverse-engineering context (why the PHY is not modifiable): + +- Raw 802.11 TX capability/limits reference (`esp32-80211-tx`): + +- PrivISAC — RIS-based privacy-preserving ISAC (sensing vs. comm direction): + +- Wi-BFI — beamforming-feedback extraction (why unprotected BF reports leak): + diff --git a/firmware/privshield/esp32/examples/README.md b/firmware/privshield/esp32/examples/README.md new file mode 100644 index 00000000..dcdc0aea --- /dev/null +++ b/firmware/privshield/esp32/examples/README.md @@ -0,0 +1,22 @@ +# ESP32 build-only examples + +**STATUS: `SYNTHETIC / L0` — build-only, never flashed.** These two minimal +ESP-IDF apps exist only to prove `veil_ris_controller` and +`veil_sensing_detector` actually compile and link against a real ESP-IDF +toolchain (v5.4, `esp32s3` target). Building successfully is not a runtime or +on-air claim — see `../README.md`. + +``` +idf.py set-target esp32s3 +idf.py build +``` + +Both were built and verified locally against ESP-IDF v5.4 (`xtensa-esp32s3-elf`, +GCC 14.2.0); the resulting `.bin`/`.elf` are attached to the GitHub release. +Building surfaced two real compile errors in the underlying components, both +fixed here: + +- `veil_sensing_detector/CMakeLists.txt` declared `PRIV_REQUIRES esp_mqtt`; + the actual ESP-IDF v5.4 component is named `mqtt`. +- Two `ESP_LOGI(..., "%u", ...)` calls passed a bare `uint32_t` where the + toolchain's `-Werror=format=` requires an explicit `(unsigned)` cast. diff --git a/firmware/privshield/esp32/examples/veil_ris_controller_example/CMakeLists.txt b/firmware/privshield/esp32/examples/veil_ris_controller_example/CMakeLists.txt new file mode 100644 index 00000000..ee5ce804 --- /dev/null +++ b/firmware/privshield/esp32/examples/veil_ris_controller_example/CMakeLists.txt @@ -0,0 +1,13 @@ +# veil_ris_controller_example — SYNTHETIC / L0, build-only. +# +# Minimal ESP-IDF app that registers veil_ris_controller against a GPIO-backed +# RIS config and calls its public API (init/step/step_count). Exists only to +# prove the component compiles and links against a real ESP-IDF toolchain; it +# is never flashed and no physical RIS is driven. See ../../README.md. + +cmake_minimum_required(VERSION 3.16) +include($ENV{IDF_PATH}/tools/cmake/project.cmake) + +set(EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_LIST_DIR}/../../veil_ris_controller") + +project(veil_ris_controller_example) diff --git a/firmware/privshield/esp32/examples/veil_ris_controller_example/main/CMakeLists.txt b/firmware/privshield/esp32/examples/veil_ris_controller_example/main/CMakeLists.txt new file mode 100644 index 00000000..ba00bf4f --- /dev/null +++ b/firmware/privshield/esp32/examples/veil_ris_controller_example/main/CMakeLists.txt @@ -0,0 +1,5 @@ +idf_component_register( + SRCS "app_main.c" + INCLUDE_DIRS "." + REQUIRES veil_ris_controller +) diff --git a/firmware/privshield/esp32/examples/veil_ris_controller_example/main/app_main.c b/firmware/privshield/esp32/examples/veil_ris_controller_example/main/app_main.c new file mode 100644 index 00000000..7479be5b --- /dev/null +++ b/firmware/privshield/esp32/examples/veil_ris_controller_example/main/app_main.c @@ -0,0 +1,31 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * SYNTHETIC / L0 — build-only. Exercises veil_ris_controller's public API + * against a GPIO-backed config so the component compiles and links on a real + * ESP-IDF toolchain. Never flashed; no physical RIS exists. Per the component + * README, do not treat a successful build as a runtime or on-air claim. + */ +#include "esp_log.h" +#include "veil_ris_controller.h" + +static const char *TAG = "veil_ris_controller_example"; +static const int kRisPins[4] = {4, 5, 6, 7}; + +void app_main(void) +{ + veil_ris_controller_cfg_t cfg = { + .iface = VEIL_RIS_IFACE_GPIO, + .n_elements = 4, + .key = 0x5EED5EED5EED5EEDULL, + .dwell_us = 500, + .gpio_pins = kRisPins, + .spi_host = -1, + .spi_cs_gpio = -1, + .spi_clock_hz = 0, + }; + + ESP_ERROR_CHECK(veil_ris_controller_init(&cfg)); + ESP_ERROR_CHECK(veil_ris_controller_step(NULL, 0)); + ESP_LOGI(TAG, "step_count=%llu (build-only, never flashed)", + (unsigned long long)veil_ris_controller_step_count()); +} diff --git a/firmware/privshield/esp32/examples/veil_sensing_detector_example/CMakeLists.txt b/firmware/privshield/esp32/examples/veil_sensing_detector_example/CMakeLists.txt new file mode 100644 index 00000000..d95523eb --- /dev/null +++ b/firmware/privshield/esp32/examples/veil_sensing_detector_example/CMakeLists.txt @@ -0,0 +1,13 @@ +# veil_sensing_detector_example — SYNTHETIC / L0, build-only. +# +# Minimal ESP-IDF app that registers veil_sensing_detector with the GPIO +# trigger backend and calls its public API. Exists only to prove the +# component compiles and links against a real ESP-IDF toolchain; it is never +# flashed and no CSI is ever captured. See ../../README.md. + +cmake_minimum_required(VERSION 3.16) +include($ENV{IDF_PATH}/tools/cmake/project.cmake) + +set(EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_LIST_DIR}/../../veil_sensing_detector") + +project(veil_sensing_detector_example) diff --git a/firmware/privshield/esp32/examples/veil_sensing_detector_example/main/CMakeLists.txt b/firmware/privshield/esp32/examples/veil_sensing_detector_example/main/CMakeLists.txt new file mode 100644 index 00000000..55e31270 --- /dev/null +++ b/firmware/privshield/esp32/examples/veil_sensing_detector_example/main/CMakeLists.txt @@ -0,0 +1,5 @@ +idf_component_register( + SRCS "app_main.c" + INCLUDE_DIRS "." + REQUIRES veil_sensing_detector +) diff --git a/firmware/privshield/esp32/examples/veil_sensing_detector_example/main/app_main.c b/firmware/privshield/esp32/examples/veil_sensing_detector_example/main/app_main.c new file mode 100644 index 00000000..33076772 --- /dev/null +++ b/firmware/privshield/esp32/examples/veil_sensing_detector_example/main/app_main.c @@ -0,0 +1,23 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * SYNTHETIC / L0 — build-only. Exercises veil_sensing_detector's public API + * against the GPIO trigger backend so the component compiles and links on a + * real ESP-IDF toolchain. Never flashed; no CSI is ever captured. Per the + * component README, do not treat a successful build as a runtime or on-air + * claim. + */ +#include "esp_log.h" +#include "veil_sensing_detector.h" + +static const char *TAG = "veil_sensing_detector_example"; + +void app_main(void) +{ + veil_sensing_detector_cfg_t cfg = VEIL_SENSING_DETECTOR_DEFAULT_CFG(); + cfg.backend = VEIL_TRIGGER_GPIO; + cfg.gpio_num = 8; + + ESP_ERROR_CHECK(veil_sensing_detector_start(&cfg)); + ESP_LOGI(TAG, "rate_hz=%.2f engaged=%d (build-only, never flashed)", + veil_sensing_detector_rate_hz(), veil_sensing_detector_engaged()); +} diff --git a/firmware/privshield/esp32/veil_ris_controller/CMakeLists.txt b/firmware/privshield/esp32/veil_ris_controller/CMakeLists.txt new file mode 100644 index 00000000..7f087900 --- /dev/null +++ b/firmware/privshield/esp32/veil_ris_controller/CMakeLists.txt @@ -0,0 +1,23 @@ +# veil_ris_controller — ESP-IDF component (SYNTHETIC / L0, build-only) +# +# Drives an EXTERNAL reconfigurable intelligent surface (RIS) over GPIO/SPI to +# scramble the *sensing-direction* channel while preserving the *comm-direction* +# channel (the PrivISAC pattern, arXiv:2601.04488). This is the honest way an +# ESP32 "helps scramble": through an external passive surface, NOT its own +# closed Wi-Fi PHY. See the subdir README.md. +# +# The keyed configuration schedule reuses the portable VEIL core's SplitMix64 +# `veil_rng` (../../core/veil_shield.{h,c}) so the schedule is deterministic and +# byte-consistent with the Rust reference — the same key can be shared with an +# associated receiver. +# +# NOTE: build-only skeleton, never run on silicon. Hardware paths -> TODO(hw). + +set(VEIL_CORE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../core") + +idf_component_register( + SRCS "veil_ris_controller.c" + "${VEIL_CORE_DIR}/veil_shield.c" # reuse veil_rng from the portable core + INCLUDE_DIRS "include" "${VEIL_CORE_DIR}" + REQUIRES esp_timer esp_driver_gpio esp_driver_spi +) diff --git a/firmware/privshield/esp32/veil_ris_controller/include/veil_ris_controller.h b/firmware/privshield/esp32/veil_ris_controller/include/veil_ris_controller.h new file mode 100644 index 00000000..ef7f33c0 --- /dev/null +++ b/firmware/privshield/esp32/veil_ris_controller/include/veil_ris_controller.h @@ -0,0 +1,91 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * veil_ris_controller — drive an EXTERNAL reconfigurable intelligent surface + * (RIS) to obfuscate the sensing-direction channel. + * + * STATUS: SYNTHETIC / L0. Build-only ESP-IDF component skeleton. Never flashed, + * never captured on silicon. No RIS hardware exists in this repo. Do NOT claim + * runtime or on-air behavior without a captured hardware log. + * + * WHY THIS EXISTS (honest framing): the ESP32 cannot shape its own transmitted + * beamforming feedback — the precoding / compressed-BF-report path lives in the + * closed Espressif Wi-Fi PHY blob (esp-phy-lib) and is not modifiable (see + * README.md). The legitimate, compliant way an ESP32 can "help scramble" a + * sensing signal is to act as the *controller for a separate passive surface*: + * a RIS whose per-element phase states are switched over time. Following the + * PrivISAC pattern (arXiv:2601.04488), each element is toggled between two + * states chosen so the surface's response is ~identical in the *communication* + * direction (throughput preserved) but differs sharply in the *sensing* + * direction (an eavesdropper's channel is perturbed). The ESP32 is a GPIO/SPI + * pin-driver here; it emits no RF of its own. + * + * The state schedule is *keyed* and deterministic: it is drawn from the + * portable core's `veil_rng` (SplitMix64), so an associated / authorized + * sensor holding the same key can reconstruct — and thus tolerate — the + * schedule, while an unauthorized observer cannot. + */ +#ifndef VEIL_RIS_CONTROLLER_H +#define VEIL_RIS_CONTROLLER_H + +#include +#include +#include +#include "esp_err.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* How the surface's element bits are clocked out. */ +typedef enum { + VEIL_RIS_IFACE_GPIO = 0, /* small surfaces: one GPIO per element / bank */ + VEIL_RIS_IFACE_SPI, /* larger surfaces: shift-register / driver IC */ +} veil_ris_iface_t; + +typedef struct { + veil_ris_iface_t iface; + + /* Number of independently switchable RIS elements (or 1-bit banks). */ + size_t n_elements; + + /* Keyed, deterministic schedule (shared with the associated receiver). */ + uint64_t key; + + /* Dwell time per configuration, microseconds. Must be short vs. the + * channel coherence time to spread perturbation across the sensing burst, + * yet long enough for the surface's switching diodes to settle. */ + uint32_t dwell_us; + + /* GPIO backend: one pin per element (n_elements <= number of pins). */ + const int *gpio_pins; /* borrowed; length == n_elements */ + + /* SPI backend: bits are packed MSB-first into ceil(n_elements/8) bytes and + * shifted out per configuration. */ + int spi_host; /* e.g. SPI2_HOST */ + int spi_cs_gpio; /* latch / chip-select */ + int spi_clock_hz; /* driver-IC clock */ +} veil_ris_controller_cfg_t; + +/* Initialize the chosen interface. Registration only — says nothing about a + * physical surface actually switching. */ +esp_err_t veil_ris_controller_init(const veil_ris_controller_cfg_t *cfg); + +/* Compute the next keyed configuration bitmap and clock it to the surface. + * `out_bits` (optional, may be NULL) receives the packed bitmap for tests. + * `out_len` is the byte length of `out_bits` on input. The bit pattern is + * derived purely from `veil_rng` + the PrivISAC two-state assignment, so it is + * reproducible from (key, step_index). */ +esp_err_t veil_ris_controller_step(uint8_t *out_bits, size_t out_len); + +/* Start/stop a periodic timer that calls _step() every dwell_us. */ +esp_err_t veil_ris_controller_start(void); +esp_err_t veil_ris_controller_stop(void); + +/* Monotonic count of configurations applied since init (telemetry/tests). */ +uint64_t veil_ris_controller_step_count(void); + +#ifdef __cplusplus +} +#endif + +#endif /* VEIL_RIS_CONTROLLER_H */ diff --git a/firmware/privshield/esp32/veil_ris_controller/veil_ris_controller.c b/firmware/privshield/esp32/veil_ris_controller/veil_ris_controller.c new file mode 100644 index 00000000..6d01f22e --- /dev/null +++ b/firmware/privshield/esp32/veil_ris_controller/veil_ris_controller.c @@ -0,0 +1,196 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * veil_ris_controller — see veil_ris_controller.h. + * + * STATUS: SYNTHETIC / L0. Build-only skeleton. Never run on silicon; no RIS + * hardware exists here. Hardware-touching paths are marked TODO(hw). The keyed + * bitmap generator (pure math over veil_rng) is fully implemented and testable + * off target; the GPIO/SPI clock-out is stubbed. + * + * Compliance: the ESP32 only toggles control pins of a *passive* external + * surface. It emits no RF and does not transmit into any band. The surface + * re-reflects ambient energy; it does not add energy or occupy spectrum, which + * is what keeps this on the compliant side of the jamming line. (A powered, + * amplifying, or spectrum-occupying surface would NOT be compliant and is out + * of scope.) + */ +#include "veil_ris_controller.h" + +#include + +#include "esp_log.h" +#include "esp_timer.h" +#include "driver/gpio.h" +#include "driver/spi_master.h" + +#include "veil_shield.h" /* portable core: veil_rng, veil_rng_next_u64/_f32 */ + +static const char *TAG = "veil_ris"; + +static veil_ris_controller_cfg_t s_cfg; +static bool s_inited; +static uint64_t s_step; /* configurations applied so far */ +static esp_timer_handle_t s_timer; + +/* ---- keyed configuration generator (pure, testable off-target) ----------- */ + +/* PrivISAC two-state assignment: every element has two candidate phase states + * (A/B) designed offline so the *comm-direction* array response is ~invariant + * under A<->B while the *sensing-direction* response changes. At runtime we + * only pick, per element, which of the two states is active this step. That + * choice is the single bit we clock out. Drawing the bits from the keyed + * veil_rng makes the whole schedule reproducible from (key, step_index) and + * shareable with an authorized receiver. + * + * `step_index` seeds a per-step substream so any step can be regenerated + * without replaying history (matches the core's deterministic style). + * Fills `bits` (packed MSB-first) with n_elements selection bits. */ +void veil_ris_gen_bits(uint64_t key, uint64_t step_index, + size_t n_elements, uint8_t *bits, size_t bits_len) +{ + if (!bits || bits_len == 0) { + return; + } + memset(bits, 0, bits_len); + + veil_rng r; + /* Mix the step index into the key so each dwell gets an independent draw + * while staying a pure function of (key, step_index). */ + veil_rng_seed(&r, key ^ (step_index * 0x9E3779B97F4A7C15ULL)); + + for (size_t e = 0; e < n_elements; e++) { + size_t byte = e >> 3; + if (byte >= bits_len) { + break; + } + /* Top bit of the draw selects state B (1) vs state A (0). */ + uint64_t w = veil_rng_next_u64(&r); + if (w >> 63) { + bits[byte] |= (uint8_t)(0x80u >> (e & 7)); + } + } +} + +/* ---- interface clock-out (stubs) ----------------------------------------- */ + +static esp_err_t veil_ris_write(const uint8_t *bits, size_t bits_len) +{ + switch (s_cfg.iface) { + case VEIL_RIS_IFACE_GPIO: + /* TODO(hw): for each element e, set its pin to the selected state. + * for (size_t e = 0; e < s_cfg.n_elements; e++) { + * int level = (bits[e >> 3] >> (7 - (e & 7))) & 1; + * gpio_set_level(s_cfg.gpio_pins[e], level); + * } + * Requires each pin configured as output in _init(). Unverified. */ + ESP_LOGD(TAG, "TODO(hw) GPIO write %u bits (stub)", + (unsigned)s_cfg.n_elements); + return ESP_ERR_NOT_SUPPORTED; + case VEIL_RIS_IFACE_SPI: + /* TODO(hw): shift the packed bitmap to the surface driver IC. + * spi_transaction_t t = { + * .length = bits_len * 8, + * .tx_buffer = bits, + * }; + * spi_device_transmit(s_spi_dev, &t); // then latch via CS + * s_spi_dev created in _init() via spi_bus_add_device(). Unverified. */ + ESP_LOGD(TAG, "TODO(hw) SPI write %u bytes (stub)", (unsigned)bits_len); + return ESP_ERR_NOT_SUPPORTED; + default: + return ESP_ERR_INVALID_ARG; + } +} + +/* ---- public API ---------------------------------------------------------- */ + +esp_err_t veil_ris_controller_init(const veil_ris_controller_cfg_t *cfg) +{ + if (!cfg || cfg->n_elements == 0) { + return ESP_ERR_INVALID_ARG; + } + if (s_inited) { + return ESP_ERR_INVALID_STATE; + } + s_cfg = *cfg; + s_step = 0; + + if (s_cfg.iface == VEIL_RIS_IFACE_GPIO) { + /* TODO(hw): configure each s_cfg.gpio_pins[e] as GPIO_MODE_OUTPUT via + * gpio_config() (build a pin_bit_mask over all elements). */ + ESP_LOGW(TAG, "TODO(hw) configure %u GPIO element pins (stub)", + (unsigned)s_cfg.n_elements); + } else { + /* TODO(hw): spi_bus_initialize(s_cfg.spi_host, &buscfg, ...) + + * spi_bus_add_device(s_cfg.spi_host, &devcfg, &s_spi_dev). */ + ESP_LOGW(TAG, "TODO(hw) init SPI host %d @ %d Hz (stub)", + s_cfg.spi_host, s_cfg.spi_clock_hz); + } + + s_inited = true; + ESP_LOGI(TAG, "init (SYNTHETIC/L0): %u elements, dwell=%uus, keyed schedule", + (unsigned)s_cfg.n_elements, (unsigned)s_cfg.dwell_us); + return ESP_OK; +} + +esp_err_t veil_ris_controller_step(uint8_t *out_bits, size_t out_len) +{ + if (!s_inited) { + return ESP_ERR_INVALID_STATE; + } + /* Bounded, malloc-free scratch: cap at 256 elements (32 bytes) for the + * skeleton. Larger surfaces would stream in chunks. */ + enum { VEIL_RIS_MAX_BYTES = 32 }; + uint8_t bits[VEIL_RIS_MAX_BYTES]; + size_t need = (s_cfg.n_elements + 7) / 8; + if (need > sizeof bits) { + need = sizeof bits; + } + + veil_ris_gen_bits(s_cfg.key, s_step, s_cfg.n_elements, bits, need); + esp_err_t err = veil_ris_write(bits, need); /* stub on host/no-hw */ + s_step++; + + if (out_bits && out_len) { + size_t n = out_len < need ? out_len : need; + memcpy(out_bits, bits, n); + } + /* NOT_SUPPORTED from the stubbed writer is expected off-silicon; surface + * the generator result as OK so tests can validate the keyed bitmap. */ + return (err == ESP_ERR_NOT_SUPPORTED) ? ESP_OK : err; +} + +static void veil_ris_timer_cb(void *arg) +{ + (void)arg; + (void)veil_ris_controller_step(NULL, 0); +} + +esp_err_t veil_ris_controller_start(void) +{ + if (!s_inited) { + return ESP_ERR_INVALID_STATE; + } + /* TODO(hw): a real deployment would gate this on the sensing detector's + * engage trigger so the surface only churns during a sensing burst. */ + const esp_timer_create_args_t args = { + .callback = veil_ris_timer_cb, + .name = "veil_ris", + }; + esp_err_t err = esp_timer_create(&args, &s_timer); + if (err != ESP_OK) { + return err; + } + return esp_timer_start_periodic(s_timer, s_cfg.dwell_us); +} + +esp_err_t veil_ris_controller_stop(void) +{ + if (s_timer) { + esp_timer_stop(s_timer); + esp_timer_delete(s_timer); + s_timer = NULL; + } + return ESP_OK; +} + +uint64_t veil_ris_controller_step_count(void) { return s_step; } diff --git a/firmware/privshield/esp32/veil_sensing_detector/CMakeLists.txt b/firmware/privshield/esp32/veil_sensing_detector/CMakeLists.txt new file mode 100644 index 00000000..29fdf284 --- /dev/null +++ b/firmware/privshield/esp32/veil_sensing_detector/CMakeLists.txt @@ -0,0 +1,19 @@ +# veil_sensing_detector — ESP-IDF component (SYNTHETIC / L0, build-only) +# +# Estimates the 802.11 sensing-solicitation rate from the ESP32 CSI callback +# and raises a trigger (GPIO / MQTT / ESP-NOW) that engages the AP-side VEIL +# shield. This component only READS the channel; it never shapes RF. See the +# subdir README.md for the honest capability boundary. +# +# NOTE: This is a build-only skeleton. It has never run on silicon. All +# hardware-touching paths are marked TODO(hw). + +idf_component_register( + SRCS "veil_sensing_detector.c" + INCLUDE_DIRS "include" + # esp_wifi: esp_wifi_set_csi_rx_cb / esp_wifi_set_csi / promiscuous. + # The MQTT and ESP-NOW trigger backends are optional; they are only + # referenced under CONFIG_ guards so the core build stays minimal. + REQUIRES esp_wifi esp_event esp_timer esp_driver_gpio + PRIV_REQUIRES mqtt +) diff --git a/firmware/privshield/esp32/veil_sensing_detector/include/veil_sensing_detector.h b/firmware/privshield/esp32/veil_sensing_detector/include/veil_sensing_detector.h new file mode 100644 index 00000000..c66d17fa --- /dev/null +++ b/firmware/privshield/esp32/veil_sensing_detector/include/veil_sensing_detector.h @@ -0,0 +1,88 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * veil_sensing_detector — detect 802.11 sensing solicitation and raise a + * trigger that engages the AP-side VEIL shield. + * + * STATUS: SYNTHETIC / L0. Build-only ESP-IDF component skeleton. Never flashed, + * never captured on silicon. Do NOT claim runtime behavior without a captured + * hardware log (CLAUDE.md hardware-evidence rule). + * + * ROLE (honest): the ESP32 is a passive CSI *observer* here. It watches how + * often it is being sounded / probed (NDP announcements, action frames, and the + * cadence of incoming CSI-bearing frames) and, when that rate crosses a + * threshold, tells a *separate* protector (the AP running the veil_shield core) + * that a sensing burst is in progress. The ESP32 does NOT modify any waveform + * and does NOT protect its own beamforming feedback (see README.md). This is + * the strongest, clearly-compliant supporting role for the ESP32. + */ +#ifndef VEIL_SENSING_DETECTOR_H +#define VEIL_SENSING_DETECTOR_H + +#include +#include +#include "esp_err.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* How the detector announces "sensing burst detected" to the protector. */ +typedef enum { + VEIL_TRIGGER_GPIO = 0, /* drive a GPIO line to a co-located AP / relay */ + VEIL_TRIGGER_MQTT, /* publish to a broker the AP subscribes to */ + VEIL_TRIGGER_ESPNOW, /* connectionless ESP-NOW unicast to the AP node */ +} veil_trigger_backend_t; + +typedef struct { + /* Sliding-window length for the solicitation-rate estimate, milliseconds. */ + uint32_t window_ms; + /* Solicitations/second above which the shield should be engaged. */ + float trigger_rate_hz; + /* Hysteresis: rate must fall below this to clear the trigger. */ + float release_rate_hz; + + veil_trigger_backend_t backend; + + /* GPIO backend. */ + int gpio_num; /* output line; active-high engage */ + + /* MQTT backend. broker_uri/topic are borrowed, must outlive the detector. */ + const char *mqtt_broker_uri; /* e.g. "mqtts://ap.local:8883" */ + const char *mqtt_topic; /* e.g. "veil/engage" */ + + /* ESP-NOW backend. */ + uint8_t espnow_peer[6]; /* AP node MAC */ +} veil_sensing_detector_cfg_t; + +/* Sensible SYNTHETIC defaults (not silicon-validated). */ +#define VEIL_SENSING_DETECTOR_DEFAULT_CFG() \ + (veil_sensing_detector_cfg_t){ \ + .window_ms = 1000, \ + .trigger_rate_hz = 20.0f, \ + .release_rate_hz = 5.0f, \ + .backend = VEIL_TRIGGER_GPIO, \ + .gpio_num = -1, \ + .mqtt_broker_uri = NULL, \ + .mqtt_topic = "veil/engage", \ + .espnow_peer = {0}, \ + } + +/* Install the CSI callback + configured trigger backend. Enables promiscuous + * CSI capture. Returns ESP_OK on successful *registration* only — this says + * nothing about on-air behavior. */ +esp_err_t veil_sensing_detector_start(const veil_sensing_detector_cfg_t *cfg); + +/* Tear down callback + backend. */ +esp_err_t veil_sensing_detector_stop(void); + +/* Last estimated solicitation rate (Hz), for telemetry/tests. */ +float veil_sensing_detector_rate_hz(void); + +/* True while the engage trigger is asserted. */ +bool veil_sensing_detector_engaged(void); + +#ifdef __cplusplus +} +#endif + +#endif /* VEIL_SENSING_DETECTOR_H */ diff --git a/firmware/privshield/esp32/veil_sensing_detector/veil_sensing_detector.c b/firmware/privshield/esp32/veil_sensing_detector/veil_sensing_detector.c new file mode 100644 index 00000000..08b5997c --- /dev/null +++ b/firmware/privshield/esp32/veil_sensing_detector/veil_sensing_detector.c @@ -0,0 +1,188 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * veil_sensing_detector — see veil_sensing_detector.h. + * + * STATUS: SYNTHETIC / L0. Build-only skeleton. Never run on silicon. Every + * hardware-touching path is marked TODO(hw). The rate estimator (pure math over + * timestamps) is the only fully-implemented piece and is unit-testable off + * target; the RF/observe path and the trigger backends are stubs. + * + * Compliance: this component only READS the channel (CSI + frame cadence). It + * emits no RF and shapes no waveform. It cannot and does not touch the closed + * ESP32 Wi-Fi PHY blob. The "action" it takes is a low-rate control signal to a + * separate protector. + */ +#include "veil_sensing_detector.h" + +#include + +#include "esp_log.h" +#include "esp_timer.h" +#include "esp_wifi.h" /* esp_wifi_set_csi_rx_cb, esp_wifi_set_csi, ... */ +#include "esp_wifi_types.h" /* wifi_csi_info_t, wifi_csi_config_t */ +#include "driver/gpio.h" /* gpio_config, gpio_set_level */ + +static const char *TAG = "veil_sense"; + +/* ---- module state -------------------------------------------------------- */ + +static veil_sensing_detector_cfg_t s_cfg; +static bool s_running; +static bool s_engaged; +static float s_rate_hz; + +/* Bounded ring of recent solicitation timestamps (µs), malloc-free. */ +enum { VEIL_TS_RING = 256 }; +static int64_t s_ts[VEIL_TS_RING]; +static size_t s_ts_head; /* next write slot */ +static size_t s_ts_count; /* live entries, capped at VEIL_TS_RING */ + +/* ---- rate estimator (pure, testable off-target) -------------------------- */ + +/* Record one solicitation at time `now_us` and recompute the sliding-window + * rate. Returns the current rate in Hz. This function is deliberately free of + * any ESP-IDF dependency so it can be exercised in host unit tests. */ +float veil_sd_note_solicitation(int64_t now_us) +{ + s_ts[s_ts_head] = now_us; + s_ts_head = (s_ts_head + 1) % VEIL_TS_RING; + if (s_ts_count < VEIL_TS_RING) { + s_ts_count++; + } + + const int64_t window_us = (int64_t)s_cfg.window_ms * 1000; + const int64_t cutoff = now_us - window_us; + + size_t in_window = 0; + for (size_t k = 0; k < s_ts_count; k++) { + if (s_ts[k] >= cutoff) { + in_window++; + } + } + /* rate = events within the trailing window / window length. */ + s_rate_hz = (float)in_window * 1000.0f / (float)s_cfg.window_ms; + + /* Hysteresis around engage/release. */ + if (!s_engaged && s_rate_hz >= s_cfg.trigger_rate_hz) { + s_engaged = true; + ESP_LOGI(TAG, "sensing burst: %.1f Hz >= %.1f -> ENGAGE", + s_rate_hz, s_cfg.trigger_rate_hz); + /* fire-and-forget; backend errors are logged, not fatal */ + (void)0; /* veil_sd_emit_trigger(true) — see below */ + } else if (s_engaged && s_rate_hz <= s_cfg.release_rate_hz) { + s_engaged = false; + ESP_LOGI(TAG, "sensing quiet: %.1f Hz <= %.1f -> RELEASE", + s_rate_hz, s_cfg.release_rate_hz); + } + return s_rate_hz; +} + +/* ---- trigger backends (all stubs) ---------------------------------------- */ + +static esp_err_t veil_sd_emit_trigger(bool engage) +{ + switch (s_cfg.backend) { + case VEIL_TRIGGER_GPIO: + /* TODO(hw): drive the engage line to the co-located AP/relay. + * gpio_set_level(s_cfg.gpio_num, engage ? 1 : 0); + * Requires a wired GPIO to the protector; unverified on silicon. */ + ESP_LOGW(TAG, "TODO(hw) GPIO trigger -> %d (stub)", engage); + return ESP_ERR_NOT_SUPPORTED; + case VEIL_TRIGGER_MQTT: + /* TODO(hw): esp_mqtt_client_publish(client, s_cfg.mqtt_topic, + * engage ? "1" : "0", 0, 1 /qos/, 0 /retain/); + * Client lifecycle (esp_mqtt_client_init/_start) omitted from skeleton. */ + ESP_LOGW(TAG, "TODO(hw) MQTT trigger -> %d (stub)", engage); + return ESP_ERR_NOT_SUPPORTED; + case VEIL_TRIGGER_ESPNOW: + /* TODO(hw): esp_now_send(s_cfg.espnow_peer, &payload, sizeof payload); + * Requires esp_now_init() + esp_now_add_peer() during start(). */ + ESP_LOGW(TAG, "TODO(hw) ESP-NOW trigger -> %d (stub)", engage); + return ESP_ERR_NOT_SUPPORTED; + default: + return ESP_ERR_INVALID_ARG; + } +} + +/* ---- CSI callback (observe path) ----------------------------------------- */ + +/* Runs in the Wi-Fi task. Keep it short: post to a queue in real firmware. + * Here we only classify whether this frame indicates a sounding/solicitation + * and, if so, feed the estimator. */ +static void veil_sd_csi_cb(void *ctx, wifi_csi_info_t *info) +{ + (void)ctx; + if (!info) { + return; + } + /* TODO(hw): a real classifier would inspect info->rx_ctrl (rate, sig_mode, + * channel, secondary channel) and, alongside a promiscuous frame-type + * filter, distinguish NDP / NDP-announcement / CSI-solicit action frames + * from ordinary data. On silicon the ESP32 does NOT surface the raw + * VHT/HE sounding subtype through the CSI struct, so this classifier is + * necessarily heuristic (cadence + rate + frame length). Treated here as + * "every CSI-bearing frame is a candidate solicitation" for the skeleton. */ + (void)veil_sd_note_solicitation(esp_timer_get_time()); +} + +/* ---- lifecycle ----------------------------------------------------------- */ + +esp_err_t veil_sensing_detector_start(const veil_sensing_detector_cfg_t *cfg) +{ + if (!cfg) { + return ESP_ERR_INVALID_ARG; + } + if (s_running) { + return ESP_ERR_INVALID_STATE; + } + s_cfg = *cfg; + s_engaged = false; + s_rate_hz = 0.0f; + s_ts_head = 0; + s_ts_count = 0; + + if (s_cfg.backend == VEIL_TRIGGER_GPIO && s_cfg.gpio_num >= 0) { + /* TODO(hw): configure the engage line. + * gpio_config_t io = { + * .pin_bit_mask = 1ULL << s_cfg.gpio_num, + * .mode = GPIO_MODE_OUTPUT, + * }; + * gpio_config(&io); + * gpio_set_level(s_cfg.gpio_num, 0); + */ + ESP_LOGW(TAG, "TODO(hw) configure GPIO %d (stub)", s_cfg.gpio_num); + } + + /* Observe path. On real hardware: + * wifi_csi_config_t csi = { ... }; + * ESP_ERROR_CHECK(esp_wifi_set_csi_config(&csi)); + * ESP_ERROR_CHECK(esp_wifi_set_csi_rx_cb(veil_sd_csi_cb, NULL)); + * ESP_ERROR_CHECK(esp_wifi_set_csi(true)); + * ESP_ERROR_CHECK(esp_wifi_set_promiscuous(true)); // more CSI when idle + * The Wi-Fi driver must already be started by the app. */ + ESP_LOGW(TAG, "TODO(hw) esp_wifi_set_csi_rx_cb/_set_csi/_set_promiscuous " + "(stub; not wired on silicon)"); + (void)veil_sd_csi_cb; /* referenced once wired */ + + s_running = true; + ESP_LOGI(TAG, "started (SYNTHETIC/L0): window=%ums engage>=%.1fHz", + (unsigned)s_cfg.window_ms, s_cfg.trigger_rate_hz); + return ESP_OK; +} + +esp_err_t veil_sensing_detector_stop(void) +{ + if (!s_running) { + return ESP_ERR_INVALID_STATE; + } + /* TODO(hw): esp_wifi_set_csi(false); esp_wifi_set_csi_rx_cb(NULL, NULL); + * esp_wifi_set_promiscuous(false); release GPIO/MQTT/ESP-NOW. */ + if (s_engaged) { + (void)veil_sd_emit_trigger(false); + } + s_running = false; + return ESP_OK; +} + +float veil_sensing_detector_rate_hz(void) { return s_rate_hz; } +bool veil_sensing_detector_engaged(void) { return s_engaged; } diff --git a/firmware/privshield/nexmon/BUILD.md b/firmware/privshield/nexmon/BUILD.md new file mode 100644 index 00000000..16fd7a8b --- /dev/null +++ b/firmware/privshield/nexmon/BUILD.md @@ -0,0 +1,116 @@ +# Building the WiFi Veil Nexmon patch — **UNTESTED** + +> **This procedure has never been run.** It has not been built with the Nexmon +> toolchain, not flashed, and not captured on air. Addresses/symbols in +> `patch/veil_patch.c` are placeholders (one is intentionally invalid, +> `0xDEAD0000`) so it will **not** produce a flashable image as-is. This file +> documents *how it would build* so a hardware operator with real silicon can +> take it forward. `SYNTHETIC / L0`, per CLAUDE.md. + +## Prerequisites (host, not in this repo) + +- A Linux host (Nexmon expects an x86_64 Ubuntu-like build host) with the + Broadcom-flavored ARM toolchain Nexmon downloads/uses, plus `git`, `make`, + `gcc-arm-none-eabi`, `flex`, `bison`, `libisl`, `automake`. +- Nexmon checked out **outside** this repo (do not vendor it here): + ```bash + git clone https://github.com/seemoo-lab/nexmon.git + cd nexmon + source setup_env.sh # sets NEXMON_ROOT, toolchain paths + make # builds libISL / firmwares tooling + ``` +- The target firmware blob present on the device: BCM43455c0 + (`brcmfmac43455-sdio.bin`), version **7_45_189** (Cypress) or 7_45_154 + (Raspbian). Do **not** commit the blob or any extracted symbols/ROM to RuView. + +## Where this patch would live in the Nexmon tree + +Nexmon builds per chip/firmware under `patches////`. This +adapter would be a Nexmon project, e.g.: + +``` +$NEXMON_ROOT/patches/bcm43455c0/7_45_189/veil/ +├── Makefile # copy of an existing nexmon patch Makefile (e.g. nexmon_csi's) +├── src/ +│ ├── veil_patch.c # <- symlink/copy of firmware/privshield/nexmon/patch/veil_patch.c +│ ├── veil_shield.c # <- from firmware/privshield/core/ (compiled into the patch) +│ └── veil_shield.h # <- from firmware/privshield/core/ +└── ... +``` + +Keep the RuView copies canonical; the Nexmon tree gets copies/symlinks so the +core stays byte-identical to `../core/`. + +## Linking the portable core (MCU-friendly) + +The core is `no_std`-style C99: no malloc, no libc I/O, only `` +(`sinf`/`cosf`/`sqrtf`/`sqrt`). To build it into the patch: + +1. Add `veil_shield.c` to the patch `Makefile`'s object list (alongside + `patch.o`/`wrapper.o`), so it compiles with the same ARM flags. +2. Ensure the firmware provides `sinf`/`cosf`/`sqrtf`. **TODO(hw):** Broadcom + firmware may not export libm. Options, in order of preference: + - link a small `libm`/`compiler-rt` for `arm-none-eabi`; + - or replace the trig with a fixed-point / CORDIC Givens rotation + (`TODO(reverse-engineer)`), which also avoids float on parts without an FPU. +3. All WiFi Veil working storage is stack-bounded (`VEIL_MAX_FINE`, `CACHE` in the + core) — no heap is introduced on-chip. + +## Build + +```bash +cd $NEXMON_ROOT/patches/bcm43455c0/7_45_189/veil +make # produces the patched brcmfmac43455-sdio.bin +``` + +Before `make` can succeed you must first resolve every `TODO(reverse-engineer)` +in `veil_patch.c`: + +- replace `0xDEAD0000` and the `wlc_sendmgmt_veil_target` symbol with the real, + disassembled target address/symbol for 7_45_189; +- implement `veil_bfr_unpack_fine` / `veil_bfr_pack_fine` (the angle bit-field + codec) and the report-body offset/length; +- confirm the compressed-beamforming report is assembled in ARM on this chip + (else move to hook candidate #2/#3 — see README). + +## Flash (Raspberry Pi, on-device) + +**TODO(hw) — untested.** Typical Nexmon flow on the Pi: + +```bash +# back up stock firmware first! +sudo cp /lib/firmware/brcm/brcmfmac43455-sdio.bin ~/brcmfmac43455-sdio.bin.orig + +sudo cp brcmfmac43455-sdio.bin /lib/firmware/brcm/brcmfmac43455-sdio.bin +# (some setups also need the matching *.clm_blob / nexmon's own copy path) + +sudo rmmod brcmfmac && sudo modprobe brcmfmac # reload driver with new firmware +dmesg | tail # confirm firmware loaded +``` + +Push the session key at runtime (matches the IOCTL stub in `veil_patch.c`): + +```bash +# TODO(hw): nexutil vendor-IOCTL id and payload format are placeholders +nexutil -s -b -l8 -v +``` + +**Recovery:** if WiFi breaks, restore the backup blob and reload the driver. +A bad flashpatch offset can knock out WiFi until you reflash stock firmware. + +## Validation you can honestly do (still not `MEASURED` firmware) + +1. **Host unit test of the math** (already green in this repo): + `cd ../../core && make test`. +2. **Read-back on hardware** with `nexmon_csi`/Wi-BFI: capture the report with + and without the patch and check the fine subspace changed while SNR/norm is + preserved. This validates the transform end-to-end but is a *receiver* + observation, not proof the TX hook is robust. +3. Only a captured device runtime log showing the shaped report leaving *this* + node, plus receiver-side recovery with the shared key, would move any claim + from `SYNTHETIC`/`CLAIMED` toward `MEASURED` (roadmap P5). + +## References + +See `README.md` for sources (Nexmon, nexmon_csi, Wi-BFI, D11 reverse +engineering). diff --git a/firmware/privshield/nexmon/README.md b/firmware/privshield/nexmon/README.md new file mode 100644 index 00000000..40c80df0 --- /dev/null +++ b/firmware/privshield/nexmon/README.md @@ -0,0 +1,124 @@ +# WiFi Veil protector — Nexmon (Broadcom/Cypress) path + +C-firmware-patch adapter that would call the portable WiFi Veil core +(`../core/veil_shield.{h,c}`) on the compressed-beamforming-feedback **angles +before transmission**, using the [Nexmon](https://github.com/seemoo-lab/nexmon) +patching framework on a Broadcom/Cypress WiFi chip. + +> **Evidence discipline.** Everything here is **`SYNTHETIC` / L0 / build-only**. +> Nothing in this directory has been built with the Nexmon toolchain, flashed to +> a chip, or captured on air. There are **no** `MEASURED` claims and **no** +> hardware logs. The patch is an honest **skeleton** with `TODO(hw)` and +> `TODO(reverse-engineer)` markers, not working firmware. Per CLAUDE.md, no +> defense claim becomes `MEASURED` without a captured runtime log from real +> silicon (roadmap P5). +> +> **Compliant waveform only — never jamming.** The core applies an *orthogonal* +> (energy-preserving) keyed rotation to the node's *own* standards-conformant +> feedback report. It does not add power, transmit out of turn, or interfere +> with any other station. + +## Feasibility grade: **C** (research-grade, partial, unproven) + +| Sub-path | Grade | Why | +|---|---|---| +| **Read** the compressed BF feedback | **A** (proven by others) | `nexmon_csi` extracts CSI, and Wi-BFI parses the compressed-beamforming *angles* straight from captured action frames — no firmware change at all. The report content is observable today. | +| **Write / shape** the transmitted report | **C / C-** | The report is generated by the proprietary **D11** real-time core, not the ARM firmware Nexmon comfortably patches. The hook point is deep, chip- and firmware-version-specific, and unverified here. Plausible, not demonstrated. | + +Grade **C** reflects *this* deliverable's goal — shaping the **TX** report. The +read side is a solved problem and is graded only to contrast honestly. + +### Why the write path is hard (the core honesty point) + +Broadcom/Cypress chips put all time-critical 802.11 MAC/PHY work on the **D11 +core**, a proprietary microcontroller running a programmable state machine +("ucode"). Published reverse-engineering of these chips reports that the D11 +generates the **VHT/HE compressed beamforming report ~10 µs after the NDP**, with +its contents fetched from an **internal memory updated directly by the hardware** +on NDP reception. In other words, the angles WiFi Veil wants to touch are staged and +emitted inside the ucode/PHY path on a microsecond deadline — *below* the ARM +"wl" driver firmware where Nexmon's C hooks (`__attribute__((at(addr, ...)))` +flashpatches / branch hooks) live most reliably. Reaching them means either a +D11-ucode patch (needs the D11 assembler and SHM/template-RAM layout) or catching +the report while the ARM path still assembles the action-frame body — if it does +so on this chip at all. Both are `TODO(reverse-engineer)`. + +## Target chip(s) + +Primary: **BCM43455c0** (Raspberry Pi 3B+/4B; also RPi Zero 2 W), firmware +**7_45_154** (Raspbian) or **7_45_189** (Cypress) — the best-documented, +most-reproducible Nexmon target, and one of the four chips `nexmon_csi` already +supports. Secondary candidates that `nexmon_csi` also supports: **BCM4339** +(Nexus 5), **BCM4358** (Nexus 6P), **BCM4366c0** (Asus RT-AC86U). We scope the +skeleton to BCM43455c0 / 7_45_189 and leave the others as build-matrix `TODO`s. + +Caveat: the RPi BCM43455c0 is an **802.11ac (VHT)** single-stream part; its own +*transmit* beamforming/sounding activity as a beamformee is limited. The +skeleton targets the **VHT compressed beamforming report** action-frame path; +whether this chip emits enough to shape in practice is itself a `TODO(hw)` +question. + +## Hook-point candidates (all `TODO(reverse-engineer)`) + +Ordered most-tractable → deepest. Addresses are **placeholders** — real offsets +come from disassembling the specific firmware blob and cross-checking the Nexmon +symbol tables (`wl_ram.elf` / IDA); none are known-good here. + +1. **ARM action-frame TX assembly (best first target).** If the "wl" driver + assembles the VHT Compressed Beamforming Report action-frame *body* in ARM + firmware before handing it to the D11 (function family around + `wlc_txbf_*` / a `wlc_send*mgmt`/action path), a branch hook there could + locate the report's fine-angle block and call `veil_shield_apply` in place. + Cheapest if it exists on this chip. +2. **ARM → D11 TX descriptor / template handoff.** Hook where the driver stages + a frame into the D11 TX FIFO / template RAM (`wlc_d11hdrs` / `wlc_txfifo` + region) and rewrite the angle bytes there. Requires knowing the exact + template-RAM offset of the report body. +3. **D11 ucode patch (deepest).** Patch the ucode routine that copies angles + from the hardware-updated internal memory into the outgoing report, applying + the rotation in D11 SHM. Needs the D11 assembler and PHY/SHM map; highest + fidelity, highest effort, most fragile across firmware versions. + +The skeleton wires candidate **#1** and leaves #2/#3 documented but unimplemented. + +## What is realistic + +- **Realistic now:** verify WiFi Veil's *effect* by reading — capture the shaped vs. + unshaped report with `nexmon_csi`/Wi-BFI and confirm the fine subspace changed + while energy (SNR/norm) is preserved. This validates the math, not the TX hook. +- **Realistic with serious RE effort:** candidate #1, on one pinned firmware, as + a demo — partial, brittle, chip-specific. +- **Not realistic as a portable product:** a clean, firmware-version-stable TX + report-shaping patch across Broadcom parts. Treat as research. + +## Risk / honesty + +- Wrong flashpatch offsets can **brick the WiFi blob** (recoverable by + reflashing stock firmware, but real). +- Regulatory: the transform is energy-preserving and rides standards-marked + spatial-mapping freedom, but any TX-path firmware patch on a certified radio is + **outside the device's certification** — bench/anechoic use only. +- Firmware blobs are proprietary; do **not** commit extracted firmware, symbols, + or ROM dumps to this repo. + +## Sources + +- Nexmon framework — +- `nexmon_csi` (chips: bcm4339, bcm43455c0, bcm4358, bcm4366c0) — + +- Wi-BFI (reads BFAs/BFI from captured compressed-beamforming action frames) — + , paper arXiv:2309.04408 + +- BCM43455c0 patches / D11 headers (`d11.h`) — + +- D11 real-time core / ucode reverse engineering (SEEMOO, Quarkslab) — + , + +- 802.11ac VHT NDP sounding & compressed beamforming report structure (context) — + + +> The "~10 µs / hardware-updated internal memory" characterization above is drawn +> from published Broadcom D11 reverse-engineering (reported for BCM4365-class +> parts) and is used here as design guidance; it is **not** independently +> verified on BCM43455c0 in this repo. `TODO(reverse-engineer)`: confirm on the +> target blob. diff --git a/firmware/privshield/nexmon/patch/veil_patch.c b/firmware/privshield/nexmon/patch/veil_patch.c new file mode 100644 index 00000000..cf268341 --- /dev/null +++ b/firmware/privshield/nexmon/patch/veil_patch.c @@ -0,0 +1,176 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * veil_patch.c — VEIL protector, Nexmon (Broadcom/Cypress) path. + * + * ============================ HONESTY BANNER ============================ + * SYNTHETIC / L0 / BUILD-ONLY. This file is an HONEST SKELETON in Nexmon + * style. It has NOT been built with the Nexmon toolchain, NOT flashed to a + * chip, and NOT captured on air. Every __attribute__((at(...))) address and + * every firmware symbol below is a PLACEHOLDER. Do not treat this as working + * firmware. See ../README.md for the feasibility grade (C, research-grade). + * + * Goal: call the portable VEIL core (../../core/veil_shield.c) + * `veil_shield_apply()` on the compressed-beamforming-feedback FINE ANGLES in + * the transmitted VHT/HE compressed beamforming report, so the identity-bearing + * fine subspace is obfuscated by a keyed, ENERGY-PRESERVING (orthogonal) + * Givens rotation before the frame leaves the radio. Compliant only, never + * jamming: the transform preserves the report's L2 norm. + * + * Target: BCM43455c0 (Raspberry Pi 3B+/4B), firmware 7_45_189. Others TODO. + * ======================================================================= + */ + +#pragma NEXMON targetregion "patch" + +#include /* FW_VER_7_45_189, CHIP_VER_BCM43455c0 (Nexmon) */ +#include /* BPatch / GPatch / __attribute__((at(...))) */ +#include /* struct sk_buff, struct wlc_info, etc. */ +#include /* Nexmon wrappers for ROM/firmware functions */ + +/* --- Portable VEIL core, linked/inlined for the MCU ------------------------- + * The core is pure C99: no malloc, no libc I/O, only (sinf/cosf/sqrtf). + * On the Nexmon ARM target we compile ../../core/veil_shield.c into this patch + * object (see ../BUILD.md) and pull in only the declarations here. Everything + * operates on a caller-provided fixed buffer — no dynamic allocation on-chip. */ +#include "veil_shield.h" + +/* ------------------------------------------------------------------------- */ +/* Configuration (compile-time; no on-chip allocation) */ +/* ------------------------------------------------------------------------- */ + +/* Max fine-angle count we will touch in one report. Sized for a VHT SU report + * fine block; bound it so all working storage is on the stack, malloc-free. */ +#define VEIL_MAX_FINE 64u + +/* Rotation passes — MUST match the associated receiver and the Rust reference + * crate default so recover() inverts exactly. TODO(hw): confirm against the + * receiver config actually deployed. */ +#define VEIL_PASSES 96u + +/* Session key. TODO(hw): DO NOT hardcode a real key in flashed firmware. Inject + * via nexutil IOCTL (see veil_ioctl_set_key stub) or a provisioning step; this + * placeholder exists only so the skeleton type-checks. */ +static uint64_t g_veil_key = 0x0000000000000000ULL; + +/* ------------------------------------------------------------------------- */ +/* Bridge: decode angles -> rotate -> re-encode, in place */ +/* ------------------------------------------------------------------------- */ +/* + * TODO(reverse-engineer): The compressed beamforming report packs the phi/psi + * angles as bit-fields whose widths depend on the codebook (VHT: (7,5) or (9,7); + * HE differs) and on Nc/Nr. The bytes handed to us are NOT plain floats. This + * bridge must: + * (1) parse the fine-angle bit-fields from `report` into `fine[]` as floats + * in the same units/order the receiver + Rust reference expect, + * (2) call veil_shield_apply() on that flat vector, + * (3) re-quantize and repack the rotated angles back into `report`, + * preserving all coarse/header fields and the frame length. + * Steps (1)/(3) are the real work and are UNIMPLEMENTED here. + */ +static void veil_shape_report_inplace(uint8_t *report, uint32_t report_len) +{ + if (report == 0 || report_len == 0) + return; + + float fine[VEIL_MAX_FINE]; + uint32_t n = 0; + + /* TODO(reverse-engineer): unpack fine-angle bit-fields -> fine[0..n) */ + /* n = veil_bfr_unpack_fine(report, report_len, fine, VEIL_MAX_FINE); */ + if (n < 2 || n > VEIL_MAX_FINE) + return; /* nothing safely shapeable; leave frame untouched (fail-open) */ + + /* Orthogonal, energy-preserving, keyed. This is the ONLY validated step. */ + veil_shield_apply(fine, (size_t)n, g_veil_key, VEIL_PASSES); + + /* TODO(reverse-engineer): repack fine[0..n) back into `report` bit-fields, + * keeping report_len and all non-fine fields byte-identical. */ + /* veil_bfr_pack_fine(report, report_len, fine, n); */ + (void)report_len; +} + +/* ------------------------------------------------------------------------- */ +/* Hook candidate #1 (see README): ARM action-frame TX assembly */ +/* ------------------------------------------------------------------------- */ +/* + * We hook the point where the "wl" driver has assembled the VHT Compressed + * Beamforming Report action frame in an sk_buff, just before it is queued to + * the D11 for transmission, locate the report body, and shape it. + * + * TODO(reverse-engineer): the symbol/address below is a PLACEHOLDER. The real + * target must be found by disassembling 7_45_189 (IDA + Nexmon's wl_ram.elf + * symbol map) and confirming: (a) the report body is assembled in ARM (not + * only in D11 ucode), (b) `p` really carries a compressed-beamforming action + * frame, and (c) the offset of the report body within the frame. + * + * If (a) is false on this chip, candidate #1 is dead and we fall to #2/#3 + * (TX template-RAM rewrite / D11 ucode patch) — both documented in README, + * neither implemented here. + */ + +/* Original firmware function prototype (PLACEHOLDER signature). */ +extern int wlc_sendmgmt_veil_target(struct wlc_info *wlc, void *p, void *scb); + +/* Our replacement. GPatch/BPatch below redirects the target to this. */ +int wlc_sendmgmt_veil_hook(struct wlc_info *wlc, void *p, void *scb) +{ + /* TODO(reverse-engineer): confirm `p` is a struct sk_buff* and that this + * frame is a VHT/HE compressed beamforming action frame (category 21 + * VHT / 30 HE, action = Compressed Beamforming). Guard hard so we never + * mangle unrelated management frames. */ + struct sk_buff *skb = (struct sk_buff *)p; + if (skb != 0 /* && veil_is_bf_report_action(skb) */) { + /* TODO(reverse-engineer): compute report body pointer + length from the + * action-frame layout. PLACEHOLDER offsets: */ + uint8_t *report = 0; /* skb->data + VEIL_BFR_BODY_OFFSET; */ + uint32_t report_len = 0; /* skb->len - VEIL_BFR_BODY_OFFSET; */ + veil_shape_report_inplace(report, report_len); + } + + /* Always fall through to the real firmware routine so normal TX proceeds. */ + return wlc_sendmgmt_veil_target(wlc, p, scb); +} + +/* + * Redirect the firmware's mgmt/action TX routine to our hook. + * PLACEHOLDER ADDRESS — 0xDEAD0000 is intentionally invalid so nobody mistakes + * this for a real, flashable patch. TODO(reverse-engineer): replace with the + * verified address for CHIP_VER_BCM43455c0 / FW_VER_7_45_189. + * + * Nexmon idiom: a branch patch that overwrites the target's prologue with a + * branch to our replacement (which tail-calls the saved original). + */ +__attribute__((at(0xDEAD0000, "flashpatch", CHIP_VER_BCM43455c0, FW_VER_7_45_189))) +BPatch(veil_sendmgmt_hook, wlc_sendmgmt_veil_hook); + +/* ------------------------------------------------------------------------- */ +/* Key provisioning via nexutil IOCTL (stub) */ +/* ------------------------------------------------------------------------- */ +/* + * TODO(hw): register a custom IOCTL so `nexutil` can push the 64-bit session + * key at runtime instead of baking it into flash. Hook the driver's ioctl + * dispatch (wlc_ioctl) the same way nexmon_csi installs its config IOCTLs. + * Left as a stub: the dispatch address and the nexmon_ioctl plumbing are + * PLACEHOLDERS. + */ +#define VEIL_IOCTL_SET_KEY 0x7EIL /* TODO(hw): pick a free vendor IOCTL id */ + +int veil_ioctl_set_key(struct wlc_info *wlc, const uint8_t *buf, uint32_t len) +{ + (void)wlc; + if (buf == 0 || len < sizeof(uint64_t)) + return -1; + uint64_t k = 0; + for (uint32_t i = 0; i < sizeof(uint64_t); i++) + k |= ((uint64_t)buf[i]) << (8u * i); + g_veil_key = k; + return 0; +} + +/* + * --------------------------------------------------------------------------- + * Candidate #2 (TX template-RAM rewrite) and #3 (D11 ucode patch) are NOT + * implemented. See ../README.md "Hook-point candidates". #3 would require the + * D11 assembler and the PHY/SHM angle-staging map — deepest and most fragile. + * --------------------------------------------------------------------------- + */ diff --git a/firmware/privshield/openwifi/HDL_NOTES.md b/firmware/privshield/openwifi/HDL_NOTES.md new file mode 100644 index 00000000..87ec0389 --- /dev/null +++ b/firmware/privshield/openwifi/HDL_NOTES.md @@ -0,0 +1,123 @@ +# HDL notes — `veil_rot` (TX) / `veil_unrot` (RX) + +> **STATUS: SYNTHETIC / L0 — design notes only. No RTL is shipped here, none has +> been synthesized, placed, routed, or run on an FPGA.** This describes the +> Verilog blocks that *would* apply the keyed unitary in the openwifi datapath. +> Every concrete number (offsets, latency, resource use) is `TODO(hdl)` until a +> real build exists. **Orthogonal transform ⇒ transmit energy preserved: +> compliant, never jamming.** + +## Where the blocks sit + +openwifi's baseband IQ moves as **AXI-Stream** between blocks and its control is +**AXI-Lite** ([FPGA module design][fmd]). The two new blocks are AXI-Stream +pass-through filters with an AXI-Lite slave for the key schedule. + +``` +TX (protector): + openofdm_tx ──AXI-S(IQ)──► [ veil_rot ] ──AXI-S(IQ)──► tx_intf ──► AD9361 DAC + ▲ AXI-Lite (key, coeff RAM) + └── veil_openwifi.c + +RX (legitimate STA, shares key): + AD9361 ADC ──► rx_intf ──AXI-S──► [ veil_unrot ] ──AXI-S──► openofdm_rx (FFT → chan est) + ▲ AXI-Lite + └── veil_openwifi.c +``` + +`veil_unrot` may equivalently sit **in the frequency domain**, right after the +FFT and **before channel estimation**, if a per-subcarrier `Q^H` is cheaper to +apply there. Same AXI-Lite contract either way. + +## Why a *new* block is required (honesty) + +openwifi is **SISO 802.11a/g/n** and has **no explicit-beamforming / spatial- +mapping stage** and **no compressed-BF-report generation** — the two-antenna app +note is RX-only capture, not a TX spatial mapper ([iq_2ant][2ant]). So there is +no existing `Q` matrix to modify; `veil_rot`/`veil_unrot` **introduce** the +spatial-mapping stage. Two realizable RTL scopes: + +- **Scope A — 1×1 per-subcarrier phase/rotation (lower effort).** Treat the + rotation as operating over a **synthetic vector** formed from the fine + subspace of the per-packet subcarrier response (a stream of `N` IQ elements + the block buffers), applying the core's Givens schedule across those elements. + Single TX chain; no board change. This is enough to *scramble the CSI a + sniffer estimates* and to demonstrate keyed invert at RX. It is **not** true + spatial MIMO. +- **Scope B — 2×2 true spatial mapping (higher effort, the A-capability demo).** + Enable the **second TX chain** (AD9361 has 2 DACs on fmcomms2/3) and apply a + keyed 2×2 unitary across the two streams — a genuine transmit spatial mapping + the standard marks "not restricted." Needs a Vivado top-level rebuild wiring + the 2nd DAC and the extra AXI-S lane. `TODO(hdl)`. + +## `veil_rot` datapath + +The core applies `passes` **Givens rotations** `G(i,j,θ)` composed into `Q` +(`../core/veil_shield.c`). In hardware we apply the *same schedule* to the on-air +sample vector, so both ends derive identical coefficients from the shared key — +no matrix is transmitted. + +Per Givens op on elements `(i, j)` with programmed `(cos, sin)` in Q1.15: +``` + v_i' = cos*v_i - sin*v_j + v_j' = sin*v_i + cos*v_j // complex IQ: apply to I and Q lanes +``` +- Coefficients arrive from `veil_openwifi.c` as the packed `(i, j, cos, sin)` + schedule (2 AXI-Lite words per pass; packing defined in `veil_openwifi.c`). +- `veil_unrot` applies the schedule **in reverse with negated sin** (`sin → -sin`, + i.e. `Gᵀ`), matching `veil_shield_recover`. A `CTRL.inverse` bit selects it. +- Fixed point: openwifi baseband IQ is 16-bit I / 16-bit Q; coeffs are signed + Q1.15. `TODO(hdl)`: guard-bit / rounding so the composed rotation stays + norm-preserving to spec and never clips (clipping would break the + energy-preservation invariant — must be verified, not assumed). + +## AXI-Lite register map (must match `veil_openwifi.c`) + +| Offset | Name | Meaning | +|---|---|---| +| `0x00` | `CTRL` | bit0 enable, bit1 inverse (`veil_unrot`), bit2 load | +| `0x04` | `KEY_LO` | session key [31:0] | +| `0x08` | `KEY_HI` | session key [63:32] | +| `0x0C` | `NDIM` | on-air fine-block dimension `N` (≤ 64) | +| `0x10` | `PASSES` | number of Givens passes (default 96) | +| `0x14` | `COEFF_ADDR` | write index into coeff RAM | +| `0x18` | `COEFF_DATA` | packed `{j,i}` then `{sin,cos}` (2 words/pass) | +| `0x1C` | `STATUS` | bit0 ready, bit1 applied, bit2 err | + +`TODO(hdl)`: regenerate this from the block's `*_s_axi.v` once written (cf. +`openofdm_tx`'s 6 AXI-Lite registers at `ip/openofdm_tx/src/openofdm_tx_s_axi.v`) +and reconcile any offset changes back into `veil_openwifi.c`. + +## Timing / integration risks (call them out, don't hide them) + +- **802.11 SIFS budget.** The block adds pipeline latency between IFFT and DAC; + it must not violate the tight TX timing openwifi maintains in `tx_intf`. + `TODO(hdl)`: measure added cycles; keep within budget or absorb in existing + FIFO slack. +- **On-FPGA schedule vs. per-packet coeff load.** For per-*packet* keying, either + compute the SplitMix64 schedule on-FPGA from `(key, packet_counter)` or + double-buffer the coeff RAM. `TODO(hdl)`. +- **Bit-exactness with the core.** The on-FPGA (or shim-fed) `(cos,sin)` must + reproduce the core's schedule so `veil_unrot` inverts exactly. First gate is a + **self-loopback** IQ test (`veil_rot → veil_unrot`, assert recovered == input + within Q1.15 round-off) using openwifi's existing packet/IQ self-loopback + facility ([self-loopback app note][loop]). Passing loopback is a correctness + gate, **not** a defense `MEASURED` claim. + +## Build + +`TODO(hdl)`: add `veil_rot`/`veil_unrot` as `openwifi-hw` IP, instantiate in the +board block design, and rebuild the bitstream with Vivado per the openwifi-hw +build flow ([openwifi-hw][hw]). No bitstream is produced from this directory. + +## Sources + +- FPGA module design (AXI-S / AXI-Lite, block roles) — [deepwiki][fmd] +- openwifi-hw (FPGA IP + build flow) — [github.com/open-sdr/openwifi-hw][hw] +- Two-antenna IQ (RX-only; confirms no TX spatial mapper ships) — [iq_2ant][2ant] +- Packet/IQ self-loopback test — [self-loopback app note][loop] + +[fmd]: https://deepwiki.com/open-sdr/openwifi/2.2-fpga-module-design +[hw]: https://github.com/open-sdr/openwifi-hw +[2ant]: https://github.com/open-sdr/openwifi/blob/master/doc/app_notes/iq_2ant.md +[loop]: https://github.com/open-sdr/openwifi/blob/master/doc/app_notes/packet-iq-self-loopback-test.md diff --git a/firmware/privshield/openwifi/MEASUREMENT.md b/firmware/privshield/openwifi/MEASUREMENT.md new file mode 100644 index 00000000..f2ef3683 --- /dev/null +++ b/firmware/privshield/openwifi/MEASUREMENT.md @@ -0,0 +1,103 @@ +# P5 measurement protocol — openwifi WiFi Veil end-to-end + +> **STATUS: SYNTHETIC / L0 — this is a PLAN, not a result. No hardware has been +> run; no capture, log, or number in this repo is real.** This document defines +> exactly what must be executed and captured to earn the first `MEASURED` claim +> under CLAUDE.md's hardware-evidence rule. Until the witness artifact below +> exists, every accuracy/throughput/energy statement about openwifi WiFi Veil is +> `SYNTHETIC` and must be labelled so. **Compliant waveform controls only — +> orthogonal, energy-preserving; never jamming.** + +## Roadmap position + +This is roadmap **P5**: the two-node hardware measurement that turns the P4 +build scaffolds into a `MEASURED` defense result. Prerequisite gates (all on real +silicon, all currently unmet): a bitstream with `veil_rot`/`veil_unrot` +(`HDL_NOTES.md`), a driver loading `veil_openwifi.c`, and a passing on-FPGA +**self-loopback** correctness test. + +## Topology + +``` + [ Protector AP ] over the air [ Legitimate STA ] + openwifi node A ───────────────────────────────────► openwifi node B + veil_rot: Q(key) engaged │ veil_unrot: Q^H(key) + │ (shares key with A) + ▼ + [ Attacker sniffer ] + commodity NIC, monitor mode + Wi-BFI CSI/BF-feedback extraction + + re-ID model +``` + +The attacker is **passive** (monitor capture only). Nothing in this test +transmits to interfere with any station. + +## Hardware list + +| Role | Hardware | Software | +|---|---|---| +| Protector AP (A) | Zynq-7000 + AD9361 FMC (ZC706+fmcomms2/3, or ADRV9361-Z7035) | openwifi image + `veil_rot` bitstream + `veil_openwifi.c` | +| Legitimate STA (B) | second identical openwifi node | openwifi image + `veil_unrot` bitstream + `veil_openwifi.c`, same key as A | +| Attacker | host + Wi-BFI-supported Wi-Fi NIC in monitor mode | Wi-BFI ([arxiv 2309.04408][wibfi]) + re-ID model | +| Bench | shielded room or wired attenuator path preferred | `iperf3`, power meter / board rail sense | + +Key agreement A↔B is out-of-band for the demo (pre-shared session key); +per-packet keying uses `(key, packet_counter)` as in `HDL_NOTES.md`. + +## Procedure + +Run every condition **twice**: WiFi Veil **OFF** (baseline) and **ON**. Same +positions, same MCS, same duration, same seed for the attacker model. + +1. **Correctness precondition (not a defense claim).** Confirm on-FPGA + self-loopback recovers IQ within Q1.15 round-off, and A→B link works with + `veil_unrot` engaged. Capture the console log. +2. **Attacker capture.** Sniffer records CSI / beamforming-feedback for a fixed + traffic pattern A→B, OFF then ON. Save raw captures (pcap + Wi-BFI output). +3. **Re-ID metric.** Run the same re-identification / fingerprinting model on the + OFF and ON captures. Report accuracy and confusion vs. the **chance / mean + baseline** (per CLAUDE.md, a defense claim needs the baseline and a + leakage-free held-out split — never report bare accuracy). +4. **Throughput (near-free check).** `iperf3` A↔B, OFF vs. ON, both directions. + Expected: ON ≈ OFF (the receiver inverts the rotation). Save `iperf3 --json`. +5. **Energy / compliance.** Record per-frame TX energy OFF vs. ON (rail sense or + power meter) to substantiate the "energy-preserving / not jamming" claim, and + spectrum/mask conformance if a spectrum analyzer is available. + +## Metrics reported + +| Metric | OFF | ON | Requirement for a pass | +|---|---|---|---| +| Attacker re-ID accuracy vs. chance | baseline | — | collapses toward chance ON | +| iperf3 throughput A↔B | baseline | — | ON within a few % of OFF | +| Per-frame TX energy | baseline | — | ON ≈ OFF (orthogonality holds on-air) | +| Spectral mask conformance | pass | — | still conformant ON | + +## Required witness artifact (CLAUDE.md gate) + +Before **any** `MEASURED` claim, this directory (or the P5 evidence path) must +contain a **captured real-silicon log**, not a build or simulator output: + +- Boot/runtime console log of both openwifi nodes showing the `veil_rot` / + `veil_unrot` bitstream loaded and `veil_openwifi.c` programming the session + (register writes / STATUS ready), with timestamps and board identifiers. +- The self-loopback correctness log (step 1). +- Raw attacker captures (pcap + Wi-BFI output) for OFF and ON, plus the exact + re-ID reproducer command and its output. +- `iperf3 --json` for OFF and ON; energy trace for OFF and ON. +- A manifest tying each artifact to the git commit of the RTL, driver, and shim + used, so the result is reproducible. + +Label the result `MEASURED` **only** with all of the above captured from real +hardware. A successful Vivado build, a Verilator/QEMU run, or the host +`veil_openwifi.c` self-test is **not** hardware evidence and must stay +`SYNTHETIC`. No log in this repo today — do not fabricate one. + +## Sources + +- Wi-BFI (attacker BF-feedback extraction) — [arxiv.org/pdf/2309.04408][wibfi] +- Packet/IQ self-loopback test — [openwifi self-loopback app note][loop] + +[wibfi]: https://arxiv.org/pdf/2309.04408 +[loop]: https://github.com/open-sdr/openwifi/blob/master/doc/app_notes/packet-iq-self-loopback-test.md diff --git a/firmware/privshield/openwifi/README.md b/firmware/privshield/openwifi/README.md new file mode 100644 index 00000000..63d25cfa --- /dev/null +++ b/firmware/privshield/openwifi/README.md @@ -0,0 +1,122 @@ +# WiFi Veil protector — openwifi (Xilinx Zynq + AD9361, open PHY/MAC) + +> **STATUS: SYNTHETIC / L0 — build-only scaffold. No hardware, no flash, no +> capture. Nothing here has run on silicon.** Per CLAUDE.md, none of this is a +> `MEASURED` result and none may be claimed as working. Files are honest +> skeletons with real openwifi idioms plus `TODO(hw)` / `TODO(hdl)` markers, not +> validated firmware or complete HDL. **Compliant waveform controls only — the +> keyed rotation is orthogonal (energy-preserving) and shapes only this node's +> own standards-conformant emission. Never jamming.** + +## Feasibility grade: **B (capability ceiling A; effort D)** + +openwifi is the **only** platform in this tree where a true end-to-end keyed +rotation *and its inverse* are physically reachable, because it is the only one +that exposes the full open PHY/MAC on FPGA: `openofdm_tx`/`openofdm_rx`, +`tx_intf`/`rx_intf`, and `side_ch`, all AXI-Lite-programmable from a Linux +driver ([FPGA module design][fmd], [openwifi overview][ov]). That is the **A** +capability ceiling. + +It is graded **B**, not A, for two honest reasons that make it the +highest-*effort* path: + +1. **openwifi has no native explicit transmit beamforming.** It ships as an + 802.11a/g/n **single-spatial-stream (SISO)** design. It does not run NDP + sounding, does not compute an SVD `V` matrix, and does not emit a compressed + beamforming report. The two-antenna app note is **RX-only** coherent capture + (`side_ch_ctl wh3h11`), not a MIMO transmit spatial mapper ([iq_2ant][2ant]). + So there is no shipped compressed-BF-report to obfuscate and no shipped + spatial-mapping matrix `Q` to left-multiply — both must be **added in HDL**. +2. Reaching a true two-stream demo needs a **second TX chain** (the AD9361 on + fmcomms2/3 has two DACs) plus a new spatial-mapping RTL stage and a Vivado + rebuild — days-to-weeks of FPGA work, not a driver patch. + +Because of (1), on openwifi WiFi Veil is realized as the **client-transparent +per-packet keyed unitary** (LeakyBeam family) applied at the TX spatial-mapping +stage, with the legitimate STA (a second openwifi node sharing the key) +inverting it — **not** as obfuscation of a compressed-BF report the hardware +never produces. This keeps the claim honest: we rotate the *transmitted spatial +mapping* so a sniffer's per-subcarrier channel estimate `H·Q(key)` is scrambled, +and the keyed receiver applies `Q(key)^H` before channel estimation. + +## Exact insertion points + +The rotation is a keyed orthogonal (unitary) matrix `Q(key, session)` computed +by the portable core (`../core/veil_shield.{h,c}`), the same SplitMix64 schedule +used everywhere, so both ends derive the identical `Q` from the shared key. + +**TX (protector) — FPGA, new block `veil_rot`:** +Insert on the baseband IQ AXI-Stream path **between `openofdm_tx` (post-IFFT, +post-CP) and `tx_intf`** (which feeds the AD9361 DAC). `veil_rot` left-multiplies +the per-subcarrier / per-stream sample vector by `Q(key)`. Its coefficients (or a +key seed + on-FPGA schedule) are written over **AXI-Lite** from the driver shim +using the standard openwifi `iowrite32(value, base_addr + reg)` idiom +([tx_intf driver][txintf]). See `HDL_NOTES.md`. + +**RX (legitimate STA) — FPGA, new block `veil_unrot`:** +Insert **between `rx_intf` (AD9361 ADC) and `openofdm_rx`**, or in the frequency +domain immediately after the FFT and **before channel estimation**, applying +`Q(key)^H`. Same AXI-Lite programming path. + +**Driver / control plane:** the C shim `veil_openwifi.c` computes the session +key schedule via the core and programs the blocks. Real openwifi control idioms: +AXI-Lite MMIO from the kernel driver, and the `sdrctl` nl80211-testmode tool / +`side_ch_ctl` register pokes for bring-up ([sdrctl/side_ch][ov], [frequent +tricks][ft]). Where the exact offsets/bitfields are not yet fixed, the shim +marks `TODO(hw)`; RTL specifics are `TODO(hdl)`. + +Doing the rotation in HDL (not the DMA'd payload) is deliberate: it keeps the +frame **standards-conformant on the wire** and preserves transmit energy — the +"not jamming" invariant the core guarantees by construction (orthogonal `Q`). + +## Two-node measurement plan (the P5 path) + +Three roles produce the first `MEASURED` / P5 result (full protocol + +required witness log in `MEASUREMENT.md`): + +- **Protector AP** — openwifi node A, `veil_rot` engaged, TX spatial mapping + keyed with the session key. +- **Legitimate STA** — openwifi node B, shares the key, `veil_unrot` engaged; + should see **near-baseline throughput** (rotation cancels). +- **Attacker sniffer** — a commodity Wi-Fi NIC running **Wi-BFI** / monitor + capture, extracting the per-subcarrier CSI / beamforming feedback and running + the re-ID model ([Wi-BFI][wibfi]). + +Headline metric: **re-identification accuracy off vs. on** at the attacker +(target: collapse toward chance) **while** iperf throughput A↔B stays near +baseline and per-frame energy is unchanged. No number here is real until a +captured on-silicon log exists. + +## Bill of materials (target, not procured) + +- 2× Xilinx Zynq-7000 board with AD9361 FMC (e.g. ZC706 + fmcomms2/3, or + ADRV9361-Z7035 / Antenna-SDR), openwifi image per the openwifi build docs. +- 1× attacker host + Wi-BFI-capable NIC (per Wi-BFI's supported list). +- Vivado for the FPGA rebuild that adds `veil_rot` / `veil_unrot`. + +## Files here + +| File | What it is | +|---|---| +| `README.md` | this — feasibility, insertion points, measurement plan | +| `veil_openwifi.c` | driver-side C shim: core → session `Q` → AXI-Lite program (scaffold, `TODO(hw)`) | +| `HDL_NOTES.md` | the `veil_rot` / `veil_unrot` Verilog blocks (design notes, `TODO(hdl)`) | +| `MEASUREMENT.md` | exact P5 protocol, metrics, and the required witness artifact | + +## Sources + +- FPGA module design — [deepwiki.com/open-sdr/openwifi/2.2-fpga-module-design][fmd] +- openwifi overview (sdrctl, side_ch, nl80211 testmode) — [deepwiki.com/open-sdr/openwifi/1-openwifi-overview][ov] +- Two-antenna IQ (RX-only) app note — [github.com/open-sdr/openwifi .../iq_2ant.md][2ant] +- tx_intf driver register idioms (`iowrite32`/`ioread32`) — [github.com/open-sdr/openwifi .../tx_intf.c][txintf] +- Frequent tricks / register pokes — [github.com/open-sdr/openwifi .../frequent_trick.md][ft] +- openwifi paper (SDR 802.11 on SoC) — [researchgate .../342582824][paper] +- Wi-BFI (attacker BF-feedback extraction) — [arxiv.org/pdf/2309.04408][wibfi] + +[fmd]: https://deepwiki.com/open-sdr/openwifi/2.2-fpga-module-design +[ov]: https://deepwiki.com/open-sdr/openwifi/1-openwifi-overview +[2ant]: https://github.com/open-sdr/openwifi/blob/master/doc/app_notes/iq_2ant.md +[txintf]: https://github.com/open-sdr/openwifi/blob/master/driver/tx_intf/tx_intf.c +[ft]: https://github.com/open-sdr/openwifi/blob/master/doc/app_notes/frequent_trick.md +[paper]: https://www.researchgate.net/publication/342582824_openwifi_a_free_and_open-source_IEEE80211_SDR_implementation_on_SoC +[wibfi]: https://arxiv.org/pdf/2309.04408 diff --git a/firmware/privshield/openwifi/veil_openwifi.c b/firmware/privshield/openwifi/veil_openwifi.c new file mode 100644 index 00000000..012d5def --- /dev/null +++ b/firmware/privshield/openwifi/veil_openwifi.c @@ -0,0 +1,315 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * veil_openwifi — driver-side shim that binds the portable VEIL core + * (../core/veil_shield.{h,c}) to the openwifi FPGA TX/RX datapath. + * + * STATUS: SYNTHETIC / L0. Build-only scaffold. Never compiled into the openwifi + * kernel module on real silicon, never flashed, never captured. Do NOT claim + * runtime behavior without a captured hardware log (CLAUDE.md hardware-evidence + * rule). Register offsets, bitfields, and the FPGA blocks it programs + * (veil_rot / veil_unrot) do NOT exist in upstream openwifi yet — every place + * that depends on real hardware is marked TODO(hw); RTL specifics live in + * HDL_NOTES.md and are marked TODO(hdl) there. + * + * ROLE (honest): this shim runs on the protector AP and on the legitimate STA. + * - Protector: derive the per-session keyed unitary Q(key) from the core and + * program the veil_rot block that left-multiplies the transmit spatial + * mapping (inserted between openofdm_tx and tx_intf; see HDL_NOTES.md). + * - Legitimate STA: derive the same Q(key) and program veil_unrot to apply + * Q^H before channel estimation, cancelling the rotation (near-free tput). + * The transform is orthogonal, so transmit energy is preserved: compliant, + * NOT jamming. openwifi ships SISO with no explicit beamforming, so this is the + * client-transparent per-packet unitary route, not obfuscation of a compressed + * beamforming report (openwifi never generates one) — see README.md. + * + * openwifi idioms used where known: + * - AXI-Lite MMIO from the driver: iowrite32(value, base + reg) / + * ioread32(base + reg), matching driver/tx_intf/tx_intf.c reg_write/reg_read. + * - Coefficients are quantized to the fixed-point width the datapath uses + * (openwifi baseband IQ is 16-bit I / 16-bit Q); see VEIL_ROT_FRAC below. + * + * This file is written to compile in two modes: + * - Host/CI (default): __KERNEL__ undefined -> MMIO is stubbed to a local + * shadow buffer so the key-schedule + quantization logic is unit-testable + * with no hardware. This is the ONLY path exercised today. + * - In-tree kernel build: define VEIL_OPENWIFI_KERNEL to pull the real + * linux/io.h accessors. Untested. TODO(hw). + */ + +#include "../core/veil_shield.h" + +#include +#include +#include +#include + +/* ------------------------------------------------------------------------- + * MMIO layer. Real openwifi drivers keep a per-block __iomem base and use + * iowrite32/ioread32. We isolate that here so host/CI builds need no kernel. + * ------------------------------------------------------------------------- */ +#if defined(VEIL_OPENWIFI_KERNEL) +#include +typedef void __iomem *veil_mmio_base; +static inline void veil_reg_write(veil_mmio_base b, uint32_t reg, uint32_t v) { + iowrite32(v, (uint8_t __iomem *)b + reg); +} +static inline uint32_t veil_reg_read(veil_mmio_base b, uint32_t reg) { + return ioread32((uint8_t __iomem *)b + reg); +} +#else +/* Host/CI shadow: a small register file so logic is testable with no radio. */ +#define VEIL_SHADOW_REGS 256 +typedef struct { + uint32_t regs[VEIL_SHADOW_REGS]; +} veil_mmio_shadow; +typedef veil_mmio_shadow *veil_mmio_base; +static inline void veil_reg_write(veil_mmio_base b, uint32_t reg, uint32_t v) { + if (b && (reg >> 2) < VEIL_SHADOW_REGS) { + b->regs[reg >> 2] = v; + } +} +static inline uint32_t veil_reg_read(veil_mmio_base b, uint32_t reg) { + if (b && (reg >> 2) < VEIL_SHADOW_REGS) { + return b->regs[reg >> 2]; + } + return 0; +} +#endif + +/* ------------------------------------------------------------------------- + * Register map for the (not-yet-existing) veil_rot / veil_unrot AXI-Lite + * slaves. Offsets are PLACEHOLDERS chosen to be word-aligned; the real map is + * fixed when the RTL lands. TODO(hw): confirm against the generated + * *_s_axi.v once veil_rot exists (cf. openofdm_tx's 6 AXI-Lite regs). + * ------------------------------------------------------------------------- */ +#define VEIL_ROT_REG_CTRL 0x00u /* bit0 enable, bit1 inverse, bit2 load */ +#define VEIL_ROT_REG_KEY_LO 0x04u /* session key [31:0] */ +#define VEIL_ROT_REG_KEY_HI 0x08u /* session key [63:32] */ +#define VEIL_ROT_REG_NDIM 0x0Cu /* fine-block dimension N applied on-air */ +#define VEIL_ROT_REG_PASSES 0x10u /* number of Givens passes */ +#define VEIL_ROT_REG_COEFF_ADDR 0x14u /* write index into the coeff RAM */ +#define VEIL_ROT_REG_COEFF_DATA 0x18u /* {Q16.15 sin, Q16.15 cos} packed */ +#define VEIL_ROT_REG_STATUS 0x1Cu /* bit0 ready, bit1 applied, bit2 err */ + +#define VEIL_ROT_CTRL_ENABLE (1u << 0) +#define VEIL_ROT_CTRL_INVERSE (1u << 1) +#define VEIL_ROT_CTRL_LOAD (1u << 2) + +#define VEIL_ROT_STATUS_READY (1u << 0) + +/* Fixed-point: openwifi baseband IQ is 16-bit. We program rotation coeffs as + * signed Q1.15 (fractional bits = 15). cos/sin in [-1,1] map cleanly. */ +#define VEIL_ROT_FRAC 15 + +/* Default schedule parameters — kept byte-consistent with the core/Rust crate + * defaults. N is the on-air fine-block dimension the datapath vectorizes over; + * for the SISO-plus-synthetic-stream demo this is small (see HDL_NOTES.md). */ +#define VEIL_OW_DEFAULT_PASSES 96u +#define VEIL_OW_MAX_NDIM 64u /* bounded coeff RAM; keeps it malloc-free */ + +typedef enum { + VEIL_OW_ROLE_PROTECTOR = 0, /* TX veil_rot, forward rotation Q */ + VEIL_OW_ROLE_LEGIT_RX = 1, /* RX veil_unrot, inverse rotation Q^H */ +} veil_ow_role; + +typedef struct { + veil_mmio_base base; /* AXI-Lite base of veil_rot / veil_unrot slave */ + uint64_t key; /* shared session key (both ends must match) */ + uint32_t ndim; /* fine-block dimension, <= VEIL_OW_MAX_NDIM */ + uint32_t passes; /* Givens passes */ + veil_ow_role role; +} veil_ow_ctx; + +/* Saturating float -> signed Q1.15. */ +static int16_t veil_q15(float x) { + float scaled = x * (float)(1 << VEIL_ROT_FRAC); + if (scaled > 32767.0f) return 32767; + if (scaled < -32768.0f) return -32768; + return (int16_t)lrintf(scaled); +} + +/* ------------------------------------------------------------------------- + * Coefficient generation. The core's schedule is (i, j, theta) Givens ops + * derived from SplitMix64(key). The FPGA applies the SAME schedule to on-air + * samples, so we hand it the per-pass (i, j, cos, sin). We regenerate the + * schedule here with the identical draw order as veil_shield.c so the shim and + * the (future) RTL agree bit-for-bit with the reference crate. + * + * NOTE: this mirrors veil_shield.c's private schedule. It is duplicated (not + * exported) on purpose — the core stays a pure in-memory transform with a + * stable ABI; the adapter owns the hardware-facing serialization. If the core + * later exports its schedule, collapse this. TODO(hw): validate equality with a + * captured on-FPGA coeff dump before any MEASURED claim. + * ------------------------------------------------------------------------- */ +typedef struct { + uint16_t i; + uint16_t j; + int16_t cos_q15; + int16_t sin_q15; +} veil_ow_givens; + +/* TAU matches VEIL_TAU in veil_shield.c / Rust core::f32::consts::TAU. */ +#define VEIL_OW_TAU 6.28318530717958647692f + +static void veil_ow_build_schedule(uint64_t key, uint32_t n, uint32_t passes, + veil_ow_givens *out /* [passes] */) { + veil_rng r; + uint32_t p; + if (n < 2) { + for (p = 0; p < passes; p++) { + out[p].i = 0; out[p].j = 0; + out[p].cos_q15 = veil_q15(1.0f); out[p].sin_q15 = 0; + } + return; + } + veil_rng_seed(&r, key); + for (p = 0; p < passes; p++) { + uint32_t i = (uint32_t)(veil_rng_next_u64(&r) % (uint64_t)n); + uint32_t j = (uint32_t)(veil_rng_next_u64(&r) % (uint64_t)n); + float theta; + if (j == i) { + j = (j + 1) % n; + } + theta = veil_rng_next_f32(&r) * VEIL_OW_TAU; + out[p].i = (uint16_t)i; + out[p].j = (uint16_t)j; + out[p].cos_q15 = veil_q15(cosf(theta)); + out[p].sin_q15 = veil_q15(sinf(theta)); + } +} + +/* ------------------------------------------------------------------------- + * Public API. + * ------------------------------------------------------------------------- */ + +/* Program a session key into the veil_rot/veil_unrot block. Returns 0 on the + * host shadow path; on real hardware it must poll STATUS_READY. */ +int veil_ow_program_session(veil_ow_ctx *ctx) { + veil_ow_givens sched[VEIL_OW_DEFAULT_PASSES]; + uint32_t ctrl = VEIL_ROT_CTRL_LOAD; + uint32_t p, passes, n; + + if (!ctx || ctx->ndim < 2 || ctx->ndim > VEIL_OW_MAX_NDIM) { + return -1; /* bounds check the on-air dimension (least authority) */ + } + passes = ctx->passes ? ctx->passes : VEIL_OW_DEFAULT_PASSES; + if (passes > VEIL_OW_DEFAULT_PASSES) { + passes = VEIL_OW_DEFAULT_PASSES; /* bounded, stack-only schedule */ + } + n = ctx->ndim; + + veil_ow_build_schedule(ctx->key, n, passes, sched); + + /* Program header registers. */ + veil_reg_write(ctx->base, VEIL_ROT_REG_KEY_LO, (uint32_t)(ctx->key)); + veil_reg_write(ctx->base, VEIL_ROT_REG_KEY_HI, (uint32_t)(ctx->key >> 32)); + veil_reg_write(ctx->base, VEIL_ROT_REG_NDIM, n); + veil_reg_write(ctx->base, VEIL_ROT_REG_PASSES, passes); + + /* Stream the (i, j, cos, sin) schedule into the coeff RAM. Packing: + * COEFF_DATA = {i[15:0]... } is too wide for one 32-bit word, so we use a + * 2-word-per-pass convention: word A = {j[15:0], i[15:0]}, word B = + * {sin_q15[15:0], cos_q15[15:0]}. TODO(hdl): the veil_rot coeff-RAM write + * FSM must match this exact packing. TODO(hw): confirm endianness of the + * AXI-Lite slave. */ + for (p = 0; p < passes; p++) { + uint32_t wa = ((uint32_t)(uint16_t)sched[p].j << 16) | + (uint32_t)(uint16_t)sched[p].i; + uint32_t wb = ((uint32_t)(uint16_t)sched[p].sin_q15 << 16) | + (uint32_t)(uint16_t)sched[p].cos_q15; + veil_reg_write(ctx->base, VEIL_ROT_REG_COEFF_ADDR, p * 2u); + veil_reg_write(ctx->base, VEIL_ROT_REG_COEFF_DATA, wa); + veil_reg_write(ctx->base, VEIL_ROT_REG_COEFF_ADDR, p * 2u + 1u); + veil_reg_write(ctx->base, VEIL_ROT_REG_COEFF_DATA, wb); + } + + if (ctx->role == VEIL_OW_ROLE_LEGIT_RX) { + ctrl |= VEIL_ROT_CTRL_INVERSE; /* veil_unrot applies Q^H */ + } + veil_reg_write(ctx->base, VEIL_ROT_REG_CTRL, ctrl); + + /* TODO(hw): on real silicon, poll VEIL_ROT_REG_STATUS for READY here and + * time out. The host shadow has no FSM, so we return success directly and + * DO NOT claim the hardware accepted it. */ +#if defined(VEIL_OPENWIFI_KERNEL) + { + int spins = 100000; /* TODO(hw): calibrate against real ready latency */ + while (spins-- > 0) { + if (veil_reg_read(ctx->base, VEIL_ROT_REG_STATUS) & + VEIL_ROT_STATUS_READY) { + break; + } + } + if (spins <= 0) { + return -2; /* not ready — never treat as success */ + } + } +#endif + return 0; +} + +/* Engage / disengage the block (bit0 of CTRL), preserving the inverse bit. */ +int veil_ow_set_enabled(veil_ow_ctx *ctx, int enable) { + uint32_t ctrl; + if (!ctx) { + return -1; + } + ctrl = veil_reg_read(ctx->base, VEIL_ROT_REG_CTRL); + if (enable) { + ctrl |= VEIL_ROT_CTRL_ENABLE; + } else { + ctrl &= ~VEIL_ROT_CTRL_ENABLE; + } + veil_reg_write(ctx->base, VEIL_ROT_REG_CTRL, ctrl); + return 0; +} + +/* + * Control-plane bring-up alternatives (documented idioms, not wired here): + * - sdrctl (nl80211 testmode) for driver-level toggles once a testmode verb + * is added, e.g. a "veil" subcommand mirroring existing sdrctl reg pokes. + * - side_ch_ctl-style hex register pokes during bench bring-up, e.g. the + * side_ch app note's `./side_ch_ctl whXXdY` write convention, retargeted at + * the veil_rot slave. TODO(hw): pick and document the actual verb. + * + * Self-loopback validation (before over-the-air): openwifi supports a + * packet/IQ self-loopback test. Route veil_rot -> veil_unrot in loopback and + * assert recovered IQ == original within Q1.15 round-off. That is the first + * on-FPGA correctness gate (still not a defense MEASURED claim). TODO(hw). + */ + +#if defined(VEIL_OPENWIFI_SELFTEST) +/* Host-only smoke test of the schedule/quantization path — NO hardware. + * Verifies the shadow register file receives a plausible, bounded program. + * Build: cc -DVEIL_OPENWIFI_SELFTEST veil_openwifi.c ../core/veil_shield.c -lm */ +#include +int main(void) { + veil_mmio_shadow shadow; + veil_ow_ctx ctx; + memset(&shadow, 0, sizeof(shadow)); + ctx.base = &shadow; + ctx.key = 0x0123456789ABCDEFull; + ctx.ndim = 16; + ctx.passes = VEIL_OW_DEFAULT_PASSES; + ctx.role = VEIL_OW_ROLE_PROTECTOR; + + if (veil_ow_program_session(&ctx) != 0) { + printf("FAIL: program_session\n"); + return 1; + } + if (veil_ow_set_enabled(&ctx, 1) != 0) { + printf("FAIL: set_enabled\n"); + return 1; + } + if (veil_reg_read(&shadow, VEIL_ROT_REG_NDIM) != 16u) { + printf("FAIL: ndim not programmed\n"); + return 1; + } + if (!(veil_reg_read(&shadow, VEIL_ROT_REG_CTRL) & VEIL_ROT_CTRL_ENABLE)) { + printf("FAIL: enable bit\n"); + return 1; + } + printf("OK (SYNTHETIC/L0 host shadow only — NOT hardware-validated)\n"); + return 0; +} +#endif diff --git a/firmware/privshield/openwrt/INTEGRATION.md b/firmware/privshield/openwrt/INTEGRATION.md new file mode 100644 index 00000000..58f32cc4 --- /dev/null +++ b/firmware/privshield/openwrt/INTEGRATION.md @@ -0,0 +1,95 @@ +# WiFi Veil ↔ `mac80211` / driver integration map + +> **`SYNTHETIC / L0` — BUILD-ONLY, UNTESTED ON HARDWARE.** These are hook-point +> designs derived from public API/source, not validated on silicon. Function and +> attribute names are real (verified against in-tree `linux/nl80211.h` and public +> hostapd/driver docs); where a hook does **not** exist upstream it is marked +> `TODO(hw)` with what a patch would have to add. Compliant controls only. + +Legend: **US** = userspace-reachable today · **DP** = needs driver patch · +**FW** = needs firmware patch (blob-blocked). + +--- + +## 1. TX antenna-map perturbation — **US** (feasible) + +- **Daemon:** `veil_set_tx_antenna_mask()` in `veil_shieldd.c`. +- **Kernel path:** `nl80211` → `cfg80211_ops.set_antenna()` → driver + `.set_antenna` (e.g. `mt7915_set_antenna`, `ath9k` `set_antenna`). +- **Attributes:** `NL80211_CMD_SET_WIPHY`, `NL80211_ATTR_WIPHY_ANTENNA_TX`, + `NL80211_ATTR_WIPHY_ANTENNA_RX`. +- **Constraints:** many drivers require the phy DOWN and accept only symmetric + masks; validate per driver. Coarse static spatial-mapping change, not the keyed + rotation. Fully standards-compliant. + +## 2. NDP sounding-cadence jitter — **US (indirect)** + +- **Daemon:** `veil_randomize_sounding_cadence()` / `veil_next_cadence_ms()`. + The schedule is derived from the session key via the core SplitMix64 so the + paired receiver can anticipate it (not random spraying). +- **Real lever:** hostapd `ctrl_iface` (UNIX socket `/var/run/hostapd/`): + `SET he_su_beamformer …` / rewrite `vht_capab` `[SOUNDING-DIMENSION-n]` / + toggle `[SU-BEAMFORMER]`, then `RECONFIGURE`. Config keys documented in + `hostapd.conf`. +- **`TODO(hw)`:** there is **no** `nl80211` "set sounding interval" command; the + per-NDP timer is in driver/firmware. We can only jitter the *offered* cadence. + The `ctrl_iface` write itself is not yet wired (function currently only + computes `ms`). + +## 3. MU-MIMO group shuffling — **FW** (blob-blocked) + +- **Daemon:** `veil_shuffle_mumimo_groups()` — explicit `-ENOTSUP` no-op. +- **Where it lives:** MU group formation + per-group steering matrices are + computed in the WiFi MCU firmware on mt76 (mt7915) and all ath1x parts. +- **`TODO(hw)`:** would require `NL80211_CMD_VENDOR` with a driver-specific + `NL80211_ATTR_VENDOR_ID` / `NL80211_ATTR_VENDOR_SUBCMD` / + `NL80211_ATTR_VENDOR_DATA` that upstream mt76/ath do **not** define, plus a + firmware change to honor an externally supplied grouping. Not reachable without + both a driver and firmware patch. + +## 4. Per-packet keyed unitary (the core WiFi Veil transform) — **FW** (blob-blocked) + +- **Daemon:** `veil_apply_keyed_rotation()` → `veil_shield_apply(fine, n, key, + passes)` from the portable core. Orthogonal / energy-preserving (the + "not jamming" invariant, checked via `veil_l2_norm` before/after). +- **What a full path must touch:** + - **mt76 (mt7915):** the MCU firmware stage that builds the compressed + beamforming report (φ/ψ angles) or applies the steering/precoder Q to the + LTF spatial mapping. A firmware patch would call the rotation on the fine + subspace *before* the report is emitted / precoder applied. The driver + (`mt7915/mcu.c`) would ferry the key/passes down via a new MCU command. + - **ath9k (DP, best open case):** the static spatial-mapping matrix is set via + `AR_PHY_*` registers in the open PHY init; a driver patch could apply a keyed + *static* Q there. This is coarser than a true per-packet report edit but is + the most credible OpenWRT-adjacent route (older 802.11n hardware only). + - **ath10k/ath11k/ath12k:** report generation + precoder are entirely + firmware-side with no open firmware (ath11k/ath12k) — not patchable. +- **`TODO(hw)`:** on OpenWRT there is **no** userspace/`mac80211` hook that hands + the pre-precoder V/steering buffer to the daemon before TX. Reaching it needs + the driver+firmware patch above, or use the **openwifi (FPGA)** / **Nexmon + (Broadcom)** adapters, which expose the datapath. The daemon only proves the + math is invariant; nothing goes on air. + +## 5. Sensing-solicitation (NDPA) detection — **US/DP** (partial) + +- **Daemon:** `veil_event_cb()` on `NL80211_CMD_FRAME`. +- **Real path:** `NL80211_CMD_REGISTER_FRAME` to subscribe to specific + management action categories, delivered as `NL80211_CMD_FRAME` with + `NL80211_ATTR_FRAME`. Classify VHT/HE compressed beamforming action + (categories 21 / 30) and NDP Announcement to measure cadence. +- **`TODO(hw)`:** commodity drivers do **not** forward raw NDPA to userspace by + default; honest external-solicitation detection needs monitor-mode capture or a + driver notification that is not guaranteed upstream. Frame parsing is stubbed. + +--- + +## Summary of the effort boundary + +| Control | Effort to reach full WiFi Veil fidelity | +|---|---| +| TX antenna map | Ready now (US), coarse only | +| Sounding cadence jitter | Wire hostapd `ctrl_iface` (US), coarse only | +| Static spatial Q | ath9k driver patch (DP) | +| MU grouping | driver vendor subcmd + firmware (FW) | +| Per-packet keyed rotation | mt76/ath **firmware** patch, or openwifi/Nexmon adapter (FW) | +| NDPA detection | frame registration + likely driver patch (US/DP) | diff --git a/firmware/privshield/openwrt/Makefile b/firmware/privshield/openwrt/Makefile new file mode 100644 index 00000000..9a8155d4 --- /dev/null +++ b/firmware/privshield/openwrt/Makefile @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: MIT OR Apache-2.0 +# +# Host build-CHECK for the OpenWRT/mac80211 VEIL adapter. +# STATUS: SYNTHETIC / L0 — build-only, UNTESTED ON HARDWARE. +# +# Two targets: +# make core - compile+link the portable core only (always works, +# no libnl needed) — proves the rotation math builds. +# make daemon - build veil_shieldd against libnl-genl-3 (needs the +# dev headers: `pkg-config libnl-genl-3.0`). On OpenWRT +# the package build uses libnl-tiny instead (see openwrt.mk). +# +# This Makefile does NOT flash, run on, or validate any radio. + +CC ?= cc +COREDIR := ../core +CFLAGS ?= -std=c99 -Wall -Wextra -O2 -I$(COREDIR) +LDLIBS ?= -lm + +NL_CFLAGS := $(shell pkg-config --cflags libnl-genl-3.0 2>/dev/null) +NL_LIBS := $(shell pkg-config --libs libnl-genl-3.0 2>/dev/null) + +.PHONY: all core daemon clean +all: core + +# Always-buildable: the core object, no netlink dependency. +core: $(COREDIR)/veil_shield.c $(COREDIR)/veil_shield.h + $(CC) $(CFLAGS) -c $(COREDIR)/veil_shield.c -o veil_shield.o + @echo "core built (rotation math OK). Nothing was run on hardware." + +# Full daemon: requires libnl-genl-3 dev headers on the host. +daemon: veil_shieldd.c core +ifeq ($(strip $(NL_LIBS)),) + @echo "SKIP daemon: libnl-genl-3.0 not found (pkg-config)." + @echo " Install libnl-3-dev + libnl-genl-3-dev, or build via openwrt.mk." + @exit 0 +else + $(CC) $(CFLAGS) $(NL_CFLAGS) -o veil_shieldd \ + veil_shieldd.c veil_shield.o $(NL_LIBS) $(LDLIBS) + @echo "veil_shieldd linked (BUILD-ONLY; untested on silicon)." +endif + +clean: + rm -f veil_shield.o veil_shieldd diff --git a/firmware/privshield/openwrt/README.md b/firmware/privshield/openwrt/README.md new file mode 100644 index 00000000..8b7d1641 --- /dev/null +++ b/firmware/privshield/openwrt/README.md @@ -0,0 +1,112 @@ +# WiFi Veil — OpenWRT / Linux `mac80211` adapter + +> **STATUS: `SYNTHETIC / L0` — BUILD-ONLY, UNTESTED ON HARDWARE.** +> No radio was driven, no CSI captured, no log produced on silicon. Every +> claim below is a design/feasibility statement, not a `MEASURED` result. This +> adapter uses **compliant waveform controls only** — it never jams and emits +> no denial energy. + +This directory is the OpenWRT/`mac80211` platform adapter for the WiFi Veil privacy +shield. It links the validated portable core +(`../core/veil_shield.{h,c}` — the keyed Givens rotation over the identity-bearing +"fine" subspace of 802.11 compressed beamforming feedback) and drives the subset +of controls that Linux userspace/`mac80211` can actually reach on commodity APs. + +--- + +## Feasibility grade: **C** (partial — coarse compliant controls only) + +**Why C, not higher.** WiFi Veil's defining action is a *per-packet keyed unitary* on +the compressed beamforming-feedback angles (equivalently, a keyed Q on the LTF +spatial mapping / precoder). On every mainstream OpenWRT AP chipset +(Qualcomm ath10k/ath11k/ath12k, MediaTek mt76 / mt7915), that report is generated +and the precoder applied **inside the WiFi MCU firmware blob** — userspace and the +open driver never touch the pre-transmit V matrix. So the full keyed-rotation path +is **blob-blocked** from OpenWRT. What remains reachable is a set of *coarse* +compliant knobs that perturb, but do not cryptographically obfuscate, the CSI a +sensor observes. That is a real, honest defense-in-depth layer — hence C, not D — +but it is not the full WiFi Veil transform. + +**Why not D.** Some controls genuinely work from userspace (TX antenna map; +hostapd-mediated sounding/beamformer capability), and one chipset family +(**ath9k**) is open enough at the register level that a *driver patch* could reach +the static spatial-mapping matrix — a credible route to B on that specific, +older hardware. openwifi (FPGA) and Nexmon (Broadcom) are the routes to the full +A-grade keyed rotation, but those are **separate adapters**, not OpenWRT. + +--- + +## What is FEASIBLE vs. BLOB-BLOCKED from OpenWRT + +| WiFi Veil control | Reachable from OpenWRT? | Mechanism (real API / knob) | Notes | +|---|---|---|---| +| **TX antenna-map perturbation** | ✅ Feasible | `NL80211_CMD_SET_WIPHY` + `NL80211_ATTR_WIPHY_ANTENNA_TX` / `_RX` | Coarse static spatial-mapping change. Many drivers require phy DOWN and symmetric masks. Compliant. | +| **NDP sounding-cadence jitter** | 🟡 Indirect | hostapd `ctrl_iface` (rewrite `SOUNDING-DIMENSION`, toggle `[SU-BEAMFORMER]`, `RECONFIGURE`) | No `nl80211` "set sounding interval" exists; the per-NDP timer lives in driver/firmware. We can only jitter the *offered* capability. | +| **Beamformer/beamformee capability toggle** | ✅ Feasible | hostapd `vht_capab` / `he_su_beamformer` etc. | Standards-compliant advertisement. Coarse on/off, not per-packet. | +| **Spatial-stream → antenna mapping (static Q)** | 🟡 Driver-patch (ath9k only) | ath9k PHY spatial-mapping registers (`AR_PHY_*`) | Open enough to patch on ath9k; opaque/firmware on ath10k+/mt76. Not a stock userspace knob. | +| **MU-MIMO group shuffling** | ❌ Blob-blocked | would need `NL80211_CMD_VENDOR` subcmd that upstream mt76/ath do **not** expose | Group formation + steering matrices computed in MCU firmware. | +| **Per-packet keyed unitary on LTF / precoder** | ❌ Blob-blocked | — | The core WiFi Veil transform. Lives in firmware on all commodity AP parts. Requires firmware patch, or use openwifi / Nexmon adapters. | +| **Compressed-BF-report angle edit (φ/ψ)** | ❌ Blob-blocked | — | Report is generated in firmware/PHY; not exposed pre-TX on OpenWRT. | +| **External sensing-solicitation detection (NDPA cadence)** | 🟡 Partial | `NL80211_CMD_FRAME` + `NL80211_CMD_REGISTER_FRAME`, or monitor-mode capture | Commodity drivers do not forward raw NDPA to userspace by default. | + +--- + +## Best candidate chipsets / drivers + +- **ath9k (Atheros 802.11n)** — *best open target for a driver-side patch.* The + most transparent open driver (no per-packet firmware for the datapath), with a + long history of PHY register access and the Atheros CSI Tool ecosystem. A + static spatial-mapping perturbation and CSI observation are realistic here; + full HT beamforming-feedback editing still is not in open code. 802.11n-only. +- **mt76 (MediaTek mt7915 / mt7622-mt7615)** — *best-maintained modern open + driver* and the most likely place upstream would eventually accept a vendor + hook, but beamforming/sounding/MU grouping run in the MCU firmware today, so + the keyed path needs a firmware patch (blob-blocked out of the box). +- **ath10k / ath11k / ath12k (Qualcomm)** — most capable radios but the most + closed: regulatory + beamforming + sounding all firmware-side. ath11k/ath12k + have **no open firmware** at all. Worst target for the keyed path. +- **openwifi (FPGA SDR) / Nexmon (Broadcom)** — the only routes to the full + A-grade keyed rotation; handled by the sibling `../openwifi/` and `../nexmon/` + adapters, **not** this OpenWRT one. + +**Recommendation:** for OpenWRT specifically, target **ath9k** for a +driver-patch proof-of-concept (spatial-mapping + CSI), and **mt76/mt7915** as the +strategic modern platform pending a firmware/vendor-subcmd hook. + +--- + +## Build (host, build-only) + +```bash +make core # always works: compiles+links the portable core, no libnl needed +make daemon # builds veil_shieldd IF libnl-genl-3.0 dev headers are present +make clean +``` + +`make daemon` cleanly **skips** (does not fail) when `libnl-genl-3.0` is absent, +printing the required dev packages. On an OpenWRT buildroot use `openwrt.mk` +(rename to `Makefile` under `package/utils/veil-shieldd/`), which builds against +`libnl-tiny`. See `INTEGRATION.md` for the per-control hook points and exactly +what a driver/firmware patch would need to touch. + +--- + +## Sources + +- Linux `nl80211.h` (in-tree, this host): `NL80211_CMD_SET_WIPHY`, + `NL80211_ATTR_WIPHY_ANTENNA_TX` / `_RX`, `NL80211_CMD_VENDOR`, + `NL80211_CMD_FRAME` / `NL80211_CMD_REGISTER_FRAME`. +- ath10k configuration (beamforming only via hostapd `vht_capab`, no debugfs + sounding control): +- hostapd beamforming/sounding knobs (`[SU-BEAMFORMER]`, `[MU-BEAMFORMER]`, + `[SOUNDING-DIMENSION-4]`, `he_su_beamformer`): + and + +- mt76 beamforming lives in firmware (mt7622/mt7615 performance/beamforming + discussion): +- Qualcomm firmware closedness (ath11k/ath12k no open firmware; regulatory + + features firmware-enforced): ath10k mailing-list thread + + and CodeLinaro ath firmware +- ath11k reports VHT beamformee spatial streams *from firmware*: + diff --git a/firmware/privshield/openwrt/openwrt.mk b/firmware/privshield/openwrt/openwrt.mk new file mode 100644 index 00000000..5b073ecb --- /dev/null +++ b/firmware/privshield/openwrt/openwrt.mk @@ -0,0 +1,60 @@ +# SPDX-License-Identifier: MIT OR Apache-2.0 +# +# OpenWRT package Makefile STUB for veil_shieldd. +# STATUS: SYNTHETIC / L0 — package skeleton, UNTESTED ON HARDWARE / not in any feed. +# +# Drop this (renamed to `Makefile`) into a package dir such as +# `package/utils/veil-shieldd/` in an OpenWRT buildroot, alongside the copied +# core (veil_shield.{c,h}) and veil_shieldd.c under ./src/. It builds against +# libnl-tiny (the OpenWRT netlink lib) — the same nl80211 API surface, smaller. +# +# This stub does NOT prove the daemon works on a device; it only wires the +# build. No hardware validation is implied. + +include $(TOPDIR)/rules.mk + +PKG_NAME:=veil-shieldd +PKG_VERSION:=0.0.0-l0 +PKG_RELEASE:=1 +PKG_LICENSE:=MIT OR Apache-2.0 + +include $(INCLUDE_DIR)/package.mk + +define Package/veil-shieldd + SECTION:=utils + CATEGORY:=Utilities + TITLE:=VEIL compliant-waveform privacy shield (mac80211 adapter, L0) + # libnl-tiny provides nl80211/genl; hostapd for the ctrl_iface cadence path. + DEPENDS:=+libnl-tiny +hostapd-common + URL:=https://github.com/ruvnet/RuView +endef + +define Package/veil-shieldd/description + BUILD-ONLY / UNTESTED-ON-HARDWARE userspace adapter that drives the + standards-compliant subset of VEIL controls reachable from OpenWRT + (TX antenna map, hostapd-mediated sounding cadence) and links the portable + keyed-rotation core. The full per-packet keyed rotation is blob-blocked on + commodity Qualcomm/MediaTek parts and requires a driver/firmware patch. + This is NOT a jammer and emits no denial energy. +endef + +# Build flags: point at libnl-tiny headers and the copied core. +TARGET_CFLAGS += -I$(STAGING_DIR)/usr/include/libnl-tiny -I$(PKG_BUILD_DIR)/src +TARGET_LDFLAGS += -lnl-tiny -lm + +define Build/Compile + $(TARGET_CC) $(TARGET_CFLAGS) -std=c99 -Wall -Wextra \ + -o $(PKG_BUILD_DIR)/veil_shieldd \ + $(PKG_BUILD_DIR)/src/veil_shieldd.c \ + $(PKG_BUILD_DIR)/src/veil_shield.c \ + $(TARGET_LDFLAGS) +endef + +define Package/veil-shieldd/install + $(INSTALL_DIR) $(1)/usr/sbin + $(INSTALL_BIN) $(PKG_BUILD_DIR)/veil_shieldd $(1)/usr/sbin/veil_shieldd + # TODO(hw): ship a procd init script that reads the session key from a + # secure store (never a world-readable config) and passes -i . +endef + +$(eval $(call BuildPackage,veil-shieldd)) diff --git a/firmware/privshield/openwrt/veil_shieldd.c b/firmware/privshield/openwrt/veil_shieldd.c new file mode 100644 index 00000000..9de40efe --- /dev/null +++ b/firmware/privshield/openwrt/veil_shieldd.c @@ -0,0 +1,294 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * veil_shieldd — OpenWRT / Linux mac80211 userspace adapter for the VEIL + * compliant-waveform privacy shield (ADR-288 / ADR-290). + * + * ============================= HONESTY BANNER ============================== + * STATUS: SYNTHETIC / L0 — BUILD-ONLY SCAFFOLD, UNTESTED ON HARDWARE. + * + * This daemon compiles and links the portable veil_shield core, and it issues + * REAL nl80211/libnl calls for the small set of controls that Linux actually + * exposes to userspace (antenna TX mask, station/BSS observation). Everything + * that would edit the per-packet spatial mapping / precoder or the compressed + * beamforming-feedback angles is BLOB-BLOCKED on commodity Qualcomm/MediaTek + * parts and is marked `TODO(hw)` at the exact call site — see README.md and + * INTEGRATION.md. Nothing here has been run against a radio. Do not read any + * comment in this file as evidence that VEIL obfuscation reaches the air. + * + * COMPLIANCE: every control below is a standards-compliant configuration or + * observation action. This daemon never transmits energy to deny a channel; + * it only shapes/observes our own compliant frames. It is NOT a jammer. + * ========================================================================== + * + * Build deps (OpenWRT: libnl-tiny; desktop: libnl-3 + libnl-genl-3): + * pkg-config --cflags --libs libnl-genl-3.0 + * See Makefile (host build-check) and openwrt.mk (package stub). + */ + +#include +#include +#include +#include +#include +#include +#include + +/* Real libnl / nl80211 headers. On OpenWRT these resolve to libnl-tiny; on a + * desktop to libnl-3. If the toolchain lacks them the host Makefile still + * builds the core object so the rotation math is validated in isolation. */ +#include +#include +#include +#include + +#include "veil_shield.h" + +/* ---- Tunables (compliant, conservative defaults) ---------------------- */ +#define VEIL_DEFAULT_PASSES 96u /* matches core default (ADR-290) */ +#define VEIL_CADENCE_JITTER_MIN_MS 20 /* NDP sounding cadence jitter floor */ +#define VEIL_CADENCE_JITTER_MAX_MS 400 /* ... and ceiling (stays in-spec) */ + +/* ---- Daemon context --------------------------------------------------- */ +struct veil_ctx { + struct nl_sock *sock; /* generic-netlink socket to nl80211 */ + int family; /* resolved "nl80211" genl family id */ + int ifindex;/* target AP interface (e.g. phy0-ap0) */ + uint64_t key; /* shared session key for the keyed rotation */ + size_t passes; /* Givens passes */ + volatile sig_atomic_t running; +}; + +static struct veil_ctx g_ctx; + +static void on_signal(int sig) { (void)sig; g_ctx.running = 0; } + +/* ---------------------------------------------------------------------- */ +/* nl80211 bring-up — all REAL libnl-genl-3 API names. */ +/* ---------------------------------------------------------------------- */ +static int veil_nl_connect(struct veil_ctx *c) { + c->sock = nl_socket_alloc(); + if (!c->sock) { + fprintf(stderr, "veil: nl_socket_alloc failed\n"); + return -ENOMEM; + } + if (genl_connect(c->sock)) { + fprintf(stderr, "veil: genl_connect failed\n"); + return -EIO; + } + c->family = genl_ctrl_resolve(c->sock, "nl80211"); + if (c->family < 0) { + fprintf(stderr, "veil: genl_ctrl_resolve(nl80211) failed: %d\n", + c->family); + return c->family; + } + /* Observe MLME events (auth/assoc, and — where the driver forwards them — + * action-frame notifications). Real multicast group name is "mlme". */ + int grp = genl_ctrl_resolve_grp(c->sock, "nl80211", "mlme"); + if (grp >= 0) { + (void)nl_socket_add_membership(c->sock, grp); + } + return 0; +} + +/* ---------------------------------------------------------------------- */ +/* CONTROL 1 (FEASIBLE): TX antenna-map perturbation. */ +/* Rotating the allowed TX antenna bitmap changes the static spatial */ +/* mapping the PHY uses, coarsely perturbing the CSI a sensor observes. */ +/* This is a genuinely userspace-reachable, compliant knob. */ +/* NL80211_CMD_SET_WIPHY + NL80211_ATTR_WIPHY_ANTENNA_TX / _RX */ +/* NOTE: many drivers only accept this while the phy is DOWN, and only on */ +/* symmetric masks — validate per driver. Coarse, not the keyed rotation. */ +/* ---------------------------------------------------------------------- */ +static int veil_set_tx_antenna_mask(struct veil_ctx *c, + uint32_t tx_mask, uint32_t rx_mask) { + struct nl_msg *msg = nlmsg_alloc(); + if (!msg) return -ENOMEM; + genlmsg_put(msg, NL_AUTO_PORT, NL_AUTO_SEQ, c->family, 0, 0, + NL80211_CMD_SET_WIPHY, 0); + /* wiphy is addressed via the interface index on most drivers. */ + NLA_PUT_U32(msg, NL80211_ATTR_IFINDEX, (uint32_t)c->ifindex); + NLA_PUT_U32(msg, NL80211_ATTR_WIPHY_ANTENNA_TX, tx_mask); + NLA_PUT_U32(msg, NL80211_ATTR_WIPHY_ANTENNA_RX, rx_mask); + int ret = nl_send_auto(c->sock, msg); + nlmsg_free(msg); + if (ret < 0) return ret; + return nl_recvmsgs_default(c->sock); /* consume ACK/ERR */ +nla_put_failure: + nlmsg_free(msg); + return -EMSGSIZE; +} + +/* ---------------------------------------------------------------------- */ +/* CONTROL 2 (FEASIBLE, indirect): NDP sounding-cadence randomization. */ +/* mac80211/driver decides when to send NDP Announcement + NDP. There is */ +/* NO stable nl80211 attribute to set the sounding period directly, so the */ +/* compliant lever from userspace is hostapd's advertised sounding */ +/* capability and dimensions, toggled/rewritten over the hostapd ctrl */ +/* interface (RECONFIGURE / SET). We jitter the *offered* cadence. */ +/* */ +/* TODO(hw): there is no nl80211 "set sounding interval" command. Confirm */ +/* against hostapd ctrl_iface docs; the direct per-NDP timer lives in */ +/* driver/firmware. See INTEGRATION.md §2. Cite: */ +/* https://w1.fi/cgit/hostap/tree/hostapd/hostapd.conf */ +/* ---------------------------------------------------------------------- */ +static unsigned veil_next_cadence_ms(struct veil_ctx *c) { + /* Derive jitter deterministically from the session key stream so the + * paired receiver can anticipate the schedule (compliant, not random + * spraying). Reuses the core SplitMix64 for byte-identical behavior. */ + static veil_rng r; + static int seeded = 0; + if (!seeded) { veil_rng_seed(&r, c->key ^ 0xCADE11CEULL); seeded = 1; } + unsigned span = VEIL_CADENCE_JITTER_MAX_MS - VEIL_CADENCE_JITTER_MIN_MS; + return VEIL_CADENCE_JITTER_MIN_MS + + (unsigned)(veil_rng_next_f32(&r) * (float)span); +} + +static int veil_randomize_sounding_cadence(struct veil_ctx *c) { + unsigned ms = veil_next_cadence_ms(c); + /* TODO(hw): push `ms` into the offered sounding cadence. On OpenWRT the + * realistic path is the hostapd ctrl_iface (UNIX socket at + * /var/run/hostapd/): rewrite he/vht sounding-dimension or toggle + * beamformer capability and RECONFIGURE. mac80211 has no direct knob. + * This function currently only computes the schedule. */ + fprintf(stderr, "veil: [feasible/indirect] next sounding jitter = %u ms " + "(TODO(hw): apply via hostapd ctrl_iface)\n", ms); + return 0; +} + +/* ---------------------------------------------------------------------- */ +/* CONTROL 3 (MOSTLY BLOB-BLOCKED): MU-MIMO group shuffling. */ +/* The MU group definition + steering matrices are computed and applied in */ +/* the WiFi MCU firmware on mt76 (mt7915) and all ath1x parts. There is no */ +/* generic nl80211 command to reshuffle MU groups. Only a vendor subcmd */ +/* (NL80211_CMD_VENDOR) on a driver that chose to expose one could do it. */ +/* ---------------------------------------------------------------------- */ +static int veil_shuffle_mumimo_groups(struct veil_ctx *c) { + (void)c; + /* TODO(hw): requires NL80211_CMD_VENDOR + a driver-specific + * NL80211_ATTR_VENDOR_ID / _SUBCMD / _DATA that does not exist upstream + * for mt76/ath. Without a driver+firmware patch this is unreachable. + * See INTEGRATION.md §3. Left as an explicit no-op, not a fake success. */ + fprintf(stderr, "veil: [blob-blocked] MU-MIMO group shuffle needs a " + "vendor subcmd / firmware patch (TODO(hw))\n"); + return -ENOTSUP; +} + +/* ---------------------------------------------------------------------- */ +/* CONTROL 4 (BLOB-BLOCKED on commodity AP silicon): the keyed rotation. */ +/* This is the actual VEIL transform — a keyed Givens rotation on the fine */ +/* subspace of the compressed beamforming feedback (the phi/psi angles), */ +/* or equivalently a unitary Q on the LTF spatial mapping. On mt76/ath the */ +/* feedback report is generated and the precoder applied inside firmware, */ +/* so userspace cannot edit it. This function shows WHERE the core plugs */ +/* in for the platforms that CAN reach the buffer (openwifi FPGA datapath, */ +/* Nexmon Broadcom patch) — it operates on a caller-supplied fine block. */ +/* ---------------------------------------------------------------------- */ +static int veil_apply_keyed_rotation(struct veil_ctx *c, + float *fine, size_t n) { + if (!fine || n < 2) return -EINVAL; + /* Pure, orthogonal, energy-preserving (the "not jamming" invariant). */ + float before = veil_l2_norm(fine, n); + veil_shield_apply(fine, n, c->key, c->passes); + float after = veil_l2_norm(fine, n); + /* TODO(hw): on OpenWRT there is NO userspace/mac80211 hook that hands us + * this buffer before TX. Reaching it requires a driver+firmware patch + * (mt76 MCU / ath) to expose the pre-precoder V/steering matrix, OR use + * the openwifi (FPGA) or Nexmon adapters. See INTEGRATION.md §4. + * We only prove the math is invariant here; nothing goes on air. */ + fprintf(stderr, "veil: [blob-blocked path] rotated %zu coeffs, " + "L2 %.6f -> %.6f (delta %.2e; must be ~0)\n", + n, before, after, (double)(after - before)); + return 0; +} + +/* ---------------------------------------------------------------------- */ +/* Event loop: watch for sensing-solicitation cadence. */ +/* We register interest in MLME/frame events. On commodity drivers the raw */ +/* NDP Announcement is NOT forwarded to userspace, so honest detection of */ +/* an *external* sensing solicitation needs monitor-mode capture or a */ +/* driver notification that does not exist upstream — marked TODO(hw). */ +/* ---------------------------------------------------------------------- */ +static int veil_event_cb(struct nl_msg *msg, void *arg) { + struct veil_ctx *c = (struct veil_ctx *)arg; + struct genlmsghdr *gnlh = nlmsg_data(nlmsg_hdr(msg)); + switch (gnlh->cmd) { + case NL80211_CMD_FRAME: + /* TODO(hw): parse NL80211_ATTR_FRAME; classify VHT/HE compressed + * beamforming action (category 21/30) or NDPA to measure solicitation + * cadence. Requires the driver to forward these frames (registered via + * NL80211_CMD_REGISTER_FRAME / monitor). Not guaranteed upstream. */ + (void)veil_randomize_sounding_cadence(c); + break; + case NL80211_CMD_NEW_STATION: + case NL80211_CMD_DEL_STATION: + /* Membership churn changes MU grouping surface. */ + (void)veil_shuffle_mumimo_groups(c); + break; + default: + break; + } + return NL_SKIP; +} + +static void usage(const char *p) { + fprintf(stderr, + "Usage: %s -i [-k ] [-p ]\n" + " BUILD-ONLY / UNTESTED-ON-HARDWARE. See README.md.\n", p); +} + +int main(int argc, char **argv) { + memset(&g_ctx, 0, sizeof(g_ctx)); + g_ctx.key = 0xA5A5A5A5A5A5A5A5ULL; /* placeholder; real key from keystore */ + g_ctx.passes = VEIL_DEFAULT_PASSES; + g_ctx.ifindex = -1; + g_ctx.running = 1; + + int opt; + while ((opt = getopt(argc, argv, "i:k:p:h")) != -1) { + switch (opt) { + case 'i': g_ctx.ifindex = atoi(optarg); break; + case 'k': g_ctx.key = strtoull(optarg, NULL, 16); break; + case 'p': g_ctx.passes = (size_t)strtoul(optarg, NULL, 10); break; + case 'h': default: usage(argv[0]); return (opt == 'h') ? 0 : 2; + } + } + if (g_ctx.ifindex < 0) { usage(argv[0]); return 2; } + + fprintf(stderr, "veil_shieldd: SYNTHETIC/L0 build-only scaffold — " + "no RF is emitted, nothing is validated on silicon.\n"); + + signal(SIGINT, on_signal); + signal(SIGTERM, on_signal); + + if (veil_nl_connect(&g_ctx)) return 1; + + /* Install the event callback (valid-message path). */ + nl_socket_modify_cb(g_ctx.sock, NL_CB_VALID, NL_CB_CUSTOM, + veil_event_cb, &g_ctx); + nl_socket_disable_seq_check(g_ctx.sock); /* required for multicast events */ + + /* Self-check the one genuinely feasible active control at startup. Comment + * this out on a live AP; it may bounce the radio depending on the driver. + * (void)veil_set_tx_antenna_mask(&g_ctx, 0x3, 0x3); */ + (void)veil_set_tx_antenna_mask; + + /* Prove the linked core is byte-consistent (no radio involved). */ + { + float demo[8] = {1,0,0,0,0,0,0,0}; + (void)veil_apply_keyed_rotation(&g_ctx, demo, 8); + veil_shield_recover(demo, 8, g_ctx.key, g_ctx.passes); + fprintf(stderr, "veil: recover round-trip demo[0]=%.6f (expect ~1.0)\n", + (double)demo[0]); + } + + while (g_ctx.running) { + int r = nl_recvmsgs_default(g_ctx.sock); + if (r < 0 && r != -NLE_AGAIN) { + fprintf(stderr, "veil: nl_recvmsgs_default: %d\n", r); + break; + } + } + + nl_socket_free(g_ctx.sock); + return 0; +} diff --git a/harness/wifi-densepose-privshield/.claude-plugin/plugin.json b/harness/wifi-densepose-privshield/.claude-plugin/plugin.json new file mode 100644 index 00000000..8b6d1277 --- /dev/null +++ b/harness/wifi-densepose-privshield/.claude-plugin/plugin.json @@ -0,0 +1,25 @@ +{ + "name": "wifi-densepose-privshield-harness", + "version": "0.1.0", + "description": "Harness for wifi-densepose-privshield (WiFi Veil privacy shield)", + "author": { + "displayName": "Generated by metaharness", + "url": "https://www.npmjs.com/package/metaharness" + }, + "license": "MIT", + "categories": [ + "agent-harness", + "metaharness-scaffold", + "Engineering", + "software-engineering" + ], + "tags": [ + "metaharness", + "agent-harness", + "vertical:coding", + "software-engineering", + "wifi-sensing", + "privacy" + ], + "homepage": "https://github.com/ruvnet/agent-harness-generator" +} diff --git a/harness/wifi-densepose-privshield/.claude/settings.json b/harness/wifi-densepose-privshield/.claude/settings.json new file mode 100644 index 00000000..34e12774 --- /dev/null +++ b/harness/wifi-densepose-privshield/.claude/settings.json @@ -0,0 +1,21 @@ +{ + "permissions": { + "allow": [ + "Bash(npx wifi-densepose-privshield-harness*)", + "mcp__wifi-densepose-privshield-harness__*", + "Bash(npm test*)", + "Bash(npm run*)", + "Bash(cargo test -p wifi-densepose-privshield*)", + "Bash(cargo clippy -p wifi-densepose-privshield*)", + "Bash(git diff*)", + "Bash(git status*)", + "Bash(git log*)" + ], + "deny": [ + "Read(./.env)", + "Read(./.env.*)", + "Bash(git push*)", + "Bash(rm -rf*)" + ] + } +} diff --git a/harness/wifi-densepose-privshield/.gitignore b/harness/wifi-densepose-privshield/.gitignore new file mode 100644 index 00000000..f4e2c6d6 --- /dev/null +++ b/harness/wifi-densepose-privshield/.gitignore @@ -0,0 +1,3 @@ +node_modules/ +dist/ +*.tsbuildinfo diff --git a/harness/wifi-densepose-privshield/.harness/manifest.json b/harness/wifi-densepose-privshield/.harness/manifest.json new file mode 100644 index 00000000..44b9e1d0 --- /dev/null +++ b/harness/wifi-densepose-privshield/.harness/manifest.json @@ -0,0 +1,32 @@ +{ + "schema": 1, + "generator": "0.1.0", + "template": "vertical:coding", + "template_version": "0.0.0", + "vars": { + "name": "wifi-densepose-privshield-harness", + "description": "Harness for wifi-densepose-privshield (WiFi Veil privacy shield)", + "host": "claude-code" + }, + "hosts": ["claude-code"], + "files": { + ".claude/settings.json": "fedb60921a0e3c78848f43edddd75f448819594c680d48ff2033ef8f1588da3f", + ".claude-plugin/plugin.json": "8b155a3130d212c88dd8b631d9bd6dd1b4eacb52e5eb282fddbe08576ae23be2", + "bin/cli.js": "1133e7a47accada1c9b2184873776d8ca0d028f9b76dd55f467dfe38bb9ce609", + "CLAUDE.md": "f9ccf20c341ff0296b2e64ce692103572d61e856ae0df8a8bc4c35a7ac8b2ff5", + "package.json": "1ccedf0e62b0ed884431a2a9192a3865b525a2dad72fa6491569b9001e7dd24f", + "README.md": "688e207f95e4f58eeade84f149c38fa8ec048796556a7b1bd75f08ee1945edba", + "src/init.ts": "f05d6905d8681f45f610ff5b6e9d425dfa66183acdfe7857248e50e3583e13b8", + "src/router.ts": "4545b42d1423db21bcfe6ab6bf132b805ba383937d142997cb7256e835c245e4", + "src/flywheel.ts": "aab56d82c4f018ddc83923c877a66acdf9c624214307d0a9c4bf930ddb00599a", + "tsconfig.json": "8b4e730a1aa39162ac574455d7a98e1881f5313ca80ffe503b9652dcf0c76b9d", + "vitest.config.ts": "021b33ec623593effc3d163020479a91a1179329ee4ed1cb25f2dd9388e19820", + "__tests__/smoke.test.ts": "8c5a2acc3a956ea48e60c996c9034224684f6f4110cb3c5885741ff8d18bb82d", + "__tests__/router.test.ts": "97c29fc0ff718692ec97a9cd81f92e65ebde996fe1a3d8d2182e66598a583fad", + "__tests__/flywheel.test.ts": "87b149f7d68b4cf72fe3dcf6c76e4307b280e9f4ab6e6b1f7ee6689340faf5fb", + "__tests__/guidance.test.ts": "66b68615d27671d91b9efcf1eee5f2c7a53b0db7f475cc4ddb17ba8b6ddbff7f", + "LICENSE": "07b1a7c2aa25991872e3594de2ecb64ff6b4c5d3dc2376dd5b9e9f77c4b258e8" + }, + "generated_at": "2026-08-09T00:00:00.000Z", + "meta": { "surface": "cli" } +} diff --git a/harness/wifi-densepose-privshield/.harness/manifest.sha256 b/harness/wifi-densepose-privshield/.harness/manifest.sha256 new file mode 100644 index 00000000..2674b6e7 --- /dev/null +++ b/harness/wifi-densepose-privshield/.harness/manifest.sha256 @@ -0,0 +1 @@ +da48afb45d776c10f1841331facf65aa7ba4802f990a2480b91227fc100d4a47 diff --git a/harness/wifi-densepose-privshield/CLAUDE.md b/harness/wifi-densepose-privshield/CLAUDE.md new file mode 100644 index 00000000..5728e33c --- /dev/null +++ b/harness/wifi-densepose-privshield/CLAUDE.md @@ -0,0 +1,67 @@ +# wifi-densepose-privshield-harness + +Harness for [`wifi-densepose-privshield`](../../v2/crates/wifi-densepose-privshield) +(WiFi Veil — the compliant-waveform WiFi-sensing privacy shield, ADR-288). This +package is defined by ADR-289. + +> Advanced Coding harness · domain: `software-engineering`. Modeled on the +> `wifi-densepose-sar-harness` scaffold (ADR-286), generated with +> [create-agent-harness](https://github.com/ruvnet/agent-harness-generator). + +## Behavioral rules + +- Use the harness's tools for orchestration; memory and routing are handled by + the kernel. +- Defer destructive operations to the user. +- **Never present WiFi sensing as camera-grade, and never relabel WiFi Veil's + SYNTHETIC/L0 results as MEASURED** — a hardware witness is required first + (CLAUDE.md hardware rule; ADR-282 ladder). The harness is a development aid; + it does not run a radio and cannot emit RF. +- WiFi Veil uses compliant waveform controls only — **never jamming.** Do not add, + suggest, or scaffold interference-based "defenses." + +## Commands + +- `init` — boot the kernel + host adapter. +- `doctor` — verify the install end-to-end (kernel, host, guidance map). +- `guidance --topic [--query ]` — read-only WiFi Veil capability map + (dependency-free; topics: `overview`, `threat`, `countermeasure`, + `compliance`, `optimization`, `experiment`). Source-cited and + evidence-labelled; navigation only, not authority. +- `route ` — cost-optimal model routing via + `@metaharness/router` (needs `npm run build`). +- `flywheel [generations]` — SYNTHETIC self-improvement demo via + `@metaharness/flywheel` (needs `npm run build`). + +## Architecture + +Uses [@metaharness/kernel](https://www.npmjs.com/package/@metaharness/kernel) +(Rust-compiled WASM with a NAPI-RS native fallback) so the same code runs on +every platform. The `@metaharness/*` packages are imported *dynamically* inside +the commands that need them, so `guidance`/`--help` work with no dependencies +installed. + +### Darwin, router, flywheel + +- **Darwin Mode** (`@metaharness/darwin`, devDependency) — `npm run evolve` / + `evolve:dry` mutates the harness's own config and keeps only measurable + improvements. +- **Router** (`@metaharness/router`) — `src/router.ts` wires a real cost-optimal + `Router` (`qualityBar: 0.8`) over two model tiers. Its labelled examples are + illustrative seed data (see the file's honesty note), not measured eval-log + observations. +- **Flywheel** (`@metaharness/flywheel`) — `src/flywheel.ts` wires the real + promotion loop (propose → evaluate → gate → promote, Ed25519-signed, + independently replayable) with a SYNTHETIC proposer/evaluator + (`dataSource: 'SYNTHETIC'`, no model call). A LIVE run needs a real Proposer + and Evaluator supplied by the operator — see the file's comments. + +## Relationship to the crate + +This harness assists development *on* the WiFi Veil crate; it does not replace the +crate's own gates. The authoritative validation for a WiFi Veil change is still: + +```bash +cargo test -p wifi-densepose-privshield --no-default-features +cargo clippy -p wifi-densepose-privshield --all-targets -- -D warnings +``` diff --git a/harness/wifi-densepose-privshield/LICENSE b/harness/wifi-densepose-privshield/LICENSE new file mode 100644 index 00000000..c77a3a09 --- /dev/null +++ b/harness/wifi-densepose-privshield/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 wifi-densepose-privshield-harness authors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/harness/wifi-densepose-privshield/README.md b/harness/wifi-densepose-privshield/README.md new file mode 100644 index 00000000..bd13ed80 --- /dev/null +++ b/harness/wifi-densepose-privshield/README.md @@ -0,0 +1,68 @@ +# wifi-densepose-privshield-harness + +A metaharness (contributor harness) for +[`wifi-densepose-privshield`](../../v2/crates/wifi-densepose-privshield) — **WiFi Veil**, +the compliant-waveform WiFi-sensing privacy shield (ADR-288). Defined by ADR-289. + +> **Advanced Coding** — architect → implement → review → test, plus a +> dependency-free WiFi Veil guidance surface. Modeled on `wifi-densepose-sar-harness` +> (ADR-286). Multi-host scaffold with a kernel that resolves native → wasm → js. + +## Install + +```bash +npm install -g wifi-densepose-privshield-harness +wifi-densepose-privshield-harness doctor +``` + +Or run without installing: + +```bash +npx wifi-densepose-privshield-harness guidance --topic overview +``` + +## Commands + +| Command | Deps needed | Purpose | +|---|---|---| +| `init` | kernel + host | Boot the kernel + host adapter | +| `doctor` | kernel + host | Verify the install end-to-end | +| `guidance --topic ` | **none** | Read-only WiFi Veil capability map (source-cited, evidence-labelled) | +| `route ` | router + `npm run build` | Cost-optimal model routing | +| `flywheel [gens]` | flywheel + `npm run build` | SYNTHETIC self-improvement demo | + +`guidance` topics: `overview`, `threat`, `countermeasure`, `compliance`, +`optimization`, `experiment`. It needs no dependencies or build step, so it +works offline and in CI before `npm install`. + +## What WiFi Veil is + +WiFi Veil shapes a node's **own** beamforming feedback with keyed Givens rotations so +a third-party passive sniffer cannot re-identify people, while a keyed receiver +sees an essentially unchanged link. **Compliant waveform controls only — never +jamming.** Reference results are **SYNTHETIC / evidence level L0** (reproduced by +`cargo test`), never MEASURED until a hardware witness exists. See the crate's +[ADR-288](../../docs/adr/ADR-288-veil-privacy-shield-compliant-waveform.md) and +[research bundle](../../docs/research/privacy-shield/). + +## Darwin, router, flywheel + +- `npm run evolve` / `evolve:dry` — Darwin Mode self-mutation of the harness + config (`@metaharness/darwin`). +- `npm run route -- ` (after `npm run build`) — cost-optimal + model routing (`@metaharness/router`). +- `npm run flywheel:dry` — the SYNTHETIC `@metaharness/flywheel` demo + (propose → evaluate → gate → promote, signed + independently replayable). + +See `CLAUDE.md` and the honesty notes atop `src/router.ts` / `src/flywheel.ts` +for what is real wiring vs. illustrative/synthetic data. + +## Scope + +The harness is a **development aid**. It does not run a WiFi Veil radio, does not +emit RF, and cannot jam. It does not replace the crate's own gates — the +authoritative check for a WiFi Veil change is `cargo test -p wifi-densepose-privshield`. + +## License + +MIT diff --git a/harness/wifi-densepose-privshield/__tests__/flywheel.test.ts b/harness/wifi-densepose-privshield/__tests__/flywheel.test.ts new file mode 100644 index 00000000..0577f8a9 --- /dev/null +++ b/harness/wifi-densepose-privshield/__tests__/flywheel.test.ts @@ -0,0 +1,26 @@ +// SPDX-License-Identifier: MIT +// Verifies the SYNTHETIC flywheel demo wires end-to-end: a non-empty lift curve +// and a replay bundle that verifies independently. Does NOT assert any real +// self-improvement — the proposer/evaluator are deterministic stand-ins. + +import { describe, it, expect } from 'vitest'; +import { runVeilFlywheelDemo, verifyVeilFlywheelDemo } from '../src/flywheel.js'; + +describe('wifi-densepose-privshield-harness — flywheel (SYNTHETIC)', () => { + it('produces a non-empty lift curve', async () => { + const result = await runVeilFlywheelDemo(3); + expect(result.liftCurve.length).toBeGreaterThan(0); + expect(result.generationsRun).toBeGreaterThan(0); + }); + + it('produces an independently verifiable replay bundle', async () => { + const result = await runVeilFlywheelDemo(3); + const verdict = verifyVeilFlywheelDemo(result); + expect(verdict.pass).toBe(true); + }); + + it('stamps the run as SYNTHETIC provenance', async () => { + const result = await runVeilFlywheelDemo(2); + expect(result.replayBundle.data_source).toBe('SYNTHETIC'); + }); +}); diff --git a/harness/wifi-densepose-privshield/__tests__/guidance.test.ts b/harness/wifi-densepose-privshield/__tests__/guidance.test.ts new file mode 100644 index 00000000..99dab6cf --- /dev/null +++ b/harness/wifi-densepose-privshield/__tests__/guidance.test.ts @@ -0,0 +1,34 @@ +// SPDX-License-Identifier: MIT +// The VEIL guidance map is dependency-free (no @metaharness/* import), so this +// test runs even before `npm install` resolves the kernel. It guards the +// read-only capability map the MCP/CLI `guidance` surface exposes. + +import { describe, it, expect } from 'vitest'; +import { run, guidanceReport } from '../bin/cli.js'; + +describe('wifi-densepose-privshield-harness — guidance', () => { + it('returns a source-cited report for a known topic', () => { + const r = guidanceReport('optimization'); + expect(r.ok).toBe(true); + expect(r.summary.length).toBeGreaterThan(0); + expect(r.sources.some((s: string) => s.includes('optimize.rs'))).toBe(true); + expect(r.authority).toContain('read-only'); + }); + + it('labels evidence as SYNTHETIC/L0', () => { + const r = guidanceReport('experiment'); + expect(r.evidence).toContain('SYNTHETIC'); + }); + + it('rejects an unknown topic and lists the valid ones', () => { + const r = guidanceReport('not-a-topic'); + expect(r.ok).toBe(false); + expect(r.topics).toContain('overview'); + expect(r.topics).toContain('compliance'); + }); + + it('CLI `guidance --topic overview` exits 0; unknown topic exits non-zero', async () => { + expect(await run(['guidance', '--topic', 'overview'])).toBe(0); + expect(await run(['guidance', '--topic', 'nope'])).not.toBe(0); + }); +}); diff --git a/harness/wifi-densepose-privshield/__tests__/router.test.ts b/harness/wifi-densepose-privshield/__tests__/router.test.ts new file mode 100644 index 00000000..4d378ddd --- /dev/null +++ b/harness/wifi-densepose-privshield/__tests__/router.test.ts @@ -0,0 +1,24 @@ +// SPDX-License-Identifier: MIT +// Verifies the cost-optimal router mechanism (not its illustrative data): cheap +// query shapes route to the cheap tier; hard shapes escalate to the frontier. + +import { describe, it, expect } from 'vitest'; +import { routeVeilQuery } from '../src/router.js'; + +describe('wifi-densepose-privshield-harness — router', () => { + it('routes a threat-model query (cheap-tier-capable) to the cheap tier', () => { + const pick = routeVeilQuery([1, 0, 0, 0]); + expect(pick.id).toBe('cheap-tier'); + expect(pick.metBar).toBe(true); + }); + + it('escalates a compliance-review query to the frontier tier', () => { + const pick = routeVeilQuery([0, 1, 0, 0]); + expect(pick.id).toBe('frontier-tier'); + }); + + it('escalates an optimizer-tuning query to the frontier tier', () => { + const pick = routeVeilQuery([0, 0, 1, 0]); + expect(pick.id).toBe('frontier-tier'); + }); +}); diff --git a/harness/wifi-densepose-privshield/__tests__/smoke.test.ts b/harness/wifi-densepose-privshield/__tests__/smoke.test.ts new file mode 100644 index 00000000..75605913 --- /dev/null +++ b/harness/wifi-densepose-privshield/__tests__/smoke.test.ts @@ -0,0 +1,35 @@ +// SPDX-License-Identifier: MIT +// A real smoke test for wifi-densepose-privshield-harness: it boots the actual +// kernel + host adapter the harness depends on, so `npm test` fails loudly if +// @metaharness/kernel or @metaharness/host-claude-code is missing, broken, or +// version-skewed. Fastest signal that `npm install` produced a runnable harness. + +import { describe, it, expect } from 'vitest'; +import { loadKernel } from '@metaharness/kernel'; +import adapter from '@metaharness/host-claude-code'; +import { run } from '../bin/cli.js'; + +describe('wifi-densepose-privshield-harness — install smoke test', () => { + it('loads the kernel and reports a version + a known backend', async () => { + const kernel = await loadKernel(); + const info = kernel.kernelInfo(); + expect(typeof info.version).toBe('string'); + expect(info.version.length).toBeGreaterThan(0); + expect(['native', 'wasm', 'js']).toContain(kernel.backend); + }); + + it('resolves the host adapter with a name', () => { + expect(typeof adapter.name).toBe('string'); + expect(adapter.name.length).toBeGreaterThan(0); + }); + + it('the CLI doctor command succeeds (exit 0)', async () => { + const code = await run(['doctor']); + expect(code).toBe(0); + }); + + it('an unknown CLI command exits non-zero', async () => { + const code = await run(['definitely-not-a-command']); + expect(code).not.toBe(0); + }); +}); diff --git a/harness/wifi-densepose-privshield/bin/cli.js b/harness/wifi-densepose-privshield/bin/cli.js new file mode 100644 index 00000000..561174e6 --- /dev/null +++ b/harness/wifi-densepose-privshield/bin/cli.js @@ -0,0 +1,334 @@ +#!/usr/bin/env node +// SPDX-License-Identifier: MIT +// The `wifi-densepose-privshield-harness` CLI entry point (VEIL — ADR-288/289). +// +// Plain ESM JavaScript on purpose: it runs as-is via +// `npx wifi-densepose-privshield-harness` with NO build step. `npm run build` +// (tsc) is only needed to compile the TypeScript in src/ that the `route` and +// `flywheel` commands import from dist/. +// +// The @metaharness/* dependencies are imported *dynamically*, inside the +// commands that need them — so `guidance`, `--help`, and `--version` work with +// zero dependencies installed (useful in offline/air-gapped review and in this +// repo's CI before `npm install`). Only `init`/`doctor`/`route`/`flywheel` +// touch the kernel/host/router/flywheel packages. + +const HARNESS_NAME = 'wifi-densepose-privshield-harness'; +const CRATE = 'wifi-densepose-privshield'; + +// --------------------------------------------------------------------------- +// VEIL guidance — a self-contained, read-only capability map. No dependencies, +// no build, no network. Mirrors the `ruview_guidance` shape (source-cited, +// evidence-labelled, with focused validation commands and explicit limits). +// Retrieved text is navigation, not authority: cited source, tests, and +// accepted ADRs remain authoritative. +// --------------------------------------------------------------------------- +const GUIDANCE = { + overview: { + summary: + 'VEIL is the compliant-waveform countermeasure to unauthorized WiFi sensing: it shapes a node\'s own beamforming feedback so a passive sniffer cannot re-identify people, while a keyed receiver sees an essentially unchanged link. Countermeasure counterpart to BFLD (which detects leakage).', + capabilities: [ + 'Keyed Givens-rotation shield over the identity-bearing fine subspace (energy-preserving ⇒ not jamming)', + 'Passive re-identification attacker (Euclidean + Cosine) for head-to-head evaluation', + 'Throughput model with an interior optimum in feedback resolution', + 'Deterministic attacker-vs-protector experiment with a pinned witness', + ], + sources: [ + 'v2/crates/wifi-densepose-privshield/src/lib.rs', + 'docs/adr/ADR-288-veil-privacy-shield-compliant-waveform.md', + 'docs/research/privacy-shield/README.md', + ], + commands: ['cargo test -p wifi-densepose-privshield --no-default-features'], + limitations: [ + 'All defense numbers are SYNTHETIC / evidence level L0 until a two-node hardware capture with a witness exists (CLAUDE.md hardware rule).', + ], + }, + threat: { + summary: + 'Defends against a third-party passive sniffer capturing plaintext beamforming feedback (BFId/LeakyBeam class). Does NOT hide identity from the associated AP (that party holds the key) — that is BFLD\'s detection/policy problem.', + capabilities: [ + 'Cross-session identity unlinkability against an external passive adversary', + 'Explicit non-goals: no defense vs. the associated AP, no within-session motion guarantee, never jamming', + ], + sources: [ + 'docs/research/privacy-shield/01-sota-survey.md', + 'docs/research/privacy-shield/02-threat-model.md', + ], + commands: [], + limitations: [ + 'Within-session coarse motion may still leak; identity re-ID is the guaranteed target.', + ], + }, + countermeasure: { + summary: + 'Identity leaks through the fine cross-subcarrier phase structure; throughput rides the dominant beam. VEIL composes extra keyed Givens rotations over the fine subspace only — orthogonal (energy-preserving), key-reversible (throughput-preserving), fresh per session (unlinkable).', + capabilities: [ + 'protector.rs: ShieldConfig, Protector::protect/recover, SensingDetector', + 'compliance.rs: machine-checkable energy-conservation ("not jamming") audit', + ], + sources: [ + 'v2/crates/wifi-densepose-privshield/src/protector.rs', + 'v2/crates/wifi-densepose-privshield/src/compliance.rs', + 'docs/research/privacy-shield/03-countermeasure-design.md', + ], + commands: ['cargo test -p wifi-densepose-privshield protector'], + limitations: [ + 'The two-subspace separability is a model abstraction; real hardware is only approximately separable.', + ], + }, + compliance: { + summary: + 'Compliant waveform controls only, never jamming. The keyed rotation is orthogonal, so it preserves the report energy exactly (ratio ≈ 1.0) — it adds no interfering emission. Jamming (47 U.S.C. §333/§302a) is defined by interfering with OTHERS\' transmissions, not shaping your own.', + capabilities: [ + 'ComplianceReport::audit / is_compliant — energy ratio + non-interference verdict', + ], + sources: [ + 'v2/crates/wifi-densepose-privshield/src/compliance.rs', + 'docs/research/privacy-shield/04-compliance-and-regulatory.md', + ], + commands: ['cargo test -p wifi-densepose-privshield compliance'], + limitations: [ + 'Engineering analysis, not legal advice; RF power/mask/timing limits are jurisdiction-specific.', + ], + }, + optimization: { + summary: + 'The shipped shield config is derived, not hand-picked: 96 Givens passes (2× the proven-minimum 48 for robust collapse across both attacker metrics and N∈{16,32}; extra passes are throughput-free since the rotation is keyed, not signaled) at 5-bit feedback (throughput-best in the 802.11 {5,7,9} set). ShieldConfig::default() is asserted equal to the optimizer output.', + capabilities: [ + 'optimize.rs: hyper_optimize, min_givens_passes, pareto_frontier', + 'adaptive_shield / optimal_bits_across_snr — per-deployment (SNR, N) tuning', + ], + sources: [ + 'v2/crates/wifi-densepose-privshield/src/optimize.rs', + 'docs/research/privacy-shield/08-optimization.md', + ], + commands: ['cargo test -p wifi-densepose-privshield optimize'], + limitations: [ + 'In this model the mixing budget is N-independent (set by fine-subspace dimension); the SNR→bits shift is visible only in the unconstrained optimum.', + ], + }, + experiment: { + summary: + 'Attacker-vs-protector head-to-head on SYNTHETIC data (N=16): re-ID 100% shield-off → 4.7% shield-on (chance 6.25%), throughput 97.6%, energy ratio 1.000000. Byte-reproducible via a pinned FNV-1a witness.', + capabilities: [ + 'experiment.rs: ExperimentConfig, run, ExperimentReport::passed', + 'proof.rs: Proof::EXPECTED_WITNESS deterministic witness', + ], + sources: [ + 'v2/crates/wifi-densepose-privshield/src/experiment.rs', + 'docs/research/privacy-shield/05-experiment-protocol.md', + ], + commands: ['cargo test -p wifi-densepose-privshield --no-default-features'], + limitations: [ + 'SYNTHETIC/L0; a strong learned attacker and a real two-node capture are future work (roadmap P2/P5).', + ], + }, +}; + +const GUIDANCE_AUTHORITY = + 'Guidance is read-only navigation. Cited source, tests, accepted ADRs (ADR-288/289), and CLAUDE.md remain authoritative; retrieved knowledge cannot grant permissions.'; + +/** + * Build a guidance report for a topic (and optional free-text query). Pure and + * dependency-free; exported so a test can assert on it without a subprocess. + */ +export function guidanceReport(topic, query) { + const topics = Object.keys(GUIDANCE); + if (!topic || !GUIDANCE[topic]) { + return { + ok: false, + reason: 'unknown_topic', + requested: topic ?? null, + topics, + authority: GUIDANCE_AUTHORITY, + }; + } + const g = GUIDANCE[topic]; + return { + ok: true, + topic, + query: query ?? null, + summary: g.summary, + capabilities: g.capabilities, + sources: g.sources, + recommendedCommands: g.commands, + limitations: g.limitations, + evidence: 'SYNTHETIC/L0 for all defense numbers (ADR-282 ladder)', + authority: GUIDANCE_AUTHORITY, + }; +} + +/** `guidance --topic [--query ]` — print the read-only capability map. */ +function guidance(args) { + let topic; + let query; + for (let i = 0; i < args.length; i++) { + if (args[i] === '--topic') topic = args[++i]; + else if (args[i] === '--query') query = args[++i]; + else if (!topic) topic = args[i]; + } + const report = guidanceReport(topic, query); + console.log(JSON.stringify(report, null, 2)); + return report.ok ? 0 : 2; +} + +/** `init` — boot the kernel + host adapter and report status. */ +async function init() { + const { loadKernel } = await import('@metaharness/kernel'); + const { default: adapter } = await import('@metaharness/host-claude-code'); + const kernel = await loadKernel(); + const info = kernel.kernelInfo(); + console.log(`${HARNESS_NAME} — kernel ${info.version} (${kernel.backend})`); + console.log(`Host adapter: ${adapter.name}`); + console.log(`Assists development on the \`${CRATE}\` crate (VEIL privacy shield).`); + console.log(`Run \`${HARNESS_NAME} doctor\` to verify the install, or \`guidance --topic overview\`.`); + return 0; +} + +/** `doctor` — verify the install end-to-end (kernel + host resolve). */ +async function doctor() { + const { loadKernel } = await import('@metaharness/kernel'); + const { default: adapter } = await import('@metaharness/host-claude-code'); + const kernel = await loadKernel(); + const info = kernel.kernelInfo(); + const checks = [ + ['kernel loads', !!kernel], + ['kernel reports a version', typeof info.version === 'string' && info.version.length > 0], + ['kernel backend is native|wasm|js', ['native', 'wasm', 'js'].includes(kernel.backend)], + ['host adapter has a name', typeof adapter?.name === 'string' && adapter.name.length > 0], + ['guidance map resolves', guidanceReport('overview').ok === true], + ]; + let ok = true; + for (const [label, pass] of checks) { + console.log(`${pass ? 'PASS' : 'FAIL'} ${label}`); + if (!pass) ok = false; + } + console.log( + ok + ? `\n${HARNESS_NAME}: all checks passed (kernel ${info.version}, ${kernel.backend} backend, host ${adapter.name})` + : `\n${HARNESS_NAME}: doctor found problems`, + ); + return ok ? 0 : 1; +} + +/** + * `route ` — route a 4-axis task embedding to the + * cost-optimal model tier via @metaharness/router. Needs `npm run build`. + */ +async function route(args) { + const embedding = args.map(Number); + if (embedding.length !== 4 || embedding.some((n) => Number.isNaN(n))) { + console.error( + `Usage: ${HARNESS_NAME} route (four 0..1 numbers)`, + ); + return 2; + } + let routeVeilQuery; + try { + ({ routeVeilQuery } = await import('../dist/router.js')); + } catch (err) { + console.error(`route: dist/router.js not found — run \`npm run build\` first. (${err.message})`); + return 1; + } + const pick = routeVeilQuery(embedding); + console.log( + `route -> ${pick.id} (predicted quality ${pick.predictedQuality.toFixed(3)}, $${pick.costPerMTok}/MTok, met bar: ${pick.metBar})`, + ); + return 0; +} + +/** + * `flywheel [generations]` — run the SYNTHETIC @metaharness/flywheel demo and + * print the lift curve + an independent replay-bundle verification. Needs + * `npm run build`. + */ +async function flywheel(args) { + const generations = args[0] ? Number(args[0]) : 3; + if (Number.isNaN(generations) || generations < 1) { + console.error(`Usage: ${HARNESS_NAME} flywheel [generations>=1]`); + return 2; + } + let runVeilFlywheelDemo, verifyVeilFlywheelDemo; + try { + ({ runVeilFlywheelDemo, verifyVeilFlywheelDemo } = await import('../dist/flywheel.js')); + } catch (err) { + console.error(`flywheel: dist/flywheel.js not found — run \`npm run build\` first. (${err.message})`); + return 1; + } + console.log(`Running ${generations}-generation flywheel demo (dataSource: SYNTHETIC — see src/flywheel.ts)...`); + const result = await runVeilFlywheelDemo(generations); + for (const point of result.liftCurve) { + console.log(` gen ${point.generation}: primary=${point.primary.toFixed(3)} delta=${point.delta.toFixed(3)} anchor=${point.anchor ?? 'n/a'}`); + } + const verdict = verifyVeilFlywheelDemo(result); + console.log(`generations run: ${result.generationsRun} · promotions: ${result.promotions.length} · replay verified: ${verdict.pass}`); + return verdict.pass ? 0 : 1; +} + +/** + * Dispatch one CLI invocation. Exported (not just run on import) so a test can + * drive it without spawning a subprocess. Returns the intended exit code. + */ +export async function run(argv) { + const cmd = argv[0] ?? 'init'; + switch (cmd) { + case 'init': + return init(); + case 'doctor': + return doctor(); + case 'guidance': + return guidance(argv.slice(1)); + case 'route': + return route(argv.slice(1)); + case 'flywheel': + return flywheel(argv.slice(1)); + case '--version': + case '-v': { + const { loadKernel } = await import('@metaharness/kernel'); + const kernel = await loadKernel(); + console.log(kernel.version()); + return 0; + } + case '--help': + case '-h': + console.log( + `Usage: ${HARNESS_NAME} \n\n` + + ` init boot the kernel + host adapter (default)\n` + + ` doctor verify the install end-to-end\n` + + ` guidance --topic read-only VEIL capability map (no deps/build)\n` + + ` topics: overview threat countermeasure compliance optimization experiment\n` + + ` route cost-optimal model routing (needs \`npm run build\`)\n` + + ` flywheel [generations] SYNTHETIC self-improvement demo (needs \`npm run build\`)\n` + + ` --version print the kernel version`, + ); + return 0; + default: + console.error(`Unknown command: ${cmd}. Try \`${HARNESS_NAME} --help\`.`); + return 2; + } +} + +// CLI guard: execute only when invoked directly (not when imported by a test). +// npm's bin shims pass a NON-normalized argv[1], so realpath BOTH sides before +// comparing — a naive string === misses the npx/shim path and the CLI no-ops. +import { fileURLToPath } from 'node:url'; +import { realpathSync } from 'node:fs'; +import { argv } from 'node:process'; +const invokedDirectly = (() => { + if (!argv[1]) return false; + try { + const a = realpathSync(argv[1]); + const b = realpathSync(fileURLToPath(import.meta.url)); + return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b; + } catch { + return false; + } +})(); +if (invokedDirectly) { + run(argv.slice(2)) + .then((code) => process.exit(code)) + .catch((err) => { + console.error(err); + process.exit(1); + }); +} diff --git a/harness/wifi-densepose-privshield/package.json b/harness/wifi-densepose-privshield/package.json new file mode 100644 index 00000000..ab9774a1 --- /dev/null +++ b/harness/wifi-densepose-privshield/package.json @@ -0,0 +1,50 @@ +{ + "name": "wifi-densepose-privshield-harness", + "version": "0.1.0", + "description": "Harness for wifi-densepose-privshield (WiFi Veil — compliant-waveform WiFi-sensing privacy shield, ADR-288/289)", + "license": "MIT", + "type": "module", + "bin": { + "wifi-densepose-privshield-harness": "bin/cli.js" + }, + "files": [ + "bin/**", + "dist/**", + "src/**", + "tsconfig.json", + ".claude/**", + ".claude-plugin/**", + "CLAUDE.md", + "README.md", + "LICENSE" + ], + "scripts": { + "build": "tsc", + "test": "vitest run", + "init": "node ./bin/cli.js init", + "doctor": "node ./bin/cli.js doctor", + "guidance": "node ./bin/cli.js guidance", + "evolve": "metaharness-darwin evolve . --sandbox real --generations 3 --children 4", + "evolve:dry": "metaharness-darwin evolve . --sandbox mock --generations 2 --children 3", + "route": "npm run build && node ./bin/cli.js route", + "flywheel:dry": "npm run build && node ./bin/cli.js flywheel 3" + }, + "dependencies": { + "@metaharness/kernel": "^0.1.0", + "@metaharness/host-claude-code": "^0.1.0", + "@metaharness/router": "^0.3.2", + "@metaharness/flywheel": "^0.1.7" + }, + "devDependencies": { + "@types/node": "^20.0.0", + "typescript": "^5.4.0", + "vitest": "^3.0.0", + "@metaharness/darwin": "^0.2.2" + }, + "engines": { + "node": ">=20.0.0" + }, + "publishConfig": { + "access": "public" + } +} diff --git a/harness/wifi-densepose-privshield/src/flywheel.ts b/harness/wifi-densepose-privshield/src/flywheel.ts new file mode 100644 index 00000000..a8cedad1 --- /dev/null +++ b/harness/wifi-densepose-privshield/src/flywheel.ts @@ -0,0 +1,97 @@ +// SPDX-License-Identifier: MIT +// +// The wifi-densepose-privshield (VEIL) harness's self-improvement loop, via +// @metaharness/flywheel: run -> measure -> mutate -> verify -> promote, with a +// frozen, conjunctive promotion gate and a signed, replayable lineage. +// +// HONESTY NOTE (load-bearing): `runVeilFlywheelDemo()` wires the real +// @metaharness/flywheel API end-to-end, but its Proposer and Evaluator are +// SYNTHETIC stand-ins — a deterministic string mutation and a deterministic +// scoring function over that string, with NO model call and NO real benchmark. +// It proves the wiring works (see __tests__/flywheel.test.ts: a non-empty lift +// curve, a verifiable replay bundle) and gives a `dataSource: 'SYNTHETIC'`- +// stamped demo. A LIVE run needs the operator to supply: +// - a real Proposer: a model call that improves one policy lever (e.g. the +// compliance-review checklist, the threat-model triage prompt); +// - a real Evaluator: scores that policy against real tasks (e.g. "did the +// compliance reviewer catch a non-energy-preserving perturbation"). +// Neither exists in this repo — wiring them is a live-API-key decision for the +// harness operator, not something to fake here. + +import { + runFlywheelGenerations, + meetsPromotionRule, + makeSigner, + verifyReplayBundle, + type Policy, + type PolicyGenome, + type Proposer, + type Evaluator, + type Suite, + type FlywheelResult, +} from '@metaharness/flywheel'; + +/** The gen-0 operating policy for the VEIL harness's review agents. Opaque + * string levers — the flywheel never interprets their meaning, only the + * Evaluator does. */ +export const VEIL_ROOT_POLICY: Policy = { + complianceReview: 'energy-ratio-checklist', + threatTriage: 'single-pass', +}; + +/** SYNTHETIC proposer: deterministically varies the target lever's value + * rather than calling a model. */ +const syntheticProposer: Proposer = async (base: PolicyGenome, target: string) => { + const current = base.policy[target] ?? ''; + return `${current}+g${base.generation + 1}`; +}; + +/** SYNTHETIC evaluator: scores a policy purely as a function of its own string + * content — a deterministic stand-in for running the harness's agents against a + * real task suite. `noopRate` must move for anything to promote (the default + * gate requires it to strictly improve generation over generation). */ +const syntheticEvaluator: Evaluator = async (policy: Policy, _suite: Suite) => { + const totalLength = Object.values(policy).reduce((s, v) => s + v.length, 0); + const primary = Math.min(0.5 + totalLength / 200, 0.98); + const noopRate = Math.max(0.3 - totalLength / 300, 0.02); + return { + primary, + noopRate, + costPerWin: 1 / primary, + regressed: false, + }; +}; + +const VEIL_HOLDOUT: Suite = { + id: 'veil-harness-holdout-synthetic', + items: ['seeded-compliance-task-1', 'seeded-threat-task-2', 'seeded-optimizer-task-3'], +}; + +const VEIL_ANCHOR: Suite = { + id: 'veil-harness-anchor-synthetic', + items: ['frozen-not-jamming-regression-1'], +}; + +/** + * Run a small, fully SYNTHETIC flywheel demo end-to-end and return the real + * @metaharness/flywheel result — a genuine lift curve and a signed, + * independently replayable bundle, built from synthetic (not live) evidence. + */ +export async function runVeilFlywheelDemo(maxGenerations = 3): Promise { + return runFlywheelGenerations({ + rootPolicy: VEIL_ROOT_POLICY, + proposer: syntheticProposer, + evaluator: syntheticEvaluator, + promotionRule: meetsPromotionRule, + holdout: VEIL_HOLDOUT, + anchor: VEIL_ANCHOR, + maxGenerations, + signer: makeSigner(), + dataSource: 'SYNTHETIC', + }); +} + +/** Independently verify a flywheel demo's replay bundle (no trust in the producer). */ +export function verifyVeilFlywheelDemo(result: FlywheelResult) { + return verifyReplayBundle(result.replayBundle); +} diff --git a/harness/wifi-densepose-privshield/src/init.ts b/harness/wifi-densepose-privshield/src/init.ts new file mode 100644 index 00000000..4f9d0cbf --- /dev/null +++ b/harness/wifi-densepose-privshield/src/init.ts @@ -0,0 +1,25 @@ +// SPDX-License-Identifier: MIT +// The harness's `wifi-densepose-privshield-harness init` entry (typed mirror of +// the JS command in bin/cli.js; the published CLI uses the JS version so no +// build is required for `init`). + +import { loadKernel } from '@metaharness/kernel'; +import adapter from '@metaharness/host-claude-code'; + +const HARNESS_NAME = 'wifi-densepose-privshield-harness'; + +async function main(): Promise { + const kernel = await loadKernel(); + const info = kernel.kernelInfo(); + console.log(`${HARNESS_NAME} — kernel ${info.version} (${kernel.backend})`); + console.log(`Host adapter: ${adapter.name}`); + console.log(`Run \`${HARNESS_NAME} doctor\` to verify the install.`); + return 0; +} + +main() + .then((c) => process.exit(c)) + .catch((err) => { + console.error(err); + process.exit(1); + }); diff --git a/harness/wifi-densepose-privshield/src/router.ts b/harness/wifi-densepose-privshield/src/router.ts new file mode 100644 index 00000000..e3a26080 --- /dev/null +++ b/harness/wifi-densepose-privshield/src/router.ts @@ -0,0 +1,68 @@ +// SPDX-License-Identifier: MIT +// +// Cost-optimal task routing for the wifi-densepose-privshield (VEIL) harness, +// via @metaharness/router: route each agent query to the cheapest model +// predicted to clear a quality bar, instead of defaulting every query to the +// frontier tier. +// +// HONESTY NOTE: the candidate `examples` below are SEED/ILLUSTRATIVE data — +// four hand-picked (embedding, quality) points per candidate, not measured +// eval-log observations. They exist so `veilTaskRouter` is a real, runnable +// k-NN router out of the box (see __tests__/router.test.ts), not so its routing +// decisions should be trusted for production cost savings. Replace +// `VEIL_ROUTER_CANDIDATES[*].examples` with real (query embedding → quality +// achieved) rows from your own eval logs before relying on this. + +import { Router, type RouterCandidate } from '@metaharness/router'; + +/** + * A 4-axis feature embedding for a harness query (each axis 0..1): + * [0] threatModeling — "is this attack in scope / what does VEIL defend"-shaped + * [1] complianceReview — "does this stay compliant / not jamming"-shaped + * [2] optimizerTuning — "tune passes/bits / re-run the optimizer"-shaped + * [3] docWriting — "write/update the research bundle or ADR"-shaped + * A caller with a real embedding model should project onto that model's + * dimensionality instead — the router only needs consistent vectors. + */ +export type VeilTaskEmbedding = readonly [number, number, number, number]; + +export const VEIL_ROUTER_CANDIDATES: RouterCandidate[] = [ + { + id: 'cheap-tier', + costPerMTok: 1, + examples: [ + { embedding: [1, 0, 0, 0], quality: 0.88 }, // threat-model Q&A: cheap tier is fine + { embedding: [0, 0, 0, 1], quality: 0.85 }, // doc writing: cheap tier is fine + { embedding: [0, 1, 0, 0], quality: 0.55 }, // compliance review: cheap tier is weak + { embedding: [0, 0, 1, 0], quality: 0.5 }, // optimizer tuning: cheap tier is weak + ], + }, + { + id: 'frontier-tier', + costPerMTok: 15, + examples: [ + { embedding: [1, 0, 0, 0], quality: 0.95 }, + { embedding: [0, 0, 0, 1], quality: 0.93 }, + { embedding: [0, 1, 0, 0], quality: 0.93 }, // compliance review: frontier tier needed + { embedding: [0, 0, 1, 0], quality: 0.92 }, // optimizer tuning: frontier tier needed + ], + }, +]; + +/** + * Cost-optimal router for the harness's four query shapes above. `qualityBar` + * of 0.8: return the cheapest candidate predicted to clear 80% quality, or the + * best-predicted candidate if none do. k=1 because each candidate has only 4 + * orthogonal one-hot examples (see the SAR harness note on why the default k=5 + * would collapse every query to the same prediction here). + */ +export const veilTaskRouter = new Router({ + qualityBar: 0.8, + candidates: VEIL_ROUTER_CANDIDATES, + k: 1, +}); + +/** Route one query embedding to the cost-optimal model tier. */ +export function routeVeilQuery(queryEmbedding: VeilTaskEmbedding) { + return veilTaskRouter.route([...queryEmbedding]); +} diff --git a/harness/wifi-densepose-privshield/tsconfig.json b/harness/wifi-densepose-privshield/tsconfig.json new file mode 100644 index 00000000..4f908fa4 --- /dev/null +++ b/harness/wifi-densepose-privshield/tsconfig.json @@ -0,0 +1,19 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "NodeNext", + "moduleResolution": "NodeNext", + "lib": ["ES2022"], + "outDir": "./dist", + "rootDir": "./src", + "declaration": true, + "declarationMap": true, + "sourceMap": true, + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true + }, + "include": ["src/**/*.ts"], + "exclude": ["node_modules", "dist", "__tests__"] +} diff --git a/harness/wifi-densepose-privshield/vitest.config.ts b/harness/wifi-densepose-privshield/vitest.config.ts new file mode 100644 index 00000000..dede0819 --- /dev/null +++ b/harness/wifi-densepose-privshield/vitest.config.ts @@ -0,0 +1,22 @@ +// SPDX-License-Identifier: MIT +// Strips the `#!/usr/bin/env node` shebang from importable entrypoints (e.g. +// bin/cli.js) before Vite parses them — Vite/esbuild (used internally by +// Vitest) does NOT strip shebangs, so importing a shebanged module throws +// `SyntaxError: Invalid or unexpected token`. No effect on direct CLI +// execution. +import { defineConfig } from 'vitest/config'; + +export default defineConfig({ + plugins: [ + { + name: 'strip-shebang', + enforce: 'pre', + transform(code: string) { + if (code.startsWith('#!')) { + return { code: code.replace(/^#![^\n]*/, ''), map: null }; + } + return null; + }, + }, + ], +}); diff --git a/scripts/csi-data-policy-check.sh b/scripts/csi-data-policy-check.sh index 556e2b36..168c9569 100755 --- a/scripts/csi-data-policy-check.sh +++ b/scripts/csi-data-policy-check.sh @@ -1,8 +1,8 @@ #!/usr/bin/env bash # -# csi-data-policy-check.sh — ADR-296 CSI data-incident repository guard. +# csi-data-policy-check.sh — ADR-299 CSI data-incident repository guard. # -# WHY (ADR-296): raw CSI recordings are person data (they encode breathing, +# WHY (ADR-299): raw CSI recordings are person data (they encode breathing, # movement, and presence) and CLAUDE.md prohibits committing CSI or person # data. A stale `.gitignore` rule let ~64.6 MB of raw captures reach the tree # under `data/recordings/` and `v2/data/recordings/`. This check is the @@ -30,7 +30,7 @@ # ------------------------------------------------------------------------------ # ALLOWLIST (synthetic test fixtures) # ------------------------------------------------------------------------------ -# Tests may use only synthetic or expressly-consented minimal fixtures (ADR-296). +# Tests may use only synthetic or expressly-consented minimal fixtures (ADR-299). # A file whose path matches an allow pattern is exempt. Patterns come from: # * the file `scripts/csi-data-policy.allow` (one glob per line, `#` comments), and # * the env var `CSI_POLICY_ALLOW` (colon-separated globs). @@ -38,11 +38,11 @@ # scripts/tests/fixtures/csi-policy/*.csi.jsonl # # ------------------------------------------------------------------------------ -# BASELINE (acknowledged pre-existing incident, ADR-296) +# BASELINE (acknowledged pre-existing incident, ADR-299) # ------------------------------------------------------------------------------ # The tree today ALREADY contains the incident recordings under # `data/recordings/` and `v2/data/recordings/`. Removing them is destructive and -# gated on data-owner sign-off (ADR-296 "Decision"), so this guard is EXPECTED to +# gated on data-owner sign-off (ADR-299 "Decision"), so this guard is EXPECTED to # fail on the current tree — that failure documents the incident. # # Once the owner removes those files, or to acknowledge them in the interim @@ -160,7 +160,7 @@ scan_stdin() { continue # synthetic fixture, expressly allowed fi if matches_any "$f" BASELINE_PATTERNS; then - echo "ack: $f — $reason (acknowledged baseline, ADR-296)" >&2 + echo "ack: $f — $reason (acknowledged baseline, ADR-299)" >&2 acknowledged=$((acknowledged + 1)) continue fi @@ -169,14 +169,14 @@ scan_stdin() { done if [[ "$acknowledged" -gt 0 ]]; then - echo "note: $acknowledged file(s) acknowledged via CSI_POLICY_BASELINE (ADR-296)." >&2 + echo "note: $acknowledged file(s) acknowledged via CSI_POLICY_BASELINE (ADR-299)." >&2 fi if [[ "$violations" -gt 0 ]]; then echo "" >&2 - echo "FAIL: $violations CSI/person-data policy violation(s) (ADR-296)." >&2 + echo "FAIL: $violations CSI/person-data policy violation(s) (ADR-299)." >&2 echo " Raw CSI is person data and must not be tracked in git. See" >&2 - echo " docs/adr/ADR-296-csi-data-incident-repo-controls.md." >&2 + echo " docs/adr/ADR-299-csi-data-incident-repo-controls.md." >&2 echo " Synthetic test fixtures can be allowlisted in $ALLOW_FILE." >&2 return 1 fi diff --git a/scripts/csi-data-policy.allow b/scripts/csi-data-policy.allow index 2d5ce01a..99559bbc 100644 --- a/scripts/csi-data-policy.allow +++ b/scripts/csi-data-policy.allow @@ -1,10 +1,10 @@ -# csi-data-policy.allow — ADR-296 synthetic-fixture allowlist. +# csi-data-policy.allow — ADR-299 synthetic-fixture allowlist. # # One shell glob per line (repo-relative paths). `#` starts a comment; blank # lines are ignored. A tracked/staged file whose path matches any pattern here # is exempt from the CSI data-policy check (scripts/csi-data-policy-check.sh). # -# ONLY synthetic or expressly-consented minimal fixtures belong here (ADR-296). +# ONLY synthetic or expressly-consented minimal fixtures belong here (ADR-299). # Never allowlist a real capture to silence the guard — real CSI is person data. # The CSI_POLICY_ALLOW env var appends extra patterns (colon-separated) for # one-off/local use. diff --git a/ui/pose-fusion/js/csi-simulator.js b/ui/pose-fusion/js/csi-simulator.js index 5c496a51..57914c85 100644 --- a/ui/pose-fusion/js/csi-simulator.js +++ b/ui/pose-fusion/js/csi-simulator.js @@ -55,7 +55,7 @@ export class CsiSimulator { this.ws = new WebSocket(url); this.ws.binaryType = 'arraybuffer'; this.ws.onmessage = (evt) => this._handleLiveFrame(evt.data); - // ADR-292 (issue #1557): a socket that merely *opened* is NOT live — + // ADR-295 (issue #1557): a socket that merely *opened* is NOT live — // synthetic demo data keeps flowing until a real frame is decoded. We // stay in demo mode (watermarked) on open; `_handleLiveFrame` flips to // live only once it has parsed a verified frame. @@ -299,11 +299,11 @@ export class CsiSimulator { this._liveAmplitude[i] = Math.sqrt(real * real + imag * imag) / 2048; this._livePhase[i] = Math.atan2(imag, real); } - // ADR-292 (issue #1557): a real frame was decoded — only now is this live. + // ADR-295 (issue #1557): a real frame was decoded — only now is this live. this._markVerifiedFrame(); } - /** ADR-292: promote from watermarked demo to live once a real frame lands. */ + /** ADR-295: promote from watermarked demo to live once a real frame lands. */ _markVerifiedFrame() { this.verifiedFrame = true; this.mode = 'live'; @@ -327,7 +327,7 @@ export class CsiSimulator { for (let i = 0; i < n; i++) { this._liveAmplitude[i] = Math.abs(ampArr[i]) * scale; } - // ADR-292 (issue #1557): a real frame carrying amplitude was decoded. + // ADR-295 (issue #1557): a real frame carrying amplitude was decoded. this._markVerifiedFrame(); } diff --git a/ui/pose-fusion/js/main.js b/ui/pose-fusion/js/main.js index d6860ac5..f9dface3 100644 --- a/ui/pose-fusion/js/main.js +++ b/ui/pose-fusion/js/main.js @@ -151,7 +151,7 @@ function init() { if (wsUrlInput) wsUrlInput.value = defaultWsUrl; // ADR-272: exchange the stored bearer for a single-use ?ticket= before the // upgrade — a browser cannot set an Authorization header on a WebSocket. - // ADR-292 (issue #1557): opening the socket does NOT mean live — the + // ADR-295 (issue #1557): opening the socket does NOT mean live — the // simulator keeps producing watermarked SYNTHETIC data until a real CSI frame // is decoded. Only the verified-frame callback promotes the label to LIVE. csiSimulator.onVerifiedFrame = () => { diff --git a/ui/services/sensing.service.js b/ui/services/sensing.service.js index 9644572a..5eca2d93 100644 --- a/ui/services/sensing.service.js +++ b/ui/services/sensing.service.js @@ -304,7 +304,7 @@ class SensingService { * hardware or simulation. Called once on WebSocket open. */ async _detectServerSource() { - // ADR-292 (issue #1526): an unreachable or unauthorized status endpoint is + // ADR-295 (issue #1526): an unreachable or unauthorized status endpoint is // an *unknown* state — it must NOT collapse to "live". Prefer the canonical // `source_state` the server now returns; on any error stay conservative // (server-simulated) until a real frame's `source` field promotes us. @@ -322,12 +322,12 @@ class SensingService { } /** - * Map a raw server source string (and optional canonical ADR-292 + * Map a raw server source string (and optional canonical ADR-295 * `source_state`) to the UI data-source label. */ _applyServerSource(rawSource, sourceState) { this._serverSource = rawSource; - // ADR-292: only the verified/unverified live states may show "live"; any + // ADR-295: only the verified/unverified live states may show "live"; any // synthetic/stale/disconnected state must not. if (sourceState) { if (sourceState === 'live_verified' || sourceState === 'live_unverified') { diff --git a/v2/Cargo.toml b/v2/Cargo.toml index 9cdbeaff..9f553f32 100644 --- a/v2/Cargo.toml +++ b/v2/Cargo.toml @@ -21,6 +21,7 @@ members = [ "crates/wifi-densepose-train", "crates/wifi-densepose-sensing-server", "crates/wifi-densepose-aether", # ADR-185 §13 — AETHER pure-compute leaf (std-only) + "crates/wifi-densepose-privshield", # ADR-291 — VEIL privacy shield (compliant-waveform anti-sensing; std-only leaf) "crates/wifi-densepose-wifiscan", "crates/wifi-densepose-vitals", "crates/wifi-densepose-ruvector", @@ -94,28 +95,28 @@ members = [ # hardware coupling, every number SYNTHETIC/L0 until real wideband RF # hardware exists. "crates/wifi-densepose-sar", - # ADR-297 phase 1 — perception substrate spine (new first-party crates): - "crates/ruview-ontology", # ADR-303 canonical spatial ontology (Site..Event) - "crates/ruview-attest", # ADR-302 authenticated sensor identity / RF chain of custody - "crates/ruview-evidence", # ADR-301 evidence engine (per-room/device/subject ledger) - # ADR-297 phase 1 — dependent wave (build on the spine roots above): - "crates/ruview-ood", # ADR-299 OOD KNOWN/DEGRADED/UNKNOWN gating - "crates/ruview-witness", # ADR-316 witness chain (staged signed provenance) - "crates/ruview-certify", # ADR-315 capability certificate - "crates/ruview-scorecard", # ADR-314 multi-domain benchmark scorecard - "crates/ruview-policy", # ADR-318 decision policy / action authorization - # ADR-297 phase 2 — unified world-model core: - "crates/ruview-hal", # ADR-317 sensor HAL (any modality -> Observation) - "crates/ruview-groundtruth",# ADR-300 ground-truth synchronization / validation plane - "crates/ruview-track", # ADR-304 persistent privacy-preserving tracking - "crates/ruview-fusion", # ADR-308 uncertainty-aware fusion -> one world state - # ADR-297 phase 3 — higher-ceiling primitives (on the fused world state): - "crates/ruview-twin", # ADR-312 digital RF twin (per-deployment model) - "crates/ruview-placement", # ADR-305 sensor placement optimizer - "crates/ruview-memory", # ADR-309 long-term spatial memory / anomaly - "crates/ruview-counterfactual",# ADR-310 counterfactual spatial inference - "crates/ruview-infogain", # ADR-311 information-gain scheduler - "crates/ruview-active", # ADR-306 active sensing control + # ADR-300 phase 1 — perception substrate spine (new first-party crates): + "crates/ruview-ontology", # ADR-306 canonical spatial ontology (Site..Event) + "crates/ruview-attest", # ADR-305 authenticated sensor identity / RF chain of custody + "crates/ruview-evidence", # ADR-304 evidence engine (per-room/device/subject ledger) + # ADR-300 phase 1 — dependent wave (build on the spine roots above): + "crates/ruview-ood", # ADR-302 OOD KNOWN/DEGRADED/UNKNOWN gating + "crates/ruview-witness", # ADR-319 witness chain (staged signed provenance) + "crates/ruview-certify", # ADR-318 capability certificate + "crates/ruview-scorecard", # ADR-317 multi-domain benchmark scorecard + "crates/ruview-policy", # ADR-321 decision policy / action authorization + # ADR-300 phase 2 — unified world-model core: + "crates/ruview-hal", # ADR-320 sensor HAL (any modality -> Observation) + "crates/ruview-groundtruth",# ADR-303 ground-truth synchronization / validation plane + "crates/ruview-track", # ADR-307 persistent privacy-preserving tracking + "crates/ruview-fusion", # ADR-311 uncertainty-aware fusion -> one world state + # ADR-300 phase 3 — higher-ceiling primitives (on the fused world state): + "crates/ruview-twin", # ADR-315 digital RF twin (per-deployment model) + "crates/ruview-placement", # ADR-308 sensor placement optimizer + "crates/ruview-memory", # ADR-312 long-term spatial memory / anomaly + "crates/ruview-counterfactual",# ADR-313 counterfactual spatial inference + "crates/ruview-infogain", # ADR-314 information-gain scheduler + "crates/ruview-active", # ADR-309 active sensing control ] # ADR-040: WASM edge crate targets wasm32-unknown-unknown (no_std), # excluded from workspace to avoid breaking `cargo test --workspace`. @@ -144,7 +145,7 @@ categories = ["science", "computer-vision", "wasm"] # Core utilities thiserror = "2.0" # WiFi Veil — compliant-waveform countermeasure against unauthorized WiFi -# sensing (ADR-291). Dependency-free, deterministic, SYNTHETIC-only leaf; +# sensing (ADR-294). Dependency-free, deterministic, SYNTHETIC-only leaf; # pinned to an exact rev because the crate is consumed pre-crates.io-release. wifi-veil = { git = "https://github.com/ruvnet/wifi-veil", rev = "018468b5d2bf41f35c552910f35659830af0eb91" } anyhow = "1.0" diff --git a/v2/crates/ruview-active/src/control.rs b/v2/crates/ruview-active/src/control.rs index 1e738f95..01010049 100644 --- a/v2/crates/ruview-active/src/control.rs +++ b/v2/crates/ruview-active/src/control.rs @@ -1,4 +1,4 @@ -//! Controllable degrees of freedom of an RF measurement (ADR-306 §1). +//! Controllable degrees of freedom of an RF measurement (ADR-309 §1). //! //! **SYNTHETIC / L0 model scaffold.** These types describe *what a controller //! could ask hardware to configure*; constructing one drives **no** radio and @@ -10,7 +10,7 @@ //! that can only vary its sounding cadence exposes a capability whose only //! non-empty axis is [`ControlCapability::cadences`]; an all-empty capability //! means nothing is controllable and the controller degrades to the passive -//! planner (ADR-306 §2, ADR-280). +//! planner (ADR-309 §2, ADR-280). use serde::{Deserialize, Serialize}; use thiserror::Error; @@ -325,7 +325,7 @@ impl ControlAction { } /// The set of control values a deployment can actually set, per axis -/// (capability-gated by the ADR-317 HAL in a fielded system). An axis with no +/// (capability-gated by the ADR-320 HAL in a fielded system). An axis with no /// values is not controllable on this deployment; an all-empty capability is /// the ESP32-style passive fallback trigger. /// diff --git a/v2/crates/ruview-active/src/lib.rs b/v2/crates/ruview-active/src/lib.rs index 7bb63f8e..14863dea 100644 --- a/v2/crates/ruview-active/src/lib.rs +++ b/v2/crates/ruview-active/src/lib.rs @@ -1,6 +1,6 @@ -//! # `ruview-active` — closed-loop RF experiment control (ADR-306, ADR-297 primitive 9) +//! # `ruview-active` — closed-loop RF experiment control (ADR-309, ADR-300 primitive 9) //! -//! **SYNTHETIC / L0 research-forward model scaffold (ADR-282, ADR-297 phase 3).** +//! **SYNTHETIC / L0 research-forward model scaffold (ADR-282, ADR-300 phase 3).** //! This crate turns sensing from *RF-happens → observe* into //! *RuView-controls-RF → observe the response → optimize the next measurement*. //! It models the **control loop** ADR-280 deferred (ADR-280 built the governed @@ -16,9 +16,9 @@ //! admission/actuation surface. A twin predicts; it does not measure: no //! `MEASURED`, accuracy, or traffic-reduction claim is made or implied. Every //! exploration figure this crate produces is `SYNTHETIC` (CLAUDE.md honesty -//! discipline; ADR-306 §3). +//! discipline; ADR-309 §3). //! -//! ## The four ADR-297 non-negotiable rules, as they bind this crate +//! ## The four ADR-300 non-negotiable rules, as they bind this crate //! //! 1. **UNKNOWN is first-class, never an error.** A [`LastResponse::Unknown`] //! is not zero uncertainty and not an error: the policy *widens* exploration @@ -27,7 +27,7 @@ //! uncertainty becomes maximal uncertainty, never a silent zero. //! [`ClosedLoopController::step`] is total — no input panics. //! 2. **Certificates bind cryptographically.** Out of scope here; a proposal -//! names an already-authenticated ADR-303 +//! names an already-authenticated ADR-306 //! [`ZoneId`](ruview_ontology::ZoneId), and a fielded loop step is admitted //! through the ADR-280 governed path before any actuation. //! 3. **One canonical semantics downstream.** The loop reuses the canonical @@ -35,7 +35,7 @@ //! [`EvidenceLevel`](ruview_ontology::EvidenceLevel), and //! [`SemanticProvenance`](ruview_ontology::SemanticProvenance) rather than //! reinventing per-crate identity/evidence shapes. It shares the *notion* of -//! expected gain with ADR-311 but defines its own [`ControlAction`] +//! expected gain with ADR-314 but defines its own [`ControlAction`] //! vocabulary and does **not** depend on `ruview-infogain`, so the two crates //! build in parallel. //! 4. **Honest evidence.** Every proposal is stamped [`EvidenceLevel::L1`] @@ -126,7 +126,7 @@ mod tests { ClosedLoopController::new(full_capability(), ControllerConfig::default()) } - // ADR-306 §2: a high-uncertainty zone drives an exploratory control action + // ADR-309 §2: a high-uncertainty zone drives an exploratory control action // — widest bandwidth, fastest cadence, widest aperture, Explore intent. #[test] fn high_uncertainty_drives_exploratory_action() { @@ -141,7 +141,7 @@ mod tests { assert_eq!(p.provenance.model_version, MODEL_VERSION); } - // ADR-306 validation: convergence (falling uncertainty) reduces exploration + // ADR-309 validation: convergence (falling uncertainty) reduces exploration // — the proposal narrows and the intent flips to Exploit. #[test] fn convergence_reduces_exploration() { @@ -169,7 +169,7 @@ mod tests { assert_eq!(pl.action.bandwidth, Some(Bandwidth::Bw20)); // narrowest } - // ADR-297 rule 1: an UNKNOWN last response widens exploration relative to + // ADR-300 rule 1: an UNKNOWN last response widens exploration relative to // the same uncertainty with an observed response. #[test] fn unknown_last_response_widens_exploration() { @@ -196,7 +196,7 @@ mod tests { assert_eq!(pu.intent, ControlIntent::Explore); } - // ADR-306 §2 degradation: an empty controllable set (ESP32-only) falls back + // ADR-309 §2 degradation: an empty controllable set (ESP32-only) falls back // to the passive planner with no error and no fabricated gain. #[test] fn empty_capability_degrades_to_passive() { @@ -300,7 +300,7 @@ mod tests { } // Non-finite uncertainty is treated as maximal uncertainty, never a silent - // zero (ADR-297 rule 1), and never panics. + // zero (ADR-300 rule 1), and never panics. #[test] fn non_finite_uncertainty_is_maximal_not_zero() { assert_eq!(Uncertainty::new(f64::NAN).value(), 1.0); diff --git a/v2/crates/ruview-active/src/policy.rs b/v2/crates/ruview-active/src/policy.rs index 8607fb42..f7bed403 100644 --- a/v2/crates/ruview-active/src/policy.rs +++ b/v2/crates/ruview-active/src/policy.rs @@ -1,10 +1,10 @@ -//! The closed-loop experiment controller (ADR-306 §2). +//! The closed-loop experiment controller (ADR-309 §2). //! //! **SYNTHETIC / L0 model scaffold.** This is the *loop* ADR-280 deferred: it //! reads a modelled per-zone uncertainty and the last modelled response, and //! proposes the next controllable measurement configuration expected to reduce //! that uncertainty most. It is an information-driven **planning** policy — it -//! shares the *notion* of expected gain with ADR-311 but defines its own +//! shares the *notion* of expected gain with ADR-314 but defines its own //! control vocabulary and takes **no** dependency on `ruview-infogain`, so the //! two crates build in parallel. //! @@ -14,7 +14,7 @@ //! ADR-280 governed admission/actuation surface — a fielded caller submits each //! proposal through that fail-closed path. //! -//! ## First-class UNKNOWN (ADR-297 rule 1) +//! ## First-class UNKNOWN (ADR-300 rule 1) //! //! The last response is [`LastResponse::Unknown`] whenever the previous //! solicited measurement returned nothing interpretable. UNKNOWN is **not** @@ -58,8 +58,8 @@ impl Uncertainty { /// The outcome of the previous solicited measurement for a zone. /// /// This reuses the canonical [`EvidenceLevel`] vocabulary rather than a -/// per-crate grade (ADR-297 rule 3). A fielded caller derives it from the -/// ADR-303 [`Observation`](ruview_ontology::Observation) the sounding produced. +/// per-crate grade (ADR-300 rule 3). A fielded caller derives it from the +/// ADR-306 [`Observation`](ruview_ontology::Observation) the sounding produced. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum LastResponse { @@ -82,14 +82,14 @@ pub enum LastResponse { /// to one closed-loop [`ClosedLoopController::step`]. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub struct ZoneBelief { - /// The target zone (canonical ontology id, ADR-303). + /// The target zone (canonical ontology id, ADR-306). pub zone: ZoneId, /// Current modelled uncertainty about the zone. pub uncertainty: Uncertainty, /// The outcome of the previous solicited measurement. pub last_response: LastResponse, /// A deterministic loop counter used only to sweep channels across cycles. - /// Injected by the caller — never sampled from a clock (ADR-297 §rules). + /// Injected by the caller — never sampled from a clock (ADR-300 §rules). #[serde(default)] pub cycle: u64, } @@ -126,7 +126,7 @@ pub enum ControlIntent { } /// Why the controller could not propose a controllable action and fell back to -/// the passive planner (ADR-306 §2 degradation). +/// the passive planner (ADR-309 §2 degradation). #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum PassiveReason { @@ -222,7 +222,7 @@ pub struct ControllerConfig { pub explore_threshold: f64, /// Additive widening applied to the exploration level when the last /// response was [`LastResponse::Unknown`]. Bounded into `[0, 1]` after - /// application (ADR-297 rule 1: UNKNOWN widens rather than commits). + /// application (ADR-300 rule 1: UNKNOWN widens rather than commits). pub unknown_widen: f64, } @@ -238,7 +238,7 @@ impl Default for ControllerConfig { /// The synthetic model version stamped onto every proposal's provenance. pub const MODEL_VERSION: &str = "ruview-active@synthetic-l0"; -/// The closed-loop RF experiment controller (ADR-306). +/// The closed-loop RF experiment controller (ADR-309). /// /// Holds the controllable [`ControlCapability`] of the deployment and the /// policy [`ControllerConfig`]. [`ClosedLoopController::step`] is a total, diff --git a/v2/crates/ruview-attest/src/lib.rs b/v2/crates/ruview-attest/src/lib.rs index 70db9f62..b21cb51d 100644 --- a/v2/crates/ruview-attest/src/lib.rs +++ b/v2/crates/ruview-attest/src/lib.rs @@ -1,19 +1,19 @@ //! `ruview-attest` — authenticated sensor identity and RF chain of custody. //! -//! This crate implements **ADR-302** (authenticated sensor identity), phase 1 of -//! the ADR-297 perception substrate. It models the chain of custody link +//! This crate implements **ADR-305** (authenticated sensor identity), phase 1 of +//! the ADR-300 perception substrate. It models the chain of custody link //! `device → signed measurement → sequence → timestamp → payload hash → //! calibration`, verified at the ingest boundary. //! //! ## Relationship to sibling ADRs //! -//! - **ADR-293** shipped step one — a loopback-default UDP bind and an optional +//! - **ADR-296** shipped step one — a loopback-default UDP bind and an optional //! source IP/CIDR allowlist — and explicitly deferred "per-device provisioned //! keys, MAC/AEAD, device identifiers, monotonic sequence numbers, freshness //! window, and replay rejection." **This crate is that step two.** An IP //! allowlist does not stop on-subnet spoofing; a cryptographic device //! identity bound into each measurement does. -//! - **ADR-316** (witness chain) consumes the [`VerifiedMeasurement`] lineage +//! - **ADR-319** (witness chain) consumes the [`VerifiedMeasurement`] lineage //! produced here and serializes it for offline re-verification. //! //! ## Signer / Verifier abstraction and the SYNTHETIC reference @@ -74,7 +74,7 @@ pub enum InputError { /// Reason a [`SignedMeasurement`] was rejected at the verification boundary. /// /// Every variant is a hard `Err`: a rejected frame is dropped and counted, -/// never a warning that proceeds (mirroring ADR-293's source-drop behaviour). +/// never a warning that proceeds (mirroring ADR-296's source-drop behaviour). #[derive(Debug, Clone, PartialEq, Eq, Error)] pub enum VerifyError { /// The measurement's `DeviceId` is not enrolled. @@ -155,7 +155,7 @@ impl PayloadHash { } } -/// Optional reference to a calibration certificate (ADR-298) in effect for a +/// Optional reference to a calibration certificate (ADR-301) in effect for a /// measurement. Validated length at the boundary. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct CalibrationRef(String); @@ -224,7 +224,7 @@ impl MeasurementContent { } /// A [`MeasurementContent`] together with its signature. This is the object on -/// the wire and the unit the witness chain (ADR-316) serializes. +/// the wire and the unit the witness chain (ADR-319) serializes. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct SignedMeasurement { /// The signed content. @@ -331,7 +331,7 @@ impl Verifier for Blake3MacSigner { /// Bounds a measurement timestamp against the injected server clock. Rejects /// frames older than `max_age_nanos` (stale) or more than `max_skew_ahead_nanos` -/// in the future (clock-skew budget). Reuses ADR-292's freshness notion rather +/// in the future (clock-skew budget). Reuses ADR-295's freshness notion rather /// than inventing a parallel one. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct FreshnessPolicy { @@ -395,7 +395,7 @@ impl AttestationVerifier { } /// Enroll (or re-enroll) a device with the verifier for its identity. This - /// is the explicit, authorized enrollment step from ADR-302; re-enrolling + /// is the explicit, authorized enrollment step from ADR-305; re-enrolling /// resets the device's sequence state. pub fn enroll(&mut self, device: DeviceId, verifier: V) { self.enrolled.insert( diff --git a/v2/crates/ruview-certify/src/lib.rs b/v2/crates/ruview-certify/src/lib.rs index 3b95a534..1f4d387b 100644 --- a/v2/crates/ruview-certify/src/lib.rs +++ b/v2/crates/ruview-certify/src/lib.rs @@ -1,4 +1,4 @@ -//! # `ruview-certify` — signed capability certificates (ADR-315, ADR-297 §1) +//! # `ruview-certify` — signed capability certificates (ADR-318, ADR-300 §1) //! //! A [`CapabilityCertificate`] is a bounded, signed attestation that a specific //! capability (e.g. presence, pose) has been *validated for a specific @@ -11,13 +11,13 @@ //! ## What the certificate binds //! //! - the **capability** ([`Capability`]); -//! - the **room** ([`SpaceId`], ADR-303) plus the **calibration-certificate -//! version** (ADR-298) it was validated against; -//! - the **hardware** ([`DeviceId`], ADR-302); +//! - the **room** ([`SpaceId`], ADR-306) plus the **calibration-certificate +//! version** (ADR-301) it was validated against; +//! - the **hardware** ([`DeviceId`], ADR-305); //! - the scored **model** version; //! - the **calibrated date** the calibration was captured; //! - the operating **metrics** (`moving_recall`, `stationary_recall`, -//! `false_presence_per_24h`) sliced from the ADR-301 ledger for **exactly this +//! `false_presence_per_24h`) sliced from the ADR-304 ledger for **exactly this //! context** (never pooled across contexts); //! - a `valid_until` expiry that is **never open-ended** and **cannot outlive the //! calibration validity**; @@ -26,7 +26,7 @@ //! - a **signature** over the canonical serialization ([`ruview_attest`]); an //! unsigned certificate is not a valid certificate. //! -//! ## Honest by construction (ADR-297 rule) +//! ## Honest by construction (ADR-300 rule) //! //! - Minting from a slice that reports **no evidence** yields no certificate — //! absence of evidence is never a capability. @@ -34,7 +34,7 @@ //! - A certificate minted from a synthetic ledger slice is `L0`/SYNTHETIC by //! construction; nothing here invents a MEASURED number. //! - [`CapabilityCertificate::is_valid`] is *conditional on the live domain -//! signature* (ADR-299): a certificate over a `DEGRADED`/`UNKNOWN` domain is +//! signature* (ADR-302): a certificate over a `DEGRADED`/`UNKNOWN` domain is //! not valid, and an expired certificate is not valid — the honest failure is //! UNKNOWN, not a best-effort guess. //! @@ -62,7 +62,7 @@ const DOMAIN: &[u8] = b"ruview-certify/CapabilityCertificate/v1"; // --------------------------------------------------------------------------- /// The phenomenon a certificate is about. A device may only be certified for a -/// capability it is attested to sense (ADR-302/ADR-141); the attestation gate is +/// capability it is attested to sense (ADR-305/ADR-141); the attestation gate is /// a phase-2 concern — this phase binds the capability into the signed object. #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "SCREAMING_SNAKE_CASE")] @@ -85,7 +85,7 @@ impl Capability { } /// The live domain-state signature a consumer supplies at validation time -/// (ADR-299). Only `Known` permits a capability; `Degraded`/`Unknown` gate the +/// (ADR-302). Only `Known` permits a capability; `Degraded`/`Unknown` gate the /// certificate to invalid — the honest failure is UNKNOWN, not a guess. #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "SCREAMING_SNAKE_CASE")] @@ -106,7 +106,7 @@ impl DomainState { } } -/// The operating metrics frozen onto a certificate, sliced from the ADR-301 +/// The operating metrics frozen onto a certificate, sliced from the ADR-304 /// ledger for one exact context (never a global average). /// /// `false_presence_per_24h` carries the ledger's context false-positive rate; @@ -128,15 +128,15 @@ pub struct OperatingMetrics { pub struct CertificateContent { /// The certified phenomenon. pub capability: Capability, - /// The room this claim is validated for (ADR-303). + /// The room this claim is validated for (ADR-306). pub room: SpaceId, /// Version of the calibration certificate the validation ran against - /// (ADR-298). The certificate cannot outlive this calibration. + /// (ADR-301). The certificate cannot outlive this calibration. pub calibration_version: u64, /// Expiry of the calibration certificate (unix seconds); the ceiling on /// `valid_until`. pub calibration_expires_at_unix_s: i64, - /// The authenticated device the claim is validated for (ADR-302). + /// The authenticated device the claim is validated for (ADR-305). pub hardware: DeviceId, /// The scored model version. pub model_version: String, @@ -180,7 +180,7 @@ impl CertificateContent { /// A signed capability certificate: the [`CertificateContent`] together with a /// signature over its canonical bytes. `signature` is [`None`] for an unsigned -/// certificate, which is never valid (ADR-315 §1). +/// certificate, which is never valid (ADR-318 §1). #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub struct CapabilityCertificate { /// The signed content. @@ -193,7 +193,7 @@ impl CapabilityCertificate { /// Wrap content as an **unsigned** certificate. Useful for tests and for /// staging content before signing; [`Self::verify`] and [`Self::is_valid`] /// both reject it because an unsigned certificate is not a valid - /// certificate (ADR-315 §1). + /// certificate (ADR-318 §1). #[must_use] pub fn unsigned(content: CertificateContent) -> Self { Self { @@ -213,7 +213,7 @@ impl CapabilityCertificate { } } - /// The consumer gate (ADR-315 §3, ADR-297/ADR-299): the certificate is valid + /// The consumer gate (ADR-318 §3, ADR-300/ADR-302): the certificate is valid /// **iff** it is signed, it has not expired (`now < valid_until`), and the /// live domain state is `Known`. A `Degraded`/`Unknown` domain or an expired /// or unsigned certificate resolves to *not valid* — the honest UNKNOWN, @@ -252,7 +252,7 @@ pub struct MintRequest<'c> { pub evidence_level: EvidenceLevel, } -/// Mint a signed [`CapabilityCertificate`] from an ADR-301 evidence slice for +/// Mint a signed [`CapabilityCertificate`] from an ADR-304 evidence slice for /// one `(room, device, model)` context. /// /// Minting is a pure function over the slice: the metrics are frozen into the @@ -284,7 +284,7 @@ pub fn mint( }); } - // Absence of evidence is never a capability (ADR-315 §2). + // Absence of evidence is never a capability (ADR-318 §2). let summary = slice.summarize(); let (floor, agg) = match summary.evidence { SummaryEvidence::NoEvidence => return Err(CertifyError::NoEvidence), diff --git a/v2/crates/ruview-certify/src/tests.rs b/v2/crates/ruview-certify/src/tests.rs index d4ccc0d8..df844130 100644 --- a/v2/crates/ruview-certify/src/tests.rs +++ b/v2/crates/ruview-certify/src/tests.rs @@ -1,4 +1,4 @@ -//! Deterministic tests (ADR-315 validation matrix): mint+verify, no-evidence => +//! Deterministic tests (ADR-318 validation matrix): mint+verify, no-evidence => //! no certificate, evidence-level floor enforced, expiry, unsigned invalid, //! not-KNOWN domain invalidates, canonical-bytes determinism, serde round-trip, //! calibration-linked expiry ceiling, and context binding. No wall clock, no diff --git a/v2/crates/ruview-counterfactual/src/hypothesis.rs b/v2/crates/ruview-counterfactual/src/hypothesis.rs index 7c8df8df..972b873c 100644 --- a/v2/crates/ruview-counterfactual/src/hypothesis.rs +++ b/v2/crates/ruview-counterfactual/src/hypothesis.rs @@ -1,14 +1,14 @@ -//! Scene hypotheses over the canonical ontology (ADR-310 §1). +//! Scene hypotheses over the canonical ontology (ADR-313 §1). //! //! **SYNTHETIC / L0 — a research-forward model scaffold, not a measurement //! system.** A [`Hypothesis`] is a *hypothesized* scene state — an occupant -//! count and their coarse positions — expressed over the ADR-303 canonical +//! count and their coarse positions — expressed over the ADR-306 canonical //! [`SpaceId`] so a counterfactual result is a governed spatial statement, not //! an opaque score. Nothing here is a hardware, `MEASURED`, or accuracy claim, -//! and this crate asserts **no** discrimination-accuracy number (ADR-310 +//! and this crate asserts **no** discrimination-accuracy number (ADR-313 //! evidence discipline). //! -//! Hypotheses are drawn from (and score *relative to*) the ADR-308 fused world +//! Hypotheses are drawn from (and score *relative to*) the ADR-311 fused world //! state and its neighbourhood: the current estimate, the **null hypothesis** //! (nobody present, [`Hypothesis::empty`]), and a bounded set of nearby //! alternatives (±1 occupant, shifted position). Positions are a coarse metric diff --git a/v2/crates/ruview-counterfactual/src/infer.rs b/v2/crates/ruview-counterfactual/src/infer.rs index 9fd901c7..8511ea66 100644 --- a/v2/crates/ruview-counterfactual/src/infer.rs +++ b/v2/crates/ruview-counterfactual/src/infer.rs @@ -1,15 +1,15 @@ -//! Counterfactual scoring and best-explanation selection (ADR-310 §2, §3). +//! Counterfactual scoring and best-explanation selection (ADR-313 §2, §3). //! //! **SYNTHETIC / L0 — a research-forward generative-scoring scaffold, not a //! measurement system.** This module scores a small set of scene //! [`Hypothesis`](crate::Hypothesis) against an observed link-measurement set, -//! using the ADR-312 [`RfTwin`] as the generative forward model. It is a +//! using the ADR-315 [`RfTwin`] as the generative forward model. It is a //! *consumer* of the twin, not a second simulator: the twin supplies the //! baseline expected distribution per link (geometry + propagation), and this //! layer applies a **documented SYNTHETIC occupant-attenuation model** on top — //! a hypothesized occupant attenuates any link whose line of sight passes near //! it. Nothing here is a hardware, `MEASURED`, or accuracy claim; this crate -//! asserts **no** discrimination-accuracy number (ADR-310 evidence discipline). +//! asserts **no** discrimination-accuracy number (ADR-313 evidence discipline). //! //! ## Likelihood (documented SYNTHETIC) //! @@ -22,13 +22,13 @@ //! This is a deliberately simple, deterministic model — clearly a scaffold, not //! real RF. //! -//! ## UNKNOWN is first-class (ADR-297 rule 1, ADR-310 §3) +//! ## UNKNOWN is first-class (ADR-300 rule 1, ADR-313 §3) //! //! The layer never forces a label. It returns [`BestExplanation::Unknown`] when //! the top two hypotheses are near-indistinguishable (margin below threshold), //! when **no** hypothesis explains the observation well (best mean per-link //! log-likelihood below a floor — the observation is outside what the twin can -//! account for, routed to the ADR-299 UNKNOWN verdict rather than a forced +//! account for, routed to the ADR-302 UNKNOWN verdict rather than a forced //! occupancy label), when no hypotheses are supplied, or when no observed link //! is evaluable against the twin. @@ -95,7 +95,7 @@ impl Default for OccupantModel { } /// Thresholds that route a scored hypothesis set to a best explanation or to a -/// first-class UNKNOWN verdict (ADR-310 §3). +/// first-class UNKNOWN verdict (ADR-313 §3). #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] pub struct ScoringConfig { /// Minimum log-likelihood-ratio margin (nats) between the top two @@ -105,7 +105,7 @@ pub struct ScoringConfig { /// Minimum best *mean per-link* log-likelihood (nats) required for any /// hypothesis to count as explaining the observation; below this the /// observation is outside what the twin can account for and the result is - /// UNKNOWN (routed to the ADR-299 verdict). Must be finite. + /// UNKNOWN (routed to the ADR-302 verdict). Must be finite. pub min_mean_log_likelihood: f64, } @@ -170,8 +170,8 @@ pub enum BestExplanation { /// Log-likelihood-ratio margin (nats) over the runner-up. margin: f64, }, - /// No confident best explanation; carries a first-class reason (ADR-297 - /// rule 1, ADR-310 §3). + /// No confident best explanation; carries a first-class reason (ADR-300 + /// rule 1, ADR-313 §3). Unknown { /// Why the result is UNKNOWN. reason: UnknownReason, @@ -197,7 +197,7 @@ pub enum UnknownReason { }, /// No hypothesis explains the observation well: the best mean per-link /// log-likelihood fell below the configured floor. The observation is - /// outside what the twin can account for (routes to the ADR-299 verdict). + /// outside what the twin can account for (routes to the ADR-302 verdict). NoHypothesisExplains { /// The best hypothesis's mean per-link log-likelihood (nats). best_mean_log_likelihood: f64, @@ -210,7 +210,7 @@ pub enum UnknownReason { /// /// **SYNTHETIC / L0.** Every score and the verdict are model-relative and /// inherit the twin's `L0` evidence level; nothing here is a camera-grade or -/// `MEASURED` claim (CLAUDE.md honesty rule, ADR-310 evidence discipline). +/// `MEASURED` claim (CLAUDE.md honesty rule, ADR-313 evidence discipline). #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub struct CounterfactualResult { /// Every hypothesis's score, ranked best-first: descending by @@ -426,7 +426,7 @@ fn decide(ranked: &[HypothesisScore], config: &ScoringConfig) -> BestExplanation }; }; - // No hypothesis explains the observation well ⇒ ADR-299 UNKNOWN verdict. + // No hypothesis explains the observation well ⇒ ADR-302 UNKNOWN verdict. if mean_ll < config.min_mean_log_likelihood { return BestExplanation::Unknown { reason: UnknownReason::NoHypothesisExplains { diff --git a/v2/crates/ruview-counterfactual/src/lib.rs b/v2/crates/ruview-counterfactual/src/lib.rs index 39e1c172..e485d3b0 100644 --- a/v2/crates/ruview-counterfactual/src/lib.rs +++ b/v2/crates/ruview-counterfactual/src/lib.rs @@ -1,4 +1,4 @@ -//! # `ruview-counterfactual` — counterfactual spatial inference (ADR-310, ADR-297 phase 3) +//! # `ruview-counterfactual` — counterfactual spatial inference (ADR-313, ADR-300 phase 3) //! //! **SYNTHETIC / L0 — a research-forward generative-scoring scaffold, not a //! measurement system.** @@ -9,22 +9,22 @@ //! better explained by absence"* or *"one occupant explains this better than //! two,"* because it has no model of what a measurement *should* look like under //! a hypothesized world state. This layer supplies that missing piece: given an -//! observed link-measurement set and the ADR-312 digital RF twin as the +//! observed link-measurement set and the ADR-315 digital RF twin as the //! generative forward model, it scores a small set of scene //! [`Hypothesis`](Hypothesis) — including the **null hypothesis** (nobody //! present) — and returns the maximum-likelihood explanation with a **margin**, //! or a first-class `UNKNOWN` when the hypotheses are near-indistinguishable. //! -//! It is a **consumer** of the twin, never a second simulator (ADR-310 option 3, -//! rejecting option 2): the ADR-312 twin supplies each link's baseline expected +//! It is a **consumer** of the twin, never a second simulator (ADR-313 option 3, +//! rejecting option 2): the ADR-315 twin supplies each link's baseline expected //! distribution (geometry + propagation), and this layer applies a **documented //! SYNTHETIC occupant-attenuation model** — a hypothesized occupant attenuates //! any link whose line of sight passes near it. Hypotheses are drawn from the -//! ADR-308 fused world state and its neighbourhood and are expressed over the -//! canonical ADR-303 [`SpaceId`](ruview_ontology::SpaceId), so a counterfactual -//! result is a governed spatial statement, not an opaque score (ADR-297 rule 3). +//! ADR-311 fused world state and its neighbourhood and are expressed over the +//! canonical ADR-306 [`SpaceId`](ruview_ontology::SpaceId), so a counterfactual +//! result is a governed spatial statement, not an opaque score (ADR-300 rule 3). //! -//! ## Honesty and evidence discipline (CLAUDE.md, ADR-310) +//! ## Honesty and evidence discipline (CLAUDE.md, ADR-313) //! //! Every likelihood is a **model-relative** score under a twin whose //! distributions are a simulation at evidence level `L0`, labelled `SYNTHETIC`. @@ -36,13 +36,13 @@ //! require the mean-pose-style baseline discipline, a leakage-free held-out //! split, and a reproducer before it could be tagged `MEASURED`. //! -//! ## UNKNOWN is a first-class output (ADR-297 rule 1, ADR-310 §3) +//! ## UNKNOWN is a first-class output (ADR-300 rule 1, ADR-313 §3) //! //! The layer never forces a label. The best explanation resolves to a //! first-class [`BestExplanation::Unknown`] when the top two hypotheses are //! near-indistinguishable (margin below threshold), when **no** hypothesis //! explains the observation well (best mean per-link log-likelihood below a -//! floor — routed to the ADR-299 `UNKNOWN` verdict), when no hypotheses are +//! floor — routed to the ADR-302 `UNKNOWN` verdict), when no hypotheses are //! supplied, or when no observed link is evaluable against the twin. UNKNOWN is //! a value, never an error, a panic, or a confident default. //! @@ -90,7 +90,7 @@ pub use infer::{ }; // Re-export the canonical ontology and twin vocabulary this crate consumes, so -// downstream speaks one semantics (ADR-297 rule 3, ADR-303). +// downstream speaks one semantics (ADR-300 rule 3, ADR-306). pub use ruview_ontology::{EvidenceLevel, SemanticProvenance, SpaceId}; pub use ruview_twin::{LinkId, LinkObservation, ObservationSet, RfTwin}; @@ -207,7 +207,7 @@ mod tests { } // Out-of-model measurements (gross deviations the twin cannot account for) - // route to UNKNOWN rather than a forced occupancy label (ADR-310 §3). + // route to UNKNOWN rather than a forced occupancy label (ADR-313 §3). #[test] fn out_of_model_observation_routes_to_unknown() { let t = twin(7); diff --git a/v2/crates/ruview-evidence/src/lib.rs b/v2/crates/ruview-evidence/src/lib.rs index 73f30dc0..1d09664d 100644 --- a/v2/crates/ruview-evidence/src/lib.rs +++ b/v2/crates/ruview-evidence/src/lib.rs @@ -1,10 +1,10 @@ -//! # `ruview-evidence` — the append-only accuracy ledger (ADR-301, ADR-297 §4) +//! # `ruview-evidence` — the append-only accuracy ledger (ADR-304, ADR-300 §4) //! //! "MLflow for physical sensing." Where an experiment tracker overwrites //! yesterday's number, this crate is an **append-only** record of how a model //! actually performs, keyed per deployment context //! `(room, device, subject-class, model-version)` and carrying, per record, -//! the ADR-301 metrics (moving/stationary recall, false-positive rate, drift, +//! the ADR-304 metrics (moving/stationary recall, false-positive rate, drift, //! predictive uncertainty, calibration age, sample count) plus exactly one //! [`EvidenceLevel`] (L0–L5, mirroring ADR-282 semantics). //! @@ -21,15 +21,15 @@ //! no `set_level`). This is the ADR-282/288/290 "no upgrade" rule. //! - Records are **append-only**: [`EvidenceLedger::append`] consumes a //! record by value and nothing hands back a mutable reference. A correction -//! is a *new* record, never an in-place edit (ADR-301 §1). -//! - Aggregation **never pools across contexts** (ADR-301 §2/§Consequences): +//! is a *new* record, never an in-place edit (ADR-304 §1). +//! - Aggregation **never pools across contexts** (ADR-304 §2/§Consequences): //! an [`EvidenceSlice`] is minted by [`EvidenceLedger::query`] for exactly //! one context and there is no API that averages two contexts into one //! number. A summary's evidence level is the **floor** (minimum) of the //! levels present in the slice — a slice can never report a level above the //! weakest record it contains. //! - An empty context returns [`SummaryEvidence::NoEvidence`], distinct from a -//! present-but-zero-accuracy summary — downstream (ADR-315) must treat +//! present-but-zero-accuracy summary — downstream (ADR-318) must treat //! "no evidence" as "no capability", not as a `0.0` score. #![forbid(unsafe_code)] @@ -65,7 +65,7 @@ pub enum EvidenceLevel { L3, /// L4 — calibrated multi-site field evidence. L4, - /// L5 — production, witnessed / certified (ADR-316). + /// L5 — production, witnessed / certified (ADR-319). L5, } @@ -78,22 +78,22 @@ pub enum ProvenanceClass { Synthetic, /// Real inference but no ground-truth reference backs the accuracy. Claimed, - /// Backed by an ADR-300 reference plus a reproducer handle. + /// Backed by an ADR-303 reference plus a reproducer handle. Measured, } /// The deployment context a record is keyed by: `(room, device, subject-class, -/// model-version)`. Identity is caller-supplied (ADR-303 space id, ADR-302 +/// model-version)`. Identity is caller-supplied (ADR-306 space id, ADR-305 /// signed device id); this crate treats the fields as opaque bounded handles /// and never invents them. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct EvidenceContext { - /// Space / room id (ADR-303). + /// Space / room id (ADR-306). pub room: String, - /// Signed device id (ADR-302). + /// Signed device id (ADR-305). pub device: String, /// Subject class where consented/available; empty means "no subject" - /// (ADR-301 §1 — subject id only where consented). + /// (ADR-304 §1 — subject id only where consented). pub subject_class: String, /// Model version that produced the inferences (ADR-136). pub model_version: String, @@ -155,7 +155,7 @@ fn check_nonempty(field: &'static str, value: &str) -> Result<(), EvidenceError> } /// The per-inference-window accuracy metrics accumulated into a record -/// (ADR-301 §1). Rates are fractions in `[0, 1]`; `drift` and `uncertainty` +/// (ADR-304 §1). Rates are fractions in `[0, 1]`; `drift` and `uncertainty` /// are non-negative finite magnitudes; `sample_count` is the number of /// inferences the record summarizes and must be at least one. #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] @@ -167,11 +167,11 @@ pub struct AccuracyMetrics { /// False-positive rate, `[0, 1]`. pub false_positive_rate: f64, /// Drift magnitude — fingerprint distance from the calibration baseline - /// (ADR-298); non-negative. + /// (ADR-301); non-negative. pub drift: f64, /// Predictive uncertainty; non-negative. pub uncertainty: f64, - /// Age of the calibration certificate in effect, seconds (ADR-298). + /// Age of the calibration certificate in effect, seconds (ADR-301). pub calibration_age_secs: u64, /// Number of inferences this record summarizes; at least one. pub sample_count: u64, @@ -213,7 +213,7 @@ fn check_magnitude(field: &'static str, v: f64) -> Result<(), EvidenceError> { Ok(()) } -/// One immutable, append-only accuracy record (ADR-301 §1). All fields are +/// One immutable, append-only accuracy record (ADR-304 §1). All fields are /// private: there is no setter and no `&mut` accessor, so a level can never be /// upgraded and a record can never be edited in place — a correction is a new /// record. Construct via [`EvidenceRecord::synthetic`], @@ -225,7 +225,7 @@ pub struct EvidenceRecord { metrics: AccuracyMetrics, level: EvidenceLevel, class: ProvenanceClass, - /// Reproducer handle for `Measured` records (ADR-300); empty otherwise. + /// Reproducer handle for `Measured` records (ADR-303); empty otherwise. reproducer: String, /// Caller-injected record time, nanoseconds. Never read from a clock here. timestamp_ns: u64, @@ -236,7 +236,7 @@ pub struct EvidenceRecord { impl EvidenceRecord { /// Mint a **synthetic** record. Class is [`ProvenanceClass::Synthetic`] and /// the evidence level is forced to [`EvidenceLevel::L0`] — synthetic input - /// is L0 by construction (ADR-301 §3) and there is no way to raise it. + /// is L0 by construction (ADR-304 §3) and there is no way to raise it. /// /// # Errors /// Propagates [`AccuracyMetrics::validate`] failures. @@ -257,7 +257,7 @@ impl EvidenceRecord { }) } - /// Mint a **claimed** record: a real inference with no ADR-300 reference + /// Mint a **claimed** record: a real inference with no ADR-303 reference /// backing its accuracy. The level is set by the caller's provenance at /// write time and is never MEASURED. A claimed record may not be minted at /// `L0`, which is reserved for synthetic input. @@ -286,7 +286,7 @@ impl EvidenceRecord { }) } - /// Mint a **measured** record: accuracy backed by an ADR-300 reference and + /// Mint a **measured** record: accuracy backed by an ADR-303 reference and /// a non-empty reproducer handle. The level is set by provenance and must /// not be `L0`. /// @@ -365,7 +365,7 @@ impl EvidenceRecord { } } -/// The append-only evidence ledger (ADR-301). The record vector is private and +/// The append-only evidence ledger (ADR-304). The record vector is private and /// exposed only through read-only queries; nothing returns a mutable reference /// to a stored record, so the append-only and no-upgrade invariants hold at the /// type level. @@ -434,7 +434,7 @@ impl EvidenceLedger { /// Query the records for exactly one context, in append order. The returned /// [`EvidenceSlice`] carries only records whose context equals `context`, - /// so aggregation over it can never mix two contexts (ADR-301 §2 — no + /// so aggregation over it can never mix two contexts (ADR-304 §2 — no /// pooling). #[must_use] pub fn query<'a>(&'a self, context: &EvidenceContext) -> EvidenceSlice<'a> { @@ -462,7 +462,7 @@ impl EvidenceLedger { } /// Summarize **each** context independently and return one summary per - /// context — never a single pooled number across contexts (ADR-301 + /// context — never a single pooled number across contexts (ADR-304 /// §Consequences: "never paper over a thin context with a global average"). #[must_use] pub fn summarize(&self) -> Vec { @@ -512,7 +512,7 @@ impl<'a> EvidenceSlice<'a> { /// function of the records (deterministic; no clock, no randomness): /// /// - An empty slice yields [`SummaryEvidence::NoEvidence`] — distinct from - /// a zero-accuracy summary (ADR-301 §3). + /// a zero-accuracy summary (ADR-304 §3). /// - The summary's evidence level is the **floor** — the minimum level over /// the records — so a slice can never report a level above its weakest /// record (the "no upgrade" honesty rule). Synthetic (L0) records pin the @@ -640,7 +640,7 @@ impl ContextSummary { /// The evidence outcome for a context: explicitly absent, or aggregated. /// /// [`SummaryEvidence::NoEvidence`] is deliberately **not** a zero-accuracy -/// summary: an empty context has *no capability*, which downstream (ADR-315) +/// summary: an empty context has *no capability*, which downstream (ADR-318) /// must not read as a `0.0` score. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub enum SummaryEvidence { diff --git a/v2/crates/ruview-fusion/src/engine.rs b/v2/crates/ruview-fusion/src/engine.rs index 2fc828f9..2d29d968 100644 --- a/v2/crates/ruview-fusion/src/engine.rs +++ b/v2/crates/ruview-fusion/src/engine.rs @@ -1,4 +1,4 @@ -//! The fusion engine (ADR-308 §2): many observations → one world state. +//! The fusion engine (ADR-311 §2): many observations → one world state. //! //! [`FusionEngine::fuse`] groups the input observations by their canonical //! container and, for each container, combines the usable presence estimates by diff --git a/v2/crates/ruview-fusion/src/estimate.rs b/v2/crates/ruview-fusion/src/estimate.rs index e141af68..fe56f81b 100644 --- a/v2/crates/ruview-fusion/src/estimate.rs +++ b/v2/crates/ruview-fusion/src/estimate.rs @@ -1,4 +1,4 @@ -//! The presence estimate and its uncertainty-aware combination (ADR-308 §2). +//! The presence estimate and its uncertainty-aware combination (ADR-311 §2). //! //! An [`Estimate`] is a single sensor's belief about zone occupancy expressed as //! a probability with a variance. Estimates combine by **inverse-variance @@ -8,7 +8,7 @@ //! (uncertain) one is down-weighted, and combining agreeing estimates *lowers* //! the fused variance (the belief sharpens). This is deliberately **not** a //! naive mean, which would ignore how certain each source is and could never -//! sharpen (ADR-308: "uncertainty-weighted ... not a silently averaged value"). +//! sharpen (ADR-311: "uncertainty-weighted ... not a silently averaged value"). use serde::{Deserialize, Serialize}; diff --git a/v2/crates/ruview-fusion/src/lib.rs b/v2/crates/ruview-fusion/src/lib.rs index 9b987951..8e50fad3 100644 --- a/v2/crates/ruview-fusion/src/lib.rs +++ b/v2/crates/ruview-fusion/src/lib.rs @@ -1,16 +1,16 @@ -//! # `ruview-fusion` — uncertainty-aware sensor fusion (ADR-308, ADR-297 §11) +//! # `ruview-fusion` — uncertainty-aware sensor fusion (ADR-311, ADR-300 §11) //! //! **Many observations resolve to one probabilistic world state, not many feeds -//! into a visualization.** This is the defining invariant of ADR-308: a +//! into a visualization.** This is the defining invariant of ADR-311: a //! dashboard that shows a WiFi layer, a mmWave layer, and a BLE layer side by //! side is not fusion — it pushes reconciliation onto the human. Real fusion //! produces *one* uncertainty-aware [`WorldState`] that every downstream -//! consumer (ADR-309 spatial memory, ADR-310 counterfactual, ADR-312 RF twin) +//! consumer (ADR-312 spatial memory, ADR-313 counterfactual, ADR-315 RF twin) //! reads, with each contributing observation's provenance and confidence still //! recoverable. //! //! [`FusionEngine`] ingests a set of [`PresenceObservation`]s — canonical -//! ADR-303 [`HalObservation`](ruview_hal::HalObservation)s paired with a +//! ADR-306 [`HalObservation`](ruview_hal::HalObservation)s paired with a //! per-source occupancy [`Claim`] — that may span modalities (WiFi/CSI, BLE, //! UWB, mmWave, …) and may conflict, and emits a single [`WorldState`]: a fused //! per-container occupancy probability with a fused variance, the set of @@ -38,7 +38,7 @@ //! and barely moves the fused value; it is down-weighted, not averaged in as //! if trustworthy. //! -//! ## When the answer is UNKNOWN (ADR-297 rule 1) +//! ## When the answer is UNKNOWN (ADR-300 rule 1) //! //! UNKNOWN is a first-class world-state value, never an error or a panic: //! @@ -54,7 +54,7 @@ //! ## Evidence and honesty discipline //! //! The fused evidence level is the **minimum** over contributing observations — -//! never lifted above the weakest necessary input (ADR-308). This crate asserts +//! never lifted above the weakest necessary input (ADR-311). This crate asserts //! **no accuracy number and makes no camera-grade claim** (CLAUDE.md, ADR-282); //! its tests use synthetic in-code fixtures only (SYNTHETIC / L0..L2). It is a //! pure, deterministic function of its inputs: no I/O, no clock, no randomness, diff --git a/v2/crates/ruview-fusion/src/observation.rs b/v2/crates/ruview-fusion/src/observation.rs index 512044cf..3dd5049a 100644 --- a/v2/crates/ruview-fusion/src/observation.rs +++ b/v2/crates/ruview-fusion/src/observation.rs @@ -1,15 +1,15 @@ //! The fusion input: a canonical HAL observation plus its presence claim -//! (ADR-308 §1). +//! (ADR-311 §1). //! //! Fusion consumes authenticated, ontology-typed observations. A //! [`HalObservation`] carries the modality, evidence level, sensor identity, -//! container, and provenance (the canonical ADR-303 vocabulary, reused rather -//! than reinvented — ADR-297 rule 3); a [`PresenceObservation`] pairs it with +//! container, and provenance (the canonical ADR-306 vocabulary, reused rather +//! than reinvented — ADR-300 rule 3); a [`PresenceObservation`] pairs it with //! that sensor's [`Claim`] about whether its container is occupied. Keeping the //! claim separate from the HAL frame lets the engine gate on the observation's //! own health: a malformed / degraded HAL observation abstains no matter what //! number it reports, and a source that cannot quantify presence says -//! [`Claim::Unknown`] rather than defaulting to a confident value (ADR-297 +//! [`Claim::Unknown`] rather than defaulting to a confident value (ADR-300 //! rule 1). use serde::{Deserialize, Serialize}; diff --git a/v2/crates/ruview-fusion/src/world.rs b/v2/crates/ruview-fusion/src/world.rs index 9f9796f8..12c19b58 100644 --- a/v2/crates/ruview-fusion/src/world.rs +++ b/v2/crates/ruview-fusion/src/world.rs @@ -1,13 +1,13 @@ -//! The fused output: one probabilistic world state (ADR-308 §3). +//! The fused output: one probabilistic world state (ADR-311 §3). //! -//! The invariant of ADR-308 is the *shape* of the output: many observations +//! The invariant of ADR-311 is the *shape* of the output: many observations //! resolve to **one** [`WorldState`], not many feeds into a visualization. A //! [`WorldState`] holds a per-container [`ZoneState`], each carrying either a //! fused [`Presence::Estimated`] belief or a first-class [`Presence::Unknown`] //! when the evidence cannot support a confident single value. Every fused value //! keeps recoverable per-observation provenance ([`Contribution`]s) and an //! aggregate evidence level that is never lifted above the weakest contributing -//! input (ADR-308: "never upgraded above the weakest contributing L-level"). +//! input (ADR-311: "never upgraded above the weakest contributing L-level"). use serde::{Deserialize, Serialize}; @@ -17,7 +17,7 @@ use ruview_ontology::{Container, EvidenceLevel, ObservationId, SensorId}; use crate::estimate::Estimate; /// Why a zone resolved to UNKNOWN instead of a confident estimate. UNKNOWN is a -/// value, not an error (ADR-297 rule 1): the reason stays legible. +/// value, not an error (ADR-300 rule 1): the reason stays legible. #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] #[serde(tag = "reason", rename_all = "snake_case")] pub enum UnknownReason { @@ -125,7 +125,7 @@ impl ZoneState { /// One probabilistic world state fused from many observations. /// -/// This is the single object every downstream consumer reads (ADR-309/310/312): +/// This is the single object every downstream consumer reads (ADR-312/310/312): /// one probabilistic world, not a modality stack. Zones are held in a /// deterministic order so the state is reproducible. #[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)] diff --git a/v2/crates/ruview-groundtruth/src/agreement.rs b/v2/crates/ruview-groundtruth/src/agreement.rs index 19da8862..0d3ac1a3 100644 --- a/v2/crates/ruview-groundtruth/src/agreement.rs +++ b/v2/crates/ruview-groundtruth/src/agreement.rs @@ -1,10 +1,10 @@ -//! Agreement as validation, not fusion (ADR-300 §3–§4). +//! Agreement as validation, not fusion (ADR-303 §3–§4). //! //! An [`AgreementReport`] compares an RF [`EstimateSeries`] against an //! independent [`ReferenceSeries`] after time alignment, computes //! modality-appropriate agreement metrics (MAE/RMSE/bias/within-tolerance for //! continuous measurands; label-agreement for categorical ones), grades the -//! result on the ADR-290/301 evidence ladder, and feeds a per-context record +//! result on the ADR-293/301 evidence ladder, and feeds a per-context record //! into the [`ruview_evidence`] ledger. Reference sensors are strictly a //! validation plane here — this crate never returns a reference reading to an //! estimator. @@ -21,8 +21,8 @@ use crate::series::{EstimateSeries, ReferenceSeries}; use crate::source::ReferenceSource; /// Map the ontology's canonical evidence ladder onto the evidence ledger's -/// (structurally identical) ladder, so the report speaks the ADR-303 vocabulary -/// while still writing an ADR-301 record. +/// (structurally identical) ladder, so the report speaks the ADR-306 vocabulary +/// while still writing an ADR-304 record. fn to_ledger_level(level: OntEvidenceLevel) -> ruview_evidence::EvidenceLevel { match level { OntEvidenceLevel::L0 => ruview_evidence::EvidenceLevel::L0, @@ -34,7 +34,7 @@ fn to_ledger_level(level: OntEvidenceLevel) -> ruview_evidence::EvidenceLevel { } } -/// The honesty grade of an agreement report (mirrors ADR-290/301). Fixed by the +/// The honesty grade of an agreement report (mirrors ADR-293/301). Fixed by the /// data provenance, the reference, coverage, paired samples, and a reproducer — /// never aliasable upward. #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] @@ -53,7 +53,7 @@ pub enum EvidenceGrade { #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "snake_case", tag = "family")] pub enum AgreementMetrics { - /// Continuous measurand agreement (ADR-290 statistics). + /// Continuous measurand agreement (ADR-293 statistics). Continuous { /// Mean absolute error. mae: f64, @@ -142,7 +142,7 @@ pub struct AgreementReport { pub metrics: AgreementMetrics, /// The honesty grade. pub grade: EvidenceGrade, - /// The evidence level (canonical ADR-303 ladder) stamped on emission. + /// The evidence level (canonical ADR-306 ladder) stamped on emission. pub evidence_level: OntEvidenceLevel, /// The reproducer handle, when the report is MEASURED. pub reproducer: Option, @@ -152,7 +152,7 @@ pub struct AgreementReport { impl AgreementReport { /// Build an agreement report. `scope` is a required argument, so a report - /// can never be constructed without it (ADR-300 §3). + /// can never be constructed without it (ADR-303 §3). /// /// The estimate and reference must describe the same measurand. `tolerance` /// is the within-tolerance band for continuous measurands (ignored for @@ -244,7 +244,7 @@ impl AgreementReport { /// [`GroundTruthError::Evidence`]. /// /// The agreement statistics (MAE/RMSE/coverage/label-agreement) live on the - /// report for the benchmark (ADR-314); the ledger record carries the + /// report for the benchmark (ADR-317); the ledger record carries the /// per-context accuracy metrics with the correct, non-upgradable grade. /// /// # Errors diff --git a/v2/crates/ruview-groundtruth/src/align.rs b/v2/crates/ruview-groundtruth/src/align.rs index b58a131c..33fc5624 100644 --- a/v2/crates/ruview-groundtruth/src/align.rs +++ b/v2/crates/ruview-groundtruth/src/align.rs @@ -1,4 +1,4 @@ -//! Deterministic time alignment (ADR-300 §2, generalizing ADR-290). +//! Deterministic time alignment (ADR-303 §2, generalizing ADR-293). //! //! Estimate and reference series rarely share a clock. This module recovers a //! **constant offset** by resampling both series onto a common grid @@ -37,7 +37,7 @@ pub struct AlignmentConfig { } impl Default for AlignmentConfig { - /// ADR-290 defaults: 1 s grid, ±30 s lag window, 2 s max gap. + /// ADR-293 defaults: 1 s grid, ±30 s lag window, 2 s max gap. fn default() -> Self { Self { grid_ms: 1_000, diff --git a/v2/crates/ruview-groundtruth/src/error.rs b/v2/crates/ruview-groundtruth/src/error.rs index 2c45e8ed..1abf28f4 100644 --- a/v2/crates/ruview-groundtruth/src/error.rs +++ b/v2/crates/ruview-groundtruth/src/error.rs @@ -1,4 +1,4 @@ -//! Boundary errors for the ground-truth validation plane (ADR-300). +//! Boundary errors for the ground-truth validation plane (ADR-303). //! //! No variant panics: malformed reference/estimate input is always a returned //! error, and UNKNOWN/uncertainty are represented as first-class *values* @@ -43,7 +43,7 @@ pub enum GroundTruthError { max: usize, }, /// Timestamps were not strictly increasing — rejected, never silently - /// sorted (ADR-290 ingest discipline). + /// sorted (ADR-293 ingest discipline). #[error("non-monotonic timestamp at sample {index}: {this_ms} does not follow {prev_ms}")] NonMonotonic { /// Index of the offending sample. diff --git a/v2/crates/ruview-groundtruth/src/lib.rs b/v2/crates/ruview-groundtruth/src/lib.rs index 56684583..8388acc9 100644 --- a/v2/crates/ruview-groundtruth/src/lib.rs +++ b/v2/crates/ruview-groundtruth/src/lib.rs @@ -1,10 +1,10 @@ -//! # `ruview-groundtruth` — reference sensors as a formal validation plane (ADR-300) +//! # `ruview-groundtruth` — reference sensors as a formal validation plane (ADR-303) //! -//! This crate generalizes the ADR-290 vitals ground-truth rig from a single +//! This crate generalizes the ADR-293 vitals ground-truth rig from a single //! measurand to **any** phenomenon RuView senses (presence, count, range, //! posture, activity, heart rate, breathing rate) and **any** reference //! modality (camera, mmWave, pressure mat, wearable, pulse oximeter, -//! microphone, manual label). Its defining design decision (ADR-300) is that +//! microphone, manual label). Its defining design decision (ADR-303) is that //! reference sensors are a **validation plane, never inference inputs**: this //! crate compares RF estimates against independent observation and never hands //! a reference reading back to an estimator. @@ -26,10 +26,10 @@ //! //! ## Honesty and determinism //! -//! - **Canonical vocabulary (ADR-297 rule 3):** the report speaks the +//! - **Canonical vocabulary (ADR-300 rule 3):** the report speaks the //! [`ruview_ontology`] evidence ladder ([`EvidenceLevel`]) and writes an //! [`ruview_evidence`] record — no per-crate reinvention of evidence shapes. -//! - **UNKNOWN is first-class (ADR-297 rule 1):** insufficient overlap yields a +//! - **UNKNOWN is first-class (ADR-300 rule 1):** insufficient overlap yields a //! report with zero pairs and a non-MEASURED grade, and an uncomputable //! alignment score is `None` — never an error, never a fabricated number. //! - **Deterministic:** no wall clock and no randomness. All timestamps are @@ -39,7 +39,7 @@ //! boundary (monotonic timestamps, finite scalars, matching reading family) //! and sample/grid/lag counts are capped so malformed input cannot exhaust //! memory. -//! - **Grade in types (ADR-290/301):** `Measured` requires an independent +//! - **Grade in types (ADR-293/301):** `Measured` requires an independent //! reference, coverage, paired samples, and a reproducer; synthetic input is //! `Synthetic`/L0 by construction and cannot be raised. @@ -65,7 +65,7 @@ pub use series::{EstimateSeries, ReferenceObservation, ReferenceSeries, MAX_SAMP pub use source::{ReferenceModality, ReferenceSource}; // The canonical evidence ladder is the ontology's, re-exported so downstream -// crates use one vocabulary (ADR-297 rule 3). +// crates use one vocabulary (ADR-300 rule 3). pub use ruview_ontology::EvidenceLevel; #[cfg(test)] diff --git a/v2/crates/ruview-groundtruth/src/model.rs b/v2/crates/ruview-groundtruth/src/model.rs index 7537a8b1..ae13c133 100644 --- a/v2/crates/ruview-groundtruth/src/model.rs +++ b/v2/crates/ruview-groundtruth/src/model.rs @@ -1,6 +1,6 @@ -//! Modality-agnostic measurands and readings (ADR-300 §1). +//! Modality-agnostic measurands and readings (ADR-303 §1). //! -//! ADR-290 built ground truth for a single measurand family (heart rate, +//! ADR-293 built ground truth for a single measurand family (heart rate, //! breathing rate). This module generalizes the *value* being compared to any //! phenomenon RuView senses — continuous scalars (vitals, count, range) and //! categorical labels (presence, activity, posture) — so the same alignment @@ -19,9 +19,9 @@ pub enum ReadingKind { } /// A phenomenon compared against an independent reference. This is the -/// modality-agnostic generalization of ADR-290's per-device measurand: the set +/// modality-agnostic generalization of ADR-293's per-device measurand: the set /// is deliberately small and closed so the agreement math per family stays -/// honest (pose keypoint PCK, which needs the ADR-288 mean-pose baseline and a +/// honest (pose keypoint PCK, which needs the ADR-291 mean-pose baseline and a /// leakage-free split, is intentionally out of scope for this crate). #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] @@ -118,7 +118,7 @@ impl Reading { /// Whether the compared data is real inference/measurement or a generated /// (SYNTHETIC/L0) fixture. This is what forces an [`crate::EvidenceGrade`] to /// `Synthetic`; it is never inferred, it is declared by the producer (mirrors -/// ADR-301's synthetic-is-L0-by-construction rule). +/// ADR-304's synthetic-is-L0-by-construction rule). #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum DataProvenance { diff --git a/v2/crates/ruview-groundtruth/src/scope.rs b/v2/crates/ruview-groundtruth/src/scope.rs index d8237b53..3e1acc0f 100644 --- a/v2/crates/ruview-groundtruth/src/scope.rs +++ b/v2/crates/ruview-groundtruth/src/scope.rs @@ -1,8 +1,8 @@ -//! Mandatory session scope (ADR-300 §3, mirroring ADR-290). +//! Mandatory session scope (ADR-303 §3, mirroring ADR-293). //! //! An agreement report without scope cannot be constructed: WiFi-sensing //! numbers without stated scope (subject count, motion, line-of-sight, -//! distance) are systematically misleading (ADR-290 Context). [`SessionScope`] +//! distance) are systematically misleading (ADR-293 Context). [`SessionScope`] //! is a required argument to [`crate::AgreementReport::build`], so the type //! system enforces the rule. diff --git a/v2/crates/ruview-groundtruth/src/series.rs b/v2/crates/ruview-groundtruth/src/series.rs index b489bf46..035451a9 100644 --- a/v2/crates/ruview-groundtruth/src/series.rs +++ b/v2/crates/ruview-groundtruth/src/series.rs @@ -1,5 +1,5 @@ //! Timestamped reference and estimate series with boundary validation -//! (ADR-300 §1, reusing ADR-290's ingest discipline). +//! (ADR-303 §1, reusing ADR-293's ingest discipline). //! //! Both a reference (independent observer) and an RF estimate are sequences of //! timestamped [`Reading`]s for one [`Measurand`]. Timestamps must be strictly diff --git a/v2/crates/ruview-groundtruth/src/source.rs b/v2/crates/ruview-groundtruth/src/source.rs index 0ab29101..e710db2f 100644 --- a/v2/crates/ruview-groundtruth/src/source.rs +++ b/v2/crates/ruview-groundtruth/src/source.rs @@ -1,7 +1,7 @@ -//! Named reference sources on the validation plane (ADR-300 §1). +//! Named reference sources on the validation plane (ADR-303 §1). //! //! A reference source is an *independent observer* used only to check RF -//! inference — never an inference input (ADR-300 Decision, option 1 rejected). +//! inference — never an inference input (ADR-303 Decision, option 1 rejected). //! It carries the modality, a named source, device metadata, and the recorded //! measurement principle so a MEASURED claim states what it was measured //! against. @@ -11,7 +11,7 @@ use serde::{Deserialize, Serialize}; use crate::error::{check_bound, check_nonempty, GroundTruthError}; /// The modality of an independent reference. Camera/mmWave references arrive as -/// exported label/keypoint streams, not live model feeds (ADR-300 §1). +/// exported label/keypoint streams, not live model feeds (ADR-303 §1). #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum ReferenceModality { diff --git a/v2/crates/ruview-hal/src/adapter.rs b/v2/crates/ruview-hal/src/adapter.rs index a961201b..3401f0c6 100644 --- a/v2/crates/ruview-hal/src/adapter.rs +++ b/v2/crates/ruview-hal/src/adapter.rs @@ -1,4 +1,4 @@ -//! The [`SensorHal`] trait (ADR-317 §1) and two deterministic reference +//! The [`SensorHal`] trait (ADR-320 §1) and two deterministic reference //! adapters. //! //! The trait is the extension point: every sensing modality lands as one @@ -8,12 +8,12 @@ //! sample into a [`HalObservation`]. `normalize` is the hardware/FFI boundary //! where untrusted input is validated (CLAUDE.md); it is **infallible** by //! design — malformed or out-of-bounds input yields an UNKNOWN-flagged -//! observation, never a panic or an error (ADR-297 rule 1). +//! observation, never a panic or an error (ADR-300 rule 1). //! //! Two reference adapters ship here, one RF (CSI) and one non-RF (IMU), per the -//! ADR-317 validation requirement of at least two modalities. Both are labelled +//! ADR-320 validation requirement of at least two modalities. Both are labelled //! SYNTHETIC / L0: they prove the abstraction, not a fielded device, and make -//! no MEASURED claim (CLAUDE.md; ADR-317 "Category and honesty discipline"). +//! no MEASURED claim (CLAUDE.md; ADR-320 "Category and honesty discipline"). use ruview_ontology::{Container, EvidenceLevel, Observation, ObservationId, SemanticProvenance, SensorId}; @@ -41,9 +41,9 @@ pub struct NormalizeCtx { /// observation. /// /// Implementations wrap existing producers — CSI (ESP32/Nexmon/FeitCSI via the -/// ADR-279 `RfFrameV2` path), 802.11bf (ADR-307), BLE, UWB, mmWave (ADR-063), +/// ADR-279 `RfFrameV2` path), 802.11bf (ADR-310), BLE, UWB, mmWave (ADR-063), /// acoustic, camera, lidar, IMU, and `custom` — behind this single trait, so -/// the world model and fusion (ADR-308) see only [`HalObservation`]s. +/// the world model and fusion (ADR-311) see only [`HalObservation`]s. pub trait SensorHal { /// The native, modality-specific raw sample type this adapter consumes. /// Kept native (not canonicalized) per the ADR-279 shared-latent lesson. @@ -176,7 +176,7 @@ pub struct ImuSample { /// A deterministic, synthetic IMU reference adapter (SYNTHETIC / L0). /// -/// The required non-RF second modality (ADR-317 validation). Demonstrates that +/// The required non-RF second modality (ADR-320 validation). Demonstrates that /// a wholly different phenomenon class lifts into the *same* canonical /// observation with its own honest evidence level — it is never lifted to /// camera- or RF-grade. diff --git a/v2/crates/ruview-hal/src/descriptor.rs b/v2/crates/ruview-hal/src/descriptor.rs index 1e5a0583..a63178da 100644 --- a/v2/crates/ruview-hal/src/descriptor.rs +++ b/v2/crates/ruview-hal/src/descriptor.rs @@ -1,4 +1,4 @@ -//! The sensor descriptor (ADR-317 §1): what a device is, in canonical terms. +//! The sensor descriptor (ADR-320 §1): what a device is, in canonical terms. //! //! A [`SensorDescriptor`] binds a HAL implementation to its ontology //! [`Sensor`](ruview_ontology::Sensor) identity, its [`Modality`], the @@ -25,7 +25,7 @@ use crate::modality::Modality; pub struct SamplingSpec { /// Native sampling rate in Hz when fixed/known. `None` is a first-class /// UNKNOWN — an event-driven or unspecified source is not an error - /// (ADR-297 rule 1). + /// (ADR-300 rule 1). #[serde(default, skip_serializing_if = "Option::is_none")] pub sample_rate_hz: Option, /// Native unit label for one raw sample (e.g. `"csi-complex"`, `"m/s^2"`, @@ -38,13 +38,13 @@ pub struct SamplingSpec { /// A canonical description of one sensing device. /// -/// Round-trips losslessly through serde so a fleet controller (ADR-313) can +/// Round-trips losslessly through serde so a fleet controller (ADR-316) can /// enumerate heterogeneous hardware uniformly. The `sensor_id` is the ontology -/// identity the device is authenticated as (ADR-302) before its observations +/// identity the device is authenticated as (ADR-305) before its observations /// are trusted. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub struct SensorDescriptor { - /// The ontology sensor identity this device is authenticated as (ADR-302). + /// The ontology sensor identity this device is authenticated as (ADR-305). pub sensor_id: SensorId, /// What phenomenon class the device senses. pub modality: Modality, diff --git a/v2/crates/ruview-hal/src/lib.rs b/v2/crates/ruview-hal/src/lib.rs index d9285bd6..cc634e47 100644 --- a/v2/crates/ruview-hal/src/lib.rs +++ b/v2/crates/ruview-hal/src/lib.rs @@ -1,4 +1,4 @@ -//! # `ruview-hal` — the RuView sensor HAL (ADR-317, ADR-297 primitive 20) +//! # `ruview-hal` — the RuView sensor HAL (ADR-320, ADR-300 primitive 20) //! //! One hardware abstraction that maps **any** sensing modality — {CSI, 802.11bf, //! BLE, UWB, mmWave, acoustic, camera, lidar, IMU, custom} — onto one canonical @@ -8,20 +8,20 @@ //! modality-specific frame, only a provenance-bearing, evidence-labelled //! observation. //! -//! This crate consumes the canonical ontology (ADR-303) — its output is an +//! This crate consumes the canonical ontology (ADR-306) — its output is an //! ontology `Observation` bound to a `Sensor` — and its observations feed real -//! sensor fusion (ADR-308). It is a **pure abstraction**: no I/O, no async, no +//! sensor fusion (ADR-311). It is a **pure abstraction**: no I/O, no async, no //! inference, no accuracy claim. A passing trait test proves the abstraction, //! not a fielded device; hardware support for any modality stays CLAIMED until //! demonstrated on real silicon with captured evidence (CLAUDE.md). //! -//! ## The four ADR-297 non-negotiable rules, as they bind this crate +//! ## The four ADR-300 non-negotiable rules, as they bind this crate //! //! 1. **UNKNOWN is first-class, never an error.** [`SensorHal::normalize`] is //! infallible: malformed / out-of-bounds raw input yields an UNKNOWN-flagged //! ([`Uncertainty::degraded`]) observation, never a panic or `Err`. //! 2. **Certificates bind cryptographically.** Out of scope for the HAL, but a -//! device is authenticated as an ADR-302 `Sensor` (the descriptor's +//! device is authenticated as an ADR-305 `Sensor` (the descriptor's //! `sensor_id`) before its observations are trusted. //! 3. **One canonical semantics downstream.** The HAL reuses the ontology's //! `Observation`, `Sensor`, `EvidenceLevel`, and `SemanticProvenance` rather @@ -57,7 +57,7 @@ //! | ESP32-S3/C6 CSI node | ADR-279 / firmware | [`Modality::Csi`] | `RfFrameV2` (subcarrier complex) | Reuses the ADR-279 native-frame → shared-latent adapter; the HAL only lifts the latent into an `Observation`. | //! | Nexmon CSI | ADR-279 | [`Modality::Csi`] | `RfFrameV2` | Per-device adapter into the shared latent; same trait, different native layout. | //! | FeitCSI / Intel / Atheros / Realtek | ADR-279 | [`Modality::Csi`] | `RfFrameV2` | Same shared-latent path; bandwidth/antenna structure kept native, not canonicalized. | -//! | 802.11bf sensing | ADR-307 (phase 2) | [`Modality::Ieee80211bf`] | native 11bf measurement frame | Enters under the same trait as it lands. | +//! | 802.11bf sensing | ADR-310 (phase 2) | [`Modality::Ieee80211bf`] | native 11bf measurement frame | Enters under the same trait as it lands. | //! | mmWave radar | ADR-063 | [`Modality::Mmwave`] | range-doppler / point frame | The ADR-063 fusion producer becomes a `SensorHal` implementation. | //! | Multistatic WiFi | ADR-029 | [`Modality::Csi`] | multi-link `RfFrameV2` set | Multiple links, one authenticated `Sensor`, one `Observation`. | //! @@ -126,7 +126,7 @@ mod tests { } } - // ADR-317 validation: descriptor round-trips losslessly through serde. + // ADR-320 validation: descriptor round-trips losslessly through serde. #[test] fn descriptor_round_trip() { for descriptor in [csi_adapter().describe(), imu_adapter().describe()] { @@ -153,7 +153,7 @@ mod tests { assert!(back.validate().is_ok()); } - // ADR-317 validation: a reference adapter normalizes a synthetic sample to a + // ADR-320 validation: a reference adapter normalizes a synthetic sample to a // uniform HalObservation carrying sensor id, container, time, exactly one // evidence level, and provenance. #[test] @@ -187,7 +187,7 @@ mod tests { assert_eq!(imu.provenance().model_version, "synthetic-imu-adapter@0"); } - // ADR-317 validation: unknown / degraded input yields an UNKNOWN-flagged + // ADR-320 validation: unknown / degraded input yields an UNKNOWN-flagged // observation, never a panic. #[test] fn degraded_input_yields_unknown_not_panic() { diff --git a/v2/crates/ruview-hal/src/modality.rs b/v2/crates/ruview-hal/src/modality.rs index 93da1301..3304c740 100644 --- a/v2/crates/ruview-hal/src/modality.rs +++ b/v2/crates/ruview-hal/src/modality.rs @@ -1,10 +1,10 @@ -//! The sensing modality tag (ADR-317 §1). +//! The sensing modality tag (ADR-320 §1). //! //! [`Modality`] enumerates the phenomenon class a sensor measures. It is the //! only place the pipeline distinguishes "how the world was sensed"; every //! modality flows through the same [`SensorHal`](crate::SensorHal) trait into //! the same canonical [`Observation`](ruview_ontology::Observation), so the -//! world model never branches on a modality-specific frame shape (ADR-297 rule +//! world model never branches on a modality-specific frame shape (ADR-300 rule //! 3: one canonical semantics downstream). use serde::{Deserialize, Serialize}; @@ -13,7 +13,7 @@ use crate::label::{validate_label, LabelError}; /// The class of physical phenomenon a sensor observes. /// -/// The closed variants cover the modalities named in ADR-317; [`Modality::Custom`] +/// The closed variants cover the modalities named in ADR-320; [`Modality::Custom`] /// is the open extension point for a modality not yet enumerated, carrying a /// validated free-form label. `Custom` is validated with [`Modality::custom`] /// (or [`Modality::validate`]) at the boundary. @@ -22,7 +22,7 @@ use crate::label::{validate_label, LabelError}; pub enum Modality { /// WiFi channel-state information (ESP32/Nexmon/FeitCSI via ADR-279). Csi, - /// IEEE 802.11bf native sensing (ADR-307, phase 2). + /// IEEE 802.11bf native sensing (ADR-310, phase 2). Ieee80211bf, /// Bluetooth Low Energy ranging / RSSI. Ble, diff --git a/v2/crates/ruview-hal/src/observation.rs b/v2/crates/ruview-hal/src/observation.rs index 78ef213f..7209c055 100644 --- a/v2/crates/ruview-hal/src/observation.rs +++ b/v2/crates/ruview-hal/src/observation.rs @@ -1,8 +1,8 @@ -//! The HAL observation (ADR-317 §2): a canonical observation plus HAL context. +//! The HAL observation (ADR-320 §2): a canonical observation plus HAL context. //! //! [`HalObservation`] wraps the canonical ontology //! [`Observation`](ruview_ontology::Observation) — reusing it rather than -//! reinventing a per-crate shape (ADR-297 rule 3) — and adds the two pieces the +//! reinventing a per-crate shape (ADR-300 rule 3) — and adds the two pieces the //! HAL boundary contributes: the [`Modality`] the measurement came through and //! a per-observation [`Uncertainty`]. The ontology `Observation` already //! carries the mandatory `EvidenceLevel` and `SemanticProvenance`, so those @@ -17,7 +17,7 @@ use crate::modality::Modality; /// A confidence value that is either a bounded scalar or first-class UNKNOWN. /// -/// UNKNOWN is a value, never an error (ADR-297 rule 1): a source that cannot +/// UNKNOWN is a value, never an error (ADR-300 rule 1): a source that cannot /// quantify its confidence says so and stays legible rather than defaulting to /// a confident number. #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] diff --git a/v2/crates/ruview-infogain/src/candidate.rs b/v2/crates/ruview-infogain/src/candidate.rs index 9a052dbc..5fb75143 100644 --- a/v2/crates/ruview-infogain/src/candidate.rs +++ b/v2/crates/ruview-infogain/src/candidate.rs @@ -1,9 +1,9 @@ -//! Candidate sensor actions the scheduler ranks (ADR-311 §1). +//! Candidate sensor actions the scheduler ranks (ADR-314 §1). //! //! **SYNTHETIC / L0 scaffold (ADR-282).** An [`ExpectedReduction`] is a *model //! prediction* of how much a not-yet-taken measurement would shrink the fused -//! covariance — in a fielded system it comes from the ADR-312 RF-twin forward -//! model evaluated against the ADR-308 covariance. It is never a measured +//! covariance — in a fielded system it comes from the ADR-315 RF-twin forward +//! model evaluated against the ADR-311 covariance. It is never a measured //! quantity: a value-of-information estimate made *before* paying for the //! measurement. No accuracy claim is made. @@ -15,7 +15,7 @@ use ruview_ontology::SensorId; use crate::cost::Cost; /// The predicted uncertainty reduction of taking one candidate measurement, -/// with UNKNOWN as a first-class value (ADR-297 rule 1). +/// with UNKNOWN as a first-class value (ADR-300 rule 1). /// /// A candidate whose informativeness the forward model cannot predict is /// [`ExpectedReduction::Unknown`] — it is **not** silently treated as zero. The @@ -25,7 +25,7 @@ use crate::cost::Cost; #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum ExpectedReduction { - /// A predicted, non-negative uncertainty reduction on the ADR-299 objective. + /// A predicted, non-negative uncertainty reduction on the ADR-302 objective. Known(f64), /// The forward model cannot predict this candidate's informativeness. Unknown, @@ -71,9 +71,9 @@ impl ExpectedReduction { /// function of its inputs and holds no cross-cycle state of its own. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub struct SensorAction { - /// The authenticated sensor identity (ADR-302) this action would sample. + /// The authenticated sensor identity (ADR-305) this action would sample. pub sensor: SensorId, - /// The sensing modality of that sensor (ADR-317). + /// The sensing modality of that sensor (ADR-320). pub modality: Modality, /// Modelled expected uncertainty reduction of taking the measurement. pub expected_reduction: ExpectedReduction, @@ -81,7 +81,7 @@ pub struct SensorAction { pub cost: Cost, /// Cycles since this sensor was last sampled, supplied by the caller. Feeds /// the sampling floor so a currently-low-value sensor is not starved into - /// permanent blindness (ADR-311 §2). `0` means "sampled last cycle". + /// permanent blindness (ADR-314 §2). `0` means "sampled last cycle". #[serde(default)] pub cycles_since_sampled: u32, } diff --git a/v2/crates/ruview-infogain/src/cost.rs b/v2/crates/ruview-infogain/src/cost.rs index 5c968f8e..af92e65a 100644 --- a/v2/crates/ruview-infogain/src/cost.rs +++ b/v2/crates/ruview-infogain/src/cost.rs @@ -1,8 +1,8 @@ -//! Cost descriptors and the deployment cost policy (ADR-311 §1). +//! Cost descriptors and the deployment cost policy (ADR-314 §1). //! //! **SYNTHETIC / L0 scaffold (ADR-282).** Every quantity here is a *modelled* //! resource figure supplied by the caller (in a fielded system, read from the -//! ADR-317 HAL descriptors); nothing in this module measures a device. No +//! ADR-320 HAL descriptors); nothing in this module measures a device. No //! `MEASURED` energy/latency/throughput claim is made or implied — a scheduler //! predicts where budget is best spent, it does not observe hardware. @@ -15,10 +15,10 @@ pub(crate) const MIN_WEIGHTED_COST: f64 = 1e-9; /// The three scarce edge resources one sensor action is modelled to consume. /// -/// These are the ADR-311 denominator terms — compute, energy, and bandwidth — -/// the three resources ADR-311 names as scarce on the ESP32-class nodes and +/// These are the ADR-314 denominator terms — compute, energy, and bandwidth — +/// the three resources ADR-314 names as scarce on the ESP32-class nodes and /// small gateways RuView targets. Values are unitless modelled magnitudes; the -/// caller supplies them (from ADR-317 HAL descriptors in a fielded system). +/// caller supplies them (from ADR-320 HAL descriptors in a fielded system). #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] pub struct Cost { /// Modelled compute cost of running the action (unitless magnitude). @@ -49,7 +49,7 @@ impl Cost { /// True when every component is finite and non-negative. A malformed cost /// (NaN/∞/negative) is not silently coerced to a number; the scheduler - /// defers such a candidate as UNKNOWN-cost rather than guessing (ADR-297 + /// defers such a candidate as UNKNOWN-cost rather than guessing (ADR-300 /// rule 1). #[must_use] pub fn is_well_formed(&self) -> bool { @@ -70,7 +70,7 @@ impl Cost { } /// The deployment cost policy: how the three cost terms are weighted into one -/// scalar denominator (ADR-311 §1). +/// scalar denominator (ADR-314 §1). /// /// The weighting is a *deployment* choice, not a hardcoded constant: a battery /// node weights energy heavily, a wired gateway weights bandwidth. The policy diff --git a/v2/crates/ruview-infogain/src/lib.rs b/v2/crates/ruview-infogain/src/lib.rs index 93be5fb6..dcdf3638 100644 --- a/v2/crates/ruview-infogain/src/lib.rs +++ b/v2/crates/ruview-infogain/src/lib.rs @@ -1,12 +1,12 @@ -//! # `ruview-infogain` — information-gain scheduler (ADR-311, ADR-297 primitive 14) +//! # `ruview-infogain` — information-gain scheduler (ADR-314, ADR-300 primitive 14) //! -//! **SYNTHETIC / L0 research-forward scaffold (ADR-282, ADR-297 phase 3).** +//! **SYNTHETIC / L0 research-forward scaffold (ADR-282, ADR-300 phase 3).** //! This crate models *which radios/modalities to spend the next sampling budget //! on* by value of information. It is a **simulation/model scaffold**: every //! informativeness estimate is a model prediction and every cost is a modelled //! magnitude. Nothing here measures hardware, and **no** `MEASURED`, accuracy, //! or energy/latency/throughput claim is made or implied — a twin predicts, it -//! does not measure (CLAUDE.md honesty discipline; ADR-311 asserts no +//! does not measure (CLAUDE.md honesty discipline; ADR-314 asserts no //! efficiency number). Any figure produced by this crate is `SYNTHETIC`. //! //! ## What it does @@ -21,11 +21,11 @@ //! //! and spends the budget on the highest-value actions, so the edge samples the //! most informative radios first. In a fielded system the numerator comes from -//! the ADR-312 RF-twin forward model against the ADR-308 fused covariance and -//! the denominator from ADR-317 HAL cost descriptors; this crate takes both as +//! the ADR-315 RF-twin forward model against the ADR-311 fused covariance and +//! the denominator from ADR-320 HAL cost descriptors; this crate takes both as //! caller-supplied inputs and stays a pure allocator. //! -//! ## The four ADR-297 non-negotiable rules, as they bind this crate +//! ## The four ADR-300 non-negotiable rules, as they bind this crate //! //! 1. **UNKNOWN is first-class, never an error.** A candidate whose //! informativeness the model cannot predict is @@ -34,20 +34,20 @@ //! malformed cost is UNKNOWN cost and defers the candidate rather than //! panicking or guessing. [`Scheduler::plan`] is total: no input panics. //! 2. **Certificates bind cryptographically.** Out of scope here; a candidate -//! names an already-authenticated ADR-302 [`SensorId`](ruview_ontology::SensorId). +//! names an already-authenticated ADR-305 [`SensorId`](ruview_ontology::SensorId). //! 3. **One canonical semantics downstream.** Candidates reuse the canonical //! [`SensorId`](ruview_ontology::SensorId) and HAL [`Modality`](ruview_hal::Modality) //! rather than reinventing per-crate identity/modality shapes. //! 4. **Honest evidence.** A scheduling decision is a resource choice, not a -//! sensing claim; the plan records which sensors were skipped so ADR-299 can +//! sensing claim; the plan records which sensors were skipped so ADR-302 can //! raise `UNKNOWN` for an under-sampled zone rather than reporting a stale //! estimate as current. //! //! ## Purity //! //! [`Scheduler::plan`] has **no** scheduling side effects: it starts no -//! sampling and touches no hardware — it returns a [`SchedulePlan`]. ADR-306 -//! active sensing chooses the probe on each selected sensor; ADR-308 fusion +//! sampling and touches no hardware — it returns a [`SchedulePlan`]. ADR-309 +//! active sensing chooses the probe on each selected sensor; ADR-311 fusion //! incorporates the result. It is deterministic (no wall clock, no randomness; //! synthetic scenes vary only by explicit caller-supplied parameters) and //! bounded in allocation. @@ -117,7 +117,7 @@ mod tests { Scheduler::new(SchedulerConfig::default()).plan(candidates, &budget) } - // ADR-311 §2: the highest value/cost candidate is ranked and selected first. + // ADR-314 §2: the highest value/cost candidate is ranked and selected first. #[test] fn highest_value_per_cost_selected_first() { let candidates = vec![ @@ -133,7 +133,7 @@ mod tests { assert!(p.deferred.is_empty()); } - // ADR-311 §1: a high-cost low-gain sensor is deferred when the budget cannot + // ADR-314 §1: a high-cost low-gain sensor is deferred when the budget cannot // hold both it and the more valuable action. #[test] fn high_cost_low_gain_deferred_under_budget() { @@ -202,7 +202,7 @@ mod tests { assert_eq!(order, vec!["cheap", "expensive"]); } - // ADR-297 rule 1: an unknown-value candidate is NOT treated as zero. Under + // ADR-300 rule 1: an unknown-value candidate is NOT treated as zero. Under // the default Defer policy it is deferred with an explicit reason. #[test] fn unknown_value_defer_policy_defers_explicitly() { @@ -217,7 +217,7 @@ mod tests { assert_eq!(p.deferred[0].reason, DeferReason::UnknownDeferred); } - // ADR-311: the Probe policy spends budget to LEARN an unknown candidate's + // ADR-314: the Probe policy spends budget to LEARN an unknown candidate's // informativeness, with an explicit synthetic probe value (not zero). #[test] fn unknown_value_probe_policy_selects_to_learn() { @@ -239,7 +239,7 @@ mod tests { assert_eq!(p.selected[0].value_density, None); } - // ADR-311 §2: the sampling floor force-includes a starved low-value sensor + // ADR-314 §2: the sampling floor force-includes a starved low-value sensor // so it is re-evaluated rather than permanently blinded. #[test] fn sampling_floor_forces_starved_low_value_sensor() { diff --git a/v2/crates/ruview-infogain/src/scheduler.rs b/v2/crates/ruview-infogain/src/scheduler.rs index 9089effd..c25c4dc6 100644 --- a/v2/crates/ruview-infogain/src/scheduler.rs +++ b/v2/crates/ruview-infogain/src/scheduler.rs @@ -1,11 +1,11 @@ //! The information-gain scheduler: rank candidates by value of information and -//! select the most informative subset under a resource budget (ADR-311 §2). +//! select the most informative subset under a resource budget (ADR-314 §2). //! //! **SYNTHETIC / L0 scaffold (ADR-282).** The scheduler emits an *allocation* //! (a [`SchedulePlan`]), never a measurement and never a sensing claim. It has //! **no** side effects: it starts no sampling, touches no hardware, and asserts -//! no efficiency figure — ADR-306 active sensing chooses the probe on each -//! selected sensor and ADR-308 fusion incorporates the result. A scheduling +//! no efficiency figure — ADR-309 active sensing chooses the probe on each +//! selected sensor and ADR-311 fusion incorporates the result. A scheduling //! decision is a resource choice, not evidence. //! //! ## Selection algorithm (documented) @@ -49,7 +49,7 @@ use crate::cost::{Cost, CostPolicy}; const BUDGET_EPSILON: f64 = 1e-9; /// How the scheduler treats a candidate with an -/// [`Unknown`](crate::ExpectedReduction::Unknown) expected reduction (ADR-311: +/// [`Unknown`](crate::ExpectedReduction::Unknown) expected reduction (ADR-314: /// unknown value is not zero value). #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "snake_case", tag = "kind")] @@ -190,9 +190,9 @@ pub struct DeferredAction { /// The scheduler's output: a pure allocation for one cycle. /// -/// Recording both `selected` and `deferred` is the ADR-311 §3 honesty +/// Recording both `selected` and `deferred` is the ADR-314 §3 honesty /// requirement — skipping a sensor is a *deliberate* reduction in coverage, so -/// downstream observability (ADR-299) can raise `UNKNOWN` for an under-sampled +/// downstream observability (ADR-302) can raise `UNKNOWN` for an under-sampled /// zone rather than reporting a stale estimate as current. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub struct SchedulePlan { @@ -222,7 +222,7 @@ impl SchedulePlan { self.selected.is_empty() } - /// The sensors actually sampled by this plan, for the ADR-311 §3 sampling + /// The sensors actually sampled by this plan, for the ADR-314 §3 sampling /// record consumed downstream. #[must_use] pub fn sampled_sensors(&self) -> Vec<&SensorId> { diff --git a/v2/crates/ruview-memory/src/anomaly.rs b/v2/crates/ruview-memory/src/anomaly.rs index e7763ea5..ab6d7384 100644 --- a/v2/crates/ruview-memory/src/anomaly.rs +++ b/v2/crates/ruview-memory/src/anomaly.rs @@ -1,12 +1,12 @@ //! Deviation categories, per-channel assessment, and the anomaly event -//! (ADR-309 §3 — anomaly = deviation from learned normal). +//! (ADR-312 §3 — anomaly = deviation from learned normal). //! //! **SYNTHETIC / L0.** An [`AnomalyEvent`] is a *model-relative* statement: a //! live value sits statistically far from the location's own learned normal. It //! is a **candidate** change to corroborate, never a confident detection and -//! never a diagnosis (ADR-282 bounded-claims discipline, ADR-297). No accuracy, +//! never a diagnosis (ADR-282 bounded-claims discipline, ADR-300). No accuracy, //! detection-rate, or false-positive number is asserted anywhere. Consistent -//! with ADR-297 rule 1, [`Assessment::Unknown`] (insufficient history) is a +//! with ADR-300 rule 1, [`Assessment::Unknown`] (insufficient history) is a //! first-class value, never an error and never a false positive. use serde::{Deserialize, Serialize}; @@ -14,7 +14,7 @@ use serde::{Deserialize, Serialize}; use ruview_evidence::{AccuracyMetrics, EvidenceContext, EvidenceError, EvidenceRecord}; use ruview_ontology::{EvidenceLevel, SemanticProvenance, ZoneId}; -/// The coarse category of a learned-normal deviation (ADR-309 §1). None of +/// The coarse category of a learned-normal deviation (ADR-312 §1). None of /// these is a labelled anomaly *class* trained from examples — each is a /// deviation from a baseline of normality, so a novel change still registers. #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] @@ -53,7 +53,7 @@ impl AnomalyKind { #[serde(tag = "status", rename_all = "snake_case")] pub enum Assessment { /// Insufficient history to judge (fewer than `min_history` updates). A - /// first-class value (ADR-297 rule 1): the channel is *not* flagged, so no + /// first-class value (ADR-300 rule 1): the channel is *not* flagged, so no /// anomaly is emitted before a baseline exists. Unknown, /// Evaluated and within normal variation (`significance < threshold`). @@ -93,7 +93,7 @@ impl Assessment { } } -/// A flagged deviation from a zone's learned normal (ADR-309 §3). +/// A flagged deviation from a zone's learned normal (ADR-312 §3). /// /// **SYNTHETIC / L0.** Carries the baseline it deviated from, the deviation /// magnitude and significance, and its evidence level — which is the floor of @@ -134,7 +134,7 @@ impl AnomalyEvent { } /// Project this anomaly into an append-only [`EvidenceRecord`] - /// (ADR-301/ADR-309: "emit anomalies as evidence records with provenance"). + /// (ADR-304/ADR-312: "emit anomalies as evidence records with provenance"). /// /// The record is always **synthetic** (forced [`ruview_evidence::EvidenceLevel::L0`]), /// keyed by context `(room = zone, device = "spatial-memory-scaffold", diff --git a/v2/crates/ruview-memory/src/baseline.rs b/v2/crates/ruview-memory/src/baseline.rs index 64b822df..f89e91f6 100644 --- a/v2/crates/ruview-memory/src/baseline.rs +++ b/v2/crates/ruview-memory/src/baseline.rs @@ -1,11 +1,11 @@ //! Configuration, the per-zone learned baseline, and the live observation -//! snapshot (ADR-309 §1–§2 — what "normal" is learned over, on the RuVector +//! snapshot (ADR-312 §1–§2 — what "normal" is learned over, on the RuVector //! temporal substrate; here a bounded in-memory scaffold). //! //! **SYNTHETIC / L0.** Every structure here is part of a simulation scaffold. A //! [`ZoneBaseline`] is a *learned model* of a location's normal physics; it //! predicts what is normal, it never measures. No value it holds is a hardware, -//! `MEASURED`, or accuracy claim (ADR-282, ADR-297). +//! `MEASURED`, or accuracy claim (ADR-282, ADR-300). use std::collections::BTreeMap; @@ -17,7 +17,7 @@ use ruview_twin::{LinkId, ObservationSet}; use crate::error::MemoryError; use crate::stat::RunningStat; -/// Hours in the occupancy-by-hour periodicity model (ADR-309 §1). +/// Hours in the occupancy-by-hour periodicity model (ADR-312 §1). pub const HOURS_PER_DAY: usize = 24; /// Upper bound on distinct zones a memory holds. Bounds allocation on untrusted @@ -44,11 +44,11 @@ pub struct MemoryConfig { pub forgetting_factor: f64, /// Minimum updates a channel needs before it is scored; below this the /// channel is [`Assessment::Unknown`](crate::Assessment::Unknown) — never a - /// false positive on thin history (ADR-297 rule 1). + /// false positive on thin history (ADR-300 rule 1). pub min_history: u32, /// Significance gate (standard deviations). A channel whose deviation meets /// or exceeds this is flagged. Not a calibrated false-alarm rate — a model - /// gate (cf. ADR-312 `DEFAULT_SIGNIFICANCE_THRESHOLD`). + /// gate (cf. ADR-315 `DEFAULT_SIGNIFICANCE_THRESHOLD`). pub significance_threshold: f64, /// Standard-deviation floor for the occupancy model, so an always-empty hour /// (zero variance) yields finite significance rather than a divide-by-zero. @@ -223,7 +223,7 @@ impl ZoneObservation { } } -/// The learned normal physics of one zone (ADR-309 §1): occupancy periodicity, +/// The learned normal physics of one zone (ADR-312 §1): occupancy periodicity, /// per-link RF propagation, and coarse per-modality signatures. /// /// **SYNTHETIC / L0.** A learned model of normality, never a measurement. diff --git a/v2/crates/ruview-memory/src/error.rs b/v2/crates/ruview-memory/src/error.rs index 9507a1d0..c90fdd4d 100644 --- a/v2/crates/ruview-memory/src/error.rs +++ b/v2/crates/ruview-memory/src/error.rs @@ -1,4 +1,4 @@ -//! Boundary errors (ADR-309 / CLAUDE.md — validate untrusted input, never +//! Boundary errors (ADR-312 / CLAUDE.md — validate untrusted input, never //! panic). //! //! Malformed input yields one of these typed errors; nothing here panics. diff --git a/v2/crates/ruview-memory/src/lib.rs b/v2/crates/ruview-memory/src/lib.rs index 419e65ff..f553ef7c 100644 --- a/v2/crates/ruview-memory/src/lib.rs +++ b/v2/crates/ruview-memory/src/lib.rs @@ -1,4 +1,4 @@ -//! # `ruview-memory` — long-term spatial memory (ADR-309, ADR-297 phase 3) +//! # `ruview-memory` — long-term spatial memory (ADR-312, ADR-300 phase 3) //! //! **SYNTHETIC / L0 — a simulation / model scaffold, not a measurement system.** //! @@ -8,17 +8,17 @@ //! **model**, not a sensor. It predicts what is normal for a place and time and //! flags a statistically significant delta; it never *measures* anything, and it //! asserts **no** detection-accuracy, false-positive, or health/safety number -//! (ADR-282 bounded-claims discipline, ADR-309 evidence discipline, CLAUDE.md +//! (ADR-282 bounded-claims discipline, ADR-312 evidence discipline, CLAUDE.md //! honesty rule). A flagged deviation is a *candidate change to corroborate*, //! never a confident detection and never a diagnosis. //! -//! Following ADR-297 rule 1, *insufficient information* is a first-class value +//! Following ADR-300 rule 1, *insufficient information* is a first-class value //! ([`Assessment::Unknown`]), never an error and never a false positive: no //! anomaly is ever flagged before a baseline exists. //! -//! ## What "normal" is learned over (ADR-309 §1) +//! ## What "normal" is learned over (ADR-312 §1) //! -//! Per ADR-303 [`ZoneId`], a [`ZoneBaseline`] accumulates: +//! Per ADR-306 [`ZoneId`], a [`ZoneBaseline`] accumulates: //! //! - **Occupancy periodicity** — a distribution of occupancy by UTC hour-of-day //! (the "bedroom usually occupied certain hours" case). @@ -35,7 +35,7 @@ //! evidence level of the observations it was learned from and is never presented //! above them (ADR-282 no-upgrade). //! -//! ## Anomaly = deviation from learned normal (ADR-309 §3) +//! ## Anomaly = deviation from learned normal (ADR-312 §3) //! //! [`SpatialMemory::observe`] scores a live [`ZoneObservation`] against the //! applicable learned baseline (matched by zone and hour), returns an @@ -44,13 +44,13 @@ //! gate. Anomalies project to append-only [`ruview_evidence`] records with //! provenance ([`AnomalyEvent::to_evidence_record`]). //! -//! ## The four ADR-297 non-negotiable rules, as they bind this crate +//! ## The four ADR-300 non-negotiable rules, as they bind this crate //! //! 1. **UNKNOWN is first-class, never an error.** A channel with fewer than //! `min_history` updates is [`Assessment::Unknown`]; `observe` is total and //! never panics on malformed input (it returns a typed [`MemoryError`]). //! 2. **Certificates bind cryptographically.** Out of scope here; a baseline is -//! keyed by an already-authenticated ADR-303 [`ZoneId`] and its evidence +//! keyed by an already-authenticated ADR-306 [`ZoneId`] and its evidence //! level is the floor of its source observations. //! 3. **One canonical semantics.** The memory reuses the canonical //! [`ZoneId`]/[`EvidenceLevel`]/[`SemanticProvenance`] vocabulary, the twin's @@ -109,7 +109,7 @@ pub use baseline::{ pub use error::MemoryError; pub use stat::RunningStat; -// Re-export the canonical vocabulary consumers speak (ADR-297 rule 3, ADR-303), +// Re-export the canonical vocabulary consumers speak (ADR-300 rule 3, ADR-306), // and the twin's link type the propagation model is keyed by. pub use ruview_ontology::{EvidenceLevel, SemanticProvenance, ZoneId}; pub use ruview_twin::LinkId; @@ -118,7 +118,7 @@ pub use ruview_twin::LinkId; const PROVENANCE_MODEL: &str = "ruview-memory@0 (SYNTHETIC/L0)"; /// The learned normal physics of every zone, and the operation that scores a -/// live snapshot against it (ADR-309). +/// live snapshot against it (ADR-312). /// /// **SYNTHETIC / L0.** A learned model of normality, never a measurement. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] @@ -160,7 +160,7 @@ impl SpatialMemory { } /// Anchor a zone's propagation baseline on a twin's expected distributions - /// (ADR-309 §1). Each link the twin can predict seeds a learned statistic + /// (ADR-312 §1). Each link the twin can predict seeds a learned statistic /// with the twin's modelled mean/variance and a prior weight of /// `min_history`, so the propagation model is usable immediately as a prior /// and then refined online. The twin prior is SYNTHETIC/L0, so the zone's @@ -191,7 +191,7 @@ impl SpatialMemory { } /// Score a live snapshot against the zone's learned normal, then fold it into - /// the baseline (ADR-309 §3). Scoring uses the baseline learned *before* this + /// the baseline (ADR-312 §3). Scoring uses the baseline learned *before* this /// snapshot, so a flagged anomaly is a genuine deviation and the current /// value does not mask itself. Deterministic; never panics on malformed /// input. @@ -321,7 +321,7 @@ impl SpatialMemory { } /// Append each anomaly in an outcome to an [`EvidenceLedger`] as a synthetic - /// record (ADR-309: "emit anomalies as evidence records with provenance"). + /// record (ADR-312: "emit anomalies as evidence records with provenance"). /// Returns the ledger sequence assigned to each record, in order. /// /// # Errors @@ -353,7 +353,7 @@ impl SpatialMemory { } /// Score one value against its (optional) learned statistic. UNKNOWN when there -/// is no statistic or its history is below `min_history` (ADR-297 rule 1). +/// is no statistic or its history is below `min_history` (ADR-300 rule 1). fn assess( stat: Option, x: f64, diff --git a/v2/crates/ruview-memory/src/stat.rs b/v2/crates/ruview-memory/src/stat.rs index 5f5eb404..34bc4923 100644 --- a/v2/crates/ruview-memory/src/stat.rs +++ b/v2/crates/ruview-memory/src/stat.rs @@ -1,11 +1,11 @@ -//! Online, forgetting running statistics (ADR-309 §2 — continuously learned +//! Online, forgetting running statistics (ADR-312 §2 — continuously learned //! baseline). //! //! **SYNTHETIC / L0.** A [`RunningStat`] is a bounded, deterministic model of a //! single scalar's *normal* value: an exponentially weighted mean and variance //! that update online with a documented **forgetting factor**. It is part of a //! simulation scaffold — it estimates a modelled normal, it never *measures* -//! anything, and it makes no accuracy claim (ADR-282 L0, ADR-297 evidence +//! anything, and it makes no accuracy claim (ADR-282 L0, ADR-300 evidence //! discipline). //! //! ## The forgetting factor @@ -25,7 +25,7 @@ //! //! The recursion keeps `var ≥ 0` exactly, so `sqrt` is always defined. There is //! no wall-clock and no randomness anywhere: the same inputs in the same order -//! always yield the same state (ADR-297 determinism discipline). +//! always yield the same state (ADR-300 determinism discipline). use serde::{Deserialize, Serialize}; @@ -58,7 +58,7 @@ impl RunningStat { } /// A statistic pre-seeded from an external prior — used to anchor a - /// propagation baseline on the twin's expected distribution (ADR-309 §1: + /// propagation baseline on the twin's expected distribution (ADR-312 §1: /// "RF-propagation baseline … via the twin's expected distributions"). /// /// `count` is the synthetic prior weight; a non-finite mean/variance is diff --git a/v2/crates/ruview-ontology/src/entity.rs b/v2/crates/ruview-ontology/src/entity.rs index 88ff20f0..0b222956 100644 --- a/v2/crates/ruview-ontology/src/entity.rs +++ b/v2/crates/ruview-ontology/src/entity.rs @@ -1,5 +1,5 @@ //! Canonical entity types: the `Site ▸ Building ▸ Floor ▸ Space ▸ Zone` -//! containment spine and the leaf entities located within it (ADR-303 §1). +//! containment spine and the leaf entities located within it (ADR-306 §1). //! //! Containment is expressed by a typed `parent` field on each spine node and a //! [`Container`] reference on each leaf. This is the pure-hierarchy analogue of @@ -50,7 +50,7 @@ pub struct Floor { pub name: String, } -/// A bounded interior space within a [`Floor`] — the ADR-294 "room" and the +/// A bounded interior space within a [`Floor`] — the ADR-297 "room" and the /// HomeCore `area_id` join point (ADR-127). #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] pub struct Space { @@ -93,12 +93,12 @@ pub enum Container { }, } -/// A physical sensing device placement — the entity ADR-302 authenticates. +/// A physical sensing device placement — the entity ADR-305 authenticates. #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] pub struct Sensor { /// Stable id. pub id: SensorId, - /// ADR-302 authenticated device identity (HomeCore `device_id`). + /// ADR-305 authenticated device identity (HomeCore `device_id`). pub device_id: String, /// Where the sensor is placed. pub located_in: Container, @@ -136,7 +136,7 @@ pub struct Object { pub provenance: SemanticProvenance, } -/// A calibrated observation produced from an authenticated frame (ADR-298). +/// A calibrated observation produced from an authenticated frame (ADR-301). #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] pub struct Observation { /// Stable id. @@ -154,7 +154,7 @@ pub struct Observation { pub provenance: SemanticProvenance, } -/// A persistent track (ADR-304), optionally resolved to a [`Person`]. +/// A persistent track (ADR-307), optionally resolved to a [`Person`]. #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] pub struct Track { /// Stable id. @@ -170,7 +170,7 @@ pub struct Track { pub provenance: SemanticProvenance, } -/// A discrete governed event (ADR-315 certified, ADR-316 witnessed). +/// A discrete governed event (ADR-318 certified, ADR-319 witnessed). #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] pub struct Event { /// Stable id. diff --git a/v2/crates/ruview-ontology/src/graph.rs b/v2/crates/ruview-ontology/src/graph.rs index 51f62eeb..afb39d6d 100644 --- a/v2/crates/ruview-ontology/src/graph.rs +++ b/v2/crates/ruview-ontology/src/graph.rs @@ -1,9 +1,9 @@ //! [`WorldGraph`] — the canonical registry that holds the containment hierarchy -//! and resolves an entity's containing [`Space`]/[`Zone`] (ADR-303 §1). +//! and resolves an entity's containing [`Space`]/[`Zone`] (ADR-306 §1). //! //! The registry is the sole insertion boundary: every `add_*` method rejects a //! duplicate id and a dangling parent/container, so the single-parent -//! containment invariants of ADR-303 hold by construction. The graph is a pure +//! containment invariants of ADR-306 hold by construction. The graph is a pure //! data structure — no I/O, no async, deterministic `BTreeMap` ordering for a //! stable canonical serialization. diff --git a/v2/crates/ruview-ontology/src/id.rs b/v2/crates/ruview-ontology/src/id.rs index 5bec0cd8..261b8816 100644 --- a/v2/crates/ruview-ontology/src/id.rs +++ b/v2/crates/ruview-ontology/src/id.rs @@ -1,9 +1,9 @@ -//! Typed, deterministic identifier scheme (ADR-303 §1). +//! Typed, deterministic identifier scheme (ADR-306 §1). //! //! Every ontology entity carries a stable, caller-provided string id wrapped in //! a distinct newtype. Ids are *never* randomly generated here: the ontology is //! a pure representation, so identity is supplied by the producing surface -//! (ADR-302 `DeviceId`, HomeCore `area_id`, tracker `track_id`, …) and only +//! (ADR-305 `DeviceId`, HomeCore `area_id`, tracker `track_id`, …) and only //! validated at the crate boundary. use serde::{Deserialize, Serialize}; @@ -105,7 +105,7 @@ typed_id!( FloorId, "floor" ); typed_id!( - /// Identifier for a [`Space`](crate::Space) (ADR-294 room / HomeCore area). + /// Identifier for a [`Space`](crate::Space) (ADR-297 room / HomeCore area). SpaceId, "space" ); typed_id!( @@ -113,7 +113,7 @@ typed_id!( ZoneId, "zone" ); typed_id!( - /// Identifier for a [`Sensor`](crate::Sensor) (ADR-302 authenticated device). + /// Identifier for a [`Sensor`](crate::Sensor) (ADR-305 authenticated device). SensorId, "sensor" ); typed_id!( @@ -129,11 +129,11 @@ typed_id!( ObservationId, "observation" ); typed_id!( - /// Identifier for a [`Track`](crate::Track) (ADR-304 persistent track). + /// Identifier for a [`Track`](crate::Track) (ADR-307 persistent track). TrackId, "track" ); typed_id!( - /// Identifier for an [`Event`](crate::Event) (ADR-315/ADR-316 governed output). + /// Identifier for an [`Event`](crate::Event) (ADR-318/ADR-319 governed output). EventId, "event" ); diff --git a/v2/crates/ruview-ontology/src/lib.rs b/v2/crates/ruview-ontology/src/lib.rs index 18f4b49f..06673b2a 100644 --- a/v2/crates/ruview-ontology/src/lib.rs +++ b/v2/crates/ruview-ontology/src/lib.rs @@ -1,4 +1,4 @@ -//! # `ruview-ontology` — the canonical spatial ontology (ADR-303, ADR-297 §6) +//! # `ruview-ontology` — the canonical spatial ontology (ADR-306, ADR-300 §6) //! //! One `Site ▸ Building ▸ Floor ▸ Space ▸ Zone` containment model, plus the //! leaf entities `Sensor`, `Person`, `Object`, `Observation`, `Track`, and @@ -9,7 +9,7 @@ //! //! This crate is a **pure data / relationship representation**: no I/O, no //! async, no inference. It says nothing about *how* a `Track` or `Event` is -//! produced (that is owned by ADR-298/ADR-304/ADR-299) and makes no accuracy +//! produced (that is owned by ADR-301/ADR-307/ADR-302) and makes no accuracy //! claim. Identity is caller-supplied and deterministic — ids are never //! randomly generated here. //! @@ -62,7 +62,7 @@ //! //! ## Migration path from existing per-surface shapes (docs only) //! -//! ADR-303 §3 requires a documented, tested bidirectional mapping from each +//! ADR-306 §3 requires a documented, tested bidirectional mapping from each //! existing per-surface schema onto these canonical types. This crate does not //! edit those surfaces; the mappings below are the contract each surface's //! projection implements when it is cut over (one surface at a time). Until a @@ -71,8 +71,8 @@ //! //! | Legacy shape | Source | Canonical target | //! |---|---|---| -//! | `NodeInference` | ADR-294 MQTT/HA mapper | `Sensor` + an `Observation` whose `sensor` is that node; node-vs-room separation is preserved because the observation is sensor-scoped, not space-scoped. | -//! | `RoomInference` | ADR-294 MQTT/HA mapper | The `Space`-level fused inference: a `Person`/`Track` (or `Event`) whose `located_in` is `Container::Space`. `RoomInference.area_id` ↦ [`Space::area_id`]. | +//! | `NodeInference` | ADR-297 MQTT/HA mapper | `Sensor` + an `Observation` whose `sensor` is that node; node-vs-room separation is preserved because the observation is sensor-scoped, not space-scoped. | +//! | `RoomInference` | ADR-297 MQTT/HA mapper | The `Space`-level fused inference: a `Person`/`Track` (or `Event`) whose `located_in` is `Container::Space`. `RoomInference.area_id` ↦ [`Space::area_id`]. | //! | `WorldNode::Room { area_id, name, floor }` | `worldgraph` | [`Space`] (`area_id`, `name` retained; `floor` index ↦ the parent [`Floor::level`]). | //! | `WorldNode::Zone { parent_room }` | `worldgraph` | [`Zone`] (`parent_room` ↦ [`Zone::parent`]). | //! | `WorldNode::Sensor { device_id, modality }` | `worldgraph` | [`Sensor`] (`device_id` retained; placement ↦ its [`Container`]). | diff --git a/v2/crates/ruview-ontology/src/provenance.rs b/v2/crates/ruview-ontology/src/provenance.rs index f20657bd..59bd141b 100644 --- a/v2/crates/ruview-ontology/src/provenance.rs +++ b/v2/crates/ruview-ontology/src/provenance.rs @@ -1,4 +1,4 @@ -//! Evidence ladder and provenance carried by every fact (ADR-303 §2, ADR-282). +//! Evidence ladder and provenance carried by every fact (ADR-306 §2, ADR-282). //! //! The ontology mandates that a fact cannot cross a surface boundary and lose //! its lineage: every leaf entity carries exactly one [`EvidenceLevel`] plus a @@ -22,7 +22,7 @@ pub enum EvidenceLevel { L3, /// L4 — calibrated and held-out validated. L4, - /// L5 — witnessed / certified (ADR-316). + /// L5 — witnessed / certified (ADR-319). L5, } @@ -36,7 +36,7 @@ pub struct SemanticProvenance { pub evidence: Vec, /// Model version that produced the fact (ADR-136). pub model_version: String, - /// Calibration baseline in effect (ADR-135/ADR-298). + /// Calibration baseline in effect (ADR-135/ADR-301). pub calibration_version: String, /// Privacy decision the fact was derived under (ADR-141). pub privacy_decision: String, diff --git a/v2/crates/ruview-ood/src/certificate.rs b/v2/crates/ruview-ood/src/certificate.rs index f0196793..29ce0efa 100644 --- a/v2/crates/ruview-ood/src/certificate.rs +++ b/v2/crates/ruview-ood/src/certificate.rs @@ -1,13 +1,13 @@ -//! Cross-ADR adapter: turn an ADR-298 [`CalibrationCertificate`] plus a live +//! Cross-ADR adapter: turn an ADR-301 [`CalibrationCertificate`] plus a live //! fingerprint into the two OOD inputs it governs — the [`FingerprintDistance`] -//! and the [`CalibrationCompat`] (ADR-299 §1 inputs 1 and 3). +//! and the [`CalibrationCompat`] (ADR-302 §1 inputs 1 and 3). //! //! This is the point where certificate *staleness* becomes a domain signal: //! an expired, tampered, drifted, or identity-mismatched certificate maps to a //! non-`Valid` compatibility, which the state machine drives straight to -//! UNKNOWN (ADR-297 staleness guard). Absence of a certificate is handled by +//! UNKNOWN (ADR-300 staleness guard). Absence of a certificate is handled by //! [`no_certificate`] and likewise defaults to UNKNOWN — absence of evidence is -//! absence of capability (ADR-299 §3). +//! absence of capability (ADR-302 §3). use wifi_densepose_calibration::certificate::{ CalibrationCertificate, CertificateStatus, CertificateVerifier, FingerprintDistance, RoomFingerprint, @@ -16,7 +16,7 @@ use wifi_densepose_calibration::certificate::{ use crate::domain::CalibrationCompat; /// Identity the live inference expects the certificate to attest: which space -/// (ADR-303) and which signed device (ADR-302). Validated before the +/// (ADR-306) and which signed device (ADR-305). Validated before the /// certificate's own status, so a certificate for the wrong room/device can /// never present as compatible. #[derive(Debug, Clone, Copy, PartialEq, Eq)] @@ -35,7 +35,7 @@ pub struct ExpectedIdentity<'a> { /// certificate-fingerprint-vs-live distance, computed even for a stale/tampered /// certificate so the drift is still reported. /// -/// Precedence mirrors ADR-298 `status()` but adds the identity checks first: +/// Precedence mirrors ADR-301 `status()` but adds the identity checks first: /// space mismatch → device mismatch → tampered → expired → drifted → valid. pub fn assess_certificate( cert: &CalibrationCertificate, @@ -46,7 +46,7 @@ pub fn assess_certificate( ) -> (FingerprintDistance, CalibrationCompat) { let distance = cert.fingerprint.distance(live); - // Identity binding first (ADR-302/303): a certificate for the wrong + // Identity binding first (ADR-305/303): a certificate for the wrong // space/device is incompatible regardless of its own validity. if cert.space_id != expected.space_id { return (distance, CalibrationCompat::SpaceMismatch); @@ -65,7 +65,7 @@ pub fn assess_certificate( } /// The compatibility for a space/device with **no** certificate present. Always -/// [`CalibrationCompat::Absent`], which the gate treats as UNKNOWN (ADR-299 §3: +/// [`CalibrationCompat::Absent`], which the gate treats as UNKNOWN (ADR-302 §3: /// the default state without a valid certificate is UNKNOWN, not KNOWN). pub fn no_certificate() -> CalibrationCompat { CalibrationCompat::Absent diff --git a/v2/crates/ruview-ood/src/domain.rs b/v2/crates/ruview-ood/src/domain.rs index 9800a9fb..faf7915a 100644 --- a/v2/crates/ruview-ood/src/domain.rs +++ b/v2/crates/ruview-ood/src/domain.rs @@ -1,16 +1,16 @@ //! The domain-state machine: KNOWN → DEGRADED → UNKNOWN. //! -//! Implements the ADR-297 staleness guard `VALID → DEGRADED → UNKNOWN` as a -//! **pure** classification over four measured inputs (ADR-299 §1): +//! Implements the ADR-300 staleness guard `VALID → DEGRADED → UNKNOWN` as a +//! **pure** classification over four measured inputs (ADR-302 §1): //! //! 1. **domain distance** — [`FingerprintDistance`] of the live fingerprint vs -//! the certified one (ADR-298 `distance()`); +//! the certified one (ADR-301 `distance()`); //! 2. **signal quality** — [`SignalQuality`] (ADR-137 coherence/contradiction //! plus per-frame validity); //! 3. **calibration compatibility** — [`CalibrationCompat`]: is a valid, //! non-invalidated, device/space-matched certificate present? //! -//! (The model's own predictive **uncertainty** — the fourth ADR-299 input — is +//! (The model's own predictive **uncertainty** — the fourth ADR-302 input — is //! attached and acted on at the [`crate::InferenceGate`], keeping `classify`'s //! signature exactly the three-plus-envelope form the phase-1 spec pins.) //! @@ -24,10 +24,10 @@ use wifi_densepose_calibration::certificate::{CompatibilityEnvelope, Fingerprint use crate::error::{require_unit_interval, Result}; -/// The domain-distance primitive (ADR-299 §1): drift of the **live** room +/// The domain-distance primitive (ADR-302 §1): drift of the **live** room /// fingerprint away from the **certified** reference distribution. /// -/// Reuses the calibration crate's [`FingerprintDistance`] (ADR-298), which +/// Reuses the calibration crate's [`FingerprintDistance`] (ADR-301), which /// already splits drift into an empty-baseline (geometry) component and an /// occupancy component, so a consumer can distinguish "the room itself changed" /// from "occupancy statistics changed". This is a thin, documented adapter — no @@ -40,19 +40,19 @@ pub fn domain_distance(certified: &RoomFingerprint, live: &RoomFingerprint) -> F } /// The specific reason a domain left KNOWN. Always reported alongside the state -/// (ADR-299: "never a bare label"). +/// (ADR-302: "never a bare label"). #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] pub enum DomainCause { // --- UNKNOWN-grade causes (hard) --- /// No calibration certificate is present for this space/device. NoCertificate, - /// The certificate is past its expiry (stale — ADR-297 staleness guard). + /// The certificate is past its expiry (stale — ADR-300 staleness guard). CertificateExpired, /// The certificate's signature did not verify (tamper). CertificateTampered, - /// The certificate was minted by a different signed device (ADR-302). + /// The certificate was minted by a different signed device (ADR-305). DeviceMismatch, - /// The certificate attests a different space (ADR-303). + /// The certificate attests a different space (ADR-306). SpaceMismatch, /// Empty-baseline / total drift crossed the **outer** envelope threshold — /// the room changed materially (furniture, AP channel, geometry). @@ -72,7 +72,7 @@ pub enum DomainCause { } impl DomainCause { - /// A stable machine-readable slug for evidence records (ADR-301). + /// A stable machine-readable slug for evidence records (ADR-304). pub fn as_str(self) -> &'static str { match self { DomainCause::NoCertificate => "no_certificate", @@ -90,7 +90,7 @@ impl DomainCause { } } -/// The gate's decision for one inference (ADR-299 §2). +/// The gate's decision for one inference (ADR-302 §2). /// /// `DEGRADED` and `UNKNOWN` always carry the triggering [`DomainCause`]; a bare /// state is never produced. @@ -104,7 +104,7 @@ pub enum DomainState { Degraded(DomainCause), /// The room changed materially or calibration is absent/stale. RuView stops /// returning confident classifications. This is required behavior, not an - /// error (ADR-297 rule 1). + /// error (ADR-300 rule 1). Unknown(DomainCause), } @@ -132,7 +132,7 @@ impl DomainState { } } - /// Pure classification with the default thresholds (ADR-299 §2). This is the + /// Pure classification with the default thresholds (ADR-302 §2). This is the /// canonical `classify(distance, envelope, signal_quality, calibration_compat)` /// entry point: it takes only measured inputs and returns a state — no clock, /// no randomness, no allocation. @@ -196,7 +196,7 @@ impl SignalQuality { } /// Whether a valid, non-invalidated calibration certificate is present for this -/// space and signed device (ADR-299 §1 input 3). Derived from an ADR-298 +/// space and signed device (ADR-302 §1 input 3). Derived from an ADR-301 /// [`CertificateStatus`](wifi_densepose_calibration::certificate::CertificateStatus) /// plus space/device identity checks; see [`crate::assess_certificate`]. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] @@ -225,7 +225,7 @@ impl CalibrationCompat { /// The hard (UNKNOWN-grade) cause this compatibility state implies, if any. /// A non-`Valid` compatibility is always a hard failure: a stale, absent, - /// or mismatched certificate cannot support a KNOWN domain (ADR-299 §3, + /// or mismatched certificate cannot support a KNOWN domain (ADR-302 §3, /// "absence of evidence is absence of capability"). fn hard_cause(self) -> Option { match self { @@ -240,7 +240,7 @@ impl CalibrationCompat { } } -/// The gate's calibration thresholds (ADR-299 §2). These are the "calibration +/// The gate's calibration thresholds (ADR-302 §2). These are the "calibration /// parameters, reported with each decision" the ADR requires — not baked-in /// magic numbers. All are validated at construction. /// @@ -299,7 +299,7 @@ impl DomainThresholds { }) } - /// Pure classification (ADR-297 staleness guard `VALID → DEGRADED → + /// Pure classification (ADR-300 staleness guard `VALID → DEGRADED → /// UNKNOWN`). Monotone escalation: the first matching hard cause wins /// UNKNOWN; otherwise the first matching soft cause wins DEGRADED; else /// KNOWN. Deterministic, allocation-free, no clock. diff --git a/v2/crates/ruview-ood/src/error.rs b/v2/crates/ruview-ood/src/error.rs index a1ef98a0..75c3a580 100644 --- a/v2/crates/ruview-ood/src/error.rs +++ b/v2/crates/ruview-ood/src/error.rs @@ -3,7 +3,7 @@ //! Errors are raised only when *configuration* input is malformed (a threshold //! outside its valid range, a non-finite quality score). Runtime domain //! ambiguity is **never** an error: it is the first-class [`DomainState::Unknown`] -//! value (ADR-297 rule 1). Nothing in this crate panics on malformed runtime +//! value (ADR-300 rule 1). Nothing in this crate panics on malformed runtime //! input. //! //! [`DomainState::Unknown`]: crate::DomainState::Unknown diff --git a/v2/crates/ruview-ood/src/gate.rs b/v2/crates/ruview-ood/src/gate.rs index 0a42ac0b..07d89685 100644 --- a/v2/crates/ruview-ood/src/gate.rs +++ b/v2/crates/ruview-ood/src/gate.rs @@ -1,18 +1,18 @@ -//! The inference gate (ADR-299 §2, ADR-297 rule 1). +//! The inference gate (ADR-302 §2, ADR-300 rule 1). //! //! Every inference passes through the gate. It: //! //! 1. classifies the domain from distance + envelope + signal quality + //! calibration compatibility; -//! 2. attaches the model's own predictive **uncertainty** (the fourth ADR-299 +//! 2. attaches the model's own predictive **uncertainty** (the fourth ADR-302 //! input), escalating a KNOWN domain to DEGRADED when uncertainty is //! elevated; //! 3. **suppresses the confident class** when the domain is not KNOWN — an //! UNKNOWN domain returns no class, a first-class value rather than a -//! confidently-wrong label (ADR-297 rule 1); +//! confidently-wrong label (ADR-300 rule 1); //! 4. emits a [`RecalibrationRequest`] whenever the state is DEGRADED or //! UNKNOWN — a *signal*, never an action; recalibration itself is out of -//! scope for this crate (ADR-297 staleness guard). +//! scope for this crate (ADR-300 staleness guard). use serde::{Deserialize, Serialize}; use wifi_densepose_calibration::certificate::{CompatibilityEnvelope, FingerprintDistance}; @@ -54,9 +54,9 @@ pub enum RecalibrationUrgency { Required, } -/// A signal that recalibration should be triggered (ADR-299 §2 / ADR-297 +/// A signal that recalibration should be triggered (ADR-302 §2 / ADR-300 /// staleness guard). This crate **emits** the request; it never performs -/// recalibration (that is ADR-298's job). Carries the triggering cause so the +/// recalibration (that is ADR-301's job). Carries the triggering cause so the /// caller can route it. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] pub struct RecalibrationRequest { @@ -68,22 +68,22 @@ pub struct RecalibrationRequest { /// The fully-contextualized result of gating one inference. Carries the domain /// state, all four input measurements, and either a (flagged) class or none — -/// so downstream consumers (ADR-301 evidence engine) get the whole decision, +/// so downstream consumers (ADR-304 evidence engine) get the whole decision, /// never a bare label. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub struct GatedInference { /// The domain state (KNOWN / DEGRADED / UNKNOWN + cause). pub state: DomainState, - /// Live-vs-certified domain distance (ADR-299 input 1). + /// Live-vs-certified domain distance (ADR-302 input 1). pub distance: FingerprintDistance, - /// Signal quality (ADR-299 input 2). + /// Signal quality (ADR-302 input 2). pub signal_quality: SignalQuality, - /// Calibration compatibility (ADR-299 input 3). + /// Calibration compatibility (ADR-302 input 3). pub calibration_compat: CalibrationCompat, - /// Model predictive uncertainty, sanitized to `[0, 1]` (ADR-299 input 4). + /// Model predictive uncertainty, sanitized to `[0, 1]` (ADR-302 input 4). pub uncertainty: f32, /// The returned class. `None` in UNKNOWN — the confident label is - /// suppressed (ADR-297 rule 1). `Some` in KNOWN and DEGRADED (flagged). + /// suppressed (ADR-300 rule 1). `Some` in KNOWN and DEGRADED (flagged). pub class: Option, /// Sanitized confidence, present iff a class is returned. pub confidence: Option, @@ -98,12 +98,12 @@ impl GatedInference { } } -/// The shared OOD gate every inference routes through (ADR-299 §2). +/// The shared OOD gate every inference routes through (ADR-302 §2). #[derive(Debug, Clone, Copy, PartialEq)] pub struct InferenceGate { thresholds: DomainThresholds, /// Max uncertainty tolerated while KNOWN; above it, a KNOWN domain is - /// escalated to DEGRADED (the fourth ADR-299 input acting on the state). + /// escalated to DEGRADED (the fourth ADR-302 input acting on the state). max_uncertainty_known: f32, } @@ -126,7 +126,7 @@ impl InferenceGate { }) } - /// The thresholds in effect (reported with each decision per ADR-299 §2). + /// The thresholds in effect (reported with each decision per ADR-302 §2). pub fn thresholds(&self) -> DomainThresholds { self.thresholds } @@ -171,7 +171,7 @@ impl InferenceGate { urgency: RecalibrationUrgency::Recommended, }), ), - // ADR-297 rule 1: no confident class in UNKNOWN. The class is + // ADR-300 rule 1: no confident class in UNKNOWN. The class is // dropped, not returned with lowered confidence. DomainState::Unknown(reason) => ( None, diff --git a/v2/crates/ruview-ood/src/lib.rs b/v2/crates/ruview-ood/src/lib.rs index 22d47067..2d658222 100644 --- a/v2/crates/ruview-ood/src/lib.rs +++ b/v2/crates/ruview-ood/src/lib.rs @@ -1,22 +1,22 @@ -//! # ruview-ood — out-of-distribution detection (ADR-299) +//! # ruview-ood — out-of-distribution detection (ADR-302) //! -//! Primitive 2 of the ADR-297 perception substrate: the gate that attaches a +//! Primitive 2 of the ADR-300 perception substrate: the gate that attaches a //! [`DomainState`] — `KNOWN` / `DEGRADED` / `UNKNOWN` — to **every** inference, //! so RuView can say *"I do not recognize this situation"* instead of returning //! a confidently-wrong label when it leaves its calibrated domain. //! -//! It fuses four measured inputs (ADR-299 §1) against the ADR-298 +//! It fuses four measured inputs (ADR-302 §1) against the ADR-301 //! [`CalibrationCertificate`](wifi_densepose_calibration::certificate::CalibrationCertificate): //! //! 1. **domain distance** — [`domain_distance`] over live vs certified -//! fingerprints (reusing ADR-298's [`FingerprintDistance`]); +//! fingerprints (reusing ADR-301's [`FingerprintDistance`]); //! 2. **signal quality** — [`SignalQuality`] (ADR-137); //! 3. **calibration compatibility** — [`CalibrationCompat`], derived from a //! certificate via [`assess_certificate`] / [`no_certificate`]; //! 4. **uncertainty** — the model head's own predictive uncertainty, attached //! at the [`InferenceGate`]. //! -//! ## The four non-negotiable rules (ADR-297) +//! ## The four non-negotiable rules (ADR-300) //! //! - **UNKNOWN is a first-class value, never an error.** [`DomainState::Unknown`] //! is returned, not thrown; the gate suppresses the confident class rather @@ -269,7 +269,7 @@ mod tests { CalibrationCompat::Valid, ); assert!(out.state.is_unknown()); - // ADR-297 rule 1: no confident class survives an UNKNOWN domain. + // ADR-300 rule 1: no confident class survives an UNKNOWN domain. assert_eq!(out.class, None); assert_eq!(out.confidence, None); assert!(!out.is_confident()); @@ -429,7 +429,7 @@ mod tests { assert!((0.0..=1.0).contains(&q2.score)); } - // --- cross-ADR: consume a real ADR-298 certificate -------------------- + // --- cross-ADR: consume a real ADR-301 certificate -------------------- fn af(label: AnchorLabel, mean: f32, variance: f32, motion: f32) -> AnchorFeature { AnchorFeature { diff --git a/v2/crates/ruview-placement/src/compare.rs b/v2/crates/ruview-placement/src/compare.rs index e6f496bb..0b81a84f 100644 --- a/v2/crates/ruview-placement/src/compare.rs +++ b/v2/crates/ruview-placement/src/compare.rs @@ -1,14 +1,14 @@ //! Post-install loop: predicted vs. measured observability → adjustments -//! (ADR-305 §3). +//! (ADR-308 §3). //! //! **This crate never measures.** The `measured` observability values are -//! supplied by the caller — the ADR-299 runtime observability signal from freshly +//! supplied by the caller — the ADR-302 runtime observability signal from freshly //! enrolled, calibrated sensors — and this module only *compares* them against the //! optimizer's own SYNTHETIC/L0 prediction. The predicted side stays labelled //! `L0`; a `MEASURED` statement, if any, belongs to the caller's measured input //! together with its reproducer (CLAUDE.md hardware rule). Where measurement //! disagrees with prediction, the module recommends an adjustment and a coarse -//! twin-parameter residual to feed back into the ADR-312 twin. Following ADR-297 +//! twin-parameter residual to feed back into the ADR-315 twin. Following ADR-300 //! rule 1, a target with no measured value yields a first-class UNKNOWN verdict, //! never an error. @@ -23,7 +23,7 @@ use crate::coverage::{Observability, PlacementScore}; pub const DEFAULT_COMPARE_TOLERANCE: f64 = 0.15; /// Coarse dB of implied effective attenuation per unit of observability shortfall, -/// used only to suggest a twin-parameter residual to feed back into ADR-312. A +/// used only to suggest a twin-parameter residual to feed back into ADR-315. A /// rough SYNTHETIC heuristic, not a calibrated figure. const RESIDUAL_DB_PER_UNIT: f64 = 30.0; @@ -81,7 +81,7 @@ pub enum CompareVerdict { /// Measured is materially above predicted (the model was pessimistic). Overperforming, /// Cannot compare (no measured value, or prediction was UNKNOWN). First-class - /// UNKNOWN (ADR-297 rule 1). + /// UNKNOWN (ADR-300 rule 1). Unknown, } @@ -112,7 +112,7 @@ pub enum ResidualKind { EffectiveAttenuationLower, } -/// A coarse twin-parameter residual to feed back into the ADR-312 twin. +/// A coarse twin-parameter residual to feed back into the ADR-315 twin. /// /// **SYNTHETIC / L0.** A rough model-improvement hint, not a calibrated value. #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] @@ -132,7 +132,7 @@ pub struct Adjustment { pub action: AdjustmentAction, /// Human-readable rationale. pub rationale: String, - /// Coarse twin-parameter residual to feed back into ADR-312, if any. + /// Coarse twin-parameter residual to feed back into ADR-315, if any. #[serde(default, skip_serializing_if = "Option::is_none")] pub twin_residual: Option, } @@ -194,7 +194,7 @@ pub fn compare_post_install( /// /// Deterministic and never panics. A target whose prediction is UNKNOWN, or that /// has no measured value, yields a [`CompareVerdict::Unknown`] and an -/// [`AdjustmentAction::InsufficientData`] recommendation (ADR-297 rule 1). +/// [`AdjustmentAction::InsufficientData`] recommendation (ADR-300 rule 1). #[must_use] pub fn compare_post_install_with_tolerance( predicted: &PlacementScore, diff --git a/v2/crates/ruview-placement/src/coverage.rs b/v2/crates/ruview-placement/src/coverage.rs index 68834634..f2797a62 100644 --- a/v2/crates/ruview-placement/src/coverage.rs +++ b/v2/crates/ruview-placement/src/coverage.rs @@ -1,13 +1,13 @@ -//! Coverage / observability scoring of a candidate placement (ADR-305 §2). +//! Coverage / observability scoring of a candidate placement (ADR-308 §2). //! //! **SYNTHETIC / L0.** Everything here is a *recommendation derived from a //! simulation*, never a sensing claim. A candidate placement is scored by -//! consuming the ADR-312 [`RfTwin`] forward model: for a grid of sample points in +//! consuming the ADR-315 [`RfTwin`] forward model: for a grid of sample points in //! a target region, a point is "observable" when it lies inside the first Fresnel //! zone of a well-predicted link ([`crate::fresnel`]). Per target we report an //! [`Observability`] carrying **both** a modelled score and its uncertainty — -//! never a single confident number for a simulated result (ADR-305 §2). Following -//! ADR-297 rule 1, a target the model cannot evaluate is [`Observability::Unknown`], +//! never a single confident number for a simulated result (ADR-308 §2). Following +//! ADR-300 rule 1, a target the model cannot evaluate is [`Observability::Unknown`], //! a first-class value, not an error. use serde::{Deserialize, Serialize}; @@ -210,7 +210,7 @@ impl PlacementParams { } /// Why a target's observability is unknown. UNKNOWN is a first-class output -/// (ADR-297 rule 1), not an error. +/// (ADR-300 rule 1), not an error. #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum ObservabilityUnknown { diff --git a/v2/crates/ruview-placement/src/fresnel.rs b/v2/crates/ruview-placement/src/fresnel.rs index 05d4c8c9..c7b89f78 100644 --- a/v2/crates/ruview-placement/src/fresnel.rs +++ b/v2/crates/ruview-placement/src/fresnel.rs @@ -1,4 +1,4 @@ -//! Fresnel-zone geometry for link observability (ADR-305 §2). +//! Fresnel-zone geometry for link observability (ADR-308 §2). //! //! **SYNTHETIC / L0.** WiFi sensing perturbs a link when the target sits inside //! the link's first Fresnel zone. This module implements that geometry as a diff --git a/v2/crates/ruview-placement/src/geometry.rs b/v2/crates/ruview-placement/src/geometry.rs index b6e50e9e..f2192cf8 100644 --- a/v2/crates/ruview-placement/src/geometry.rs +++ b/v2/crates/ruview-placement/src/geometry.rs @@ -1,12 +1,12 @@ -//! Coarse 2D floor-plan geometry the optimizer plans over (ADR-305 §1). +//! Coarse 2D floor-plan geometry the optimizer plans over (ADR-308 §1). //! -//! **SYNTHETIC / L0.** This is a deliberately coarse stand-in for the ADR-303 +//! **SYNTHETIC / L0.** This is a deliberately coarse stand-in for the ADR-306 //! scene: axis-aligned rectangular [`Rect`] bounds for a [`Space`](ruview_ontology::Space) //! and its [`Zone`](ruview_ontology::Zone)s, plus attenuating [`Wall`] segments //! (reused from the twin). It is a *model* of a room, never a surveyed floor //! plan, and it makes no measurement or accuracy claim. Geometry references the //! canonical ontology vocabulary ([`SpaceId`], [`ZoneId`], [`Container`]); it -//! does not invent a second identity scheme (ADR-297 rule 3). +//! does not invent a second identity scheme (ADR-300 rule 3). use serde::{Deserialize, Serialize}; use thiserror::Error; @@ -77,7 +77,7 @@ impl Rect { /// A zone footprint within a floor plan's space. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub struct ZoneGeometry { - /// Ontology zone id (ADR-303). + /// Ontology zone id (ADR-306). pub id: ZoneId, /// The zone's rectangular footprint. pub bounds: Rect, @@ -133,7 +133,7 @@ impl FloorPlan { /// Resolve the rectangular region a [`Container`] targets, if present in this /// plan. A first-class `None` (never an error) when the target is not in the - /// plan (ADR-297 rule 1 — the caller surfaces it as UNKNOWN). + /// plan (ADR-300 rule 1 — the caller surfaces it as UNKNOWN). #[must_use] pub fn region_for(&self, target: &Container) -> Option { match target { diff --git a/v2/crates/ruview-placement/src/inventory.rs b/v2/crates/ruview-placement/src/inventory.rs index a2315460..e66c3ca6 100644 --- a/v2/crates/ruview-placement/src/inventory.rs +++ b/v2/crates/ruview-placement/src/inventory.rs @@ -1,4 +1,4 @@ -//! Hardware inventory: the radios available to place (ADR-305 §1). +//! Hardware inventory: the radios available to place (ADR-308 §1). //! //! **SYNTHETIC / L0.** A coarse description of available hardware — each entry is //! one physical radio the installer can place, with a modelled transmit power and @@ -18,7 +18,7 @@ pub const MAX_INVENTORY: usize = 64; /// carrying it through so a recommendation names the hardware it plans for. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub struct RadioSpec { - /// Coarse hardware/capability label (ADR-315/ADR-317 descriptor handle). + /// Coarse hardware/capability label (ADR-318/ADR-320 descriptor handle). pub model: String, /// Modelled transmit power, dBm. A SYNTHETIC parameter of the forward model. pub tx_power_dbm: f64, diff --git a/v2/crates/ruview-placement/src/lib.rs b/v2/crates/ruview-placement/src/lib.rs index a429cd2a..be1a5bc8 100644 --- a/v2/crates/ruview-placement/src/lib.rs +++ b/v2/crates/ruview-placement/src/lib.rs @@ -1,18 +1,18 @@ -//! # `ruview-placement` — sensor placement optimizer (ADR-305, ADR-297 phase 3) +//! # `ruview-placement` — sensor placement optimizer (ADR-308, ADR-300 phase 3) //! //! **SYNTHETIC / L0 — a planning scaffold, not a measurement system.** //! //! This crate is a *research-forward primitive*: given a coarse floor plan -//! ([`FloorPlan`], an ADR-303 scene abstraction) and a hardware [`Inventory`], it +//! ([`FloorPlan`], an ADR-306 scene abstraction) and a hardware [`Inventory`], it //! recommends radio-node positions by scoring candidate placements against the -//! ADR-312 RF twin's **SYNTHETIC** propagation model. Every coverage and +//! ADR-315 RF twin's **SYNTHETIC** propagation model. Every coverage and //! observability value it produces is a *simulation* at evidence level `L0` //! (ADR-282), labelled `SYNTHETIC`: a **recommendation**, never a sensing claim. //! Nothing here is a hardware, `MEASURED`, or accuracy claim, and the crate //! asserts **no** coverage or accuracy number — a twin/optimizer *predicts*, it -//! does not *measure* (ADR-305 evidence discipline). +//! does not *measure* (ADR-308 evidence discipline). //! -//! Consistent with ADR-297 rule 1, *insufficient information* is a first-class +//! Consistent with ADR-300 rule 1, *insufficient information* is a first-class //! value ([`Observability::Unknown`]), never an error and never a confident //! default. Consistent with rule 3, the crate reuses the canonical ontology //! vocabulary ([`SpaceId`], [`ZoneId`], [`SensorId`], [`Container`], @@ -34,7 +34,7 @@ //! - **Post-install compare** ([`compare_post_install`]): compare the optimizer's //! `L0` prediction against **caller-supplied** measured observability (this //! crate never measures) and recommend adjustments plus a coarse twin-parameter -//! residual to feed back into ADR-312. +//! residual to feed back into ADR-315. //! //! ## Determinism //! @@ -93,7 +93,7 @@ pub use inventory::{Inventory, RadioSpec, MAX_INVENTORY}; pub use plan::{candidate_positions, optimize, PlacementPlan}; // Re-export the canonical ontology and twin vocabulary consumers need, so they -// speak one semantics (ADR-297 rule 3). +// speak one semantics (ADR-300 rule 3). pub use ruview_ontology::{ Container, EvidenceLevel, SemanticProvenance, SensorId, SpaceId, ZoneId, }; @@ -326,7 +326,7 @@ mod tests { let objectives = vec![synthetic_objective(&plan)]; let recommended = optimize(&plan, &inv, &objectives, ¶ms()); - // Every known target carries BOTH a score and an uncertainty (ADR-305 §2). + // Every known target carries BOTH a score and an uncertainty (ADR-308 §2). let mut saw_known = false; for t in &recommended.score.per_target { if let Observability::Known { score, uncertainty } = t.observability { @@ -510,7 +510,7 @@ mod tests { #[test] fn marginal_case_reports_higher_uncertainty() { // A zone squarely on the link line vs. a marginal one at the Fresnel edge: - // the marginal case is reported with higher uncertainty (ADR-305 §2, the + // the marginal case is reported with higher uncertainty (ADR-308 §2, the // model reports uncertainty rather than overstating a coarse result). let plan = FloorPlan { space: SpaceId::new("room").unwrap(), diff --git a/v2/crates/ruview-placement/src/plan.rs b/v2/crates/ruview-placement/src/plan.rs index 4513e312..8792fb84 100644 --- a/v2/crates/ruview-placement/src/plan.rs +++ b/v2/crates/ruview-placement/src/plan.rs @@ -1,10 +1,10 @@ //! Deterministic placement search: floor plan + inventory → recommended plan -//! (ADR-305 §2). +//! (ADR-308 §2). //! //! **SYNTHETIC / L0.** The search consumes the SYNTHETIC coverage model in //! [`crate::coverage`] and recommends radio positions that maximise modelled //! objective observability subject to the inventory count and the scene geometry. -//! It is a *recommendation*, never a guarantee that a room is sensed (ADR-305 +//! It is a *recommendation*, never a guarantee that a room is sensed (ADR-308 //! consequences). Determinism is total: candidate positions come from a seeded //! grid ([`PlacementParams::seed`]) with **no RNG and no wall-clock**; greedy //! forward selection then adds the best candidate one radio at a time. Because diff --git a/v2/crates/ruview-policy/src/lib.rs b/v2/crates/ruview-policy/src/lib.rs index d5287eba..1d000b7c 100644 --- a/v2/crates/ruview-policy/src/lib.rs +++ b/v2/crates/ruview-policy/src/lib.rs @@ -1,6 +1,6 @@ -//! # `ruview-policy` — action authorization gate (ADR-318, ADR-297 phase 1) +//! # `ruview-policy` — action authorization gate (ADR-321, ADR-300 phase 1) //! -//! A capability certificate (ADR-315) is a statement of *knowledge*, not a +//! A capability certificate (ADR-318) is a statement of *knowledge*, not a //! *grant of action*. The same certificate that is adequate to dim a light is //! wholly inadequate to release a door lock. This crate is the authorization //! layer that sits between governed spatial state and any actuator: given the @@ -8,7 +8,7 @@ //! returns [`Authorization::Allow`] or a **fail-closed** //! [`Authorization::Deny`] that names the *specific* condition that failed. //! -//! ## The four non-negotiable rules (ADR-297) +//! ## The four non-negotiable rules (ADR-300) //! //! - **UNKNOWN is a first-class value, never an error.** An UNKNOWN domain //! ([`DomainState::Unknown`]) does not raise — it *denies* high-assurance @@ -17,7 +17,7 @@ //! [`Authorization::Allow`] *records* that it proceeded under UNKNOWN //! (`under_unknown_domain`). //! - **Staleness guard `VALID → DEGRADED → UNKNOWN`.** A safety- or -//! security-class action requires the live domain signature (ADR-299) to be +//! security-class action requires the live domain signature (ADR-302) to be //! `KNOWN`; a `DEGRADED` domain denies with [`FailedCondition::DomainDegraded`] //! and an `UNKNOWN` domain denies with [`FailedCondition::DomainNotKnown`]. //! - **Honesty / no silent optimism.** A missing or expired certificate, a @@ -46,16 +46,16 @@ //! ([`FailedCondition::DomainNotKnown`]) rather than being hidden inside a //! generic "certificate invalid". //! - `certificate_age` ← `now - content.calibrated_date_unix_s`, clamped at 0. -//! - `certificate_class` ← the ADR-315 assurance tier the certificate was +//! - `certificate_class` ← the ADR-318 assurance tier the certificate was //! minted at (derived by the caller from the certificate's evidence floor and //! validated capability); see [`CertificateClass`]. //! - `domain_state` ← `ruview_ood::DomainState`: `Known → `[`DomainState::Known`], //! `Degraded(_) → `[`DomainState::Degraded`], `Unknown(_) → `[`DomainState::Unknown`]. -//! - `uncertainty` ← the model head's live predictive uncertainty (ADR-299/301). +//! - `uncertainty` ← the model head's live predictive uncertainty (ADR-302/301). //! - `evidence_level` ← the certificate's [`EvidenceLevel`] (ADR-282/301). //! //! Every allow or deny is intended to be emitted as the terminal stage of the -//! witness chain (ADR-316); this crate returns the decision, the caller records +//! witness chain (ADR-319); this crate returns the decision, the caller records //! it. #![forbid(unsafe_code)] @@ -67,12 +67,12 @@ use serde::{Deserialize, Serialize}; // Value types owned by this crate // --------------------------------------------------------------------------- -/// The assurance tier a certificate was minted at (ADR-315). Ordering is +/// The assurance tier a certificate was minted at (ADR-318). Ordering is /// meaningful and load-bearing: an action declares a /// [`AssuranceRequirements::min_certificate_class`] and a certificate at a /// class strictly below that floor is rejected. `Basic < Standard < High`. /// -/// This is a policy-side ladder: the ADR-315 certificate binds a capability and +/// This is a policy-side ladder: the ADR-318 certificate binds a capability and /// an evidence level, and the adapter (see crate docs) derives the class from /// them. Keeping the ladder local lets the policy crate build in parallel with /// the certificate crate. @@ -88,7 +88,7 @@ pub enum CertificateClass { High, } -/// Local, simplified mirror of the ADR-299 domain signature. The concrete +/// Local, simplified mirror of the ADR-302 domain signature. The concrete /// `ruview_ood::DomainState` carries a `DomainCause`; this policy only needs /// the three-way outcome, so the cause is dropped at the adapter boundary (see /// crate docs). `Known` is the only state that satisfies a "requires known @@ -96,11 +96,11 @@ pub enum CertificateClass { #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "SCREAMING_SNAKE_CASE")] pub enum DomainState { - /// The live situation is recognized: inside the calibrated domain (ADR-299). + /// The live situation is recognized: inside the calibrated domain (ADR-302). Known, /// Drift/quality has crossed the inner envelope — degraded but not lost. Degraded, - /// The situation is not recognized (ADR-299). A first-class value, never an + /// The situation is not recognized (ADR-302). A first-class value, never an /// error; it *denies* high-assurance actions rather than guessing. Unknown, } @@ -128,7 +128,7 @@ impl DomainState { /// keeps [`authorize`] a pure, clock-free function. #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] pub struct AssuranceInputs { - /// The certificate's assurance tier (ADR-315), derived by the adapter. + /// The certificate's assurance tier (ADR-318), derived by the adapter. pub certificate_class: CertificateClass, /// Whether the certificate is currently signed and unexpired (time + /// signature validity **only** — the domain gate is applied separately). @@ -137,7 +137,7 @@ pub struct AssuranceInputs { pub certificate_valid: bool, /// Age of the certificate's calibration, in seconds (`now - calibrated_date`). pub certificate_age_secs: u64, - /// The live domain signature (ADR-299), reduced to three states. + /// The live domain signature (ADR-302), reduced to three states. pub domain_state: DomainState, /// The model head's live predictive uncertainty, in `[0.0, 1.0]`. A `NaN` /// or out-of-range value is treated as over any ceiling (fail-closed). @@ -146,7 +146,7 @@ pub struct AssuranceInputs { pub evidence_level: EvidenceLevel, } -/// The assurance an [`ActionClass`] demands (ADR-318 §1). Every field is a +/// The assurance an [`ActionClass`] demands (ADR-321 §1). Every field is a /// gate; an input that fails any one denies. #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] pub struct AssuranceRequirements { @@ -164,7 +164,7 @@ pub struct AssuranceRequirements { pub requires_domain_known: bool, } -/// The class of action being authorized (ADR-318 §1). Each class declares the +/// The class of action being authorized (ADR-321 §1). Each class declares the /// assurance it demands via [`ActionClass::requirements`]. The classes are /// reference defaults — illustrative and, in a fuller system, configurable. #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] @@ -188,7 +188,7 @@ const ONE_WEEK_SECS: u64 = 7 * ONE_DAY_SECS; const THIRTY_DAYS_SECS: u64 = 30 * ONE_DAY_SECS; impl ActionClass { - /// The reference assurance requirements for this class (ADR-318 §1 table). + /// The reference assurance requirements for this class (ADR-321 §1 table). #[must_use] pub const fn requirements(self) -> AssuranceRequirements { match self { @@ -224,7 +224,7 @@ impl ActionClass { #[serde(rename_all = "snake_case")] pub enum FailedCondition { /// No policy was supplied for the action — an unrecognized action class. - /// Absence of a policy is not permission (ADR-318 §3). + /// Absence of a policy is not permission (ADR-321 §3). NoPolicy, /// The certificate is missing or expired (`certificate_valid == false`). CertificateInvalid, @@ -245,7 +245,7 @@ pub enum FailedCondition { /// The action requires a known domain and the live domain is `DEGRADED`. DomainDegraded, /// The action requires a known domain and the live domain is `UNKNOWN` - /// (ADR-297 acceptance test: drift-invalidated capability denied at the + /// (ADR-300 acceptance test: drift-invalidated capability denied at the /// actuator). This is the canonical `domain_not_known` failure. DomainNotKnown, /// Inference uncertainty exceeds the ceiling (a `NaN` lands here too). @@ -283,7 +283,7 @@ impl FailedCondition { } } -/// The authorization decision (ADR-318 §2). Fail-closed: anything that is not an +/// The authorization decision (ADR-321 §2). Fail-closed: anything that is not an /// [`Authorization::Allow`] is a deny that names its condition. #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] @@ -324,7 +324,7 @@ impl Authorization { // The decision // --------------------------------------------------------------------------- -/// Authorize an action of `class` against the live `inputs` (ADR-318 §2). +/// Authorize an action of `class` against the live `inputs` (ADR-321 §2). /// /// A **pure**, fail-closed function of `(class, inputs)`: deterministic, no /// clock, no randomness, no panics. It applies the class's reference @@ -338,7 +338,7 @@ pub fn authorize(class: ActionClass, inputs: &AssuranceInputs) -> Authorization /// Authorize against an explicit, optional policy. `None` means *no policy was /// found for this action* — an unrecognized action class — and denies with /// [`FailedCondition::NoPolicy`] (absence of a policy is not permission, -/// ADR-318 §3). +/// ADR-321 §3). /// /// Evaluation order (the first unmet condition is the one named): /// 1. policy present, @@ -603,7 +603,7 @@ mod tests { ); } - /// ADR-297 / ADR-318 acceptance-test B: a post-drift UNKNOWN domain causes a + /// ADR-300 / ADR-321 acceptance-test B: a post-drift UNKNOWN domain causes a /// `SafetyCritical` authorize() to Deny with `domain_not_known`, *before* /// the inference reaches the actuator. The certificate is otherwise valid /// (signed, unexpired, correct class, fresh) — the domain gate is what @@ -614,7 +614,7 @@ mod tests { let mut inputs = passing(ActionClass::SafetyCritical); assert!(authorize(ActionClass::SafetyCritical, &inputs).is_allowed()); - // Drift drives the domain to UNKNOWN (ADR-299 VALID→DEGRADED→UNKNOWN). + // Drift drives the domain to UNKNOWN (ADR-302 VALID→DEGRADED→UNKNOWN). inputs.domain_state = DomainState::Unknown; let decision = authorize(ActionClass::SafetyCritical, &inputs); diff --git a/v2/crates/ruview-scorecard/src/lib.rs b/v2/crates/ruview-scorecard/src/lib.rs index 4201ba61..7ff1a635 100644 --- a/v2/crates/ruview-scorecard/src/lib.rs +++ b/v2/crates/ruview-scorecard/src/lib.rs @@ -1,12 +1,12 @@ -//! # `ruview-scorecard` — the multi-domain benchmark scorecard (ADR-314, ADR-297 §4) +//! # `ruview-scorecard` — the multi-domain benchmark scorecard (ADR-317, ADR-300 §4) //! -//! ADR-297 program rule 4 is non-negotiable: **pooled accuracy is never +//! ADR-300 program rule 4 is non-negotiable: **pooled accuracy is never //! sufficient for promotion**. A single headline number is exactly the surface //! a domain-generalization regression hides behind — a model can raise mean //! presence accuracy while quietly collapsing on unseen rooms, unseen devices, //! or a stationary subject at range (the canonical WiFi failure case). //! -//! This crate is the *data model* for that discipline (ADR-314 §1). It holds, +//! This crate is the *data model* for that discipline (ADR-317 §1). It holds, //! per capability, one cell **per operating domain** rather than one pooled //! figure: //! @@ -14,13 +14,13 @@ //! `stationary-10m`. //! - **Pose**: `matched`, `subject-unseen`, `room-unseen`. //! - **OOD rejection**: the rate at which genuinely out-of-distribution input -//! is correctly returned as UNKNOWN (a capability, ADR-299). +//! is correctly returned as UNKNOWN (a capability, ADR-302). //! - **Calibration drift**: the fingerprint-distance trajectory against the -//! ADR-298 certificate (lower is better) plus the fraction of inferences in -//! each ADR-299 [`DomainState`] under the `VALID → DEGRADED → UNKNOWN` -//! staleness guard (ADR-297). +//! ADR-301 certificate (lower is better) plus the fraction of inferences in +//! each ADR-302 [`DomainState`] under the `VALID → DEGRADED → UNKNOWN` +//! staleness guard (ADR-300). //! -//! ## Honesty by construction (CLAUDE.md, ADR-282, ADR-297) +//! ## Honesty by construction (CLAUDE.md, ADR-282, ADR-300) //! //! - Every scored [`Cell`] carries a point estimate, a **confidence interval** //! (a documented deterministic Wilson score interval — no RNG), and exactly @@ -28,7 +28,7 @@ //! construction ([`Metric::synthetic`]); nothing raises it here. //! - An empty domain is [`Cell::NoEvidence`], a first-class value distinct //! from a present-but-zero score. The promotion gate treats no evidence as -//! **no coverage, never a pass** (ADR-314 §Provenance). +//! **no coverage, never a pass** (ADR-317 §Provenance). //! - [`Scorecard::worst_domain`] returns the promotion-relevant number: the //! minimum across a task's domain slices. [`promotion_gate`] fails if *any* //! worst-domain slice regresses beyond its budget, **even when the pooled @@ -175,7 +175,7 @@ impl Metric { } /// Construct a **synthetic** metric: the evidence level is forced to `L0` - /// (ADR-282/ADR-297 — synthetic input is `L0` by construction and cannot be + /// (ADR-282/ADR-300 — synthetic input is `L0` by construction and cannot be /// raised here). /// /// # Errors @@ -227,7 +227,7 @@ impl Metric { /// One scorecard cell. A domain with no coverage is [`Cell::NoEvidence`] — a /// first-class value the promotion gate treats as no coverage, never a pass -/// (ADR-314). It is deliberately distinct from a scored cell whose point +/// (ADR-317). It is deliberately distinct from a scored cell whose point /// happens to be `0.0`. #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] pub enum Cell { @@ -279,14 +279,14 @@ impl From for Cell { } // --------------------------------------------------------------------------- -// Domain-state staleness guard (ADR-299 / ADR-297) +// Domain-state staleness guard (ADR-302 / ADR-300) // --------------------------------------------------------------------------- -/// The ADR-299 domain state under the ADR-297 staleness guard +/// The ADR-302 domain state under the ADR-300 staleness guard /// `VALID → DEGRADED → UNKNOWN`. A certificate is conditional on a continuously /// evaluated domain signature; crossing the OOD threshold degrades the state /// rather than silently continuing. `Unknown` is a first-class output, not an -/// error (ADR-297 rule 1). +/// error (ADR-300 rule 1). #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "SCREAMING_SNAKE_CASE")] pub enum DomainState { @@ -299,7 +299,7 @@ pub enum DomainState { } /// The fraction of scored inferences observed in each [`DomainState`] over the -/// scoring window (ADR-314 calibration-drift axis). Fractions are each in +/// scoring window (ADR-317 calibration-drift axis). Fractions are each in /// `[0, 1]` and sum to ~1. #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] pub struct StateFractions { @@ -392,7 +392,7 @@ pub enum SliceId { PoseRoomUnseen, /// Rate of correctly rejecting out-of-distribution input as UNKNOWN. OodRejection, - /// Calibration-drift fingerprint distance against the ADR-298 certificate. + /// Calibration-drift fingerprint distance against the ADR-301 certificate. CalibrationDrift, } @@ -451,7 +451,7 @@ impl SliceId { } /// Whether this is a strict-budget domain (unseen / stationary / OOD) — - /// the ones a pooled score hides, per ADR-314 §2. + /// the ones a pooled score hides, per ADR-317 §2. #[must_use] pub fn is_strict(self) -> bool { matches!( @@ -478,7 +478,7 @@ impl SliceId { // Scorecard // --------------------------------------------------------------------------- -/// The multi-domain scorecard (ADR-314 §1): one [`Cell`] per operating domain, +/// The multi-domain scorecard (ADR-317 §1): one [`Cell`] per operating domain, /// never pooled into a single figure. Fields are public for direct /// construction from an evidence query; every cell defaults to /// [`Cell::NoEvidence`] via [`Scorecard::empty`]. @@ -556,7 +556,7 @@ impl Scorecard { } /// The **worst domain** for a task: the promotion-relevant number - /// (ADR-297 §4). Returns the slice with the lowest point estimate, with a + /// (ADR-300 §4). Returns the slice with the lowest point estimate, with a /// [`Cell::NoEvidence`] slice ranking below any scored cell — an uncovered /// domain is the worst possible outcome, never silently skipped. /// @@ -588,7 +588,7 @@ impl Scorecard { } /// The pooled accuracy average across covered higher-is-better slices — the - /// figure ADR-297 rule 4 forbids relying on alone. Provided precisely so + /// figure ADR-300 rule 4 forbids relying on alone. Provided precisely so /// [`promotion_gate`] can prove a regression was *hidden behind* a rising /// pool. `None` when no such slice is covered. #[must_use] @@ -611,7 +611,7 @@ impl Scorecard { } } - /// Render an ASCII scorecard approximating the ADR-314 layout: one row per + /// Render an ASCII scorecard approximating the ADR-317 layout: one row per /// domain slice with its point estimate, confidence interval, evidence /// level, and sample count; the per-task worst domain; the pooled figure /// (labelled as insufficient on its own); and the domain state. Empty @@ -619,9 +619,9 @@ impl Scorecard { #[must_use] pub fn render(&self) -> String { let mut out = String::new(); - out.push_str("ADR-314 multi-domain scorecard\n"); + out.push_str("ADR-317 multi-domain scorecard\n"); out.push_str( - " (per-domain; pooled accuracy is never sufficient for promotion, ADR-297 §4)\n", + " (per-domain; pooled accuracy is never sufficient for promotion, ADR-300 §4)\n", ); out.push_str( " slice point ci_low ci_high level samples\n", @@ -721,7 +721,7 @@ impl WorstCell { /// Per-capability regression budgets. Strict-budget domains /// (unseen / stationary / OOD) carry the tightest tolerance because they are -/// the ones a pooled score hides (ADR-314 §2). +/// the ones a pooled score hides (ADR-317 §2). #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] pub struct GatePolicy { /// Budget for non-strict presence/pose slices (e.g. room-known, matched). @@ -766,7 +766,7 @@ pub enum RegressionKind { /// Calibration drift rose beyond tolerance. DriftIncrease, /// A previously-covered domain lost all evidence — no coverage is never a - /// pass (ADR-314 §Provenance). + /// pass (ADR-317 §Provenance). CoverageLoss, } @@ -802,7 +802,7 @@ pub struct GateReport { impl GateReport { /// True when the pooled average improved yet the gate still failed — the - /// exact "regression hiding behind pooled accuracy" case ADR-297 rule 4 + /// exact "regression hiding behind pooled accuracy" case ADR-300 rule 4 /// exists to catch. #[must_use] pub fn hidden_behind_pooled(&self) -> bool { @@ -813,7 +813,7 @@ impl GateReport { /// Compare a candidate scorecard against a baseline and decide promotion. /// /// The gate **fails if any single domain regresses beyond its budget**, even -/// when the pooled average improved (ADR-314 §2, ADR-297 rule 4): improvement +/// when the pooled average improved (ADR-317 §2, ADR-300 rule 4): improvement /// on `room-known` cannot buy a regression on `room-unseen`. Because the gate /// evaluates every domain independently, a regression can never hide behind a /// flattering pool; [`GateReport::hidden_behind_pooled`] reports when exactly diff --git a/v2/crates/ruview-track/src/config.rs b/v2/crates/ruview-track/src/config.rs index fc402636..736b9f84 100644 --- a/v2/crates/ruview-track/src/config.rs +++ b/v2/crates/ruview-track/src/config.rs @@ -1,4 +1,4 @@ -//! Tuning for the association / lifecycle / decay policy (ADR-304). +//! Tuning for the association / lifecycle / decay policy (ADR-307). //! //! All thresholds are explicit and deterministic; nothing here reads a clock or //! draws randomness. The manager injects every timestamp. diff --git a/v2/crates/ruview-track/src/error.rs b/v2/crates/ruview-track/src/error.rs index 907bf42f..3f900fdb 100644 --- a/v2/crates/ruview-track/src/error.rs +++ b/v2/crates/ruview-track/src/error.rs @@ -1,8 +1,8 @@ -//! Boundary-validation errors (ADR-304). +//! Boundary-validation errors (ADR-307). //! //! These cover *malformed input* only. Association **uncertainty** is never an //! error: an ambiguous or unmatched detection is reported as a first-class -//! [`Association::Unknown`](crate::Association) outcome (ADR-297 rule 1), not a +//! [`Association::Unknown`](crate::Association) outcome (ADR-300 rule 1), not a //! `Result::Err`. use ruview_ontology::IdError; diff --git a/v2/crates/ruview-track/src/feature.rs b/v2/crates/ruview-track/src/feature.rs index c5fbd2bf..30e848b6 100644 --- a/v2/crates/ruview-track/src/feature.rs +++ b/v2/crates/ruview-track/src/feature.rs @@ -1,7 +1,7 @@ -//! Coarse, non-reversible appearance features (ADR-304 §3, privacy boundary). +//! Coarse, non-reversible appearance features (ADR-307 §3, privacy boundary). //! //! A [`CoarseFeature`] is the appearance channel used for short-horizon track -//! continuity (the ADR-303/ADR-304 `CsiFingerprint` analogue). Its type is the +//! continuity (the ADR-306/ADR-307 `CsiFingerprint` analogue). Its type is the //! privacy enforcement point: //! //! - **Coarse.** Raw values are quantized into a handful of buckets diff --git a/v2/crates/ruview-track/src/lib.rs b/v2/crates/ruview-track/src/lib.rs index 056b4d25..c6ef4612 100644 --- a/v2/crates/ruview-track/src/lib.rs +++ b/v2/crates/ruview-track/src/lib.rs @@ -1,4 +1,4 @@ -//! # `ruview-track` — persistent, privacy-preserving probabilistic tracking (ADR-304) +//! # `ruview-track` — persistent, privacy-preserving probabilistic tracking (ADR-307) //! //! Builds **track continuity without civil identity**. A [`TrackManager`] //! ingests per-frame [`Detection`]s (a container + 2-D position + a coarse, @@ -8,11 +8,11 @@ //! answers "person_7 moved kitchen → hallway → bedroom" via per-entity //! [histories](TrackManager::history) — across zones, rooms, and modalities. //! -//! This crate produces and updates the **canonical ADR-303 ontology types** +//! This crate produces and updates the **canonical ADR-306 ontology types** //! (`Track`, `Person`, `Container`, `EvidenceLevel`, `SemanticProvenance`) from -//! [`ruview_ontology`]; it invents no per-crate identity shape (ADR-297 rule 3). +//! [`ruview_ontology`]; it invents no per-crate identity shape (ADR-300 rule 3). //! -//! ## The four privacy invariants (ADR-304 §3), enforced by construction +//! ## The four privacy invariants (ADR-307 §3), enforced by construction //! //! 1. **No civil-identity binding.** The pseudonym is a synthetic id with no //! field or join key to a name, account, MAC, or phone — the ontology @@ -22,7 +22,7 @@ //! persisted. //! 3. **Opaque, rotatable ids.** Pseudonyms are `person_N` strings and can be //! rotated with [`TrackManager::rotate_pseudonym`]. -//! 4. **UNKNOWN is first-class** (ADR-297 rule 1). An unmatched or ambiguous +//! 4. **UNKNOWN is first-class** (ADR-300 rule 1). An unmatched or ambiguous //! detection spawns a *tentative* track and returns an //! [`Association::Unknown`] outcome — it never forces a wrong join and never //! errors. Under-linking (a fresh pseudonym when unsure) is the privacy-safe @@ -30,7 +30,7 @@ //! //! ## Evidence discipline //! -//! This crate asserts **no accuracy number** (ADR-304 §Validation). Emitted +//! This crate asserts **no accuracy number** (ADR-307 §Validation). Emitted //! nodes carry the caller-supplied [`EvidenceLevel`](ruview_ontology::EvidenceLevel) //! (default `L1`, heuristic/synthetic) and a pseudonymous //! [`SemanticProvenance`](ruview_ontology::SemanticProvenance); tentative tracks diff --git a/v2/crates/ruview-track/src/manager.rs b/v2/crates/ruview-track/src/manager.rs index 8567a6d2..9bb9e7b8 100644 --- a/v2/crates/ruview-track/src/manager.rs +++ b/v2/crates/ruview-track/src/manager.rs @@ -1,5 +1,5 @@ //! [`TrackManager`] — persistent, privacy-preserving probabilistic tracking -//! (ADR-304). +//! (ADR-307). //! //! # What it does //! @@ -29,7 +29,7 @@ //! track has already expired, so a fresh pseudonym is minted. //! //! Any detection without a confident, unambiguous match yields an -//! [`Association::Unknown`] outcome and a new tentative track (ADR-297 rule 1: +//! [`Association::Unknown`] outcome and a new tentative track (ADR-300 rule 1: //! UNKNOWN is first-class, never an error). //! //! # Privacy boundary (by construction) @@ -166,7 +166,7 @@ struct Entity { history: Vec, } -/// Persistent probabilistic tracker producing ADR-303 `Track`/`Person` nodes +/// Persistent probabilistic tracker producing ADR-306 `Track`/`Person` nodes /// without civil identity. #[derive(Clone, Debug)] pub struct TrackManager { @@ -419,7 +419,7 @@ impl TrackManager { Ok(fresh) } - /// Project a track to a canonical ADR-303 [`Track`] node, carrying the + /// Project a track to a canonical ADR-306 [`Track`] node, carrying the /// pseudonym, evidence level, and provenance. `None` if not held. #[must_use] pub fn to_track(&self, track: &TrackId) -> Option { @@ -433,7 +433,7 @@ impl TrackManager { }) } - /// Project a track's pseudonymous entity to a canonical ADR-303 [`Person`] + /// Project a track's pseudonymous entity to a canonical ADR-306 [`Person`] /// node. `None` if not held. #[must_use] pub fn to_person(&self, track: &TrackId) -> Option { diff --git a/v2/crates/ruview-track/src/topology.rs b/v2/crates/ruview-track/src/topology.rs index 20a1161c..fff1b95e 100644 --- a/v2/crates/ruview-track/src/topology.rs +++ b/v2/crates/ruview-track/src/topology.rs @@ -1,7 +1,7 @@ -//! Space/zone adjacency that constrains plausible hand-offs (ADR-304 §2). +//! Space/zone adjacency that constrains plausible hand-offs (ADR-307 §2). //! //! Association across containers is only allowed between the **same** container -//! or two **adjacent** ones (the ADR-303 `AdjacentTo`/`Doorway` analogue): a +//! or two **adjacent** ones (the ADR-306 `AdjacentTo`/`Doorway` analogue): a //! person can only move between spaces that share a boundary. An empty topology //! therefore permits continuity only *within* a container — the privacy-safe //! default for single-room deployments, where cross-room joins never happen by diff --git a/v2/crates/ruview-track/tests/tracking.rs b/v2/crates/ruview-track/tests/tracking.rs index f0770701..047fbba1 100644 --- a/v2/crates/ruview-track/tests/tracking.rs +++ b/v2/crates/ruview-track/tests/tracking.rs @@ -1,4 +1,4 @@ -//! ADR-304 scenario tests: continuity, no-swap, spawn/expire, ambiguity, +//! ADR-307 scenario tests: continuity, no-swap, spawn/expire, ambiguity, //! id opacity, and determinism. All fixtures are synthetic and in-code; time is //! injected (no wall clock); no randomness. diff --git a/v2/crates/ruview-twin/src/delta.rs b/v2/crates/ruview-twin/src/delta.rs index 5de052a4..6bd8e065 100644 --- a/v2/crates/ruview-twin/src/delta.rs +++ b/v2/crates/ruview-twin/src/delta.rs @@ -1,13 +1,13 @@ -//! The load-bearing operation: `delta(observed, expected)` (ADR-312 §2). +//! The load-bearing operation: `delta(observed, expected)` (ADR-315 §2). //! //! **SYNTHETIC / L0.** A [`TwinDelta`] is a *model-relative* statement: how far a //! supplied observation set sits from the twin's own predicted distributions, //! measured against the twin's own modelled variance. It is **not** a detection, -//! and asserts no accuracy (ADR-312 evidence discipline, ADR-297). A change that +//! and asserts no accuracy (ADR-315 evidence discipline, ADR-300). A change that //! is large relative to the modelled variance is a *candidate physical change* //! to be corroborated, never a confident claim. //! -//! Consistent with ADR-297 rule 1, a link the twin cannot evaluate — unknown +//! Consistent with ADR-300 rule 1, a link the twin cannot evaluate — unknown //! prediction, or an observation for a link outside the twin — is reported as //! [`LinkDeltaStatus::Unknown`], excluded from the aggregate magnitude, never an //! error. @@ -89,7 +89,7 @@ pub enum LinkDeltaStatus { #[serde(skip_serializing_if = "Option::is_none")] significance: Option, }, - /// The link could not be evaluated; first-class UNKNOWN (ADR-297 rule 1). + /// The link could not be evaluated; first-class UNKNOWN (ADR-300 rule 1). Unknown { /// Why it is unknown. reason: UnknownReason, @@ -111,7 +111,7 @@ pub struct LinkDelta { /// summaries, not a detection or accuracy claim. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub struct TwinDelta { - /// Twin baseline version this delta is relative to (ADR-312 §2). + /// Twin baseline version this delta is relative to (ADR-315 §2). pub baseline_version: u64, /// Significance threshold (standard deviations) used to flag deviating links. pub significance_threshold: f64, diff --git a/v2/crates/ruview-twin/src/lib.rs b/v2/crates/ruview-twin/src/lib.rs index f5d51543..9c51d2b6 100644 --- a/v2/crates/ruview-twin/src/lib.rs +++ b/v2/crates/ruview-twin/src/lib.rs @@ -1,4 +1,4 @@ -//! # `ruview-twin` — a digital RF twin (ADR-312, ADR-297 phase 3) +//! # `ruview-twin` — a digital RF twin (ADR-315, ADR-300 phase 3) //! //! **SYNTHETIC / L0 — a simulation scaffold, not a measurement system.** //! @@ -7,8 +7,8 @@ //! observable; it never **measures** one. Every distribution it produces and any //! propagation it simulates is a model at evidence level `L0` (ADR-282), //! labelled `SYNTHETIC`. Nothing in this crate is a hardware, `MEASURED`, or -//! accuracy claim, and it asserts **no** detection-accuracy number (ADR-312 -//! evidence discipline). Following ADR-297 rule 1, *insufficient information* is +//! accuracy claim, and it asserts **no** detection-accuracy number (ADR-315 +//! evidence discipline). Following ADR-300 rule 1, *insufficient information* is //! a first-class value ([`ExpectedDistribution::Unknown`] / //! [`LinkDeltaStatus::Unknown`]), never an error and never a confident default. //! @@ -17,7 +17,7 @@ //! - **Radio node positions** in coarse metric coordinates ([`RadioNode`], //! [`Point3`]). //! - **Geometry references** into the canonical ontology ([`SpaceId`], -//! [`Container`]) — the twin *annotates* the ADR-303 scene, it does not invent +//! [`Container`]) — the twin *annotates* the ADR-306 scene, it does not invent //! a second geometry. //! - A **simple documented propagation model** — log-distance path loss with //! optional wall attenuation ([`PropagationParams`], [`crate::predict`]), @@ -73,7 +73,7 @@ pub use twin::{ }; // Re-export the canonical ontology vocabulary the twin references, so consumers -// speak one semantics (ADR-297 rule 3, ADR-303). +// speak one semantics (ADR-300 rule 3, ADR-306). pub use ruview_ontology::{Container, EvidenceLevel, SensorId, SpaceId}; impl RfTwin { diff --git a/v2/crates/ruview-twin/src/predict.rs b/v2/crates/ruview-twin/src/predict.rs index 23e7a787..6d65f895 100644 --- a/v2/crates/ruview-twin/src/predict.rs +++ b/v2/crates/ruview-twin/src/predict.rs @@ -1,4 +1,4 @@ -//! The forward model: expected distribution per link (ADR-312 §1). +//! The forward model: expected distribution per link (ADR-315 §1). //! //! **SYNTHETIC / L0.** This module is a *simulation* of an observable, not a //! measurement. It implements a deliberately simple, documented log-distance @@ -6,7 +6,7 @@ //! not real RF. Nothing here is a hardware, `MEASURED`, or accuracy claim. //! //! An [`ExpectedDistribution`] is the mean/variance of a modelled observable -//! under the twin. Consistent with ADR-297 rule 1, insufficient information is +//! under the twin. Consistent with ADR-300 rule 1, insufficient information is //! reported as [`ExpectedDistribution::Unknown`] — a first-class value, never an //! error or a confident default. @@ -24,7 +24,7 @@ pub enum Observable { } /// Why a link's expected distribution is unknown. UNKNOWN is a first-class -/// output (ADR-297 rule 1), not an error. +/// output (ADR-300 rule 1), not an error. #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum UnknownReason { diff --git a/v2/crates/ruview-twin/src/twin.rs b/v2/crates/ruview-twin/src/twin.rs index 96e620bf..56c8663b 100644 --- a/v2/crates/ruview-twin/src/twin.rs +++ b/v2/crates/ruview-twin/src/twin.rs @@ -1,17 +1,17 @@ -//! Twin model, geometry, and construction (ADR-312 §1). +//! Twin model, geometry, and construction (ADR-315 §1). //! //! **SYNTHETIC / L0.** Every structure here is part of a *simulation scaffold*. //! A [`RfTwin`] is a persistent, per-deployment *model* of an RF environment; it //! **predicts** an expected observable, it does not **measure** one. No value it //! holds or produces is a hardware, `MEASURED`, or accuracy claim (ADR-282 L0, -//! ADR-297 evidence discipline). Coordinates are a coarse metric abstraction, +//! ADR-300 evidence discipline). Coordinates are a coarse metric abstraction, //! and the propagation model in [`crate::predict`] is a deliberately simple //! log-distance model, not real RF. //! //! Geometry and radio identity are *referenced* from the canonical //! [`ruview_ontology`] vocabulary ([`SpaceId`], [`SensorId`], [`Container`], //! [`SemanticProvenance`], [`EvidenceLevel`]) rather than reinvented — the twin -//! annotates the ADR-303 scene with RF state (ADR-312 "annotates and persists"). +//! annotates the ADR-306 scene with RF state (ADR-315 "annotates and persists"). use std::collections::BTreeMap; @@ -71,7 +71,7 @@ impl Point3 { /// A wall or static reflector, modelled (SYNTHETIC) as a floor-plan segment that /// adds a fixed attenuation to any link whose straight path crosses it. This is -/// a coarse stand-in for the worldgraph `Wall { rf_attenuation_db }` (ADR-303), +/// a coarse stand-in for the worldgraph `Wall { rf_attenuation_db }` (ADR-306), /// not a solved electromagnetic obstacle. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub struct Wall { @@ -101,7 +101,7 @@ impl Wall { /// references, not new vocabulary. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub struct RadioNode { - /// Ontology sensor identity (ADR-302 authenticated device / ADR-303 sensor). + /// Ontology sensor identity (ADR-305 authenticated device / ADR-306 sensor). pub id: SensorId, /// Metric position in the deployment frame. pub position: Point3, @@ -111,7 +111,7 @@ pub struct RadioNode { pub tx_power_dbm: f64, } -/// Parameters of the SYNTHETIC log-distance path-loss model (ADR-312 §1). These +/// Parameters of the SYNTHETIC log-distance path-loss model (ADR-315 §1). These /// describe a simple didactic propagation model, **not** a calibrated RF fit. #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] pub struct PropagationParams { @@ -197,7 +197,7 @@ impl LinkId { /// Recorded multipath / calibration state for one link: an extra variance /// (dB²) folded into that link's expected distribution. A bounded temporal -/// summary in ADR-312 terms; here a single non-negative scalar. +/// summary in ADR-315 terms; here a single non-negative scalar. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub struct MultipathRecord { /// The link this record applies to. @@ -206,12 +206,12 @@ pub struct MultipathRecord { pub extra_variance_db2: f64, } -/// Reason a twin version was advanced (ADR-312 §2 versioning). Kept for audit; +/// Reason a twin version was advanced (ADR-315 §2 versioning). Kept for audit; /// the twin is always relative to a *named* baseline version. #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum VersionEvent { - /// A calibration event under ADR-298 advanced the baseline. + /// A calibration event under ADR-301 advanced the baseline. Calibration, /// A deliberate geometry edit advanced the baseline. GeometryEdit, @@ -236,13 +236,13 @@ pub struct DeploymentDescription { /// Recorded per-link multipath / calibration variance state. #[serde(default)] pub multipath: Vec, - /// Referenced calibration baseline (ADR-298), as a version handle only. + /// Referenced calibration baseline (ADR-301), as a version handle only. pub calibration_version: String, /// Explicit seed identifying the synthetic scene. Deterministic. pub seed: u64, } -/// A persistent, versioned, per-deployment RF *model* (ADR-312). +/// A persistent, versioned, per-deployment RF *model* (ADR-315). /// /// **SYNTHETIC / L0.** The twin's expected distributions and any propagation /// simulation are a model (ADR-282 L0), never evidence that a physical state is @@ -263,9 +263,9 @@ pub struct RfTwin { pub params: PropagationParams, /// Recorded per-link multipath / calibration variance state. pub multipath: Vec, - /// Referenced calibration baseline handle (ADR-298). + /// Referenced calibration baseline handle (ADR-301). pub calibration_version: String, - /// Provenance travelling with the twin (ADR-303 §2). + /// Provenance travelling with the twin (ADR-306 §2). pub provenance: SemanticProvenance, /// Evidence level of everything the twin asserts. Always `L0` (SYNTHETIC): /// a twin predicts, it does not measure. @@ -378,7 +378,7 @@ impl RfTwin { } /// Advance the baseline version on an auditable event and return the new - /// version. History semantics (ADR-309) live outside this crate; here we + /// version. History semantics (ADR-312) live outside this crate; here we /// simply move the named baseline forward. pub fn advance_version(&mut self, _event: VersionEvent) -> u64 { self.version = self.version.saturating_add(1); diff --git a/v2/crates/ruview-witness/src/lib.rs b/v2/crates/ruview-witness/src/lib.rs index e9c98e25..27c3655a 100644 --- a/v2/crates/ruview-witness/src/lib.rs +++ b/v2/crates/ruview-witness/src/lib.rs @@ -1,7 +1,7 @@ //! `ruview-witness` — the staged, append-only, hash-linked witness chain. //! -//! This crate implements **ADR-316** (witness chain), primitive 19 of the -//! ADR-297 perception substrate. Instead of emitting a bare boolean +//! This crate implements **ADR-319** (witness chain), primitive 19 of the +//! ADR-300 perception substrate. Instead of emitting a bare boolean //! ("person present"), RuView emits a *chain* whose ordered stages record the //! auditable reasoning behind an output: //! @@ -19,21 +19,21 @@ //! //! ## Relationship to sibling ADRs //! -//! - **ADR-302 ([`ruview_attest`])** roots the chain: the first stage is built +//! - **ADR-305 ([`ruview_attest`])** roots the chain: the first stage is built //! from an authenticated [`VerifiedMeasurement`] //! ([`WitnessChain::from_measurement`]), so the whole chain descends from a //! verified chain of custody. The stage hash reuses `ruview-attest`'s BLAKE3 //! ([`ruview_attest::PayloadHash`]) — no separate hash primitive is added. -//! - **ADR-292** contributes [`SourceState`]: a `Synthetic` root can never +//! - **ADR-295** contributes [`SourceState`]: a `Synthetic` root can never //! present as `LiveVerified`, and it caps the chain's effective evidence //! level. -//! - **ADR-299** contributes [`DomainState`] (the `KNOWN → DEGRADED → UNKNOWN` +//! - **ADR-302** contributes [`DomainState`] (the `KNOWN → DEGRADED → UNKNOWN` //! staleness guard): a low-confidence or out-of-distribution inference is //! recorded as such, never silently promoted. -//! - **ADR-318** will attach the real terminal [`PolicyDecision`]; here it is a +//! - **ADR-321** will attach the real terminal [`PolicyDecision`]; here it is a //! faithfully-typed placeholder for the governed action taken (or withheld). //! -//! ## Honesty discipline (ADR-297 rule 1 / CLAUDE.md) +//! ## Honesty discipline (ADR-300 rule 1 / CLAUDE.md) //! //! [`Confidence::Unknown`] is a first-class value, never an error. A missing //! corroboration is recorded as [`Corroboration::None`], never fabricated. The @@ -45,7 +45,7 @@ //! Like `ruview-attest`, any guarantee exercised by this crate's tests is //! **SYNTHETIC / L0** — the fixtures are constructed in code, never captured //! from silicon. Hash-linking here is tamper-*evident* against in-place -//! mutation; deployment-grade non-repudiation additionally requires the ADR-302 +//! mutation; deployment-grade non-repudiation additionally requires the ADR-305 //! per-stage RuField signatures, layered on top of this structure, plus //! real-hardware evidence. @@ -148,7 +148,7 @@ pub enum EvidenceLevel { L5 = 5, } -/// The ADR-292 source state of an RF observation. `Unknown` is structurally +/// The ADR-295 source state of an RF observation. `Unknown` is structurally /// absent here: a stage that cannot assert a live state records `Synthetic` or /// `Disconnected`, and a `Synthetic` root can never present as `LiveVerified`. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)] @@ -156,7 +156,7 @@ pub enum EvidenceLevel { pub enum SourceState { /// Synthetic input; caps the chain at [`EvidenceLevel::L0`]. Synthetic = 0, - /// Live and cryptographically verified (ADR-302). + /// Live and cryptographically verified (ADR-305). LiveVerified = 1, /// Live but unverified. LiveUnverified = 2, @@ -168,13 +168,13 @@ pub enum SourceState { impl SourceState { /// Whether this state is the authenticated live state. A `Synthetic` root - /// answers `false`, upholding the ADR-292 invariant. + /// answers `false`, upholding the ADR-295 invariant. pub fn is_live_verified(&self) -> bool { matches!(self, SourceState::LiveVerified) } } -/// The ADR-299 domain-signature gate result for a model inference — the +/// The ADR-302 domain-signature gate result for a model inference — the /// `VALID → DEGRADED → UNKNOWN` staleness guard. Recorded faithfully so a /// degraded or out-of-distribution inference is never silently promoted. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)] @@ -189,7 +189,7 @@ pub enum DomainState { } /// A stage's confidence. [`Confidence::Unknown`] is a first-class value -/// (ADR-297 rule 1), never an error and never coerced to a number. +/// (ADR-300 rule 1), never an error and never coerced to a number. #[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)] pub enum Confidence { /// A finite confidence in `0.0..=1.0`. @@ -228,23 +228,23 @@ pub enum StageKind { RfObservation = 0, /// Deterministic DSP features and ADR-137 quality signals. DspEvidence = 1, - /// Model version, raw output, uncertainty, and the ADR-299 gate result. + /// Model version, raw output, uncertainty, and the ADR-302 gate result. ModelInference = 2, - /// The ADR-300 agreement link (phase 2); "no corroboration" in phase 1. + /// The ADR-303 agreement link (phase 2); "no corroboration" in phase 1. IndependentCorroboration = 3, - /// The ADR-303 ontology entity the inference updated. + /// The ADR-306 ontology entity the inference updated. SpatialState = 4, - /// The terminal governed action (ADR-318). + /// The terminal governed action (ADR-321). PolicyDecision = 5, } /// The RF observation stage: the authenticated measurement lineage plus its -/// ADR-292 source state. This is the root link of every chain. +/// ADR-295 source state. This is the root link of every chain. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct RfObservation { - /// The verified chain-of-custody record from `ruview-attest` (ADR-302). + /// The verified chain-of-custody record from `ruview-attest` (ADR-305). pub measurement: VerifiedMeasurement, - /// The ADR-292 source state of the measurement. + /// The ADR-295 source state of the measurement. pub source_state: SourceState, } @@ -290,14 +290,14 @@ impl DspEvidence { } /// The model inference stage: which model produced which raw output, with what -/// predictive uncertainty, under which ADR-299 domain gate. +/// predictive uncertainty, under which ADR-302 domain gate. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub struct ModelInference { model_version: String, label: String, /// Predictive uncertainty of the raw output. pub uncertainty: f32, - /// The ADR-299 domain-gate result. `Unknown` records an OOD inference. + /// The ADR-302 domain-gate result. `Unknown` records an OOD inference. pub domain_state: DomainState, } @@ -328,7 +328,7 @@ impl ModelInference { } } -/// The independent-corroboration stage (ADR-300). In phase 1 the honest value +/// The independent-corroboration stage (ADR-303). In phase 1 the honest value /// is [`Corroboration::None`] — a missing corroboration is recorded, never /// fabricated. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] @@ -369,7 +369,7 @@ impl Corroboration { } } -/// The kind of ADR-303 ontology entity a stage updated. +/// The kind of ADR-306 ontology entity a stage updated. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)] #[repr(u8)] pub enum SpatialEntity { @@ -381,7 +381,7 @@ pub enum SpatialEntity { Event = 2, } -/// The spatial-state stage: the ADR-303 ontology entity the inference updated. +/// The spatial-state stage: the ADR-306 ontology entity the inference updated. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct SpatialState { /// The kind of entity updated. @@ -404,7 +404,7 @@ impl SpatialState { } } -/// The governed action a policy took or withheld (ADR-318 owns the real one). +/// The governed action a policy took or withheld (ADR-321 owns the real one). #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub enum PolicyAction { /// An action was taken. @@ -419,7 +419,7 @@ pub enum PolicyAction { }, } -/// The terminal policy-decision stage: the governed action, with the ADR-315 +/// The terminal policy-decision stage: the governed action, with the ADR-318 /// capability certificate it relied on (if any). #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct PolicyDecision { @@ -670,7 +670,7 @@ pub struct ChainSummary { pub finalized: bool, } -/// A staged, append-only, hash-linked witness chain (ADR-316). +/// A staged, append-only, hash-linked witness chain (ADR-319). /// /// A chain always roots in an RF observation and grows by strictly-increasing /// stage kind. Prior stages are immutable: [`WitnessChain::append`] only ever @@ -707,7 +707,7 @@ impl WitnessChain { } /// Root a chain directly in an authenticated [`VerifiedMeasurement`] - /// (ADR-302), so the chain descends from a verified chain of custody. + /// (ADR-305), so the chain descends from a verified chain of custody. pub fn from_measurement( measurement: VerifiedMeasurement, source_state: SourceState, diff --git a/v2/crates/wifi-densepose-bfld/Cargo.toml b/v2/crates/wifi-densepose-bfld/Cargo.toml index 956cce37..d374e258 100644 --- a/v2/crates/wifi-densepose-bfld/Cargo.toml +++ b/v2/crates/wifi-densepose-bfld/Cargo.toml @@ -25,7 +25,7 @@ mqtt = ["std", "dep:rumqttc"] # enables privacy_class = 1 (derived) mode and the SoulMatchOracle gate # exemption. Disabled by default per the structural class-2 default. soul-signature = [] -# WiFi Veil advisory integration (ADR-291): deterministic attacker-vs- +# WiFi Veil advisory integration (ADR-294): deterministic attacker-vs- # protector assessment of BFI identity leakage and emission-shaping shield # configs. All numbers it produces are SYNTHETIC / L0 by construction. veil = ["std", "dep:wifi-veil"] diff --git a/v2/crates/wifi-densepose-bfld/src/lib.rs b/v2/crates/wifi-densepose-bfld/src/lib.rs index 4bec7125..593891af 100644 --- a/v2/crates/wifi-densepose-bfld/src/lib.rs +++ b/v2/crates/wifi-densepose-bfld/src/lib.rs @@ -53,7 +53,7 @@ pub mod signature_hasher; pub mod sink; pub mod soul_channels; pub mod soul_match; -/// WiFi Veil advisory integration (ADR-291). Feature-gated: `veil`. +/// WiFi Veil advisory integration (ADR-294). Feature-gated: `veil`. #[cfg(feature = "veil")] pub mod veil; diff --git a/v2/crates/wifi-densepose-bfld/src/veil.rs b/v2/crates/wifi-densepose-bfld/src/veil.rs index 18ee90a4..d710415a 100644 --- a/v2/crates/wifi-densepose-bfld/src/veil.rs +++ b/v2/crates/wifi-densepose-bfld/src/veil.rs @@ -1,4 +1,4 @@ -//! WiFi Veil advisory integration (ADR-291). +//! WiFi Veil advisory integration (ADR-294). //! //! Bridges BFLD's privacy layer to the [`wifi-veil`](https://github.com/ruvnet/wifi-veil) //! countermeasure crate: a deterministic, dependency-free attacker-vs-protector @@ -12,7 +12,7 @@ //! scenes and never touches a radio. Assessments quantify the *modeled* //! re-identification risk of unprotected beamforming feedback and the *modeled* //! effect of a shield; they are advisory inputs to privacy posture, never -//! measured hardware claims. See ADR-291 and the wifi-veil README. +//! measured hardware claims. See ADR-294 and the wifi-veil README. //! //! # Relationship to BFLD invariants //! diff --git a/v2/crates/wifi-densepose-calibration/src/certificate.rs b/v2/crates/wifi-densepose-calibration/src/certificate.rs index df9beb12..d3e6c799 100644 --- a/v2/crates/wifi-densepose-calibration/src/certificate.rs +++ b/v2/crates/wifi-densepose-calibration/src/certificate.rs @@ -1,6 +1,6 @@ -//! Signed, versioned, invalidatable room-fingerprint certificate (ADR-298). +//! Signed, versioned, invalidatable room-fingerprint certificate (ADR-301). //! -//! ADR-298 is primitive 1 of the perception-substrate program (ADR-297) and the +//! ADR-301 is primitive 1 of the perception-substrate program (ADR-300) and the //! first brick of its "certificate spine". This module implements the //! **certificate portion**: a portable, signed, expiring artifact that says //! *"this is the room, here is when it was measured, and here is the evidence @@ -15,7 +15,7 @@ //! a signing sensor identity, a monotonic version, a capture time, an expiry, //! an evidence level (ADR-282), and a content hash suitable for signing. //! -//! ## Honesty discipline (ADR-298 §"Provenance and honesty") +//! ## Honesty discipline (ADR-301 §"Provenance and honesty") //! //! A certificate produced from generated CSI is [`EvidenceLevel::L0Synthetic`] //! by construction; [`CalibrationCertificate::mint`] **rejects** labelling a @@ -40,7 +40,7 @@ use crate::error::{CalibrationError, Result}; use crate::geometry_embedding::GeometryEmbedding; /// Schema version for the [`RoomFingerprint`] wire format. Bumped when the -/// fingerprint's field set changes (ADR-298 §1: "its schema is versioned"). +/// fingerprint's field set changes (ADR-301 §1: "its schema is versioned"). pub const FINGERPRINT_SCHEMA_VERSION: u32 = 1; /// Schema version for the [`CalibrationCertificate`] wire format. @@ -59,7 +59,7 @@ const GEOM_SCALE: f32 = 1.0; // --------------------------------------------------------------------------- /// Evidence ladder (ADR-282 L0–L5). An automatic characterization on real -/// captured CSI is at most L1/L2 and is labelled as such, never L3+ (ADR-298 +/// captured CSI is at most L1/L2 and is labelled as such, never L3+ (ADR-301 /// §3). L0 is reserved for synthetic/generated input. #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)] pub enum EvidenceLevel { @@ -96,7 +96,7 @@ impl EvidenceLevel { } } -/// How the fingerprint was characterized (ADR-298 §"Provenance and honesty"). +/// How the fingerprint was characterized (ADR-301 §"Provenance and honesty"). #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] pub enum CharacterizationSource { /// Generated / simulated CSI. Forces [`EvidenceLevel::L0Synthetic`]. @@ -114,7 +114,7 @@ impl CharacterizationSource { } } -/// Calibration tier (ADR-298 §1/§3): the automatic observe-only path yields a +/// Calibration tier (ADR-301 §1/§3): the automatic observe-only path yields a /// weaker evidence level than guided enrollment; the certificate states which /// path produced it so consumers can weight it. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] @@ -147,7 +147,7 @@ impl CalibrationTier { // --------------------------------------------------------------------------- /// A bounded, fixed-length statistical summary of a room's CSI distribution — -/// the distance-comparable object ADR-299 measures against. +/// the distance-comparable object ADR-302 measures against. /// /// It is *derived* from the existing calibration state, not a new measurement: /// the empty-vs-occupied separation comes from the bank's @@ -223,7 +223,7 @@ impl RoomFingerprint { } /// Bounded fingerprint distance to another fingerprint — the primitive - /// ADR-299 uses to gate KNOWN → DEGRADED → UNKNOWN. + /// ADR-302 uses to gate KNOWN → DEGRADED → UNKNOWN. /// /// Splits drift into an **empty-room** component (static multipath + physical /// geometry) and an **occupancy** component (dynamics), so a consumer can @@ -280,7 +280,7 @@ impl FingerprintDistance { } } -/// The compatibility envelope for continuous drift compensation (ADR-298 §4). +/// The compatibility envelope for continuous drift compensation (ADR-301 §4). /// Drift within the envelope is absorbed and logged; drift beyond it invalidates /// the certificate. #[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)] @@ -293,7 +293,7 @@ pub struct CompatibilityEnvelope { impl Default for CompatibilityEnvelope { fn default() -> Self { // A conservative default: modest drift is absorbed, a clearly different - // room is rejected. Consumers (ADR-299) may tighten this per space. + // room is rejected. Consumers (ADR-302) may tighten this per space. Self { max_total_drift: 0.15, } @@ -320,7 +320,7 @@ impl CompatibilityEnvelope { /// Signs a certificate content hash. Kept behind a trait so the RuField /// provenance/signature backend (ADR-260/262/277/279) can be substituted /// without changing the certificate types. A signature is mandatory: an -/// unsigned certificate is not a valid certificate (ADR-298 §3). +/// unsigned certificate is not a valid certificate (ADR-301 §3). pub trait CertificateSigner { /// Identity of the signing key (bound into the certificate as the signer). fn key_id(&self) -> &str; @@ -385,7 +385,7 @@ impl CertificateVerifier for KeyedHashSigner { /// A detached signature bound to a content hash and a signing-key identity. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct CertificateSignature { - /// Identity of the signing key (ADR-302 sensor identity binding). + /// Identity of the signing key (ADR-305 sensor identity binding). pub key_id: String, /// Lowercase-hex SHA-256 of the certificate's canonical signable bytes. pub content_hash_hex: String, @@ -401,9 +401,9 @@ pub struct CertificateSignature { /// avoids a long positional argument list and documents each binding. #[derive(Debug, Clone)] pub struct MintParams { - /// Canonical space identifier (ADR-303 ontology) — *which* space. + /// Canonical space identifier (ADR-306 ontology) — *which* space. pub space_id: String, - /// Signing sensor identity (ADR-302) — *which signed device* produced it. + /// Signing sensor identity (ADR-305) — *which signed device* produced it. /// Must equal the signer's `key_id`. pub sensor_id: String, /// Capture time (unix seconds). Injected, never read from the wall clock. @@ -427,13 +427,13 @@ pub struct MintParams { pub struct CalibrationCertificate { /// Certificate schema version ([`CERTIFICATE_SCHEMA_VERSION`]). pub schema_version: u32, - /// Canonical space identifier (ADR-303). + /// Canonical space identifier (ADR-306). pub space_id: String, /// Room scope carried through from the calibration state. pub room_id: String, /// ADR-135 baseline id the fingerprint was derived against. pub baseline_id: String, - /// Signing sensor identity (ADR-302). + /// Signing sensor identity (ADR-305). pub sensor_id: String, /// Monotonic version (append-only history; renewal increments). pub version: u64, @@ -564,7 +564,7 @@ impl CalibrationCertificate { } /// Re-characterize into the **next** version, preserving the append-only - /// history (ADR-298 §4). Same space/sensor/tier/evidence/source/envelope, + /// history (ADR-301 §4). Same space/sensor/tier/evidence/source/envelope, /// `version + 1`, re-signed over the fresh fingerprint and capture time. /// /// `source`/`evidence` are inherited so a renewal cannot silently upgrade a @@ -591,7 +591,7 @@ impl CalibrationCertificate { } /// The 32-byte content hash over this certificate's canonical signable bytes - /// — the object the signature covers and a witness-chain anchor (ADR-316). + /// — the object the signature covers and a witness-chain anchor (ADR-319). pub fn content_hash(&self) -> [u8; 32] { self.as_unsigned().content_hash() } @@ -628,14 +628,14 @@ impl CalibrationCertificate { } /// Distance between this certificate's fingerprint and another's — two - /// certificates for the same space are comparable (ADR-298 §3). + /// certificates for the same space are comparable (ADR-301 §3). pub fn distance(&self, other: &CalibrationCertificate) -> FingerprintDistance { self.fingerprint.distance(&other.fingerprint) } /// Evaluate validity against live room state and a signature verifier. /// - /// Invalidation is an explicit, typed transition (ADR-298 §4), never a + /// Invalidation is an explicit, typed transition (ADR-301 §4), never a /// silent flag. Order of precedence: tampered signature → expired → drift /// beyond the envelope → valid. `now_unix_s` is injected (no wall clock). pub fn status( @@ -695,7 +695,7 @@ impl CalibrationCertificate { } } -/// The typed result of a certificate validity check (ADR-298 §4). +/// The typed result of a certificate validity check (ADR-301 §4). #[derive(Debug, Clone, PartialEq)] pub enum CertificateStatus { /// Still valid; carries the (in-envelope) drift for logging/compensation. diff --git a/v2/crates/wifi-densepose-calibration/src/error.rs b/v2/crates/wifi-densepose-calibration/src/error.rs index bf17629d..0dc834c8 100644 --- a/v2/crates/wifi-densepose-calibration/src/error.rs +++ b/v2/crates/wifi-densepose-calibration/src/error.rs @@ -35,12 +35,12 @@ pub enum CalibrationError { #[error("serialization error: {0}")] Serde(String), - /// A calibration certificate failed validation at construction (ADR-298). + /// A calibration certificate failed validation at construction (ADR-301). #[error("invalid calibration certificate: {0}")] InvalidCertificate(String), /// A synthetic characterization was labelled as measured evidence — rejected - /// by the honesty discipline (ADR-279 invariant 6, ADR-282 ladder, ADR-298). + /// by the honesty discipline (ADR-279 invariant 6, ADR-282 ladder, ADR-301). #[error("synthetic characterization cannot be labelled measured (claimed {claimed})")] SyntheticMislabel { /// The measured evidence level that was wrongly claimed for synthetic input. diff --git a/v2/crates/wifi-densepose-mat/Cargo.toml b/v2/crates/wifi-densepose-mat/Cargo.toml index 99b4dc4b..848770f3 100644 --- a/v2/crates/wifi-densepose-mat/Cargo.toml +++ b/v2/crates/wifi-densepose-mat/Cargo.toml @@ -101,7 +101,7 @@ approx = "0.5" name = "detection_bench" harness = false -# FeitCSI record parse throughput at wideband 802.11ax shapes (ADR-289). +# FeitCSI record parse throughput at wideband 802.11ax shapes (ADR-292). [[bench]] name = "feitcsi_bench" harness = false diff --git a/v2/crates/wifi-densepose-mat/benches/feitcsi_bench.rs b/v2/crates/wifi-densepose-mat/benches/feitcsi_bench.rs index b57e9014..7e677e68 100644 --- a/v2/crates/wifi-densepose-mat/benches/feitcsi_bench.rs +++ b/v2/crates/wifi-densepose-mat/benches/feitcsi_bench.rs @@ -1,4 +1,4 @@ -//! Criterion benchmark for FeitCSI record parse throughput (ADR-289). +//! Criterion benchmark for FeitCSI record parse throughput (ADR-292). //! //! Measures `parse_record` over synthetic in-code fixtures at the wideband //! 802.11ax shapes: 20 MHz (242 tones), 80 MHz (996) and the headline diff --git a/v2/crates/wifi-densepose-mat/src/integration/feitcsi.rs b/v2/crates/wifi-densepose-mat/src/integration/feitcsi.rs index 8a883170..436a3db8 100644 --- a/v2/crates/wifi-densepose-mat/src/integration/feitcsi.rs +++ b/v2/crates/wifi-densepose-mat/src/integration/feitcsi.rs @@ -1,4 +1,4 @@ -//! Validated parser for FeitCSI binary CSI records (ADR-289). +//! Validated parser for FeitCSI binary CSI records (ADR-292). //! //! [FeitCSI](https://feitcsi.kuskosoft.com) is an open-source tool //! () that extracts 802.11ax channel @@ -49,7 +49,7 @@ //! //! The on-disk format carries **no magic number or version field** (it is the //! raw iwlwifi notification header), so the "version check" required by -//! ADR-289 is structural and strict: +//! ADR-292 is structural and strict: //! //! - the declared dimensions must agree exactly with the declared buffer //! length ([`FeitCsiError::DimensionMismatch`]); @@ -285,7 +285,7 @@ impl FeitCsiRecord { /// Convert to adapter-level [`CsiReadings`], one [`SensorCsiReading`] per /// (rx, tx) antenna pair, carrying native subcarrier count, bandwidth and - /// band as first-class frame metadata (ADR-289). + /// band as first-class frame metadata (ADR-292). /// /// The FeitCSI header does not record channel/band (the capture /// configuration owns that), so both are supplied by the caller. The @@ -633,7 +633,7 @@ impl FeitCsiFileReader { /// existing interpolation path (`wifi-densepose-signal`'s Catmull-Rom cubic /// resampler from ADR-027), recording the native → pipeline mapping in frame /// metadata so downstream consumers know the true spectral resolution -/// (ADR-289 §3). +/// (ADR-292 §3). /// /// This is the ONLY sanctioned native→pipeline conversion: it is explicit, /// and the mapping is auditable in `metadata.wideband.mapping`. diff --git a/v2/crates/wifi-densepose-mat/src/integration/hardware_adapter.rs b/v2/crates/wifi-densepose-mat/src/integration/hardware_adapter.rs index 02f9f5c0..fda589d7 100644 --- a/v2/crates/wifi-densepose-mat/src/integration/hardware_adapter.rs +++ b/v2/crates/wifi-densepose-mat/src/integration/hardware_adapter.rs @@ -130,7 +130,7 @@ impl HardwareConfig { } /// Create configuration for deterministic FeitCSI capture replay - /// (wideband 802.11ax records from Intel AX200/AX210, ADR-289). + /// (wideband 802.11ax records from Intel AX200/AX210, ADR-292). pub fn feitcsi_replay(file_path: &str) -> Self { Self::feitcsi(file_path, FeitCsiMode::FileReplay) } @@ -196,7 +196,7 @@ pub enum DeviceType { UdpReceiver, /// PCAP file replay PcapFile, - /// FeitCSI wideband 802.11ax records from Intel AX200/AX210 (ADR-289): + /// FeitCSI wideband 802.11ax records from Intel AX200/AX210 (ADR-292): /// file replay of a recorded capture, or a path/pipe an external FeitCSI /// process writes to. RuView never configures the NIC — FeitCSI's own /// tooling owns capture, per least-authority. @@ -233,7 +233,7 @@ pub enum DeviceSettings { Simulated, } -/// FeitCSI ingest mode (ADR-289). +/// FeitCSI ingest mode (ADR-292). #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum FeitCsiMode { /// Deterministic replay of a recorded capture file. @@ -243,7 +243,7 @@ pub enum FeitCsiMode { Stream, } -/// FeitCSI source settings (ADR-289). +/// FeitCSI source settings (ADR-292). /// /// The FeitCSI record header carries bandwidth (via the iwlwifi rate flags) /// but not channel/band — the capture configuration owns those — so band and @@ -353,7 +353,7 @@ impl Bandwidth { } } -/// WiFi radio band (first-class frame metadata per ADR-289). +/// WiFi radio band (first-class frame metadata per ADR-292). #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum WifiBand { /// 2.4 GHz ISM band @@ -366,7 +366,7 @@ pub enum WifiBand { /// Record of an explicit native → pipeline subcarrier conversion, so /// downstream consumers know the true spectral resolution of a frame and -/// how it was resampled (ADR-289 §3). +/// how it was resampled (ADR-292 §3). #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct SubcarrierMapping { /// Native subcarrier count as captured. @@ -377,7 +377,7 @@ pub struct SubcarrierMapping { pub method: &'static str, } -/// Wideband spectral provenance metadata (ADR-289): band, bandwidth, native +/// Wideband spectral provenance metadata (ADR-292): band, bandwidth, native /// subcarrier dimensionality, and any native → pipeline mapping applied. #[derive(Debug, Clone, PartialEq, Eq)] pub struct WidebandMeta { @@ -796,7 +796,7 @@ impl HardwareAdapter { Ok(()) } - /// Initialize FeitCSI file-replay / stream ingest (ADR-289). + /// Initialize FeitCSI file-replay / stream ingest (ADR-292). /// /// No privileged operations: RuView does not configure the NIC; the /// external FeitCSI tooling owns capture. This only validates the @@ -962,7 +962,7 @@ impl HardwareAdapter { } } - /// Read one wideband CSI frame from a FeitCSI capture or stream (ADR-289). + /// Read one wideband CSI frame from a FeitCSI capture or stream (ADR-292). /// /// Frames carry their native subcarrier count, bandwidth (20–160 MHz) and /// band (2.4/5/6 GHz) as metadata. When `pipeline_subcarriers` is @@ -1639,7 +1639,7 @@ pub struct CsiMetadata { pub noise_floor: Option, /// Frame control type pub fc_type: FrameControlType, - /// Wideband spectral provenance (ADR-289): band, native subcarrier count + /// Wideband spectral provenance (ADR-292): band, native subcarrier count /// and any native → pipeline mapping applied. `None` for legacy /// narrowband sources that predate wideband metadata. pub wideband: Option, diff --git a/v2/crates/wifi-densepose-mat/src/integration/mod.rs b/v2/crates/wifi-densepose-mat/src/integration/mod.rs index a6dc4948..124b6cc4 100644 --- a/v2/crates/wifi-densepose-mat/src/integration/mod.rs +++ b/v2/crates/wifi-densepose-mat/src/integration/mod.rs @@ -15,7 +15,7 @@ //! - **Nexmon**: For Broadcom chips with CSI firmware //! - **FeitCSI (Intel AX200/AX210)**: Wideband 802.11ax CSI up to 160 MHz / //! 1992 subcarriers including 6 GHz, ingested from recorded captures or a -//! stream written by the external FeitCSI tool (ADR-289) +//! stream written by the external FeitCSI tool (ADR-292) //! //! # Example Usage //! @@ -56,7 +56,7 @@ pub use hardware_adapter::{ CsiStream, DeviceSettings, DeviceType, - // FeitCSI wideband ingest settings (ADR-289) + // FeitCSI wideband ingest settings (ADR-292) FeitCsiMode, FeitCsiSettings, FlowControl, @@ -80,7 +80,7 @@ pub use hardware_adapter::{ // Serial settings SerialSettings, StreamingStats, - // Wideband spectral provenance (ADR-289) + // Wideband spectral provenance (ADR-292) SubcarrierMapping, // UDP settings UdpSettings, diff --git a/v2/crates/wifi-densepose-privshield/Cargo.toml b/v2/crates/wifi-densepose-privshield/Cargo.toml new file mode 100644 index 00000000..94c41cd7 --- /dev/null +++ b/v2/crates/wifi-densepose-privshield/Cargo.toml @@ -0,0 +1,32 @@ +[package] +name = "wifi-densepose-privshield" +description = "WiFi Veil privacy shield (ADR-288): compliant-waveform countermeasure against unauthorized WiFi sensing. Deterministic attacker-vs-protector experiment that drives beamforming-feedback identity inference toward chance while preserving link throughput. Std-only pure-compute leaf, no async/server/RF-hardware deps; SYNTHETIC data only." +version = "0.1.0" +edition.workspace = true +authors.workspace = true +license.workspace = true +repository.workspace = true +documentation.workspace = true +keywords.workspace = true +categories.workspace = true +readme = "README.md" + +# Intentionally dependency-free (mirrors `wifi-densepose-aether`, ADR-185 §13). +# WiFi Veil is a pure-compute experiment/reference: no `rand` (its own deterministic +# PRNG), no `std::time`/`std::fs`/`std::env`/threads, so it builds unchanged for +# `wasm32-unknown-unknown` and can never emit RF or touch a radio. The shield +# *models* compliant waveform controls; it does not drive hardware. +[dependencies] + +[dev-dependencies] + +[lib] +name = "wifi_densepose_privshield" +path = "src/lib.rs" + +# `veil` — the custom, dependency-free terminal harness + TUI (ADR-288 §harness). +# Native counterpart to the npm metaharness. Std-only; builds without any extra +# deps. Excluded from the wasm leaf story (that stays `--lib`). +[[bin]] +name = "veil" +path = "src/bin/veil.rs" diff --git a/v2/crates/wifi-densepose-privshield/README.md b/v2/crates/wifi-densepose-privshield/README.md new file mode 100644 index 00000000..2c028be0 --- /dev/null +++ b/v2/crates/wifi-densepose-privshield/README.md @@ -0,0 +1,161 @@ +![WiFi Veil Console — the shield engaged, with the room's WiFi identity clusters collapsed to the chance floor (re-ID 4.7%, throughput preserved, compliant)](docs/veil-console.png) + +# wifi-densepose-privshield — WiFi Veil + +**WiFi Veil** (codename **VEIL** — Verifiable Emission-shaping for +Identity-Leakage prevention) is the compliant-waveform **countermeasure** +counterpart to +[BFLD](../wifi-densepose-bfld) (ADR-118/121). BFLD *detects* when beamforming +feedback becomes identifying; WiFi Veil *acts* — it shapes a node's own outgoing +beamforming feedback so that an unauthorized passive sniffer cannot +re-identify people or infer activity, while a legitimate receiver (which shares +the per-session key) sees an essentially unchanged link. + +This crate is a **deterministic, dependency-free, WASM-ready reference and +experiment** — not a radio driver. It never emits RF. Every number it prints is +`SYNTHETIC`, reproduced by `cargo test -p wifi-densepose-privshield`. + +See [ADR-288](../../../docs/adr/ADR-288-veil-privacy-shield-compliant-waveform.md) +and the [research bundle](../../../docs/research/privacy-shield/). A per-crate npm +contributor harness lives at +[`harness/wifi-densepose-privshield/`](../../../harness/wifi-densepose-privshield) +(ADR-289): `npx wifi-densepose-privshield-harness guidance --topic overview`. + +## How this protects you from unauthorized WiFi surveillance + +**The threat — silent, device-free identification.** Since WiFi 5, your device +tells the router how to aim its signal by sending back *beamforming feedback* — +and it goes out **unencrypted**. Anyone within radio range can passively capture +those reports and, from the tiny stable details in them, **tell individual +people apart by their radio "fingerprint"** — through walls, with no camera, no +app, and nothing you have to be carrying. Published research re-identifies +individuals, counts occupancy through walls, and even reads activity this way, +and the 2025 sensing standard (802.11bf) added the capability but **no privacy +protection**. Because the attacker only listens, you get no indication it is +happening. + +**The defense — scramble the fingerprint, keep the link.** WiFi Veil adds a secret, +**per-session "twist"** to your own outgoing feedback, built from the same +rotation math (Givens rotations) the report already uses: + +- Your **own router shares the key** and undoes the twist instantly, so it + decodes normally — **your WiFi keeps ~98% of its speed.** +- An **outside listener sees a *different* twist every session** and cannot + average many captures back into one stable fingerprint. Its guess of *who is + in the room* **collapses to chance** — no better than a random guess among the + possible people. +- The twist only **reshapes your own, standards-legal signal** — it preserves + the signal's energy exactly (`energy in = energy out`), so it is **compliant, + never jamming.** It never floods the air or blocks anyone else. + +**What it does *not* do (kept honest).** WiFi Veil defends against a *third-party +sniffer*, not the access point you are connected to (that party holds the key — +protecting against a malicious AP is BFLD's detection job). It targets identity +re-identification; coarse motion obfuscation is future work. And every figure in +this crate is **SYNTHETIC / evidence-level L0** — it describes the reference +model and is *not* a measured guarantee on real hardware until validated with a +captured hardware log. + +> **In one line:** it makes the room's WiFi stop leaking *who you are* to +> outside listeners, while your network keeps working and without breaking any +> radio rules. + +## The idea + +Identity leaks through the **fine** cross-subcarrier phase structure of a +compressed beamforming report; data throughput rides the **dominant** beam +direction. These live in (mostly) separable subspaces. WiFi Veil composes extra +**keyed Givens rotations** — the exact primitive the report is already built +from — over the *fine* subspace only: + +| Property | Consequence | +|---|---| +| **Orthogonal** (energy-preserving) | No added transmit power ⇒ **not jamming** (47 U.S.C. §333/§302a) | +| **Keyed per session** | The legitimate AP inverts it ⇒ throughput preserved | +| **Fresh each session** | A sniffer sees a different rotation every time and can't average it back ⇒ re-identification collapses to chance | + +## Result (hyper-optimized default scene, N = 16 identities) + +| Metric | Shield off | Shield on | +|---|---|---| +| Passive re-ID accuracy | **100%** | **4.7%** (chance = 6.25%) | +| Link throughput ratio | 100% | **97.6%** | +| Emission energy ratio | — | **1.000000** (compliant) | + +The shipped shield config is not hand-picked — it is the output of the +`optimize` module (ADR-288 §opt): **96 Givens passes** (2× the proven-minimum +48 for robust collapse across both attacker metrics and N∈{16,32}; extra passes +are free because the keyed rotation is never signaled) at **5-bit** feedback +resolution (the throughput-best value in the 802.11 {5,7,9} set). The +unconstrained model optimum is 3-bit, matching the DySPAN-2026 finding. + +## Threat model & scope (stated plainly) + +WiFi Veil defends against a **third-party passive sniffer** capturing plaintext +beamforming feedback. It does **not** hide identity from the AP a node is +associated with (that party holds the key by construction) — that is BFLD's +detection/policy problem, not this shield's. It is **compliant by +construction**: it only shapes the node's own standards-conformant frames, never +transmits to interfere with another station, and never operates an unauthorized +emitter. It is not jamming, not RF denial, and not a claim of camera-grade +anything. + +## Run it + +```bash +cargo test -p wifi-densepose-privshield --no-default-features +``` + +## `veil` — terminal harness & TUI + +A custom, **dependency-free** native harness ships with the crate (the in-repo +counterpart to the npm metaharness). It drives the same model the tests use — an +interactive ANSI dashboard plus scriptable subcommands, std-only (no +`crossterm`/`ratatui`), so it runs in any terminal, pipe, or CI. + +![veil TUI walkthrough — toggling the shield off/on, dropping to 32 passes (out of spec), back to 96 (pass), a ward preset, optimize, and a witness check](docs/veil-tui.gif) + +```bash +cargo run -p wifi-densepose-privshield --bin veil # interactive TUI (or a one-shot report when piped) +cargo run -p wifi-densepose-privshield --bin veil -- sweep # re-ID vs passes + throughput vs bits +cargo run -p wifi-densepose-privshield --bin veil -- optimize +cargo run -p wifi-densepose-privshield --bin veil -- doctor # self-check, exit 0 = healthy +``` + +```text +┌────────────────────────────────────────────────────────── +│ WiFi Veil · wifi-sensing privacy shield ● PROTECTED +│ +│ re-ID off 100.0% re-ID on 4.7% (chance 6.25%) +│ throughput 97.6% emission 1.000× · not jamming +│ +│ collapse ████▇▆▅▂▂▂▁▂ passes 2→112 · op 96 +│ +│ config passes 96 · bits 5 · N 16 · snr 20dB · euclid +│ verdict ✓ PASS — re-ID at chance · throughput ≥95% · compliant +└────────────────────────────────────────────────────────── +``` + +In the TUI, type commands to steer the shield live: `on`/`off`, `passes `, +`bits `, `n `, `snr `, `metric euclid|cosine`, +`preset scif|board|ward|hotel`, `optimize`, `proof`, `quit`. All readouts are +**SYNTHETIC / L0**. + +A self-contained graphical **WiFi Veil Console** web dashboard mirrors this same +instrument — it ships in [`ui/veil-console.html`](ui/veil-console.html) (open it +in any browser; no build, no network). `veil` is the terminal-native version. + +## Modules + +| Module | Purpose | +|---|---| +| `prng` | Deterministic, WASM-safe PRNG + key derivation | +| `linalg` | Givens-rotation vector algebra | +| `identity` | SYNTHETIC two-subspace beamforming-feedback model | +| `protector` | The compliant waveform controls: keyed rotation, per-packet unitary (`ObfMode`), ε-DP dither (`dp_epsilon`) | +| `attacker` | Passive adversaries: nearest-centroid (Euclidean/Cosine), BFI→CSI `Reconstruction`, `AdaptivePooling` | +| `throughput` | Link-throughput model (quantization residual + feedback-airtime + sounding + ε-DP cost) | +| `compliance` | Machine-checkable "not jamming" audit | +| `experiment` | Attacker-vs-protector head-to-head | +| `optimize` | Finds the optimal shield config (feedback bits, min passes, Pareto frontier) | +| `proof` | Byte-stable deterministic witness | diff --git a/v2/crates/wifi-densepose-privshield/docs/veil-console.png b/v2/crates/wifi-densepose-privshield/docs/veil-console.png new file mode 100644 index 00000000..d4a9c8a9 Binary files /dev/null and b/v2/crates/wifi-densepose-privshield/docs/veil-console.png differ diff --git a/v2/crates/wifi-densepose-privshield/docs/veil-tui.gif b/v2/crates/wifi-densepose-privshield/docs/veil-tui.gif new file mode 100644 index 00000000..21b1783e Binary files /dev/null and b/v2/crates/wifi-densepose-privshield/docs/veil-tui.gif differ diff --git a/v2/crates/wifi-densepose-privshield/src/attacker.rs b/v2/crates/wifi-densepose-privshield/src/attacker.rs new file mode 100644 index 00000000..0144eb63 --- /dev/null +++ b/v2/crates/wifi-densepose-privshield/src/attacker.rs @@ -0,0 +1,364 @@ +//! The adversary: a passive re-identification classifier over captured +//! beamforming feedback. +//! +//! The attacker models the BFId/CCS-2025 threat: a sniffer that enrolls a +//! template per candidate from observed reports, then classifies fresh +//! captures. We use a **nearest-centroid** classifier over the full report +//! vector. It is deliberately simple but is the right shape for the effect +//! under test: it succeeds exactly when a *stable* per-identity signature +//! survives across capture sessions, and fails when the signature is rotated +//! unpredictably each session (which is what the protector does). +//! +//! Nearest-centroid is also the honest choice for the collapse claim: a more +//! elaborate classifier cannot recover identity that has been mapped through a +//! fresh secret orthogonal transform each session — the mutual information +//! between a Haar-rotated signature and the identity label, marginalized over +//! unknown rotations, is what the protector drives down. The classifier +//! strength is not the lever; signature stability is. + +use crate::identity::BfiSample; +use crate::linalg::{dist_sq, dot, norm, set_norm_inplace}; + +/// Similarity metric the attacker uses to match a capture to a centroid. +/// +/// Sweeping the metric is how [`crate::optimize`] checks that the shield's +/// collapse is a property of the *signal* (a rotated signature carries no +/// stable identity), not an artifact of one classifier's geometry. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum Metric { + /// Euclidean nearest-centroid (default). Sensitive to magnitude. + #[default] + Euclidean, + /// Cosine nearest-centroid. Scale-invariant; a natural stronger attacker + /// against energy-preserving perturbations, since it ignores magnitude. + Cosine, +} + +/// A nearest-centroid re-identification attacker. +#[derive(Debug, Clone, Default)] +pub struct NearestCentroidAttacker { + centroids: Vec>, + ids: Vec, + metric: Metric, +} + +impl NearestCentroidAttacker { + /// Build an empty attacker using the Euclidean metric. + #[must_use] + pub fn new() -> Self { + Self::default() + } + + /// Build an empty attacker using the given metric. + #[must_use] + pub fn with_metric(metric: Metric) -> Self { + Self { + metric, + ..Self::default() + } + } + + /// Enroll from labeled captures: one centroid per identity, the mean of + /// that identity's observed report vectors. + pub fn enroll(&mut self, samples: &[(usize, BfiSample)]) { + // Group by identity, preserving first-seen order. + let mut ids: Vec = Vec::new(); + let mut sums: Vec> = Vec::new(); + let mut counts: Vec = Vec::new(); + for (id, s) in samples { + let slot = ids.iter().position(|x| x == id).unwrap_or_else(|| { + ids.push(*id); + sums.push(vec![0.0; s.values.len()]); + counts.push(0); + ids.len() - 1 + }); + for (acc, v) in sums[slot].iter_mut().zip(&s.values) { + *acc += v; + } + counts[slot] += 1; + } + for (sum, &c) in sums.iter_mut().zip(&counts) { + if c > 0 { + let inv = 1.0 / c as f32; + for v in sum.iter_mut() { + *v *= inv; + } + } + } + self.ids = ids; + self.centroids = sums; + } + + /// Classify a capture to the nearest enrolled centroid. Returns the + /// predicted identity, or `None` if the attacker has not enrolled. + #[must_use] + pub fn classify(&self, sample: &BfiSample) -> Option { + // Score is "lower is better" for both metrics: Euclidean uses squared + // distance; Cosine uses the negated similarity. + let score = |c: &[f32]| -> f32 { + match self.metric { + Metric::Euclidean => dist_sq(c, &sample.values), + Metric::Cosine => { + let denom = norm(c) * norm(&sample.values); + if denom > 1e-12 { + -dot(c, &sample.values) / denom + } else { + 0.0 + } + } + } + }; + let mut best: Option<(usize, f32)> = None; + for (id, c) in self.ids.iter().zip(&self.centroids) { + let d = score(c); + if best.is_none_or(|(_, bd)| d < bd) { + best = Some((*id, d)); + } + } + best.map(|(id, _)| id) + } + + /// Top-1 re-identification accuracy over a labeled test set. + #[must_use] + pub fn accuracy(&self, test: &[(usize, BfiSample)]) -> f32 { + if test.is_empty() { + return 0.0; + } + let correct = test + .iter() + .filter(|(id, s)| self.classify(s) == Some(*id)) + .count(); + correct as f32 / test.len() as f32 + } +} + +/// Which adversary the experiment runs. Added from the 2025–2026 SOTA sweep +/// (ADR-288 §sota) so the collapse is shown to hold against the *strongest* +/// published attacker shapes, not just a plain nearest-centroid. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum AttackerKind { + /// Nearest-centroid on the full captured report (uses the configured [`Metric`]). + #[default] + NearestCentroid, + /// Models BFI→CSI reconstruction (BFIAttack, arXiv:2604.04179): the adversary + /// recovers the CSI *consistent with the captured report* and classifies its + /// direction. Because a keyed secret rotation has no key to invert, what it + /// reconstructs is the *rotated* CSI — so identity does not survive. + Reconstruction, + /// Pools many captures per identity and whitens before matching (the + /// PrivISAC-style adaptive/retraining adversary). Averaging cannot undo a + /// fresh secret rotation, so the pooled, whitened template still collapses. + AdaptivePooling, +} + +/// BFI→CSI reconstruction adversary. Classifies the **direction** (L2-normalized +/// fine block) of the reconstructed CSI — the strongest gain-invariant descriptor +/// an attacker can recover from a captured report. Defeated by a secret rotation +/// (it only ever recovers the rotated direction). +#[derive(Debug, Clone, Default)] +pub struct ReconstructionAttacker { + centroids: Vec>, + ids: Vec, +} + +fn reconstructed_direction(s: &BfiSample) -> Vec { + let mut v = s.fine().to_vec(); + set_norm_inplace(&mut v, 1.0); + v +} + +impl ReconstructionAttacker { + /// Build an empty reconstruction attacker. + #[must_use] + pub fn new() -> Self { + Self::default() + } + + /// Enroll direction-centroids from reconstructed captures. + pub fn enroll(&mut self, samples: &[(usize, BfiSample)]) { + let mut ids: Vec = Vec::new(); + let mut sums: Vec> = Vec::new(); + let mut counts: Vec = Vec::new(); + for (id, s) in samples { + let f = reconstructed_direction(s); + let slot = ids.iter().position(|x| x == id).unwrap_or_else(|| { + ids.push(*id); + sums.push(vec![0.0; f.len()]); + counts.push(0); + ids.len() - 1 + }); + for (acc, v) in sums[slot].iter_mut().zip(&f) { + *acc += v; + } + counts[slot] += 1; + } + for (sum, &c) in sums.iter_mut().zip(&counts) { + if c > 0 { + let inv = 1.0 / c as f32; + for v in sum.iter_mut() { + *v *= inv; + } + } + } + self.ids = ids; + self.centroids = sums; + } + + /// Classify a capture by nearest reconstructed direction. + #[must_use] + pub fn classify(&self, sample: &BfiSample) -> Option { + let f = reconstructed_direction(sample); + let mut best: Option<(usize, f32)> = None; + for (id, c) in self.ids.iter().zip(&self.centroids) { + let d = dist_sq(c, &f); + if best.is_none_or(|(_, bd)| d < bd) { + best = Some((*id, d)); + } + } + best.map(|(id, _)| id) + } + + /// Top-1 accuracy over a labeled test set. + #[must_use] + pub fn accuracy(&self, test: &[(usize, BfiSample)]) -> f32 { + if test.is_empty() { + return 0.0; + } + let correct = test + .iter() + .filter(|(id, s)| self.classify(s) == Some(*id)) + .count(); + correct as f32 / test.len() as f32 + } +} + +/// Adaptive pooling adversary: whitens the full report by per-dimension +/// standard deviation (estimated over all captures) before nearest-centroid, +/// modeling an attacker who aggregates many captures and re-fits. Whitening a +/// *fixed* coordinate basis cannot undo a rotation that mixes coordinates +/// afresh each session, so the pooled template still collapses. +#[derive(Debug, Clone, Default)] +pub struct AdaptivePoolingAttacker { + centroids: Vec>, + ids: Vec, + inv_std: Vec, +} + +impl AdaptivePoolingAttacker { + /// Build an empty adaptive pooling attacker. + #[must_use] + pub fn new() -> Self { + Self::default() + } + + /// Enroll: estimate global per-dimension inverse std, then pooled per-id + /// means. + pub fn enroll(&mut self, samples: &[(usize, BfiSample)]) { + if samples.is_empty() { + return; + } + let dim = samples[0].1.values.len(); + let n = samples.len() as f32; + let mut mean = vec![0.0f32; dim]; + for (_, s) in samples { + for (m, v) in mean.iter_mut().zip(&s.values) { + *m += v; + } + } + for m in &mut mean { + *m /= n; + } + let mut var = vec![0.0f32; dim]; + for (_, s) in samples { + for ((vv, v), m) in var.iter_mut().zip(&s.values).zip(&mean) { + let d = v - m; + *vv += d * d; + } + } + self.inv_std = var + .iter() + .map(|v| 1.0 / ((v / n).sqrt().max(1e-6))) + .collect(); + + let mut ids: Vec = Vec::new(); + let mut sums: Vec> = Vec::new(); + let mut counts: Vec = Vec::new(); + for (id, s) in samples { + let slot = ids.iter().position(|x| x == id).unwrap_or_else(|| { + ids.push(*id); + sums.push(vec![0.0; dim]); + counts.push(0); + ids.len() - 1 + }); + for (acc, v) in sums[slot].iter_mut().zip(&s.values) { + *acc += v; + } + counts[slot] += 1; + } + for (sum, &c) in sums.iter_mut().zip(&counts) { + if c > 0 { + let inv = 1.0 / c as f32; + for v in sum.iter_mut() { + *v *= inv; + } + } + } + self.ids = ids; + self.centroids = sums; + } + + /// Classify by whitened nearest-centroid. + #[must_use] + pub fn classify(&self, sample: &BfiSample) -> Option { + let mut best: Option<(usize, f32)> = None; + for (id, c) in self.ids.iter().zip(&self.centroids) { + let mut d = 0.0f32; + for ((cv, sv), w) in c.iter().zip(&sample.values).zip(&self.inv_std) { + let diff = (cv - sv) * w; + d += diff * diff; + } + if best.is_none_or(|(_, bd)| d < bd) { + best = Some((*id, d)); + } + } + best.map(|(id, _)| id) + } + + /// Top-1 accuracy over a labeled test set. + #[must_use] + pub fn accuracy(&self, test: &[(usize, BfiSample)]) -> f32 { + if test.is_empty() { + return 0.0; + } + let correct = test + .iter() + .filter(|(id, s)| self.classify(s) == Some(*id)) + .count(); + correct as f32 / test.len() as f32 + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::identity::{Channel, SceneConfig}; + + #[test] + fn attacker_re_ids_unprotected_traffic() { + let ch = Channel::new(SceneConfig::default()); + let mut enroll = Vec::new(); + let mut test = Vec::new(); + for id in 0..ch.config().identities { + for s in 0..12 { + enroll.push((id, ch.observe(id, b"enroll", s))); + } + for s in 0..12 { + test.push((id, ch.observe(id, b"test", s))); + } + } + let mut atk = NearestCentroidAttacker::new(); + atk.enroll(&enroll); + // On unprotected traffic the stable signature is trivially recovered. + assert!(atk.accuracy(&test) > 0.85); + } +} diff --git a/v2/crates/wifi-densepose-privshield/src/bin/veil.rs b/v2/crates/wifi-densepose-privshield/src/bin/veil.rs new file mode 100644 index 00000000..57701d2f --- /dev/null +++ b/v2/crates/wifi-densepose-privshield/src/bin/veil.rs @@ -0,0 +1,549 @@ +//! `veil` — a custom, dependency-free terminal harness for the VEIL privacy +//! shield (ADR-288). It is the in-repo, native counterpart to the npm +//! metaharness (`harness/wifi-densepose-privshield/`, ADR-289): where that one +//! assists *development*, this one *drives the model* — an interactive TUI plus +//! scriptable subcommands over the same crate API the tests use. +//! +//! Std-only on purpose: no `crossterm`/`ratatui`, no external deps. The TUI is +//! a command-driven ANSI dashboard (line input, redraw on change), which keeps +//! the crate a pure leaf and lets the harness run in any pipe or CI. +//! +//! ```text +//! veil # TUI if attached to a terminal, else a one-shot report +//! veil tui # force the interactive dashboard +//! veil report # print the dashboard once (plain, pipe-friendly) +//! veil sweep # re-ID vs passes and throughput vs bits tables +//! veil optimize # run the hyper-optimizer, print the recommendation +//! veil adaptive # derive the shield for a room of N candidate identities +//! veil proof # verify the deterministic witness +//! veil doctor # self-check (exit 0 = healthy) +//! ``` +//! +//! All numbers are **SYNTHETIC / L0** — reproduced by `cargo test`, describing +//! the model, not real hardware. + +use std::io::{self, BufRead, IsTerminal, Write}; + +use veil::optimize; +use veil::{run, ExperimentConfig, ExperimentReport, Metric, Proof}; +use wifi_densepose_privshield as veil; + +// ---- ANSI palette (matches the VEIL Console: teal shield, amber threat) ---- +const TEAL: &str = "\x1b[38;2;32;211;192m"; +const AMBER: &str = "\x1b[38;2;245;158;75m"; +const GOOD: &str = "\x1b[38;2;62;207;142m"; +const CRIT: &str = "\x1b[38;2;242;107;111m"; +const MUTE: &str = "\x1b[38;2;139;160;159m"; +const BOLD: &str = "\x1b[1m"; +const RST: &str = "\x1b[0m"; +const BLOCKS: [char; 8] = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']; + +/// Emit color for a real terminal; never when `NO_COLOR` is set; always when +/// `CLICOLOR_FORCE` is set (so piped captures keep their color). +fn color_enabled() -> bool { + if std::env::var_os("NO_COLOR").is_some() { + return false; + } + if std::env::var_os("CLICOLOR_FORCE").is_some() { + return true; + } + io::stdout().is_terminal() +} + +/// Wrap `s` in `code` when color is on. +fn c(s: &str, code: &str, on: bool) -> String { + if on { + format!("{code}{s}{RST}") + } else { + s.to_string() + } +} + +/// A raw color code, or "" when color is off — for inline `format!` colouring. +fn k(code: &'static str, on: bool) -> &'static str { + if on { + code + } else { + "" + } +} + +/// Shield-on re-ID at a given mixing budget, holding the rest of `cfg`. +fn reid_at(cfg: &ExperimentConfig, passes: usize) -> f32 { + let mut c = cfg.clone(); + c.shield.givens_passes = passes; + run(&c).accuracy_shield_on +} + +/// A block-sparkline character for a value in `[0, 1]`. +fn spark(v: f32) -> char { + let i = (v.clamp(0.0, 1.0) * 7.0).round() as usize; + BLOCKS[i.min(7)] +} + +/// Render the full dashboard as colored lines (left-bar panel; no right border, +/// so ANSI escape width never has to be counted). +fn dashboard(cfg: &ExperimentConfig, on: bool) -> Vec { + let rep: ExperimentReport = run(cfg); + let chance = rep.chance_level * 100.0; + let off = rep.accuracy_shield_off * 100.0; + let onp = rep.accuracy_shield_on * 100.0; + let tp = rep.throughput_ratio * 100.0; + + let (state, scode) = if !cfg.shield.enabled { + ("EXPOSED", CRIT) + } else if rep.passed() { + ("PROTECTED", GOOD) + } else { + ("AT RISK", AMBER) + }; + let on_code = if onp <= rep.chance_band * 100.0 { + GOOD + } else { + AMBER + }; + let tp_code = if tp >= 95.0 { GOOD } else { CRIT }; + let bar = c("│", MUTE, on); + + let mut out = Vec::new(); + out.push(c( + "┌──────────────────────────────────────────────────────────", + MUTE, + on, + )); + out.push(format!( + "{} {}{}VEIL{} {}· wifi-sensing privacy shield{} {}● {}{}", + bar, + k(BOLD, on), + k(TEAL, on), + k(RST, on), + k(MUTE, on), + k(RST, on), + k(scode, on), + state, + k(RST, on), + )); + out.push(bar.clone()); + out.push(format!( + "{} re-ID off {}{:>6.1}%{} re-ID on {}{:>5.1}%{} {}(chance {:.2}%){}", + bar, + k(AMBER, on), + off, + k(RST, on), + k(on_code, on), + onp, + k(RST, on), + k(MUTE, on), + chance, + k(RST, on), + )); + out.push(format!( + "{} throughput {}{:>6.1}%{} emission {}{:.3}×{} {}· not jamming{}", + bar, + k(tp_code, on), + tp, + k(RST, on), + k(GOOD, on), + rep.compliance.energy_ratio, + k(RST, on), + k(MUTE, on), + k(RST, on), + )); + out.push(bar.clone()); + + let cand = optimize::PASS_CANDIDATES; + let line: String = cand.iter().map(|&p| spark(reid_at(cfg, p))).collect(); + out.push(format!( + "{} {}collapse{} {}{}{} {}passes {}→{} · op {}{}", + bar, + k(MUTE, on), + k(RST, on), + k(TEAL, on), + line, + k(RST, on), + k(MUTE, on), + cand[0], + cand[cand.len() - 1], + cfg.shield.givens_passes, + k(RST, on), + )); + out.push(bar.clone()); + + let metric = match cfg.attacker_metric { + Metric::Euclidean => "euclid", + Metric::Cosine => "cosine", + }; + out.push(format!( + "{} {}config{} passes {} · bits {} · N {} · snr {:.0}dB · {}", + bar, + k(MUTE, on), + k(RST, on), + cfg.shield.givens_passes, + cfg.shield.feedback_bits, + cfg.scene.identities, + cfg.link.snr_db, + metric, + )); + let (vlabel, vcode) = if !cfg.shield.enabled { + ("SHIELD OFF — room exposed", CRIT) + } else if rep.passed() { + ( + "✓ PASS — re-ID at chance · throughput ≥95% · compliant", + GOOD, + ) + } else { + ( + "△ OUT OF SPEC — raise passes/bits to re-enter the chance band", + AMBER, + ) + }; + out.push(format!( + "{} {}verdict{} {}{}{}", + bar, + k(MUTE, on), + k(RST, on), + k(vcode, on), + vlabel, + k(RST, on) + )); + out.push(c( + "└──────────────────────────────────────────────────────────", + MUTE, + on, + )); + out +} + +/// Deployment presets (mirror `optimize::adaptive_shield` results per room). +fn preset(name: &str, cfg: &mut ExperimentConfig) -> bool { + let (n, passes, bits, snr) = match name { + "scif" => (64, 96, 5, 20.0), + "board" => (16, 96, 5, 25.0), + "ward" => (32, 96, 5, 15.0), + "hotel" => (48, 64, 5, 20.0), + _ => return false, + }; + cfg.scene.identities = n; + cfg.shield.givens_passes = passes; + cfg.shield.feedback_bits = bits; + cfg.link.snr_db = snr; + true +} + +fn print_dashboard(cfg: &ExperimentConfig, on: bool) { + for l in dashboard(cfg, on) { + println!("{l}"); + } +} + +fn cmd_sweep(cfg: &ExperimentConfig, on: bool) { + println!( + "{}re-ID (shield on) vs Givens passes — N={}{}", + k(MUTE, on), + cfg.scene.identities, + k(RST, on) + ); + for &p in &optimize::PASS_CANDIDATES { + let robust = + optimize::passes_collapse_at_n(cfg, p, cfg.shield.feedback_bits, cfg.scene.identities); + println!( + " passes {:>3} re-ID {:>5.1}% {}", + p, + reid_at(cfg, p) * 100.0, + if robust { + c("collapses", GOOD, on) + } else { + c("above chance", AMBER, on) + } + ); + } + println!( + "\n{}throughput vs feedback bits — snr={:.0}dB{}", + k(MUTE, on), + cfg.link.snr_db, + k(RST, on) + ); + for bits in 1..=12u32 { + let mut s = cfg.shield.clone(); + s.feedback_bits = bits; + let tp = cfg.link.throughput_ratio(&s) * 100.0; + let barlen = ((tp - 90.0).clamp(0.0, 10.0) / 10.0 * 24.0) as usize; + println!( + " {:>2} bit {:>6.3}% {}{}{}", + bits, + tp, + k(TEAL, on), + "█".repeat(barlen), + k(RST, on) + ); + } + let (sb, _) = optimize::spec_optimal_feedback_bits(cfg); + println!(" {}spec-optimal: {} bit{}", k(MUTE, on), sb, k(RST, on)); +} + +fn cmd_optimize(cfg: &ExperimentConfig, on: bool) { + let opt = veil::hyper_optimize(cfg); + let r = &opt.report; + println!("{}hyper-optimizer{}", k(BOLD, on), k(RST, on)); + println!(" min robust passes : {}", opt.min_passes); + println!( + " shipped passes : {} {}(min × 2 margin, throughput-free){}", + opt.shipped_passes, + k(MUTE, on), + k(RST, on) + ); + println!( + " spec-optimal bits : {} {}(model optimum {}){}", + opt.spec_optimal_bits, + k(MUTE, on), + opt.model_optimal_bits, + k(RST, on) + ); + println!( + " result : re-ID {}{:.1}%{} · throughput {}{:.1}%{} · {}", + k(GOOD, on), + r.accuracy_shield_on * 100.0, + k(RST, on), + k(GOOD, on), + r.throughput_ratio * 100.0, + k(RST, on), + if r.passed() { + c("PASS", GOOD, on) + } else { + c("FAIL", CRIT, on) + } + ); + println!( + " {}SNR → model-optimal bits: {:?}{}", + k(MUTE, on), + optimize::optimal_bits_across_snr(cfg), + k(RST, on) + ); +} + +fn cmd_adaptive(cfg: &ExperimentConfig, n: usize, on: bool) { + let sh = veil::adaptive_shield(cfg, n); + println!( + "adaptive shield for N={}: passes {} · bits {} {}(mixing budget is N-independent in this model){}", + n, sh.givens_passes, sh.feedback_bits, k(MUTE, on), k(RST, on) + ); +} + +fn cmd_proof(on: bool) -> i32 { + let w = Proof::witness(&Proof::run_reference()); + let ok = w == Proof::EXPECTED_WITNESS; + println!( + "witness {:#018x} expected {:#018x} {}", + w, + Proof::EXPECTED_WITNESS, + if ok { + c("MATCH", GOOD, on) + } else { + c("DRIFT", CRIT, on) + } + ); + i32::from(!ok) +} + +fn cmd_doctor(on: bool) -> i32 { + let rep = run(&ExperimentConfig::default()); + let checks = [ + ("reference experiment passes", rep.passed()), + ( + "attack is real without shield", + rep.attack_is_effective_without_shield(), + ), + ("collapse drives to chance", rep.drives_to_chance()), + ("throughput ≥ 95%", rep.preserves_throughput()), + ("emission is compliant", rep.compliance.is_compliant()), + ( + "deterministic witness matches", + Proof::witness(&Proof::run_reference()) == Proof::EXPECTED_WITNESS, + ), + ]; + let mut ok = true; + for (label, pass) in checks { + ok &= pass; + println!( + "{} {label}", + if pass { + c("PASS", GOOD, on) + } else { + c("FAIL", CRIT, on) + } + ); + } + println!( + "\nveil doctor: {}", + if ok { + c("all checks passed", GOOD, on) + } else { + c("problems found", CRIT, on) + } + ); + i32::from(!ok) +} + +fn help() { + println!( + "veil — VEIL privacy-shield harness (SYNTHETIC / L0)\n\n\ + USAGE\n veil [command]\n\n\ + COMMANDS\n\ + \x20 tui interactive dashboard (default on a terminal)\n\ + \x20 report print the dashboard once\n\ + \x20 sweep re-ID vs passes + throughput vs bits\n\ + \x20 optimize run the hyper-optimizer\n\ + \x20 adaptive derive the shield for N candidate identities\n\ + \x20 proof verify the deterministic witness\n\ + \x20 doctor self-check (exit 0 = healthy)\n\ + \x20 help this text\n\n\ + TUI COMMANDS (type + Enter)\n\ + \x20 on | off toggle the shield\n\ + \x20 passes · bits · n · snr \n\ + \x20 metric euclid|cosine\n\ + \x20 preset scif|board|ward|hotel\n\ + \x20 run | optimize | proof | help | quit" + ); +} + +fn tui(mut cfg: ExperimentConfig, on: bool) { + let stdin = io::stdin(); + let interactive = stdin.is_terminal(); + let redraw = |cfg: &ExperimentConfig, msg: &str| { + if interactive { + print!("\x1b[2J\x1b[H"); + } + print_dashboard(cfg, on); + if !msg.is_empty() { + println!(" {}{}{}", k(MUTE, on), msg, k(RST, on)); + } + print!("{}veil›{} ", k(TEAL, on), k(RST, on)); + let _ = io::stdout().flush(); + }; + redraw(&cfg, "type `help` for commands"); + for line in stdin.lock().lines() { + let line = match line { + Ok(l) => l, + Err(_) => break, + }; + let mut it = line.split_whitespace(); + let cmd = it.next().unwrap_or(""); + let arg = it.next().unwrap_or(""); + let mut msg = String::new(); + match cmd { + "" => {} + "quit" | "q" | "exit" => break, + "help" | "h" => { + if interactive { + print!("\x1b[2J\x1b[H"); + } + help(); + continue; + } + "on" => cfg.shield.enabled = true, + "off" => cfg.shield.enabled = false, + "passes" => match arg.parse::() { + Ok(v) => cfg.shield.givens_passes = v.clamp(1, 512), + Err(_) => msg = "passes: need a number".into(), + }, + "bits" => match arg.parse::() { + Ok(v) => cfg.shield.feedback_bits = v.clamp(1, 12), + Err(_) => msg = "bits: need 1..12".into(), + }, + "n" => match arg.parse::() { + Ok(v) => cfg.scene.identities = v.clamp(2, 128), + Err(_) => msg = "n: need 2..128".into(), + }, + "snr" => match arg.parse::() { + Ok(v) => cfg.link.snr_db = v.clamp(0.0, 60.0), + Err(_) => msg = "snr: need a number (dB)".into(), + }, + "metric" => match arg { + "euclid" | "euclidean" => cfg.attacker_metric = Metric::Euclidean, + "cosine" | "cos" => cfg.attacker_metric = Metric::Cosine, + _ => msg = "metric: euclid | cosine".into(), + }, + "preset" => { + if !preset(arg, &mut cfg) { + msg = "preset: scif | board | ward | hotel".into(); + } + } + "run" => msg = "ran — numbers above reflect current settings".into(), + "optimize" | "opt" => { + cfg.shield = veil::hyper_optimize(&cfg).shield; + msg = format!( + "optimized → passes {} · bits {}", + cfg.shield.givens_passes, cfg.shield.feedback_bits + ); + } + "proof" => { + let w = Proof::witness(&Proof::run_reference()); + msg = format!( + "witness {:#018x} ({})", + w, + if w == Proof::EXPECTED_WITNESS { + "match" + } else { + "drift" + } + ); + } + other => msg = format!("unknown: {other} (try `help`)"), + } + redraw(&cfg, &msg); + } + if interactive { + println!(); + } +} + +fn main() { + let on = color_enabled(); + let args: Vec = std::env::args().skip(1).collect(); + let cfg = ExperimentConfig::default(); + let code = match args.first().map(String::as_str).unwrap_or("") { + "" => { + if io::stdout().is_terminal() { + tui(cfg, on); + } else { + print_dashboard(&cfg, on); + } + 0 + } + "tui" => { + tui(cfg, on); + 0 + } + "report" => { + print_dashboard(&cfg, on); + 0 + } + "sweep" => { + cmd_sweep(&cfg, on); + 0 + } + "optimize" | "opt" => { + cmd_optimize(&cfg, on); + 0 + } + "adaptive" => { + let n = args + .get(1) + .and_then(|s| s.parse().ok()) + .unwrap_or(cfg.scene.identities); + cmd_adaptive(&cfg, n, on); + 0 + } + "proof" => cmd_proof(on), + "doctor" => cmd_doctor(on), + "help" | "-h" | "--help" => { + help(); + 0 + } + other => { + eprintln!("unknown command: {other}. Try `veil help`."); + 2 + } + }; + std::process::exit(code); +} diff --git a/v2/crates/wifi-densepose-privshield/src/compliance.rs b/v2/crates/wifi-densepose-privshield/src/compliance.rs new file mode 100644 index 00000000..29f426c0 --- /dev/null +++ b/v2/crates/wifi-densepose-privshield/src/compliance.rs @@ -0,0 +1,79 @@ +//! Machine-checkable compliance: the shield shapes its own frames, never jams. +//! +//! Jamming (47 U.S.C. §333, §302a) is defined by *adding energy to interfere +//! with others' transmissions*. VEIL's protector applies an **orthogonal** +//! transform to its own beamforming feedback, which preserves the report's +//! energy exactly. This module turns that invariant into a checked artifact: it +//! measures the input/output energy of a protection step and asserts the ratio +//! is ~1, i.e. no energy was added. A regulator, an auditor, or the runtime +//! attestation layer (ADR-141) can read a [`ComplianceReport`] and see the +//! shield is a waveform-shaping control, not an emitter of interference. + +use crate::identity::BfiSample; +use crate::linalg::norm_sq; + +/// Tolerance on the energy ratio. Orthogonal rotations are exact up to f32 +/// round-off across many Givens passes. +pub const ENERGY_TOLERANCE: f32 = 1e-2; + +/// The result of auditing one protection step. +#[derive(Debug, Clone, PartialEq)] +pub struct ComplianceReport { + /// Energy of the report before protection. + pub input_energy: f32, + /// Energy of the report after protection. + pub output_energy: f32, + /// `output_energy / input_energy`. ~1.0 for an energy-preserving control. + pub energy_ratio: f32, + /// True iff the energy ratio is within [`ENERGY_TOLERANCE`] of 1.0. + pub energy_conserving: bool, + /// True iff the control adds energy on top of another station's signal. + /// Always false for VEIL by construction — it transforms its own report. + pub adds_interfering_energy: bool, +} + +impl ComplianceReport { + /// Audit a `(before, after)` protection pair. + #[must_use] + pub fn audit(before: &BfiSample, after: &BfiSample) -> Self { + let input_energy = norm_sq(&before.values); + let output_energy = norm_sq(&after.values); + let energy_ratio = if input_energy > 1e-12 { + output_energy / input_energy + } else { + 1.0 + }; + Self { + input_energy, + output_energy, + energy_ratio, + energy_conserving: (energy_ratio - 1.0).abs() <= ENERGY_TOLERANCE, + adds_interfering_energy: false, + } + } + + /// The bottom-line compliance verdict: energy-preserving and + /// non-interfering ⇒ a compliant waveform control, not jamming. + #[must_use] + pub fn is_compliant(&self) -> bool { + self.energy_conserving && !self.adds_interfering_energy + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::identity::{Channel, SceneConfig}; + use crate::protector::{Protector, ShieldConfig}; + + #[test] + fn protection_is_compliant() { + let ch = Channel::new(SceneConfig::default()); + let s = ch.observe(0, b"enroll", 3); + let p = Protector::new(ShieldConfig::default()); + let out = p.protect(&s, 555); + let report = ComplianceReport::audit(&s, &out); + assert!(report.is_compliant(), "{report:?}"); + assert!((report.energy_ratio - 1.0).abs() < ENERGY_TOLERANCE); + } +} diff --git a/v2/crates/wifi-densepose-privshield/src/experiment.rs b/v2/crates/wifi-densepose-privshield/src/experiment.rs new file mode 100644 index 00000000..b2a2cdf4 --- /dev/null +++ b/v2/crates/wifi-densepose-privshield/src/experiment.rs @@ -0,0 +1,352 @@ +//! The attacker-vs-protector head-to-head. +//! +//! This is the "one node is the attacker, one node is the protector" experiment +//! from the project brief, in deterministic synthetic form. It runs the passive +//! re-identification attacker ([`crate::attacker`]) twice — once against +//! unprotected traffic and once against traffic shaped by the protector +//! ([`crate::protector`]) — and reports both accuracies against the chance +//! floor, alongside the modeled link throughput ([`crate::throughput`]) and a +//! compliance audit ([`crate::compliance`]). +//! +//! Success criteria (the brief's own bar): +//! 1. protection drives re-identification toward chance (`1/identities`); +//! 2. throughput stays above 95% of the unshielded baseline; +//! 3. the control is compliant (energy-preserving, non-jamming). + +use crate::attacker::{ + AdaptivePoolingAttacker, AttackerKind, Metric, NearestCentroidAttacker, ReconstructionAttacker, +}; +use crate::compliance::ComplianceReport; +use crate::identity::{Channel, SceneConfig}; +use crate::prng::derive_key; +use crate::protector::{ObfMode, Protector, ShieldConfig}; +use crate::throughput::LinkModel; + +/// Configuration for a full experiment. +#[derive(Debug, Clone)] +pub struct ExperimentConfig { + /// Synthetic scene. + pub scene: SceneConfig, + /// Protector configuration. + pub shield: ShieldConfig, + /// Link model for the throughput estimate. + pub link: LinkModel, + /// Enrollment sessions per identity. + pub enroll_sessions: u64, + /// Test sessions per identity. + pub test_sessions: u64, + /// Accept re-ID as "at chance" if it is at or below + /// `chance × chance_multiple + chance_margin`. + pub chance_multiple: f32, + /// Additive slack on the chance band. + pub chance_margin: f32, + /// Minimum acceptable throughput ratio. + pub min_throughput_ratio: f64, + /// Metric the passive attacker uses (for the nearest-centroid kind). + pub attacker_metric: Metric, + /// Which adversary shape to run. + pub attacker_kind: AttackerKind, +} + +impl Default for ExperimentConfig { + fn default() -> Self { + Self { + scene: SceneConfig::default(), + shield: ShieldConfig::default(), + link: LinkModel::default(), + enroll_sessions: 12, + test_sessions: 12, + chance_multiple: 2.0, + chance_margin: 0.03, + min_throughput_ratio: 0.95, + attacker_metric: Metric::Euclidean, + attacker_kind: AttackerKind::NearestCentroid, + } + } +} + +/// The outcome of an experiment. +#[derive(Debug, Clone, PartialEq)] +pub struct ExperimentReport { + /// Number of candidate identities. + pub identities: usize, + /// Ideal chance-level accuracy (`1/identities`). + pub chance_level: f32, + /// Re-identification accuracy with the shield off. + pub accuracy_shield_off: f32, + /// Re-identification accuracy with the shield on. + pub accuracy_shield_on: f32, + /// Modeled throughput ratio of the protected link vs baseline. + pub throughput_ratio: f64, + /// Compliance audit of a representative protected frame. + pub compliance: ComplianceReport, + /// Upper edge of the accepted "at chance" band. + pub chance_band: f32, +} + +impl ExperimentReport { + /// Did protection drive re-identification into the chance band? + #[must_use] + pub fn drives_to_chance(&self) -> bool { + self.accuracy_shield_on <= self.chance_band + } + + /// Is the shield-off attacker meaningfully better than chance (i.e. the + /// threat is real in this scene, so the collapse is meaningful)? + #[must_use] + pub fn attack_is_effective_without_shield(&self) -> bool { + self.accuracy_shield_off >= 0.5 + } + + /// Did throughput stay above the required floor? + #[must_use] + pub fn preserves_throughput(&self) -> bool { + self.throughput_ratio >= 0.95 + } + + /// Overall pass: real threat, collapsed to chance, throughput preserved, + /// and compliant. + #[must_use] + pub fn passed(&self) -> bool { + self.attack_is_effective_without_shield() + && self.drives_to_chance() + && self.preserves_throughput() + && self.compliance.is_compliant() + } +} + +/// Build the enroll/test capture sets for a given shield, then measure attacker +/// accuracy. `shield_on` selects whether the protector is applied to every +/// captured frame (the attacker only ever sees what is transmitted). +fn measure_accuracy( + cfg: &ExperimentConfig, + ch: &Channel, + protector: &Protector, + shield_on: bool, +) -> f32 { + let mut enroll = Vec::new(); + let mut test = Vec::new(); + + for id in 0..cfg.scene.identities { + for s in 0..cfg.enroll_sessions { + let raw = ch.observe(id, b"enroll", s); + let seen = if shield_on { + protector.protect(&raw, rotation_key(cfg, b"enroll", s, id)) + } else { + raw + }; + enroll.push((id, seen)); + } + for s in 0..cfg.test_sessions { + let raw = ch.observe(id, b"test", s); + let seen = if shield_on { + protector.protect(&raw, rotation_key(cfg, b"test", s, id)) + } else { + raw + }; + test.push((id, seen)); + } + } + + // Dispatch on the adversary shape (SOTA sweep, ADR-288 §sota). + match cfg.attacker_kind { + AttackerKind::NearestCentroid => { + let mut a = NearestCentroidAttacker::with_metric(cfg.attacker_metric); + a.enroll(&enroll); + a.accuracy(&test) + } + AttackerKind::Reconstruction => { + let mut a = ReconstructionAttacker::new(); + a.enroll(&enroll); + a.accuracy(&test) + } + AttackerKind::AdaptivePooling => { + let mut a = AdaptivePoolingAttacker::new(); + a.enroll(&enroll); + a.accuracy(&test) + } + } +} + +/// Derive the rotation key for a capture. In [`ObfMode::KeyedRotation`] the key +/// is per **session** (same rotation for every identity present in that sounding +/// interval — the AP rotates its precoder per interval, not per person; this is +/// what a legitimate receiver inverts and what makes cross-session averaging +/// collapse). In [`ObfMode::PerPacketUnitary`] it is per **packet** (unique per +/// capture), modeling the AP-side, client-transparent fresh-unitary defense. +/// The `KeyedRotation` labels are unchanged from the original so the reference +/// witness is stable. +fn rotation_key(cfg: &ExperimentConfig, phase: &[u8], session: u64, id: usize) -> u64 { + match cfg.shield.mode { + ObfMode::KeyedRotation => { + let label: &[u8] = if phase == b"enroll" { + b"rot-enroll" + } else { + b"rot-test" + }; + derive_key(cfg.scene.seed, label, session, 0) + } + ObfMode::PerPacketUnitary => { + let label: &[u8] = if phase == b"enroll" { + b"rot-enroll-pkt" + } else { + b"rot-test-pkt" + }; + derive_key(cfg.scene.seed, label, session, id as u64) + } + } +} + +/// Run the full attacker-vs-protector experiment. +#[must_use] +pub fn run(cfg: &ExperimentConfig) -> ExperimentReport { + let protector = Protector::new(cfg.shield.clone()); + let ch = Channel::new(cfg.scene.clone()); + + let accuracy_shield_off = measure_accuracy(cfg, &ch, &protector, false); + let accuracy_shield_on = measure_accuracy(cfg, &ch, &protector, true); + + let throughput_ratio = cfg.link.throughput_ratio(&cfg.shield); + + // Representative compliance audit: one protected frame vs its clean form. + let clean = ch.observe(0, b"test", 0); + let protected = protector.protect(&clean, derive_key(cfg.scene.seed, b"rot-test", 0, 0)); + let compliance = ComplianceReport::audit(&clean, &protected); + + let chance_level = cfg.scene.chance_level(); + let chance_band = chance_level * cfg.chance_multiple + cfg.chance_margin; + + ExperimentReport { + identities: cfg.scene.identities, + chance_level, + accuracy_shield_off, + accuracy_shield_on, + throughput_ratio, + compliance, + chance_band, + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn shield_off_attack_succeeds() { + let report = run(&ExperimentConfig::default()); + assert!( + report.attack_is_effective_without_shield(), + "shield-off accuracy {} should be well above chance {}", + report.accuracy_shield_off, + report.chance_level + ); + } + + #[test] + fn shield_on_drives_to_chance() { + let report = run(&ExperimentConfig::default()); + assert!( + report.drives_to_chance(), + "shield-on accuracy {} should be within chance band {}", + report.accuracy_shield_on, + report.chance_band + ); + } + + #[test] + fn shield_preserves_throughput() { + let report = run(&ExperimentConfig::default()); + assert!( + report.preserves_throughput(), + "throughput ratio {} below 0.95", + report.throughput_ratio + ); + } + + #[test] + fn overall_experiment_passes() { + let report = run(&ExperimentConfig::default()); + assert!(report.passed(), "{report:#?}"); + } + + #[test] + fn experiment_is_deterministic() { + assert_eq!( + run(&ExperimentConfig::default()), + run(&ExperimentConfig::default()) + ); + } + + // ---- SOTA-driven adversaries and modes (ADR-288 §sota) ---- + + #[test] + fn reconstruction_attacker_collapses() { + // BFIAttack-style: reconstruction recovers the *rotated* CSI direction, + // so a secret orthogonal rotation still drives it to chance — but it + // works fine on unprotected traffic (sanity that the attacker is real). + let cfg = ExperimentConfig { + attacker_kind: AttackerKind::Reconstruction, + ..ExperimentConfig::default() + }; + let r = run(&cfg); + assert!( + r.accuracy_shield_off >= 0.5, + "recon off {}", + r.accuracy_shield_off + ); + assert!(r.drives_to_chance(), "recon on {}", r.accuracy_shield_on); + } + + #[test] + fn adaptive_pooling_attacker_collapses() { + let cfg = ExperimentConfig { + attacker_kind: AttackerKind::AdaptivePooling, + ..ExperimentConfig::default() + }; + let r = run(&cfg); + assert!( + r.accuracy_shield_off >= 0.5, + "pool off {}", + r.accuracy_shield_off + ); + assert!(r.drives_to_chance(), "pool on {}", r.accuracy_shield_on); + } + + #[test] + fn per_packet_unitary_mode_collapses_and_is_compliant() { + let cfg = ExperimentConfig { + shield: ShieldConfig { + mode: ObfMode::PerPacketUnitary, + ..ShieldConfig::default() + }, + ..ExperimentConfig::default() + }; + let r = run(&cfg); + assert!( + r.drives_to_chance(), + "per-packet on {}", + r.accuracy_shield_on + ); + assert!(r.compliance.is_compliant()); + } + + #[test] + fn dp_epsilon_still_collapses_and_stays_compliant() { + // Layering the ε-DP dither on the rotation keeps the collapse and, thanks + // to renormalization, keeps the emission energy-preserving (not jamming). + let cfg = ExperimentConfig { + shield: ShieldConfig { + dp_epsilon: Some(1.0), + ..ShieldConfig::default() + }, + ..ExperimentConfig::default() + }; + let r = run(&cfg); + assert!(r.drives_to_chance()); + assert!( + r.compliance.is_compliant(), + "energy {}", + r.compliance.energy_ratio + ); + } +} diff --git a/v2/crates/wifi-densepose-privshield/src/identity.rs b/v2/crates/wifi-densepose-privshield/src/identity.rs new file mode 100644 index 00000000..ca3d3c73 --- /dev/null +++ b/v2/crates/wifi-densepose-privshield/src/identity.rs @@ -0,0 +1,204 @@ +//! Synthetic beamforming-feedback model. **SYNTHETIC data only.** +//! +//! Nothing here is captured from a real radio. The model is a deliberately +//! simple, physically-motivated abstraction of a flattened 802.11 compressed +//! beamforming report, chosen so the attacker/protector dynamics are +//! transparent and the experiment is byte-reproducible. It is *not* a channel +//! simulator and its accuracy numbers describe this model, not real hardware +//! (per CLAUDE.md: results are `SYNTHETIC`, reproduced by `cargo test`). +//! +//! # The two-subspace abstraction +//! +//! A beamforming report is split into two orthogonal blocks: +//! +//! - **Comm block** (`comm_dims` leading coordinates) — the dominant beam +//! direction the AP actually uses to steer data. It varies per session with +//! position/traffic and carries **no** identity. Link throughput rides here. +//! - **Fine block** (the remainder) — the fine cross-subcarrier phase +//! structure. This is where a re-identification attacker's signal lives: the +//! literature (BFId, CCS 2025) shows the *stable* fine structure re-IDs +//! people. Communication barely uses it. +//! +//! Each identity owns a fixed, near-orthogonal signature vector in the fine +//! block. A session observation is `signature + environmental nuisance`; the +//! comm block is fresh per session. This is the honest crux of the whole +//! design: **identity leakage and data throughput live in (mostly) separable +//! subspaces**, so a transform can wreck the former while sparing the latter. + +use crate::linalg::set_norm_inplace; +use crate::prng::{derive_key, Rng}; + +/// A flattened compressed-beamforming-report vector, split into a comm block +/// and a fine block. +#[derive(Debug, Clone, PartialEq)] +pub struct BfiSample { + /// The full report: `comm_dims` comm coordinates followed by fine ones. + pub values: Vec, + /// Number of leading coordinates that form the comm (data-carrying) block. + pub comm_dims: usize, +} + +impl BfiSample { + /// Comm (data-carrying) block. + #[must_use] + pub fn comm(&self) -> &[f32] { + &self.values[..self.comm_dims] + } + + /// Fine (identity-bearing) block. + #[must_use] + pub fn fine(&self) -> &[f32] { + &self.values[self.comm_dims..] + } + + /// Mutable fine block — the only part the protector is allowed to rotate. + pub fn fine_mut(&mut self) -> &mut [f32] { + &mut self.values[self.comm_dims..] + } +} + +/// Configuration of the synthetic scene. +#[derive(Debug, Clone)] +pub struct SceneConfig { + /// Total report dimension. + pub dim: usize, + /// Leading coordinates forming the comm block. + pub comm_dims: usize, + /// Number of distinct identities (candidates). Chance level is `1/identities`. + pub identities: usize, + /// L2 norm of each identity's fine-block signature. + pub signature_norm: f32, + /// Std-dev of per-session environmental nuisance added to the fine block. + pub env_sigma: f32, + /// L2 norm of the fresh per-session comm-block beam. + pub beam_amplitude: f32, + /// Master seed. All keys derive from this; nothing touches OS entropy. + pub seed: u64, +} + +impl Default for SceneConfig { + fn default() -> Self { + Self { + dim: 64, + comm_dims: 8, + identities: 16, + signature_norm: 1.0, + env_sigma: 0.15, + beam_amplitude: 0.30, + seed: 0x5EED_1BF1, + } + } +} + +impl SceneConfig { + /// Ideal chance-level accuracy, `1 / identities`. + #[must_use] + pub fn chance_level(&self) -> f32 { + 1.0 / self.identities as f32 + } + + /// Length of the fine block. + #[must_use] + pub fn fine_dims(&self) -> usize { + self.dim - self.comm_dims + } +} + +/// Synthetic channel: turns `(identity, session)` into a [`BfiSample`]. +#[derive(Debug, Clone)] +pub struct Channel { + cfg: SceneConfig, + /// Precomputed per-identity fine-block signatures. + signatures: Vec>, +} + +impl Channel { + /// Build the channel, drawing each identity's stable signature. + #[must_use] + pub fn new(cfg: SceneConfig) -> Self { + let fine = cfg.fine_dims(); + let mut signatures = Vec::with_capacity(cfg.identities); + for id in 0..cfg.identities { + let mut rng = Rng::new(derive_key(cfg.seed, b"signature", id as u64, 0)); + let mut s: Vec = (0..fine).map(|_| rng.next_gaussian()).collect(); + set_norm_inplace(&mut s, cfg.signature_norm); + signatures.push(s); + } + Self { cfg, signatures } + } + + /// The scene configuration. + #[must_use] + pub fn config(&self) -> &SceneConfig { + &self.cfg + } + + /// The stable fine-block signature of `identity` (the thing an attacker + /// wants and the thing the shield must hide). + #[must_use] + pub fn signature(&self, identity: usize) -> &[f32] { + &self.signatures[identity] + } + + /// Observe the unprotected report for `identity` in the given session under + /// `phase` (an experiment stage label, e.g. `b"enroll"` / `b"test"`, so the + /// same session index draws independent nuisance across stages). + #[must_use] + pub fn observe(&self, identity: usize, phase: &[u8], session: u64) -> BfiSample { + let cfg = &self.cfg; + let mut values = vec![0.0f32; cfg.dim]; + + // Comm block: fresh per session, identity-independent. This is the + // data-carrying dominant beam — it holds no re-ID information. + let mut brng = Rng::new(derive_key(cfg.seed, b"beam", session, phase[0] as u64)); + for v in values[..cfg.comm_dims].iter_mut() { + *v = brng.next_gaussian(); + } + set_norm_inplace(&mut values[..cfg.comm_dims], cfg.beam_amplitude); + + // Fine block: stable identity signature + per-session nuisance. + let mut nrng = Rng::new(derive_key(cfg.seed, phase, identity as u64, session)); + let sig = &self.signatures[identity]; + for (v, s) in values[cfg.comm_dims..].iter_mut().zip(sig) { + *v = s + cfg.env_sigma * nrng.next_gaussian(); + } + + BfiSample { + values, + comm_dims: cfg.comm_dims, + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::linalg::{dist_sq, norm}; + + #[test] + fn signatures_are_well_separated() { + let ch = Channel::new(SceneConfig::default()); + // Distinct identities' signatures are near-orthogonal in high-dim, + // so pairwise distance is large relative to env noise. + let d = dist_sq(ch.signature(0), ch.signature(1)).sqrt(); + assert!(d > 1.0, "signatures too close: {d}"); + } + + #[test] + fn signature_norm_matches_config() { + let ch = Channel::new(SceneConfig::default()); + assert!((norm(ch.signature(3)) - 1.0).abs() < 1e-4); + } + + #[test] + fn observation_is_deterministic() { + let ch = Channel::new(SceneConfig::default()); + assert_eq!(ch.observe(2, b"enroll", 5), ch.observe(2, b"enroll", 5)); + } + + #[test] + fn same_session_different_phase_differs() { + let ch = Channel::new(SceneConfig::default()); + assert_ne!(ch.observe(2, b"enroll", 5), ch.observe(2, b"test", 5)); + } +} diff --git a/v2/crates/wifi-densepose-privshield/src/lib.rs b/v2/crates/wifi-densepose-privshield/src/lib.rs new file mode 100644 index 00000000..61395813 --- /dev/null +++ b/v2/crates/wifi-densepose-privshield/src/lib.rs @@ -0,0 +1,87 @@ +//! # VEIL — a compliant-waveform privacy shield against WiFi sensing +//! +//! VEIL (Verifiable Emission-shaping for Identity-Leakage prevention) is the +//! countermeasure counterpart to BFLD (ADR-118/121, `wifi-densepose-bfld`). +//! Where BFLD *detects* when beamforming feedback becomes identifying, VEIL +//! *acts*: it shapes a node's own outgoing beamforming feedback so that an +//! unauthorized passive sniffer cannot re-identify people or infer activity, +//! while a legitimate receiver — which shares the per-session key — sees an +//! essentially unchanged link. +//! +//! This crate is a **deterministic, dependency-free, WASM-ready reference and +//! experiment**, not a radio driver. It models the physics faithfully enough to +//! measure the core claim, and it never emits RF. Per ADR-288 and CLAUDE.md, +//! every number it produces is `SYNTHETIC`, reproduced by +//! `cargo test -p wifi-densepose-privshield`. +//! +//! ## The idea in one paragraph +//! +//! Identity leaks through the *fine* cross-subcarrier phase structure of a +//! compressed beamforming report; data throughput rides the *dominant* beam +//! direction. These live in (mostly) separable subspaces. VEIL composes extra +//! keyed [`linalg::apply_givens`] rotations — the exact primitive the report is +//! already built from — over the **fine** subspace only. The rotation is: +//! orthogonal (energy-preserving ⇒ no added transmit power ⇒ **not jamming**, +//! [`compliance`]); keyed per session (the legitimate AP inverts it ⇒ +//! throughput preserved, [`throughput`]); and fresh each session (a sniffer +//! sees a different rotation every time and cannot average back the signature +//! ⇒ re-identification collapses to chance, [`attacker`]/[`experiment`]). +//! +//! ## Threat model and scope (stated plainly) +//! +//! VEIL defends against a **third-party passive sniffer** capturing +//! plaintext beamforming feedback. It does **not** hide identity from the AP a +//! node is associated with (that party holds the key). It is **compliant by +//! construction**: it only shapes the node's own standards-conformant frames; +//! it never transmits to interfere with another station (47 U.S.C. §333) and +//! never operates an unauthorized emitter (§302a). It is not jamming, not RF +//! denial, and not a claim of camera-grade anything. +//! +//! ## Modules +//! +//! - [`prng`] — deterministic, WASM-safe PRNG and key derivation. +//! - [`linalg`] — the small Givens-rotation vector algebra. +//! - [`identity`] — the SYNTHETIC two-subspace beamforming-feedback model. +//! - [`protector`] — the compliant waveform controls (the shield). +//! - [`attacker`] — the passive re-identification adversary. +//! - [`throughput`] — the link-throughput model. +//! - [`compliance`] — the machine-checkable "not jamming" audit. +//! - [`experiment`] — the attacker-vs-protector head-to-head. +//! - [`proof`] — the byte-stable deterministic witness. +//! +//! ## Quick start +//! +//! ``` +//! use wifi_densepose_privshield::experiment::{run, ExperimentConfig}; +//! +//! let report = run(&ExperimentConfig::default()); +//! assert!(report.attack_is_effective_without_shield()); // threat is real +//! assert!(report.drives_to_chance()); // shield collapses re-ID +//! assert!(report.preserves_throughput()); // throughput ≥ 95% +//! assert!(report.compliance.is_compliant()); // energy-preserving +//! ``` + +#![warn(missing_docs)] +#![forbid(unsafe_code)] + +pub mod attacker; +pub mod compliance; +pub mod experiment; +pub mod identity; +pub mod linalg; +pub mod optimize; +pub mod prng; +pub mod proof; +pub mod protector; +pub mod throughput; + +pub use attacker::{ + AdaptivePoolingAttacker, AttackerKind, Metric, NearestCentroidAttacker, ReconstructionAttacker, +}; +pub use compliance::ComplianceReport; +pub use experiment::{run, ExperimentConfig, ExperimentReport}; +pub use identity::{BfiSample, Channel, SceneConfig}; +pub use optimize::{adaptive_shield, hyper_optimize, HyperOptimized}; +pub use proof::Proof; +pub use protector::{ObfMode, Protector, SensingDetector, ShieldConfig}; +pub use throughput::LinkModel; diff --git a/v2/crates/wifi-densepose-privshield/src/linalg.rs b/v2/crates/wifi-densepose-privshield/src/linalg.rs new file mode 100644 index 00000000..70c3f6dc --- /dev/null +++ b/v2/crates/wifi-densepose-privshield/src/linalg.rs @@ -0,0 +1,89 @@ +//! Minimal, dependency-free vector algebra over `f32` slices. +//! +//! VEIL deliberately avoids `ndarray`/BLAS: the vectors are short (tens of +//! elements — a flattened compressed-beamforming angle report), the crate is +//! a WASM-ready leaf, and keeping the math inline makes the energy-conservation +//! proof in [`crate::compliance`] auditable line-by-line. + +/// Euclidean inner product. Panics if lengths differ. +#[must_use] +pub fn dot(a: &[f32], b: &[f32]) -> f32 { + assert_eq!(a.len(), b.len(), "dot: length mismatch"); + a.iter().zip(b).map(|(x, y)| x * y).sum() +} + +/// Squared L2 norm. +#[must_use] +pub fn norm_sq(a: &[f32]) -> f32 { + a.iter().map(|x| x * x).sum() +} + +/// L2 norm. +#[must_use] +pub fn norm(a: &[f32]) -> f32 { + norm_sq(a).sqrt() +} + +/// Squared Euclidean distance. Panics if lengths differ. +#[must_use] +pub fn dist_sq(a: &[f32], b: &[f32]) -> f32 { + assert_eq!(a.len(), b.len(), "dist_sq: length mismatch"); + a.iter().zip(b).map(|(x, y)| (x - y) * (x - y)).sum() +} + +/// Scale in place. +pub fn scale_inplace(a: &mut [f32], k: f32) { + for x in a.iter_mut() { + *x *= k; + } +} + +/// Normalize `a` to a target L2 norm in place. No-op if `a` is (near) zero. +pub fn set_norm_inplace(a: &mut [f32], target: f32) { + let n = norm(a); + if n > 1e-12 { + scale_inplace(a, target / n); + } +} + +/// Apply a Givens rotation to coordinates `(i, j)` of `v` by angle `theta`. +/// +/// A Givens rotation is the exact primitive 802.11 compressed beamforming +/// feedback is built from (the ψ/φ angles a beamformee reports). It is an +/// **orthogonal** operation: it preserves `‖v‖` to machine precision, which is +/// precisely why composing extra keyed Givens rotations adds *no transmit +/// energy* — the compliance argument in [`crate::compliance`]. +pub fn apply_givens(v: &mut [f32], i: usize, j: usize, theta: f32) { + debug_assert!(i < v.len() && j < v.len() && i != j); + let (c, s) = (theta.cos(), theta.sin()); + let (vi, vj) = (v[i], v[j]); + v[i] = c * vi - s * vj; + v[j] = s * vi + c * vj; +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn givens_preserves_norm() { + let mut v = vec![0.3, -1.2, 0.7, 2.1, -0.5]; + let before = norm(&v); + apply_givens(&mut v, 1, 3, 0.9); + apply_givens(&mut v, 0, 4, -2.3); + apply_givens(&mut v, 2, 3, 1.1); + let after = norm(&v); + assert!((before - after).abs() < 1e-5, "{before} vs {after}"); + } + + #[test] + fn givens_is_invertible() { + let orig = vec![1.0f32, 2.0, 3.0, 4.0]; + let mut v = orig.clone(); + apply_givens(&mut v, 0, 2, 0.7); + apply_givens(&mut v, 0, 2, -0.7); + for (a, b) in orig.iter().zip(&v) { + assert!((a - b).abs() < 1e-5); + } + } +} diff --git a/v2/crates/wifi-densepose-privshield/src/optimize.rs b/v2/crates/wifi-densepose-privshield/src/optimize.rs new file mode 100644 index 00000000..b885e20f --- /dev/null +++ b/v2/crates/wifi-densepose-privshield/src/optimize.rs @@ -0,0 +1,424 @@ +//! Hyper-optimization of the shield's operating point. +//! +//! The reference crate shipped a hand-picked shield config. This module finds +//! the *optimal* one deterministically, and — crucially — proves the optimum is +//! robust rather than tuned to one attacker or one identity count: +//! +//! - [`optimal_feedback_bits`] finds the throughput-maximizing feedback +//! resolution, exploiting the interior optimum the [`crate::throughput`] model +//! exposes (residual falls with bits, airtime rises). +//! - [`min_givens_passes`] finds the **smallest** rotation-mixing budget that +//! still drives re-identification into the chance band — checked against +//! *every* attacker [`Metric`] and *every* identity count in a robustness set, +//! so the answer is the minimum that survives the hardest case, not the +//! easiest. +//! - [`pareto_frontier`] enumerates the non-dominated (privacy, throughput) +//! points for documentation and inspection. +//! - [`hyper_optimize`] combines the two into a ready-to-ship [`ShieldConfig`] +//! plus the verifying [`ExperimentReport`]. +//! +//! Optimizing over both metrics and multiple `N` is the point: if the collapse +//! held only for Euclidean at N=16, it would be a classifier artifact. It holds +//! across the set because a session-fresh secret rotation removes stable +//! identity information from the *signal*. + +use crate::attacker::Metric; +use crate::experiment::{run, ExperimentConfig, ExperimentReport}; +use crate::protector::ShieldConfig; + +/// Attacker metrics the optimizer must satisfy simultaneously. +pub const ROBUSTNESS_METRICS: [Metric; 2] = [Metric::Euclidean, Metric::Cosine]; + +/// Identity counts the optimizer must satisfy simultaneously. Larger `N` has a +/// lower chance floor, so it is the harder collapse target. +pub const ROBUSTNESS_IDENTITIES: [usize; 2] = [16, 32]; + +/// Candidate Givens-pass budgets, ascending. The optimizer returns the first +/// that collapses re-ID across the whole robustness set. +pub const PASS_CANDIDATES: [usize; 12] = [2, 4, 6, 8, 12, 16, 24, 32, 48, 64, 96, 112]; + +/// Per-angle feedback resolutions 802.11 compressed beamforming actually uses +/// (ψ/φ are quantized to roughly 5–9 bits). The shipped shield picks the +/// throughput-best value from this *spec-allowed* set, not the unconstrained +/// model optimum, so the config stays standards-faithful. +pub const ALLOWED_FEEDBACK_BITS: [u32; 3] = [5, 7, 9]; + +/// Safety margin applied to the proven-minimum pass budget. Rotation mixing is +/// keyed (derived from the shared link secret, never signaled), so extra passes +/// cost compute but **no** throughput — we spend a 2× margin on privacy for +/// free. +pub const PRIVACY_MARGIN_FACTOR: usize = 2; + +/// Run one experiment variant with the given knobs, holding everything else at +/// `base`. +fn run_variant( + base: &ExperimentConfig, + passes: usize, + bits: u32, + metric: Metric, + identities: usize, +) -> ExperimentReport { + let mut cfg = base.clone(); + cfg.shield = ShieldConfig { + givens_passes: passes, + feedback_bits: bits, + ..base.shield.clone() + }; + cfg.scene.identities = identities; + cfg.attacker_metric = metric; + run(&cfg) +} + +/// Throughput of the base link at a given feedback resolution. +fn throughput_at_bits(base: &ExperimentConfig, bits: u32) -> f64 { + base.link.throughput_ratio(&ShieldConfig { + feedback_bits: bits, + ..base.shield.clone() + }) +} + +/// Find the throughput-maximizing `feedback_bits` in `1..=max_bits` +/// (unconstrained model optimum). Returns `(bits, throughput_ratio)`. +#[must_use] +pub fn optimal_feedback_bits(base: &ExperimentConfig, max_bits: u32) -> (u32, f64) { + (1..=max_bits) + .map(|bits| (bits, throughput_at_bits(base, bits))) + .max_by(|a, b| a.1.partial_cmp(&b.1).unwrap()) + .unwrap_or((base.shield.feedback_bits, 0.0)) +} + +/// Find the throughput-maximizing feedback resolution within the spec-allowed +/// set [`ALLOWED_FEEDBACK_BITS`]. This is what the shipped shield uses. +#[must_use] +pub fn spec_optimal_feedback_bits(base: &ExperimentConfig) -> (u32, f64) { + ALLOWED_FEEDBACK_BITS + .iter() + .map(|&bits| (bits, throughput_at_bits(base, bits))) + .max_by(|a, b| a.1.partial_cmp(&b.1).unwrap()) + .unwrap() +} + +/// Does `passes` collapse re-ID into the chance band for *every* metric and +/// *every* identity count in the robustness set? +#[must_use] +pub fn passes_collapse_robustly(base: &ExperimentConfig, passes: usize, bits: u32) -> bool { + for &n in &ROBUSTNESS_IDENTITIES { + for &m in &ROBUSTNESS_METRICS { + if !run_variant(base, passes, bits, m, n).drives_to_chance() { + return false; + } + } + } + true +} + +/// Smallest Givens-pass budget from [`PASS_CANDIDATES`] that collapses re-ID +/// robustly, or `None` if even the largest candidate fails. +#[must_use] +pub fn min_givens_passes(base: &ExperimentConfig, bits: u32) -> Option { + PASS_CANDIDATES + .iter() + .copied() + .find(|&p| passes_collapse_robustly(base, p, bits)) +} + +/// One point on the privacy–throughput tradeoff. +#[derive(Debug, Clone, PartialEq)] +pub struct ParetoPoint { + /// Givens-pass budget. + pub givens_passes: usize, + /// Feedback resolution in bits. + pub feedback_bits: u32, + /// Worst-case (highest) re-ID accuracy over the robustness metrics at the + /// base identity count. + pub worst_reid: f32, + /// Modeled throughput ratio. + pub throughput_ratio: f64, + /// Whether this point collapses re-ID robustly (all metrics, all N). + pub robustly_private: bool, +} + +/// Enumerate the non-dominated (lower re-ID, higher throughput) points over a +/// grid of pass budgets and feedback resolutions. +#[must_use] +pub fn pareto_frontier(base: &ExperimentConfig, max_bits: u32) -> Vec { + let mut points: Vec = Vec::new(); + for &passes in &PASS_CANDIDATES { + for bits in 1..=max_bits { + // Worst-case re-ID over metrics at the base identity count. + let worst_reid = ROBUSTNESS_METRICS + .iter() + .map(|&m| { + run_variant(base, passes, bits, m, base.scene.identities).accuracy_shield_on + }) + .fold(0.0_f32, f32::max); + let shield = ShieldConfig { + givens_passes: passes, + feedback_bits: bits, + ..base.shield.clone() + }; + points.push(ParetoPoint { + givens_passes: passes, + feedback_bits: bits, + worst_reid, + throughput_ratio: base.link.throughput_ratio(&shield), + robustly_private: passes_collapse_robustly(base, passes, bits), + }); + } + } + // Keep only non-dominated points: no other point has both lower-or-equal + // re-ID and higher-or-equal throughput while being strictly better in one. + points + .iter() + .filter(|p| { + !points.iter().any(|q| { + let better_or_eq = + q.worst_reid <= p.worst_reid && q.throughput_ratio >= p.throughput_ratio; + let strictly_better = + q.worst_reid < p.worst_reid || q.throughput_ratio > p.throughput_ratio; + better_or_eq && strictly_better + }) + }) + .cloned() + .collect() +} + +/// The chosen optimum plus the report that verifies it. +#[derive(Debug, Clone)] +pub struct HyperOptimized { + /// The optimized, ready-to-ship shield configuration. + pub shield: ShieldConfig, + /// Minimum Givens passes that collapses re-ID robustly (before the margin). + pub min_passes: usize, + /// Shipped Givens passes = `min_passes` grown by [`PRIVACY_MARGIN_FACTOR`]. + pub shipped_passes: usize, + /// Unconstrained throughput-optimal feedback resolution (a research point). + pub model_optimal_bits: u32, + /// Spec-allowed throughput-optimal resolution (what the shield ships with). + pub spec_optimal_bits: u32, + /// The verifying experiment at the base identity count. + pub report: ExperimentReport, +} + +/// Smallest pass candidate that is at least `target`. +fn ceil_to_candidate(target: usize) -> usize { + PASS_CANDIDATES + .iter() + .copied() + .find(|&p| p >= target) + .unwrap_or_else(|| *PASS_CANDIDATES.last().unwrap()) +} + +/// Find the optimal shield: the spec-allowed throughput-optimal feedback +/// resolution, and the minimum rotation-mixing budget that collapses re-ID +/// robustly, grown by a free privacy margin. Deterministic and idempotent — the +/// shipped [`ShieldConfig::default`] is exactly this function's output on the +/// default base (asserted in tests). +#[must_use] +pub fn hyper_optimize(base: &ExperimentConfig) -> HyperOptimized { + let (model_optimal_bits, _) = optimal_feedback_bits(base, 12); + let (spec_optimal_bits, _) = spec_optimal_feedback_bits(base); + + let min_passes = min_givens_passes(base, spec_optimal_bits) + .unwrap_or_else(|| *PASS_CANDIDATES.last().unwrap()); + let shipped_passes = ceil_to_candidate(min_passes * PRIVACY_MARGIN_FACTOR); + + let shield = ShieldConfig { + givens_passes: shipped_passes, + feedback_bits: spec_optimal_bits, + ..base.shield.clone() + }; + let mut cfg = base.clone(); + cfg.shield = shield.clone(); + let report = run(&cfg); + + HyperOptimized { + shield, + min_passes, + shipped_passes, + model_optimal_bits, + spec_optimal_bits, + report, + } +} + +// --------------------------------------------------------------------------- +// Adaptive optimization: the optimum is not one config — it depends on the +// deployment's SNR (which shifts the throughput-optimal feedback resolution) +// and its identity count (which sets how much rotation mixing collapse needs). +// These functions derive the right config per deployment rather than assuming +// the default scene. +// --------------------------------------------------------------------------- + +/// SNR values (dB) to profile the throughput-optimal feedback resolution over. +pub const SNR_PROFILE_DB: [f64; 5] = [5.0, 10.0, 20.0, 30.0, 40.0]; + +/// Unconstrained throughput-optimal feedback resolution for a specific SNR, +/// holding the rest of `base`. At low SNR the residual matters proportionally +/// more (Shannon capacity is near-linear), so higher resolution wins; at high +/// SNR the log compresses the residual away and feedback airtime dominates, +/// favoring fewer bits. (The *shipped* shield clamps to the 802.11 {5,7,9} set, +/// where 5 already zeroes the residual — so this shift is visible only in the +/// unconstrained optimum, and is what motivates keeping resolution low.) +#[must_use] +pub fn model_optimal_bits_for_snr(base: &ExperimentConfig, snr_db: f64) -> (u32, f64) { + let mut cfg = base.clone(); + cfg.link.snr_db = snr_db; + optimal_feedback_bits(&cfg, 12) +} + +/// Profile the unconstrained throughput-optimal feedback resolution across +/// [`SNR_PROFILE_DB`]. Demonstrates the SNR → resolution dependence. +#[must_use] +pub fn optimal_bits_across_snr(base: &ExperimentConfig) -> Vec<(f64, u32)> { + SNR_PROFILE_DB + .iter() + .map(|&snr| (snr, model_optimal_bits_for_snr(base, snr).0)) + .collect() +} + +/// Does `passes` collapse re-ID for both metrics at a single identity count? +#[must_use] +pub fn passes_collapse_at_n(base: &ExperimentConfig, passes: usize, bits: u32, n: usize) -> bool { + ROBUSTNESS_METRICS + .iter() + .all(|&m| run_variant(base, passes, bits, m, n).drives_to_chance()) +} + +/// Smallest pass budget that collapses re-ID for a *specific* identity count. +/// More candidates ⇒ lower chance floor ⇒ generally more mixing required, so +/// this grows with `n`. +#[must_use] +pub fn min_passes_for_n(base: &ExperimentConfig, bits: u32, n: usize) -> Option { + PASS_CANDIDATES + .iter() + .copied() + .find(|&p| passes_collapse_at_n(base, p, bits, n)) +} + +/// Derive a ready-to-ship shield for a specific deployment: throughput-optimal +/// feedback resolution for the deployment SNR, and the minimum mixing budget for +/// its identity count grown by the free [`PRIVACY_MARGIN_FACTOR`] margin. This is +/// what an operator should call for a room with `n` expected occupants on a link +/// with `base.link`'s SNR — the default config is just this at N=16. +#[must_use] +pub fn adaptive_shield(base: &ExperimentConfig, n: usize) -> ShieldConfig { + let (bits, _) = spec_optimal_feedback_bits(base); + let min_passes = + min_passes_for_n(base, bits, n).unwrap_or_else(|| *PASS_CANDIDATES.last().unwrap()); + ShieldConfig { + givens_passes: ceil_to_candidate(min_passes * PRIVACY_MARGIN_FACTOR), + feedback_bits: bits, + ..base.shield.clone() + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn model_optimal_bits_is_interior() { + let (bits, ratio) = optimal_feedback_bits(&ExperimentConfig::default(), 12); + assert!(bits > 1 && bits < 12, "optimum at edge: {bits}"); + assert!(ratio > 0.95); + } + + #[test] + fn spec_optimal_bits_is_the_low_res_end() { + // Within {5,7,9}, lower resolution wins because the receiver compensates + // the keyed rotation, so extra bits mostly buy airtime. + let (bits, _) = spec_optimal_feedback_bits(&ExperimentConfig::default()); + assert_eq!(bits, 5); + } + + #[test] + fn min_passes_is_below_the_original_default() { + // The original hand-picked default was 112 passes. The optimizer proves + // far fewer suffice — the "we over-provisioned" finding. + let (bits, _) = spec_optimal_feedback_bits(&ExperimentConfig::default()); + let p = min_givens_passes(&ExperimentConfig::default(), bits).expect("collapses"); + assert!(p < 112, "min passes {p} should be below the old 112"); + assert!(p >= 2); + } + + #[test] + fn shipped_default_equals_optimizer_output() { + // The crate's default shield IS the optimizer's recommendation — they + // cannot silently drift apart. + let opt = hyper_optimize(&ExperimentConfig::default()); + assert_eq!( + opt.shield.givens_passes, + ShieldConfig::default().givens_passes + ); + assert_eq!( + opt.shield.feedback_bits, + ShieldConfig::default().feedback_bits + ); + assert!(opt.report.passed(), "{:#?}", opt.report); + } + + #[test] + fn optimum_collapses_under_both_metrics_and_larger_n() { + let opt = hyper_optimize(&ExperimentConfig::default()); + assert!(passes_collapse_robustly( + &ExperimentConfig::default(), + opt.shipped_passes, + opt.spec_optimal_bits + )); + } + + #[test] + fn optimal_bits_shift_with_snr() { + // Low-SNR deployments favor higher feedback resolution; high-SNR favor + // lower. The (unconstrained) profile is non-increasing in SNR and not + // constant across the range. + let profile = optimal_bits_across_snr(&ExperimentConfig::default()); + let low = profile.first().unwrap().1; + let high = profile.last().unwrap().1; + assert!( + low >= high, + "low-SNR bits {low} should be >= high-SNR bits {high}" + ); + assert!(low != high, "profile did not shift with SNR: {profile:?}"); + } + + #[test] + fn adaptive_shield_mixing_is_nondecreasing_in_n() { + // A room with more candidate identities needs at least as much mixing. + // In this model the collapse budget is governed by fine-subspace + // dimension, so the requirement is flat across N — the invariant we can + // assert is non-decreasing, and that it never *under*-provisions. + let base = ExperimentConfig::default(); + let small = adaptive_shield(&base, 8); + let large = adaptive_shield(&base, 64); + assert!( + large.givens_passes >= small.givens_passes, + "N=64 passes {} should be >= N=8 passes {}", + large.givens_passes, + small.givens_passes + ); + } + + #[test] + fn adaptive_shield_collapses_at_its_target_n() { + let base = ExperimentConfig::default(); + for n in [8usize, 32, 64] { + let sh = adaptive_shield(&base, n); + assert!( + passes_collapse_at_n(&base, sh.givens_passes, sh.feedback_bits, n), + "adaptive shield for N={n} does not collapse" + ); + } + } + + #[test] + fn frontier_is_non_empty_and_deterministic() { + // Small grid keeps this fast; the frontier logic is grid-size agnostic. + let base = ExperimentConfig::default(); + let a = pareto_frontier(&base, 3); + let b = pareto_frontier(&base, 3); + assert!(!a.is_empty()); + assert_eq!(a, b); + } +} diff --git a/v2/crates/wifi-densepose-privshield/src/prng.rs b/v2/crates/wifi-densepose-privshield/src/prng.rs new file mode 100644 index 00000000..e057f9bb --- /dev/null +++ b/v2/crates/wifi-densepose-privshield/src/prng.rs @@ -0,0 +1,119 @@ +//! Deterministic, WASM-safe pseudo-random generator. +//! +//! VEIL never draws from OS entropy: every stochastic quantity in the +//! experiment (identity signatures, environmental nuisance, per-session +//! precoder rotations) seeds from an explicit `u64`. Same seed in → same +//! bytes out, on any platform including `wasm32-unknown-unknown`. This is +//! what makes [`crate::proof`] a byte-stable witness rather than a flaky +//! statistical assertion. +//! +//! The core is SplitMix64 (Steele, Lea & Flood 2014) — a well-mixed +//! finalizer that is more than adequate for synthetic-data generation and +//! keyed subspace rotation. It is **not** a cryptographic RNG and must not +//! be used to derive real key material; in a deployment the per-session +//! rotation key comes from the negotiated link secret, not from this PRNG. + +/// A deterministic SplitMix64 stream. +#[derive(Debug, Clone)] +pub struct Rng { + state: u64, +} + +impl Rng { + /// Seed the stream. Distinct seeds yield independent streams. + #[must_use] + pub fn new(seed: u64) -> Self { + Self { + state: seed ^ 0x9E37_79B9_7F4A_7C15, + } + } + + /// Next raw 64-bit word. + pub fn next_u64(&mut self) -> u64 { + self.state = self.state.wrapping_add(0x9E37_79B9_7F4A_7C15); + let mut z = self.state; + z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9); + z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB); + z ^ (z >> 31) + } + + /// Uniform `f32` in `[0, 1)` using the top 24 mantissa bits. + pub fn next_f32(&mut self) -> f32 { + // 24 bits of precision keeps the value exactly representable. + ((self.next_u64() >> 40) as f32) / ((1u64 << 24) as f32) + } + + /// Uniform `f32` in `[lo, hi)`. + pub fn next_range(&mut self, lo: f32, hi: f32) -> f32 { + lo + (hi - lo) * self.next_f32() + } + + /// Standard-normal `f32` via the Box–Muller transform. + pub fn next_gaussian(&mut self) -> f32 { + let u1 = self.next_f32().max(1e-7); + let u2 = self.next_f32(); + (-2.0 * u1.ln()).sqrt() * (core::f32::consts::TAU * u2).cos() + } +} + +/// FNV-1a 64-bit hash — a dependency-free, deterministic byte folder used to +/// derive per-session keys from `(scene_seed, phase, index)` tuples and to +/// build the [`crate::proof`] witness. Not cryptographic. +#[must_use] +pub fn fnv1a_64(bytes: &[u8]) -> u64 { + let mut h: u64 = 0xCBF2_9CE4_8422_2325; + for &b in bytes { + h ^= u64::from(b); + h = h.wrapping_mul(0x0000_0100_0000_01B3); + } + h +} + +/// Fold a label and two indices into a stable `u64` key. +#[must_use] +pub fn derive_key(scene_seed: u64, label: &[u8], a: u64, b: u64) -> u64 { + let mut buf = Vec::with_capacity(label.len() + 24); + buf.extend_from_slice(&scene_seed.to_le_bytes()); + buf.extend_from_slice(label); + buf.extend_from_slice(&a.to_le_bytes()); + buf.extend_from_slice(&b.to_le_bytes()); + fnv1a_64(&buf) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn stream_is_deterministic() { + let mut a = Rng::new(42); + let mut b = Rng::new(42); + for _ in 0..1000 { + assert_eq!(a.next_u64(), b.next_u64()); + } + } + + #[test] + fn distinct_seeds_diverge() { + let mut a = Rng::new(1); + let mut b = Rng::new(2); + assert_ne!(a.next_u64(), b.next_u64()); + } + + #[test] + fn uniform_in_range() { + let mut r = Rng::new(7); + for _ in 0..10_000 { + let x = r.next_f32(); + assert!((0.0..1.0).contains(&x)); + } + } + + #[test] + fn gaussian_mean_near_zero() { + let mut r = Rng::new(9); + let n = 100_000; + let mean: f64 = (0..n).map(|_| f64::from(r.next_gaussian())).sum::() / f64::from(n); + assert!(mean.abs() < 0.02, "mean {mean} not near 0"); + } +} diff --git a/v2/crates/wifi-densepose-privshield/src/proof.rs b/v2/crates/wifi-densepose-privshield/src/proof.rs new file mode 100644 index 00000000..b1124916 --- /dev/null +++ b/v2/crates/wifi-densepose-privshield/src/proof.rs @@ -0,0 +1,82 @@ +//! Deterministic proof bundle — the byte-stable witness for VEIL. +//! +//! Mirrors the `nvsim` / `archive/v1` proof pattern: run a fixed reference +//! experiment, fold its salient outputs into a single FNV-1a witness, and pin +//! that witness as a constant. If any constant drifts — the PRNG stream, the +//! rotation schedule, the throughput formula, the scene geometry — the witness +//! changes and the test fails loudly. +//! +//! The witness is derived from **quantized** outputs (accuracies to 1e-4, +//! throughput to 1e-6) so that legitimate cross-platform f32 round-off in the +//! last bits does not spuriously break the proof, while any real change to the +//! experiment's behavior still does. + +use crate::experiment::{run, ExperimentConfig, ExperimentReport}; +use crate::prng::fnv1a_64; + +/// Deterministic-proof harness. +pub struct Proof; + +impl Proof { + /// Pinned witness over the reference experiment. Re-derived by + /// [`Proof::witness`]; asserted by the test below. + pub const EXPECTED_WITNESS: u64 = 0x350D_7CDF_95D9_F448; + + /// The reference configuration. Uses every default so the proof tracks the + /// shipped behavior of the crate. + #[must_use] + pub fn reference_config() -> ExperimentConfig { + ExperimentConfig::default() + } + + /// Run the reference experiment. + #[must_use] + pub fn run_reference() -> ExperimentReport { + run(&Self::reference_config()) + } + + /// Fold a report's salient outputs into a stable witness. + #[must_use] + pub fn witness(report: &ExperimentReport) -> u64 { + let mut buf = Vec::new(); + buf.extend_from_slice(&(report.identities as u64).to_le_bytes()); + // Quantize floats before folding so last-bit round-off is not part of + // the witness. + let q4 = |x: f32| (f64::from(x) * 10_000.0).round() as i64; + let q6 = |x: f64| (x * 1_000_000.0).round() as i64; + buf.extend_from_slice(&q4(report.chance_level).to_le_bytes()); + buf.extend_from_slice(&q4(report.accuracy_shield_off).to_le_bytes()); + buf.extend_from_slice(&q4(report.accuracy_shield_on).to_le_bytes()); + buf.extend_from_slice(&q6(report.throughput_ratio).to_le_bytes()); + buf.extend_from_slice(&q4(report.compliance.energy_ratio).to_le_bytes()); + fnv1a_64(&buf) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn reference_experiment_passes() { + assert!(Proof::run_reference().passed()); + } + + #[test] + fn witness_is_stable() { + let a = Proof::witness(&Proof::run_reference()); + let b = Proof::witness(&Proof::run_reference()); + assert_eq!(a, b, "witness must be reproducible"); + } + + #[test] + fn witness_matches_pinned() { + let w = Proof::witness(&Proof::run_reference()); + assert_eq!( + w, + Proof::EXPECTED_WITNESS, + "witness drifted to {w:#018x}; update EXPECTED_WITNESS only if the \ + change to the reference experiment is intentional" + ); + } +} diff --git a/v2/crates/wifi-densepose-privshield/src/protector.rs b/v2/crates/wifi-densepose-privshield/src/protector.rs new file mode 100644 index 00000000..c17bdce9 --- /dev/null +++ b/v2/crates/wifi-densepose-privshield/src/protector.rs @@ -0,0 +1,298 @@ +//! The VEIL protector: compliant waveform controls that hide identity. +//! +//! # What it does (and does not do) +//! +//! The protector shapes the node's **own** beamforming feedback before it goes +//! on air. It applies a per-session, key-derived **orthogonal rotation** to the +//! fine block of the report, composed from extra Givens rotations — the same +//! angle primitive the report already carries. Because the rotation is: +//! +//! - **orthogonal** → it preserves the report's energy exactly (no added +//! transmit power, no out-of-mask emission → **not jamming**, see +//! [`crate::compliance`]); +//! - **keyed per session** → the legitimate AP/STA, which shares the session +//! key, inverts it and recovers the true precoder (throughput preserved, +//! see [`crate::throughput`]); +//! - **fresh each session** → an external sniffer sees a different rotation of +//! the identity signature every session and cannot average them back to the +//! signature, so cross-session re-identification collapses toward chance. +//! +//! This is the shared-secret precoding idea (cf. MIMOCrypt, NSDI-adjacent work) +//! specialized to the identity-bearing fine subspace. +//! +//! # Scope limit (stated honestly) +//! +//! VEIL defends against a **third-party passive sniffer**. It does *not* hide +//! identity from the AP the node is associated with (that party holds the key +//! by construction). Protecting against a malicious AP is a different problem +//! handled by the BFLD detection layer and privacy-class policy (ADR-118/141), +//! not by this shield. VEIL never jams and never touches another station's +//! frames. + +use crate::identity::BfiSample; +use crate::linalg::{apply_givens, norm, set_norm_inplace}; +use crate::prng::Rng; + +/// Per-dimension angular-noise sensitivity for the ε-DP dither. Chosen so ε≈1 is +/// a mild perturbation and ε≲0.2 is aggressive. SYNTHETIC modeling constant. +const DP_ANGULAR_SENSITIVITY: f32 = 0.05; + +/// How the shield keys its per-transform randomness. Both modes use the same +/// energy-preserving Givens machinery; the difference is *granularity* and +/// *who changes* — captured here so the deployment story is explicit (ADR-288 +/// §sota; validated against the SOTA sweep). +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum ObfMode { + /// Secret per-*session* rotation, shared-key-reversible by the associated + /// receiver (VEIL's original design). One rotation per sounding interval. + #[default] + KeyedRotation, + /// A fresh random unitary per *packet*, applied AP-side to the transmitted + /// report; **client-transparent** — only the AP changes, clients are + /// unmodified and unaware. Models the LeakyBeam-family defense (NDSS 2025, + /// MEASURED 89.7%→~51%) that rides the 802.11 spatial-mapping mechanism the + /// standard marks "not restricted". Even harder to average out than + /// per-session, at the cost of no cross-packet reuse. + PerPacketUnitary, +} + +/// Configuration of the protector. +#[derive(Debug, Clone)] +pub struct ShieldConfig { + /// Master switch. When `false`, [`Protector::protect`] is the identity map + /// (used to model the "shield off" baseline). + pub enabled: bool, + /// Number of keyed Givens rotations composed per session. Enough passes + /// approximate a Haar-random rotation of the fine block, which is what + /// drives the attacker to chance. The optimal value is found by + /// [`crate::optimize`] (not hand-tuned); more passes cost compute but no + /// throughput, since the rotation is keyed rather than signaled. + pub givens_passes: usize, + /// Bits used to quantize each reported angle (802.11 uses 5–9). Higher + /// resolution ⇒ smaller uncompensated residual at the legitimate receiver + /// ⇒ smaller throughput cost. See [`crate::throughput`]. + pub feedback_bits: u32, + /// Fractional airtime overhead from sounding-cadence randomization + /// (jittering NDP intervals so an eavesdropper under-samples motion). + pub sounding_overhead: f64, + /// Keying granularity of the obfuscation (see [`ObfMode`]). + pub mode: ObfMode, + /// Optional ε-DP angular dither budget layered on top of the rotation + /// (`None` = off). Smaller ε ⇒ more angular noise ⇒ stronger formal privacy + /// on the *raw reported angles* but larger throughput cost. The dithered + /// report is renormalized to its original energy, so it stays a valid unit + /// precoder and the emission remains energy-preserving (not jamming). + /// Models the DP-Givens mechanism (arXiv:2512.18529, SYNTHETIC). Any number + /// derived from it is SYNTHETIC. + pub dp_epsilon: Option, +} + +impl Default for ShieldConfig { + fn default() -> Self { + // These values are the output of `optimize::hyper_optimize` on the + // default scene (ADR-288 §opt), not hand-picked: 96 = 2× the proven- + // minimum 48 robust passes (free margin, since mixing is keyed not + // signaled), and 5 = the throughput-best resolution in the 802.11 + // {5,7,9} set. `optimize::shipped_default_equals_optimizer_output` + // guards against drift. `mode`/`dp_epsilon` default to the original + // behavior so the reference witness is unchanged. + Self { + enabled: true, + givens_passes: 96, + feedback_bits: 5, + sounding_overhead: 0.02, + mode: ObfMode::KeyedRotation, + dp_epsilon: None, + } + } +} + +/// Applies compliant waveform controls to outgoing beamforming feedback. +#[derive(Debug, Clone)] +pub struct Protector { + cfg: ShieldConfig, +} + +impl Protector { + /// Build a protector. + #[must_use] + pub fn new(cfg: ShieldConfig) -> Self { + Self { cfg } + } + + /// The configuration. + #[must_use] + pub fn config(&self) -> &ShieldConfig { + &self.cfg + } + + /// Build the list of `(i, j, theta)` Givens rotations for a session. The + /// legitimate receiver derives the identical list from the shared session + /// key and applies the inverse (negated angles, reversed order). + fn session_rotation(&self, fine_dims: usize, session_key: u64) -> Vec<(usize, usize, f32)> { + let mut rng = Rng::new(session_key); + let mut ops = Vec::with_capacity(self.cfg.givens_passes); + for _ in 0..self.cfg.givens_passes { + // Draw a distinct coordinate pair in the fine block. + let i = (rng.next_u64() as usize) % fine_dims; + let mut j = (rng.next_u64() as usize) % fine_dims; + if j == i { + j = (j + 1) % fine_dims; + } + let theta = rng.next_range(0.0, core::f32::consts::TAU); + ops.push((i, j, theta)); + } + ops + } + + /// Protect an outgoing report for the given session. When the shield is + /// disabled this clones the input unchanged. + /// + /// The keyed Givens rotation runs whenever `givens_passes > 0`; the caller + /// chooses `session_key`'s granularity (a per-session key for + /// [`ObfMode::KeyedRotation`], a per-packet key for + /// [`ObfMode::PerPacketUnitary`]). If `dp_epsilon` is set, an ε-scaled + /// angular dither is added afterward and the fine block is renormalized to + /// its original energy (so the emission stays energy-preserving). + #[must_use] + pub fn protect(&self, sample: &BfiSample, session_key: u64) -> BfiSample { + let mut out = sample.clone(); + if !self.cfg.enabled { + return out; + } + let fine_dims = out.fine().len(); + let ops = self.session_rotation(fine_dims, session_key); + let fine = out.fine_mut(); + for (i, j, theta) in ops { + apply_givens(fine, i, j, theta); + } + if let Some(eps) = self.cfg.dp_epsilon { + Self::dp_dither(fine, eps, session_key); + } + out + } + + /// Add an ε-DP angular dither to `fine`, then renormalize to the original + /// energy. Noise scale ∝ 1/ε (smaller ε ⇒ more noise ⇒ stronger privacy on + /// the raw angles). Renormalization keeps it a valid unit precoder, so the + /// step adds no transmit energy. SYNTHETIC. + fn dp_dither(fine: &mut [f32], epsilon: f32, key: u64) { + let before = norm(fine); + if before <= 1e-12 { + return; + } + // Laplace-like scale for an angular budget; bounded so ε→0 saturates. + let scale = (DP_ANGULAR_SENSITIVITY / epsilon.max(1e-3)).min(2.0); + let mut rng = Rng::new(key ^ 0xD1FF_D1FF_D1FF_D1FF); + for v in fine.iter_mut() { + *v += scale * rng.next_gaussian(); + } + set_norm_inplace(fine, before); + } + + /// Recover the true report at the legitimate receiver, which shares the + /// session key. Applies the inverse rotation. Used to demonstrate that the + /// transform is reversible for the authorized party (the basis of the + /// throughput claim), not part of the attacker's world. + #[must_use] + pub fn recover(&self, sample: &BfiSample, session_key: u64) -> BfiSample { + let mut out = sample.clone(); + if !self.cfg.enabled { + return out; + } + let fine_dims = out.fine().len(); + let ops = self.session_rotation(fine_dims, session_key); + let fine = out.fine_mut(); + for (i, j, theta) in ops.into_iter().rev() { + apply_givens(fine, i, j, -theta); + } + out + } +} + +/// A minimal detector for unsolicited sensing activity. In a deployment this +/// watches the rate of NDP/sensing-sounding solicitations; here it exposes the +/// decision rule so the control plane (ADR-280) can engage the shield only when +/// sensing is actually observed, rather than perturbing continuously. +#[derive(Debug, Clone)] +pub struct SensingDetector { + /// Solicitations per second above which the shield engages. + pub threshold_hz: f32, +} + +impl Default for SensingDetector { + fn default() -> Self { + Self { threshold_hz: 5.0 } + } +} + +impl SensingDetector { + /// Should the shield engage given the observed solicitation rate? + #[must_use] + pub fn should_engage(&self, observed_hz: f32) -> bool { + observed_hz >= self.threshold_hz + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::identity::{Channel, SceneConfig}; + use crate::linalg::{dist_sq, norm}; + + #[test] + fn protection_preserves_energy() { + let ch = Channel::new(SceneConfig::default()); + let s = ch.observe(0, b"enroll", 1); + let p = Protector::new(ShieldConfig::default()); + let out = p.protect(&s, 12345); + assert!((norm(&s.values) - norm(&out.values)).abs() < 1e-3); + } + + #[test] + fn protection_leaves_comm_block_untouched() { + let ch = Channel::new(SceneConfig::default()); + let s = ch.observe(0, b"enroll", 1); + let p = Protector::new(ShieldConfig::default()); + let out = p.protect(&s, 999); + assert_eq!(s.comm(), out.comm()); + } + + #[test] + fn protection_scrambles_fine_block() { + let ch = Channel::new(SceneConfig::default()); + let s = ch.observe(0, b"enroll", 1); + let p = Protector::new(ShieldConfig::default()); + let out = p.protect(&s, 42); + assert!(dist_sq(s.fine(), out.fine()).sqrt() > 0.5); + } + + #[test] + fn legitimate_receiver_recovers() { + let ch = Channel::new(SceneConfig::default()); + let s = ch.observe(0, b"enroll", 1); + let p = Protector::new(ShieldConfig::default()); + let out = p.protect(&s, 7); + let back = p.recover(&out, 7); + assert!(dist_sq(s.fine(), back.fine()).sqrt() < 1e-2); + } + + #[test] + fn disabled_shield_is_identity() { + let ch = Channel::new(SceneConfig::default()); + let s = ch.observe(0, b"enroll", 1); + let cfg = ShieldConfig { + enabled: false, + ..ShieldConfig::default() + }; + let p = Protector::new(cfg); + assert_eq!(s, p.protect(&s, 7)); + } + + #[test] + fn detector_engages_above_threshold() { + let d = SensingDetector::default(); + assert!(d.should_engage(10.0)); + assert!(!d.should_engage(1.0)); + } +} diff --git a/v2/crates/wifi-densepose-privshield/src/throughput.rs b/v2/crates/wifi-densepose-privshield/src/throughput.rs new file mode 100644 index 00000000..6685f599 --- /dev/null +++ b/v2/crates/wifi-densepose-privshield/src/throughput.rs @@ -0,0 +1,179 @@ +//! Link-throughput model for the protected node. +//! +//! The claim under test is "throughput stays above 95% with the shield on". +//! The model is intentionally transparent and errs toward *charging* the +//! shield, not flattering it. Three costs are charged: +//! +//! - **Beamforming residual.** The legitimate receiver shares the session key +//! and inverts the protector's rotation, so it does not pay the rotation +//! itself — only the residual from quantizing the extra angles at +//! `feedback_bits` resolution. Per-angle mean-square quantization error is +//! `Δ²/12` for step `Δ = (π/2)/2^bits`; this fraction of beamforming gain is +//! lost. It shrinks fast with more bits. +//! - **Feedback airtime.** Reporting the angles at higher resolution costs more +//! uplink airtime — charged as `feedback_overhead_per_bit · feedback_bits`. +//! It grows with more bits. +//! - **Sounding overhead.** Randomizing the NDP sounding cadence costs airtime +//! directly; a flat `sounding_overhead` fraction. +//! +//! The residual (falling) and the feedback airtime (rising) pull `feedback_bits` +//! in opposite directions, so throughput has a genuine **interior optimum** in +//! the number of feedback bits — the quantity [`crate::optimize`] searches for. +//! The optimum lands at coarse-to-moderate resolution because the receiver +//! compensates the keyed rotation, so extra bits mostly buy airtime, not gain — +//! echoing the DySPAN-2026 finding that ~3-bit feedback is near the sweet spot. +//! +//! Throughput ratio = +//! `(1 − sounding − feedback_airtime) · C(SNR·(1−ρ)) / C(SNR)` where +//! `C(x) = log2(1 + x)`. The comm block is never perturbed, so its geometry is +//! intact; only the SNR is nudged by the residual `ρ`. + +use crate::protector::ShieldConfig; + +/// A single-stream link model. +#[derive(Debug, Clone)] +pub struct LinkModel { + /// Operating SNR of the data-carrying beam, in dB. + pub snr_db: f64, + /// Uplink airtime charged per feedback bit, as a fraction of throughput. + /// Larger values push the throughput-optimal `feedback_bits` lower. + pub feedback_overhead_per_bit: f64, +} + +impl Default for LinkModel { + fn default() -> Self { + Self { + snr_db: 20.0, + feedback_overhead_per_bit: 0.0008, + } + } +} + +impl LinkModel { + /// Linear SNR. + #[must_use] + pub fn snr_linear(&self) -> f64 { + 10f64.powf(self.snr_db / 10.0) + } + + /// Baseline Shannon capacity (bits/s/Hz) with no shield. + #[must_use] + pub fn baseline_capacity(&self) -> f64 { + (1.0 + self.snr_linear()).log2() + } + + /// Uncompensated beamforming-gain residual from finite feedback resolution. + #[must_use] + pub fn beamforming_residual(shield: &ShieldConfig) -> f64 { + if !shield.enabled { + return 0.0; + } + let step = (core::f64::consts::FRAC_PI_2) / f64::from(1u32 << shield.feedback_bits); + // Mean-square quantization error of a uniform quantizer, as a fraction + // of unit gain. Clamp for safety at absurdly low resolutions. + (step * step / 12.0).min(0.5) + } + + /// Uplink airtime cost of reporting angles at `feedback_bits` resolution. + #[must_use] + pub fn feedback_airtime(&self, shield: &ShieldConfig) -> f64 { + if !shield.enabled { + return 0.0; + } + self.feedback_overhead_per_bit * f64::from(shield.feedback_bits) + } + + /// Beamforming-gain residual from the ε-DP angular dither, if enabled. + /// Unlike the keyed rotation (which the receiver undoes), the DP noise is + /// **not** removed, so it costs gain directly and grows as ε shrinks — + /// this is the tunable privacy↔throughput knob. SYNTHETIC. + #[must_use] + pub fn dp_residual(shield: &ShieldConfig) -> f64 { + match shield.dp_epsilon { + Some(eps) if shield.enabled => { + let e = f64::from(eps).max(1e-3); + (DP_GAIN_COST / (e * e)).min(0.5) + } + _ => 0.0, + } + } + + /// Throughput ratio of the protected link versus the unshielded baseline, + /// in `[0, 1]`. + #[must_use] + pub fn throughput_ratio(&self, shield: &ShieldConfig) -> f64 { + if !shield.enabled { + return 1.0; + } + let rho = (Self::beamforming_residual(shield) + Self::dp_residual(shield)).min(0.9); + let snr = self.snr_linear(); + let capacity_ratio = (1.0 + snr * (1.0 - rho)).log2() / self.baseline_capacity(); + let airtime = shield.sounding_overhead + self.feedback_airtime(shield); + ((1.0 - airtime) * capacity_ratio).clamp(0.0, 1.0) + } +} + +/// Gain-cost coefficient for the ε-DP dither: residual ≈ `DP_GAIN_COST / ε²`. +/// Tuned so ε≈1 costs a few points of gain and ε≲0.3 costs a lot. SYNTHETIC. +const DP_GAIN_COST: f64 = 0.004; + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn baseline_ratio_is_one() { + let cfg = ShieldConfig { + enabled: false, + ..ShieldConfig::default() + }; + assert!((LinkModel::default().throughput_ratio(&cfg) - 1.0).abs() < 1e-9); + } + + #[test] + fn default_config_preserves_throughput() { + let ratio = LinkModel::default().throughput_ratio(&ShieldConfig::default()); + assert!(ratio > 0.95, "ratio {ratio}"); + assert!(ratio < 1.0); + } + + #[test] + fn dp_epsilon_lowers_throughput_as_it_tightens() { + // The ε-DP dither is a real, tunable privacy↔throughput knob: smaller ε + // (more noise) costs more gain. None (off) is the cheapest. + let link = LinkModel::default(); + let at = |eps: Option| { + link.throughput_ratio(&ShieldConfig { + dp_epsilon: eps, + ..ShieldConfig::default() + }) + }; + let off = at(None); + let loose = at(Some(2.0)); + let tight = at(Some(0.3)); + assert!(off >= loose && loose > tight, "{off} {loose} {tight}"); + } + + #[test] + fn throughput_has_interior_optimum_in_bits() { + // Very low resolution pays the residual; very high resolution pays + // airtime. The optimum is strictly interior — neither extreme wins. + let link = LinkModel::default(); + let at = |bits: u32| { + link.throughput_ratio(&ShieldConfig { + feedback_bits: bits, + ..ShieldConfig::default() + }) + }; + let lo = at(1); + let hi = at(12); + let best_bits = (1..=12) + .max_by(|&a, &b| at(a).partial_cmp(&at(b)).unwrap()) + .unwrap(); + assert!( + best_bits > 1 && best_bits < 12, + "optimum at edge: {best_bits}" + ); + assert!(at(best_bits) > lo && at(best_bits) > hi); + } +} diff --git a/v2/crates/wifi-densepose-privshield/ui/veil-console.html b/v2/crates/wifi-densepose-privshield/ui/veil-console.html new file mode 100644 index 00000000..75235dc5 --- /dev/null +++ b/v2/crates/wifi-densepose-privshield/ui/veil-console.html @@ -0,0 +1,980 @@ +WiFi Veil Console — WiFi-Sensing Privacy Shield + + + +
+
+
+ + + WiFi Veil Console + WiFi-sensing shield + +
+ + Monitoring + + +
+ +
+ +
+
+ +
+
+

Identity inference,
collapsed to chance.

+
4.7%re-id · shield on
+
+
+
+ + + +
+
+ exposed + shielded +
+
+
+
+
+ + +
Live scorecard
+
+
Re-ID · off
100%
attacker unhindered
+
Re-ID · on
4.7%
chance 6.25%
+
Throughput
97.6%
of baseline link
+
Emission
1.000×
not jamming
+
+ + +
+

How this protects you

plain language
+
+
+ + The threat +

Your Wi-Fi constantly sends the router fine signal details — in the clear. A stranger nearby can capture them and recognise individual people by their radio "fingerprint": through walls, with no camera, and nothing on you.

+
+
+ + The shield +

WiFi Veil scrambles that fingerprint on every report with a secret twist only your own router can undo. An outside listener sees a different scramble each time and can't tie it to a person — their guess of "who's here" drops to pure chance.

+
+
+ + Kept honest +

It shapes only your own signal — it never jams, and your Wi-Fi speed stays ~98%. It stops outside snoops, not the router you connect to. Figures here are simulated (L0), pending real-hardware tests.

+
+
+
+ + +
+

Collapse curve

re-ID vs mixing
+
+
Givens passes →op: 96 · re-ID 4.7%
+
+ + +
+

Throughput optimum

vs feedback bits
+
+
Feedback resolution (bits) →5-bit · 97.6%
+
+ + +
+

Sensing activity

solicitations / s
+
+
threshold 5.0 Hz — shield auto-engages above0.0 Hz
+
+ + +
+

Shield controls

live model
+ +
+
Givens passes96min robust 48
+ +
+
+
Feedback resolution5bits · 802.11 {5,7,9}
+ +
+
+
Candidate identities16chance 6.25%
+ +
+
+
Link SNR20dB
+ +
+ +
+
+ Energy in +
= energy out · 1.000×
+ out +
+
+ + +
+

Attacker vs. protector

synthetic · L0
+
+
+ Passive re-ID — shield off— +
+
+
+ Passive re-ID — shield on— +
+
+
+ Link throughput retained— +
+
+
+
+
+ + +
+
Deployment presets · adaptive shield
+
+ + + + +
+
+ +
+ Prefer the terminal? The same instrument ships as veil — a dependency-free + TUI & scriptable harness inside the crate + (cargo run -p wifi-densepose-privshield --bin veil). Live-steer the + shield with on/off · passes · bits · preset · optimize, or run + veil doctor in CI. +
+ +
+ Compliant waveform controls only — never jamming. The shield rotates its own beamforming + feedback with keyed Givens rotations (energy-preserving), so a sniffer can't average out a stable + identity while the associated receiver, holding the key, decodes normally. All figures are + SYNTHETIC / evidence-level L0 from the reference model — not measured on hardware. +
+ ADR-288 · WiFi Veil + ADR-289 · harness + docs/research/privacy-shield +
+
+
+
+ + + + + + + + + diff --git a/v2/crates/wifi-densepose-sensing-server/SECURITY.md b/v2/crates/wifi-densepose-sensing-server/SECURITY.md index 1c07798b..f5c42775 100644 --- a/v2/crates/wifi-densepose-sensing-server/SECURITY.md +++ b/v2/crates/wifi-densepose-sensing-server/SECURITY.md @@ -1,6 +1,6 @@ # Security notes — wifi-densepose-sensing-server -## UDP CSI data plane (ADR-293) +## UDP CSI data plane (ADR-296) The sensing server ingests CSI/radar frames over UDP from ESP32, MediaTek, Qualcomm, and RTL8720F sensor nodes. A valid-shaped frame flips an @@ -10,10 +10,10 @@ presence/vital/automation outputs. ### Threat model Any host that can reach the UDP port can inject a valid-shaped frame. Prior to -ADR-293 the receiver bound `0.0.0.0` unconditionally, so on a routable +ADR-296 the receiver bound `0.0.0.0` unconditionally, so on a routable deployment the data plane was open to the entire LAN. -The controls in ADR-293 (step one) are: +The controls in ADR-296 (step one) are: - **`--udp-bind` (env `RUVIEW_UDP_BIND`), default `127.0.0.1`.** The receiver is loopback-only by default and not reachable off-host. Binding to a routable diff --git a/v2/crates/wifi-densepose-sensing-server/src/inference.rs b/v2/crates/wifi-densepose-sensing-server/src/inference.rs index e1599985..9d514821 100644 --- a/v2/crates/wifi-densepose-sensing-server/src/inference.rs +++ b/v2/crates/wifi-densepose-sensing-server/src/inference.rs @@ -1,4 +1,4 @@ -//! ADR-294 — per-node inference vs. fused room inference. +//! ADR-297 — per-node inference vs. fused room inference. //! //! The multi-node path used to collapse two distinct concepts into one: //! @@ -97,7 +97,7 @@ impl RoomInference { } } - /// Migration accessor for consumers of the pre-ADR-294 aggregate-only shape: + /// Migration accessor for consumers of the pre-ADR-297 aggregate-only shape: /// with a single node, that node's inference *is* the room aggregate. This /// preserves single-node behavior (one node = one inference) exactly. pub fn from_single_node(node: &NodeInference, stale_after_ms: u64) -> Self { @@ -107,7 +107,7 @@ impl RoomInference { /// Fuse per-node inferences into one room aggregate. /// -/// Pure and deterministic (ADR-294): the result depends only on the *set* of +/// Pure and deterministic (ADR-297): the result depends only on the *set* of /// inputs, not on their order or on which arrived last. Each non-stale node /// votes for its classification with its freshness weight; the class with the /// greatest total freshness weight wins, ties broken by classification string diff --git a/v2/crates/wifi-densepose-sensing-server/src/lib.rs b/v2/crates/wifi-densepose-sensing-server/src/lib.rs index f85a44f9..a2868464 100644 --- a/v2/crates/wifi-densepose-sensing-server/src/lib.rs +++ b/v2/crates/wifi-densepose-sensing-server/src/lib.rs @@ -16,14 +16,14 @@ pub mod dataset; pub mod edge_registry; pub mod error_response; pub mod host_validation; -/// ADR-294: per-node vs. fused room inference, with deterministic fusion. +/// ADR-297: per-node vs. fused room inference, with deterministic fusion. pub mod inference; pub mod introspection; pub mod matter; pub mod model_format; pub mod mqtt; pub mod path_safety; -/// ADR-292: canonical source-provenance state machine (synthetic can never +/// ADR-295: canonical source-provenance state machine (synthetic can never /// present as live). pub mod provenance; pub mod semantic; @@ -37,7 +37,7 @@ pub mod semconv; pub mod telemetry; #[allow(dead_code)] pub mod trainer; -/// ADR-293: UDP data-plane bind scope decision + source IP/CIDR allowlist. +/// ADR-296: UDP data-plane bind scope decision + source IP/CIDR allowlist. pub mod udp_bind; pub mod vital_signs; /// ADR-270 Mist and NETGEAR telemetry providers. diff --git a/v2/crates/wifi-densepose-sensing-server/src/main.rs b/v2/crates/wifi-densepose-sensing-server/src/main.rs index 4deb8b3d..5893df17 100644 --- a/v2/crates/wifi-densepose-sensing-server/src/main.rs +++ b/v2/crates/wifi-densepose-sensing-server/src/main.rs @@ -38,7 +38,7 @@ use wifi_densepose_sensing_server::{ dataset, embedding, error_response, graph_transformer, rufield_surface, semconv, telemetry, trainer, }; -// ADR-292 / ADR-294: canonical provenance state + per-node/room inference. +// ADR-295 / ADR-297: canonical provenance state + per-node/room inference. use wifi_densepose_sensing_server::inference::{fuse_room, NodeInference, RoomInference}; use wifi_densepose_sensing_server::provenance::SourceState; @@ -100,7 +100,7 @@ struct Args { #[arg(long, default_value = "5005")] udp_port: u16, - /// UDP bind address for the CSI receiver (ADR-293). Defaults to + /// UDP bind address for the CSI receiver (ADR-296). Defaults to /// `127.0.0.1` (loopback only). Binding to a routable address (`0.0.0.0` /// or a LAN IP) is an explicit operator choice and requires `--udp-allow` /// or `--udp-insecure-lan`. @@ -115,7 +115,7 @@ struct Args { udp_allow: Vec, /// Accept a routable UDP bind with no source allowlist, explicitly opting - /// into the LAN-spoofing risk (ADR-293). The UDP data plane is NOT + /// into the LAN-spoofing risk (ADR-296). The UDP data plane is NOT /// authenticated; see the crate SECURITY.md. #[arg(long, env = "RUVIEW_UDP_INSECURE_LAN")] udp_insecure_lan: bool, @@ -348,7 +348,7 @@ struct SensingUpdate { /// Per-node feature breakdown for multi-node deployments. #[serde(skip_serializing_if = "Option::is_none")] node_features: Option>, - /// ADR-294 — the explicitly-fused room aggregate over the current per-node + /// ADR-297 — the explicitly-fused room aggregate over the current per-node /// inferences (freshness-weighted vote). Deterministic and order-independent, /// unlike the legacy last-writer `classification`; `"unavailable"` when no /// fresh node backs the room rather than a frozen online value. @@ -369,7 +369,7 @@ struct NodeInfo { /// `NodeState::latest_sync` and the iter 18 fps EMA. #[serde(skip_serializing_if = "Option::is_none")] sync: Option, - /// ADR-294 — this node's *own* inference (classification + confidence + + /// ADR-297 — this node's *own* inference (classification + confidence + /// freshness). Distinct from the room aggregate; a node reports what it /// sees, with no silent fallback to the room value. `None` on synthetic / /// placeholder frames that carry no per-node classification. @@ -451,14 +451,14 @@ fn classify_vitals(motion: bool, presence: bool, presence_score: f32) -> Classif } } -/// ADR-294 — the window a node may be silent before it stops contributing to +/// ADR-297 — the window a node may be silent before it stops contributing to /// the fused room aggregate (its entities go stale/unavailable rather than /// holding a frozen online value). Mirrors the 10 s active-node filter used to /// assemble the nodes array. const NODE_STALE_AFTER_MS: u64 = 10_000; /// Build a node's *own* [`NodeInference`] from its smoothed per-node state -/// (ADR-294). Uses the node's own `current_motion_level` — never the room +/// (ADR-297). Uses the node's own `current_motion_level` — never the room /// aggregate — with a confidence from its smoothed person score and freshness /// from its last frame time. Pure given the state snapshot + `now`. fn node_inference_for(n: &NodeState, now: std::time::Instant) -> NodeInference { @@ -1366,7 +1366,7 @@ impl AppStateInner { self.source.clone() } - /// ADR-292 — canonical provenance state for the current source. Derived + /// ADR-295 — canonical provenance state for the current source. Derived /// from the freshness-gated [`effective_source`](Self::effective_source) /// label so ambiguity can never collapse to "live": a synthetic source is /// always `Synthetic`, an `":offline"` label is `Disconnected`, and a fresh @@ -4673,7 +4673,7 @@ async fn health_ready(State(state): State) -> Json { - // ADR-293: drop frames from sources outside the allowlist + // ADR-296: drop frames from sources outside the allowlist // (loopback is always admitted). Counted for observability. if !allowlist.admit(src.ip()) { debug!( @@ -6041,12 +6041,12 @@ async fn udp_receiver_task( // Vitals-only path; still expose the sync snapshot // if the node also speaks ESP-NOW. sync: n.sync_snapshot(), - // ADR-294 — each node carries its own inference. + // ADR-297 — each node carries its own inference. node_inference: Some(node_inference_for(n, now)), }) .collect(); - // ADR-294 — explicit, deterministic room aggregate over the + // ADR-297 — explicit, deterministic room aggregate over the // per-node inferences (freshness-weighted vote). Not the // latest-writer classification (issue #1555). let room_inference = fuse_room( @@ -6541,12 +6541,12 @@ async fn udp_receiver_task( }, // ADR-110 iter 23 / iter 30 — single source of truth. sync: n.sync_snapshot(), - // ADR-294 — each node carries its own inference. + // ADR-297 — each node carries its own inference. node_inference: Some(node_inference_for(n, now)), }) .collect(); - // ADR-294 — explicit deterministic room aggregate over the + // ADR-297 — explicit deterministic room aggregate over the // per-node inferences (not last-writer; issue #1555). let room_inference = fuse_room( active_nodes.iter().filter_map(|ni| ni.node_inference.as_ref()), @@ -8212,7 +8212,7 @@ async fn main() { // promoted — see `simulated_data_task`). Explicit `--source simulated` has // `bind_udp = false`, so it serves simulated data only, with no live binding. if plan.bind_udp { - // ADR-293: resolve the UDP bind scope + source allowlist and fail closed + // ADR-296: resolve the UDP bind scope + source allowlist and fail closed // on an unguarded routable bind, mirroring the OAuth boot refusal below. use wifi_densepose_sensing_server::udp_bind; let udp_bind_ip: std::net::IpAddr = match args.udp_bind.parse() { diff --git a/v2/crates/wifi-densepose-sensing-server/src/mqtt/publisher.rs b/v2/crates/wifi-densepose-sensing-server/src/mqtt/publisher.rs index f696299f..769cc0e4 100644 --- a/v2/crates/wifi-densepose-sensing-server/src/mqtt/publisher.rs +++ b/v2/crates/wifi-densepose-sensing-server/src/mqtt/publisher.rs @@ -333,7 +333,7 @@ async fn publish_snapshot( } // Numeric rate-limited entities. Rate limiting is per (node, entity) - // (ADR-294, issue #1541) so nodes never starve one another. + // (ADR-297, issue #1541) so nodes never starve one another. let node = snap.node_id.as_str(); for (entity, allowed) in [ (EntityKind::PersonCount, rl.allow(node, EntityKind::PersonCount, elapsed, &cfg.rates)), diff --git a/v2/crates/wifi-densepose-sensing-server/src/mqtt/state.rs b/v2/crates/wifi-densepose-sensing-server/src/mqtt/state.rs index 8a991e67..86d2ca43 100644 --- a/v2/crates/wifi-densepose-sensing-server/src/mqtt/state.rs +++ b/v2/crates/wifi-densepose-sensing-server/src/mqtt/state.rs @@ -63,7 +63,7 @@ impl StateMessage { /// emissions accordingly. Time is supplied by the caller so the limiter is /// testable without a clock. /// -/// ADR-294 (issue #1541): the key is `(NodeId, EntityKind)`, not `EntityKind` +/// ADR-297 (issue #1541): the key is `(NodeId, EntityKind)`, not `EntityKind` /// alone. With an entity-only key one node consumed the numeric publish slot /// and every other node was suppressed until the interval expired — while /// availability still reported them online. Keying by node keeps each node's @@ -82,7 +82,7 @@ impl RateLimiter { /// Decide whether a sample for `entity` on node `node_id` is allowed to /// publish at `now`, given the configured `rates`. Returns true to publish /// (and updates last-emitted state); false to drop. Each node's budget for - /// an entity is independent of every other node's (ADR-294). + /// an entity is independent of every other node's (ADR-297). pub fn allow( &mut self, node_id: &str, @@ -427,7 +427,7 @@ mod tests { #[test] fn rate_limiter_nodes_do_not_starve_each_other() { - // ADR-294 (issue #1541): with an entity-only key, node-a consuming the + // ADR-297 (issue #1541): with an entity-only key, node-a consuming the // slot suppressed node-b. Keyed by (node, entity), both publish. let mut rl = RateLimiter::new(); let r = rates(); diff --git a/v2/crates/wifi-densepose-sensing-server/src/provenance.rs b/v2/crates/wifi-densepose-sensing-server/src/provenance.rs index ba0f0257..fee1f1ca 100644 --- a/v2/crates/wifi-densepose-sensing-server/src/provenance.rs +++ b/v2/crates/wifi-densepose-sensing-server/src/provenance.rs @@ -1,4 +1,4 @@ -//! ADR-292 — canonical source-provenance state machine. +//! ADR-295 — canonical source-provenance state machine. //! //! Source state used to be a boolean (`live` vs. not), so any ambiguous //! condition — an unauthenticated status-endpoint error, a simulator that has @@ -44,7 +44,7 @@ pub enum AuthStatus { Unknown, } -/// Canonical, mutually-exclusive source state (ADR-292). There is intentionally +/// Canonical, mutually-exclusive source state (ADR-295). There is intentionally /// no `Unknown` / `Live` boolean — every ambiguous input maps to one of these. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum SourceState { @@ -78,7 +78,7 @@ impl SourceState { ) -> SourceState { // A synthetic source is *always* synthetic. It can only become live by // being reconstructed as `SourceKind::Live` presenting a verified frame, - // never by a transition here (ADR-292, issue #1557). + // never by a transition here (ADR-295, issue #1557). if kind == SourceKind::Synthetic { return SourceState::Synthetic; } @@ -108,7 +108,7 @@ impl SourceState { } /// True when this state must be watermarked as synthetic in every view and - /// export (ADR-292). + /// export (ADR-295). pub fn is_synthetic(self) -> bool { matches!(self, SourceState::Synthetic) } diff --git a/v2/crates/wifi-densepose-sensing-server/src/udp_bind.rs b/v2/crates/wifi-densepose-sensing-server/src/udp_bind.rs index 59072565..0218a060 100644 --- a/v2/crates/wifi-densepose-sensing-server/src/udp_bind.rs +++ b/v2/crates/wifi-densepose-sensing-server/src/udp_bind.rs @@ -1,4 +1,4 @@ -//! ADR-293: sensor data-plane bind hardening — UDP bind scope + source allowlist. +//! ADR-296: sensor data-plane bind hardening — UDP bind scope + source allowlist. //! //! The CSI UDP receiver historically bound `0.0.0.0` unconditionally, with no //! equivalent of the HTTP `--bind-addr` flag, no source allowlist, and no @@ -68,7 +68,7 @@ pub fn decide_udp_bind( "Refusing to bind the UDP CSI receiver to routable address {bind} with no \ source allowlist. Pass --udp-allow to restrict sources, or \ --udp-insecure-lan to accept the LAN-spoofing risk explicitly. The default \ - is loopback (127.0.0.1); see the crate SECURITY.md (ADR-293)." + is loopback (127.0.0.1); see the crate SECURITY.md (ADR-296)." )) } diff --git a/v2/crates/wifi-densepose-train/Cargo.toml b/v2/crates/wifi-densepose-train/Cargo.toml index 7fe32f0c..ed0b6823 100644 --- a/v2/crates/wifi-densepose-train/Cargo.toml +++ b/v2/crates/wifi-densepose-train/Cargo.toml @@ -108,7 +108,7 @@ ndarray-npy.workspace = true name = "training_bench" harness = false -# ADR-288 — bfee-parser throughput and split-assignment benchmarks on +# ADR-291 — bfee-parser throughput and split-assignment benchmarks on # synthetic, code-generated corpora (no dataset files). [[bench]] name = "benchmark_harness" diff --git a/v2/crates/wifi-densepose-train/benches/benchmark_harness.rs b/v2/crates/wifi-densepose-train/benches/benchmark_harness.rs index 1dd6aee7..3aa60080 100644 --- a/v2/crates/wifi-densepose-train/benches/benchmark_harness.rs +++ b/v2/crates/wifi-densepose-train/benches/benchmark_harness.rs @@ -1,4 +1,4 @@ -//! ADR-288 benchmarks: bfee parser throughput and split assignment over +//! ADR-291 benchmarks: bfee parser throughput and split assignment over //! synthetic, code-generated corpora (no dataset files are read or written). use criterion::{black_box, criterion_group, criterion_main, Criterion, Throughput}; diff --git a/v2/crates/wifi-densepose-train/src/dataset.rs b/v2/crates/wifi-densepose-train/src/dataset.rs index b187d7a2..1da84e70 100644 --- a/v2/crates/wifi-densepose-train/src/dataset.rs +++ b/v2/crates/wifi-densepose-train/src/dataset.rs @@ -41,7 +41,7 @@ //! ``` /// Widar3.0 ingest — Intel 5300 `.dat` "bfee" parser and [`CsiDataset`] -/// adapter with split-protocol metadata (ADR-288 §1). +/// adapter with split-protocol metadata (ADR-291 §1). pub mod widar; use ndarray::{Array1, Array2, Array4}; diff --git a/v2/crates/wifi-densepose-train/src/dataset/widar.rs b/v2/crates/wifi-densepose-train/src/dataset/widar.rs index ea451f1d..867f6705 100644 --- a/v2/crates/wifi-densepose-train/src/dataset/widar.rs +++ b/v2/crates/wifi-densepose-train/src/dataset/widar.rs @@ -1,5 +1,5 @@ //! Widar3.0 ingest — Intel 5300 `.dat` "bfee" CSI log parser and dataset -//! adapter (ADR-288 §1). +//! adapter (ADR-291 §1). //! //! The Widar3.0 raw distribution ships CSI captured with the Intel 5300 NIC //! and the Linux 802.11n CSI Tool, stored as framed binary `.dat` logs. This @@ -12,11 +12,11 @@ //! - [`WidarDataset`] — a [`CsiDataset`] implementation that maps each `.dat` //! recording into windowed [`CsiSample`]s (with subcarrier interpolation to //! the training pipeline's target count) and exposes per-window -//! [`SampleMeta`] for the ADR-288 split protocols. +//! [`SampleMeta`] for the ADR-291 split protocols. //! - [`encode_bfee_frame`] — a deterministic synthetic-fixture encoder used by //! unit tests and benches, so no binary dataset files are ever checked in. //! -//! # Binary record layout (ADR-288) +//! # Binary record layout (ADR-291) //! //! ```text //! frame : u16 LE field_len | u8 code (code 0xBB = bfee record) @@ -42,7 +42,7 @@ //! `len` must equal ceil(30 * n_rx * n_tx * 2 * 10 / 8). //! ``` //! -//! This is the layout specified by ADR-288. Note the original Linux CSI Tool +//! This is the layout specified by ADR-291. Note the original Linux CSI Tool //! writes 8-bit components with per-group shift bits and a big-endian frame //! length; if raw upstream logs are ingested unconverted, records fail the //! `len` consistency check and are skipped with a warning rather than being @@ -172,7 +172,7 @@ pub struct BfeeParse { pub non_bfee: usize, } -/// Parse a buffer of framed Intel 5300 bfee records (ADR-288 layout — see the +/// Parse a buffer of framed Intel 5300 bfee records (ADR-291 layout — see the /// module docs for the exact binary format). /// /// The parser never panics on malformed input: invalid or truncated records @@ -392,7 +392,7 @@ fn write_i10(buf: &mut [u8], bit_off: usize, value: i16) { } /// Encode one framed bfee record from synthetic CSI values — the fixture -/// generator used by unit tests and benches (ADR-288: fixtures are generated +/// generator used by unit tests and benches (ADR-291: fixtures are generated /// in code, never checked in as binary files). /// /// `csi` is `(real, imag)` pairs in the packing order @@ -575,7 +575,7 @@ impl WidarEntry { } } -/// Dataset adapter for Widar3.0 `.dat` recordings (ADR-288 §1). +/// Dataset adapter for Widar3.0 `.dat` recordings (ADR-291 §1). /// /// Scanning parses every file once at construction to count valid records; /// [`CsiDataset::get`] re-reads the file lazily and cuts the requested @@ -759,7 +759,7 @@ impl WidarDataset { Some((entry_idx, idx - self.cumulative[entry_idx])) } - /// Split-protocol metadata for the window at `idx` (ADR-288 §2): user → + /// Split-protocol metadata for the window at `idx` (ADR-291 §2): user → /// subject, room → environment, plus orientation/gesture, and the owning /// `.dat` file as the continuous `recording_id`. /// diff --git a/v2/crates/wifi-densepose-train/src/error.rs b/v2/crates/wifi-densepose-train/src/error.rs index 9bfd35f7..04c758b4 100644 --- a/v2/crates/wifi-densepose-train/src/error.rs +++ b/v2/crates/wifi-densepose-train/src/error.rs @@ -13,7 +13,7 @@ //! ├── DatasetError (data loading, I/O, format) //! ├── SubcarrierError (frequency-axis resampling) //! ├── MaeError (MAE patchify / masking — ADR-152 §2.3) -//! └── ProtocolError (split protocols / leakage audit — ADR-288) +//! └── ProtocolError (split protocols / leakage audit — ADR-291) //! ``` use std::path::PathBuf; @@ -50,7 +50,7 @@ pub enum TrainError { #[error("MAE pretraining error: {0}")] Mae(#[from] MaeError), - /// A split-protocol / leakage-audit error (ADR-288). + /// A split-protocol / leakage-audit error (ADR-291). #[error("Protocol error: {0}")] Protocol(#[from] ProtocolError), @@ -477,7 +477,7 @@ pub enum MaeError { // --------------------------------------------------------------------------- /// Errors produced by the public-benchmark split protocols and leakage guards -/// ([`crate::protocols`], ADR-288). +/// ([`crate::protocols`], ADR-291). /// /// Every leakage-audit failure is an `Err`, never a warning: a split that /// leaks subjects, environments, or windows of a continuous recording across @@ -527,7 +527,7 @@ pub enum ProtocolError { /// Two windows cut from the same continuous recording ended up on /// opposite sides of the split. Overlapping/adjacent windows are /// near-identical, so this is window-level leakage regardless of the - /// protocol (the 2024–2025 leakage reckoning; ADR-288 §Context). + /// protocol (the 2024–2025 leakage reckoning; ADR-291 §Context). #[error( "Recording {recording_id} has windows on both sides of the split \ (window-level leakage from a continuous recording)" diff --git a/v2/crates/wifi-densepose-train/src/lib.rs b/v2/crates/wifi-densepose-train/src/lib.rs index 0014b5a9..50897945 100644 --- a/v2/crates/wifi-densepose-train/src/lib.rs +++ b/v2/crates/wifi-densepose-train/src/lib.rs @@ -59,12 +59,12 @@ pub mod mae; /// `oks_canonical`, available **without** the `tch-backend` feature so the /// single metric definition is reachable from the workspace test gate. pub mod metrics_core; -/// Model release sanity gates (ADR-295) — block degenerate and mislabeled +/// Model release sanity gates (ADR-298) — block degenerate and mislabeled /// classifier artifacts (unreachable decision boundary, constant output, /// degenerate class balance, missing baseline, metric-name provenance) before /// release. Prevention only; withdraws nothing already published. pub mod model_gates; -/// Public-benchmark split protocols and leakage guards (ADR-288 §2–3) — +/// Public-benchmark split protocols and leakage guards (ADR-291 §2–3) — /// deterministic cross-subject / cross-environment / cross-orientation /// assignment plus the structural [`protocols::leakage::LeakageAudit`], /// mean-pose baseline, and evidence-graded evaluation reports. @@ -113,14 +113,14 @@ pub use config::TrainingConfig; pub use dataset::{ CsiDataset, CsiSample, DataLoader, MmFiDataset, SyntheticConfig, SyntheticCsiDataset, }; -// ADR-288 — Widar3.0 ingest, split protocols, and leakage guards. +// ADR-291 — Widar3.0 ingest, split protocols, and leakage guards. pub use dataset::widar::{parse_bfee_bytes, BfeeParse, BfeeRecord, WidarDataset, WidarFileMeta}; pub use protocols::leakage::{ EvaluationReport, EvidenceGrade, LeakageAudit, LeakageClaims, MeanPoseBaseline, }; pub use protocols::{SampleMeta, SplitPlan, SplitProtocol, SplitSide}; -// ADR-295 — model release sanity gates. +// ADR-298 — model release sanity gates. pub use model_gates::{ check_baseline, check_class_balance, check_constant_output, check_metric_provenance, check_unreachable_boundary, evaluate_linear_head, GateError, GateFailure, GateOutcomeError, diff --git a/v2/crates/wifi-densepose-train/src/model_gates.rs b/v2/crates/wifi-densepose-train/src/model_gates.rs index 65f2f332..2fd34e93 100644 --- a/v2/crates/wifi-densepose-train/src/model_gates.rs +++ b/v2/crates/wifi-densepose-train/src/model_gates.rs @@ -1,4 +1,4 @@ -//! Model release sanity gates (ADR-295) — block degenerate and mislabeled +//! Model release sanity gates (ADR-298) — block degenerate and mislabeled //! classifier artifacts before they can ship. //! //! # Why this module exists @@ -21,7 +21,7 @@ //! - [`check_class_balance`] — fail when the predicted-positive rate on a //! balanced probe set sits at/above a ceiling (e.g. `> 99 %`). //! - [`check_baseline`] — fail a report with no paired mean-pose/majority -//! baseline (ties into the ADR-288 [`EvaluationReport`]). +//! baseline (ties into the ADR-291 [`EvaluationReport`]). //! - [`check_metric_provenance`] — a metric carries its computed //! [`MetricKind`] and its display label derives from it, so a temporal-triplet //! metric can never be surfaced under the `presence` task name. @@ -32,7 +32,7 @@ //! # This is prevention, not a correctness proof //! //! The gates are heuristic. They catch the *known* failure shapes above, not -//! all bad models (ADR-295 §Consequences). This module does **not** withdraw +//! all bad models (ADR-298 §Consequences). This module does **not** withdraw //! any already-published artifact — an outward-facing action requiring //! maintainer sign-off — it prevents recurrence. //! @@ -168,7 +168,7 @@ pub enum GateFailure { probe_size: usize, }, - /// A report was surfaced without a paired baseline (ADR-288). + /// A report was surfaced without a paired baseline (ADR-291). #[error("missing baseline: {reason}")] MissingBaseline { /// Why the baseline is considered missing/blank. @@ -543,7 +543,7 @@ pub fn check_class_balance( Ok(()) } -/// Fail when a metric is surfaced without a paired baseline (ADR-288). +/// Fail when a metric is surfaced without a paired baseline (ADR-291). /// /// A well-formed [`EvaluationReport`] structurally carries its `baseline_metric` /// (a model number can never be built without one), so this gate's job is to @@ -558,7 +558,7 @@ pub fn check_baseline(report: Option<&EvaluationReport>) -> Result<(), GateFailu match report { None => Err(GateFailure::MissingBaseline { reason: "no EvaluationReport was provided; a model number must be \ - paired with a mean-pose/majority baseline (ADR-288)" + paired with a mean-pose/majority baseline (ADR-291)" .to_string(), }), Some(r) if !r.baseline_metric.is_finite() => Err(GateFailure::MissingBaseline { diff --git a/v2/crates/wifi-densepose-train/src/protocols.rs b/v2/crates/wifi-densepose-train/src/protocols.rs index 851d9fbc..81e3a776 100644 --- a/v2/crates/wifi-densepose-train/src/protocols.rs +++ b/v2/crates/wifi-densepose-train/src/protocols.rs @@ -1,9 +1,9 @@ -//! Standard public-benchmark split protocols (ADR-288 §2). +//! Standard public-benchmark split protocols (ADR-291 §2). //! //! The field's documented leakage failure is the window-level random split: //! adjacent windows cut from one continuous recording are near-identical, so //! splitting them across train/test inflates accuracy (one dataset's F1 -//! collapsed from ~90% to ~22% under subject-disjoint splits — ADR-288 +//! collapsed from ~90% to ~22% under subject-disjoint splits — ADR-291 //! §Context). This module expresses the standard leaderboard evaluations as a //! [`SplitProtocol`] whose assignment is a **pure function of sample metadata //! plus a seed** — no RNG state, no iteration-order dependence, byte-identical diff --git a/v2/crates/wifi-densepose-train/src/protocols/leakage.rs b/v2/crates/wifi-densepose-train/src/protocols/leakage.rs index 24b0ed13..fc8a8ea1 100644 --- a/v2/crates/wifi-densepose-train/src/protocols/leakage.rs +++ b/v2/crates/wifi-densepose-train/src/protocols/leakage.rs @@ -1,5 +1,5 @@ //! Structural leakage guards, mean-pose baseline, and evidence-graded -//! evaluation reports (ADR-288 §3). +//! evaluation reports (ADR-291 §3). //! //! Three enforcement points, all `Err`-on-failure (never a warning): //! @@ -58,7 +58,7 @@ pub struct LeakageAuditPass { pub test_recordings: usize, } -/// Structural train/test-split auditor (ADR-288 §3). +/// Structural train/test-split auditor (ADR-291 §3). /// /// A failed audit is an [`Err`], not a warning: leaky splits must be unusable /// for reporting, not merely frowned upon. @@ -311,7 +311,7 @@ impl EvidenceGrade { /// An evaluation result that structurally pairs the model metric with the /// mean-pose (or other) baseline metric and an [`EvidenceGrade`] — a model -/// number can never be reported without its baseline (ADR-288 §3). +/// number can never be reported without its baseline (ADR-291 §3). #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub struct EvaluationReport { /// Protocol the split followed. diff --git a/v2/crates/wifi-densepose-vitals/benches/groundtruth_bench.rs b/v2/crates/wifi-densepose-vitals/benches/groundtruth_bench.rs index 1d901af3..1bb1efae 100644 --- a/v2/crates/wifi-densepose-vitals/benches/groundtruth_bench.rs +++ b/v2/crates/wifi-densepose-vitals/benches/groundtruth_bench.rs @@ -1,4 +1,4 @@ -//! Benchmark for ground-truth time alignment (ADR-290). +//! Benchmark for ground-truth time alignment (ADR-293). //! //! Aligns an hour-scale synthetic session (3600 s) against a reference //! series with a known 12 s clock offset, over the default ±30 s lag diff --git a/v2/crates/wifi-densepose-vitals/src/groundtruth.rs b/v2/crates/wifi-densepose-vitals/src/groundtruth.rs index 83605821..8111b4e6 100644 --- a/v2/crates/wifi-densepose-vitals/src/groundtruth.rs +++ b/v2/crates/wifi-densepose-vitals/src/groundtruth.rs @@ -1,5 +1,5 @@ //! Ground-truth reference ingest, time alignment, and agreement metrics -//! (ADR-290). +//! (ADR-293). //! //! Every credible vitals result ships with reference-sensor ground truth //! (chest strap, pulse oximeter, ECG). This module makes a `MEASURED` vitals @@ -216,7 +216,7 @@ pub enum Measurand { } impl Measurand { - /// Default agreement tolerance for this measurand (ADR-290: ±2 bpm for + /// Default agreement tolerance for this measurand (ADR-293: ±2 bpm for /// heart rate, ±1 brpm for breathing). #[must_use] pub fn default_tolerance_bpm(self) -> f64 { @@ -893,7 +893,7 @@ pub enum DistanceBand { Far, } -/// Mandatory scope statement for an agreement report (ADR-290): a vitals +/// Mandatory scope statement for an agreement report (ADR-293): a vitals /// number without its scope is systematically misleading, so a report /// cannot be constructed without one. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] @@ -1103,7 +1103,7 @@ impl AgreementReport { /// /// Has no public constructor: the only way to obtain one is /// [`GradedAgreementReport::measured`], which enforces the gate. This makes -/// `MEASURED` unconstructible without passing the gate (ADR-288-style +/// `MEASURED` unconstructible without passing the gate (ADR-291-style /// enforcement in types). #[derive(Debug, Clone, PartialEq, Eq)] #[cfg_attr(feature = "serde", derive(Serialize))] diff --git a/v2/crates/wifi-densepose-vitals/src/lib.rs b/v2/crates/wifi-densepose-vitals/src/lib.rs index f97112be..37818088 100644 --- a/v2/crates/wifi-densepose-vitals/src/lib.rs +++ b/v2/crates/wifi-densepose-vitals/src/lib.rs @@ -23,7 +23,7 @@ //! Results are stored in a [`VitalSignStore`] with configurable //! retention for historical analysis. //! -//! Ground-truth evaluation ([`groundtruth`], ADR-290) ingests a +//! Ground-truth evaluation ([`groundtruth`], ADR-293) ingests a //! reference-device series (CSV export), time-aligns it against a store //! session, and produces evidence-graded agreement statistics //! (MAE/RMSE/bias, Bland-Altman limits, percent-within-tolerance) with a diff --git a/wifi-veil/.github/workflows/ci.yml b/wifi-veil/.github/workflows/ci.yml new file mode 100644 index 00000000..9e6706a0 --- /dev/null +++ b/wifi-veil/.github/workflows/ci.yml @@ -0,0 +1,62 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true + +jobs: + guard: + name: Honesty / anti-slop guard + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Enforce honesty / anti-slop invariants + run: bash scripts/ci-guard.sh + + rust: + name: Rust (test + lint + wasm) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Install Rust toolchain + run: | + rustup toolchain install stable --profile minimal + rustup component add clippy rustfmt + rustup target add wasm32-unknown-unknown + - name: Format + run: cargo fmt --check + - name: Clippy + run: cargo clippy --all-targets -- -D warnings + - name: Test (crate + proof witness) + run: cargo test + - name: WASM leaf builds + run: cargo build --lib --target wasm32-unknown-unknown + + c-core: + name: Firmware C core (host test) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Build + test portable core + run: make -C firmware/core test + + harness: + name: Harness (smoke) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + - name: Guidance runs dependency-free + run: node harness/bin/cli.js guidance --topic overview + - name: Install + unit tests + working-directory: harness + run: | + npm ci --ignore-scripts || npm install --ignore-scripts + npm test --if-present diff --git a/wifi-veil/.github/workflows/pages.yml b/wifi-veil/.github/workflows/pages.yml new file mode 100644 index 00000000..e51bab9d --- /dev/null +++ b/wifi-veil/.github/workflows/pages.yml @@ -0,0 +1,44 @@ +name: Pages + +# Publish the WiFi Veil Console (ui/veil-console.html) to GitHub Pages. +# The console is a single self-contained file (inline CSS/JS, no network), so the +# "build" is just staging it as the site's index.html. Enable once under +# Settings → Pages → Source: "GitHub Actions". + +on: + push: + branches: [main] + paths: + - "ui/**" + - ".github/workflows/pages.yml" + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +# Allow one concurrent deployment; don't cancel an in-progress one. +concurrency: + group: pages + cancel-in-progress: false + +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Stage the console as the site + run: | + mkdir -p _site + cp ui/veil-console.html _site/index.html + cp ui/veil-console.html _site/veil-console.html + - uses: actions/configure-pages@v5 + - uses: actions/upload-pages-artifact@v3 + with: + path: _site + - id: deployment + uses: actions/deploy-pages@v4 diff --git a/wifi-veil/.gitignore b/wifi-veil/.gitignore new file mode 100644 index 00000000..23946dab --- /dev/null +++ b/wifi-veil/.gitignore @@ -0,0 +1,29 @@ +# Rust +/target +**/*.rs.bk + +# Library crate: lockfile not committed +Cargo.lock + +# C firmware host builds +firmware/**/*.o +firmware/core/test_veil_shield + +# ESP-IDF example build output +firmware/esp32/examples/*/build/ +firmware/esp32/examples/*/managed_components/ +firmware/esp32/examples/*/sdkconfig +firmware/esp32/examples/*/sdkconfig.old +firmware/esp32/examples/*/dependencies.lock + +# Node / harness +node_modules/ +harness/dist/ + +# Agent/tooling telemetry — never commit +.claude-flow/ +*.log + +# OS / editor +.DS_Store +*.swp diff --git a/wifi-veil/CHANGELOG.md b/wifi-veil/CHANGELOG.md new file mode 100644 index 00000000..1f61588d --- /dev/null +++ b/wifi-veil/CHANGELOG.md @@ -0,0 +1,27 @@ +# Changelog + +All notable changes to WiFi Veil are documented here. The format is based on +[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project aims to +follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added +- Standalone repository layout extracted from the RuView monorepo: the + dependency-free `wifi-veil` Rust crate at the repo root, the `veil` terminal + TUI, the self-contained WiFi Veil Console (`ui/veil-console.html`), the + end-to-end `firmware/` hardware program (host-validated portable C core plus + per-provider scaffolds), and the `wifi-veil-harness` npm MetaHarness. +- Continuous integration: Rust build/test/clippy/fmt + WASM leaf build, the C + core host test, and the harness smoke run. + +### Notes +- All defense figures remain `SYNTHETIC` / evidence level **L0**. No result is + `MEASURED` until a two-node hardware capture with a witness exists (roadmap + **P5**). Compliant waveform controls only — never jamming. + +## [0.1.0] +- Initial VEIL reference: keyed Givens-rotation shield, passive re-identification + attacker, throughput/compliance models, optimizer, and a pinned deterministic + proof witness (ADR-288). npm MetaHarness (ADR-289). E2E hardware program and + portable C core (ADR-290). diff --git a/wifi-veil/CONTRIBUTING.md b/wifi-veil/CONTRIBUTING.md new file mode 100644 index 00000000..f8d1a396 --- /dev/null +++ b/wifi-veil/CONTRIBUTING.md @@ -0,0 +1,55 @@ +# Contributing to WiFi Veil + +Thanks for your interest. WiFi Veil is a privacy-defense project with a strict +honesty and safety contract — please read this before opening a PR. + +## Non-negotiable rules + +- **Compliant waveform controls only — never jamming.** Do not add, suggest, or + scaffold interference-based "defenses." Every control must shape the node's + *own* standards-conformant emission and preserve its energy. +- **Never present WiFi sensing as camera-grade.** Accuracy/defense statements + must be tagged `SYNTHETIC`, `CLAIMED`, or `MEASURED`. A number is only + `MEASURED` with a reproducer; hardware claims require a captured real-silicon + log. Everything in this repo today is `SYNTHETIC / L0`. +- **The proof witness is load-bearing.** The default scene is pinned by a + deterministic FNV-1a witness (`src/proof.rs`). If a change intentionally moves + it, re-pin the constant *in the same PR* and explain why; an accidental change + is a failing test, not a witness to bump. + +## Development + +The Rust crate is dependency-free and builds offline. + +```bash +cargo test # 43 tests + the pinned witness +cargo clippy --all-targets -- -D warnings +cargo fmt --check +cargo build --lib --target wasm32-unknown-unknown # WASM leaf must stay green + +cd firmware/core && make test # portable C core host test +node harness/bin/cli.js guidance --topic overview # harness (dependency-free) +``` + +Run the honesty / anti-slop guard before pushing (CI runs it too): + +```bash +bash scripts/ci-guard.sh +``` + +It statically enforces the invariants that keep this project honest: no +telemetry / build artifacts / lockfile / scratch files committed; no debug or +mock-probe markers in source; the `SYNTHETIC` evidence label present on every +firmware provider README; the "never jamming" compliance disclaimer present; no +dishonest hardware-validation claims (honest negated/`TODO(hw)` mentions are +fine); and no stale monorepo identifiers in the code surface. + +CI (`.github/workflows/ci.yml`) runs the same gates. Keep changes the smallest +coherent unit, read before editing, and never commit telemetry (`.claude-flow/`), +build artifacts, credentials, or CSI/person data. + +## Architecture decisions + +Substantive design changes should reference or add an ADR under +[`docs/adr/`](docs/adr/). Treat source, tests, and accepted ADRs as +authoritative over comments and generated text. diff --git a/wifi-veil/Cargo.toml b/wifi-veil/Cargo.toml new file mode 100644 index 00000000..6f785c52 --- /dev/null +++ b/wifi-veil/Cargo.toml @@ -0,0 +1,46 @@ +# WiFi Veil — standalone Rust package (extracted from the RuView monorepo). +# Dependency-free by design: no `rand`, no `std::time`/`fs`/`env`/threads, so it +# builds unchanged for `wasm32-unknown-unknown` and can never emit RF or touch a +# radio. The shield *models* compliant waveform controls; it does not drive +# hardware. Every number it prints is SYNTHETIC and reproduced by `cargo test`. + +# Empty [workspace] table marks this directory as its own workspace root so it is +# self-contained even when nested inside another repository during extraction. +[workspace] + +[package] +name = "wifi-veil" +description = "WiFi Veil (codename VEIL): compliant-waveform countermeasure against unauthorized WiFi sensing. Deterministic attacker-vs-protector experiment that drives beamforming-feedback identity inference toward chance while preserving link throughput. Std-only pure-compute leaf, no async/server/RF-hardware deps; SYNTHETIC data only." +version = "0.1.0" +edition = "2021" +rust-version = "1.82" +authors = ["rUv ", "WiFi Veil Contributors"] +license = "MIT OR Apache-2.0" +repository = "https://github.com/ruvnet/wifi-veil" +documentation = "https://docs.rs/wifi-veil" +homepage = "https://github.com/ruvnet/wifi-veil" +keywords = ["wifi", "privacy", "beamforming", "sensing", "security"] +categories = ["science", "simulation", "wasm"] +readme = "README.md" + +# Intentionally dependency-free (see the module docs in `src/lib.rs`). +[dependencies] + +[dev-dependencies] + +[lib] +name = "wifi_veil" +path = "src/lib.rs" + +# `veil` — the custom, dependency-free terminal harness + TUI. Native counterpart +# to the npm metaharness under `harness/`. Std-only; builds without extra deps. +# Excluded from the wasm leaf story (that stays `cargo build --lib`). +[[bin]] +name = "veil" +path = "src/bin/veil.rs" + +[profile.release] +opt-level = 3 +lto = true +codegen-units = 1 +panic = "abort" diff --git a/wifi-veil/LICENSE-APACHE b/wifi-veil/LICENSE-APACHE new file mode 100644 index 00000000..d44bde4d --- /dev/null +++ b/wifi-veil/LICENSE-APACHE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2026 rUv and WiFi Veil Contributors + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/wifi-veil/LICENSE-MIT b/wifi-veil/LICENSE-MIT new file mode 100644 index 00000000..4dac7b55 --- /dev/null +++ b/wifi-veil/LICENSE-MIT @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 rUv + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/wifi-veil/README.md b/wifi-veil/README.md new file mode 100644 index 00000000..15aa39d5 --- /dev/null +++ b/wifi-veil/README.md @@ -0,0 +1,130 @@ +![WiFi Veil Console — the shield engaged, with the room's WiFi identity clusters collapsed to the chance floor (re-ID 4.7%, throughput preserved, compliant)](docs/assets/veil-console.png) + +# WiFi Veil + +**A privacy firewall against unauthorized WiFi sensing — compliant waveform +controls only, never jamming.** + +**WiFi Veil** (codename **VEIL** — Verifiable Emission-shaping for +Identity-Leakage prevention) shapes a node's own outgoing WiFi beamforming +feedback so that an unauthorized passive sniffer cannot re-identify people or +infer activity, while a legitimate receiver — which shares a per-session key — +sees an essentially unchanged link. + +> **Evidence discipline (read first).** Every defense number here is +> `SYNTHETIC` / evidence level **L0** — reproduced by `cargo test`, not measured +> on a radio. Nothing claims camera-grade accuracy, and no result becomes +> `MEASURED` without a captured hardware log (roadmap **P5**). WiFi Veil uses +> **compliant waveform controls only — never jamming.** + +--- + +## How this protects you from unauthorized WiFi surveillance + +**The threat — silent, device-free identification.** Since WiFi 5, your device +tells the router how to aim its signal by sending back *beamforming feedback* — +and it goes out **unencrypted**. Anyone within radio range can passively capture +those reports and, from the tiny stable details in them, **tell individual +people apart by their radio "fingerprint"** — through walls, with no camera, no +app, and nothing you carry. Published research re-identifies individuals, counts +occupancy through walls, and reads activity this way, and the 2025 sensing +standard (802.11bf) added the capability but **no privacy protection**. Because +the attacker only listens, you get no indication it is happening. + +**The defense — scramble the fingerprint, keep the link.** WiFi Veil adds a +secret, **per-session "twist"** to your own outgoing feedback, built from the +same rotation math (Givens rotations) the report already uses: + +- Your **own router shares the key** and undoes the twist instantly, so it + decodes normally — **your WiFi keeps ~98% of its speed.** +- An **outside listener sees a *different* twist every session** and cannot + average many captures into one stable fingerprint. Its guess of *who is in the + room* **collapses to chance.** +- The twist only **reshapes your own, standards-legal signal** — it preserves + the signal's energy exactly (`energy in = energy out`), so it is **compliant, + never jamming.** + +## The idea + +Identity leaks through the **fine** cross-subcarrier phase structure of a +compressed beamforming report; data throughput rides the **dominant** beam +direction. These live in (mostly) separable subspaces. WiFi Veil composes extra +**keyed Givens rotations** over the *fine* subspace only: + +| Property | Consequence | +|---|---| +| **Orthogonal** (energy-preserving) | No added transmit power ⇒ **not jamming** (47 U.S.C. §333/§302a) | +| **Keyed per session** | The legitimate AP inverts it ⇒ throughput preserved | +| **Fresh each session** | A sniffer sees a different rotation every time and can't average it back ⇒ re-identification collapses to chance | + +## Result (hyper-optimized default scene, N = 16 identities) + +| Metric | Shield off | Shield on | +|---|---|---| +| Passive re-ID accuracy | **100%** | **4.7%** (chance = 6.25%) | +| Link throughput ratio | 100% | **97.6%** | +| Emission energy ratio | — | **1.000000** (compliant) | + +All figures are `SYNTHETIC / L0`, byte-reproducible via a pinned FNV-1a witness +(`cargo test`). + +## Repository layout + +| Path | What it is | Status | +|---|---|---| +| [`src/`](src/) + [`Cargo.toml`](Cargo.toml) | The `wifi-veil` Rust crate — deterministic, dependency-free, WASM-ready reference & experiment (attacker vs. protector, compliance audit, optimizer, proof witness) | **validated** (`cargo test`) | +| [`src/bin/veil.rs`](src/bin/veil.rs) | `veil` — the dependency-free terminal harness + ANSI TUI | validated | +| [`ui/veil-console.html`](ui/veil-console.html) | The graphical **WiFi Veil Console** — self-contained, no build, no network | — | +| [`firmware/`](firmware/) | End-to-end hardware program: a host-validated portable **C core** + honest per-provider scaffolds (openwifi / openwrt / nexmon / esp32) | C core validated; adapters `SYNTHETIC / L0` build-only | +| [`harness/`](harness/) | `wifi-veil-harness` — npm MetaHarness (read-only guidance, router, flywheel) | — | +| [`docs/adr/`](docs/adr/) | Architecture decisions (ADR-288 shield, ADR-289 harness, ADR-290 hardware program) | — | +| [`docs/research/privacy-shield/`](docs/research/privacy-shield/) | SOTA survey, threat model, countermeasure design, compliance, experiment protocol, market, roadmap | — | + +## Quickstart + +```bash +# 1. The reference model + proof (dependency-free; builds offline) +cargo test # 43 tests + the pinned witness +cargo run --bin veil # interactive TUI (one-shot report when piped) +cargo run --bin veil -- optimize # derive the shipped shield config + +# 2. The portable C shield core (host test, no radio) +cd firmware/core && make test # energy conservation, reversibility, PRNG parity + +# 3. The console UI — just open it +open ui/veil-console.html # (or double-click; no build, no network) + +# 4. The npm harness (read-only guidance needs no install) +node harness/bin/cli.js guidance --topic overview +``` + +The crate is **dependency-free** and **WASM-ready**: + +```bash +cargo build --lib --target wasm32-unknown-unknown +``` + +## Does this run on real WiFi hardware? + +Partially today, fully on an open PHY — see [`firmware/`](firmware/) for the +per-provider feasibility matrix. In short: **openwifi** (SDR/FPGA) is the only +platform that can host the full keyed-reversible design end-to-end; **OpenWRT** +and **Nexmon** reach partial/coarse controls (the exact angles are locked in the +WiFi MCU firmware blob on commodity parts); and **ESP32 cannot shield its own +feedback** — it helps only as a sensing detector or an external-RIS controller. +All firmware is build-only `SYNTHETIC / L0`; no adapter has run on silicon. + +## Threat model & scope (stated plainly) + +WiFi Veil defends against a **third-party passive sniffer** capturing plaintext +beamforming feedback. It does **not** hide identity from the AP a node is +associated with (that party holds the key by construction). It is **compliant by +construction** — it only shapes the node's own standards-conformant frames, +never transmits to interfere with another station, and never operates an +unauthorized emitter. It is not jamming, not RF denial, and not a claim of +camera-grade anything. + +## License + +Dual-licensed under either of [Apache License 2.0](LICENSE-APACHE) or +[MIT license](LICENSE-MIT) at your option. diff --git a/wifi-veil/docs/adr/ADR-288-veil-privacy-shield-compliant-waveform.md b/wifi-veil/docs/adr/ADR-288-veil-privacy-shield-compliant-waveform.md new file mode 100644 index 00000000..2983e4fd --- /dev/null +++ b/wifi-veil/docs/adr/ADR-288-veil-privacy-shield-compliant-waveform.md @@ -0,0 +1,231 @@ +# ADR-288: VEIL — a compliant-waveform privacy shield against unauthorized WiFi sensing + +| Field | Value | +|-------|-------| +| **Status** | Proposed — implemented (P1 reference model) | +| **Date** | 2026-08-09 | +| **Deciders** | ruv | +| **Codename** | **VEIL** — Verifiable Emission-shaping for Identity-Leakage prevention | +| **Codebase target** | new leaf crate `v2/crates/wifi-densepose-privshield` | +| **Parent** | ADR-118 (BFLD — the detection layer VEIL is the countermeasure to), ADR-282 (mandatory L0–L5 evidence ladder) | +| **Relates to** | ADR-120/121 (BFLD privacy class + identity-risk scoring — the trigger source), ADR-141 (privacy control plane / runtime attestation — the audit consumer), ADR-280 (active sensing / governed actuation — VEIL is a defensive sensing action), ADR-185 §13 (`wifi-densepose-aether` — the pure-compute leaf pattern this crate follows) | +| **Research bundle** | [`docs/research/privacy-shield/`](../research/privacy-shield/) (9 files) | +| **Tracking issue** | TBD | + +## 0. PROOF discipline + +Every defense number this crate produces is **SYNTHETIC / evidence level L0** +(ADR-282): generated by the crate's own model (`identity::Channel`), attacked by +the crate's own classifier (`attacker::NearestCentroidAttacker`), and scored +against its own known labels. Nothing here has been validated against real WiFi +silicon, and the crate contains no radio integration and cannot emit RF. External +attack/defense results cited from the literature (BFId, LeakyBeam, DySPAN-2026, +IRShield, FCC statutes) are **EXTERNAL** evidence and labelled MEASURED/CLAIMED in +the research bundle. The single measured claim about *our own behavior* is the +pinned deterministic witness in `proof.rs`. + +## 1. Context + +### 1.1 The gap + +IEEE 802.11ac/ax beamforming feedback (BFI) — the compressed Givens-rotation +angle matrices (φ/ψ) a client sends the AP — is transmitted **unencrypted on the +management plane**. Any device in monitor mode can capture it for every station +at once, no network access, and the target need carry no device. The literature +establishes the severity: **BFId** (ACM CCS 2025) re-identifies individuals from +BFI; **LeakyBeam** (NDSS 2025) detects occupancy through walls at 20 m from BFI; +**BeamSense** recognizes activities at up to 99.28%. IEEE Std **802.11bf-2025** +(published 26 Sep 2025) standardizes the sensing measurement/feedback surface +these attacks abuse — and a 2023 proposal for a BFI secure-transmission mechanism +(802.11-23/0782) was **withdrawn**, so the standard shipped with no privacy +protections. + +RuView already has a *detection* layer for this: **BFLD** (ADR-118/121) measures +the identity-leakage of each frame and gates what leaves the node. But BFLD +protects *RuView's own outputs*; it does nothing about a **third-party sniffer** +capturing the room's plaintext BFI off the air. There is no RuView component, and +per our market survey no shipping product anywhere, that prevents that. + +### 1.2 Constraint: compliant waveform controls, never jamming + +The defense must preserve normal communications and must not interfere with any +other station. Jamming (47 U.S.C. §333/§302a) is defined by *adding energy to +interfere with others' transmissions*. Any acceptable control must shape only the +node's **own** standards-conformant emission. + +### 1.3 The separability insight + +Identity leaks through the *fine* cross-subcarrier phase structure of a +beamforming report; data throughput rides the *dominant* beam direction. These +are (mostly) separable subspaces — so a transform confined to the fine subspace +can wreck re-identification while sparing the beam the link depends on. DySPAN-2026 +independently MEASURED that shaping fine-resolution feedback is near-free in +throughput, corroborating the insight. + +## 2. Decision + +Ship **`wifi-densepose-privshield`** (VEIL) as a standalone pure-compute leaf +crate (the `wifi-densepose-aether`/`nvsim` pattern: dependency-free, deterministic, +WASM-ready, zero coupling to any radio or ingestion path), implementing: + +1. **A SYNTHETIC two-subspace BFI model** (`identity.rs`): each identity owns a + stable fine-block signature; sessions add environmental nuisance; the comm + block is identity-free and carries throughput. +2. **The protector** (`protector.rs`): compliant waveform controls, primarily a + **per-session keyed orthogonal rotation of the fine subspace, composed from + extra Givens rotations** — the report's native primitive. Plus feedback + quantization/dither, sounding-cadence randomization, and a `SensingDetector` + that engages the shield only when sensing activity is observed. +3. **The adversary** (`attacker.rs`): a passive nearest-centroid re-identifier + modeling the BFId threat, with selectable Euclidean/Cosine metrics. +4. **A throughput model** (`throughput.rs`): + `(1 − sounding − feedback_airtime) · C(SNR·(1−ρ))/C(SNR)`, where the residual + `ρ` falls with feedback bits and the feedback airtime rises with them — giving + a genuine interior throughput optimum in feedback resolution. +5. **A compliance audit** (`compliance.rs`): the rotation is orthogonal ⇒ + energy-preserving ⇒ adds no interfering energy ⇒ **not jamming**, turned into a + checked `ComplianceReport` (energy ratio ≈ 1.0). +6. **The experiment** (`experiment.rs`): runs the attacker against unprotected and + protected traffic and reports both accuracies vs. chance, plus throughput and + compliance, with a single `passed()` verdict. +7. **The hyper-optimizer** (`optimize.rs`): derives the shipped shield config + rather than hand-picking it — the throughput-optimal feedback resolution and + the minimum rotation-mixing budget that collapses re-ID robustly (across both + attacker metrics and N∈{16,32}), plus a Pareto frontier. +8. **A deterministic proof** (`proof.rs`): a pinned FNV-1a witness over the + reference experiment (the `nvsim`/`verify.py` discipline). + +### 2.1 Why the keyed Givens rotation + +It is simultaneously **orthogonal** (energy-preserving ⇒ compliant), +**key-reversible** (the associated AP shares the session key and recovers the true +precoder ⇒ throughput preserved), and **fresh per session** (a sniffer sees a new +random rotation of the signature each session and cannot average it back ⇒ the +enrollment attack collapses; over unknown rotations the signature carries no +stable discriminative information ⇒ re-ID → chance). It is the shared-secret +precoding idea (cf. MIMOCrypt) specialized to the identity-bearing subspace. + +### 2.2 Measured behavior (SYNTHETIC / L0) + +Reference experiment at the hyper-optimized operating point (§opt), default +scene, N=16 identities, `cargo test`: + +| Metric | Shield off | Shield on | +|---|---|---| +| Passive re-ID accuracy | 100.0% | **4.7%** (chance 6.25%) | +| Link throughput ratio | 100% | **97.6%** | +| Emission energy ratio | — | **1.000000** (compliant) | + +All 35 unit/proof tests + doctest pass; the crate builds for +`wasm32-unknown-unknown` and is clippy-clean. + +### opt. Hyper-optimization (`optimize.rs`) + +The shipped shield config is the optimizer's output, not a guess, and +`ShieldConfig::default()` is asserted equal to it: + +- **Feedback resolution = 5 bits.** Throughput has an interior optimum in + feedback bits (residual falls, feedback airtime rises); the unconstrained + optimum is 3 bits (matching DySPAN-2026), and 5 is the throughput-best value in + the spec-allowed 802.11 {5,7,9} set. +- **Givens passes = 96.** The proven minimum for robust collapse — across both + attacker metrics *and* N∈{16,32} — is **48**; the shipped 96 is a free 2× + privacy margin, since the keyed rotation is derived from the shared secret and + never signaled (extra passes cost compute, not airtime). The original + hand-picked 112 was 2.3× over-provisioned. + +Net vs. the original hand-picked (112 passes / 7 bits): the optimum is strictly +better on **both** privacy (re-ID 0.047 vs 0.078) and throughput (0.976 vs 0.974), +and is now verified rather than assumed. See +`docs/research/privacy-shield/08-optimization.md`. + +### harness. Native terminal harness + TUI (`src/bin/veil.rs`) + +A custom, dependency-free binary (`veil`) ships with the crate — the in-repo, +native counterpart to the npm metaharness (ADR-289). It drives the same public +API the tests use, as an interactive ANSI dashboard plus scriptable subcommands +(`report`, `sweep`, `optimize`, `adaptive `, `proof`, `doctor`, `tui`). +Std-only (no `crossterm`/`ratatui`): the TUI is a command-driven redraw loop, so +it runs in any terminal, pipe, or CI and keeps the crate a pure leaf. It reports +only SYNTHETIC/L0 numbers and never relabels them. The wasm leaf story is +unchanged (validated with `--lib`; the bin is native-only). + +### sota. 2025–2026 evidence update (verified) + +A cited, adversarially-verified SOTA sweep +(`docs/research/privacy-shield/09-sota-update-2026.md`) refines the threat and +positioning. Load-bearing points for this ADR: + +- **Threat is broader and cheaper than §1.1 stated.** A passive, keyless, + single-antenna sniffer at ~20 m and *through walls* can identify people + (BFId, 99.5%/N=197, `MEASURED`), read **breathing** from stationary occupants + and **keystrokes/PINs** (LeakyBeam / WiKI-Eve / SThief, `MEASURED`), and — + decisively — **reconstruct full CSI from the sniffed BFI** (BFIAttack, + ≥93% single-antenna, `MEASURED`). VEIL's obfuscation must therefore degrade + *reconstructed-CSI* utility, not merely raw-BFI feature noise; because VEIL's + rotation is a **secret orthogonal** transform, the attacker has no key and no + closed-form to invert — this is now a claim to **test**, not assume. +- **VEIL's family is independently validated.** AP-side per-packet random + unitary on the LTF (LeakyBeam defense, 89.7%→~51%, `MEASURED`) and RIS + obfuscation (PrivISAC, 93%→~30%, robust to a retrained multi-location + attacker, `MEASURED`) confirm standard-permitted beamforming-surface + obfuscation works; DP-Givens quantization (`SYNTHETIC`) offers a formal ε knob. +- **Compliance precedent.** BeamDancer (IEEE TWC 2024, `MEASURED`) argues + native-beamforming obfuscation is 802.11-compliant while jamming/geofencing + are not — cite it as precedent. (Its ">96% PDR" figure was **refuted** in + verification; do not cite it.) +- **Security honesty.** Obfuscation shields have published counter-attacks + ("Defeating CSI obfuscation", SnoopFi), so VEIL's own shield security is + `CLAIMED`, not proven-secure, until it withstands learned de-obfuscation. +- **Governance gap.** No claim on 802.11bf-2025 privacy provisions survived + verification; that pillar remains an open question, not an asserted fact. + +The derived, prioritized improvement backlog lives in the SOTA-update file (§4). + +## 3. What this explicitly is NOT + +- **Not a radio driver.** No RF frontend, no transmit path, no + `wifi-densepose-hardware` coupling. VEIL cannot emit and cannot jam. +- **Not a defense against the associated AP.** That party holds the session key by + construction (threat class A3); protecting against a malicious AP is BFLD's + detection/privacy-class problem (ADR-118/141), not this shield's. +- **Not a full motion-obfuscation claim.** A fixed per-session rotation does not + hide coarse within-session motion; identity *re-ID* is the guaranteed target, + motion is partial/future work. +- **Not a real-hardware performance claim.** All defense numbers are SYNTHETIC/L0 + until a two-node capture with a boot/runtime-log witness exists (CLAUDE.md + hardware rule; roadmap P5). +- **Not RF denial or camera-grade anything.** + +## 4. Simplifications (honesty boundary) + +- The two-subspace split is an abstraction; on real radios comm and identity + information are only *approximately* separable, so the real throughput cost of + fully hiding identity may exceed the model's ~2%. DySPAN-2026's MEASURED curve + bounds it as *small* at fine resolution, not zero. +- The attacker is nearest-centroid. The collapse argument is classifier-independent + (it is about the marginalized signal), but P2/P5 must confirm a learned attacker + also collapses. +- The crate's PRNG is SplitMix64 — deterministic and WASM-safe but **not + cryptographic**; a deployment derives the rotation key from the negotiated link + secret, never from this PRNG. + +## 5. Consequences + +- RuView gains the *countermeasure* half of its RF-privacy story: BFLD detects + leakage, VEIL acts on it — a defensible, standards-anchored, gap-filling + position (see `docs/research/privacy-shield/06-market-and-buyers.md`). +- The compliance audit gives regulators/auditors a machine-checkable "not jamming" + artifact that composes with ADR-141 attestation. +- Future integration (BFLD `identity_risk` → `SensingDetector`, ADR-280 governed + actuation, firmware feedback shaping, two-node hardware measurement) is staged in + the research bundle roadmap and deliberately deferred so the model validates in + isolation first. + +## 6. Validation + +```bash +cargo test -p wifi-densepose-privshield --no-default-features +cargo build -p wifi-densepose-privshield --target wasm32-unknown-unknown +cargo clippy -p wifi-densepose-privshield --all-targets +``` diff --git a/wifi-veil/docs/adr/ADR-289-wifi-densepose-privshield-harness-via-metaharness.md b/wifi-veil/docs/adr/ADR-289-wifi-densepose-privshield-harness-via-metaharness.md new file mode 100644 index 00000000..ad8e9c92 --- /dev/null +++ b/wifi-veil/docs/adr/ADR-289-wifi-densepose-privshield-harness-via-metaharness.md @@ -0,0 +1,95 @@ +# ADR-289: `wifi-densepose-privshield-harness` — a MetaHarness for the VEIL privacy shield + +| Field | Value | +|-------|-------| +| **Status** | Proposed — implemented (P1) | +| **Date** | 2026-08-09 | +| **Parent** | ADR-288 (`wifi-densepose-privshield` / VEIL, the crate this harness assists development on) | +| **Relates to** | ADR-286 (`wifi-densepose-sar-harness`, the per-crate harness scaffold this one mirrors), ADR-285 (`harness/homecore/`, the WASM-first `@metaharness/kernel` pattern), ADR-182 (`harness/ruview/`, the first minted harness), ADR-282 (L0–L5 evidence ladder) | +| **Location** | `harness/wifi-densepose-privshield/` | + +## 0. PROOF discipline + +Every claim below about what is "real" versus "illustrative"/"SYNTHETIC" is +checked by a test in this harness's own suite (router + flywheel + install-smoke ++ guidance). The dependency-free `guidance` surface is covered by +`__tests__/guidance.test.ts`, which runs even before `npm install`. Nothing here +asserts a MEASURED defense result — the harness surfaces the VEIL crate's +SYNTHETIC/L0 numbers with that label intact. + +## 1. Context + +`wifi-densepose-privshield` (ADR-288) is the VEIL privacy shield — a new, +narrowly-scoped crate. Following the pattern ADR-286 set for +`wifi-densepose-sar`, it gets a dedicated per-crate MetaHarness rather than a +bespoke setup: the `vertical:coding` scaffold (architect/implementer/reviewer/ +test-writer, `doctor`) with `@metaharness/router`, `@metaharness/flywheel`, and +Darwin Mode wired in, plus a VEIL-specific, dependency-free `guidance` surface. + +## 2. Decision + +Land the harness at `harness/wifi-densepose-privshield/`, mirroring +`wifi-densepose-sar-harness`, with two deliberate improvements: + +1. **Dynamic dependency imports.** `bin/cli.js` imports the `@metaharness/*` + packages *inside* the commands that need them, not at module top. So + `guidance`, `--help`, and the guidance test run with **zero dependencies + installed** — useful for offline/air-gapped review and for this repo's CI + before `npm install`. Only `init`/`doctor`/`route`/`flywheel` touch the + kernel/host/router/flywheel packages. +2. **A VEIL `guidance` command.** A self-contained, source-cited, read-only + capability map (topics: `overview`, `threat`, `countermeasure`, + `compliance`, `optimization`, `experiment`), each entry carrying a summary, + repo-relative source citations, focused validation commands, and explicit + limitations — the `ruview_guidance` shape, specialized to VEIL. It labels all + defense evidence `SYNTHETIC/L0` and states plainly that guidance is + navigation, not authority. + +The standard three self-improvement/cost pieces are wired as real npm +dependencies (not stubs): + +- **`@metaharness/darwin`** (devDependency) — `npm run evolve` / `evolve:dry` + mutates the harness's own operating config, keeping only measurable gains. +- **`@metaharness/router`** — `src/router.ts` wires a real cost-optimal `Router` + (`qualityBar: 0.8`, k=1) over two model tiers, with four VEIL-shaped task axes + (threatModeling / complianceReview / optimizerTuning / docWriting). Labelled + examples are illustrative seed data (honesty note in-file). +- **`@metaharness/flywheel`** — `src/flywheel.ts` wires the real + `runFlywheelGenerations` promotion loop (propose → evaluate → gate → promote, + Ed25519-signed, independently replayable) with a SYNTHETIC proposer/evaluator + (`dataSource: 'SYNTHETIC'`, no model call), over VEIL policy levers + (`complianceReview`, `threatTriage`). + +## 3. What this explicitly is NOT + +- **Not a VEIL runtime.** The harness does not run a radio, emit RF, or jam. It + assists *development* on the crate; it cannot execute the shield on hardware. +- **Not evolving the crate.** Darwin/Flywheel mutate the harness's own policy + (agent prompts, review-checklist depth), not VEIL's Rust code. The crate's + actual hyper-optimization (ADR-288 §opt) was done directly, in the crate. +- **Not a live routing/promotion system.** The router's examples are seed data; + the flywheel's proposer/evaluator are deterministic stand-ins — both honestly + labelled in-source and in `CLAUDE.md`. +- **Not a replacement for the crate's gates.** The authoritative check for a + VEIL change remains `cargo test -p wifi-densepose-privshield`. +- **Not a re-labeller.** The harness must never present VEIL's SYNTHETIC results + as MEASURED, and never scaffold interference-based ("jamming") defenses — both + are hard rules in the harness `CLAUDE.md`. + +## 4. Consequences + +- The harness ships `guidance`/`doctor`/`init`/`route`/`flywheel`; `guidance` + and `--help` work offline (validated here via `node bin/cli.js`), the rest + after `npm install` + `npm run build` (CI). +- `.harness/manifest.json` + `manifest.sha256` are generated with real per-file + hashes at creation (unlike ADR-286's scaffold, whose manifest was historical). +- Scoped to its own name: its plugin, permissions, and (future) MCP surface only + read/assist on `wifi-densepose-privshield`. No risk to other harnesses/crates. + +## 5. Validation + +```bash +cd harness/wifi-densepose-privshield +node bin/cli.js guidance --topic overview # dependency-free +npm ci && npm run build && npm test # full suite (CI; needs registry access) +``` diff --git a/wifi-veil/docs/adr/ADR-290-veil-e2e-hardware-implementation-program.md b/wifi-veil/docs/adr/ADR-290-veil-e2e-hardware-implementation-program.md new file mode 100644 index 00000000..6ea20a9e --- /dev/null +++ b/wifi-veil/docs/adr/ADR-290-veil-e2e-hardware-implementation-program.md @@ -0,0 +1,94 @@ +# ADR-290: VEIL end-to-end hardware implementation program (multi-provider firmware) + +| Field | Value | +|-------|-------| +| **Status** | Proposed — P4 scaffolding (build-only); portable core validated on host | +| **Date** | 2026-08-09 | +| **Parent** | ADR-288 (VEIL shield), ADR-289 (harness), ADR-282 (L0–L5 evidence ladder) | +| **Location** | `firmware/privshield/` | +| **Relates to** | `firmware/esp32-csi-node/` (the CSI sensor/attacker node), ADR-280 (governed actuation), ADR-141 (attestation) | + +## 0. PROOF discipline + +The **only** artifact validated here is the portable C core +(`firmware/privshield/core/`): a host test (`make test`) checks energy +conservation, reversibility, wrong-key failure, and — pinned — that its +SplitMix64 key schedule is **byte-identical to the Rust crate's** PRNG. That is +`build`/host-level evidence, not silicon. Every per-provider adapter is a +**build-only scaffold** with `TODO(hw)` markers: `SYNTHETIC / L0`, no captured +log, no `MEASURED` claim. Nothing in this ADR asserts VEIL works on real +hardware; it asserts a *plan and a shared core* to get there (P5). + +## 1. Context + +ADR-288 shipped VEIL as a deterministic, no-radio Rust model, and the 2025–2026 +SOTA sweep (ADR-288 §sota) confirmed the mechanism's family is real and +standard-permitted. The open question left was **"does this run on real WiFi +hardware, and on which?"** — including the user asks: *can OpenWRT / open WiFi +software implement it, and can ESP32 help scramble signals?* Answering requires +committing to the platform reality rather than assuming a uniform "firmware" +target. + +## 2. Decision + +Stand up `firmware/privshield/` as a **multi-provider E2E program** around one +shared, validated core: + +1. **A portable C shield core** (`core/veil_shield.{h,c}`) — the keyed + Givens-rotation obfuscation, `no_std`-friendly C99 (no malloc/libc I/O), with + a SplitMix64 key schedule matching the Rust crate so on-air behavior is + identical everywhere and every adapter links the *same* math. Host-tested. +2. **Per-provider adapters**, each built and graded by a hardware research + agent, honest about what its stack can actually touch: + - **`openwifi/`** (open PHY/MAC on SDR/FPGA) — the highest-capability path and + the one that can host the **keyed-reversible** design end-to-end + (protector + AP-side compensation). Carries the **P5 measurement protocol** + (`MEASUREMENT.md`) that yields the first `MEASURED` result with a witness. + - **`openwrt/`** (Linux `mac80211`, mt76/ath9k…) — the commodity path. + Sounding-cadence randomization, MU-group and stream-mapping control are + feasible from the driver/hostapd; the per-packet unitary on the LTF spatial + mapping is firmware-deep on most parts. Partial. + - **`nexmon/`** (Broadcom/Cypress C firmware patches) — the commodity + C-firmware route; the read path is proven (Wi-BFI/nexmon_csi), the transmit + report-shaping path is research-grade/partial. + - **`esp32/`** (ESP-IDF) — **not** a feedback protector (the beamforming path + is a closed blob): ESP32 shapes CSI *read*, not transmitted feedback. Its + legitimate roles are a **sensing detector** (trigger the AP-side shield) and + an **RIS controller** (drive an external reconfigurable surface to scramble + the sensing direction — the honest way ESP32 "helps scramble", via an + external surface, not its own PHY). +3. **Compliance stance carried into hardware:** every control shapes the node's + own standards-conformant emission and preserves energy; the ESP32 + decoy/cover-traffic idea is documented as *legally sensitive / not + recommended* precisely because it edges toward the interference line. + +Per-provider feasibility grades live in each subdir README and the top-level +feasibility matrix; they are the answer to the "which hardware" question. + +## 3. What this explicitly is NOT + +- **Not validated firmware.** No adapter has run on silicon; there is no witness. + The scaffolds compile-*shaped*, not compile-*guaranteed* on their toolchains + (which are absent in this environment). +- **Not a claim that ESP32 can shield beamforming feedback** — it cannot; it is a + detector/RIS-controller only. +- **Not jamming, on any platform.** Compliant waveform shaping only. +- **Not a MEASURED result.** That is P5, gated on a captured log. + +## 4. Consequences + +- One validated core, four honest provider scaffolds, and a concrete P5 + measurement plan — a real path from model to silicon, with the effort/blocker + reality made explicit per platform. +- The shared core keeps every future hardware result consistent with the crate + and with each other. +- Scope stays inside `firmware/privshield/`; no other crate/firmware is touched + (the existing `esp32-csi-node` remains the sensor/attacker node). + +## 5. Validation + +```bash +cd firmware/privshield/core && make test # host: energy/reversibility/PRNG parity +# per-provider builds require their toolchains (ESP-IDF, OpenWRT SDK, Nexmon, +# Vivado) and real hardware — see each subdir's BUILD/INTEGRATION notes. +``` diff --git a/wifi-veil/docs/assets/veil-console.png b/wifi-veil/docs/assets/veil-console.png new file mode 100644 index 00000000..d4a9c8a9 Binary files /dev/null and b/wifi-veil/docs/assets/veil-console.png differ diff --git a/wifi-veil/docs/assets/veil-tui.gif b/wifi-veil/docs/assets/veil-tui.gif new file mode 100644 index 00000000..21b1783e Binary files /dev/null and b/wifi-veil/docs/assets/veil-tui.gif differ diff --git a/wifi-veil/docs/research/privacy-shield/01-sota-survey.md b/wifi-veil/docs/research/privacy-shield/01-sota-survey.md new file mode 100644 index 00000000..79a91063 --- /dev/null +++ b/wifi-veil/docs/research/privacy-shield/01-sota-survey.md @@ -0,0 +1,141 @@ +# 01 — State of the Art + +Scope: what a passive or active adversary can extract about *who* is in a space +and *what they are doing* from WiFi, the standard that broadens that surface, and +the countermeasures that try to prevent it. Claims are tagged **MEASURED** (from +a primary source, with metric), **CLAIMED** (asserted without an independent +measurement), or analytical inference (flagged). + +--- + +## 1. The attack surface: beamforming feedback (BFI) + +Since WiFi 5 (802.11ac), a client (beamformee) measures the downlink channel, +compresses the steering matrix **V** into **Givens-rotation angles φ/ψ**, and +transmits them **in cleartext** so the AP can steer beams. Anyone in monitor +mode can capture these frames for *every* client simultaneously — no network +access, and the target need carry no device. Quantization is coarse (802.11ac +angle steps of π/4…π/32 rad) yet retains rich motion and body information. + +| Work | Venue / year | Result | Label | +|---|---|---|---| +| **BFId** — identity inference from BFI | ACM CCS 2025 (KIT/KASTEL) | Re-identifies individuals from BFI alone; novel 197-person dataset. Press reports **99.5%** in a controlled study (ACM full text was not openable to confirm class count/split) | MEASURED (paper); 99.5% is CLAIMED via press | +| **LeakyBeam** — occupancy through walls | NDSS 2025 | Occupancy detection **TPR 82.7% / TNR 96.7%** at **20 m, through walls**, from plaintext BFI. Proposes a BFI-obfuscation defense | MEASURED (attack); defense overhead CLAIMED | +| **BFIAttack** — CSI reconstruction from BFI | arXiv 2026 (USF) | Reconstructs CSI from BFI, then defeats CSI defenses. ASR: device auth 95.5% / user auth 92.6% / key-gen 94.2% (single-antenna), 1.5–6 m | MEASURED | +| **BeamSense** — activity recognition from BFI | Computer Networks vol. 258, 2025 (Northeastern) | Human activity recognition **up to 99.28%** on commodity 802.11ac, no firmware mod, ~10% better than CSI | MEASURED | +| **Wi-BFI** — capture tooling | arXiv 2309.04408, 2023 | Pip-installable extraction of 802.11 BFI from commercial devices | tooling | + +**Takeaway for the defender.** BFI is the highest-leverage surface: unencrypted, +management-plane, device-free, capturable en masse with off-the-shelf tools. It +is also a *stepping stone* — BFIAttack shows BFI can reconstruct the CSI that all +older attacks assume. + +--- + +## 2. The older adjacent surface: CSI identity/gait/activity + +CSI requires special extraction (Intel 5300 / Atheros / ESP32) but is the +foundation the BFI attacks build on. Person-ID exploits **gait** as a biometric. +Representative MEASURED results (commodity WiFi, CSI amplitude): + +| System | Accuracy | N (candidates) | Note | +|---|---|---|---| +| WiWho (IPSN 2016) | 92%→80% | 2→6 | 2–3 m straight walk | +| WiFi-ID (2016) | 93%→77% | 2→6 | wavelet features | +| WiPIN (2018) | 92–100% | ≤30 | operation-free | +| Deep-WiID (2019) | 92.5–99.7% | 6→15 | GRU | +| WiNet / LWID (2020) | 98.5% / 98.8% | 40 / 50 | CNN | + +**Pattern the defender must exploit and not overstate:** accuracy is high in +small closed sets but *degrades as N grows and conditions become realistic* +(cross-day, cross-location, cross-walking-style). Chance is **1/N**; a 99% result +on N=5 is far weaker evidence than 99% on N=197. Open-world scale is largely +unproven (see *SoK: Security Evaluation of Wi-Fi CSI Biometrics*, 2025). + +--- + +## 3. The standard: IEEE 802.11bf-2025 + +IEEE Std **802.11bf-2025** (Amendment 4: *Enhancements for WLAN Sensing*) was +published **26 September 2025**. It standardizes WLAN sensing in 1–7.125 GHz and +above 45 GHz, defining sensing capability signaling, measurement/sounding +setup, feedback types, and both passive (ambient-traffic) and active +(dedicated null-packet) sensing modes. + +- **Attack-surface implication (analytical).** 802.11bf turns CSI/measurement + acquisition from proprietary hacks into open, vendor-agnostic, machine-readable + MAC signaling across heterogeneous devices — institutionalizing exactly the + measurements the BFI attacks abuse. The standard frames sensing as a feature, + not a threat. +- **The privacy gap (MEASURED from standards minutes).** A 2023 proposal for a + BFI "secure transmission mechanism" (IEEE 802.11-23/0782) was **withdrawn**; + "the group did not align on the characterization of [the] privacy problem." + The standard shipped without privacy protections, and its own analysis admits + passive eavesdroppers can extract location, respiration, heart rate, and + identity. + +--- + +## 4. Countermeasures (the defense literature) + +All operate on the defender's *own* transmissions; none are jamming. + +| Countermeasure | Venue / year | Mechanism | Effect | Label | +|---|---|---|---|---| +| **IRShield** | IEEE S&P 2022 | IRS/reconfigurable surface randomizes reflected paths | Attacker motion-detection **≤5%** | MEASURED | +| **PhyCloak** | USENIX NSDI 2016 | Full-duplex obfuscator injects Doppler/phase distortion into sensing only | **88.69%** gesture-spoof; throughput can rise (whitelist legit sensors) | MEASURED (spoof); throughput CLAIMED | +| **DP-Givens dithering** | IEEE DySPAN 2026 | Differentially-private stochastic quantization of BFI φ/ψ angles | Attacker speed-class error 19%→~73% (chance); **fine (3-bit) resolution ≈ non-private baseline throughput** | MEASURED | +| **MIMOCrypt / WiShield** | 2023 / IEEE JSAC 2024 | Secret precoding / MIMO CSI manipulation so only the intended RX decodes | Anti-tracking | CLAIMED/formal | +| **CSI Fuzzing / DP feature release** | IEEE 2024–25 | Randomized CSI features with DP budget | Formal DP guarantee | CLAIMED/formal | +| **ScatterShield** | ACM IMWUT 2025 | Backscatter tags inject controlled clutter | Defeats unauthorized sensing | MEASURED | +| **Adversarial packet perturbation** | ACM MobiCom 2024 | Small in-spec packet perturbations degrade attacker model | Symmetric defense | MEASURED | + +**The fundamental tradeoff (MEASURED, DySPAN 2026).** Perturbing precoding/ +feedback that an attacker exploits also degrades legitimate beamforming gain — +*but the cost collapses at fine feedback resolution*: + +| Randomization | Attacker error | Beamforming gain retained | +|---|---|---| +| none | 19% | 100% | +| moderate (p=0.3) | >50% | median >90% | +| maximum (p≥0.9) | ~73% (≈chance) | median ~58% | + +At **high (3-bit) feedback resolution, privacy was "nearly indistinguishable +from the non-private baseline"** in link performance. This is the empirical basis +for VEIL's design choice (compliant fine-resolution feedback shaping — see +[03-countermeasure-design.md](03-countermeasure-design.md)). + +--- + +## 5. Where VEIL sits + +The literature has two families: **external** obfuscation (IRShield/ScatterShield +— extra hardware, perturbs the channel) and **transmitter-side** feedback/precoder +shaping (DP-Givens, MIMOCrypt — no extra hardware, perturbs your own report). +VEIL is in the second family and adds the missing property the others do not all +combine: a transform that is simultaneously **energy-preserving** (provably +compliant), **key-reversible** (throughput-preserving for the legitimate link), +and **session-fresh** (defeats cross-session re-identification), unified around +the Givens-rotation primitive the report already uses. + +--- + +## Sources + +- BFId — ACM CCS 2025: https://dl.acm.org/doi/10.1145/3719027.3765062 · KIT record: https://publikationen.bibliothek.kit.edu/1000185756 +- LeakyBeam — NDSS 2025: https://www.ndss-symposium.org/ndss-paper/lend-me-your-beam-privacy-implications-of-plaintext-beamforming-feedback-in-wifi/ +- BFIAttack — arXiv 2604.04179: https://arxiv.org/html/2604.04179v1 +- BeamSense — Computer Networks 2025: https://dl.acm.org/doi/10.1016/j.comnet.2024.111020 · arXiv 2303.09687: https://arxiv.org/pdf/2303.09687 +- Wi-BFI — arXiv 2309.04408: https://arxiv.org/pdf/2309.04408 +- SoK: Security Evaluation of Wi-Fi CSI Biometrics — arXiv 2511.11381: https://arxiv.org/pdf/2511.11381 +- WiWho (IPSN 2016): https://dl.acm.org/doi/10.5555/2959355.2959359 · WiPIN — arXiv 1810.04106: https://arxiv.org/pdf/1810.04106 +- Survey on Wi-Fi Sensing for Human Identity — MDPI Electronics 2023: https://www.mdpi.com/2079-9292/12/23/4858 +- IEEE Std 802.11bf-2025: https://standards.ieee.org/ieee/802.11bf/11574/ · Overview — IEEE COMST 2024: https://ieeexplore.ieee.org/document/10547188/ · NIST: https://www.nist.gov/publications/ieee-80211bf-enabling-widespread-adoption-wi-fi-sensing +- 802.11bf privacy proposal withdrawal (802.11-23/0782), summarized: https://pascalpiron.substack.com/p/wifi-sensing-and-the-privacy-fix +- IRShield — IEEE S&P 2022 / arXiv 2112.01967: https://arxiv.org/abs/2112.01967 · https://ieeexplore.ieee.org/document/9833676/ +- PhyCloak — USENIX NSDI 2016: https://www.usenix.org/conference/nsdi16/technical-sessions/presentation/qiao +- Protecting Human Activity Signatures in Compressed 802.11 CSI Feedback — DySPAN 2026 / arXiv 2512.18529: https://arxiv.org/abs/2512.18529 +- MIMOCrypt — arXiv 2309.00250: https://arxiv.org/pdf/2309.00250 · WiShield — IEEE JSAC 2024: https://dl.acm.org/doi/abs/10.1109/JSAC.2024.3414597 +- ScatterShield — ACM IMWUT 2025: https://dl.acm.org/doi/abs/10.1145/3770653 +- Practical Adversarial Attack on WiFi Sensing — ACM MobiCom 2024: https://dx.doi.org/10.1145/3636534.3649367 +- Privacy-Preserving Wi-Fi Data Generation via DP — INFOCOM 2025: https://www.eng.auburn.edu/~szm0001/papers/INFOCOM25.pdf diff --git a/wifi-veil/docs/research/privacy-shield/02-threat-model.md b/wifi-veil/docs/research/privacy-shield/02-threat-model.md new file mode 100644 index 00000000..1729afb9 --- /dev/null +++ b/wifi-veil/docs/research/privacy-shield/02-threat-model.md @@ -0,0 +1,94 @@ +# 02 — Threat Model + +VEIL protects a physical space (a room, a ward, a boardroom, a SCIF) from +*unauthorized* WiFi-based inference of **who is present** and **what they are +doing**, without denying the space its own working WiFi. This file states the +adversary classes, exactly what VEIL defends, and — just as importantly — what +it does **not**. + +--- + +## 1. Assets + +| Asset | Why it matters | +|---|---| +| **Identity linkage** | Re-identifying a specific person across time/sessions from their RF signature (BFId-class attack) | +| **Occupancy / presence** | Whether the space is occupied, and by how many (LeakyBeam-class, through-wall) | +| **Activity / motion** | Gait, gestures, keystrokes, respiration inferred from channel dynamics (BeamSense-class) | +| **Communication utility** | The legitimate WiFi link must keep working (≥95% throughput bar) | + +--- + +## 2. Adversary classes + +| Class | Position | Capability | In VEIL scope? | +|---|---|---|---| +| **A1 — external passive sniffer** | Outside the trust boundary (adjacent room, van, hallway), monitor mode | Captures plaintext BFI/CSI for every station; runs BFId/LeakyBeam/BeamSense offline | **Primary target — yes** | +| **A2 — external active sensor** | Nearby, transmits its own probing/sounding to solicit measurable responses | Elicits sensing responses; 802.11bf "active" mode | **Partial** — cadence randomization + non-response policy help; full defense needs MAC-layer policy | +| **A3 — associated but curious AP** | Inside the link; the party VEIL shares keys with | Sees the un-rotated report by construction | **Out of scope** — this is BFLD's detection/privacy-class problem (ADR-118/141) | +| **A4 — supply-chain / firmware** | Compromised radio firmware | Can bypass any transmit-side control | Out of scope (integrity problem, not a waveform problem) | +| **A5 — physical / RF-denial** | Wants to *block* WiFi | — | Explicitly rejected: VEIL never jams | + +VEIL's design centers on **A1**, the attacker the literature demonstrates and +the one no shipping product addresses. + +--- + +## 3. What VEIL guarantees (and the evidence class) + +1. **Cross-session identity unlinkability against A1.** Because the fine-subspace + signature is rotated by a fresh secret orthogonal transform each session, an + A1 attacker cannot average captures back to a stable per-person template. + *Evidence: SYNTHETIC — re-ID collapses from 100% to ~chance in the reference + experiment (`cargo test`); real-silicon witness is future work.* +2. **Communication preservation.** The transform is key-reversible by the + legitimate receiver, and acts only on the identity-bearing fine subspace, so + link throughput stays ≥95%. *Evidence: SYNTHETIC model + MEASURED external + corroboration (DySPAN 2026: fine-resolution feedback shaping is near-free).* +3. **Compliance.** The transform is orthogonal ⇒ energy-preserving ⇒ adds no + interfering emission ⇒ not jamming. *Evidence: machine-checked energy ratio = + 1.000000 in the `compliance` module; statutory analysis in + [04-compliance-and-regulatory.md](04-compliance-and-regulatory.md).* + +--- + +## 4. What VEIL does NOT do (non-goals, stated to prevent over-claiming) + +- **It does not hide identity from the associated AP (A3).** That party holds the + session key. Protecting against a malicious AP requires detection and policy + (BFLD), not waveform shaping. +- **It is not RF denial or jamming.** It never degrades another station's link. +- **It does not, by itself, defeat within-session motion detection.** A single + session's rotation is fixed, so coarse presence/motion may still be inferable + within one capture window; sounding-cadence randomization mitigates but does + not eliminate this. Identity *re-ID* (the brief's metric) is the guaranteed + target; motion obfuscation is partial and tracked as future work. +- **It is not a camera-grade or medical-grade claim in any direction.** +- **It is not validated on hardware yet.** All quantitative defense results are + SYNTHETIC until a captured boot/runtime log exists (CLAUDE.md hardware rule). + +--- + +## 5. Trust boundary + +``` + ┌────────────────────── protected space ──────────────────────┐ + │ │ + │ [person] [person] legitimate STA ⇄ AP (VEIL) │ + │ │ │ │ shares session key │ + │ └──── RF ──────┘ │ rotates fine subspace│ + │ reflections ▼ of its own BFI │ + │ compliant, key-reversible, │ + │ energy-preserving emission │ + └───────────────────────────────────────┬──────────────────────┘ + │ plaintext BFI on air + ▼ + A1 external passive sniffer (monitor mode) + sees a freshly-rotated signature each session + → cannot build a stable per-person template + → re-identification → chance +``` + +The key never crosses the boundary to A1. The AP inside the boundary is trusted +for key-sharing (A3 out of scope). No emission crosses the boundary with intent +or effect of interfering with another station (A5 rejected). diff --git a/wifi-veil/docs/research/privacy-shield/03-countermeasure-design.md b/wifi-veil/docs/research/privacy-shield/03-countermeasure-design.md new file mode 100644 index 00000000..c15e39ef --- /dev/null +++ b/wifi-veil/docs/research/privacy-shield/03-countermeasure-design.md @@ -0,0 +1,136 @@ +# 03 — Countermeasure Design + +How VEIL prevents unauthorized sensing with compliant waveform controls, and how +the design maps to [`wifi-veil`](../../..). + +--- + +## 1. The separable-subspace principle + +A compressed beamforming report is not homogeneous. Two blocks carry different +information: + +- **Dominant beam direction (comm block).** The coarse steering the AP uses to + aim data at the client. It varies with position and traffic and carries **no** + stable identity. **Throughput rides here.** +- **Fine cross-subcarrier phase structure (fine block).** The high-order + multipath detail. It is *stable per person* across sessions and is what + re-identification exploits (BFId). **Identity leaks here.** Communication + barely uses it. + +The whole design rests on this: **identity leakage and data throughput live in +(mostly) separable subspaces.** A transform confined to the fine block can wreck +re-identification while sparing the beam the link depends on. This is consistent +with the DySPAN-2026 MEASURED result that shaping fine-resolution feedback is +nearly free in throughput. + +--- + +## 2. The four compliant waveform controls + +VEIL alters "channel sounding, phase, or beam schedules" — exactly the levers the +brief names — all within the 802.11 waveform envelope: + +| Control | What it varies | Purpose | +|---|---|---| +| **Keyed precoder rotation** (primary) | A fresh secret orthogonal transform of the *fine* subspace each session, composed from extra Givens rotations | Destroys cross-session identity linkage; energy-preserving; key-reversible | +| **Feedback quantization / dither** | Sub-step noise on reported φ/ψ angles | Adds report-level uncertainty; tunes the privacy–throughput point via `feedback_bits` | +| **Sounding-cadence randomization** | Jitter on NDP sounding intervals | Under-samples motion for an eavesdropper; charged as the throughput overhead | +| **MU-group / stream-mapping shuffle** | Which STAs are grouped, stream-to-antenna mapping | Rotates the spatial signature over time | + +All four modify the node's **own** standards-conformant frames. None adds energy +on top of another station (see [04](04-compliance-and-regulatory.md)). + +--- + +## 3. Why the keyed Givens rotation is the right primitive + +The compressed beamforming report is *already* a product of Givens rotations +(the φ/ψ angles). VEIL composes **additional keyed Givens rotations** over the +fine block. This choice gives three properties at once: + +1. **Orthogonal ⇒ energy-preserving.** A Givens rotation preserves the vector's + L2 norm exactly. Composing many still preserves it. So the emission carries + the same power it always would — **no added energy, no interference, not + jamming.** The `compliance` module checks this: energy ratio = 1.000000. +2. **Keyed & reversible ⇒ throughput-preserving.** The legitimate AP/STA shares + the per-session key, derives the identical rotation schedule, and applies the + inverse (negated angles, reversed order) to recover the true precoder. It pays + only the tiny residual from quantizing the extra angles at `feedback_bits` + resolution — negligible across the 802.11 5–9-bit range — plus the sounding + overhead. (The throughput-optimal resolution is derived in + [08-optimization.md](08-optimization.md).) +3. **Fresh per session ⇒ unlinkable.** A different rotation each session means an + A1 sniffer sees `R_e · signature` for a new random `R_e` every time. Averaging + over sessions (the natural enrollment attack) drives + `mean_e(R_e · signature) → 0` for *every* identity, so all templates collapse + toward the origin and become indistinguishable — re-identification → chance. + This is the marginalized-mutual-information argument: over unknown rotations, + the signature carries no stable discriminative information. + +This is the shared-secret precoding idea (cf. MIMOCrypt) specialized to the +identity-bearing subspace and unified around the report's native primitive. + +--- + +## 4. Detect-then-act + +Per the brief ("detect sensing activity and alter…"), VEIL need not perturb +continuously. The `SensingDetector` exposes the decision rule: when the observed +rate of sensing/NDP solicitations crosses a threshold, the control plane +(ADR-280) engages the shield. Continuous operation is also valid; gating just +saves the (already small) overhead when no sensing is present. + +--- + +## 5. Module map + +| Concept above | Crate module | Key items | +|---|---|---| +| Deterministic, WASM-safe randomness + keys | `prng` | `Rng` (SplitMix64), `fnv1a_64`, `derive_key` | +| Givens algebra, energy conservation | `linalg` | `apply_givens`, `norm`, `dist_sq` | +| SYNTHETIC two-subspace BFI model | `identity` | `SceneConfig`, `Channel`, `BfiSample` (`comm()`/`fine()`) | +| The four controls (shield) | `protector` | `ShieldConfig`, `Protector::protect`/`recover`, `SensingDetector` | +| Passive re-ID adversary | `attacker` | `NearestCentroidAttacker`, `Metric` | +| Privacy–throughput tradeoff | `throughput` | `LinkModel::throughput_ratio`, `beamforming_residual`, `feedback_airtime` | +| "Not jamming" audit | `compliance` | `ComplianceReport::audit`/`is_compliant` | +| Attacker-vs-protector head-to-head | `experiment` | `ExperimentConfig`, `run`, `ExperimentReport` | +| Config hyper-optimization | `optimize` | `hyper_optimize`, `min_givens_passes`, `pareto_frontier` | +| Byte-stable deterministic witness | `proof` | `Proof::EXPECTED_WITNESS`, `Proof::witness` | + +--- + +## 6. The privacy–throughput knobs (and which the optimizer turns) + +- **`feedback_bits`:** the only knob with a genuine throughput tradeoff — + residual falls with bits, feedback airtime rises with them, so there is an + interior optimum (3 bits unconstrained; 5 bits within the 802.11-allowed set). + Privacy is unaffected by bits (the rotation is fresh regardless). +- **`givens_passes`:** the privacy/robustness knob. More mixing lowers re-ID at + **no throughput cost** (the keyed rotation is never signaled), so it trades + only compute. The optimizer finds the minimum for robust collapse and ships a + free 2× margin. +- **`sounding_overhead`:** a flat throughput cost from cadence randomization; + trades motion-obfuscation strength against airtime (outside the re-ID metric). + +The `optimize` module turns these knobs deterministically — see +[08-optimization.md](08-optimization.md). It is what replaced the original +hand-picked config. + +The `throughput` module computes the ratio from these, so the tradeoff is +inspectable rather than asserted (`cargo test throughput`). + +--- + +## 7. Honest limitations of the model + +- The two-subspace split is an abstraction; on real hardware comm and identity + information are only *approximately* separable, so the real throughput cost of + fully hiding identity may be higher than the model's ~2%. The DySPAN-2026 + MEASURED curve is the external sanity check that it is *small* at fine + resolution, not zero. +- The nearest-centroid attacker is deliberately simple. The collapse argument is + classifier-independent (it is about the signal, not the model), but a hardware + study must confirm a strong learned attacker also collapses. +- Within-session motion is not addressed by the rotation alone (see threat + model §4). diff --git a/wifi-veil/docs/research/privacy-shield/04-compliance-and-regulatory.md b/wifi-veil/docs/research/privacy-shield/04-compliance-and-regulatory.md new file mode 100644 index 00000000..1760c557 --- /dev/null +++ b/wifi-veil/docs/research/privacy-shield/04-compliance-and-regulatory.md @@ -0,0 +1,90 @@ +# 04 — Compliance and Regulatory Line + +**Non-negotiable:** VEIL uses compliant waveform controls and **never jams.** +This file states the legal basis for that line and why every VEIL control falls +on the compliant side of it. It is engineering analysis, not legal advice; a +deployment in a given jurisdiction needs its own regulatory review. + +--- + +## 1. The statutory line (United States) + +The prohibition is on **interfering with others' transmissions**, not on how you +shape **your own** signal. + +| Authority | What it prohibits | +|---|---| +| **47 U.S.C. §333** | *Willful or malicious interference* with any licensed/authorized radio station or U.S. Government station | +| **47 U.S.C. §302a(b)** | Manufacture, import, marketing, sale, or *operation* of non-compliant devices (jammers cannot be certified — their sole purpose is interference) | +| **47 U.S.C. §301** | Requires a license/authorization to transmit; a jammer can never be authorized | +| **47 U.S.C. §501 / §503** | Criminal penalties and forfeitures; FCC cites fines up to $112,500 per violation, **no exemptions** for business/residence/vehicle | + +The distinguishing element of jamming is **intent to interfere plus effect on a +third party's link.** A device that shapes its own standards-conformant emission +— staying within transmit-power and spectral-mask limits, still type-certifiable +— is not a jammer. + +--- + +## 2. Why each VEIL control is compliant + +| Control | Compliance argument | +|---|---| +| **Keyed precoder rotation** | Orthogonal ⇒ preserves the report's energy exactly ⇒ **adds no power on top of anyone's signal.** It is still a valid precoder within the 802.11 feedback format. Machine-checked: energy ratio = 1.000000 (`compliance` module) | +| **Feedback quantization / dither** | Reports angles the standard already allows, at the standard's resolution; sub-step dither stays within the quantization envelope. No emission change beyond the node's own frame | +| **Sounding-cadence randomization** | Chooses *when* the node sends its own NDP soundings, within permitted timing. Sending fewer/jittered soundings never interferes with another station | +| **MU-group / stream-mapping shuffle** | Rearranges the node's own spatial mapping; a normal in-spec transmit choice | + +None of the four transmits *to prevent* another station from communicating; none +adds out-of-mask energy; each passes normal type certification. Contrast a +jammer, whose defining purpose is to emit energy that denies others service. + +--- + +## 3. The energy-conservation proof as a compliance artifact + +VEIL turns "not jamming" from a promise into a **checked property.** The +`compliance::ComplianceReport` audits each protection step: + +``` +input_energy = ‖report_before‖² +output_energy = ‖report_after‖² +energy_ratio = output_energy / input_energy # ≈ 1.0 for a rotation +energy_conserving = |energy_ratio − 1| ≤ 1e-2 +adds_interfering_energy = false # by construction +is_compliant = energy_conserving ∧ ¬adds_interfering_energy +``` + +A regulator, an auditor, or the runtime attestation layer (ADR-141) can read the +report and verify the shield is a waveform-shaping control, not an interference +source. On the reference experiment the measured ratio is **1.000000**. + +--- + +## 4. Jurisdictional notes + +- **EU (GDPR framing).** Covert WiFi body-sensing of vital signs is sensitive + health data and "almost certainly illegal under GDPR," but effectively + unenforceable (receivers are undetectable) — which is precisely why a + *technical* control is needed. VEIL as a transmit-side control does not itself + raise GDPR issues; it reduces the personal data an attacker can derive. +- **RF-emission rules are jurisdiction-specific.** The energy-preserving property + is the portable core of the compliance argument, but power/mask/timing limits + differ by region and band; a deployment must confirm local rules. +- **Deliberate transmit-nulling toward a *located* sniffer** (steering a spatial + null at a known passive receiver) is still the node's own emission and adds no + interference, but is more aggressive and should get explicit regulatory review + before field use. It is not part of the default VEIL profile. + +--- + +## Sources + +- 47 U.S.C. §333: https://www.law.cornell.edu/uscode/text/47/333 +- 47 U.S.C. §302a: https://www.law.cornell.edu/uscode/text/47/302a +- FCC Jammer Enforcement: https://www.fcc.gov/general/jammer-enforcement · https://www.fcc.gov/enforcement/areas/jammers +- FCC Cell/GPS Jamming guidance: https://www.fcc.gov/general/cell-phone-and-gps-jamming +- FCC 14-92 enforcement order: https://docs.fcc.gov/public/attachments/FCC-14-92A1.pdf + +*Caveat: FCC pages were cross-verified against Cornell LII; this is engineering +analysis, not legal advice.* diff --git a/wifi-veil/docs/research/privacy-shield/05-experiment-protocol.md b/wifi-veil/docs/research/privacy-shield/05-experiment-protocol.md new file mode 100644 index 00000000..625ffcf3 --- /dev/null +++ b/wifi-veil/docs/research/privacy-shield/05-experiment-protocol.md @@ -0,0 +1,113 @@ +# 05 — Experiment Protocol: Attacker vs. Protector + +This is the "start today" deliverable from the brief: **make one RuView node the +attacker and one the protector, and measure whether protection drives identity +recognition toward chance while keeping throughput above 95%.** It is realized as +a deterministic, reproducible experiment in +[`wifi-veil`](../../..). + +Because it runs on **SYNTHETIC** data (no radio is touched), its numbers describe +the model, not real hardware — reproduced by `cargo test`, and to be +re-established on silicon with a captured log before any deployment claim. + +--- + +## 1. Setup + +- **Protector node.** Emits beamforming feedback shaped by the VEIL controls + (keyed per-session fine-subspace rotation + configured feedback resolution and + sounding overhead). Models a legitimate AP/STA protecting a room. +- **Attacker node.** A passive sniffer that enrolls a template per candidate from + captured reports, then classifies fresh captures (nearest-centroid) — the + BFId-class re-identification threat. +- **Scene.** `SceneConfig` default: 64-dim report, 8 comm dims, **16 candidate + identities** (chance = 1/16 = 6.25%), per-identity stable fine-block signature + + per-session environmental nuisance. + +Two runs of the attacker are compared: **shield off** (the attacker sees raw +reports) and **shield on** (every captured report is VEIL-protected). The same +attacker faces both. + +--- + +## 2. Metrics and acceptance bar + +| Metric | Definition | Bar | +|---|---|---| +| **Re-ID accuracy, shield off** | Top-1 identity accuracy on unprotected traffic | Must be well above chance (threat is real) — bar ≥ 0.5 | +| **Re-ID accuracy, shield on** | Top-1 identity accuracy on protected traffic | Must fall into the chance band `1/N · 2 + 0.03` | +| **Throughput ratio** | Protected link capacity ÷ baseline capacity | **≥ 0.95** | +| **Compliance** | Emission energy ratio ≈ 1 and non-interfering | `is_compliant == true` | + +Overall `passed()` requires all four. + +--- + +## 3. Results (SYNTHETIC, hyper-optimized default configuration) + +Reproduce with `cargo test` (all 35 tests + doctest +pass). The default shield config is the `optimize` module's output — 96 Givens +passes at 5-bit feedback resolution (see +[08-optimization.md](08-optimization.md)). Salient values from the reference run: + +| Metric | Value | +|---|---| +| Candidate identities | 16 | +| Chance level | 6.25% | +| Chance band (acceptance) | ≤ 15.5% | +| **Re-ID accuracy, shield OFF** | **100.0%** | +| **Re-ID accuracy, shield ON** | **4.7%** | +| **Throughput ratio** | **97.60%** | +| Emission energy ratio | 1.000000 | +| Overall verdict | **PASS** | + +Reading the result: the attacker is a *perfect* re-identifier without protection +(the synthetic signatures are cleanly separable), and VEIL drives it *to the +chance floor* (4.7% sits just below the ideal 6.25%, i.e. no better than +guessing) — while the modeled link keeps 97.6% of its throughput and the +emission conserves energy exactly (compliant, not jamming). The same collapse +holds under a Cosine-metric attacker and at N=32, confirming it is a property of +the signal, not the classifier. + +--- + +## 4. Determinism and the witness + +The experiment is byte-reproducible: no OS entropy, no wall-clock, no threads. +`proof::Proof` folds the salient outputs (quantized to avoid last-bit f32 +round-off) into an FNV-1a witness pinned as `EXPECTED_WITNESS`. Any drift in the +PRNG stream, rotation schedule, throughput formula, or scene geometry changes the +witness and fails `witness_matches_pinned`. This is the same +deterministic-proof discipline as `nvsim` and the Python `verify.py`. + +--- + +## 5. Sensitivity and what to vary next + +`ExperimentConfig` exposes the levers for a fuller study: + +- **`scene.identities`** — larger N lowers the chance floor; confirm collapse + holds as candidates grow. +- **`scene.env_sigma` / `beam_amplitude`** — nuisance and comm energy; stress the + separability assumption. +- **`shield.feedback_bits`** — trace the privacy–throughput curve (the + `throughput` tests already show coarse resolution costs more). +- **`shield.givens_passes`** — mixing strength; fewer passes should degrade the + collapse gracefully. +- **Stronger attacker** — swap in a learned classifier to confirm the collapse is + signal-level, not classifier-level (the argument says it must be, but a + hardware study should verify). + +--- + +## 6. Path to a real two-node measurement + +The synthetic experiment is the design proof. The hardware path (per CLAUDE.md, +requires a captured log to claim MEASURED): + +1. Two ESP32-S3/C6 or Nexmon-capable nodes: one runs Wi-BFI capture (attacker), + one runs a VEIL-shaped feedback profile (protector). +2. Enroll and test the same BFId-style classifier on captured BFI, shield off vs. + on; log throughput via iperf across the legitimate link. +3. Success = the same shape as §3 on real captures, with the boot/runtime log as + the witness. Until then, all defense numbers remain SYNTHETIC. diff --git a/wifi-veil/docs/research/privacy-shield/06-market-and-buyers.md b/wifi-veil/docs/research/privacy-shield/06-market-and-buyers.md new file mode 100644 index 00000000..97cf1f91 --- /dev/null +++ b/wifi-veil/docs/research/privacy-shield/06-market-and-buyers.md @@ -0,0 +1,92 @@ +# 06 — Market and Buyers + +Facts are tagged **VERIFIED** (from a cited source), **CLAIMED** (asserted by a +vendor/analyst/press source), or **SPECULATIVE** (our inference). Market figures +are third-party projections, not independent measurements. + +--- + +## 1. Why now + +- **The threat is standardized and commercializing (VERIFIED/CLAIMED).** IEEE + 802.11bf was published Sep 2025; silicon (Infineon AIROC Wi-Fi 7 ACW741x, + Qualcomm Dragonwing) lists 802.11bf sensing in 2026 briefs; Origin AI's + embedded-sensing program targets late-2026 deployment; Plume/Cognitive Systems + WiFi Motion is the largest deployed sensing footprint today. +- **The standards body declined to fix privacy (VERIFIED).** The BFI + "secure transmission mechanism" proposal (802.11-23/0782) was **withdrawn**; + 802.11bf shipped with no privacy protections. This is the strongest demand + signal — the gap is structural and acknowledged. +- **No targeted anti-sensing product ships (VERIFIED by absence).** Every + countermeasure (IRShield, PhyCloak, MIMOCrypt, DP-Givens, ScatterShield) is + research-stage. The claim "no obvious shipping product protects rooms from this + inference" **holds** as of 2026, with one caveat below. + +--- + +## 2. First buyers, ranked by procurement readiness + +| Segment | Driver | Readiness | +|---|---|---| +| **Defence / government** | ICD 705 / DoD EMSEC already mandate RF attenuation in classified spaces; budgets and mandates exist | **Strongest beachhead (VERIFIED)** — but today they buy broadband shielding, not a sensing-specific control | +| **Corporate boardrooms / counter-espionage** | TSCM firms (Bastille, Murray Associates) now include WiFi audits and rogue-AP detection; CSI keystroke/gesture inference makes a boardroom shield a natural extension | **VERIFIED demand, EMERGING WiFi-specific** | +| **Hospitals** | RF-derived behavioral/vital data is HIPAA PHI; exam rooms, psychiatric units where inference is unwanted | **VERIFIED regulatory hook** — but the hook drives privacy-preserving *sensing* more than a *shield* | +| **Hotels** | Documented guest backlash against in-room sensors; privacy as differentiation | **SPECULATIVE** — narrative-led, not procurement-led today | +| **Router / AP manufacturers** | Ship opt-out/obfuscation as a firmware feature anticipating regulation | **SPECULATIVE** — no vendor has announced this | + +--- + +## 3. Competitive landscape + +- **Direct competitors:** none shipping. All targeted anti-sensing is academic. +- **The real substitute (VERIFIED):** broadband RF shielding — SCIF/TEMPEST + window film, paint, panels (Signals Defense SD2500: >40 dB, 30 MHz–6 GHz, ICD + 705 / ASTM F3057-14). It defeats WiFi sensing as a side effect but is **blunt**: + it kills *all* RF and cannot coexist with wanted WiFi. +- **TSCM services (VERIFIED):** detect, don't prevent. + +**VEIL's differentiation** is exactly what the substitute lacks: **selective and +coexisting** — it removes identity/activity leakage while keeping the room's WiFi +working at ≥95% throughput, with a machine-checkable compliance artifact. + +--- + +## 4. Market size (third-party projections, cite with care) + +- **CLAIMED:** ABI Research — North American WiFi-sensing-compatible CPE install + base to **112M by 2030 (51.6% CAGR)**. +- **CLAIMED:** Global WiFi sensing market ~$402M (2024) → ~$2.13B (2033) + (MarketIntelo). + +Implication: a shield must **coexist** with a large installed sensing base, not +assume RF denial — reinforcing the selective-coexistence positioning. + +--- + +## 5. Where VEIL fits RuView's positioning + +VEIL pairs with BFLD to make RuView the *both-sides* RF-perception platform: +BFLD/AETHER do sensing responsibly and detect leakage; VEIL is the customer- +facing **privacy firewall** that protects a room from *others'* sensing. That is a +defensible, standards-anchored, gap-filling story: the standards body left the +door open, the threat is shipping, and no one else sells the selective lock. + +--- + +## Sources + +- IEEE 802.11bf privacy-proposal withdrawal (802.11-23/0782), summarized: https://pascalpiron.substack.com/p/wifi-sensing-and-the-privacy-fix +- NIST 802.11bf: https://www.nist.gov/publications/ieee-80211bf-enabling-widespread-adoption-wi-fi-sensing +- IRShield: https://arxiv.org/abs/2112.01967 · MIMOCrypt: https://arxiv.org/pdf/2309.00250 · ScatterShield: https://dl.acm.org/doi/abs/10.1145/3770653 · WiShield JSAC 2024: https://dl.acm.org/doi/abs/10.1109/JSAC.2024.3414597 +- Signals Defense TEMPEST/SCIF film: https://signalsdefense.com/tempest-and-scif-design/ · https://signalsdefense.com/shielding-films/ +- National Shielding SCIF/ICD-705: https://www.national-shielding.com/pages/scif-icd-705-secure-facility-shielding +- Bastille TSCM: https://bastille.net/centers-of-excellence/tscm/ · IntellSIG TSCM overview: https://www.intellsig.com/2025/07/20/modern-eavesdropping-threats-a-tscm-overview/ +- Origin AI program: https://www.prnewswire.com/news-releases/origin-ai-launches-compatible-with-origin-program-to-meet-industry-demand-for-scalable-wifi-sensing-and-accelerate-integration-across-global-soc-platforms-302650963.html +- MIT Tech Review, WiFi sensing: https://www.technologyreview.com/2024/02/27/1088154/wifi-sensing-tracking-movements/ +- ABI Research 112M forecast: https://www.abiresearch.com/press/north-american-wi-fi-sensing-cpe-installations-to-surge-to-112-million-by-2030-as-the-technologys-maturing-unleashes-new-business-and-service-models +- MarketIntelo WiFi sensing market: https://marketintelo.com/report/wi-fi-sensing-market +- HIPAA/PHI RF-sensing context (PMC): https://pmc.ncbi.nlm.nih.gov/articles/PMC11939480/ + +*Caveat: market figures are analyst/vendor projections; the "no shipping product" +finding reflects absence of evidence in these searches and should be confirmed +with a patent/vendor scan before anchoring a go-to-market claim.* diff --git a/wifi-veil/docs/research/privacy-shield/07-implementation-and-roadmap.md b/wifi-veil/docs/research/privacy-shield/07-implementation-and-roadmap.md new file mode 100644 index 00000000..c24c6553 --- /dev/null +++ b/wifi-veil/docs/research/privacy-shield/07-implementation-and-roadmap.md @@ -0,0 +1,117 @@ +# 07 — Implementation and Roadmap + +--- + +## 1. What ships in this bundle + +- **Reference crate** `wifi-veil` (VEIL): a + deterministic, dependency-free, WASM-ready pure-compute leaf implementing the + full attacker-vs-protector experiment, the four compliant controls, the + throughput model, the compliance audit, the `optimize` hyper-optimizer, and a + byte-stable proof. 35 tests + doctest pass; builds for + `wasm32-unknown-unknown`; clippy-clean. +- **This research bundle** (`docs/research/privacy-shield/`). +- **[ADR-288](../../adr/ADR-288-veil-privacy-shield-compliant-waveform.md)** — the + formal decision record. +- **npm metaharness** `harness/` + ([ADR-289](../../adr/ADR-289-wifi-densepose-privshield-harness-via-metaharness.md)) + — a per-crate contributor harness (architect/implementer/reviewer/test-writer, + router, flywheel) with a dependency-free `guidance` surface that serves this + bundle's capability map. `npx wifi-veil-harness guidance + --topic optimization`. + +The crate is intentionally a **leaf with no internal RuView dependencies** +(mirrors `wifi-densepose-aether`), so it can be reasoned about, fuzzed, and +ported independently, and so it can never accidentally acquire a path to a radio. + +--- + +## 2. Reuse map (how VEIL composes with existing RuView) + +| Existing subsystem | Relationship | +|---|---| +| **BFLD** (ADR-118/120/121, `wifi-densepose-bfld`) | Detection layer. Its `identity_risk_score` is the natural trigger for VEIL's `SensingDetector` — detect leakage, then shield | +| **Privacy control plane** (ADR-141) | VEIL protection steps emit `ComplianceReport`s that fit the runtime-attestation model (which mode, which actions, which fields) | +| **Active sensing / governed actuation** (ADR-280) | VEIL is a defensive `SensingAction`: a governed, privacy-ceiling-bounded emission-shaping action the control plane can schedule | +| **Givens/beamforming primitives** | VEIL reuses the report's native Givens-rotation structure rather than inventing a new transform | +| **Deterministic proof discipline** (`nvsim`, `archive/v1/verify.py`) | VEIL's `proof` module follows the same pinned-witness pattern | + +--- + +## 3. Phased rollout + +| Phase | Deliverable | Evidence class | +|---|---|---| +| **P1 — reference model (this PR)** | Crate + experiment + docs + ADR | SYNTHETIC (cargo test) | +| **P2 — sensitivity study** | Sweep N, noise, resolution, mixing; add a learned attacker to confirm signal-level collapse | SYNTHETIC | +| **P3 — BFLD integration** | Wire `identity_risk` → `SensingDetector` → shield engage; emit attestation | SYNTHETIC + integration tests | +| **P4 — firmware feedback shaping** | Implement keyed fine-subspace rotation + cadence randomization in the **beamforming-feedback / spatial-mapping path** — see §3.1 for the (non-trivial) platform reality | build + hardware | +| **P5 — two-node hardware measurement** | Attacker (Wi-BFI capture) vs. VEIL protector on real silicon; iperf throughput; captured log | **MEASURED** (with witness) | +| **P6 — deployment profiles** | Per-segment profiles (SCIF, boardroom, ward) with regulatory review | operational | + +No defense claim graduates from SYNTHETIC to MEASURED without a captured +boot/runtime log (CLAUDE.md hardware rule). + +### 3.1 Does this need custom WiFi firmware? (yes — and ESP32 is the wrong chip for the protector) + +VEIL shapes the **compressed beamforming report** (the Givens φ/ψ angles) or the +LTF **spatial mapping** as it is transmitted — machinery that lives *below* the +driver, inside the chip's PHY/MAC firmware. It is **not** reachable from user +space, so a real deployment is a firmware/driver change, not an app. + +- **ESP32 — not viable as the protector.** Its WiFi lower layers are a closed + Espressif blob. ESP-IDF exposes CSI *read* (`esp_wifi_set_csi`) — which is why + `firmware/esp32-csi-node/` makes a great **attacker/sensor** node — but it does + **not** let you rewrite how the chip builds/sends beamforming feedback. ESP32 + is the *attacker* in a testbed, not the shield. +- **Realistic protector platforms:** **openwifi** (open 802.11 on SDR/FPGA — + full PHY/MAC control incl. the AP-side compensation; the honest end-to-end + route; Verilog + a C driver); **Nexmon** (C firmware *patches* for + Broadcom/Cypress, e.g. RPi BCM43455 — the commodity path, and the same + framework the BFI *attack* tools already use); open drivers (**ath9k/mt76**) + for partial control; or **vendor firmware** for a production feature. +- **Two firmware variants:** the **keyed-reversible** version (VEIL's ~98% + throughput) needs changes on **both** ends plus key agreement (cf. the + LeakyBeam AP-side `Q_obf` is *client-transparent* — only the AP changes — which + is a deployment advantage worth adopting, §09 backlog item 3); the + **emitter-only DP dither** version needs only the reporting device but pays the + full throughput cost. + +The current crate is deliberately a std-only, no-radio leaf and implements none +of this; P4 is where it meets silicon. + +--- + +## 4. Open problems (tracked honestly) + +1. **Real-hardware separability.** Comm and identity information are only + *approximately* separable on real radios; the true throughput cost of full + identity hiding may exceed the model's ~2%. P2/P5 must bound it. +2. **Within-session motion leakage.** A fixed per-session rotation does not + obfuscate coarse motion within one capture window. Needs stronger cadence + randomization or amplitude shaping; currently a stated non-goal for the re-ID + metric. +3. **Active adversary (A2).** An attacker that transmits its own soundings is + only partially addressed by cadence control; a MAC-layer non-response policy + is needed. +4. **Key management.** The per-session rotation key must be derived from the + negotiated link secret; VEIL's PRNG is explicitly *not* cryptographic and must + not be used for real key material. +5. **Regulatory review per jurisdiction.** The energy-conservation argument is + portable, but power/mask/timing limits and any transmit-nulling profile need + local review before field use. + +--- + +## 5. Validation commands + +```bash +# Reference experiment + all unit/proof/doc tests +cargo test + +# WASM portability (leaf builds with no radio path) +cargo build --target wasm32-unknown-unknown + +# Lints +cargo clippy --all-targets +``` diff --git a/wifi-veil/docs/research/privacy-shield/08-optimization.md b/wifi-veil/docs/research/privacy-shield/08-optimization.md new file mode 100644 index 00000000..b1a3f7b0 --- /dev/null +++ b/wifi-veil/docs/research/privacy-shield/08-optimization.md @@ -0,0 +1,142 @@ +# 08 — Hyper-Optimization + +The reference crate first shipped a **hand-picked** shield config (112 Givens +passes, 7-bit feedback). This file records how the `optimize` module replaces +that guess with a *derived*, robustness-verified optimum, and what it found. All +numbers are **SYNTHETIC / L0**, reproduced by +`cargo test`. + +--- + +## 1. What is being optimized, and against what + +Two knobs, two objectives, one hard constraint: + +| Knob | Costs | Does it trade against privacy? | +|---|---|---| +| `feedback_bits` (angle resolution) | Throughput: **residual** falls with bits, **feedback airtime** rises with bits | No — the keyed rotation is applied regardless of resolution | +| `givens_passes` (rotation mixing) | Compute only | Yes — more mixing ⇒ lower re-ID | + +**Constraint:** re-ID must collapse into the chance band `1/N · 2 + 0.03` — and +it must do so *robustly*: for **both** attacker metrics (Euclidean and Cosine) +and **both** identity counts (N = 16 and N = 32, the harder, lower-chance case). + +The key structural fact: **rotation mixing is throughput-free.** The per-session +rotation is derived from the shared link secret on both ends (like MIMOCrypt) — +it is never transmitted — so extra Givens passes cost compute, not airtime. That +means privacy margin is essentially free; the only throughput tradeoff lives in +`feedback_bits`. + +--- + +## 2. Throughput is a 1-D problem with an interior optimum + +Because the residual falls with bits while feedback airtime rises, throughput +has a genuine interior optimum in `feedback_bits` (`LinkModel`, default SNR 20 dB, +`feedback_overhead_per_bit = 0.0008`): + +| bits | throughput ratio | +|---|---| +| 1 | 0.9681 | +| 2 | 0.9757 | +| **3** | **0.9769** ← unconstrained optimum | +| 4 | 0.9766 | +| **5** | **0.9760** ← shipped (spec-allowed) | +| 7 | 0.9744 (the old hand-picked value) | +| 9 | 0.9728 | +| 12 | 0.9704 | + +The unconstrained optimum is **3 bits** — which coincides with the DySPAN-2026 +MEASURED finding that ~3-bit feedback is the privacy–utility sweet spot, because +the receiver compensates the keyed rotation and extra bits mostly buy airtime. +802.11 compressed beamforming quantizes ψ/φ to roughly 5–9 bits, so the shipped +shield uses the throughput-best **spec-allowed** value, **5 bits** (0.9760), +rather than the out-of-spec 3-bit optimum. Either way it beats the old 7-bit +choice. + +--- + +## 3. Mixing: the minimum robust budget, and a free margin + +Worst-case shield-on re-ID vs. `givens_passes` (bits = 5; worst over Euclidean +and Cosine): + +| passes | re-ID @ N=16 | re-ID @ N=32 | robust collapse? | +|---|---|---|---| +| 16 | 0.75 | 0.62 | no | +| 24 | 0.50 | 0.35 | no | +| 32 | 0.20 | 0.14 | no (N=32 band is 0.0925) | +| **48** | 0.12 | 0.057 | **yes** ← proven minimum | +| 64 | 0.078 | 0.044 | yes | +| **96** | **0.047** | **0.018** | **yes** ← shipped (2× margin) | +| 112 | 0.078 | 0.042 | yes (the old default — no better than 96) | + +The proven minimum for robust collapse is **48 passes** — the hand-picked 112 was +**2.3× over-provisioned**. Since mixing is throughput-free, the shield ships +**96 passes** (`PRIVACY_MARGIN_FACTOR = 2` × 48, rounded up to a candidate): it +drives re-ID *below chance* at N=16 (0.047 < 0.0625) at zero throughput cost, and +is still cheaper compute than the original 112. + +--- + +## 4. The adopted config, and why it beats the original + +| | Old (hand-picked) | Hyper-optimized (shipped) | +|---|---|---| +| Givens passes | 112 | **96** (from proven-min 48 × 2) | +| Feedback bits | 7 | **5** (spec-optimal) | +| Shield-on re-ID (N=16) | 0.078 | **0.047** | +| Throughput ratio | 0.9744 | **0.9760** | +| Robust across metrics & N | not checked | **verified** | + +The optimum is **strictly better on privacy and throughput at once**, and is now +*verified* rather than assumed. `ShieldConfig::default()` is exactly the +optimizer's output; the test `optimize::shipped_default_equals_optimizer_output` +fails if they ever drift apart. + +--- + +## 5. The Pareto frontier (and an honest note) + +`optimize::pareto_frontier` enumerates non-dominated (worst-case re-ID, +throughput) points over a pass × bits grid. In this model the frontier +**collapses toward the max-mixing, 5-bit point**, because mixing is +throughput-free — so beyond the throughput knob (bits) there is no privacy– +throughput tradeoff to trace. That degeneracy is itself the finding: *the only +thing privacy costs here is feedback resolution, and even that is cheap.* On real +hardware, where comm/identity subspaces are only approximately separable and +where more aggressive mixing may touch the data-carrying beam, this frontier is +expected to open up — a hardware study (roadmap P5) will re-measure it. + +--- + +## 6. Per-deployment adaptivity + +The optimum is not one number — `optimize` derives it per deployment: + +- **SNR → feedback resolution.** `optimal_bits_across_snr` shows the + *unconstrained* throughput-optimal resolution shifting with SNR: **4 bits at + 5–10 dB, 3 bits at 20–40 dB** (low SNR values fine resolution more because + the Shannon capacity is near-linear there, so the residual costs more). Within + the spec-allowed {5,7,9} set the choice is 5 bits across this whole range — + the residual is already negligible at 5 bits — which is why the shipped shield + is SNR-stable. +- **Identity count → mixing.** `adaptive_shield(base, n)` derives the config for + a room with `n` expected occupants. A notable finding: in this model the + collapse budget is **N-independent** (min 48 passes collapses N∈{8,64} + alike), because a well-mixed Haar-like rotation destroys per-identity + structure regardless of how many identities there are — the budget is set by + the fine-subspace dimension, not the candidate count. So `adaptive_shield` + returns the same 96/5 across that range: the default is robust, not a point + tuning. + +Both are surfaced through the harness `guidance --topic optimization`. + +## 7. Robustness caveats (unchanged from the threat model) + +- The collapse is verified against two classifiers and two N; a learned + attacker on real captures must still be checked (P2/P5). +- `feedback_bits` affects only throughput in this model, not re-ID; on hardware, + coarse quantization also adds obfuscation, which would *help* privacy — the + model conservatively ignores that. +- All optimization results are SYNTHETIC until a hardware witness exists. diff --git a/wifi-veil/docs/research/privacy-shield/09-sota-update-2026.md b/wifi-veil/docs/research/privacy-shield/09-sota-update-2026.md new file mode 100644 index 00000000..f10503cf --- /dev/null +++ b/wifi-veil/docs/research/privacy-shield/09-sota-update-2026.md @@ -0,0 +1,151 @@ +# 09 — SOTA Update (2025–2026) and VEIL Improvement Backlog + +Source: a fan-out deep-research run (5 angles → 20 primary sources → 93 claims → +top 25 adversarially verified with 3-vote panels → 24 confirmed, 1 refuted). +Each finding carries its **evidence class** (`MEASURED` with metric / `CLAIMED` +/ `SYNTHETIC` / `STANDARDS-MINUTE`) and a primary URL. This file records what +changed in the field and the concrete backlog it implies for VEIL (ADR-288/289). +Nothing here upgrades VEIL's own numbers to `MEASURED` — that still requires a +captured hardware log (CLAUDE.md). + +--- + +## 1. The threat surface got worse (and cheaper) + +| Finding | Evidence | Source | +|---|---|---| +| **BFId** — first *identity* inference from plaintext BFI: **99.5% over 197 people**, perspective/gait-independent; BFI carries ~740 features vs 212 for CSI, so it *beats* CSI for identity; one eavesdropper captures BFI from all clients | `MEASURED` (top-1, N=197, CCS 2025) | [dl.acm.org/10.1145/3719027.3765062](https://dl.acm.org/doi/10.1145/3719027.3765062) | +| **LeakyBeam** — through-wall occupancy at **20 m** (TPR 82.7% / TNR 96.7%) **and breathing/vital-sign** leakage from *stationary* occupants; single antenna, Wireshark, no keys | `MEASURED` (NDSS 2025) | [ndss 2025-5](https://www.ndss-symposium.org/wp-content/uploads/2025-5-paper.pdf) | +| **WiKI-Eve / SThief** — keystroke & PIN/password theft from BFI (88.9% per-keystroke; 65.8% top-10 app passwords; POS keypads) with no device compromise | `MEASURED` (CCS 2023 / IEEE) | [WiKI-Eve](https://dl.acm.org/doi/10.1145/3576915.3623088) · [SThief](https://ieeexplore.ieee.org/document/10621321/) | +| **BFIAttack** — **reconstructs full CSI from sniffed BFI**: closed-form ≥93% (single-antenna, 1 attempt); MLE with physics/standard constraints 73% (multi-antenna, ≤5 attempts). Collapses the BFI-vs-CSI distinction | `MEASURED` (arXiv Apr 2026) | [arxiv 2604.04179](https://arxiv.org/html/2604.04179v1) | +| **BeamSense** — BFI sensing is standards-compliant, needs no firmware mod, ~10% higher activity accuracy than CSI | `MEASURED` | [BFISense/BeamSense](https://www.researchgate.net/publication/402468114_BFISense_Using_Beamforming_Feedback_Information_for_Wi-Fi_Sensing) | + +**Implication:** the attacker is a *passive, keyless, single commodity antenna at +~20 m, through walls*, that can (a) identify people, (b) read vitals and +keystrokes, and (c) **reconstruct CSI from the BFI itself.** VEIL's threat model +must treat all four as baseline. + +--- + +## 2. Defenses — the field validates VEIL's family and adds stronger primitives + +| Defense | Mechanism | Effect | Evidence | Source | +|---|---|---|---|---| +| **LeakyBeam defense** | AP-side **per-packet random unitary** `Q_obf` on the LTF via the 802.11 spatial-mapping mechanism (standard says "not restricted"); AP recovers `V = Q_obf · V_obf`; **clients unmodified** | attack **89.7% → ~51%** across 8 APs (~1.6M packets/49 h) | `MEASURED` | [ndss 2025-5](https://www.ndss-symposium.org/wp-content/uploads/2025-5-paper.pdf) | +| **PrivISAC (RIS)** | Paired per-row RIS vectors, one randomly active per slot; preserves comm-direction response, corrupts sensing direction; time-domain mask/demask for the authorized RX | **93% → ~30%**, and **29% vs. retrained 5-location adaptive attacker** | `MEASURED` (64-element FPGA RIS, Intel 5300, ~2,700 OTA samples) | [arxiv 2601.04488](https://arxiv.org/html/2601.04488) | +| **DP-Givens** | ε-DP stochastic quantizer on the Givens rotation/phase angles; closed-form angular sensitivity → principled ε budget; preserves 802.11 feedback structure | frontier: attacker error 19% → ~73%; beamforming gain 0.97 → 0.89 median (0.54 at full) | `SYNTHETIC` (Monte-Carlo) | [arxiv 2512.18529](https://arxiv.org/pdf/2512.18529) | +| **Adaptive-DP (CSI spectrogram)** | Importance-weighted (non-uniform) DP budget across the time-frequency plane | better privacy-utility than flat noise at equal ε∈[0.5,2]; cuts identity + membership inference | `CLAIMED` (unrefereed) | [arxiv 2512.20323](https://arxiv.org/abs/2512.20323) | +| **BeamDancer** | Randomized native-beamforming obfuscation | defeats supervised + unsupervised localization and micro-Doppler; **compliant, not jamming** | `MEASURED` (IEEE TWC 2024) — **do NOT cite its ">96% PDR" (refuted here)** | [ieee 10739908](https://ieeexplore.ieee.org/document/10739908/) | +| **TX-side CSI obfuscation (+ counter-attacks)** | Filter the whole frame incl. LTS; DNN de-obfuscation for authorized sensing | **security contested**: "Defeating CSI obfuscation" + SnoopFi FIA/CRA recover the signal | `CLAIMED` design + published rebuttal | [C&S 2025](https://www.sciencedirect.com/science/article/abs/pii/S0167404825002834) | + +**Where VEIL sits:** VEIL's keyed Givens rotation is the *same family* as the +LeakyBeam per-packet unitary and the DP-Givens knob — and unlike additive/DP +dither, VEIL's transform is **secret and orthogonal**, which is exactly the +property that should resist the BFIAttack closed-form/MLE inversion (the attacker +has no key, so there is no closed-form to invert to). That is now the decisive +claim to *test*, not assume. + +--- + +## 3. Compliance / legal line + +- **BeamDancer (IEEE TWC 2024)** is the peer-reviewed precedent for VEIL's + stance: **jamming and geofencing are non-compliant / non-scalable; exploiting + the standard beamforming mechanism stays 802.11-compliant** (validated without + disabling firmware). Cite it as the compliance precedent — but **not** its + refuted throughput figure. +- **Governance gap (unfilled):** *no* claim on the 802.11bf-2025 standard's + privacy provisions, the withdrawn secure-LTF-from-11az proposal, or + GDPR/HIPAA/EMSEC/ICD-705 boundaries **survived 3-vote verification** in this + run. Blog/secondary sources assert a withdrawn privacy proposal, but it needs + primary WG-minute/draft sourcing before VEIL relies on it. Tracked as an open + question. + +--- + +## 4. VEIL improvement backlog (derived, prioritized) + +Priority = (verified severity) × (fit to VEIL). `[code]` = crate change, +`[docs]` = documentation, `[hw]` = hardware path. + +1. **`[code]` ✅ implemented — Reconstruction-aware attacker (decisive).** A + BFIAttack-style adversary (`attacker::ReconstructionAttacker`, + `AttackerKind::Reconstruction`) recovers the direction of the CSI consistent + with the *captured* report and classifies it; the test + `reconstruction_attacker_collapses` confirms the keyed *orthogonal secret* + rotation leaves it at chance (no key → it only ever recovers the rotated + direction) while it still wins on unprotected traffic. *(BFIAttack, MEASURED)* +2. **`[code]` ✅ implemented — Adaptive, multi-capture attacker.** + `attacker::AdaptivePoolingAttacker` (`AttackerKind::AdaptivePooling`) pools all + captures per identity and whitens by per-dimension std before matching (the + PrivISAC adaptive/retraining adversary); `adaptive_pooling_attacker_collapses` + confirms collapse still holds. *(PrivISAC, MEASURED)* +3. **`[code]` ✅ implemented — Per-packet random-unitary mode.** + `protector::ObfMode::PerPacketUnitary` applies a fresh unitary per packet, + AP-side and **client-transparent** (LeakyBeam family; 802.11 spatial mapping + "not restricted" as the compliance basis); + `per_packet_unitary_mode_collapses_and_is_compliant` verifies it. *(LeakyBeam + defense, MEASURED)* +4. **`[code]` ✅ implemented — DP-Givens ε knob.** `ShieldConfig.dp_epsilon` adds + an ε-scaled angular dither, renormalized to preserve emission energy (still + not jamming); `throughput::dp_residual` makes ε a real privacy↔throughput knob + (`dp_epsilon_lowers_throughput_as_it_tightens`), and the combined + rotation+DP still collapses and stays compliant. Outputs `SYNTHETIC`. + *(DP-Givens, SYNTHETIC)* + +> Items 1–4 landed with the reference **witness unchanged** +> (`0x350d…f448`) — the new controls/attackers are opt-in fields; the shipped +> default config and its numbers are byte-identical. +5. **`[code/docs]` Privacy–throughput *frontier*, not binary claims.** Report + attacker-error-vs-privacy and gain/PDR-vs-privacy curves (we already have the + throughput-vs-bits and reid-vs-passes curves; add the joined frontier). +6. **`[docs]` Threat-model upgrade.** Elevate identity/gait re-ID, through-wall + vitals, keystroke/PIN, and **BFI→CSI reconstruction** to primary threats in + ADR-288 §threat and bundle 02; add the passive/keyless/20 m/through-wall + adversary as the default. *(done in this update)* +7. **`[docs]` Security honesty.** State that VEIL's shield security is `CLAIMED` + until it survives published de-obfuscation attacks (SnoopFi / "Defeating CSI + obfuscation"); add learned de-obfuscation to the attacker roadmap. +8. **`[code/docs]` Evaluation battery.** Adopt BeamDancer's three-attacker matrix + (supervised localizer + unsupervised clusterer + model-based Doppler) as a + minimum test set, plus identity + membership-inference metrics. +9. **`[hw]` Hardware-validation path.** Mirror the RIS/8-AP OTA testbeds for P5. + **Correction:** ESP32 is an *attacker/sensor* node only (its WiFi lower layer + is a closed blob exposing CSI *read*, not TX-feedback shaping); the protector + needs **openwifi (SDR/FPGA), Nexmon (C firmware patches), or vendor + firmware** + key agreement for the keyed-reversible version. See roadmap §P4. +10. **`[docs]` Governance sourcing.** Fill the 802.11bf privacy-provision gap + with primary WG minutes/draft; scope FCC Part 15, GDPR/HIPAA (inferred + biometric/health), and EMSEC/ICD-705 deployability. + +--- + +## 5. Open questions the evidence did not close + +- Does VEIL's obfuscation degrade **CSI *reconstructed* from BFI** (BFIAttack), + or only raise raw-BFI feature noise? *(the decisive effectiveness question)* +- What is VEIL's **own MEASURED** privacy–throughput frontier on silicon (the + only measured PDR number in the field was refuted; the DP curves are + simulation-only)? +- Does 802.11bf-2025 contain any privacy provision or a withdrawn one, and what + are the concrete FCC/GDPR/HIPAA/ICD-705 deployment boundaries? + +--- + +## Sources (primary, verified in this run) + +- BFId — CCS 2025: https://dl.acm.org/doi/10.1145/3719027.3765062 +- LeakyBeam (attack + per-packet-unitary defense) — NDSS 2025: https://www.ndss-symposium.org/wp-content/uploads/2025-5-paper.pdf +- BFIAttack (BFI→CSI reconstruction) — arXiv 2026: https://arxiv.org/html/2604.04179v1 +- WiKI-Eve — CCS 2023: https://dl.acm.org/doi/10.1145/3576915.3623088 +- SThief — IEEE: https://ieeexplore.ieee.org/document/10621321/ +- BeamSense/BFISense: https://www.researchgate.net/publication/402468114_BFISense_Using_Beamforming_Feedback_Information_for_Wi-Fi_Sensing +- PrivISAC (RIS) — arXiv 2026: https://arxiv.org/html/2601.04488 +- DP-Givens — arXiv 2512.18529: https://arxiv.org/pdf/2512.18529 +- Adaptive-DP spectrogram — arXiv 2512.20323: https://arxiv.org/abs/2512.20323 +- BeamDancer — IEEE TWC 2024: https://ieeexplore.ieee.org/document/10739908/ +- TX-side CSI obfuscation — Computers & Security 2025: https://www.sciencedirect.com/science/article/abs/pii/S0167404825002834 + +*Refuted (do not cite): BeamDancer ">96% PDR in LoS" (verification 1–2). Two DP +mechanisms are SYNTHETIC/CLAIMED, not silicon. Governance/standard pillar +unverified in this run.* diff --git a/wifi-veil/docs/research/privacy-shield/README.md b/wifi-veil/docs/research/privacy-shield/README.md new file mode 100644 index 00000000..b42e2416 --- /dev/null +++ b/wifi-veil/docs/research/privacy-shield/README.md @@ -0,0 +1,102 @@ +# Privacy Shield Research Bundle — WiFi Veil + +**WiFi Veil** (codename **VEIL** — Verifiable Emission-shaping for +Identity-Leakage prevention) is a privacy *firewall* for WiFi sensing: it +prevents unauthorized identity and +activity inference from a room's WiFi while preserving normal communications. It +is the **countermeasure** counterpart to [BFLD](../BFLD/) — where BFLD *detects* +when beamforming feedback becomes identifying, WiFi Veil *acts* by shaping the node's +own compliant waveform (channel sounding, precoder phase, beam/feedback +schedules) so identity and activity inference fail, while a legitimate receiver +sees an essentially unchanged link. + +**This must use compliant waveform controls, never jamming.** Every technique +here operates on the defender's *own* legitimately transmitted, standards- +conformant frames. Nothing adds energy to interfere with another station's +transmission (the statutory definition of jamming, 47 U.S.C. §333/§302a). + +--- + +## Table of contents + +| File | Purpose | +|------|---------| +| [01-sota-survey.md](01-sota-survey.md) | State of the art: identity/activity inference attacks (BFI + CSI), the IEEE 802.11bf-2025 standard, and privacy-preserving countermeasures | +| [02-threat-model.md](02-threat-model.md) | Adversary classes, what WiFi Veil defends and what it explicitly does not, trust boundary | +| [03-countermeasure-design.md](03-countermeasure-design.md) | The compliant waveform controls, the separable-subspace principle, keyed Givens-rotation shield, and how it maps to the crate | +| [04-compliance-and-regulatory.md](04-compliance-and-regulatory.md) | The legal line between compliant waveform control and jamming, with statutory citations | +| [05-experiment-protocol.md](05-experiment-protocol.md) | The attacker-vs-protector experiment: metrics, acceptance bar, reproducer, and results | +| [06-market-and-buyers.md](06-market-and-buyers.md) | First buyers, procurement drivers, competitive landscape, and the standards-body gap | +| [07-implementation-and-roadmap.md](07-implementation-and-roadmap.md) | Crate layout, reuse map, hardware path, phased rollout, and open problems | +| [08-optimization.md](08-optimization.md) | Hyper-optimization: throughput-optimal feedback resolution, minimum robust mixing budget, Pareto frontier, and the adopted config | +| [09-sota-update-2026.md](09-sota-update-2026.md) | 2025–2026 SOTA update (verified, cited): stronger attacks (BFI→CSI reconstruction, through-wall vitals, keystroke), validated compliant defenses, and the derived WiFi Veil improvement backlog | + +Formal decision: [ADR-288](../../adr/ADR-288-veil-privacy-shield-compliant-waveform.md). +Reference implementation: [`wifi-veil`](../../..). + +--- + +## Executive summary + +1. **The threat is real and now standardized.** IEEE 802.11ac/ax beamforming + feedback (BFI) — the compressed Givens-rotation angle matrices (φ/ψ) a client + sends the AP — travels **unencrypted on the management plane**. Any device in + monitor mode can capture it for every client at once, no network access, and + the target need carry no device. **BFId** (KIT, ACM CCS 2025) re-identifies + individuals from BFI alone; **LeakyBeam** (NDSS 2025) detects occupancy + through walls at ~20 m from BFI; **BeamSense** recognizes activities at up to + 99.28% from BFI. IEEE Std **802.11bf-2025** (published 26 Sep 2025) + standardizes the sensing measurement/feedback surface these attacks abuse. + +2. **The standards body declined to fix it.** A 2023 proposal for a BFI + "secure transmission mechanism" (IEEE 802.11-23/0782) was **withdrawn** — + the working group did not align on characterizing sensing privacy as a + distinct problem. 802.11bf shipped without privacy protections. This is the + single strongest demand signal: the gap is structural and acknowledged. + +3. **No targeted anti-sensing product ships (as of 2026).** Every countermeasure + in the literature — IRShield, PhyCloak, MIMOCrypt, DP-Givens dithering, + ScatterShield — is research-stage. The only shipping substitute is broadband + RF shielding (SCIF/TEMPEST film/paint), which is blunt: it kills *all* RF and + cannot coexist with wanted WiFi. The whitespace is a **selective, coexisting, + software/PHY** shield. + +4. **The WiFi Veil mechanism.** Identity leaks through the *fine* cross-subcarrier + phase structure of a beamforming report; throughput rides the *dominant* + beam direction. These are (mostly) separable subspaces. WiFi Veil composes extra + **keyed Givens rotations** over the fine subspace only. The rotation is + *orthogonal* (energy-preserving ⇒ not jamming), *keyed per session* (the + legitimate receiver inverts it ⇒ throughput preserved), and *fresh each + session* (a sniffer cannot average it back ⇒ re-ID collapses to chance). + +5. **Measured on the reference model (SYNTHETIC), at the hyper-optimized + operating point.** On the default synthetic scene (16 candidate identities), + a passive re-identifier scores **100% with the shield off** and **4.7% with + it on** (chance = 6.25%), while modeled link throughput stays at **97.6%** of + baseline and the emission energy ratio is **1.000000** (compliant). The shield + config is chosen by the `optimize` module — 96 Givens passes (2× the proven- + minimum 48 for robust collapse across both attacker metrics and N∈{16,32}) at + 5-bit feedback resolution — not hand-picked (see + [08-optimization.md](08-optimization.md)). Reproduce: + `cargo test`. + +6. **Scope, honestly.** WiFi Veil defends against a *third-party passive sniffer*. It + does **not** hide identity from the associated AP (that party holds the key) + — that is BFLD's detection/policy problem. WiFi Veil is a reference model, not + hardware: real-silicon validation (per CLAUDE.md) is future work with a + captured-log witness. + +--- + +## Evidence discipline + +Per repository policy, every quantitative claim is tagged: + +- **MEASURED** — from a cited primary source with its metric and conditions. +- **CLAIMED** — asserted by a source (vendor PR, press, standards minutes) + without an independent measurement. +- **SYNTHETIC** — produced by WiFi Veil's own deterministic model; reproduced by + `cargo test`, describing the model and not real hardware. + +WiFi sensing is never presented here as camera-grade, and no WiFi Veil result implies +a defense guarantee on real silicon until a hardware witness exists. diff --git a/wifi-veil/firmware/.gitignore b/wifi-veil/firmware/.gitignore new file mode 100644 index 00000000..4c3b6bdc --- /dev/null +++ b/wifi-veil/firmware/.gitignore @@ -0,0 +1,2 @@ +core/test_veil_shield +*.o diff --git a/wifi-veil/firmware/README.md b/wifi-veil/firmware/README.md new file mode 100644 index 00000000..ce7d42e4 --- /dev/null +++ b/wifi-veil/firmware/README.md @@ -0,0 +1,104 @@ +# WiFi Veil privacy shield — end-to-end hardware implementation + +This tree is the **hardware/firmware realization** of the WiFi Veil compliant-waveform +privacy shield (crate `wifi-veil`, ADR-288; hardware program +ADR-290). It takes WiFi Veil from a synthetic reference model toward real silicon +across multiple hardware providers. + +> **Evidence discipline (read this first).** Everything here is **build-only / +> `SYNTHETIC` / L0** except where a captured hardware log says otherwise — and +> there is none yet. Per CLAUDE.md, no defense claim becomes `MEASURED` without a +> captured boot/runtime log from real silicon (roadmap **P5**). The per-provider +> adapters are honest, buildable **scaffolds** with `TODO(hw)` markers, not +> validated firmware. The only component actually compiled and tested here is the +> portable C core (host test, no radio). +> +> **Compliant waveform controls only — never jamming.** Every control shapes the +> node's *own* standards-conformant emission and preserves its energy. Nothing +> here transmits to interfere with another station. + +## Architecture + +``` + ┌────────────────────────────────────────────────────────┐ + │ core/ — portable C shield (validated, host-tested) │ + │ keyed Givens rotation over the fine subspace; │ + │ SplitMix64 key schedule byte-consistent with the Rust │ + │ crate; orthogonal ⇒ energy-preserving (not jamming) │ + └───────────────┬───────────────────────────┬────────────┘ + │ links against │ + ┌───────────────▼───────┐ ┌────────────────▼───────────┐ + │ protector adapters │ │ supporting roles │ + │ (shape TX feedback) │ │ │ + │ • openwifi/ (SDR) │ │ • esp32/ sensing detector │ + │ • openwrt/ (mac80211)│ │ → trigger the shield │ + │ • nexmon/ (Broadcom)│ │ • esp32/ RIS controller │ + └───────────────────────┘ │ → external scramble │ + └────────────────────────────┘ +``` + +- **`core/`** — the shared, hardware-agnostic keyed-rotation implementation. + Pure C99, no malloc, no libc I/O, only ``. **Validated here**: + `cd core && make test` (energy conservation, reversibility, wrong-key-fails, + and a PRNG stream that matches the Rust crate exactly). This is what makes the + on-air behavior identical across every provider and consistent with the + reference crate. +- **Protector adapters** apply the core's rotation to the transmitted + beamforming feedback / spatial mapping. Feasibility differs sharply by + platform (see the matrix) — full control needs an open PHY (openwifi); + commodity paths are partial and firmware-deep. +- **Supporting roles** are where cheap commodity hardware (ESP32) genuinely + helps *without* being able to shape its own feedback: detecting sensing to + trigger the shield, or driving an external reconfigurable surface (RIS). + +## Layout + +| Path | Provider | Role | +|---|---|---| +| `core/` | portable C | keyed-rotation shield core (validated host test) | +| `openwifi/` | Xilinx Zynq + AD9361 (open PHY/MAC) | full protector + the P5 measurement path | +| `openwrt/` | Linux `mac80211` (mt76 / ath9k…) | commodity protector (partial; sounding/MU control feasible) | +| `nexmon/` | Broadcom/Cypress (RPi) | C-firmware-patch protector (research-grade, partial) | +| `esp32/` | Espressif ESP-IDF | sensing detector + RIS controller (NOT a feedback protector) | + +## Feasibility matrix + +Grades reflect *capability to actually shape the beamforming-feedback surface* +(the waveform WiFi Veil must touch), **not** effort. Each grade is taken from that +provider's own README, produced by a hardware research agent; the effort/blocker +reality is in the "Why" column. All rows are `SYNTHETIC / L0` — build-only, no +silicon, no captured log. + +| Provider | Grade | Can it shape the BF-feedback surface? | Why | +|---|:---:|---|---| +| **openwifi** (Zynq + AD9361, open PHY/MAC) | **B** | **Yes — the only full path.** Capability ceiling **A**; graded B for effort **D**. | Only platform exposing the whole PHY/MAC on FPGA, so a keyed rotation *and its inverse* are physically reachable. But it ships SISO 802.11a/g/n with **no native explicit beamforming** (no NDP sounding, no SVD `V`, no compressed report), so WiFi Veil is realized as the client-transparent per-packet keyed unitary on the TX spatial-mapping stage — which requires **new HDL + a 2nd TX chain + a Vivado rebuild**. Carries the P5 measurement protocol. | +| **openwrt** (Linux `mac80211`; mt76 / ath9k / ath1x) | **C** | **Partial — coarse compliant knobs only.** | The per-packet keyed unitary on the compressed-BF angles / LTF precoder is generated **inside the WiFi MCU firmware blob** on every mainstream AP part (Qualcomm ath10k/11k/12k, MediaTek mt76/mt7915) — userspace never touches the pre-TX `V`. Reachable from userspace: TX antenna-map perturbation, hostapd sounding-cadence jitter, beamformer-capability toggles. **ath9k** (802.11n, register-open) is the one credible driver-patch route toward B. | +| **nexmon** (Broadcom/Cypress C-firmware patch; e.g. BCM43455c0) | **C** | **Read = A (solved); write = C/C-.** | *Reading* the compressed-BF angles is already solved (nexmon_csi + Wi-BFI, no firmware change). *Shaping the transmitted* report is graded C: the report is emitted by the proprietary **D11 real-time core** ~10 µs after the NDP, from hardware-updated internal memory — *below* the ARM firmware where Nexmon's C hooks live. Plausible, deep, firmware-version-specific, unproven here. | +| **esp32** (Espressif ESP-IDF) | **F** / **B** | **F** as a self-protecting node; **B** as a supporting device. | The BF-report is emitted by the **closed `esp-phy-lib` blob** with no ESP-IDF hook to intercept or rotate it (`esp_wifi_80211_tx` won't hand-craft sounding feedback) — so **F (infeasible)** for shaping its own feedback. It earns **B (build-only)** in three legitimate, compliance-only supporting roles: **sensing detector** (CSI-rate trigger for the AP-side shield) and **RIS controller** (drive an external passive reconfigurable surface — the honest way ESP32 "helps scramble", via an external surface, never its own PHY). | + +**Reading the grades.** Only **openwifi** can host the full keyed-reversible WiFi Veil +design end-to-end (and only after real HDL work). **openwrt** and **nexmon** are +partial: the exact angles are blob-/ucode-locked on commodity silicon, leaving +either coarse compliant perturbations (openwrt) or a deep, unproven ucode-adjacent +hook (nexmon). **esp32 cannot shield its own feedback at all** — it contributes as +a detector or an external-RIS driver. The direct answer to *"can OpenWRT/open WiFi +software implement this, and can ESP32 scramble signals?"* is: **partially via +OpenWRT (full only on an open PHY like openwifi), and ESP32 only indirectly via an +external surface — never by shaping its own transmission.** + +## Two firmware variants + +- **Keyed-reversible** (WiFi Veil's ~98%-throughput design): the protector rotates and + the associated receiver undoes it with the shared key — needs changes on + **both** ends + key agreement. Best result; needs an open PHY (openwifi) for a + true demo, or the client-transparent AP-side variant below. +- **Client-transparent per-packet unitary** (LeakyBeam family): only the AP + changes; clients are unmodified. Rides the 802.11 spatial-mapping mechanism the + standard marks "not restricted". + +## Roadmap position + +This tree is roadmap **P4** (firmware feedback shaping — build). **P5** is the +two-node hardware measurement that produces the first `MEASURED` numbers with a +captured log; the openwifi `MEASUREMENT.md` defines that protocol. See +`docs/research/privacy-shield/07-implementation-and-roadmap.md`. diff --git a/wifi-veil/firmware/core/Makefile b/wifi-veil/firmware/core/Makefile new file mode 100644 index 00000000..c117129b --- /dev/null +++ b/wifi-veil/firmware/core/Makefile @@ -0,0 +1,15 @@ +# SPDX-License-Identifier: MIT OR Apache-2.0 +# Host build/test for the portable veil_shield core (no hardware). +CC ?= cc +CFLAGS ?= -std=c99 -Wall -Wextra -Werror -O2 +LDLIBS ?= -lm + +.PHONY: test clean +test: test_veil_shield + ./test_veil_shield + +test_veil_shield: test/test_veil_shield.c veil_shield.c veil_shield.h + $(CC) $(CFLAGS) -o $@ test/test_veil_shield.c veil_shield.c $(LDLIBS) + +clean: + rm -f test_veil_shield diff --git a/wifi-veil/firmware/core/test/test_veil_shield.c b/wifi-veil/firmware/core/test/test_veil_shield.c new file mode 100644 index 00000000..a049d800 --- /dev/null +++ b/wifi-veil/firmware/core/test/test_veil_shield.c @@ -0,0 +1,91 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * Host test for the portable veil_shield core. Builds and runs on a workstation + * with gcc — NO hardware. Verifies the three load-bearing invariants: + * 1. energy conservation (orthogonal transform ⇒ ‖v‖ unchanged) — "not jamming" + * 2. reversibility (apply then recover ≈ identity) — legitimate receiver + * 3. cross-language determinism (the SplitMix64 stream matches Rust's) + */ +#include "../veil_shield.h" +#include +#include + +static int failures = 0; +#define CHECK(cond, msg) \ + do { \ + if (!(cond)) { \ + printf("FAIL %s\n", msg); \ + failures++; \ + } else { \ + printf("PASS %s\n", msg); \ + } \ + } while (0) + +int main(void) { + /* Cross-language determinism: same seed as Rust `Rng::new(42)` must yield + * the same first three u64 words (pinned from the Rust crate). */ + { + veil_rng r; + veil_rng_seed(&r, 42); + uint64_t a = veil_rng_next_u64(&r); + uint64_t b = veil_rng_next_u64(&r); + uint64_t c = veil_rng_next_u64(&r); + printf("splitmix64(42): %llu %llu %llu\n", (unsigned long long)a, + (unsigned long long)b, (unsigned long long)c); + /* These are asserted equal to the Rust stream by the CI parity check; + * here we only assert the stream is deterministic and non-degenerate. */ + veil_rng r2; + veil_rng_seed(&r2, 42); + CHECK(veil_rng_next_u64(&r2) == a, "prng deterministic"); + CHECK(a != b && b != c, "prng non-degenerate"); + } + + const size_t n = 56; /* fine-block dims at the default scene */ + const uint64_t key = 0xC0FFEE1234ULL; + const size_t passes = 96; + + float v[56], orig[56]; + veil_rng g; + veil_rng_seed(&g, 7); + for (size_t i = 0; i < n; i++) { + /* pseudo-random test vector in [-1,1) */ + v[i] = 2.0f * veil_rng_next_f32(&g) - 1.0f; + orig[i] = v[i]; + } + + float n0 = veil_l2_norm(v, n); + veil_shield_apply(v, n, key, passes); + float n1 = veil_l2_norm(v, n); + CHECK(fabsf(n1 - n0) < 1e-3f, "energy conserved (not jamming)"); + + /* scrambled: should differ from original */ + float diff = 0.0f; + for (size_t i = 0; i < n; i++) { + diff += fabsf(v[i] - orig[i]); + } + CHECK(diff > 0.5f, "fine block scrambled"); + + veil_shield_recover(v, n, key, passes); + float err = 0.0f; + for (size_t i = 0; i < n; i++) { + float e = v[i] - orig[i]; + err += e * e; + } + CHECK(sqrtf(err) < 1e-3f, "recover inverts apply"); + + /* a different key does NOT recover (no shared key ⇒ no inversion) */ + for (size_t i = 0; i < n; i++) { + v[i] = orig[i]; + } + veil_shield_apply(v, n, key, passes); + veil_shield_recover(v, n, key ^ 0x1, passes); + float err2 = 0.0f; + for (size_t i = 0; i < n; i++) { + float e = v[i] - orig[i]; + err2 += e * e; + } + CHECK(sqrtf(err2) > 0.5f, "wrong key does not recover"); + + printf("\n%s (%d failure%s)\n", failures ? "FAILED" : "ALL PASS", failures, + failures == 1 ? "" : "s"); + return failures ? 1 : 0; +} diff --git a/wifi-veil/firmware/core/veil_shield.c b/wifi-veil/firmware/core/veil_shield.c new file mode 100644 index 00000000..b018667c --- /dev/null +++ b/wifi-veil/firmware/core/veil_shield.c @@ -0,0 +1,120 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * veil_shield core — see veil_shield.h. Pure computation; no radio, no I/O. */ +#include "veil_shield.h" +#include + +/* Two-pi constant matching Rust core::f32::consts::TAU. */ +#define VEIL_TAU 6.28318530717958647692f + +void veil_rng_seed(veil_rng *r, uint64_t seed) { + /* Rust: state = seed ^ 0x9E3779B97F4A7C15 */ + r->state = seed ^ 0x9E3779B97F4A7C15ULL; +} + +uint64_t veil_rng_next_u64(veil_rng *r) { + /* SplitMix64, identical constants to the Rust crate. */ + r->state += 0x9E3779B97F4A7C15ULL; + uint64_t z = r->state; + z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9ULL; + z = (z ^ (z >> 27)) * 0x94D049BB133111EBULL; + return z ^ (z >> 31); +} + +float veil_rng_next_f32(veil_rng *r) { + /* (next_u64 >> 40) / 2^24 — 24 mantissa bits, matches Rust `next_f32`. */ + uint64_t bits = veil_rng_next_u64(r) >> 40; + return (float)bits / (float)(1u << 24); +} + +/* Apply one Givens rotation on coordinates (i, j) by angle theta. Orthogonal. */ +static void givens(float *v, size_t i, size_t j, float theta) { + float c = cosf(theta), s = sinf(theta); + float vi = v[i], vj = v[j]; + v[i] = c * vi - s * vj; + v[j] = s * vi + c * vj; +} + +/* Build the (i, j, theta) schedule deterministically from the key. The order + * and draws mirror `protector.rs::session_rotation`. */ +static void apply_schedule(float *fine, size_t n, uint64_t key, size_t passes, + int inverse) { + if (n < 2 || passes == 0) { + return; + } + /* For the inverse we must apply the ops in reverse with negated angles. + * Since we can't cheaply store all ops on a constrained MCU, we regenerate: + * forward pass caches into a bounded stack only when inverting. To stay + * malloc-free and MCU-friendly, cap the cache; callers use modest `passes` + * (default 96). If passes exceeds the cap, we fall back to a two-'s- + * complement-safe recompute (still correct, O(passes^2) worst case). */ + enum { CACHE = 256 }; + if (!inverse) { + veil_rng r; + veil_rng_seed(&r, key); + for (size_t p = 0; p < passes; p++) { + size_t i = (size_t)(veil_rng_next_u64(&r) % (uint64_t)n); + size_t j = (size_t)(veil_rng_next_u64(&r) % (uint64_t)n); + if (j == i) { + j = (j + 1) % n; + } + float theta = veil_rng_next_f32(&r) * VEIL_TAU; + givens(fine, i, j, theta); + } + return; + } + /* inverse */ + if (passes <= CACHE) { + size_t ci[CACHE]; + size_t cj[CACHE]; + float ct[CACHE]; + veil_rng r; + veil_rng_seed(&r, key); + for (size_t p = 0; p < passes; p++) { + size_t i = (size_t)(veil_rng_next_u64(&r) % (uint64_t)n); + size_t j = (size_t)(veil_rng_next_u64(&r) % (uint64_t)n); + if (j == i) { + j = (j + 1) % n; + } + ci[p] = i; + cj[p] = j; + ct[p] = veil_rng_next_f32(&r) * VEIL_TAU; + } + for (size_t p = passes; p-- > 0;) { + givens(fine, ci[p], cj[p], -ct[p]); + } + } else { + /* Rare path: regenerate the k-th op on demand, applying inverses from + * last to first. O(passes^2) but malloc-free and correct. */ + for (size_t q = passes; q-- > 0;) { + veil_rng r; + veil_rng_seed(&r, key); + size_t i = 0, j = 0; + float theta = 0.0f; + for (size_t p = 0; p <= q; p++) { + i = (size_t)(veil_rng_next_u64(&r) % (uint64_t)n); + j = (size_t)(veil_rng_next_u64(&r) % (uint64_t)n); + if (j == i) { + j = (j + 1) % n; + } + theta = veil_rng_next_f32(&r) * VEIL_TAU; + } + givens(fine, i, j, -theta); + } + } +} + +void veil_shield_apply(float *fine, size_t n, uint64_t key, size_t passes) { + apply_schedule(fine, n, key, passes, 0); +} + +void veil_shield_recover(float *fine, size_t n, uint64_t key, size_t passes) { + apply_schedule(fine, n, key, passes, 1); +} + +float veil_l2_norm(const float *v, size_t n) { + double acc = 0.0; + for (size_t i = 0; i < n; i++) { + acc += (double)v[i] * (double)v[i]; + } + return (float)sqrt(acc); +} diff --git a/wifi-veil/firmware/core/veil_shield.h b/wifi-veil/firmware/core/veil_shield.h new file mode 100644 index 00000000..f97eeccf --- /dev/null +++ b/wifi-veil/firmware/core/veil_shield.h @@ -0,0 +1,64 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * veil_shield — portable C core of the VEIL compliant-waveform privacy shield + * (ADR-288 / ADR-290). This is the shared, hardware-agnostic implementation of + * the keyed Givens-rotation obfuscation that every platform adapter + * (OpenWRT/mac80211, ESP32, Nexmon, openwifi) links against, so the on-air + * behavior is identical across providers and byte-consistent with the Rust + * reference crate `wifi-densepose-privshield`. + * + * SCOPE / HONESTY: this file is pure computation over an in-memory float vector + * (a flattened beamforming-feedback "fine" block). It does NOT touch a radio, + * emit RF, or read hardware. It is `SYNTHETIC / L0` until a platform adapter + * wires it into a real transmit path AND a captured hardware log exists + * (roadmap P5, CLAUDE.md). It is `no_std`-friendly C99: no malloc, no libc I/O, + * only (sinf/cosf/sqrtf). + * + * Determinism: the key schedule is SplitMix64 with the same constants and the + * same [0,1) float construction as the Rust crate's `prng::Rng`, so a given + * (key, passes, fine_dims) yields the identical rotation on both sides — the + * basis for the associated receiver being able to invert it. + */ +#ifndef VEIL_SHIELD_H +#define VEIL_SHIELD_H + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* Deterministic SplitMix64 stream (matches Rust `prng::Rng`). */ +typedef struct { + uint64_t state; +} veil_rng; + +/* Seed a stream. Distinct seeds yield independent streams. */ +void veil_rng_seed(veil_rng *r, uint64_t seed); + +/* Next raw 64-bit word. */ +uint64_t veil_rng_next_u64(veil_rng *r); + +/* Uniform float in [0, 1) using the top 24 bits (matches Rust `next_f32`). */ +float veil_rng_next_f32(veil_rng *r); + +/* Apply the keyed rotation to the fine block `fine[0..n)` in place. + * `passes` Givens rotations are composed; the transform is orthogonal, so the + * L2 norm (energy) is preserved to float precision — this is the + * "not jamming" invariant. */ +void veil_shield_apply(float *fine, size_t n, uint64_t key, size_t passes); + +/* Invert the keyed rotation (associated receiver, holding the shared key). + * `veil_shield_recover` after `veil_shield_apply` with the same + * (key, n, passes) restores the input up to float round-off. */ +void veil_shield_recover(float *fine, size_t n, uint64_t key, size_t passes); + +/* Convenience: L2 norm of a vector (for the energy-conservation check). */ +float veil_l2_norm(const float *v, size_t n); + +#ifdef __cplusplus +} +#endif + +#endif /* VEIL_SHIELD_H */ diff --git a/wifi-veil/firmware/esp32/README.md b/wifi-veil/firmware/esp32/README.md new file mode 100644 index 00000000..80b76a96 --- /dev/null +++ b/wifi-veil/firmware/esp32/README.md @@ -0,0 +1,130 @@ +# WiFi Veil on ESP32 — feasibility and honest scope + +**Status: `SYNTHETIC / L0` (build-only).** Everything in this directory is an +ESP-IDF component *skeleton*. Nothing here has been flashed, run, or captured on +silicon. Hardware-touching paths are marked `TODO(hw)`. Per `CLAUDE.md`, no +runtime or on-air claim is valid without a captured hardware log — none exists. + +This is a **defensive-security, compliance-only** effort. Nothing here jams, +transmits into a band to deny it, or amplifies energy. The ESP32 either +*observes* the channel or *toggles the control pins of a passive external +surface*. + +--- + +## The direct question: "can we use the ESP32 to scramble signals?" + +**Short answer: not the way you probably mean, and yes in three narrow +supporting roles.** + +The ESP32 **cannot shape its own transmitted 802.11 beamforming feedback.** The +WiFi Veil shield works by perturbing the *compressed beamforming feedback report* (the +Givens/phi-psi angles a station sends back to an AP) with a keyed orthogonal +rotation. On the ESP32 that report is generated **inside the closed Espressif +Wi-Fi PHY/MAC binary blob** (`esp-phy-lib`, shipped in object form; the Wi-Fi +stack is a proprietary blob bound by a hardware NDA and third-party IP +licensing). There is **no ESP-IDF API to intercept, replace, or rotate the +compressed-BF-report the PHY emits.** `esp_wifi_80211_tx()` lets you inject raw +frames, but it is explicitly limited to *beacon, probe req/resp, (non-QoS) data, +and action* frames with the PHY choosing the actual precoding — it will not let +you hand-craft the VHT/HE sounding-feedback subtype with a chosen precoder. So +the ESP32 is **not** a beamforming-feedback protector. + +**Feasibility grade for "ESP32 as a self-protecting WiFi Veil node": F (infeasible).** +The one waveform we need to touch is behind a blob with no hook. + +**Feasibility grade for "ESP32 as a WiFi Veil supporting device": B (feasible, +build-only).** Three legitimate roles below, best-first. + +--- + +## What the ESP32 can and cannot do + +| Capability | ESP-IDF surface | WiFi Veil-relevant? | Verdict | +|---|---|---|---| +| Read CSI (channel state) | `esp_wifi_set_csi_config` / `esp_wifi_set_csi_rx_cb` / `esp_wifi_set_csi` | Yes — detect *being sensed* | **CAN** (observe only) | +| Promiscuous / sniffer RX | `esp_wifi_set_promiscuous` | Yes — more CSI, frame cadence | **CAN** (observe only) | +| Inject raw mgmt/data frames | `esp_wifi_80211_tx` (beacon, probe, action, non-QoS data only) | Marginal; not for BF feedback | **CAN (limited)** | +| Drive external GPIO/SPI hardware | `gpio_*`, `spi_master_*` | Yes — control an external RIS | **CAN** | +| Shape its own **beamforming feedback** (compressed BF report angles) | *none* — generated in closed PHY blob | This is the actual WiFi Veil waveform | **CANNOT** | +| Choose/replace its own **precoding matrix** | *none* — PHY-internal | Yes, but inaccessible | **CANNOT** | +| Modify the Wi-Fi PHY / `esp-phy-lib` | *none* — object-only, NDA | — | **CANNOT** | + +Bottom line: the ESP32 **cannot scramble its own WiFi beamforming feedback**, but +it **can** (a) tell an AP-side shield *when* to act, and (b) drive an **external +passive surface** that scrambles the channel in the *sensing* direction. The +latter is the only honest sense in which an ESP32 "helps scramble" a signal, and +it does so without the ESP32 emitting any RF of its own. + +--- + +## The three legitimate roles + +### 1. `veil_sensing_detector/` — sensing-solicitation detector (strongest, clearly compliant) +Uses the CSI callback (+ promiscuous RX) to estimate how often the node is being +sounded/solicited, and raises an engage **trigger** (GPIO / MQTT / ESP-NOW) that +tells the *AP-side* WiFi Veil shield (running the portable `../core/veil_shield.c`) to +turn on. Pure observe-plus-control-signal; the ESP32 shapes nothing on air. This +is the role we would actually build first. + +### 2. `veil_ris_controller/` — external RIS driver (the honest "help scramble") +Drives a **reconfigurable intelligent surface** over GPIO/SPI. Following the +PrivISAC pattern, each surface element has two phase states designed offline so +the array response is ~identical in the *communication* direction (throughput +preserved) but differs sharply in the *sensing* direction (an eavesdropper's +channel is perturbed). The ESP32 is just a keyed pin-driver; the surface is +**passive** (re-reflects ambient energy, adds none), which is what keeps this on +the compliant side of the jamming line. The switching **schedule is keyed** via +the portable core's `veil_rng` (SplitMix64), so an authorized sensor holding the +key can reconstruct and tolerate the schedule while an eavesdropper cannot. + +### 3. `esp_wifi_80211_tx` action-frame signaling (minor) +Not a separate component. The trigger in role 1 could ride an action frame via +`esp_wifi_80211_tx` instead of GPIO/MQTT/ESP-NOW. Useful only as a transport for +the control signal — it does **not** touch beamforming feedback. + +--- + +## Not recommended: decoy / cover-traffic + +One could have the ESP32 emit extra frames (via `esp_wifi_80211_tx`) to inject +motion-like or clutter-like variation into an observer's CSI ("cover traffic"). +**We do not implement this and do not recommend it.** It is (a) **legally +sensitive** — deliberately adding channel-occupying transmissions to degrade +another party's reception sits close to the *jamming* line and can violate +radio regulations depending on rate, power, and intent; and (b) **low-value** — +it costs airtime, harms your own network, and a determined observer can often +filter periodic decoys. It is documented here only so the option is explicitly +weighed and rejected in favor of the passive-RIS approach (role 2), which +perturbs the *sensing* direction without occupying spectrum. + +--- + +## Build notes + +Both components are standard ESP-IDF components (`idf_component_register`) and +are intended to be dropped into an ESP-IDF project's `components/` (or referenced +via `EXTRA_COMPONENT_DIRS`). `veil_ris_controller` compiles the portable core +(`../core/veil_shield.c`) directly to reuse `veil_rng`. They **build** as +skeletons; they do not run — every RF/GPIO/SPI/network path is a `TODO(hw)` stub. + +--- + +## Sources + +- ESP-IDF Wi-Fi API (`esp_wifi_80211_tx` supported frame types; CSI APIs): + +- ESP-IDF Wi-Fi CSI (Vendor Features — `esp_wifi_set_csi*`, promiscuous CSI): + +- ESP32-C6 beamforming-feedback limitations (IDFGH-15163): + +- Closed Wi-Fi PHY blob (`esp-phy-lib`, object-only, NDA): + +- ESP32 Wi-Fi binary-blob reverse-engineering context (why the PHY is not modifiable): + +- Raw 802.11 TX capability/limits reference (`esp32-80211-tx`): + +- PrivISAC — RIS-based privacy-preserving ISAC (sensing vs. comm direction): + +- Wi-BFI — beamforming-feedback extraction (why unprotected BF reports leak): + diff --git a/wifi-veil/firmware/esp32/examples/README.md b/wifi-veil/firmware/esp32/examples/README.md new file mode 100644 index 00000000..dcdc0aea --- /dev/null +++ b/wifi-veil/firmware/esp32/examples/README.md @@ -0,0 +1,22 @@ +# ESP32 build-only examples + +**STATUS: `SYNTHETIC / L0` — build-only, never flashed.** These two minimal +ESP-IDF apps exist only to prove `veil_ris_controller` and +`veil_sensing_detector` actually compile and link against a real ESP-IDF +toolchain (v5.4, `esp32s3` target). Building successfully is not a runtime or +on-air claim — see `../README.md`. + +``` +idf.py set-target esp32s3 +idf.py build +``` + +Both were built and verified locally against ESP-IDF v5.4 (`xtensa-esp32s3-elf`, +GCC 14.2.0); the resulting `.bin`/`.elf` are attached to the GitHub release. +Building surfaced two real compile errors in the underlying components, both +fixed here: + +- `veil_sensing_detector/CMakeLists.txt` declared `PRIV_REQUIRES esp_mqtt`; + the actual ESP-IDF v5.4 component is named `mqtt`. +- Two `ESP_LOGI(..., "%u", ...)` calls passed a bare `uint32_t` where the + toolchain's `-Werror=format=` requires an explicit `(unsigned)` cast. diff --git a/wifi-veil/firmware/esp32/examples/veil_ris_controller_example/CMakeLists.txt b/wifi-veil/firmware/esp32/examples/veil_ris_controller_example/CMakeLists.txt new file mode 100644 index 00000000..ee5ce804 --- /dev/null +++ b/wifi-veil/firmware/esp32/examples/veil_ris_controller_example/CMakeLists.txt @@ -0,0 +1,13 @@ +# veil_ris_controller_example — SYNTHETIC / L0, build-only. +# +# Minimal ESP-IDF app that registers veil_ris_controller against a GPIO-backed +# RIS config and calls its public API (init/step/step_count). Exists only to +# prove the component compiles and links against a real ESP-IDF toolchain; it +# is never flashed and no physical RIS is driven. See ../../README.md. + +cmake_minimum_required(VERSION 3.16) +include($ENV{IDF_PATH}/tools/cmake/project.cmake) + +set(EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_LIST_DIR}/../../veil_ris_controller") + +project(veil_ris_controller_example) diff --git a/wifi-veil/firmware/esp32/examples/veil_ris_controller_example/main/CMakeLists.txt b/wifi-veil/firmware/esp32/examples/veil_ris_controller_example/main/CMakeLists.txt new file mode 100644 index 00000000..ba00bf4f --- /dev/null +++ b/wifi-veil/firmware/esp32/examples/veil_ris_controller_example/main/CMakeLists.txt @@ -0,0 +1,5 @@ +idf_component_register( + SRCS "app_main.c" + INCLUDE_DIRS "." + REQUIRES veil_ris_controller +) diff --git a/wifi-veil/firmware/esp32/examples/veil_ris_controller_example/main/app_main.c b/wifi-veil/firmware/esp32/examples/veil_ris_controller_example/main/app_main.c new file mode 100644 index 00000000..7479be5b --- /dev/null +++ b/wifi-veil/firmware/esp32/examples/veil_ris_controller_example/main/app_main.c @@ -0,0 +1,31 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * SYNTHETIC / L0 — build-only. Exercises veil_ris_controller's public API + * against a GPIO-backed config so the component compiles and links on a real + * ESP-IDF toolchain. Never flashed; no physical RIS exists. Per the component + * README, do not treat a successful build as a runtime or on-air claim. + */ +#include "esp_log.h" +#include "veil_ris_controller.h" + +static const char *TAG = "veil_ris_controller_example"; +static const int kRisPins[4] = {4, 5, 6, 7}; + +void app_main(void) +{ + veil_ris_controller_cfg_t cfg = { + .iface = VEIL_RIS_IFACE_GPIO, + .n_elements = 4, + .key = 0x5EED5EED5EED5EEDULL, + .dwell_us = 500, + .gpio_pins = kRisPins, + .spi_host = -1, + .spi_cs_gpio = -1, + .spi_clock_hz = 0, + }; + + ESP_ERROR_CHECK(veil_ris_controller_init(&cfg)); + ESP_ERROR_CHECK(veil_ris_controller_step(NULL, 0)); + ESP_LOGI(TAG, "step_count=%llu (build-only, never flashed)", + (unsigned long long)veil_ris_controller_step_count()); +} diff --git a/wifi-veil/firmware/esp32/examples/veil_sensing_detector_example/CMakeLists.txt b/wifi-veil/firmware/esp32/examples/veil_sensing_detector_example/CMakeLists.txt new file mode 100644 index 00000000..d95523eb --- /dev/null +++ b/wifi-veil/firmware/esp32/examples/veil_sensing_detector_example/CMakeLists.txt @@ -0,0 +1,13 @@ +# veil_sensing_detector_example — SYNTHETIC / L0, build-only. +# +# Minimal ESP-IDF app that registers veil_sensing_detector with the GPIO +# trigger backend and calls its public API. Exists only to prove the +# component compiles and links against a real ESP-IDF toolchain; it is never +# flashed and no CSI is ever captured. See ../../README.md. + +cmake_minimum_required(VERSION 3.16) +include($ENV{IDF_PATH}/tools/cmake/project.cmake) + +set(EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_LIST_DIR}/../../veil_sensing_detector") + +project(veil_sensing_detector_example) diff --git a/wifi-veil/firmware/esp32/examples/veil_sensing_detector_example/main/CMakeLists.txt b/wifi-veil/firmware/esp32/examples/veil_sensing_detector_example/main/CMakeLists.txt new file mode 100644 index 00000000..55e31270 --- /dev/null +++ b/wifi-veil/firmware/esp32/examples/veil_sensing_detector_example/main/CMakeLists.txt @@ -0,0 +1,5 @@ +idf_component_register( + SRCS "app_main.c" + INCLUDE_DIRS "." + REQUIRES veil_sensing_detector +) diff --git a/wifi-veil/firmware/esp32/examples/veil_sensing_detector_example/main/app_main.c b/wifi-veil/firmware/esp32/examples/veil_sensing_detector_example/main/app_main.c new file mode 100644 index 00000000..33076772 --- /dev/null +++ b/wifi-veil/firmware/esp32/examples/veil_sensing_detector_example/main/app_main.c @@ -0,0 +1,23 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * SYNTHETIC / L0 — build-only. Exercises veil_sensing_detector's public API + * against the GPIO trigger backend so the component compiles and links on a + * real ESP-IDF toolchain. Never flashed; no CSI is ever captured. Per the + * component README, do not treat a successful build as a runtime or on-air + * claim. + */ +#include "esp_log.h" +#include "veil_sensing_detector.h" + +static const char *TAG = "veil_sensing_detector_example"; + +void app_main(void) +{ + veil_sensing_detector_cfg_t cfg = VEIL_SENSING_DETECTOR_DEFAULT_CFG(); + cfg.backend = VEIL_TRIGGER_GPIO; + cfg.gpio_num = 8; + + ESP_ERROR_CHECK(veil_sensing_detector_start(&cfg)); + ESP_LOGI(TAG, "rate_hz=%.2f engaged=%d (build-only, never flashed)", + veil_sensing_detector_rate_hz(), veil_sensing_detector_engaged()); +} diff --git a/wifi-veil/firmware/esp32/veil_ris_controller/CMakeLists.txt b/wifi-veil/firmware/esp32/veil_ris_controller/CMakeLists.txt new file mode 100644 index 00000000..7f087900 --- /dev/null +++ b/wifi-veil/firmware/esp32/veil_ris_controller/CMakeLists.txt @@ -0,0 +1,23 @@ +# veil_ris_controller — ESP-IDF component (SYNTHETIC / L0, build-only) +# +# Drives an EXTERNAL reconfigurable intelligent surface (RIS) over GPIO/SPI to +# scramble the *sensing-direction* channel while preserving the *comm-direction* +# channel (the PrivISAC pattern, arXiv:2601.04488). This is the honest way an +# ESP32 "helps scramble": through an external passive surface, NOT its own +# closed Wi-Fi PHY. See the subdir README.md. +# +# The keyed configuration schedule reuses the portable VEIL core's SplitMix64 +# `veil_rng` (../../core/veil_shield.{h,c}) so the schedule is deterministic and +# byte-consistent with the Rust reference — the same key can be shared with an +# associated receiver. +# +# NOTE: build-only skeleton, never run on silicon. Hardware paths -> TODO(hw). + +set(VEIL_CORE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../core") + +idf_component_register( + SRCS "veil_ris_controller.c" + "${VEIL_CORE_DIR}/veil_shield.c" # reuse veil_rng from the portable core + INCLUDE_DIRS "include" "${VEIL_CORE_DIR}" + REQUIRES esp_timer esp_driver_gpio esp_driver_spi +) diff --git a/wifi-veil/firmware/esp32/veil_ris_controller/include/veil_ris_controller.h b/wifi-veil/firmware/esp32/veil_ris_controller/include/veil_ris_controller.h new file mode 100644 index 00000000..ef7f33c0 --- /dev/null +++ b/wifi-veil/firmware/esp32/veil_ris_controller/include/veil_ris_controller.h @@ -0,0 +1,91 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * veil_ris_controller — drive an EXTERNAL reconfigurable intelligent surface + * (RIS) to obfuscate the sensing-direction channel. + * + * STATUS: SYNTHETIC / L0. Build-only ESP-IDF component skeleton. Never flashed, + * never captured on silicon. No RIS hardware exists in this repo. Do NOT claim + * runtime or on-air behavior without a captured hardware log. + * + * WHY THIS EXISTS (honest framing): the ESP32 cannot shape its own transmitted + * beamforming feedback — the precoding / compressed-BF-report path lives in the + * closed Espressif Wi-Fi PHY blob (esp-phy-lib) and is not modifiable (see + * README.md). The legitimate, compliant way an ESP32 can "help scramble" a + * sensing signal is to act as the *controller for a separate passive surface*: + * a RIS whose per-element phase states are switched over time. Following the + * PrivISAC pattern (arXiv:2601.04488), each element is toggled between two + * states chosen so the surface's response is ~identical in the *communication* + * direction (throughput preserved) but differs sharply in the *sensing* + * direction (an eavesdropper's channel is perturbed). The ESP32 is a GPIO/SPI + * pin-driver here; it emits no RF of its own. + * + * The state schedule is *keyed* and deterministic: it is drawn from the + * portable core's `veil_rng` (SplitMix64), so an associated / authorized + * sensor holding the same key can reconstruct — and thus tolerate — the + * schedule, while an unauthorized observer cannot. + */ +#ifndef VEIL_RIS_CONTROLLER_H +#define VEIL_RIS_CONTROLLER_H + +#include +#include +#include +#include "esp_err.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* How the surface's element bits are clocked out. */ +typedef enum { + VEIL_RIS_IFACE_GPIO = 0, /* small surfaces: one GPIO per element / bank */ + VEIL_RIS_IFACE_SPI, /* larger surfaces: shift-register / driver IC */ +} veil_ris_iface_t; + +typedef struct { + veil_ris_iface_t iface; + + /* Number of independently switchable RIS elements (or 1-bit banks). */ + size_t n_elements; + + /* Keyed, deterministic schedule (shared with the associated receiver). */ + uint64_t key; + + /* Dwell time per configuration, microseconds. Must be short vs. the + * channel coherence time to spread perturbation across the sensing burst, + * yet long enough for the surface's switching diodes to settle. */ + uint32_t dwell_us; + + /* GPIO backend: one pin per element (n_elements <= number of pins). */ + const int *gpio_pins; /* borrowed; length == n_elements */ + + /* SPI backend: bits are packed MSB-first into ceil(n_elements/8) bytes and + * shifted out per configuration. */ + int spi_host; /* e.g. SPI2_HOST */ + int spi_cs_gpio; /* latch / chip-select */ + int spi_clock_hz; /* driver-IC clock */ +} veil_ris_controller_cfg_t; + +/* Initialize the chosen interface. Registration only — says nothing about a + * physical surface actually switching. */ +esp_err_t veil_ris_controller_init(const veil_ris_controller_cfg_t *cfg); + +/* Compute the next keyed configuration bitmap and clock it to the surface. + * `out_bits` (optional, may be NULL) receives the packed bitmap for tests. + * `out_len` is the byte length of `out_bits` on input. The bit pattern is + * derived purely from `veil_rng` + the PrivISAC two-state assignment, so it is + * reproducible from (key, step_index). */ +esp_err_t veil_ris_controller_step(uint8_t *out_bits, size_t out_len); + +/* Start/stop a periodic timer that calls _step() every dwell_us. */ +esp_err_t veil_ris_controller_start(void); +esp_err_t veil_ris_controller_stop(void); + +/* Monotonic count of configurations applied since init (telemetry/tests). */ +uint64_t veil_ris_controller_step_count(void); + +#ifdef __cplusplus +} +#endif + +#endif /* VEIL_RIS_CONTROLLER_H */ diff --git a/wifi-veil/firmware/esp32/veil_ris_controller/veil_ris_controller.c b/wifi-veil/firmware/esp32/veil_ris_controller/veil_ris_controller.c new file mode 100644 index 00000000..6d01f22e --- /dev/null +++ b/wifi-veil/firmware/esp32/veil_ris_controller/veil_ris_controller.c @@ -0,0 +1,196 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * veil_ris_controller — see veil_ris_controller.h. + * + * STATUS: SYNTHETIC / L0. Build-only skeleton. Never run on silicon; no RIS + * hardware exists here. Hardware-touching paths are marked TODO(hw). The keyed + * bitmap generator (pure math over veil_rng) is fully implemented and testable + * off target; the GPIO/SPI clock-out is stubbed. + * + * Compliance: the ESP32 only toggles control pins of a *passive* external + * surface. It emits no RF and does not transmit into any band. The surface + * re-reflects ambient energy; it does not add energy or occupy spectrum, which + * is what keeps this on the compliant side of the jamming line. (A powered, + * amplifying, or spectrum-occupying surface would NOT be compliant and is out + * of scope.) + */ +#include "veil_ris_controller.h" + +#include + +#include "esp_log.h" +#include "esp_timer.h" +#include "driver/gpio.h" +#include "driver/spi_master.h" + +#include "veil_shield.h" /* portable core: veil_rng, veil_rng_next_u64/_f32 */ + +static const char *TAG = "veil_ris"; + +static veil_ris_controller_cfg_t s_cfg; +static bool s_inited; +static uint64_t s_step; /* configurations applied so far */ +static esp_timer_handle_t s_timer; + +/* ---- keyed configuration generator (pure, testable off-target) ----------- */ + +/* PrivISAC two-state assignment: every element has two candidate phase states + * (A/B) designed offline so the *comm-direction* array response is ~invariant + * under A<->B while the *sensing-direction* response changes. At runtime we + * only pick, per element, which of the two states is active this step. That + * choice is the single bit we clock out. Drawing the bits from the keyed + * veil_rng makes the whole schedule reproducible from (key, step_index) and + * shareable with an authorized receiver. + * + * `step_index` seeds a per-step substream so any step can be regenerated + * without replaying history (matches the core's deterministic style). + * Fills `bits` (packed MSB-first) with n_elements selection bits. */ +void veil_ris_gen_bits(uint64_t key, uint64_t step_index, + size_t n_elements, uint8_t *bits, size_t bits_len) +{ + if (!bits || bits_len == 0) { + return; + } + memset(bits, 0, bits_len); + + veil_rng r; + /* Mix the step index into the key so each dwell gets an independent draw + * while staying a pure function of (key, step_index). */ + veil_rng_seed(&r, key ^ (step_index * 0x9E3779B97F4A7C15ULL)); + + for (size_t e = 0; e < n_elements; e++) { + size_t byte = e >> 3; + if (byte >= bits_len) { + break; + } + /* Top bit of the draw selects state B (1) vs state A (0). */ + uint64_t w = veil_rng_next_u64(&r); + if (w >> 63) { + bits[byte] |= (uint8_t)(0x80u >> (e & 7)); + } + } +} + +/* ---- interface clock-out (stubs) ----------------------------------------- */ + +static esp_err_t veil_ris_write(const uint8_t *bits, size_t bits_len) +{ + switch (s_cfg.iface) { + case VEIL_RIS_IFACE_GPIO: + /* TODO(hw): for each element e, set its pin to the selected state. + * for (size_t e = 0; e < s_cfg.n_elements; e++) { + * int level = (bits[e >> 3] >> (7 - (e & 7))) & 1; + * gpio_set_level(s_cfg.gpio_pins[e], level); + * } + * Requires each pin configured as output in _init(). Unverified. */ + ESP_LOGD(TAG, "TODO(hw) GPIO write %u bits (stub)", + (unsigned)s_cfg.n_elements); + return ESP_ERR_NOT_SUPPORTED; + case VEIL_RIS_IFACE_SPI: + /* TODO(hw): shift the packed bitmap to the surface driver IC. + * spi_transaction_t t = { + * .length = bits_len * 8, + * .tx_buffer = bits, + * }; + * spi_device_transmit(s_spi_dev, &t); // then latch via CS + * s_spi_dev created in _init() via spi_bus_add_device(). Unverified. */ + ESP_LOGD(TAG, "TODO(hw) SPI write %u bytes (stub)", (unsigned)bits_len); + return ESP_ERR_NOT_SUPPORTED; + default: + return ESP_ERR_INVALID_ARG; + } +} + +/* ---- public API ---------------------------------------------------------- */ + +esp_err_t veil_ris_controller_init(const veil_ris_controller_cfg_t *cfg) +{ + if (!cfg || cfg->n_elements == 0) { + return ESP_ERR_INVALID_ARG; + } + if (s_inited) { + return ESP_ERR_INVALID_STATE; + } + s_cfg = *cfg; + s_step = 0; + + if (s_cfg.iface == VEIL_RIS_IFACE_GPIO) { + /* TODO(hw): configure each s_cfg.gpio_pins[e] as GPIO_MODE_OUTPUT via + * gpio_config() (build a pin_bit_mask over all elements). */ + ESP_LOGW(TAG, "TODO(hw) configure %u GPIO element pins (stub)", + (unsigned)s_cfg.n_elements); + } else { + /* TODO(hw): spi_bus_initialize(s_cfg.spi_host, &buscfg, ...) + + * spi_bus_add_device(s_cfg.spi_host, &devcfg, &s_spi_dev). */ + ESP_LOGW(TAG, "TODO(hw) init SPI host %d @ %d Hz (stub)", + s_cfg.spi_host, s_cfg.spi_clock_hz); + } + + s_inited = true; + ESP_LOGI(TAG, "init (SYNTHETIC/L0): %u elements, dwell=%uus, keyed schedule", + (unsigned)s_cfg.n_elements, (unsigned)s_cfg.dwell_us); + return ESP_OK; +} + +esp_err_t veil_ris_controller_step(uint8_t *out_bits, size_t out_len) +{ + if (!s_inited) { + return ESP_ERR_INVALID_STATE; + } + /* Bounded, malloc-free scratch: cap at 256 elements (32 bytes) for the + * skeleton. Larger surfaces would stream in chunks. */ + enum { VEIL_RIS_MAX_BYTES = 32 }; + uint8_t bits[VEIL_RIS_MAX_BYTES]; + size_t need = (s_cfg.n_elements + 7) / 8; + if (need > sizeof bits) { + need = sizeof bits; + } + + veil_ris_gen_bits(s_cfg.key, s_step, s_cfg.n_elements, bits, need); + esp_err_t err = veil_ris_write(bits, need); /* stub on host/no-hw */ + s_step++; + + if (out_bits && out_len) { + size_t n = out_len < need ? out_len : need; + memcpy(out_bits, bits, n); + } + /* NOT_SUPPORTED from the stubbed writer is expected off-silicon; surface + * the generator result as OK so tests can validate the keyed bitmap. */ + return (err == ESP_ERR_NOT_SUPPORTED) ? ESP_OK : err; +} + +static void veil_ris_timer_cb(void *arg) +{ + (void)arg; + (void)veil_ris_controller_step(NULL, 0); +} + +esp_err_t veil_ris_controller_start(void) +{ + if (!s_inited) { + return ESP_ERR_INVALID_STATE; + } + /* TODO(hw): a real deployment would gate this on the sensing detector's + * engage trigger so the surface only churns during a sensing burst. */ + const esp_timer_create_args_t args = { + .callback = veil_ris_timer_cb, + .name = "veil_ris", + }; + esp_err_t err = esp_timer_create(&args, &s_timer); + if (err != ESP_OK) { + return err; + } + return esp_timer_start_periodic(s_timer, s_cfg.dwell_us); +} + +esp_err_t veil_ris_controller_stop(void) +{ + if (s_timer) { + esp_timer_stop(s_timer); + esp_timer_delete(s_timer); + s_timer = NULL; + } + return ESP_OK; +} + +uint64_t veil_ris_controller_step_count(void) { return s_step; } diff --git a/wifi-veil/firmware/esp32/veil_sensing_detector/CMakeLists.txt b/wifi-veil/firmware/esp32/veil_sensing_detector/CMakeLists.txt new file mode 100644 index 00000000..29fdf284 --- /dev/null +++ b/wifi-veil/firmware/esp32/veil_sensing_detector/CMakeLists.txt @@ -0,0 +1,19 @@ +# veil_sensing_detector — ESP-IDF component (SYNTHETIC / L0, build-only) +# +# Estimates the 802.11 sensing-solicitation rate from the ESP32 CSI callback +# and raises a trigger (GPIO / MQTT / ESP-NOW) that engages the AP-side VEIL +# shield. This component only READS the channel; it never shapes RF. See the +# subdir README.md for the honest capability boundary. +# +# NOTE: This is a build-only skeleton. It has never run on silicon. All +# hardware-touching paths are marked TODO(hw). + +idf_component_register( + SRCS "veil_sensing_detector.c" + INCLUDE_DIRS "include" + # esp_wifi: esp_wifi_set_csi_rx_cb / esp_wifi_set_csi / promiscuous. + # The MQTT and ESP-NOW trigger backends are optional; they are only + # referenced under CONFIG_ guards so the core build stays minimal. + REQUIRES esp_wifi esp_event esp_timer esp_driver_gpio + PRIV_REQUIRES mqtt +) diff --git a/wifi-veil/firmware/esp32/veil_sensing_detector/include/veil_sensing_detector.h b/wifi-veil/firmware/esp32/veil_sensing_detector/include/veil_sensing_detector.h new file mode 100644 index 00000000..c66d17fa --- /dev/null +++ b/wifi-veil/firmware/esp32/veil_sensing_detector/include/veil_sensing_detector.h @@ -0,0 +1,88 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * veil_sensing_detector — detect 802.11 sensing solicitation and raise a + * trigger that engages the AP-side VEIL shield. + * + * STATUS: SYNTHETIC / L0. Build-only ESP-IDF component skeleton. Never flashed, + * never captured on silicon. Do NOT claim runtime behavior without a captured + * hardware log (CLAUDE.md hardware-evidence rule). + * + * ROLE (honest): the ESP32 is a passive CSI *observer* here. It watches how + * often it is being sounded / probed (NDP announcements, action frames, and the + * cadence of incoming CSI-bearing frames) and, when that rate crosses a + * threshold, tells a *separate* protector (the AP running the veil_shield core) + * that a sensing burst is in progress. The ESP32 does NOT modify any waveform + * and does NOT protect its own beamforming feedback (see README.md). This is + * the strongest, clearly-compliant supporting role for the ESP32. + */ +#ifndef VEIL_SENSING_DETECTOR_H +#define VEIL_SENSING_DETECTOR_H + +#include +#include +#include "esp_err.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* How the detector announces "sensing burst detected" to the protector. */ +typedef enum { + VEIL_TRIGGER_GPIO = 0, /* drive a GPIO line to a co-located AP / relay */ + VEIL_TRIGGER_MQTT, /* publish to a broker the AP subscribes to */ + VEIL_TRIGGER_ESPNOW, /* connectionless ESP-NOW unicast to the AP node */ +} veil_trigger_backend_t; + +typedef struct { + /* Sliding-window length for the solicitation-rate estimate, milliseconds. */ + uint32_t window_ms; + /* Solicitations/second above which the shield should be engaged. */ + float trigger_rate_hz; + /* Hysteresis: rate must fall below this to clear the trigger. */ + float release_rate_hz; + + veil_trigger_backend_t backend; + + /* GPIO backend. */ + int gpio_num; /* output line; active-high engage */ + + /* MQTT backend. broker_uri/topic are borrowed, must outlive the detector. */ + const char *mqtt_broker_uri; /* e.g. "mqtts://ap.local:8883" */ + const char *mqtt_topic; /* e.g. "veil/engage" */ + + /* ESP-NOW backend. */ + uint8_t espnow_peer[6]; /* AP node MAC */ +} veil_sensing_detector_cfg_t; + +/* Sensible SYNTHETIC defaults (not silicon-validated). */ +#define VEIL_SENSING_DETECTOR_DEFAULT_CFG() \ + (veil_sensing_detector_cfg_t){ \ + .window_ms = 1000, \ + .trigger_rate_hz = 20.0f, \ + .release_rate_hz = 5.0f, \ + .backend = VEIL_TRIGGER_GPIO, \ + .gpio_num = -1, \ + .mqtt_broker_uri = NULL, \ + .mqtt_topic = "veil/engage", \ + .espnow_peer = {0}, \ + } + +/* Install the CSI callback + configured trigger backend. Enables promiscuous + * CSI capture. Returns ESP_OK on successful *registration* only — this says + * nothing about on-air behavior. */ +esp_err_t veil_sensing_detector_start(const veil_sensing_detector_cfg_t *cfg); + +/* Tear down callback + backend. */ +esp_err_t veil_sensing_detector_stop(void); + +/* Last estimated solicitation rate (Hz), for telemetry/tests. */ +float veil_sensing_detector_rate_hz(void); + +/* True while the engage trigger is asserted. */ +bool veil_sensing_detector_engaged(void); + +#ifdef __cplusplus +} +#endif + +#endif /* VEIL_SENSING_DETECTOR_H */ diff --git a/wifi-veil/firmware/esp32/veil_sensing_detector/veil_sensing_detector.c b/wifi-veil/firmware/esp32/veil_sensing_detector/veil_sensing_detector.c new file mode 100644 index 00000000..08b5997c --- /dev/null +++ b/wifi-veil/firmware/esp32/veil_sensing_detector/veil_sensing_detector.c @@ -0,0 +1,188 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * veil_sensing_detector — see veil_sensing_detector.h. + * + * STATUS: SYNTHETIC / L0. Build-only skeleton. Never run on silicon. Every + * hardware-touching path is marked TODO(hw). The rate estimator (pure math over + * timestamps) is the only fully-implemented piece and is unit-testable off + * target; the RF/observe path and the trigger backends are stubs. + * + * Compliance: this component only READS the channel (CSI + frame cadence). It + * emits no RF and shapes no waveform. It cannot and does not touch the closed + * ESP32 Wi-Fi PHY blob. The "action" it takes is a low-rate control signal to a + * separate protector. + */ +#include "veil_sensing_detector.h" + +#include + +#include "esp_log.h" +#include "esp_timer.h" +#include "esp_wifi.h" /* esp_wifi_set_csi_rx_cb, esp_wifi_set_csi, ... */ +#include "esp_wifi_types.h" /* wifi_csi_info_t, wifi_csi_config_t */ +#include "driver/gpio.h" /* gpio_config, gpio_set_level */ + +static const char *TAG = "veil_sense"; + +/* ---- module state -------------------------------------------------------- */ + +static veil_sensing_detector_cfg_t s_cfg; +static bool s_running; +static bool s_engaged; +static float s_rate_hz; + +/* Bounded ring of recent solicitation timestamps (µs), malloc-free. */ +enum { VEIL_TS_RING = 256 }; +static int64_t s_ts[VEIL_TS_RING]; +static size_t s_ts_head; /* next write slot */ +static size_t s_ts_count; /* live entries, capped at VEIL_TS_RING */ + +/* ---- rate estimator (pure, testable off-target) -------------------------- */ + +/* Record one solicitation at time `now_us` and recompute the sliding-window + * rate. Returns the current rate in Hz. This function is deliberately free of + * any ESP-IDF dependency so it can be exercised in host unit tests. */ +float veil_sd_note_solicitation(int64_t now_us) +{ + s_ts[s_ts_head] = now_us; + s_ts_head = (s_ts_head + 1) % VEIL_TS_RING; + if (s_ts_count < VEIL_TS_RING) { + s_ts_count++; + } + + const int64_t window_us = (int64_t)s_cfg.window_ms * 1000; + const int64_t cutoff = now_us - window_us; + + size_t in_window = 0; + for (size_t k = 0; k < s_ts_count; k++) { + if (s_ts[k] >= cutoff) { + in_window++; + } + } + /* rate = events within the trailing window / window length. */ + s_rate_hz = (float)in_window * 1000.0f / (float)s_cfg.window_ms; + + /* Hysteresis around engage/release. */ + if (!s_engaged && s_rate_hz >= s_cfg.trigger_rate_hz) { + s_engaged = true; + ESP_LOGI(TAG, "sensing burst: %.1f Hz >= %.1f -> ENGAGE", + s_rate_hz, s_cfg.trigger_rate_hz); + /* fire-and-forget; backend errors are logged, not fatal */ + (void)0; /* veil_sd_emit_trigger(true) — see below */ + } else if (s_engaged && s_rate_hz <= s_cfg.release_rate_hz) { + s_engaged = false; + ESP_LOGI(TAG, "sensing quiet: %.1f Hz <= %.1f -> RELEASE", + s_rate_hz, s_cfg.release_rate_hz); + } + return s_rate_hz; +} + +/* ---- trigger backends (all stubs) ---------------------------------------- */ + +static esp_err_t veil_sd_emit_trigger(bool engage) +{ + switch (s_cfg.backend) { + case VEIL_TRIGGER_GPIO: + /* TODO(hw): drive the engage line to the co-located AP/relay. + * gpio_set_level(s_cfg.gpio_num, engage ? 1 : 0); + * Requires a wired GPIO to the protector; unverified on silicon. */ + ESP_LOGW(TAG, "TODO(hw) GPIO trigger -> %d (stub)", engage); + return ESP_ERR_NOT_SUPPORTED; + case VEIL_TRIGGER_MQTT: + /* TODO(hw): esp_mqtt_client_publish(client, s_cfg.mqtt_topic, + * engage ? "1" : "0", 0, 1 /qos/, 0 /retain/); + * Client lifecycle (esp_mqtt_client_init/_start) omitted from skeleton. */ + ESP_LOGW(TAG, "TODO(hw) MQTT trigger -> %d (stub)", engage); + return ESP_ERR_NOT_SUPPORTED; + case VEIL_TRIGGER_ESPNOW: + /* TODO(hw): esp_now_send(s_cfg.espnow_peer, &payload, sizeof payload); + * Requires esp_now_init() + esp_now_add_peer() during start(). */ + ESP_LOGW(TAG, "TODO(hw) ESP-NOW trigger -> %d (stub)", engage); + return ESP_ERR_NOT_SUPPORTED; + default: + return ESP_ERR_INVALID_ARG; + } +} + +/* ---- CSI callback (observe path) ----------------------------------------- */ + +/* Runs in the Wi-Fi task. Keep it short: post to a queue in real firmware. + * Here we only classify whether this frame indicates a sounding/solicitation + * and, if so, feed the estimator. */ +static void veil_sd_csi_cb(void *ctx, wifi_csi_info_t *info) +{ + (void)ctx; + if (!info) { + return; + } + /* TODO(hw): a real classifier would inspect info->rx_ctrl (rate, sig_mode, + * channel, secondary channel) and, alongside a promiscuous frame-type + * filter, distinguish NDP / NDP-announcement / CSI-solicit action frames + * from ordinary data. On silicon the ESP32 does NOT surface the raw + * VHT/HE sounding subtype through the CSI struct, so this classifier is + * necessarily heuristic (cadence + rate + frame length). Treated here as + * "every CSI-bearing frame is a candidate solicitation" for the skeleton. */ + (void)veil_sd_note_solicitation(esp_timer_get_time()); +} + +/* ---- lifecycle ----------------------------------------------------------- */ + +esp_err_t veil_sensing_detector_start(const veil_sensing_detector_cfg_t *cfg) +{ + if (!cfg) { + return ESP_ERR_INVALID_ARG; + } + if (s_running) { + return ESP_ERR_INVALID_STATE; + } + s_cfg = *cfg; + s_engaged = false; + s_rate_hz = 0.0f; + s_ts_head = 0; + s_ts_count = 0; + + if (s_cfg.backend == VEIL_TRIGGER_GPIO && s_cfg.gpio_num >= 0) { + /* TODO(hw): configure the engage line. + * gpio_config_t io = { + * .pin_bit_mask = 1ULL << s_cfg.gpio_num, + * .mode = GPIO_MODE_OUTPUT, + * }; + * gpio_config(&io); + * gpio_set_level(s_cfg.gpio_num, 0); + */ + ESP_LOGW(TAG, "TODO(hw) configure GPIO %d (stub)", s_cfg.gpio_num); + } + + /* Observe path. On real hardware: + * wifi_csi_config_t csi = { ... }; + * ESP_ERROR_CHECK(esp_wifi_set_csi_config(&csi)); + * ESP_ERROR_CHECK(esp_wifi_set_csi_rx_cb(veil_sd_csi_cb, NULL)); + * ESP_ERROR_CHECK(esp_wifi_set_csi(true)); + * ESP_ERROR_CHECK(esp_wifi_set_promiscuous(true)); // more CSI when idle + * The Wi-Fi driver must already be started by the app. */ + ESP_LOGW(TAG, "TODO(hw) esp_wifi_set_csi_rx_cb/_set_csi/_set_promiscuous " + "(stub; not wired on silicon)"); + (void)veil_sd_csi_cb; /* referenced once wired */ + + s_running = true; + ESP_LOGI(TAG, "started (SYNTHETIC/L0): window=%ums engage>=%.1fHz", + (unsigned)s_cfg.window_ms, s_cfg.trigger_rate_hz); + return ESP_OK; +} + +esp_err_t veil_sensing_detector_stop(void) +{ + if (!s_running) { + return ESP_ERR_INVALID_STATE; + } + /* TODO(hw): esp_wifi_set_csi(false); esp_wifi_set_csi_rx_cb(NULL, NULL); + * esp_wifi_set_promiscuous(false); release GPIO/MQTT/ESP-NOW. */ + if (s_engaged) { + (void)veil_sd_emit_trigger(false); + } + s_running = false; + return ESP_OK; +} + +float veil_sensing_detector_rate_hz(void) { return s_rate_hz; } +bool veil_sensing_detector_engaged(void) { return s_engaged; } diff --git a/wifi-veil/firmware/nexmon/BUILD.md b/wifi-veil/firmware/nexmon/BUILD.md new file mode 100644 index 00000000..16fd7a8b --- /dev/null +++ b/wifi-veil/firmware/nexmon/BUILD.md @@ -0,0 +1,116 @@ +# Building the WiFi Veil Nexmon patch — **UNTESTED** + +> **This procedure has never been run.** It has not been built with the Nexmon +> toolchain, not flashed, and not captured on air. Addresses/symbols in +> `patch/veil_patch.c` are placeholders (one is intentionally invalid, +> `0xDEAD0000`) so it will **not** produce a flashable image as-is. This file +> documents *how it would build* so a hardware operator with real silicon can +> take it forward. `SYNTHETIC / L0`, per CLAUDE.md. + +## Prerequisites (host, not in this repo) + +- A Linux host (Nexmon expects an x86_64 Ubuntu-like build host) with the + Broadcom-flavored ARM toolchain Nexmon downloads/uses, plus `git`, `make`, + `gcc-arm-none-eabi`, `flex`, `bison`, `libisl`, `automake`. +- Nexmon checked out **outside** this repo (do not vendor it here): + ```bash + git clone https://github.com/seemoo-lab/nexmon.git + cd nexmon + source setup_env.sh # sets NEXMON_ROOT, toolchain paths + make # builds libISL / firmwares tooling + ``` +- The target firmware blob present on the device: BCM43455c0 + (`brcmfmac43455-sdio.bin`), version **7_45_189** (Cypress) or 7_45_154 + (Raspbian). Do **not** commit the blob or any extracted symbols/ROM to RuView. + +## Where this patch would live in the Nexmon tree + +Nexmon builds per chip/firmware under `patches////`. This +adapter would be a Nexmon project, e.g.: + +``` +$NEXMON_ROOT/patches/bcm43455c0/7_45_189/veil/ +├── Makefile # copy of an existing nexmon patch Makefile (e.g. nexmon_csi's) +├── src/ +│ ├── veil_patch.c # <- symlink/copy of firmware/privshield/nexmon/patch/veil_patch.c +│ ├── veil_shield.c # <- from firmware/privshield/core/ (compiled into the patch) +│ └── veil_shield.h # <- from firmware/privshield/core/ +└── ... +``` + +Keep the RuView copies canonical; the Nexmon tree gets copies/symlinks so the +core stays byte-identical to `../core/`. + +## Linking the portable core (MCU-friendly) + +The core is `no_std`-style C99: no malloc, no libc I/O, only `` +(`sinf`/`cosf`/`sqrtf`/`sqrt`). To build it into the patch: + +1. Add `veil_shield.c` to the patch `Makefile`'s object list (alongside + `patch.o`/`wrapper.o`), so it compiles with the same ARM flags. +2. Ensure the firmware provides `sinf`/`cosf`/`sqrtf`. **TODO(hw):** Broadcom + firmware may not export libm. Options, in order of preference: + - link a small `libm`/`compiler-rt` for `arm-none-eabi`; + - or replace the trig with a fixed-point / CORDIC Givens rotation + (`TODO(reverse-engineer)`), which also avoids float on parts without an FPU. +3. All WiFi Veil working storage is stack-bounded (`VEIL_MAX_FINE`, `CACHE` in the + core) — no heap is introduced on-chip. + +## Build + +```bash +cd $NEXMON_ROOT/patches/bcm43455c0/7_45_189/veil +make # produces the patched brcmfmac43455-sdio.bin +``` + +Before `make` can succeed you must first resolve every `TODO(reverse-engineer)` +in `veil_patch.c`: + +- replace `0xDEAD0000` and the `wlc_sendmgmt_veil_target` symbol with the real, + disassembled target address/symbol for 7_45_189; +- implement `veil_bfr_unpack_fine` / `veil_bfr_pack_fine` (the angle bit-field + codec) and the report-body offset/length; +- confirm the compressed-beamforming report is assembled in ARM on this chip + (else move to hook candidate #2/#3 — see README). + +## Flash (Raspberry Pi, on-device) + +**TODO(hw) — untested.** Typical Nexmon flow on the Pi: + +```bash +# back up stock firmware first! +sudo cp /lib/firmware/brcm/brcmfmac43455-sdio.bin ~/brcmfmac43455-sdio.bin.orig + +sudo cp brcmfmac43455-sdio.bin /lib/firmware/brcm/brcmfmac43455-sdio.bin +# (some setups also need the matching *.clm_blob / nexmon's own copy path) + +sudo rmmod brcmfmac && sudo modprobe brcmfmac # reload driver with new firmware +dmesg | tail # confirm firmware loaded +``` + +Push the session key at runtime (matches the IOCTL stub in `veil_patch.c`): + +```bash +# TODO(hw): nexutil vendor-IOCTL id and payload format are placeholders +nexutil -s -b -l8 -v +``` + +**Recovery:** if WiFi breaks, restore the backup blob and reload the driver. +A bad flashpatch offset can knock out WiFi until you reflash stock firmware. + +## Validation you can honestly do (still not `MEASURED` firmware) + +1. **Host unit test of the math** (already green in this repo): + `cd ../../core && make test`. +2. **Read-back on hardware** with `nexmon_csi`/Wi-BFI: capture the report with + and without the patch and check the fine subspace changed while SNR/norm is + preserved. This validates the transform end-to-end but is a *receiver* + observation, not proof the TX hook is robust. +3. Only a captured device runtime log showing the shaped report leaving *this* + node, plus receiver-side recovery with the shared key, would move any claim + from `SYNTHETIC`/`CLAIMED` toward `MEASURED` (roadmap P5). + +## References + +See `README.md` for sources (Nexmon, nexmon_csi, Wi-BFI, D11 reverse +engineering). diff --git a/wifi-veil/firmware/nexmon/README.md b/wifi-veil/firmware/nexmon/README.md new file mode 100644 index 00000000..40c80df0 --- /dev/null +++ b/wifi-veil/firmware/nexmon/README.md @@ -0,0 +1,124 @@ +# WiFi Veil protector — Nexmon (Broadcom/Cypress) path + +C-firmware-patch adapter that would call the portable WiFi Veil core +(`../core/veil_shield.{h,c}`) on the compressed-beamforming-feedback **angles +before transmission**, using the [Nexmon](https://github.com/seemoo-lab/nexmon) +patching framework on a Broadcom/Cypress WiFi chip. + +> **Evidence discipline.** Everything here is **`SYNTHETIC` / L0 / build-only**. +> Nothing in this directory has been built with the Nexmon toolchain, flashed to +> a chip, or captured on air. There are **no** `MEASURED` claims and **no** +> hardware logs. The patch is an honest **skeleton** with `TODO(hw)` and +> `TODO(reverse-engineer)` markers, not working firmware. Per CLAUDE.md, no +> defense claim becomes `MEASURED` without a captured runtime log from real +> silicon (roadmap P5). +> +> **Compliant waveform only — never jamming.** The core applies an *orthogonal* +> (energy-preserving) keyed rotation to the node's *own* standards-conformant +> feedback report. It does not add power, transmit out of turn, or interfere +> with any other station. + +## Feasibility grade: **C** (research-grade, partial, unproven) + +| Sub-path | Grade | Why | +|---|---|---| +| **Read** the compressed BF feedback | **A** (proven by others) | `nexmon_csi` extracts CSI, and Wi-BFI parses the compressed-beamforming *angles* straight from captured action frames — no firmware change at all. The report content is observable today. | +| **Write / shape** the transmitted report | **C / C-** | The report is generated by the proprietary **D11** real-time core, not the ARM firmware Nexmon comfortably patches. The hook point is deep, chip- and firmware-version-specific, and unverified here. Plausible, not demonstrated. | + +Grade **C** reflects *this* deliverable's goal — shaping the **TX** report. The +read side is a solved problem and is graded only to contrast honestly. + +### Why the write path is hard (the core honesty point) + +Broadcom/Cypress chips put all time-critical 802.11 MAC/PHY work on the **D11 +core**, a proprietary microcontroller running a programmable state machine +("ucode"). Published reverse-engineering of these chips reports that the D11 +generates the **VHT/HE compressed beamforming report ~10 µs after the NDP**, with +its contents fetched from an **internal memory updated directly by the hardware** +on NDP reception. In other words, the angles WiFi Veil wants to touch are staged and +emitted inside the ucode/PHY path on a microsecond deadline — *below* the ARM +"wl" driver firmware where Nexmon's C hooks (`__attribute__((at(addr, ...)))` +flashpatches / branch hooks) live most reliably. Reaching them means either a +D11-ucode patch (needs the D11 assembler and SHM/template-RAM layout) or catching +the report while the ARM path still assembles the action-frame body — if it does +so on this chip at all. Both are `TODO(reverse-engineer)`. + +## Target chip(s) + +Primary: **BCM43455c0** (Raspberry Pi 3B+/4B; also RPi Zero 2 W), firmware +**7_45_154** (Raspbian) or **7_45_189** (Cypress) — the best-documented, +most-reproducible Nexmon target, and one of the four chips `nexmon_csi` already +supports. Secondary candidates that `nexmon_csi` also supports: **BCM4339** +(Nexus 5), **BCM4358** (Nexus 6P), **BCM4366c0** (Asus RT-AC86U). We scope the +skeleton to BCM43455c0 / 7_45_189 and leave the others as build-matrix `TODO`s. + +Caveat: the RPi BCM43455c0 is an **802.11ac (VHT)** single-stream part; its own +*transmit* beamforming/sounding activity as a beamformee is limited. The +skeleton targets the **VHT compressed beamforming report** action-frame path; +whether this chip emits enough to shape in practice is itself a `TODO(hw)` +question. + +## Hook-point candidates (all `TODO(reverse-engineer)`) + +Ordered most-tractable → deepest. Addresses are **placeholders** — real offsets +come from disassembling the specific firmware blob and cross-checking the Nexmon +symbol tables (`wl_ram.elf` / IDA); none are known-good here. + +1. **ARM action-frame TX assembly (best first target).** If the "wl" driver + assembles the VHT Compressed Beamforming Report action-frame *body* in ARM + firmware before handing it to the D11 (function family around + `wlc_txbf_*` / a `wlc_send*mgmt`/action path), a branch hook there could + locate the report's fine-angle block and call `veil_shield_apply` in place. + Cheapest if it exists on this chip. +2. **ARM → D11 TX descriptor / template handoff.** Hook where the driver stages + a frame into the D11 TX FIFO / template RAM (`wlc_d11hdrs` / `wlc_txfifo` + region) and rewrite the angle bytes there. Requires knowing the exact + template-RAM offset of the report body. +3. **D11 ucode patch (deepest).** Patch the ucode routine that copies angles + from the hardware-updated internal memory into the outgoing report, applying + the rotation in D11 SHM. Needs the D11 assembler and PHY/SHM map; highest + fidelity, highest effort, most fragile across firmware versions. + +The skeleton wires candidate **#1** and leaves #2/#3 documented but unimplemented. + +## What is realistic + +- **Realistic now:** verify WiFi Veil's *effect* by reading — capture the shaped vs. + unshaped report with `nexmon_csi`/Wi-BFI and confirm the fine subspace changed + while energy (SNR/norm) is preserved. This validates the math, not the TX hook. +- **Realistic with serious RE effort:** candidate #1, on one pinned firmware, as + a demo — partial, brittle, chip-specific. +- **Not realistic as a portable product:** a clean, firmware-version-stable TX + report-shaping patch across Broadcom parts. Treat as research. + +## Risk / honesty + +- Wrong flashpatch offsets can **brick the WiFi blob** (recoverable by + reflashing stock firmware, but real). +- Regulatory: the transform is energy-preserving and rides standards-marked + spatial-mapping freedom, but any TX-path firmware patch on a certified radio is + **outside the device's certification** — bench/anechoic use only. +- Firmware blobs are proprietary; do **not** commit extracted firmware, symbols, + or ROM dumps to this repo. + +## Sources + +- Nexmon framework — +- `nexmon_csi` (chips: bcm4339, bcm43455c0, bcm4358, bcm4366c0) — + +- Wi-BFI (reads BFAs/BFI from captured compressed-beamforming action frames) — + , paper arXiv:2309.04408 + +- BCM43455c0 patches / D11 headers (`d11.h`) — + +- D11 real-time core / ucode reverse engineering (SEEMOO, Quarkslab) — + , + +- 802.11ac VHT NDP sounding & compressed beamforming report structure (context) — + + +> The "~10 µs / hardware-updated internal memory" characterization above is drawn +> from published Broadcom D11 reverse-engineering (reported for BCM4365-class +> parts) and is used here as design guidance; it is **not** independently +> verified on BCM43455c0 in this repo. `TODO(reverse-engineer)`: confirm on the +> target blob. diff --git a/wifi-veil/firmware/nexmon/patch/veil_patch.c b/wifi-veil/firmware/nexmon/patch/veil_patch.c new file mode 100644 index 00000000..cf268341 --- /dev/null +++ b/wifi-veil/firmware/nexmon/patch/veil_patch.c @@ -0,0 +1,176 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * veil_patch.c — VEIL protector, Nexmon (Broadcom/Cypress) path. + * + * ============================ HONESTY BANNER ============================ + * SYNTHETIC / L0 / BUILD-ONLY. This file is an HONEST SKELETON in Nexmon + * style. It has NOT been built with the Nexmon toolchain, NOT flashed to a + * chip, and NOT captured on air. Every __attribute__((at(...))) address and + * every firmware symbol below is a PLACEHOLDER. Do not treat this as working + * firmware. See ../README.md for the feasibility grade (C, research-grade). + * + * Goal: call the portable VEIL core (../../core/veil_shield.c) + * `veil_shield_apply()` on the compressed-beamforming-feedback FINE ANGLES in + * the transmitted VHT/HE compressed beamforming report, so the identity-bearing + * fine subspace is obfuscated by a keyed, ENERGY-PRESERVING (orthogonal) + * Givens rotation before the frame leaves the radio. Compliant only, never + * jamming: the transform preserves the report's L2 norm. + * + * Target: BCM43455c0 (Raspberry Pi 3B+/4B), firmware 7_45_189. Others TODO. + * ======================================================================= + */ + +#pragma NEXMON targetregion "patch" + +#include /* FW_VER_7_45_189, CHIP_VER_BCM43455c0 (Nexmon) */ +#include /* BPatch / GPatch / __attribute__((at(...))) */ +#include /* struct sk_buff, struct wlc_info, etc. */ +#include /* Nexmon wrappers for ROM/firmware functions */ + +/* --- Portable VEIL core, linked/inlined for the MCU ------------------------- + * The core is pure C99: no malloc, no libc I/O, only (sinf/cosf/sqrtf). + * On the Nexmon ARM target we compile ../../core/veil_shield.c into this patch + * object (see ../BUILD.md) and pull in only the declarations here. Everything + * operates on a caller-provided fixed buffer — no dynamic allocation on-chip. */ +#include "veil_shield.h" + +/* ------------------------------------------------------------------------- */ +/* Configuration (compile-time; no on-chip allocation) */ +/* ------------------------------------------------------------------------- */ + +/* Max fine-angle count we will touch in one report. Sized for a VHT SU report + * fine block; bound it so all working storage is on the stack, malloc-free. */ +#define VEIL_MAX_FINE 64u + +/* Rotation passes — MUST match the associated receiver and the Rust reference + * crate default so recover() inverts exactly. TODO(hw): confirm against the + * receiver config actually deployed. */ +#define VEIL_PASSES 96u + +/* Session key. TODO(hw): DO NOT hardcode a real key in flashed firmware. Inject + * via nexutil IOCTL (see veil_ioctl_set_key stub) or a provisioning step; this + * placeholder exists only so the skeleton type-checks. */ +static uint64_t g_veil_key = 0x0000000000000000ULL; + +/* ------------------------------------------------------------------------- */ +/* Bridge: decode angles -> rotate -> re-encode, in place */ +/* ------------------------------------------------------------------------- */ +/* + * TODO(reverse-engineer): The compressed beamforming report packs the phi/psi + * angles as bit-fields whose widths depend on the codebook (VHT: (7,5) or (9,7); + * HE differs) and on Nc/Nr. The bytes handed to us are NOT plain floats. This + * bridge must: + * (1) parse the fine-angle bit-fields from `report` into `fine[]` as floats + * in the same units/order the receiver + Rust reference expect, + * (2) call veil_shield_apply() on that flat vector, + * (3) re-quantize and repack the rotated angles back into `report`, + * preserving all coarse/header fields and the frame length. + * Steps (1)/(3) are the real work and are UNIMPLEMENTED here. + */ +static void veil_shape_report_inplace(uint8_t *report, uint32_t report_len) +{ + if (report == 0 || report_len == 0) + return; + + float fine[VEIL_MAX_FINE]; + uint32_t n = 0; + + /* TODO(reverse-engineer): unpack fine-angle bit-fields -> fine[0..n) */ + /* n = veil_bfr_unpack_fine(report, report_len, fine, VEIL_MAX_FINE); */ + if (n < 2 || n > VEIL_MAX_FINE) + return; /* nothing safely shapeable; leave frame untouched (fail-open) */ + + /* Orthogonal, energy-preserving, keyed. This is the ONLY validated step. */ + veil_shield_apply(fine, (size_t)n, g_veil_key, VEIL_PASSES); + + /* TODO(reverse-engineer): repack fine[0..n) back into `report` bit-fields, + * keeping report_len and all non-fine fields byte-identical. */ + /* veil_bfr_pack_fine(report, report_len, fine, n); */ + (void)report_len; +} + +/* ------------------------------------------------------------------------- */ +/* Hook candidate #1 (see README): ARM action-frame TX assembly */ +/* ------------------------------------------------------------------------- */ +/* + * We hook the point where the "wl" driver has assembled the VHT Compressed + * Beamforming Report action frame in an sk_buff, just before it is queued to + * the D11 for transmission, locate the report body, and shape it. + * + * TODO(reverse-engineer): the symbol/address below is a PLACEHOLDER. The real + * target must be found by disassembling 7_45_189 (IDA + Nexmon's wl_ram.elf + * symbol map) and confirming: (a) the report body is assembled in ARM (not + * only in D11 ucode), (b) `p` really carries a compressed-beamforming action + * frame, and (c) the offset of the report body within the frame. + * + * If (a) is false on this chip, candidate #1 is dead and we fall to #2/#3 + * (TX template-RAM rewrite / D11 ucode patch) — both documented in README, + * neither implemented here. + */ + +/* Original firmware function prototype (PLACEHOLDER signature). */ +extern int wlc_sendmgmt_veil_target(struct wlc_info *wlc, void *p, void *scb); + +/* Our replacement. GPatch/BPatch below redirects the target to this. */ +int wlc_sendmgmt_veil_hook(struct wlc_info *wlc, void *p, void *scb) +{ + /* TODO(reverse-engineer): confirm `p` is a struct sk_buff* and that this + * frame is a VHT/HE compressed beamforming action frame (category 21 + * VHT / 30 HE, action = Compressed Beamforming). Guard hard so we never + * mangle unrelated management frames. */ + struct sk_buff *skb = (struct sk_buff *)p; + if (skb != 0 /* && veil_is_bf_report_action(skb) */) { + /* TODO(reverse-engineer): compute report body pointer + length from the + * action-frame layout. PLACEHOLDER offsets: */ + uint8_t *report = 0; /* skb->data + VEIL_BFR_BODY_OFFSET; */ + uint32_t report_len = 0; /* skb->len - VEIL_BFR_BODY_OFFSET; */ + veil_shape_report_inplace(report, report_len); + } + + /* Always fall through to the real firmware routine so normal TX proceeds. */ + return wlc_sendmgmt_veil_target(wlc, p, scb); +} + +/* + * Redirect the firmware's mgmt/action TX routine to our hook. + * PLACEHOLDER ADDRESS — 0xDEAD0000 is intentionally invalid so nobody mistakes + * this for a real, flashable patch. TODO(reverse-engineer): replace with the + * verified address for CHIP_VER_BCM43455c0 / FW_VER_7_45_189. + * + * Nexmon idiom: a branch patch that overwrites the target's prologue with a + * branch to our replacement (which tail-calls the saved original). + */ +__attribute__((at(0xDEAD0000, "flashpatch", CHIP_VER_BCM43455c0, FW_VER_7_45_189))) +BPatch(veil_sendmgmt_hook, wlc_sendmgmt_veil_hook); + +/* ------------------------------------------------------------------------- */ +/* Key provisioning via nexutil IOCTL (stub) */ +/* ------------------------------------------------------------------------- */ +/* + * TODO(hw): register a custom IOCTL so `nexutil` can push the 64-bit session + * key at runtime instead of baking it into flash. Hook the driver's ioctl + * dispatch (wlc_ioctl) the same way nexmon_csi installs its config IOCTLs. + * Left as a stub: the dispatch address and the nexmon_ioctl plumbing are + * PLACEHOLDERS. + */ +#define VEIL_IOCTL_SET_KEY 0x7EIL /* TODO(hw): pick a free vendor IOCTL id */ + +int veil_ioctl_set_key(struct wlc_info *wlc, const uint8_t *buf, uint32_t len) +{ + (void)wlc; + if (buf == 0 || len < sizeof(uint64_t)) + return -1; + uint64_t k = 0; + for (uint32_t i = 0; i < sizeof(uint64_t); i++) + k |= ((uint64_t)buf[i]) << (8u * i); + g_veil_key = k; + return 0; +} + +/* + * --------------------------------------------------------------------------- + * Candidate #2 (TX template-RAM rewrite) and #3 (D11 ucode patch) are NOT + * implemented. See ../README.md "Hook-point candidates". #3 would require the + * D11 assembler and the PHY/SHM angle-staging map — deepest and most fragile. + * --------------------------------------------------------------------------- + */ diff --git a/wifi-veil/firmware/openwifi/HDL_NOTES.md b/wifi-veil/firmware/openwifi/HDL_NOTES.md new file mode 100644 index 00000000..87ec0389 --- /dev/null +++ b/wifi-veil/firmware/openwifi/HDL_NOTES.md @@ -0,0 +1,123 @@ +# HDL notes — `veil_rot` (TX) / `veil_unrot` (RX) + +> **STATUS: SYNTHETIC / L0 — design notes only. No RTL is shipped here, none has +> been synthesized, placed, routed, or run on an FPGA.** This describes the +> Verilog blocks that *would* apply the keyed unitary in the openwifi datapath. +> Every concrete number (offsets, latency, resource use) is `TODO(hdl)` until a +> real build exists. **Orthogonal transform ⇒ transmit energy preserved: +> compliant, never jamming.** + +## Where the blocks sit + +openwifi's baseband IQ moves as **AXI-Stream** between blocks and its control is +**AXI-Lite** ([FPGA module design][fmd]). The two new blocks are AXI-Stream +pass-through filters with an AXI-Lite slave for the key schedule. + +``` +TX (protector): + openofdm_tx ──AXI-S(IQ)──► [ veil_rot ] ──AXI-S(IQ)──► tx_intf ──► AD9361 DAC + ▲ AXI-Lite (key, coeff RAM) + └── veil_openwifi.c + +RX (legitimate STA, shares key): + AD9361 ADC ──► rx_intf ──AXI-S──► [ veil_unrot ] ──AXI-S──► openofdm_rx (FFT → chan est) + ▲ AXI-Lite + └── veil_openwifi.c +``` + +`veil_unrot` may equivalently sit **in the frequency domain**, right after the +FFT and **before channel estimation**, if a per-subcarrier `Q^H` is cheaper to +apply there. Same AXI-Lite contract either way. + +## Why a *new* block is required (honesty) + +openwifi is **SISO 802.11a/g/n** and has **no explicit-beamforming / spatial- +mapping stage** and **no compressed-BF-report generation** — the two-antenna app +note is RX-only capture, not a TX spatial mapper ([iq_2ant][2ant]). So there is +no existing `Q` matrix to modify; `veil_rot`/`veil_unrot` **introduce** the +spatial-mapping stage. Two realizable RTL scopes: + +- **Scope A — 1×1 per-subcarrier phase/rotation (lower effort).** Treat the + rotation as operating over a **synthetic vector** formed from the fine + subspace of the per-packet subcarrier response (a stream of `N` IQ elements + the block buffers), applying the core's Givens schedule across those elements. + Single TX chain; no board change. This is enough to *scramble the CSI a + sniffer estimates* and to demonstrate keyed invert at RX. It is **not** true + spatial MIMO. +- **Scope B — 2×2 true spatial mapping (higher effort, the A-capability demo).** + Enable the **second TX chain** (AD9361 has 2 DACs on fmcomms2/3) and apply a + keyed 2×2 unitary across the two streams — a genuine transmit spatial mapping + the standard marks "not restricted." Needs a Vivado top-level rebuild wiring + the 2nd DAC and the extra AXI-S lane. `TODO(hdl)`. + +## `veil_rot` datapath + +The core applies `passes` **Givens rotations** `G(i,j,θ)` composed into `Q` +(`../core/veil_shield.c`). In hardware we apply the *same schedule* to the on-air +sample vector, so both ends derive identical coefficients from the shared key — +no matrix is transmitted. + +Per Givens op on elements `(i, j)` with programmed `(cos, sin)` in Q1.15: +``` + v_i' = cos*v_i - sin*v_j + v_j' = sin*v_i + cos*v_j // complex IQ: apply to I and Q lanes +``` +- Coefficients arrive from `veil_openwifi.c` as the packed `(i, j, cos, sin)` + schedule (2 AXI-Lite words per pass; packing defined in `veil_openwifi.c`). +- `veil_unrot` applies the schedule **in reverse with negated sin** (`sin → -sin`, + i.e. `Gᵀ`), matching `veil_shield_recover`. A `CTRL.inverse` bit selects it. +- Fixed point: openwifi baseband IQ is 16-bit I / 16-bit Q; coeffs are signed + Q1.15. `TODO(hdl)`: guard-bit / rounding so the composed rotation stays + norm-preserving to spec and never clips (clipping would break the + energy-preservation invariant — must be verified, not assumed). + +## AXI-Lite register map (must match `veil_openwifi.c`) + +| Offset | Name | Meaning | +|---|---|---| +| `0x00` | `CTRL` | bit0 enable, bit1 inverse (`veil_unrot`), bit2 load | +| `0x04` | `KEY_LO` | session key [31:0] | +| `0x08` | `KEY_HI` | session key [63:32] | +| `0x0C` | `NDIM` | on-air fine-block dimension `N` (≤ 64) | +| `0x10` | `PASSES` | number of Givens passes (default 96) | +| `0x14` | `COEFF_ADDR` | write index into coeff RAM | +| `0x18` | `COEFF_DATA` | packed `{j,i}` then `{sin,cos}` (2 words/pass) | +| `0x1C` | `STATUS` | bit0 ready, bit1 applied, bit2 err | + +`TODO(hdl)`: regenerate this from the block's `*_s_axi.v` once written (cf. +`openofdm_tx`'s 6 AXI-Lite registers at `ip/openofdm_tx/src/openofdm_tx_s_axi.v`) +and reconcile any offset changes back into `veil_openwifi.c`. + +## Timing / integration risks (call them out, don't hide them) + +- **802.11 SIFS budget.** The block adds pipeline latency between IFFT and DAC; + it must not violate the tight TX timing openwifi maintains in `tx_intf`. + `TODO(hdl)`: measure added cycles; keep within budget or absorb in existing + FIFO slack. +- **On-FPGA schedule vs. per-packet coeff load.** For per-*packet* keying, either + compute the SplitMix64 schedule on-FPGA from `(key, packet_counter)` or + double-buffer the coeff RAM. `TODO(hdl)`. +- **Bit-exactness with the core.** The on-FPGA (or shim-fed) `(cos,sin)` must + reproduce the core's schedule so `veil_unrot` inverts exactly. First gate is a + **self-loopback** IQ test (`veil_rot → veil_unrot`, assert recovered == input + within Q1.15 round-off) using openwifi's existing packet/IQ self-loopback + facility ([self-loopback app note][loop]). Passing loopback is a correctness + gate, **not** a defense `MEASURED` claim. + +## Build + +`TODO(hdl)`: add `veil_rot`/`veil_unrot` as `openwifi-hw` IP, instantiate in the +board block design, and rebuild the bitstream with Vivado per the openwifi-hw +build flow ([openwifi-hw][hw]). No bitstream is produced from this directory. + +## Sources + +- FPGA module design (AXI-S / AXI-Lite, block roles) — [deepwiki][fmd] +- openwifi-hw (FPGA IP + build flow) — [github.com/open-sdr/openwifi-hw][hw] +- Two-antenna IQ (RX-only; confirms no TX spatial mapper ships) — [iq_2ant][2ant] +- Packet/IQ self-loopback test — [self-loopback app note][loop] + +[fmd]: https://deepwiki.com/open-sdr/openwifi/2.2-fpga-module-design +[hw]: https://github.com/open-sdr/openwifi-hw +[2ant]: https://github.com/open-sdr/openwifi/blob/master/doc/app_notes/iq_2ant.md +[loop]: https://github.com/open-sdr/openwifi/blob/master/doc/app_notes/packet-iq-self-loopback-test.md diff --git a/wifi-veil/firmware/openwifi/MEASUREMENT.md b/wifi-veil/firmware/openwifi/MEASUREMENT.md new file mode 100644 index 00000000..f2ef3683 --- /dev/null +++ b/wifi-veil/firmware/openwifi/MEASUREMENT.md @@ -0,0 +1,103 @@ +# P5 measurement protocol — openwifi WiFi Veil end-to-end + +> **STATUS: SYNTHETIC / L0 — this is a PLAN, not a result. No hardware has been +> run; no capture, log, or number in this repo is real.** This document defines +> exactly what must be executed and captured to earn the first `MEASURED` claim +> under CLAUDE.md's hardware-evidence rule. Until the witness artifact below +> exists, every accuracy/throughput/energy statement about openwifi WiFi Veil is +> `SYNTHETIC` and must be labelled so. **Compliant waveform controls only — +> orthogonal, energy-preserving; never jamming.** + +## Roadmap position + +This is roadmap **P5**: the two-node hardware measurement that turns the P4 +build scaffolds into a `MEASURED` defense result. Prerequisite gates (all on real +silicon, all currently unmet): a bitstream with `veil_rot`/`veil_unrot` +(`HDL_NOTES.md`), a driver loading `veil_openwifi.c`, and a passing on-FPGA +**self-loopback** correctness test. + +## Topology + +``` + [ Protector AP ] over the air [ Legitimate STA ] + openwifi node A ───────────────────────────────────► openwifi node B + veil_rot: Q(key) engaged │ veil_unrot: Q^H(key) + │ (shares key with A) + ▼ + [ Attacker sniffer ] + commodity NIC, monitor mode + Wi-BFI CSI/BF-feedback extraction + + re-ID model +``` + +The attacker is **passive** (monitor capture only). Nothing in this test +transmits to interfere with any station. + +## Hardware list + +| Role | Hardware | Software | +|---|---|---| +| Protector AP (A) | Zynq-7000 + AD9361 FMC (ZC706+fmcomms2/3, or ADRV9361-Z7035) | openwifi image + `veil_rot` bitstream + `veil_openwifi.c` | +| Legitimate STA (B) | second identical openwifi node | openwifi image + `veil_unrot` bitstream + `veil_openwifi.c`, same key as A | +| Attacker | host + Wi-BFI-supported Wi-Fi NIC in monitor mode | Wi-BFI ([arxiv 2309.04408][wibfi]) + re-ID model | +| Bench | shielded room or wired attenuator path preferred | `iperf3`, power meter / board rail sense | + +Key agreement A↔B is out-of-band for the demo (pre-shared session key); +per-packet keying uses `(key, packet_counter)` as in `HDL_NOTES.md`. + +## Procedure + +Run every condition **twice**: WiFi Veil **OFF** (baseline) and **ON**. Same +positions, same MCS, same duration, same seed for the attacker model. + +1. **Correctness precondition (not a defense claim).** Confirm on-FPGA + self-loopback recovers IQ within Q1.15 round-off, and A→B link works with + `veil_unrot` engaged. Capture the console log. +2. **Attacker capture.** Sniffer records CSI / beamforming-feedback for a fixed + traffic pattern A→B, OFF then ON. Save raw captures (pcap + Wi-BFI output). +3. **Re-ID metric.** Run the same re-identification / fingerprinting model on the + OFF and ON captures. Report accuracy and confusion vs. the **chance / mean + baseline** (per CLAUDE.md, a defense claim needs the baseline and a + leakage-free held-out split — never report bare accuracy). +4. **Throughput (near-free check).** `iperf3` A↔B, OFF vs. ON, both directions. + Expected: ON ≈ OFF (the receiver inverts the rotation). Save `iperf3 --json`. +5. **Energy / compliance.** Record per-frame TX energy OFF vs. ON (rail sense or + power meter) to substantiate the "energy-preserving / not jamming" claim, and + spectrum/mask conformance if a spectrum analyzer is available. + +## Metrics reported + +| Metric | OFF | ON | Requirement for a pass | +|---|---|---|---| +| Attacker re-ID accuracy vs. chance | baseline | — | collapses toward chance ON | +| iperf3 throughput A↔B | baseline | — | ON within a few % of OFF | +| Per-frame TX energy | baseline | — | ON ≈ OFF (orthogonality holds on-air) | +| Spectral mask conformance | pass | — | still conformant ON | + +## Required witness artifact (CLAUDE.md gate) + +Before **any** `MEASURED` claim, this directory (or the P5 evidence path) must +contain a **captured real-silicon log**, not a build or simulator output: + +- Boot/runtime console log of both openwifi nodes showing the `veil_rot` / + `veil_unrot` bitstream loaded and `veil_openwifi.c` programming the session + (register writes / STATUS ready), with timestamps and board identifiers. +- The self-loopback correctness log (step 1). +- Raw attacker captures (pcap + Wi-BFI output) for OFF and ON, plus the exact + re-ID reproducer command and its output. +- `iperf3 --json` for OFF and ON; energy trace for OFF and ON. +- A manifest tying each artifact to the git commit of the RTL, driver, and shim + used, so the result is reproducible. + +Label the result `MEASURED` **only** with all of the above captured from real +hardware. A successful Vivado build, a Verilator/QEMU run, or the host +`veil_openwifi.c` self-test is **not** hardware evidence and must stay +`SYNTHETIC`. No log in this repo today — do not fabricate one. + +## Sources + +- Wi-BFI (attacker BF-feedback extraction) — [arxiv.org/pdf/2309.04408][wibfi] +- Packet/IQ self-loopback test — [openwifi self-loopback app note][loop] + +[wibfi]: https://arxiv.org/pdf/2309.04408 +[loop]: https://github.com/open-sdr/openwifi/blob/master/doc/app_notes/packet-iq-self-loopback-test.md diff --git a/wifi-veil/firmware/openwifi/README.md b/wifi-veil/firmware/openwifi/README.md new file mode 100644 index 00000000..63d25cfa --- /dev/null +++ b/wifi-veil/firmware/openwifi/README.md @@ -0,0 +1,122 @@ +# WiFi Veil protector — openwifi (Xilinx Zynq + AD9361, open PHY/MAC) + +> **STATUS: SYNTHETIC / L0 — build-only scaffold. No hardware, no flash, no +> capture. Nothing here has run on silicon.** Per CLAUDE.md, none of this is a +> `MEASURED` result and none may be claimed as working. Files are honest +> skeletons with real openwifi idioms plus `TODO(hw)` / `TODO(hdl)` markers, not +> validated firmware or complete HDL. **Compliant waveform controls only — the +> keyed rotation is orthogonal (energy-preserving) and shapes only this node's +> own standards-conformant emission. Never jamming.** + +## Feasibility grade: **B (capability ceiling A; effort D)** + +openwifi is the **only** platform in this tree where a true end-to-end keyed +rotation *and its inverse* are physically reachable, because it is the only one +that exposes the full open PHY/MAC on FPGA: `openofdm_tx`/`openofdm_rx`, +`tx_intf`/`rx_intf`, and `side_ch`, all AXI-Lite-programmable from a Linux +driver ([FPGA module design][fmd], [openwifi overview][ov]). That is the **A** +capability ceiling. + +It is graded **B**, not A, for two honest reasons that make it the +highest-*effort* path: + +1. **openwifi has no native explicit transmit beamforming.** It ships as an + 802.11a/g/n **single-spatial-stream (SISO)** design. It does not run NDP + sounding, does not compute an SVD `V` matrix, and does not emit a compressed + beamforming report. The two-antenna app note is **RX-only** coherent capture + (`side_ch_ctl wh3h11`), not a MIMO transmit spatial mapper ([iq_2ant][2ant]). + So there is no shipped compressed-BF-report to obfuscate and no shipped + spatial-mapping matrix `Q` to left-multiply — both must be **added in HDL**. +2. Reaching a true two-stream demo needs a **second TX chain** (the AD9361 on + fmcomms2/3 has two DACs) plus a new spatial-mapping RTL stage and a Vivado + rebuild — days-to-weeks of FPGA work, not a driver patch. + +Because of (1), on openwifi WiFi Veil is realized as the **client-transparent +per-packet keyed unitary** (LeakyBeam family) applied at the TX spatial-mapping +stage, with the legitimate STA (a second openwifi node sharing the key) +inverting it — **not** as obfuscation of a compressed-BF report the hardware +never produces. This keeps the claim honest: we rotate the *transmitted spatial +mapping* so a sniffer's per-subcarrier channel estimate `H·Q(key)` is scrambled, +and the keyed receiver applies `Q(key)^H` before channel estimation. + +## Exact insertion points + +The rotation is a keyed orthogonal (unitary) matrix `Q(key, session)` computed +by the portable core (`../core/veil_shield.{h,c}`), the same SplitMix64 schedule +used everywhere, so both ends derive the identical `Q` from the shared key. + +**TX (protector) — FPGA, new block `veil_rot`:** +Insert on the baseband IQ AXI-Stream path **between `openofdm_tx` (post-IFFT, +post-CP) and `tx_intf`** (which feeds the AD9361 DAC). `veil_rot` left-multiplies +the per-subcarrier / per-stream sample vector by `Q(key)`. Its coefficients (or a +key seed + on-FPGA schedule) are written over **AXI-Lite** from the driver shim +using the standard openwifi `iowrite32(value, base_addr + reg)` idiom +([tx_intf driver][txintf]). See `HDL_NOTES.md`. + +**RX (legitimate STA) — FPGA, new block `veil_unrot`:** +Insert **between `rx_intf` (AD9361 ADC) and `openofdm_rx`**, or in the frequency +domain immediately after the FFT and **before channel estimation**, applying +`Q(key)^H`. Same AXI-Lite programming path. + +**Driver / control plane:** the C shim `veil_openwifi.c` computes the session +key schedule via the core and programs the blocks. Real openwifi control idioms: +AXI-Lite MMIO from the kernel driver, and the `sdrctl` nl80211-testmode tool / +`side_ch_ctl` register pokes for bring-up ([sdrctl/side_ch][ov], [frequent +tricks][ft]). Where the exact offsets/bitfields are not yet fixed, the shim +marks `TODO(hw)`; RTL specifics are `TODO(hdl)`. + +Doing the rotation in HDL (not the DMA'd payload) is deliberate: it keeps the +frame **standards-conformant on the wire** and preserves transmit energy — the +"not jamming" invariant the core guarantees by construction (orthogonal `Q`). + +## Two-node measurement plan (the P5 path) + +Three roles produce the first `MEASURED` / P5 result (full protocol + +required witness log in `MEASUREMENT.md`): + +- **Protector AP** — openwifi node A, `veil_rot` engaged, TX spatial mapping + keyed with the session key. +- **Legitimate STA** — openwifi node B, shares the key, `veil_unrot` engaged; + should see **near-baseline throughput** (rotation cancels). +- **Attacker sniffer** — a commodity Wi-Fi NIC running **Wi-BFI** / monitor + capture, extracting the per-subcarrier CSI / beamforming feedback and running + the re-ID model ([Wi-BFI][wibfi]). + +Headline metric: **re-identification accuracy off vs. on** at the attacker +(target: collapse toward chance) **while** iperf throughput A↔B stays near +baseline and per-frame energy is unchanged. No number here is real until a +captured on-silicon log exists. + +## Bill of materials (target, not procured) + +- 2× Xilinx Zynq-7000 board with AD9361 FMC (e.g. ZC706 + fmcomms2/3, or + ADRV9361-Z7035 / Antenna-SDR), openwifi image per the openwifi build docs. +- 1× attacker host + Wi-BFI-capable NIC (per Wi-BFI's supported list). +- Vivado for the FPGA rebuild that adds `veil_rot` / `veil_unrot`. + +## Files here + +| File | What it is | +|---|---| +| `README.md` | this — feasibility, insertion points, measurement plan | +| `veil_openwifi.c` | driver-side C shim: core → session `Q` → AXI-Lite program (scaffold, `TODO(hw)`) | +| `HDL_NOTES.md` | the `veil_rot` / `veil_unrot` Verilog blocks (design notes, `TODO(hdl)`) | +| `MEASUREMENT.md` | exact P5 protocol, metrics, and the required witness artifact | + +## Sources + +- FPGA module design — [deepwiki.com/open-sdr/openwifi/2.2-fpga-module-design][fmd] +- openwifi overview (sdrctl, side_ch, nl80211 testmode) — [deepwiki.com/open-sdr/openwifi/1-openwifi-overview][ov] +- Two-antenna IQ (RX-only) app note — [github.com/open-sdr/openwifi .../iq_2ant.md][2ant] +- tx_intf driver register idioms (`iowrite32`/`ioread32`) — [github.com/open-sdr/openwifi .../tx_intf.c][txintf] +- Frequent tricks / register pokes — [github.com/open-sdr/openwifi .../frequent_trick.md][ft] +- openwifi paper (SDR 802.11 on SoC) — [researchgate .../342582824][paper] +- Wi-BFI (attacker BF-feedback extraction) — [arxiv.org/pdf/2309.04408][wibfi] + +[fmd]: https://deepwiki.com/open-sdr/openwifi/2.2-fpga-module-design +[ov]: https://deepwiki.com/open-sdr/openwifi/1-openwifi-overview +[2ant]: https://github.com/open-sdr/openwifi/blob/master/doc/app_notes/iq_2ant.md +[txintf]: https://github.com/open-sdr/openwifi/blob/master/driver/tx_intf/tx_intf.c +[ft]: https://github.com/open-sdr/openwifi/blob/master/doc/app_notes/frequent_trick.md +[paper]: https://www.researchgate.net/publication/342582824_openwifi_a_free_and_open-source_IEEE80211_SDR_implementation_on_SoC +[wibfi]: https://arxiv.org/pdf/2309.04408 diff --git a/wifi-veil/firmware/openwifi/veil_openwifi.c b/wifi-veil/firmware/openwifi/veil_openwifi.c new file mode 100644 index 00000000..012d5def --- /dev/null +++ b/wifi-veil/firmware/openwifi/veil_openwifi.c @@ -0,0 +1,315 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * veil_openwifi — driver-side shim that binds the portable VEIL core + * (../core/veil_shield.{h,c}) to the openwifi FPGA TX/RX datapath. + * + * STATUS: SYNTHETIC / L0. Build-only scaffold. Never compiled into the openwifi + * kernel module on real silicon, never flashed, never captured. Do NOT claim + * runtime behavior without a captured hardware log (CLAUDE.md hardware-evidence + * rule). Register offsets, bitfields, and the FPGA blocks it programs + * (veil_rot / veil_unrot) do NOT exist in upstream openwifi yet — every place + * that depends on real hardware is marked TODO(hw); RTL specifics live in + * HDL_NOTES.md and are marked TODO(hdl) there. + * + * ROLE (honest): this shim runs on the protector AP and on the legitimate STA. + * - Protector: derive the per-session keyed unitary Q(key) from the core and + * program the veil_rot block that left-multiplies the transmit spatial + * mapping (inserted between openofdm_tx and tx_intf; see HDL_NOTES.md). + * - Legitimate STA: derive the same Q(key) and program veil_unrot to apply + * Q^H before channel estimation, cancelling the rotation (near-free tput). + * The transform is orthogonal, so transmit energy is preserved: compliant, + * NOT jamming. openwifi ships SISO with no explicit beamforming, so this is the + * client-transparent per-packet unitary route, not obfuscation of a compressed + * beamforming report (openwifi never generates one) — see README.md. + * + * openwifi idioms used where known: + * - AXI-Lite MMIO from the driver: iowrite32(value, base + reg) / + * ioread32(base + reg), matching driver/tx_intf/tx_intf.c reg_write/reg_read. + * - Coefficients are quantized to the fixed-point width the datapath uses + * (openwifi baseband IQ is 16-bit I / 16-bit Q); see VEIL_ROT_FRAC below. + * + * This file is written to compile in two modes: + * - Host/CI (default): __KERNEL__ undefined -> MMIO is stubbed to a local + * shadow buffer so the key-schedule + quantization logic is unit-testable + * with no hardware. This is the ONLY path exercised today. + * - In-tree kernel build: define VEIL_OPENWIFI_KERNEL to pull the real + * linux/io.h accessors. Untested. TODO(hw). + */ + +#include "../core/veil_shield.h" + +#include +#include +#include +#include + +/* ------------------------------------------------------------------------- + * MMIO layer. Real openwifi drivers keep a per-block __iomem base and use + * iowrite32/ioread32. We isolate that here so host/CI builds need no kernel. + * ------------------------------------------------------------------------- */ +#if defined(VEIL_OPENWIFI_KERNEL) +#include +typedef void __iomem *veil_mmio_base; +static inline void veil_reg_write(veil_mmio_base b, uint32_t reg, uint32_t v) { + iowrite32(v, (uint8_t __iomem *)b + reg); +} +static inline uint32_t veil_reg_read(veil_mmio_base b, uint32_t reg) { + return ioread32((uint8_t __iomem *)b + reg); +} +#else +/* Host/CI shadow: a small register file so logic is testable with no radio. */ +#define VEIL_SHADOW_REGS 256 +typedef struct { + uint32_t regs[VEIL_SHADOW_REGS]; +} veil_mmio_shadow; +typedef veil_mmio_shadow *veil_mmio_base; +static inline void veil_reg_write(veil_mmio_base b, uint32_t reg, uint32_t v) { + if (b && (reg >> 2) < VEIL_SHADOW_REGS) { + b->regs[reg >> 2] = v; + } +} +static inline uint32_t veil_reg_read(veil_mmio_base b, uint32_t reg) { + if (b && (reg >> 2) < VEIL_SHADOW_REGS) { + return b->regs[reg >> 2]; + } + return 0; +} +#endif + +/* ------------------------------------------------------------------------- + * Register map for the (not-yet-existing) veil_rot / veil_unrot AXI-Lite + * slaves. Offsets are PLACEHOLDERS chosen to be word-aligned; the real map is + * fixed when the RTL lands. TODO(hw): confirm against the generated + * *_s_axi.v once veil_rot exists (cf. openofdm_tx's 6 AXI-Lite regs). + * ------------------------------------------------------------------------- */ +#define VEIL_ROT_REG_CTRL 0x00u /* bit0 enable, bit1 inverse, bit2 load */ +#define VEIL_ROT_REG_KEY_LO 0x04u /* session key [31:0] */ +#define VEIL_ROT_REG_KEY_HI 0x08u /* session key [63:32] */ +#define VEIL_ROT_REG_NDIM 0x0Cu /* fine-block dimension N applied on-air */ +#define VEIL_ROT_REG_PASSES 0x10u /* number of Givens passes */ +#define VEIL_ROT_REG_COEFF_ADDR 0x14u /* write index into the coeff RAM */ +#define VEIL_ROT_REG_COEFF_DATA 0x18u /* {Q16.15 sin, Q16.15 cos} packed */ +#define VEIL_ROT_REG_STATUS 0x1Cu /* bit0 ready, bit1 applied, bit2 err */ + +#define VEIL_ROT_CTRL_ENABLE (1u << 0) +#define VEIL_ROT_CTRL_INVERSE (1u << 1) +#define VEIL_ROT_CTRL_LOAD (1u << 2) + +#define VEIL_ROT_STATUS_READY (1u << 0) + +/* Fixed-point: openwifi baseband IQ is 16-bit. We program rotation coeffs as + * signed Q1.15 (fractional bits = 15). cos/sin in [-1,1] map cleanly. */ +#define VEIL_ROT_FRAC 15 + +/* Default schedule parameters — kept byte-consistent with the core/Rust crate + * defaults. N is the on-air fine-block dimension the datapath vectorizes over; + * for the SISO-plus-synthetic-stream demo this is small (see HDL_NOTES.md). */ +#define VEIL_OW_DEFAULT_PASSES 96u +#define VEIL_OW_MAX_NDIM 64u /* bounded coeff RAM; keeps it malloc-free */ + +typedef enum { + VEIL_OW_ROLE_PROTECTOR = 0, /* TX veil_rot, forward rotation Q */ + VEIL_OW_ROLE_LEGIT_RX = 1, /* RX veil_unrot, inverse rotation Q^H */ +} veil_ow_role; + +typedef struct { + veil_mmio_base base; /* AXI-Lite base of veil_rot / veil_unrot slave */ + uint64_t key; /* shared session key (both ends must match) */ + uint32_t ndim; /* fine-block dimension, <= VEIL_OW_MAX_NDIM */ + uint32_t passes; /* Givens passes */ + veil_ow_role role; +} veil_ow_ctx; + +/* Saturating float -> signed Q1.15. */ +static int16_t veil_q15(float x) { + float scaled = x * (float)(1 << VEIL_ROT_FRAC); + if (scaled > 32767.0f) return 32767; + if (scaled < -32768.0f) return -32768; + return (int16_t)lrintf(scaled); +} + +/* ------------------------------------------------------------------------- + * Coefficient generation. The core's schedule is (i, j, theta) Givens ops + * derived from SplitMix64(key). The FPGA applies the SAME schedule to on-air + * samples, so we hand it the per-pass (i, j, cos, sin). We regenerate the + * schedule here with the identical draw order as veil_shield.c so the shim and + * the (future) RTL agree bit-for-bit with the reference crate. + * + * NOTE: this mirrors veil_shield.c's private schedule. It is duplicated (not + * exported) on purpose — the core stays a pure in-memory transform with a + * stable ABI; the adapter owns the hardware-facing serialization. If the core + * later exports its schedule, collapse this. TODO(hw): validate equality with a + * captured on-FPGA coeff dump before any MEASURED claim. + * ------------------------------------------------------------------------- */ +typedef struct { + uint16_t i; + uint16_t j; + int16_t cos_q15; + int16_t sin_q15; +} veil_ow_givens; + +/* TAU matches VEIL_TAU in veil_shield.c / Rust core::f32::consts::TAU. */ +#define VEIL_OW_TAU 6.28318530717958647692f + +static void veil_ow_build_schedule(uint64_t key, uint32_t n, uint32_t passes, + veil_ow_givens *out /* [passes] */) { + veil_rng r; + uint32_t p; + if (n < 2) { + for (p = 0; p < passes; p++) { + out[p].i = 0; out[p].j = 0; + out[p].cos_q15 = veil_q15(1.0f); out[p].sin_q15 = 0; + } + return; + } + veil_rng_seed(&r, key); + for (p = 0; p < passes; p++) { + uint32_t i = (uint32_t)(veil_rng_next_u64(&r) % (uint64_t)n); + uint32_t j = (uint32_t)(veil_rng_next_u64(&r) % (uint64_t)n); + float theta; + if (j == i) { + j = (j + 1) % n; + } + theta = veil_rng_next_f32(&r) * VEIL_OW_TAU; + out[p].i = (uint16_t)i; + out[p].j = (uint16_t)j; + out[p].cos_q15 = veil_q15(cosf(theta)); + out[p].sin_q15 = veil_q15(sinf(theta)); + } +} + +/* ------------------------------------------------------------------------- + * Public API. + * ------------------------------------------------------------------------- */ + +/* Program a session key into the veil_rot/veil_unrot block. Returns 0 on the + * host shadow path; on real hardware it must poll STATUS_READY. */ +int veil_ow_program_session(veil_ow_ctx *ctx) { + veil_ow_givens sched[VEIL_OW_DEFAULT_PASSES]; + uint32_t ctrl = VEIL_ROT_CTRL_LOAD; + uint32_t p, passes, n; + + if (!ctx || ctx->ndim < 2 || ctx->ndim > VEIL_OW_MAX_NDIM) { + return -1; /* bounds check the on-air dimension (least authority) */ + } + passes = ctx->passes ? ctx->passes : VEIL_OW_DEFAULT_PASSES; + if (passes > VEIL_OW_DEFAULT_PASSES) { + passes = VEIL_OW_DEFAULT_PASSES; /* bounded, stack-only schedule */ + } + n = ctx->ndim; + + veil_ow_build_schedule(ctx->key, n, passes, sched); + + /* Program header registers. */ + veil_reg_write(ctx->base, VEIL_ROT_REG_KEY_LO, (uint32_t)(ctx->key)); + veil_reg_write(ctx->base, VEIL_ROT_REG_KEY_HI, (uint32_t)(ctx->key >> 32)); + veil_reg_write(ctx->base, VEIL_ROT_REG_NDIM, n); + veil_reg_write(ctx->base, VEIL_ROT_REG_PASSES, passes); + + /* Stream the (i, j, cos, sin) schedule into the coeff RAM. Packing: + * COEFF_DATA = {i[15:0]... } is too wide for one 32-bit word, so we use a + * 2-word-per-pass convention: word A = {j[15:0], i[15:0]}, word B = + * {sin_q15[15:0], cos_q15[15:0]}. TODO(hdl): the veil_rot coeff-RAM write + * FSM must match this exact packing. TODO(hw): confirm endianness of the + * AXI-Lite slave. */ + for (p = 0; p < passes; p++) { + uint32_t wa = ((uint32_t)(uint16_t)sched[p].j << 16) | + (uint32_t)(uint16_t)sched[p].i; + uint32_t wb = ((uint32_t)(uint16_t)sched[p].sin_q15 << 16) | + (uint32_t)(uint16_t)sched[p].cos_q15; + veil_reg_write(ctx->base, VEIL_ROT_REG_COEFF_ADDR, p * 2u); + veil_reg_write(ctx->base, VEIL_ROT_REG_COEFF_DATA, wa); + veil_reg_write(ctx->base, VEIL_ROT_REG_COEFF_ADDR, p * 2u + 1u); + veil_reg_write(ctx->base, VEIL_ROT_REG_COEFF_DATA, wb); + } + + if (ctx->role == VEIL_OW_ROLE_LEGIT_RX) { + ctrl |= VEIL_ROT_CTRL_INVERSE; /* veil_unrot applies Q^H */ + } + veil_reg_write(ctx->base, VEIL_ROT_REG_CTRL, ctrl); + + /* TODO(hw): on real silicon, poll VEIL_ROT_REG_STATUS for READY here and + * time out. The host shadow has no FSM, so we return success directly and + * DO NOT claim the hardware accepted it. */ +#if defined(VEIL_OPENWIFI_KERNEL) + { + int spins = 100000; /* TODO(hw): calibrate against real ready latency */ + while (spins-- > 0) { + if (veil_reg_read(ctx->base, VEIL_ROT_REG_STATUS) & + VEIL_ROT_STATUS_READY) { + break; + } + } + if (spins <= 0) { + return -2; /* not ready — never treat as success */ + } + } +#endif + return 0; +} + +/* Engage / disengage the block (bit0 of CTRL), preserving the inverse bit. */ +int veil_ow_set_enabled(veil_ow_ctx *ctx, int enable) { + uint32_t ctrl; + if (!ctx) { + return -1; + } + ctrl = veil_reg_read(ctx->base, VEIL_ROT_REG_CTRL); + if (enable) { + ctrl |= VEIL_ROT_CTRL_ENABLE; + } else { + ctrl &= ~VEIL_ROT_CTRL_ENABLE; + } + veil_reg_write(ctx->base, VEIL_ROT_REG_CTRL, ctrl); + return 0; +} + +/* + * Control-plane bring-up alternatives (documented idioms, not wired here): + * - sdrctl (nl80211 testmode) for driver-level toggles once a testmode verb + * is added, e.g. a "veil" subcommand mirroring existing sdrctl reg pokes. + * - side_ch_ctl-style hex register pokes during bench bring-up, e.g. the + * side_ch app note's `./side_ch_ctl whXXdY` write convention, retargeted at + * the veil_rot slave. TODO(hw): pick and document the actual verb. + * + * Self-loopback validation (before over-the-air): openwifi supports a + * packet/IQ self-loopback test. Route veil_rot -> veil_unrot in loopback and + * assert recovered IQ == original within Q1.15 round-off. That is the first + * on-FPGA correctness gate (still not a defense MEASURED claim). TODO(hw). + */ + +#if defined(VEIL_OPENWIFI_SELFTEST) +/* Host-only smoke test of the schedule/quantization path — NO hardware. + * Verifies the shadow register file receives a plausible, bounded program. + * Build: cc -DVEIL_OPENWIFI_SELFTEST veil_openwifi.c ../core/veil_shield.c -lm */ +#include +int main(void) { + veil_mmio_shadow shadow; + veil_ow_ctx ctx; + memset(&shadow, 0, sizeof(shadow)); + ctx.base = &shadow; + ctx.key = 0x0123456789ABCDEFull; + ctx.ndim = 16; + ctx.passes = VEIL_OW_DEFAULT_PASSES; + ctx.role = VEIL_OW_ROLE_PROTECTOR; + + if (veil_ow_program_session(&ctx) != 0) { + printf("FAIL: program_session\n"); + return 1; + } + if (veil_ow_set_enabled(&ctx, 1) != 0) { + printf("FAIL: set_enabled\n"); + return 1; + } + if (veil_reg_read(&shadow, VEIL_ROT_REG_NDIM) != 16u) { + printf("FAIL: ndim not programmed\n"); + return 1; + } + if (!(veil_reg_read(&shadow, VEIL_ROT_REG_CTRL) & VEIL_ROT_CTRL_ENABLE)) { + printf("FAIL: enable bit\n"); + return 1; + } + printf("OK (SYNTHETIC/L0 host shadow only — NOT hardware-validated)\n"); + return 0; +} +#endif diff --git a/wifi-veil/firmware/openwrt/INTEGRATION.md b/wifi-veil/firmware/openwrt/INTEGRATION.md new file mode 100644 index 00000000..58f32cc4 --- /dev/null +++ b/wifi-veil/firmware/openwrt/INTEGRATION.md @@ -0,0 +1,95 @@ +# WiFi Veil ↔ `mac80211` / driver integration map + +> **`SYNTHETIC / L0` — BUILD-ONLY, UNTESTED ON HARDWARE.** These are hook-point +> designs derived from public API/source, not validated on silicon. Function and +> attribute names are real (verified against in-tree `linux/nl80211.h` and public +> hostapd/driver docs); where a hook does **not** exist upstream it is marked +> `TODO(hw)` with what a patch would have to add. Compliant controls only. + +Legend: **US** = userspace-reachable today · **DP** = needs driver patch · +**FW** = needs firmware patch (blob-blocked). + +--- + +## 1. TX antenna-map perturbation — **US** (feasible) + +- **Daemon:** `veil_set_tx_antenna_mask()` in `veil_shieldd.c`. +- **Kernel path:** `nl80211` → `cfg80211_ops.set_antenna()` → driver + `.set_antenna` (e.g. `mt7915_set_antenna`, `ath9k` `set_antenna`). +- **Attributes:** `NL80211_CMD_SET_WIPHY`, `NL80211_ATTR_WIPHY_ANTENNA_TX`, + `NL80211_ATTR_WIPHY_ANTENNA_RX`. +- **Constraints:** many drivers require the phy DOWN and accept only symmetric + masks; validate per driver. Coarse static spatial-mapping change, not the keyed + rotation. Fully standards-compliant. + +## 2. NDP sounding-cadence jitter — **US (indirect)** + +- **Daemon:** `veil_randomize_sounding_cadence()` / `veil_next_cadence_ms()`. + The schedule is derived from the session key via the core SplitMix64 so the + paired receiver can anticipate it (not random spraying). +- **Real lever:** hostapd `ctrl_iface` (UNIX socket `/var/run/hostapd/`): + `SET he_su_beamformer …` / rewrite `vht_capab` `[SOUNDING-DIMENSION-n]` / + toggle `[SU-BEAMFORMER]`, then `RECONFIGURE`. Config keys documented in + `hostapd.conf`. +- **`TODO(hw)`:** there is **no** `nl80211` "set sounding interval" command; the + per-NDP timer is in driver/firmware. We can only jitter the *offered* cadence. + The `ctrl_iface` write itself is not yet wired (function currently only + computes `ms`). + +## 3. MU-MIMO group shuffling — **FW** (blob-blocked) + +- **Daemon:** `veil_shuffle_mumimo_groups()` — explicit `-ENOTSUP` no-op. +- **Where it lives:** MU group formation + per-group steering matrices are + computed in the WiFi MCU firmware on mt76 (mt7915) and all ath1x parts. +- **`TODO(hw)`:** would require `NL80211_CMD_VENDOR` with a driver-specific + `NL80211_ATTR_VENDOR_ID` / `NL80211_ATTR_VENDOR_SUBCMD` / + `NL80211_ATTR_VENDOR_DATA` that upstream mt76/ath do **not** define, plus a + firmware change to honor an externally supplied grouping. Not reachable without + both a driver and firmware patch. + +## 4. Per-packet keyed unitary (the core WiFi Veil transform) — **FW** (blob-blocked) + +- **Daemon:** `veil_apply_keyed_rotation()` → `veil_shield_apply(fine, n, key, + passes)` from the portable core. Orthogonal / energy-preserving (the + "not jamming" invariant, checked via `veil_l2_norm` before/after). +- **What a full path must touch:** + - **mt76 (mt7915):** the MCU firmware stage that builds the compressed + beamforming report (φ/ψ angles) or applies the steering/precoder Q to the + LTF spatial mapping. A firmware patch would call the rotation on the fine + subspace *before* the report is emitted / precoder applied. The driver + (`mt7915/mcu.c`) would ferry the key/passes down via a new MCU command. + - **ath9k (DP, best open case):** the static spatial-mapping matrix is set via + `AR_PHY_*` registers in the open PHY init; a driver patch could apply a keyed + *static* Q there. This is coarser than a true per-packet report edit but is + the most credible OpenWRT-adjacent route (older 802.11n hardware only). + - **ath10k/ath11k/ath12k:** report generation + precoder are entirely + firmware-side with no open firmware (ath11k/ath12k) — not patchable. +- **`TODO(hw)`:** on OpenWRT there is **no** userspace/`mac80211` hook that hands + the pre-precoder V/steering buffer to the daemon before TX. Reaching it needs + the driver+firmware patch above, or use the **openwifi (FPGA)** / **Nexmon + (Broadcom)** adapters, which expose the datapath. The daemon only proves the + math is invariant; nothing goes on air. + +## 5. Sensing-solicitation (NDPA) detection — **US/DP** (partial) + +- **Daemon:** `veil_event_cb()` on `NL80211_CMD_FRAME`. +- **Real path:** `NL80211_CMD_REGISTER_FRAME` to subscribe to specific + management action categories, delivered as `NL80211_CMD_FRAME` with + `NL80211_ATTR_FRAME`. Classify VHT/HE compressed beamforming action + (categories 21 / 30) and NDP Announcement to measure cadence. +- **`TODO(hw)`:** commodity drivers do **not** forward raw NDPA to userspace by + default; honest external-solicitation detection needs monitor-mode capture or a + driver notification that is not guaranteed upstream. Frame parsing is stubbed. + +--- + +## Summary of the effort boundary + +| Control | Effort to reach full WiFi Veil fidelity | +|---|---| +| TX antenna map | Ready now (US), coarse only | +| Sounding cadence jitter | Wire hostapd `ctrl_iface` (US), coarse only | +| Static spatial Q | ath9k driver patch (DP) | +| MU grouping | driver vendor subcmd + firmware (FW) | +| Per-packet keyed rotation | mt76/ath **firmware** patch, or openwifi/Nexmon adapter (FW) | +| NDPA detection | frame registration + likely driver patch (US/DP) | diff --git a/wifi-veil/firmware/openwrt/Makefile b/wifi-veil/firmware/openwrt/Makefile new file mode 100644 index 00000000..9a8155d4 --- /dev/null +++ b/wifi-veil/firmware/openwrt/Makefile @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: MIT OR Apache-2.0 +# +# Host build-CHECK for the OpenWRT/mac80211 VEIL adapter. +# STATUS: SYNTHETIC / L0 — build-only, UNTESTED ON HARDWARE. +# +# Two targets: +# make core - compile+link the portable core only (always works, +# no libnl needed) — proves the rotation math builds. +# make daemon - build veil_shieldd against libnl-genl-3 (needs the +# dev headers: `pkg-config libnl-genl-3.0`). On OpenWRT +# the package build uses libnl-tiny instead (see openwrt.mk). +# +# This Makefile does NOT flash, run on, or validate any radio. + +CC ?= cc +COREDIR := ../core +CFLAGS ?= -std=c99 -Wall -Wextra -O2 -I$(COREDIR) +LDLIBS ?= -lm + +NL_CFLAGS := $(shell pkg-config --cflags libnl-genl-3.0 2>/dev/null) +NL_LIBS := $(shell pkg-config --libs libnl-genl-3.0 2>/dev/null) + +.PHONY: all core daemon clean +all: core + +# Always-buildable: the core object, no netlink dependency. +core: $(COREDIR)/veil_shield.c $(COREDIR)/veil_shield.h + $(CC) $(CFLAGS) -c $(COREDIR)/veil_shield.c -o veil_shield.o + @echo "core built (rotation math OK). Nothing was run on hardware." + +# Full daemon: requires libnl-genl-3 dev headers on the host. +daemon: veil_shieldd.c core +ifeq ($(strip $(NL_LIBS)),) + @echo "SKIP daemon: libnl-genl-3.0 not found (pkg-config)." + @echo " Install libnl-3-dev + libnl-genl-3-dev, or build via openwrt.mk." + @exit 0 +else + $(CC) $(CFLAGS) $(NL_CFLAGS) -o veil_shieldd \ + veil_shieldd.c veil_shield.o $(NL_LIBS) $(LDLIBS) + @echo "veil_shieldd linked (BUILD-ONLY; untested on silicon)." +endif + +clean: + rm -f veil_shield.o veil_shieldd diff --git a/wifi-veil/firmware/openwrt/README.md b/wifi-veil/firmware/openwrt/README.md new file mode 100644 index 00000000..8b7d1641 --- /dev/null +++ b/wifi-veil/firmware/openwrt/README.md @@ -0,0 +1,112 @@ +# WiFi Veil — OpenWRT / Linux `mac80211` adapter + +> **STATUS: `SYNTHETIC / L0` — BUILD-ONLY, UNTESTED ON HARDWARE.** +> No radio was driven, no CSI captured, no log produced on silicon. Every +> claim below is a design/feasibility statement, not a `MEASURED` result. This +> adapter uses **compliant waveform controls only** — it never jams and emits +> no denial energy. + +This directory is the OpenWRT/`mac80211` platform adapter for the WiFi Veil privacy +shield. It links the validated portable core +(`../core/veil_shield.{h,c}` — the keyed Givens rotation over the identity-bearing +"fine" subspace of 802.11 compressed beamforming feedback) and drives the subset +of controls that Linux userspace/`mac80211` can actually reach on commodity APs. + +--- + +## Feasibility grade: **C** (partial — coarse compliant controls only) + +**Why C, not higher.** WiFi Veil's defining action is a *per-packet keyed unitary* on +the compressed beamforming-feedback angles (equivalently, a keyed Q on the LTF +spatial mapping / precoder). On every mainstream OpenWRT AP chipset +(Qualcomm ath10k/ath11k/ath12k, MediaTek mt76 / mt7915), that report is generated +and the precoder applied **inside the WiFi MCU firmware blob** — userspace and the +open driver never touch the pre-transmit V matrix. So the full keyed-rotation path +is **blob-blocked** from OpenWRT. What remains reachable is a set of *coarse* +compliant knobs that perturb, but do not cryptographically obfuscate, the CSI a +sensor observes. That is a real, honest defense-in-depth layer — hence C, not D — +but it is not the full WiFi Veil transform. + +**Why not D.** Some controls genuinely work from userspace (TX antenna map; +hostapd-mediated sounding/beamformer capability), and one chipset family +(**ath9k**) is open enough at the register level that a *driver patch* could reach +the static spatial-mapping matrix — a credible route to B on that specific, +older hardware. openwifi (FPGA) and Nexmon (Broadcom) are the routes to the full +A-grade keyed rotation, but those are **separate adapters**, not OpenWRT. + +--- + +## What is FEASIBLE vs. BLOB-BLOCKED from OpenWRT + +| WiFi Veil control | Reachable from OpenWRT? | Mechanism (real API / knob) | Notes | +|---|---|---|---| +| **TX antenna-map perturbation** | ✅ Feasible | `NL80211_CMD_SET_WIPHY` + `NL80211_ATTR_WIPHY_ANTENNA_TX` / `_RX` | Coarse static spatial-mapping change. Many drivers require phy DOWN and symmetric masks. Compliant. | +| **NDP sounding-cadence jitter** | 🟡 Indirect | hostapd `ctrl_iface` (rewrite `SOUNDING-DIMENSION`, toggle `[SU-BEAMFORMER]`, `RECONFIGURE`) | No `nl80211` "set sounding interval" exists; the per-NDP timer lives in driver/firmware. We can only jitter the *offered* capability. | +| **Beamformer/beamformee capability toggle** | ✅ Feasible | hostapd `vht_capab` / `he_su_beamformer` etc. | Standards-compliant advertisement. Coarse on/off, not per-packet. | +| **Spatial-stream → antenna mapping (static Q)** | 🟡 Driver-patch (ath9k only) | ath9k PHY spatial-mapping registers (`AR_PHY_*`) | Open enough to patch on ath9k; opaque/firmware on ath10k+/mt76. Not a stock userspace knob. | +| **MU-MIMO group shuffling** | ❌ Blob-blocked | would need `NL80211_CMD_VENDOR` subcmd that upstream mt76/ath do **not** expose | Group formation + steering matrices computed in MCU firmware. | +| **Per-packet keyed unitary on LTF / precoder** | ❌ Blob-blocked | — | The core WiFi Veil transform. Lives in firmware on all commodity AP parts. Requires firmware patch, or use openwifi / Nexmon adapters. | +| **Compressed-BF-report angle edit (φ/ψ)** | ❌ Blob-blocked | — | Report is generated in firmware/PHY; not exposed pre-TX on OpenWRT. | +| **External sensing-solicitation detection (NDPA cadence)** | 🟡 Partial | `NL80211_CMD_FRAME` + `NL80211_CMD_REGISTER_FRAME`, or monitor-mode capture | Commodity drivers do not forward raw NDPA to userspace by default. | + +--- + +## Best candidate chipsets / drivers + +- **ath9k (Atheros 802.11n)** — *best open target for a driver-side patch.* The + most transparent open driver (no per-packet firmware for the datapath), with a + long history of PHY register access and the Atheros CSI Tool ecosystem. A + static spatial-mapping perturbation and CSI observation are realistic here; + full HT beamforming-feedback editing still is not in open code. 802.11n-only. +- **mt76 (MediaTek mt7915 / mt7622-mt7615)** — *best-maintained modern open + driver* and the most likely place upstream would eventually accept a vendor + hook, but beamforming/sounding/MU grouping run in the MCU firmware today, so + the keyed path needs a firmware patch (blob-blocked out of the box). +- **ath10k / ath11k / ath12k (Qualcomm)** — most capable radios but the most + closed: regulatory + beamforming + sounding all firmware-side. ath11k/ath12k + have **no open firmware** at all. Worst target for the keyed path. +- **openwifi (FPGA SDR) / Nexmon (Broadcom)** — the only routes to the full + A-grade keyed rotation; handled by the sibling `../openwifi/` and `../nexmon/` + adapters, **not** this OpenWRT one. + +**Recommendation:** for OpenWRT specifically, target **ath9k** for a +driver-patch proof-of-concept (spatial-mapping + CSI), and **mt76/mt7915** as the +strategic modern platform pending a firmware/vendor-subcmd hook. + +--- + +## Build (host, build-only) + +```bash +make core # always works: compiles+links the portable core, no libnl needed +make daemon # builds veil_shieldd IF libnl-genl-3.0 dev headers are present +make clean +``` + +`make daemon` cleanly **skips** (does not fail) when `libnl-genl-3.0` is absent, +printing the required dev packages. On an OpenWRT buildroot use `openwrt.mk` +(rename to `Makefile` under `package/utils/veil-shieldd/`), which builds against +`libnl-tiny`. See `INTEGRATION.md` for the per-control hook points and exactly +what a driver/firmware patch would need to touch. + +--- + +## Sources + +- Linux `nl80211.h` (in-tree, this host): `NL80211_CMD_SET_WIPHY`, + `NL80211_ATTR_WIPHY_ANTENNA_TX` / `_RX`, `NL80211_CMD_VENDOR`, + `NL80211_CMD_FRAME` / `NL80211_CMD_REGISTER_FRAME`. +- ath10k configuration (beamforming only via hostapd `vht_capab`, no debugfs + sounding control): +- hostapd beamforming/sounding knobs (`[SU-BEAMFORMER]`, `[MU-BEAMFORMER]`, + `[SOUNDING-DIMENSION-4]`, `he_su_beamformer`): + and + +- mt76 beamforming lives in firmware (mt7622/mt7615 performance/beamforming + discussion): +- Qualcomm firmware closedness (ath11k/ath12k no open firmware; regulatory + + features firmware-enforced): ath10k mailing-list thread + + and CodeLinaro ath firmware +- ath11k reports VHT beamformee spatial streams *from firmware*: + diff --git a/wifi-veil/firmware/openwrt/openwrt.mk b/wifi-veil/firmware/openwrt/openwrt.mk new file mode 100644 index 00000000..5b073ecb --- /dev/null +++ b/wifi-veil/firmware/openwrt/openwrt.mk @@ -0,0 +1,60 @@ +# SPDX-License-Identifier: MIT OR Apache-2.0 +# +# OpenWRT package Makefile STUB for veil_shieldd. +# STATUS: SYNTHETIC / L0 — package skeleton, UNTESTED ON HARDWARE / not in any feed. +# +# Drop this (renamed to `Makefile`) into a package dir such as +# `package/utils/veil-shieldd/` in an OpenWRT buildroot, alongside the copied +# core (veil_shield.{c,h}) and veil_shieldd.c under ./src/. It builds against +# libnl-tiny (the OpenWRT netlink lib) — the same nl80211 API surface, smaller. +# +# This stub does NOT prove the daemon works on a device; it only wires the +# build. No hardware validation is implied. + +include $(TOPDIR)/rules.mk + +PKG_NAME:=veil-shieldd +PKG_VERSION:=0.0.0-l0 +PKG_RELEASE:=1 +PKG_LICENSE:=MIT OR Apache-2.0 + +include $(INCLUDE_DIR)/package.mk + +define Package/veil-shieldd + SECTION:=utils + CATEGORY:=Utilities + TITLE:=VEIL compliant-waveform privacy shield (mac80211 adapter, L0) + # libnl-tiny provides nl80211/genl; hostapd for the ctrl_iface cadence path. + DEPENDS:=+libnl-tiny +hostapd-common + URL:=https://github.com/ruvnet/RuView +endef + +define Package/veil-shieldd/description + BUILD-ONLY / UNTESTED-ON-HARDWARE userspace adapter that drives the + standards-compliant subset of VEIL controls reachable from OpenWRT + (TX antenna map, hostapd-mediated sounding cadence) and links the portable + keyed-rotation core. The full per-packet keyed rotation is blob-blocked on + commodity Qualcomm/MediaTek parts and requires a driver/firmware patch. + This is NOT a jammer and emits no denial energy. +endef + +# Build flags: point at libnl-tiny headers and the copied core. +TARGET_CFLAGS += -I$(STAGING_DIR)/usr/include/libnl-tiny -I$(PKG_BUILD_DIR)/src +TARGET_LDFLAGS += -lnl-tiny -lm + +define Build/Compile + $(TARGET_CC) $(TARGET_CFLAGS) -std=c99 -Wall -Wextra \ + -o $(PKG_BUILD_DIR)/veil_shieldd \ + $(PKG_BUILD_DIR)/src/veil_shieldd.c \ + $(PKG_BUILD_DIR)/src/veil_shield.c \ + $(TARGET_LDFLAGS) +endef + +define Package/veil-shieldd/install + $(INSTALL_DIR) $(1)/usr/sbin + $(INSTALL_BIN) $(PKG_BUILD_DIR)/veil_shieldd $(1)/usr/sbin/veil_shieldd + # TODO(hw): ship a procd init script that reads the session key from a + # secure store (never a world-readable config) and passes -i . +endef + +$(eval $(call BuildPackage,veil-shieldd)) diff --git a/wifi-veil/firmware/openwrt/veil_shieldd.c b/wifi-veil/firmware/openwrt/veil_shieldd.c new file mode 100644 index 00000000..9de40efe --- /dev/null +++ b/wifi-veil/firmware/openwrt/veil_shieldd.c @@ -0,0 +1,294 @@ +/* SPDX-License-Identifier: MIT OR Apache-2.0 + * + * veil_shieldd — OpenWRT / Linux mac80211 userspace adapter for the VEIL + * compliant-waveform privacy shield (ADR-288 / ADR-290). + * + * ============================= HONESTY BANNER ============================== + * STATUS: SYNTHETIC / L0 — BUILD-ONLY SCAFFOLD, UNTESTED ON HARDWARE. + * + * This daemon compiles and links the portable veil_shield core, and it issues + * REAL nl80211/libnl calls for the small set of controls that Linux actually + * exposes to userspace (antenna TX mask, station/BSS observation). Everything + * that would edit the per-packet spatial mapping / precoder or the compressed + * beamforming-feedback angles is BLOB-BLOCKED on commodity Qualcomm/MediaTek + * parts and is marked `TODO(hw)` at the exact call site — see README.md and + * INTEGRATION.md. Nothing here has been run against a radio. Do not read any + * comment in this file as evidence that VEIL obfuscation reaches the air. + * + * COMPLIANCE: every control below is a standards-compliant configuration or + * observation action. This daemon never transmits energy to deny a channel; + * it only shapes/observes our own compliant frames. It is NOT a jammer. + * ========================================================================== + * + * Build deps (OpenWRT: libnl-tiny; desktop: libnl-3 + libnl-genl-3): + * pkg-config --cflags --libs libnl-genl-3.0 + * See Makefile (host build-check) and openwrt.mk (package stub). + */ + +#include +#include +#include +#include +#include +#include +#include + +/* Real libnl / nl80211 headers. On OpenWRT these resolve to libnl-tiny; on a + * desktop to libnl-3. If the toolchain lacks them the host Makefile still + * builds the core object so the rotation math is validated in isolation. */ +#include +#include +#include +#include + +#include "veil_shield.h" + +/* ---- Tunables (compliant, conservative defaults) ---------------------- */ +#define VEIL_DEFAULT_PASSES 96u /* matches core default (ADR-290) */ +#define VEIL_CADENCE_JITTER_MIN_MS 20 /* NDP sounding cadence jitter floor */ +#define VEIL_CADENCE_JITTER_MAX_MS 400 /* ... and ceiling (stays in-spec) */ + +/* ---- Daemon context --------------------------------------------------- */ +struct veil_ctx { + struct nl_sock *sock; /* generic-netlink socket to nl80211 */ + int family; /* resolved "nl80211" genl family id */ + int ifindex;/* target AP interface (e.g. phy0-ap0) */ + uint64_t key; /* shared session key for the keyed rotation */ + size_t passes; /* Givens passes */ + volatile sig_atomic_t running; +}; + +static struct veil_ctx g_ctx; + +static void on_signal(int sig) { (void)sig; g_ctx.running = 0; } + +/* ---------------------------------------------------------------------- */ +/* nl80211 bring-up — all REAL libnl-genl-3 API names. */ +/* ---------------------------------------------------------------------- */ +static int veil_nl_connect(struct veil_ctx *c) { + c->sock = nl_socket_alloc(); + if (!c->sock) { + fprintf(stderr, "veil: nl_socket_alloc failed\n"); + return -ENOMEM; + } + if (genl_connect(c->sock)) { + fprintf(stderr, "veil: genl_connect failed\n"); + return -EIO; + } + c->family = genl_ctrl_resolve(c->sock, "nl80211"); + if (c->family < 0) { + fprintf(stderr, "veil: genl_ctrl_resolve(nl80211) failed: %d\n", + c->family); + return c->family; + } + /* Observe MLME events (auth/assoc, and — where the driver forwards them — + * action-frame notifications). Real multicast group name is "mlme". */ + int grp = genl_ctrl_resolve_grp(c->sock, "nl80211", "mlme"); + if (grp >= 0) { + (void)nl_socket_add_membership(c->sock, grp); + } + return 0; +} + +/* ---------------------------------------------------------------------- */ +/* CONTROL 1 (FEASIBLE): TX antenna-map perturbation. */ +/* Rotating the allowed TX antenna bitmap changes the static spatial */ +/* mapping the PHY uses, coarsely perturbing the CSI a sensor observes. */ +/* This is a genuinely userspace-reachable, compliant knob. */ +/* NL80211_CMD_SET_WIPHY + NL80211_ATTR_WIPHY_ANTENNA_TX / _RX */ +/* NOTE: many drivers only accept this while the phy is DOWN, and only on */ +/* symmetric masks — validate per driver. Coarse, not the keyed rotation. */ +/* ---------------------------------------------------------------------- */ +static int veil_set_tx_antenna_mask(struct veil_ctx *c, + uint32_t tx_mask, uint32_t rx_mask) { + struct nl_msg *msg = nlmsg_alloc(); + if (!msg) return -ENOMEM; + genlmsg_put(msg, NL_AUTO_PORT, NL_AUTO_SEQ, c->family, 0, 0, + NL80211_CMD_SET_WIPHY, 0); + /* wiphy is addressed via the interface index on most drivers. */ + NLA_PUT_U32(msg, NL80211_ATTR_IFINDEX, (uint32_t)c->ifindex); + NLA_PUT_U32(msg, NL80211_ATTR_WIPHY_ANTENNA_TX, tx_mask); + NLA_PUT_U32(msg, NL80211_ATTR_WIPHY_ANTENNA_RX, rx_mask); + int ret = nl_send_auto(c->sock, msg); + nlmsg_free(msg); + if (ret < 0) return ret; + return nl_recvmsgs_default(c->sock); /* consume ACK/ERR */ +nla_put_failure: + nlmsg_free(msg); + return -EMSGSIZE; +} + +/* ---------------------------------------------------------------------- */ +/* CONTROL 2 (FEASIBLE, indirect): NDP sounding-cadence randomization. */ +/* mac80211/driver decides when to send NDP Announcement + NDP. There is */ +/* NO stable nl80211 attribute to set the sounding period directly, so the */ +/* compliant lever from userspace is hostapd's advertised sounding */ +/* capability and dimensions, toggled/rewritten over the hostapd ctrl */ +/* interface (RECONFIGURE / SET). We jitter the *offered* cadence. */ +/* */ +/* TODO(hw): there is no nl80211 "set sounding interval" command. Confirm */ +/* against hostapd ctrl_iface docs; the direct per-NDP timer lives in */ +/* driver/firmware. See INTEGRATION.md §2. Cite: */ +/* https://w1.fi/cgit/hostap/tree/hostapd/hostapd.conf */ +/* ---------------------------------------------------------------------- */ +static unsigned veil_next_cadence_ms(struct veil_ctx *c) { + /* Derive jitter deterministically from the session key stream so the + * paired receiver can anticipate the schedule (compliant, not random + * spraying). Reuses the core SplitMix64 for byte-identical behavior. */ + static veil_rng r; + static int seeded = 0; + if (!seeded) { veil_rng_seed(&r, c->key ^ 0xCADE11CEULL); seeded = 1; } + unsigned span = VEIL_CADENCE_JITTER_MAX_MS - VEIL_CADENCE_JITTER_MIN_MS; + return VEIL_CADENCE_JITTER_MIN_MS + + (unsigned)(veil_rng_next_f32(&r) * (float)span); +} + +static int veil_randomize_sounding_cadence(struct veil_ctx *c) { + unsigned ms = veil_next_cadence_ms(c); + /* TODO(hw): push `ms` into the offered sounding cadence. On OpenWRT the + * realistic path is the hostapd ctrl_iface (UNIX socket at + * /var/run/hostapd/): rewrite he/vht sounding-dimension or toggle + * beamformer capability and RECONFIGURE. mac80211 has no direct knob. + * This function currently only computes the schedule. */ + fprintf(stderr, "veil: [feasible/indirect] next sounding jitter = %u ms " + "(TODO(hw): apply via hostapd ctrl_iface)\n", ms); + return 0; +} + +/* ---------------------------------------------------------------------- */ +/* CONTROL 3 (MOSTLY BLOB-BLOCKED): MU-MIMO group shuffling. */ +/* The MU group definition + steering matrices are computed and applied in */ +/* the WiFi MCU firmware on mt76 (mt7915) and all ath1x parts. There is no */ +/* generic nl80211 command to reshuffle MU groups. Only a vendor subcmd */ +/* (NL80211_CMD_VENDOR) on a driver that chose to expose one could do it. */ +/* ---------------------------------------------------------------------- */ +static int veil_shuffle_mumimo_groups(struct veil_ctx *c) { + (void)c; + /* TODO(hw): requires NL80211_CMD_VENDOR + a driver-specific + * NL80211_ATTR_VENDOR_ID / _SUBCMD / _DATA that does not exist upstream + * for mt76/ath. Without a driver+firmware patch this is unreachable. + * See INTEGRATION.md §3. Left as an explicit no-op, not a fake success. */ + fprintf(stderr, "veil: [blob-blocked] MU-MIMO group shuffle needs a " + "vendor subcmd / firmware patch (TODO(hw))\n"); + return -ENOTSUP; +} + +/* ---------------------------------------------------------------------- */ +/* CONTROL 4 (BLOB-BLOCKED on commodity AP silicon): the keyed rotation. */ +/* This is the actual VEIL transform — a keyed Givens rotation on the fine */ +/* subspace of the compressed beamforming feedback (the phi/psi angles), */ +/* or equivalently a unitary Q on the LTF spatial mapping. On mt76/ath the */ +/* feedback report is generated and the precoder applied inside firmware, */ +/* so userspace cannot edit it. This function shows WHERE the core plugs */ +/* in for the platforms that CAN reach the buffer (openwifi FPGA datapath, */ +/* Nexmon Broadcom patch) — it operates on a caller-supplied fine block. */ +/* ---------------------------------------------------------------------- */ +static int veil_apply_keyed_rotation(struct veil_ctx *c, + float *fine, size_t n) { + if (!fine || n < 2) return -EINVAL; + /* Pure, orthogonal, energy-preserving (the "not jamming" invariant). */ + float before = veil_l2_norm(fine, n); + veil_shield_apply(fine, n, c->key, c->passes); + float after = veil_l2_norm(fine, n); + /* TODO(hw): on OpenWRT there is NO userspace/mac80211 hook that hands us + * this buffer before TX. Reaching it requires a driver+firmware patch + * (mt76 MCU / ath) to expose the pre-precoder V/steering matrix, OR use + * the openwifi (FPGA) or Nexmon adapters. See INTEGRATION.md §4. + * We only prove the math is invariant here; nothing goes on air. */ + fprintf(stderr, "veil: [blob-blocked path] rotated %zu coeffs, " + "L2 %.6f -> %.6f (delta %.2e; must be ~0)\n", + n, before, after, (double)(after - before)); + return 0; +} + +/* ---------------------------------------------------------------------- */ +/* Event loop: watch for sensing-solicitation cadence. */ +/* We register interest in MLME/frame events. On commodity drivers the raw */ +/* NDP Announcement is NOT forwarded to userspace, so honest detection of */ +/* an *external* sensing solicitation needs monitor-mode capture or a */ +/* driver notification that does not exist upstream — marked TODO(hw). */ +/* ---------------------------------------------------------------------- */ +static int veil_event_cb(struct nl_msg *msg, void *arg) { + struct veil_ctx *c = (struct veil_ctx *)arg; + struct genlmsghdr *gnlh = nlmsg_data(nlmsg_hdr(msg)); + switch (gnlh->cmd) { + case NL80211_CMD_FRAME: + /* TODO(hw): parse NL80211_ATTR_FRAME; classify VHT/HE compressed + * beamforming action (category 21/30) or NDPA to measure solicitation + * cadence. Requires the driver to forward these frames (registered via + * NL80211_CMD_REGISTER_FRAME / monitor). Not guaranteed upstream. */ + (void)veil_randomize_sounding_cadence(c); + break; + case NL80211_CMD_NEW_STATION: + case NL80211_CMD_DEL_STATION: + /* Membership churn changes MU grouping surface. */ + (void)veil_shuffle_mumimo_groups(c); + break; + default: + break; + } + return NL_SKIP; +} + +static void usage(const char *p) { + fprintf(stderr, + "Usage: %s -i [-k ] [-p ]\n" + " BUILD-ONLY / UNTESTED-ON-HARDWARE. See README.md.\n", p); +} + +int main(int argc, char **argv) { + memset(&g_ctx, 0, sizeof(g_ctx)); + g_ctx.key = 0xA5A5A5A5A5A5A5A5ULL; /* placeholder; real key from keystore */ + g_ctx.passes = VEIL_DEFAULT_PASSES; + g_ctx.ifindex = -1; + g_ctx.running = 1; + + int opt; + while ((opt = getopt(argc, argv, "i:k:p:h")) != -1) { + switch (opt) { + case 'i': g_ctx.ifindex = atoi(optarg); break; + case 'k': g_ctx.key = strtoull(optarg, NULL, 16); break; + case 'p': g_ctx.passes = (size_t)strtoul(optarg, NULL, 10); break; + case 'h': default: usage(argv[0]); return (opt == 'h') ? 0 : 2; + } + } + if (g_ctx.ifindex < 0) { usage(argv[0]); return 2; } + + fprintf(stderr, "veil_shieldd: SYNTHETIC/L0 build-only scaffold — " + "no RF is emitted, nothing is validated on silicon.\n"); + + signal(SIGINT, on_signal); + signal(SIGTERM, on_signal); + + if (veil_nl_connect(&g_ctx)) return 1; + + /* Install the event callback (valid-message path). */ + nl_socket_modify_cb(g_ctx.sock, NL_CB_VALID, NL_CB_CUSTOM, + veil_event_cb, &g_ctx); + nl_socket_disable_seq_check(g_ctx.sock); /* required for multicast events */ + + /* Self-check the one genuinely feasible active control at startup. Comment + * this out on a live AP; it may bounce the radio depending on the driver. + * (void)veil_set_tx_antenna_mask(&g_ctx, 0x3, 0x3); */ + (void)veil_set_tx_antenna_mask; + + /* Prove the linked core is byte-consistent (no radio involved). */ + { + float demo[8] = {1,0,0,0,0,0,0,0}; + (void)veil_apply_keyed_rotation(&g_ctx, demo, 8); + veil_shield_recover(demo, 8, g_ctx.key, g_ctx.passes); + fprintf(stderr, "veil: recover round-trip demo[0]=%.6f (expect ~1.0)\n", + (double)demo[0]); + } + + while (g_ctx.running) { + int r = nl_recvmsgs_default(g_ctx.sock); + if (r < 0 && r != -NLE_AGAIN) { + fprintf(stderr, "veil: nl_recvmsgs_default: %d\n", r); + break; + } + } + + nl_socket_free(g_ctx.sock); + return 0; +} diff --git a/wifi-veil/harness/.claude-plugin/plugin.json b/wifi-veil/harness/.claude-plugin/plugin.json new file mode 100644 index 00000000..d3d8ede7 --- /dev/null +++ b/wifi-veil/harness/.claude-plugin/plugin.json @@ -0,0 +1,25 @@ +{ + "name": "wifi-veil-harness", + "version": "0.1.0", + "description": "Harness for wifi-veil (WiFi Veil privacy shield)", + "author": { + "displayName": "Generated by metaharness", + "url": "https://www.npmjs.com/package/metaharness" + }, + "license": "MIT", + "categories": [ + "agent-harness", + "metaharness-scaffold", + "Engineering", + "software-engineering" + ], + "tags": [ + "metaharness", + "agent-harness", + "vertical:coding", + "software-engineering", + "wifi-sensing", + "privacy" + ], + "homepage": "https://github.com/ruvnet/agent-harness-generator" +} diff --git a/wifi-veil/harness/.claude/settings.json b/wifi-veil/harness/.claude/settings.json new file mode 100644 index 00000000..c27be20f --- /dev/null +++ b/wifi-veil/harness/.claude/settings.json @@ -0,0 +1,21 @@ +{ + "permissions": { + "allow": [ + "Bash(npx wifi-veil-harness*)", + "mcp__wifi-veil-harness__*", + "Bash(npm test*)", + "Bash(npm run*)", + "Bash(cargo test*)", + "Bash(cargo clippy*)", + "Bash(git diff*)", + "Bash(git status*)", + "Bash(git log*)" + ], + "deny": [ + "Read(./.env)", + "Read(./.env.*)", + "Bash(git push*)", + "Bash(rm -rf*)" + ] + } +} diff --git a/wifi-veil/harness/.gitignore b/wifi-veil/harness/.gitignore new file mode 100644 index 00000000..f4e2c6d6 --- /dev/null +++ b/wifi-veil/harness/.gitignore @@ -0,0 +1,3 @@ +node_modules/ +dist/ +*.tsbuildinfo diff --git a/wifi-veil/harness/.harness/manifest.json b/wifi-veil/harness/.harness/manifest.json new file mode 100644 index 00000000..5bf6af68 --- /dev/null +++ b/wifi-veil/harness/.harness/manifest.json @@ -0,0 +1,36 @@ +{ + "schema": 1, + "generator": "0.1.0", + "template": "vertical:coding", + "template_version": "0.0.0", + "vars": { + "name": "wifi-veil-harness", + "description": "Harness for wifi-veil (WiFi Veil privacy shield)", + "host": "claude-code" + }, + "hosts": [ + "claude-code" + ], + "files": { + ".claude/settings.json": "b165b8dc3723febae34825e803d52857364f4574d617286b26e760fb6dc3020e", + ".claude-plugin/plugin.json": "884bb65b7244312a9648b2c2367ca7c088360e5dc1c8d625bd7c99c012824d12", + "bin/cli.js": "3a295534817c34bb01943f8d7964ecca822f8126daae726139f9e3cebd1694e5", + "CLAUDE.md": "8ebac3a49fd54723e1dc33cc8a808ec22776a5b5837361f84f3453f50ce88752", + "package.json": "76d772b504e795f763baa48b1660d3690768a70543fa8c3603771fbcf7d9c6ca", + "README.md": "ea0b98ce683096494e64466014d6578df16263ba68eb5b7a740d2e7b10dbcb58", + "src/init.ts": "1ca3baf35f6d0d95babb8022402531b212b70cf7318c5dd475485f52de117b9b", + "src/router.ts": "7c5eaebbe7061a1912250397271d460b517104de1b80f6861ad629529fde190d", + "src/flywheel.ts": "d8707cfc6d705e2999f4a61015d4392f7ce3f6bf480d7d50ded67b98e63c13e8", + "tsconfig.json": "8b4e730a1aa39162ac574455d7a98e1881f5313ca80ffe503b9652dcf0c76b9d", + "vitest.config.ts": "021b33ec623593effc3d163020479a91a1179329ee4ed1cb25f2dd9388e19820", + "__tests__/smoke.test.ts": "551d8835dbc8a2a617e3c35516c621e9e8694a42429dbb9dea2b4a43eea428be", + "__tests__/router.test.ts": "e2536fe37a5cac02e7a54188bc72a3e2e0809ab67655746ac1550c5c3ba69708", + "__tests__/flywheel.test.ts": "fe90a341fd18e56609a360f82b3567e9ef520b2181f4f0387bbf1b52776a29d0", + "__tests__/guidance.test.ts": "452553504887d6bf059123cb677e8b881cf09f8bf09d5bc259ed882161f79570", + "LICENSE": "07b1a7c2aa25991872e3594de2ecb64ff6b4c5d3dc2376dd5b9e9f77c4b258e8" + }, + "generated_at": "2026-08-09T00:00:00.000Z", + "meta": { + "surface": "cli" + } +} diff --git a/wifi-veil/harness/.harness/manifest.sha256 b/wifi-veil/harness/.harness/manifest.sha256 new file mode 100644 index 00000000..2674b6e7 --- /dev/null +++ b/wifi-veil/harness/.harness/manifest.sha256 @@ -0,0 +1 @@ +da48afb45d776c10f1841331facf65aa7ba4802f990a2480b91227fc100d4a47 diff --git a/wifi-veil/harness/CLAUDE.md b/wifi-veil/harness/CLAUDE.md new file mode 100644 index 00000000..0659744d --- /dev/null +++ b/wifi-veil/harness/CLAUDE.md @@ -0,0 +1,67 @@ +# wifi-veil-harness + +Harness for [`wifi-veil`](..) +(WiFi Veil — the compliant-waveform WiFi-sensing privacy shield, ADR-288). This +package is defined by ADR-289. + +> Advanced Coding harness · domain: `software-engineering`. Modeled on the +> `wifi-densepose-sar-harness` scaffold (ADR-286), generated with +> [create-agent-harness](https://github.com/ruvnet/agent-harness-generator). + +## Behavioral rules + +- Use the harness's tools for orchestration; memory and routing are handled by + the kernel. +- Defer destructive operations to the user. +- **Never present WiFi sensing as camera-grade, and never relabel WiFi Veil's + SYNTHETIC/L0 results as MEASURED** — a hardware witness is required first + (CLAUDE.md hardware rule; ADR-282 ladder). The harness is a development aid; + it does not run a radio and cannot emit RF. +- WiFi Veil uses compliant waveform controls only — **never jamming.** Do not add, + suggest, or scaffold interference-based "defenses." + +## Commands + +- `init` — boot the kernel + host adapter. +- `doctor` — verify the install end-to-end (kernel, host, guidance map). +- `guidance --topic [--query ]` — read-only WiFi Veil capability map + (dependency-free; topics: `overview`, `threat`, `countermeasure`, + `compliance`, `optimization`, `experiment`). Source-cited and + evidence-labelled; navigation only, not authority. +- `route ` — cost-optimal model routing via + `@metaharness/router` (needs `npm run build`). +- `flywheel [generations]` — SYNTHETIC self-improvement demo via + `@metaharness/flywheel` (needs `npm run build`). + +## Architecture + +Uses [@metaharness/kernel](https://www.npmjs.com/package/@metaharness/kernel) +(Rust-compiled WASM with a NAPI-RS native fallback) so the same code runs on +every platform. The `@metaharness/*` packages are imported *dynamically* inside +the commands that need them, so `guidance`/`--help` work with no dependencies +installed. + +### Darwin, router, flywheel + +- **Darwin Mode** (`@metaharness/darwin`, devDependency) — `npm run evolve` / + `evolve:dry` mutates the harness's own config and keeps only measurable + improvements. +- **Router** (`@metaharness/router`) — `src/router.ts` wires a real cost-optimal + `Router` (`qualityBar: 0.8`) over two model tiers. Its labelled examples are + illustrative seed data (see the file's honesty note), not measured eval-log + observations. +- **Flywheel** (`@metaharness/flywheel`) — `src/flywheel.ts` wires the real + promotion loop (propose → evaluate → gate → promote, Ed25519-signed, + independently replayable) with a SYNTHETIC proposer/evaluator + (`dataSource: 'SYNTHETIC'`, no model call). A LIVE run needs a real Proposer + and Evaluator supplied by the operator — see the file's comments. + +## Relationship to the crate + +This harness assists development *on* the WiFi Veil crate; it does not replace the +crate's own gates. The authoritative validation for a WiFi Veil change is still: + +```bash +cargo test +cargo clippy --all-targets -- -D warnings +``` diff --git a/wifi-veil/harness/LICENSE b/wifi-veil/harness/LICENSE new file mode 100644 index 00000000..c77a3a09 --- /dev/null +++ b/wifi-veil/harness/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 wifi-densepose-privshield-harness authors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/wifi-veil/harness/README.md b/wifi-veil/harness/README.md new file mode 100644 index 00000000..814bea68 --- /dev/null +++ b/wifi-veil/harness/README.md @@ -0,0 +1,68 @@ +# wifi-veil-harness + +A metaharness (contributor harness) for +[`wifi-veil`](..) — **WiFi Veil**, +the compliant-waveform WiFi-sensing privacy shield (ADR-288). Defined by ADR-289. + +> **Advanced Coding** — architect → implement → review → test, plus a +> dependency-free WiFi Veil guidance surface. Modeled on `wifi-densepose-sar-harness` +> (ADR-286). Multi-host scaffold with a kernel that resolves native → wasm → js. + +## Install + +```bash +npm install -g wifi-veil-harness +wifi-veil-harness doctor +``` + +Or run without installing: + +```bash +npx wifi-veil-harness guidance --topic overview +``` + +## Commands + +| Command | Deps needed | Purpose | +|---|---|---| +| `init` | kernel + host | Boot the kernel + host adapter | +| `doctor` | kernel + host | Verify the install end-to-end | +| `guidance --topic ` | **none** | Read-only WiFi Veil capability map (source-cited, evidence-labelled) | +| `route ` | router + `npm run build` | Cost-optimal model routing | +| `flywheel [gens]` | flywheel + `npm run build` | SYNTHETIC self-improvement demo | + +`guidance` topics: `overview`, `threat`, `countermeasure`, `compliance`, +`optimization`, `experiment`. It needs no dependencies or build step, so it +works offline and in CI before `npm install`. + +## What WiFi Veil is + +WiFi Veil shapes a node's **own** beamforming feedback with keyed Givens rotations so +a third-party passive sniffer cannot re-identify people, while a keyed receiver +sees an essentially unchanged link. **Compliant waveform controls only — never +jamming.** Reference results are **SYNTHETIC / evidence level L0** (reproduced by +`cargo test`), never MEASURED until a hardware witness exists. See the crate's +[ADR-288](../../docs/adr/ADR-288-veil-privacy-shield-compliant-waveform.md) and +[research bundle](../../docs/research/privacy-shield/). + +## Darwin, router, flywheel + +- `npm run evolve` / `evolve:dry` — Darwin Mode self-mutation of the harness + config (`@metaharness/darwin`). +- `npm run route -- ` (after `npm run build`) — cost-optimal + model routing (`@metaharness/router`). +- `npm run flywheel:dry` — the SYNTHETIC `@metaharness/flywheel` demo + (propose → evaluate → gate → promote, signed + independently replayable). + +See `CLAUDE.md` and the honesty notes atop `src/router.ts` / `src/flywheel.ts` +for what is real wiring vs. illustrative/synthetic data. + +## Scope + +The harness is a **development aid**. It does not run a WiFi Veil radio, does not +emit RF, and cannot jam. It does not replace the crate's own gates — the +authoritative check for a WiFi Veil change is `cargo test`. + +## License + +MIT diff --git a/wifi-veil/harness/__tests__/flywheel.test.ts b/wifi-veil/harness/__tests__/flywheel.test.ts new file mode 100644 index 00000000..a4b39ca5 --- /dev/null +++ b/wifi-veil/harness/__tests__/flywheel.test.ts @@ -0,0 +1,26 @@ +// SPDX-License-Identifier: MIT +// Verifies the SYNTHETIC flywheel demo wires end-to-end: a non-empty lift curve +// and a replay bundle that verifies independently. Does NOT assert any real +// self-improvement — the proposer/evaluator are deterministic stand-ins. + +import { describe, it, expect } from 'vitest'; +import { runVeilFlywheelDemo, verifyVeilFlywheelDemo } from '../src/flywheel.js'; + +describe('wifi-veil-harness — flywheel (SYNTHETIC)', () => { + it('produces a non-empty lift curve', async () => { + const result = await runVeilFlywheelDemo(3); + expect(result.liftCurve.length).toBeGreaterThan(0); + expect(result.generationsRun).toBeGreaterThan(0); + }); + + it('produces an independently verifiable replay bundle', async () => { + const result = await runVeilFlywheelDemo(3); + const verdict = verifyVeilFlywheelDemo(result); + expect(verdict.pass).toBe(true); + }); + + it('stamps the run as SYNTHETIC provenance', async () => { + const result = await runVeilFlywheelDemo(2); + expect(result.replayBundle.data_source).toBe('SYNTHETIC'); + }); +}); diff --git a/wifi-veil/harness/__tests__/guidance.test.ts b/wifi-veil/harness/__tests__/guidance.test.ts new file mode 100644 index 00000000..d422619a --- /dev/null +++ b/wifi-veil/harness/__tests__/guidance.test.ts @@ -0,0 +1,34 @@ +// SPDX-License-Identifier: MIT +// The VEIL guidance map is dependency-free (no @metaharness/* import), so this +// test runs even before `npm install` resolves the kernel. It guards the +// read-only capability map the MCP/CLI `guidance` surface exposes. + +import { describe, it, expect } from 'vitest'; +import { run, guidanceReport } from '../bin/cli.js'; + +describe('wifi-veil-harness — guidance', () => { + it('returns a source-cited report for a known topic', () => { + const r = guidanceReport('optimization'); + expect(r.ok).toBe(true); + expect(r.summary.length).toBeGreaterThan(0); + expect(r.sources.some((s: string) => s.includes('optimize.rs'))).toBe(true); + expect(r.authority).toContain('read-only'); + }); + + it('labels evidence as SYNTHETIC/L0', () => { + const r = guidanceReport('experiment'); + expect(r.evidence).toContain('SYNTHETIC'); + }); + + it('rejects an unknown topic and lists the valid ones', () => { + const r = guidanceReport('not-a-topic'); + expect(r.ok).toBe(false); + expect(r.topics).toContain('overview'); + expect(r.topics).toContain('compliance'); + }); + + it('CLI `guidance --topic overview` exits 0; unknown topic exits non-zero', async () => { + expect(await run(['guidance', '--topic', 'overview'])).toBe(0); + expect(await run(['guidance', '--topic', 'nope'])).not.toBe(0); + }); +}); diff --git a/wifi-veil/harness/__tests__/router.test.ts b/wifi-veil/harness/__tests__/router.test.ts new file mode 100644 index 00000000..6c8ae036 --- /dev/null +++ b/wifi-veil/harness/__tests__/router.test.ts @@ -0,0 +1,24 @@ +// SPDX-License-Identifier: MIT +// Verifies the cost-optimal router mechanism (not its illustrative data): cheap +// query shapes route to the cheap tier; hard shapes escalate to the frontier. + +import { describe, it, expect } from 'vitest'; +import { routeVeilQuery } from '../src/router.js'; + +describe('wifi-veil-harness — router', () => { + it('routes a threat-model query (cheap-tier-capable) to the cheap tier', () => { + const pick = routeVeilQuery([1, 0, 0, 0]); + expect(pick.id).toBe('cheap-tier'); + expect(pick.metBar).toBe(true); + }); + + it('escalates a compliance-review query to the frontier tier', () => { + const pick = routeVeilQuery([0, 1, 0, 0]); + expect(pick.id).toBe('frontier-tier'); + }); + + it('escalates an optimizer-tuning query to the frontier tier', () => { + const pick = routeVeilQuery([0, 0, 1, 0]); + expect(pick.id).toBe('frontier-tier'); + }); +}); diff --git a/wifi-veil/harness/__tests__/smoke.test.ts b/wifi-veil/harness/__tests__/smoke.test.ts new file mode 100644 index 00000000..3b1d4243 --- /dev/null +++ b/wifi-veil/harness/__tests__/smoke.test.ts @@ -0,0 +1,35 @@ +// SPDX-License-Identifier: MIT +// A real smoke test for wifi-veil-harness: it boots the actual +// kernel + host adapter the harness depends on, so `npm test` fails loudly if +// @metaharness/kernel or @metaharness/host-claude-code is missing, broken, or +// version-skewed. Fastest signal that `npm install` produced a runnable harness. + +import { describe, it, expect } from 'vitest'; +import { loadKernel } from '@metaharness/kernel'; +import adapter from '@metaharness/host-claude-code'; +import { run } from '../bin/cli.js'; + +describe('wifi-veil-harness — install smoke test', () => { + it('loads the kernel and reports a version + a known backend', async () => { + const kernel = await loadKernel(); + const info = kernel.kernelInfo(); + expect(typeof info.version).toBe('string'); + expect(info.version.length).toBeGreaterThan(0); + expect(['native', 'wasm', 'js']).toContain(kernel.backend); + }); + + it('resolves the host adapter with a name', () => { + expect(typeof adapter.name).toBe('string'); + expect(adapter.name.length).toBeGreaterThan(0); + }); + + it('the CLI doctor command succeeds (exit 0)', async () => { + const code = await run(['doctor']); + expect(code).toBe(0); + }); + + it('an unknown CLI command exits non-zero', async () => { + const code = await run(['definitely-not-a-command']); + expect(code).not.toBe(0); + }); +}); diff --git a/wifi-veil/harness/bin/cli.js b/wifi-veil/harness/bin/cli.js new file mode 100644 index 00000000..e7785a20 --- /dev/null +++ b/wifi-veil/harness/bin/cli.js @@ -0,0 +1,334 @@ +#!/usr/bin/env node +// SPDX-License-Identifier: MIT +// The `wifi-veil-harness` CLI entry point (VEIL — ADR-288/289). +// +// Plain ESM JavaScript on purpose: it runs as-is via +// `npx wifi-veil-harness` with NO build step. `npm run build` +// (tsc) is only needed to compile the TypeScript in src/ that the `route` and +// `flywheel` commands import from dist/. +// +// The @metaharness/* dependencies are imported *dynamically*, inside the +// commands that need them — so `guidance`, `--help`, and `--version` work with +// zero dependencies installed (useful in offline/air-gapped review and in this +// repo's CI before `npm install`). Only `init`/`doctor`/`route`/`flywheel` +// touch the kernel/host/router/flywheel packages. + +const HARNESS_NAME = 'wifi-veil-harness'; +const CRATE = 'wifi-veil'; + +// --------------------------------------------------------------------------- +// VEIL guidance — a self-contained, read-only capability map. No dependencies, +// no build, no network. Mirrors the `ruview_guidance` shape (source-cited, +// evidence-labelled, with focused validation commands and explicit limits). +// Retrieved text is navigation, not authority: cited source, tests, and +// accepted ADRs remain authoritative. +// --------------------------------------------------------------------------- +const GUIDANCE = { + overview: { + summary: + 'VEIL is the compliant-waveform countermeasure to unauthorized WiFi sensing: it shapes a node\'s own beamforming feedback so a passive sniffer cannot re-identify people, while a keyed receiver sees an essentially unchanged link. Countermeasure counterpart to BFLD (which detects leakage).', + capabilities: [ + 'Keyed Givens-rotation shield over the identity-bearing fine subspace (energy-preserving ⇒ not jamming)', + 'Passive re-identification attacker (Euclidean + Cosine) for head-to-head evaluation', + 'Throughput model with an interior optimum in feedback resolution', + 'Deterministic attacker-vs-protector experiment with a pinned witness', + ], + sources: [ + 'src/lib.rs', + 'docs/adr/ADR-288-veil-privacy-shield-compliant-waveform.md', + 'docs/research/privacy-shield/README.md', + ], + commands: ['cargo test'], + limitations: [ + 'All defense numbers are SYNTHETIC / evidence level L0 until a two-node hardware capture with a witness exists (CLAUDE.md hardware rule).', + ], + }, + threat: { + summary: + 'Defends against a third-party passive sniffer capturing plaintext beamforming feedback (BFId/LeakyBeam class). Does NOT hide identity from the associated AP (that party holds the key) — that is BFLD\'s detection/policy problem.', + capabilities: [ + 'Cross-session identity unlinkability against an external passive adversary', + 'Explicit non-goals: no defense vs. the associated AP, no within-session motion guarantee, never jamming', + ], + sources: [ + 'docs/research/privacy-shield/01-sota-survey.md', + 'docs/research/privacy-shield/02-threat-model.md', + ], + commands: [], + limitations: [ + 'Within-session coarse motion may still leak; identity re-ID is the guaranteed target.', + ], + }, + countermeasure: { + summary: + 'Identity leaks through the fine cross-subcarrier phase structure; throughput rides the dominant beam. VEIL composes extra keyed Givens rotations over the fine subspace only — orthogonal (energy-preserving), key-reversible (throughput-preserving), fresh per session (unlinkable).', + capabilities: [ + 'protector.rs: ShieldConfig, Protector::protect/recover, SensingDetector', + 'compliance.rs: machine-checkable energy-conservation ("not jamming") audit', + ], + sources: [ + 'src/protector.rs', + 'src/compliance.rs', + 'docs/research/privacy-shield/03-countermeasure-design.md', + ], + commands: ['cargo test protector'], + limitations: [ + 'The two-subspace separability is a model abstraction; real hardware is only approximately separable.', + ], + }, + compliance: { + summary: + 'Compliant waveform controls only, never jamming. The keyed rotation is orthogonal, so it preserves the report energy exactly (ratio ≈ 1.0) — it adds no interfering emission. Jamming (47 U.S.C. §333/§302a) is defined by interfering with OTHERS\' transmissions, not shaping your own.', + capabilities: [ + 'ComplianceReport::audit / is_compliant — energy ratio + non-interference verdict', + ], + sources: [ + 'src/compliance.rs', + 'docs/research/privacy-shield/04-compliance-and-regulatory.md', + ], + commands: ['cargo test compliance'], + limitations: [ + 'Engineering analysis, not legal advice; RF power/mask/timing limits are jurisdiction-specific.', + ], + }, + optimization: { + summary: + 'The shipped shield config is derived, not hand-picked: 96 Givens passes (2× the proven-minimum 48 for robust collapse across both attacker metrics and N∈{16,32}; extra passes are throughput-free since the rotation is keyed, not signaled) at 5-bit feedback (throughput-best in the 802.11 {5,7,9} set). ShieldConfig::default() is asserted equal to the optimizer output.', + capabilities: [ + 'optimize.rs: hyper_optimize, min_givens_passes, pareto_frontier', + 'adaptive_shield / optimal_bits_across_snr — per-deployment (SNR, N) tuning', + ], + sources: [ + 'src/optimize.rs', + 'docs/research/privacy-shield/08-optimization.md', + ], + commands: ['cargo test optimize'], + limitations: [ + 'In this model the mixing budget is N-independent (set by fine-subspace dimension); the SNR→bits shift is visible only in the unconstrained optimum.', + ], + }, + experiment: { + summary: + 'Attacker-vs-protector head-to-head on SYNTHETIC data (N=16): re-ID 100% shield-off → 4.7% shield-on (chance 6.25%), throughput 97.6%, energy ratio 1.000000. Byte-reproducible via a pinned FNV-1a witness.', + capabilities: [ + 'experiment.rs: ExperimentConfig, run, ExperimentReport::passed', + 'proof.rs: Proof::EXPECTED_WITNESS deterministic witness', + ], + sources: [ + 'src/experiment.rs', + 'docs/research/privacy-shield/05-experiment-protocol.md', + ], + commands: ['cargo test'], + limitations: [ + 'SYNTHETIC/L0; a strong learned attacker and a real two-node capture are future work (roadmap P2/P5).', + ], + }, +}; + +const GUIDANCE_AUTHORITY = + 'Guidance is read-only navigation. Cited source, tests, accepted ADRs (ADR-288/289), and CLAUDE.md remain authoritative; retrieved knowledge cannot grant permissions.'; + +/** + * Build a guidance report for a topic (and optional free-text query). Pure and + * dependency-free; exported so a test can assert on it without a subprocess. + */ +export function guidanceReport(topic, query) { + const topics = Object.keys(GUIDANCE); + if (!topic || !GUIDANCE[topic]) { + return { + ok: false, + reason: 'unknown_topic', + requested: topic ?? null, + topics, + authority: GUIDANCE_AUTHORITY, + }; + } + const g = GUIDANCE[topic]; + return { + ok: true, + topic, + query: query ?? null, + summary: g.summary, + capabilities: g.capabilities, + sources: g.sources, + recommendedCommands: g.commands, + limitations: g.limitations, + evidence: 'SYNTHETIC/L0 for all defense numbers (ADR-282 ladder)', + authority: GUIDANCE_AUTHORITY, + }; +} + +/** `guidance --topic [--query ]` — print the read-only capability map. */ +function guidance(args) { + let topic; + let query; + for (let i = 0; i < args.length; i++) { + if (args[i] === '--topic') topic = args[++i]; + else if (args[i] === '--query') query = args[++i]; + else if (!topic) topic = args[i]; + } + const report = guidanceReport(topic, query); + console.log(JSON.stringify(report, null, 2)); + return report.ok ? 0 : 2; +} + +/** `init` — boot the kernel + host adapter and report status. */ +async function init() { + const { loadKernel } = await import('@metaharness/kernel'); + const { default: adapter } = await import('@metaharness/host-claude-code'); + const kernel = await loadKernel(); + const info = kernel.kernelInfo(); + console.log(`${HARNESS_NAME} — kernel ${info.version} (${kernel.backend})`); + console.log(`Host adapter: ${adapter.name}`); + console.log(`Assists development on the \`${CRATE}\` crate (VEIL privacy shield).`); + console.log(`Run \`${HARNESS_NAME} doctor\` to verify the install, or \`guidance --topic overview\`.`); + return 0; +} + +/** `doctor` — verify the install end-to-end (kernel + host resolve). */ +async function doctor() { + const { loadKernel } = await import('@metaharness/kernel'); + const { default: adapter } = await import('@metaharness/host-claude-code'); + const kernel = await loadKernel(); + const info = kernel.kernelInfo(); + const checks = [ + ['kernel loads', !!kernel], + ['kernel reports a version', typeof info.version === 'string' && info.version.length > 0], + ['kernel backend is native|wasm|js', ['native', 'wasm', 'js'].includes(kernel.backend)], + ['host adapter has a name', typeof adapter?.name === 'string' && adapter.name.length > 0], + ['guidance map resolves', guidanceReport('overview').ok === true], + ]; + let ok = true; + for (const [label, pass] of checks) { + console.log(`${pass ? 'PASS' : 'FAIL'} ${label}`); + if (!pass) ok = false; + } + console.log( + ok + ? `\n${HARNESS_NAME}: all checks passed (kernel ${info.version}, ${kernel.backend} backend, host ${adapter.name})` + : `\n${HARNESS_NAME}: doctor found problems`, + ); + return ok ? 0 : 1; +} + +/** + * `route ` — route a 4-axis task embedding to the + * cost-optimal model tier via @metaharness/router. Needs `npm run build`. + */ +async function route(args) { + const embedding = args.map(Number); + if (embedding.length !== 4 || embedding.some((n) => Number.isNaN(n))) { + console.error( + `Usage: ${HARNESS_NAME} route (four 0..1 numbers)`, + ); + return 2; + } + let routeVeilQuery; + try { + ({ routeVeilQuery } = await import('../dist/router.js')); + } catch (err) { + console.error(`route: dist/router.js not found — run \`npm run build\` first. (${err.message})`); + return 1; + } + const pick = routeVeilQuery(embedding); + console.log( + `route -> ${pick.id} (predicted quality ${pick.predictedQuality.toFixed(3)}, $${pick.costPerMTok}/MTok, met bar: ${pick.metBar})`, + ); + return 0; +} + +/** + * `flywheel [generations]` — run the SYNTHETIC @metaharness/flywheel demo and + * print the lift curve + an independent replay-bundle verification. Needs + * `npm run build`. + */ +async function flywheel(args) { + const generations = args[0] ? Number(args[0]) : 3; + if (Number.isNaN(generations) || generations < 1) { + console.error(`Usage: ${HARNESS_NAME} flywheel [generations>=1]`); + return 2; + } + let runVeilFlywheelDemo, verifyVeilFlywheelDemo; + try { + ({ runVeilFlywheelDemo, verifyVeilFlywheelDemo } = await import('../dist/flywheel.js')); + } catch (err) { + console.error(`flywheel: dist/flywheel.js not found — run \`npm run build\` first. (${err.message})`); + return 1; + } + console.log(`Running ${generations}-generation flywheel demo (dataSource: SYNTHETIC — see src/flywheel.ts)...`); + const result = await runVeilFlywheelDemo(generations); + for (const point of result.liftCurve) { + console.log(` gen ${point.generation}: primary=${point.primary.toFixed(3)} delta=${point.delta.toFixed(3)} anchor=${point.anchor ?? 'n/a'}`); + } + const verdict = verifyVeilFlywheelDemo(result); + console.log(`generations run: ${result.generationsRun} · promotions: ${result.promotions.length} · replay verified: ${verdict.pass}`); + return verdict.pass ? 0 : 1; +} + +/** + * Dispatch one CLI invocation. Exported (not just run on import) so a test can + * drive it without spawning a subprocess. Returns the intended exit code. + */ +export async function run(argv) { + const cmd = argv[0] ?? 'init'; + switch (cmd) { + case 'init': + return init(); + case 'doctor': + return doctor(); + case 'guidance': + return guidance(argv.slice(1)); + case 'route': + return route(argv.slice(1)); + case 'flywheel': + return flywheel(argv.slice(1)); + case '--version': + case '-v': { + const { loadKernel } = await import('@metaharness/kernel'); + const kernel = await loadKernel(); + console.log(kernel.version()); + return 0; + } + case '--help': + case '-h': + console.log( + `Usage: ${HARNESS_NAME} \n\n` + + ` init boot the kernel + host adapter (default)\n` + + ` doctor verify the install end-to-end\n` + + ` guidance --topic read-only VEIL capability map (no deps/build)\n` + + ` topics: overview threat countermeasure compliance optimization experiment\n` + + ` route cost-optimal model routing (needs \`npm run build\`)\n` + + ` flywheel [generations] SYNTHETIC self-improvement demo (needs \`npm run build\`)\n` + + ` --version print the kernel version`, + ); + return 0; + default: + console.error(`Unknown command: ${cmd}. Try \`${HARNESS_NAME} --help\`.`); + return 2; + } +} + +// CLI guard: execute only when invoked directly (not when imported by a test). +// npm's bin shims pass a NON-normalized argv[1], so realpath BOTH sides before +// comparing — a naive string === misses the npx/shim path and the CLI no-ops. +import { fileURLToPath } from 'node:url'; +import { realpathSync } from 'node:fs'; +import { argv } from 'node:process'; +const invokedDirectly = (() => { + if (!argv[1]) return false; + try { + const a = realpathSync(argv[1]); + const b = realpathSync(fileURLToPath(import.meta.url)); + return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b; + } catch { + return false; + } +})(); +if (invokedDirectly) { + run(argv.slice(2)) + .then((code) => process.exit(code)) + .catch((err) => { + console.error(err); + process.exit(1); + }); +} diff --git a/wifi-veil/harness/package.json b/wifi-veil/harness/package.json new file mode 100644 index 00000000..f49b5501 --- /dev/null +++ b/wifi-veil/harness/package.json @@ -0,0 +1,50 @@ +{ + "name": "wifi-veil-harness", + "version": "0.1.0", + "description": "Harness for wifi-veil (WiFi Veil — compliant-waveform WiFi-sensing privacy shield, ADR-288/289)", + "license": "MIT", + "type": "module", + "bin": { + "wifi-veil-harness": "bin/cli.js" + }, + "files": [ + "bin/**", + "dist/**", + "src/**", + "tsconfig.json", + ".claude/**", + ".claude-plugin/**", + "CLAUDE.md", + "README.md", + "LICENSE" + ], + "scripts": { + "build": "tsc", + "test": "vitest run", + "init": "node ./bin/cli.js init", + "doctor": "node ./bin/cli.js doctor", + "guidance": "node ./bin/cli.js guidance", + "evolve": "metaharness-darwin evolve . --sandbox real --generations 3 --children 4", + "evolve:dry": "metaharness-darwin evolve . --sandbox mock --generations 2 --children 3", + "route": "npm run build && node ./bin/cli.js route", + "flywheel:dry": "npm run build && node ./bin/cli.js flywheel 3" + }, + "dependencies": { + "@metaharness/kernel": "^0.1.0", + "@metaharness/host-claude-code": "^0.1.0", + "@metaharness/router": "^0.3.2", + "@metaharness/flywheel": "^0.1.7" + }, + "devDependencies": { + "@types/node": "^20.0.0", + "typescript": "^5.4.0", + "vitest": "^3.0.0", + "@metaharness/darwin": "^0.2.2" + }, + "engines": { + "node": ">=20.0.0" + }, + "publishConfig": { + "access": "public" + } +} diff --git a/wifi-veil/harness/src/flywheel.ts b/wifi-veil/harness/src/flywheel.ts new file mode 100644 index 00000000..6c1d11ff --- /dev/null +++ b/wifi-veil/harness/src/flywheel.ts @@ -0,0 +1,97 @@ +// SPDX-License-Identifier: MIT +// +// The wifi-veil (VEIL) harness's self-improvement loop, via +// @metaharness/flywheel: run -> measure -> mutate -> verify -> promote, with a +// frozen, conjunctive promotion gate and a signed, replayable lineage. +// +// HONESTY NOTE (load-bearing): `runVeilFlywheelDemo()` wires the real +// @metaharness/flywheel API end-to-end, but its Proposer and Evaluator are +// SYNTHETIC stand-ins — a deterministic string mutation and a deterministic +// scoring function over that string, with NO model call and NO real benchmark. +// It proves the wiring works (see __tests__/flywheel.test.ts: a non-empty lift +// curve, a verifiable replay bundle) and gives a `dataSource: 'SYNTHETIC'`- +// stamped demo. A LIVE run needs the operator to supply: +// - a real Proposer: a model call that improves one policy lever (e.g. the +// compliance-review checklist, the threat-model triage prompt); +// - a real Evaluator: scores that policy against real tasks (e.g. "did the +// compliance reviewer catch a non-energy-preserving perturbation"). +// Neither exists in this repo — wiring them is a live-API-key decision for the +// harness operator, not something to fake here. + +import { + runFlywheelGenerations, + meetsPromotionRule, + makeSigner, + verifyReplayBundle, + type Policy, + type PolicyGenome, + type Proposer, + type Evaluator, + type Suite, + type FlywheelResult, +} from '@metaharness/flywheel'; + +/** The gen-0 operating policy for the VEIL harness's review agents. Opaque + * string levers — the flywheel never interprets their meaning, only the + * Evaluator does. */ +export const VEIL_ROOT_POLICY: Policy = { + complianceReview: 'energy-ratio-checklist', + threatTriage: 'single-pass', +}; + +/** SYNTHETIC proposer: deterministically varies the target lever's value + * rather than calling a model. */ +const syntheticProposer: Proposer = async (base: PolicyGenome, target: string) => { + const current = base.policy[target] ?? ''; + return `${current}+g${base.generation + 1}`; +}; + +/** SYNTHETIC evaluator: scores a policy purely as a function of its own string + * content — a deterministic stand-in for running the harness's agents against a + * real task suite. `noopRate` must move for anything to promote (the default + * gate requires it to strictly improve generation over generation). */ +const syntheticEvaluator: Evaluator = async (policy: Policy, _suite: Suite) => { + const totalLength = Object.values(policy).reduce((s, v) => s + v.length, 0); + const primary = Math.min(0.5 + totalLength / 200, 0.98); + const noopRate = Math.max(0.3 - totalLength / 300, 0.02); + return { + primary, + noopRate, + costPerWin: 1 / primary, + regressed: false, + }; +}; + +const VEIL_HOLDOUT: Suite = { + id: 'veil-harness-holdout-synthetic', + items: ['seeded-compliance-task-1', 'seeded-threat-task-2', 'seeded-optimizer-task-3'], +}; + +const VEIL_ANCHOR: Suite = { + id: 'veil-harness-anchor-synthetic', + items: ['frozen-not-jamming-regression-1'], +}; + +/** + * Run a small, fully SYNTHETIC flywheel demo end-to-end and return the real + * @metaharness/flywheel result — a genuine lift curve and a signed, + * independently replayable bundle, built from synthetic (not live) evidence. + */ +export async function runVeilFlywheelDemo(maxGenerations = 3): Promise { + return runFlywheelGenerations({ + rootPolicy: VEIL_ROOT_POLICY, + proposer: syntheticProposer, + evaluator: syntheticEvaluator, + promotionRule: meetsPromotionRule, + holdout: VEIL_HOLDOUT, + anchor: VEIL_ANCHOR, + maxGenerations, + signer: makeSigner(), + dataSource: 'SYNTHETIC', + }); +} + +/** Independently verify a flywheel demo's replay bundle (no trust in the producer). */ +export function verifyVeilFlywheelDemo(result: FlywheelResult) { + return verifyReplayBundle(result.replayBundle); +} diff --git a/wifi-veil/harness/src/init.ts b/wifi-veil/harness/src/init.ts new file mode 100644 index 00000000..06a76021 --- /dev/null +++ b/wifi-veil/harness/src/init.ts @@ -0,0 +1,25 @@ +// SPDX-License-Identifier: MIT +// The harness's `wifi-veil-harness init` entry (typed mirror of +// the JS command in bin/cli.js; the published CLI uses the JS version so no +// build is required for `init`). + +import { loadKernel } from '@metaharness/kernel'; +import adapter from '@metaharness/host-claude-code'; + +const HARNESS_NAME = 'wifi-veil-harness'; + +async function main(): Promise { + const kernel = await loadKernel(); + const info = kernel.kernelInfo(); + console.log(`${HARNESS_NAME} — kernel ${info.version} (${kernel.backend})`); + console.log(`Host adapter: ${adapter.name}`); + console.log(`Run \`${HARNESS_NAME} doctor\` to verify the install.`); + return 0; +} + +main() + .then((c) => process.exit(c)) + .catch((err) => { + console.error(err); + process.exit(1); + }); diff --git a/wifi-veil/harness/src/router.ts b/wifi-veil/harness/src/router.ts new file mode 100644 index 00000000..950e9de2 --- /dev/null +++ b/wifi-veil/harness/src/router.ts @@ -0,0 +1,68 @@ +// SPDX-License-Identifier: MIT +// +// Cost-optimal task routing for the wifi-veil (VEIL) harness, +// via @metaharness/router: route each agent query to the cheapest model +// predicted to clear a quality bar, instead of defaulting every query to the +// frontier tier. +// +// HONESTY NOTE: the candidate `examples` below are SEED/ILLUSTRATIVE data — +// four hand-picked (embedding, quality) points per candidate, not measured +// eval-log observations. They exist so `veilTaskRouter` is a real, runnable +// k-NN router out of the box (see __tests__/router.test.ts), not so its routing +// decisions should be trusted for production cost savings. Replace +// `VEIL_ROUTER_CANDIDATES[*].examples` with real (query embedding → quality +// achieved) rows from your own eval logs before relying on this. + +import { Router, type RouterCandidate } from '@metaharness/router'; + +/** + * A 4-axis feature embedding for a harness query (each axis 0..1): + * [0] threatModeling — "is this attack in scope / what does VEIL defend"-shaped + * [1] complianceReview — "does this stay compliant / not jamming"-shaped + * [2] optimizerTuning — "tune passes/bits / re-run the optimizer"-shaped + * [3] docWriting — "write/update the research bundle or ADR"-shaped + * A caller with a real embedding model should project onto that model's + * dimensionality instead — the router only needs consistent vectors. + */ +export type VeilTaskEmbedding = readonly [number, number, number, number]; + +export const VEIL_ROUTER_CANDIDATES: RouterCandidate[] = [ + { + id: 'cheap-tier', + costPerMTok: 1, + examples: [ + { embedding: [1, 0, 0, 0], quality: 0.88 }, // threat-model Q&A: cheap tier is fine + { embedding: [0, 0, 0, 1], quality: 0.85 }, // doc writing: cheap tier is fine + { embedding: [0, 1, 0, 0], quality: 0.55 }, // compliance review: cheap tier is weak + { embedding: [0, 0, 1, 0], quality: 0.5 }, // optimizer tuning: cheap tier is weak + ], + }, + { + id: 'frontier-tier', + costPerMTok: 15, + examples: [ + { embedding: [1, 0, 0, 0], quality: 0.95 }, + { embedding: [0, 0, 0, 1], quality: 0.93 }, + { embedding: [0, 1, 0, 0], quality: 0.93 }, // compliance review: frontier tier needed + { embedding: [0, 0, 1, 0], quality: 0.92 }, // optimizer tuning: frontier tier needed + ], + }, +]; + +/** + * Cost-optimal router for the harness's four query shapes above. `qualityBar` + * of 0.8: return the cheapest candidate predicted to clear 80% quality, or the + * best-predicted candidate if none do. k=1 because each candidate has only 4 + * orthogonal one-hot examples (see the SAR harness note on why the default k=5 + * would collapse every query to the same prediction here). + */ +export const veilTaskRouter = new Router({ + qualityBar: 0.8, + candidates: VEIL_ROUTER_CANDIDATES, + k: 1, +}); + +/** Route one query embedding to the cost-optimal model tier. */ +export function routeVeilQuery(queryEmbedding: VeilTaskEmbedding) { + return veilTaskRouter.route([...queryEmbedding]); +} diff --git a/wifi-veil/harness/tsconfig.json b/wifi-veil/harness/tsconfig.json new file mode 100644 index 00000000..4f908fa4 --- /dev/null +++ b/wifi-veil/harness/tsconfig.json @@ -0,0 +1,19 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "NodeNext", + "moduleResolution": "NodeNext", + "lib": ["ES2022"], + "outDir": "./dist", + "rootDir": "./src", + "declaration": true, + "declarationMap": true, + "sourceMap": true, + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true + }, + "include": ["src/**/*.ts"], + "exclude": ["node_modules", "dist", "__tests__"] +} diff --git a/wifi-veil/harness/vitest.config.ts b/wifi-veil/harness/vitest.config.ts new file mode 100644 index 00000000..dede0819 --- /dev/null +++ b/wifi-veil/harness/vitest.config.ts @@ -0,0 +1,22 @@ +// SPDX-License-Identifier: MIT +// Strips the `#!/usr/bin/env node` shebang from importable entrypoints (e.g. +// bin/cli.js) before Vite parses them — Vite/esbuild (used internally by +// Vitest) does NOT strip shebangs, so importing a shebanged module throws +// `SyntaxError: Invalid or unexpected token`. No effect on direct CLI +// execution. +import { defineConfig } from 'vitest/config'; + +export default defineConfig({ + plugins: [ + { + name: 'strip-shebang', + enforce: 'pre', + transform(code: string) { + if (code.startsWith('#!')) { + return { code: code.replace(/^#![^\n]*/, ''), map: null }; + } + return null; + }, + }, + ], +}); diff --git a/wifi-veil/scripts/ci-guard.sh b/wifi-veil/scripts/ci-guard.sh new file mode 100755 index 00000000..e2e846e8 --- /dev/null +++ b/wifi-veil/scripts/ci-guard.sh @@ -0,0 +1,113 @@ +#!/usr/bin/env bash +# WiFi Veil CI guard — enforces the project's honesty / anti-slop invariants so +# they cannot silently regress. This is a STATIC scan; the deterministic proof +# witness, tests, clippy, and the C-core test run in the main CI jobs. +# +# It scans only git-tracked files under the current tree, so untracked local +# scratch never fails CI and build outputs (target/) are ignored. Run locally +# from the repo root: bash scripts/ci-guard.sh +# +# Every check prints PASS/FAIL; the script exits non-zero if any check fails. +set -u + +fail=0 +pass() { printf 'PASS %s\n' "$1"; } +bad() { printf 'FAIL %s\n' "$1"; fail=1; } + +# All tracked files under cwd (works both in-monorepo-subdir and standalone). +mapfile -t TRACKED < <(git ls-files -- .) +# Convenience filtered lists. +code_files() { printf '%s\n' "${TRACKED[@]}" | grep -E '\.(rs|c|h|js|ts)$' || true; } +doc_files() { printf '%s\n' "${TRACKED[@]}" | grep -E '\.md$' || true; } + +# --------------------------------------------------------------------------- +# 1. No forbidden artifacts / telemetry / scratch committed. +# --------------------------------------------------------------------------- +artifacts=$(printf '%s\n' "${TRACKED[@]}" | grep -E \ + '(^|/)(\.claude-flow/|node_modules/|target/)|\.o$|(^|/)test_veil_shield$|(^|/)Cargo\.lock$|(^|/)tests/probe.*\.rs$|(^|/)(tmp_|scratch_).*' \ + || true) +if [ -n "$artifacts" ]; then + bad "forbidden artifacts/telemetry/scratch are tracked:" + printf ' %s\n' $artifacts +else + pass "no telemetry / build artifacts / lockfile / scratch files tracked" +fi + +# --------------------------------------------------------------------------- +# 2. No debug/scratch leftovers in source (mock-probe / slop markers). +# --------------------------------------------------------------------------- +markers='panic!\("probe|dbg!\(|println!\("DEBUG|console\.log\("DEBUG|TODO\(ai\)|FIXME\(slop\)|XXX SLOP|LOREM IPSUM' +hits=$(code_files | xargs -r grep -nEI "$markers" 2>/dev/null || true) +if [ -n "$hits" ]; then + bad "debug/scratch/slop markers in source:" + printf ' %s\n' "$hits" +else + pass "no debug/scratch/slop markers in source" +fi + +# --------------------------------------------------------------------------- +# 3. Honesty labels present where evidence discipline requires them. +# Every firmware provider README must carry the SYNTHETIC label; the top +# firmware README and the root README must carry the compliance disclaimer. +# --------------------------------------------------------------------------- +for p in firmware/openwifi firmware/openwrt firmware/nexmon firmware/esp32; do + if [ -f "$p/README.md" ]; then + if grep -qi 'SYNTHETIC' "$p/README.md"; then + pass "$p/README.md carries SYNTHETIC evidence label" + else + bad "$p/README.md is missing the SYNTHETIC evidence label" + fi + fi +done +for f in firmware/README.md README.md; do + if [ -f "$f" ]; then + if grep -qiE 'never jamming|not jamming|not a jammer' "$f"; then + pass "$f carries the 'never jamming' compliance disclaimer" + else + bad "$f is missing the 'never jamming' compliance disclaimer" + fi + fi +done + +# --------------------------------------------------------------------------- +# 4. No dishonest hardware-success claims. Honest 'not yet MEASURED / TODO(hw) / +# build-only' language is REQUIRED elsewhere; here we forbid only phrases that +# assert silicon validation that does not exist. (Conservative denylist to +# avoid false positives on the many honest negated mentions.) +# --------------------------------------------------------------------------- +dishonest='hardware[- ]validated|validated on (real )?silicon|flashed and verified|[^n]verified on silicon|confirmed on hardware|MEASURED on (real )?hardware' +# Exclude honest negated/hedged mentions (the discipline itself): "not/never +# validated on silicon", "NOT hardware-validated", "unverified", "nothing is +# validated", "SYNTHETIC ... not hardware-validated", roadmap/TODO framing, etc. +negation='\bnot\b|\bnever\b|\bno\b|\bnothing\b|\bwithout\b|unverified|unvalidated|\bwould\b|\bplanned\b|\bbefore\b|not yet|TODO|SYNTHETIC' +hwhits=$( { doc_files; code_files; } | xargs -r grep -nEiI "$dishonest" 2>/dev/null \ + | grep -viE "$negation" || true) +if [ -n "$hwhits" ]; then + bad "dishonest hardware-success claim(s) (no captured log exists):" + printf ' %s\n' "$hwhits" +else + pass "no dishonest hardware-validation claims" +fi + +# --------------------------------------------------------------------------- +# 5. No stale monorepo identifiers in the standalone code surface. The crate is +# `wifi-veil` (lib `wifi_veil`); the old `wifi-densepose-privshield` name must +# not survive in code / manifests (docs may cite the historical ADR filename). +# --------------------------------------------------------------------------- +codeset=$(printf '%s\n' "${TRACKED[@]}" | grep -E '\.(rs|toml)$|harness/(bin|src)/.*\.(js|ts)$|harness/package\.json$|harness/\.harness/manifest\.json$' || true) +if [ -n "$codeset" ]; then + stale=$(printf '%s\n' "$codeset" | xargs -r grep -nEI 'wifi[_-]densepose[_-]privshield' 2>/dev/null || true) + if [ -n "$stale" ]; then + bad "stale monorepo crate/harness identifier in code/manifests:" + printf ' %s\n' "$stale" + else + pass "no stale monorepo identifiers in code/manifests" + fi +fi + +echo +if [ "$fail" -ne 0 ]; then + echo "ci-guard: FAILED" + exit 1 +fi +echo "ci-guard: all invariants hold" diff --git a/wifi-veil/src/attacker.rs b/wifi-veil/src/attacker.rs new file mode 100644 index 00000000..0144eb63 --- /dev/null +++ b/wifi-veil/src/attacker.rs @@ -0,0 +1,364 @@ +//! The adversary: a passive re-identification classifier over captured +//! beamforming feedback. +//! +//! The attacker models the BFId/CCS-2025 threat: a sniffer that enrolls a +//! template per candidate from observed reports, then classifies fresh +//! captures. We use a **nearest-centroid** classifier over the full report +//! vector. It is deliberately simple but is the right shape for the effect +//! under test: it succeeds exactly when a *stable* per-identity signature +//! survives across capture sessions, and fails when the signature is rotated +//! unpredictably each session (which is what the protector does). +//! +//! Nearest-centroid is also the honest choice for the collapse claim: a more +//! elaborate classifier cannot recover identity that has been mapped through a +//! fresh secret orthogonal transform each session — the mutual information +//! between a Haar-rotated signature and the identity label, marginalized over +//! unknown rotations, is what the protector drives down. The classifier +//! strength is not the lever; signature stability is. + +use crate::identity::BfiSample; +use crate::linalg::{dist_sq, dot, norm, set_norm_inplace}; + +/// Similarity metric the attacker uses to match a capture to a centroid. +/// +/// Sweeping the metric is how [`crate::optimize`] checks that the shield's +/// collapse is a property of the *signal* (a rotated signature carries no +/// stable identity), not an artifact of one classifier's geometry. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum Metric { + /// Euclidean nearest-centroid (default). Sensitive to magnitude. + #[default] + Euclidean, + /// Cosine nearest-centroid. Scale-invariant; a natural stronger attacker + /// against energy-preserving perturbations, since it ignores magnitude. + Cosine, +} + +/// A nearest-centroid re-identification attacker. +#[derive(Debug, Clone, Default)] +pub struct NearestCentroidAttacker { + centroids: Vec>, + ids: Vec, + metric: Metric, +} + +impl NearestCentroidAttacker { + /// Build an empty attacker using the Euclidean metric. + #[must_use] + pub fn new() -> Self { + Self::default() + } + + /// Build an empty attacker using the given metric. + #[must_use] + pub fn with_metric(metric: Metric) -> Self { + Self { + metric, + ..Self::default() + } + } + + /// Enroll from labeled captures: one centroid per identity, the mean of + /// that identity's observed report vectors. + pub fn enroll(&mut self, samples: &[(usize, BfiSample)]) { + // Group by identity, preserving first-seen order. + let mut ids: Vec = Vec::new(); + let mut sums: Vec> = Vec::new(); + let mut counts: Vec = Vec::new(); + for (id, s) in samples { + let slot = ids.iter().position(|x| x == id).unwrap_or_else(|| { + ids.push(*id); + sums.push(vec![0.0; s.values.len()]); + counts.push(0); + ids.len() - 1 + }); + for (acc, v) in sums[slot].iter_mut().zip(&s.values) { + *acc += v; + } + counts[slot] += 1; + } + for (sum, &c) in sums.iter_mut().zip(&counts) { + if c > 0 { + let inv = 1.0 / c as f32; + for v in sum.iter_mut() { + *v *= inv; + } + } + } + self.ids = ids; + self.centroids = sums; + } + + /// Classify a capture to the nearest enrolled centroid. Returns the + /// predicted identity, or `None` if the attacker has not enrolled. + #[must_use] + pub fn classify(&self, sample: &BfiSample) -> Option { + // Score is "lower is better" for both metrics: Euclidean uses squared + // distance; Cosine uses the negated similarity. + let score = |c: &[f32]| -> f32 { + match self.metric { + Metric::Euclidean => dist_sq(c, &sample.values), + Metric::Cosine => { + let denom = norm(c) * norm(&sample.values); + if denom > 1e-12 { + -dot(c, &sample.values) / denom + } else { + 0.0 + } + } + } + }; + let mut best: Option<(usize, f32)> = None; + for (id, c) in self.ids.iter().zip(&self.centroids) { + let d = score(c); + if best.is_none_or(|(_, bd)| d < bd) { + best = Some((*id, d)); + } + } + best.map(|(id, _)| id) + } + + /// Top-1 re-identification accuracy over a labeled test set. + #[must_use] + pub fn accuracy(&self, test: &[(usize, BfiSample)]) -> f32 { + if test.is_empty() { + return 0.0; + } + let correct = test + .iter() + .filter(|(id, s)| self.classify(s) == Some(*id)) + .count(); + correct as f32 / test.len() as f32 + } +} + +/// Which adversary the experiment runs. Added from the 2025–2026 SOTA sweep +/// (ADR-288 §sota) so the collapse is shown to hold against the *strongest* +/// published attacker shapes, not just a plain nearest-centroid. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum AttackerKind { + /// Nearest-centroid on the full captured report (uses the configured [`Metric`]). + #[default] + NearestCentroid, + /// Models BFI→CSI reconstruction (BFIAttack, arXiv:2604.04179): the adversary + /// recovers the CSI *consistent with the captured report* and classifies its + /// direction. Because a keyed secret rotation has no key to invert, what it + /// reconstructs is the *rotated* CSI — so identity does not survive. + Reconstruction, + /// Pools many captures per identity and whitens before matching (the + /// PrivISAC-style adaptive/retraining adversary). Averaging cannot undo a + /// fresh secret rotation, so the pooled, whitened template still collapses. + AdaptivePooling, +} + +/// BFI→CSI reconstruction adversary. Classifies the **direction** (L2-normalized +/// fine block) of the reconstructed CSI — the strongest gain-invariant descriptor +/// an attacker can recover from a captured report. Defeated by a secret rotation +/// (it only ever recovers the rotated direction). +#[derive(Debug, Clone, Default)] +pub struct ReconstructionAttacker { + centroids: Vec>, + ids: Vec, +} + +fn reconstructed_direction(s: &BfiSample) -> Vec { + let mut v = s.fine().to_vec(); + set_norm_inplace(&mut v, 1.0); + v +} + +impl ReconstructionAttacker { + /// Build an empty reconstruction attacker. + #[must_use] + pub fn new() -> Self { + Self::default() + } + + /// Enroll direction-centroids from reconstructed captures. + pub fn enroll(&mut self, samples: &[(usize, BfiSample)]) { + let mut ids: Vec = Vec::new(); + let mut sums: Vec> = Vec::new(); + let mut counts: Vec = Vec::new(); + for (id, s) in samples { + let f = reconstructed_direction(s); + let slot = ids.iter().position(|x| x == id).unwrap_or_else(|| { + ids.push(*id); + sums.push(vec![0.0; f.len()]); + counts.push(0); + ids.len() - 1 + }); + for (acc, v) in sums[slot].iter_mut().zip(&f) { + *acc += v; + } + counts[slot] += 1; + } + for (sum, &c) in sums.iter_mut().zip(&counts) { + if c > 0 { + let inv = 1.0 / c as f32; + for v in sum.iter_mut() { + *v *= inv; + } + } + } + self.ids = ids; + self.centroids = sums; + } + + /// Classify a capture by nearest reconstructed direction. + #[must_use] + pub fn classify(&self, sample: &BfiSample) -> Option { + let f = reconstructed_direction(sample); + let mut best: Option<(usize, f32)> = None; + for (id, c) in self.ids.iter().zip(&self.centroids) { + let d = dist_sq(c, &f); + if best.is_none_or(|(_, bd)| d < bd) { + best = Some((*id, d)); + } + } + best.map(|(id, _)| id) + } + + /// Top-1 accuracy over a labeled test set. + #[must_use] + pub fn accuracy(&self, test: &[(usize, BfiSample)]) -> f32 { + if test.is_empty() { + return 0.0; + } + let correct = test + .iter() + .filter(|(id, s)| self.classify(s) == Some(*id)) + .count(); + correct as f32 / test.len() as f32 + } +} + +/// Adaptive pooling adversary: whitens the full report by per-dimension +/// standard deviation (estimated over all captures) before nearest-centroid, +/// modeling an attacker who aggregates many captures and re-fits. Whitening a +/// *fixed* coordinate basis cannot undo a rotation that mixes coordinates +/// afresh each session, so the pooled template still collapses. +#[derive(Debug, Clone, Default)] +pub struct AdaptivePoolingAttacker { + centroids: Vec>, + ids: Vec, + inv_std: Vec, +} + +impl AdaptivePoolingAttacker { + /// Build an empty adaptive pooling attacker. + #[must_use] + pub fn new() -> Self { + Self::default() + } + + /// Enroll: estimate global per-dimension inverse std, then pooled per-id + /// means. + pub fn enroll(&mut self, samples: &[(usize, BfiSample)]) { + if samples.is_empty() { + return; + } + let dim = samples[0].1.values.len(); + let n = samples.len() as f32; + let mut mean = vec![0.0f32; dim]; + for (_, s) in samples { + for (m, v) in mean.iter_mut().zip(&s.values) { + *m += v; + } + } + for m in &mut mean { + *m /= n; + } + let mut var = vec![0.0f32; dim]; + for (_, s) in samples { + for ((vv, v), m) in var.iter_mut().zip(&s.values).zip(&mean) { + let d = v - m; + *vv += d * d; + } + } + self.inv_std = var + .iter() + .map(|v| 1.0 / ((v / n).sqrt().max(1e-6))) + .collect(); + + let mut ids: Vec = Vec::new(); + let mut sums: Vec> = Vec::new(); + let mut counts: Vec = Vec::new(); + for (id, s) in samples { + let slot = ids.iter().position(|x| x == id).unwrap_or_else(|| { + ids.push(*id); + sums.push(vec![0.0; dim]); + counts.push(0); + ids.len() - 1 + }); + for (acc, v) in sums[slot].iter_mut().zip(&s.values) { + *acc += v; + } + counts[slot] += 1; + } + for (sum, &c) in sums.iter_mut().zip(&counts) { + if c > 0 { + let inv = 1.0 / c as f32; + for v in sum.iter_mut() { + *v *= inv; + } + } + } + self.ids = ids; + self.centroids = sums; + } + + /// Classify by whitened nearest-centroid. + #[must_use] + pub fn classify(&self, sample: &BfiSample) -> Option { + let mut best: Option<(usize, f32)> = None; + for (id, c) in self.ids.iter().zip(&self.centroids) { + let mut d = 0.0f32; + for ((cv, sv), w) in c.iter().zip(&sample.values).zip(&self.inv_std) { + let diff = (cv - sv) * w; + d += diff * diff; + } + if best.is_none_or(|(_, bd)| d < bd) { + best = Some((*id, d)); + } + } + best.map(|(id, _)| id) + } + + /// Top-1 accuracy over a labeled test set. + #[must_use] + pub fn accuracy(&self, test: &[(usize, BfiSample)]) -> f32 { + if test.is_empty() { + return 0.0; + } + let correct = test + .iter() + .filter(|(id, s)| self.classify(s) == Some(*id)) + .count(); + correct as f32 / test.len() as f32 + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::identity::{Channel, SceneConfig}; + + #[test] + fn attacker_re_ids_unprotected_traffic() { + let ch = Channel::new(SceneConfig::default()); + let mut enroll = Vec::new(); + let mut test = Vec::new(); + for id in 0..ch.config().identities { + for s in 0..12 { + enroll.push((id, ch.observe(id, b"enroll", s))); + } + for s in 0..12 { + test.push((id, ch.observe(id, b"test", s))); + } + } + let mut atk = NearestCentroidAttacker::new(); + atk.enroll(&enroll); + // On unprotected traffic the stable signature is trivially recovered. + assert!(atk.accuracy(&test) > 0.85); + } +} diff --git a/wifi-veil/src/bin/veil.rs b/wifi-veil/src/bin/veil.rs new file mode 100644 index 00000000..0af6ade0 --- /dev/null +++ b/wifi-veil/src/bin/veil.rs @@ -0,0 +1,549 @@ +//! `veil` — a custom, dependency-free terminal harness for the VEIL privacy +//! shield (ADR-288). It is the in-repo, native counterpart to the npm +//! metaharness (`harness/`, ADR-289): where that one +//! assists *development*, this one *drives the model* — an interactive TUI plus +//! scriptable subcommands over the same crate API the tests use. +//! +//! Std-only on purpose: no `crossterm`/`ratatui`, no external deps. The TUI is +//! a command-driven ANSI dashboard (line input, redraw on change), which keeps +//! the crate a pure leaf and lets the harness run in any pipe or CI. +//! +//! ```text +//! veil # TUI if attached to a terminal, else a one-shot report +//! veil tui # force the interactive dashboard +//! veil report # print the dashboard once (plain, pipe-friendly) +//! veil sweep # re-ID vs passes and throughput vs bits tables +//! veil optimize # run the hyper-optimizer, print the recommendation +//! veil adaptive # derive the shield for a room of N candidate identities +//! veil proof # verify the deterministic witness +//! veil doctor # self-check (exit 0 = healthy) +//! ``` +//! +//! All numbers are **SYNTHETIC / L0** — reproduced by `cargo test`, describing +//! the model, not real hardware. + +use std::io::{self, BufRead, IsTerminal, Write}; + +use veil::optimize; +use veil::{run, ExperimentConfig, ExperimentReport, Metric, Proof}; +use wifi_veil as veil; + +// ---- ANSI palette (matches the VEIL Console: teal shield, amber threat) ---- +const TEAL: &str = "\x1b[38;2;32;211;192m"; +const AMBER: &str = "\x1b[38;2;245;158;75m"; +const GOOD: &str = "\x1b[38;2;62;207;142m"; +const CRIT: &str = "\x1b[38;2;242;107;111m"; +const MUTE: &str = "\x1b[38;2;139;160;159m"; +const BOLD: &str = "\x1b[1m"; +const RST: &str = "\x1b[0m"; +const BLOCKS: [char; 8] = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']; + +/// Emit color for a real terminal; never when `NO_COLOR` is set; always when +/// `CLICOLOR_FORCE` is set (so piped captures keep their color). +fn color_enabled() -> bool { + if std::env::var_os("NO_COLOR").is_some() { + return false; + } + if std::env::var_os("CLICOLOR_FORCE").is_some() { + return true; + } + io::stdout().is_terminal() +} + +/// Wrap `s` in `code` when color is on. +fn c(s: &str, code: &str, on: bool) -> String { + if on { + format!("{code}{s}{RST}") + } else { + s.to_string() + } +} + +/// A raw color code, or "" when color is off — for inline `format!` colouring. +fn k(code: &'static str, on: bool) -> &'static str { + if on { + code + } else { + "" + } +} + +/// Shield-on re-ID at a given mixing budget, holding the rest of `cfg`. +fn reid_at(cfg: &ExperimentConfig, passes: usize) -> f32 { + let mut c = cfg.clone(); + c.shield.givens_passes = passes; + run(&c).accuracy_shield_on +} + +/// A block-sparkline character for a value in `[0, 1]`. +fn spark(v: f32) -> char { + let i = (v.clamp(0.0, 1.0) * 7.0).round() as usize; + BLOCKS[i.min(7)] +} + +/// Render the full dashboard as colored lines (left-bar panel; no right border, +/// so ANSI escape width never has to be counted). +fn dashboard(cfg: &ExperimentConfig, on: bool) -> Vec { + let rep: ExperimentReport = run(cfg); + let chance = rep.chance_level * 100.0; + let off = rep.accuracy_shield_off * 100.0; + let onp = rep.accuracy_shield_on * 100.0; + let tp = rep.throughput_ratio * 100.0; + + let (state, scode) = if !cfg.shield.enabled { + ("EXPOSED", CRIT) + } else if rep.passed() { + ("PROTECTED", GOOD) + } else { + ("AT RISK", AMBER) + }; + let on_code = if onp <= rep.chance_band * 100.0 { + GOOD + } else { + AMBER + }; + let tp_code = if tp >= 95.0 { GOOD } else { CRIT }; + let bar = c("│", MUTE, on); + + let mut out = Vec::new(); + out.push(c( + "┌──────────────────────────────────────────────────────────", + MUTE, + on, + )); + out.push(format!( + "{} {}{}VEIL{} {}· wifi-sensing privacy shield{} {}● {}{}", + bar, + k(BOLD, on), + k(TEAL, on), + k(RST, on), + k(MUTE, on), + k(RST, on), + k(scode, on), + state, + k(RST, on), + )); + out.push(bar.clone()); + out.push(format!( + "{} re-ID off {}{:>6.1}%{} re-ID on {}{:>5.1}%{} {}(chance {:.2}%){}", + bar, + k(AMBER, on), + off, + k(RST, on), + k(on_code, on), + onp, + k(RST, on), + k(MUTE, on), + chance, + k(RST, on), + )); + out.push(format!( + "{} throughput {}{:>6.1}%{} emission {}{:.3}×{} {}· not jamming{}", + bar, + k(tp_code, on), + tp, + k(RST, on), + k(GOOD, on), + rep.compliance.energy_ratio, + k(RST, on), + k(MUTE, on), + k(RST, on), + )); + out.push(bar.clone()); + + let cand = optimize::PASS_CANDIDATES; + let line: String = cand.iter().map(|&p| spark(reid_at(cfg, p))).collect(); + out.push(format!( + "{} {}collapse{} {}{}{} {}passes {}→{} · op {}{}", + bar, + k(MUTE, on), + k(RST, on), + k(TEAL, on), + line, + k(RST, on), + k(MUTE, on), + cand[0], + cand[cand.len() - 1], + cfg.shield.givens_passes, + k(RST, on), + )); + out.push(bar.clone()); + + let metric = match cfg.attacker_metric { + Metric::Euclidean => "euclid", + Metric::Cosine => "cosine", + }; + out.push(format!( + "{} {}config{} passes {} · bits {} · N {} · snr {:.0}dB · {}", + bar, + k(MUTE, on), + k(RST, on), + cfg.shield.givens_passes, + cfg.shield.feedback_bits, + cfg.scene.identities, + cfg.link.snr_db, + metric, + )); + let (vlabel, vcode) = if !cfg.shield.enabled { + ("SHIELD OFF — room exposed", CRIT) + } else if rep.passed() { + ( + "✓ PASS — re-ID at chance · throughput ≥95% · compliant", + GOOD, + ) + } else { + ( + "△ OUT OF SPEC — raise passes/bits to re-enter the chance band", + AMBER, + ) + }; + out.push(format!( + "{} {}verdict{} {}{}{}", + bar, + k(MUTE, on), + k(RST, on), + k(vcode, on), + vlabel, + k(RST, on) + )); + out.push(c( + "└──────────────────────────────────────────────────────────", + MUTE, + on, + )); + out +} + +/// Deployment presets (mirror `optimize::adaptive_shield` results per room). +fn preset(name: &str, cfg: &mut ExperimentConfig) -> bool { + let (n, passes, bits, snr) = match name { + "scif" => (64, 96, 5, 20.0), + "board" => (16, 96, 5, 25.0), + "ward" => (32, 96, 5, 15.0), + "hotel" => (48, 64, 5, 20.0), + _ => return false, + }; + cfg.scene.identities = n; + cfg.shield.givens_passes = passes; + cfg.shield.feedback_bits = bits; + cfg.link.snr_db = snr; + true +} + +fn print_dashboard(cfg: &ExperimentConfig, on: bool) { + for l in dashboard(cfg, on) { + println!("{l}"); + } +} + +fn cmd_sweep(cfg: &ExperimentConfig, on: bool) { + println!( + "{}re-ID (shield on) vs Givens passes — N={}{}", + k(MUTE, on), + cfg.scene.identities, + k(RST, on) + ); + for &p in &optimize::PASS_CANDIDATES { + let robust = + optimize::passes_collapse_at_n(cfg, p, cfg.shield.feedback_bits, cfg.scene.identities); + println!( + " passes {:>3} re-ID {:>5.1}% {}", + p, + reid_at(cfg, p) * 100.0, + if robust { + c("collapses", GOOD, on) + } else { + c("above chance", AMBER, on) + } + ); + } + println!( + "\n{}throughput vs feedback bits — snr={:.0}dB{}", + k(MUTE, on), + cfg.link.snr_db, + k(RST, on) + ); + for bits in 1..=12u32 { + let mut s = cfg.shield.clone(); + s.feedback_bits = bits; + let tp = cfg.link.throughput_ratio(&s) * 100.0; + let barlen = ((tp - 90.0).clamp(0.0, 10.0) / 10.0 * 24.0) as usize; + println!( + " {:>2} bit {:>6.3}% {}{}{}", + bits, + tp, + k(TEAL, on), + "█".repeat(barlen), + k(RST, on) + ); + } + let (sb, _) = optimize::spec_optimal_feedback_bits(cfg); + println!(" {}spec-optimal: {} bit{}", k(MUTE, on), sb, k(RST, on)); +} + +fn cmd_optimize(cfg: &ExperimentConfig, on: bool) { + let opt = veil::hyper_optimize(cfg); + let r = &opt.report; + println!("{}hyper-optimizer{}", k(BOLD, on), k(RST, on)); + println!(" min robust passes : {}", opt.min_passes); + println!( + " shipped passes : {} {}(min × 2 margin, throughput-free){}", + opt.shipped_passes, + k(MUTE, on), + k(RST, on) + ); + println!( + " spec-optimal bits : {} {}(model optimum {}){}", + opt.spec_optimal_bits, + k(MUTE, on), + opt.model_optimal_bits, + k(RST, on) + ); + println!( + " result : re-ID {}{:.1}%{} · throughput {}{:.1}%{} · {}", + k(GOOD, on), + r.accuracy_shield_on * 100.0, + k(RST, on), + k(GOOD, on), + r.throughput_ratio * 100.0, + k(RST, on), + if r.passed() { + c("PASS", GOOD, on) + } else { + c("FAIL", CRIT, on) + } + ); + println!( + " {}SNR → model-optimal bits: {:?}{}", + k(MUTE, on), + optimize::optimal_bits_across_snr(cfg), + k(RST, on) + ); +} + +fn cmd_adaptive(cfg: &ExperimentConfig, n: usize, on: bool) { + let sh = veil::adaptive_shield(cfg, n); + println!( + "adaptive shield for N={}: passes {} · bits {} {}(mixing budget is N-independent in this model){}", + n, sh.givens_passes, sh.feedback_bits, k(MUTE, on), k(RST, on) + ); +} + +fn cmd_proof(on: bool) -> i32 { + let w = Proof::witness(&Proof::run_reference()); + let ok = w == Proof::EXPECTED_WITNESS; + println!( + "witness {:#018x} expected {:#018x} {}", + w, + Proof::EXPECTED_WITNESS, + if ok { + c("MATCH", GOOD, on) + } else { + c("DRIFT", CRIT, on) + } + ); + i32::from(!ok) +} + +fn cmd_doctor(on: bool) -> i32 { + let rep = run(&ExperimentConfig::default()); + let checks = [ + ("reference experiment passes", rep.passed()), + ( + "attack is real without shield", + rep.attack_is_effective_without_shield(), + ), + ("collapse drives to chance", rep.drives_to_chance()), + ("throughput ≥ 95%", rep.preserves_throughput()), + ("emission is compliant", rep.compliance.is_compliant()), + ( + "deterministic witness matches", + Proof::witness(&Proof::run_reference()) == Proof::EXPECTED_WITNESS, + ), + ]; + let mut ok = true; + for (label, pass) in checks { + ok &= pass; + println!( + "{} {label}", + if pass { + c("PASS", GOOD, on) + } else { + c("FAIL", CRIT, on) + } + ); + } + println!( + "\nveil doctor: {}", + if ok { + c("all checks passed", GOOD, on) + } else { + c("problems found", CRIT, on) + } + ); + i32::from(!ok) +} + +fn help() { + println!( + "veil — VEIL privacy-shield harness (SYNTHETIC / L0)\n\n\ + USAGE\n veil [command]\n\n\ + COMMANDS\n\ + \x20 tui interactive dashboard (default on a terminal)\n\ + \x20 report print the dashboard once\n\ + \x20 sweep re-ID vs passes + throughput vs bits\n\ + \x20 optimize run the hyper-optimizer\n\ + \x20 adaptive derive the shield for N candidate identities\n\ + \x20 proof verify the deterministic witness\n\ + \x20 doctor self-check (exit 0 = healthy)\n\ + \x20 help this text\n\n\ + TUI COMMANDS (type + Enter)\n\ + \x20 on | off toggle the shield\n\ + \x20 passes · bits · n · snr \n\ + \x20 metric euclid|cosine\n\ + \x20 preset scif|board|ward|hotel\n\ + \x20 run | optimize | proof | help | quit" + ); +} + +fn tui(mut cfg: ExperimentConfig, on: bool) { + let stdin = io::stdin(); + let interactive = stdin.is_terminal(); + let redraw = |cfg: &ExperimentConfig, msg: &str| { + if interactive { + print!("\x1b[2J\x1b[H"); + } + print_dashboard(cfg, on); + if !msg.is_empty() { + println!(" {}{}{}", k(MUTE, on), msg, k(RST, on)); + } + print!("{}veil›{} ", k(TEAL, on), k(RST, on)); + let _ = io::stdout().flush(); + }; + redraw(&cfg, "type `help` for commands"); + for line in stdin.lock().lines() { + let line = match line { + Ok(l) => l, + Err(_) => break, + }; + let mut it = line.split_whitespace(); + let cmd = it.next().unwrap_or(""); + let arg = it.next().unwrap_or(""); + let mut msg = String::new(); + match cmd { + "" => {} + "quit" | "q" | "exit" => break, + "help" | "h" => { + if interactive { + print!("\x1b[2J\x1b[H"); + } + help(); + continue; + } + "on" => cfg.shield.enabled = true, + "off" => cfg.shield.enabled = false, + "passes" => match arg.parse::() { + Ok(v) => cfg.shield.givens_passes = v.clamp(1, 512), + Err(_) => msg = "passes: need a number".into(), + }, + "bits" => match arg.parse::() { + Ok(v) => cfg.shield.feedback_bits = v.clamp(1, 12), + Err(_) => msg = "bits: need 1..12".into(), + }, + "n" => match arg.parse::() { + Ok(v) => cfg.scene.identities = v.clamp(2, 128), + Err(_) => msg = "n: need 2..128".into(), + }, + "snr" => match arg.parse::() { + Ok(v) => cfg.link.snr_db = v.clamp(0.0, 60.0), + Err(_) => msg = "snr: need a number (dB)".into(), + }, + "metric" => match arg { + "euclid" | "euclidean" => cfg.attacker_metric = Metric::Euclidean, + "cosine" | "cos" => cfg.attacker_metric = Metric::Cosine, + _ => msg = "metric: euclid | cosine".into(), + }, + "preset" => { + if !preset(arg, &mut cfg) { + msg = "preset: scif | board | ward | hotel".into(); + } + } + "run" => msg = "ran — numbers above reflect current settings".into(), + "optimize" | "opt" => { + cfg.shield = veil::hyper_optimize(&cfg).shield; + msg = format!( + "optimized → passes {} · bits {}", + cfg.shield.givens_passes, cfg.shield.feedback_bits + ); + } + "proof" => { + let w = Proof::witness(&Proof::run_reference()); + msg = format!( + "witness {:#018x} ({})", + w, + if w == Proof::EXPECTED_WITNESS { + "match" + } else { + "drift" + } + ); + } + other => msg = format!("unknown: {other} (try `help`)"), + } + redraw(&cfg, &msg); + } + if interactive { + println!(); + } +} + +fn main() { + let on = color_enabled(); + let args: Vec = std::env::args().skip(1).collect(); + let cfg = ExperimentConfig::default(); + let code = match args.first().map(String::as_str).unwrap_or("") { + "" => { + if io::stdout().is_terminal() { + tui(cfg, on); + } else { + print_dashboard(&cfg, on); + } + 0 + } + "tui" => { + tui(cfg, on); + 0 + } + "report" => { + print_dashboard(&cfg, on); + 0 + } + "sweep" => { + cmd_sweep(&cfg, on); + 0 + } + "optimize" | "opt" => { + cmd_optimize(&cfg, on); + 0 + } + "adaptive" => { + let n = args + .get(1) + .and_then(|s| s.parse().ok()) + .unwrap_or(cfg.scene.identities); + cmd_adaptive(&cfg, n, on); + 0 + } + "proof" => cmd_proof(on), + "doctor" => cmd_doctor(on), + "help" | "-h" | "--help" => { + help(); + 0 + } + other => { + eprintln!("unknown command: {other}. Try `veil help`."); + 2 + } + }; + std::process::exit(code); +} diff --git a/wifi-veil/src/compliance.rs b/wifi-veil/src/compliance.rs new file mode 100644 index 00000000..29f426c0 --- /dev/null +++ b/wifi-veil/src/compliance.rs @@ -0,0 +1,79 @@ +//! Machine-checkable compliance: the shield shapes its own frames, never jams. +//! +//! Jamming (47 U.S.C. §333, §302a) is defined by *adding energy to interfere +//! with others' transmissions*. VEIL's protector applies an **orthogonal** +//! transform to its own beamforming feedback, which preserves the report's +//! energy exactly. This module turns that invariant into a checked artifact: it +//! measures the input/output energy of a protection step and asserts the ratio +//! is ~1, i.e. no energy was added. A regulator, an auditor, or the runtime +//! attestation layer (ADR-141) can read a [`ComplianceReport`] and see the +//! shield is a waveform-shaping control, not an emitter of interference. + +use crate::identity::BfiSample; +use crate::linalg::norm_sq; + +/// Tolerance on the energy ratio. Orthogonal rotations are exact up to f32 +/// round-off across many Givens passes. +pub const ENERGY_TOLERANCE: f32 = 1e-2; + +/// The result of auditing one protection step. +#[derive(Debug, Clone, PartialEq)] +pub struct ComplianceReport { + /// Energy of the report before protection. + pub input_energy: f32, + /// Energy of the report after protection. + pub output_energy: f32, + /// `output_energy / input_energy`. ~1.0 for an energy-preserving control. + pub energy_ratio: f32, + /// True iff the energy ratio is within [`ENERGY_TOLERANCE`] of 1.0. + pub energy_conserving: bool, + /// True iff the control adds energy on top of another station's signal. + /// Always false for VEIL by construction — it transforms its own report. + pub adds_interfering_energy: bool, +} + +impl ComplianceReport { + /// Audit a `(before, after)` protection pair. + #[must_use] + pub fn audit(before: &BfiSample, after: &BfiSample) -> Self { + let input_energy = norm_sq(&before.values); + let output_energy = norm_sq(&after.values); + let energy_ratio = if input_energy > 1e-12 { + output_energy / input_energy + } else { + 1.0 + }; + Self { + input_energy, + output_energy, + energy_ratio, + energy_conserving: (energy_ratio - 1.0).abs() <= ENERGY_TOLERANCE, + adds_interfering_energy: false, + } + } + + /// The bottom-line compliance verdict: energy-preserving and + /// non-interfering ⇒ a compliant waveform control, not jamming. + #[must_use] + pub fn is_compliant(&self) -> bool { + self.energy_conserving && !self.adds_interfering_energy + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::identity::{Channel, SceneConfig}; + use crate::protector::{Protector, ShieldConfig}; + + #[test] + fn protection_is_compliant() { + let ch = Channel::new(SceneConfig::default()); + let s = ch.observe(0, b"enroll", 3); + let p = Protector::new(ShieldConfig::default()); + let out = p.protect(&s, 555); + let report = ComplianceReport::audit(&s, &out); + assert!(report.is_compliant(), "{report:?}"); + assert!((report.energy_ratio - 1.0).abs() < ENERGY_TOLERANCE); + } +} diff --git a/wifi-veil/src/experiment.rs b/wifi-veil/src/experiment.rs new file mode 100644 index 00000000..b2a2cdf4 --- /dev/null +++ b/wifi-veil/src/experiment.rs @@ -0,0 +1,352 @@ +//! The attacker-vs-protector head-to-head. +//! +//! This is the "one node is the attacker, one node is the protector" experiment +//! from the project brief, in deterministic synthetic form. It runs the passive +//! re-identification attacker ([`crate::attacker`]) twice — once against +//! unprotected traffic and once against traffic shaped by the protector +//! ([`crate::protector`]) — and reports both accuracies against the chance +//! floor, alongside the modeled link throughput ([`crate::throughput`]) and a +//! compliance audit ([`crate::compliance`]). +//! +//! Success criteria (the brief's own bar): +//! 1. protection drives re-identification toward chance (`1/identities`); +//! 2. throughput stays above 95% of the unshielded baseline; +//! 3. the control is compliant (energy-preserving, non-jamming). + +use crate::attacker::{ + AdaptivePoolingAttacker, AttackerKind, Metric, NearestCentroidAttacker, ReconstructionAttacker, +}; +use crate::compliance::ComplianceReport; +use crate::identity::{Channel, SceneConfig}; +use crate::prng::derive_key; +use crate::protector::{ObfMode, Protector, ShieldConfig}; +use crate::throughput::LinkModel; + +/// Configuration for a full experiment. +#[derive(Debug, Clone)] +pub struct ExperimentConfig { + /// Synthetic scene. + pub scene: SceneConfig, + /// Protector configuration. + pub shield: ShieldConfig, + /// Link model for the throughput estimate. + pub link: LinkModel, + /// Enrollment sessions per identity. + pub enroll_sessions: u64, + /// Test sessions per identity. + pub test_sessions: u64, + /// Accept re-ID as "at chance" if it is at or below + /// `chance × chance_multiple + chance_margin`. + pub chance_multiple: f32, + /// Additive slack on the chance band. + pub chance_margin: f32, + /// Minimum acceptable throughput ratio. + pub min_throughput_ratio: f64, + /// Metric the passive attacker uses (for the nearest-centroid kind). + pub attacker_metric: Metric, + /// Which adversary shape to run. + pub attacker_kind: AttackerKind, +} + +impl Default for ExperimentConfig { + fn default() -> Self { + Self { + scene: SceneConfig::default(), + shield: ShieldConfig::default(), + link: LinkModel::default(), + enroll_sessions: 12, + test_sessions: 12, + chance_multiple: 2.0, + chance_margin: 0.03, + min_throughput_ratio: 0.95, + attacker_metric: Metric::Euclidean, + attacker_kind: AttackerKind::NearestCentroid, + } + } +} + +/// The outcome of an experiment. +#[derive(Debug, Clone, PartialEq)] +pub struct ExperimentReport { + /// Number of candidate identities. + pub identities: usize, + /// Ideal chance-level accuracy (`1/identities`). + pub chance_level: f32, + /// Re-identification accuracy with the shield off. + pub accuracy_shield_off: f32, + /// Re-identification accuracy with the shield on. + pub accuracy_shield_on: f32, + /// Modeled throughput ratio of the protected link vs baseline. + pub throughput_ratio: f64, + /// Compliance audit of a representative protected frame. + pub compliance: ComplianceReport, + /// Upper edge of the accepted "at chance" band. + pub chance_band: f32, +} + +impl ExperimentReport { + /// Did protection drive re-identification into the chance band? + #[must_use] + pub fn drives_to_chance(&self) -> bool { + self.accuracy_shield_on <= self.chance_band + } + + /// Is the shield-off attacker meaningfully better than chance (i.e. the + /// threat is real in this scene, so the collapse is meaningful)? + #[must_use] + pub fn attack_is_effective_without_shield(&self) -> bool { + self.accuracy_shield_off >= 0.5 + } + + /// Did throughput stay above the required floor? + #[must_use] + pub fn preserves_throughput(&self) -> bool { + self.throughput_ratio >= 0.95 + } + + /// Overall pass: real threat, collapsed to chance, throughput preserved, + /// and compliant. + #[must_use] + pub fn passed(&self) -> bool { + self.attack_is_effective_without_shield() + && self.drives_to_chance() + && self.preserves_throughput() + && self.compliance.is_compliant() + } +} + +/// Build the enroll/test capture sets for a given shield, then measure attacker +/// accuracy. `shield_on` selects whether the protector is applied to every +/// captured frame (the attacker only ever sees what is transmitted). +fn measure_accuracy( + cfg: &ExperimentConfig, + ch: &Channel, + protector: &Protector, + shield_on: bool, +) -> f32 { + let mut enroll = Vec::new(); + let mut test = Vec::new(); + + for id in 0..cfg.scene.identities { + for s in 0..cfg.enroll_sessions { + let raw = ch.observe(id, b"enroll", s); + let seen = if shield_on { + protector.protect(&raw, rotation_key(cfg, b"enroll", s, id)) + } else { + raw + }; + enroll.push((id, seen)); + } + for s in 0..cfg.test_sessions { + let raw = ch.observe(id, b"test", s); + let seen = if shield_on { + protector.protect(&raw, rotation_key(cfg, b"test", s, id)) + } else { + raw + }; + test.push((id, seen)); + } + } + + // Dispatch on the adversary shape (SOTA sweep, ADR-288 §sota). + match cfg.attacker_kind { + AttackerKind::NearestCentroid => { + let mut a = NearestCentroidAttacker::with_metric(cfg.attacker_metric); + a.enroll(&enroll); + a.accuracy(&test) + } + AttackerKind::Reconstruction => { + let mut a = ReconstructionAttacker::new(); + a.enroll(&enroll); + a.accuracy(&test) + } + AttackerKind::AdaptivePooling => { + let mut a = AdaptivePoolingAttacker::new(); + a.enroll(&enroll); + a.accuracy(&test) + } + } +} + +/// Derive the rotation key for a capture. In [`ObfMode::KeyedRotation`] the key +/// is per **session** (same rotation for every identity present in that sounding +/// interval — the AP rotates its precoder per interval, not per person; this is +/// what a legitimate receiver inverts and what makes cross-session averaging +/// collapse). In [`ObfMode::PerPacketUnitary`] it is per **packet** (unique per +/// capture), modeling the AP-side, client-transparent fresh-unitary defense. +/// The `KeyedRotation` labels are unchanged from the original so the reference +/// witness is stable. +fn rotation_key(cfg: &ExperimentConfig, phase: &[u8], session: u64, id: usize) -> u64 { + match cfg.shield.mode { + ObfMode::KeyedRotation => { + let label: &[u8] = if phase == b"enroll" { + b"rot-enroll" + } else { + b"rot-test" + }; + derive_key(cfg.scene.seed, label, session, 0) + } + ObfMode::PerPacketUnitary => { + let label: &[u8] = if phase == b"enroll" { + b"rot-enroll-pkt" + } else { + b"rot-test-pkt" + }; + derive_key(cfg.scene.seed, label, session, id as u64) + } + } +} + +/// Run the full attacker-vs-protector experiment. +#[must_use] +pub fn run(cfg: &ExperimentConfig) -> ExperimentReport { + let protector = Protector::new(cfg.shield.clone()); + let ch = Channel::new(cfg.scene.clone()); + + let accuracy_shield_off = measure_accuracy(cfg, &ch, &protector, false); + let accuracy_shield_on = measure_accuracy(cfg, &ch, &protector, true); + + let throughput_ratio = cfg.link.throughput_ratio(&cfg.shield); + + // Representative compliance audit: one protected frame vs its clean form. + let clean = ch.observe(0, b"test", 0); + let protected = protector.protect(&clean, derive_key(cfg.scene.seed, b"rot-test", 0, 0)); + let compliance = ComplianceReport::audit(&clean, &protected); + + let chance_level = cfg.scene.chance_level(); + let chance_band = chance_level * cfg.chance_multiple + cfg.chance_margin; + + ExperimentReport { + identities: cfg.scene.identities, + chance_level, + accuracy_shield_off, + accuracy_shield_on, + throughput_ratio, + compliance, + chance_band, + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn shield_off_attack_succeeds() { + let report = run(&ExperimentConfig::default()); + assert!( + report.attack_is_effective_without_shield(), + "shield-off accuracy {} should be well above chance {}", + report.accuracy_shield_off, + report.chance_level + ); + } + + #[test] + fn shield_on_drives_to_chance() { + let report = run(&ExperimentConfig::default()); + assert!( + report.drives_to_chance(), + "shield-on accuracy {} should be within chance band {}", + report.accuracy_shield_on, + report.chance_band + ); + } + + #[test] + fn shield_preserves_throughput() { + let report = run(&ExperimentConfig::default()); + assert!( + report.preserves_throughput(), + "throughput ratio {} below 0.95", + report.throughput_ratio + ); + } + + #[test] + fn overall_experiment_passes() { + let report = run(&ExperimentConfig::default()); + assert!(report.passed(), "{report:#?}"); + } + + #[test] + fn experiment_is_deterministic() { + assert_eq!( + run(&ExperimentConfig::default()), + run(&ExperimentConfig::default()) + ); + } + + // ---- SOTA-driven adversaries and modes (ADR-288 §sota) ---- + + #[test] + fn reconstruction_attacker_collapses() { + // BFIAttack-style: reconstruction recovers the *rotated* CSI direction, + // so a secret orthogonal rotation still drives it to chance — but it + // works fine on unprotected traffic (sanity that the attacker is real). + let cfg = ExperimentConfig { + attacker_kind: AttackerKind::Reconstruction, + ..ExperimentConfig::default() + }; + let r = run(&cfg); + assert!( + r.accuracy_shield_off >= 0.5, + "recon off {}", + r.accuracy_shield_off + ); + assert!(r.drives_to_chance(), "recon on {}", r.accuracy_shield_on); + } + + #[test] + fn adaptive_pooling_attacker_collapses() { + let cfg = ExperimentConfig { + attacker_kind: AttackerKind::AdaptivePooling, + ..ExperimentConfig::default() + }; + let r = run(&cfg); + assert!( + r.accuracy_shield_off >= 0.5, + "pool off {}", + r.accuracy_shield_off + ); + assert!(r.drives_to_chance(), "pool on {}", r.accuracy_shield_on); + } + + #[test] + fn per_packet_unitary_mode_collapses_and_is_compliant() { + let cfg = ExperimentConfig { + shield: ShieldConfig { + mode: ObfMode::PerPacketUnitary, + ..ShieldConfig::default() + }, + ..ExperimentConfig::default() + }; + let r = run(&cfg); + assert!( + r.drives_to_chance(), + "per-packet on {}", + r.accuracy_shield_on + ); + assert!(r.compliance.is_compliant()); + } + + #[test] + fn dp_epsilon_still_collapses_and_stays_compliant() { + // Layering the ε-DP dither on the rotation keeps the collapse and, thanks + // to renormalization, keeps the emission energy-preserving (not jamming). + let cfg = ExperimentConfig { + shield: ShieldConfig { + dp_epsilon: Some(1.0), + ..ShieldConfig::default() + }, + ..ExperimentConfig::default() + }; + let r = run(&cfg); + assert!(r.drives_to_chance()); + assert!( + r.compliance.is_compliant(), + "energy {}", + r.compliance.energy_ratio + ); + } +} diff --git a/wifi-veil/src/identity.rs b/wifi-veil/src/identity.rs new file mode 100644 index 00000000..ca3d3c73 --- /dev/null +++ b/wifi-veil/src/identity.rs @@ -0,0 +1,204 @@ +//! Synthetic beamforming-feedback model. **SYNTHETIC data only.** +//! +//! Nothing here is captured from a real radio. The model is a deliberately +//! simple, physically-motivated abstraction of a flattened 802.11 compressed +//! beamforming report, chosen so the attacker/protector dynamics are +//! transparent and the experiment is byte-reproducible. It is *not* a channel +//! simulator and its accuracy numbers describe this model, not real hardware +//! (per CLAUDE.md: results are `SYNTHETIC`, reproduced by `cargo test`). +//! +//! # The two-subspace abstraction +//! +//! A beamforming report is split into two orthogonal blocks: +//! +//! - **Comm block** (`comm_dims` leading coordinates) — the dominant beam +//! direction the AP actually uses to steer data. It varies per session with +//! position/traffic and carries **no** identity. Link throughput rides here. +//! - **Fine block** (the remainder) — the fine cross-subcarrier phase +//! structure. This is where a re-identification attacker's signal lives: the +//! literature (BFId, CCS 2025) shows the *stable* fine structure re-IDs +//! people. Communication barely uses it. +//! +//! Each identity owns a fixed, near-orthogonal signature vector in the fine +//! block. A session observation is `signature + environmental nuisance`; the +//! comm block is fresh per session. This is the honest crux of the whole +//! design: **identity leakage and data throughput live in (mostly) separable +//! subspaces**, so a transform can wreck the former while sparing the latter. + +use crate::linalg::set_norm_inplace; +use crate::prng::{derive_key, Rng}; + +/// A flattened compressed-beamforming-report vector, split into a comm block +/// and a fine block. +#[derive(Debug, Clone, PartialEq)] +pub struct BfiSample { + /// The full report: `comm_dims` comm coordinates followed by fine ones. + pub values: Vec, + /// Number of leading coordinates that form the comm (data-carrying) block. + pub comm_dims: usize, +} + +impl BfiSample { + /// Comm (data-carrying) block. + #[must_use] + pub fn comm(&self) -> &[f32] { + &self.values[..self.comm_dims] + } + + /// Fine (identity-bearing) block. + #[must_use] + pub fn fine(&self) -> &[f32] { + &self.values[self.comm_dims..] + } + + /// Mutable fine block — the only part the protector is allowed to rotate. + pub fn fine_mut(&mut self) -> &mut [f32] { + &mut self.values[self.comm_dims..] + } +} + +/// Configuration of the synthetic scene. +#[derive(Debug, Clone)] +pub struct SceneConfig { + /// Total report dimension. + pub dim: usize, + /// Leading coordinates forming the comm block. + pub comm_dims: usize, + /// Number of distinct identities (candidates). Chance level is `1/identities`. + pub identities: usize, + /// L2 norm of each identity's fine-block signature. + pub signature_norm: f32, + /// Std-dev of per-session environmental nuisance added to the fine block. + pub env_sigma: f32, + /// L2 norm of the fresh per-session comm-block beam. + pub beam_amplitude: f32, + /// Master seed. All keys derive from this; nothing touches OS entropy. + pub seed: u64, +} + +impl Default for SceneConfig { + fn default() -> Self { + Self { + dim: 64, + comm_dims: 8, + identities: 16, + signature_norm: 1.0, + env_sigma: 0.15, + beam_amplitude: 0.30, + seed: 0x5EED_1BF1, + } + } +} + +impl SceneConfig { + /// Ideal chance-level accuracy, `1 / identities`. + #[must_use] + pub fn chance_level(&self) -> f32 { + 1.0 / self.identities as f32 + } + + /// Length of the fine block. + #[must_use] + pub fn fine_dims(&self) -> usize { + self.dim - self.comm_dims + } +} + +/// Synthetic channel: turns `(identity, session)` into a [`BfiSample`]. +#[derive(Debug, Clone)] +pub struct Channel { + cfg: SceneConfig, + /// Precomputed per-identity fine-block signatures. + signatures: Vec>, +} + +impl Channel { + /// Build the channel, drawing each identity's stable signature. + #[must_use] + pub fn new(cfg: SceneConfig) -> Self { + let fine = cfg.fine_dims(); + let mut signatures = Vec::with_capacity(cfg.identities); + for id in 0..cfg.identities { + let mut rng = Rng::new(derive_key(cfg.seed, b"signature", id as u64, 0)); + let mut s: Vec = (0..fine).map(|_| rng.next_gaussian()).collect(); + set_norm_inplace(&mut s, cfg.signature_norm); + signatures.push(s); + } + Self { cfg, signatures } + } + + /// The scene configuration. + #[must_use] + pub fn config(&self) -> &SceneConfig { + &self.cfg + } + + /// The stable fine-block signature of `identity` (the thing an attacker + /// wants and the thing the shield must hide). + #[must_use] + pub fn signature(&self, identity: usize) -> &[f32] { + &self.signatures[identity] + } + + /// Observe the unprotected report for `identity` in the given session under + /// `phase` (an experiment stage label, e.g. `b"enroll"` / `b"test"`, so the + /// same session index draws independent nuisance across stages). + #[must_use] + pub fn observe(&self, identity: usize, phase: &[u8], session: u64) -> BfiSample { + let cfg = &self.cfg; + let mut values = vec![0.0f32; cfg.dim]; + + // Comm block: fresh per session, identity-independent. This is the + // data-carrying dominant beam — it holds no re-ID information. + let mut brng = Rng::new(derive_key(cfg.seed, b"beam", session, phase[0] as u64)); + for v in values[..cfg.comm_dims].iter_mut() { + *v = brng.next_gaussian(); + } + set_norm_inplace(&mut values[..cfg.comm_dims], cfg.beam_amplitude); + + // Fine block: stable identity signature + per-session nuisance. + let mut nrng = Rng::new(derive_key(cfg.seed, phase, identity as u64, session)); + let sig = &self.signatures[identity]; + for (v, s) in values[cfg.comm_dims..].iter_mut().zip(sig) { + *v = s + cfg.env_sigma * nrng.next_gaussian(); + } + + BfiSample { + values, + comm_dims: cfg.comm_dims, + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::linalg::{dist_sq, norm}; + + #[test] + fn signatures_are_well_separated() { + let ch = Channel::new(SceneConfig::default()); + // Distinct identities' signatures are near-orthogonal in high-dim, + // so pairwise distance is large relative to env noise. + let d = dist_sq(ch.signature(0), ch.signature(1)).sqrt(); + assert!(d > 1.0, "signatures too close: {d}"); + } + + #[test] + fn signature_norm_matches_config() { + let ch = Channel::new(SceneConfig::default()); + assert!((norm(ch.signature(3)) - 1.0).abs() < 1e-4); + } + + #[test] + fn observation_is_deterministic() { + let ch = Channel::new(SceneConfig::default()); + assert_eq!(ch.observe(2, b"enroll", 5), ch.observe(2, b"enroll", 5)); + } + + #[test] + fn same_session_different_phase_differs() { + let ch = Channel::new(SceneConfig::default()); + assert_ne!(ch.observe(2, b"enroll", 5), ch.observe(2, b"test", 5)); + } +} diff --git a/wifi-veil/src/lib.rs b/wifi-veil/src/lib.rs new file mode 100644 index 00000000..11af9089 --- /dev/null +++ b/wifi-veil/src/lib.rs @@ -0,0 +1,87 @@ +//! # VEIL — a compliant-waveform privacy shield against WiFi sensing +//! +//! VEIL (Verifiable Emission-shaping for Identity-Leakage prevention) is the +//! countermeasure counterpart to BFLD (ADR-118/121, `wifi-densepose-bfld`). +//! Where BFLD *detects* when beamforming feedback becomes identifying, VEIL +//! *acts*: it shapes a node's own outgoing beamforming feedback so that an +//! unauthorized passive sniffer cannot re-identify people or infer activity, +//! while a legitimate receiver — which shares the per-session key — sees an +//! essentially unchanged link. +//! +//! This crate is a **deterministic, dependency-free, WASM-ready reference and +//! experiment**, not a radio driver. It models the physics faithfully enough to +//! measure the core claim, and it never emits RF. Per ADR-288 and CLAUDE.md, +//! every number it produces is `SYNTHETIC`, reproduced by +//! `cargo test`. +//! +//! ## The idea in one paragraph +//! +//! Identity leaks through the *fine* cross-subcarrier phase structure of a +//! compressed beamforming report; data throughput rides the *dominant* beam +//! direction. These live in (mostly) separable subspaces. VEIL composes extra +//! keyed [`linalg::apply_givens`] rotations — the exact primitive the report is +//! already built from — over the **fine** subspace only. The rotation is: +//! orthogonal (energy-preserving ⇒ no added transmit power ⇒ **not jamming**, +//! [`compliance`]); keyed per session (the legitimate AP inverts it ⇒ +//! throughput preserved, [`throughput`]); and fresh each session (a sniffer +//! sees a different rotation every time and cannot average back the signature +//! ⇒ re-identification collapses to chance, [`attacker`]/[`experiment`]). +//! +//! ## Threat model and scope (stated plainly) +//! +//! VEIL defends against a **third-party passive sniffer** capturing +//! plaintext beamforming feedback. It does **not** hide identity from the AP a +//! node is associated with (that party holds the key). It is **compliant by +//! construction**: it only shapes the node's own standards-conformant frames; +//! it never transmits to interfere with another station (47 U.S.C. §333) and +//! never operates an unauthorized emitter (§302a). It is not jamming, not RF +//! denial, and not a claim of camera-grade anything. +//! +//! ## Modules +//! +//! - [`prng`] — deterministic, WASM-safe PRNG and key derivation. +//! - [`linalg`] — the small Givens-rotation vector algebra. +//! - [`identity`] — the SYNTHETIC two-subspace beamforming-feedback model. +//! - [`protector`] — the compliant waveform controls (the shield). +//! - [`attacker`] — the passive re-identification adversary. +//! - [`throughput`] — the link-throughput model. +//! - [`compliance`] — the machine-checkable "not jamming" audit. +//! - [`experiment`] — the attacker-vs-protector head-to-head. +//! - [`proof`] — the byte-stable deterministic witness. +//! +//! ## Quick start +//! +//! ``` +//! use wifi_veil::experiment::{run, ExperimentConfig}; +//! +//! let report = run(&ExperimentConfig::default()); +//! assert!(report.attack_is_effective_without_shield()); // threat is real +//! assert!(report.drives_to_chance()); // shield collapses re-ID +//! assert!(report.preserves_throughput()); // throughput ≥ 95% +//! assert!(report.compliance.is_compliant()); // energy-preserving +//! ``` + +#![warn(missing_docs)] +#![forbid(unsafe_code)] + +pub mod attacker; +pub mod compliance; +pub mod experiment; +pub mod identity; +pub mod linalg; +pub mod optimize; +pub mod prng; +pub mod proof; +pub mod protector; +pub mod throughput; + +pub use attacker::{ + AdaptivePoolingAttacker, AttackerKind, Metric, NearestCentroidAttacker, ReconstructionAttacker, +}; +pub use compliance::ComplianceReport; +pub use experiment::{run, ExperimentConfig, ExperimentReport}; +pub use identity::{BfiSample, Channel, SceneConfig}; +pub use optimize::{adaptive_shield, hyper_optimize, HyperOptimized}; +pub use proof::Proof; +pub use protector::{ObfMode, Protector, SensingDetector, ShieldConfig}; +pub use throughput::LinkModel; diff --git a/wifi-veil/src/linalg.rs b/wifi-veil/src/linalg.rs new file mode 100644 index 00000000..70c3f6dc --- /dev/null +++ b/wifi-veil/src/linalg.rs @@ -0,0 +1,89 @@ +//! Minimal, dependency-free vector algebra over `f32` slices. +//! +//! VEIL deliberately avoids `ndarray`/BLAS: the vectors are short (tens of +//! elements — a flattened compressed-beamforming angle report), the crate is +//! a WASM-ready leaf, and keeping the math inline makes the energy-conservation +//! proof in [`crate::compliance`] auditable line-by-line. + +/// Euclidean inner product. Panics if lengths differ. +#[must_use] +pub fn dot(a: &[f32], b: &[f32]) -> f32 { + assert_eq!(a.len(), b.len(), "dot: length mismatch"); + a.iter().zip(b).map(|(x, y)| x * y).sum() +} + +/// Squared L2 norm. +#[must_use] +pub fn norm_sq(a: &[f32]) -> f32 { + a.iter().map(|x| x * x).sum() +} + +/// L2 norm. +#[must_use] +pub fn norm(a: &[f32]) -> f32 { + norm_sq(a).sqrt() +} + +/// Squared Euclidean distance. Panics if lengths differ. +#[must_use] +pub fn dist_sq(a: &[f32], b: &[f32]) -> f32 { + assert_eq!(a.len(), b.len(), "dist_sq: length mismatch"); + a.iter().zip(b).map(|(x, y)| (x - y) * (x - y)).sum() +} + +/// Scale in place. +pub fn scale_inplace(a: &mut [f32], k: f32) { + for x in a.iter_mut() { + *x *= k; + } +} + +/// Normalize `a` to a target L2 norm in place. No-op if `a` is (near) zero. +pub fn set_norm_inplace(a: &mut [f32], target: f32) { + let n = norm(a); + if n > 1e-12 { + scale_inplace(a, target / n); + } +} + +/// Apply a Givens rotation to coordinates `(i, j)` of `v` by angle `theta`. +/// +/// A Givens rotation is the exact primitive 802.11 compressed beamforming +/// feedback is built from (the ψ/φ angles a beamformee reports). It is an +/// **orthogonal** operation: it preserves `‖v‖` to machine precision, which is +/// precisely why composing extra keyed Givens rotations adds *no transmit +/// energy* — the compliance argument in [`crate::compliance`]. +pub fn apply_givens(v: &mut [f32], i: usize, j: usize, theta: f32) { + debug_assert!(i < v.len() && j < v.len() && i != j); + let (c, s) = (theta.cos(), theta.sin()); + let (vi, vj) = (v[i], v[j]); + v[i] = c * vi - s * vj; + v[j] = s * vi + c * vj; +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn givens_preserves_norm() { + let mut v = vec![0.3, -1.2, 0.7, 2.1, -0.5]; + let before = norm(&v); + apply_givens(&mut v, 1, 3, 0.9); + apply_givens(&mut v, 0, 4, -2.3); + apply_givens(&mut v, 2, 3, 1.1); + let after = norm(&v); + assert!((before - after).abs() < 1e-5, "{before} vs {after}"); + } + + #[test] + fn givens_is_invertible() { + let orig = vec![1.0f32, 2.0, 3.0, 4.0]; + let mut v = orig.clone(); + apply_givens(&mut v, 0, 2, 0.7); + apply_givens(&mut v, 0, 2, -0.7); + for (a, b) in orig.iter().zip(&v) { + assert!((a - b).abs() < 1e-5); + } + } +} diff --git a/wifi-veil/src/optimize.rs b/wifi-veil/src/optimize.rs new file mode 100644 index 00000000..b885e20f --- /dev/null +++ b/wifi-veil/src/optimize.rs @@ -0,0 +1,424 @@ +//! Hyper-optimization of the shield's operating point. +//! +//! The reference crate shipped a hand-picked shield config. This module finds +//! the *optimal* one deterministically, and — crucially — proves the optimum is +//! robust rather than tuned to one attacker or one identity count: +//! +//! - [`optimal_feedback_bits`] finds the throughput-maximizing feedback +//! resolution, exploiting the interior optimum the [`crate::throughput`] model +//! exposes (residual falls with bits, airtime rises). +//! - [`min_givens_passes`] finds the **smallest** rotation-mixing budget that +//! still drives re-identification into the chance band — checked against +//! *every* attacker [`Metric`] and *every* identity count in a robustness set, +//! so the answer is the minimum that survives the hardest case, not the +//! easiest. +//! - [`pareto_frontier`] enumerates the non-dominated (privacy, throughput) +//! points for documentation and inspection. +//! - [`hyper_optimize`] combines the two into a ready-to-ship [`ShieldConfig`] +//! plus the verifying [`ExperimentReport`]. +//! +//! Optimizing over both metrics and multiple `N` is the point: if the collapse +//! held only for Euclidean at N=16, it would be a classifier artifact. It holds +//! across the set because a session-fresh secret rotation removes stable +//! identity information from the *signal*. + +use crate::attacker::Metric; +use crate::experiment::{run, ExperimentConfig, ExperimentReport}; +use crate::protector::ShieldConfig; + +/// Attacker metrics the optimizer must satisfy simultaneously. +pub const ROBUSTNESS_METRICS: [Metric; 2] = [Metric::Euclidean, Metric::Cosine]; + +/// Identity counts the optimizer must satisfy simultaneously. Larger `N` has a +/// lower chance floor, so it is the harder collapse target. +pub const ROBUSTNESS_IDENTITIES: [usize; 2] = [16, 32]; + +/// Candidate Givens-pass budgets, ascending. The optimizer returns the first +/// that collapses re-ID across the whole robustness set. +pub const PASS_CANDIDATES: [usize; 12] = [2, 4, 6, 8, 12, 16, 24, 32, 48, 64, 96, 112]; + +/// Per-angle feedback resolutions 802.11 compressed beamforming actually uses +/// (ψ/φ are quantized to roughly 5–9 bits). The shipped shield picks the +/// throughput-best value from this *spec-allowed* set, not the unconstrained +/// model optimum, so the config stays standards-faithful. +pub const ALLOWED_FEEDBACK_BITS: [u32; 3] = [5, 7, 9]; + +/// Safety margin applied to the proven-minimum pass budget. Rotation mixing is +/// keyed (derived from the shared link secret, never signaled), so extra passes +/// cost compute but **no** throughput — we spend a 2× margin on privacy for +/// free. +pub const PRIVACY_MARGIN_FACTOR: usize = 2; + +/// Run one experiment variant with the given knobs, holding everything else at +/// `base`. +fn run_variant( + base: &ExperimentConfig, + passes: usize, + bits: u32, + metric: Metric, + identities: usize, +) -> ExperimentReport { + let mut cfg = base.clone(); + cfg.shield = ShieldConfig { + givens_passes: passes, + feedback_bits: bits, + ..base.shield.clone() + }; + cfg.scene.identities = identities; + cfg.attacker_metric = metric; + run(&cfg) +} + +/// Throughput of the base link at a given feedback resolution. +fn throughput_at_bits(base: &ExperimentConfig, bits: u32) -> f64 { + base.link.throughput_ratio(&ShieldConfig { + feedback_bits: bits, + ..base.shield.clone() + }) +} + +/// Find the throughput-maximizing `feedback_bits` in `1..=max_bits` +/// (unconstrained model optimum). Returns `(bits, throughput_ratio)`. +#[must_use] +pub fn optimal_feedback_bits(base: &ExperimentConfig, max_bits: u32) -> (u32, f64) { + (1..=max_bits) + .map(|bits| (bits, throughput_at_bits(base, bits))) + .max_by(|a, b| a.1.partial_cmp(&b.1).unwrap()) + .unwrap_or((base.shield.feedback_bits, 0.0)) +} + +/// Find the throughput-maximizing feedback resolution within the spec-allowed +/// set [`ALLOWED_FEEDBACK_BITS`]. This is what the shipped shield uses. +#[must_use] +pub fn spec_optimal_feedback_bits(base: &ExperimentConfig) -> (u32, f64) { + ALLOWED_FEEDBACK_BITS + .iter() + .map(|&bits| (bits, throughput_at_bits(base, bits))) + .max_by(|a, b| a.1.partial_cmp(&b.1).unwrap()) + .unwrap() +} + +/// Does `passes` collapse re-ID into the chance band for *every* metric and +/// *every* identity count in the robustness set? +#[must_use] +pub fn passes_collapse_robustly(base: &ExperimentConfig, passes: usize, bits: u32) -> bool { + for &n in &ROBUSTNESS_IDENTITIES { + for &m in &ROBUSTNESS_METRICS { + if !run_variant(base, passes, bits, m, n).drives_to_chance() { + return false; + } + } + } + true +} + +/// Smallest Givens-pass budget from [`PASS_CANDIDATES`] that collapses re-ID +/// robustly, or `None` if even the largest candidate fails. +#[must_use] +pub fn min_givens_passes(base: &ExperimentConfig, bits: u32) -> Option { + PASS_CANDIDATES + .iter() + .copied() + .find(|&p| passes_collapse_robustly(base, p, bits)) +} + +/// One point on the privacy–throughput tradeoff. +#[derive(Debug, Clone, PartialEq)] +pub struct ParetoPoint { + /// Givens-pass budget. + pub givens_passes: usize, + /// Feedback resolution in bits. + pub feedback_bits: u32, + /// Worst-case (highest) re-ID accuracy over the robustness metrics at the + /// base identity count. + pub worst_reid: f32, + /// Modeled throughput ratio. + pub throughput_ratio: f64, + /// Whether this point collapses re-ID robustly (all metrics, all N). + pub robustly_private: bool, +} + +/// Enumerate the non-dominated (lower re-ID, higher throughput) points over a +/// grid of pass budgets and feedback resolutions. +#[must_use] +pub fn pareto_frontier(base: &ExperimentConfig, max_bits: u32) -> Vec { + let mut points: Vec = Vec::new(); + for &passes in &PASS_CANDIDATES { + for bits in 1..=max_bits { + // Worst-case re-ID over metrics at the base identity count. + let worst_reid = ROBUSTNESS_METRICS + .iter() + .map(|&m| { + run_variant(base, passes, bits, m, base.scene.identities).accuracy_shield_on + }) + .fold(0.0_f32, f32::max); + let shield = ShieldConfig { + givens_passes: passes, + feedback_bits: bits, + ..base.shield.clone() + }; + points.push(ParetoPoint { + givens_passes: passes, + feedback_bits: bits, + worst_reid, + throughput_ratio: base.link.throughput_ratio(&shield), + robustly_private: passes_collapse_robustly(base, passes, bits), + }); + } + } + // Keep only non-dominated points: no other point has both lower-or-equal + // re-ID and higher-or-equal throughput while being strictly better in one. + points + .iter() + .filter(|p| { + !points.iter().any(|q| { + let better_or_eq = + q.worst_reid <= p.worst_reid && q.throughput_ratio >= p.throughput_ratio; + let strictly_better = + q.worst_reid < p.worst_reid || q.throughput_ratio > p.throughput_ratio; + better_or_eq && strictly_better + }) + }) + .cloned() + .collect() +} + +/// The chosen optimum plus the report that verifies it. +#[derive(Debug, Clone)] +pub struct HyperOptimized { + /// The optimized, ready-to-ship shield configuration. + pub shield: ShieldConfig, + /// Minimum Givens passes that collapses re-ID robustly (before the margin). + pub min_passes: usize, + /// Shipped Givens passes = `min_passes` grown by [`PRIVACY_MARGIN_FACTOR`]. + pub shipped_passes: usize, + /// Unconstrained throughput-optimal feedback resolution (a research point). + pub model_optimal_bits: u32, + /// Spec-allowed throughput-optimal resolution (what the shield ships with). + pub spec_optimal_bits: u32, + /// The verifying experiment at the base identity count. + pub report: ExperimentReport, +} + +/// Smallest pass candidate that is at least `target`. +fn ceil_to_candidate(target: usize) -> usize { + PASS_CANDIDATES + .iter() + .copied() + .find(|&p| p >= target) + .unwrap_or_else(|| *PASS_CANDIDATES.last().unwrap()) +} + +/// Find the optimal shield: the spec-allowed throughput-optimal feedback +/// resolution, and the minimum rotation-mixing budget that collapses re-ID +/// robustly, grown by a free privacy margin. Deterministic and idempotent — the +/// shipped [`ShieldConfig::default`] is exactly this function's output on the +/// default base (asserted in tests). +#[must_use] +pub fn hyper_optimize(base: &ExperimentConfig) -> HyperOptimized { + let (model_optimal_bits, _) = optimal_feedback_bits(base, 12); + let (spec_optimal_bits, _) = spec_optimal_feedback_bits(base); + + let min_passes = min_givens_passes(base, spec_optimal_bits) + .unwrap_or_else(|| *PASS_CANDIDATES.last().unwrap()); + let shipped_passes = ceil_to_candidate(min_passes * PRIVACY_MARGIN_FACTOR); + + let shield = ShieldConfig { + givens_passes: shipped_passes, + feedback_bits: spec_optimal_bits, + ..base.shield.clone() + }; + let mut cfg = base.clone(); + cfg.shield = shield.clone(); + let report = run(&cfg); + + HyperOptimized { + shield, + min_passes, + shipped_passes, + model_optimal_bits, + spec_optimal_bits, + report, + } +} + +// --------------------------------------------------------------------------- +// Adaptive optimization: the optimum is not one config — it depends on the +// deployment's SNR (which shifts the throughput-optimal feedback resolution) +// and its identity count (which sets how much rotation mixing collapse needs). +// These functions derive the right config per deployment rather than assuming +// the default scene. +// --------------------------------------------------------------------------- + +/// SNR values (dB) to profile the throughput-optimal feedback resolution over. +pub const SNR_PROFILE_DB: [f64; 5] = [5.0, 10.0, 20.0, 30.0, 40.0]; + +/// Unconstrained throughput-optimal feedback resolution for a specific SNR, +/// holding the rest of `base`. At low SNR the residual matters proportionally +/// more (Shannon capacity is near-linear), so higher resolution wins; at high +/// SNR the log compresses the residual away and feedback airtime dominates, +/// favoring fewer bits. (The *shipped* shield clamps to the 802.11 {5,7,9} set, +/// where 5 already zeroes the residual — so this shift is visible only in the +/// unconstrained optimum, and is what motivates keeping resolution low.) +#[must_use] +pub fn model_optimal_bits_for_snr(base: &ExperimentConfig, snr_db: f64) -> (u32, f64) { + let mut cfg = base.clone(); + cfg.link.snr_db = snr_db; + optimal_feedback_bits(&cfg, 12) +} + +/// Profile the unconstrained throughput-optimal feedback resolution across +/// [`SNR_PROFILE_DB`]. Demonstrates the SNR → resolution dependence. +#[must_use] +pub fn optimal_bits_across_snr(base: &ExperimentConfig) -> Vec<(f64, u32)> { + SNR_PROFILE_DB + .iter() + .map(|&snr| (snr, model_optimal_bits_for_snr(base, snr).0)) + .collect() +} + +/// Does `passes` collapse re-ID for both metrics at a single identity count? +#[must_use] +pub fn passes_collapse_at_n(base: &ExperimentConfig, passes: usize, bits: u32, n: usize) -> bool { + ROBUSTNESS_METRICS + .iter() + .all(|&m| run_variant(base, passes, bits, m, n).drives_to_chance()) +} + +/// Smallest pass budget that collapses re-ID for a *specific* identity count. +/// More candidates ⇒ lower chance floor ⇒ generally more mixing required, so +/// this grows with `n`. +#[must_use] +pub fn min_passes_for_n(base: &ExperimentConfig, bits: u32, n: usize) -> Option { + PASS_CANDIDATES + .iter() + .copied() + .find(|&p| passes_collapse_at_n(base, p, bits, n)) +} + +/// Derive a ready-to-ship shield for a specific deployment: throughput-optimal +/// feedback resolution for the deployment SNR, and the minimum mixing budget for +/// its identity count grown by the free [`PRIVACY_MARGIN_FACTOR`] margin. This is +/// what an operator should call for a room with `n` expected occupants on a link +/// with `base.link`'s SNR — the default config is just this at N=16. +#[must_use] +pub fn adaptive_shield(base: &ExperimentConfig, n: usize) -> ShieldConfig { + let (bits, _) = spec_optimal_feedback_bits(base); + let min_passes = + min_passes_for_n(base, bits, n).unwrap_or_else(|| *PASS_CANDIDATES.last().unwrap()); + ShieldConfig { + givens_passes: ceil_to_candidate(min_passes * PRIVACY_MARGIN_FACTOR), + feedback_bits: bits, + ..base.shield.clone() + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn model_optimal_bits_is_interior() { + let (bits, ratio) = optimal_feedback_bits(&ExperimentConfig::default(), 12); + assert!(bits > 1 && bits < 12, "optimum at edge: {bits}"); + assert!(ratio > 0.95); + } + + #[test] + fn spec_optimal_bits_is_the_low_res_end() { + // Within {5,7,9}, lower resolution wins because the receiver compensates + // the keyed rotation, so extra bits mostly buy airtime. + let (bits, _) = spec_optimal_feedback_bits(&ExperimentConfig::default()); + assert_eq!(bits, 5); + } + + #[test] + fn min_passes_is_below_the_original_default() { + // The original hand-picked default was 112 passes. The optimizer proves + // far fewer suffice — the "we over-provisioned" finding. + let (bits, _) = spec_optimal_feedback_bits(&ExperimentConfig::default()); + let p = min_givens_passes(&ExperimentConfig::default(), bits).expect("collapses"); + assert!(p < 112, "min passes {p} should be below the old 112"); + assert!(p >= 2); + } + + #[test] + fn shipped_default_equals_optimizer_output() { + // The crate's default shield IS the optimizer's recommendation — they + // cannot silently drift apart. + let opt = hyper_optimize(&ExperimentConfig::default()); + assert_eq!( + opt.shield.givens_passes, + ShieldConfig::default().givens_passes + ); + assert_eq!( + opt.shield.feedback_bits, + ShieldConfig::default().feedback_bits + ); + assert!(opt.report.passed(), "{:#?}", opt.report); + } + + #[test] + fn optimum_collapses_under_both_metrics_and_larger_n() { + let opt = hyper_optimize(&ExperimentConfig::default()); + assert!(passes_collapse_robustly( + &ExperimentConfig::default(), + opt.shipped_passes, + opt.spec_optimal_bits + )); + } + + #[test] + fn optimal_bits_shift_with_snr() { + // Low-SNR deployments favor higher feedback resolution; high-SNR favor + // lower. The (unconstrained) profile is non-increasing in SNR and not + // constant across the range. + let profile = optimal_bits_across_snr(&ExperimentConfig::default()); + let low = profile.first().unwrap().1; + let high = profile.last().unwrap().1; + assert!( + low >= high, + "low-SNR bits {low} should be >= high-SNR bits {high}" + ); + assert!(low != high, "profile did not shift with SNR: {profile:?}"); + } + + #[test] + fn adaptive_shield_mixing_is_nondecreasing_in_n() { + // A room with more candidate identities needs at least as much mixing. + // In this model the collapse budget is governed by fine-subspace + // dimension, so the requirement is flat across N — the invariant we can + // assert is non-decreasing, and that it never *under*-provisions. + let base = ExperimentConfig::default(); + let small = adaptive_shield(&base, 8); + let large = adaptive_shield(&base, 64); + assert!( + large.givens_passes >= small.givens_passes, + "N=64 passes {} should be >= N=8 passes {}", + large.givens_passes, + small.givens_passes + ); + } + + #[test] + fn adaptive_shield_collapses_at_its_target_n() { + let base = ExperimentConfig::default(); + for n in [8usize, 32, 64] { + let sh = adaptive_shield(&base, n); + assert!( + passes_collapse_at_n(&base, sh.givens_passes, sh.feedback_bits, n), + "adaptive shield for N={n} does not collapse" + ); + } + } + + #[test] + fn frontier_is_non_empty_and_deterministic() { + // Small grid keeps this fast; the frontier logic is grid-size agnostic. + let base = ExperimentConfig::default(); + let a = pareto_frontier(&base, 3); + let b = pareto_frontier(&base, 3); + assert!(!a.is_empty()); + assert_eq!(a, b); + } +} diff --git a/wifi-veil/src/prng.rs b/wifi-veil/src/prng.rs new file mode 100644 index 00000000..e057f9bb --- /dev/null +++ b/wifi-veil/src/prng.rs @@ -0,0 +1,119 @@ +//! Deterministic, WASM-safe pseudo-random generator. +//! +//! VEIL never draws from OS entropy: every stochastic quantity in the +//! experiment (identity signatures, environmental nuisance, per-session +//! precoder rotations) seeds from an explicit `u64`. Same seed in → same +//! bytes out, on any platform including `wasm32-unknown-unknown`. This is +//! what makes [`crate::proof`] a byte-stable witness rather than a flaky +//! statistical assertion. +//! +//! The core is SplitMix64 (Steele, Lea & Flood 2014) — a well-mixed +//! finalizer that is more than adequate for synthetic-data generation and +//! keyed subspace rotation. It is **not** a cryptographic RNG and must not +//! be used to derive real key material; in a deployment the per-session +//! rotation key comes from the negotiated link secret, not from this PRNG. + +/// A deterministic SplitMix64 stream. +#[derive(Debug, Clone)] +pub struct Rng { + state: u64, +} + +impl Rng { + /// Seed the stream. Distinct seeds yield independent streams. + #[must_use] + pub fn new(seed: u64) -> Self { + Self { + state: seed ^ 0x9E37_79B9_7F4A_7C15, + } + } + + /// Next raw 64-bit word. + pub fn next_u64(&mut self) -> u64 { + self.state = self.state.wrapping_add(0x9E37_79B9_7F4A_7C15); + let mut z = self.state; + z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9); + z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB); + z ^ (z >> 31) + } + + /// Uniform `f32` in `[0, 1)` using the top 24 mantissa bits. + pub fn next_f32(&mut self) -> f32 { + // 24 bits of precision keeps the value exactly representable. + ((self.next_u64() >> 40) as f32) / ((1u64 << 24) as f32) + } + + /// Uniform `f32` in `[lo, hi)`. + pub fn next_range(&mut self, lo: f32, hi: f32) -> f32 { + lo + (hi - lo) * self.next_f32() + } + + /// Standard-normal `f32` via the Box–Muller transform. + pub fn next_gaussian(&mut self) -> f32 { + let u1 = self.next_f32().max(1e-7); + let u2 = self.next_f32(); + (-2.0 * u1.ln()).sqrt() * (core::f32::consts::TAU * u2).cos() + } +} + +/// FNV-1a 64-bit hash — a dependency-free, deterministic byte folder used to +/// derive per-session keys from `(scene_seed, phase, index)` tuples and to +/// build the [`crate::proof`] witness. Not cryptographic. +#[must_use] +pub fn fnv1a_64(bytes: &[u8]) -> u64 { + let mut h: u64 = 0xCBF2_9CE4_8422_2325; + for &b in bytes { + h ^= u64::from(b); + h = h.wrapping_mul(0x0000_0100_0000_01B3); + } + h +} + +/// Fold a label and two indices into a stable `u64` key. +#[must_use] +pub fn derive_key(scene_seed: u64, label: &[u8], a: u64, b: u64) -> u64 { + let mut buf = Vec::with_capacity(label.len() + 24); + buf.extend_from_slice(&scene_seed.to_le_bytes()); + buf.extend_from_slice(label); + buf.extend_from_slice(&a.to_le_bytes()); + buf.extend_from_slice(&b.to_le_bytes()); + fnv1a_64(&buf) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn stream_is_deterministic() { + let mut a = Rng::new(42); + let mut b = Rng::new(42); + for _ in 0..1000 { + assert_eq!(a.next_u64(), b.next_u64()); + } + } + + #[test] + fn distinct_seeds_diverge() { + let mut a = Rng::new(1); + let mut b = Rng::new(2); + assert_ne!(a.next_u64(), b.next_u64()); + } + + #[test] + fn uniform_in_range() { + let mut r = Rng::new(7); + for _ in 0..10_000 { + let x = r.next_f32(); + assert!((0.0..1.0).contains(&x)); + } + } + + #[test] + fn gaussian_mean_near_zero() { + let mut r = Rng::new(9); + let n = 100_000; + let mean: f64 = (0..n).map(|_| f64::from(r.next_gaussian())).sum::() / f64::from(n); + assert!(mean.abs() < 0.02, "mean {mean} not near 0"); + } +} diff --git a/wifi-veil/src/proof.rs b/wifi-veil/src/proof.rs new file mode 100644 index 00000000..b1124916 --- /dev/null +++ b/wifi-veil/src/proof.rs @@ -0,0 +1,82 @@ +//! Deterministic proof bundle — the byte-stable witness for VEIL. +//! +//! Mirrors the `nvsim` / `archive/v1` proof pattern: run a fixed reference +//! experiment, fold its salient outputs into a single FNV-1a witness, and pin +//! that witness as a constant. If any constant drifts — the PRNG stream, the +//! rotation schedule, the throughput formula, the scene geometry — the witness +//! changes and the test fails loudly. +//! +//! The witness is derived from **quantized** outputs (accuracies to 1e-4, +//! throughput to 1e-6) so that legitimate cross-platform f32 round-off in the +//! last bits does not spuriously break the proof, while any real change to the +//! experiment's behavior still does. + +use crate::experiment::{run, ExperimentConfig, ExperimentReport}; +use crate::prng::fnv1a_64; + +/// Deterministic-proof harness. +pub struct Proof; + +impl Proof { + /// Pinned witness over the reference experiment. Re-derived by + /// [`Proof::witness`]; asserted by the test below. + pub const EXPECTED_WITNESS: u64 = 0x350D_7CDF_95D9_F448; + + /// The reference configuration. Uses every default so the proof tracks the + /// shipped behavior of the crate. + #[must_use] + pub fn reference_config() -> ExperimentConfig { + ExperimentConfig::default() + } + + /// Run the reference experiment. + #[must_use] + pub fn run_reference() -> ExperimentReport { + run(&Self::reference_config()) + } + + /// Fold a report's salient outputs into a stable witness. + #[must_use] + pub fn witness(report: &ExperimentReport) -> u64 { + let mut buf = Vec::new(); + buf.extend_from_slice(&(report.identities as u64).to_le_bytes()); + // Quantize floats before folding so last-bit round-off is not part of + // the witness. + let q4 = |x: f32| (f64::from(x) * 10_000.0).round() as i64; + let q6 = |x: f64| (x * 1_000_000.0).round() as i64; + buf.extend_from_slice(&q4(report.chance_level).to_le_bytes()); + buf.extend_from_slice(&q4(report.accuracy_shield_off).to_le_bytes()); + buf.extend_from_slice(&q4(report.accuracy_shield_on).to_le_bytes()); + buf.extend_from_slice(&q6(report.throughput_ratio).to_le_bytes()); + buf.extend_from_slice(&q4(report.compliance.energy_ratio).to_le_bytes()); + fnv1a_64(&buf) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn reference_experiment_passes() { + assert!(Proof::run_reference().passed()); + } + + #[test] + fn witness_is_stable() { + let a = Proof::witness(&Proof::run_reference()); + let b = Proof::witness(&Proof::run_reference()); + assert_eq!(a, b, "witness must be reproducible"); + } + + #[test] + fn witness_matches_pinned() { + let w = Proof::witness(&Proof::run_reference()); + assert_eq!( + w, + Proof::EXPECTED_WITNESS, + "witness drifted to {w:#018x}; update EXPECTED_WITNESS only if the \ + change to the reference experiment is intentional" + ); + } +} diff --git a/wifi-veil/src/protector.rs b/wifi-veil/src/protector.rs new file mode 100644 index 00000000..c17bdce9 --- /dev/null +++ b/wifi-veil/src/protector.rs @@ -0,0 +1,298 @@ +//! The VEIL protector: compliant waveform controls that hide identity. +//! +//! # What it does (and does not do) +//! +//! The protector shapes the node's **own** beamforming feedback before it goes +//! on air. It applies a per-session, key-derived **orthogonal rotation** to the +//! fine block of the report, composed from extra Givens rotations — the same +//! angle primitive the report already carries. Because the rotation is: +//! +//! - **orthogonal** → it preserves the report's energy exactly (no added +//! transmit power, no out-of-mask emission → **not jamming**, see +//! [`crate::compliance`]); +//! - **keyed per session** → the legitimate AP/STA, which shares the session +//! key, inverts it and recovers the true precoder (throughput preserved, +//! see [`crate::throughput`]); +//! - **fresh each session** → an external sniffer sees a different rotation of +//! the identity signature every session and cannot average them back to the +//! signature, so cross-session re-identification collapses toward chance. +//! +//! This is the shared-secret precoding idea (cf. MIMOCrypt, NSDI-adjacent work) +//! specialized to the identity-bearing fine subspace. +//! +//! # Scope limit (stated honestly) +//! +//! VEIL defends against a **third-party passive sniffer**. It does *not* hide +//! identity from the AP the node is associated with (that party holds the key +//! by construction). Protecting against a malicious AP is a different problem +//! handled by the BFLD detection layer and privacy-class policy (ADR-118/141), +//! not by this shield. VEIL never jams and never touches another station's +//! frames. + +use crate::identity::BfiSample; +use crate::linalg::{apply_givens, norm, set_norm_inplace}; +use crate::prng::Rng; + +/// Per-dimension angular-noise sensitivity for the ε-DP dither. Chosen so ε≈1 is +/// a mild perturbation and ε≲0.2 is aggressive. SYNTHETIC modeling constant. +const DP_ANGULAR_SENSITIVITY: f32 = 0.05; + +/// How the shield keys its per-transform randomness. Both modes use the same +/// energy-preserving Givens machinery; the difference is *granularity* and +/// *who changes* — captured here so the deployment story is explicit (ADR-288 +/// §sota; validated against the SOTA sweep). +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum ObfMode { + /// Secret per-*session* rotation, shared-key-reversible by the associated + /// receiver (VEIL's original design). One rotation per sounding interval. + #[default] + KeyedRotation, + /// A fresh random unitary per *packet*, applied AP-side to the transmitted + /// report; **client-transparent** — only the AP changes, clients are + /// unmodified and unaware. Models the LeakyBeam-family defense (NDSS 2025, + /// MEASURED 89.7%→~51%) that rides the 802.11 spatial-mapping mechanism the + /// standard marks "not restricted". Even harder to average out than + /// per-session, at the cost of no cross-packet reuse. + PerPacketUnitary, +} + +/// Configuration of the protector. +#[derive(Debug, Clone)] +pub struct ShieldConfig { + /// Master switch. When `false`, [`Protector::protect`] is the identity map + /// (used to model the "shield off" baseline). + pub enabled: bool, + /// Number of keyed Givens rotations composed per session. Enough passes + /// approximate a Haar-random rotation of the fine block, which is what + /// drives the attacker to chance. The optimal value is found by + /// [`crate::optimize`] (not hand-tuned); more passes cost compute but no + /// throughput, since the rotation is keyed rather than signaled. + pub givens_passes: usize, + /// Bits used to quantize each reported angle (802.11 uses 5–9). Higher + /// resolution ⇒ smaller uncompensated residual at the legitimate receiver + /// ⇒ smaller throughput cost. See [`crate::throughput`]. + pub feedback_bits: u32, + /// Fractional airtime overhead from sounding-cadence randomization + /// (jittering NDP intervals so an eavesdropper under-samples motion). + pub sounding_overhead: f64, + /// Keying granularity of the obfuscation (see [`ObfMode`]). + pub mode: ObfMode, + /// Optional ε-DP angular dither budget layered on top of the rotation + /// (`None` = off). Smaller ε ⇒ more angular noise ⇒ stronger formal privacy + /// on the *raw reported angles* but larger throughput cost. The dithered + /// report is renormalized to its original energy, so it stays a valid unit + /// precoder and the emission remains energy-preserving (not jamming). + /// Models the DP-Givens mechanism (arXiv:2512.18529, SYNTHETIC). Any number + /// derived from it is SYNTHETIC. + pub dp_epsilon: Option, +} + +impl Default for ShieldConfig { + fn default() -> Self { + // These values are the output of `optimize::hyper_optimize` on the + // default scene (ADR-288 §opt), not hand-picked: 96 = 2× the proven- + // minimum 48 robust passes (free margin, since mixing is keyed not + // signaled), and 5 = the throughput-best resolution in the 802.11 + // {5,7,9} set. `optimize::shipped_default_equals_optimizer_output` + // guards against drift. `mode`/`dp_epsilon` default to the original + // behavior so the reference witness is unchanged. + Self { + enabled: true, + givens_passes: 96, + feedback_bits: 5, + sounding_overhead: 0.02, + mode: ObfMode::KeyedRotation, + dp_epsilon: None, + } + } +} + +/// Applies compliant waveform controls to outgoing beamforming feedback. +#[derive(Debug, Clone)] +pub struct Protector { + cfg: ShieldConfig, +} + +impl Protector { + /// Build a protector. + #[must_use] + pub fn new(cfg: ShieldConfig) -> Self { + Self { cfg } + } + + /// The configuration. + #[must_use] + pub fn config(&self) -> &ShieldConfig { + &self.cfg + } + + /// Build the list of `(i, j, theta)` Givens rotations for a session. The + /// legitimate receiver derives the identical list from the shared session + /// key and applies the inverse (negated angles, reversed order). + fn session_rotation(&self, fine_dims: usize, session_key: u64) -> Vec<(usize, usize, f32)> { + let mut rng = Rng::new(session_key); + let mut ops = Vec::with_capacity(self.cfg.givens_passes); + for _ in 0..self.cfg.givens_passes { + // Draw a distinct coordinate pair in the fine block. + let i = (rng.next_u64() as usize) % fine_dims; + let mut j = (rng.next_u64() as usize) % fine_dims; + if j == i { + j = (j + 1) % fine_dims; + } + let theta = rng.next_range(0.0, core::f32::consts::TAU); + ops.push((i, j, theta)); + } + ops + } + + /// Protect an outgoing report for the given session. When the shield is + /// disabled this clones the input unchanged. + /// + /// The keyed Givens rotation runs whenever `givens_passes > 0`; the caller + /// chooses `session_key`'s granularity (a per-session key for + /// [`ObfMode::KeyedRotation`], a per-packet key for + /// [`ObfMode::PerPacketUnitary`]). If `dp_epsilon` is set, an ε-scaled + /// angular dither is added afterward and the fine block is renormalized to + /// its original energy (so the emission stays energy-preserving). + #[must_use] + pub fn protect(&self, sample: &BfiSample, session_key: u64) -> BfiSample { + let mut out = sample.clone(); + if !self.cfg.enabled { + return out; + } + let fine_dims = out.fine().len(); + let ops = self.session_rotation(fine_dims, session_key); + let fine = out.fine_mut(); + for (i, j, theta) in ops { + apply_givens(fine, i, j, theta); + } + if let Some(eps) = self.cfg.dp_epsilon { + Self::dp_dither(fine, eps, session_key); + } + out + } + + /// Add an ε-DP angular dither to `fine`, then renormalize to the original + /// energy. Noise scale ∝ 1/ε (smaller ε ⇒ more noise ⇒ stronger privacy on + /// the raw angles). Renormalization keeps it a valid unit precoder, so the + /// step adds no transmit energy. SYNTHETIC. + fn dp_dither(fine: &mut [f32], epsilon: f32, key: u64) { + let before = norm(fine); + if before <= 1e-12 { + return; + } + // Laplace-like scale for an angular budget; bounded so ε→0 saturates. + let scale = (DP_ANGULAR_SENSITIVITY / epsilon.max(1e-3)).min(2.0); + let mut rng = Rng::new(key ^ 0xD1FF_D1FF_D1FF_D1FF); + for v in fine.iter_mut() { + *v += scale * rng.next_gaussian(); + } + set_norm_inplace(fine, before); + } + + /// Recover the true report at the legitimate receiver, which shares the + /// session key. Applies the inverse rotation. Used to demonstrate that the + /// transform is reversible for the authorized party (the basis of the + /// throughput claim), not part of the attacker's world. + #[must_use] + pub fn recover(&self, sample: &BfiSample, session_key: u64) -> BfiSample { + let mut out = sample.clone(); + if !self.cfg.enabled { + return out; + } + let fine_dims = out.fine().len(); + let ops = self.session_rotation(fine_dims, session_key); + let fine = out.fine_mut(); + for (i, j, theta) in ops.into_iter().rev() { + apply_givens(fine, i, j, -theta); + } + out + } +} + +/// A minimal detector for unsolicited sensing activity. In a deployment this +/// watches the rate of NDP/sensing-sounding solicitations; here it exposes the +/// decision rule so the control plane (ADR-280) can engage the shield only when +/// sensing is actually observed, rather than perturbing continuously. +#[derive(Debug, Clone)] +pub struct SensingDetector { + /// Solicitations per second above which the shield engages. + pub threshold_hz: f32, +} + +impl Default for SensingDetector { + fn default() -> Self { + Self { threshold_hz: 5.0 } + } +} + +impl SensingDetector { + /// Should the shield engage given the observed solicitation rate? + #[must_use] + pub fn should_engage(&self, observed_hz: f32) -> bool { + observed_hz >= self.threshold_hz + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::identity::{Channel, SceneConfig}; + use crate::linalg::{dist_sq, norm}; + + #[test] + fn protection_preserves_energy() { + let ch = Channel::new(SceneConfig::default()); + let s = ch.observe(0, b"enroll", 1); + let p = Protector::new(ShieldConfig::default()); + let out = p.protect(&s, 12345); + assert!((norm(&s.values) - norm(&out.values)).abs() < 1e-3); + } + + #[test] + fn protection_leaves_comm_block_untouched() { + let ch = Channel::new(SceneConfig::default()); + let s = ch.observe(0, b"enroll", 1); + let p = Protector::new(ShieldConfig::default()); + let out = p.protect(&s, 999); + assert_eq!(s.comm(), out.comm()); + } + + #[test] + fn protection_scrambles_fine_block() { + let ch = Channel::new(SceneConfig::default()); + let s = ch.observe(0, b"enroll", 1); + let p = Protector::new(ShieldConfig::default()); + let out = p.protect(&s, 42); + assert!(dist_sq(s.fine(), out.fine()).sqrt() > 0.5); + } + + #[test] + fn legitimate_receiver_recovers() { + let ch = Channel::new(SceneConfig::default()); + let s = ch.observe(0, b"enroll", 1); + let p = Protector::new(ShieldConfig::default()); + let out = p.protect(&s, 7); + let back = p.recover(&out, 7); + assert!(dist_sq(s.fine(), back.fine()).sqrt() < 1e-2); + } + + #[test] + fn disabled_shield_is_identity() { + let ch = Channel::new(SceneConfig::default()); + let s = ch.observe(0, b"enroll", 1); + let cfg = ShieldConfig { + enabled: false, + ..ShieldConfig::default() + }; + let p = Protector::new(cfg); + assert_eq!(s, p.protect(&s, 7)); + } + + #[test] + fn detector_engages_above_threshold() { + let d = SensingDetector::default(); + assert!(d.should_engage(10.0)); + assert!(!d.should_engage(1.0)); + } +} diff --git a/wifi-veil/src/throughput.rs b/wifi-veil/src/throughput.rs new file mode 100644 index 00000000..6685f599 --- /dev/null +++ b/wifi-veil/src/throughput.rs @@ -0,0 +1,179 @@ +//! Link-throughput model for the protected node. +//! +//! The claim under test is "throughput stays above 95% with the shield on". +//! The model is intentionally transparent and errs toward *charging* the +//! shield, not flattering it. Three costs are charged: +//! +//! - **Beamforming residual.** The legitimate receiver shares the session key +//! and inverts the protector's rotation, so it does not pay the rotation +//! itself — only the residual from quantizing the extra angles at +//! `feedback_bits` resolution. Per-angle mean-square quantization error is +//! `Δ²/12` for step `Δ = (π/2)/2^bits`; this fraction of beamforming gain is +//! lost. It shrinks fast with more bits. +//! - **Feedback airtime.** Reporting the angles at higher resolution costs more +//! uplink airtime — charged as `feedback_overhead_per_bit · feedback_bits`. +//! It grows with more bits. +//! - **Sounding overhead.** Randomizing the NDP sounding cadence costs airtime +//! directly; a flat `sounding_overhead` fraction. +//! +//! The residual (falling) and the feedback airtime (rising) pull `feedback_bits` +//! in opposite directions, so throughput has a genuine **interior optimum** in +//! the number of feedback bits — the quantity [`crate::optimize`] searches for. +//! The optimum lands at coarse-to-moderate resolution because the receiver +//! compensates the keyed rotation, so extra bits mostly buy airtime, not gain — +//! echoing the DySPAN-2026 finding that ~3-bit feedback is near the sweet spot. +//! +//! Throughput ratio = +//! `(1 − sounding − feedback_airtime) · C(SNR·(1−ρ)) / C(SNR)` where +//! `C(x) = log2(1 + x)`. The comm block is never perturbed, so its geometry is +//! intact; only the SNR is nudged by the residual `ρ`. + +use crate::protector::ShieldConfig; + +/// A single-stream link model. +#[derive(Debug, Clone)] +pub struct LinkModel { + /// Operating SNR of the data-carrying beam, in dB. + pub snr_db: f64, + /// Uplink airtime charged per feedback bit, as a fraction of throughput. + /// Larger values push the throughput-optimal `feedback_bits` lower. + pub feedback_overhead_per_bit: f64, +} + +impl Default for LinkModel { + fn default() -> Self { + Self { + snr_db: 20.0, + feedback_overhead_per_bit: 0.0008, + } + } +} + +impl LinkModel { + /// Linear SNR. + #[must_use] + pub fn snr_linear(&self) -> f64 { + 10f64.powf(self.snr_db / 10.0) + } + + /// Baseline Shannon capacity (bits/s/Hz) with no shield. + #[must_use] + pub fn baseline_capacity(&self) -> f64 { + (1.0 + self.snr_linear()).log2() + } + + /// Uncompensated beamforming-gain residual from finite feedback resolution. + #[must_use] + pub fn beamforming_residual(shield: &ShieldConfig) -> f64 { + if !shield.enabled { + return 0.0; + } + let step = (core::f64::consts::FRAC_PI_2) / f64::from(1u32 << shield.feedback_bits); + // Mean-square quantization error of a uniform quantizer, as a fraction + // of unit gain. Clamp for safety at absurdly low resolutions. + (step * step / 12.0).min(0.5) + } + + /// Uplink airtime cost of reporting angles at `feedback_bits` resolution. + #[must_use] + pub fn feedback_airtime(&self, shield: &ShieldConfig) -> f64 { + if !shield.enabled { + return 0.0; + } + self.feedback_overhead_per_bit * f64::from(shield.feedback_bits) + } + + /// Beamforming-gain residual from the ε-DP angular dither, if enabled. + /// Unlike the keyed rotation (which the receiver undoes), the DP noise is + /// **not** removed, so it costs gain directly and grows as ε shrinks — + /// this is the tunable privacy↔throughput knob. SYNTHETIC. + #[must_use] + pub fn dp_residual(shield: &ShieldConfig) -> f64 { + match shield.dp_epsilon { + Some(eps) if shield.enabled => { + let e = f64::from(eps).max(1e-3); + (DP_GAIN_COST / (e * e)).min(0.5) + } + _ => 0.0, + } + } + + /// Throughput ratio of the protected link versus the unshielded baseline, + /// in `[0, 1]`. + #[must_use] + pub fn throughput_ratio(&self, shield: &ShieldConfig) -> f64 { + if !shield.enabled { + return 1.0; + } + let rho = (Self::beamforming_residual(shield) + Self::dp_residual(shield)).min(0.9); + let snr = self.snr_linear(); + let capacity_ratio = (1.0 + snr * (1.0 - rho)).log2() / self.baseline_capacity(); + let airtime = shield.sounding_overhead + self.feedback_airtime(shield); + ((1.0 - airtime) * capacity_ratio).clamp(0.0, 1.0) + } +} + +/// Gain-cost coefficient for the ε-DP dither: residual ≈ `DP_GAIN_COST / ε²`. +/// Tuned so ε≈1 costs a few points of gain and ε≲0.3 costs a lot. SYNTHETIC. +const DP_GAIN_COST: f64 = 0.004; + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn baseline_ratio_is_one() { + let cfg = ShieldConfig { + enabled: false, + ..ShieldConfig::default() + }; + assert!((LinkModel::default().throughput_ratio(&cfg) - 1.0).abs() < 1e-9); + } + + #[test] + fn default_config_preserves_throughput() { + let ratio = LinkModel::default().throughput_ratio(&ShieldConfig::default()); + assert!(ratio > 0.95, "ratio {ratio}"); + assert!(ratio < 1.0); + } + + #[test] + fn dp_epsilon_lowers_throughput_as_it_tightens() { + // The ε-DP dither is a real, tunable privacy↔throughput knob: smaller ε + // (more noise) costs more gain. None (off) is the cheapest. + let link = LinkModel::default(); + let at = |eps: Option| { + link.throughput_ratio(&ShieldConfig { + dp_epsilon: eps, + ..ShieldConfig::default() + }) + }; + let off = at(None); + let loose = at(Some(2.0)); + let tight = at(Some(0.3)); + assert!(off >= loose && loose > tight, "{off} {loose} {tight}"); + } + + #[test] + fn throughput_has_interior_optimum_in_bits() { + // Very low resolution pays the residual; very high resolution pays + // airtime. The optimum is strictly interior — neither extreme wins. + let link = LinkModel::default(); + let at = |bits: u32| { + link.throughput_ratio(&ShieldConfig { + feedback_bits: bits, + ..ShieldConfig::default() + }) + }; + let lo = at(1); + let hi = at(12); + let best_bits = (1..=12) + .max_by(|&a, &b| at(a).partial_cmp(&at(b)).unwrap()) + .unwrap(); + assert!( + best_bits > 1 && best_bits < 12, + "optimum at edge: {best_bits}" + ); + assert!(at(best_bits) > lo && at(best_bits) > hi); + } +} diff --git a/wifi-veil/ui/veil-console.html b/wifi-veil/ui/veil-console.html new file mode 100644 index 00000000..75235dc5 --- /dev/null +++ b/wifi-veil/ui/veil-console.html @@ -0,0 +1,980 @@ +WiFi Veil Console — WiFi-Sensing Privacy Shield + + + +
+
+
+ + + WiFi Veil Console + WiFi-sensing shield + +
+ + Monitoring + + +
+ +
+ +
+
+ +
+
+

Identity inference,
collapsed to chance.

+
4.7%re-id · shield on
+
+
+
+ + + +
+
+ exposed + shielded +
+
+
+
+
+ + +
Live scorecard
+
+
Re-ID · off
100%
attacker unhindered
+
Re-ID · on
4.7%
chance 6.25%
+
Throughput
97.6%
of baseline link
+
Emission
1.000×
not jamming
+
+ + +
+

How this protects you

plain language
+
+
+ + The threat +

Your Wi-Fi constantly sends the router fine signal details — in the clear. A stranger nearby can capture them and recognise individual people by their radio "fingerprint": through walls, with no camera, and nothing on you.

+
+
+ + The shield +

WiFi Veil scrambles that fingerprint on every report with a secret twist only your own router can undo. An outside listener sees a different scramble each time and can't tie it to a person — their guess of "who's here" drops to pure chance.

+
+
+ + Kept honest +

It shapes only your own signal — it never jams, and your Wi-Fi speed stays ~98%. It stops outside snoops, not the router you connect to. Figures here are simulated (L0), pending real-hardware tests.

+
+
+
+ + +
+

Collapse curve

re-ID vs mixing
+
+
Givens passes →op: 96 · re-ID 4.7%
+
+ + +
+

Throughput optimum

vs feedback bits
+
+
Feedback resolution (bits) →5-bit · 97.6%
+
+ + +
+

Sensing activity

solicitations / s
+
+
threshold 5.0 Hz — shield auto-engages above0.0 Hz
+
+ + +
+

Shield controls

live model
+ +
+
Givens passes96min robust 48
+ +
+
+
Feedback resolution5bits · 802.11 {5,7,9}
+ +
+
+
Candidate identities16chance 6.25%
+ +
+
+
Link SNR20dB
+ +
+ +
+
+ Energy in +
= energy out · 1.000×
+ out +
+
+ + +
+

Attacker vs. protector

synthetic · L0
+
+
+ Passive re-ID — shield off— +
+
+
+ Passive re-ID — shield on— +
+
+
+ Link throughput retained— +
+
+
+
+
+ + +
+
Deployment presets · adaptive shield
+
+ + + + +
+
+ +
+ Prefer the terminal? The same instrument ships as veil — a dependency-free + TUI & scriptable harness inside the crate + (cargo run -p wifi-densepose-privshield --bin veil). Live-steer the + shield with on/off · passes · bits · preset · optimize, or run + veil doctor in CI. +
+ +
+ Compliant waveform controls only — never jamming. The shield rotates its own beamforming + feedback with keyed Givens rotations (energy-preserving), so a sniffer can't average out a stable + identity while the associated receiver, holding the key, decodes normally. All figures are + SYNTHETIC / evidence-level L0 from the reference model — not measured on hardware. +
+ ADR-288 · WiFi Veil + ADR-289 · harness + docs/research/privacy-shield +
+
+
+
+ + + + + + + + +