vps-manager/docs/goal-spec-credentials-vault.md

Goal Spec：凭据库（密码 + 2FA）与账号体系联动

供 goal 机制执行的规格说明。执行顺序：M0 → M1 → M2 → M3（M4 待用户圈选后启动）。

1. Goal Objective（可复制的目标摘要）

为 vps-manager 增加统一的「凭据库」：新建 credentials 表（站点 × 登录方式粒度，存用户名/密码/2FA secret/URL/备注），作为登录凭据的唯一事实源；平台账号（Account）保留「资产归属 + API 配置」语义，通过 credential_id 关联其登录凭据，账号密码的读写全部重定向到凭据层；提供独立的密码库前端视图（搜索/复制/授权登录标记）与 TOTP 动态验证码展示（录入需校验码验证）；编写幂等迁移把历史 accounts.login_password_encrypted 迁入凭据表并清空原字段；全程不新增 Python 依赖（TOTP 按 RFC 6238 自实现）。

同时建立 MASTER_KEY 密钥托管（M0，最先落地）：系统生成随机 RESTORE_KEY（离线抄写保存 2~3 份），用其加密 MASTER_KEY 生成 master_key.escrow 随 data/ 备份流转；MASTER_KEY 遗失时运行一次性恢复脚本输入 RESTORE_KEY 找回并回写 .env，全量密文零迁移恢复，日常运行零接触 escrow、零新增网络接口。

本地 pytest + uvicorn 端到端验证截图后提交，再由 Gitea → cc1 timer 自动部署并做生产验证。

2. 领域模型决策（已与用户确认）

1. 凭据粒度 = 站点 × 登录方式。同一 gmail 注册 A~F 六个网站 = 六条 credential，邮箱只是 username 的取值，重复出现是常态而非冗余。
2. 密码相同不共享。A/B 站都是 xxx 也各存一份密文（改密逐站发生，禁止联动耦合）。
3. 授权登录（OAuth/SSO）是一条正常记录：login_type='oauth' + oauth_provider='google' 等，password 为空，仍占一条便于检索回忆。
4. 2FA 挂在 credential 上（登录凭据的一部分，非独立孤岛）；账号体系通过关联的凭据使用 2FA。
5. 唯一事实源 = credentials 表。accounts.login_password_encrypted 迁移后清空、停止写入；Account 的 login_user 字段保留（非机密，供展示）；api_config_encrypted（SDK 用）留在 Account 不动。
6. 账号与凭据解耦生命周期：删除账号不影响其凭据条目（凭据库独立留存）；账号侧新建/改密自动同步到凭据。
7. TOTP 不引第三方库：app/core/totp.py 自实现 RFC 6238（HMAC-SHA1 + Base32，6 位 / 30s 步长），原因：零 SSH 部署链路不重装依赖，避免 update.sh 缺包导致自毁；用 RFC 6238 附录 B 官方向量做 pytest 锚定。
8. site 显示平台中文名（迁移时 join providers），无平台记录时回退 platform 原文 / "未分类"。
9. MASTER_KEY 防遗失 = Key Escrow（托管），而非"后补万能钥匙"：Fernet 单钥设计下 key 遗失后补的钥匙解不开旧密文，恢复能力必须预先建立（见 §3）。

3. MASTER_KEY 密钥托管（M0，最先落地）

3.1 设计决策

• 问题：Fernet 单钥架构下 MASTER_KEY 遗失 = 全量密文不可解；其中 2FA secret 无法像密码一样逐站重置，损失不可逆。
• 方案（Key Escrow）：
  1. 系统生成随机 RESTORE_KEY（Fernet key 格式，44 字符 urlsafe base64）；
  2. 用 RESTORE_KEY 加密当前 MASTER_KEY，得 escrow token（v1: 前缀 + Fernet token），写入 data/master_key.escrow；
  3. escrow 随 data/ 备份流转（其内容被 RESTORE_KEY 加密，库/备份泄露也解不开）；RESTORE_KEY 只离线保存：用户抄写 2~3 份（密码管理器 / 纸质 / 可信家人）；
  4. MASTER_KEY 遗失时：运行 scripts/recover_master_key.py，输入 RESTORE_KEY → 解密 escrow 找回 MASTER_KEY → 写回 .env → 重启服务，全量密文可解、零迁移。
