Keystash

keystash 🔑

值留给钥匙串，AI 只拿引用名。

The Keychain keeps the values; your AI agent only ever gets references.

keystash 让 AI 助手（MCP、Claude Code、任何 agent）帮你管理 API key、token、密码， 而不让它看见它们。

v0.4.0 起：值存在 macOS 登录钥匙串，磁盘上只剩元数据，而且全库没有 read 工具 —— 没有任何一个接口会把密钥交给 AI。

一句话：这一版的安全性来自「没有 read 工具」＋「全库没有明文出口」，不是来自「用了什么加密」。

---

English

Why keystash

The usual advice — "don't paste your API key into the chat" — stopped working the day agents became useful. An agent that cannot read OPENAI_API_KEY cannot rotate it, cannot call the API on your behalf, cannot tell you which key expires next month.

So the goal is not "the agent never touches keys". It is the agent manages keys it cannot see:

• The value goes into the macOS login Keychain. It is never written to a file this tool owns, never printed, never returned by any API.
• Only metadata (name, tags, rotation schedule, allowed URLs) lives on disk, in plain 0600 JSON. Metadata is deliberately *not* secret — so listing and editing it needs no unlock.
• There is no `secret_read` tool, and no CLI command that echoes a value to stdout. Not a disabled flag — the code path does not exist.
• The one route to the outside world, secret_use, can only reach URLs you pre-approved per entry.

Quick start

pip install keystash          # or: uv tool install keystash

keystash doctor # check Keychain / osascript / security / pbcopy

Store a key. The value is typed into a native hidden dialog — never argv, never the shell history.

keystash add OPENAI_PROD_KEY -a https://api.openai.com/ -r 90

Let keystash invent one instead; it prints a fingerprint, never the value.

keystash generate STRIPE_PROD_SECRET -a https://api.stripe.com/ -r 180

generated STRIPE_PROD_SECRET sha256:1f3a9c02 (43 chars)

keystash list # metadata only keystash list --json keystash use OPENAI_PROD_KEY https://api.openai.com/v1/models keystash rm OPENAI_PROD_KEY

Piping a value in (CI, another vault, a password manager export) skips the dialog:

printf '%s' "$VALUE" | keystash add MY_SERVICE_PROD_KEY --stdin -a https://api.myservice.com/

Naming convention: SERVICE_ENV_PURPOSE — OPENAI_PROD_KEY, ALIYUN_OSS_STAGING_SECRET. Enforced: ^A-Z{0,63}$.

Touch ID unlock

Values live in the login Keychain. keystash copy NAME puts the value on the clipboard and clears it again after 30 seconds (--clear-after 0 disables the clear). Nothing is printed. The Touch ID prompt appears when a value is actually needed — not on list, not on show, not on doctor, not on metadata edits.

keystash doctor — clean up the mess you already have

keystash doctor reports the platform, whether the Keychain backend is available, the paths of osascript / security / pbcopy, your metadata file, the audit log, and the legacy vault path. If the metadata file exists it also prints the entry count and which entries are past their rotation interval.

AI agents, zero plaintext: keystash mcp

keystash mcp speaks MCP over stdio only — it opens no socket, not even on 127.0.0.1. It exposes exactly six tools. There is no secret_read, and no run_command:

Wire it into an MCP client:

{

"mcpServers": { "keystash": { "command": "keystash", "args": ["mcp"], "env": { "KEYSTASH_META": "/Users/you/.keystash/entries.json" } } } }

Three things worth knowing about secret_use:

1. Per-entry allow-list. Every entry carries allowed_urls, and a URL must be a prefix match of one of them. https://api.openai.com.evil.com/ does not match https://api.openai.com/, and prefix matching is why the entries must end in /. An empty allow-list refuses everything — the AI cannot pick the destination host, so secret_use cannot be turned into an exfiltration primitive.
2. Redirects are refused, not followed (allow_redirects=False), so an allowed host cannot bounce the credential somewhere else.
3. The response body is scrubbed against the value and its encodings (raw, base64, URL-encoded, hex) before it reaches the model, and truncated at 20 000 characters.

Every secret_use call appends one line to the audit log (~/.keystash/audit.log, mode 0600): timestamp, entry name, method, URL, HTTP status. Who called what, never the value.

Commands

Migrating from v0.3

v0.3 kept everything in one PBKDF2 + Fernet vault file. migrate reads that vault once and writes each value into the Keychain:

keystash migrate -s ~/keystash-vault.json --retire-vault

