57c3efb70e
- API：桌面登录 session、Google 托管回调与轮询 - Desktop：轮询登录；bootstrap 在 vault 未解锁时不返回 shell，避免跳过主密码 - 文档与 deploy/.env.example 对齐 GOOGLE_OAUTH_* 与 SECRETS_PUBLIC_BASE_URL
241 lines
7.2 KiB
Markdown
241 lines
7.2 KiB
Markdown
# Secrets — AGENTS.md
|
||
|
||
本仓库当前为 **v3 桌面端架构**：
|
||
|
||
- `apps/api`：远端 JSON API
|
||
- `apps/desktop/src-tauri`：桌面客户端
|
||
- `crates/desktop-daemon`：本地 MCP daemon
|
||
- `crates/application` / `domain` / `infrastructure-db`：v3 业务与数据层
|
||
|
||
旧 `secrets-core` / `secrets-mcp` / `secrets-mcp-local` 已移除，不再作为开发入口。
|
||
|
||
## 版本控制
|
||
|
||
本仓库使用 **[Jujutsu (jj)](https://jj-vcs.dev/)** 作为版本控制系统（纯 jj 模式，无 `.git` 目录）。
|
||
|
||
### 常用 jj 命令对照
|
||
|
||
| 操作 | jj 命令 |
|
||
|------|---------|
|
||
| 查看历史 | `jj log` / `jj log 'all()'` |
|
||
| 查看状态 | `jj status` |
|
||
| 新建提交 | `jj commit` |
|
||
| 创建新变更 | `jj new` |
|
||
| 变基 | `jj rebase` |
|
||
| 合并提交 | `jj squash` |
|
||
| 撤销操作 | `jj undo` |
|
||
| 查看标签 | `jj tag list` |
|
||
| 查看分支 | `jj bookmark list` |
|
||
| 推送远端 | `jj git push` |
|
||
| 拉取远端 | `jj git fetch` |
|
||
|
||
### 注意事项
|
||
|
||
- 本仓库为纯 `jj` 模式，本地不要使用 `git` 命令。
|
||
- CI Runner 侧仍可能使用 `git` 拉代码，这不影响本地开发。
|
||
- 检查 tag 是否存在时，使用 `jj log --no-graph --revisions "tag(${tag})"`。
|
||
|
||
## 提交前检查
|
||
|
||
每次提交前至少运行：
|
||
|
||
```bash
|
||
cargo fmt -- --check
|
||
cargo clippy --locked -- -D warnings
|
||
cargo test --locked
|
||
```
|
||
|
||
也可以直接运行：
|
||
|
||
```bash
|
||
./scripts/release-check.sh
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
secrets/
|
||
Cargo.toml
|
||
apps/
|
||
api/ # 远端 JSON API
|
||
desktop/src-tauri/ # 桌面端
|
||
crates/
|
||
application/ # v3 应用服务
|
||
client-integrations/ # Cursor / Claude Code 配置注入
|
||
crypto/ # 通用加密辅助
|
||
desktop-daemon/ # 本地 MCP daemon
|
||
device-auth/ # 设备登录 / Desktop OAuth 辅助
|
||
domain/ # v3 领域模型
|
||
infrastructure-db/ # 数据库与迁移
|
||
deploy/
|
||
scripts/
|
||
.gitea/workflows/
|
||
.vscode/tasks.json
|
||
```
|
||
|
||
## 数据库
|
||
|
||
- 建议数据库名：`secrets-v3`
|
||
- 连接串：`SECRETS_DATABASE_URL`
|
||
- 首次连接会自动运行 `secrets-infrastructure-db::migrate_current_schema`
|
||
|
||
当前 v3 主要表：
|
||
|
||
- `users`
|
||
- `oauth_accounts`
|
||
- `devices`
|
||
- `device_login_tokens`
|
||
- `auth_events`
|
||
- `vault_objects`
|
||
- `vault_object_revisions`
|
||
|
||
### 当前模型约束
|
||
|
||
- 服务端只保存同步所需的密文对象与版本信息
|
||
- 搜索、详情、reveal、history 主要在 desktop 本地 vault 中完成
|
||
- 删除通过对象级 `deleted_at` / tombstone 传播
|
||
- 历史服务端保留在 `vault_object_revisions`，本地另有 `vault_object_history`
|
||
|
||
### 字段职责
|
||
|
||
| 字段 | 含义 | 示例 |
|
||
|------|------|------|
|
||
| `object_id` | 同步对象标识 | `UUID` |
|
||
| `object_kind` | 当前对象类别 | `cipher` |
|
||
| `revision` | 对象版本号 | `12` |
|
||
| `cipher_version` | 密文封装版本 | `1` |
|
||
| `ciphertext` | 密文对象载荷 | AES-GCM 密文 |
|
||
| `content_hash` | 密文内容摘要 | `sha256:...` |
|
||
| `deleted_at` | 对象删除时间 | `2026-04-14T12:00:00Z` |
|
||
|
||
## Google 登录
|
||
|
||
当前登录流为 **Google Desktop OAuth**：
|
||
|
||
- 桌面端使用系统浏览器拉起 Google 授权
|
||
- API 服务端持有 Google OAuth client 配置并处理 callback / token exchange
|
||
- desktop 创建一次性 login session，打开托管登录页后轮询状态
|
||
- API 校验 Google userinfo 后发放本地 device token
|
||
|
||
官网 DMG 正式分发时，服务端至少需要配置：
|
||
|
||
- `SECRETS_PUBLIC_BASE_URL`
|
||
- `GOOGLE_OAUTH_CLIENT_ID`
|
||
- `GOOGLE_OAUTH_CLIENT_SECRET`
|
||
- `GOOGLE_OAUTH_REDIRECT_URI`
|
||
|
||
推荐约束：
|
||
|
||
- `SECRETS_PUBLIC_BASE_URL` 使用用户浏览器实际访问的 HTTPS 官网地址
|
||
- `GOOGLE_OAUTH_REDIRECT_URI` 配置为 `${SECRETS_PUBLIC_BASE_URL}/auth/google/callback`
|
||
- `GOOGLE_OAUTH_CLIENT_SECRET` 只保留在服务端环境变量或密钥管理系统中，不入库
|
||
- Google Cloud Console 中登记的 callback URL 必须与 `GOOGLE_OAUTH_REDIRECT_URI` 完全一致
|
||
|
||
## MCP
|
||
|
||
本地 MCP 入口由 `crates/desktop-daemon` 提供，默认地址：
|
||
|
||
```text
|
||
http://127.0.0.1:9515/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_env_map`
|
||
|
||
### `target_exec`
|
||
|
||
`target_exec` 会显式读取 entry 当前 secrets 的真实值，并从 metadata / secrets 派生标准环境变量，例如：
|
||
|
||
- `TARGET_ENTRY_ID`
|
||
- `TARGET_NAME`
|
||
- `TARGET_FOLDER`
|
||
- `TARGET_TYPE`
|
||
- `TARGET_HOST`
|
||
- `TARGET_PORT`
|
||
- `TARGET_USER`
|
||
- `TARGET_BASE_URL`
|
||
- `TARGET_API_KEY`
|
||
- `TARGET_TOKEN`
|
||
- `TARGET_SSH_KEY`
|
||
|
||
## 桌面端
|
||
|
||
桌面端当前支持：
|
||
|
||
- Google 登录
|
||
- 自动写入 `Cursor` / `Claude Code` 的 `mcp.json`
|
||
- 新建条目
|
||
- 搜索、按 type 筛选
|
||
- 右侧原地编辑
|
||
- secret 新增、编辑、删除
|
||
- secret 明文显示 / 复制
|
||
- secret 历史查看与回滚
|
||
- 删除到最近删除与恢复
|
||
- 登录态仅在当前 desktop 进程内有效，不做自动恢复登录
|
||
- desktop 进程退出后，本地 daemon 所有工具不可用
|
||
|
||
### 配置注入
|
||
|
||
桌面端会把本地 daemon 配置写入：
|
||
|
||
- `~/.cursor/mcp.json`
|
||
- `~/.claude/mcp.json`
|
||
|
||
写入策略：
|
||
|
||
- 保留现有其它 `mcpServers`
|
||
- 仅覆盖同名 `secrets` 节点
|
||
|
||
### 图标与前端 dist（本地 / CI）
|
||
|
||
版本库为减小噪音，**不提交** Tauri 生成的多尺寸图标包；但 **`apps/desktop/dist/`** 现在作为桌面端前端静态资源目录，**需要提交到版本库**，以保证新机器 clone 后可直接运行 Tauri desktop。
|
||
|
||
- **图标**：仅跟踪 `apps/desktop/src-tauri/icons/icon.png` 作为源图（建议 **1024×1024** PNG）。检出代码后，若需要完整 `icons/`（例如打包、验证窗口/托盘图标），在 **`apps/desktop/src-tauri`** 下执行：
|
||
|
||
```bash
|
||
cd apps/desktop/src-tauri
|
||
cargo tauri icon icons/icon.png
|
||
```
|
||
|
||
需已安装 **Tauri CLI**（例如 `cargo install tauri-cli`，或与项目一致的 `cargo-tauri` 版本）。
|
||
|
||
- **前端 dist**：`tauri.conf.json` 中 `build.frontendDist` 指向 `../dist`。当前仓库直接跟踪 **`apps/desktop/dist/`** 下的静态页面资源，因此新机器 clone 后无需额外生成前端产物即可运行 `cargo run -p secrets-desktop`。若后续引入独立前端构建链，再单独把这部分切回构建产物管理。
|
||
|
||
## 代码规范
|
||
|
||
- 业务层优先使用 `anyhow::Result`
|
||
- 避免生产路径 `unwrap()`
|
||
- 使用 `tokio` + `sqlx` async
|
||
- SQL 使用参数绑定，不要手拼用户输入
|
||
- 运维日志使用 `tracing`
|
||
- 变更后优先跑最小必要验证，不要只改不测
|
||
|
||
## CI / 脚本
|
||
|
||
- `.gitea/workflows/secrets.yml` 现在是 v3 workspace 级 CI
|
||
- `scripts/release-check.sh` 只做 workspace 质量检查
|
||
- `deploy/.env.example` 反映当前 v3 API / daemon / desktop 登录配置
|
||
|
||
## 安全约束
|
||
|
||
- 不要把 Google `client_secret` 提交到受版本控制的配置文件中
|
||
- 不要把 device token、数据库密码、真实生产密钥提交入库
|
||
- 数据库生产环境优先使用 `verify-full`
|
||
- AI 审查时，不要把“随机高熵 token 明文存储”机械地当成密码学问题处理，必须结合当前架构和威胁模型判断
|