• 恢复钥匙形态：系统生成随机强钥匙（已确认），不引入口令派生（防弱口令拖库风险）。
• 恢复入口：一次性 CLI 脚本（已确认），零新增网络接口/攻击面；日常运行不读取 escrow。
• 边界：RESTORE_KEY 自身遗失 = escrow 失效 → 缓解手段是离线多副本抄写；不做 Shamir 秘密拆分（单用户规模过度设计）。
• 托管对象是 key 本身而非用户数据：escrow 泄露最坏影响 = 需轮换 MASTER_KEY，不直接暴露任何业务密文（还要同时拿到离线 RESTORE_KEY 才有意义）。

3.2 实现清单

• app/core/crypto.py 增加（不动现有 encrypt/decrypt 与 lru 缓存）：
  • _fernet_from_key(key: str) -> Fernet：按给定 key 构造独立实例（不走 MASTER_KEY 缓存）。
  • build_escrow(restore_key: str) -> str：读 settings.MASTER_KEY，返回 'v1:' + Fernet(restore_key).encrypt(master_key_bytes)。
  • recover_master_key(restore_key: str, escrow: str) -> str：解析 v1: 前缀并解密，失败抛错（钥匙错误/文件损坏）。
• 新增 scripts/setup_key_escrow.py：
  • 生成 RESTORE_KEY（Fernet.generate_key()）；
  • 立即用 build_escrow + recover_master_key 回验自检；
  • 写入 data/master_key.escrow（权限 0600）；幂等：文件已存在且回验通过则跳过并提示，--force 才重建；
  • 终端仅此一次打印 RESTORE_KEY，附保存建议（3 个离线位置），随后清屏提示已保存到 .env 旁说明文件（data/master_key.escrow.README，含步骤简述、不含钥匙）。
• 新增 scripts/recover_master_key.py：
  • --key <RESTORE_KEY> 必填（也支持环境变量 RESTORE_KEY，避免 shell 历史残留）；
  • 读 data/master_key.escrow → recover_master_key；失败提示"恢复钥匙错误或 escrow 损坏"；
  • 默认仅打印找回的 MASTER_KEY；--write 则备份 .env 为 .env.bak-pre-recover 后回写 MASTER_KEY 行，提示重启服务。
• .gitignore：确认 data/ 已忽略（escrow 绝不进 git）；M0 落地时手动把 escrow 文件复制一份到离线备份介质。

3.3 M0 验收门槛

1. 本地运行 setup 脚本生成 escrow，终端显示 RESTORE_KEY（留存截图一次后即离线保存）。
2. 丢失演练：备份 .env → 用错误 MASTER_KEY 启动，验证真实数据解密失败 → 运行 recover（不带 --write）找回原 key → 回写 .env → 重启 → 既有真实账号密码可正常解密查看。
3. escrow 文件权限 0600、未纳入 git、已复制离线备份。

4. 数据模型

4.1 新表 credentials

app/models/credential.py，挂 assets.db：

列	类型	说明
id	int PK
site	str, index	站点/服务名（如 "GitHub"、"阿里云"），迁移自平台名
username	str, index, nullable	登录用户名/邮箱
login_type	str, default 'password'	password / oauth / other
oauth_provider	str, nullable	授权来源：google / apple / github / wechat 等
password_encrypted	str, nullable	Fernet 密文；oauth 为空
otp_secret_encrypted	str, nullable	Fernet 密文，存 base32 secret（不存 otpauth URI，可随时重建）
url	str, nullable	登录页地址（可选跳转）
note	str, nullable	备注
created_at / updated_at	datetime	与 Asset 同款 utcnow 模式

• 不建 (site, username) 唯一约束（SQLite 对 NULL 不友好 + 同站多账号合法）；服务层创建时提示重复但允许继续。
• 2FA 展示所需信息均从 secret 派生：issuer=site、account=username，导出时可重建 otpauth URI。

4.2 accounts 加列

Account 增加 credential_id: Optional[int] = Field(default=None, foreign_key="credentials.id", index=True)。

4.3 相关文件

• app/database.py：init_db 的 asset_models 加入 Credential；_migrate_assets_db 增加迁移函数（见 §5）。
• app/main.py：include_router(credentials.router)。

