Register your CLI tool with keychain-auth at install

Step-by-step guide to registering your binary at install time, granting it a zero-trust baseline, and keeping its hash current after upgrades.

When a user installs your CLI tool, keychain-auth needs to know about it before it can interact with the OS keychain. Registration records your binary’s path and SHA-256 hash in the local policy database, placing it in a zero-trust state — recognized by the daemon but not yet permitted to read, write, or search any secrets. You then authorize specific service namespaces in a separate configuration step.

The integration lifecycle

Every CLI tool that integrates with keychain-auth passes through three phases, in order.

1. Registration

   Your installer registers the binary with the daemon. The binary is recorded in config.json with empty permission sets. It cannot access any secrets yet.

2. Authorization

   You or your installer grants the binary access to specific service namespaces by editing ~/.config/keychain-auth/config.json. This is a one-time setup step performed after registration.

3. Runtime queries

   On every execution, your CLI connects to the daemon socket. The daemon verifies the binary’s path and hash against config.json, binds the matching policy to the connection, and enforces it for the lifetime of that session.

Phase 1: Install-time registration

In your installer script or package post-install hook, run:

keychain-auth register $(which your-tool)

This command:

1. Resolves the binary path (e.g., /usr/local/bin/your-tool).
2. Computes its SHA-256 hash.
3. Appends a new entry to ~/.config/keychain-auth/config.json.

The resulting entry looks like this:

{
  "path": "/usr/local/bin/your-tool",
  "hash": "sha256:fd7ecae9159e6f93a25178d3489fbffa7219917ca12567d5e42b156948",
  "allowed_read_services": [],
  "allowed_write_services": [],
  "can_search": false
}

Registered binaries start with empty permission sets. Your tool is recognized by the daemon, but all read, write, search, and delete operations will be denied until you configure service namespace permissions.

Phase 2: Authorization (policy configuration)

After registration, grant your binary access to the service namespaces it needs. Open ~/.config/keychain-auth/config.json and populate the permission fields for your tool’s entry. See Configure service namespace permissions for the full configuration reference and architectural patterns.

Phase 3: Runtime queries

Once registered and authorized, your CLI connects to the daemon socket on each execution. The daemon retrieves your process ID from the kernel (via SO_PEERCRED on Linux, LOCAL_PEERPID on macOS, or Named Pipe verification on Windows), resolves your binary path, recomputes its SHA-256 hash, and compares it against your config.json. If the path and hash match, the daemon binds your policy to the active connection.

Your tool can then send newline-delimited JSON requests over the socket for the duration of that connection.

Handling binary upgrades

When your tool is updated (for example, your package manager installs a new version), its SHA-256 hash changes. The daemon will reject the updated binary as unregistered until you update the recorded hash.

Run this command in your package post-upgrade hook:

keychain-auth upgrade $(which your-tool)

This recomputes the binary’s hash, locates the matching path in config.json, and updates the approved hash entry in place — without modifying your existing permission policies.

Add both the register call to your post-install hook and the upgrade call to your post-upgrade hook so users never need to re-authorize your tool manually after an update.