keychain-auth wire protocol: JSON over local socket

keychain-auth uses newline-delimited JSON over a Unix socket or Windows Named Pipe. The connection itself is the authenticated session — no tokens required.

keychain-auth communicates over a local IPC channel using newline-delimited JSON. Every message is a single JSON object terminated by a newline (\n). There are no HTTP layers, no TLS handshakes, and no session tokens — your process’s kernel-verified identity is the credential.

Transport

The daemon listens on a platform-specific IPC endpoint:

Platform	Transport	Socket / Pipe path
macOS	Unix domain socket	~/Library/Application Support/keychain-auth/agent.sock
Linux	Unix domain socket	$XDG_RUNTIME_DIR/keychain-auth/agent.sock (fallback: ~/.cache/keychain-auth/agent.sock)
Windows	Named Pipe	\\.\pipe\keychain-auth

On macOS, the socket lives in ~/Library/Application Support/keychain-auth/. On Linux it uses $XDG_RUNTIME_DIR when set, otherwise ~/.cache/keychain-auth/.

Architecture

┌────────────────────────┐         Newline-Delimited JSON         ┌────────────────────────┐
│   Your Application     │ ◄─────────────────────────────────────► │     keychain-auth      │
│ (registered binary)    │    Unix socket / Windows Named Pipe    │    (Security Daemon)   │
└────────────────────────┘                                         └───────────┬────────────┘
                                                                               │
                                                                    Kernel verifies caller PID,
                                                                    binary path & SHA-256 hash
                                                                               │
                                                                               ▼
                                                                   ┌────────────────────────┐
                                                                   │   Native OS Keychain   │
                                                                   │ (macOS / Linux / Win)  │
                                                                   └────────────────────────┘

Connection-bound authentication

keychain-auth does not issue session tokens or API keys. The connection is the session. When you open a socket, the daemon immediately reads your process’s true PID directly from the kernel — it never trusts a self-reported value.

Once your PID is known, the daemon:

1. Resolves your binary’s path on disk.
2. Computes and verifies its SHA-256 hash against the approved config.json database.
3. Binds your binary’s fine-grained access policy to the active connection.

From that point on, every request you send on that connection is evaluated against your policy. The policy does not change mid-connection — it is bound at connect time.

If your application forks and exec’s a child process, that child inherits open file descriptors by default. Always open the socket with SOCK_CLOEXEC (Unix) or set the handle as non-inheritable (Windows) to prevent child processes from hijacking your authenticated session.

Connection lifecycle

A typical session follows this sequence:

1. Connect — open the socket or named pipe.
2. Kernel verification — the daemon reads your PID, resolves your binary, and verifies its hash. If your binary is unregistered, the daemon sends a final denied response and closes the connection immediately.
3. Policy binding — the daemon reads config.json and binds your allowed services and capabilities to the connection.
4. Request loop — send REQUEST messages and receive RESPONSE messages sequentially.
5. Disconnect — close the connection when done.

Message format

Every message — both requests and responses — is a single JSON object on one line, terminated by \n:

{"type":"REQUEST","action":"read","service":"aws","targets":["prod-api-key"]}\n

The daemon reads up to the newline, parses the JSON, and writes a single-line JSON response back before waiting for the next message.

Pipelining

Pipelining is sequential: send one request, receive one response, then send the next. The daemon processes requests one at a time per connection. You can reuse the same connection for as many requests as you need without reconnecting.

Use batch targets arrays to read, write, or delete multiple keys in a single round-trip rather than sending one request per key.