5. 幂等迁移（_migrate_assets_db 内）

_migrate_credentials():
1. accounts 表存在时：若无 credential_id 列 → ALTER TABLE accounts ADD COLUMN credential_id INTEGER
2. 建表/加列后执行 backfill（幂等条件：credential_id 已非空则跳过）：
   遍历 accounts 中 login_password_encrypted 非空 且 credential_id IS NULL 的行：
     site     = providers.name（platform=slug 匹配）→ 否则 platform → 否则 '未分类'
     username = COALESCE(login_user, name)
     login_type = 'password'
     password_encrypted = 原密文原样搬入（不解密再加密，避免中间态暴露）
     credential_id = 新行 id
     搬入成功后置空 accounts.login_password_encrypted（唯一事实源，防双份漂移）
3. 为 credentials 建索引 ix_credentials_site / ix_credentials_username（IF NOT EXISTS）

执行前必须备份：cp data/assets.db data/assets.db.bak-pre-vault（本地与生产各自执行一次，人工确认）。

回滚：git revert 后执行逆迁移（credential.password_encrypted 写回 account.login_password_encrypted 并解除关联）——单用户数据量小，直接在 sqlite3/脚本内完成，仅在需要时编写。

6. 后端改动清单

6.1 新增 app/core/totp.py（无依赖）

• b32decode(secret)：容错去空格/补 =。
• totp_at(secret_b32, ts=None) → (code6, period_left_seconds)：RFC 6238 标准实现。
• verify(secret_b32, code, window=1)：允许 ±1 步进（录入校验容时钟偏差）。
• parse_otpauth_uri(uri) → {secret, issuer, account}：支持用户直接粘贴 otpauth://totp/... 录入（仅取 secret 入库，issuer/account 仅回填建议）。
• random_secret()：secrets 生成 20 字节 → Base32（供"生成随机密钥"按钮，可选）。

6.2 新增 app/schemas/credential.py

CredentialBase:  site, username, login_type='password', oauth_provider, url, note
CredentialCreate: CredentialBase + password(明文, 可空) + otp_secret(可空) + otp_code(可空)
CredentialUpdate: 全字段可空；password: None=不改，''=清除，非空=重加密（沿用 Account 惯例）
CredentialRead:  id, site, username, login_type, oauth_provider, url, note,
                  has_password, has_otp, account_name(可空，反向关联的账号名), created_at, updated_at
OtpBindRequest:   secret(必填), code(必填, 6位)      # 录入必须过校验

6.3 新增 app/services/credential_service.py

• list_credentials(session, q, login_type, has_otp)：搜索 site/username/note；反向查 account 填充 account_name。
• create_credential：(site, username) 重复时允许但返回提示（校验在路由层给 warning 字段或直接允许）；password 用 crypto.encrypt；otp 见 §6.5。
• update_credential / delete_credential。
• reveal_password(credential_id) → {username, password}（同账号 reveal 语义）。
• bind_otp / unbind_otp / current_otp（见 §6.5）。
• 依赖注入、404、加密方式与 account_service 完全同构。

6.4 新增 app/routers/credentials.py（prefix /api/credentials）

方法	路径	鉴权	说明
GET	`` ?q=&login_type=&has_otp=	读	列表
POST	``	require_api_key	创建（含可选 otp 绑定）
PUT	/{id}	require_api_key	更新（含改密/清密）
DELETE	/{id}	require_api_key	删除凭据（不动任何账号/资产）
GET	/{id}/password	require_api_key	解密查看密码
GET	/{id}/otp	require_api_key	{code, expires_in}；未绑定 404
PUT	/{id}/otp	require_api_key	OtpBindRequest，verify 通过才存
DELETE	/{id}/otp	require_api_key	解绑 2FA

• GET /otp 返回 Cache-Control: no-store（动态码防缓存）。
• 所有写操作与账号/资产路由一致使用 require_api_key（内网放行规则自动生效）。

6.5 2FA 绑定与生成规则

• 绑定：secret + 用户当前 6 位码 code 一起提交 → 服务端 verify(secret, code) 通过才加密入库，失败 400「验证码不匹配」（防止 secret 手误录入成废条目，沿用 GitHub 添加 TOTP 模式）。
• 生成：current_otp 用 totp_at 算出 {code, expires_in}；前端本地倒计时、到 0 重新请求（不轮询）。

