keychain-auth upgrade: update a binary's registered hash

Recompute and update the SHA-256 hash for an already-registered binary after it has been updated, preserving all of its existing service permissions.

The upgrade command updates the stored SHA-256 hash for a binary that already exists in config.json. Because keychain-auth uses cryptographic hash verification to identify callers, every time a binary is updated — by a package manager, manual install, or build — its hash changes. The daemon will reject the updated binary as unrecognized until the hash in config.json is refreshed. Running upgrade recomputes the hash and updates the config in place, without changing the binary’s configured service permissions.

Why upgrades are necessary

keychain-auth identifies every binary by both its path on disk and its SHA-256 hash. When you update a tool — for example, by running brew upgrade mytool or pip install --upgrade mytool — the binary at that path is replaced with a new version. The new binary has a different hash, so the daemon treats it as an unregistered binary and rejects its connections.

Rather than going through the full registration or approval flow again, upgrade handles this case: it reads the new binary, computes the updated hash, and overwrites only the hash field in the existing config.json entry. Your allowed_read_services, allowed_write_services, and can_search settings are preserved exactly as they were.

Usage

keychain-auth upgrade <path/to/binary>

The most common usage is to pass the binary’s location on your PATH:

keychain-auth upgrade $(which your-tool)

On success, the command prints the new hash:

Upgraded /usr/local/bin/your-tool to new hash sha256:a1b2c3d4...

Adding upgrade to post-install hooks

To make the process seamless for users of your tool, add the upgrade call to your package manager’s post-install or post-upgrade hook. For example, in a shell-based installer script:

# After installing or updating the binary
keychain-auth upgrade $(which your-tool)

This ensures that every time a user updates your tool, the keychain-auth entry is refreshed automatically and the tool continues to work without interruption.

If you maintain a Homebrew formula, Debian package, or similar, add the upgrade command to the post_install or post_upgrade step. Your users will never see an unexpected “unregistered binary” rejection after an update.

When to use register instead

upgrade only works for binaries already present in config.json. If the binary path has changed — for example, the binary moved from /usr/bin/mytool to /usr/local/bin/mytool — you must use keychain-auth register to add the new path as a fresh entry.

If you run upgrade on a path that is not registered, the command will exit with an error:

path /usr/local/bin/mytool is not registered. use 'register' instead

If the binary was moved to a new path and you want to preserve its permissions, register the new path, then manually copy the allowed_read_services, allowed_write_services, and can_search values from the old entry in ~/.config/keychain-auth/config.json to the new one.