A CC0 research-alpha repository for privacy-preserving event intelligence. NeuroFHE Relay explores how sparse event processing and homomorphic encryption can work together: process sensitive signals locally, encrypt selected features, and evaluate them without exposing their plaintext values to the compute service.
The repository includes a runnable JavaScript scaffold, native OpenFHE and TFHE-rs
comparison lanes, reproducible evidence artifacts, and an FPGA relay reference design.
Research alpha: the software and hardware require further integration and
validation before deployment. productionClaim: false and
releaseGateSatisfied: false remain the current evidence posture.
Documentation · Evidence dashboard · Hardware reference design · Roadmap
| Your goal | Start here |
|---|---|
| Curious — understand the project without a technical background | Plain-English quickstart |
| Reviewing — assess the architecture, evidence, or research scope | Reviewer quickstart |
| Building — run the scaffold or contribute | Developer quickstart |
For a visual introduction, open the browser briefing locally. The demo walkthrough explains the output in plain English.
Use Node.js 22 for parity with CI; Node.js 20 or newer is supported. The portable JavaScript harness has no npm dependencies.
git clone https://github.com/AlexanderDaly/neurofhe-relay.git
cd neurofhe-relay
npm run demo
npm run gateway:demo
npm run ciThe first demo runs an educational sparse scorer using toy additive encryption. The gateway demo exercises event validation, export policy, and local recommendation handling. Neither requires native FHE libraries or a connected device.
| Task | Command |
|---|---|
| Run tests, metadata checks, documentation checks, and the hygiene scan | npm run ci |
| Check whitespace before committing | git diff --check |
| Publish a synthetic benchmark to a local output directory | npm run benchmark:artifact -- --out tmp/benchmark-artifacts |
| Inspect native library availability and evidence | npm run native:doctor |
| Generate a release-evidence dashboard artifact | npm run release:evidence -- --artifact |
See the command reference for artifact options and native workflows, and troubleshooting for setup failures. Generating a dashboard does not satisfy the release gate.
The design separates local signal processing from encrypted evaluation. Sparse representations reduce the input to selected scoring workloads; native homomorphic-encryption libraries provide the encrypted compute paths.
flowchart LR
subgraph Local[Local trust boundary]
A[Raw signals] --> B[Spatial spike sorter]
B --> C[Relay gateway: validate and apply policy]
C --> D[Encrypt selected features]
G[Decrypt result and validate recommendation] --> H[Permitted local action]
end
D --> E[External encrypted evaluation]
E --> G
The local gateway controls which representations may leave the device. Raw
payloads stay local by design; approved exports can include encrypted features,
aggregated metadata, or explicitly permitted plaintext fields. Encryption alone
does not hide all metadata, so artifacts record the applicable privacyBoundary
and cryptoInventory.
The runnable research-alpha scaffold demonstrates:
- Event encoding:
rawNeuralFrame -> spatialSpikeSorter -> eventWindow, with integer operations suitable for an FPGA or edge implementation. - Gateway policy: validation of raw and pre-sorted inputs, provenance, sanitization, and explicit plaintext, encrypted, aggregated, or withheld fields.
- Sparse scoring: a fixed linear model,
scores = W x + bias, with comparable dense, unsorted-spike, and spatial-sorted representations. - Recommendation handling: validation of permitted local reversible actions, rejection of raw device commands, and sanitized audit records.
See the architecture decisions and prototype map for implementation details.
The project distinguishes portable demonstrations, native-library measurements, and hardware design verification. Each supports a different level of evidence.
| Status Item | Current Posture | Confirm In |
|---|---|---|
| Research-alpha release target | v0.1.0-research-alpha; release readiness remains gated. |
Release requirements, roadmap |
| Portable validation | Locally recorded with 143 passing tests; verify hosted checks on the current commit. | Validation record |
| Merge state | Check the relevant PR; merges are governed by repository ruleset/admin policy as well as validation results. | Operations runbook |
| Release gate | releaseGateSatisfied: false; the evidence dashboard is not release approval. |
Release evidence, gate matrix |
| Claim boundary | productionClaim: false; preserve the documented privacy and cryptographic boundaries. |
Evidence guide |
Committed artifacts cover derived UCI EEG Eye State plaintext baselines, sampled public N-MNIST plaintext baselines, synthetic reconstruction-risk probes, metadata-padding comparisons, and native OpenFHE and TFHE-rs runs or structured blocker reports. Native results are specific to their recorded inputs, parameters, and host environments.
Use the evidence dashboard for a summary, the artifact index for source records, and the claim-evidence ledger to assess what each result supports. These artifacts do not establish production security, clinical validity, or general performance guarantees.
The ENER reference design connects an existing acquisition device to a Raspberry Pi host and an iCE40UP5K FPGA mezzanine. It includes 16 patent architecture figures, eight circuit sheets, a 55-component bill of materials, and the FPGA encoder implementation.
Simulation and routed timing pass at the 16 MHz target. The board has not been assembled; native KiCad ERC, physical electrical testing, and headset-specific integration remain outstanding. The package contains no PCB layout or Gerbers.
Download the complete design package
| Path | Purpose |
|---|---|
| docs/ | Architecture, quickstarts, research status, and operational guidance. |
| prototype/ | Portable scaffold code, test suite, artifact publishers, and native lane adapters. |
| benchmark-artifacts/ | Derived measurements, provenance, blocker reports, and evidence dashboards. |
| patent/ | ENER drafting materials, architecture drawings, and reference-design sources. |
| output/ | Reference-design PDFs and the editable handoff archive. |
| .github/ | CI workflows, contribution templates, and dependency-update configuration. |
| Root policy files | Contribution, security, maintenance, release, and CC0/public-domain guidance. |
See the package manifest for the detailed inventory.
| Role | Primary reference | Supporting guidance |
|---|---|---|
| New reviewer | Reviewer quickstart | FAQ, changelog |
| Contributor | Contributing | Developer quickstart, command reference |
| Maintainer | Maintainer responsibilities | Review checklist, operations runbook |
| Evidence reviewer | Evidence guide | Claim-evidence ledger, release gates |
The JavaScript scaffold is a portable contract harness for demos, schema checks, artifact generation, and orchestration. Its toy arithmetic is educational and cannot substitute for native FHE measurements. Performance-sensitive execution belongs in native libraries, systems code, or hardware implementations; see the native performance track.
Post-quantum transport, identity, and artifact integrity are design directions, not implemented security guarantees. Cryptographic agility requires explicit library choices, parameters, implementation review, and side-channel analysis.
Contributions to reproducibility, documentation, native adapters, and validation
are welcome. Follow CONTRIBUTING.md, run npm run ci and
git diff --check, and describe the evidence and limitations of your change.
Keep raw datasets and sensitive payloads outside git; commit derived artifacts
with provenance or structured blocker reports.
Use Support for questions and issue routing, and the security policy to report sensitive findings.
Released under CC0 1.0 Universal. The reference material is intended to be freely studied, copied, modified, and shared. See the public-domain notice for details.