Introducing a new way to review your PRs.

Read the announcement

ruvnet / ruview

π RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.

View on GitHub

13 documents · Updated Nov 19, 2026

docs / wifi-veil-subproject

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 SceneConfig splits each flattened report into a leading communication block and a fine identity-bearing block. Channel::new precomputes deterministic per-identity signatures from prng::derive_key, and Channel::observe adds 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::protect clones a BfiSample, 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::recover applies the inverse schedule for the authorized receiver. SensingDetector is 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 an ExperimentReport with shield-off accuracy, shield-on accuracy, throughput, a compliance audit, and a passed() 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 pins Proof::EXPECTED_WITNESS over 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, then hyper_optimize returns the spec-optimal 5-bit / 96-pass default with a 2× privacy margin. adaptive_shield derives 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 exposes veil_rng_*, veil_shield_apply, veil_shield_recover, and veil_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/Makefile runs it with make 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 new veil_rot / veil_unrot blocks. veil_openwifi.c serializes the same schedule into placeholder AXI-Lite registers with host shadow-MMIO support and an optional VEIL_OPENWIFI_SELFTEST; HDL_NOTES.md specifies the missing RTL and register map; MEASUREMENT.md defines the P5 two-node measurement artifact required before any MEASURED claim.
  • wifi-veil/firmware/openwrt/ is the Linux mac80211 / OpenWRT adapter. veil_shieldd.c uses real libnl/nl80211 APIs for the controls that userspace can reach, especially TX antenna-map changes via NL80211_CMD_SET_WIPHY, while marking the core keyed rotation and MU-MIMO group control as firmware/blob-blocked on commodity chipsets. The host Makefile always builds the C core and skips the daemon if libnl-genl-3.0 is missing; openwrt.mk is a package skeleton for libnl-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 address 0xDEAD0000, 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, while veil_ris_controller/ uses the C core RNG to generate keyed bitmaps for a passive external RIS and stubs the GPIO/SPI writes. The examples/ 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

Risks

  • wifi-veil/…/veil_patch.c is intentionally not buildable as real firmware: the branch patch address is 0xDEAD0000, VEIL_IOCTL_SET_KEY uses 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_rot register 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, causing veil_unrot not to invert and breaking both throughput and compliance measurements.
  • wifi-veil/…/veil-console.html hard-codes REID16 and 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_WITNESS is 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_shieldd as a full protector, operators may believe the shield is on-air when only coarse controls or no-op stubs are active.