Architecture

A wallet, its wardens, and the law

Three layers, one rule: the layer that holds secrets never talks to agents, and the layer that talks to agents never holds secrets.

┌─ Electron app (plain TypeScript) ─────────────┐
│  Approval · Vault · Request Logs · Policies   │  holds no secrets
└──────────────┬────────────────────────────────┘
               │ whitelisted IPC (main process)
┌──────────────▼────────────────────────────────┐
│  vaultd — the dumb vault                      │
│  AES-256-GCM store · OS-keychain master key   │
│  deterministic policy (the law) · grants/TTL  │
│  in-daemon secret injection · audit log       │
└──────┬───────────────────────────▲────────────┘
       │ MCP (stdio)               │ metadata only
┌──────▼──────────────┐   ┌────────┴────────────┐
│ Agents in any IDE   │   │ Meta LLM wardens    │
│ Cursor·Claude·Codex │   │ 3B → Glimmer → Spark│
└─────────────────────┘   └─────────────────────┘

Request flow

• Agent calls request_capability(alias, scope, reason) over MCP.
• Policy pre-check: unknown alias, rate limit, or a requested write above a read ceiling → denied before any model call.
• The warden (Meta LLM) scores metadata only and returns strict JSON: risk, recommended scope, approval need, one-line explanation.
• Policy clamps: the warden can narrow, never widen. Writes always require the human; standing approval covers only read-only low-risk repeats.
• Human approves in the app (daemon-token-guarded route — an agent approving itself gets 401).
• vaultd decrypts in-memory, injects the credential into that single connector call, returns only the tool result. Grant expires immediately (tripwire: after use, after TTL, or on revoke).

Invariants (tested, not promised)

• No secret value in any MCP response, HTTP response, log, audit row, UI payload, or model prompt — enforced by a canary test scanning 17 surfaces; the build fails on a hit.
• Plaintext exists only inside vaultd during one connector execution.
• The model can narrow scope, never widen it beyond policy ceilings.
• Grants are single-use and expiring; revoke is immediate and also interrupts in-flight work where the connector supports it.
• The daemon binds to localhost only. Human-decision routes require the daemon token; MCP exposes no approval tool.
• Secure with no warden on duty: model down, malformed, or fooled → policy + human decide. The floor never moves.

The warden (Meta LLMs)

Effect-TS services with tagged errors (MarshalUnavailable, GrantExpired, …) and Effect Schema at every boundary. The warden prompt treats all agent-supplied fields as untrusted data; output is schema-decoded, never hand-parsed. Levels: none → Llama 3.2 3B (local) → Muse Glimmer 30B (local) → Muse Spark / Wonder (Meta Model API). Stronger wardens detect attacks — writes phrased as reads, injection in the reason field, slow scope-creep — and can flag rogue agents mid-testing.

How this compares to a crypto wallet

Same skeleton: an encrypted vault, a human approval surface, keys that are used but never displayed. Different payload: a wallet signs one predictable transaction; OpenVault authorises arbitrary API behaviour, so approval needs context a signature prompt never had — who is asking, what scope, what history, what the warden thinks. That context is the product.

Measured evidence (2026-10-31, RTX 3070 8 GB)

• 146 tests passing; strict typecheck and lint clean.
• Brain eval, 17 labelled scenarios (benign, disguised writes, escalation, injection, bursts): fake brain safety 100%; live Llama 3.2 3B safety 100%, risk-label accuracy 23.5% — weak labels, unbroken floor.
• Live rehearsal: 7/7 checks in 3.6 s; warm marshal decision ~1.9 s; revoke denial ~10 ms.
• Two independent MCP hosts (VS Code + Claude Code configs) verified against one daemon.
• Windows NSIS installer built (115.6 MB, unsigned). Full log: docs/VERIFICATION.md in the repo.

Future

Air-gapped vault mode (no network path at all), secure-enclave and hardened-device deployments, a browser extension approval surface, and per-team policy packs. The architecture already isolates the vault from every network-facing surface except localhost — air-gapping is a packaging decision, not a redesign.