Locksmith is a secure, biometric-protected keychain vault for macOS, Windows, and Linux. It allows you to store keys, tokens, and passwords in the native system keychain, requiring biometric authentication (Touch ID on macOS, Windows Hello on Windows, Polkit/Secret Service on Linux) for access.
- Biometric Security: Leverages macOS
LocalAuthentication, Windows Hello, and Linux Polkit for biometric and interactive protection. - Keychain Integration: Stores secrets in the secure macOS Keychain Services, Windows Credential Manager, and the Linux Secret Service DBus.
- Disk Caching: Optional encrypted disk cache for fast re-access with configurable TTL.
- CLI & Library: Use it as a standalone command-line tool or import it as a Go package.
- Auto-Provisioning: Built-in
Makefilethat automatically installs its own security and quality tools.
The preferred method for installing Locksmith on macOS. This ensures you receive a pre-signed binary that is compatible with macOS security policies:
brew tap bonjoski/locksmith
brew install locksmithIf you encounter a publickey error despite the repository being public, your local Git config is likely forcing SSH for all GitHub connections. You can bypass this for just this command without changing your global configuration:
GIT_CONFIG_GLOBAL=/dev/null brew tap bonjoski/locksmithWarning
While Locksmith can be used as a Go module, the Homebrew CLI is the recommended way to interact with the vault on macOS.
Using it as a library requires your host application to have specific signing entitlements to access the macOS Keychain, which can lead to Permission Denied errors if not handled correctly.
The locksmith library is read-only by default...
- macOS with Touch ID or Apple Watch support.
- Go 1.25.4.
- Xcode Command Line Tools (
xcode-select --install). - An Apple Developer ID is recommended for persistent trust, but ad-hoc signing (
-) is supported for local development.
- Windows 10/11 with Windows Hello support.
- Go 1.25.4.
git clone https://github.com/bonjoski/locksmith.git
cd locksmith
make build
make sign./locksmith add my-service my-password --expires 30d./locksmith get my-service./locksmith listLocksmith can be used as a Summon provider to inject biometric-protected secrets into processes:
make install-summonCreate a secrets.yml file:
AWS_ACCESS_KEY_ID: !var aws/access-key
AWS_SECRET_ACCESS_KEY: !var aws/secret-key
DATABASE_PASSWORD: !var db/passwordRun your command with Summon:
summon --provider locksmith -f secrets.yml <command>Examples:
# Docker with biometric-protected secrets
summon --provider locksmith -f secrets.yml docker run --env-file @SUMMONENVFILE myapp
# Python script with AWS credentials
summon --provider locksmith -f secrets.yml python deploy.py
# Any command that reads environment variables
summon --provider locksmith -f secrets.yml env | grep AWSThis provides Touch ID authentication for your DevOps workflows, ensuring secrets are never exposed in plaintext.
Locksmith supports optional configuration via ~/.locksmith/config.yml for customizing expiration notifications:
auth:
require_biometrics: true # Enforce Touch ID / Windows Hello
prompt_message: "Authenticate to access Locksmith secret '%s'" # Optional custom prompt
notifications:
expiring_threshold: 7d # Warn when secrets expire within this duration
method: stderr # Options: stderr, macos, silent
show_on_get: true # Show warnings on 'get' command
show_on_list: true # Show status on 'list' commandLocksmith can warn you about expiring or expired secrets:
Get command with warnings:
$ locksmith get aws/key
Warning: Secret 'aws/key' expires in 2 days
AKIAIOSFODNN7EXAMPLEJSON output:
$ locksmith get aws/key --json
{
"key": "aws/key",
"value": "AKIAIOSFODNN7EXAMPLE",
"created_at": "2026-01-01T12:00:00Z",
"expires_at": "2026-02-15T12:00:00Z",
"expires_in": "48h0m0s",
"is_expired": false,
"is_expiring": true
}List command with status:
$ locksmith list
KEY CREATED EXPIRES STATUS
------------------------------------------------------------------------------------
aws/access-key 2026-01-01 2026-02-15 ⚠️ Expiring
db/password 2026-01-15 2027-01-15 ✓ Valid
api/token 2025-12-01 2026-01-01 ❌ ExpiredConfiguration options:
expiring_threshold: Duration formats:7d(days),2w(weeks),1mo(months),1y(years),24h(hours)method:stderr(default): Print warnings to stderrmacos: Show macOS notification popupsilent: No notifications (useful for automation)
See config.example.yml for a complete example.
Locksmith includes a comprehensive suite of quality and security checks.
# Run all quality and security checks
make check
# Run manual biometric regression tests (macOS)
make test-manual
# View all available commands
make helpLocksmith implements defense-in-depth security:
- Hardware-backed security: Biometric authentication is enforced by the macOS Secure Enclave and Windows TPM.
- Biometric protection: Touch ID/Face ID, Apple Watch, and Windows Hello required for sensitive operations.
- Memory zeroing: Secrets cleared from memory immediately after use
- SLSA provenance: Releases include cryptographic attestations
- Continuous Fuzzing: Daily fuzz testing of critical parsing logic
- OpenSSF Scorecard: Automated security assessment
All releases include cryptographic attestations. Verify a binary:
gh attestation verify locksmith-darwin-arm64 --owner bonjoskiSee RELEASING.md for details.
Distributed under the MIT License. See LICENSE for more information.
For security-related issues, please refer to our Security Policy.
This repository is optimized for AI-assisted development.
- Rules & Guidelines: See .cursorrules and .memory/guidelines.md.
- Architecture: See .memory/architecture.md for Mermaid diagrams and data flow.
- Tech Stack: Details on libraries and platform bridges in .memory/tech-stack.md.