pdaxt/pqvault-rs

## 问题所在 ``` ~/.env → plaintext, no access control, no audit trail claude.json env blocks → keys scattered across MCP configs shell history → keys logged forever 1Password / Bitwarden → designed for humans, not AI agents HashiCorp Vault → enterprise complexity for a dev machine ``` **AI 智能体需要 API 密钥。** 但它们不需要*看到*密钥明文。它们不需要无限制的访问权限。而且，没有人追踪是哪个智能体在凌晨 3 点耗尽了您 $200 的 Anthropic 配额。 ## 解决方案 ``` ┌─────────────────────────────────────────────────┐ │ PQVault │ │ │ │ ✓ One encrypted vault for all secrets │ │ ✓ AI agents access keys via MCP protocol │ │ ✓ Zero-knowledge proxy — keys never leave │ │ ✓ Per-key rate limits (RPM, daily, monthly) │ │ ✓ Usage tracking + cost estimation per key │ │ ✓ Audit log for every access │ │ ✓ Post-quantum encryption (ML-KEM-768) │ │ ✓ Web dashboard for humans, MCP for agents │ └─────────────────────────────────────────────────┘ ``` ## PQVault 与其他方案对比 | 特性 | `.env` 文件 | 1Password | HashiCorp Vault | **PQVault** | |---------|:-----------:|:---------:|:---------------:|:-----------:| | AI 智能体访问 (MCP) | ❌ | ❌ | ❌ | ✅ | | 零知识代理 | ❌ | ❌ | ❌ | ✅ | | 后量子加密 | ❌ | ❌ | ❌ | ✅ | | 单密钥速率限制 | ❌ | ❌ | ✅ | ✅ | | 使用量与成本追踪 | ❌ | ❌ | ❌ | ✅ | | 自动提供商检测 | ❌ | ❌ | ❌ | ✅ | | 密钥健康监控 | ❌ | ❌ | ✅ | ✅ | | 无需基础设施 | ✅ | ✅ | ❌ | ✅ | | 免费且开源 | ✅ | ❌ | 部分 | ✅ | | 单一二进制文件 | ✅ | ❌ | ❌ | ✅ | ## 🚀 快速开始 ``` # 克隆并构建 git clone https://github.com/pdaxt/pqvault-rs.git cd pqvault-rs cargo build --release # macOS: ad-hoc 签名以避免 Gatekeeper codesign -s - target/release/pqvault # 初始化 vault (生成 PQ + 经典 keypairs，将 master password 存储在 Keychain 中) ./target/release/pqvault init # 添加你的第一个 secret ./target/release/pqvault add ANTHROPIC_API_KEY sk-ant-xxxxx # 检查 vault 状态 ./target/release/pqvault status # 启动 web dashboard ./target/release/pqvault web # → http://localhost:9876 # 启动 MCP server (用于 AI agents) ./target/release/pqvault serve ``` ### 配置 MCP 客户端 添加到您的 Claude Code、Cursor 或任何兼容 MCP 的客户端： ``` { "mcpServers": { "pqvault": { "command": "/path/to/pqvault-rs/target/release/pqvault", "args": ["serve"] } } } ``` PQVault 提供 4 个专注的 MCP 服务器以供模块化使用： | 服务器 | Crate | 工具 | 用途 | |--------|-------|-------|---------| | `pqvault serve` | `pqvault-mcp` | vault_get, vault_add, vault_list, ... | 核心保管库操作 | | `pqvault proxy` | `pqvault-proxy-mcp` | vault_proxy | 零知识 API 代理 | | `pqvault health` | `pqvault-health-mcp` | vault_health, vault_dashboard, vault_usage | 监控与分析 | | `pqvault env` | `pqvault-env-mcp` | vault_project_env, vault_write_env, vault_rotate | 环境管理 | ## 🏗 架构 ``` HUMAN AI AGENTS │ │ │ http://localhost:9876 │ stdio JSON-RPC (MCP) ▼ ▼ ┌──────────────────┐ ┌─────────────────────────────────────────┐ │ Web Dashboard │ │ PQVault MCP Server (rmcp 1.1) │ │ (Axum) │ │ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌─────────┐ │ │ • Browse keys │ │ │ 14 Tools │ │ Rate │ │ Usage │ │ │ • Verify keys │ │ │ (MCP) │ │ Limiter │ │ Tracker │ │ │ • Edit metadata │ │ └────┬─────┘ └────┬─────┘ └────┬────┘ │ │ • Search/filter │ │ └─────────────┼───────────┘ │ └────────┬─────────┘ │ │ │ │ │ ┌──────────────────▼──────────────────┐│ │ │ │ Vault Engine ││ └──────────────────┤ │ open → decrypt → operate → encrypt ││ │ └──────────────────┬──────────────────┘│ │ │ │ │ ┌──────────────────▼──────────────────┐│ │ │ Hybrid Crypto Layer ││ │ │ ML-KEM-768 ⊕ X25519 → HKDF → ││ │ │ AES-256-GCM ││ │ └──────────────────┬──────────────────┘│ └─────────────────────┼───────────────────┘ │ ┌────────────────────────┼──────────────────┐ ▼ ▼ ▼ ~/.pqvault/ macOS Keychain ~/.pqvault/ vault.enc (master password) usage.json *.bin / *.enc audit.log ``` ### 工作区结构 ``` pqvault-rs/ ├── crates/ │ ├── pqvault-core/ # Crypto, vault engine, providers, models │ ├── pqvault-mcp/ # Core MCP server (14 tools) │ ├── pqvault-proxy-mcp/ # Zero-knowledge API proxy │ ├── pqvault-health-mcp/ # Health monitoring & dashboards │ ├── pqvault-env-mcp/ # .env generation & management │ ├── pqvault-cli/ # Terminal interface │ └── pqvault-web/ # Web dashboard (Axum) └── Cargo.toml # Workspace root ``` ## 🛡 零知识代理 核心杀手锏功能。AI 智能体**通过** PQVault 调用 API —— 密钥永远不会离开保管库进程。 ``` ┌─────────────────┐ ┌─────────────────┐ │ AI Agent │ vault_proxy() │ PQVault │ │ │ ───────────────>│ │ │ "Call Stripe │ │ 1. Decrypt key │ │ /v1/balance" │ │ 2. Inject auth │──> Stripe API │ │ { response } │ 3. Make request │<── Response │ │ <───────────────│ 4. Return data │ └─────────────────┘ └─────────────────┘ Key stays here ↑ ``` ``` # 不要这样做 (key 暴露给 agent): vault_get("STRIPE_SECRET_KEY") → agent gets key → agent calls Stripe # 这样做 (key 永不暴露): vault_proxy(key="STRIPE_SECRET_KEY", method="GET", url="/v1/balance") → vault calls Stripe internally → returns only the response ``` **安全层级：** - 仅限 HTTPS 强制执行 - SSRF 防护（阻止 localhost、metadata 端点、IP 字面量） - 每个提供商的域名白名单 - 自动检测的认证注入（Bearer、Basic、header、query param） - 1MB 响应限制 ## 🧰 MCP 工具 (14) ### 读取操作 | 工具 | 描述 | |------|-------------| | `vault_status` | 加密信息、密钥数量、健康状态、活跃警报 | | `vault_get` | 检索密钥（受速率限制、追踪使用量、审计日志） | | `vault_list` | 列出所有密钥及元数据 —— 不暴露值 | | `vault_search` | 在名称、描述、标签中进行不区分大小写的搜索 | | `vault_health` | 过期密钥、轮换警告、使用量激增、闲置密钥警报 | | `vault_usage` | 单密钥分析：请求数、速率限制 %、成本、调用者 | | `vault_dashboard` | 完整的 markdown 仪表板，包含所有密钥、成本、限制 | | `vault_project_env` | 为已注册项目生成 `.env` 内容 | ### 写入操作 | 工具 | 描述 | |------|-------------| | `vault_add` | 添加密钥，自动检测提供商、类别和速率限制 | | `vault_rotate` | 轮换密钥值，重置时间戳，清除警报 | | `vault_delete` | 移除密钥并清理项目引用 | | `vault_import_claude` | 扫描 `~/.claude.json` 并从 MCP env 块导入 API 密钥 | ### 零知识操作 | 工具 | 描述 | |------|-------------| | `vault_proxy` | 代理 API 调用 —— 密钥自动注入，永不暴露给调用者 | | `vault_write_env` | 将 `.env` 文件写入磁盘 —— 值永不返回给调用者 | ## 🌐 Web 仪表板 功能齐全的 Web UI，位于 `http://localhost:9876` —— 嵌入在二进制文件中，零外部依赖。 | 能力 | 详情 | |------------|---------| | **按提供商分组视图** | 密钥按 Anthropic、Stripe、Resend、GitHub 等组织 | | **一键验证** | 调用提供商 API 检查密钥是否活跃、过期或受限 | | **掩码值** | 显示 `sk-a...8QAA` —— 点击查看 | | **侧边栏过滤器** | 按提供商、状态（active/error/unknown）、类别过滤 | | **全文搜索** | 搜索密钥名称、账户、描述、项目 | | **元数据编辑** | 为每个密钥设置账户、环境、描述 | | **CRUD 操作** | 通过模态对话框添加、轮换、删除密钥 | | **深色主题** | 紫色调，专为开发者设计 | ### API 端点 | 方法 | 路径 | 描述 | |--------|------|-------------| | `GET` | `/` | 仪表板 HTML | | `GET` | `/api/status` | 保管库摘要 | | `GET` | `/api/secrets` | 所有密钥（掩码值） | | `POST` | `/api/secrets` | 添加密钥 | | `DELETE` | `/api/secrets/{key}` | 删除密钥 | | `PUT` | `/api/secrets/{key}/rotate` | 轮换值 | | `PUT` | `/api/secrets/{key}/meta` | 更新元数据 | | `POST` | `/api/secrets/{key}/verify` | 对照提供商 API 验证 | | `GET` | `/api/health` | 健康报告 | | `GET` | `/api/search?q=...` | 搜索密钥 | ## 🔑 加密深入解析 ### 为什么选择混合后量子？ ### 加密流程 ``` ┌─────────────────────┐ │ Plaintext secrets │ └──────────┬──────────┘ │ ┌────────────────┼────────────────┐ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ │ ML-KEM-768 │ │ X25519 ECDH │ │ (Post-Quantum) │ │ (Classical) │ │ │ │ │ │ pq_ss (32B) │ │ x_ss (32B) │ └────────┬────────┘ └────────┬────────┘ │ │ └──────────────┬───────────────────┘ ▼ ┌────────────────────────┐ │ HKDF-SHA256 │ │ ikm = pq_ss ‖ x_ss │ │ info = "pqvault- │ │ hybrid-dek-v1" │ └───────────┬────────────┘ ▼ ┌────────────────────────┐ │ AES-256-GCM │ │ key = derived DEK │ │ aad = "pqvault-v1" │ └───────────┬────────────┘ ▼ ┌──────────────┐ │ Ciphertext │ └──────────────┘ ``` 攻击者必须**同时**攻破 ML-KEM-768（后量子格密码）**和** X25519（经典 ECDH）。 ### 安全属性 | 属性 | 机制 | |----------|-----------| | 量子抗性 | ML-KEM-768 (FIPS 203, 基于格) | | 经典抗性 | X25519 + AES-256-GCM | | 混合绑定 | DEK 派生需要两个共享密钥 | | 前向保密 | 每次加密使用临时 X25519 密钥对 | | 认证 | 带有关联数据的 AES-GCM AEAD | | 密钥静态保护 | scrypt (N=131072, 128MB) + AES-256-GCM | | 主密码 | macOS Keychain (Secure Enclave) + 文件缓存 | ### 二进制载荷格式 ``` Bytes 0-3: u32 BE — pq_ciphertext length (1088 for ML-KEM-768) Bytes 4-7: u32 BE — x25519_ephemeral length (32) Bytes 8-11: u32 BE — salt length (32) Bytes 12-15: u32 BE — nonce length (12) Bytes 16-19: u32 BE — ciphertext length (varies) Byte 20+: pq_ciphertext ‖ x25519_ephemeral ‖ salt ‖ nonce ‖ ciphertext ``` ## 📊 提供商系统 ### 自动检测 当添加密钥时，PQVault 从以下方面检测提供商： 1. **密钥名称** —— 词边界匹配（`AWS_KEY` 匹配，`AWESOME_VAR` 不匹配） 2. **值模式** —— 密钥值的正则匹配（例如，`^sk-ant-` → Anthropic） 3. **最长匹配优先** —— 避免误报 ### 内置提供商 (10) | 提供商 | 检测方式 | 速率限制 | 成本/请求 | 轮换 | |----------|-------------|:----------:|:--------:|:--------:| | **Anthropic** | `ANTHROPIC`, `^sk-ant-` | 50 RPM / 1万 日 | $0.003 | 90天 | | **OpenAI** | `OPENAI`, `^sk-[a-z0-9]{20,}` | 60 RPM / 1万 日 | $0.002 | 90天 | | **GitHub** | `GITHUB`, `^ghp_\|gho_` | 83 RPM / 5千 日 | 免费 | 90天 | | **Stripe** | `STRIPE`, `^sk_live_\|sk_test_` | 100 RPM / 1万 日 | 免费 | 30天 | | **Google** | `GOOGLE_API`, `^AIza` | 100 RPM / 1万 日 | $0.001 | 180天 | | **Brave** | `BRAVE`, `^BSA` | 10 RPM / 2千 月 | 免费 | 365天 | | **Resend** | `RESEND`, `^re_` | 10 RPM / 100 日 | 免费 | 180天 | | **Cloudflare** | `CLOUDFLARE`, `CF_API` | 50 RPM / 1万 日 | 免费 | 90天 | | **ElevenLabs** | `ELEVENLABS` | 20 RPM / 500 日 | $0.005 | 180天 | | **Serper** | `SERPER` | 5 RPM / 100 月 | 免费 | 365天 | ### 三层速率限制 ``` Request → [Token Bucket (per-minute)] → [Daily Counter] → [Monthly Counter] → Allowed refills at RPM/60 resets at midnight resets monthly ``` ### 智能警报 | 警报 | 触发条件 | 严重程度 | |-------|---------|----------| | 未使用的密钥 | 超过 30 天无访问 | ⚠️ 警告 | | 需要轮换 | 密钥年龄超过提供商建议 | ⚠️ / 🔴 严重 | | 使用量激增 | 今日请求 > 3 倍 7 天平均值 | ⚠️ 警告 | ## 📁 文件布局 ``` ~/.pqvault/ ├── vault.enc # Encrypted vault (hybrid PQ + classical) ├── vault.meta.json # Algorithm metadata (no secrets) ├── pq_public.bin # ML-KEM-768 encapsulation key (1184 bytes) ├── pq_private.enc # ML-KEM-768 decapsulation key (encrypted) ├── x25519_public.bin # X25519 public key (32 bytes) ├── x25519_private.enc # X25519 private key (encrypted) ├── usage.json # Per-key usage stats, rate limits, alerts ├── .master_cache # Cached master password (0600 permissions) ├── audit.log # JSONL access log (rotates at 10k lines) ├── audit.log.{1,2,3} # Rotated audit logs (max 3) └── backups/ └── vault.YYYY-MM-DD.enc ``` ## CLI 参考 ``` pqvault init # Initialize vault + generate keypairs pqvault serve # Start MCP server (stdio JSON-RPC) pqvault status # Vault health summary pqvault list # List secrets (no values) pqvault get # Print secret value pqvault add [-c cat] # Add secret with optional category pqvault health # Rotation, expiry, orphan warnings pqvault web [--port 9876] # Start web dashboard ``` ## 🔮 路线图：Daemon 模式 (v3) ``` HUMAN (Browser) │ localhost:7700 TOTP + password auth │ ┌───────────┴───────────────────────────┐ │ PQVault Daemon │ │ │ │ Web Portal (Axum) │ │ Token Manager (SQLite) │ │ Approval Queue (SSE push) │ │ Vault Engine (existing crypto) │ │ │ │ localhost:7700 (HTTP) │ │ /tmp/pqvault.sock (Unix) │ └────────────┬──────────────────────────┘ │ Unix socket + token ┌────────┼────────┐ ▼ ▼ ▼ MCP Proxy CLI Other tools ``` **计划更改：** - 主密码通过 Web 门户输入（TOTP 门控），仅保存在守护进程内存中 - 加密的 usage.json + audit.log（密钥名称不再泄露） - 每个智能体的令牌范围访问（哪些密钥、TTL、自动批准 vs 人工批准） - 从 Web 门户即时撤销 ## 已知限制

