fix(unityfs): share bounded header probing with desktop inspection (#12169)

This commit is contained in:
morluto authored and GitHub committed 2026-11-19 03:34:19 +00:00
1 parent 3d313b56bc
commit 2b7d54257f
5 files changed
+86 -14

No files matched your search

+3
View File
@@ -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
+14 -3
View File
@@ -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",
+4 -7
View File
@@ -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");
+12 -4
View File
@@ -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,
};
};
+53
View File
@@ -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 }),
]),
}),
]),
});
},
);