Skip to content

fix(nx_unpack): 支持修订版卡带的稀疏本体 NCA(SparseInfo)导入检查与解包判因 - #1590

Open
lugeke wants to merge 1 commit into
jhaizhou-ops:mainfrom
lugeke:fix/inspect-sparse-base-nca
Open

lugeke wants to merge 1 commit into
jhaizhou-ops:mainfrom
lugeke:fix/inspect-sparse-base-nca

Conversation

@lugeke

@lugeke lugeke commented Nov 18, 2026

Copy link
Copy Markdown

问题与要证明什么

要证明的读数变化:带任天堂官方稀疏本体 NCA(NcaFsHeader.ExistsSparseLayer() == true,修订版/带板载更新卡带常见,例如 010097F018538000 周年版 XCI,以及类似 #1511 中「本体第 0/1 段 2002-4644、第 2 段标志和控制数据正常」的现象)在 nx_unpack --inspect 时不再误报 【校验跳过】 + 【原因 content_damaged】/【原因 keys_wrong】(rc=3),而是正常返回 rc=0、0 警告、检出完整包元数据。

根因(三处同源):

  1. pack/nx_unpack/Inspect.cs:119-120:对 kind == "base" 无条件单独调用 nca.OpenFileSystem(NcaSectionType.Code, ...)。任天堂修订版卡带会把本体程序被板载更新替换的 ExeFS(第 0 段)做成 SparseInfo.Generation != 0、MetaSize == 0 的空稀疏段;LibHac 单独读空稀疏段吐出全 0x00 → 首轮触发块哈希不符打 【校验跳过】 → 次轮跳过校验读分区头不是 PFS0 抛 ResultFsPartitionSignatureVerificationFailed (2002-4644)。
  2. pack/nx_unpack/Program.cs:219:SiblingDecrypts() 只排除了更新补丁段 AesCtrEx,没有排除 ExistsSparseLayer(),导致容器里只要有稀疏本体、同代别的内容正常,就会被误判成 content_damaged(甚至在容器内另一代密钥真出错时也盖过 keys_wrong)。
  3. pack/nx_unpack/Program.cs:459,481,515 与 VerifyReport()(276):无更新单独解包稀疏本体时直接打开稀疏段也会撞 2002-4644 误报损坏/密钥错,而不是明确提示「稀疏本体需配合更新包」。

改动(只改了哪些文件)

  • pack/nx_unpack/Program.cs:
    • 新增 IsSparseSection(Nca, NcaSectionType)(以 LibHac 原生 NcaFsHeader.ExistsSparseLayer() 判定)。
    • SiblingDecrypts() 排除 ExistsSparseLayer() 分段,与 AesCtrEx 同口径。
    • VerifyReport() 对稀疏段标明「没核对(稀疏段,要叠上更新才能读)」,不再单独调用 VerifySection 误报「不过」。
    • Run() 在 patId == null(未提供更新)且本体 Code / Data 为稀疏段时直接抛 SourceError,说明这是稀疏本体、需把对应更新包一起提供。
  • pack/nx_unpack/Inspect.cs:
    • kind == "base" 的 Program NCA 若 IsSparseSection(nca, NcaSectionType.Code),跳过单独打开本体 ExeFS(保留 guestIsa="unknown"、builds={},与 nup_inspect/extract_inspect 同形;pack/jobs/library.py guest_isa() 与 pack/source_pick.py 均优先从同容器或另行导入的 update 读取位数)。非稀疏 NCA 路径逐行不变。
  • tests/nx_unpack_fail_test.sh:新增 3 份原创合成稀疏本体夹具(纯 Python AES-128 + 全假测试密钥,不含任何真实密钥或游戏数据)及 5 项回归断言。
  • docs/坑记录.md:追加客观记录(现象 → 根因 → 实测读数 → 做法)。

修前 → 修后读数

项 期望 → 实测
新单测在 main(83d65735a)上 红 → 红(tests/nx_unpack_fail_test.sh 30 项,不通 4:不通 稀疏本体单独 --inspect、不通 稀疏本体 + 更新同容器 --inspect、不通 稀疏本体无更新单独解包、不通 同容器含稀疏本体 + 另一代密钥错误)
新单测在本 PR 上 绿 → 绿(tests/nx_unpack_fail_test.sh 30/30 通过,不通 0)
实测修订版 XCI(010097F018538000 周年版,整文件 SHA-256 匹配官方内容号)--inspect 修前 rc=3(【校验跳过】 + 【原因 content_damaged】) → 修后 rc=0、stderr 0 字节、检出全部 4 个包(本体 + 更新 aarch64 + 附赠程序 aarch64 + DLC)与封面
原有单测(gate_route 列出的 nx_unpack / npdm_isa / docs 套件 + test_import.py) 全绿 → 全部通过:nx_unpack_fail 30/30、nx_unpack_ncz PASS、nx_unpack_romfs 47/47、nx_unpack_symlink 2/2、nx_unpack_zbic 24/24+5、npdm_isa 12/12、docs_consistency 24/24、pack/jobs/tests/test_import.py 32/32

负对照

在当前分支上仅回退 pack/nx_unpack/Inspect.cs 与 pack/nx_unpack/Program.cs 到 HEAD~1(保留新增单测),重跑 bash tests/nx_unpack_fail_test.sh:

  • 期望:新增的 4 条修复断言重新变红。
  • 实测:4 条全部重新变红(✗ nx_unpack 解包失败回归:30 项,不通 4),分别红在 稀疏本体单独 --inspect、稀疏本体 + 更新同容器 --inspect、稀疏本体无更新单独解包、同容器含稀疏本体 + 另一代密钥错误。

射程

  • 合成回归:tests/nx_unpack_fail_test.sh 30 项(含新增 5 项稀疏本体用例,覆盖单本体 --inspect、本体+更新同容器 --inspect、--exefs-only 解包、无更新单独解包、同容器含稀疏本体 + 另一代密钥错误)、nx_unpack_ncz / romfs (47 项) / symlink (2 项) / zbic (24 项+5) / npdm_isa (12 项) / docs_consistency (24 项) / pack/jobs/tests/test_import.py (32 项),全部 0 不符。
  • 真实原件:Apple 芯片 Mac / .NET 10.0.404 上验证 1 份修订版卡带 XCI(010097F018538000)--inspect 与 --exefs-only / S2A_NXUNPACK_ROMFS_HEADER=1,0 局实机游戏。

一级自检

本机系统自带 bash 为 3.2.57,缺少 Homebrew bash 5,bash tools/contrib_check.sh --base origin/main 在前置环境检查以 rc=2 退出(未生成摘要);本次终端原文如下(已单独跑完上述 nx_unpack / docs / test_import 全部路由单测):

❌ bash 5:3.2.57(1)-release(要求 ≥ 5)
   → brew install bash,再用 /opt/homebrew/bin/bash 跑 tools/contrib_check.sh
✅ Python 3.12+:python3 = 3.14.7(/opt/homebrew/bin/python3)
❌ Python 包:版本不符: capstone(要 5.0.7,本机 没装) lz4(要 4.4.5,本机 没装)(tools/rewriter-requirements.txt)
✅ Xcode:Xcode 27.2:/Applications/Xcode.app/Contents/Developer|iOS SDK 27.2|Apple metal version 32023.922 (metalfe-32023.922.4)
✅ .NET 10 SDK:dotnet SDK 10.0.404(/Users/lujiaheng/.dotnet/dotnet;要求 10.0.403、rollForward latestFeature,compat/tree/global.json)
❌ 改写器固定依赖:...

🔴 缺 bash 5 / Python 3.12+:几乎每一步都要,先按上面的命令装好再跑(结论:不完整)

苹果路径不受影响的证明(改共用目录时必写)

  • 改动仅限 pack/nx_unpack/{Inspect.cs,Program.cs}(加 ExistsSparseLayer() 判定)、tests/nx_unpack_fail_test.sh 与 docs/坑记录.md。
  • 所有非稀疏 NCA 的 ExistsSparseLayer() 恒为 false,解析与解包路径逐字节不变;原有 nx_unpack 5 套回归与 npdm_isa、test_import 全部通过。

限制 / 未测项 / 后续

  • 未运行依赖 bash 5 的整套 tools/contrib_check.sh 其余 47 项非 nx_unpack 路由单测,交由合入队列门禁补齐。
  • 未获取 [问题] 0.5.4《胡闹搬家 2》NSZ 本体与 XCI 均报 hash_mismatch,无法导入本体 #1511 原帖玩家的实件验证,仅确认症状高度吻合(稀疏本体第 0/1 段失败而第 2 段标志与控制数据通过)。
  • 若玩家只导入拆分出来的稀疏本体文件而尚未导入更新包,启动器里该款 guestIsa 暂为 unknown(不拦截导入),补齐更新包后即由更新包提供 aarch64 并正常解包出包;若未配更新包直接解包,本次改动会给出明确的稀疏本体缺更新提示。

@jhaizhou-ops

Copy link
Copy Markdown
Owner

@lugeke 谢谢,稀疏本体这个根因写得很清楚(三处同源、附原创合成夹具)。我们这边先跑 tests/nx_unpack_fail_test.sh 和导入相关的整套测试,再拿一份带板载更新的卡带核一遍 --inspect 读数,结论在这里回复。

@jhaizhou-ops

Copy link
Copy Markdown
Owner

@lugeke 核完了,已进合入队列:

  • tests/nx_unpack_fail_test.sh:30 项,不通 0;新加的 5 项稀疏本体用例都通过。
  • 拿本机一张非稀疏的 XCI 跑 --inspect,改前改后输出逐字一致,说明非稀疏路径确实没动。手上没有稀疏本体的卡带,所以这类卡带的效果以你的合成夹具为准。
  • 无更新单独解包时直接说「要配上更新包」:这是物理上做不到(空洞读出全 0),不算拦截,我们同意这样报。

合进 main 后在这里贴提交号。

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants