keychain-bridge

# Keychain Bridge

## Trigger Phrases

- "migrate secrets to keychain" / "move secrets"
- "check keychain health" / "keychain status"
- "audit secrets" / "check for leaks"
- "read secret" / "get API key"
- "store secret" / "write to keychain"
- "keychain not working" / "security find-generic-password hangs"

## Example Usage

```
User: "Migrate my secrets to the keychain"
Action: python3 SKILL_DIR/scripts/migrate_secrets.py --dir ~/.openclaw/secrets/ --account moltbot --dry-run

User: "Check if the keychain bridge is healthy"
Action: Run keychain health check (test write/read/delete cycle)

User: "Audit for plaintext secret leaks"
Action: python3 SKILL_DIR/scripts/audit_secrets.py --dir ~/.openclaw/secrets/ --account moltbot
```

Manage secrets via macOS Keychain instead of plaintext files. Eliminates plaintext credential storage while maintaining compatibility with bash-based tools through a file-bridge architecture.

## Prerequisites

The `keyring` Python library must be installed for each Python version that will access secrets:

```bash
pip3 install keyring
# If multiple Python versions exist (common on macOS):
/usr/bin/python3 -m pip install keyring
/opt/homebrew/opt/python@3.14/bin/python3.14 -m pip install --break-system-packages keyring
```

## Check Keychain Health

Verify the keychain bridge is working correctly:

```bash
python3 -c "
import keyring
# Test write
keyring.set_password('keychain-bridge-test', 'test', 'hello')
# Test read
val = keyring.get_password('keychain-bridge-test', 'test')
assert val == 'hello', f'Read back {val!r}, expected hello'
# Cleanup
keyring.delete_password('keychain-bridge-test', 'test')
print('Keychain health: OK')
"
```

If this fails, see **Diagnose Issues** below.

## Migrate Secrets

Migrate plaintext secret files to macOS Keychain. The migration tool:
- Auto-detects all Python versions on the system
- Injects each secret from ALL detected Python binaries (required for ACL coverage)
- Verifies the round-trip read
- Optiona...

# Keychain Bridge for OpenClaw

Stop storing API keys in plaintext. Migrate your OpenClaw secrets to macOS
Keychain with one command — and never worry about credential leaks again.

## The Problem

macOS Tahoe 26.x introduced several breaking changes to keychain access that
affect OpenClaw deployments:

- **`security find-generic-password -w` hangs indefinitely** — the standard CLI
  method for reading keychain items is broken on Tahoe (exit code 36 or infinite hang)
- **Plaintext files in `~/.openclaw/secrets/`** are discoverable by any process
  with file access — and 283 ClawHub skills were found with credential exposure
- **Keychain ACLs are per-binary** — an item created by Python 3.9 can't be read
  by Python 3.14 unless both binaries are in the ACL
- **Python keyring hangs from bash LaunchAgents** — a novel finding where the
  SecurityAgent session attachment is lost in bash-to-python subprocess transitions

## The Solution

Keychain Bridge is a battle-tested skill built from a real production deployment
on a Mac Mini M4 Pro running OpenClaw 24/7 with 12+ API keys, 25 scripts, and
15 cron jobs. It provides:

- **One-command migration** from plaintext files to macOS Keychain
- **Auto-detection** of all Python versions on the system with full ACL coverage
- **Group A/B architecture** for mixed Python/bash environments
- **Plaintext leak auditor** that catches forgotten secret files
- **Diagnostic tools** for every known Tahoe keychain failure mode
- **Boot-time file bridge** for bash scripts that can't use keychain directly

## What You Get

| File | Purpose |
|------|---------|
| `SKILL.md` | Full agent instructions — your OpenClaw agent knows how to use everything |
| `scripts/migrate_secrets.py` | Batch migration with multi-Python ACL injection and verification |
| `scripts/audit_secrets.py` | Continuous plaintext leak detection and keychain health checks |
| `scripts/keychain_helper.py` | Drop-in Python module — replaces file reads with keychain lookups |
|...