Skip to content

核心库与 pn CLI 开发文档(core) ​

本文记录 feat/core 工作线在 v0.1 阶段交付的 Rust workspace、密码学原语、保险库存储格式、应用服务层和 pn CLI。

契约变更请求(Contract change requests) ​

  • v0.1(已完成):严格按照 应用服务接口约定 实现,未改动 docs/plan.md 或 docs/dev/api.md。
  • v0.2 feat/data(供 feat/ui 与后续集成参考):
    1. passno-model::FieldType 新增 CardNumber、CardType、Gender 三个变体(CardNumber.is_concealed() == true);若桌面端或前端 UI 需要专有字段渲染或徽标,请同步处理这三个枚举值。
    2. passno-model::AttachmentRef 新增可选字段 blob_id: Option<String>;跨纪元修复再增加 blob_epoch: Option<u64>(均以 #[serde(default)] 向后兼容旧日志和快照)。
    3. passno-service::PassnoService 以默认实现增量新增了 9 个方法(list_attachments、add_attachment、export_attachment、delete_attachment、list_password_history、reveal_password_history、list_trashed_items、purge_item、empty_trash),已有 mock 与 feat/daemon 无需立刻修改即可编译。
    4. 为避免破坏未编辑范围的 apps/desktop/src-tauri/src/dto.rs(其 From<ItemFilter> 使用严格结构体字面量),ItemFilter 保持现有 6 个字段不变,回收站列表由独立的 list_trashed_items 提供。桌面端后续接入垃圾箱、附件、密码历史 UI 时,需在 commands.rs 暴露对应 Tauri command 并按需更新前端 TypeScript 绑定。

已交付组件 ​

Crate / 文件职责关键类型与实现
根目录Cargo workspace、双许可、CI、格式化配置Cargo.toml、LICENSE-MIT、LICENSE-APACHE、.github/workflows/rust.yml
passno-model纯数据模型,无 I/O 与密码学依赖Item、Field、FieldType、ItemKind、ItemUrl(含 UrlMatchMode)、TotpRef、AttachmentRef、PasswordHistoryEntry、SourceRef、AgentPolicy,全量实现 Zeroize / ZeroizeOnDrop
passno-crypto标准密码学原语组合Argon2id(默认 m=64 MiB, t=3, p=4,可按保险库覆盖)、HKDF-SHA256(主密码派生密钥 + Secret Key → AUK)、XChaCha20-Poly1305(带 AAD)、Ed25519 域分离签名、X25519 + HKDF + AEAD 纪元密钥包裹、Secret Key 编解码(A3- 前缀 + 5 组 Base32 + 4 字符 SHA-256 校验)
passno-vault单成员单设备本地保险库引擎文件头 vault.header.json、公钥 account/<member>.pub、签名哈希链成员日志 members/<device>/<seq>、包裹纪元密钥 keys/<epoch>/<member>、分档补齐的加密签名操作日志 ops/<device>/<seq>、周期快照 snapshots/<device>/<seq>、HLC 字段级 LWW 合并(平局按 device_id 决胜,被覆盖密码进历史)、本地防回滚状态 local/rollback.json、原子写盘、SecretKeyStore trait 与 FileSecretKeyStore($PASSNO_HOME/secret-key,权限 0600)
passno-import导入器骨架Importer trait、ImportPreview / ImportReport / ImportFormat / DuplicatePolicy、detect_format(支持 .1pux / ZIP 魔数、UTF-8 BOM 与 Apple / 1Password CSV 表头识别),各解析器暂返回 ImportError::NotImplemented(经服务层映射为 ServiceError::Invalid("not implemented yet"))
passno-servicePassnoService trait 与本地单用户实现LocalPassnoService;经 Generator、TotpProvider、ImporterBridge trait 隔离外部能力,当前内置临时实现 BasicGenerator(rand + zxcvbn)和 Rfc6238TotpProvider(带 // TODO(v0.1-merge) 标记)
passno-clipn 命令行工具与文档生成器init、unlock、status、list、search、show、add、edit、rm、restore、gen、totp、import、doctor、agent-help、help --json;同步生成 pn.md

构建与测试 ​

sh
# 格式化检查
cargo fmt --all -- --check

# Clippy 静态检查(零警告)
cargo clippy --workspace --all-targets -- -D warnings

# 运行全部单元测试与 CLI 非 TTY 集成测试
cargo test --workspace

# 重新生成 CLI 参考文档
cargo run -p passno-cli --bin gen-pn-docs

测试环境默认通过 PASSNO_HOME 环境变量指向临时目录,避免污染本机 ~/Library/Application Support/passno。

关键设计与决策 ​

  1. Secret Key 格式与校验:采用 128 位随机数(26 个 RFC 4648 Base32 字符)拼接 4 个字符的 SHA-256 校验和,共 30 个字符分为 5 组:A3-XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX。解析时忽略大小写、空格与连字符,能可靠捕获单字符笔误且不泄露任何密钥信息。
  2. HLC 字段级 LWW 与密码历史:ItemState 为条目每个属性及每个 Field 单独维护 HlcTimestamp(wall_ms, counter, device_id)。并发更新不同字段时互不覆盖;并发更新同一密码字段时,不论新值胜出还是旧值胜出,被覆盖或落败的不同密码都会写入 password_history,避免并发改密丢失旧密码。
  3. 防回滚与防篡改分层:
    • 每个写入者的操作日志与成员日志均强制连续序号(1..=N)与 prev_hash 哈希链,并经写入设备 Ed25519 私钥签名(域分离 passno-op-v1 / passno-snapshot-v1 / passno-member-log-v1)。
    • AEAD 关联数据绑定 vault_id、epoch、device_id、seq 与 prev_hash,防止跨文件重排或替换。
    • $PASSNO_HOME/local/rollback.json 保存在同步保险库目录之外,记录每个写入者的最高已见序号与哈希;若同步目录被截断或回退,下次打开立即返回 RollbackDetected。
  4. 密文补齐(Padding):操作日志和快照在 AEAD 加密前按 256 / 512 / 1024 / 2048 / 4096 / 8192 / 16384 字节分档补齐,减少条目长度元数据泄露。
  5. 非交互式 CLI 与 agent 安全边界:
    • 任何需要主密码的命令在非 TTY 环境下若未传 --password-stdin,立即以退出码 2 和三段式错误退出,绝不挂起等待输入。
    • pn show 默认对 Concealed / Totp / SshKey 字段输出 null / [CONCEALED];pn show --reveal 仅在标准输入和标准输出均为交互式终端时允许,否则以退出码 8 拒绝,并提示 agent 访问将在 v0.2 提供。
    • pn list --json / pn search --json 输出带 schema_version: 1 的单文档 JSON 信封({"schema_version": 1, "items": [...]}),便于脚本和 agent 直接解析。
  6. LocalPassnoService 密码强度与统计口径:
    • init 拒绝少于 8 个字符或 passno_gen::estimate_user_password(基于 zxcvbn)评分低于 2 的弱主密码(返回 WeakPassword)。
    • stats() 与 security_audit() 共用同一审计实现:weak 按估算熵值低于 50.0 bits 统计;reused 统计与其他活跃条目共享相同非空密码的条目数量;missing_totp_where_supported 使用 passno-match 对常见支持 TOTP 站点进行 PSL + PMR 域名匹配并统计尚未配置 2FA 的登录条目。
    • passno-vault 通过 $PASSNO_HOME/local/vault.lock 排他文件锁串行化多进程写入,并在 reload_if_changed() / 写入前检测外部更改后重放日志。

已知缺口与 v0.2 待办 ​

  • 跨工作线状态(v0.1):passno-gen、passno-totp、passno-match 已在集成阶段合入 passno-service;passno-import 仍保留骨架实现,待导入线合入后启用完整解析。
  • v0.2 后台进程与平台能力:
    • 增加 passnod 后台进程、passno-ipc(Unix socket + PeerVerifier)和 passno-agent(策略审批、代理注入、审计日志、pn mcp)。
    • 增加 Touch ID / 安全飞地 Unlocker 及 iCloud Keychain SecretKeyStore。
    • CLI pn unlock / pn show 改为连接 passnod 会话,不再要求每条命令单独解锁。
  • v1 多设备与共享:扩展 SyncTransport、成员增删换纪元(epoch rotation)及离线重加密。

v0.2 数据层与检索交付(feat/data) ​

本阶段在保持 MIT / Apache-2.0 双许可与零 GPL 依赖的前提下完成了数据层升级:

  1. 流式加密附件块(passno-crypto::stream + passno-vault):
    • 选用 RustCrypto 生态的 aead-stream(v0.6.0,Apache-2.0 OR MIT)StreamBE32<XChaCha20Poly1305> 与每块 64 KiB 分片格式(PNBLB1\0\0 魔数头 + 长度前缀密文块),单文件强制限制 128 MiB。
    • 开源方案对比与取舍:对比 age/rage(C2SP age 规范)的 age-encryption 分块与 aead-stream 直接集成:因为 passno-crypto 已使用同一套 RustCrypto chacha20poly1305 与 hkdf,直接组合 HKDF-SHA256(epoch_key, salt) 与 aead-stream::StreamBE32 无需重复引入格式解析树,并可将完整 47 字节文件头、vault_id、epoch 绑定进每一块的 AEAD AAD,可靠检测半块/整块截断、尾部追加字节、块重排与比特翻转。
    • 密文按完整密文 SHA-256 写入 vaults/<vault-id>/blobs/<blob-id>,并在 remove_attachment、purge_item、empty_trash 后自动垃圾回收未引用块;import_commit 自动持久化 .1pux 样本与真实导出中的 Document / file 附件。
  2. 导入保真度(passno-import):
    • 将 1Password creditCardType、creditCardNumber、gender 无损映射为 FieldType::CardType、FieldType::CardNumber、FieldType::Gender,sample.1pux 不再出现上述 3 类字段的降级告警。
  3. 中文(CJK)与拼音首字母搜索(passno-service::search):
    • 放弃先遍历全库 clone Item 的旧实现,改为直接迭代 Vault::items_iter() 中的 ItemState 引用,零克隆过滤:
      • 支持纯汉字无空格子串匹配(如 "公司邮" 匹配 "公司邮箱")与 ASCII 零分配大小写忽略窗口匹配。
      • 开源方案对比与取舍:选用零传递依赖的 pinyin crate(v0.11.0,MIT,plain + heteronym 特性)对比 ib-pinyin;前者静态查找表可直接无堆分配流式迭代每个汉字的多音字读音并用位掩码匹配连续首字母(如 "重庆银行" 同时匹配 "cqyh" / "zqyh" / "cqyx")。
      • 在单核 debug 测试条件下,10,000 条混合中英文条目的子串与拼音首字母扫描耗时均远低于 200ms 目标预算。
  4. 密码历史与回收站彻底删除:
    • VaultOp::PurgeItem 搭配 VaultState.purged HLC 墓碑,彻底清除条目(阻止更早的并发重放复活条目),活跃条目禁止直接 purge;支持 empty_trash() 批量清空并回收附件块。
    • list_password_history 仅返回 { index, changed_at },明文仅经 reveal_password_history 且 CLI --reveal 与 pn show --reveal 共用交互式终端检查(非 TTY 退出码 8)。
    • 新增 CLI 子命令:pn attach add|ls|export|rm、pn history <id> [--reveal] [--index N]、pn trash ls|restore|purge [<id>|--all] 以及 pn list --trashed。

附件跨纪元读取(2026-11-16,fix/blob-epoch) ​

  • 原因与格式:附件原先只保存 blob ID,读取时误用当前 epoch 的密钥和 AAD。现在 AttachmentRef.blob_epoch 记录实际加密 epoch,随条目操作与快照一起加密、签名;StoredBlob.epoch 将实际 epoch 传给上传及 .1pux 导入路径。PNBLB1 流格式、HKDF、StreamBE32 和 vault 格式版本均不变,不增加密码学原语。
  • 写入与读取:上传在保险库文件锁内重新读取成员日志和当前 epoch,再加密;普通上传在同一锁内写入附件引用。导出按引用的 epoch 选择密钥及 passno-blob-v1:<vault-id>:<epoch> AAD。历史密钥仍从 keys/<epoch>/<member> 的签名包裹记录加载,与操作日志使用同一个验签/解包函数;设备移除不删除这些历史记录,现有同步传输会带上它们。新纪元快照即使跳过旧操作重放,也不影响旧附件解密。
  • 旧库兼容:缺少或为 null 的 blob_epoch 按旧格式处理,依次尝试当前及本成员已有的历史纪元密钥;不能用承载引用的操作 epoch 推断,因为引用可能被复制进后续操作或快照。候选密钥先完整流式认证到丢弃输出,成功后才重新读取并导出,不缓存整个附件、不将失败尝试的部分明文写入调用方。显式 epoch 不匹配时直接失败,不回退;密钥记录验签失败、所有候选失败、密文摘要/明文摘要/大小不符仍拒绝。
  • 撤销边界:导出前检查成员日志,已同步到撤销记录的旧解锁句柄也返回 DeviceRemoved;新上传只使用新随机纪元密钥,旧密钥不能解密。此修复不改变 design.md 5.2/5.3 已说明的账户恢复材料边界:完整账户凭据失陷仍需账户换钥,不能将设备 ID 撤销描述成对恶意账户持有者的密码学隔离。
  • 回归覆盖:合成多块附件在两次轮换后仍可读;三设备 Folder 同步后剩余设备重开可读;旧格式引用跨操作/快照可读(含 epoch 2 写入的旧格式);撤销设备 API 拒绝、旧密钥对新密文解密失败、错误显式 epoch 拒绝、末块篡改检测、过期上传句柄刷新,以及导入字段和 iOS AUK 重开兼容性。
  • 本分支验证:cargo fmt --all、cargo clippy --workspace --all-targets -- -D warnings、cargo test --workspace 均通过;CLI 帮助和文档同步测试保持通过。

轮换快照的同步路径冲突(2026-11-16,fix/rotation-snapshot) ​

  • 原因:同一设备在操作序号 N 写入并上传快照后,remove_device 原先直接把新纪元快照写回 snapshots/<device>/N。新密钥和随机 nonce 产生不同密文,违反同步路径不可变约束,下一次同步正确地返回 ForkDetected。
  • 修复:在保险库锁内完成成员撤销及换纪元后,追加加密、签名的 VaultOp::EpochRotation,推进设备操作序号并持久化新的回滚 tip,再写新序号的快照。该操作只推进 HLC 和日志位置,不修改条目。保留追加操作保存的回滚状态,不再用轮换前的副本覆盖新 op tip。
  • 快照不可变:同一设备同一序号已有快照时保留原字节,不重新加密;轮换标记触发自动快照时,随后的显式快照调用也不会覆盖它。后续合并的状态仍可从操作日志重建。同步层的哈希比较、签名、连续序号、哈希链、回滚与撤销检查均未放宽。
  • 兼容性:旧库的操作、快照、路径与历史密钥仍可读取,无需迁移;仅新增一种操作载荷,快照结构、vault 格式版本和密码学原语不变。旧客户端若需要重放新标记须升级,不能承诺旧客户端读取新操作。此前已经发生的同路径分叉仍会被拒绝,本修复不会自动覆盖冲突文件。
  • 回归覆盖:passno-sync/tests/sync_simulation.rs 在当前序号快照已经上传的条件下移除设备,验证剩余设备同步、条目与跨纪元附件读取、重新打开、旧格式附件、重复快照和再次轮换;覆盖快照间隔 1、2、50 及空库序号 0。另验证轮换标记落盘后立即截断会报 RollbackDetected、没有轮换快照时可重放标记、撤销设备仍被拒绝,以及同一路径的两份有效签名快照仍报 ForkDetected。
  • 验证:cargo fmt --all、cargo clippy --workspace --all-targets -- -D warnings、cargo test --workspace 均通过。

文档对应提交 56d1c45 · 由仓库 docs/ 自动生成