0011: The agent daemon owns key material; transports and the relay
- Status: accepted
- Date: 2026-09-22
Context
Secrets must be usable on machines that do not hold the user's private key: remote dev boxes, devcontainers, CI runners with a human on call, and servers being restarted over SSH. The private key must never move and no component may expose a "decrypt anything" oracle.
Decision
- A long-running agent daemon on the trusted device holds unlocked identities (ADR 0009) for a session TTL. The CLI, TUI and GUI never touch key material; they ask the daemon. The daemon exposes a small, enumerated request API (see the agent-daemon spec): principally "unwrap the KEK for this collection and epoch" and "resolve this one reference", each scoped to a named session. No request returns private key material.
- Every request carries the entry path or collection scope, the requesting host, and the session, so approval prompts are meaningful. Approvals are once, or for a session with a TTL, and are scoped to a collection or path prefix. Requests are logged locally in an append-only audit file.
- Transports, in order of preference:
- Local Unix socket (mode 0600) or Windows named pipe. Default.
- SSH remote socket forwarding of the local socket. No accounts, no new network surface; the documented free path for remote work.
- Hosted relay. Both the daemon and the remote CLI connect outbound
over WebSocket to the relay. The two ends run a Noise handshake with
their own vaultfold device keys; the relay forwards opaque bytes and
learns only that a request happened, never its content. Pairing uses
the device-code pattern: the remote prints a
vaultfold://unlock/<request id>link and a short code; whichever device claims the request shows the same code, the host, the session and the requested scope, and the human confirms the code matches before approving. URLs carry only a request id, never key material, because custom URL schemes can be registered by any application. A typed-code fallback covers terminals that cannot open links. - Tailscale as bring-your-own-network: the daemon binds to the tailnet
interface only and identifies peers through the local
tailscaledLocalAPIwhois. No embeddedtsnetnode. - Public listeners: never.
- Replay protection (nonce and counter), channel binding to the approved request, and rate limiting apply on every transport.
- On the remote side, the session binding is per shell session: keyed by controlling tty for interactive use, by the MCP server instance and project for agent harnesses (ADR 0012), never stored in a shared home directory. Two people on one shared OS account therefore get two sessions routed to two devices.
- Unattended processes (daemons, CI) never use a forwarded human identity; they get machine identities (ADR 0008) scoped to what they need.
- Approvals may be answered from any of the member's devices, including a phone woken by a push notification from the hosted service.
Consequences
- A compromised remote machine can request anything the human would approve; scoped, short-lived, explicit approvals are the mitigation and must be the default.
- The relay is a hosted component with push credentials; it can be self hosted but the mobile approval path depends on APNs/FCM.
- The relay learns which device keys connect and when, never which vault, entry, scope or value (see threat-model.md).
Alternatives considered
- gpg-agent style key forwarding. Rejected: exposes a general signing and decryption oracle.
- Embedding Tailscale (
tsnet) in every client on a per-user tailnet. Rejected: requires operating a coordination server and relays, which is a larger trust and operations burden than a purpose-built relay. - Cloudflare quick tunnels (as nfi-tools does). Rejected: a public URL protected only by a token.