0038: Daemon clients verify the endpoint they connect to
- Status: accepted
- Date: 2026-10-08
- Amends: 0028 ("Local transport": the client side)
Context
ADR 0028 secures the daemon's side of the local transport: a 0600 socket
in a 0700 directory, a protected pipe DACL with first-instance
exclusivity, and the peer's OS credentials checked on every connection.
Nothing checked the other direction. The CLI (agentclient) and the
browser native host dialed whatever answered at the resolved endpoint
and sent it unlock passphrases and save passwords.
On Windows the default pipe name is predictable (ADR 0035), any user may
create a pipe of any unused name and choose its DACL, and first-instance
exclusivity only makes the real daemon fail to start. Another local user
could pre-create a user's pipe, let the user connect, and receive the
passphrase of the next vaultfold agent unlock. On unix the default
socket sits in the user's 0700 runtime directory, but a directory with
wrong permissions, a VAULTFOLD_AGENT_SOCK pointing at another user's
path, or a pre-created long-path fallback directory under /tmp gave
the same result. The windows-per-profile-endpoint design wrongly said a
client already refused a server of another user. The details are in the
OpenSpec change daemon-client-endpoint-check.
Decision
- Every daemon client verifies the endpoint once connected and before it
writes a byte: the CLI through
transport.Dial, the native host through its mirrorendpoint.Dial. A connection that fails is closed unused. Where nothing accepts the connection (a missing or stale socket, a missing pipe) the result is "no daemon" as before: there is nobody to refuse. - Unix, by
lstat: the socket's directory must be a directory, not a symlink, owned by the user, with no group or other permission bits, and the socket must be a socket (a symlink is refused), owned by the user, with no group or other permission bits. Then the listening process's uid from the kernel (SO_PEERCRED,LOCAL_PEERCRED) must be the user's. - Windows, on the connected handle: the pipe's owner
must be the user's SID or
BUILTIN\Administrators(the owner an elevated token gives what it creates), and the server process (GetNamedPipeServerProcessId) must run with the user's SID in its token. The owner is set by the kernel from the creator's token, so only a token holding SeRestorePrivilege (administrators, backup operators) can fake it; the process check refuses such a squatter too. - A check that cannot be made refuses the endpoint (fail closed).
- A refusal is
ErrUntrustedEndpoint. The CLI neither starts a daemon nor unlocks in-process; it exits 3 with the codeagent-untrustedand an error naming the endpoint, what was found, that nothing was sent, and what to do.doctorreportsendpoint-untrusted. The native host answers the extensionunavailablewith a message namingvaultfold doctor. - Nothing is added to
hello: anything a peer says about itself proves nothing that the OS-reported identity does not already prove better.
Consequences
- A squatted Windows pipe or a foreign unix socket receives nothing, and the user is told instead of silently falling back.
- An SSH-forwarded socket still works when it is forwarded into a
directory only the user can access: sshd creates the socket 0600 (its
default
StreamLocalBindMaskis 0177) as the user, and sshd is the server end. A remote path in a shared or group-readable directory (a 0755 home directory,/tmp) is refused; the README says to forward into a 0700 directory. - A user whose runtime directory has wrong permissions and holds a stale socket now gets an error with the fix instead of an in-process fallback.
- On Windows a daemon running elevated while the client is not may have a token the client cannot read; it is refused. Run the daemon and its clients at the same elevation.
- Administrators and same-user processes stay out of scope, as in the threat model.
Alternatives considered
- Only the socket file checks on unix. Rejected: they race with the connect; the kernel's peer uid identifies the process actually reached.
- Only the server process on Windows. Rejected as the sole check: the owner is the kernel-enforced fact, and checking both costs nothing.
- A DACL rule on the client, as doctor's check has. Rejected: once the server is the user's own process, the DACL is the user's business, and doctor already reports it.
- Fall back in-process on a refusal. Rejected: safe for the secret, but it hides that someone holds the user's endpoint.
- A challenge in
hello. Rejected: a same-user impostor could answer it and a foreign-user one is already refused by the OS identity.