The old master password is fetched the way v0.3 fetched it: KEYSTASH_MASTER_PASSWORD if set, then the login Keychain (service keystash, account = the vault's absolute path — the item v0.3 wrote, so anyone who never typed that password by hand still does not have to), and only then a hidden prompt. Values pass through memory only; the only output is a table of old name / new name / tags / verified. --verify (on by default) reads each value back out of the Keychain and compares it before the entry is considered migrated, so a silent Keychain failure cannot lose a key. --retire-vault renames the old file to *.migrated after a fully successful run — it is not deleted. Keep that file until you have confirmed every entry.

Migration leaves every entry's allowed_urls empty on purpose, so secret_use refuses everything until you allow a host: keystash edit NAME --allow https://api.example.com/ (the trailing slash is required). Only the prefixes you add are reachable.

Multi-machine sync

The metadata file is plain JSON; sync it however you like. The values do not sync — they are in this Mac's login Keychain, and that is the point. On a second machine, re-enter or keystash add --stdin each value once, then copy the metadata file over.

Security model

Read this part before trusting the tool.

What keystash does eliminate. The plaintext inventory. Before, your keys were in ~/.zshrc, in .env files, in shell history, in chat logs, in MCP transcripts, in your clipboard buffer's past. Now they are in one place the AI has no tool to read, and no command prints them.

What it does not do. With Keychain storage, encryption at rest is the OS's job, and the layer beneath is your login session. Concretely:

• Any process running as you can read the same values. security find-generic-password -s keystash -a OPENAI_PROD_KEY -w works from any same-user shell. keystash does not defend against a compromised account, and does not claim to.
• The boundary is same-user process isolation, not encryption. keystash removes plaintext from the *artifacts* — files, logs, transcripts, argv, env — not from a *trusted* process's memory.
• Metadata is not secret (plain 0600 JSON): names, tags, rotation dates and allowed URLs are readable by anyone who can read your home directory. Names leak intent ("ALIYUN_PROD_KEY" tells an attacker where to look). Do not put secrets in tags.
• Scrubbing is literal replacement over a fixed encoding set (raw, base64, urlsafe-base64, percent-encoded, hex). A value re-encoded some other way — encrypted, split across lines, character-shifted — can survive it. Values shorter than 8 characters are still redacted verbatim, but their encoding variants are not, so a short secret is only partially covered.
• Rotation is a reminder, not an enforcement. -r DAYS makes doctor and the MCP secret_list flag overdue entries. Nothing rotates automatically.
• Secrets injected into a request are visible to same-user processes in principle; that is the same boundary as above.

What the AI can still do. It can list your entry names, delete entries, call allow-listed URLs with stored credentials (and read the responses), and store *new* values — including ones it invents. Treat secret_delete and the allow-lists as things you review, not things you set once. Read the audit log.

keystash 消掉的是明文，不是信任。

Environment variables

The --meta/-m and --vault/-V flags override them.

Development

git clone https://github.com/thu-lawyer/keystash.git

cd keystash pip install -e ".[dev]" pytest -q # the real Keychain is never touched ruff check src tests

The test suite drives the CLI as a subprocess and injects an in-memory store, so it passes on Linux and Windows CI with no Keychain. Set KEYSTASH_TEST_KEYCHAIN=1 to opt into the one test that touches the real login Keychain.

License

MIT

---

中文

为什么是 keystash

「别把 API key 贴进对话」这条建议，在 agent 变得有用的那天就失效了。 一个读不到 OPENAI_API_KEY 的 agent，没法帮你轮换它、没法代你调接口、也说不清下个月哪个 key 过期。

所以目标不是「agent 永不接触密钥」，而是让 agent 管理它看不见的密钥：

• 值进 macOS 登录钥匙串，不写进本工具拥有的任何文件、不打印、不被任何接口返回。
• 磁盘上只有元数据（名字、标签、轮换周期、允许的 URL），0600 明文 JSON。 元数据故意不算秘密 —— 所以列出和编辑它不需要解锁。
• 没有 `secret_read` 工具，也没有任何把值打到 stdout 的 CLI 命令。 不是「关掉的开关」，是这条代码路径根本不存在。
• 唯一通往外面的路 secret_use，只能打你按条目预先批准的 URL。

快速上手

pip install keystash          # 或：uv tool install keystash

keystash doctor # 检查 Keychain / osascript / security / pbcopy

存一个 key。值在系统隐藏输入框里手打 —— 不走 argv，不进 shell 历史。

keystash add OPENAI_PROD_KEY -a https://api.openai.com/ -r 90

也可以让 keystash 生成；它只打印指纹，不打印值。

keystash generate STRIPE_PROD_SECRET -a https://api.stripe.com/ -r 180

generated STRIPE_PROD_SECRET sha256:1f3a9c02 (43 chars)

keystash list # 只有元数据 keystash list --json keystash use OPENAI_PROD_KEY https://api.openai.com/v1/models keystash rm OPENAI_PROD_KEY

从管道喂值（CI、别的密码库导出）可以跳过弹窗：

printf '%s' "$VALUE" | keystash add MY_SERVICE_PROD_KEY --stdin -a https://api.myservice.com/

命名规范：SERVICE_ENV_PURPOSE —— OPENAI_PROD_KEY、ALIYUN_OSS_STAGING_SECRET。 已强制校验：^A-Z{0,63}$。

Touch ID 解锁

值在登录钥匙串里。keystash copy NAME 把值放进剪贴板，30 秒后自动清除（--clear-after 0 关闭清除）。 不打印任何东西。 真正取值时才出现 Touch ID 提示 —— list、show、doctor、 改元数据都不会触发。

keystash doctor —— 主动清剿你已经撒出去的明文

keystash doctor 会报出平台、Keyc