让 AI 使用密钥完成工作，但不把密钥交给 AI。
English · 用户指南 · MCP 接入 · 安全模型 · 常见问题
KeyBroker 是一款完全本地运行、开源、面向 AI 编程代理的密钥使用代理。用户把 API Token、密码、CDK、TOTP 种子等凭据保存在本地加密 Vault 中；AI 只能看到公开名称、用途、使用策略以及不可解引用的 km:// 标识符。真正需要使用凭据时，AI 请求一个受约束的操作，KeyBroker 在本机完成审批、策略验证和凭据注入，并只返回经过脱敏的结果。
它解决的不是“怎样把密码更方便地复制给 AI”，而是“怎样让 AI 完成需要密码的任务，同时不获得密码本身”。
在 AI 编程工作流中，常见做法都存在明显风险：
- 把 API Key 直接粘贴进对话，会进入模型上下文、日志或截图。
- 把密钥写进命令参数，可能出现在进程列表、终端历史和审计日志中。
- 使用全局字符串替换，容易把密钥注入错误的目标或不受信任的内容。
- 给 AI 一个通用密码管理器读取接口，本质上仍然是把明文交给模型。
KeyBroker 改用“能力请求”模型：AI 可以请求“使用代码仓库令牌访问这个精确 API”，但不能请求“显示代码仓库令牌”。
- 无明文读取接口：CLI 和 MCP 均没有
reveal、resolve、export或复制到剪贴板功能。 - 标识符不是授权凭证：知道
km://secret/...只代表知道一个引用，仍需满足策略和本机审批。 - 使用范围最小化：HTTPS Origin、方法、路径、注入位置、CLI 参数和 SSH 命令都必须预先固定。
- 密钥只在本机短暂出现：Vault、策略、别名和审计记录整体加密；临时原生缓冲区锁页并清零。
- 模型只能看到安全结果：响应内容、标准输出和错误输出会按原文及常见编码形式进行脱敏。
- 高风险操作由人确认：每次真实密钥使用都显示本机原生审批窗口。
sequenceDiagram
participant User as 用户
participant AI as AI / Codex
participant MCP as keybroker-mcp
participant D as keybrokerd
participant Target as API / CLI / SSH
User->>D: 在本机保存密钥、用途和策略
D-->>AI: 仅公开名称、用途、策略、km:// 标识符
AI->>MCP: 请求执行受约束操作
MCP->>D: 认证 Named Pipe 请求
D->>D: 校验目标、方法、路径和使用次数
D->>User: 本机审批
User-->>D: 允许或拒绝
D->>Target: 本地注入密钥并执行
Target-->>D: 返回结果
D-->>AI: 脱敏后的结果和审计状态
| 能力 | 行为 | 密钥是否返回给 AI |
|---|---|---|
| HTTPS 请求 | 精确 Origin、方法和路径前缀；阻止重定向；DNS 检查与地址固定 | 否 |
| 一次性 CDK | 仅在上游成功后标记为已消费，成功后不可复用 | 否 |
| TOTP | 守护进程内按 RFC 6238 生成当期验证码并立即使用 | 否 |
| 固定 CLI Profile | 固定可执行文件绝对路径、SHA-256 和参数向量；仅允许 stdin/指定环境变量注入 | 否 |
| SSH Agent Profile | 私钥留在 Windows OpenSSH Agent；仅允许固定主机、用户、端口和远程命令 | 否 |
| 审计 | 加密记录请求时间、目标、结果和使用次数，不记录密钥 | 不适用 |
| 备份恢复 | 备份仍由 DPAPI CurrentUser 和 AES-256-GCM 保护，恢复前验证完整性 | 否 |
keybrokerd.exe：单写者守护进程，是唯一长期持有解密 Vault 状态的进程。keybroker.exe：面向用户的 CLI，同时负责启动 WPF 管理界面。keybroker-mcp.exe：stdio MCP 适配器，只暴露元数据和受控使用工具。KeyBroker.UI.ps1：本地 WPF 管理界面，不包含显示或导出密钥功能。
本地客户端通过拒绝远程连接的 Windows Named Pipe 通信。每条连接必须使用 DPAPI CurrentUser 保护的 IPC 密钥完成随机 HMAC-SHA-256 挑战。Vault 使用随机 256 位密钥进行 AES-256-GCM 整体加密，该密钥再由 Windows DPAPI CurrentUser 包装。
- Windows 10 或 Windows 11 x64。
- Windows PowerShell 5.1，用于管理界面和安装脚本。
- 使用 SSH 功能时需要 Windows OpenSSH Client 与 OpenSSH Authentication Agent。
- 从源码构建需要 Rust 1.97.0 gnullvm 和 LLVM-MinGW 20260407；普通用户使用发布包不需要 Rust。
解压发布包后运行：
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1安装器会先验证 SHA256SUMS.txt，默认安装到：
%LOCALAPPDATA%\Programs\KeyBroker
keybroker doctor
keybroker ui通过 UI 添加，或使用隐藏终端输入：
keybroker add `
--alias github-dev `
--purpose "读取 example/project 的 Issues" `
--origin https://api.github.com `
--method GET `
--path-prefix /repos/example/project/真实值不会出现在命令参数中。列出 AI 可见的公开信息：
keybroker list完整操作说明见 用户指南。
在 %USERPROFILE%\.codex\config.toml 中使用绝对路径并设置显式工具白名单：
[mcp_servers.keybroker]
command = "C:\\Users\\YOUR_NAME\\AppData\\Local\\Programs\\KeyBroker\\keybroker-mcp.exe"
startup_timeout_sec = 10
tool_timeout_sec = 120
enabled_tools = [
"secret_list",
"secret_describe",
"secret_http_request",
"secret_cdk_use",
"secret_totp_http_request",
"secret_audit",
"profile_list",
"cli_profile_run",
"ssh_profile_run",
]可用工具和推荐提示词见 MCP 接入指南。
keybroker backup --output D:\secure\keybroker-backup.json
keybroker verify-backup --input D:\secure\keybroker-backup.json
keybroker restore --input D:\secure\keybroker-backup.json备份仍绑定当前 Windows 用户的 DPAPI 主密钥，不是跨账户或重装系统后的便携备份。正式使用前请阅读 恢复手册。
当前版本为 1.0.0-rc.1。它已经实现核心架构、安装器、SBOM、哈希清单、加密恢复、变异回归测试和双目录可复现构建，但仍是预审计候选版，不应宣称为经过独立安全审计的生产级密码管理器。
最终 1.0 的外部门槛包括：
- 独立第三方安全审计；
- 可信发布者代码签名；
- 在独立构建机上复现；
- MSVC/Linux Sanitizer 环境中的覆盖引导模糊测试；
- 人工 UI/无障碍验收；
- 使用一次性低权限账户完成真实服务集成测试。
同一 Windows 用户权限下运行的恶意软件、管理员攻击以及已获批准目标主动滥用凭据，超出当前隔离能力。详见 威胁模型。
cd native
cargo fmt --all -- --check
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked修改任何密钥传递、MCP 返回内容、IPC 或策略校验代码前，请先阅读威胁模型。贡献流程见 CONTRIBUTING.md。任何把明文密钥返回给 MCP/CLI 的改动都属于安全回归。