From 2b7d54257f2edba82f4d2eb4a2c65dce991a367b Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Thu, 19 Nov 2026 11:34:19 +0800 Subject: [PATCH] fix(unityfs): share bounded header probing with desktop inspection (#12169) --- docs/unityfs.md | 3 ++ src/artifacts/DesktopFileInspection.ts | 17 +++++++-- src/artifacts/UnityFsStructures.ts | 11 ++---- src/domain/unityfsFormat.ts | 16 ++++++-- tests/boundary/cli/unityFsCli.test.ts | 53 ++++++++++++++++++++++++++ 5 files changed, 86 insertions(+), 14 deletions(-) diff --git a/docs/unityfs.md b/docs/unityfs.md index 6592e461cc..90f98a5520 100644 --- a/docs/unityfs.md +++ b/docs/unityfs.md @@ -8,6 +8,9 @@ layout and is unsupported until independently verified. Inspection retains the header facts: format version, player and engine version strings, declared size, dataflags, blocks-and-directory table bounds, the producer's 16-byte data hash as declared, and the resolved data-area offset. +Desktop application inspection uses the same header bounds. When the initial +file probe stops before both version strings and the fixed fields are read, +its normal probe budget applies to the additional bytes. Members (`CAB-*` SerializedFiles, `.resS` resource streams, shared assets) retain declared source paths, virtual stream offsets, sizes and raw node flags. The directory flag identifies directories. `compare_artifacts` compares each diff --git a/src/artifacts/DesktopFileInspection.ts b/src/artifacts/DesktopFileInspection.ts index 921587aff0..4891edf6c8 100644 --- a/src/artifacts/DesktopFileInspection.ts +++ b/src/artifacts/DesktopFileInspection.ts @@ -25,6 +25,7 @@ import { hasMachoMagic } from "../domain/apple/machoContainer.js"; import { hasUnityFsHeader, readUnityFsHeaderFacts, + UNITYFS_HEADER_PREFIX_BYTES, } from "../domain/unityfsFormat.js"; import { sha256Hex } from "../kernel/sha256Hex.js"; @@ -69,7 +70,7 @@ class DesktopProbeLimit extends ArtifactReaderFailure { } } -/** Inspect selected ranges on an already admitted descriptor; never hash payloads. */ +/** Inspect and hash selected ranges on an already admitted descriptor. */ export const inspectDesktopFile = async ( file: FileHandle, row: DesktopFile, @@ -171,8 +172,18 @@ export const inspectDesktopFile = async ( }, }); } - if (prefix.length >= 20 && hasUnityFsHeader(prefix)) { - const unityfsHeader = readUnityFsHeaderFacts(prefix); + if (hasUnityFsHeader(prefix)) { + let unityfsHeader = readUnityFsHeaderFacts(prefix); + const headerPrefixBytes = Math.min(size, UNITYFS_HEADER_PREFIX_BYTES); + // The generic probe can end inside a version string or the fixed tail. + // Continue only for UnityFS and charge the additional range to the same budget. + if (unityfsHeader === undefined && prefix.length < headerPrefixBytes) + unityfsHeader = readUnityFsHeaderFacts( + Buffer.concat([ + prefix, + await read(prefix.length, headerPrefixBytes - prefix.length), + ]), + ); if (unityfsHeader !== undefined) fact({ kind: "unityfs-header", diff --git a/src/artifacts/UnityFsStructures.ts b/src/artifacts/UnityFsStructures.ts index e9864a529d..c775a1c8a7 100644 --- a/src/artifacts/UnityFsStructures.ts +++ b/src/artifacts/UnityFsStructures.ts @@ -12,6 +12,7 @@ import { } from "../domain/binaryContainer.js"; import { setImmediate } from "node:timers/promises"; import { + hasUnityFsHeader, readUnityFsHeaderFacts, UNITYFS_COMPRESSION_LZ4, UNITYFS_COMPRESSION_LZ4HC, @@ -20,8 +21,7 @@ import { UNITYFS_FLAG_COMPRESSION_MASK, UNITYFS_FORMAT_VERSION_MAX, UNITYFS_FORMAT_VERSION_MIN, - UNITYFS_HEADER_STRING_MAX, - UNITYFS_SIGNATURE, + UNITYFS_HEADER_PREFIX_BYTES, unityFsLayoutFlags, } from "../domain/unityfsFormat.js"; import { strictUtf8Decoder } from "../domain/strictUtf8.js"; @@ -42,8 +42,6 @@ const directoryLimit = (): ArtifactReaderFailure => { boundary: "memory" }, ); -/** Signature, version, two bounded strings and the fixed tail; reads are bounded. */ -const HEADER_PREFIX_MAX = 8 + 4 + UNITYFS_HEADER_STRING_MAX * 2 + 20; const UTF8 = strictUtf8Decoder("preserve"); export interface UnityFsHeader { @@ -112,12 +110,11 @@ export const readUnityFsHeader = async ( const prefix = await readArtifactFileBytes( handle, 0, - Math.min(size, HEADER_PREFIX_MAX), + Math.min(size, UNITYFS_HEADER_PREFIX_BYTES), size, signal, ); - if (prefix.length < 20 || !prefix.subarray(0, 8).equals(UNITYFS_SIGNATURE)) - return undefined; + if (prefix.length < 20 || !hasUnityFsHeader(prefix)) return undefined; const facts = readUnityFsHeaderFacts(prefix); if (facts === undefined) throw unityFsFormatFailure("header is truncated or exceeds its bounds"); diff --git a/src/domain/unityfsFormat.ts b/src/domain/unityfsFormat.ts index 4c17a4e41d..36bdc5ebe5 100644 --- a/src/domain/unityfsFormat.ts +++ b/src/domain/unityfsFormat.ts @@ -105,7 +105,15 @@ export const unityFsLayoutFlags = ( }; /** Producer version strings are short; the bound keeps a corrupt header local. */ -export const UNITYFS_HEADER_STRING_MAX = 1024; +const UNITYFS_HEADER_STRING_MAX = 1024; +const UNITYFS_VERSION_STRINGS_OFFSET = UNITYFS_SIGNATURE.length + 4; +const UNITYFS_HEADER_TAIL_BYTES = 8 + 4 + 4 + 4; + +/** A prefix covering the signature, version, both bounded strings and fixed tail. */ +export const UNITYFS_HEADER_PREFIX_BYTES = + UNITYFS_VERSION_STRINGS_OFFSET + + 2 * UNITYFS_HEADER_STRING_MAX + + UNITYFS_HEADER_TAIL_BYTES; /** Declared header fields; support and extent admission belong to callers. */ export interface UnityFsHeaderFacts { @@ -132,7 +140,7 @@ export const readUnityFsHeaderFacts = ( ): UnityFsHeaderFacts | undefined => { if (!hasUnityFsHeader(bytes)) return undefined; const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength); - let cursor = 12; + let cursor = UNITYFS_VERSION_STRINGS_OFFSET; const readString = (): string | undefined => { const start = cursor; while ( @@ -157,7 +165,7 @@ export const readUnityFsHeaderFacts = ( if ( playerVersion === undefined || engineVersion === undefined || - cursor + 20 > bytes.length + cursor + UNITYFS_HEADER_TAIL_BYTES > bytes.length ) return undefined; const fixed = cursor; @@ -169,6 +177,6 @@ export const readUnityFsHeaderFacts = ( compressedBlocksInfoSize: view.getUint32(fixed + 8), uncompressedBlocksInfoSize: view.getUint32(fixed + 12), flags: view.getUint32(fixed + 16), - afterFixed: fixed + 20, + afterFixed: fixed + UNITYFS_HEADER_TAIL_BYTES, }; }; diff --git a/tests/boundary/cli/unityFsCli.test.ts b/tests/boundary/cli/unityFsCli.test.ts index 68bfc002b6..1ac943c2e5 100644 --- a/tests/boundary/cli/unityFsCli.test.ts +++ b/tests/boundary/cli/unityFsCli.test.ts @@ -191,6 +191,7 @@ cliTest( files: expect.arrayContaining([ expect.objectContaining({ path: "assets/content.bundle", + ranges: [{ offset: 0, bytes: 64, sha256: expect.any(String) }], facts: expect.arrayContaining([ expect.objectContaining({ kind: "unityfs-header", @@ -202,3 +203,55 @@ cliTest( }); }, ); + +cliTest( + "retains the same UnityFS header facts when the version strings extend past the desktop prefix", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-unity-desktop-header-"); + const assets = join(root, "assets"); + await mkdir(assets); + const engineVersion = "2022.3.1f1"; + const bytes = buildUnityFs([{ path: "CAB", data: Buffer.alloc(3_000) }], { + playerVersion: "game-player-build-" + "x".repeat(72), + engineVersion, + blockCompression: 0, + }); + const path = join(assets, "content.bundle"); + await writeFile(path, bytes); + const inventory = await cli.run({ + arguments: ["inspect-artifact", path, "--json"], + }); + expect(inventory.exitCode, inventory.stderr).toBe(0); + const artifact = artifactInspectionResultSchema.parse( + parseEvidence(inventory.json).normalized_result, + ).substeps[0]!.evidence.normalized_result; + const facts = { + format_version: 8, + engine_version: engineVersion, + declared_size: bytes.length, + }; + expect(artifact.occurrences[0]!.format_metadata).toMatchObject(facts); + + const scan = await cli.run({ + arguments: ["inspect-desktop-application", root, "--json"], + }); + expect(scan.exitCode, scan.stderr).toBe(0); + expect(parseEvidence(scan.json).normalized_result).toMatchObject({ + files: expect.arrayContaining([ + expect.objectContaining({ + path: "assets/content.bundle", + facts: expect.arrayContaining([ + expect.objectContaining({ + kind: "unityfs-header", + value: expect.objectContaining(facts), + }), + ]), + ranges: expect.arrayContaining([ + expect.objectContaining({ offset: 0, bytes: 64 }), + expect.objectContaining({ offset: 64, bytes: 2_016 }), + ]), + }), + ]), + }); + }, +);