wifi-ruview/docs/adr/ADR-118-bfld-beamforming-feedback-layer-for-detection.md

ADR-118: BFLD — Beamforming Feedback Layer for Detection

Field	Value
Status	Proposed
Date	2026-05-24
Deciders	ruv
Codename	BFLD — Beamforming Feedback Layer for Detection
Relates to	ADR-024 (AETHER), ADR-027 (MERIDIAN), ADR-028 (witness), ADR-029 (multistatic), ADR-030 (field model), ADR-031 (sensing-first), ADR-032 (mesh security), ADR-095 (rvCSI), ADR-115 (HA), ADR-116 (Matter), ADR-117 (pip)
Sub-ADRs	ADR-119 (frame), ADR-120 (privacy), ADR-121 (risk), ADR-122 (RuView), ADR-123 (capture)
Research bundle	docs/research/BFLD/ (11 files, 13,544 words)
Companion research	docs/research/soul/ — Soul Signature multi-modal biometric. BFLD is the policy-enforcement and compliance layer for Soul Signature; the two share the AETHER encoder (ADR-024), the witness chain (ADR-110/028), the RVF container, and cross_room.rs (ADR-030).
Tracking issue	TBD

---

1. Context

1.1 The plaintext BFI problem

IEEE 802.11ac and 802.11ax beamforming feedback (BFI) is exchanged between client stations (STA) and access points (AP) in unencrypted management-plane frames. The STA compresses the channel response into a Givens-rotation angle matrix (Φ/ψ) and transmits it as a VHT/HE Compressed Beamforming Report (CBFR). Any device in WiFi monitor mode within range can passively sniff these frames without joining the network.

Two independent 2024–2025 research results establish the severity of this exposure:

1. BFId (KIT, ACM CCS 2025) — re-identifies 197 individuals from BFI alone with >90% accuracy from 5 s of capture. https://publikationen.bibliothek.kit.edu/1000185756
2. LeakyBeam (NDSS 2025) — detects occupancy through walls at 20 m with 82.7% TPR / 96.7% TNR using only plaintext BFI. https://www.ndss-symposium.org/wp-content/uploads/2025-5-paper.pdf

Capture tooling is freely available: Wi-BFI (pip-installable), PicoScenes, Nexmon BFI patches for BCM43455c0 (Raspberry Pi 5 / 4 / 3B+).

1.2 Gap in the existing RuView pipeline

The wifi-densepose / RuView pipeline processes CSI via the rvCSI runtime (ADR-095/096) and emits presence, pose, vitals, and zone-activity events. No layer in the existing pipeline measures whether the data it is processing is capable of identifying individuals. All CSI is treated as equivalent from a privacy standpoint regardless of operating regime.

This gap becomes a compliance and liability issue at deployment scale. An operator placing RuView in a care home, hotel, shared office, or rental property has no instrument to verify that the system is operating anonymously.

1.3 BFI as a sensing signal

BFI is not only a threat vector — its compressed angle matrices carry multipath geometry useful for presence and motion detection, particularly in single-AP deployments where MIMO CSI is unavailable. BFLD treats BFI as an optional input alongside CSI, not a replacement.

1.4 Relationship to the Soul Signature research

The Soul Signature research (docs/research/soul/) defines a 7-channel multi-modal biometric for consent-based passive re-identification of enrolled individuals. Where Soul Signature intentionally produces identity (with a 60-second enrollment protocol), BFLD measures and gates identity leakage from the same sensing substrate. The two systems are complementary by design:

Concern	Soul Signature	BFLD
Intent	Create a biometric for enrolled persons	Measure and gate identity leakage
Consent model	Explicit enrollment, GDPR/HIPAA modes	Default-deny, all unenrolled persons
Operating class	Must run at privacy_class = 1 (derived)	Defaults to class 2 (anonymous)
Shared assets	AETHER encoder (ADR-024), WitnessChain (ADR-110/028), RVF container, cross_room.rs (ADR-030)	Same
ID space	Long-lived opaque person_id per enrolled subject	Rotating rf_signature_hash per day per unenrolled person

BFLD becomes Soul Signature's enforcement layer: the identity_risk_score gates whether a zone is leaky enough to enroll, the witness bundle is the regulator-facing audit artifact, and the structural privacy invariants (I1/I2/I3) ensure unenrolled bystanders stay anonymous even in zones where Soul Signature is actively matching enrolled persons. See ADR-120 §2.7 and ADR-121 §2.7 for the integration points.

1.5 What this ADR is not

• Not a removal of the CSI pipeline. ADR-095/096 rvCSI stays authoritative for CSI.
• Not a port of any external sniffer into the repo. The Nexmon capture path lives in a separate adapter (see ADR-123).
• Not a Matter SDK ship — Matter exposure is filtered through the ADR-116 cog-ha-matter boundary.

---

2. Decision

Create a new Rust crate wifi-densepose-bfld in v2/crates/ that:

1. Ingests BFI angle matrices (Φ/ψ) from CBFR frames, optionally fused with CSI.
2. Computes nine named features and an identity_risk_score (separability × temporal_stability × cross_perspective_consistency × sample_confidence).
3. Gates all output through a privacy_class byte that structurally prevents identity-correlated data from being published at classes 2 (anonymous) and 3 (restricted).
4. Emits BfldEvent JSON over MQTT under ruview/<node_id>/bfld/* with per-class topic routing.
5. Enforces three invariants structurally, not by policy:
   • I1: Raw BFI never exits the node.
   • I2: Identity embedding is in-RAM-only (no disk, no network).
   • I3: Cross-site identity correlation is cryptographically impossible via per-site keyed BLAKE3 hash rotation with a daily epoch.

The umbrella implementation is decomposed into five sub-ADRs:

Sub-ADR	Scope
ADR-119	BfldFrame wire format, magic 0xBF1D_0001, deterministic serialization, CRC32
ADR-120	privacy_class semantics, BLAKE3 hash rotation, default-deny field classification
ADR-121	Identity risk scoring formula, coherence gate, leakage estimator
ADR-122	RuView surface: HA entities, Matter cluster boundary, MQTT topic ACL
ADR-123	Capture path: Pi 5 / Nexmon adapter + ESP32-S3 BFI feasibility

2.1 Crate module layout

v2/crates/wifi-densepose-bfld/
├── Cargo.toml
└── src/
    ├── lib.rs
    ├── frame.rs             # BfldFrame (ADR-119)
    ├── extractor.rs         # CBFR parser → BfiCapture
    ├── features.rs          # 9 features
    ├── identity_risk.rs     # risk score (ADR-121)
    ├── privacy_gate.rs      # privacy_class enforcement (ADR-120)
    ├── hash_rotation.rs     # BLAKE3 per-site rotation (ADR-120)
    ├── emitter.rs           # BfldEvent → MQTT
    ├── mqtt.rs              # topic routing (ADR-122)
    └── ffi.rs               # PyO3 bindings (ADR-117 pattern)

2.2 Reuse map

BFLD module	Depends on
features.rs	wifi-densepose-signal/src/ruvsense/coherence.rs, multistatic.rs
identity_risk.rs	wifi-densepose-ruvector/src/viewpoint/attention.rs, coherence.rs
privacy_gate.rs	(new) — no upstream dependency
hash_rotation.rs	blake3 = "1.5" (keyed mode)
extractor.rs	vendor/rvcsi/crates/rvcsi-adapter-nexmon (ADR-095/096)

---

3. Consequences

Positive

• First explicit, auditable RF-layer privacy primitive in the wifi-densepose ecosystem.
• identity_risk_score doubles as an anomaly signal (sudden spike → new AP firmware / nearby attacker-grade sniffer / unusual propagation).
• BFI fusion augments presence/motion in single-AP deployments.
• Deterministic frame hashes extend the ADR-028 witness-bundle pattern to the new surface.
• Cross-site isolation is structural, not policy-dependent — a stronger guarantee than ACLs.

Negative

• ESP32-S3 cannot directly capture CBFR via the Espressif WiFi API. Full BFLD pipeline requires a Pi 5 / Nexmon host sniffer (cognitum-v0 available; see ADR-123).
• identity_risk_score calibration requires the KIT BFId dataset (non-commercial research agreement).
• Estimated effort: ~10.5 engineer-weeks across the six ADRs.

Neutral

• BFLD does not prevent passive BFI capture by an external attacker (LeakyBeam-class). It only ensures the node's own output is non-identifying. Operators must understand this distinction.
• Daily hash rotation prevents multi-day analytics correlating individual signatures across the day boundary. Acceptable for privacy goals; may surprise analytics use-cases.

---

4. Alternatives Considered

Alt 1: Skip BFI entirely (CSI-only)

Rejected because: (a) leaves the identity-leakage gap open for the CSI pipeline; (b) as BFI tooling becomes ubiquitous (Wi-BFI, PicoScenes), the absence of a privacy layer becomes more conspicuous for operators.

Alt 2: Publish identity_risk_score publicly by default

Rejected: the risk score itself is privacy-sensitive (reveals presence via timing correlation). Default is opt-in.

Alt 3: Cloud ML on raw BFI

Rejected: violates I1. Cloud training creates an off-node store of angle matrices reconstructible into identity profiles.

Alt 4: Differential privacy noise on BFI at ingress

Deferred to a follow-up ADR. DP sensitivity analysis and its interaction with identity_risk_score calibration are not yet complete. Current design achieves privacy through structural impossibility, not noise injection.

---

5. Acceptance Criteria

• AC1: Extractor parses BFI from 802.11ac and 802.11ax captures, 20/40/80/160 MHz, 2×2 through 4×4 MIMO.
• AC2: Presence detection latency ≤ 1 s p95 from first non-empty BFI frame.
• AC3: Motion score published at ≥ 1 Hz on ruview/<node_id>/bfld/motion/state.
• AC4: Raw BFI bytes never present in any serialized BfldFrame payload at any privacy_class value.
• AC5: With privacy_mode enabled, all identity-derived fields are absent from outbound events.
• AC6: Identical BfiCapture inputs produce bit-identical BfldFrame serialization (deterministic hash).
• AC7: Pipeline produces valid BfldEvent outputs without csi_matrix (BFI-only mode).

Per-sub-ADR acceptance criteria are defined in ADR-119 through ADR-123.

---

6. Phased Rollout

Phase	ADR	Scope	Effort
P1	119	Frame format + extractor stub	1.5 wk
P2	121	Features + identity_risk_score	2.0 wk
P3	120	Privacy gate + hash rotation	1.5 wk
P4	122 (a)	MQTT emitter + HA discovery	1.5 wk
P5	122 (b)	Matter cluster boundary in cog-ha-matter	1.5 wk
P6	123	Pi 5 / Nexmon capture adapter	2.5 wk
Total			10.5 wk

---

7. Related ADRs

See header table. Cross-references in body cite the structural reuse of:

• ADR-024 (AETHER embedding for identity_risk computation)
• ADR-027 (MERIDIAN's no-cross-site assumption is now structurally enforced by I3)
• ADR-028 (witness-bundle extends to BFLD surface)
• ADR-029/030 (multistatic.rs, cross_room.rs reused)
• ADR-095/096 (rvCSI Nexmon adapter for BFI capture)
• ADR-115 (HA surface extension)
• ADR-116 (cog-ha-matter boundary filter)
• ADR-117 (PyO3 bindings pattern)