Skip to content

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 mirror endpoint.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 code agent-untrusted and an error naming the endpoint, what was found, that nothing was sent, and what to do. doctor reports endpoint-untrusted. The native host answers the extension unavailable with a message naming vaultfold 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 StreamLocalBindMask is 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.