0020: In-process unlock until the daemon
- Status: superseded by 0028
- Date: 2026-09-25
- Superseded: 2026-10-03, when
add-agent-daemonmade 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=1with no daemon running, no user runtime directory, or a failed start), plusinit, adding a hosted vault andkey rotate, which always unlock in-process. Two details below no longer hold even there:key newnow 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/ttyon POSIX,CONIN$/CONOUT$on Windows, echo disabled) or from an inherited file descriptor named byVAULTFOLD_PASSPHRASE_FD, one line per prompt. Never from an argument or an environment value. With neither, the command exits 3 namingVAULTFOLD_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,runwith 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.CloseAllcloses 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). Beforerunorinjectstarts a child,session.ReleaseSignalszeroes 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 newalways 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,syncand 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 withVAULTFOLD_PASSPHRASE_FD, whichscripts/smoke.shuses. - 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-daemonchange (proposed on branchopenspec/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
devcommands'VAULTFOLD_DEV_PASSPHRASEis dev-only (throwaway passphrases formake smoke) and is not wired into the real command surface.