6.6 改造 app/services/account_service.py

• _to_read：has_login_password 改判 bool(account.credential_id)；AccountRead 增 credential_id、has_otp 两字段（schema 同步加，均默认 False/None，兼容老前端）。 has_otp 需查关联 credential —— list 时批量取 credential_id in (...) 后填充。
• create_account：保存 login_password 时（解密前不落库）：
  • 同一事务内创建 credential（site=平台显示名规则同迁移，username=COALESCE(login_user,name)），记 account.credential_id。
• update_account：改名/换平台时同步 credential.site/username（保持引用一致）；login_password 非空 → upsert 到关联 credential（没有则新建并回填 id）；'' → 清 credential.password；None → 不动。
• reveal_password：改从关联 credential 解密（未关联 → 404 同旧语义）。
• delete_account：不删 credential（生命周期解耦，凭据库独立留存）。

6.7 AccountRead schema 扩展

credential_id: Optional[int] = None
has_otp: bool = False

7. 前端改动清单

7.1 导航与路由（app.js + static/js/views/vault.js 新建）

• NAVS 增加 { key: 'vault', label: '凭据库', icon: '🔐' }（放在「平台」之前）。
• VIEW_MAP 增加 vault: 'vault-view'。
• 新建 static/js/views/vault.js：VaultView 组件。
• index.html 在 modals.js 之前加入 <script src="/static/js/views/vault.js?v={{ asset_version }}">。
• app.js 注册 app.component('vault-view', VaultView)。

7.2 凭据库视图（vault.js）行为

• 头部：搜索框（site/username/note，复用资产页搜索样式）；「+ 新增」。
• 列表：每行 site + username，徽章：登录方式（密码=无/隐藏值 ••••••、Google 授权 等、其他）；2FA 蓝色徽章；有密码行提供 复制密码 按钮（fetch password 后 clipboard）；点击行 → 展开详情。
• 展开详情：url（可点击跳转）、note、关联账号（若有，account_name 显示"来自平台账号"）、操作：显示/复制密码、编辑、删除。
• 2FA 区块（has_otp 才显示）：大字 6 位码 + 倒计时秒（expires_in 驱动本地 1s tick，归零重新请求 GET /otp）+ 复制验证码 + 解绑。
• 空态：提示"从平台账号迁移的凭据会自动出现在这里"。

7.3 凭据表单（扩展 modals.js 或新建 CredentialModal）

• 字段：site*、username、url、login_type 下拉（密码登录/授权登录/其他）、oauth_provider（login_type=oauth 时出现，含常用建议 google/apple/github/wechat + 自由输入）、password（type=password，编辑时留空=不改）、note。
• 2FA 区块：secret 输入框（或粘贴 otpauth:// URI 自动解析填入）+「获取当前验证码」辅助说明 + 当前 code 输入（6 位，必须填，提交时服务端校验）→ 校验失败原地报错不落库。
• 保存后刷新列表 + loadAccounts()（账号关联展示需要）。

7.4 账号体系联动（modals.js / accounts-view 相关）

• 账号列表（accounts-view-modal）与账号弹窗的"查看密码"按钮逻辑不变（后端已重定向）。
• 若账号关联凭据且有 2FA：查看密码弹窗旁增加「获取验证码」按钮 → 调 GET /api/credentials/{credential_id}/otp 展示动态码（复用展开详情的 2FA 组件逻辑，独立小函数）。
• 平台页账号入口保持不动。

7.5 store.js / api.js

• store.credentials + loadCredentials()，loadAll() 并联加入。
• CRUD 函数与 credentialModal state（复制 saveAccount 的 saving 锁模式防双击）。
• Fmt.LOGIN_TYPE_LABELS = { password: '密码', oauth: '授权登录', other: '其他' } 与 oauth provider 徽章色。

8. 交互打磨（M4，占位待用户圈选后启动）

用户对交互尚有保留意见，此处列候选独立小改动，启动前由用户勾选范围：

