keychain-auth approve: authorize a pending binary

Approve a queued unregistered binary by its SHA-256 hash, adding it to config.json with zero-trust defaults so you can then configure its service permissions.

The approve command moves a binary from the pending queue into your active config.json, granting it a recognized identity in the daemon. When an unregistered binary attempts to connect to the daemon, the connection is rejected and the binary’s details — path, SHA-256 hash, command-line arguments, and timestamp — are held in ~/.config/keychain-auth/pending.json for 24 hours. You can review this queue at any time and approve binaries you trust.

The pending approval workflow

When a binary that is not in config.json tries to query the daemon:

1. The daemon immediately denies the request with reason unregistered_binary_pending_approval.
2. The connection is closed.
3. The daemon writes the binary’s details to ~/.config/keychain-auth/pending.json with a 24-hour TTL.

The pending queue records the following for each attempt:

• Path of the binary on disk
• SHA-256 hash of the binary
• Exact command-line arguments used
• Timestamp of the attempt

Entries expire automatically after 24 hours. If an unregistered binary attempts to connect again before the entry expires, the existing record is updated.

Reviewing the pending queue

List all binaries currently waiting for authorization:

keychain-auth list-pending

Example output:

Found 1 pending binaries waiting for authorization:

Path:       /usr/local/bin/mytool
Hash:       sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Command:    mytool secrets fetch --env production
Attempted:  2026-05-21T12:34:56+00:00
------------------------------------------------------------

Approving a binary

Copy the hash from the list-pending output and pass it to approve:

keychain-auth approve <hash>

For example:

keychain-auth approve sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

The daemon looks up the hash in pending.json to find the binary’s path automatically. If the hash has already expired or was never queued, you can provide the path as an optional second argument:

keychain-auth approve <hash> /usr/local/bin/mytool

What approve writes to config.json

Approving a binary creates a zero-trust entry in config.json — the binary is recognized, but has no permissions:

{
  "path": "/usr/local/bin/mytool",
  "hash": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "registered_at": "2026-05-21T12:35:10Z",
  "allowed_read_services": [],
  "allowed_write_services": [],
  "can_search": false
}

After approving, the entry is removed from pending.json.

Approving a binary does not grant it any keychain access. You must still open ~/.config/keychain-auth/config.json and add the service namespaces you want it to read from or write to. See keychain-auth register for a full description of the permission fields.

Only approve binaries you recognize and trust. Inspect the Command and Path fields in the pending queue carefully before approving. A hash match confirms the binary has not been tampered with, but you should still verify the path corresponds to a tool you intentionally installed.