Skip to content

0020: In-process unlock until the daemon

  • Status: superseded by 0028
  • Date: 2026-09-25
  • Superseded: 2026-10-03, when add-agent-daemon made the CLI get its keys from the agent daemon. In-process unlock as described below is now only the fallback when no daemon can be used (auto-start off, VAULTFOLD_NO_AGENT=1 with no daemon running, no user runtime directory, or a failed start), plus init, adding a hosted vault and key rotate, which always unlock in-process. Two details below no longer hold even there: key new now creates an OS keychain identity where the daemon can use it, and in-process unlock can also open such an identity through the OS keychain (refused in an agent session). See 0028 and 0029.

Context

ADR 0011 makes the agent daemon the only long-lived holder of private key material, and the baseline agent-daemon spec ("The daemon is the only holder of key material") required every client, the CLI included, to send requests to the daemon instead of unlocking keys itself. The daemon is not part of the implement-cli-v1 change; it is proposed separately as add-agent-daemon. Read literally, the baseline would have left the first usable CLI unable to decrypt anything.

The baseline already allowed "the CLI acting in-process" for machine identities, so in-process unlock was not a new kind of key holder. What had to be preserved is the property the requirement protects: no long-lived key holder other than the daemon, and no key material written anywhere or shared between processes.

Decision

implement-cli-v1 modifies the requirement through its agent-daemon delta, openspec/changes/archive/2026-09-25-implement-cli-v1/specs/agent-daemon/spec.md (once that change is archived, the requirement lives in openspec/specs/agent-daemon/spec.md and the delta under openspec/changes/archive/). When no daemon is available, the CLI MAY unlock a device key in-process for the duration of a single command, and then:

  • The passphrase is read only from the controlling terminal (/dev/tty on POSIX, CONIN$/CONOUT$ on Windows, echo disabled) or from an inherited file descriptor named by VAULTFOLD_PASSPHRASE_FD, one line per prompt. Never from an argument or an environment value. With neither, the command exits 3 naming VAULTFOLD_PASSPHRASE_FD (design.md "Identities and unlock"; group 4 decisions 3 and 4).
  • A wrong or empty passphrase is retried on the same prompt up to three reads in total, then exit 3; a failing read stops at once. Every passphrase buffer is zeroed after use (group 4 decision 3).
  • Unlocked keys are cached per process only, keyed by the identity file path, so a command that opens several vaults with one identity (search, run with references to several vaults) prompts once, and concurrent opens in one process share one unlock (group 5 decisions 5 and 11).
  • The device key and every unwrapped KEK live only in memory and are zeroed before the process exits: session.CloseAll closes every vault and zeroes every cached key, and the first unlocking open installs a SIGINT/SIGTERM handler that runs it and exits with 128 plus the signal number (group 5 decision 5). Before run or inject starts a child, session.ReleaseSignals zeroes the keys and hands signal delivery to the child runner (group 10 decision 6, group 11 decision 4), so no key outlives resolution.
  • Nothing is cached across processes: no key agent, no unlocked-key file, no keychain entry. The encrypted local cache holds heads and sync times, never keys or plaintext (design.md "Local cache").
  • key new always creates a passphrase-protected key and says that OS keychain and hardware protection arrive in a later change.

Consequences

  • The CLI is usable end to end today, including run, inject, sync and member management, without waiting for the daemon.
  • Every command that decrypts prompts for the passphrase. This is the main usability cost of this decision and is listed under "Known limitations" in cmd/vaultfold/README.md. Automation passes the passphrase on a file descriptor with VAULTFOLD_PASSPHRASE_FD, which scripts/smoke.sh uses.
  • No Touch ID, Windows Hello or OS keychain unlock, no unlock TTL, idle or screen-lock locking, and no per-collection touch policy: all of these need a long-lived holder and belong to the daemon.
  • Zeroisation is best effort, as core/README.md "Zeroisation limitations" records: the Go garbage collector may copy bytes, memory is neither pinned nor excluded from swap, and a process killed with SIGKILL or dumped by the OS never runs the handler. A short-lived process bounds the exposure; it does not remove it.
  • The agent-session policy (ADR 0012) is enforced by the CLI itself through the nudge on value-returning commands, not by a separate process holding the keys, so it is a convention a determined agent could bypass by calling the binary differently. The daemon turns it into a control.
  • Follow-up: the add-agent-daemon change (proposed on branch openspec/add-agent-daemon) switches the CLI to the daemon whenever one is reachable, keeps in-process unlock only as the no-daemon fallback this delta allows, and adds keychain unlock, TTLs and machine identity mode (VAULTFOLD_IDENTITY, refused by this build).

Alternatives considered

  • Build the daemon first. Rejected: it is a large change of its own (transports, peer credentials, caller verification, keychain integration per OS), and doing it first would leave the vault format, git sync and the command surface unexercised by real workflows for that much longer.
  • Cache the unlocked key across commands (an unlocked-key file or a short-lived background process). Rejected: it recreates a daemon without the daemon's protections (peer checks, locking, audit), which is exactly what the requirement exists to prevent.
  • Accept the passphrase from an argument or an environment variable. Rejected: arguments are visible to other processes and shell history, and environment values leak to children and crash reports. The file-descriptor form gives automation the same reach without either. The hidden dev commands' VAULTFOLD_DEV_PASSPHRASE is dev-only (throwaway passphrases for make smoke) and is not wired into the real command surface.