# secrets-mcp

Workspace：**`secrets-core`** + **`secrets-mcp`**（HTTP Streamable MCP + Web）。多租户密钥与元数据存 PostgreSQL；用户通过 **Google OAuth** 登录，**API Key** 鉴权 MCP 请求；秘密数据用**用户密码短语派生的密钥**在客户端加密，服务端不持有原始密钥。

## 安装

```bash
cargo build --release -p secrets-mcp
# 产物: target/release/secrets-mcp
```

发版产物见 Gitea Release（tag：`secrets-mcp-<version>`，Linux musl 预编译）；其它平台本地 `cargo build`。

## 环境变量与本地运行

复制 `deploy/.env.example` 为项目根目录 `.env`（已在 `.gitignore`），或导出同名变量：

| 变量 | 说明 |
|------|------|
| `SECRETS_DATABASE_URL` | **必填**。PostgreSQL 连接串（建议专用库，如 `secrets-mcp`）。 |
| `BASE_URL` | 对外访问基址；OAuth 回调为 `{BASE_URL}/auth/google/callback`。默认 `http://localhost:9315`。 |
| `SECRETS_MCP_BIND` | 监听地址，默认 `127.0.0.1:9315`。容器内或直接对外暴露端口时请改为 `0.0.0.0:9315`；反代时常为 `127.0.0.1:9315`。 |
| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | 可选；不配置则无 Google 登录入口。运行时从环境读取，勿写入 CI、勿打入二进制。 |
| `RUST_LOG` | 可选；日志级别，如 `secrets_mcp=debug`。 |

```bash
cargo run -p secrets-mcp
```

- **Web**：`BASE_URL`（登录、Dashboard、设置密码短语、创建 API Key）。
- **MCP**：Streamable HTTP 基址 `{BASE_URL}/mcp`，需 `Authorization: Bearer <api_key>` + `X-Encryption-Key: <hex>` 请求头（读密文工具须带密钥）。

## MCP 与 AI 工作流（v0.3+）

条目在逻辑上以 **`(folder, name)`** 在用户内唯一（数据库唯一索引：`user_id + folder + name`）。同名可在不同 folder 下各存一条（例如 `refining/aliyun` 与 `ricnsmart/aliyun`）。

- **`secrets_search`**：发现条目（可按 query / folder / type / name 过滤）；不要求加密头。
- **`secrets_get` / `secrets_update` / `secrets_delete`（按 name）/ `secrets_history` / `secrets_rollback`**：仅 `name` 且全局唯一则直接命中；若多条同名，返回消歧错误，需在参数中补 **`folder`**。
- **`secrets_delete`**：`dry_run=true` 时与真实删除相同的消歧规则——唯一则预览一条，多条则报错并要求 `folder`。

## 加密架构（混合 E2EE）

### 密钥派生

用户在 Web Dashboard 设置**密码短语**，浏览器使用 **Web Crypto API（PBKDF2-SHA256，600k 次迭代）**在本地派生 256-bit AES 密钥。

- **Salt（32B）**：首次设置时在浏览器生成，存入服务端 `users.key_salt`
- **key_check**：派生密钥加密已知常量 `"secrets-mcp-key-check"`，存入 `users.key_check`，用于登录时验证密码短语
- **服务端不存储原始密钥**，只存 salt + key_check

跨设备同步：新设备登录 → 输入相同密码短语 → 从服务端取 salt → 同样的 PBKDF2 → 得到相同密钥。

### 写入与读取流程

```mermaid
flowchart LR
    subgraph Web["Web 浏览器（E2E）"]
        P["密码短语"] --> K["PBKDF2 → 256-bit key"]
        K --> Enc["AES-256-GCM 加密"]
        K --> Dec["AES-256-GCM 解密"]
    end

    subgraph AI["AI 客户端（MCP）"]
        HdrKey["X-Encryption-Key: hex"]
    end

    subgraph Server["secrets-mcp 服务端"]
        Middleware["请求中临时持有 key\n请求结束即丢弃"]
        DB[(PostgreSQL\nsecrets.encrypted = 密文\nentries.metadata = 明文)]
    end

    Enc -->|密文| Server
    HdrKey -->|key + 请求| Middleware
    Middleware <-->|加解密| DB
    DB -->|密文| Dec
```

### 两种客户端对比

| | Web 浏览器 | AI 客户端（MCP） |
|---|---|---|
| 密钥位置 | 仅在浏览器内存 / sessionStorage | MCP 配置 headers 中 |
| 加解密位置 | 客户端（真正 E2E） | 服务端临时（请求级生命周期） |
| 安全边界 | 服务端零知识 | 依赖 TLS + 服务端内存隔离 |

### 敏感数据传输

- **OAuth `client_secret`** 只存服务端环境变量，不发给浏览器
- **API Key** 当前存放在 `users.api_key`，Dashboard 会明文展示并可重置
- **X-Encryption-Key** 随 MCP 请求经 TLS 传输，服务端仅在请求处理期间持有（不持久化）
- **生产环境必须走 HTTPS/TLS**

## AI 客户端配置

在 Web Dashboard 设置密码短语后，解锁页面会按客户端格式生成配置。常见客户端示例如下：

`Cursor / Claude Desktop` 风格：

```json
{
  "mcpServers": {
    "secrets": {
      "url": "https://secrets.example.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_abc123...",
        "X-Encryption-Key": "a1b2c3...（64位hex）"
      }
    }
  }
}
```

