Keychain 3.0.0

[danielrobbins]

First stable release of Keychain 3.

Keychain 3 is a ground-up Python 3 evolution of Daniel Robbins' long-running SSH and GPG agent orchestrator. It preserves Keychain's single-file deployment model as a single-file, self-contained keychain.pyz (see Python Rationale), while replacing the historical Bourne shell implementation with a tested, auditable Python package. It requires Python 3.9 or newer and has no third-party runtime dependencies.

The 3.0.0 release incorporates the work delivered through all three public betas. Highlights include:

• One coordinated agent experience across terminals and sessions. Keychain discovers, validates, starts, and reconnects to a long-running agent per user and host. Managed ssh-agent sockets now live at stable, host-specific paths under ~/.keychain/, avoiding fragile temporary socket directories.

• Coordinated multi-terminal initialization. When several shells discover missing keys at the same time, they cooperate instead of racing for a lock or displaying duplicate passphrase prompts. Any waiting terminal can take over an inaccessible prompt, and all participants are notified when key loading completes.

• A modern interface with strong 2.x compatibility. The action-oriented command surface includes add, agent, list, env, inspect, help, and man. Traditional Keychain 2.x invocations remain supported through an explicit compatibility layer; intentional differences are documented under keychain man topic:compat.

• Broader SSH and GPG workflows. Keychain can load PKCS#11 providers for smartcards and hardware tokens, use or start gpg-agent with SSH support, and explicitly warm GPG signing, encryption, and decryption credentials. Verification failures are reported instead of being mistaken for success.

• Native macOS confirmation support. When --confirm is used with a new Keychain-managed ssh-agent, Keychain installs a private, confirmation-only osascript helper and gives OpenSSH a zero-dependency, native macOS Allow/Deny dialog for each key use. It works entirely with facilities built into macOS, with no additional askpass package or graphical toolkit to install. Denial, cancellation, a missing desktop session, or helper failure all fail closed. --confirm and --no-gui are intentionally incompatible.

• Configuration, inspection, and embedded documentation. Persistent preferences may live in an optional ~/.keychainrc; keychain inspect exposes resolved runtime state in human-readable or JSON form; and the complete, versioned manual ships inside the zipapp with topic and option-level help (keychain man and keychain man --list).

• Hardened state handling and testing. Agent sockets, pidfiles, locks, coordination state, and waiter endpoints are ownership- and permission- checked. The test suite covers modern and legacy CLI behavior, real SSH and GPG integration, multi-terminal coordination, and supported platform differences.

Changes since 3.0.0_beta3:

• Added zero-dependency, native macOS --confirm dialog support (--confirm not working in MacOS #222).
• Made --confirm --no-gui fail explicitly.
• Fixed an issue where --quiet suppressed the prompt to press Enter to initialize keys (Waiting for enter but nothing is displayed in the terminal #223).
• Expanded inspect with .keychainrc status, effective settings and their sources, runtime identity, and relevant environment state. inspect --json now emits a versioned diagnostic report suitable for bug reports.
• Completed a dedicated security hardening pass across runtime storage, configuration, agent handling, and generated shell output. Keychain now rejects unsafe ownership or permissions on .keychainrc and runtime files, validates SSH endpoints before use, rechecks agent identity before stopping it, writes private state atomically, quotes exports for each target shell, and rejects unsafe control characters.
• Reworked concurrent initialization around operating-system advisory locks. Lock ownership and liveness no longer depend on PID heuristics; locks are released automatically when the owning process exits, and abandoned activation handoffs are safely reconciled.
• Hardened the release pipeline with commit-pinned GitHub Actions, verified release artifacts, and automatically generated SHA256 checksums.
• Converted command timeouts, malformed agent arguments, and operating-system failures into concise user errors instead of Python tracebacks (3.0.0b3: gpg timeout leads to a verbose/long error (normal for beta?) #224).
• Corrected askpass environment handling to follow OpenSSH's DISPLAY, WAYLAND_DISPLAY, and SSH_ASKPASS_REQUIRE=force rules.
• Strengthened GPG warm-up verification so gpga: proves both signing and decryption capability before reporting success, and made decrypt verification portable by avoiding /dev/null as the temporary encrypted payload.
• Expanded end-to-end SSH confirmation and agent startup coverage.
• Shortened managed ssh-agent socket names to avoid UNIX-domain socket path limits on macOS, Linux, and other POSIX systems.
• Extensive code cleanups throughout the codebase (removing deprecated code, simplifying logic where possible, etc.)

Prior Keychain 3 beta users on MacOS will need to restart ssh-agent and Keychain completely in order to use the new --confirm functionality. Run keychain agent stop once, then start Keychain normally. This will initialize the new graphical --confirm support. You will now be prompted with a graphical dialog to allow or deny each use of the cached key.

---

This discussion was created from the release Keychain 3.0.0.

[danielrobbins]

macOS --confirm note: Keychain’s native confirmation dialog requires an ssh-agent started by Keychain, because an existing launchd-managed agent cannot receive the required SSH_ASKPASS environment after it has started. Before first enabling confirmation, run keychain agent stop, then invoke Keychain with --no-inherit --confirm. For persistent use, set inherit = false and confirm = true under [agent] in ~/.keychainrc.