keychain-auth error codes: causes and client handling

All reason codes in keychain-auth denied and error responses, what triggers each one, whether the connection closes, and how your client should respond.

When a request results in a "denied" or "error" status, the reason field carries a machine-readable code that tells you exactly what went wrong. Your client should handle each code explicitly rather than treating all non-success responses the same way.

unregistered_binary_pending_approval

Status: denied

What causes it: Your binary’s SHA-256 hash was not found in the daemon’s approved config.json database, or the hash was found but the binary path did not match. This happens the first time you run a new or updated binary without registering it first.

What the daemon does: It writes details about the connection attempt (binary path, hash, command-line arguments, timestamp) to ~/.config/keychain-auth/pending.json for manual review, sends this denial response, and immediately closes the socket connection. No further requests can be sent on this connection.

What your client should do:

1. Detect that the connection has been closed after receiving this response.

2. Surface a clear, actionable error message to your user, for example:

   keychain-auth: this binary is not registered.
   To approve it, run: keychain-auth approve <hash>
   To list pending binaries: keychain-auth list-pending
   

3. Do not retry automatically. The binary cannot proceed until a human explicitly approves it.

For tool authors: add keychain-auth register $(which your-tool) to your installation script so users are registered before they ever hit this error.

service_not_allowed

Status: denied

What causes it: Your binary attempted to read from or write to a service namespace that is not listed in its policy. For read and search operations, the service must be in allowed_read_services. For write and delete operations, the service must be in allowed_write_services.

What your client should do:

1. Do not retry the same request — it will be denied again.

2. Surface an error that names the service and the action, for example:

   Access denied: this binary is not allowed to read from service "aws".
   Contact your keychain-auth administrator to update the policy.
   

3. If you are the tool author, check that your registration includes the correct allowed_read_services and allowed_write_services entries.

action_not_in_policy

Status: denied

What causes it: Your binary attempted a search action, or a read or delete with "match": "prefix", but its policy does not have can_search: true. Prefix-based read and delete require search capability because the daemon must enumerate keys internally to resolve matches.

What your client should do:

1. Do not retry without a policy change.
2. If search is genuinely needed for your use case, ask the user or administrator to enable can_search: true for your binary in config.json.
3. If your code sent "match": "prefix" unintentionally, switch to "match": "exact" and provide full key names.

malformed_request

Status: error

What causes it: The daemon could not parse or validate your request. Common causes:

• Invalid JSON syntax (missing bracket, trailing comma, etc.)
• type is not "REQUEST"
• action is not one of "read", "write", "delete", "search"
• match is set to an unrecognized value
• action is "write" and targets.length does not equal values.length
• action is "write" and match is "prefix"
• targets is empty when required (all actions except search in exact mode require at least one target)

What your client should do:

1. Treat this as a programming error in your client code — log the full request payload for debugging.
2. Do not retry the same request unchanged.
3. Validate targets and values lengths before sending write requests.
4. Verify that your JSON serializer is writing valid newline-terminated JSON.

The connection remains open after a malformed_request error. You can send corrected requests on the same connection.

internal_error

Status: error

What causes it: The daemon successfully authorized your request but encountered a failure when communicating with the underlying OS keychain backend. Common causes:

• macOS Keychain database is locked (user has logged out or the keychain has been explicitly locked).
• Linux D-Bus session is unavailable or the GNOME Keyring / KWallet daemon is not running.
• Windows Credential Manager returned an unexpected error.
• Headless environments where no keychain backend is available and the fallback file-based store is inaccessible.

What your client should do:

1. This error may be transient. It is reasonable to retry once after a short delay (1–2 seconds).

2. If the error persists, surface a message that the keychain backend is unavailable and suggest the user check their keychain status:

   keychain-auth: OS keychain is unavailable.
   On Linux, ensure GNOME Keyring or KWallet is running.
   On macOS, ensure your login keychain is unlocked.
   

3. The connection remains open. You may retry on the same connection or reconnect.

target_not_allowed

Status: denied

What causes it: Your binary requested a specific target key that its policy does not permit. This is a more granular variant of service_not_allowed — the service namespace may be allowed, but the specific key name is restricted.

What your client should do:

1. Do not retry the same request.
2. Check whether the target key name is correct and within the service namespace your binary is authorized for.
3. If the key is legitimate, verify the policy configuration in ~/.config/keychain-auth/config.json.

hash_mismatch_during_fork

Status: denied

What causes it: The daemon detected that the binary making the request has a different hash than the binary that originally established the connection. This can occur if a binary replaces itself in memory or if an unexpected process substitution occurred.

What your client should do:

1. This is a security event — do not retry.
2. Surface an alert to the user that the daemon detected an unexpected hash change mid-connection.
3. If the binary was legitimately updated, run keychain-auth upgrade $(which your-tool) to refresh the approved hash, then reconnect.

Quick reference table

Reason code	Status	Connection closed?	Retryable?
unregistered_binary_pending_approval	denied	Yes — immediately	No — requires human approval
service_not_allowed	denied	No	No — requires policy change
action_not_in_policy	denied	No	No — requires policy change
target_not_allowed	denied	No	No — requires policy change
hash_mismatch_during_fork	denied	Yes — immediately	No — security event
malformed_request	error	No	Only after fixing the request
internal_error	error	No	Yes — may be transient