Appearance
passno 设计(草案,2026-11-16)
passno 是开源密码管理器,人和 AI agent 共用。跨平台(macOS / Windows / Linux,移动端以后再做),不用服务器同步,v1 就支持家庭和小团队共享,可以从 1Password 和 Apple 密码迁移。许可证为 Apache-2.0 / MIT 双许可。
调研依据见 docs/research/01–04。GPL 项目(KeePassXC、Bitwarden 客户端、Rowel 应用部分、Proton Pass)只参考思路,不复制代码。
1. 原则
- agent 默认拿不到明文。 agent 能做的是"用"密钥:注入到一条命令、代发一个 HTTP 请求、代填一个网页表单、代签一次 SSH。要直接取出明文,必须是条目上单独开过的例外,而且每次都要人确认。
- 所有改动都签名,每个文件只有一个写入者。 这样不用服务器也能做多设备同步和多人共享,而且能检测篡改和回滚。
- 核心逻辑全在 Rust 里。 后台进程、CLI、浏览器扩展、管理界面、以后的 Swift 扩展都只是客户端,规则只在一个地方实现。
- SOLID: 格式、加密、同步传输、平台解锁、IPC 身份校验、导入器各自放在独立的 trait 后面。加一个平台或一种导入格式,就是加一个实现,不改已有的分支。
2. 组件
crates/
passno-model 条目数据模型(纯数据,无 I/O)
passno-crypto KDF / AEAD / 签名 / 密钥包裹(只依赖 RustCrypto 等纯库)
passno-vault 操作日志、快照、纪元、成员日志、合并(HLC)
passno-activity 活动记录:每台设备的签名、加密、哈希链日志,压缩与校验(7.2)
passno-sync trait SyncTransport:Folder(iCloud/Syncthing/Dropbox)、Git
passno-import trait Importer:OnePux、OnePasswordCsv、AppleCsv、Cxf
passno-gen 密码 / 口令生成、网站密码规则(PMR)、强度估算
passno-match URL 匹配(PSL、PMR 共用账号域名组)
passno-totp TOTP / otpauth 解析
passno-unlock trait Unlocker:Password、MacSecureEnclave、WindowsHello、LinuxPolkit
passno-ipc 协议定义 + trait PeerVerifier(每个系统一个实现)
passno-agent 授权引擎、审计日志(哈希链)、代执行(run/inject、HTTP 代理、SSH)
passno-daemon passnod:持有密钥、自动锁定、审批请求、对外提供 IPC
passno-cli pn:给人和 agent 用的命令行(含 MCP server:`pn mcp`),随 App 一起安装(见第 12 节)
passno-nmhost 浏览器 native messaging 转发程序
passno-ffi UniFFI 绑定,给 iOS / macOS 的 Swift 代码用
passno-diag 本机崩溃报告:只存编译期就固定的信息,从不上传
apps/desktop Tauri v2 管理界面,也负责审批弹窗;安装包里同时带 pn、passnod、passno-nmhost
extension/ Manifest V3 扩展(TypeScript),一套代码支持 Chrome/Edge/Firefox;Safari 版由 apple/ 打包
apple/ Swift:AutoFill provider(iOS + macOS)、CXF 导入、Safari 扩展;iOS 主 App(阶段 6 验证后定用 Tauri 还是 SwiftUI)
(以后)windows/ 通行密钥插件(MSIX)分层依赖:
- model ← crypto ← vault ← (sync, import) ← daemon ← (cli, nmhost, desktop)。
- 上层只依赖 trait,具体实现在启动时注入。测试时换成假实现:内存目录、假解锁器、假的对端校验。
3. 数据模型
- Item 包含:
id、vault_id、kind(Login / Password / Note / Card / Identity / SshKey / ApiCredential / Document / Wifi / Custom)、title、urls[](每条带匹配模式)、fields[]、totp[]、passkeys[]、attachments[]、tags[]、favorite、archived、history[]、agent_policy、created、updated。 - Field 包含:
label、value、type(text / concealed / email / url / phone / date / monthYear / address / menu / reference / file)、section、designation(username / password / none)。 - 导入时映射不了的字段一律变成自定义字段,不丢数据。导入完给出报告:每个来源导入了多少条、哪些字段被降级。
4. 密钥结构
主密码 ──Argon2id(m=64MiB,t=3,p=4)──┐
Secret Key(128 位,默认开启)───────┴─HKDF→ AUK(账户解锁密钥)
AUK 包裹 → 成员私钥:X25519(加密)+ Ed25519(签名);每台设备一对设备密钥
保险库纪元密钥(256 位,随机)→ 用每个成员的 X25519 公钥分别包裹(HPKE)
条目 → XChaCha20-Poly1305,AAD = vault_id ‖ item_id ‖ epochSecret Key 默认开启(用户 2026-11-16 定)。初始化时生成,同时给出应急套件(PDF 或二维码),提示用户打印或存放在别处。高级选项里可以关掉,只适合不同步的本地保险库。
平时解锁用 Touch ID、Face ID、Apple Watch,不用每次输主密码(用户 2026-11-16 定):
- macOS:
- v0.2 实现:生成 256 位随机设备本地包裹密钥,写入受
kSecAttrAccessibleWhenUnlockedThisDeviceOnly与BIOMETRY_CURRENT_SET | OR | WATCH保护的 macOS 数据保护钥匙串(需带权限签名的 App bundle;本地 ad-hoc 签名无 entitlement 时回退到本机登录钥匙串 +LAContext策略评估与evaluatedPolicyDomainState指纹集哈希校验),并用该包裹密钥通过 XChaCha20-Poly1305(AAD =passno-bio-auk-v1)加密 AUK 存放在$PASSNO_HOME/local/biometric_auk.json。后续签署 Developer ID 并启用钥匙串权限组后,可平滑升级为安全飞地 P-256 ECIES 包裹。 - Mac 上允许 Touch ID 或 Apple Watch 确认(
LAContextDeviceOwnerAuthenticationWithBiometricsOrCompanion)。 - 新录入或删除指纹(
evaluatedPolicyDomainState变化)、重启、超过 14 天或修改安全设置后,生物识别失效,必须重新输一次主密码。 - 完整硬件绑定与数据保护钥匙串需要签名并带权限的 App bundle。
- v0.2 实现:生成 256 位随机设备本地包裹密钥,写入受
- iOS: AUK 使用 Secure Enclave P-256 ECIES 包裹和
biometryCurrentSet访问控制,失败拒绝;模拟器替代存储仅编译于 simulator,详见第 13 节。Rust 侧复用 main 的 AUK 打开路径,继续验证成员日志、纪元与回滚状态。 - Windows: Windows Hello 签挑战,再对签名做 HKDF。2026-11-16 实现(
passno-unlock/src/windows.rs,在虚拟机实测前只经过交叉编译):- 每个保险库在 TPM 里建一把 Windows Hello 密钥(
KeyCredentialManager,名字passno-<vault_id>;RSA PKCS#1 v1.5,同一内容的签名每次相同)。 - 解锁时对
passno-windows-hello-wrap-v1:<vault_id>签名(会弹 Windows Hello),用 HKDF-SHA256(salt 为域名串,info 为 vault_id)从签名派生 32 字节密钥,再用 passno-crypto 的 XChaCha20-Poly1305(AAD 为 vault_id)解开$PASSNO_HOME/local/hello-wrap-<vault_id>.json里的包裹密钥。后面的 AUK 路径和 macOS 相同。 - 理由: 只组合 TPM 签名、RustCrypto HKDF 和已有 AEAD,不新造原语;密钥不出 TPM,每次解锁都要本人过 Windows Hello;文件被拷走也解不开。KeePassXC 和 Bitwarden 用同样思路(都是 GPL,只看思路)。Windows Hello 被重置时密钥消失,解锁报“缺少绑定”,回到输主密码。Windows Hello 不提供指纹集摘要,所以“指纹有变化必须输主密码”这条在 Windows 上靠密钥失效来体现。
- Secret Key 存在 Windows 凭据管理器(DPAPI 按用户保护,
CRED_PERSIST_LOCAL_MACHINE,不漫游),写失败退回 0600 文件,同 macOS 的回退方式。 - “批准 agent 看明文”的本人确认在 Windows 上用
UserConsentVerifier(人脸、指纹或 PIN)。
- 每个保险库在 TPM 里建一把 Windows Hello 密钥(
- Linux: 主密码,加 Polkit。
- macOS:
生物识别只是便利,不能替代主密码。 以下情况必须输主密码:
- 重启后第一次解锁;
- 距上次输主密码超过 14 天(可调);
- 指纹有变化;
- 加新设备;
- 修改共享成员或安全设置。
这样主密码不会被忘掉,安全飞地也不会成为单点。
Secret Key 在苹果设备之间同步: 存进 iCloud 钥匙串(可同步、端到端加密),用户可以关掉。这样新的 Mac 或 iPhone 只要登录同一个 Apple ID,再输一次主密码就能用,不用扫码。钥匙串条目的可读级别是“开机后首次解锁之后”(
kSecAttrAccessibleAfterFirstUnlock,后台服务常用的级别),Mac 锁屏时 passnod 也读得到,经 ssh 运行pn unlock不会失败;单有 Secret Key 打不开保险库,还要主密码。旧条目在下一次成功读取时自动升级。读不到钥匙串时如实报“钥匙串锁着”,不再说成“找不到 Secret Key”(2026-11-18)。- 安全飞地的密钥绑定在单台设备上,不能同步,所以每台设备首次解锁后各自建立 Touch ID 包裹。
- Windows / Linux 设备仍然要扫码或手动输入 Secret Key。
KDF 参数写在文件头里,以后可以升级。
手机批准、电脑临时解锁(用户 2026-11-16 同意,阶段 6 做): 可以把某台 Mac 设成“要手机批准才能解锁”。长期解锁能力(包裹 AUK 的密钥)存在 iPhone 的安全存储里,Mac 磁盘上没有能自动解锁的长期凭据。Mac 发起请求时带一个随机挑战和临时 X25519 公钥;iPhone 显示是哪台电脑、哪个保险库、用途和期限,Face ID 批准后用 HPKE 把本次解锁材料加密给这个临时公钥,并对(挑战、电脑、保险库、到期时间)签名。期限是绝对的(默认 30 分钟),锁屏、休眠、
passnod重启都清除;手机不在就保持锁定,主密码 + Secret Key 仍可作为恢复路径。传输:同一局域网用 Bonjour 直连,不在一处时用 CloudKit 私有数据库加订阅推送,不自建服务器。- 实现协议见 手机批准开发说明。手机批准使用
passno-crypto::hpke的 RFC 9180 X25519/HKDF-SHA256/ChaCha20Poly1305 envelope,签名使用已有 Ed25519 域隔离接口;不改变保险库格式。原 epoch wrapper 仍为已有 ECIES 组合,不能与此 wire 格式混用。
- 实现协议见 手机批准开发说明。手机批准使用
锁定的计时方式(参考
docs/research/05-password-architecture-notes.md):保险库自动锁定按空闲计时(键鼠活动会续期),另有最长会话时长(绝对期限,到点必锁);系统锁屏、休眠、注销、passnod重启都立即锁定。App、pn、插件共用passnod的同一个会话,不允许哪个客户端自己留一份更长的会话。
4.1 修改主密码与忘记主密码(2026-11-16)
用户忘了主密码,才发现 passno 既不能改主密码,也没有任何指引。实现和测试见 修改主密码开发说明。
先比较了三种做法(只看公开文档和思路,GPL 代码一行没看):
| 项目 | 改密码时做什么 | 旧副本 | 取舍 |
|---|---|---|---|
| 1Password(白皮书 附录 A「Beware of the leopard」) | 两把钥匙(密码 + Secret Key)派生 AUK;改密码只用新 AUK 重新加密原来的个人密钥组,不换密钥组;服务器替换旧的加密密钥组 | 拿到旧密钥组又知道旧密码和旧 Secret Key 的人仍能解开,还能读改密码之后的新数据;要换密钥组得走“账户恢复” | 和 passno 的密钥结构完全一样,最直接 |
| Bitwarden(Encryption Key Rotation、Master Password,只看文档) | 默认只用新主密码重新包裹用户密钥,条目不重加密;另有可选的“同时轮换账户加密密钥”,会重加密全部数据并要求其他客户端重新登录 | 同上 | 把“换包裹”和“换密钥”分成两件事,思路和 passno 已有的 pn device revoke-lost 一致 |
| KeePassXC(GPL,只看用户文档和 issue #2176、discussion #3597) | 单文件格式,保存时用新的组合密钥重加密整个数据库 | 旧备份和同步盘里的旧版本仍能用旧密码打开;另一台设备没合并就保存会覆盖掉改动 | 依赖“能覆盖整个文件”,passno 的同步文件一律只写一次,不适用 |
选择:1Password / Bitwarden 默认的做法,加一条只追加的签名记录。 账户密钥(X25519 + Ed25519)不变,只换包裹它们的 AUK。passno 没有服务器,account/<成员>.keys.json 和发现头又是只写一次的同步文件(改内容会被当成分叉),所以不改旧文件,而是追加一个新同步对象:
account/<成员>.rewrap/<写入设备>/<序号> AccountKeyRewrap(版本 1)
generation = 上一代 + 1(keys.json 是第 1 代)
prev_sha256 = 上一代文件的 SHA-256
新的 password_salt、auk_salt(KDF 参数沿用文件头里的)
wrapped_account_keys = XChaCha20-Poly1305(新 AUK, AAD = passno-account-keys-v2:库:成员:代数)
wrapped_previous_auk = XChaCha20-Poly1305(新 AUK, AAD = passno-previous-auk-v1:库:成员:代数, 旧 AUK)
成员 Ed25519 签名(新域 passno-account-rewrap-v1)- 只组合已有原语: Argon2id、HKDF(
derive_auk)、XChaCha20-Poly1305(seal)、Ed25519 签名,都是passno-crypto里已有的函数;passno-crypto没改。保险库格式只新增一种同步对象(旧客户端不认识这个路径,扫描时忽略),条目、操作日志、快照、纪元密钥、keys.json、发现头都不变。 - 为什么要带上旧 AUK: 每台设备本地文件头
vault.header.json里的设备签名私钥只用本机当时的 AUK 包裹。另一台设备只知道新密码时,用新 AUK 解开wrapped_previous_auk一代代往回走,就能打开自己的旧文件头,再用新 AUK 重新包裹(本机文件,原子替换)。这不给任何人新的能力:能解开它的人本来就知道新密码,而旧 AUK 只能打开旧包裹的同一组密钥。 - 哪一代算数: 所有设备都认同一个“当前代”:代数最大,其次时间最新,再按文件哈希。新设备加入、从 iCloud 恢复都用当前代(
enroll_new_device_from_bundle已改)。 - 旧密码失效: 本机改完后,文件头换成新代,旧密码直接打不开。其他设备同步到新记录后,即使本地文件头还是旧的,旧密码、Touch ID / Face ID 里存的旧 AUK、配对 iPhone 交来的旧 AUK 一律被拒绝,报
PasswordChanged(“主密码已在另一台设备上修改,请输入新主密码”)。还没同步到的设备在同步之前仍接受旧密码,这是没有服务器的必然结果,文档和界面都写明。 - 崩溃安全: 先写签名记录(提交点),再原子替换本机文件头。记录写好、文件头没换时崩溃,下次用新密码走上面的迁移路径照样打开,旧密码被拒;记录没写成功则什么都没变,旧密码照常用。任何时刻都至少有一个密码能打开,也不删除任何文件。
- 两台设备同时改: 记录按设备分路径,不会撞同一个文件(不会把同步卡死在分叉上)。两条都是第 2 代时按上面的规则选出当前代;输的那台设备用赢的密码解锁时,旧 AUK 链接不到它的文件头,于是用账户密钥把这台设备重新登记成同一成员的新设备(新设备 ID、签名的
AddDevice),旧设备 ID 已写的签名文件仍然有效。只在这种极少见的情况下设备列表里会多一条旧记录。 - 篡改: 记录必须由
keys.json里固定的成员公钥签名,库 ID、成员、公钥、Secret Key 指纹都要对上,路径里的设备和序号也要和内容一致。同步在接收前就校验(verify_staged_vault_public),伪造的记录进不了本地。
依赖主密码的东西,逐个处理:
| 依赖 AUK 的东西 | 怎么处理 | 理由 |
|---|---|---|
账户密钥包 account/<成员>.keys.json(同步) | 不动;新代写在 .rewrap/ 里 | 同步文件只写一次 |
本机文件头 vault.header.json(不同步) | 用新 AUK 重新包裹,原子替换 | 本机文件,可以替换 |
| 其他设备的文件头 | 下次用新密码解锁时自动迁移(见上) | 不需要在场,也不需要旧密码 |
Mac 的 Touch ID 包裹(passno-unlock) | 改密码的这台 Mac:立刻用新 AUK 重新包裹;失败就关掉并提示到设置里重新打开。其他 Mac:同步后 Touch ID 解锁被拒并自动删掉旧包裹(PasswordChanged),用新密码解锁一次时自动重新包裹 | 包裹的是旧 AUK,留着没用;输了新密码等于重新满足“开 Touch ID 要先输主密码”的规则 |
| iPhone 的 Face ID 包裹(Secure Enclave) | 在 iPhone 上改:立刻用新 AUK 重新包裹。在别处改:Face ID 解锁被拒并关闭,输新密码后再打开 | 同上 |
配对 iPhone 的解锁能力(Capsule 里的 Mac 的 AUK) | 不能远程更新;Mac 标记“需要重新配对”(设置里显示,pn passwd 的 phone_needs_repair),旧能力批准解锁会被拒。快速批准 agent 请求不用 AUK,继续可用 | 胶囊在手机安全存储里,Mac 主动推送新 AUK 要改手机协议,这次不做;重新配对本来就要求主密码会话 |
| 恢复包(iCloud 钥匙串)、应急套件 | 不变 | 里面只有 Secret Key 和存放位置,没有主密码 |
| Secret Key | 不变 | 换 Secret Key 等于换账户,用 pn device revoke-lost |
| 共享库成员身份、agent 子库、服务令牌、活动记录 | 不变 | 都绑在账户 / 设备密钥或令牌上,不绑 AUK |
修改时怎么证明是本人(决定):
- 当前主密码:任何地方都可以(App、
pn passwd、iPhone)。 - 当下的一次 Touch ID / Apple Watch(Mac App)或 Face ID(iPhone):只在 App 里,而且必须是这一次重新解开生物识别包裹拿到的 AUK,不接受 Mac 登录密码兜底,也不接受“刚才解锁过”的会话。理由:忘了主密码时,这是唯一不靠服务器的自助办法;能过这台设备 Touch ID 的人本来就能读出、删改全部条目,改密码没有扩大他的能力;包裹受“重启后、超过 14 天、指纹变了都要先输主密码”的规则约束,新录入的指纹也用不了。代价写在文档里:能过 Touch ID 的人可以让主人在其他设备上用不了旧密码。
- 不接受:只凭已解锁的会话、Mac 登录密码、配对 iPhone 的一次批准(要改手机协议,这次没做,见 plan.md)。命令行只接受当前主密码,
PASSNO_AGENT_KEY/PASSNO_SERVICE_TOKEN在环境里时直接拒绝;MCP 没有这个工具。
这不是换钥: 和 1Password 一样,改主密码不换账户密钥。拿到过旧同步文件、又知道旧密码和 Secret Key 的人,仍能解开旧的 keys.json,从而读到以后的数据。怀疑主密码和 Secret Key 都泄露、或设备丢失时,用已有的 pn device revoke-lost(换账户密钥、Secret Key 和全部纪元密钥)。界面和 pn passwd --help 都说明了这一点。
忘记主密码: passno 没有服务器,找不回主密码。解锁页的“忘记主密码?”照实说明:能用 Touch ID(或 iPhone 上 Face ID)打开的话先解锁再改;应急套件里没有主密码;都不行只能重新开始。重新开始(App、pn reset --move-aside)只在本人确认后执行:锁定、结束所有 agent 授权,把这台设备上的保险库和本机状态整个移到 $PASSNO_HOME/moved-aside/<时间>/(附说明文件),不删除任何东西,其他设备、iCloud 和其他存放位置不受影响;以后想起主密码,把文件移回去就能打开。确认方式:App 里勾选“我明白”,命令行要在终端里输入 START OVER;两者都还要过这台 Mac 的本人确认(Touch ID、Apple Watch 或登录密码)。没有终端的进程(agent)一律拒绝。移动顺序是先写待办标记、最后移 vault/,中途崩溃时旧保险库仍是当前的,再执行一次会接着移完。
5. 存储与同步
<vault-root>/
account/<member>.pub 公钥 + 指纹
account/<member>.keys.json AUK 包裹的账户私钥(第 1 代,只写一次)
account/<member>.rewrap/<device>/<seq> 改主密码后的签名重新包裹(第 2 代起,见 4.1)
vaults/<vault-id>/
members/<device>/<seq> 成员日志(签名、哈希链)
keys/<epoch>/<member> 包裹好的纪元密钥
ops/<device>/<seq> 加密 + 签名的操作(只追加)
snapshots/<device>/<n> 定期快照
blobs/<blob-id> 内容寻址不可变加密附件块(StreamBE32)
activity/<device>/<seq> 活动记录段(加密 + 签名,只追加,见 7.2)
activity-checkpoints/<device>/<seq> 活动记录压缩检查点(见 7.2)- 每个文件只有一个写入者,同步路径一旦写入就不再改变内容;不同内容占用同一路径仍按分叉拒绝。
- 轮换快照(2026-11-16):为避免移除设备后用同一操作序号覆盖已上传快照,
remove_device在新纪元追加加密、签名的EpochRotation标记操作,再以新序号写快照。标记不修改条目,但沿用操作哈希链、HLC、连续序号和本地回滚状态;纪元仍绑定在签名记录及 AEAD AAD 中。重复写同一序号的快照保留原文件,包含自动快照与轮换显式快照重合的情况。路径、快照结构、密钥与加密原语不变;新版本无需迁移即可读取没有标记的旧库。旧客户端在需要重放新标记时不认识该操作,因此参与轮换的客户端应升级。 - 附件采用
aead-stream的StreamBE32<XChaCha20Poly1305>分块流式加密(每块 HKDF 派生密钥 + 全文件头/库/纪元 AAD 绑定),按完整密文 SHA-256 存入blobs/<blob-id>,单文件上限 128 MiB;彻底粉碎条目或删除附件后由本地垃圾回收清理不再被引用的块。 - 附件纪元(2026-11-16):为修复换纪元后旧附件不可读,附件引用增加可选
blob_epoch: u64,记录 blob 加密时的纪元;该字段在加密且签名的操作/快照载荷内,不能由同步存储单独改写。普通上传和导入均记录实际使用的当前纪元;读取使用该纪元密钥及对应 AAD。沿用操作日志的签名密钥包裹记录keys/<epoch>/<member>,轮换保留历史记录供仍获授权的设备同步和读取,无须重加密不可变 blob,不改PNBLB1或密码学原语。 - 旧附件兼容:缺少或为 null 的
blob_epoch时,尝试本成员已有的已验证纪元密钥(当前到历史),每次使用相应 epoch 的 AAD。引用可能随新操作/快照复制,不能假设操作 epoch 就是 blob epoch。候选先完整流式认证并丢弃输出,成功后才重新导出;显式 epoch 失败不回退。仍校验密文内容地址、明文摘要与长度。旧客户端可解析可选字段,但轮换后的旧附件读取需升级到此修复。 - 附件撤销边界:导出前验证本地已同步的成员日志;已撤销设备不能经 API 加载 blob 密钥。新附件使用新随机纪元密钥,历史密钥不能解密;保留历史密钥不会赋予新纪元访问权。账户级恢复凭据失陷的限制见 5.2/5.3,不能将本修复等同于账户凭据吊销。
- 文件名用随机 ID,内容按大小分档补齐,减少元数据泄露。
- 合并规则:按字段取最后写入者(HLC 时间戳,平局时比设备 ID)。并发修改中被覆盖的版本放进历史。
- 本地 SQLite 只是搜索和匹配缓存,可以随时从日志重建。
- 防回滚:每台设备记住每个写入者的最高序号和对应哈希,发现倒退就告警。
5.1 存放位置(用户 2026-11-16 要求:可选,并能自动发现和恢复)
保险库目录里全是密文和签名,存在哪里都一样安全,所以存放位置做成可插拔的 SyncTransport,用户在设置里选,一个保险库可以同时存几处(主存放 + 备份):
| 存放位置 | 实现 | 说明 |
|---|---|---|
| iCloud Drive(苹果设备默认) | SyncLocation::ICloud { vault_dir } → FolderTransport | 存在 App 自己的 iCloud 容器 iCloud.com.virtever.passno 的 Documents/passno/<vault-id>/。位置只记文件夹名,每台设备按自己的容器路径解析(Mac:~/Library/Mobile Documents/iCloud~com~virtever~passno/…;iPhone:系统给的容器 URL),所以 Mac 写的恢复包在 iPhone 上也能用。2026-11-16 起不再用 iCloud Drive 根目录(com~apple~CloudDocs,iOS App 进不去);旧配置照常读取。真正经 iCloud 同步需要两端 App 都签上 iCloud 容器权限 |
| Syncthing、Dropbox、NAS、U 盘 | FolderTransport | 任意会被同步的目录 |
| GitHub 私有仓库(或任何 git 远端) | GitTransport | 每次同步一个提交,从不强推;gh 已登录时可一键建私有仓库 |
| Cloudflare R2、AWS S3、自建 MinIO | S3Transport | S3 兼容接口;每个文件只写一次,用条件写入(If-None-Match: *)防覆盖 |
| 自建服务器 | WebDavTransport,或 S3Transport | 任何 WebDAV(Nextcloud、群晖)或 S3 兼容服务都能当服务器,不需要专门的 passno 服务端。以后如需要推送通知,再出一个极简的 passno-server(只存密文,可部署成 Cloudflare Worker + R2) |
服务器端永远只看到密文;存放位置不可信也不影响安全,最多影响可用性(防回滚靠 5 节的序号和哈希)。
默认备份到 iCloud(用户 2026-11-16 要求,参考钱包 App 的 iCloud 备份): Mac 和 iPhone 新建保险库时,只要这台设备拿得到 App 的 iCloud 容器(签了权限、登录了 iCloud),就默认勾选“备份到 iCloud”,主位置设为 iCloud;之后按已有调度自动同步。拿不到容器时不显示这个选项,以免“看起来备份了,其实只在本机”。只用已有的同步格式和恢复包,不改密码学和保险库格式。
存放位置的凭据(R2 的访问密钥、WebDAV 密码、git 远端地址)本身是秘密,但又不能只放在保险库里,否则新设备打不开保险库就拿不到凭据。所以和 Secret Key 一起放进恢复包。
5.2 恢复包和自动发现(“从 iCloud 恢复”)
恢复包:一条 iCloud 钥匙串里可同步的条目,内容是
{账户 ID, Secret Key, 保险库列表: [{vault-id, 名称, 存放位置及其凭据}]},用钥匙串自身的端到端加密保护。用户可以关掉。iCloud 里的保险库(2026-11-18,用户要求“哪些能删、哪些能改名、哪个正在用,要让用户清楚”):设置 → 存储里列出 iCloud 容器里的每个保险库,加上恢复包里记着、但数据已不在 iCloud 的条目(
passno-sync/src/backups.rs)。每行有名字(同名时加编号前 8 位)、“正在使用”、最后修改时间(文件夹里最新文件的时间)、创建日期(签名库头)、大小,以及新设备恢复要什么(恢复包里有就只要主密码,否则要 Secret Key)。正在使用的不能删。删除要输入库名确认,文件夹移到passno/.trash/<vault-id>@<毫秒>,30 天内可以还原,过期后连同恢复包里的条目一起删掉(恢复包条目留到那时,还原后仍能只凭主密码恢复);数据已不在的条目“清除”只删恢复包里那一条。回收站在容器的下一层,恢复发现只看一层,所以不会被当成可恢复的库。思路参考 Strongbox、KeePassium(移除与删除分开)、1Password 和 Enpass(正在用的库不能删、输名字确认),没有用它们的代码。改名(2026-11-18):vault.json在同步里是只写一次的(内容变了会被当成分叉),所以改名不重签库头,而是追加一条签名的改名记录names/<设备>/<毫秒>({version, vault_id, member_id, name, at_ms, signature},域passno-vault-name-v1,用签库头的同一把成员密钥签)。显示名取通过校验的最新一条,没有就用库头里的名字(passno-vault/src/vault_name.rs)。同步拉取时逐条校验,签名不对按篡改拒绝;旧版 App 不认识names/,会跳过,继续显示原名。只有正在使用、已解锁的库能改名(要它的成员密钥);改完立刻同步一次,恢复包里的名字也跟着改。名称 1–64 个字,不能有控制字符。这是新增的同步对象,不改密码学原语、不动已有文件。新苹果设备(Mac 或 iPhone)登录同一个 Apple ID 后:首次打开 passno 不直接显示“新建保险库”,而是先自动发现:
- 读 iCloud 钥匙串里的恢复包;
- 扫 iCloud Drive 的
passno/目录,读每个保险库未加密的头文件(vault.json:vault-id、名称、创建时间、KDF 参数;不含任何条目信息); - 把两者对上,显示“发现 1 个保险库:个人(存在 iCloud Drive,最近更新 2 小时前)→ 恢复”;
- 用户只输主密码就能打开(Secret Key 来自恢复包),存放位置在 R2 或 GitHub 的也一样,因为凭据在恢复包里。
没有 iCloud 的设备(Windows、Linux)或恢复包被关掉时:用应急套件。应急套件里除了 Secret Key,还印着存放位置(例如
github.com/xxx/passno-vault或 R2 的 bucket 和端点);扫码或手动输入后再输主密码。其他位置的发现:
gh已登录时列出带passno-vault标记(topic)的私有仓库;本机常见同步目录(Dropbox、Syncthing 默认目录)里找vault.json。发现结果只用来少打字,打开前仍然要主密码,并校验头文件签名。命令行:
pn vault discover --json、pn vault restore <vault-id>、pn sync setup --icloud|--folder|--git|--s3|--webdav、pn sync locations。待补(2026-11-16 合并同步时记下):移除设备不等于吊销账户凭据。 新设备扫码拿到的是 Secret Key 和恢复凭据,属于账户级;移除设备会换保险库纪元密钥,但被移除的设备如果还记得主密码,仍可能用账户密钥解开新纪元。所以“设备丢失”要走完整流程:换账户密钥对和 Secret Key、重新包裹各保险库纪元密钥、更新恢复包、提示改主密码。放进第 3 波。
5.2.1 完整吊销实现(sharing 工作线)
pn device revoke-lost 在隔离 staging home 生成新账户 X25519 / Ed25519、新设备身份、Secret Key、AUK 和各库随机纪元密钥,要求不同于旧主密码的新主密码。个人条目(含历史与附件)及 agent 子库迁移到新账户 generation;旧服务令牌不迁移。自己拥有的共享库由旧 owner 签名授权新 owner 身份并换纪元,保留共享库 ID 与其他成员。别人拥有的共享库必须先由其 owner 移除旧身份,本机退出后再继续;预检失败不换任何密钥。
为避免账户包和发现头不可变路径冲突,新个人库使用新 vault/member ID,Folder/S3/WebDAV 使用新子路径、Git 使用新分支。原账户密文留在 revoked/<old-vault-id>/ 作为恢复备份,不再作为活动库。恢复包更新为新 Secret Key、公钥与新位置,应急套件写入权限 0600 的独立文件;CLI/IPC 仅返回文件路径和待改密码清单。所有其他设备必须重新登记,旧设备 AUK、账户私钥、Secret Key 或旧服务令牌都不能打开后续写入。
切换前保存 rekey-pending.json;有未完成日志时普通打开与旧句柄写入均拒绝,pn device resume-revocation 幂等完成恢复存储和目录切换。生成阶段失败只清理 staging,切换阶段失败保留新 generation 供重试。完成后锁定并移除活动生物识别包裹。解锁后需执行个人库和共享库同步;异步存储中尚未传到对方的撤销不能承诺即时生效。
5.3 v0.2 同步实现约定(sync 工作线)
公开发现头 vault/vault.json 与设备本地 vault.header.json 分开:前者只含名称、头创建时间、vault/member ID、KDF 参数、公钥、账户包 SHA-256 和成员签名;后者含设备包裹材料,不参与同步。新增头是为了新设备不用先解锁就能发现保险库,使用既有 Ed25519 签名原语和独立域 passno-discovery-header-v1,不改操作日志密码学。头自身签名只验证内部一致性;恢复前还要和恢复包固定公钥、主密码解出的账户公钥对齐,防止替换整个自签名保险库。
存放位置默认保存在恢复包,普通配置仅存不透明引用;主位置双向同步,备份只接收已验证本地副本。S3/WebDAV 条件写失败(412)只有内容完全相同时才算幂等成功;其余算分叉。恢复先在隔离目录完成验证和新设备登记,再安装到空的本地 home;不会自动覆盖已有库或在认证前上传。
设备二维码包含长期 Secret Key,需要同时知道主密码才能加入;在没有可信在线消费服务时,不能承诺二维码“一次性”。设备撤销强制拒绝旧设备 ID 后续写入并换纪元,但同账户设备已经拥有账户级恢复材料,不能把它解释成对恶意账户持有者的密码学隔离;账户级失陷需要轮换恢复凭据及已暴露密码。恢复包无明文配置回退。
6. 共享
- 加入: 当面核对指纹,或扫邀请二维码。管理员在成员日志里签"加人",再把纪元密钥包裹给新成员。
- 角色: 共享库对外为 owner / editor / viewer(分别管理、读写、只读),写入时和读取验签时都执行;个人库旧枚举暂保持兼容。另有一种 agent 使用权限,见第 7 节。
- 移除: 开新纪元、换新密钥、重加密,并提示其余成员轮换那个人看得到的密码。没有服务器,撤回不了对方已经读过的内容,界面上要说清楚。
- 验证: 读取时拒绝没有写权限的签名。
6.1 共享库独立格式(sharing 工作线)
$PASSNO_HOME/sharing/shared/<uuid>/ 保存 members/<epoch>、ops/<epoch>/<writer>/<seq>、leaves/<invitation-id>。成员记录为 owner 签名的单链,明确包含全体成员、公钥、角色、各成员的纪元包裹、新纪元加密基线和旧操作截止哈希。单个 owner 串行管理;离线分叉拒绝,不靠时间戳选一个管理员。身份轮换由前一个 owner 签署新 owner;本地固定最初指纹,从整条链验证。
纪元基线与操作使用现有 XChaCha20-Poly1305,AAD 绑定库、纪元、成员链哈希、写者、序号、前驱;操作额外由成员 Ed25519 签名,读写两侧拒绝 viewer。每次成员变化均生成新随机密钥并重加密基线,不把旧密钥当作新纪元密钥。仍用现有 X25519/HKDF/XChaCha 包裹函数(ECIES,不是 RFC 9180 HPKE),不修改个人库格式或加密原语。
邀请是绑定收件人公钥的 pnshare1_ 编码,可作为二维码内容;双方核对指纹,接受时验证 owner 签名链、邀请 ID、接收者身份和当前成员资格。本地接受记录只能消费一次,重放不增加权限;复制本地账户恢复材料等于复制同一身份,不能把邀请描述成服务器全局一次性令牌。个人库、Secret Key、账户私钥包不进入共享位置。主动退出发布本人签名请求并立即禁止本地访问,owner 下次同步处理请求并换纪元;离线 owner 尚未处理时不能声称密码学撤销已完成。
详细操作、安全边界和测试见 共享开发文档。
7. agent 访问
agent 不是加密层面的成员,拿不到任何密钥。它们是后台进程里的策略主体。
- 登记:
pn agent enroll <名字>为 agent 生成一个专属凭据,用户在桌面端确认一次。以后每个请求都带上这个凭据,同时后台进程校验调用方的进程树(macOS 用 audit token,Linux 用SO_PEERCRED,Windows 用命名管道的客户端 PID)。 - 能看到的范围: 只有条目上
agent_policy允许、或者所在保险库开了"agent 可用"的条目。agent 只能看到标题、URL 和用户名,看不到密码。 - 操作分档:
| 档位 | 方式 | 明文会到 agent 吗 |
|---|---|---|
| 代填网页 | MCP fill_login / pn fill:经 passno 扩展在你的 Chrome 里填登录表单(可选提交),2026-11-16 实现 | 不会;但 agent 若能控制这个浏览器、在页面里运行脚本,就可能读到填进去的值,所以审批时提醒,和注入命令一样慎批 |
| 代发 HTTP | 本地代理把占位符替换成密钥;绑定 host + path + method;不跟随重定向。密钥只发往条目自己的网站(同一站点,含子域名,规则和自动填充一样)或主人用 --allow-host 允许的主机;条目没有网址又没设允许主机就拒绝;主人还可以用 --allow-path /api/ 限定路径(按路径段匹配,/api 覆盖 /api/v1、不覆盖 /apix,忽略查询参数),防止同一网站上别的页面(比如公开评论)拿到密钥;被拒的尝试都写进审计(2026-11-18 起。原来允许列表为空就放行任何主机,被提示词注入的 agent 能把 {{pn://…}} 发到任意服务器) | 不会 |
| SSH 代签 | passno 充当 ssh-agent;当前仅未加口令的 Ed25519 | 不会 |
| 注入命令 | pn run --env K=pn://… -- cmd(也可 --env-file、--stdin 写进标准输入、--file 写成 0600 临时文件),审批绑定到精确的命令行 | 会到子进程(最弱一档,界面上标黄) |
| 取出明文 | 条目单独允许后,每次都要人确认 | 会(例外) |
- 声明用途: 每个 agent 请求都要带
--reason(MCP 里是必填的reason参数),审批弹窗显示它,审计日志记下它。它只是可审查的说明,不替代审批。 - 授权按绝对时长到期: "N 小时"从批准那一刻算起,使用中不续期。每次授权用新的临时会话密钥,绑定请求挑战、调用方和期限,旧授权不能重放。
- 审批: 桌面弹窗,选项为本次 / 本次运行 / N 小时 / 拒绝(2026-11-16 已实现:仅这一次约 1 分钟、本次运行 15 分钟、1 小时;同日和用户商定:弹窗默认只有“仅这一次 / 直到电脑锁定 / 总是允许”,15 分钟、1 小时、24 小时、7 天收进设置的“更多时长”。“总是允许”是长期权限:同一 agent、同一条目、HTTP 按同一主机,N 天不用自动取消(默认 30),选它要 Touch ID。长授权锁屏时也能用:批准时只把那一个条目复制在 passnod 内存里,不写盘;手动锁定 = 暂停(解锁后恢复),撤销才取消,见
docs/dev/agent.md“长授权”;只有桌面 App 和配对过的 iPhone 能批,没人能批或 90 秒没人点就告诉 agent“待批准”,见docs/dev/agent.md)。远程审批:配对的 iPhone 在同一局域网内直连;不在同一网络时,Mac 经 CloudKit 推送唤醒手机,批准消息经你自己 iCloud 私有数据库里的两条记录中转(只运和局域网一样的加密签名帧,验证全在 Mac 上,2026-11-16,见docs/dev/phone-approve.md)。保险库锁着时(2026-11-16):agent 请求也发到 iPhone,Face ID 批准并选时长,手机用和“手机解锁 Mac”相同的 HPKE 通道把解锁材料交给 Mac,Mac 只为这次调用打开保险库并保持锁定,见docs/dev/phone-approve.md。配对 iPhone 不再关掉 Mac 的 Touch ID,“只能用 iPhone 解锁这台 Mac”是单独的开关。敏感请求还要再过一道本人确认:2026-11-16 实现为“取出明文”(Reveal,唯一会把值交给 agent 的一档)在 Mac 上批准时,daemon 先用UserVerifier弹 Touch ID / Apple Watch / 登录密码(LAPolicy.deviceOwnerAuthentication),在审批的 core 锁之外进行,取消则请求继续等待;拒绝不需要确认。iPhone 上每次查看和批准都要 Face ID(配对能力锁在 Secure Enclave,biometryCurrentSet),本身已满足。2026-11-16 加了按条目标记敏感:AgentPolicy.confirm_each_use(serde(default),旧数据读出为 false,条目在加密日志里按 JSON 存储,不改保险库格式),pn add --confirm-each-use设置。这类条目每次 agent 使用都重新请求、只授权一次(引擎不复用之前的批准,max_uses = 1;审批中心把任何批准都按“仅这一次”给),并和取出明文一样要本人确认。Mac 弹窗和 iPhone 只显示“仅这一次”和“拒绝”。2026-11-17 和用户商定加了介于“每次都问”和普通时长之间的限额:打开“每次使用都要我确认”后,下面多两项设置“免确认时长”(5 分钟 / 15 分钟 / 1 小时,默认 5 分钟)和“免确认次数”(1 次 / 3 次 / 5 次 / 10 次,默认 1 次)。本人确认一次(Mac 上 Touch ID,iPhone 上 Face ID)后,agent 做同一件事(同一命令或同一方法 + 主机 + 路径)在时长或次数先到的那个之前不再问,保险库一锁就作废;选 1 次就是原来的每次都问,不管时长。存在AgentPolicy.confirm_window_minutes/confirm_max_uses(serde(default),旧数据读出为 5 分钟、1 次,即原来的行为;同样在加密日志里按 JSON 存,不改保险库格式)。授权仍是短授权(锁定即失效、不进锁屏副本、不能“总是允许”),时长是从批准起算的绝对时长;引擎只在授权不超过条目当前限额时才复用(另一台设备调低了限额,或先有授权后才标记敏感,旧授权都不再算数),调低限额时 passnod 立即作废该条目上的授权。取出明文不受限额影响,始终一次一批。弹窗和 iPhone 上只有一个批准按钮写明限额(“批准(5 分钟内或 3 次内不再问)”)和“拒绝”;手机快捷批准和 Apple Watch 通知按钮照旧不能批这类请求。活动记录写入时长和次数(ApprovalRecord.max_uses)。Mac 锁着时经 iPhone 批准的这类请求,手机上看不到条目,所以显示普通时长选项,Mac 按条目限额截短。Windows Hello 随 Windows 版(已冻结)。另外,iPhone 配对时生成一把“快捷批准”密钥(不需要每次 Face ID,但不能解锁 Mac,也不能批敏感请求或取出明文),用于在通知和 Apple Watch 上直接批准普通 agent 请求,详见 phone-approve。只用到已有的 Ed25519 签名和 HPKE,不改保险库格式。远程时可以以后加手机推送。保险库一锁,所有授权全部作废;托盘上有一键全部撤销。 - 服务令牌(无人值守,用户 2026-11-16 同意): 给 agent 建一个专用保险库,
pn agent token create --vault Agent --read-only --ttl 30d生成令牌。令牌里带这个保险库纪元密钥的包裹材料(用令牌自身派生的密钥包裹),所以不用人在场、不用解锁主保险库也能读这个库;其他保险库它解不开。可限只读或读写、有效期,随时撤销(撤销 = 换这个库的纪元密钥)。界面上要说明:这个库的安全性等于令牌的保管。参考 1Password Service Account、Bitwardenbws。- 服务令牌密码学设计:
- 生成 256 位随机
token_secret与唯一token_id。 - 用标准原语派生包裹密钥:
wrap_key = HKDF-SHA256(salt = "passno-service-token-salt-v1", ikm = token_secret, info = "passno-service-token-wrap-v1:" || token_id || ":" || vault_id || ":" || epoch)。 - 载荷
ServiceTokenKeyMaterial包含目标子保险库当前纪元的 256 位epoch_key;仅当令牌非只读时,额外包含一个令牌专用的 Ed25519 写入签名私钥(并在成员日志中以受限写者登记)。 - 用
XChaCha20-Poly1305(随机 192 位 nonce)加密载荷,关联数据绑定AAD = "passno-service-token-aad-v1:" || token_id || ":" || vault_id || ":" || epoch || ":" || read_only || ":" || expires_at_ms。 - 令牌编码为
pnst_v1_<base64url>,携带上述元数据、token_secret与SealedBox密文;磁盘上的令牌注册表(tokens.json)只保存SHA-256(token_secret)、权限、到期时间与撤销标记,不保存明文token_secret或epoch_key。 - 注册表是权限和期限的权威:读取时逐项核对 epoch、read_only、expires_at_ms,且同时检查注册表到期时间。持有人知道包裹密钥,能重包裹自己的载荷,所以不能仅相信载荷里的期限或 AEAD 完整性。子库禁止使用 default / primary 等主库别名。
- 解密隔离:令牌只携带该子保险库当前纪元的
epoch_key,无法解开主保险库的wrapped_member_keys或其他保险库。 - 撤销与纪元轮换:
pn agent token revoke标记令牌失效,并为该子保险库生成全新的 256 位epoch_key(epoch + 1),用成员公钥重新包裹后把当前物化状态重新加密写入新纪元基线并清除旧纪元操作/快照密文,确保已撤销令牌既无法通过注册表校验,也无法解密新纪元或当前盘上文件。
- 生成 256 位随机
- 轮换写盘顺序(agent 线补充): 首纪元沿用现有 ops/snapshots 路径,后续纪元写在独立的
epochs/<N>/下。先持久化新包裹密钥、新基线和该纪元的回滚状态,最后原子替换子库 header 的 current_epoch;切换后才清理旧密文。准备失败时旧 header 和旧数据仍可由 owner 打开;旧令牌先撤销,失败重试不会重新放行。主库格式不变。
- 服务令牌密码学设计:
- MCP:
pn mcp只暴露list/search/request_grant/run/http/generate/totp-status/whoami,所有工具均要求必填参数reason,返回的是授权编号和执行结果,从来不是密钥明文。 - 审计: 每次请求和授权都记进哈希链日志,界面上能查也能校验。2026-11-16 起这份日志就是活动记录(7.2)里 agent 的部分,随同步到每台设备并逐台校验。
- 输出打码(raw、base64、URL 编码、JSON)只是最后一道保险,不当成安全边界。
2026-11-16 安全依赖约束:SSH 的 RSA / ECDSA 后端因稳定上游仍使用存在时序漏洞的依赖而禁用。对应条目保留在库内,但身份列表跳过,直接签名同样拒绝;加口令私钥也不被 agent 加载。通行密钥的 p256 0.14 不受影响。最小上游 feature 补丁、锁文件例外、自动回归与移除条件见 威胁模型。
7.1 daemon 集成约束(2026-11-16)
主人命令按终端会话授权(2026-11-16 安全修复): 保险库解锁不等于同用户的所有进程都是主人。除桌面 App 和 Chrome 下的 passno-nmhost 外,主人请求要有调用方终端会话(Unix 会话号 + 首进程启动时间)的授权,来自该会话的解锁、Touch ID 或主密码(没有终端的会话也会在 Mac 上弹 Touch ID 确认,提示写出是哪个程序在要,同一时间只弹一个、取消后 60 秒内不再弹,2026-11-16 用户要求);10 分钟空闲、12 小时或锁定即失效。agent 的 shell 是独立会话,只能走自带凭据的代理请求。带 agent 凭据(PASSNO_SERVICE_TOKEN / PASSNO_AGENT_KEY)的 pn 一律按 agent 处理:list / search 只返回这个凭据能看的条目元数据(和 MCP list / search 一样),其他主人命令直接拒绝(退出码 8),不再弹主人确认(2026-11-18 端到端测试发现:原来会弹 Touch ID 问“允许 pn ← Python 以你的身份使用”,主人顺手一按,只能用 Agent 子库的令牌就拿到了整个主库)。思路参考 1Password CLI 按终端授权,实现和时限按 passno 自己的模型定。不改密码学和保险库格式。
CliBackend 默认把 agent 管理与使用操作交给 passnod,只有 --no-daemon 才允许进程内路径。owner broker 通过共享服务访问当前已解锁保险库,不复制解锁密钥;服务令牌每次在 daemon 内独立打开其授权子库。IPC 只返回元数据、授权、打码后的执行结果、公钥或签名,reveal 仍单独执行第 7 节的例外规则。密码、私钥和生成值不通过常规 agent RPC 回传。
主库的多设备日志/快照验证与服务令牌子库的独立验证并存;本次合并只抽出并保留子库内部辅助函数,不修改加密原语、主库格式或子库纪元落盘顺序。锁定清除 owner 会话并撤销授权,服务令牌仍可重新申请。审批保持 SIMULATED,daemon 启动时指定策略,普通 RPC 不能切换审批器。
7.2 活动记录:后台可追溯、可审计(2026-11-16)
用户要求:授权和读取虽然分布在多台设备上,但都要能回溯、能审计;只看后台(agent、服务令牌、各设备的登录解锁锁定),不记人在 App 里查看、复制。实现和用法见 活动记录开发说明。
- 每台设备一份自己的记录,单写入者。 所有事件先写进本机哈希链日志(
$PASSNO_HOME/activity/journal.jsonl,锁着也能写,例如长授权在锁屏时被使用);保险库解锁时把还没发布的记录封成段写进同步目录vaults/<id>/activity/<设备>/<序号>。一个段只由一台设备写一次,路径和内容都不再改变,符合第 5 节“每个文件只有一个写入者”。随已有同步走全部存放位置(iCloud/目录、Git、S3/R2、WebDAV),任何设备都能看到并校验所有设备的记录。 - 可校验: 记录内部是哈希链(
SHA-256(域 ‖ 序号 ‖ 上一条哈希 ‖ 原文));段之间用上一段文件的 SHA-256 链起来;每段由写入设备已有的 Ed25519 设备密钥签名(新的域passno-activity-segment-v1)。校验方查签名、文件链、记录链、序号连续、纪元不倒退;本机记住见过的各设备最新段(tips.json),之后被截断或改写都能发现。被移除的设备:纪元不低于移除纪元的段、或序号超过移除者当时见过的最后一段(移除者在自己的签名记录里写下这个位置),都标为“移除后写入”。 - 加密: 段的内容用当前纪元密钥经已有 XChaCha20-Poly1305 加密,AAD 绑定库、纪元、设备、序号、上一段哈希;先加密再签名,和操作日志相同。存储方只看到设备 id、序号、纪元和长度。被移除的设备拿不到新纪元密钥,读不到之后的记录。
- 保留期限: 每台设备每天最多压缩一次,把最后一条早于 90 天的段(以及总数超过 2 万条时最老的段)压成一个签名、加密的检查点(覆盖到第几段、那一段的文件哈希、最后一条记录的序号和哈希、条数和类型计数),删掉被覆盖的段,链从检查点接着验。存储里的旧文件只由写入它的设备删除(新增
SyncTransport::delete_compacted,只接受活动记录);其他设备看到被有效签名检查点覆盖的文件消失不算回滚,没被覆盖的照旧报回滚。 - 和原来的 agent 审计: agent 引擎的
AuditLog改由ActivityAuditLog实现,审计就是这份日志里 agent 记录的视图,只有一个来源;旧的agent/audit.jsonl校验后一次性导入。 - 理由: 只组合已有原语(SHA-256、Ed25519 设备密钥、纪元密钥 + XChaCha20-Poly1305、已有补齐),不改条目、操作、快照、成员日志的格式;新增的是两种同步对象和一个签名域。不放进操作日志,是因为操作会改条目状态、旧客户端会拒绝不认识的操作,且记录在锁着时也要能写。旧客户端扫描时忽略不认识的路径,不受影响。没有服务器,所以“发布前就被丢掉的最新记录”“第一次校验前就被截掉的记录”“仍在成员里的被盗设备写的假记录”发现不了,文档里写明。参考了 Secure Scuttlebutt 的每写入者一条签名链、Certificate Transparency / C2SP tlog-checkpoint 的签名检查点和见证者思路(只参考设计)。
8. 浏览器自动填充
- 链路: 扩展 ⇄
passno-nmhost(stdio)⇄ passnod(socket / 命名管道)。nmhost 校验 argv[1] 里的扩展 origin;扩展和后台进程之间首次配对用 X25519,配对码在桌面端确认。 - 能力:
- 识别登录、注册、改密码、TOTP 表单。
- 页面内菜单:封闭 shadow root + 扩展页 iframe + popover,检测页面篡改。
- 只在用户真实点击后才填。
- 提交后在隔离的横幅里提示保存或更新。
- 注册和改密码表单旁边直接给生成的密码,按网站规则生成。
- HTTP Basic 认证。
- 匹配在核心里做:默认 eTLD+1(PSL,含私有段),可选主机或精确匹配,加上 PMR 共用账号域名组。禁止 HTTPS 降级,跨域 iframe 要单独确认。
9. 密码生成
- 随机字符: 长度、字符类、每类最少几个、排除易混淆字符。
- 口令短语: EFF 长词表,可选分隔符、大写、数字。
- 按网站规则: 用 PMR 的
password-rules.json加页面上的passwordrules属性,经password-rules-parser解析。 - 强度: 生成的密码显示精确熵值;手输的密码用 zxcvbn 估算。
- 调用方: CLI、扩展、界面、agent 共用同一个实现。
10. 管理界面(Tauri v2)
- 浏览、搜索、编辑、标签、收藏、归档、回收站、附件、历史版本。
- 生成器、导入向导(显示迁移报告)。
- 安全检查:重复密码、弱密码、缺少 2FA 的网站(PMR),以及泄露检测(HIBP k-匿名,可选)。
- 共享成员管理、agent 授权和审计、设备管理、同步状态。
- 视觉风格、交互和流畅度指标见
docs/ui/style.md。 - 明文留在 Rust 侧,按需显示或复制。剪贴板按设定时间清空,锁定时也清,但只清 passno 自己放进去的内容:复制时记下 macOS 剪贴板的变更计数,到点时计数没变才清;之后你复制的文字或截图不会被清掉(2026-11-16 修:以前到点无条件清空,把用户后来复制的截图清掉了)。复制的密码带 nspasteboard.org 约定的
org.nspasteboard.ConcealedType标记,剪贴板历史工具(Maccy、Paste 等)不会记录。CSP 和 capability 都配到最严。
11. 迁移
| 来源 | v1 方式 | 能迁的 | 迁不了的 |
|---|---|---|---|
| 1Password | .1pux | 所有账户和保险库、全部字段类型、TOTP、附件、标签、归档、历史 | 通行密钥(桌面版导不出) |
| 1Password | CSV(兜底) | 登录、密码 | 自定义字段、附件 |
| Apple 密码 | CSV | 标题、URL、用户名、密码、备注、TOTP | 通行密钥、多个 URL、Wi-Fi、共享群组 |
| 二者 | CXF(以后) | 包括通行密钥 | 附件(Apple API 不支持文件) |
- CXF 的解析和映射在 Rust 核心里做,基于
credential-exchange-format(MIT)。macOS / iOS 原生壳只负责把 JSON 传过来。 - 导入是幂等的:用来源 UUID 去重,同一份文件重复导入不会出现重复条目。
12. 安装与命令行:App 自带 CLI(用户 2026-11-16 定)
装了 App 就有 pn,不用另外安装。 CLI、后台进程和界面在同一个安装包里,版本始终一致,签名也一致(后台进程靠校验签名来认 CLI,见第 7 节)。
12.1 各平台怎么带上 CLI
| 平台 | 安装包内容 | pn 怎么进 PATH |
|---|---|---|
| macOS | passno.app/Contents/MacOS/ 里放 passno(界面)、pn、passnod、passno-nmhost,都用同一个 Team ID 签名 | 第一次启动时,欢迎页里有一个默认勾选的"安装命令行工具":建软链 /usr/local/bin/pn → App 里的 pn,系统弹一次管理员授权。用户拒绝的话,退而建 ~/.local/bin/pn,并提示怎么把它加进 PATH。软链指向 App 内部,所以 App 一更新,CLI 跟着更新。设置里可以重装或卸载。 |
| macOS 后台进程 | passnod 用 SMAppService 注册成登录项(LaunchAgent),由 App 管理 | — |
| Windows | MSIX 包里带 pn.exe | 用 MSIX 的 AppExecutionAlias,装完直接就能在 PATH 里用,不需要管理员 |
| Linux | deb、rpm 装到 /usr/bin/pn;AppImage 首次运行时提示建 ~/.local/bin/pn 软链 | — |
| iOS | 没有 CLI | — |
做法参考的是常见桌面软件,我凭经验写的,没逐个核对源码,agy 实现时请对一下:VS Code 有"在 PATH 中安装 code 命令",Docker Desktop 把 CLI 软链到 /usr/local/bin,Tailscale 的 macOS App 里自带 CLI 程序。
pn doctor 检查以下几项,每个问题都给出一条修复命令:
- CLI 是否在 PATH 上,是否指向当前 App;
- 后台进程是否在运行;
- 保险库是否已解锁;
- 浏览器扩展是否已配对;
- 签名是否一致。
12.2 对 agent 友好的帮助和输出
- 帮助分三层:
pn --help:一屏以内。说明 passno 是什么,列出最常用的 8 条命令,每条带一个例子,最后一行写"AI agent 请先运行pn agent-help"。pn <命令> --help:参数、2–4 个可以直接复制的例子、输出格式、可能的错误码。pn help <命令> --json:机器可读的帮助,包括参数、类型、默认值、输出的 JSON Schema、退出码。- 三层都从 clap 定义自动生成,同时导出 man 页和
docs/cli/*.md,保证只有一个来源。
pn agent-help:给 LLM agent 的简明指南(Markdown,200 行以内):- passno 的安全模型:拿不到明文,只能"用",每次使用都要人批准;
- 推荐的调用方式:先
pn search,然后pn run、pn http或pn fill; - 遇到"待批准"、"已拒绝"、"已锁定"时怎么办;
- 典型任务的完整示例;
- 明确告诉 agent:"不要试图读取或打印密钥,这种请求会被拒绝并记进审计日志。"
pn agent install-skill: 把上面的指南写成 skill 或说明文件,装到 Claude Code(~/.claude/skills/passno/)、Codex 等 agent 的约定位置。也可以--print只打印不安装。- 输出:
- 所有读操作都支持
--json,字段名稳定,带schema_version。列表和事件流用 NDJSON。 - 默认输出给人看(表格、颜色)。stdout 不是终端时自动去掉颜色。
- 所有读操作都支持
- 不交互、不卡住:
- stdin 不是终端时,绝不弹出交互式提问。缺参数就直接报错,并给出正确用法。
- 需要人批准时,立即返回:json
{"status":"pending_approval","grant_id":"…","hint":"请用户在 passno 中批准;或加 --wait 60 等待"}--wait <秒>用来等待批准,最长 120 秒。
- 退出码固定:
| 退出码 | 含义 |
|---|---|
| 0 | 成功 |
| 2 | 用法错误 |
| 3 | 保险库已锁定 |
| 4 | 被拒绝 |
| 5 | 找不到 |
| 6 | 等待批准超时 |
| 7 | 后台进程没运行 |
| 8 | 策略不允许 |
- 错误信息三段式: 发生了什么、为什么、下一步运行什么。例如:命令打错时给出最接近的建议。
error: 保险库已锁定 原因: 空闲 15 分钟后自动锁定 下一步: 请用户在 passno 中解锁(Touch ID),或运行 pn unlock - CLI 和 MCP 共用一套说明。
pn mcp的工具描述和pn agent-help出自同一个定义,不会出现两边说法不一样的情况。
13. iOS 原生实现与通行密钥(2026-11-16)
iOS 选用 SwiftUI + UniFFI,App 与 AutoFill .appex 共用 PassnoKit / App Group;对照 Tauri iOS 的构建验证与指标见 docs/dev/ios.md。保留桌面的 React 风格令牌,手机使用原生导航、分组行和系统文件选择器。
通行密钥存储与密码学
为保持现有保险库格式兼容,每个通行密钥暂存于 Item 的 Concealed 字段,designation=passkey、section=Passkeys、字段 ID 为随机 credential ID 的 base64url 前缀形式。字段内 JSON 包含 RP ID、user handle、用户名、credential ID、算法 ES256(-7)、签名计数、创建时间,以及 PKCS#8 DER 私钥的 base64url。JSON 不是加密:整个字段随条目经原有 XChaCha20-Poly1305 加密并签名后存盘,列表/详情只暴露摘要。后续原生 passkeys 模型迁移应保留这些字段。
passno-crypto::passkey 依赖 RustCrypto p256 / sha2 和 ciborium,生成 P-256 密钥,输出 COSE 公钥、none attestation 和 DER ECDSA 签名。系统验证 origin 与 RP 关系;FFI 只允许精确 RP 匹配、限定 ES256,扩展每次请求都要求本人解锁,才设置 UP/UV。不创建 agent 可调用的签名或私钥导出端点。此为软件可导出凭据,不宣称硬件 attestation 或已完成真实同步。Apple 的提供方接口要求 BE/BS 均置位(本机清除 BS 后注册被拒),所以当前输出这两个兼容性标志;它不能作为用户保险库已同步的证据,详见 iOS 开发文档的发布边界。
原生安全边界
FFI 是 App / 系统扩展的进程内接口,不是 agent IPC。get_item 脱敏;reveal_field、AUK 导出及 AutoFill 填充只由本人界面消费。真机 AUK 必须经 Secure Enclave ECIES 包裹,失败拒绝;模拟器的测试替代实现仅在 simulator 编译条件下存在。Secret Key 由 Swift Keychain 持久化,Rust 正式客户端不写普通密钥文件。App 与扩展各自保持短期会话,系统每次填充请求重新核验用户。
手机批准 Mac 已由 passno-approve + UniFFI PhoneApprovalClient + 原生批准页接入 daemon;Bonjour 发现与加密 TCP 已实现,CloudKit 保留显式失败 stub。请求绑定双方指纹、vault ID、随机挑战、临时 X25519 公钥、用途与绝对到期时间。原生逐次认证后返回 HPKE 密文及签名;模拟器只使用模拟 Face ID。详见 手机批准。
其余待定
- 条目级密钥:阶段 7 做共享时再评估。