import { Budget } from "../domain/budget.js"; import type { FileHandle } from "node:fs/promises"; import { ArtifactReaderFailure, assertArtifactReadActive, } from "../resources/index.js"; import { readArtifactFileBytes } from "./ArtifactFileRange.js"; import { decodeLz4Block } from "../compression/Lz4Block.js"; import { BinaryReader, BinaryFormatFailure, BinaryResourceFailure, } from "../domain/binaryContainer.js"; import { setImmediate } from "node:timers/promises"; import { hasUnityFsHeader, readUnityFsHeaderFacts, UNITYFS_COMPRESSION_LZ4, UNITYFS_COMPRESSION_LZ4HC, UNITYFS_COMPRESSION_NONE, UNITYFS_FLAG_BLOCKS_INFO_AT_END, UNITYFS_FLAG_COMPRESSION_MASK, UNITYFS_FORMAT_VERSION_MAX, UNITYFS_FORMAT_VERSION_MIN, UNITYFS_HEADER_PREFIX_BYTES, unityFsLayoutFlags, } from "../domain/unityfsFormat.js"; import { strictUtf8Decoder } from "../domain/strictUtf8.js"; /** Per-decode resource limits, not format limits. Plain blocks are streamed. */ const MAX_BLOCK_UNCOMPRESSED_BYTES = 64 * 1024 * 1024; const MAX_BLOCK_ENCODED_BYTES = MAX_BLOCK_UNCOMPRESSED_BYTES + Math.floor(MAX_BLOCK_UNCOMPRESSED_BYTES / 255) + 16; const MAX_TABLE_BYTES = 16 * 1024 * 1024; const DIRECTORY_BUDGET_BYTES = 64 * 1024 * 1024; const directoryLimit = (): ArtifactReaderFailure => new ArtifactReaderFailure( "limit", "UnityFS directory exceeds its 16 MiB buffer or 64 MiB representation budget", { boundary: "memory" }, ); const UTF8 = strictUtf8Decoder("preserve"); export interface UnityFsHeader { readonly formatVersion: number; readonly playerVersion: string; readonly engineVersion: string; readonly declaredSize: number; readonly flags: number; readonly compressedBlocksInfoSize: number; readonly uncompressedBlocksInfoSize: number; readonly blocksInfoAtEnd: boolean; readonly compression: number; readonly layout: | { readonly status: | "encrypted" | "unsupported-compression" | "unsupported-layout"; } | { readonly status: "available"; readonly blocksInfoOffset: number; readonly afterHeader: number; readonly dataPadding: boolean; }; } export interface UnityFsBlock { readonly uncompressedSize: number; readonly compressedSize: number; readonly flags: number; readonly compression: number; /** Prefix count lets range consumers identify unsupported content in O(1). */ readonly unavailableCount: number; /** Cumulative compressed byte offset inside the data area. */ readonly compressedStart: number; /** Cumulative uncompressed byte offset inside the virtual stream. */ readonly streamStart: number; } export interface UnityFsNode { readonly offset: number; readonly size: number; readonly flags: number; readonly path: string; } export interface UnityFsBlocksInfo { readonly dataHash: string; readonly blocks: readonly UnityFsBlock[]; readonly nodes: readonly UnityFsNode[]; readonly dataStart: number; } export const unityFsFormatFailure = (detail: string): ArtifactReaderFailure => new ArtifactReaderFailure("format", `UnityFS is malformed: ${detail}`); const align16 = (value: number): number => (value + 15) & ~15; /** Decode header fields once; unsupported content does not erase observed headers. */ export const readUnityFsHeader = async ( handle: FileHandle, size: number, signal?: AbortSignal, ): Promise => { const prefix = await readArtifactFileBytes( handle, 0, Math.min(size, UNITYFS_HEADER_PREFIX_BYTES), size, signal, ); if (prefix.length < 20 || !hasUnityFsHeader(prefix)) return undefined; const facts = readUnityFsHeaderFacts(prefix); if (facts === undefined) throw unityFsFormatFailure("header is truncated or exceeds its bounds"); if ( facts.formatVersion < UNITYFS_FORMAT_VERSION_MIN || facts.formatVersion > UNITYFS_FORMAT_VERSION_MAX ) throw new ArtifactReaderFailure( "unavailable", `UnityFS format ${String(facts.formatVersion)} is unsupported; ${String(UNITYFS_FORMAT_VERSION_MIN)}-${String(UNITYFS_FORMAT_VERSION_MAX)} are supported`, ); if (facts.declaredSize > BigInt(size)) throw unityFsFormatFailure("declared size exceeds the file"); if (facts.declaredSize < BigInt(facts.afterFixed)) throw unityFsFormatFailure("declared size excludes the header"); const declaredSize = Number(facts.declaredSize); if (facts.compressedBlocksInfoSize > declaredSize - facts.afterFixed) throw unityFsFormatFailure( "declared blocks-info exceeds the bundle extent", ); const blocksInfoAtEnd = (facts.flags & UNITYFS_FLAG_BLOCKS_INFO_AT_END) !== 0; const compression = facts.flags & UNITYFS_FLAG_COMPRESSION_MASK; const common = { formatVersion: facts.formatVersion, playerVersion: facts.playerVersion, engineVersion: facts.engineVersion, declaredSize, flags: facts.flags, compressedBlocksInfoSize: facts.compressedBlocksInfoSize, uncompressedBlocksInfoSize: facts.uncompressedBlocksInfoSize, blocksInfoAtEnd, compression, }; const layout = unityFsLayoutFlags( facts.formatVersion, facts.engineVersion, facts.flags, ); if (layout.encrypted === true) return { ...common, layout: { status: "encrypted" } }; if ( layout.encrypted === undefined || layout.headerAligned === undefined || layout.dataPadding === undefined ) return { ...common, layout: { status: "unsupported-layout" } }; if ( compression !== UNITYFS_COMPRESSION_NONE && compression !== UNITYFS_COMPRESSION_LZ4 && compression !== UNITYFS_COMPRESSION_LZ4HC ) return { ...common, layout: { status: "unsupported-compression" } }; const position = layout.headerAligned ? align16(facts.afterFixed) : facts.afterFixed; if (position > declaredSize) throw unityFsFormatFailure("declared size excludes the padded header"); const blocksInfoOffset = blocksInfoAtEnd ? declaredSize - facts.compressedBlocksInfoSize : position; if ( blocksInfoOffset < position || facts.compressedBlocksInfoSize > declaredSize - blocksInfoOffset ) throw unityFsFormatFailure( "declared blocks-info exceeds the bundle extent", ); return { ...common, layout: { status: "available", afterHeader: position, blocksInfoOffset, dataPadding: layout.dataPadding, }, }; }; const decodeBlocksInfoTable = async ( header: UnityFsHeader, compressed: Buffer, signal?: AbortSignal, ): Promise => { const compression = header.compression; if (compression === UNITYFS_COMPRESSION_NONE) { if (compressed.length !== header.uncompressedBlocksInfoSize) throw unityFsFormatFailure( "plain directory size disagrees with its declaration", ); return compressed; } if ( compression === UNITYFS_COMPRESSION_LZ4 || compression === UNITYFS_COMPRESSION_LZ4HC ) return decodeUnityFsLz4( compressed, header.uncompressedBlocksInfoSize, signal, ); throw new ArtifactReaderFailure( "unavailable", `UnityFS blocks-info compression ${String(compression)} is unsupported`, ); }; /** Translate decoder failures once, without erasing cancellation or resource reasons. */ export const decodeUnityFsLz4 = async ( encoded: Buffer, expected: number, signal?: AbortSignal, ): Promise => { try { return await decodeLz4Block( encoded, expected, MAX_BLOCK_UNCOMPRESSED_BYTES, signal, ); } catch (cause: unknown) { if (cause instanceof ArtifactReaderFailure) throw cause; if (cause instanceof BinaryResourceFailure) throw new ArtifactReaderFailure( "limit", "UnityFS LZ4 exceeds the decoder memory budget", { cause, boundary: "memory" }, ); if (cause instanceof BinaryFormatFailure) throw new ArtifactReaderFailure( "format", "UnityFS is malformed: LZ4 block does not decode to its declared size", { cause }, ); throw cause; } }; const parseBlocks = async ( table: BinaryReader, dataBytes: number, budget: Budget, signal?: AbortSignal, ): Promise => { if (table.bytes.length < 24) throw unityFsFormatFailure("blocks-info table is truncated"); const blockCount = table.u32(16); if (20 + blockCount * 10 + 4 > table.bytes.length) throw unityFsFormatFailure("declared block count exceeds the table"); // Includes array slots, numeric fields and the retained lookup representation. budget.charge(blockCount * 256, directoryLimit); const blocks: UnityFsBlock[] = []; let cursor = 20; let compressedStart = 0; let streamStart = 0; let unavailableCount = 0; for (let index = 0; index < blockCount; index++) { if (index % 256 === 0) await setImmediate(); assertArtifactReadActive(signal); const uncompressedSize = table.u32(cursor); const compressedSize = table.u32(cursor + 4); const flags = table.u16(cursor + 8); if (compressedSize > dataBytes - compressedStart) throw unityFsFormatFailure( "declared data area exceeds the bundle extent", ); const compression = flags & UNITYFS_FLAG_COMPRESSION_MASK; cursor += 10; const lz4 = compression === UNITYFS_COMPRESSION_LZ4 || compression === UNITYFS_COMPRESSION_LZ4HC; if ( lz4 && (uncompressedSize > MAX_BLOCK_UNCOMPRESSED_BYTES || compressedSize > MAX_BLOCK_ENCODED_BYTES) ) throw new ArtifactReaderFailure( "limit", "UnityFS LZ4 block exceeds its 64 MiB decoded or bounded encoded buffer budget", { boundary: "memory" }, ); if ( compression === UNITYFS_COMPRESSION_NONE && compressedSize !== uncompressedSize ) throw unityFsFormatFailure( "plain block size disagrees with its declaration", ); if ( uncompressedSize > 0 && compression !== UNITYFS_COMPRESSION_NONE && !lz4 ) unavailableCount++; if (compression !== UNITYFS_COMPRESSION_NONE && compressedSize === 0) throw unityFsFormatFailure("compressed block declares no bytes"); blocks.push({ uncompressedSize, compressedSize, flags, compression, unavailableCount, compressedStart, streamStart, }); compressedStart += compressedSize; streamStart += uncompressedSize; } return blocks; }; const parseNodes = async ( table: BinaryReader, blocks: readonly UnityFsBlock[], budget: Budget, signal?: AbortSignal, ): Promise => { let cursor = 20 + blocks.length * 10; if (cursor + 4 > table.bytes.length) throw unityFsFormatFailure("node count is missing from the table"); const nodeCount = table.u32(cursor); cursor += 4; if (cursor + nodeCount * 21 > table.bytes.length) throw unityFsFormatFailure("declared node count exceeds the table"); // Covers parsed rows plus the reader's owned entries/map; paths are charged separately. budget.charge(nodeCount * 512, directoryLimit); const streamSize = blocks.length === 0 ? 0 : (blocks[blocks.length - 1]?.streamStart ?? 0) + (blocks[blocks.length - 1]?.uncompressedSize ?? 0); const nodes: UnityFsNode[] = []; for (let index = 0; index < nodeCount; index++) { if (index % 256 === 0) await setImmediate(); assertArtifactReadActive(signal); if (cursor + 20 > table.bytes.length) throw unityFsFormatFailure("node fixed fields are truncated"); const offsetBig = table.word(cursor, 64); const sizeBig = table.word(cursor + 8, 64); const flags = table.u32(cursor + 16); cursor += 20; const nameEnd = table.bytes.indexOf(0, cursor); if (nameEnd === -1) throw unityFsFormatFailure("node path is unterminated"); // UTF-16 plus repeated JSON-escaped source/canonical path projections. budget.charge((nameEnd - cursor) * 24, directoryLimit); const name = table.range(cursor, nameEnd - cursor, "UnityFS node path"); let path: string; try { path = UTF8.decode(name); } catch (cause: unknown) { throw new ArtifactReaderFailure( "format", "UnityFS node path is not valid UTF-8", { cause }, ); } cursor = nameEnd + 1; // Preserve the source spelling; ArtifactPaths owns destination validation. if (path.length === 0) throw unityFsFormatFailure("empty member path"); if ( offsetBig > BigInt(streamSize) || sizeBig > BigInt(streamSize) - offsetBig ) throw unityFsFormatFailure(`member exceeds the stream: ${path}`); nodes.push({ offset: Number(offsetBig), size: Number(sizeBig), flags, path, }); } return nodes; }; export const readUnityFsBlocksInfo = async ( handle: FileHandle, header: UnityFsHeader, signal?: AbortSignal, ): Promise => { const layout = header.layout; if (layout.status !== "available") throw new ArtifactReaderFailure( "unavailable", "UnityFS directory layout is unavailable", ); if ( header.compressedBlocksInfoSize > MAX_TABLE_BYTES || header.uncompressedBlocksInfoSize > MAX_TABLE_BYTES ) throw directoryLimit(); const unalignedDataStart = header.blocksInfoAtEnd ? layout.afterHeader : layout.blocksInfoOffset + header.compressedBlocksInfoSize; const dataStart = layout.dataPadding ? align16(unalignedDataStart) : unalignedDataStart; const dataEnd = header.blocksInfoAtEnd ? layout.blocksInfoOffset : header.declaredSize; if (dataStart < 0 || dataStart > dataEnd) throw unityFsFormatFailure("declared data area exceeds the bundle extent"); const budget = new Budget(DIRECTORY_BUDGET_BYTES); budget.charge(header.compressedBlocksInfoSize, directoryLimit); if (header.compression !== UNITYFS_COMPRESSION_NONE) budget.charge(header.uncompressedBlocksInfoSize, directoryLimit); const compressed = await readArtifactFileBytes( handle, layout.blocksInfoOffset, header.compressedBlocksInfoSize, header.declaredSize, signal, ); const table = new BinaryReader( await decodeBlocksInfoTable(header, compressed, signal), false, "unityfs", ); const blocks = await parseBlocks(table, dataEnd - dataStart, budget, signal); const nodes = await parseNodes(table, blocks, budget, signal); return { dataHash: table.range(0, 16, "UnityFS data hash").toString("hex"), blocks, nodes, dataStart, }; };