177 lines
5.9 KiB
Markdown
177 lines
5.9 KiB
Markdown
# 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`
|
||
- 桌面端会自动把本地 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_*` 环境变量并执行本地命令 |
|
||
|
||
## 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)（发版规则、代码规范）。 |