ruvnet--RuView/docs/adr/ADR-288-veil-privacy-shield-compliant-waveform.md

# 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 <N>`, `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
```