Appearance
修改主密码与忘记主密码(开发说明)
日期:2026-11-16(新加坡时间)。设计和取舍见 design.md 第 4.1 节。全部测试只用合成数据和临时 PASSNO_HOME,没有碰真实保险库和钥匙串。
代码在哪里
| 层 | 文件 | 做什么 |
|---|---|---|
| 保险库 | crates/passno-vault/src/password.rs | AccountKeyRewrap 记录、AccountKeyChain(加载、校验签名、按 prev_sha256 连成链、选当前代、沿旧 AUK 往回走)、verify_public_rewraps(给同步用) |
| 保险库 | crates/passno-vault/src/vault.rs | Vault::change_master_password(先写记录、再换文件头);open_returning_auk 遇到旧文件头时迁移;open_with_auk 遇到旧文件头报 PasswordChanged;新设备加入用当前代;两台同时改时的重新登记 |
| 保险库 | crates/passno-vault/src/reset.rs | move_vault_aside:把 $PASSNO_HOME 里除 run/、moved-aside/ 以外的全部移到 moved-aside/vault-<毫秒>/,vault/ 最后移;有待办标记,可重入 |
| 同步 | crates/passno-sync/src/transport.rs、engine.rs | 新对象类型 AccountKeyRewrap(只写一次);拉取前语法检查,暂存区里校验签名和链 |
| 服务 | crates/passno-service/src/password.rs | change_master_password(CurrentProof, 新密码)(Password 或 FreshBiometricAuk)、move_vault_aside |
| 解锁 | crates/passno-unlock/src/unlocker.rs | refresh_biometric_wrap;Touch ID 包裹遇到新密码时删除并报 MasterPasswordRequired(PasswordChanged);主密码解锁后如果文件头换了代就自动重新包裹 |
| passnod | crates/passno-daemon/src/password.rs | IPC change_master_password、move_vault_aside;配对 iPhone 标记“需要重新配对” |
| CLI | crates/passno-cli/src/passwd_cmd.rs | pn passwd、pn reset --move-aside |
| FFI | crates/passno-ffi/src/lib.rs | change_master_password(current_password?, current_auk?, new_password) -> 新 AUK、move_vault_aside() -> 路径 |
| Mac App | apps/desktop/src/components/MasterPasswordSection.tsx、ForgotPasswordDialog.tsx、UnlockScreen.tsx、PhonePairingSection.tsx | 设置 → 安全与解锁 → 修改主密码;解锁页“忘记主密码?”;iPhone 需要重新配对的提示 |
| iOS | apps/ios/PassnoApp/ChangeMasterPasswordView.swift、ForgotPasswordView.swift,PassnoKit/PassnoSession.swift | 设置 → 修改主密码;解锁页“忘记主密码?”;Face ID 重新包裹 |
IPC
method | params | 返回 | 谁能调 |
|---|---|---|---|
change_master_password | { current_password?: string, new_password: string } | account { biometrics: refreshed|disabled|off, phone_needs_repair, other_devices } | 需要已解锁;App,或已有主人会话的终端。current_password 省略时 passnod 弹一次 Touch ID / Apple Watch(只限 App,不接受登录密码) |
move_vault_aside | { confirmed: true } | account { moved_to, old_vault_id, deleted: false } | 锁着也能用;App,或有终端的命令行,并且都要过本人确认(Touch ID / Apple Watch / 登录密码)。确认在 core 锁外弹出 |
phone_approve status 增加 capability_stale:主密码改过、iPhone 还没重新配对。新错误码 PasswordChanged(退出码 3):用的是旧代的主密码或旧 AUK。MasterPasswordRequired 新增原因 password_changed。
请求和返回的 Debug 都不打印密码;返回里只有元数据。
命令行
pn passwd(别名pn change-master-password):终端里依次隐藏输入当前密码、新密码、再输一次;脚本用--password-stdin给两行(当前、新)。没有终端又没有--password-stdin时退出码 2,从不提示。锁着时先用当前密码解锁,已解锁时用当前密码给这个终端授权,然后修改。环境里有PASSNO_AGENT_KEY或PASSNO_SERVICE_TOKEN时退出码 8。pn reset --move-aside:必须是交互终端(标准输入和标准错误都是终端),输入START OVER,再过一次本人确认。否则退出码 8。- 两条命令都写进了
pn agent-help:agent 不要自己运行或建议;遇到PasswordChanged请人用新密码解锁。MCP 没有对应工具。
测试
| 测试 | 覆盖 |
|---|---|
crates/passno-vault/tests/password_change.rs(9 项) | 旧密码失效、新密码打开、条目不变;存下的旧 AUK 打不开;错误的当前证明或 Secret Key 什么都不改;提交点之后崩溃(记录已写、文件头没换)仍能用新密码打开且旧密码被拒;提交点之前崩溃旧密码照用;另一台同步设备用新密码迁移、继续写入并互相同步;新设备只能用新密码加入;落后两代的设备沿链迁移;两台同时改时收敛到一个密码;篡改记录被拒 |
crates/passno-vault/src/reset.rs(2 项) | 移走全部本机状态、保留 run/、旧库在新位置仍能打开、同一个 home 可以新建、再次重新开始用新文件夹;没东西可移报错;中途崩溃后再执行接着完成 |
crates/passno-sync/tests/password_change_sync.rs(2 项) | 经文件夹存放位置:另一台设备拉到记录后旧密码报 PasswordChanged、新密码打开并继续双向同步;第三台设备从存储恢复只能用新密码;存储里伪造的记录被同步拒绝,本地不受影响 |
crates/passno-unlock/tests/password_change_tests.rs(2 项) | 改密码的 Mac 上 Touch ID 继续可用;另一台 Mac 同步后旧 Touch ID 包裹被拒并删除,新密码可用;另一台先用新密码解锁时自动重新包裹 Touch ID |
crates/passno-daemon/tests/password_change_tests.rs(3 项) | passnod:错误当前密码、弱密码不改;用当前密码改,旧密码失效、Touch ID 继续可用;忘了密码时用 Touch ID 改;返回里没有密码;锁着时重新开始、未确认被拒、本人确认失败被拒、旧库在新位置仍能打开 |
crates/passno-daemon/tests/cli_items_tests.rs passwd_through_passnod_… | 真实 pn + passnod:agent 环境退出码 8;没终端没 --password-stdin 退出码 2;pn reset 没终端退出码 8;错误当前密码退出码 3;修改后旧密码解锁退出码 3、新密码成功、条目还在;输出里没有密码 |
crates/passno-ffi/tests/password_change.rs | iOS 路径:锁着不能改;当前密码改;Face ID 解开的 AUK 改;旧 AUK 失效;重新开始 |
apps/desktop/src/test/master-password.test.tsx(5 项) | 设置里改密码并验证旧密码失效;错误当前密码和两次不一致的提示;用 Touch ID 改并显示 iPhone 需要重新配对;“忘记主密码?”说明和确认后的重新开始;Touch ID 可用时从说明里解锁并转到修改 |
apps/ios/PassnoKitTests/PassnoKitTests.swift testChangeMasterPasswordAndStartOver | 会话层:错误当前密码;当前密码改;Face ID 重新包裹后仍能解锁;用 Face ID 改;重新开始后回到首次设置 |
界面检查清单(docs/ui/style.md,逐条过了一遍)
- 闪屏: 修改主密码是普通弹窗(已有
Modal,入场动画不用transform);错误提示区预留了一行高度,出现错误时弹窗不变高;Touch ID 选项要等daemon_status返回才显示,显示的是弹窗里最下面一行小字链接,不推动表单。“忘记主密码?”是解锁卡片里固定位置的一行小字,打开弹窗不影响解锁页。 - 交互: Tab 顺序是当前密码 → 新密码 → 再输一次 → 取消 → 修改;Enter 提交;Esc 关闭(忙的时候不能关)。按钮在条件不满足或进行中时禁用,进行中显示“正在修改…”或“等待 Touch ID…”。当前密码错了清空当前密码框,其余保留。重新开始要先勾选“我明白”,按钮才可用,还有“返回”。
- 看到的是什么: 只有平实的话,没有错误码和路径以外的内部格式(重新开始成功后直接回到首次设置)。成功后在设置里留一句结果:Touch ID 是否继续可用、iPhone 是否要重新配对。
- 多余元素: 设置里只多了一张卡片和一个次要按钮;解锁页只多一行小字链接。不常用的“重新开始”藏在说明弹窗的第二步。
- 优雅: 每个弹窗只有一个主按钮(修改主密码 / 用 Touch ID 解锁),危险操作用
danger样式;表单用FormGroup/FormRow,标签不超过 4 个字。 - 切换: 弹窗两步之间只换内容,不重新挂载弹窗;沿用 150–200 ms 的淡入。
- 悬停点击: 沿用
Button的按下态和禁用态,链接悬停只改颜色和下划线,不改布局。
iOS 版用系统 List 分组、SecureField 和系统 alert,标题用原生导航栏;危险按钮用 role: .destructive,同样先打开“我明白”开关。
还没做 / 需要人看
- 配对 iPhone 的解锁能力不会自动更新,要在 Mac 设置里重新配对(界面有提示)。自动下发新能力需要改手机协议。
- 用配对 iPhone 的一次批准来代替当前主密码(Mac 上没开 Touch ID、只靠 iPhone 解锁时)没有做;这时请在 iPhone 上用 Face ID 改,或输当前主密码。
- 首次设置页(
FirstRunScreen.tsx,另一条工作线在改)重新开始后可能会在“发现的保险库”里列出旧库(iCloud 里的副本),需要那边决定要不要加“忘记主密码?”的链接。 - 真机上的 Touch ID / Face ID 弹窗、Secure Enclave 重新包裹、钥匙串授权要本人在场验收(plan.md 最前面的表)。