1. 全局 toast「已复制」取代旧式 alert/瞬时无反馈（可做成 store.toast + 简单组件）。
2. OTP 环形/进度条倒计时视觉 + 复制即消失反馈。
3. / 快捷键聚焦当前页搜索框（移动端不启用）。
4. 账号查看密码弹窗合并进凭据详情（统一交互路径，减少两套弹窗）。
5. 快速录入：从平台账号弹窗一键「补全 2FA」跳凭据表单并预填 site/username。
6. 二维码录入（需要引入前端 QR 解码库/后端解码，成本高，默认不做，除非用户点名）。
7. 双击行快速复制密码、长按移动端复制。

M4 独立成 goal/任务执行，不阻塞 M0–M3。

9. 测试与验收

9.1 pytest（tests/ 新增 test_totp.py、test_credential_migration.py）

• RFC 6238 附录 B 官方向量（secret = ASCII "12345678901234567890" 的 Base32，T=59 / 1111111109 / 1111111111 / 1234567890 / 2000000000 / 20000000000，8 位转 6 位 = 取模 1000000 补零）逐条断言 code 与 expires_in。
• parse_otpauth_uri 解析标准 URI 与缺 issuer 容错。
• 迁移幂等：造含密码账号 → 跑两次 backfill → 只产生一条 credential、account 密码字段已清空、第二次不重复建。
• 绑定校验：错 code 拒绝、对 code 落库、current_otp 用固定时间戳种子断言稳定性。
• escrow 回验：build_escrow 后 recover_master_key 能还原 MASTER_KEY；错误钥匙抛错。

9.2 本地端到端（必做，提交前）

1. .venv/bin/uvicorn app.main:app --port 8000（项目根 vps-manager/ 下，load_dotenv 自动读 .env）。
2. 先完成 M0 丢失演练（见 §3.3）。
3. 手动建测试凭据（含 oauth 条目 + 2FA 绑定真实 secret，用手机验证器/在线 TOTP 工具对码）。
4. 浏览器逐项验证：列表搜索、复制密码、OTP 倒计时刷新、账号弹窗查密码仍可用、新增账号自动生成凭据条目。
5. 迁移干跑：确认生产量级账号行全部迁移、无残留明文。
6. 截图留存（本地验证 + 产物截图惯例），再 git commit + push。

9.3 生产验证（cc1 自动部署后）

• git push origin main → cc1 timer 拉取更新（deploy.sh 若再出现 git push 卡住，按经验手动 git push origin main 干预）。
• 生产环境先备份 data/assets.db，确认 /health 新 commit。
• 生产也执行 M0 setup（生成新 escrow + RESTORE_KEY 离线保存）。
• 端到端抽查：老账号密码可见、2FA 录入→对码成功→删除测试数据。
• 确认 VERSION/commit 展示与静态资源版本（?v= mtime 机制自动生效，无需手动）。

10. 里程碑与验收门槛

里程碑	内容	完成门槛
M0	Key Escrow 托管（crypto 扩展 + setup/recover 脚本 + escrow 文件）	丢失演练通过（§3.3）；pytest escrow 回验绿
M1	模型/schema/totp/迁移/credential service+router/account_service 改造 + pytest	全绿；迁移干跑幂等
M2	vault 视图 + CredentialModal + 账号联动 + store/api	本地端到端截图验证通过
M3	commit → push → cc1 生产验证（含生产 escrow 建立）	生产抽查通过，无回归
M4	交互打磨（圈选后另行启动）	独立

11. 风险与注意

• 迁移前必须备份 assets.db（本地与生产各一次），迁移函数幂等可重跑。
• 迁移/回滚脚本只搬密文、不落明文，避免中间态暴露。
• RESTORE_KEY 一旦遗失 escrow 即失效 → 落地时强制抄写 3 个离线位置，并保存一份 escrow 到离线介质；.env 与 escrow 尽量分介质存放。
• 旧前端页面在部署后需刷新（HTML no-cache + asset_version 已保证）。
• credentials 是个人全量密码仓库：reveal / otp 接口均走 require_api_key，Tailscale 内网直连放行策略不变；前端不落任何明文到 localStorage（仅展示期内存持有）。
• 依赖零新增：requirements.txt / .env 均不改（MASTER_KEY 已存在；RESTORE_KEY 只作为脚本参数/环境变量出现，不常驻配置）。
• 本 spec 为凭据与 2FA 的完整闭环；账号的 api_config_encrypted（SDK 密钥）不在本次范围（后续可演进为"API 凭据"视图，不阻塞）。