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/ (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).

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

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