# Enigma Witness Vault Software Integration

This guide describes the intended software stack for the Raspberry Pi Zero 2 W Witness Vault. It is build-ready for appliance bring-up while staying honest about the security boundary: the device can improve local custody, witness evidence, and operator-visible state; it cannot prove provider deletion, model forgetting, truth of memories, tamper-proof storage, or complete side-channel absence.

## Target stack

- Hardware: Raspberry Pi Zero 2 W, ATECC608A I2C sidecar, SSD1306 OLED, optional PN532 NFC.
- OS: Raspberry Pi OS Lite, 64-bit preferred where available for Pi Zero 2 W.
- Runtime: Node.js >= 24.
- Requirement shorthand: Node >=24.
- Enigma repository/app: installed from the project source or release package used by the deployment.
- Service style: local-first daemon with optional SSH/MCP bridge, optional relay/gateway clients, and explicit no-network mode.

Use a high-endurance microSD card and keep a known-good recovery image. For field units, record the OS image date, Enigma version, Node version, hardware options, and network mode.

## Pi OS bring-up

Recommended first-boot posture:

1. Flash Raspberry Pi OS Lite to the microSD card.
2. Create a non-default admin user.
3. Enable SSH only for service paths that require it.
4. Configure the selected network mode: Wi-Fi, USB gadget Ethernet, relay/gateway, or no-network.
5. Boot with the lid open for first hardware validation.
6. Confirm the I2C bus is enabled before expecting OLED or ATECC detection.
7. Install Node.js >= 24 using the project-approved package source for the deployment.
8. Install Enigma from the checked-out source tree or release artifact.
9. Configure the Enigma data directory on local storage with restrictive permissions.

Windows host note: if preparing the card from Windows, use Raspberry Pi Imager or an equivalent imaging tool, then use the Pi's first boot customization for username, SSH key, locale, and Wi-Fi only if Wi-Fi mode is intended. For no-network demos, do not pre-load Wi-Fi credentials.

## Bring-up command skeleton

Adapt these commands to the chosen image, package source, and username. They are operator instructions for the Pi, not verification commands run by this document.

```sh
# Run on the Pi after first boot.
sudo raspi-config nonint do_i2c 0
id -u enigma >/dev/null 2>&1 || sudo useradd --system --home /var/lib/enigma --shell /usr/sbin/nologin enigma
sudo install -d -o root -g root -m 0755 /opt/enigma /etc/enigma
sudo install -d -o enigma -g enigma -m 0750 /var/lib/enigma /var/log/enigma

# Install Node.js >= 24 from the deployment-approved source, then install Enigma.
node --version
sudo npm install -g enigma-memory

# Confirm the expected Enigma entry points are available.
command -v enigma
command -v enigma-mcp
command -v enigma-relay
command -v enigma-gateway
```

If deploying from a checked-out source tree instead of the package, keep the tree in `/opt/enigma` and point service `ExecStart` lines at the repository binaries:

```sh
/opt/enigma/apps/cli/bin/enigma.mjs
/opt/enigma/packages/mcp-server/bin/enigma-mcp.mjs
/opt/enigma/apps/relay/src/server.mjs
/opt/enigma/apps/gateway/src/server.mjs
```

Windows host note: use PowerShell or Windows Terminal for SSH sessions. Keep paths and keys outside synced consumer folders when handling vault exports, and do not drag raw appliance data into screenshots or chat tools during demos.


## Enigma install layout

Suggested appliance layout:

| Path | Purpose |
|---|---|
| `/opt/enigma` | Enigma application checkout or release files. |
| `/var/lib/enigma` | Vault state, receipts, local indexes, and device state. |
| `/etc/enigma` | Appliance configuration. |
| `/var/log/enigma` | Service logs, with rotation. |
| `/run/enigma` | Runtime sockets and transient status. |

Keep secrets and device keys out of exported demo bundles. If using the ATECC608A for signing, the private key material should remain device-bound according to the provisioning model; exports should carry public verification material and receipts, not raw secrets.

## Service architecture

The appliance should run as small cooperating services rather than a single opaque process:

| Service | Responsibility | Network requirement |
|---|---|---|
| `enigma-vault` | Local vault API, receipt creation, import/export policy checks. | None for local-only operation. |
| `enigma-mcp-bridge` | MCP stdio bridge over SSH or local command execution. | SSH or local stdio path only. |
| `enigma-witness` | Witness packaging, local signing hooks, optional relay submission. | Optional; disabled in no-network mode. |
| `enigma-statusd` | OLED/status/button daemon. | None. |
| `enigma-hwcheck` | Startup hardware inventory: I2C devices, sidecar presence, display presence. | None. |

