Files
reverse-engineering-anything/src/artifacts/NodeSeaArtifactReader.test.ts
T
Matt Van Hornandgensokyo-dev a88c0a5554 feat(artifacts): inspect Android boot image components
Inventory Android boot and vendor_boot images through shared artifact workflows. Preserve parser failure kinds and bounded stored-component extraction.

Assisted-by: Suika (gensokyo-skills:suika-scatter-gather-planning)
Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
2026-11-17 12:08:42 +00:00

1229 lines
40 KiB
TypeScript

import { createHash } from "node:crypto";
import { once } from "node:events";
import { writeFileSync } from "node:fs";
import { buffer } from "node:stream/consumers";
import { createReader } from "./inventory/reader.js";
import {
open,
readFile,
stat,
writeFile,
type FileHandle,
} from "node:fs/promises";
import { join } from "node:path";
import { setImmediate } from "node:timers";
import { expect, it, vi } from "vitest";
import * as artifactPaths from "../resources/ArtifactPaths.js";
import { NodeSeaArtifactReader } from "./NodeSeaArtifactReader.js";
import type { ArtifactEntry } from "../resources/ArtifactReader.js";
import { artifactFormatDescriptor } from "./artifactFormats.js";
import { ArtifactResourceScope } from "../resources/ArtifactResourceScope.js";
import { extractArtifact } from "./extraction/ArtifactExtraction.js";
import {
NODE_SEA_FUSE_HASH,
NODE_SEA_FIXTURE_MAGIC,
buildNodeSeaBlob,
nodeSeaElf,
nodeSeaMachO,
nodeSeaPe,
nodeSeaUniversal,
} from "./nodeSea/NodeSea.fixture.js";
import { elfNote, elfNoteFixture } from "../native/elf/ElfNotes.fixture.js";
import { peResourceFixture } from "../domain/pe/peResources.fixture.js";
import { locateNodeSea } from "./nodeSea/NodeSeaLocation.js";
import { MAX_INSPECT_PE_FILE_BYTES } from "../domain/native/peResources.js";
import { openRegularFile } from "../filesystem/RegularFile.js";
import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js";
import { scanCanonicalArtifactInventory } from "../../tests/fixtures/artifactInventory.js";
import { classifyAndHashRootForInventory } from "./inventory/classify.js";
import { DEFAULT_NODE_SEA_READER_LIMITS } from "../domain/artifactReaderLimits.js";
const writeCarrier = async (name: string, bytes: Buffer): Promise<string> => {
const directory = await createTestTempDirectory("rea-node-sea-");
const path = join(directory, name);
await writeFile(path, bytes);
return path;
};
const seaEntries = async (
reader: NodeSeaArtifactReader,
): Promise<ArtifactEntry[]> => {
const entries: ArtifactEntry[] = [];
for await (const entry of reader.entries()) entries.push(entry);
return entries;
};
const script = 'console.log("rea-node-sea")\n';
const populated = {
codePath: "app/main.js",
main: script,
codeCache: Buffer.from("cache"),
assets: [{ name: "assets/message.txt", body: "hello" }],
execArgv: ["--no-warnings"],
disableExperimentalSeaWarning: true,
fuse: "set" as const,
};
it("rechecks a lower SEA policy instead of reusing an earlier admitted decode", async () => {
const path = await writeCarrier(
"sea-policy",
nodeSeaElf({ execArgv: ["one", "two"], fuse: "set" }),
);
const scope = new ArtifactResourceScope();
try {
await scope.run(async () => {
const classified = await classifyAndHashRootForInventory(
path,
false,
await stat(path),
{ resourceScope: scope },
);
const source = classified.rootSource;
if (source !== undefined) scope.addCloseHook(() => source.owner.close());
const admitted = classified.readerAdmission;
if (
admitted === undefined ||
!("kind" in admitted) ||
admitted.kind !== "node-sea"
)
throw new Error("Expected a production Node SEA admission");
const refused = new NodeSeaArtifactReader(path, admitted, {
...DEFAULT_NODE_SEA_READER_LIMITS,
argument_count: 1,
});
try {
await expect(seaEntries(refused)).rejects.toMatchObject({
reason: "limit",
readerLimit: {
parameter: "artifact_limits.node_sea.argument_count",
effective_value: 1,
required_value: 2,
},
});
} finally {
await refused.close();
}
const recovered = new NodeSeaArtifactReader(path, admitted, {
...DEFAULT_NODE_SEA_READER_LIMITS,
argument_count: 2,
});
try {
await seaEntries(recovered);
expect(recovered.formatMetadata()?.exec_argv).toEqual(["one", "two"]);
} finally {
await recovered.close();
}
});
} finally {
await scope.close();
}
});
it("locates SEA after a long unrelated ELF note owner without admitting its text", async () => {
const notes = Buffer.concat([
elfNote("vendor".repeat(700), 1, Buffer.from("unrelated")),
elfNote(
"NODE_SEA_BLOB",
0,
buildNodeSeaBlob({ main: script, codePath: "sea.js" }),
),
]);
const path = await writeCarrier(
"long-note-owner",
elfNoteFixture({ notes, ownership: "program", type: 2 }),
);
const snapshot = await scanCanonicalArtifactInventory(path);
expect(snapshot.manifest.root_format).toBe("node-sea");
expect(snapshot.occurrences).toContainEqual(
expect.objectContaining({
logical_path: "sea.js",
declared_size: Buffer.byteLength(script),
}),
);
});
it("applies selected aggregate work before yielding SEA members", async () => {
const path = await writeCarrier(
"sea-expanded",
nodeSeaElf({
main: "hello",
assets: [{ name: "data", body: "world" }],
fuse: "set",
}),
);
const refused = new NodeSeaArtifactReader(
path,
undefined,
DEFAULT_NODE_SEA_READER_LIMITS,
9,
);
try {
await expect(seaEntries(refused)).rejects.toMatchObject({
reason: "limit",
readerLimit: {
parameter: "artifact_limits.expanded_bytes",
effective_value: 9,
required_value: 10,
},
});
} finally {
await refused.close();
}
const recovered = new NodeSeaArtifactReader(
path,
undefined,
DEFAULT_NODE_SEA_READER_LIMITS,
10,
);
try {
expect(await seaEntries(recovered)).toHaveLength(2);
} finally {
await recovered.close();
}
});
it.each([
["mach-o", nodeSeaMachO(populated)],
["elf", nodeSeaElf(populated)],
["pe", nodeSeaPe(populated)],
] as const)("inventories a %s Node SEA carrier", async (carrier, bytes) => {
const path = await writeCarrier(`sea-${carrier}`, bytes);
const snapshot = await scanCanonicalArtifactInventory(path);
expect(snapshot.manifest.root_format).toBe("node-sea");
expect(snapshot.coverage.status).toBe("complete");
const limitation = artifactFormatDescriptor("node-sea")?.readerLimitation;
if (limitation === undefined) throw new Error("Missing Node SEA limitation");
expect(snapshot.limitations).toContain(limitation);
expect(limitation).toMatch(/snapshots.*code cache.*not deserialized/iu);
expect(limitation).toMatch(/application.*not executed/iu);
expect(snapshot.limitations).not.toContainEqual(
expect.stringMatching(/NODE_SEA_FUSE sentinel.*unset/iu),
);
const root = snapshot.occurrences.find((row) => row.logical_path === ".");
expect(root).toMatchObject({ artifact_kind: "container" });
expect(root?.format_metadata).toMatchObject({
kind: "node-sea",
magic: NODE_SEA_FIXTURE_MAGIC,
carrier,
code_path: "app/main.js",
disable_experimental_sea_warning: true,
use_snapshot: false,
use_code_cache: true,
include_assets: true,
include_exec_argv: true,
exec_argv: ["--no-warnings"],
exec_argv_extension: "env",
fuse_state: "set",
fuse_sentinel: `NODE_SEA_FUSE_${NODE_SEA_FUSE_HASH}:1`,
fuse_contradiction: null,
});
expect(
snapshot.occurrences.find((row) => row.logical_path === "app/main.js"),
).toMatchObject({
artifact_kind: "javascript",
artifact_format: "javascript-bundle",
format_metadata: { kind: "node-sea-entry", role: "main-script" },
});
expect(
snapshot.occurrences.find(
(row) => row.logical_path === "__node_sea__/code-cache",
),
).toMatchObject({
artifact_format: "file",
format_metadata: { role: "code-cache" },
});
expect(
snapshot.occurrences.find(
(row) => row.logical_path === "assets/message.txt",
),
).toMatchObject({ format_metadata: { role: "asset" } });
const scriptNode = snapshot.nodes.find(
(node) => node.size === Buffer.byteLength(script),
);
expect(scriptNode).toBeDefined();
const direct = new NodeSeaArtifactReader(path);
try {
for await (const entry of direct.entries()) {
const occurrence = snapshot.occurrences.find(
(row) => row.logical_path === entry.path,
);
expect(occurrence?.format_metadata).toEqual(entry.formatMetadata);
const member = await buffer(await direct.open(entry));
expect(
snapshot.nodes.find(
(node) => node.artifact_id === occurrence?.artifact_id,
),
).toMatchObject({
sha256: createHash("sha256").update(member).digest("hex"),
size: member.length,
});
}
expect(direct.formatMetadata()).toEqual(root?.format_metadata);
} finally {
await direct.close();
}
});
it("accepts the __NODE_SEA segment spelling and a universal Mach-O slice", async () => {
const underscored = await scanCanonicalArtifactInventory(
await writeCarrier(
"underscored",
nodeSeaMachO({ ...populated, segmentName: "__NODE_SEA" }),
),
);
expect(underscored.manifest.root_format).toBe("node-sea");
const universal = await scanCanonicalArtifactInventory(
await writeCarrier("universal", nodeSeaUniversal(populated)),
);
expect(universal.manifest.root_format).toBe("node-sea");
expect(
universal.occurrences.find((row) => row.logical_path === ".")
?.format_metadata,
).toMatchObject({ carrier: "mach-o", fuse_state: "set" });
});
it("reads a 32-bit and a big-endian Mach-O section", async () => {
for (const bytes of [
nodeSeaMachO({ ...populated, bits: 32 }),
nodeSeaMachO({ ...populated, littleEndian: false }),
]) {
const snapshot = await scanCanonicalArtifactInventory(
await writeCarrier("macho-variant", bytes),
);
expect(snapshot.manifest.root_format).toBe("node-sea");
expect(
snapshot.occurrences.find((row) => row.logical_path === "app/main.js"),
).toMatchObject({ artifact_format: "javascript-bundle" });
}
});
it("classifies a main script without a JavaScript suffix as javascript-bundle", async () => {
const snapshot = await scanCanonicalArtifactInventory(
await writeCarrier(
"plain-name",
nodeSeaElf({ codePath: "main", main: script, fuse: "set" }),
),
);
expect(
snapshot.occurrences.find((row) => row.logical_path === "main"),
).toMatchObject({
artifact_kind: "javascript",
artifact_format: "javascript-bundle",
});
});
it("keeps a snapshot body opaque and retains the code path", async () => {
const snapshot = await scanCanonicalArtifactInventory(
await writeCarrier(
"snapshot",
nodeSeaElf({
codePath: "sea.js",
snapshot: Buffer.from("snap-bytes"),
fuse: "set",
}),
),
);
const root = snapshot.occurrences.find((row) => row.logical_path === ".");
expect(root?.format_metadata).toMatchObject({
use_snapshot: true,
code_path: "sea.js",
});
expect(
snapshot.occurrences.find((row) => row.logical_path === "sea.js"),
).toBeUndefined();
expect(
snapshot.occurrences.find(
(row) => row.logical_path === "__node_sea__/snapshot",
),
).toMatchObject({
artifact_format: "file",
format_metadata: { role: "snapshot" },
});
});
it.each([
["absent", undefined, "absent", null],
["unset", "unset", "unset", `NODE_SEA_FUSE_${NODE_SEA_FUSE_HASH}:0`],
] as const)(
"reports a %s fuse as a contradiction",
async (_label, fuse, state, sentinel) => {
const reason =
state === "absent"
? /no NODE_SEA_FUSE sentinel.*observed/iu
: /NODE_SEA_FUSE sentinel.*unset/iu;
const snapshot = await scanCanonicalArtifactInventory(
await writeCarrier(
"fuse",
nodeSeaElf({ ...(fuse === undefined ? {} : { fuse }), main: script }),
),
);
const metadata = snapshot.occurrences.find(
(row) => row.logical_path === ".",
)?.format_metadata;
expect(metadata).toMatchObject({
fuse_state: state,
fuse_sentinel: sentinel,
fuse_contradiction: expect.stringMatching(reason),
});
const contradiction = (metadata as { fuse_contradiction: string })
.fuse_contradiction;
expect(snapshot.limitations).toContain(contradiction);
expect(snapshot.coverage.status).toBe("complete");
},
);
it("reports disagreeing fuse sentinels", async () => {
const snapshot = await scanCanonicalArtifactInventory(
await writeCarrier("conflict", nodeSeaPe({ fuse: "conflicting" })),
);
const metadata = snapshot.occurrences.find(
(row) => row.logical_path === ".",
)?.format_metadata;
expect(metadata).toMatchObject({
fuse_state: "conflicting",
fuse_sentinel: null,
fuse_contradiction: expect.stringMatching(/fuse sentinels disagree/iu),
});
const contradiction = (metadata as { fuse_contradiction: string })
.fuse_contradiction;
expect(snapshot.limitations).toContain(contradiction);
});
it("leaves a Mach-O, ELF, or PE without a SEA slot in its native format", async () => {
const mach = await scanCanonicalArtifactInventory(
await writeCarrier(
"plain-macho",
nodeSeaMachO({
segmentName: "__TEXT",
sectionName: "__text",
blob: Buffer.from("text"),
}),
),
);
expect(mach.manifest.root_format).toBe("mach-o");
const elf = await scanCanonicalArtifactInventory(
await writeCarrier("plain-elf", elfNoteFixture({ type: 2 })),
);
expect(elf.manifest.root_format).toBe("elf");
const pe = await scanCanonicalArtifactInventory(
await writeCarrier("plain-pe", peResourceFixture(true).bytes),
);
expect(pe.manifest.root_format).toBe("pe");
});
it.each([false, true])(
"scopes the large PE admission limit to SEA resources (PE32+: %s)",
async (plus) => {
for (const sea of [false, true]) {
const bytes = peResourceFixture(plus, [
{
type: sea ? 10 : 11,
name: "NODE_SEA_BLOB",
language: 1033,
payload: buildNodeSeaBlob(populated),
},
{
type: 10,
name: "OTHER_RESOURCE",
language: 1033,
payload: Buffer.from("other"),
},
]).bytes;
const path = await writeCarrier("large-pe", bytes);
const handle = await open(path, "r+");
try {
if (!sea)
await expect(
locateNodeSea(handle, bytes.length),
).resolves.toBeUndefined();
await handle.truncate(MAX_INSPECT_PE_FILE_BYTES + 1);
const located = locateNodeSea(handle, MAX_INSPECT_PE_FILE_BYTES + 1);
if (sea)
await expect(located).rejects.toMatchObject({
reason: "limit",
message: expect.stringMatching(/PE.*512 MiB/iu),
});
else await expect(located).resolves.toBeUndefined();
} finally {
await handle.close();
}
}
},
);
it("trusts the PT_NOTE blob over a stale SHT_NOTE entry", async () => {
const bytes = nodeSeaElf({ ...populated, ownership: "both" });
// ELF64: the note section header follows one 56-byte program header.
const noteOffsetField = 64 + 56 + 64 + 24;
const noteOffset = bytes.readBigUInt64LE(noteOffsetField);
bytes.writeBigUInt64LE(noteOffset + 20n, noteOffsetField);
const inventory = await scanCanonicalArtifactInventory(
await writeCarrier("stale-section-note", bytes),
);
expect(inventory.manifest.root_format).toBe("node-sea");
});
it("leaves a non-SEA PE with a cyclic resource tree to native classification", async () => {
const fixture = peResourceFixture(true);
fixture.bytes.writeUInt32LE(0x80000000, (fixture.entryOffsets[0] ?? 0) + 4);
const path = await writeCarrier("cyclic-pe", fixture.bytes);
const handle = await open(path, "r");
try {
await expect(
locateNodeSea(handle, fixture.bytes.length),
).resolves.toBeUndefined();
} finally {
await handle.close();
}
const inventory = await scanCanonicalArtifactInventory(path);
expect(inventory.manifest.root_format).not.toBe("node-sea");
});
it("fails closed when the located blob is truncated, has a bad magic, or unknown flags", async () => {
await expect(
scanCanonicalArtifactInventory(
await writeCarrier(
"truncated",
nodeSeaElf({ blob: Buffer.from([0x20, 0xda, 0x43]) }),
),
),
).rejects.toMatchObject({
reason: "format",
message: expect.stringMatching(/Node SEA.*truncated/iu),
});
await expect(
scanCanonicalArtifactInventory(
await writeCarrier("bad-magic", nodeSeaMachO({ blob: Buffer.alloc(16) })),
),
).rejects.toMatchObject({
reason: "format",
message: expect.stringMatching(/magic.*not.*0x143da20/iu),
});
const unknown = Buffer.alloc(9);
unknown.writeUInt32LE(NODE_SEA_FIXTURE_MAGIC, 0);
unknown.writeUInt32LE(1 << 5, 4);
unknown[8] = 1;
await expect(
scanCanonicalArtifactInventory(
await writeCarrier("unknown-flags", nodeSeaPe({ blob: unknown })),
),
).rejects.toMatchObject({
reason: "format",
message: expect.stringMatching(/flags.*unknown bits/iu),
});
});
it("fails closed when two different blobs are declared", async () => {
await expect(
scanCanonicalArtifactInventory(
await writeCarrier(
"dup-elf",
nodeSeaElf({
extraBlobs: [buildNodeSeaBlob({ main: "other\n" })],
}),
),
),
).rejects.toMatchObject({
reason: "format",
message: expect.stringMatching(/Node SEA blob.*declared more than once/iu),
});
await expect(
scanCanonicalArtifactInventory(
await writeCarrier(
"dup-macho",
nodeSeaMachO({
extraBlobs: [buildNodeSeaBlob({ codePath: "other.js", main: "x" })],
}),
),
),
).rejects.toMatchObject({
reason: "format",
message: expect.stringMatching(/Node SEA blob.*declared more than once/iu),
});
});
it("keeps one blob when the same bytes are declared twice", async () => {
const blob = buildNodeSeaBlob({ main: script, codePath: "sea.js" });
const snapshot = await scanCanonicalArtifactInventory(
await writeCarrier(
"same",
nodeSeaElf({ blob, extraBlobs: [blob], fuse: "set" }),
),
);
expect(snapshot.manifest.root_format).toBe("node-sea");
expect(
snapshot.occurrences.filter((row) => row.logical_path === "sea.js"),
).toHaveLength(1);
});
/** ELF64 whose `count` PT_NOTE program headers all declare the same notes. */
const repeatedNoteElf = (count: number, notes: Buffer): Buffer => {
const noteOffset = 64 + count * 56;
const bytes = Buffer.alloc(noteOffset + notes.length);
bytes.writeUInt32LE(0x464c457f, 0);
bytes[4] = 2;
bytes[5] = 1;
bytes[6] = 1;
bytes.writeUInt16LE(3, 0x10);
bytes.writeUInt16LE(62, 0x12);
bytes.writeUInt32LE(1, 0x14);
bytes.writeBigUInt64LE(64n, 0x20);
bytes.writeUInt16LE(64, 0x34);
bytes.writeUInt16LE(56, 0x36);
bytes.writeUInt16LE(count, 0x38);
bytes.writeUInt16LE(64, 0x3a);
for (let index = 0; index < count; index += 1) {
const at = 64 + index * 56;
bytes.writeUInt32LE(4, at);
bytes.writeBigUInt64LE(BigInt(noteOffset), at + 8);
bytes.writeBigUInt64LE(BigInt(notes.length), at + 32);
bytes.writeBigUInt64LE(BigInt(notes.length), at + 40);
bytes.writeBigUInt64LE(4n, at + 48);
}
notes.copy(bytes, noteOffset);
return bytes;
};
it("reports limited SEA recognition rather than absence above the ELF header policy", async () => {
const blob = buildNodeSeaBlob({ main: script, codePath: "sea.js" });
const bytes = repeatedNoteElf(4097, elfNote("NODE_SEA_BLOB", 0, blob));
// Only the first header claims the note; the others are valid PT_NULL rows.
for (let index = 1; index < 4097; index++)
bytes.writeUInt32LE(0, 64 + index * 56);
const path = await writeCarrier("sea-header-count", bytes);
const handle = await open(path, "r");
try {
await expect(locateNodeSea(handle, bytes.length)).rejects.toMatchObject({
reason: "limit",
readerLimit: {
parameter: "artifact_limits.node_sea.recognition_header_count",
effective_value: 4096,
required_value: 4097,
},
});
await expect(
locateNodeSea(handle, bytes.length, undefined, {
...DEFAULT_NODE_SEA_READER_LIMITS,
recognition_header_count: 4097,
}),
).resolves.toMatchObject({ carrier: "elf", blobLength: blob.length });
} finally {
await handle.close();
}
});
it("recovers SEA recognition after raising Mach-O load-command admission", async () => {
const bytes = nodeSeaMachO({ main: script, codePath: "sea.js" });
const required = bytes.readUInt32LE(20);
const handle = await open(
await writeCarrier("sea-load-commands", bytes),
"r",
);
try {
await expect(
locateNodeSea(handle, bytes.length, undefined, {
...DEFAULT_NODE_SEA_READER_LIMITS,
recognition_load_command_bytes: required - 1,
}),
).rejects.toMatchObject({
reason: "limit",
readerLimit: {
parameter: "artifact_limits.node_sea.recognition_load_command_bytes",
required_value: required,
},
});
await expect(
locateNodeSea(handle, bytes.length, undefined, {
...DEFAULT_NODE_SEA_READER_LIMITS,
recognition_load_command_bytes: required,
}),
).resolves.toMatchObject({ carrier: "mach-o" });
} finally {
await handle.close();
}
});
it("reads repeated PT_NOTE declarations at most once per note the file holds", async () => {
// 4 KiB of zero bytes is 341 empty 12-byte notes.
const empty = Buffer.alloc(4096);
const unconfirmed = repeatedNoteElf(64, empty);
const handle = await open(
await writeCarrier("repeated-notes", unconfirmed),
"r",
);
const read = vi.spyOn(handle, "read");
try {
await expect(
locateNodeSea(handle, unconfirmed.length),
).resolves.toBeUndefined();
// The prefix, the ELF header and 64 program headers, then the notes.
expect(read.mock.calls.length).toBeLessThanOrEqual(
2 + 64 + Math.floor(unconfirmed.length / 12),
);
} finally {
await handle.close();
}
const blob = buildNodeSeaBlob({ main: script, codePath: "sea.js" });
const confirmed = repeatedNoteElf(
64,
Buffer.concat([elfNote("NODE_SEA_BLOB", 0, blob), empty]),
);
await expect(
scanCanonicalArtifactInventory(
await writeCarrier("repeated-sea-notes", confirmed),
),
).rejects.toMatchObject({
reason: "format",
message: expect.stringMatching(
/ELF note tables.*more notes than the file holds/iu,
),
});
});
it("extracts the main script and assets without executing them", async () => {
const directory = await createTestTempDirectory("rea-node-sea-extract-");
const path = join(directory, "sea.elf");
await writeFile(path, nodeSeaElf(populated));
const resourceScope = new ArtifactResourceScope();
try {
const extracted = await extractArtifact({
inputPath: path,
inputFormat: "elf",
outputRoot: join(directory, "out"),
environment: process.env,
integrityPolicy: "fail",
resourceScope,
});
expect(
await readFile(join(extracted.output_root, "app/main.js"), "utf8"),
).toBe(script);
expect(
await readFile(join(extracted.output_root, "assets/message.txt"), "utf8"),
).toBe("hello");
expect(
Buffer.compare(
await readFile(join(extracted.output_root, "__node_sea__/code-cache")),
Buffer.from("cache"),
),
).toBe(0);
const extractedInventory = await scanCanonicalArtifactInventory(
extracted.output_root,
);
expect(extractedInventory.manifest.root_format).toBe("directory");
expect(
extractedInventory.occurrences.find(
(row) => row.logical_path === "app/main.js",
)?.artifact_format,
).toBe("javascript-bundle");
} finally {
await resourceScope.close();
}
});
it("rejects duplicate raw asset keys", async () => {
const path = await writeCarrier(
"duplicate-assets",
nodeSeaElf({
assets: [
{ name: "data.txt", body: "a" },
{ name: "data.txt", body: "b" },
],
}),
);
await expect(scanCanonicalArtifactInventory(path)).rejects.toThrow();
});
it("maps an unsafe main path and opaque asset keys without losing their sources", async () => {
const path = await writeCarrier(
"opaque-names",
nodeSeaElf({
codePath: "/absolute/main.js",
main: script,
assets: [
{ name: "", body: "empty" },
{ name: "__node_sea__/snapshot", body: "reserved" },
{ name: "a/café.txt", body: "composed" },
{ name: "a/cafe\u0301.txt", body: "decomposed" },
{ name: "tree", body: "parent" },
{ name: "tree/child", body: "child" },
{ name: "__node_sea__", body: "namespace" },
],
}),
);
const graph = await scanCanonicalArtifactInventory(path);
const rows = graph.occurrences.filter(
(row) => row.format_metadata?.kind === "node-sea-entry",
);
expect(
rows
.map((row) => [
row.logical_path,
row.format_metadata?.kind === "node-sea-entry"
? row.format_metadata.source_path
: null,
])
.sort(),
).toEqual(
[
["__node_sea__/main.cjs", "/absolute/main.js"],
["__node_sea__/assets/0", ""],
["__node_sea__/assets/1", "__node_sea__/snapshot"],
["a/café.txt", "a/café.txt"],
["__node_sea__/assets/3", "a/cafe\u0301.txt"],
["tree", "tree"],
["__node_sea__/assets/5", "tree/child"],
["__node_sea__/assets/6", "__node_sea__"],
].sort(),
);
expect(rows.map((row) => row.source_path).sort()).toEqual(
[
"/absolute/main.js",
"",
"__node_sea__/snapshot",
"a/café.txt",
"a/cafe\u0301.txt",
"tree",
"tree/child",
"__node_sea__",
].sort(),
);
});
it("maps a script collision and later file-prefix asset collision", async () => {
const graph = await scanCanonicalArtifactInventory(
await writeCarrier(
"collisions",
nodeSeaElf({
codePath: "main.js",
assets: [
{ name: "main.js", body: "same destination" },
{ name: "folder/item", body: "first" },
{ name: "folder", body: "later prefix" },
],
}),
),
);
const rows = graph.occurrences.filter(
(row) => row.format_metadata?.kind === "node-sea-entry",
);
expect(
rows
.map((row) => [
row.logical_path,
row.format_metadata?.kind === "node-sea-entry"
? row.format_metadata.source_path
: null,
])
.sort(),
).toEqual(
[
["main.js", "main.js"],
["__node_sea__/assets/0", "main.js"],
["folder/item", "folder/item"],
["__node_sea__/assets/2", "folder"],
].sort(),
);
});
it("retains source asset spelling separately from normalized graph paths", async () => {
const path = await writeCarrier(
"source-path",
nodeSeaElf({ assets: [{ name: "data/cafe\u0301.txt", body: "asset" }] }),
);
const graph = await scanCanonicalArtifactInventory(path);
expect(
graph.occurrences.find((row) => row.logical_path === "data/café.txt")
?.format_metadata,
).toMatchObject({ role: "asset", source_path: "data/cafe\u0301.txt" });
});
it("leaves Mach-O carriers with unreadable command framing unrecognized", async () => {
for (const littleEndian of [true, false]) {
const bytes = nodeSeaMachO({ littleEndian });
if (littleEndian) bytes.writeUInt32LE(bytes.length, 20);
else bytes.writeUInt32BE(bytes.length, 20);
const handle = await open(
await writeCarrier("command-framing", bytes),
"r",
);
try {
expect(await locateNodeSea(handle, bytes.length)).toBeUndefined();
} finally {
await handle.close();
}
}
});
it("rejects missing Mach-O load commands after a confirmed SEA section", async () => {
const bytes = nodeSeaMachO();
bytes.writeUInt32LE(2, 16);
const path = await writeCarrier("commands", bytes);
// Inventory admits Mach-O only when its command framing decodes, as
// target resolution does, so it does not route these bytes to the SEA reader.
const inventory = await scanCanonicalArtifactInventory(path);
expect(inventory.manifest.root_format).toBe("unknown");
const handle = await open(path, "r");
try {
await expect(locateNodeSea(handle, bytes.length)).rejects.toMatchObject({
reason: "format",
message: expect.stringMatching(/Mach-O.*load commands.*truncated/iu),
});
} finally {
await handle.close();
}
});
it("rejects forged entries and changed carrier identity, then closes idempotently", async () => {
const path = await writeCarrier("identity", nodeSeaElf());
const reader = new NodeSeaArtifactReader(path);
try {
const entries = [];
for await (const entry of reader.entries()) entries.push(entry);
const entry = entries[0];
if (entry === undefined) throw new Error("Missing main script");
await expect(
reader.open({ ...entry, byteOffset: 0 }),
).rejects.toMatchObject({ reason: "integrity" });
await writeFile(path, nodeSeaElf({ main: "changed bytes" }));
await expect(reader.open(entry)).rejects.toMatchObject({
reason: "integrity",
});
} finally {
await reader.close();
await reader.close();
}
});
it("reports a member that ends after the carrier recheck as an integrity failure", async () => {
const path = await writeCarrier("ended", nodeSeaElf());
const descriptor = await openRegularFile(path, { symlinks: "reject" });
const reader = new NodeSeaArtifactReader(path, descriptor);
try {
const entries = [];
for await (const entry of reader.entries()) entries.push(entry);
const entry = entries[0];
if (entry === undefined) throw new Error("Missing main script");
// open() rechecks the carrier's identity; the file then ends mid-member.
const read = descriptor.handle.read.bind(descriptor.handle);
let calls = 0;
const truncated = vi
.spyOn(descriptor.handle, "read")
.mockImplementation((...args: unknown[]) => {
calls += 1;
if (calls > 1)
return Promise.resolve({ bytesRead: 0, buffer: args[0] });
args[2] = 3;
return Reflect.apply(read, descriptor.handle, args);
});
try {
await expect(buffer(await reader.open(entry))).rejects.toMatchObject({
reason: "integrity",
message: expect.stringContaining("sea.js"),
});
expect(calls).toBe(2);
} finally {
truncated.mockRestore();
}
} finally {
await reader.close();
await descriptor.handle.close();
}
});
it.each([8, 1024 * 1024])(
"retires an unread %i-byte member through the shared reader factory",
async (size) => {
const path = await writeCarrier(
"close",
nodeSeaElf({ main: Buffer.alloc(size, 65) }),
);
const reader = createReader(path, "node-sea", {});
if (reader === undefined) throw new Error("Missing Node SEA reader");
try {
const entries = [];
for await (const entry of reader.entries()) entries.push(entry);
const entry = entries[0];
if (entry === undefined) throw new Error("Missing main script");
const stream = await reader.open(entry);
const produced = size === 8 ? once(stream, "finish") : undefined;
await once(stream, "readable");
if (produced !== undefined) await produced;
expect(stream.destroyed).toBe(false);
await reader.close();
expect(stream.destroyed).toBe(true);
expect(stream.closed).toBe(true);
await expect(buffer(stream)).rejects.toMatchObject({
reason: "unavailable",
});
await reader.close();
} finally {
await reader.close();
}
},
);
it("honors cancellation before admitting a carrier", async () => {
const path = await writeCarrier("cancel", nodeSeaElf());
const reader = new NodeSeaArtifactReader(path);
const controller = new AbortController();
controller.abort("test cancellation");
try {
await expect(
reader.entries(controller.signal)[Symbol.asyncIterator]().next(),
).rejects.toMatchObject({ reason: "cancelled" });
} finally {
await reader.close();
}
});
it.each(["cancel", "close"] as const)(
"settles preparation when the caller requests %s during inventory construction",
async (action) => {
const path = await writeCarrier(
"large-table",
nodeSeaElf({
assets: [
...Array.from({ length: 1024 }, (_, index) => ({
name: `asset-${String(index)}`,
body: "",
})),
{ name: "../unsafe", body: "" },
],
}),
);
const reader = new NodeSeaArtifactReader(path);
const controller = new AbortController();
const reason = { stage: "building inventory" };
let completion: Promise<void> | undefined;
const normalize = artifactPaths.normalizeArtifactPath;
// Schedule the request from a real consumer boundary after construction
// has begun. A synchronous whole-table pass reaches the unsafe tail first.
const observer = vi
.spyOn(artifactPaths, "normalizeArtifactPath")
.mockImplementation((name) => {
if (name === "asset-10")
setImmediate(() => {
if (action === "cancel") controller.abort(reason);
else completion = reader.close();
});
return normalize(name);
});
try {
await expect(
reader.entries(controller.signal)[Symbol.asyncIterator]().next(),
).rejects.toMatchObject(
action === "cancel"
? { reason: "cancelled", cause: reason }
: { reason: "unavailable" },
);
await completion;
await reader.close();
await expect(
reader.entries()[Symbol.asyncIterator]().next(),
).rejects.toMatchObject({ reason: "unavailable" });
} finally {
observer.mockRestore();
await reader.close();
}
},
);
it.each(["__TEXT", "NODE_SEA"])(
"keeps an incomplete %s segment unrecognized before SEA admission",
async (name) => {
const bytes = Buffer.alloc(32 + 24);
bytes.writeUInt32LE(0xfeedfacf, 0);
bytes.writeUInt32LE(0x0100000c, 4);
bytes.writeUInt32LE(1, 16);
bytes.writeUInt32LE(24, 20);
bytes.writeUInt32LE(0x19, 32);
bytes.writeUInt32LE(24, 36);
bytes.write(name, 40, "latin1");
const handle = await open(
await writeCarrier("incomplete-segment", bytes),
"r",
);
try {
expect(await locateNodeSea(handle, bytes.length)).toBeUndefined();
} finally {
await handle.close();
}
},
);
it("retains SEA admission for a complete segment with a nonaligned command size", async () => {
const original = nodeSeaMachO();
const commandSize = original.readUInt32LE(20);
const payloadAt = 32 + commandSize;
const bytes = Buffer.concat([
original.subarray(0, payloadAt),
Buffer.alloc(1),
original.subarray(payloadAt),
]);
bytes.writeUInt32LE(commandSize + 1, 20);
bytes.writeUInt32LE(commandSize + 1, 32 + 4);
bytes.writeBigUInt64LE(BigInt(payloadAt + 1), 32 + 40);
bytes.writeUInt32LE(payloadAt + 1, 32 + 72 + 48);
const handle = await open(
await writeCarrier("unaligned-command", bytes),
"r",
);
try {
expect(await locateNodeSea(handle, bytes.length)).toEqual({
carrier: "mach-o",
blobOffset: payloadAt + 1,
blobLength: Number(original.readBigUInt64LE(32 + 72 + 40)),
});
} finally {
await handle.close();
}
});
it.each([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe])(
"does not admit four-byte thin magic %i as Mach-O or a SEA carrier",
async (magic) => {
const bytes = Buffer.alloc(4);
bytes.writeUInt32BE(magic);
const path = await writeCarrier("thin-prefix", bytes);
const inventory = await scanCanonicalArtifactInventory(path);
// The magic alone does not decode a header; target resolution refuses it too.
expect(inventory.manifest.root_format).toBe("unknown");
const handle = await open(path, "r");
try {
expect(await locateNodeSea(handle, bytes.length)).toBeUndefined();
} finally {
await handle.close();
}
},
);
it("confirms SEA naming before rejecting an unrelated cyclic PE resource branch", async () => {
const fixture = peResourceFixture(true, [
{ type: 3, name: 1, language: 1033, payload: Buffer.from("other") },
{
type: 10,
name: "NODE_SEA_BLOB",
language: 1033,
payload: buildNodeSeaBlob(populated),
},
]);
const other = fixture.entryOffsets.find(
(at) => fixture.bytes.readUInt32LE(at) === 3,
);
if (other === undefined) throw new Error("Expected unrelated resource type");
fixture.bytes.writeUInt32LE(0x80000000, other + 4);
const handle = await open(
await writeCarrier("sea-with-unrelated-cycle", fixture.bytes),
"r",
);
try {
await expect(
locateNodeSea(handle, fixture.bytes.length),
).rejects.toMatchObject({ reason: "malformed" });
} finally {
await handle.close();
}
});
it.each(["valid replacement", "malformed blob"] as const)(
"rejects post-classification carrier mutation before publishing Node SEA facts: %s",
async (mode) => {
const blob = buildNodeSeaBlob(populated);
const original = nodeSeaElf({ blob, fuse: "set" });
const changed =
mode === "valid replacement"
? buildNodeSeaBlob({ ...populated, main: script.toUpperCase() })
: Buffer.from(blob);
if (mode === "malformed blob") changed[0] = (changed[0] ?? 0) ^ 0xff;
const replacement = nodeSeaElf({ blob: changed, fuse: "set" });
expect(replacement.length).toBe(original.length);
const path = await writeCarrier("classification-mutation", original);
let created: NodeSeaArtifactReader | undefined;
await expect(
scanCanonicalArtifactInventory(path, {}, (...args) => {
expect(args[1]).toBe("node-sea");
writeFileSync(args[0], replacement);
const reader = createReader(...args);
if (reader instanceof NodeSeaArtifactReader) created = reader;
return reader;
}),
).rejects.toMatchObject({ reason: "integrity" });
expect(created).toBeInstanceOf(NodeSeaArtifactReader);
expect(created?.formatMetadata()).toBeUndefined();
},
);
it("allows an uncancelled inventory after a cancelled SEA preparation", async () => {
const path = await writeCarrier("cancel-retry", nodeSeaElf(populated));
const reader = new NodeSeaArtifactReader(path);
const controller = new AbortController();
const reason = { stop: "first inventory" };
const observed = await open(path, "r");
const prototype = Object.getPrototypeOf(observed) as FileHandle;
const original = prototype.read;
let stopped = false;
const spy = vi.spyOn(prototype, "read").mockImplementation(async function (
this: FileHandle,
...args: Parameters<typeof original>
) {
const result = await original.apply(this, args);
if (!stopped) {
stopped = true;
controller.abort(reason);
}
return result;
});
try {
await expect(
reader.entries(controller.signal)[Symbol.asyncIterator]().next(),
).rejects.toMatchObject({ reason: "cancelled" });
spy.mockRestore();
const entries = [];
for await (const entry of reader.entries()) entries.push(entry);
expect(entries.length).toBeGreaterThan(0);
} finally {
spy.mockRestore();
await observed.close();
await reader.close();
}
});
it.each([
{
field: "assets",
count: 100_001n,
blob: buildNodeSeaBlob({ assets: [{ name: "a", body: "" }] }),
},
{
field: "exec argv",
count: 4097n,
blob: buildNodeSeaBlob({ execArgv: ["a"] }),
},
])(
"reports a truncated $field table as malformed through the reader",
async ({ count, blob }) => {
const declared = Buffer.alloc(8);
declared.writeBigUInt64LE(count);
// Each case has one optional table immediately after the common fields.
const tableOffset = buildNodeSeaBlob().length;
const truncated = Buffer.concat([blob.subarray(0, tableOffset), declared]);
const path = await writeCarrier(
"truncated-sea",
nodeSeaElf({ blob: truncated, fuse: "set" }),
);
const reader = new NodeSeaArtifactReader(path);
try {
await expect(async () => {
for await (const _entry of reader.entries()) {
/* consume */
}
}).rejects.toMatchObject({ reason: "format" });
} finally {
await reader.close();
}
},
);