`OpenCode` 风格：

```json
{
  "mcp": {
    "secrets": {
      "type": "remote",
      "enabled": true,
      "url": "https://secrets.example.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_abc123...",
        "X-Encryption-Key": "a1b2c3...（64位hex）"
      }
    }
  }
}
```

## 数据模型

主表 **`entries`**（`folder`、`type`、`name`、`notes`、`tags`、`metadata`，多租户时带 `user_id`）+ 子表 **`secrets`**（每行一个加密字段：`field_name`、`encrypted`）。**唯一性**：`UNIQUE(user_id, folder, name)`（`user_id` 为空时为遗留行唯一 `(folder, name)`）。另有 `entries_history`、`secrets_history`、`audit_log`，以及 **`users`**（含 `key_salt`、`key_check`、`key_params`、`api_key`）、**`oauth_accounts`**。首次连库自动迁移建表（`secrets-core` 的 `migrate`）；已有库可对照 [`scripts/migrate-v0.3.0.sql`](scripts/migrate-v0.3.0.sql) 做列重命名与索引重建。**Web 登录会话**（tower-sessions）使用同一 `SECRETS_DATABASE_URL`，进程启动时对会话存储执行迁移（见 `secrets-mcp` 中 `PostgresStore::migrate`），无需额外环境变量。

| 位置 | 字段 | 说明 |
|------|------|------|
| entries | folder | 组织/隔离空间，如 `refining`、`ricnsmart`；参与唯一键 |
| entries | type | 软分类，如 `server`、`service`、`key`、`person`（可扩展，不参与唯一键） |
| entries | name | 人类可读标识；与 `folder` 一起在用户内唯一 |
| entries | notes | 非敏感说明文本 |
| entries | metadata | 明文 JSON（ip、url、`key_ref` 等） |
| secrets | field_name | 明文字段名，便于 schema 展示 |
| secrets | encrypted | AES-GCM 密文（含 nonce） |
| users | key_salt | PBKDF2 salt（32B），首次设置密码短语时写入 |
| users | key_check | 派生密钥加密已知常量，用于验证密码短语 |
| users | key_params | 派生算法参数，如 `{"alg":"pbkdf2-sha256","iterations":600000}` |

### PEM 共享（`key_ref`）

同一 PEM 可被多条 `server` 等记录引用：将 PEM 存为 **`type=key`** 的 entry，在其它条目的 `metadata.key_ref` 中写该 key 条目的 `name`；轮换时只更新 key 对应记录即可。

## 审计日志

`add`、`update`、`delete` 等写操作写入 **`audit_log`**（操作类型、对象、摘要，不含 secret 明文）。多租户场景下可写 **`user_id`**（可空，兼容遗留行）。
业务条目事件使用 **`folder` / `type` / `name`**；登录类事件使用 **`folder='auth'`**，此时 `type`/`name` 表示认证目标（例如 `oauth` / `google`），不表示某条 secrets entry。

```sql
SELECT action, folder, type, name, detail, user_id, created_at
FROM audit_log
ORDER BY created_at DESC
LIMIT 20;
```

## 项目结构

```
Cargo.toml
crates/secrets-core/     # db / crypto / models / audit / service
crates/secrets-mcp/     # MCP HTTP、Web、OAuth、API Key
scripts/
  migrate-v0.3.0.sql    # 可选：手动 SQL 迁移（namespace/kind → folder/type、唯一键含 folder）
deploy/                 # systemd、.env 示例
```

## CI/CD（Gitea Actions）

见 [`.gitea/workflows/secrets.yml`](.gitea/workflows/secrets.yml)。

- **触发**：任意分支 `push`，且变更路径包含 `crates/**`、`deploy/**`、根目录 `Cargo.toml` / `Cargo.lock`、`.gitea/workflows/**`。
- **流水线**：解析 `crates/secrets-mcp/Cargo.toml` 版本 → `cargo fmt` / `clippy --locked` / `test --locked` → 交叉编译 `x86_64-unknown-linux-musl` 的 `secrets-mcp` → 构建成功后打 tag `secrets-mcp-<version>`（若远端已存在同名 tag，会先删除再于**当前提交**重建并推送，覆盖式发版）。
- **Release（可选）**：配置仓库 Secret `RELEASE_TOKEN`（Gitea PAT，明文勿 base64）时，会通过 API **创建或更新**已指向该 tag 的 Release（非 draft）、上传 `tar.gz` 与 `.sha256`；未配置则跳过 API Release，仅 tag + 构建结果。
- **部署（可选）**：仅在 `main`、`feat/mcp` 或 `mcp` 分支且构建成功时，若已配置 `vars.DEPLOY_HOST`、`vars.DEPLOY_USER` 与 `secrets.DEPLOY_SSH_KEY`，则 `deploy-mcp` 通过 SCP/SSH 更新目标机二进制并 `systemctl restart secrets-mcp`。
- **通知（可选）**：`vars.WEBHOOK_URL` 为飞书 Webhook 时，构建/部署/发布节点会推送简要状态。

```bash
./scripts/setup-gitea-actions.sh   # 通过 Gitea API 写入 RELEASE_TOKEN、WEBHOOK_URL、部署相关变量等
```

详见 [AGENTS.md](AGENTS.md)（发版规则、代码规范）。