安全性 (点击展开)

- Web UI 无身份验证（仅限 localhost，但仍未受保护） - 文件缓存以明文存储主密码（0600 权限，同用户可读） - `usage.json` 和 `audit.log` 未加密（密钥名称可见） - Web UI 无 TLS（仅限 localhost HTTP）

功能性

- 无批量密钥验证（仅限顺序） - 密钥故障无推送通知 - 无法从 `.env` 文件导入（仅限 `~/.claude.json`） - 单一保管库，单一主密码（无多用户） - Web UI 中无备份管理

架构

- Web UI HTML 嵌入在二进制文件中（约 560 行内联 HTML/CSS/JS） - 所有状态存储在 JSON 文件中（适用于 <1000 个密钥） - 每次保存时进行完整的混合重新加密

## 依赖项 基于经过严格审计的 Rust crates 构建： | 类别 | Crates | |----------|--------| | **Crypto** | `ml-kem` 0.2, `x25519-dalek` 2, `aes-gcm` 0.10, `hkdf` 0.12, `scrypt` 0.11 | | **MCP** | `rmcp` 1.1 (stdio JSON-RPC, tool routing, schemars) | | **** | `axum` 0.8, `tower` 0.5, `tower-http` 0.6 | | **HTTP** | `reqwest` 0.12 (rustls-tls, no OpenSSL) | | **CLI** | `clap` 4 with derive macros | | **Runtime** | `tokio` 1 (multi-threaded async) | | **Keychain** | `keyring` 3 (apple-native) | | **Serialization** | `serde` 1.0, `serde_json` 1.0, `schemars` 1.0 |

由 [Pranjal Gupta](https://github.com/pdaxt) @ [DataXLR8](https://dataxlr8.ai) 构建 DataXLR8 AI 基础设施生态系统的一部分。

标签：AES-256-GCM, API密钥, Claude, CVE检测, DLL 劫持, Kyber, LLM, MCP Server, ML-KEM-768, Model Context Protocol, PQC, Rust, Streamlit, StruQ, Unmanaged PE, X25519, 人工智能代理, 代理服务, 可视化界面, 后量子密码学, 大语言模型, 大语言模型安全, 威胁情报, 审计日志, 开发者工具, 抗量子加密, 敏感数据保护, 机密管理, 混合加密, 网络安全, 网络流量审计, 蓝队防御, 访问控制, 通知系统, 隐私保护, 零知识证明