feat(artifacts): inspect classic iNES container regions
This commit is contained in:
@@ -1,5 +1,9 @@
|
||||
import { constants, type Stats } from "node:fs";
|
||||
import { createHash } from "node:crypto";
|
||||
import {
|
||||
nesContainerFormat,
|
||||
parseInesLayout,
|
||||
} from "../domain/inesContainer.js";
|
||||
import {
|
||||
access,
|
||||
lstat,
|
||||
@@ -276,19 +280,30 @@ const detectArtifactFormat = async (
|
||||
> => {
|
||||
throwIfTargetResolutionCancelled(signal);
|
||||
const lower = path.toLowerCase();
|
||||
const magic = Buffer.alloc(8);
|
||||
const magic = Buffer.alloc(16);
|
||||
const observed = await handle.read(magic, 0, magic.length, 0);
|
||||
throwIfTargetResolutionCancelled(signal);
|
||||
if (
|
||||
observed.bytesRead === 8 &&
|
||||
magic.equals(Buffer.from([0, 0x61, 0x73, 0x6d, 1, 0, 0, 0]))
|
||||
observed.bytesRead >= 8 &&
|
||||
magic.subarray(0, 8).equals(Buffer.from([0, 0x61, 0x73, 0x6d, 1, 0, 0, 0]))
|
||||
)
|
||||
throw new BinaryTargetError(
|
||||
path,
|
||||
"WebAssembly v1 artifacts are not supported by the native opening route",
|
||||
{ constraint: "wasm_requires_static_inspection" },
|
||||
);
|
||||
if (hasZipSignature(magic.subarray(0, observed.bytesRead))) {
|
||||
const prefix = magic.subarray(0, observed.bytesRead);
|
||||
const nesFormat = nesContainerFormat(prefix);
|
||||
if (nesFormat !== undefined) {
|
||||
const parsed = parseInesLayout(prefix, (await handle.stat()).size);
|
||||
throwIfTargetResolutionCancelled(signal);
|
||||
if (!parsed.ok)
|
||||
throw new BinaryTargetError(path, parsed.error, {
|
||||
constraint: "file_format_rejected",
|
||||
});
|
||||
return "ines";
|
||||
}
|
||||
if (hasZipSignature(prefix)) {
|
||||
// The HarmonyOS App Pack suffix `.app` is a root-input concept; a nested
|
||||
// ZIP member ending in `.app` keeps the generic zip classification.
|
||||
if (lower.endsWith(".app")) return "app-pack";
|
||||
@@ -339,7 +354,7 @@ const isArchiveFormat = (
|
||||
| "raw-binary"
|
||||
>,
|
||||
): format is Extract<BinaryTarget, { kind: "archive" }>["format"] =>
|
||||
isZipPackageFormat(format) || ["asar", "dmg", "pkg"].includes(format);
|
||||
isZipPackageFormat(format) || ["asar", "ines", "dmg", "pkg"].includes(format);
|
||||
|
||||
const sha256Handle = async (
|
||||
handle: FileHandle,
|
||||
|
||||
@@ -32,7 +32,7 @@ import {
|
||||
} from "../domain/analysisErrorCore.js";
|
||||
import { ArtifactOperationError } from "../domain/artifactOperationError.js";
|
||||
import type { AnalysisError } from "../domain/analysisErrorBase.js";
|
||||
import type { JsonValue } from "../domain/jsonValue.js";
|
||||
import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js";
|
||||
import { interfaceBuilderLimitsSchema } from "../domain/apple/interfaceBuilderGraph.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
import { ArtifactReaderFailure } from "./ArtifactReader.js";
|
||||
@@ -349,7 +349,7 @@ class ArtifactClient implements AnalysisClient {
|
||||
const inventoryEvidence = createEvidence(subject, ARTIFACT_GRAPH_PROVIDER, {
|
||||
operation: "inventory_artifact",
|
||||
parameters: inventoryParameters,
|
||||
result: inventory,
|
||||
result: jsonValueSchema.parse(inventory),
|
||||
rawResult: null,
|
||||
limitations: inventory.limitations,
|
||||
// The nested inventory already names every occurrence's logical path.
|
||||
|
||||
@@ -92,7 +92,7 @@ export const sameArtifactEntry = (
|
||||
|
||||
/** Read-only adapter over one directory, archive, or virtual container. */
|
||||
export interface ArtifactReader {
|
||||
readonly format: "directory" | ZipPackageFormat | "asar" | "file";
|
||||
readonly format: "directory" | ZipPackageFormat | "asar" | "ines" | "file";
|
||||
entries(signal?: AbortSignal): AsyncIterable<ArtifactEntry>;
|
||||
open(entry: ArtifactEntry, signal?: AbortSignal): Promise<Readable>;
|
||||
provenance(): readonly ArtifactCommand[];
|
||||
|
||||
@@ -0,0 +1,192 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { lstat } from "node:fs/promises";
|
||||
import { Readable } from "node:stream";
|
||||
import {
|
||||
parseInesLayout,
|
||||
type InesInventory,
|
||||
type InesLayout,
|
||||
} from "../domain/inesContainer.js";
|
||||
import type { ArtifactCommand } from "../domain/artifactGraph.js";
|
||||
import {
|
||||
sameRegularFileState,
|
||||
type StableRegularFileDescriptor,
|
||||
} from "../filesystem/RegularFile.js";
|
||||
import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";
|
||||
import type { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
|
||||
import {
|
||||
ArtifactReaderFailure,
|
||||
copyArtifactEntry,
|
||||
sameArtifactEntry,
|
||||
type ArtifactEntry,
|
||||
type ArtifactReader,
|
||||
} from "./ArtifactReader.js";
|
||||
import { abortIfNeeded } from "./ArtifactHash.js";
|
||||
import { streamChunkToBuffer } from "./StreamBytes.js";
|
||||
|
||||
export const INES_LIMITATION =
|
||||
"Classic iNES file regions are observed; mapper execution, CPU bank mappings, CHR-RAM contents, 6502 analysis and emulator behavior are not observed. Trailing bytes are retained without interpretation. NES 2.0 and UNIF are unsupported.";
|
||||
|
||||
/** Read positional regions from a descriptor retained by the artifact resource scope. */
|
||||
export class InesArtifactReader implements ArtifactReader {
|
||||
readonly format = "ines" as const;
|
||||
readonly #entries = new Map<string, ArtifactEntry>();
|
||||
#layout: InesLayout | undefined;
|
||||
#closed = false;
|
||||
|
||||
constructor(
|
||||
private readonly path: string,
|
||||
private readonly source: StableRegularFileDescriptor,
|
||||
private readonly ownedSource?: OwnedFileHandle,
|
||||
) {}
|
||||
|
||||
async *entries(signal?: AbortSignal): AsyncIterable<ArtifactEntry> {
|
||||
abortIfNeeded(signal);
|
||||
await this.#verifySource();
|
||||
const prefix = Buffer.alloc(16);
|
||||
const { bytesRead } = await this.source.handle.read(prefix, 0, 16, 0);
|
||||
abortIfNeeded(signal);
|
||||
const parsed = parseInesLayout(
|
||||
prefix.subarray(0, bytesRead),
|
||||
this.source.initial.size,
|
||||
);
|
||||
if (!parsed.ok) throw new ArtifactReaderFailure("format", parsed.error);
|
||||
this.#layout = parsed.value;
|
||||
await this.#verifySource();
|
||||
this.#entries.clear();
|
||||
for (const region of parsed.value.regions) {
|
||||
abortIfNeeded(signal);
|
||||
const entry: ArtifactEntry = {
|
||||
path: region.path,
|
||||
kind: "file",
|
||||
declaredSize: region.length,
|
||||
compressedSize: null,
|
||||
executable: false,
|
||||
encrypted: false,
|
||||
byteOffset: region.offset,
|
||||
declaredSha256: null,
|
||||
unpacked: false,
|
||||
limitations: [],
|
||||
adapterKey: region.path,
|
||||
};
|
||||
this.#entries.set(entry.adapterKey, copyArtifactEntry(entry));
|
||||
yield entry;
|
||||
}
|
||||
}
|
||||
|
||||
async open(entry: ArtifactEntry, signal?: AbortSignal): Promise<Readable> {
|
||||
abortIfNeeded(signal);
|
||||
const produced = this.#entries.get(entry.adapterKey);
|
||||
if (produced === undefined || !sameArtifactEntry(entry, produced))
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
"iNES region does not match this reader's inventory",
|
||||
);
|
||||
await this.#verifySource();
|
||||
const offset = produced.byteOffset;
|
||||
const size = produced.declaredSize;
|
||||
if (offset === null || size === null || size <= 0)
|
||||
throw new ArtifactReaderFailure("integrity", "Invalid iNES region range");
|
||||
const stream = readFileHandleChunks(this.source.handle, {
|
||||
start: offset,
|
||||
end: offset + size - 1,
|
||||
signal,
|
||||
});
|
||||
const verify = () => this.#verifySource();
|
||||
return Readable.from(
|
||||
(async function* () {
|
||||
let bytes = 0;
|
||||
try {
|
||||
for await (const raw of stream) {
|
||||
abortIfNeeded(signal);
|
||||
const chunk = streamChunkToBuffer(raw);
|
||||
bytes += chunk.length;
|
||||
yield chunk;
|
||||
}
|
||||
if (bytes !== size)
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
"Truncated iNES region",
|
||||
);
|
||||
await verify();
|
||||
} catch (cause: unknown) {
|
||||
abortIfNeeded(signal);
|
||||
if (cause instanceof ArtifactReaderFailure) throw cause;
|
||||
throw new ArtifactReaderFailure("io", "Could not read iNES region", {
|
||||
cause,
|
||||
});
|
||||
}
|
||||
})(),
|
||||
{ objectMode: false },
|
||||
);
|
||||
}
|
||||
|
||||
/** Hash actual ordered region bytes; per-region digests alone cannot prove concatenation. */
|
||||
async verifyReconstruction(
|
||||
expectedSha256: string,
|
||||
signal?: AbortSignal,
|
||||
): Promise<InesInventory> {
|
||||
const layout = this.#layout;
|
||||
if (layout === undefined || this.#entries.size !== layout.regions.length)
|
||||
throw new ArtifactReaderFailure("integrity", "Incomplete iNES inventory");
|
||||
const hash = createHash("sha256");
|
||||
let bytes = 0;
|
||||
for (const region of layout.regions) {
|
||||
if (region.offset !== bytes)
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
"Noncontiguous iNES regions",
|
||||
);
|
||||
const entry = this.#entries.get(region.path);
|
||||
if (entry === undefined)
|
||||
throw new ArtifactReaderFailure("integrity", "Missing iNES region");
|
||||
for await (const raw of await this.open(entry, signal)) {
|
||||
const chunk = streamChunkToBuffer(raw);
|
||||
hash.update(chunk);
|
||||
bytes += chunk.length;
|
||||
}
|
||||
}
|
||||
const sha256 = hash.digest("hex");
|
||||
if (bytes !== this.source.initial.size || sha256 !== expectedSha256)
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
"iNES reconstruction differs from the source",
|
||||
);
|
||||
return {
|
||||
header: layout.header,
|
||||
reconstruction: {
|
||||
region_order: layout.regions.map(({ path }) => path),
|
||||
bytes,
|
||||
sha256,
|
||||
verified: true,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
provenance(): readonly ArtifactCommand[] {
|
||||
return [];
|
||||
}
|
||||
|
||||
close(): Promise<void> {
|
||||
// Inventory borrows its admitting scope's descriptor. Extraction owns its
|
||||
// separately opened descriptor and retains this reader if close fails.
|
||||
this.#closed = true;
|
||||
return this.ownedSource?.close() ?? Promise.resolve();
|
||||
}
|
||||
|
||||
async #verifySource(): Promise<void> {
|
||||
if (this.#closed)
|
||||
throw new ArtifactReaderFailure("unavailable", "iNES reader is closed");
|
||||
const [opened, selected] = await Promise.all([
|
||||
this.source.handle.stat(),
|
||||
lstat(this.path),
|
||||
]);
|
||||
if (
|
||||
!sameRegularFileState(this.source.initial, opened) ||
|
||||
!sameRegularFileState(this.source.initial, selected)
|
||||
)
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
"iNES source changed during reading",
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -3,6 +3,8 @@ import { lstat, realpath } from "node:fs/promises";
|
||||
import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
|
||||
import { digestCanonicalValue } from "../../domain/canonicalDigest.js";
|
||||
import { AsarArtifactReader } from "../AsarArtifactReader.js";
|
||||
import { InesArtifactReader } from "../InesArtifactReader.js";
|
||||
import { openRootArtifact } from "../inventory/hashStableRootArtifact.js";
|
||||
import {
|
||||
ArtifactPathRegistry,
|
||||
normalizeArtifactPath,
|
||||
@@ -421,6 +423,7 @@ const requireExtractableFormat = async (
|
||||
if (
|
||||
!directory &&
|
||||
format !== "asar" &&
|
||||
format !== "ines" &&
|
||||
!isMachOFormat(format) &&
|
||||
!isZipFormat(format)
|
||||
)
|
||||
@@ -436,13 +439,38 @@ const createReader = async (
|
||||
path: string,
|
||||
input: Pick<
|
||||
ArtifactExtractionInput,
|
||||
"inputPath" | "inputFormat" | "environment"
|
||||
"inputPath" | "inputFormat" | "environment" | "resourceScope"
|
||||
>,
|
||||
): Promise<ArtifactReader> => {
|
||||
const format = input.inputFormat;
|
||||
if (await requireExtractableFormat(path, input))
|
||||
return new DirectoryArtifactReader(path);
|
||||
if (format === "asar") return new AsarArtifactReader(path);
|
||||
if (format === "ines") {
|
||||
const owner = await openRootArtifact(path, input.resourceScope);
|
||||
try {
|
||||
return new InesArtifactReader(
|
||||
path,
|
||||
{
|
||||
handle: owner.handle,
|
||||
initial: await owner.handle.stat(),
|
||||
},
|
||||
owner,
|
||||
);
|
||||
} catch (cause: unknown) {
|
||||
const attempt = await input.resourceScope.release({
|
||||
kind: "file-handle",
|
||||
handle: owner,
|
||||
resource: `iNES source ${path}`,
|
||||
});
|
||||
if (attempt.kind === "failed")
|
||||
throw ArtifactReaderFailure.withCleanup(
|
||||
cause,
|
||||
ArtifactReaderFailure.cleanupObservation(attempt.cause, path),
|
||||
);
|
||||
throw cause;
|
||||
}
|
||||
}
|
||||
if (isZipFormat(format)) return new ZipArtifactReader(path, format);
|
||||
return new MachOSliceArtifactReader(path, input.environment);
|
||||
};
|
||||
|
||||
@@ -19,6 +19,10 @@ import {
|
||||
type ZipPackageFormat,
|
||||
} from "../../domain/zipPackageFormat.js";
|
||||
import { mzWindowsHeaderOffset, parseDosMzHeader } from "../../domain/dosMz.js";
|
||||
import {
|
||||
nesContainerFormat,
|
||||
parseInesLayout,
|
||||
} from "../../domain/inesContainer.js";
|
||||
|
||||
/** Mutable internal occurrence used until root-bound IDs are known. */
|
||||
export interface MutableOccurrence {
|
||||
@@ -219,7 +223,7 @@ export const rootOccurrenceFor = (
|
||||
artifact_kind:
|
||||
metadata.format === "directory" ||
|
||||
isZipPackageFormat(metadata.format) ||
|
||||
["asar", "dmg", "pkg"].includes(metadata.format)
|
||||
["asar", "ines", "dmg", "pkg"].includes(metadata.format)
|
||||
? "container"
|
||||
: artifactRoleForFormat(metadata.path, metadata.format).kind,
|
||||
artifact_format: metadata.format,
|
||||
@@ -419,6 +423,7 @@ const artifactRoleForFormat = (
|
||||
format: zipPackageFormatForPath(path) ?? format,
|
||||
};
|
||||
if (format === "plist") return { kind: "plist", format };
|
||||
if (format === "ines") return { kind: "container", format };
|
||||
return {
|
||||
kind: ["native-addon", "dynamic-library"].includes(byPath.kind)
|
||||
? byPath.kind
|
||||
@@ -432,6 +437,13 @@ export const classifyArtifactBytes = (
|
||||
prefix: Buffer,
|
||||
fileSize = prefix.length,
|
||||
): ArtifactNode["format"] => {
|
||||
// A header-only region has the signature but not the declared cartridge
|
||||
// extent. Keep it as a file instead of inventing another container.
|
||||
if (
|
||||
nesContainerFormat(prefix) === "ines" &&
|
||||
parseInesLayout(prefix, fileSize).ok
|
||||
)
|
||||
return "ines";
|
||||
if (hasZipSignature(prefix)) return "zip";
|
||||
if (prefix.subarray(0, 8).equals(Buffer.from("bplist00"))) return "plist";
|
||||
if (prefix.length >= 4) {
|
||||
|
||||
@@ -5,6 +5,10 @@ import type { StableRegularFileDescriptor } from "../../filesystem/RegularFile.j
|
||||
import type { OwnedFileHandle } from "../../filesystem/OwnedFileHandle.js";
|
||||
|
||||
import { classifyArtifactContent } from "./ArtifactGraphConstruction.js";
|
||||
import {
|
||||
nesContainerFormat,
|
||||
parseInesLayout,
|
||||
} from "../../domain/inesContainer.js";
|
||||
import { ARTIFACT_CLASSIFICATION_PREFIX_BYTES } from "../ArtifactHash.js";
|
||||
import type { ArtifactOccurrence } from "../../domain/artifactGraph.js";
|
||||
import {
|
||||
@@ -71,7 +75,7 @@ export const classifyAndHashRoot = async (
|
||||
});
|
||||
};
|
||||
|
||||
/** Classify a root and retain its admitted ZIP descriptor for child inventory. */
|
||||
/** Classify a root and retain its admitted container descriptor for child inventory. */
|
||||
export const classifyAndHashRootForInventory = async (
|
||||
path: string,
|
||||
directory: boolean,
|
||||
@@ -112,7 +116,9 @@ export const classifyAndHashRootForInventory = async (
|
||||
options.signal,
|
||||
);
|
||||
const retainSource =
|
||||
isZipPackageFormat(format) || format === "mach-o-universal";
|
||||
isZipPackageFormat(format) ||
|
||||
format === "mach-o-universal" ||
|
||||
format === "ines";
|
||||
outcome = {
|
||||
kind: "completed",
|
||||
value: {
|
||||
@@ -148,6 +154,11 @@ const classifyRootFormat = async (
|
||||
const magic = Buffer.alloc(ARTIFACT_CLASSIFICATION_PREFIX_BYTES);
|
||||
const observed = await handle.read(magic, 0, magic.length, 0);
|
||||
const prefix = magic.subarray(0, observed.bytesRead);
|
||||
if (nesContainerFormat(prefix) !== undefined) {
|
||||
const parsed = parseInesLayout(prefix, (await handle.stat()).size);
|
||||
if (!parsed.ok) throw new ArtifactReaderFailure("format", parsed.error);
|
||||
return "ines";
|
||||
}
|
||||
const lower = path.toLowerCase();
|
||||
if (hasZipSignature(prefix)) return zipRootPackageFormat(lower);
|
||||
if (
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
import { AsarArtifactReader } from "../AsarArtifactReader.js";
|
||||
import { InesArtifactReader, INES_LIMITATION } from "../InesArtifactReader.js";
|
||||
import { ArtifactReaderFailure } from "../ArtifactReader.js";
|
||||
import type { ArtifactReader } from "../ArtifactReader.js";
|
||||
import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
|
||||
import { MachOSliceArtifactReader } from "../MachOSliceArtifactReader.js";
|
||||
@@ -20,6 +22,13 @@ export const createReader = (
|
||||
if (isZipPackageFormat(format))
|
||||
return new ZipArtifactReader(path, format, undefined, rootSource);
|
||||
switch (format) {
|
||||
case "ines":
|
||||
if (rootSource === undefined)
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
"iNES inventory requires its admitted source descriptor",
|
||||
);
|
||||
return new InesArtifactReader(path, rootSource);
|
||||
case "directory":
|
||||
return new DirectoryArtifactReader(path);
|
||||
case "asar":
|
||||
@@ -40,6 +49,7 @@ export const inventoryLimitations = (
|
||||
format: ArtifactOccurrence["artifact_format"],
|
||||
reader: ArtifactReader | undefined,
|
||||
): string[] => {
|
||||
if (format === "ines") return [INES_LIMITATION];
|
||||
if (reader !== undefined)
|
||||
return isZipPackageFormat(reader.format)
|
||||
? [ZIP_NON_ENTRY_TAIL_LIMITATION]
|
||||
|
||||
@@ -2,6 +2,7 @@ import type { ArtifactInventorySnapshot } from "../../domain/artifactInventorySn
|
||||
import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
|
||||
|
||||
import { AsarArtifactReader } from "../AsarArtifactReader.js";
|
||||
import { InesArtifactReader } from "../InesArtifactReader.js";
|
||||
|
||||
import { lstat } from "node:fs/promises";
|
||||
import type { Stats } from "node:fs";
|
||||
@@ -270,6 +271,9 @@ const buildInventorySnapshot = async (
|
||||
});
|
||||
return {
|
||||
manifest,
|
||||
...(reader instanceof InesArtifactReader && rootDigest !== null
|
||||
? { ines: await reader.verifyReconstruction(rootDigest.sha256, signal) }
|
||||
: {}),
|
||||
nodes: orderedNodes,
|
||||
occurrences: orderedOccurrences,
|
||||
edges: orderedEdges,
|
||||
|
||||
@@ -67,7 +67,7 @@ const artifact = <
|
||||
export const ARTIFACT_TOOL_CONTRACTS = [
|
||||
artifact(
|
||||
"inspect_artifact",
|
||||
"Inspect an active archive or application package in one call. Returns the complete content-addressed artifact graph once, as the nested inventory Evidence, with root and integrity observations, integrity contradictions, hypotheses, unexplored branches, limitations, and next probes inline. Read-only DMG mounting is used automatically on supported macOS hosts. Integrity mismatches fail by default; record-and-continue keeps mismatches explicitly untrusted. It does not extract files; use extract_artifact to materialize its regular contents.",
|
||||
"Inspect an active archive or application package in one call. Returns the complete content-addressed artifact graph once, as the nested inventory Evidence, with root and integrity observations, integrity contradictions, hypotheses, unexplored branches, limitations, and next probes inline. Classic iNES includes header facts, PRG/CHR file-region hashes and byte-exact reconstruction evidence; mapper execution and CPU bank mappings remain unobserved. Read-only DMG mounting is used automatically on supported macOS hosts. Integrity mismatches fail by default; record-and-continue keeps mismatches explicitly untrusted. It does not extract files; use extract_artifact to materialize its regular contents.",
|
||||
artifactInventoryInputSchema,
|
||||
),
|
||||
artifact(
|
||||
|
||||
@@ -65,6 +65,7 @@ export const targetFormatSchema = z.enum([
|
||||
"msix",
|
||||
"appx",
|
||||
"asar",
|
||||
"ines",
|
||||
"dmg",
|
||||
"pkg",
|
||||
"plist",
|
||||
|
||||
@@ -66,6 +66,7 @@ const formatSchema = z.enum([
|
||||
"hsp",
|
||||
"app-pack",
|
||||
"asar",
|
||||
"ines",
|
||||
"dmg",
|
||||
"pkg",
|
||||
"plist",
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
import { z } from "zod";
|
||||
import { prefixedDigestSchema } from "./../domain/digests.js";
|
||||
import { inesInventorySchema } from "./inesContainer.js";
|
||||
|
||||
const sha256Schema = z.string().regex(/^[a-f0-9]{64}$/u);
|
||||
const artifactIdSchema = prefixedDigestSchema("art");
|
||||
@@ -42,6 +43,7 @@ const artifactFormatSchema = z.enum([
|
||||
"zip",
|
||||
"pkg",
|
||||
"asar",
|
||||
"ines",
|
||||
"javascript-bundle",
|
||||
"source-map",
|
||||
"mach-o-universal",
|
||||
@@ -69,6 +71,7 @@ const artifactFormatSchema = z.enum([
|
||||
|
||||
/** Formats established from bytes or a virtual directory tree, independent of path roles. */
|
||||
const artifactContentFormatSchema = artifactFormatSchema.extract([
|
||||
"ines",
|
||||
"zip",
|
||||
"mach-o-universal",
|
||||
"mach-o",
|
||||
@@ -196,6 +199,7 @@ export const artifactInventoryResultSchema = z.object({
|
||||
edges: z.array(artifactEdgeSchema),
|
||||
provenance: z.array(artifactCommandSchema),
|
||||
integrity_contradictions: z.array(integrityContradictionSchema).default([]),
|
||||
ines: inesInventorySchema.optional(),
|
||||
limitations: z.array(z.string()),
|
||||
});
|
||||
|
||||
|
||||
@@ -16,7 +16,12 @@ const artifactIdSchema = prefixedDigestSchema("art");
|
||||
|
||||
const inspectionObservationSchema = z.strictObject({
|
||||
observation_id: prefixedDigestSchema("aio"),
|
||||
kind: z.enum(["root-manifest", "integrity"]),
|
||||
kind: z.enum([
|
||||
"root-manifest",
|
||||
"integrity",
|
||||
"container-header",
|
||||
"reconstruction",
|
||||
]),
|
||||
subject: textSchema,
|
||||
value: jsonValueSchema,
|
||||
evidence_id: evidenceIdSchema,
|
||||
@@ -209,6 +214,22 @@ const allObservations = (
|
||||
...inventory.integrity_contradictions.map((value) =>
|
||||
observation("integrity", value.contradiction_id, value, evidenceId),
|
||||
),
|
||||
...(inventory.ines === undefined
|
||||
? []
|
||||
: [
|
||||
observation(
|
||||
"container-header",
|
||||
inventory.manifest.root_artifact_id,
|
||||
inventory.ines.header,
|
||||
evidenceId,
|
||||
),
|
||||
observation(
|
||||
"reconstruction",
|
||||
inventory.manifest.root_artifact_id,
|
||||
inventory.ines.reconstruction,
|
||||
evidenceId,
|
||||
),
|
||||
]),
|
||||
];
|
||||
|
||||
const observation = (
|
||||
|
||||
@@ -14,5 +14,6 @@ export interface ArtifactInventorySnapshot {
|
||||
ArtifactInventoryResult["provenance"][number]
|
||||
>;
|
||||
readonly integrity_contradictions: readonly IntegrityContradiction[];
|
||||
readonly ines?: ArtifactInventoryResult["ines"];
|
||||
readonly limitations: readonly string[];
|
||||
}
|
||||
|
||||
@@ -127,6 +127,7 @@ export type BinaryTarget =
|
||||
| "hsp"
|
||||
| "app-pack"
|
||||
| "asar"
|
||||
| "ines"
|
||||
| "dmg"
|
||||
| "pkg";
|
||||
})
|
||||
|
||||
@@ -59,6 +59,7 @@ const subjectSchema = z.object({
|
||||
"hsp",
|
||||
"app-pack",
|
||||
"asar",
|
||||
"ines",
|
||||
"dmg",
|
||||
"pkg",
|
||||
"plist",
|
||||
|
||||
@@ -0,0 +1,92 @@
|
||||
import { expect, it } from "vitest";
|
||||
import { parseInesLayout } from "./inesContainer.js";
|
||||
|
||||
const header = (): Buffer => {
|
||||
const bytes = Buffer.alloc(16);
|
||||
bytes.write("NES\x1a", "latin1");
|
||||
bytes[4] = 1;
|
||||
return bytes;
|
||||
};
|
||||
|
||||
it("bounds the complete classic header count without inventing RAM regions", () => {
|
||||
const bytes = header();
|
||||
bytes[4] = 255;
|
||||
bytes[5] = 255;
|
||||
bytes[6] = 0xfe;
|
||||
bytes[7] = 0xf3;
|
||||
const parsed = parseInesLayout(bytes, 16 + 512 + 255 * (16_384 + 8_192));
|
||||
if (!parsed.ok) throw new Error(parsed.error);
|
||||
expect(parsed.value.header).toMatchObject({
|
||||
mapper: 255,
|
||||
trainer_present: true,
|
||||
battery_flag: true,
|
||||
mirroring: "four-screen",
|
||||
});
|
||||
expect(parsed.value.regions).toHaveLength(512);
|
||||
expect(parsed.value.regions.at(-1)).toMatchObject({
|
||||
path: "chr/254.bin",
|
||||
length: 8_192,
|
||||
});
|
||||
});
|
||||
|
||||
it.each([
|
||||
{
|
||||
label: "short header",
|
||||
modify: (bytes: Buffer) => bytes.subarray(0, 8),
|
||||
size: 8,
|
||||
reason: "truncated iNES header",
|
||||
},
|
||||
{
|
||||
label: "short payload",
|
||||
modify: (bytes: Buffer) => bytes,
|
||||
size: 16,
|
||||
reason: "truncated iNES payload",
|
||||
},
|
||||
{
|
||||
label: "NES 2.0",
|
||||
modify: (bytes: Buffer) => {
|
||||
bytes[7] = 8;
|
||||
return bytes;
|
||||
},
|
||||
size: 16_400,
|
||||
reason: "nes-2.0",
|
||||
},
|
||||
{
|
||||
label: "dirty legacy header",
|
||||
modify: (bytes: Buffer) => {
|
||||
bytes[12] = 1;
|
||||
return bytes;
|
||||
},
|
||||
size: 16_400,
|
||||
reason: "ambiguous iNES mapper",
|
||||
},
|
||||
{
|
||||
label: "empty PRG",
|
||||
modify: (bytes: Buffer) => {
|
||||
bytes[4] = 0;
|
||||
return bytes;
|
||||
},
|
||||
size: 16,
|
||||
reason: "at least one PRG",
|
||||
},
|
||||
{
|
||||
label: "unsupported variant",
|
||||
modify: (bytes: Buffer) => {
|
||||
bytes[7] = 4;
|
||||
return bytes;
|
||||
},
|
||||
size: 16_400,
|
||||
reason: "unsupported iNES header variant",
|
||||
},
|
||||
{
|
||||
label: "unsafe extent",
|
||||
modify: (bytes: Buffer) => bytes,
|
||||
size: Number.MAX_SAFE_INTEGER + 1,
|
||||
reason: "invalid iNES file extent",
|
||||
},
|
||||
])("refuses $label before producing regions", ({ modify, size, reason }) => {
|
||||
expect(parseInesLayout(modify(header()), size)).toMatchObject({
|
||||
ok: false,
|
||||
error: expect.stringContaining(reason),
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,131 @@
|
||||
import { z } from "zod";
|
||||
import { err, ok, type Result } from "./result.js";
|
||||
|
||||
/** Byte signatures select a container family, never an executable architecture. */
|
||||
export const nesContainerFormat = (
|
||||
prefix: Buffer,
|
||||
): "ines" | "nes-2.0" | "unif" | undefined => {
|
||||
if (prefix.subarray(0, 4).equals(Buffer.from("UNIF"))) return "unif";
|
||||
if (!prefix.subarray(0, 4).equals(Buffer.from([0x4e, 0x45, 0x53, 0x1a])))
|
||||
return undefined;
|
||||
return prefix.length >= 8 && (prefix.readUInt8(7) & 0x0c) === 0x08
|
||||
? "nes-2.0"
|
||||
: "ines";
|
||||
};
|
||||
|
||||
const inesHeaderSchema = z.strictObject({
|
||||
format: z.literal("ines"),
|
||||
header_hex: z.string().regex(/^[a-f0-9]{32}$/u),
|
||||
prg_rom_units_16k: z.number().int().min(1).max(255),
|
||||
chr_rom_units_8k: z.number().int().min(0).max(255),
|
||||
mapper: z.number().int().min(0).max(255),
|
||||
flags_6: z.number().int().min(0).max(255),
|
||||
flags_7: z.number().int().min(0).max(255),
|
||||
trainer_present: z.boolean(),
|
||||
battery_flag: z.boolean(),
|
||||
mirroring: z.enum(["horizontal", "vertical", "four-screen"]),
|
||||
});
|
||||
|
||||
/** Verified concatenation is a byte identity claim, not an emulator claim. */
|
||||
export const inesInventorySchema = z.strictObject({
|
||||
header: inesHeaderSchema,
|
||||
reconstruction: z.strictObject({
|
||||
region_order: z.array(z.string().min(1)).min(2),
|
||||
bytes: z.number().int().min(16).max(Number.MAX_SAFE_INTEGER),
|
||||
sha256: z.string().regex(/^[a-f0-9]{64}$/u),
|
||||
verified: z.literal(true),
|
||||
}),
|
||||
});
|
||||
|
||||
export type InesInventory = z.infer<typeof inesInventorySchema>;
|
||||
|
||||
export interface InesRegion {
|
||||
readonly path: string;
|
||||
readonly offset: number;
|
||||
readonly length: number;
|
||||
}
|
||||
|
||||
export interface InesLayout {
|
||||
readonly header: InesInventory["header"];
|
||||
readonly regions: readonly InesRegion[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Classic iNES counts 16 KiB PRG and 8 KiB CHR file units. Those units do not
|
||||
* establish the mapper's runtime windows. Preserve all other bytes verbatim.
|
||||
*/
|
||||
export const parseInesLayout = (
|
||||
prefix: Buffer,
|
||||
fileSize: number,
|
||||
): Result<InesLayout, string> => {
|
||||
const format = nesContainerFormat(prefix);
|
||||
if (format !== "ines")
|
||||
return err(
|
||||
format === undefined
|
||||
? "missing iNES byte signature"
|
||||
: `${format} containers are not supported by the classic iNES lane`,
|
||||
);
|
||||
if (!Number.isSafeInteger(fileSize) || fileSize < 0)
|
||||
return err("invalid iNES file extent: expected a nonnegative safe integer");
|
||||
if (fileSize < 16 || prefix.length < 16)
|
||||
return err("truncated iNES header: expected 16 bytes");
|
||||
const prgUnits = prefix.readUInt8(4);
|
||||
const chrUnits = prefix.readUInt8(5);
|
||||
const flags6 = prefix.readUInt8(6);
|
||||
const flags7 = prefix.readUInt8(7);
|
||||
if ((flags7 & 0x0c) !== 0) return err("unsupported iNES header variant");
|
||||
// Dirty legacy headers make the upper mapper bits ambiguous. Do not repair
|
||||
// them or claim a mapper that the observed header cannot establish.
|
||||
if (prefix.subarray(12, 16).some((byte) => byte !== 0))
|
||||
return err(
|
||||
"ambiguous iNES mapper: reserved header bytes 12..15 are nonzero",
|
||||
);
|
||||
if (prgUnits === 0) return err("iNES requires at least one PRG-ROM unit");
|
||||
const trainer = (flags6 & 4) !== 0;
|
||||
const declaredEnd =
|
||||
16 + (trainer ? 512 : 0) + prgUnits * 16_384 + chrUnits * 8_192;
|
||||
if (declaredEnd > fileSize)
|
||||
return err(
|
||||
`truncated iNES payload: header declares ${declaredEnd} bytes; file has ${fileSize}`,
|
||||
);
|
||||
const regions: InesRegion[] = [{ path: "header.bin", offset: 0, length: 16 }];
|
||||
let offset = 16;
|
||||
if (trainer) {
|
||||
regions.push({ path: "trainer.bin", offset, length: 512 });
|
||||
offset += 512;
|
||||
}
|
||||
for (const [kind, count, length] of [
|
||||
["prg", prgUnits, 16_384],
|
||||
["chr", chrUnits, 8_192],
|
||||
] as const)
|
||||
for (let index = 0; index < count; index += 1) {
|
||||
regions.push({
|
||||
path: `${kind}/${String(index).padStart(3, "0")}.bin`,
|
||||
offset,
|
||||
length,
|
||||
});
|
||||
offset += length;
|
||||
}
|
||||
if (offset < fileSize)
|
||||
regions.push({ path: "trailing.bin", offset, length: fileSize - offset });
|
||||
return ok({
|
||||
header: {
|
||||
format: "ines",
|
||||
header_hex: prefix.subarray(0, 16).toString("hex"),
|
||||
prg_rom_units_16k: prgUnits,
|
||||
chr_rom_units_8k: chrUnits,
|
||||
mapper: (flags6 >>> 4) | (flags7 & 0xf0),
|
||||
flags_6: flags6,
|
||||
flags_7: flags7,
|
||||
trainer_present: trainer,
|
||||
battery_flag: (flags6 & 2) !== 0,
|
||||
mirroring:
|
||||
(flags6 & 8) !== 0
|
||||
? "four-screen"
|
||||
: (flags6 & 1) !== 0
|
||||
? "vertical"
|
||||
: "horizontal",
|
||||
},
|
||||
regions,
|
||||
});
|
||||
};
|
||||
Reference in New Issue
Block a user