Skip to content

导入器开发文档(passno-import) ​

本文记录 feat/import 工作线在 v0.1 阶段交付的 passno-import 迁移解析器、格式嗅探、passno-service / pn import 接线与自动化测试。

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

无。本工作线未修改 docs/plan.md、docs/dev/api.md 或 passno-model。

  • 为使 LocalPassnoService::import_commit 能如实填充 ImportReport.downgraded_fields 和 ImportReport.errors,在 Importer 与 ImporterBridge 上增量添加了带默认实现的方法 parse_with_report(默认委托给既有 parse),已有外部实现和模拟对象无需改动即可继续编译。

1. 交付组件 ​

模块 / 文件职责
crates/passno-import/src/lib.rsImporter trait、ImportFormat / ImportPreview / DuplicatePolicy / ImportReport / ParseResult / ImportedAttachment 类型、importer_for 与 detect_format
crates/passno-import/src/onepux.rs.1pux ZIP+JSON 解包、多账户/多保险库读取、全类别与全字段映射、附件解析与 SHA-256 校验
crates/passno-import/src/apple_csv.rsApple 密码 CSV(Title,URL,Username,Password,Notes,OTPAuth)与旧版 Safari CSV(Title,Url,Username,Password)
crates/passno-import/src/onepassword_csv.rs1Password 8 CSV(按表头列名映射,容忍任意列顺序、标签分隔与布尔标记)
crates/passno-import/src/csv_common.rsCSV 公共逻辑:UTF-8 BOM 剥离、CRLF/RFC 4180 多行引号字段解析、密码原样保留、URL 裁剪与稳定 source_id
crates/passno-import/src/common.rsSHA-256 摘要、totp 校验告警、按 ItemKind 统计、MIME 推断与 Unix 日期格式化
crates/passno-service / crates/passno-cliDefaultImporterBridge::parse_with_report 接线至 import_commit,完善 pn import --preview / pn import 人类可读输出
crates/passno-import/tests/fixtures_tests.rs基于 tests/fixtures/import/manifest.json 的全样本断言测试
crates/passno-import/tests/proptest_import.rsproptest 属性测试:任意字节/字符串/损坏 ZIP/损坏 JSON 下不 panic

2. 映射表 ​

2.1 .1pux 条目类别 → ItemKind ​

categoryUuid1Password 类别passno_model::ItemKind说明
001LoginLogin优先按 designation,其次 fieldType/name,其次名为 username/password 的分区字段
002CreditCardCard
003SecureNoteSecureNote
004IdentityIdentity分区内的 username 字段不会被提升为登录 designation
005PasswordPassword回退读取 details.password
006DocumentDocument解析 details.documentAttributes 关联附件
109WirelessRouterWifi
112API_CredentialApiCredential
114SSH_KeySshKey解析 OpenSSH 私钥、PKCS#8 副私钥、公钥、指纹与密钥类型
100–108, 110, 111, 113SoftwareLicense / BankAccount / Database / DriversLicense / OutdoorLicense / Membership / Passport / RewardsProgram / SSN / Server / EmailAccount / MedicalRecordCustom完整保留全部原始分区与字段类型
其他未知编号未知Custom兜底映射为 Custom 并在 warnings 中记录,绝不丢弃条目

2.2 .1pux 字段值类型 → FieldType ​

1pux 来源 / 值类型passno_model::FieldType处理方式与降级说明
loginFields (E / U / P / TEL / T/N/A/C/I)Email / Url / Concealed / Phone / Textdesignation="password" 强制设为 Concealed;未知 fieldType 降级为 Text 并写入 downgraded_fields 与 warnings
stringText(guarded=true 时为 Concealed)保留原值
concealedConcealed隐藏字段
totpTotp同时写入 Item.fields 和 Item.totps(保留全部多个 TOTP),并用 passno-totp 校验格式
urlUrl分区 URL 保留在 fields,overview.urls / overview.url 写入 Item.urls
emailEmail兼容纯字符串与 {email_address, provider} 对象
phonePhone保留原值
dateDateUnix 秒数格式化为 UTC YYYY-MM-DD(非零点时保留 THH:MM:SSZ)
monthYearMonthYearYYYYMM 整数格式化为 YYYY-MM
addressAddress按 street, city, state, zip, country 拼接非空部分
menuMenu保留选项字符串
referenceReference保留目标条目 UUID
fileFile读取 files/<documentId>__<fileName> 计算真实大小、SHA-256 与 MIME,写入 Item.attachments
sshKeySshKey私钥存入 FieldType::SshKey;metadata.privateKey 存为 Concealed;publicKey/fingerprint/keyType 存为 Text
gender / creditCardType / creditCardNumberGender / CardType / CardNumber无损映射为专用 FieldType(不再降级为 Text,CardNumber 默认隐藏)
其他未知类型Text(guarded=true 时为 Concealed)保留序列化值,同时写入 downgraded_fields 与 warnings

