feat(privshield): E2E hardware program — validated C core + multi-provider firmware scaffolds

Take VEIL from the synthetic Rust reference model toward real WiFi silicon
across multiple hardware providers, around one shared, host-validated core.
Answers the questions "can OpenWRT / open WiFi software implement this?" and
"can ESP32 help scramble signals?" with an honest per-platform feasibility map.

Portable C shield core (firmware/privshield/core/) — VALIDATED (host test):
- veil_shield.{h,c}: keyed Givens-rotation obfuscation of the identity-bearing
  "fine" subspace, C99, no malloc / no libc I/O, only <math.h>. SplitMix64 key
  schedule byte-identical to the Rust crate, so on-air behavior is consistent
  everywhere and every adapter links the same math.
- make test passes: energy conservation (orthogonal => "not jamming"),
  reversibility (recover inverts apply), wrong-key-fails, and PRNG stream parity
  with the Rust crate. This is build/host evidence, NOT silicon.

Per-provider adapters (all SYNTHETIC / L0, build-only, TODO(hw) markers):
- openwifi/  grade B (ceiling A, effort D): only open PHY/MAC (FPGA) that can
  host the full keyed rotation + inverse; needs new HDL + 2nd TX chain. Carries
  the P5 measurement protocol (MEASUREMENT.md) for the first MEASURED result.
- openwrt/   grade C: per-packet keyed unitary is blob-blocked on commodity APs;
  coarse compliant knobs (TX antenna map, sounding-cadence jitter) reachable
  from userspace/hostapd; ath9k is the one credible driver-patch route.
- nexmon/    grade C: reading the compressed-BF angles is solved (nexmon_csi /
  Wi-BFI); shaping the transmitted report is research-grade (D11 ucode-adjacent).
- esp32/     grade F (self) / B (supporting): cannot shape its own BF feedback
  (closed esp-phy-lib blob); legitimate as a sensing detector and external-RIS
  controller — the honest way ESP32 "helps scramble", via an external surface.

Docs:
- firmware/privshield/README.md: architecture, layout, and the feasibility matrix.
- ADR-290: the E2E hardware program, PROOF discipline, and per-provider decision;
  added to docs/adr/README.md index.

Compliant waveform controls only, never jamming. No adapter has run on silicon;
no MEASURED claim is made (that is roadmap P5, gated on a captured log).

Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01WEXNqzs7UsfNFBcP5yW21p

firmware/privshield/openwifi/MEASUREMENT.md

@@ -0,0 +1,103 @@
+# P5 measurement protocol — openwifi 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 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**: 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