Recommended behavior:

- Services fail closed for exports that require unavailable signing or policy checks.
- Network-dependent services are explicit and separately disable-able.
- Logs should identify missing optional hardware without treating it as fatal.
- Hardware inventory should distinguish `not installed`, `not detected`, and `detected but not provisioned`.

MCP over stdio is best treated as an on-demand SSH command, not a background daemon. A minimal forced-command key entry uses a real public key line like this after replacing the example key with the operator key created for the appliance:

```text
command="cd /var/lib/enigma && ENIGMA_CONFIG=/etc/enigma/witness-vault.env ENIGMA_DATA_DIR=/var/lib/enigma /usr/bin/env enigma-mcp",no-agent-forwarding,no-X11-forwarding,no-pty ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILocallyGeneratedOperatorKeyExampleReplaceBeforeUse operator-mcp
```

Relay and gateway are separate, deliberate services. Package installs expose `enigma-relay`, `enigma-gateway`, and the equivalent CLI subcommands `enigma relay serve` and `enigma gateway serve`; enable only the mode the appliance is meant to run. In a local/MCP appliance posture, keep relay and gateway stopped:

```sh
sudo systemctl disable --now enigma-relay.service enigma-gateway.service
```

If a deployment installs relay or gateway unit files, their `ExecStart` should use the real package entry points and a dedicated environment file:

```ini
# /etc/systemd/system/enigma-relay.service
[Service]
User=enigma
Group=enigma
EnvironmentFile=/etc/enigma/witness-vault.env
WorkingDirectory=/var/lib/enigma
ExecStart=/usr/bin/env enigma-relay
Restart=on-failure
NoNewPrivileges=true
PrivateTmp=true
```

Use the same pattern for `enigma-gateway` only when gateway mode is explicitly configured. The current package provides CLI, MCP, relay, and gateway entry points. If a deployment adds a resident `enigma-vault` daemon, keep it as a local-only unit and do not start relay or gateway services from that base vault unit.


## USB gadget Ethernet

USB gadget Ethernet is useful for demos and service because it gives a direct host-to-Pi link without Wi-Fi.

Expected flow:

1. Configure the Pi Zero 2 W USB OTG port for Ethernet gadget mode.
2. Assign a stable link-local or private static IP on the Pi gadget interface.
3. Connect the Pi USB data/OTG port to the host with a data-capable cable.
4. SSH from the host to the Pi over the USB Ethernet interface.
5. Run Enigma CLI/MCP operations over that SSH channel.

Windows host notes:

- Use the Pi USB data port, not the power-only port.
- Windows may show a new USB Ethernet/RNDIS-style adapter.
- If automatic addressing fails, configure static IPv4 addresses on both sides, for example host `10.77.0.1/24` and Pi `10.77.0.2/24`.
- Treat USB gadget Ethernet as a local wired network. It is not the same thing as no-network mode unless all other network interfaces are disabled and the demo claim is scoped to the chosen cable link.

Typical SSH target examples:

```powershell
# Windows host, with a static USB gadget address.
ssh enigma@10.77.0.2

# Run the MCP bridge as the remote command when the host client supports stdio over SSH.
ssh enigma@10.77.0.2 enigma-mcp --transport stdio --profile witness-vault
```

If the Windows adapter appears but SSH fails, check the host firewall profile for the USB Ethernet adapter and confirm the Pi and host addresses are in the same subnet.

## MCP over SSH/stdio bridge

The recommended control path is MCP over a narrow SSH/stdio bridge:

1. The operator connects to the Pi over SSH using a key, preferably through USB gadget Ethernet for demos.
2. The SSH command starts a constrained Enigma MCP bridge process on the Pi.
3. The bridge speaks MCP over stdio to the host-side client.
4. The bridge accesses local vault APIs and hardware signing/status services through local sockets or local process calls.
5. The bridge exits when the SSH session closes.

This keeps the appliance from needing to expose a broad HTTP API on the network for normal operation. If a network API is enabled for gateway mode, it should be a deliberate configuration change with clear status indication.

Operational guardrails:

- Use SSH keys, not passwords, for normal operation.
- Restrict the bridge command where possible.
- Keep host-side logs redacted.
- Make export commands explicit and operator-visible.
- In no-network mode, do not silently fall back to relay or gateway submission.

## OLED/status daemon roadmap

The OLED is an operator-awareness surface, not a security proof. It should make state legible at a glance.

Minimum useful pages:

| Page | Example fields |
|---|---|
| Boot | Device ID short hash, Enigma version, hardware inventory. |
| Network | `NO-NET`, `USB-LINK`, `WIFI`, `RELAY`, or `GATEWAY`; current IP when applicable. |
| Vault | Locked/unlocked state, last receipt short hash, pending export count. |
| Sidecar | ATECC present/provisioned/signing status. |
| Warning | Redacted export required, network disabled, sidecar unavailable, or clock unset. |

Button behavior if buttons are installed:

- Action/confirm cycles or confirms a local prompt.
- Back/cancel returns to the main status page.
- Service button held at boot requests local service/no-network posture.

Roadmap expectations:

- `enigma-statusd` should read status from local sockets/files, not scrape logs.
- Display updates should be rate-limited to avoid flicker.
- Missing OLED should not stop vault service startup.
- The daemon should never display raw secrets, tokens, private keys, or unredacted memory contents.

## ATECC608A sidecar semantics

The ATECC608A sidecar is used for device-bound key custody and signing support. In the Witness Vault story, it can help show that a receipt or witness record was produced by the enrolled appliance key.

What it can support:

- Device identity key generation or storage, depending on provisioning.
- Signing local receipts or attestations.
- Binding an export or witness packet to a physical appliance identity.
- Detecting that the expected sidecar is absent or unprovisioned.

What it does not prove:

- It does not prove provider deletion.
- It does not prove a model forgot information.
- It does not prove memories are true.
- It does not make storage tamper-proof.
- It does not eliminate side channels.
- It does not replace clear export policy and operator review.

Provisioning should be recorded without exposing private key material. Public keys, certificate chains if used, slot policy summaries, and device identifiers can be exported for verification. Private slots and secrets must not be included in redacted exports.

## Redacted export warning

Exports from the appliance must be designed as redacted evidence packages, not raw vault dumps.

Before allowing an export, the software should require an explicit profile:

| Export profile | Contents | Excludes |
|---|---|---|
| Public demo | Synthetic or user-approved sample records, public verification material, selected receipts. | Secrets, raw private memories, tokens, private keys. |
| Operator audit | Policy decisions, receipt hashes, device public identity, hardware inventory. | Raw secret values unless explicitly approved. |
| Support bundle | Version, logs with redaction, hardware presence, configuration summary. | Vault contents, credentials, key material. |

Warnings should be visible in CLI output and, when available, on the OLED. Do not name an export `proof of deletion` or `proof of forgetting`; use narrower names such as `witness receipt`, `custody receipt`, or `redacted audit bundle`.

## Relay and gateway modes

Relay/gateway modes are optional networked modes for integration beyond the local appliance.

Relay mode:

- The appliance packages local witness records and submits them to a configured relay.
- Relay submission should be queued and retryable only when relay mode is enabled.
- Queue contents should be inspectable and clearable by the operator.
- No-network mode must disable relay submission and background retries.

Gateway mode:

- The appliance exposes or connects to a controlled gateway path for enterprise or demo integration.
- Gateway mode should be visibly indicated on OLED/status output.
- Gateway APIs must not be enabled accidentally by installing the base image.
- Gateway responses should preserve redaction boundaries.

For both modes, network claims must be precise. A successful relay or gateway receipt proves a configured communication path handled a record; it does not prove anything about external provider deletion or model behavior.

## No-network mode

No-network mode is a first-class operating mode for local demonstrations and high-custody workflows.

Expected behavior:

- Wi-Fi disabled.
- BLE disabled where practical.
- Relay and gateway services disabled.
- No background update checks.
- No telemetry.
- MCP available only through local stdio, direct console, or explicitly allowed USB gadget Ethernet if the demo defines that cable link as local service access.
- OLED/status clearly shows `NO-NET` or the exact local service link state.

No-network mode should be configured, not merely claimed. Record the settings used for the demo or deployment. If USB gadget Ethernet remains enabled, state that the unit has a local wired host link; do not claim complete physical isolation.

## First appliance smoke checklist

Use this after assembly and software install:

1. Boot with the enclosure open.
2. Confirm the configured service path works: local console, SSH over USB gadget Ethernet, Wi-Fi, relay, or gateway.
3. Confirm Enigma starts and uses the intended data directory.
4. Confirm ATECC presence is reported separately from provisioning state.
5. Confirm OLED status page does not show secrets.
6. Confirm optional buttons change only local UI/service state.
7. Confirm optional PN532 is detected only if installed and enabled.
8. Confirm redacted export mode excludes private key material and raw secrets.
9. Confirm no-network mode disables relay/gateway behavior and reports that state to the operator.
10. Close the enclosure and repeat the status/service-path check.

Do not ship or demo the unit with default passwords, unreviewed exports, or ambiguous network claims.