2.3 CSV 格式字段映射 ​

来源ItemKindSourceRef特殊处理
Apple 密码 CSV / 旧版 Safari CSVLogin{ source: "apple_csv", source_id: sha256(title, trimmed_url, username) }剥离 UTF-8 BOM;csv crate 处理 CRLF 与 RFC 4180 多行引号;密码字节原样保留不 trim;仅裁剪 URL;空 URL 允许;OTPAuth 同时写入 totps 与 FieldType::Totp
1Password 8 CSVLogin(无 URL 且无用户名但有密码时为 Password){ source: "1password_csv", source_id: sha256(title, trimmed_url, username) }按表头动态定位列,不依赖列顺序;解析 Favorite/Archived/Tags(逗号或分号分隔);额外未知列保留为 Text 字段并记录到 downgraded_fields

3. 构建与测试 ​

sh
# 格式化与静态检查
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings

# 运行导入器测试(含 manifest.json 驱动测试与 proptest)
cargo test -p passno-import

# 运行全工作区测试(含 pn import CLI 端到端测试)
cargo test --workspace

使用 CLI 预览和导入示例:

sh
printf 'correct-horse-battery-staple\n' | cargo run -p passno-cli -- import tests/fixtures/import/1password/sample.1pux --preview --password-stdin --json
printf 'correct-horse-battery-staple\n' | cargo run -p passno-cli -- import tests/fixtures/import/1password/sample.1pux --password-stdin --json

4. 设计决策与取舍 ​

  1. 格式合规与零 GPL 依赖:全程依据 1Password 公开格式文档与 docs/research/02-import-formats.md 独立编写 Rust 解析器,仅依赖 MIT / Apache-2.0 / Unlicense 许可的 zip、csv、serde_json、sha2、passno-totp。
  2. 保险库容器与多账户保留:读取 .1pux 中全部账户与保险库(包括空库),将 vault.attrs.name 写入 Item.vault_id,并使用 <account_uuid>/<vault_uuid>/<item_uuid> 作为 source_id。不同保险库中同名同用户名的条目因此不会被误合并或误去重。
  3. 专用 FieldType 无损保留:gender、creditCardType、creditCardNumber 已映射到 FieldType::Gender、FieldType::CardType、FieldType::CardNumber,sample.1pux 导入不再产生字段降级,未知未来字段仍保留为 Text/Concealed 并写入 ImportReport.downgraded_fields。
  4. Zip 条目上限保护:读取 export.attributes、export.data 与附件时强制 Read::take 上限(分别为 1 MiB 与 128 MiB),避免恶意或损坏 ZIP 头导致内存暴涨。
  5. 字段 ID 唯一性保证:由于 passno-vault 的 ItemState 使用 BTreeMap<String, LwwSlot<Option<Field>>> 以字段 id 为键,导入器在每个条目内部对字段 id 做去重补编号,确保空 ID 或重名字段不会被 LWW 状态机相互覆盖。

5. 已知缺口与 v0.2 待办 ​

  • 附件密文块持久化(已于 v0.2 feat/data 落地):LocalPassnoService::import_commit 现将 ParseResult.attachments 中的 .1pux 附件字节通过 Vault::store_blob_stream 分块加密写入 vaults/<vault-id>/blobs/<blob-id>,并在条目 AttachmentRef.blob_id 中建立引用,可用 pn attach export 完整导出校验。
  • 标签到 AgentPolicy 的映射:agent-ok 等导入标签当前作为普通标签完整保留,v0.2 接入策略引擎后可引导用户一键授权。
  • FIDO CXF / CXP 导入:待 v0.2 / 阶段 6 原生 Apple AutoFill 扩展就绪后,基于 credential-exchange-format 实现 CXF JSON 到内部模型的映射,用于迁移通行密钥。
  • 真实导出样本回归:待本人在 1Password 8 与 Apple 密码 App 导出真实测试库至 ~/passno-samples/ 后,复核 tests/fixtures/import/manifest.json 中标记为 unverified_against_real_exports 的边界细节(已删除条目、100–113 类别真实字段 ID、Apple 仅通行密钥条目导出形态)。

网页表单详情(2026-11-16) ​

1Password 登录条目里除用户名、密码以外的网页表单字段(提交按钮 commit、“记住我”勾选框等)照样导入,但放进 web_form 分区(passno_model::WEB_FORM_SECTION)。桌面详情面板把它们收进默认折叠的“网页表单详情(n)”,不再和用户名、密码排在一起;值为空的字段不显示复制按钮。

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