Appearance
导入器开发文档(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.rs | Importer 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.rs | Apple 密码 CSV(Title,URL,Username,Password,Notes,OTPAuth)与旧版 Safari CSV(Title,Url,Username,Password) |
crates/passno-import/src/onepassword_csv.rs | 1Password 8 CSV(按表头列名映射,容忍任意列顺序、标签分隔与布尔标记) |
crates/passno-import/src/csv_common.rs | CSV 公共逻辑:UTF-8 BOM 剥离、CRLF/RFC 4180 多行引号字段解析、密码原样保留、URL 裁剪与稳定 source_id |
crates/passno-import/src/common.rs | SHA-256 摘要、totp 校验告警、按 ItemKind 统计、MIME 推断与 Unix 日期格式化 |
crates/passno-service / crates/passno-cli | DefaultImporterBridge::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.rs | proptest 属性测试:任意字节/字符串/损坏 ZIP/损坏 JSON 下不 panic |
2. 映射表
2.1 .1pux 条目类别 → ItemKind
categoryUuid | 1Password 类别 | passno_model::ItemKind | 说明 |
|---|---|---|---|
001 | Login | Login | 优先按 designation,其次 fieldType/name,其次名为 username/password 的分区字段 |
002 | CreditCard | Card | |
003 | SecureNote | SecureNote | |
004 | Identity | Identity | 分区内的 username 字段不会被提升为登录 designation |
005 | Password | Password | 回退读取 details.password |
006 | Document | Document | 解析 details.documentAttributes 关联附件 |
109 | WirelessRouter | Wifi | |
112 | API_Credential | ApiCredential | |
114 | SSH_Key | SshKey | 解析 OpenSSH 私钥、PKCS#8 副私钥、公钥、指纹与密钥类型 |
100–108, 110, 111, 113 | SoftwareLicense / BankAccount / Database / DriversLicense / OutdoorLicense / Membership / Passport / RewardsProgram / SSN / Server / EmailAccount / MedicalRecord | Custom | 完整保留全部原始分区与字段类型 |
| 其他未知编号 | 未知 | 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 / Text | designation="password" 强制设为 Concealed;未知 fieldType 降级为 Text 并写入 downgraded_fields 与 warnings |
string | Text(guarded=true 时为 Concealed) | 保留原值 |
concealed | Concealed | 隐藏字段 |
totp | Totp | 同时写入 Item.fields 和 Item.totps(保留全部多个 TOTP),并用 passno-totp 校验格式 |
url | Url | 分区 URL 保留在 fields,overview.urls / overview.url 写入 Item.urls |
email | Email | 兼容纯字符串与 {email_address, provider} 对象 |
phone | Phone | 保留原值 |
date | Date | Unix 秒数格式化为 UTC YYYY-MM-DD(非零点时保留 THH:MM:SSZ) |
monthYear | MonthYear | YYYYMM 整数格式化为 YYYY-MM |
address | Address | 按 street, city, state, zip, country 拼接非空部分 |
menu | Menu | 保留选项字符串 |
reference | Reference | 保留目标条目 UUID |
file | File | 读取 files/<documentId>__<fileName> 计算真实大小、SHA-256 与 MIME,写入 Item.attachments |
sshKey | SshKey | 私钥存入 FieldType::SshKey;metadata.privateKey 存为 Concealed;publicKey/fingerprint/keyType 存为 Text |
gender / creditCardType / creditCardNumber | Gender / CardType / CardNumber | 无损映射为专用 FieldType(不再降级为 Text,CardNumber 默认隐藏) |
| 其他未知类型 | Text(guarded=true 时为 Concealed) | 保留序列化值,同时写入 downgraded_fields 与 warnings |
2.3 CSV 格式字段映射
| 来源 | ItemKind | SourceRef | 特殊处理 |
|---|---|---|---|
| Apple 密码 CSV / 旧版 Safari CSV | Login | { 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 CSV | Login(无 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 --json4. 设计决策与取舍
- 格式合规与零 GPL 依赖:全程依据 1Password 公开格式文档与
docs/research/02-import-formats.md独立编写 Rust 解析器,仅依赖 MIT / Apache-2.0 / Unlicense 许可的zip、csv、serde_json、sha2、passno-totp。 - 保险库容器与多账户保留:读取
.1pux中全部账户与保险库(包括空库),将vault.attrs.name写入Item.vault_id,并使用<account_uuid>/<vault_uuid>/<item_uuid>作为source_id。不同保险库中同名同用户名的条目因此不会被误合并或误去重。 - 专用
FieldType无损保留:gender、creditCardType、creditCardNumber已映射到FieldType::Gender、FieldType::CardType、FieldType::CardNumber,sample.1pux导入不再产生字段降级,未知未来字段仍保留为Text/Concealed并写入ImportReport.downgraded_fields。 - Zip 条目上限保护:读取
export.attributes、export.data与附件时强制Read::take上限(分别为 1 MiB 与 128 MiB),避免恶意或损坏 ZIP 头导致内存暴涨。 - 字段 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)”,不再和用户名、密码排在一起;值为空的字段不显示复制按钮。