WiFi Veil subproject
Overview
wifi-veil/ is a self-contained Rust workspace nested in the parent repository. wifi-veil/Cargo.toml deliberately declares its own empty [workspace], has no Rust dependencies, and builds a pure-compute wifi_veil library plus the native veil binary. The project models VEIL (Verifiable Emission-shaping for Identity-Leakage prevention): a compliant-waveform privacy shield that shapes a node's own WiFi beamforming feedback so a third-party passive sniffer loses stable identity features while a keyed receiver can invert the transform. The root wifi-veil/README.md and wifi-veil/…/lib.rs repeatedly mark all reference results as SYNTHETIC / L0; the crate does not drive radios, read OS entropy, or emit RF.
The Rust model is organized around a deterministic attacker-vs-protector loop:
- wifi-veil/…/identity.rs builds the synthetic beamforming-feedback samples. A
SceneConfigsplits each flattened report into a leading communication block and a fine identity-bearing block.Channel::newprecomputes deterministic per-identity signatures fromprng::derive_key, andChannel::observeadds session-specific beam and environmental nuisance without touching external state. - wifi-veil/…/protector.rs implements the shield.
ShieldConfig::default()is the shipped operating point: enabled, 96 Givens passes, 5 feedback bits, 2% sounding overhead,ObfMode::KeyedRotation, and no DP dither.Protector::protectclones aBfiSample, rotates only the fine block with a key-derived sequence of Givens rotations, optionally adds renormalized ε-DP dither, and leaves the communication block unchanged.Protector::recoverapplies the inverse schedule for the authorized receiver.SensingDetectoris only a rate-threshold decision rule used by control-plane stories. - wifi-veil/…/attacker.rs provides the passive adversaries: nearest-centroid with Euclidean or cosine metric, a reconstruction-style direction classifier, and an adaptive pooling/whitening classifier. wifi-veil/…/experiment.rs enrolls and tests these attackers on unprotected and protected captures, derives rotation keys per session or per packet according to
ObfMode, then returns anExperimentReportwith shield-off accuracy, shield-on accuracy, throughput, a compliance audit, and apassed()verdict. - wifi-veil/…/throughput.rs computes the protected-link ratio from quantization residual, feedback airtime, and sounding overhead. wifi-veil/…/compliance.rs audits one before/after protection pair by comparing report energy and hard-coding
adds_interfering_energy = false, which is the project's machine-checkable “not jamming” invariant. wifi-veil/…/proof.rs pinsProof::EXPECTED_WITNESSover quantized reference outputs so drift in the default experiment fails tests. - wifi-veil/…/optimize.rs derives the default shield instead of treating it as hand-picked. It searches the 802.11-allowed feedback bit set
{5,7,9}, pass candidates, attacker metrics, and identity counts, thenhyper_optimizereturns the spec-optimal 5-bit / 96-pass default with a 2× privacy margin.adaptive_shieldderives room-specific settings for a candidate identity count and current link SNR.
The native CLI in wifi-veil/…/veil.rs is the operator-facing model harness. It calls the same public APIs as the tests and exposes report, sweep, optimize, adaptive <N>, proof, doctor, and an ANSI TUI. It is std-only, honors NO_COLOR/CLICOLOR_FORCE, and falls back to a one-shot report when stdout is not a terminal. The TUI accepts local commands such as passes, bits, n, snr, metric, preset, optimize, and proof; all outputs remain synthetic model numbers.
The self-contained web UI in wifi-veil/…/veil-console.html is a single HTML file with inline CSS and JavaScript. It mirrors the Rust model at presentation level rather than importing crate code: REID16 stores piecewise-linear shield-on re-ID points, throughput(bits, snrDb) repeats the throughput formula, and mutable state S drives sliders, presets, a simulated sensing detector, a “Run experiment” animation, theme switching, onboarding modals, and a guided tour. wifi-veil/…/pages.yml publishes this file as GitHub Pages by copying it to _site/index.html and _site/veil-console.html; there is no frontend build step or network dependency.
wifi-veil/firmware/ is the hardware/firmware program. Its top-level README.md is explicit that only the portable C core is host-tested and every adapter is build-only SYNTHETIC / L0 until a captured hardware witness exists.
wifi-veil/firmware/core/veil_shield.{h,c}is the shared C99 implementation of the keyed Givens rotation. It exposesveil_rng_*,veil_shield_apply,veil_shield_recover, andveil_l2_norm, uses no malloc or libc I/O, and keeps its SplitMix64 schedule aligned with wifi-veil/…/prng.rs. wifi-veil/…/test_veil_shield.c checks deterministic PRNG behavior, energy conservation, scrambling, correct-key recovery, and wrong-key failure;wifi-veil/firmware/core/Makefileruns it withmake test.wifi-veil/firmware/openwifi/is the highest-capability path but still a scaffold. README.md explains that openwifi exposes an FPGA PHY/MAC but lacks native explicit beamforming, so the planned realization is a client-transparent per-packet unitary in newveil_rot/veil_unrotblocks. veil_openwifi.c serializes the same schedule into placeholder AXI-Lite registers with host shadow-MMIO support and an optionalVEIL_OPENWIFI_SELFTEST; HDL_NOTES.md specifies the missing RTL and register map; MEASUREMENT.md defines the P5 two-node measurement artifact required before anyMEASUREDclaim.wifi-veil/firmware/openwrt/is the Linuxmac80211/ OpenWRT adapter. veil_shieldd.c uses real libnl/nl80211 APIs for the controls that userspace can reach, especially TX antenna-map changes viaNL80211_CMD_SET_WIPHY, while marking the core keyed rotation and MU-MIMO group control as firmware/blob-blocked on commodity chipsets. The hostMakefilealways builds the C core and skips the daemon iflibnl-genl-3.0is missing;openwrt.mkis a package skeleton forlibnl-tiny; INTEGRATION.md maps each control to userspace, driver-patch, or firmware-patch effort.wifi-veil/firmware/nexmon/is a Broadcom/Cypress research skeleton. README.md grades reading compressed BF feedback as solved by external tools but transmitting shaped reports as fragile and D11/firmware-version-specific. patch/veil_patch.c contains a Nexmon-style hook with intentionally invalid placeholder address0xDEAD0000, unimplemented angle unpack/repack, and a stub key IOCTL; BUILD.md explains how a hardware operator would move the patch into a Nexmon tree without committing firmware blobs.wifi-veil/firmware/esp32/states that ESP32 cannot shield its own beamforming feedback because the Wi-Fi PHY/MAC path is closed. Its legitimate roles are supporting devices:veil_sensing_detector/observes CSI/frame cadence and raises a trigger through stub GPIO/MQTT/ESP-NOW backends, whileveil_ris_controller/uses the C core RNG to generate keyed bitmaps for a passive external RIS and stubs the GPIO/SPI writes. Theexamples/apps compile the component APIs in ESP-IDF but are documented as never flashed.
wifi-veil/harness/ is the npm MetaHarness development aid, not a VEIL runtime. harness/…/cli.js is plain ESM so guidance, --help, and --version work without building or installing TypeScript outputs; it dynamically imports @metaharness/* only for init, doctor, route, and flywheel. The guidance map is embedded in the CLI and emits source-cited JSON for topics such as overview, threat, countermeasure, compliance, optimization, and experiment. harness/…/router.ts wires a real @metaharness/router over seed illustrative embeddings, while harness/…/flywheel.ts wires the real flywheel API to a deterministic synthetic proposer/evaluator. harness/package.json runs tsc, vitest, and the CLI commands; the root CI only requires dependency-free guidance before installing harness dependencies.
The docs inside wifi-veil/docs/ are part of this subproject's evidence and design trail. docs/…/ADR-288-veil-privacy-shield-compliant-waveform.md describes the Rust reference model, optimizer, proof, and non-goals; ADR-289-wifi-densepose-privshield-harness-via-metaharness.md records the harness design, including older historical names; ADR-290-veil-e2e-hardware-implementation-program.md records the multi-provider firmware program. docs/research/privacy-shield/ contains the survey, threat model, compliance analysis, experiment protocol, optimization notes, and roadmap that the code and harness guidance cite. docs/assets/ holds the console screenshot/GIF used by the README.
CI and release discipline also live under wifi-veil/. wifi-veil/…/ci.yml has separate jobs for scripts/ci-guard.sh, Rust formatting/clippy/tests/WASM build, the firmware C core host test, and the harness smoke/tests. wifi-veil/…/ci-guard.sh scans only git-tracked files under the subproject for forbidden build artifacts, debug/slop markers, missing SYNTHETIC/“never jamming” labels, dishonest hardware-validation language, and stale crate identifiers in code/manifests. That script intentionally forbids tracking Cargo.lock because wifi-veil is maintained as a dependency-free leaf crate.
Coupling
- If wifi-veil/…/prng.rs changes
Rng,next_f32,derive_key, or SplitMix64 constants, also update and re-run wifi-veil/…/veil_shield.c, wifi-veil/…/test_veil_shield.c, wifi-veil/…/veil_openwifi.c, and wifi-veil/…/veil_ris_controller.c. The Rust protector, C core, openwifi coefficient serialization, and ESP32 RIS schedule all assume the same deterministic stream; drift means authorized receivers or hardware shims derive different rotations. - If
wifi-veil/src/protector.rs::ShieldConfig::default,session_rotation, orObfModesemantics change, verify wifi-veil/…/optimize.rs tests,wifi-veil/src/proof.rs::EXPECTED_WITNESS, wifi-veil/…/veil.rs presets/output, wifi-veil/…/veil-console.html constants, and firmware defaults such asVEIL_DEFAULT_PASSES,VEIL_OW_DEFAULT_PASSES, andVEIL_PASSES. These are not generated from a shared schema, so default pass/bit/keying drift silently makes the UI, CLI, firmware scaffolds, and proof describe different shields. - If the throughput formula or compliance tolerance changes in wifi-veil/…/throughput.rs or wifi-veil/…/compliance.rs, also update wifi-veil/…/veil-console.html, wifi-veil/…/cli.js guidance text, wifi-veil/README.md, and the research/ADR docs that cite the 97.6% throughput and energy-ratio claims. The UI and guidance repeat model numbers manually rather than importing the Rust crate.
- If the experiment pass criteria in wifi-veil/…/experiment.rs change, update
wifi-veil/src/bin/veil.rs::cmd_doctor, the UIshowVerdictthreshold in wifi-veil/…/veil-console.html, wifi-veil/…/proof.rs, and the README quick result table together. Otherwisecargo test,veil doctor, and the browser PASS badge can disagree. - If firmware paths are renamed or moved, adjust wifi-veil/…/ci-guard.sh and wifi-veil/…/ci.yml. The guard hard-codes provider README paths and the CI runs
make -C firmware/core test; moving files without those changes can either skip honesty checks or fail CI unrelated to code behavior. - If wifi-veil/…/veil_openwifi.c changes the placeholder AXI-Lite register offsets or coefficient packing, update wifi-veil/…/HDL_NOTES.md in the same change. The planned RTL contract is duplicated in prose and C comments; a mismatch would make future HDL self-loopback fail even if the host shadow self-test passes.
- If wifi-veil/…/cli.js guidance topics, source paths, or recommended commands change, update wifi-veil/…/guidance.test.ts and wifi-veil/…/README.md. The dependency-free guidance surface is intentionally the root CI smoke gate before
npm install. - If the repository is extracted or renamed from the parent, audit historical path/name strings in wifi-veil/…/ADR-288-veil-privacy-shield-compliant-waveform.md,
ADR-289,ADR-290, firmware comments, and wifi-veil/…/ci-guard.sh. Some docs preserve olderwifi-densepose-privshieldorfirmware/privshieldnames as historical context, while the guard forbids stale identifiers in code/manifests.
Risks
- wifi-veil/…/veil_patch.c is intentionally not buildable as real firmware: the branch patch address is
0xDEAD0000,VEIL_IOCTL_SET_KEYuses an invalid-looking placeholder token, and the compressed-BF angle unpack/repack functions are unimplemented. If a future change removes the honesty guards without resolving the reverse-engineering tasks, users could flash a broken Broadcom firmware patch or mistake a skeleton for a validated protector. - wifi-veil/…/veil_openwifi.c and wifi-veil/…/HDL_NOTES.md duplicate the future
veil_rotregister map and two-word coefficient packing before RTL exists. If either side changes alone, the first real FPGA block may accept keys but apply the wrong(i,j,cos,sin)schedule, causingveil_unrotnot to invert and breaking both throughput and compliance measurements. - wifi-veil/…/veil-console.html hard-codes
REID16and duplicates the throughput formula in JavaScript. If the Rust optimizer or model changes without updating the UI, the published Pages console can show stale re-ID/throughput outcomes while the crate tests and proof witness report different numbers. wifi-veil/src/proof.rs::EXPECTED_WITNESSis a single pinned constant over quantized default outputs. Any intentional model change requires updating the witness; an accidental update without reviewing wifi-veil/…/experiment.rs, wifi-veil/…/protector.rs, and wifi-veil/…/throughput.rs would mask semantic drift in the shipped claim.- wifi-veil/…/veil_shieldd.c includes real nl80211 calls for antenna masks but leaves the actual keyed rotation on a caller-supplied in-memory buffer because commodity OpenWRT does not expose the pre-precoder/feedback buffer. If deployment documentation treats
veil_shielddas a full protector, operators may believe the shield is on-air when only coarse controls or no-op stubs are active.