keychain-auth register: register a trusted binary

Register a binary’s path and SHA-256 hash in config.json with zero permissions, establishing its identity before you grant it access to any keychain service.

The register command adds a binary to ~/.config/keychain-auth/config.json so the daemon recognizes it. When you register a binary, keychain-auth computes its SHA-256 hash from disk, writes the path and hash to the config file, and sets all permissions to their most restrictive defaults. The binary is now known to the daemon, but it cannot access any keychain service until you explicitly configure its permissions.

Usage

keychain-auth register <path/to/binary>

The most common pattern is to register the binary currently on your PATH:

keychain-auth register $(which your-tool)

You can also provide an absolute path directly:

keychain-auth register /usr/local/bin/mytool

What registration does

1. Resolves the provided path to an absolute path.
2. Computes the SHA-256 hash of the binary file at that path.
3. Loads ~/.config/keychain-auth/config.json (creating it if it does not exist).
4. Appends a new entry — or updates the hash if the path is already present — with zero-trust defaults.
5. Saves the updated config atomically.

The resulting entry in config.json looks like this:

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

All three permission fields start empty or false. This is intentional — keychain-auth applies zero-trust by default, meaning a newly registered binary has no access to any keychain service until you grant it.

Configuring permissions after registration

After registering a binary, open ~/.config/keychain-auth/config.json and add the service namespaces you want it to access:

{
  "allowed_read_services": ["aws", "openai"],
  "allowed_write_services": ["openai"],
  "can_search": false
}

Field	Type	Description
allowed_read_services	Array of strings	Service namespaces the binary is permitted to read from.
allowed_write_services	Array of strings	Service namespaces the binary is permitted to write to or delete from.
can_search	Boolean	Whether the binary may run search or prefix-based read/delete operations.

The daemon re-reads config.json on every new connection, so permission changes take effect immediately without restarting the daemon.

For tool authors

If you are building a CLI tool that integrates with keychain-auth, run register as part of your installer so users do not need to do it manually:

keychain-auth register $(which your-cli-tool)

Because the installer runs in the user’s active shell, it writes the config directly to the user’s ~/.config/keychain-auth/config.json. Your tool will be recognized by the daemon the first time it connects.

If your binary is updated (new version installed), the SHA-256 hash changes and the daemon will reject the connection. Use keychain-auth upgrade after updates to refresh the registered hash without losing your configured permissions.