diff --git a/docs/guides/javascript/v8-code-cache.md b/docs/guides/javascript/v8-code-cache.md index 40c2c69ce7..7c17450ca9 100644 --- a/docs/guides/javascript/v8-code-cache.md +++ b/docs/guides/javascript/v8-code-cache.md @@ -16,13 +16,16 @@ Evidence. ## What is read -A V8 code cache is a producer-written container, not a documented file format. This reader -admits one container shape and reports everything else as an observation, so a build it -has never seen still yields facts instead of a false parse. +A V8 code cache is a version-dependent container. This reader recognizes a pinned +layout with both supported header extents and reports observed header values and +payload bytes. -The 32-byte header is eight little-endian 32-bit words. Every word is reported in -`header.fields` with its byte offset, its observed value, the role this reader believes it -has, and how confident that role is: +The [Node v24.22.1 V8 serializer](https://github.com/nodejs/node/blob/v24.22.1/deps/v8/src/snapshot/code-serializer.h#L106-L119) +defines seven little-endian 32-bit words followed by pointer-alignment padding. +Four-byte alignment produces a 28-byte header. Eight-byte alignment produces a +32-byte header with a zero padding word. The reader derives the candidate header +extent from the container length and declared payload length. Each observed word +appears in `header.fields` with its byte offset, value, role, and confidence. | Offset | Role | Status | | -------------- | -------------- | ----------- | @@ -39,13 +42,15 @@ has, and how confident that role is: could plausibly differ. `unconfirmed` means the word is reported and nothing more is claimed. -Only three facts gate admission: +Admission requires the V8 magic high half `0xc0de` and a declared payload +that reaches the end of the file from a 28- or 32-byte header. +`ExternalReferenceTable::kSize` accounts for the varying low half of the magic word. +A candidate 28-byte header followed by a zero word is ambiguous. A 32-byte header +with a four-byte-truncated payload leaves its zero padding at the same offset as a +28-byte header whose payload begins with that word. The reader refuses that case. -1. the header size this reader pins (32 bytes); -2. the V8 code cache magic high half, `0xc0de`. The low half is - `ExternalReferenceTable::kSize` and varies per V8 build, so it is reported as a build - fingerprint and never required to match a fixed value; -3. the declared payload length must equal the bytes that follow the header exactly. +Header extent describes the retained bytes. The synthetic narrow fixture tests +reader admission. Runtime compatibility remains unverified for a 32-bit producer. `header.source_length` is the producer's recorded source length in UTF-16 code units. V8's serializer calls this field the source hash; on the producers measured here its value diff --git a/scripts/verify/baselines/raw-buffer-read.json b/scripts/verify/baselines/raw-buffer-read.json index 77622a1a9f..e02c78266d 100644 --- a/scripts/verify/baselines/raw-buffer-read.json +++ b/scripts/verify/baselines/raw-buffer-read.json @@ -8,6 +8,5 @@ "src/native/AppleObjcDispatchFacets.ts": 1, "src/native/AppleSwiftDispatchFacets.ts": 1, "src/native/elf/ElfNoteParser.ts": 6, - "src/native/pe/PeCertificateAsn1.ts": 2, - "src/v8/V8CodeCacheParser.ts": 1 + "src/native/pe/PeCertificateAsn1.ts": 2 } diff --git a/src/domain/v8/v8CodeCache.ts b/src/domain/v8/v8CodeCache.ts index cf52f26231..057713ab5d 100644 --- a/src/domain/v8/v8CodeCache.ts +++ b/src/domain/v8/v8CodeCache.ts @@ -12,8 +12,19 @@ const offset = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER); * process; it matches the pinned CPython pyc reader's 64 MiB ceiling. */ export const MAX_INSPECT_V8_CODE_CACHE_FILE_BYTES = 67108864; -/** Hard ceiling on the V8 code cache container header this reader accepts. */ +/** The 28-byte word area after alignment to an eight-byte pointer. */ export const V8_CODE_CACHE_HEADER_BYTES = 32; +/** The same word area with four-byte pointer alignment. */ +export const V8_CODE_CACHE_NARROW_HEADER_BYTES = 28; +/** Every container header size admitted by the pinned layout. */ +export const V8_CODE_CACHE_HEADER_SIZES: readonly number[] = [ + V8_CODE_CACHE_NARROW_HEADER_BYTES, + V8_CODE_CACHE_HEADER_BYTES, +]; +/** Shortest admitted header, so no selected file is smaller than this. */ +export const V8_CODE_CACHE_MIN_HEADER_BYTES = Math.min( + ...V8_CODE_CACHE_HEADER_SIZES, +); /** * V8 stamps every serialized code cache with `0xC0DE0000 ^ ExternalReferenceTable::kSize`. * Only the high half is stable across builds, so the low half is a build fingerprint and @@ -114,8 +125,8 @@ const headerSchema = z.strictObject({ magic: uint, /** High half of the magic, the only part stable across V8 builds. */ magic_build_stable: uint, - /** Every header word, in container order. */ - fields: z.array(headerFieldSchema).length(8), + /** Every header word this container carries, in container order. */ + fields: z.array(headerFieldSchema).min(7).max(8), /** Bytes this reader treats as header before the payload begins. */ header_bytes: uint, /** Source length in UTF-16 code units, as recorded by the producer, if determinable. */ @@ -178,11 +189,23 @@ export const v8CodeCacheSchema = z limitations: z.array(z.string().min(1)).min(1), }) .superRefine((report, context) => { - if (report.header.header_bytes !== V8_CODE_CACHE_HEADER_BYTES) + if (!V8_CODE_CACHE_HEADER_SIZES.includes(report.header.header_bytes)) context.addIssue({ code: "custom", path: ["header", "header_bytes"], - message: "This reader only accepts its pinned container header size.", + message: + "This reader only accepts the container header sizes it admits.", + }); + // The word table describes the container's own header, so it cannot disagree with it. + if ( + report.header.fields.length * 4 !== report.header.header_bytes || + report.header.fields.some(({ offset }, index) => offset !== index * 4) + ) + context.addIssue({ + code: "custom", + path: ["header", "fields"], + message: + "The reported words must cover the declared header in byte order.", }); if (report.header.magic_build_stable !== V8_CODE_CACHE_MAGIC_HIGH) context.addIssue({ @@ -191,6 +214,12 @@ export const v8CodeCacheSchema = z message: "The admitted magic must carry the stable V8 code cache high half.", }); + if (report.payload.offset !== report.header.header_bytes) + context.addIssue({ + code: "custom", + path: ["payload", "offset"], + message: "The payload must start at the end of the declared header.", + }); if (report.payload.offset + report.payload.bytes !== report.artifact.bytes) context.addIssue({ code: "custom", diff --git a/src/v8/V8CodeCache.fixture.ts b/src/v8/V8CodeCache.fixture.ts index be81df68ca..c7da6b6910 100644 --- a/src/v8/V8CodeCache.fixture.ts +++ b/src/v8/V8CodeCache.fixture.ts @@ -1,4 +1,8 @@ import vm from "node:vm"; +import { + V8_CODE_CACHE_HEADER_BYTES, + V8_CODE_CACHE_NARROW_HEADER_BYTES, +} from "../domain/v8/v8CodeCache.js"; /** * Generate a real V8 code cache instead of committing a version-pinned binary. Node @@ -9,6 +13,13 @@ export const v8CodeCacheFixture = ( ): Buffer => new vm.Script(source, { produceCachedData: true }).createCachedData(); +/** Build an offline reader fixture with the wide header's alignment word removed. */ +export const withSyntheticNarrowHeader = (wide: Buffer): Buffer => + Buffer.concat([ + wide.subarray(0, V8_CODE_CACHE_NARROW_HEADER_BYTES), + wide.subarray(V8_CODE_CACHE_HEADER_BYTES), + ]); + /** `vm.compileFunction` sets the producer bit in the source-length word. */ export const v8FunctionCodeCacheFixture = (source = "return 1 + 2;"): Buffer => vm.compileFunction(source, [], { produceCachedData: true }).cachedData ?? diff --git a/src/v8/V8CodeCacheParser.test.ts b/src/v8/V8CodeCacheParser.test.ts index 46df14a90c..2d62660e33 100644 --- a/src/v8/V8CodeCacheParser.test.ts +++ b/src/v8/V8CodeCacheParser.test.ts @@ -4,6 +4,8 @@ import { inspectV8CodeCacheInputSchema, v8CodeCacheSchema, V8_CODE_CACHE_HEADER_BYTES, + V8_CODE_CACHE_MAGIC_HIGH, + V8_CODE_CACHE_NARROW_HEADER_BYTES, type V8CodeCache, } from "../domain/v8/v8CodeCache.js"; import { parseV8CodeCache } from "./V8CodeCacheParser.js"; @@ -11,6 +13,7 @@ import { v8CodeCacheFixture, v8FunctionCodeCacheFixture, withHeaderWord, + withSyntheticNarrowHeader, } from "./V8CodeCache.fixture.js"; const defaults = inspectV8CodeCacheInputSchema.parse({ @@ -199,9 +202,9 @@ it("fails closed on a payload-length mismatch", () => { }); it("fails closed on a truncated header", () => { - expect(() => parse(real.subarray(0, V8_CODE_CACHE_HEADER_BYTES - 1))).toThrow( - expect.objectContaining({ kind: "malformed" }), - ); + expect(() => + parse(real.subarray(0, V8_CODE_CACHE_NARROW_HEADER_BYTES - 1)), + ).toThrow(expect.objectContaining({ kind: "malformed" })); }); it("fails closed when fewer payload bytes follow the header than it declares", () => { @@ -265,3 +268,136 @@ it("raises min_string_bytes and reports only runs that long", () => { const realSlice = (bytes: Buffer, offset: number, length: number): string => bytes.subarray(offset, offset + length).toString("latin1"); + +it("inspects a synthetic narrow layout derived from a 64-bit cache", () => { + // Removing the alignment word preserves the retained payload bytes. + const narrow = withSyntheticNarrowHeader(real); + const report = parse(narrow); + + expect(narrow.readUInt32LE(20)).toBe( + narrow.length - V8_CODE_CACHE_NARROW_HEADER_BYTES, + ); + expect(report.header.header_bytes).toBe(V8_CODE_CACHE_NARROW_HEADER_BYTES); + expect(report.payload.offset).toBe(V8_CODE_CACHE_NARROW_HEADER_BYTES); + // Nothing but the padding is removed, so the payload is identical. + expect(report.payload.sha256).toBe(parse(real).payload.sha256); + // The word table covers exactly the header this container carries. + expect(report.header.fields).toHaveLength(7); + expect(report.header.fields.map((entry) => entry.offset)).toEqual([ + 0, 4, 8, 12, 16, 20, 24, + ]); +}); + +it("fails closed when the declared payload leaves no admitted header size", () => { + // Padding that is neither 28 nor 32 bytes is not a container this reader admits. + expect(() => + parse( + Buffer.concat([ + real.subarray(0, V8_CODE_CACHE_NARROW_HEADER_BYTES + 2), + real.subarray(V8_CODE_CACHE_HEADER_BYTES), + ]), + ), + ).toThrow(expect.objectContaining({ kind: "malformed" })); +}); + +it("refuses a wide container that is only four bytes short", () => { + // Truncating a 32-byte-header cache by four bytes makes `bytes.length - declaredPayload` + // equal 28. The padding then occupies the same position as a zero first + // payload word in a narrow container, so the reader refuses the ambiguity. + const short = real.subarray(0, real.length - 4); + expect(short.readUInt32LE(28)).toBe(0); + expect(() => parse(short)).toThrow( + expect.objectContaining({ kind: "malformed" }), + ); + expect(() => parse(short)).toThrow(/ambiguous/u); + // A synthetic narrow fixture has payload at the same byte offset. + const narrow = withSyntheticNarrowHeader(real); + expect(narrow.readUInt32LE(V8_CODE_CACHE_NARROW_HEADER_BYTES)).not.toBe(0); + expect(parse(narrow).header.header_bytes).toBe( + V8_CODE_CACHE_NARROW_HEADER_BYTES, + ); +}); + +it("rejects a reported word table that does not cover the header it declares", () => { + // The parser derives both from one offset, so this pair cannot disagree on a + // parsed container; the schema is what a stored or projected report also goes + // through, and there the two are independent fields. Without these cases the + // rule could be deleted and every parser test would still pass. + const reported = (fieldCount: number, headerBytes: number) => ({ + artifact: { + path: "/artifacts/module.jsc", + sha256: "a".repeat(64), + bytes: 4096, + }, + header: { + magic: 0xf00d, + magic_build_stable: V8_CODE_CACHE_MAGIC_HIGH, + fields: Array.from({ length: fieldCount }, (_, index) => ({ + offset: index * 4, + value: index, + role: "reserved", + status: "unconfirmed" as const, + })), + header_bytes: headerBytes, + source_length: 10, + producer: "script" as const, + }, + payload: { + offset: headerBytes, + bytes: 4096 - headerBytes, + sha256: "b".repeat(64), + trailing_bytes: 0, + }, + embedded_strings: [], + coverage: { + status: "complete" as const, + scanned_bytes: 4096 - headerBytes, + strings: 0, + }, + limitations: ["measured on one producer"], + }); + + // Seven words is 28 bytes and eight is 32, so each header size has exactly one + // word count that covers it. + const cases = [ + { fields: 7, bytes: V8_CODE_CACHE_HEADER_BYTES, accepted: false }, + { fields: 8, bytes: V8_CODE_CACHE_NARROW_HEADER_BYTES, accepted: false }, + { fields: 7, bytes: V8_CODE_CACHE_NARROW_HEADER_BYTES, accepted: true }, + { fields: 8, bytes: V8_CODE_CACHE_HEADER_BYTES, accepted: true }, + ]; + for (const { fields, bytes, accepted } of cases) { + const label = `${String(fields)} words / ${String(bytes)} bytes`; + const parsed = v8CodeCacheSchema.safeParse(reported(fields, bytes)); + expect(parsed.success, label).toBe(accepted); + expect( + parsed.error?.issues.some( + (issue) => issue.path.join(".") === "header.fields", + ) ?? false, + label, + ).toBe(!accepted); + } +}); + +it("rejects retained header and payload coordinates that disagree", () => { + const report = parse(real); + const disordered = { + ...report, + header: { + ...report.header, + fields: report.header.fields.map((field, index) => + index === 0 ? { ...field, offset: 4 } : field, + ), + }, + }; + const shiftedPayload = { + ...report, + artifact: { ...report.artifact, bytes: report.artifact.bytes + 4 }, + payload: { ...report.payload, offset: report.payload.offset + 4 }, + }; + expect( + v8CodeCacheSchema.safeParse(disordered).error?.issues ?? [], + ).toContainEqual(expect.objectContaining({ path: ["header", "fields"] })); + expect( + v8CodeCacheSchema.safeParse(shiftedPayload).error?.issues ?? [], + ).toContainEqual(expect.objectContaining({ path: ["payload", "offset"] })); +}); diff --git a/src/v8/V8CodeCacheParser.ts b/src/v8/V8CodeCacheParser.ts index 3f18ffddf8..a062b75848 100644 --- a/src/v8/V8CodeCacheParser.ts +++ b/src/v8/V8CodeCacheParser.ts @@ -4,6 +4,9 @@ import { V8_CODE_CACHE_LEGACY_MODULE_BIT, V8_CODE_CACHE_MODULE_BIT, V8_CODE_CACHE_HEADER_BYTES, + V8_CODE_CACHE_HEADER_SIZES, + V8_CODE_CACHE_MIN_HEADER_BYTES, + V8_CODE_CACHE_NARROW_HEADER_BYTES, V8_CODE_CACHE_MAGIC_HIGH, V8_CODE_CACHE_SOURCE_LENGTH_MASK, type V8CodeCache, @@ -13,6 +16,7 @@ import { V8_CODE_CACHE_FORMAT, v8CodeCacheBudgetFailure, } from "../v8/V8CodeCache.errors.js"; +import { BinaryReader } from "../domain/binaryContainer.js"; import { malformedInput, unsupportedInput } from "../domain/parseFailure.js"; import { sha256Hex } from "../kernel/sha256Hex.js"; @@ -72,28 +76,52 @@ export const parseV8CodeCache = ( ): V8CodeCache => { if (bytes.length !== artifact.bytes) malformed("Selected artifact length disagrees with the retained bytes."); - if (bytes.length < V8_CODE_CACHE_HEADER_BYTES) + if (bytes.length < V8_CODE_CACHE_MIN_HEADER_BYTES) malformed( - `Selected file is shorter than the ${String(V8_CODE_CACHE_HEADER_BYTES)}-byte V8 code cache header.`, + `Selected file is shorter than the ${String(V8_CODE_CACHE_MIN_HEADER_BYTES)}-byte V8 code cache header.`, ); - const field = (index: number): number => bytes.readUInt32LE(index * 4); - const magic = field(0); + const headerReader = new BinaryReader( + bytes.subarray(0, V8_CODE_CACHE_HEADER_BYTES), + true, + V8_CODE_CACHE_FORMAT, + ); + const readField = (entry: (typeof HEADER_ROLES)[number], index: number) => { + const offset = index * 4; + return { offset, value: headerReader.u32(offset), ...entry }; + }; + const commonFieldCount = V8_CODE_CACHE_NARROW_HEADER_BYTES / 4; + const fields = HEADER_ROLES.slice(0, commonFieldCount).map(readField); + const magic = fields[0]!.value; const magicHigh = magic >>> 16; if (magicHigh !== V8_CODE_CACHE_MAGIC_HIGH) unsupported( `Container magic 0x${magic.toString(16).padStart(8, "0")} does not carry the V8 code cache high half 0x${V8_CODE_CACHE_MAGIC_HIGH.toString(16)}; this file is not a V8 code cache.`, ); - const declaredPayload = field(5); - const payloadOffset = V8_CODE_CACHE_HEADER_BYTES; - const expectedPayload = bytes.length - payloadOffset; - if (declaredPayload !== expectedPayload) + // The declared payload length gives the candidate aligned header extent. + const declaredPayload = fields[5]!.value; + const payloadOffset = bytes.length - declaredPayload; + if (!V8_CODE_CACHE_HEADER_SIZES.includes(payloadOffset)) malformed( - `Header declares a ${String(declaredPayload)}-byte payload but ${String(expectedPayload)} bytes follow the ${String(V8_CODE_CACHE_HEADER_BYTES)}-byte header; the container is truncated or corrupt.`, + `Header declares a ${String(declaredPayload)}-byte payload, leaving ${String(payloadOffset)} header bytes, which is no admitted V8 code cache header size (${V8_CODE_CACHE_HEADER_SIZES.join(" or ")}); the container is truncated or corrupt.`, + ); + // Node v24.22.1's SerializedCodeData writer in code-serializer.cc zeroes + // the alignment bytes after its words. A missing final wide payload word + // and a narrow payload beginning with a zero word are indistinguishable here. + if ( + payloadOffset === V8_CODE_CACHE_NARROW_HEADER_BYTES && + bytes.length >= V8_CODE_CACHE_HEADER_BYTES && + headerReader.u32(V8_CODE_CACHE_NARROW_HEADER_BYTES) === 0 + ) + malformed( + "A 28-byte header extent followed by a zero word is ambiguous: the file may have a zero-leading narrow payload or a truncated 32-byte layout.", ); - const sourceWord = field(2); + if (payloadOffset === V8_CODE_CACHE_HEADER_BYTES) + fields.push(readField(HEADER_ROLES[commonFieldCount]!, commonFieldCount)); + + const sourceWord = fields[2]!.value; const sourceLength = sourceWord & V8_CODE_CACHE_SOURCE_LENGTH_MASK; // Bit 30 marks a `vm.SourceTextModule` cache and bit 29 a `vm.compileFunction` one. // Measured on Node 24.22.1, a 19-unit module source reads `0x40000013` while a script of @@ -162,13 +190,8 @@ export const parseV8CodeCache = ( header: { magic, magic_build_stable: magicHigh, - fields: HEADER_ROLES.map((entry, index) => ({ - offset: index * 4, - value: field(index), - role: entry.role, - status: entry.status, - })), - header_bytes: V8_CODE_CACHE_HEADER_BYTES, + fields, + header_bytes: payloadOffset, source_length: sourceLength, producer, }, diff --git a/tests/acceptance/v8CodeCacheCli.test.ts b/tests/acceptance/v8CodeCacheCli.test.ts index a60713fa34..89737816ba 100644 --- a/tests/acceptance/v8CodeCacheCli.test.ts +++ b/tests/acceptance/v8CodeCacheCli.test.ts @@ -3,34 +3,44 @@ import { writeFile } from "node:fs/promises"; import { join } from "node:path"; import { expect } from "vitest"; import { toolContract } from "../../src/contracts/toolContracts.js"; -import { v8CodeCacheFixture } from "../../src/v8/V8CodeCache.fixture.js"; +import { + v8CodeCacheFixture, + withSyntheticNarrowHeader, +} from "../../src/v8/V8CodeCache.fixture.js"; import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; import { cliTest } from "../support/cli/cliFixture.js"; const outputSchema = toolContract("inspect_v8_code_cache").outputSchema; cliTest( - "reports the observed header and payload through the public CLI", + "reports wide and synthetic narrow header extents through the public CLI", async ({ cli }) => { const root = await createTestTempDirectory("rea-v8-cli-"); - const path = join(root, "module.jsc"); - const bytes = v8CodeCacheFixture( - "function add(a, b) { return a + b; } add(1, 2);", - ); - await writeFile(path, bytes); - const result = await cli.run({ - arguments: ["inspect-v8-code-cache", path, "--json"], - }); - expect(result.exitCode, result.stderr).toBe(0); - const evidence = outputSchema.parse(result.json); - const report = evidence.normalized_result; - expect(report.header.magic).toBe(bytes.readUInt32LE(0)); - expect(report.header.magic_build_stable).toBe(0xc0de); - expect(report.header.fields).toHaveLength(8); - expect(report.payload.offset).toBe(32); - expect(report.payload.bytes).toBe(bytes.length - 32); - expect(report.payload.sha256).toMatch(/^[0-9a-f]{64}$/u); - expect(report.coverage.status).toBe("complete"); + const wide = v8CodeCacheFixture(); + const narrow = withSyntheticNarrowHeader(wide); + const payloadDigest = createHash("sha256") + .update(wide.subarray(32)) + .digest("hex"); + for (const [bytes, headerBytes] of [ + [wide, 32], + [narrow, 28], + ] as const) { + const path = join(root, `header-${String(headerBytes)}.jsc`); + await writeFile(path, bytes); + const result = await cli.run({ + arguments: ["inspect-v8-code-cache", path, "--json"], + }); + expect(result.exitCode, result.stderr).toBe(0); + const report = outputSchema.parse(result.json).normalized_result; + expect(report.header.magic).toBe(bytes.readUInt32LE(0)); + expect(report.header.magic_build_stable).toBe(0xc0de); + expect(report.header.header_bytes).toBe(headerBytes); + expect(report.header.fields).toHaveLength(headerBytes / 4); + expect(report.payload.offset).toBe(headerBytes); + expect(report.payload.bytes).toBe(bytes.length - headerBytes); + expect(report.payload.sha256).toBe(payloadDigest); + expect(report.coverage.status).toBe("complete"); + } }, );