refining/secrets
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 68 Wiki Activity
Files
57c3efb70e5d38a81a57269a979125a73f772f56
secrets/AGENTS.md
agent 57c3efb70e feat(auth): 服务端托管 Google OAuth；修复未解锁 vault 时 bootstrap 
- API：桌面登录 session、Google 托管回调与轮询
- Desktop：轮询登录；bootstrap 在 vault 未解锁时不返回 shell，避免跳过主密码
- 文档与 deploy/.env.example 对齐 GOOGLE_OAUTH_* 与 SECRETS_PUBLIC_BASE_URL
2026-04-14 22:05:11 +08:00

7.2 KiB
Raw Blame History

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) 作为版本控制系统（纯 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})"。

提交前检查

每次提交前至少运行：

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

也可以直接运行：

./scripts/release-check.sh

项目结构

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 提供，默认地址：

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 下执行：

    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 明文存储”机械地当成密码学问题处理，必须结合当前架构和威胁模型判断
Reference in New Issue View Git Blame Copy Permalink