secrets/README.md

# Secrets

这是 v3 架构的仓库，当前主路径已经收敛为：

- `apps/api`：远端 JSON API
- `apps/desktop/src-tauri`：桌面客户端
- `crates/desktop-daemon`：本地 MCP 入口
- `crates/application` / `domain` / `infrastructure-db`：业务与数据层

## 本地开发

```bash
cp deploy/.env.example .env

# 远端 API
cargo run -p secrets-api --bin secrets-api

# 本地 daemon
cargo run -p secrets-desktop-daemon

# 桌面客户端
cargo run -p secrets-desktop
```

## 当前能力

- 桌面端使用系统浏览器完成 Google Desktop OAuth 登录
- 登录成功后向 API 注册设备，并在当前桌面进程内维护登录会话
- 本地 daemon 提供显式拆分的 MCP 工具：
  - `secrets_entry_find` / `secrets_entry_get`
  - `secrets_entry_add` / `secrets_entry_update` / `secrets_entry_delete` / `secrets_entry_restore`
  - `secrets_secret_add` / `secrets_secret_update` / `secrets_secret_delete`
  - `secrets_secret_history` / `secrets_secret_rollback`
  - `target_exec`
- 保留兼容别名：`secrets_find` / `secrets_add` / `secrets_update`
- 桌面端会自动把本地 daemon MCP 配置写入 `Cursor` 与 `Claude Code`
- 桌面端支持条目新建、搜索、按 type 筛选、元数据编辑、最近删除与恢复
- 桌面端支持 secret 新增、编辑、删除、明文显示、真实复制、历史查看与回滚
- 不保留 `secrets_env_map`
- 不做自动恢复登录；重启 app 后必须重新登录

## 提交前检查

```bash
cargo fmt -- --check
cargo clippy --locked -- -D warnings
cargo test --locked
```

## PostgreSQL TLS 加固

- 推荐将数据库域名单独设置为 `db.refining.ltd`，服务域名保持 `secrets.refining.app`。
- 数据库证书建议使用可校验链路（如 Let's Encrypt 或私有 CA），并保证证书 `SAN` 包含 `db.refining.ltd`。
- PostgreSQL 侧建议使用 `hostssl` 规则限制应用来源（如 `47.238.146.244/32`），逐步移除公网明文 `host` 访问。
- 应用端推荐 `SECRETS_DATABASE_SSL_MODE=verify-full`；仅在过渡阶段可临时用 `verify-ca`。
- 可执行运维步骤见 `[deploy/postgres-tls-hardening.md](deploy/postgres-tls-hardening.md)`。

## MCP 与 AI 工作流（v3）

当前 v3 以 **桌面端 + 本地 daemon** 为主路径：

- 桌面端登录态仅在当前进程内有效，不持久化 `device token`
- 本地 daemon 默认监听 `http://127.0.0.1:9515/mcp`
- daemon 通过活跃 desktop 进程提供的本地会话转发访问 API；desktop 进程退出后所有工具不可用
- `target_exec` 会显式读取真实 secret 值后再生成 `TARGET_*` 环境变量
- 不保留 `secrets_env_map`

### Canonical MCP 工具

| 工具 | 说明 |
| --- | --- |
| `secrets_entry_find` | 从 desktop 已解锁本地 vault 搜索对象，支持 `query` / `folder` / `type` |
| `secrets_entry_get` | 读取单条本地对象，并返回当前 secrets 的真实值 |
| `secrets_entry_add` | 在本地 vault 创建对象，可选附带初始 secrets |
| `secrets_entry_update` | 更新本地对象的 folder / type / name / metadata |
| `secrets_entry_delete` | 将本地对象标记为删除 |
| `secrets_entry_restore` | 恢复本地已删除对象 |
| `secrets_secret_add` | 向已有本地对象新增 secret |
| `secrets_secret_update` | 更新本地 secret 名称、类型或内容 |
| `secrets_secret_delete` | 删除单个本地 secret |
| `secrets_secret_history` | 查看单个本地 secret 的历史版本 |
| `secrets_secret_rollback` | 将单个本地 secret 回滚到指定版本 |
| `target_exec` | 用本地对象的 metadata 和 secrets 生成 `TARGET_*` 环境变量并执行本地命令 |

### 兼容别名

以下旧名称仍可用，但内部已转发到 v3 工具：

- `secrets_find` -> `secrets_entry_find`
- `secrets_add` -> `secrets_entry_add`
- `secrets_update` -> `secrets_entry_update`

## AI 客户端配置

桌面端会自动把本地 daemon 写入以下配置：

- `~/.cursor/mcp.json`
- `~/.claude/mcp.json`

写入示例：

```json
{
  "mcpServers": {
    "secrets": {
      "url": "http://127.0.0.1:9515/mcp"
    }
  }
}
```

## 数据模型

当前 v3 已切到**零知识同步模型**：

- 服务端保存 `vault_objects` 与 `vault_object_revisions`
- desktop 本地保存 `vault_objects`、`vault_object_history`、`pending_changes`、`sync_state`
- 搜索、详情、reveal、history 主要在本地已解锁 vault 上完成
- 服务端负责 `auth/device` 与 `/sync/*`，不再承担明文搜索与明文 reveal

主要表：

- `users`
- `oauth_accounts`
- `devices`
- `device_login_tokens`
- `auth_events`
- `vault_objects`
- `vault_object_revisions`

字段职责：

| 位置 | 字段 | 说明 |
| --- | --- | --- |
| `vault_objects` | `object_id` | 同步对象标识 |
| `vault_objects` | `object_kind` | 当前对象类别，当前主要为 `cipher` |
| `vault_objects` | `revision` | 服务端对象版本 |
| `vault_objects` | `ciphertext` | 密文对象载荷 |
| `vault_objects` | `content_hash` | 密文摘要 |
| `vault_objects` | `deleted_at` | 对象级删除标记 |
| `vault_object_revisions` | `revision` / `ciphertext` | 服务端对象历史版本 |

## 认证与事件

当前登录流为 Google Desktop OAuth：

- 桌面端使用系统浏览器拉起 Google 授权
- 使用本地 loopback callback + PKCE
- API 校验 Google userinfo 后发放 `device token`
- 登录与设备活动写入 `auth_events`

## 项目结构

```text
Cargo.toml
apps/
  api/                  # 远端 JSON API
  desktop/src-tauri/    # Tauri 桌面端
crates/
  application/          # v3 应用服务
  client-integrations/  # Cursor / Claude Code mcp.json 注入
  crypto/               # 通用加密辅助
  desktop-daemon/       # 本地 MCP daemon
  device-auth/          # Desktop OAuth / device token 辅助
  domain/               # 领域模型
  infrastructure-db/    # PostgreSQL 连接与迁移
deploy/
  .env.example
  secrets-mcp.service
  postgres-tls-hardening.md
scripts/
  release-check.sh
  setup-gitea-actions.sh
```

## CI/CD（Gitea Actions）

当前以 workspace 级检查为主，见 `[.gitea/workflows/secrets.yml](.gitea/workflows/secrets.yml)`。

提交前建议直接运行：

```bash
./scripts/release-check.sh
```

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