keychain-auth: Zero-Trust Keychain Access Control

keychain-auth is a security daemon that mediates keychain access using kernel-level process verification, cryptographic attestation, and per-binary policies.

keychain-auth is a local security daemon that sits between your CLI tools and your operating system’s keychain. Instead of allowing any process to silently read your secrets, keychain-auth verifies the cryptographic identity of every caller, enforces fine-grained access policies, and writes a structured audit log of every operation. It works across macOS Keychain, Linux Secret Service, and Windows Credential Manager without changing how your tools store or retrieve secrets.

Installation

Install the keychain-auth binary on macOS, Linux, or Windows and start the daemon.

Quickstart

Register your first binary, configure permissions, and send your first request in 5 minutes.

CLI reference

Full reference for the start, register, approve, and upgrade commands.

Protocol reference

Build a custom client using the JSON-over-socket wire protocol.

The problem keychain-auth solves

Native OS keychains have two significant security gaps for local development tools and CLI utilities.

No process sandboxing on Linux and Windows. Any script, package dependency, or process running under your user account can query D-Bus (org.freedesktop.secrets) on Linux or call CredRead on Windows to read every credential in your keychain — AWS keys, API tokens, database passwords — without your knowledge or any prompt.

Prompt fatigue on macOS. Command-line tools lack application bundle signatures, so macOS triggers a permission dialog on every new binary invocation. Users quickly learn to click “Always Allow,” which permanently grants every CLI tool unlimited keychain access.

How keychain-auth fixes both problems

keychain-auth replaces direct keychain access with a local broker. Your tools connect to the daemon over a Unix domain socket (or a Windows Named Pipe) and request specific secrets by service and target name. Before fulfilling any request, the daemon:

1. Retrieves the caller’s real process ID from the kernel — never from self-reported data.
2. Resolves the executable path and computes its SHA-256 hash.
3. Checks the hash against a user-managed registry of approved binaries.
4. Enforces the binary’s explicit read and write service namespaces.

A binary that is not registered is dropped with an unregistered_binary response and logged to a pending queue for review. A registered read-only binary cannot write or delete secrets, regardless of what it requests.

keychain-auth uses kernel-enforced peer credential APIs — SO_PEERCRED on Linux, LOCAL_PEERPID on macOS, and GetNamedPipeClientProcessId on Windows — to identify callers. It is not possible to spoof a registered binary’s identity over these channels.

Key capabilities

Kernel-level process verification. The daemon reads the caller’s PID directly from the OS kernel. Active processes are also protected from in-place binary tampering by the operating system (ETXTBSY), so long-lived connections remain secure throughout their lifetime.

Cryptographic attestation. Every registered binary is identified by its SHA-256 hash. When a binary is updated, you re-register it with keychain-auth upgrade to update the approved hash.

Zero-trust access control. Each registered binary declares exactly which service namespaces it may read from and write to. A binary with allowed_read_services: ["aws"] cannot touch any other service, and cannot write even to aws unless aws also appears in allowed_write_services.

Batch and prefix operations. Clients can read, write, delete, or search multiple secrets in a single round-trip. Prefix matching lets you retrieve or delete all secrets under a namespace hierarchy in one request, provided the binary has can_search: true.

Structured audit log. Every approved request, denied request, and search operation is written to a structured JSON log at ~/.local/share/keychain-auth/audit.log (Linux/Windows) or ~/Library/Logs/keychain-auth/audit.log (macOS). Search operations return target key names only — secret values only appear in explicit read entries, keeping the audit trail granular and useful.

Pending approval queue. Unregistered binaries are not silently dropped. The daemon logs their command-line arguments, hash, and timestamp to ~/.config/keychain-auth/pending.json for 24 hours. You can review and approve them with keychain-auth list-pending and keychain-auth approve <hash>.