[PR #5726] [CLOSED] fix(il2cpp): report a magic without a complete version as a truncated header #7036

New issue

Closed

opened 2026-11-01 21:44:53 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-01 21:44:53 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/5726
Author: @8rulerstar
Created: 10/21/2026
Status: ❌ Closed

Base: main ← Head: fix/il2cpp-truncated-version

📝 Commits (1)

20353a7 fix(il2cpp): report a magic without a complete version as a truncated header

📊 Changes

4 files changed (+68 additions, -2 deletions)

View changed files

📝 docs/il2cpp-metadata.md (+1 -1)
📝 src/il2cpp/Il2cppMetadataFile.ts (+8 -1)
📝 tests/boundary/il2cpp/il2cppMetadataFile.test.ts (+29 -0)
📝 tests/boundary/il2cpp/il2cppMetadataProvider.test.ts (+30 -0)

📄 Description

Summary

Thank you @coygeek for the clear report and the reproducible CLI script.

Fixes #5403

A 4 to 7 byte file that starts with the complete IL2CPP magic 0xFAB11BAF was rejected as unrecognized-magic (an unsupported target), although the magic is present and only the version field is missing. It is now an input error (invalid_request) with an invalid_format issue naming truncated-header, as docs/il2cpp-metadata.md describes for a file shorter than its header.

Problem and expected behavior

readHeader in src/il2cpp/Il2cppMetadataFile.ts combined two checks: bytes.length < 8 || magic !== IL2CPP_METADATA_MAGIC. A recognized magic followed by a partial version therefore took the wrong-magic branch. The documented contract reserves unrecognized-magic for a magic other than 0xFAB11BAF.

Change and scope

The magic check now stands alone. Files shorter than four bytes still read no magic (null) and keep unrecognized-magic, because they cannot establish metadata.
A recognized magic with fewer than 8 bytes throws truncated-header without assuming a version or header size: the file has N bytes, ending inside the 4-byte metadata version field; the version and header size are unknown.
The provider already maps truncated-header (a corrupt reason) to AnalysisInputError with invalid_format and keeps partial source Evidence, so no provider change was needed.
The docs failure table row for truncated-header now mentions the incomplete version field.

Not included: any change to wrong-magic, unsupported-version or version-specific header-size handling.

Contract and boundary impact

Semantic owner and earliest changed stage: readHeader in src/il2cpp/Il2cppMetadataFile.ts, header classification.
Contribution scope fit and linked maintainer decision: ordinary fix within the existing IL2CPP metadata reader; not applicable.
CLI and MCP/tool-catalog contract: no schema change. For 4 to 7 byte magic-prefixed files, code changes from unsupported_target to invalid_request with details.issues[0].reason: invalid_format.
Provider, bridge, target-format, or platform compatibility: none.
Evidence, artifact, provenance, or reconstruction contract: partial source Evidence (path, SHA-256, byte length, not-returned-as-complete) is retained as before.
Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable.
Generated metadata, package, or installation impact: none.
Read existing files or captured data.
Launch or attach to a process.
Inject instrumentation or run scripts/code.
Change process memory, registers, files, or configuration.
Contact network services.
Recover protected code or work around protections.
Documentation or usability only; no target interaction.
Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

Tests added or updated:
- tests/boundary/il2cpp/il2cppMetadataFile.test.ts: every length 4, 5, 6, 7 with the magic is truncated-header (corrupt) and names its byte count; at 8 bytes the version decides (39 and 27 give their own truncated-header with 380 and 256 byte headers, 30 gives unsupported-version); a 3-byte magic prefix and a one-byte-off magic stay unrecognized-magic.
- tests/boundary/il2cpp/il2cppMetadataProvider.test.ts: a 7-byte file returns AnalysisInputError with one invalid_format issue and partial source Evidence.
- Both new tests fail on the base revision (2 failed, 64 passed) and pass with the change (66 passed).
Base reproduction or other evidence: the issue's CLI script, replayed on this branch (built CLI):

magic-4.dat 1 invalid_request invalid_format | truncated-header: the file has 4 bytes, ending inside the 4-byte metadata version field; ...
magic-5.dat 1 invalid_request invalid_format | ... 5 bytes ...
magic-6.dat 1 invalid_request invalid_format | ... 6 bytes ...
magic-7.dat 1 invalid_request invalid_format | ... 7 bytes ...
cut-header.dat 1 invalid_request invalid_format | the file has 64 bytes, fewer than the 380-byte version 39 header
v39-eight.dat 1 invalid_request invalid_format | the file has 8 bytes, fewer than the 380-byte version 39 header
wrong-magic.dat 1 unsupported_target unrecognized-magic: ...
v30-eight.dat 1 unsupported_target unsupported-version: metadata version 30 is not supported; ...
three.dat (3-byte magic prefix) 1 unsupported_target unrecognized-magic: ...

The issue's v27-eight.dat control is now a supported version on main, so a version 30 file was used as the complete unsupported-version control.

Also replayed: MCP stdio tools/call for the same files returns the same invalid_request / invalid_format result as the CLI.
Remaining proof gaps: none known for the reported inputs.

For evidence-bearing changes:

Observed, derived, and inferred claims remain distinguishable.
Artifact identity, source provenance, and failed attempts remain preserved.
Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

npm run build:cached: passed
npm run test:focused -- tests/boundary/il2cpp/il2cppMetadataFile.test.ts tests/boundary/il2cpp/il2cppMetadataProvider.test.ts: 66 passed (base revision: 2 failed, 64 passed)
npm run check:fast (typecheck and lint): passed
npm run format:check: passed
npm run metadata:check: passed
npm run docs:check: passed
Issue CLI reproduction on the built branch: output above

Compatibility, safety, and release

Breaking changes or migration steps: none. Callers matching unsupported_target for these malformed 4 to 7 byte files now receive invalid_request, as documented.
Real Hopper/Ghidra, browser, or OS coverage: not applicable; synthetic files on macOS arm64, Node 26.5.0.
Package or release metadata impact: none.
Security, privacy, process, or containment review: no new reads or processes.

Author readiness

Human owner: @8rulerstar

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

Before merge

This PR addresses a concrete problem or an agreed enhancement.
Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

Thanks again for the report.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/5726 **Author:** [@8rulerstar](https://github.com/8rulerstar) **Created:** 10/21/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/il2cpp-truncated-version` --- ### 📝 Commits (1) - [`20353a7`](https://github.com/morluto/rea/commit/20353a725b8d6245fb461f8845bb57d58b8a336b) fix(il2cpp): report a magic without a complete version as a truncated header ### 📊 Changes **4 files changed** (+68 additions, -2 deletions) <details> <summary>View changed files</summary> 📝 `docs/il2cpp-metadata.md` (+1 -1) 📝 `src/il2cpp/Il2cppMetadataFile.ts` (+8 -1) 📝 `tests/boundary/il2cpp/il2cppMetadataFile.test.ts` (+29 -0) 📝 `tests/boundary/il2cpp/il2cppMetadataProvider.test.ts` (+30 -0) </details> ### 📄 Description ## Summary Thank you @coygeek for the clear report and the reproducible CLI script. Fixes #5403 A 4 to 7 byte file that starts with the complete IL2CPP magic `0xFAB11BAF` was rejected as `unrecognized-magic` (an unsupported target), although the magic is present and only the version field is missing. It is now an input error (`invalid_request`) with an `invalid_format` issue naming `truncated-header`, as `docs/il2cpp-metadata.md` describes for a file shorter than its header. ## Problem and expected behavior `readHeader` in `src/il2cpp/Il2cppMetadataFile.ts` combined two checks: `bytes.length < 8 || magic !== IL2CPP_METADATA_MAGIC`. A recognized magic followed by a partial version therefore took the wrong-magic branch. The documented contract reserves `unrecognized-magic` for a magic other than `0xFAB11BAF`. ## Change and scope - The magic check now stands alone. Files shorter than four bytes still read no magic (`null`) and keep `unrecognized-magic`, because they cannot establish metadata. - A recognized magic with fewer than 8 bytes throws `truncated-header` without assuming a version or header size: `the file has N bytes, ending inside the 4-byte metadata version field; the version and header size are unknown`. - The provider already maps `truncated-header` (a corrupt reason) to `AnalysisInputError` with `invalid_format` and keeps partial source Evidence, so no provider change was needed. - The docs failure table row for `truncated-header` now mentions the incomplete version field. Not included: any change to wrong-magic, unsupported-version or version-specific header-size handling. ## Contract and boundary impact - Semantic owner and earliest changed stage: `readHeader` in `src/il2cpp/Il2cppMetadataFile.ts`, header classification. - Contribution scope fit and linked maintainer decision: ordinary fix within the existing IL2CPP metadata reader; not applicable. - CLI and MCP/tool-catalog contract: no schema change. For 4 to 7 byte magic-prefixed files, `code` changes from `unsupported_target` to `invalid_request` with `details.issues[0].reason: invalid_format`. - Provider, bridge, target-format, or platform compatibility: none. - Evidence, artifact, provenance, or reconstruction contract: partial source Evidence (path, SHA-256, byte length, `not-returned-as-complete`) is retained as before. - Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable. - Generated metadata, package, or installation impact: none. - [x] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [ ] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: - `tests/boundary/il2cpp/il2cppMetadataFile.test.ts`: every length 4, 5, 6, 7 with the magic is `truncated-header` (corrupt) and names its byte count; at 8 bytes the version decides (39 and 27 give their own `truncated-header` with 380 and 256 byte headers, 30 gives `unsupported-version`); a 3-byte magic prefix and a one-byte-off magic stay `unrecognized-magic`. - `tests/boundary/il2cpp/il2cppMetadataProvider.test.ts`: a 7-byte file returns `AnalysisInputError` with one `invalid_format` issue and partial source Evidence. - Both new tests fail on the base revision (2 failed, 64 passed) and pass with the change (66 passed). - Base reproduction or other evidence: the issue's CLI script, replayed on this branch (built CLI): ```text magic-4.dat 1 invalid_request invalid_format | truncated-header: the file has 4 bytes, ending inside the 4-byte metadata version field; ... magic-5.dat 1 invalid_request invalid_format | ... 5 bytes ... magic-6.dat 1 invalid_request invalid_format | ... 6 bytes ... magic-7.dat 1 invalid_request invalid_format | ... 7 bytes ... cut-header.dat 1 invalid_request invalid_format | the file has 64 bytes, fewer than the 380-byte version 39 header v39-eight.dat 1 invalid_request invalid_format | the file has 8 bytes, fewer than the 380-byte version 39 header wrong-magic.dat 1 unsupported_target unrecognized-magic: ... v30-eight.dat 1 unsupported_target unsupported-version: metadata version 30 is not supported; ... three.dat (3-byte magic prefix) 1 unsupported_target unrecognized-magic: ... ``` The issue's `v27-eight.dat` control is now a supported version on main, so a version 30 file was used as the complete unsupported-version control. - Also replayed: MCP stdio `tools/call` for the same files returns the same `invalid_request` / `invalid_format` result as the CLI. - Remaining proof gaps: none known for the reported inputs. For evidence-bearing changes: - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npm run build:cached`: passed - `npm run test:focused -- tests/boundary/il2cpp/il2cppMetadataFile.test.ts tests/boundary/il2cpp/il2cppMetadataProvider.test.ts`: 66 passed (base revision: 2 failed, 64 passed) - `npm run check:fast` (typecheck and lint): passed - `npm run format:check`: passed - `npm run metadata:check`: passed - `npm run docs:check`: passed - Issue CLI reproduction on the built branch: output above ## Compatibility, safety, and release - Breaking changes or migration steps: none. Callers matching `unsupported_target` for these malformed 4 to 7 byte files now receive `invalid_request`, as documented. - Real Hopper/Ghidra, browser, or OS coverage: not applicable; synthetic files on macOS arm64, Node 26.5.0. - Package or release metadata impact: none. - Security, privacy, process, or containment review: no new reads or processes. ## Author readiness Human owner: @8rulerstar - [ ] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [ ] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [ ] I declare this PR ready for initial maintainer review. ## Before merge - [ ] This PR addresses a concrete problem or an agreed enhancement. - [ ] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [ ] The PR has one focused outcome and the title follows `type(scope): outcome`. - [ ] Related issue is linked, or the reason for not linking one is stated above. - [ ] Tests cover changed observable behavior and meaningful failure paths. - [ ] Owning docs, contracts, and generated metadata are updated where needed. - [ ] User-visible CLI/MCP changes include representative output. - [ ] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. Thanks again for the report. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-11-01 21:44:53 +00:00