Files
reverse-engineering-anything/src/domain/unityfsFormat.ts
T
morluto cabd56ea71 refactor(domain): give strict UTF-8 decoding one owner with an explicit BOM policy (#10728)
* refactor(domain): give strict UTF-8 decoding one owner with an explicit BOM policy

* fix(domain): keep the leading-BOM behaviour every migrated UTF-8 decoder had

* refactor(domain): read the domain layer's strict UTF-8 through the BOM-policy owner (#10803)

Twelve domain decoders built their own fatal TextDecoder with ignoreBOM: true. They now use strictUtf8Decoder("preserve"), which keeps that behaviour: each reads bytes where a leading U+FEFF is content (binary-format names and fields, JSON and XML read byte-for-byte, recorded bodies, registry seeds whose kept bytes are re-emitted). The counted baseline drops from 74 to 62.

* refactor(artifacts): read artifact readers' strict UTF-8 through the BOM-policy owner (#10871)

Fourteen artifact reader modules (17 sites) built their own fatal TextDecoder. They now take it from strictUtf8Decoder with the policy each had: every one kept a leading BOM (ignoreBOM: true), so they use "preserve"; JavaScriptArtifactFiles keeps it for JavaScript and HTML entries and strips it otherwise, as before. The strict-utf8-decoder baseline drops those 17 sites.

* refactor(domain): drop TextDecoder imports left by the strict UTF-8 migration

* refactor(application): read MCP registration metadata through the strict UTF-8 owner

* refactor(formats): read binary-format readers' strict UTF-8 through the BOM-policy owner (#10903)

* refactor(formats): read binary-format readers' strict UTF-8 through the BOM-policy owner

* refactor(formats): drop the model readers' unused TextDecoder imports

* refactor(browser): read browser capture and fetch strict UTF-8 through the BOM-policy owner (#10935)

* refactor(browser): read browser capture and fetch strict UTF-8 through the BOM-policy owner

* refactor(native): read LLDB and Mach-O name strict UTF-8 through the BOM-policy owner (#10936)

* refactor(native): read LLDB and Mach-O name strict UTF-8 through the BOM-policy owner

* refactor(process): read MCP and NDJSON transport frames' strict UTF-8 through the BOM-policy owner (#10937)

* refactor(process): read MCP and NDJSON transport frames' strict UTF-8 through the BOM-policy owner

* refactor(application): read JSON and file inputs' strict UTF-8 through the BOM-policy owner (#10938)

* refactor(application): read JSON and file inputs' strict UTF-8 through the BOM-policy owner

* refactor(providers): read IDA, Electron, Ghidra and reference strict UTF-8 through the BOM-policy owner (#10939)

* refactor(providers): read IDA, Electron, Ghidra and reference strict UTF-8 through the BOM-policy owner

* refactor(evm): read the hex bytecode carrier's strict UTF-8 through the owner and refuse new local decoders (#10940)

* refactor(evm): read the hex bytecode carrier's strict UTF-8 through the BOM-policy owner

* chore(architecture): match local strict UTF-8 decoders in any option order
2026-11-15 19:54:39 +08:00

175 lines
5.8 KiB
TypeScript

import { strictUtf8Decoder } from "./strictUtf8.js";
/**
* UnityFS (AssetBundle) container structure: a fixed signature header followed
* by a compressed blocks-and-directory table and a block-compressed data area.
* All multi-byte fields in the header and table are big-endian.
*/
export const UNITYFS_SIGNATURE = Buffer.from("UnityFS\0", "latin1");
/** Whether bytes start with a standalone UnityFS header. */
export const hasUnityFsHeader = (bytes: Uint8Array): boolean =>
bytes.length >= UNITYFS_SIGNATURE.length &&
Buffer.from(bytes.buffer, bytes.byteOffset, UNITYFS_SIGNATURE.length).equals(
UNITYFS_SIGNATURE,
);
/**
* Header dataflags. Producer revision, rather than format number alone,
* determines whether 0x200 declares padding or Unity-CN encryption.
*/
export const UNITYFS_FLAG_COMPRESSION_MASK = 0x3f;
export const UNITYFS_FLAG_BLOCKS_INFO_AT_END = 0x80;
const UNITYFS_FLAG_PADDING_OR_LEGACY_ENCRYPTION = 0x200;
export const UNITYFS_FLAG_USES_BUNDLE_ENCRYPTION = 0x1400;
/** Per-block compression values in the low six flag bits. */
export const UNITYFS_COMPRESSION_NONE = 0;
export const UNITYFS_COMPRESSION_LZ4 = 2;
export const UNITYFS_COMPRESSION_LZ4HC = 3;
/** Supported block-table revisions. */
export const UNITYFS_FORMAT_VERSION_MIN = 6;
// Version 9 adds explicit block offsets; it needs a different table reader.
export const UNITYFS_FORMAT_VERSION_MAX = 8;
/** Header is aligned to 16 bytes for format 7+ and for 2019.4.15+ producers. */
const unityfsHeaderAligned = (
formatVersion: number,
engineMajor: number | undefined,
engineMinor: number | undefined,
enginePatch: number | undefined,
): boolean =>
formatVersion >= 7 ||
(engineMajor === 2019 &&
engineMinor === 4 &&
enginePatch !== undefined &&
enginePatch >= 15);
type UnityFsRevision = readonly [major: number, minor: number, patch: number];
const parseUnityFsRevision = (value: string): UnityFsRevision | undefined => {
// Unity-CN appends cN to otherwise ordinary release revisions.
const match = /^([1-9]\d*)\.(\d+)\.(\d+)(?:[abfp]\d+(?:c\d+)?)?$/u.exec(
value,
);
if (match === null) return undefined;
const major = Number(match[1]),
minor = Number(match[2]),
patch = Number(match[3]);
return [major, minor, patch].every(Number.isSafeInteger)
? [major, minor, patch]
: undefined;
};
const hasModernUnityFsFlags = ([
major,
minor,
patch,
]: UnityFsRevision): boolean => {
if (major < 2020) return false;
if (major > 2022) return true;
const minorThreshold = major === 2022 ? 1 : 3;
const patchThreshold = major === 2020 ? 34 : major === 2021 ? 2 : 1;
return (
minor > minorThreshold ||
(minor === minorThreshold && patch >= patchThreshold)
);
};
/** Interpret the reused padding/encryption bit once, retaining ambiguous revisions. */
export const unityFsLayoutFlags = (
formatVersion: number,
engineVersion: string,
flags: number,
): {
readonly headerAligned: boolean | undefined;
readonly dataPadding: boolean | undefined;
readonly encrypted: boolean | undefined;
} => {
const revision = parseUnityFsRevision(engineVersion);
const reusedBit = (flags & UNITYFS_FLAG_PADDING_OR_LEGACY_ENCRYPTION) !== 0;
const modernBits = (flags & UNITYFS_FLAG_USES_BUNDLE_ENCRYPTION) !== 0;
if (revision === undefined)
return {
headerAligned: formatVersion >= 7 ? true : undefined,
dataPadding: reusedBit ? undefined : false,
encrypted: reusedBit || modernBits ? undefined : false,
};
const modern = hasModernUnityFsFlags(revision);
return {
headerAligned: unityfsHeaderAligned(formatVersion, ...revision),
dataPadding: modern && reusedBit,
// New encryption bits in an old producer declaration are inconsistent.
encrypted: modern ? modernBits : modernBits ? undefined : reusedBit,
};
};
/** Producer version strings are short; the bound keeps a corrupt header local. */
export const UNITYFS_HEADER_STRING_MAX = 1024;
/** Declared header fields; support and extent admission belong to callers. */
export interface UnityFsHeaderFacts {
readonly formatVersion: number;
readonly playerVersion: string;
readonly engineVersion: string;
readonly declaredSize: bigint;
readonly compressedBlocksInfoSize: number;
readonly uncompressedBlocksInfoSize: number;
readonly flags: number;
/** Byte offset just past the fixed tail, before any block alignment. */
readonly afterFixed: number;
}
const utf8 = strictUtf8Decoder("preserve");
/**
* Decode declared fields after the caller admits a prefix covering the
* variable-length header. Undefined means the admitted bytes cannot carry a
* complete header; signature absence stays the caller's earlier check.
*/
export const readUnityFsHeaderFacts = (
bytes: Uint8Array,
): UnityFsHeaderFacts | undefined => {
if (!hasUnityFsHeader(bytes)) return undefined;
const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
let cursor = 12;
const readString = (): string | undefined => {
const start = cursor;
while (
cursor < bytes.length &&
cursor - start < UNITYFS_HEADER_STRING_MAX
) {
if (bytes[cursor] === 0) {
const value = bytes.subarray(start, cursor);
cursor += 1;
try {
return utf8.decode(value);
} catch {
return undefined;
}
}
cursor += 1;
}
return undefined;
};
const playerVersion = readString();
const engineVersion = readString();
if (
playerVersion === undefined ||
engineVersion === undefined ||
cursor + 20 > bytes.length
)
return undefined;
const fixed = cursor;
return {
formatVersion: view.getUint32(8),
playerVersion,
engineVersion,
declaredSize: view.getBigUint64(fixed),
compressedBlocksInfoSize: view.getUint32(fixed + 8),
uncompressedBlocksInfoSize: view.getUint32(fixed + 12),
flags: view.getUint32(fixed + 16),
afterFixed: fixed + 20,
};
};