diff --git a/scripts/verify/architecture-guard-baselines.json b/scripts/verify/architecture-guard-baselines.json
index 7a53f9710b..ae0bf2e639 100644
--- a/scripts/verify/architecture-guard-baselines.json
+++ b/scripts/verify/architecture-guard-baselines.json
@@ -83,10 +83,7 @@
"src/process/ownedDebuggerSession.ts": 1
},
"parser-format-failure-class": {
- "src/browser/assets/WebArtifactReads.ts": 1,
- "src/domain/xmlDocument.ts": 1,
- "src/native/AppleMachoSelection.ts": 1,
- "src/native/MachoCommandNames.ts": 1
+ "src/domain/evidenceFormat.ts": 1
},
"parser-json-parse": {
"src/android/JadxProtocol.ts": 2,
@@ -113,14 +110,6 @@
"src/artifacts/ReleaseExposureReader.ts": 1,
"src/artifacts/StreamBytes.ts": 1,
"src/artifacts/ZipArtifactReader.ts": 1,
- "src/artifacts/apple/BinaryPlistMaterializer.ts": 4,
- "src/artifacts/apple/KeyedArchiveReader.ts": 1,
- "src/artifacts/apple/NibArchive.ts": 19,
- "src/artifacts/apple/PlistScalars.ts": 3,
- "src/artifacts/apple/PropertyListDecodeBudget.ts": 25,
- "src/domain/apple/interfaceBuilderKeyedArchive.ts": 1,
- "src/domain/apple/keyedArchive.ts": 5,
- "src/domain/apple/plistValue.ts": 3,
"src/domain/native/functionByteCoverage.ts": 1,
"src/domain/python/marshalUtf8.ts": 1,
"src/dotnet/ManagedArtifactInspector.ts": 1,
@@ -143,7 +132,6 @@
"src/native/apple/AppleIpsFieldReader.ts": 1,
"src/native/parsers/demangle.ts": 3,
"src/native/parsers/lipo.ts": 1,
- "src/native/parsers/plist.ts": 1,
"src/native/pwndbg/PwndbgCoreContext.ts": 2,
"src/native/pwntools/PwntoolsDecoder.ts": 2,
"src/native/pwntools/PwntoolsResourceLimits.ts": 1
@@ -285,8 +273,6 @@
},
"range-error-interpretation": {
"src/application/JsonInputFile.ts": 1,
- "src/artifacts/apple/InterfaceBuilderAnalysis.ts": 1,
- "src/artifacts/apple/KeyedArchiveReader.ts": 1,
"src/artifacts/nodeSea/NodeSeaBlob.ts": 1,
"src/browser/WebBundleAnalysisWorkerServer.ts": 1,
"src/cli/cliResultOutput.ts": 1,
@@ -710,5 +696,6 @@
"scripts/verify/javascript/recovery.mjs": 1,
"scripts/verify/javascript/retained-facts.mjs": 1,
"scripts/verify/managed/conformance.mjs": 1
- }
+ },
+ "macho-load-command-literal": {}
}
diff --git a/scripts/verify/architecture-guards.mjs b/scripts/verify/architecture-guards.mjs
index b093c674bc..152b2c1506 100644
--- a/scripts/verify/architecture-guards.mjs
+++ b/scripts/verify/architecture-guards.mjs
@@ -422,8 +422,11 @@ checkCounted(
["src/native/metadata/BinaryContainer.ts"],
);
+// An input fault is a ParseFailureError; a broken internal assumption is a
+// defect, not an input fault, and throws invariantViolation from
+// src/domain/internalInvariant so callers never read it as bad bytes.
checkCounted(
- "plain Error, TypeError or RangeError thrown by a parser (throw a ParseFailureError from src/domain/parseFailure)",
+ "plain Error, TypeError or RangeError thrown by a parser (throw a ParseFailureError from src/domain/parseFailure for an input fault, or invariantViolation from src/domain/internalInvariant for a broken internal assumption)",
"parser-plain-throw",
parserFiles,
/throw new (?:Error|TypeError|RangeError)\(/gu,
@@ -432,15 +435,34 @@ checkCounted(
// A per-format failure class restates the ParseFailure algebra under its own
// spelling and needs its own catch-site translation; parsers throw a
-// ParseFailureError (or a subclass of it) instead.
+// ParseFailureError instead. A subclass of ParseFailureError (such as
+// CaptureFormatError) keeps the shared kind and is not counted. The name
+// pattern covers format, parse, document, source, decode and syntax failures,
+// and any property-list or archive failure (such as a nesting limit or an
+// unsupported UID), built on any of the host's general error classes.
checkCounted(
- "per-format failure class extending Error (throw a ParseFailureError from src/domain/parseFailure)",
+ "per-format failure class extending a host error (throw a ParseFailureError from src/domain/parseFailure)",
"parser-format-failure-class",
files,
- /class \w*(?:Format|Parse)(?:Failure|Error) extends Error\b/gu,
+ /class (?:\w*(?:Format|Parse|Document|Source|Decode|Decoding|Encoding|Syntax)|\w*(?:Plist|PropertyList|Archive)\w*)(?:Failure|Error|Issue) extends (?:Error|TypeError|RangeError|SyntaxError)\b/gu,
["src/domain/parseFailure.ts"],
);
+// Mach-O load-command codes have one table; a literal code in a load-command
+// reader restates it and drifts from the named command it means.
+checkCounted(
+ "literal Mach-O load-command code (use LC from src/domain/apple/machoLoadCommandCodes)",
+ "macho-load-command-literal",
+ files.filter((file) =>
+ /MachoLoadCommandCursor|readMachoLoadCommand|machoLoadCommandCodes/u.test(
+ file.content,
+ ),
+ ),
+ // An equality test, or membership in a literal list of codes.
+ /\b(?:frame\.command|command\.kind|command|cmd)\s*[!=]==\s*(?:0x[0-9a-fA-F]+|\d+)\b|\[\s*(?:0x[0-9a-fA-F]+|\d+)(?:\s*,\s*(?:0x[0-9a-fA-F]+|\d+))*\s*,?\s*\]\s*\.(?:includes|indexOf)\(\s*(?:\w+\.)*(?:command|cmd|kind)\s*\)/gu,
+ ["src/domain/apple/machoLoadCommandCodes.ts"],
+);
+
// JSON.parse keeps the last of repeated member names without saying so; a
// parser of artifact content must state its duplicate-member policy
// (src/domain/jsonDuplicateMember.ts finds a repeated name).
diff --git a/src/android/AndroidManifestComponents.ts b/src/android/AndroidManifestComponents.ts
index 7ae622a346..c8185ed8dd 100644
--- a/src/android/AndroidManifestComponents.ts
+++ b/src/android/AndroidManifestComponents.ts
@@ -165,7 +165,7 @@ export const parseAndroidManifestComponents = (
});
if (!parsed.ok)
return unavailable(
- `The decoded manifest is not well-formed XML (${parsed.error.reason}), so its component inventory is unavailable.`,
+ `The decoded manifest is not well-formed XML (${parsed.error.failure.field ?? parsed.error.kind}), so its component inventory is unavailable.`,
);
const root = parsed.value.documentElement;
if (!isManifestElement(root) || root.nodeName !== "manifest")
diff --git a/src/apktool/ApktoolDecodeOutput.test.ts b/src/apktool/ApktoolDecodeOutput.test.ts
index 247c4b5d7d..4bc9a3edc8 100644
--- a/src/apktool/ApktoolDecodeOutput.test.ts
+++ b/src/apktool/ApktoolDecodeOutput.test.ts
@@ -346,9 +346,9 @@ describe("parseDecodedStrings", () => {
expect(parseDecodedStrings(xml)).toMatchObject({
ok: false,
error: {
- _tag: "ApktoolStringsDocumentError",
- reason: "malformed",
- cause: { _tag: "XmlDocumentParseError" },
+ _tag: "ParseFailureError",
+ kind: "malformed",
+ failure: { format: "xml" },
},
});
});
@@ -436,7 +436,11 @@ describe("string document validity and omission counts", () => {
parseDecodedStrings("no"),
).toMatchObject({
ok: false,
- error: { _tag: "ApktoolStringsDocumentError", reason: "malformed" },
+ error: {
+ _tag: "ParseFailureError",
+ kind: "malformed",
+ failure: { format: "xml" },
+ },
});
expect(
parseDecodedStrings(
@@ -452,7 +456,14 @@ it.each(["", 'one'])(
const parsed = parseDecodedStrings(xml);
expect(parsed).toMatchObject({
ok: false,
- error: { _tag: "ApktoolStringsDocumentError", reason: "wrong_root" },
+ error: {
+ _tag: "ParseFailureError",
+ kind: "malformed",
+ failure: {
+ format: "android-string-resources",
+ field: "documentElement",
+ },
+ },
});
expect(parsed).not.toHaveProperty("value");
if (parsed.ok) throw new Error("Expected document failure");
diff --git a/src/apktool/ApktoolDecodeOutput.ts b/src/apktool/ApktoolDecodeOutput.ts
index a86dffdc5a..8c9d24ff75 100644
--- a/src/apktool/ApktoolDecodeOutput.ts
+++ b/src/apktool/ApktoolDecodeOutput.ts
@@ -1,6 +1,10 @@
import type { Element, Node } from "@xmldom/xmldom";
-import { parseXmlDocument } from "../domain/xmlDocument.js";
+import {
+ parseXmlDocument,
+ type XmlParseFailure,
+} from "../domain/xmlDocument.js";
import { ok, err, type Result } from "../domain/result.js";
+import { malformedInput } from "../domain/parseFailure.js";
import {
isMap,
isScalar,
@@ -158,18 +162,6 @@ export interface DecodedStringEntry {
readonly value: string;
}
-/** A whole-document failure does not establish an omitted-entry count. */
-export class ApktoolStringsDocumentError extends Error {
- readonly _tag = "ApktoolStringsDocumentError";
- constructor(
- readonly reason: "malformed" | "wrong_root",
- message: string,
- options?: ErrorOptions,
- ) {
- super(message, options);
- }
-}
-
/**
* Project direct `` children from decoded resources XML. DOM parsing
* identifies elements and attributes; text values are sliced from the input
@@ -183,24 +175,21 @@ export const parseDecodedStrings = (
readonly entries: readonly DecodedStringEntry[];
readonly unparsedCount: number;
},
- ApktoolStringsDocumentError
+ // A whole-document failure does not establish an omitted-entry count.
+ XmlParseFailure
> => {
const parsed = parseXmlDocument(stringsXml, {
doctype: "allow",
lineEndings: "preserve",
});
- if (!parsed.ok)
- return err(
- new ApktoolStringsDocumentError("malformed", parsed.error.message, {
- cause: parsed.error,
- }),
- );
+ if (!parsed.ok) return err(parsed.error);
const root = parsed.value.documentElement;
if (root === null || root.nodeName !== "resources")
return err(
- new ApktoolStringsDocumentError(
- "wrong_root",
+ malformedInput(
+ "android-string-resources",
"String resource document root must be ",
+ { field: "documentElement" },
),
);
diff --git a/src/artifacts/apple/BinaryPlistMaterializer.test.ts b/src/artifacts/apple/BinaryPlistMaterializer.test.ts
index 8395821bf2..fd9b8bd1de 100644
--- a/src/artifacts/apple/BinaryPlistMaterializer.test.ts
+++ b/src/artifacts/apple/BinaryPlistMaterializer.test.ts
@@ -10,6 +10,7 @@ import {
} from "./BinaryPlistMaterializer.js";
import { estimateBinaryPlistExpansion } from "./PropertyListDecodeBudget.js";
import { parseXmlPropertyList } from "../../domain/propertyListKeys.js";
+import { InternalInvariantError } from "../../domain/internalInvariant.js";
const source = (objects: readonly Buffer[]): Buffer => {
const table =
@@ -300,3 +301,14 @@ it("bounds the text that overlapping table entries repeat", () => {
// A range past the remaining budget is rejected before it is decoded.
expect(decodedBytes).toBeLessThanOrEqual(2 * budget + bytes.length);
});
+
+it("reports a plan without its binary source as a defect, not as bad input", () => {
+ const bytes = source([text("value")]);
+ const { binaryValuePlan: _omitted, ...plan } = estimateBinaryPlistExpansion(
+ bytes,
+ 1024 * 1024,
+ );
+ expect(() => decodeBinaryPlistValue(bytes, plan)).toThrow(
+ InternalInvariantError,
+ );
+});
diff --git a/src/artifacts/apple/BinaryPlistMaterializer.ts b/src/artifacts/apple/BinaryPlistMaterializer.ts
index 39e0e07014..7ac6a306ce 100644
--- a/src/artifacts/apple/BinaryPlistMaterializer.ts
+++ b/src/artifacts/apple/BinaryPlistMaterializer.ts
@@ -1,3 +1,4 @@
+import { invariantViolation } from "../../domain/internalInvariant.js";
import { readBinaryPlistLayout } from "./BinaryPlistLayout.js";
import { parseBinary } from "plist";
import { markPlistDictionary } from "../../domain/apple/plistUid.js";
@@ -27,7 +28,7 @@ const scalarArrayInput = (
// belong to the compatible decoder copy, not the original source plan.
const compatibleLayoutResult = readBinaryPlistLayout(bytes);
if (!compatibleLayoutResult.ok)
- throw new RangeError("binary plist trailer is truncated");
+ throw invariantViolation("binary plist decoder copy lost its trailer");
const compatibleLayout = compatibleLayoutResult.value;
const referenceWidth = compatibleLayout.referenceWidth;
const objectCount = Number(compatibleLayout.objectCount);
@@ -115,7 +116,7 @@ export const decodeBinaryPlistValue = (
): unknown => {
const source = plan.binaryValuePlan;
if (source === undefined)
- throw new TypeError("Binary plist source plan is missing");
+ throw invariantViolation("Binary plist source plan is missing");
const compatible = decodeBinaryPlistScalars(bytes, metadata, plan);
const scalars = parseBinary(
scalarArrayInput(
@@ -140,7 +141,7 @@ export const decodeBinaryPlistValue = (
if (container === undefined) {
const index = scalarIndex.get(entry.object);
if (index === undefined)
- throw new TypeError("Binary plist scalar source is missing");
+ throw invariantViolation("Binary plist scalar source is missing");
value = scalarOccurrence(
scalars[index],
source.scalars[index]!.uid,
@@ -234,7 +235,10 @@ export const decodeBinaryPlistText = (
): BinaryPlistText => {
decodeBinaryPlistValue(bytes, preflightPropertyListDecode(bytes, maxBytes));
const layout = readBinaryPlistLayout(bytes);
- if (!layout.ok) throw new RangeError("binary plist trailer is truncated");
+ if (!layout.ok)
+ throw invariantViolation(
+ "binary plist trailer was not validated by its preflight",
+ );
const texts: string[] = [];
let decoded = 0;
let complete = true;
diff --git a/src/artifacts/apple/InterfaceBuilderAnalysis.ts b/src/artifacts/apple/InterfaceBuilderAnalysis.ts
index 556f7607d6..9546f6634e 100644
--- a/src/artifacts/apple/InterfaceBuilderAnalysis.ts
+++ b/src/artifacts/apple/InterfaceBuilderAnalysis.ts
@@ -1,4 +1,8 @@
import { createHash } from "node:crypto";
+import {
+ isHostLimitFailure,
+ ParseFailureError,
+} from "../../domain/parseFailure.js";
import { TextDecoder } from "node:util";
import { decodeBinaryPropertyList } from "./BinaryPlistMaterializer.js";
@@ -39,7 +43,6 @@ import {
type PlistDecodePreflight,
} from "./PropertyListDecodeBudget.js";
import {
- interfaceBuilderDecodeBudgetFailure,
InterfaceBuilderDecodeBudget,
InterfaceBuilderDecodeBudgetExceeded,
} from "./InterfaceBuilderDecodeBudget.js";
@@ -216,7 +219,6 @@ const decodeInterfaceBuilderBundle = async (
numberProjection: true,
uidProjection: true,
budget: "the aggregate Interface Builder decode budget",
- fail: interfaceBuilderDecodeBudgetFailure,
},
);
decodeBudget.reserve(
@@ -288,6 +290,12 @@ const decodeInterfaceBuilderBundle = async (
recordOmittedArchive(entry.path, cause.reason);
continue;
}
+ // A plist decode budget or nesting limit is not evidence the archive
+ // is malformed; it is omitted against the shared budget.
+ if (cause instanceof ParseFailureError && cause.kind === "limit") {
+ recordOmittedArchive(entry.path, "aggregate_decode_budget_exhausted");
+ continue;
+ }
if (cause instanceof UnsupportedBinaryPlistUidError) {
recordOmittedArchive(entry.path, "unsupported_uid_exact_range");
continue;
@@ -1059,14 +1067,15 @@ const readEntry = async (
/**
* The shared parser bounds plist value nesting before its recursive decode and
- * reports the limit as a RangeError; that is an omitted archive, not a
+ * reports the limit as a `limit` parse failure, which the document loop omits.
+ * A host stack or capacity limit is likewise an omitted archive, not a
* malformed one.
*/
const parseXmlWithinDecodeBudget = (text: string) => {
try {
return parseXmlPropertyList(text);
} catch (cause: unknown) {
- if (cause instanceof RangeError)
+ if (cause instanceof Error && isHostLimitFailure(cause))
throw new InterfaceBuilderDecodeBudgetExceeded(
"aggregate_decode_budget_exhausted",
cause.message,
diff --git a/src/artifacts/apple/InterfaceBuilderDecodeBudget.test.ts b/src/artifacts/apple/InterfaceBuilderDecodeBudget.test.ts
index ec2c0d0a82..d4b65c43ba 100644
--- a/src/artifacts/apple/InterfaceBuilderDecodeBudget.test.ts
+++ b/src/artifacts/apple/InterfaceBuilderDecodeBudget.test.ts
@@ -6,7 +6,6 @@ import { buildBinary } from "plist";
import { describe, expect, it } from "vitest";
import { analyzeInterfaceBuilderBundle } from "./InterfaceBuilderAnalysis.js";
-import { interfaceBuilderDecodeBudgetFailure } from "./InterfaceBuilderDecodeBudget.js";
import { preflightPropertyListDecode } from "./PropertyListDecodeBudget.js";
import { parseXmlPropertyList } from "../../domain/propertyListKeys.js";
import { createTestTempDirectory } from "../../../tests/fixtures/temporaryDirectory.js";
@@ -128,7 +127,6 @@ describe("inert XML declaration examples in Interface Builder archives", () => {
undefined,
{
budget: "the aggregate Interface Builder decode budget",
- fail: interfaceBuilderDecodeBudgetFailure,
},
),
).toThrow(
@@ -151,7 +149,6 @@ describe("inert XML declaration examples in Interface Builder archives", () => {
undefined,
{
budget: "the aggregate Interface Builder decode budget",
- fail: interfaceBuilderDecodeBudgetFailure,
},
),
).not.toThrow();
@@ -352,6 +349,28 @@ describe("binary Interface Builder plist dates", () => {
);
});
+ it("reports a reference cycle as an invalid archive, not a budget omission", async () => {
+ // One array (offset 8) whose only reference is itself; 1-byte offsets
+ // and references, offset table at 10.
+ const trailer = Buffer.alloc(32);
+ trailer[6] = 1;
+ trailer[7] = 1;
+ trailer.writeBigUInt64BE(1n, 8);
+ trailer.writeBigUInt64BE(10n, 24);
+ const cycle = Buffer.concat([
+ Buffer.from("bplist00"),
+ Buffer.from([0xa1, 0x00, 0x08]),
+ trailer,
+ ]);
+ const result = await nib(cycle, "cycle");
+ expect(result.limitations.join("\n")).toContain(
+ "Panel.nib: binary plist object references form a cycle",
+ );
+ expect(JSON.stringify(result)).not.toContain(
+ "aggregate_decode_budget_exhausted",
+ );
+ });
+
it("counts a sub-millisecond date as unknown and keeps the canonical control known", async () => {
const submillisecond = Buffer.from(control);
const offset = submillisecond.indexOf(marker);
diff --git a/src/artifacts/apple/InterfaceBuilderDecodeBudget.ts b/src/artifacts/apple/InterfaceBuilderDecodeBudget.ts
index 11aad7169c..0f0a115156 100644
--- a/src/artifacts/apple/InterfaceBuilderDecodeBudget.ts
+++ b/src/artifacts/apple/InterfaceBuilderDecodeBudget.ts
@@ -12,16 +12,6 @@ export class InterfaceBuilderDecodeBudgetExceeded extends Error {
}
}
-/** Map shared plist preflight limits to Interface Builder's public reason. */
-export const interfaceBuilderDecodeBudgetFailure = (
- _kind: "cycle" | "depth" | "expansion",
- message: string,
-): Error =>
- new InterfaceBuilderDecodeBudgetExceeded(
- "aggregate_decode_budget_exhausted",
- message,
- );
-
/** Shared byte budget for decoder records and projected archive data. */
export class InterfaceBuilderDecodeBudget {
readonly #initialBytes: number;
diff --git a/src/artifacts/apple/KeyedArchiveReader.test.ts b/src/artifacts/apple/KeyedArchiveReader.test.ts
index 69f3e124e3..eddd6c4706 100644
--- a/src/artifacts/apple/KeyedArchiveReader.test.ts
+++ b/src/artifacts/apple/KeyedArchiveReader.test.ts
@@ -11,6 +11,7 @@ import {
inspectBundleKeyedArchive,
} from "./KeyedArchiveReader.js";
import { PlistNestingLimitError } from "../../domain/apple/plistValue.js";
+import { ParseFailureError } from "../../domain/parseFailure.js";
import { deeplyNestedXmlPlist } from "../../../tests/fixtures/keyedArchiveXmlNesting.js";
import { createTestTempDirectory } from "../../../tests/fixtures/temporaryDirectory.js";
import { embedSubmillisecondDateInWideIntegerPayload } from "../../../tests/fixtures/binaryPlistScalarAlias.js";
@@ -421,9 +422,13 @@ describe("binary plist reference preflight", () => {
expect(() =>
decodeKeyedArchiveBytes(keyedRoot([plistArray([8])]), selection),
).toThrow(
- new TypeError(
- "binary plist object references form a cycle, which a property list cannot represent",
- ),
+ expect.objectContaining({
+ failure: expect.objectContaining({
+ kind: "malformed",
+ detail:
+ "binary plist object references form a cycle, which a property list cannot represent",
+ }),
+ }),
);
});
@@ -437,7 +442,14 @@ describe("binary plist reference preflight", () => {
keyedRoot([...levels, plistString("x")]),
selection,
),
- ).toThrow(RangeError);
+ ).toThrow(
+ expect.objectContaining({
+ failure: expect.objectContaining({
+ kind: "limit",
+ limit: { name: "plist-decode-bytes", maximum: 512 * 1024 * 1024 },
+ }),
+ }),
+ );
});
it("decodes shared leaf references", () => {
@@ -646,7 +658,8 @@ describe("binary keyed archive invalid dates", () => {
} catch (cause: unknown) {
decodeFailure = cause;
}
- expect(decodeFailure).toBeInstanceOf(TypeError);
+ expect(decodeFailure).toBeInstanceOf(ParseFailureError);
+ expect(decodeFailure).toMatchObject({ kind: "malformed" });
if (!(decodeFailure instanceof Error))
throw new Error("Expected invalid date marker to fail");
expect(decodeFailure.message).toContain(`0x${marker.toString(16)}`);
diff --git a/src/artifacts/apple/KeyedArchiveReader.ts b/src/artifacts/apple/KeyedArchiveReader.ts
index 2cd1eedb56..c118596b14 100644
--- a/src/artifacts/apple/KeyedArchiveReader.ts
+++ b/src/artifacts/apple/KeyedArchiveReader.ts
@@ -1,4 +1,9 @@
import { createHash } from "node:crypto";
+import {
+ decodeLimit,
+ isHostLimitFailure,
+ ParseFailureError,
+} from "../../domain/parseFailure.js";
import { basename, join } from "node:path";
import { realpath } from "node:fs/promises";
import { readStableArtifact } from "../readStableArtifact.js";
@@ -81,7 +86,10 @@ export const decodeKeyedArchiveBytes = (
selection: { root?: string | undefined; offset: number; limit: number },
) => {
if (bytes.length > MAX_BYTES)
- throw new RangeError("Keyed archive exceeds 64 MiB");
+ throw decodeLimit("keyed-archive", "Keyed archive exceeds 64 MiB", {
+ name: "keyed-archive-bytes",
+ maximum: MAX_BYTES,
+ });
if (hasNibArchiveSignature(bytes))
throw new KeyedArchiveKindError(
"Selected file is a compiled NIBArchive, not a Foundation plist archive; decode it with decode_interface_builder",
@@ -91,16 +99,10 @@ export const decodeKeyedArchiveBytes = (
const xmlText = binary ? undefined : decodeXmlPlistText(bytes);
// Scalar decoding and source container materialization expand shared references,
// so a few hundred bytes can exhaust memory or the stack without preflight.
- // RangeError reports a resource limit; a reference cycle is malformed.
+ // A budget is a `limit` parse failure; a reference cycle is malformed.
const binaryExpansion = binary
? estimateBinaryPlistExpansion(bytes, MAX_DECODE_BYTES, {
budget: "the keyed archive decode budget",
- fail: (kind, message) =>
- kind === "cycle"
- ? new TypeError(
- "binary plist object references form a cycle, which a property list cannot represent",
- )
- : new RangeError(message),
bounds: "decoder",
numberProjection: true,
uidProjection: true,
@@ -171,7 +173,7 @@ export const decodeKeyedArchiveBytes = (
* decode_interface_builder is portable; inspect_plist requires macOS.
*/
const keyedArchiveKindRemediation = (
- kind: KeyedArchiveKindError["kind"],
+ kind: KeyedArchiveKindError["fileKind"],
platform: NodeJS.Platform,
): string => {
if (kind === "nib-archive")
@@ -469,13 +471,16 @@ const decodeSelectedArchive = (
{
cause,
remediationAction: keyedArchiveKindRemediation(
- cause.kind,
+ cause.fileKind,
input.platform ?? process.platform,
),
},
);
throw new ArtifactReaderFailure(
- cause instanceof RangeError ? "limit" : "format",
+ (cause instanceof ParseFailureError && cause.kind === "limit") ||
+ isHostLimitFailure(cause)
+ ? "limit"
+ : "format",
`Cannot decode selected Foundation keyed archive: ${cause instanceof Error ? cause.message : String(cause)}`,
{ cause },
);
diff --git a/src/artifacts/apple/MachoLoadCommandReader.ts b/src/artifacts/apple/MachoLoadCommandReader.ts
index c456c5d603..1566b8b58a 100644
--- a/src/artifacts/apple/MachoLoadCommandReader.ts
+++ b/src/artifacts/apple/MachoLoadCommandReader.ts
@@ -1,4 +1,9 @@
import { LC } from "../../domain/apple/machoLoadCommandCodes.js";
+import {
+ malformedInput,
+ ParseFailureError,
+ unsupportedInput,
+} from "../../domain/parseFailure.js";
import {
machoDependencyCommand,
readMachoDylibCommandFacts,
@@ -22,8 +27,8 @@ import type {
} from "../../domain/apple/dylibResolution.js";
import { machoArchitectureName } from "../../domain/apple/machoCpuIdentity.js";
import {
+ MACHO_VERSION_MIN_PLATFORMS,
legacyMachoPlatform,
- type MachoVersionMinPlatform,
} from "../../domain/apple/machoPlatform.js";
import {
classifyFatContainerIdentity,
@@ -61,15 +66,6 @@ const MAX_LAZY_INFO_SYMBOL_REFERENCES = 64 * 1024;
const CPU_TYPE_ARM64 = 0x0100000c;
-/** loader.h command codes and their device platform identities. */
-const VERSION_MIN_PLATFORMS: ReadonlyMap =
- new Map([
- [0x24, 1], // LC_VERSION_MIN_MACOSX
- [0x25, 2], // LC_VERSION_MIN_IPHONEOS
- [0x2f, 3], // LC_VERSION_MIN_TVOS
- [0x30, 4], // LC_VERSION_MIN_WATCHOS
- ]);
-
const LAZY_INFO_HEADER_BYTES = 24;
/** ld64 may-be-missing bit: the lazy image is allowed to be absent. */
const LAZY_INFO_MAY_BE_MISSING = 0x1;
@@ -83,15 +79,24 @@ const DYLIB_USE_REEXPORT = 0x2;
const DYLIB_USE_UPWARD = 0x4;
const DYLIB_USE_DELAYED_INIT = 0x8;
+const MACHO_FORMAT = "mach-o";
+
/** Malformed or unsupported structure found while decoding one image. */
-class MachoFormatIssue extends Error {
- constructor(
- readonly status: "malformed" | "unsupported",
- message: string,
- ) {
- super(message);
- }
-}
+const machoIssue = (
+ status: "malformed" | "unsupported",
+ reason: string,
+): ParseFailureError<"malformed"> | ParseFailureError<"unsupported"> =>
+ status === "malformed"
+ ? malformedInput(MACHO_FORMAT, reason)
+ : unsupportedInput(MACHO_FORMAT, reason);
+
+/** The issue this reader threw, or `undefined` for any other failure. */
+const machoIssueOf = (cause: unknown): MachoReadIssue | undefined =>
+ cause instanceof ParseFailureError &&
+ cause.failure.format === MACHO_FORMAT &&
+ (cause.kind === "malformed" || cause.kind === "unsupported")
+ ? { status: cause.kind, reason: cause.message }
+ : undefined;
/** A structural defect, and whether it is malformed or merely unsupported. */
export interface MachoReadIssue {
@@ -278,8 +283,8 @@ export const readMachoImage = async (
...(hiddenSlice === null ? {} : { hiddenSlices: [hiddenSlice] }),
};
} catch (cause: unknown) {
- if (cause instanceof MachoFormatIssue)
- return { status: cause.status, reason: cause.message };
+ const issue = machoIssueOf(cause);
+ if (issue !== undefined) return issue;
throw cause;
}
};
@@ -334,10 +339,9 @@ const readHiddenSlice = async (
row: HiddenFatRow | null,
): Promise => {
if (row === null) return null;
- if (row.status !== "declared")
- throw new MachoFormatIssue(row.status, row.reason);
+ if (row.status !== "declared") throw machoIssue(row.status, row.reason);
const { declaration, rangeIssue } = row;
- if (rangeIssue !== null) throw new MachoFormatIssue("malformed", rangeIssue);
+ if (rangeIssue !== null) throw machoIssue("malformed", rangeIssue);
const slice = await readSlice(readAt, declaration.offset, declaration.size, {
fatCpuType: declaration.cpuType,
fatCpuSubtype: declaration.cpuSubtype,
@@ -347,8 +351,7 @@ const readHiddenSlice = async (
cpuType: slice.cpu_type,
cpuSubtype: slice.cpu_subtype,
});
- if (identityIssue !== null)
- throw new MachoFormatIssue("malformed", identityIssue);
+ if (identityIssue !== null) throw machoIssue("malformed", identityIssue);
return { ...slice, hidden: true };
};
@@ -359,7 +362,7 @@ const readFatSlices = async (
const slices: MachoSlice[] = [];
// Keep validating after an unsupported slice so a later malformed slice is
// reported as malformed whatever the slice order.
- let unsupported: MachoFormatIssue | undefined;
+ let unsupported: MachoReadIssue | undefined;
for (const declaration of declarations) {
const { offset, size: length, cpuType, cpuSubtype } = declaration;
let slice: MachoSlice;
@@ -370,23 +373,20 @@ const readFatSlices = async (
alignmentExponent: declaration.alignmentExponent,
});
} catch (cause: unknown) {
- if (
- !(cause instanceof MachoFormatIssue) ||
- cause.status !== "unsupported"
- )
- throw cause;
- unsupported ??= cause;
+ const issue = machoIssueOf(cause);
+ if (issue?.status !== "unsupported") throw cause;
+ unsupported ??= issue;
continue;
}
const identityIssue = validateFatSliceIdentity(declaration, {
cpuType: slice.cpu_type,
cpuSubtype: slice.cpu_subtype,
});
- if (identityIssue !== null)
- throw new MachoFormatIssue("malformed", identityIssue);
+ if (identityIssue !== null) throw machoIssue("malformed", identityIssue);
slices.push(slice);
}
- if (unsupported !== undefined) throw unsupported;
+ if (unsupported !== undefined)
+ throw machoIssue(unsupported.status, unsupported.reason);
return slices;
};
@@ -531,8 +531,7 @@ const readSlice = async (
} | null = null,
): Promise => {
const table = await readSliceCommandTable(readAt, base, length);
- if (table.status !== "read")
- throw new MachoFormatIssue(table.status, table.reason);
+ if (table.status !== "read") throw machoIssue(table.status, table.reason);
const { header } = table;
const slice: MachoSlice = {
architecture: machoArchitectureName(header.cpuType, header.cpuSubtype),
@@ -571,7 +570,7 @@ const readSlice = async (
if (command === LC.LAZY_LOAD_DYLIB_INFO) {
lazyInfoCount += 1;
if (lazyInfoCount > MAX_LAZY_INFO_DEPENDENCIES)
- throw new MachoFormatIssue(
+ throw machoIssue(
"unsupported",
`LC_LAZY_LOAD_DYLIB_INFO commands exceed the ${MAX_LAZY_INFO_DEPENDENCIES}-dependency limit`,
);
@@ -580,9 +579,9 @@ const readSlice = async (
if (decoded !== undefined) dependencies.push(decoded);
});
if (framed.status !== "framed")
- throw new MachoFormatIssue(framed.status, framed.reason);
+ throw machoIssue(framed.status, framed.reason);
if (lazyInfoCount > 0 && unreadableSegment !== undefined)
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${unreadableSegment} is too short to establish the slice VM range for LC_LAZY_LOAD_DYLIB_INFO`,
);
@@ -676,7 +675,7 @@ const containedPayload = (
for (const read of reads) {
work.rangeChecks += 1;
if (work.rangeChecks > MAX_LOAD_COMMAND_BYTES)
- throw new MachoFormatIssue(
+ throw machoIssue(
"unsupported",
`LC_LAZY_LOAD_DYLIB_INFO payload range lookup exceeds the ${MAX_LOAD_COMMAND_BYTES}-check limit`,
);
@@ -758,7 +757,7 @@ const decodeCommand = (
}
if (command === LC.CODE_SIGNATURE) {
if (readMachoLinkeditDataCommand(LC.CODE_SIGNATURE, body, true) === null)
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${index} is too short for LC_CODE_SIGNATURE`,
);
@@ -767,14 +766,14 @@ const decodeCommand = (
}
if (command === LC.BUILD_VERSION) {
if (body.byteLength < 24)
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${index} is too short for LC_BUILD_VERSION`,
);
const view = viewOf(body);
const toolCount = view.getUint32(20, true);
if (toolCount > Math.floor((body.byteLength - 24) / 8))
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${index} LC_BUILD_VERSION tool records exceed cmdsize`,
);
@@ -782,10 +781,10 @@ const decodeCommand = (
slice.platforms.push(platform);
return;
}
- const legacyPlatform = VERSION_MIN_PLATFORMS.get(command);
+ const legacyPlatform = MACHO_VERSION_MIN_PLATFORMS.get(command);
if (legacyPlatform !== undefined) {
if (body.byteLength < 16)
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${index} is too short for a version-min command`,
);
@@ -809,7 +808,7 @@ const decodeLazyLoadDylibInfoCommand = (
index: number,
): LazyLoadDylibInfoCommand => {
if (body.byteLength < 16)
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${index} is too short for LC_LAZY_LOAD_DYLIB_INFO`,
);
@@ -817,12 +816,12 @@ const decodeLazyLoadDylibInfoCommand = (
const dataOffset = view.getUint32(8, true);
const dataSize = view.getUint32(12, true);
if (dataSize < LAZY_INFO_HEADER_BYTES)
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${index} LC_LAZY_LOAD_DYLIB_INFO payload is shorter than its 24-byte header`,
);
if (dataSize > MAX_LOAD_COMMAND_BYTES)
- throw new MachoFormatIssue(
+ throw machoIssue(
"unsupported",
`LC_LAZY_LOAD_DYLIB_INFO payload occupies ${dataSize} bytes, above the ${MAX_LOAD_COMMAND_BYTES}-byte limit`,
);
@@ -840,7 +839,7 @@ const readLazyPayloadBytes = async (
if (covered !== undefined) return covered;
work.payloadBytes += size;
if (work.payloadBytes > MAX_LOAD_COMMAND_BYTES)
- throw new MachoFormatIssue(
+ throw machoIssue(
"unsupported",
`LC_LAZY_LOAD_DYLIB_INFO payloads occupy ${work.payloadBytes} bytes, above the ${MAX_LOAD_COMMAND_BYTES}-byte aggregate limit`,
);
@@ -866,13 +865,13 @@ const readLazyLoadDylibInfo = async (
command.dataOffset > length ||
command.dataSize > length - command.dataOffset
)
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${command.index} LC_LAZY_LOAD_DYLIB_INFO payload extends beyond the Mach-O slice`,
);
const fileOffset = base + command.dataOffset;
if (!Number.isSafeInteger(fileOffset))
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${command.index} LC_LAZY_LOAD_DYLIB_INFO payload offset is not a safe integer`,
);
@@ -907,17 +906,17 @@ const decodeLazyLoadDylibInfoPayload = (
const symbolCount = view.getUint32(16, true);
const symbolArrayOffset = view.getUint32(20, true);
if (BigInt(flagImageOffset) > maxVmOffset)
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${index} LC_LAZY_LOAD_DYLIB_INFO flag image offset 0x${flagImageOffset.toString(16)} is beyond the slice VM range 0x${maxVmOffset.toString(16)}`,
);
if (BigInt(chainStartImageOffset) > maxVmOffset)
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${index} LC_LAZY_LOAD_DYLIB_INFO chain start image offset 0x${chainStartImageOffset.toString(16)} is beyond the slice VM range 0x${maxVmOffset.toString(16)}`,
);
if ((flags & ~LAZY_INFO_MAY_BE_MISSING) !== 0)
- throw new MachoFormatIssue(
+ throw machoIssue(
"unsupported",
`load command ${index} LC_LAZY_LOAD_DYLIB_INFO flags 0x${flags.toString(16)} include unrecognized bits`,
);
@@ -925,7 +924,7 @@ const decodeLazyLoadDylibInfoPayload = (
symbolArrayOffset > payload.byteLength ||
symbolCount > (payload.byteLength - symbolArrayOffset) / 4
)
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${index} LC_LAZY_LOAD_DYLIB_INFO symbol table extends beyond the payload`,
);
@@ -940,7 +939,7 @@ const decodeLazyLoadDylibInfoPayload = (
);
const symbolReferences = work.symbolReferences + symbolCount;
if (symbolReferences > MAX_LAZY_INFO_SYMBOL_REFERENCES)
- throw new MachoFormatIssue(
+ throw machoIssue(
"unsupported",
`LC_LAZY_LOAD_DYLIB_INFO symbol validation exceeds the ${MAX_LAZY_INFO_SYMBOL_REFERENCES}-reference limit`,
);
@@ -973,7 +972,7 @@ const decodeLazyLoadDylibInfoPayload = (
const chargeLazyString = (work: LazyPayloadWork, examined: number): void => {
const occupied = work.stringBytes + examined;
if (occupied > MAX_LOAD_COMMAND_BYTES)
- throw new MachoFormatIssue(
+ throw machoIssue(
"unsupported",
`LC_LAZY_LOAD_DYLIB_INFO string validation occupies ${occupied} bytes, above the ${MAX_LOAD_COMMAND_BYTES}-byte limit`,
);
@@ -995,12 +994,12 @@ const payloadString = (
excludeFinalByte: boolean,
): string => {
if (offset < LAZY_INFO_HEADER_BYTES)
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${index} LC_LAZY_LOAD_DYLIB_INFO ${label} offset ${offset} is inside the payload header`,
);
if (offset >= payload.byteLength)
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${index} LC_LAZY_LOAD_DYLIB_INFO ${label} offset ${offset} is outside the payload`,
);
@@ -1015,7 +1014,7 @@ const payloadString = (
if (cached !== undefined && absolute !== undefined) {
const end = cached.end - fileOffset;
if (end < offset || end >= terminatorLimit)
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${index} LC_LAZY_LOAD_DYLIB_INFO ${label} is unterminated`,
);
@@ -1023,7 +1022,7 @@ const payloadString = (
return cached.text;
}
if (offset >= terminatorLimit)
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${index} LC_LAZY_LOAD_DYLIB_INFO ${label} is unterminated`,
);
@@ -1032,11 +1031,11 @@ const payloadString = (
const end = payload.subarray(0, windowEnd).indexOf(0, offset);
if (end < 0) {
if (windowEnd < terminatorLimit)
- throw new MachoFormatIssue(
+ throw machoIssue(
"unsupported",
`LC_LAZY_LOAD_DYLIB_INFO string validation occupies ${work.stringBytes + (windowEnd - offset) + 1} bytes, above the ${MAX_LOAD_COMMAND_BYTES}-byte limit`,
);
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${index} LC_LAZY_LOAD_DYLIB_INFO ${label} is unterminated`,
);
@@ -1048,7 +1047,7 @@ const payloadString = (
payload.subarray(offset, end),
);
} catch {
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${index} LC_LAZY_LOAD_DYLIB_INFO ${label} is not UTF-8`,
);
@@ -1066,7 +1065,7 @@ const decodeDependency = (
const parsed = readMachoDylibCommandFacts(body, true);
if (!parsed.ok) {
if (parsed.error._tag === "InvalidMachoDylibCommand")
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${index} is too short for a dylib command`,
);
@@ -1111,7 +1110,7 @@ const throwCommandStringIssue = (
: failure.reason === "invalid-offset"
? `load command ${index} has string offset ${failure.offset} outside the command`
: `load command ${index} has an unterminated string`;
- throw new MachoFormatIssue("malformed", reason);
+ throw machoIssue("malformed", reason);
};
const decodeCommandString = (bytes: Uint8Array, index: number): string => {
@@ -1121,7 +1120,7 @@ const decodeCommandString = (bytes: Uint8Array, index: number): string => {
bytes,
);
} catch {
- throw new MachoFormatIssue(
+ throw machoIssue(
"malformed",
`load command ${index} has a string that is not UTF-8`,
);
@@ -1136,7 +1135,7 @@ const readExact = async (
): Promise => {
const bytes = await readAt(offset, length);
if (bytes.byteLength < length)
- throw new MachoFormatIssue("malformed", `${label} is truncated`);
+ throw machoIssue("malformed", `${label} is truncated`);
return bytes;
};
diff --git a/src/artifacts/apple/NibArchive.test.ts b/src/artifacts/apple/NibArchive.test.ts
index d68c6b836c..9545089e02 100644
--- a/src/artifacts/apple/NibArchive.test.ts
+++ b/src/artifacts/apple/NibArchive.test.ts
@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";
import { decodeNibArchive } from "./NibArchive.js";
import { encodeNibArchiveFixture as encodeArchive } from "./NibArchive.fixture.js";
import { InterfaceBuilderDecodeBudgetExceeded } from "./InterfaceBuilderDecodeBudget.js";
+import { ParseFailureError } from "../../domain/parseFailure.js";
const archiveWithOverlappingObjectRanges = (objectCount: number): Buffer => {
const objectRecords = Buffer.alloc(objectCount * 3);
@@ -207,3 +208,34 @@ it("retains repeated serialized collection fields in source order", () => {
UINibEncoderEmptyKey: [{ $nib_object_ref: 2 }, { $nib_object_ref: 1 }],
});
});
+
+it("classifies NIBArchive input faults through ParseFailure", () => {
+ const valid = encodeArchive({
+ classes: ["NSObject"],
+ objects: [{ classIndex: 0, values: { child: { ref: 4 } } }],
+ });
+ const failureOf = (bytes: Buffer): unknown => {
+ try {
+ decodeNibArchive(bytes);
+ } catch (cause: unknown) {
+ return cause;
+ }
+ throw new Error("Expected the NIBArchive to be refused");
+ };
+ const newerVersion = Buffer.from(valid);
+ newerVersion.writeUInt32LE(2, 10);
+ expect(failureOf(newerVersion)).toMatchObject({
+ failure: {
+ kind: "unsupported",
+ format: "nib-archive",
+ undecodedContent: true,
+ },
+ });
+ expect(failureOf(valid)).toBeInstanceOf(ParseFailureError);
+ expect(failureOf(valid)).toMatchObject({ kind: "malformed" });
+ expect(failureOf(valid.subarray(0, valid.length - 1))).toMatchObject({
+ kind: "truncated",
+ });
+ // Intact magic with a header cut short is missing bytes, not bad bytes.
+ expect(failureOf(valid.subarray(0, 20))).toMatchObject({ kind: "truncated" });
+});
diff --git a/src/artifacts/apple/NibArchive.ts b/src/artifacts/apple/NibArchive.ts
index 8cf55a01e4..f7a266b66e 100644
--- a/src/artifacts/apple/NibArchive.ts
+++ b/src/artifacts/apple/NibArchive.ts
@@ -2,6 +2,11 @@ import type { JsonValue } from "../../domain/jsonValue.js";
import { hasNibArchiveSignature } from "../../domain/apple/appleArchiveFormat.js";
import { isInterfaceBuilderConnectionClass } from "../../domain/apple/interfaceBuilderKeyedArchive.js";
import { TextDecoder } from "node:util";
+import {
+ malformedInput,
+ truncatedInput,
+ unsupportedInput,
+} from "../../domain/parseFailure.js";
import {
InterfaceBuilderDecodeBudget,
InterfaceBuilderDecodeBudgetExceeded,
@@ -65,14 +70,18 @@ export const decodeNibArchive = (
bytes: Buffer,
budget = new InterfaceBuilderDecodeBudget(DEFAULT_DECODE_BUDGET_BYTES),
): NibArchiveDocument => {
- if (bytes.length < 50 || !hasNibArchiveSignature(bytes))
- throw new TypeError("NIBArchive magic or header is invalid");
+ if (!hasNibArchiveSignature(bytes))
+ throw malformedInput("nib-archive", "NIBArchive magic is invalid");
+ if (bytes.length < 50)
+ throw truncatedInput("nib-archive", "NIBArchive header is truncated");
const formatVersion = readU32(bytes, 10);
const coderVersion = readU32(bytes, 14);
if (formatVersion !== 1)
- throw new TypeError(
+ throw unsupportedInput(
+ "nib-archive",
`Unsupported NIBArchive format version ${formatVersion}`,
+ { undecodedContent: true },
);
const objectCount = readCount(bytes, 18, "object");
@@ -144,7 +153,8 @@ export const decodeNibArchive = (
typeof value.$nib_object_ref === "number" &&
value.$nib_object_ref >= objectCount
)
- throw new TypeError(
+ throw malformedInput(
+ "nib-archive",
"NIBArchive object reference is outside the object table",
);
}
@@ -238,7 +248,8 @@ const parseObjects = (
valueStart > valueCount ||
countForObject > valueCount - valueStart
)
- throw new TypeError(
+ throw malformedInput(
+ "nib-archive",
`NIBArchive object ${index} references an invalid table range`,
);
output.push({
@@ -248,7 +259,10 @@ const parseObjects = (
});
}
if (cursor.offset > end)
- throw new TypeError("NIBArchive object table overlaps the next table");
+ throw malformedInput(
+ "nib-archive",
+ "NIBArchive object table overlaps the next table",
+ );
return output;
};
@@ -277,7 +291,8 @@ const preflightProjectedFieldCount = (
valueStart > valueCount ||
fieldCount > valueCount - valueStart
)
- throw new TypeError(
+ throw malformedInput(
+ "nib-archive",
`NIBArchive object ${index} references an invalid table range`,
);
projectedFields += fieldCount;
@@ -330,7 +345,8 @@ const parseClasses = (
const length = readVarint(bytes, cursor, end);
const extraCount = readVarint(bytes, cursor, end);
if (extraCount > 16)
- throw new TypeError(
+ throw malformedInput(
+ "nib-archive",
`NIBArchive class ${index} has too many extension values`,
);
ensureRange(
@@ -371,7 +387,8 @@ const parseValues = (
for (let index = 0; index < count; index += 1) {
const keyIndex = readVarint(bytes, cursor, end);
if (keyIndex >= keyCount)
- throw new TypeError(
+ throw malformedInput(
+ "nib-archive",
`NIBArchive value ${index} references an invalid key`,
);
ensureRange(cursor.offset, 1, end, `value ${index} type`);
@@ -388,7 +405,10 @@ const parseValues = (
output.set(index, { key_index: keyIndex, value });
}
if (cursor.offset > end)
- throw new TypeError("NIBArchive value table overlaps the next table");
+ throw malformedInput(
+ "nib-archive",
+ "NIBArchive value table overlaps the next table",
+ );
return output;
};
@@ -490,8 +510,10 @@ const readValue = (
return { $nib_object_ref: objectIndex };
}
default:
- throw new TypeError(
+ throw unsupportedInput(
+ "nib-archive",
`NIBArchive value ${index} has unsupported type ${type}`,
+ { undecodedContent: true },
);
}
};
@@ -541,8 +563,10 @@ const skipValue = (
return;
}
default:
- throw new TypeError(
+ throw unsupportedInput(
+ "nib-archive",
`NIBArchive value ${index} has unsupported type ${type}`,
+ { undecodedContent: true },
);
}
};
@@ -560,7 +584,8 @@ const valueIndexes = (
)
indexes.add(index);
if (indexes.size > total)
- throw new TypeError(
+ throw malformedInput(
+ "nib-archive",
"NIBArchive object value ranges exceed the value table",
);
return indexes;
@@ -569,7 +594,10 @@ const valueIndexes = (
const readCount = (bytes: Buffer, offset: number, label: string): number => {
const count = readU32(bytes, offset);
if (count > bytes.length)
- throw new TypeError(`NIBArchive ${label} count exceeds the archive length`);
+ throw malformedInput(
+ "nib-archive",
+ `NIBArchive ${label} count exceeds the archive length`,
+ );
return count;
};
@@ -581,7 +609,10 @@ const readOffset = (
): number => {
const value = readU32(bytes, offset);
if (value < 50 || value > fileLength)
- throw new TypeError(`NIBArchive ${label} table offset is invalid`);
+ throw malformedInput(
+ "nib-archive",
+ `NIBArchive ${label} table offset is invalid`,
+ );
return value;
};
@@ -602,9 +633,11 @@ const decodeUtf8 = (
bytes.subarray(start, end),
);
} catch (cause: unknown) {
- throw new TypeError(`NIBArchive ${label} is not valid UTF-8`, {
- cause,
- });
+ throw malformedInput(
+ "nib-archive",
+ `NIBArchive ${label} is not valid UTF-8`,
+ { cause },
+ );
}
};
@@ -621,12 +654,18 @@ const readVarint = (
value += (byte & 0x7f) * 2 ** shift;
if ((byte & 0x80) !== 0) {
if (value > 0x7fff_ffff)
- throw new TypeError("NIBArchive variable integer is out of range");
+ throw malformedInput(
+ "nib-archive",
+ "NIBArchive variable integer is out of range",
+ );
return value;
}
shift += 7;
}
- throw new TypeError("NIBArchive variable integer is too long");
+ throw malformedInput(
+ "nib-archive",
+ "NIBArchive variable integer is too long",
+ );
};
const checkedEnd = (
@@ -636,7 +675,10 @@ const checkedEnd = (
label: string,
): number => {
if (!Number.isSafeInteger(length) || length < 0 || start + length > limit)
- throw new TypeError(`NIBArchive ${label} exceeds its table`);
+ throw truncatedInput(
+ "nib-archive",
+ `NIBArchive ${label} exceeds its table`,
+ );
return start + length;
};
@@ -653,7 +695,10 @@ const assertOrderedOffsets = (length: number, offsets: readonly number[]) => {
let previous = 50;
for (const offset of offsets) {
if (offset < previous || offset > length)
- throw new TypeError("NIBArchive table offsets are out of order");
+ throw malformedInput(
+ "nib-archive",
+ "NIBArchive table offsets are out of order",
+ );
previous = offset;
}
};
diff --git a/src/artifacts/apple/PlistScalars.test.ts b/src/artifacts/apple/PlistScalars.test.ts
index 90359fbda9..aa7ed79f72 100644
--- a/src/artifacts/apple/PlistScalars.test.ts
+++ b/src/artifacts/apple/PlistScalars.test.ts
@@ -12,7 +12,7 @@ import {
} from "./PlistScalars.js";
import {
estimateBinaryPlistExpansion,
- PropertyListDecodeBudgetFailure,
+ isPlistDecodeBudgetFailure,
} from "./PropertyListDecodeBudget.js";
const dataObjectWithUnusedOverlappingInteger = (): Buffer => {
@@ -191,6 +191,9 @@ describe("binary plist scalar bounds", () => {
expect(() => estimateBinaryPlistExpansion(malformed, 1024 * 1024)).toThrow(
/date marker/u,
);
+ expect(() => estimateBinaryPlistExpansion(malformed, 1024 * 1024)).toThrow(
+ expect.objectContaining({ kind: "malformed" }),
+ );
});
it.each([
@@ -284,9 +287,22 @@ describe("binary plist UID widths", () => {
const bytes = binaryPlistWithUid(3, 0xabcdefn);
for (const options of [{}, { numberProjection: true }]) {
const plan = estimateBinaryPlistExpansion(bytes, 1024 * 1024, options);
- expect(() =>
- estimateBinaryPlistExpansion(bytes, plan.estimatedBytes - 1, options),
- ).toThrow(PropertyListDecodeBudgetFailure);
+ const refusal = (() => {
+ try {
+ estimateBinaryPlistExpansion(bytes, plan.estimatedBytes - 1, options);
+ return undefined;
+ } catch (cause: unknown) {
+ return cause;
+ }
+ })();
+ expect(isPlistDecodeBudgetFailure(refusal)).toBe(true);
+ expect(refusal).toMatchObject({
+ failure: {
+ kind: "limit",
+ format: "plist",
+ limit: { maximum: plan.estimatedBytes - 1 },
+ },
+ });
}
});
@@ -298,6 +314,22 @@ describe("binary plist UID widths", () => {
expect(() => estimateBinaryPlistExpansion(truncated, 1024)).toThrow(
"binary plist UID object is truncated",
);
+ expect(() => estimateBinaryPlistExpansion(truncated, 1024)).toThrow(
+ expect.objectContaining({
+ failure: expect.objectContaining({
+ kind: "truncated",
+ format: "plist",
+ }),
+ }),
+ );
+
+ // An eight-byte string length with only two bytes before the table.
+ const cutLength = Buffer.alloc(50);
+ cutLength.set([0x5f, 0x13, 0, 0], 8);
+ binaryPlistObjectTable(cutLength, [8], 12);
+ expect(() => estimateBinaryPlistExpansion(cutLength, 1024)).toThrow(
+ expect.objectContaining({ kind: "truncated" }),
+ );
const inexact = binaryPlistWithUid(8, BigInt(Number.MAX_SAFE_INTEGER) + 1n);
expect(() => estimateBinaryPlistExpansion(inexact, 1024)).toThrow(
diff --git a/src/artifacts/apple/PlistScalars.ts b/src/artifacts/apple/PlistScalars.ts
index 64b57ab3b5..fe093cc8c6 100644
--- a/src/artifacts/apple/PlistScalars.ts
+++ b/src/artifacts/apple/PlistScalars.ts
@@ -1,3 +1,8 @@
+import {
+ ParseFailureError,
+ unsupportedInput,
+} from "../../domain/parseFailure.js";
+import { invariantViolation } from "../../domain/internalInvariant.js";
import {
readBinaryPlistLayout,
readBinaryPlistUnsigned64,
@@ -55,16 +60,18 @@ export interface BinaryPlistScalarDecodePlan {
}
/** A binary-plist UID cannot be projected to plist@5's numeric UID value exactly. */
-export class UnsupportedBinaryPlistUidError extends TypeError {
- readonly _tag = "UnsupportedBinaryPlistUidError";
-
+export class UnsupportedBinaryPlistUidError extends ParseFailureError<"unsupported"> {
constructor(
readonly decimalValue: string,
readonly sourceWidth: number,
) {
- super(
- `binary plist UID value ${decimalValue} in ${sourceWidth}-byte encoding exceeds the exact supported range`,
- );
+ super({
+ kind: "unsupported",
+ format: "binary-plist",
+ detail: `binary plist UID value ${decimalValue} in ${sourceWidth}-byte encoding exceeds the exact supported range`,
+ field: "uid",
+ undecodedContent: true,
+ });
this.name = "UnsupportedBinaryPlistUidError";
}
}
@@ -411,7 +418,9 @@ export const decodeBinaryPlistScalars = (
}
const sourceLayoutResult = readBinaryPlistLayout(bytes);
if (!sourceLayoutResult.ok)
- throw new RangeError("binary plist trailer is truncated");
+ throw invariantViolation(
+ "binary plist trailer was not validated by its preflight",
+ );
const sourceLayout = sourceLayoutResult.value;
const sourceReferenceSize = sourceLayout.referenceWidth;
const normalizedReferenceSize =
@@ -475,7 +484,8 @@ const cloneBinaryPlistObjects = (
normalizedOffsetSize ??
binaryPlistCloneOffsetWidth(offsetSize, trailerOffset, replacementLengths);
if (newOffsetSize === undefined)
- throw new RangeError(
+ throw unsupportedInput(
+ "plist",
"binary plist cloned scalar offset exceeds supported width",
);
// Preserve every source offset, including objects after the old table. The
@@ -488,7 +498,8 @@ const cloneBinaryPlistObjects = (
const newTableOffset = cloneStart + cloneBytes;
const newLength = bytes.length + cloneBytes + objectCount * newOffsetSize;
if (!Number.isSafeInteger(newLength))
- throw new RangeError(
+ throw unsupportedInput(
+ "plist",
"binary plist cloned scalar representation is too large",
);
const compatible = Buffer.alloc(newLength);
diff --git a/src/artifacts/apple/PropertyListDecodeBudget.ts b/src/artifacts/apple/PropertyListDecodeBudget.ts
index 0577907aa5..53df121cce 100644
--- a/src/artifacts/apple/PropertyListDecodeBudget.ts
+++ b/src/artifacts/apple/PropertyListDecodeBudget.ts
@@ -4,6 +4,14 @@ import {
} from "./BinaryPlistLayout.js";
import { decodeXmlPlistText } from "../../domain/propertyListXmlText.js";
import { hasBinaryPlistSignature } from "../../domain/apple/appleArchiveFormat.js";
+import { PlistNestingLimitError } from "../../domain/apple/plistValue.js";
+import {
+ decodeLimit,
+ malformedInput,
+ ParseFailureError,
+ truncatedInput,
+ unsupportedInput,
+} from "../../domain/parseFailure.js";
import {
binaryPlistCloneOffsetWidth,
binaryDateRequiresExactSeconds,
@@ -18,21 +26,19 @@ export const preflightPropertyListDecode = (
xmlText?: string,
options: Pick<
BinaryPlistExpansionOptions,
- "numberProjection" | "uidProjection" | "budget" | "fail"
+ "numberProjection" | "uidProjection" | "budget"
> = {},
): PlistDecodePreflight => {
const {
numberProjection = false,
uidProjection = false,
budget = "the property list decode budget",
- fail = propertyListDecodeBudgetFailure,
} = options;
const expansion = hasBinaryPlistSignature(bytes)
? estimateBinaryPlistExpansion(bytes, maxBytes, {
numberProjection,
uidProjection,
budget,
- fail,
})
: {
estimatedBytes: estimateXmlPlistExpansion(
@@ -41,7 +47,6 @@ export const preflightPropertyListDecode = (
xmlText,
numberProjection,
budget,
- fail,
),
datePrecisionOverlapCount: 0,
@@ -56,7 +61,10 @@ export const preflightPropertyListDecode = (
normalizedReferenceSize: 1,
};
if (expansion.estimatedBytes > maxBytes)
- throw fail("expansion", `plist representation exceeds ${budget}`);
+ throw decodeBudgetExceeded(
+ `plist representation exceeds ${budget}`,
+ maxBytes,
+ );
return expansion;
};
@@ -77,7 +85,6 @@ const estimateXmlPlistExpansion = (
xmlText: string | undefined,
numberProjection: boolean,
budget: string,
- fail: (kind: BinaryPlistExpansionFailure, message: string) => Error,
): number => {
const xml = xmlText ?? decodeXmlPlistText(bytes);
// The decoded text and the DOM's copies of its character data.
@@ -91,9 +98,9 @@ const estimateXmlPlistExpansion = (
if (token.internalSubset)
// Only a declaration outside opaque text can introduce an internal
// subset. Brackets in quoted external identifiers are literal text.
- throw fail(
- "expansion",
+ throw decodeBudgetExceeded(
`XML plist internal entity expansion exceeds ${budget}`,
+ maxBytes,
);
if (token.text) estimate += XML_NODE_BYTES;
estimate += token.references * XML_REFERENCE_BYTES;
@@ -219,26 +226,25 @@ function* xmlPreflightTokens(xml: string): Generator<{
/** Deepest binary plist value nesting the reference walk admits. */
export const MAX_BINARY_PLIST_NESTING_DEPTH = 128;
-/** Resource or structural failure found while preflighting a plist. */
-export type BinaryPlistExpansionFailure = "cycle" | "depth" | "expansion";
+/** Limit name of the decoded-representation budget a plist preflight enforces. */
+export const PLIST_DECODE_BYTES_LIMIT = "plist-decode-bytes";
-/** Typed failure for shared plist preflight resource limits. */
-export class PropertyListDecodeBudgetFailure extends Error {
- constructor(
- readonly kind: BinaryPlistExpansionFailure,
- message: string,
- ) {
- super(message);
- this.name = "PropertyListDecodeBudgetFailure";
- }
-}
+/** The decoded representation would exceed the caller's byte budget. */
+const decodeBudgetExceeded = (
+ detail: string,
+ maximum: number,
+): ParseFailureError<"limit"> =>
+ decodeLimit("plist", detail, { name: PLIST_DECODE_BYTES_LIMIT, maximum });
-const propertyListDecodeBudgetFailure = (
- kind: BinaryPlistExpansionFailure,
- message: string,
-): Error => new PropertyListDecodeBudgetFailure(kind, message);
+/** Whether a plist preflight refused the decode for its byte budget. */
+export const isPlistDecodeBudgetFailure = (
+ cause: unknown,
+): cause is ParseFailureError<"limit"> =>
+ cause instanceof ParseFailureError &&
+ cause.failure.kind === "limit" &&
+ cause.failure.limit.name === PLIST_DECODE_BYTES_LIMIT;
-/** How a caller names and reports binary plist expansion failures. */
+/** How a caller names its budget and selects binary plist projection. */
export interface BinaryPlistExpansionOptions {
/** Source-value depth; archive consumers retain the default 128-level allowance. */
readonly maximumDepth?: number;
@@ -248,8 +254,6 @@ export interface BinaryPlistExpansionOptions {
readonly uidProjection?: boolean;
/** Budget named in failure messages. */
readonly budget?: string;
- /** Error for budget, depth, and reference-cycle failures. */
- readonly fail?: (kind: BinaryPlistExpansionFailure, message: string) => Error;
/**
* Structural bounds: "strict" keeps objects and the offset table before the
* trailer; "decoder" follows the decoder's object-table boundary policy
@@ -334,15 +338,16 @@ const findOverlappingScalarOffsets = (
/**
* Validate and budget every expanded source reference before scalar decoding
- * and independent container materialization. Malformed
- * structure throws TypeError; resource and cycle failures use `fail`.
+ * and independent container materialization. Malformed structure throws
+ * TypeError, and a reference cycle a malformed parse failure; a budget throws
+ * a `limit` parse failure ({@link PLIST_DECODE_BYTES_LIMIT}, or the
+ * nesting-depth limit of {@link PlistNestingLimitError}).
*/
export const estimateBinaryPlistExpansion = (
bytes: Buffer,
maxBytes: number,
{
budget = "the property list decode budget",
- fail = propertyListDecodeBudgetFailure,
bounds = "strict",
numberProjection = false,
uidProjection = false,
@@ -350,10 +355,10 @@ export const estimateBinaryPlistExpansion = (
}: BinaryPlistExpansionOptions = {},
): PlistDecodePreflight => {
if (bytes.length < 40)
- throw new TypeError("binary plist trailer is truncated");
+ throw truncatedInput("plist", "binary plist trailer is truncated");
const sourceLayoutResult = readBinaryPlistLayout(bytes);
if (!sourceLayoutResult.ok)
- throw new TypeError("binary plist trailer is truncated");
+ throw truncatedInput("plist", "binary plist trailer is truncated");
const sourceLayout = sourceLayoutResult.value;
const {
trailerOffset: trailer,
@@ -361,7 +366,10 @@ export const estimateBinaryPlistExpansion = (
referenceWidth: referenceSize,
} = sourceLayout;
if (offsetSize < 1 || referenceSize < 1)
- throw new TypeError("binary plist trailer integer sizes are invalid");
+ throw malformedInput(
+ "plist",
+ "binary plist trailer integer sizes are invalid",
+ );
const safeDeclaration = (value: bigint): number =>
value <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(value) : -1;
const readInteger = (offset: number, size: number): number => {
@@ -382,12 +390,18 @@ export const estimateBinaryPlistExpansion = (
!Number.isSafeInteger(offsetTable + objectCount * offsetSize) ||
offsetTable + objectCount * offsetSize > tableEnd
)
- throw new TypeError("binary plist trailer or object table is invalid");
+ throw malformedInput(
+ "plist",
+ "binary plist trailer or object table is invalid",
+ );
if (
(offsetSize < 8 && offsetTable >= 2 ** (offsetSize * 8)) ||
(referenceSize < 8 && objectCount >= 2 ** (referenceSize * 8))
)
- throw new TypeError("binary plist table width cannot address its contents");
+ throw malformedInput(
+ "plist",
+ "binary plist table width cannot address its contents",
+ );
const normalizedReferenceSize =
[1, 2, 4, 8].includes(referenceSize) &&
(referenceSize === 8 || objectCount < 2 ** (referenceSize * 8))
@@ -396,7 +410,10 @@ export const estimateBinaryPlistExpansion = (
(width) => width === 8 || objectCount < 2 ** (width * 8),
);
if (normalizedReferenceSize === undefined)
- throw new TypeError("binary plist object reference count is invalid");
+ throw malformedInput(
+ "plist",
+ "binary plist object reference count is invalid",
+ );
// Reserve source container/reference facts, scalar indexing, and the scalar
// array/table overhead; projection also retains numeric/UID source metadata.
const objectBytes = numberProjection || uidProjection ? 512 : 256;
@@ -407,7 +424,10 @@ export const estimateBinaryPlistExpansion = (
let estimate =
bytes.length * (numberProjection ? 4 : 3) + objectCount * objectBytes;
if (estimate > maxBytes)
- throw fail("expansion", `binary plist object table exceeds ${budget}`);
+ throw decodeBudgetExceeded(
+ `binary plist object table exceeds ${budget}`,
+ maxBytes,
+ );
const active = new Set();
const pending: Array<{
@@ -431,23 +451,39 @@ export const estimateBinaryPlistExpansion = (
if (prior !== undefined) return prior;
const offset = safeDeclaration(sourceLayout.objectOffset(object));
if (offset < 8 || offset >= objectsEnd)
- throw new TypeError("binary plist object offset is invalid");
+ throw malformedInput("plist", "binary plist object offset is invalid");
const marker = bytes[offset] ?? 0;
const type = marker >> 4;
if (type !== 5 && type !== 6)
- throw new TypeError("binary plist dictionary key is not a string");
+ throw malformedInput(
+ "plist",
+ "binary plist dictionary key is not a string",
+ );
let size = marker & 0x0f;
let cursor = offset + 1;
if (size === 15) {
const extended = bytes[cursor] ?? 0;
if (extended >> 4 !== 1 || (extended & 15) > 3)
- throw new TypeError("binary plist extended object size is invalid");
+ throw malformedInput(
+ "plist",
+ "binary plist extended object size is invalid",
+ );
const width = 1 << (extended & 15);
size = readInteger(cursor + 1, width);
cursor += 1 + width;
+ if (cursor > objectsEnd)
+ throw truncatedInput(
+ "plist",
+ "binary plist extended object size is truncated",
+ );
+ if (size < 0)
+ throw malformedInput(
+ "plist",
+ "binary plist extended object size is invalid",
+ );
}
- if (size < 0 || cursor + size * (type === 6 ? 2 : 1) > objectsEnd)
- throw new TypeError("binary plist scalar object is truncated");
+ if (cursor + size * (type === 6 ? 2 : 1) > objectsEnd)
+ throw truncatedInput("plist", "binary plist scalar object is truncated");
let key = "";
for (let index = 0; index < size; index += 1)
key += String.fromCharCode(
@@ -482,18 +518,21 @@ export const estimateBinaryPlistExpansion = (
}
pendingObjectCount -= 1;
if (entry.depth > maximumDepth)
- throw fail("depth", `binary plist nesting exceeds ${budget}`);
+ throw new PlistNestingLimitError(maximumDepth);
if (active.has(entry.object))
- throw fail("cycle", `binary plist reference cycle exceeds ${budget}`);
+ throw malformedInput(
+ "plist",
+ "binary plist object references form a cycle, which a property list cannot represent",
+ );
estimate += expandedNodeBytes;
if (estimate > maxBytes)
- throw fail(
- "expansion",
+ throw decodeBudgetExceeded(
`binary plist reference expansion exceeds ${budget}`,
+ maxBytes,
);
const offset = safeDeclaration(sourceLayout.objectOffset(entry.object));
if (offset < 8 || offset >= objectsEnd)
- throw new TypeError("binary plist object offset is invalid");
+ throw malformedInput("plist", "binary plist object offset is invalid");
if (numberProjection) reachableObjectOffsets.add(offset);
const marker = bytes[offset] ?? 0;
const type = marker >> 4;
@@ -503,17 +542,21 @@ export const estimateBinaryPlistExpansion = (
uid: type === 8,
});
if (entry.dictionaryKey && type !== 5 && type !== 6)
- throw new TypeError("binary plist dictionary key is not a string");
+ throw malformedInput(
+ "plist",
+ "binary plist dictionary key is not a string",
+ );
if (type === 3) {
if (marker !== 0x33)
- throw new TypeError(
+ throw malformedInput(
+ "plist",
`binary plist date marker 0x${marker.toString(16)} is invalid`,
);
// The offset table and trailer are not part of an encoded object. Keep
// this scalar boundary even when compatibility mode follows decoder
// bounds for other object and reference checks.
if (offset + 9 > offsetTable)
- throw new TypeError("binary plist date object is truncated");
+ throw truncatedInput("plist", "binary plist date object is truncated");
if (numberProjection) {
reachableDateOffsets.add(offset);
reachableDateOccurrences.push(offset);
@@ -523,7 +566,7 @@ export const estimateBinaryPlistExpansion = (
if (type === 8) {
const uidWidth = (marker & 0x0f) + 1;
if (offset + 1 + uidWidth > objectsEnd)
- throw new TypeError("binary plist UID object is truncated");
+ throw truncatedInput("plist", "binary plist UID object is truncated");
const normalizedWidth = binaryPlistUidNormalizationWidth(bytes, offset);
if (normalizedWidth !== undefined)
uidWidthsToNormalize.set(offset, normalizedWidth);
@@ -532,12 +575,15 @@ export const estimateBinaryPlistExpansion = (
if (type === 1 || type === 2) {
const info = marker & 0x0f;
if (type === 1 && info > 4)
- throw new TypeError("binary plist integer width is invalid");
+ throw malformedInput("plist", "binary plist integer width is invalid");
if (type === 2 && info !== 2 && info !== 3)
- throw new TypeError("binary plist real width is invalid");
+ throw malformedInput("plist", "binary plist real width is invalid");
const width = 1 << info;
if (offset + 1 + width > offsetTable)
- throw new TypeError("binary plist numeric scalar is truncated");
+ throw truncatedInput(
+ "plist",
+ "binary plist numeric scalar is truncated",
+ );
if (numberProjection) {
reachableNumericOffsets.add(offset);
if (type === 1 && width === 16) reachableWideIntegerOffsets.add(offset);
@@ -549,23 +595,39 @@ export const estimateBinaryPlistExpansion = (
if (size === 0x0f && type !== 0 && type !== 8) {
const extMarker = bytes[cursor] ?? 0;
if (extMarker >> 4 !== 1 || (extMarker & 0x0f) > 3)
- throw new TypeError("binary plist extended object size is invalid");
+ throw malformedInput(
+ "plist",
+ "binary plist extended object size is invalid",
+ );
cursor += 1;
const integerSize = 1 << (extMarker & 0x0f);
size = readInteger(cursor, integerSize);
cursor += integerSize;
- if (size < 0 || cursor > objectsEnd)
- throw new TypeError("binary plist extended object size is invalid");
+ // The length record crossing the object area is missing bytes; a
+ // complete record whose value is not a safe length is invalid.
+ if (cursor > objectsEnd)
+ throw truncatedInput(
+ "plist",
+ "binary plist extended object size is truncated",
+ );
+ if (size < 0)
+ throw malformedInput(
+ "plist",
+ "binary plist extended object size is invalid",
+ );
}
if (type === 4 || type === 5 || type === 6) {
const byteLength = type === 6 ? size * 2 : size;
if (cursor + byteLength > objectsEnd)
- throw new TypeError("binary plist scalar object is truncated");
+ throw truncatedInput(
+ "plist",
+ "binary plist scalar object is truncated",
+ );
estimate += type === 4 ? size + 4 * Math.ceil(size / 3) : byteLength * 2;
if (estimate > maxBytes)
- throw fail(
- "expansion",
+ throw decodeBudgetExceeded(
`binary plist scalar expansion exceeds ${budget}`,
+ maxBytes,
);
continue;
}
@@ -573,14 +635,17 @@ export const estimateBinaryPlistExpansion = (
const childCount = type === 13 ? size * 2 : size;
const refsEnd = cursor + childCount * referenceSize;
if (!Number.isSafeInteger(refsEnd) || refsEnd > objectsEnd)
- throw new TypeError("binary plist reference table is truncated");
+ throw truncatedInput(
+ "plist",
+ "binary plist reference table is truncated",
+ );
const availableNodes = Math.floor(
(maxBytes - estimate) / expandedNodeBytes,
);
if (childCount > availableNodes - pendingObjectCount)
- throw fail(
- "expansion",
+ throw decodeBudgetExceeded(
`binary plist reference expansion exceeds ${budget}`,
+ maxBytes,
);
const references = Array.from({ length: childCount }, (_, index) => {
const reference = readInteger(
@@ -588,7 +653,7 @@ export const estimateBinaryPlistExpansion = (
referenceSize,
);
if (reference < 0 || reference >= objectCount)
- throw new TypeError("binary plist reference is invalid");
+ throw malformedInput("plist", "binary plist reference is invalid");
return reference;
});
if (!sourceContainers.has(entry.object))
@@ -638,7 +703,10 @@ export const estimateBinaryPlistExpansion = (
const cloneLength =
headerLength + references.length * normalizedReferenceSize;
if (!Number.isSafeInteger(cloneLength))
- throw new TypeError("binary plist reference table is too large");
+ throw unsupportedInput(
+ "plist",
+ "binary plist reference table is too large",
+ );
return cloneLength;
},
);
@@ -651,7 +719,10 @@ export const estimateBinaryPlistExpansion = (
cloneLengths,
);
if (width === undefined)
- throw new TypeError("binary plist object offset exceeds supported width");
+ throw unsupportedInput(
+ "plist",
+ "binary plist object offset exceeds supported width",
+ );
return width;
};
if (!numberProjection) {
@@ -668,9 +739,9 @@ export const estimateBinaryPlistExpansion = (
const cloneBytes = cloneLengths.reduce((sum, length) => sum + length, 0);
estimate += 2 * (cloneBytes + objectCount * normalizedOffsetSize);
if (estimate > maxBytes)
- throw fail(
- "expansion",
+ throw decodeBudgetExceeded(
`binary plist UID-copy expansion exceeds ${budget}`,
+ maxBytes,
);
}
return {
@@ -743,9 +814,9 @@ export const estimateBinaryPlistExpansion = (
const cloneBytes = cloneLengths.reduce((sum, length) => sum + length, 0);
estimate += 2 * (cloneBytes + objectCount * normalizedOffsetSize);
if (estimate > maxBytes)
- throw fail(
- "expansion",
+ throw decodeBudgetExceeded(
`binary plist scalar-copy expansion exceeds ${budget}`,
+ maxBytes,
);
}
const precisionUnknownOffsets = new Set(precisionUnknownDateOffsets);
diff --git a/src/browser/WebSourceMapFetcher.test.ts b/src/browser/WebSourceMapFetcher.test.ts
index 8f15c7e5d9..d2fb42303a 100644
--- a/src/browser/WebSourceMapFetcher.test.ts
+++ b/src/browser/WebSourceMapFetcher.test.ts
@@ -20,6 +20,26 @@ const request = {
fetchUrl: "https://app.example.test/app.js.map",
};
+it("reports a source map that is not UTF-8 as invalid with its response identity", async () => {
+ const result = await fetchWebSourceMapsOk(
+ [request],
+ { ...input, allowed_origins: [new URL(request.fetchUrl).origin] },
+ undefined,
+ { fetch: async () => new Response(Buffer.from([0x7b, 0xff, 0x7d])) },
+ );
+
+ expect(result.items[0]).toMatchObject({
+ status: "invalid",
+ limitation: expect.stringMatching(
+ /^Source-map response is not valid UTF-8\. Response text was not retained/u,
+ ),
+ response_identity: {
+ bytes: 3,
+ representation: "fetch-response-body-bytes",
+ },
+ });
+});
+
it("reports an empty selected request set without starting fetch work", async () => {
const result = await fetchWebSourceMapsOk([], input, undefined, {
fetch: async () => {
diff --git a/src/browser/WebSourceMapFetcher.ts b/src/browser/WebSourceMapFetcher.ts
index 11fb0f7d76..f75e0ac0d7 100644
--- a/src/browser/WebSourceMapFetcher.ts
+++ b/src/browser/WebSourceMapFetcher.ts
@@ -48,7 +48,10 @@ import {
sourceMapLimitFailure,
type SourceMapLeaf,
} from "../javascript/sourceMaps/SourceMapFormat.js";
-import type { ParseFailureError } from "../domain/parseFailure.js";
+import {
+ malformedInput,
+ type ParseFailureError,
+} from "../domain/parseFailure.js";
import { selectedBrowserDeadlineMs } from "../domain/browserDeadline.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
@@ -323,13 +326,6 @@ class SourceMapSizeLimitError extends Error {
}
}
-class SourceMapEncodingError extends Error {
- constructor(readonly responseIdentity: ResponseIdentity) {
- super("Source-map response is not valid UTF-8.");
- this.name = "SourceMapEncodingError";
- }
-}
-
class SourceMapRedirectLocationError extends Error {
constructor(url: string, location: string) {
super(
@@ -669,9 +665,17 @@ const fetchOne = async (
fetchedUrl,
);
completedResponseIdentity = body.responseIdentity;
+ if (!body.text.ok)
+ return emptySourceMapItem(
+ request,
+ "invalid",
+ body.text.error.message,
+ effectiveUrl,
+ body.responseIdentity,
+ );
return normalizeSourceMap(
request,
- body.text,
+ body.text.value,
body.responseIdentity,
fetchedUrl,
{
@@ -713,14 +717,6 @@ const fetchOne = async (
!(signal.reason instanceof SourceMapDeadlineError)
)
throw cause;
- if (cause instanceof SourceMapEncodingError)
- return emptySourceMapItem(
- request,
- "invalid",
- cause.message,
- effectiveUrl,
- cause.responseIdentity,
- );
return emptySourceMapItem(
request,
"fetch_failed",
@@ -815,10 +811,14 @@ const readBoundedText = async (
maxBytes: number,
signal: AbortSignal | undefined,
resource: string,
-): Promise<{ text: string; responseIdentity: ResponseIdentity }> => {
+): Promise<{
+ /** The UTF-8 text, or why the bytes are not UTF-8. */
+ text: Result>;
+ responseIdentity: ResponseIdentity;
+}> => {
if (response.body === null)
return {
- text: "",
+ text: ok(""),
responseIdentity: {
sha256: createHash("sha256").digest("hex"),
bytes: 0,
@@ -911,13 +911,24 @@ const readBoundedText = async (
};
try {
return {
- text: new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(
- joined,
+ text: ok(
+ new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(
+ joined,
+ ),
+ ),
+ responseIdentity,
+ };
+ } catch (cause: unknown) {
+ return {
+ text: err(
+ malformedInput(
+ "source-map",
+ "Source-map response is not valid UTF-8.",
+ { cause },
+ ),
),
responseIdentity,
};
- } catch {
- throw new SourceMapEncodingError(responseIdentity);
}
};
diff --git a/src/browser/assets/WebArtifactReads.ts b/src/browser/assets/WebArtifactReads.ts
index ed331b3885..496009a40b 100644
--- a/src/browser/assets/WebArtifactReads.ts
+++ b/src/browser/assets/WebArtifactReads.ts
@@ -28,6 +28,10 @@ import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js";
import { safeParseJson } from "../../domain/safeJson.js";
+import {
+ malformedInput,
+ ParseFailureError,
+} from "../../domain/parseFailure.js";
/** The selected artifact and input field owning a reader failure. */
export interface WebArtifactReadContext {
@@ -40,8 +44,8 @@ export interface WebArtifactReadContext {
readonly limitRecovery?: string;
}
-/** A malformed producer document, distinct from host I/O failures. */
-export class WebArtifactFormatFailure extends Error {}
+/** The ParseFailure format of a captured web artifact document. */
+const WEB_ARTIFACT_FORMAT = "captured-web-artifact";
/** Decode exact UTF-8 content, preserving a BOM for digest verification. */
export const decodeWebArtifact = (bytes: Buffer): string => {
@@ -50,7 +54,8 @@ export const decodeWebArtifact = (bytes: Buffer): string => {
bytes,
);
} catch (cause: unknown) {
- throw new WebArtifactFormatFailure(
+ throw malformedInput(
+ WEB_ARTIFACT_FORMAT,
"Selected artifact is not valid UTF-8.",
{ cause },
);
@@ -114,7 +119,7 @@ export class WebArtifactAcquisition {
) {
const data = await this.read(role, path, maximumBytes, signal, scope);
const value = safeParseJson(decodeWebArtifact(data.bytes));
- if (!value.ok) throw new WebArtifactFormatFailure(value.error);
+ if (!value.ok) throw malformedInput(WEB_ARTIFACT_FORMAT, value.error);
return { ...data, value: value.value };
}
@@ -225,20 +230,27 @@ const webArtifactPrimaryError = (
`${context.targetPath}: ${cause.code}: ${cause.message}`,
{ cause },
);
- if (!context.callerSelected && cause instanceof WebArtifactFormatFailure)
+ // A malformed producer document, distinct from host I/O failures.
+ const malformed =
+ cause instanceof ParseFailureError && cause.kind === "malformed"
+ ? cause
+ : undefined;
+ if (!context.callerSelected && malformed !== undefined)
return new ArtifactOperationError(
context.operation,
"format",
undefined,
- `${context.targetPath}: ${cause.message}`,
+ `${context.targetPath}: ${malformed.message}`,
{ cause },
);
- if (cause instanceof WebArtifactFormatFailure || cause instanceof z.ZodError)
+ const invalid =
+ malformed ?? (cause instanceof z.ZodError ? cause : undefined);
+ if (invalid !== undefined)
return new AnalysisInputError(context.operation, { cause }, [
{
path: context.field,
reason: "invalid_format",
- message: `${context.targetPath}: ${cause.message}`,
+ message: `${context.targetPath}: ${invalid.message}`,
},
]);
return new ProviderAdapterError("captured-web-artifacts", context.operation, {
diff --git a/src/browser/history/SazMetadata.ts b/src/browser/history/SazMetadata.ts
index fd0025fda5..2a2a86ce3e 100644
--- a/src/browser/history/SazMetadata.ts
+++ b/src/browser/history/SazMetadata.ts
@@ -47,8 +47,8 @@ export const decodeSazMetadata = (bytes: Buffer): JsonValue => {
});
if (!parsed.ok)
throw new CaptureFormatError(
- parsed.error.reason === "doctype" ? "unsupported" : "malformed",
- parsed.error.reason === "doctype"
+ parsed.error.kind === "unsupported" ? "unsupported" : "malformed",
+ parsed.error.kind === "unsupported"
? "SAZ metadata DTDs are unsupported."
: "SAZ metadata is not well-formed XML.",
"",
diff --git a/src/domain/apple/interfaceBuilderKeyedArchive.ts b/src/domain/apple/interfaceBuilderKeyedArchive.ts
index 12f5bdd6e1..0a70a2365a 100644
--- a/src/domain/apple/interfaceBuilderKeyedArchive.ts
+++ b/src/domain/apple/interfaceBuilderKeyedArchive.ts
@@ -2,6 +2,7 @@ import { plistUidValue } from "./plistUid.js";
import { z } from "zod";
import { jsonObjectSchema, jsonValueSchema } from "../jsonValue.js";
+import { malformedInput } from "../parseFailure.js";
const objectNode = z.strictObject({
id: z.string().min(1),
@@ -92,7 +93,8 @@ export const requireInterfaceBuilderArchive = (value: unknown): void => {
)
)
return;
- throw new TypeError(
+ throw malformedInput(
+ "interface-builder-archive",
"Property list is not a recognized Interface Builder archive",
);
};
diff --git a/src/domain/apple/keyedArchive.test.ts b/src/domain/apple/keyedArchive.test.ts
index b50ba3938c..a4da35bb5d 100644
--- a/src/domain/apple/keyedArchive.test.ts
+++ b/src/domain/apple/keyedArchive.test.ts
@@ -114,7 +114,15 @@ describe("projectKeyedArchive root reference projection", () => {
},
{ offset: 0, limit: 1 },
),
- ).toThrow(RangeError);
+ ).toThrow(
+ expect.objectContaining({
+ failure: expect.objectContaining({
+ kind: "limit",
+ format: "keyed-archive",
+ limit: { name: "keyed-archive-values-per-object", maximum: 200_000 },
+ }),
+ }),
+ );
});
});
diff --git a/src/domain/apple/keyedArchive.ts b/src/domain/apple/keyedArchive.ts
index 162e16c955..4bc08d7f00 100644
--- a/src/domain/apple/keyedArchive.ts
+++ b/src/domain/apple/keyedArchive.ts
@@ -8,21 +8,31 @@ import {
} from "../jsonValue.js";
import { localPathStringSchema } from "../localPath.js";
import { plistUidValue } from "./plistUid.js";
+import {
+ decodeLimit,
+ malformedInput,
+ ParseFailureError,
+} from "../parseFailure.js";
import { projectPlistValue } from "./plistValue.js";
/**
* The selected file is intact but is another kind of file, so another tool
* applies. A malformed NSKeyedArchiver archive is not this error.
*/
-export class KeyedArchiveKindError extends TypeError {
+export class KeyedArchiveKindError extends ParseFailureError<"unsupported"> {
override readonly name = "KeyedArchiveKindError";
constructor(
message: string,
/** What the selected file is instead. */
- readonly kind: "nib-archive" | "property-list",
+ readonly fileKind: "nib-archive" | "property-list",
) {
- super(message);
+ super({
+ kind: "unsupported",
+ format: "keyed-archive",
+ detail: message,
+ undecodedContent: false,
+ });
}
}
@@ -109,6 +119,12 @@ const archiverMismatch = (
: "its $archiver is not a string";
};
+const KEYED_ARCHIVE_FORMAT = "keyed-archive";
+/** Decode allowances for one archive; this release has no runtime override. */
+const MAX_OBJECT_TABLE_ENTRIES = 200_000;
+const MAX_VALUES_PER_SCAN = 200_000;
+const MAX_REFERENCE_EDGES = 200_000;
+
/** Interpret decoded Foundation values without instantiating archive classes. */
export const projectKeyedArchive = (
value: unknown,
@@ -127,13 +143,30 @@ export const projectKeyedArchive = (
"property-list",
);
if (!Array.isArray(archive.$objects))
- throw new TypeError("Expected NSKeyedArchiver with an $objects array");
+ throw malformedInput(
+ KEYED_ARCHIVE_FORMAT,
+ "Expected NSKeyedArchiver with an $objects array",
+ { field: "$objects" },
+ );
const table = archive.$objects;
- if (table.length > 200_000)
- throw new RangeError("Archive exceeds 200000 object-table entries");
+ if (table.length > MAX_OBJECT_TABLE_ENTRIES)
+ throw decodeLimit(
+ KEYED_ARCHIVE_FORMAT,
+ `Archive exceeds ${String(MAX_OBJECT_TABLE_ENTRIES)} object-table entries`,
+ {
+ name: "keyed-archive-object-table-entries",
+ maximum: MAX_OBJECT_TABLE_ENTRIES,
+ },
+ );
const top = record(archive.$top, wrappedScalars);
if (top === undefined || Object.keys(top).length === 0)
- throw new TypeError("Keyed archive has no $top roots");
+ throw malformedInput(
+ KEYED_ARCHIVE_FORMAT,
+ "Keyed archive has no $top roots",
+ {
+ field: "$top",
+ },
+ );
if (selection.root !== undefined && !Object.hasOwn(top, selection.root))
throw new AnalysisInputError("inspect_keyed_archive", undefined, [
{
@@ -149,6 +182,9 @@ export const projectKeyedArchive = (
: { [selection.root]: top[selection.root] ?? null };
const references: z.infer[] = [];
type Pending = { value: JsonValue; path: (string | number)[] };
+ // Nesting needs no bound here: projectPlistValue above refuses the whole
+ // archive past MAX_PLIST_DEPTH, and every scanned value sits at least two
+ // levels below the archive root ($top or $objects, then its key or index).
// `initial` is popped from the end, so callers list it in reverse order.
const scan = (source: number | null, initial: Pending[]) => {
const pending = initial;
@@ -156,10 +192,16 @@ export const projectKeyedArchive = (
while (pending.length > 0) {
const item = pending.pop();
if (item === undefined) break;
- if (++visited > 200_000 || item.path.length > 128)
- throw new RangeError(
- "Archive exceeds 200000 values per object or 128 nesting levels",
+ if (++visited > MAX_VALUES_PER_SCAN)
+ throw decodeLimit(
+ KEYED_ARCHIVE_FORMAT,
+ `Archive exceeds ${String(MAX_VALUES_PER_SCAN)} values per object`,
+ {
+ name: "keyed-archive-values-per-object",
+ maximum: MAX_VALUES_PER_SCAN,
+ },
);
+
const target = uid(item.value, wrappedScalars);
if (target !== undefined) {
const index =
@@ -193,8 +235,15 @@ export const projectKeyedArchive = (
pending.push({ value: child, path: [...item.path, key] });
}
}
- if (references.length > 200_000)
- throw new RangeError("Archive exceeds 200000 reference edges");
+ if (references.length > MAX_REFERENCE_EDGES)
+ throw decodeLimit(
+ KEYED_ARCHIVE_FORMAT,
+ `Archive exceeds ${String(MAX_REFERENCE_EDGES)} reference edges`,
+ {
+ name: "keyed-archive-reference-edges",
+ maximum: MAX_REFERENCE_EDGES,
+ },
+ );
}
};
// Root names belong to the `$top` map, not to the encoded value. Scanning
diff --git a/src/domain/apple/machoDylibCommand.ts b/src/domain/apple/machoDylibCommand.ts
index 08bd30b2f6..b47c988ee7 100644
--- a/src/domain/apple/machoDylibCommand.ts
+++ b/src/domain/apple/machoDylibCommand.ts
@@ -1,3 +1,4 @@
+import { LC } from "./machoLoadCommandCodes.js";
import type { MachoDependency } from "./dylibResolution.js";
import { err, ok, type Result } from "../result.js";
import {
@@ -7,11 +8,11 @@ import {
const DEPENDENCY_COMMANDS: ReadonlyMap =
new Map([
- [0xc, "LC_LOAD_DYLIB"],
- [0x80000018, "LC_LOAD_WEAK_DYLIB"],
- [0x8000001f, "LC_REEXPORT_DYLIB"],
- [0x20, "LC_LAZY_LOAD_DYLIB"],
- [0x80000023, "LC_LOAD_UPWARD_DYLIB"],
+ [LC.LOAD_DYLIB, "LC_LOAD_DYLIB"],
+ [LC.LOAD_WEAK_DYLIB, "LC_LOAD_WEAK_DYLIB"],
+ [LC.REEXPORT_DYLIB, "LC_REEXPORT_DYLIB"],
+ [LC.LAZY_LOAD_DYLIB, "LC_LAZY_LOAD_DYLIB"],
+ [LC.LOAD_UPWARD_DYLIB, "LC_LOAD_UPWARD_DYLIB"],
]);
/** Dependency order follows command order; LC_ID_DYLIB does not consume an ordinal. */
diff --git a/src/domain/apple/machoLoadCommandCodes.ts b/src/domain/apple/machoLoadCommandCodes.ts
index e92697a287..e3498601a5 100644
--- a/src/domain/apple/machoLoadCommandCodes.ts
+++ b/src/domain/apple/machoLoadCommandCodes.ts
@@ -1,3 +1,6 @@
+/** loader.h `LC_REQ_DYLD`: dyld must understand a command carrying this bit. */
+export const LC_REQ_DYLD = 0x80000000;
+
/**
* Mach-O load-command codes from ``, keyed by their header
* names. This is the one table of these values; parsers and projections import
diff --git a/src/domain/apple/machoLoadCommands.ts b/src/domain/apple/machoLoadCommands.ts
index 571a407c1b..1605f427db 100644
--- a/src/domain/apple/machoLoadCommands.ts
+++ b/src/domain/apple/machoLoadCommands.ts
@@ -144,10 +144,10 @@ export class MachoLoadCommandCursor {
// Fields with fixed uint32 layouts in mach-o/loader.h. This table is the single
// owner of those layouts; consumers read decoded fields rather than offsets.
const FIXED_WORD_FIELDS: ReadonlyMap = new Map([
- [0x2, ["symoff", "nsyms", "stroff", "strsize"]],
- [0x3, ["offset", "size"]],
+ [LC.SYMTAB, ["symoff", "nsyms", "stroff", "strsize"]],
+ [LC.SYMSEG, ["offset", "size"]],
[
- 0xb,
+ LC.DYSYMTAB,
[
"ilocalsym",
"nlocalsym",
@@ -169,13 +169,13 @@ const FIXED_WORD_FIELDS: ReadonlyMap = new Map([
"nlocrel",
],
],
- [0x16, ["offset", "nhints"]],
- [0x17, ["cksum"]],
- [0x1d, ["dataoff", "datasize"]],
- [0x1e, ["dataoff", "datasize"]],
- [0x21, ["cryptoff", "cryptsize", "cryptid"]],
+ [LC.TWOLEVEL_HINTS, ["offset", "nhints"]],
+ [LC.PREBIND_CKSUM, ["cksum"]],
+ [LC.CODE_SIGNATURE, ["dataoff", "datasize"]],
+ [LC.SEGMENT_SPLIT_INFO, ["dataoff", "datasize"]],
+ [LC.ENCRYPTION_INFO, ["cryptoff", "cryptsize", "cryptid"]],
[
- 0x22,
+ LC.DYLD_INFO,
[
"rebase_off",
"rebase_size",
@@ -190,7 +190,7 @@ const FIXED_WORD_FIELDS: ReadonlyMap = new Map([
],
],
[
- 0x80000022,
+ LC.DYLD_INFO_ONLY,
[
"rebase_off",
"rebase_size",
@@ -204,16 +204,16 @@ const FIXED_WORD_FIELDS: ReadonlyMap = new Map([
"export_size",
],
],
- [0x26, ["dataoff", "datasize"]],
- [0x29, ["dataoff", "datasize"]],
- [0x2b, ["dataoff", "datasize"]],
- [0x2c, ["cryptoff", "cryptsize", "cryptid", "pad"]],
- [0x2e, ["dataoff", "datasize"]],
- [0x80000033, ["dataoff", "datasize"]],
- [0x80000034, ["dataoff", "datasize"]],
- [0x36, ["dataoff", "datasize"]],
- [0x37, ["dataoff", "datasize"]],
- [0x38, ["dataoff", "datasize"]],
+ [LC.FUNCTION_STARTS, ["dataoff", "datasize"]],
+ [LC.DATA_IN_CODE, ["dataoff", "datasize"]],
+ [LC.DYLIB_CODE_SIGN_DRS, ["dataoff", "datasize"]],
+ [LC.ENCRYPTION_INFO_64, ["cryptoff", "cryptsize", "cryptid", "pad"]],
+ [LC.LINKER_OPTIMIZATION_HINT, ["dataoff", "datasize"]],
+ [LC.DYLD_EXPORTS_TRIE, ["dataoff", "datasize"]],
+ [LC.DYLD_CHAINED_FIXUPS, ["dataoff", "datasize"]],
+ [LC.ATOM_INFO, ["dataoff", "datasize"]],
+ [LC.FUNCTION_VARIANTS, ["dataoff", "datasize"]],
+ [LC.FUNCTION_VARIANT_FIXUPS, ["dataoff", "datasize"]],
]);
/** Names of a command's fixed uint32 fields, or undefined for other layouts. */
diff --git a/src/domain/apple/machoPlatform.ts b/src/domain/apple/machoPlatform.ts
index 997f3c6c63..099626d5b3 100644
--- a/src/domain/apple/machoPlatform.ts
+++ b/src/domain/apple/machoPlatform.ts
@@ -1,6 +1,19 @@
+import { LC } from "./machoLoadCommandCodes.js";
+
/** Device platform encoded by a legacy LC_VERSION_MIN_* command. */
export type MachoVersionMinPlatform = 1 | 2 | 3 | 4;
+/** loader.h LC_VERSION_MIN_* command codes and their device platforms. */
+export const MACHO_VERSION_MIN_PLATFORMS: ReadonlyMap<
+ number,
+ MachoVersionMinPlatform
+> = new Map([
+ [LC.VERSION_MIN_MACOSX, 1],
+ [LC.VERSION_MIN_IPHONEOS, 2],
+ [LC.VERSION_MIN_TVOS, 3],
+ [LC.VERSION_MIN_WATCHOS, 4],
+]);
+
/**
* dyld derives legacy simulator platforms from the CPU type. tvOS uses
* x86_64 only; iOS and watchOS also recognize i386. Explicit LC_BUILD_VERSION
diff --git a/src/domain/apple/plistValue.test.ts b/src/domain/apple/plistValue.test.ts
index 01e9ce026b..bd01d09021 100644
--- a/src/domain/apple/plistValue.test.ts
+++ b/src/domain/apple/plistValue.test.ts
@@ -1,7 +1,8 @@
import { expect, it } from "vitest";
+import { InternalInvariantError } from "../internalInvariant.js";
import { parseBinary } from "plist";
-import { projectPlistValue } from "./plistValue.js";
+import { PlistNestingLimitError, projectPlistValue } from "./plistValue.js";
import { UnknownPlistScalar } from "./unknownPlistScalar.js";
// Binary decoders build dates from seconds; beyond the Date range they are invalid.
@@ -49,7 +50,7 @@ it("rejects excessive plist nesting without exhausting the stack", () => {
cursor.push(next);
cursor = next;
}
- expect(() => projectPlistValue(deep)).toThrow(RangeError);
+ expect(() => projectPlistValue(deep)).toThrow(PlistNestingLimitError);
});
it("reports only generated scalar wrappers and keeps lookalike dictionaries distinct", () => {
@@ -108,7 +109,7 @@ it("rejects accessors, proxies, holes and symbol keys without invoking user code
Array(1),
{ [Symbol("key")]: "value" },
])
- expect(() => projectPlistValue(value)).toThrow(TypeError);
+ expect(() => projectPlistValue(value)).toThrow(InternalInvariantError);
expect(accessed).toBe(0);
});
diff --git a/src/domain/apple/plistValue.ts b/src/domain/apple/plistValue.ts
index cd81093d2e..9429989926 100644
--- a/src/domain/apple/plistValue.ts
+++ b/src/domain/apple/plistValue.ts
@@ -1,7 +1,9 @@
import { types } from "node:util";
import { z } from "zod";
+import { invariantViolation } from "../internalInvariant.js";
import { MAX_JSON_DEPTH, type JsonValue } from "../jsonValue.js";
+import { ParseFailureError } from "../parseFailure.js";
import { copyPlistUidIdentity } from "./plistUid.js";
import { UnknownPlistScalar } from "./unknownPlistScalar.js";
@@ -26,11 +28,15 @@ const plistNestingLimitMessage = (maximumDepth = MAX_PLIST_DEPTH): string =>
`Plist exceeds ${String(maximumDepth)} nesting levels. This release has no runtime override for this ${String(maximumDepth)}-level nesting allowance.`;
/** A source-value depth refusal, distinct from malformed decoder output. */
-export class PlistNestingLimitError extends RangeError {
- readonly _tag = "PlistNestingLimitError";
-
+export class PlistNestingLimitError extends ParseFailureError<"limit"> {
constructor(readonly maximumDepth: number) {
- super(plistNestingLimitMessage(maximumDepth));
+ super({
+ kind: "limit",
+ format: "plist",
+ detail: plistNestingLimitMessage(maximumDepth),
+ limit: { name: "plist-nesting-depth", maximum: maximumDepth },
+ });
+ this.name = "PlistNestingLimitError";
}
}
@@ -96,7 +102,7 @@ export const projectPlistValue = (
const project = (item: unknown, depth: number): JsonValue => {
if (depth > maximumDepth) throw new PlistNestingLimitError(maximumDepth);
if (item !== null && typeof item === "object" && types.isProxy(item))
- throw new TypeError("Plist values cannot contain proxies");
+ throw invariantViolation("Plist values cannot contain proxies");
if (item instanceof Uint8Array)
return scalar({
$plist_type: "data",
@@ -141,7 +147,7 @@ export const projectPlistValue = (
for (let index = 0; index < item.length; index++) {
const descriptor = Object.getOwnPropertyDescriptor(item, index);
if (descriptor === undefined || !Object.hasOwn(descriptor, "value"))
- throw new TypeError(
+ throw invariantViolation(
"Plist arrays require dense data properties without accessors",
);
result.push(project(descriptor.value, depth + 1));
@@ -154,7 +160,7 @@ export const projectPlistValue = (
const descriptor = Object.getOwnPropertyDescriptor(item, key);
if (descriptor?.enumerable !== true) continue;
if (typeof key !== "string" || !Object.hasOwn(descriptor, "value"))
- throw new TypeError(
+ throw invariantViolation(
"Plist dictionary entries require string keys and data properties",
);
entries.push([key, project(descriptor.value, depth + 1)]);
diff --git a/src/domain/internalInvariant.ts b/src/domain/internalInvariant.ts
new file mode 100644
index 0000000000..40f68eddd2
--- /dev/null
+++ b/src/domain/internalInvariant.ts
@@ -0,0 +1,21 @@
+/**
+ * A broken internal assumption: code reached a state its own earlier checks
+ * rule out, such as a plan its preflight should have produced. This is a REA
+ * defect, never evidence about the input, so parsers throw it instead of a
+ * `ParseFailureError`, and no ParseFailure kind (malformed,
+ * truncated, unsupported or limit) describes it.
+ */
+export class InternalInvariantError extends Error {
+ readonly _tag = "InternalInvariantError";
+
+ constructor(message: string, options?: ErrorOptions) {
+ super(message, options);
+ this.name = "InternalInvariantError";
+ }
+}
+
+/** Report a broken internal assumption; `throw invariantViolation(...)`. */
+export const invariantViolation = (
+ message: string,
+ options?: ErrorOptions,
+): InternalInvariantError => new InternalInvariantError(message, options);
diff --git a/src/domain/managed/managedApplicationGraph.ts b/src/domain/managed/managedApplicationGraph.ts
index f812aa36c1..a114b1de2f 100644
--- a/src/domain/managed/managedApplicationGraph.ts
+++ b/src/domain/managed/managedApplicationGraph.ts
@@ -318,6 +318,14 @@ export const readManagedGraphProjection = (
boundaries: boundaries.value,
};
const identity = chooseArtifact(sources);
+ if (identity === undefined) {
+ const missing = "Provide at least one managed inspection result.";
+ return err(
+ new AnalysisInputError(OPERATION, { userMessage: missing }, [
+ { path: [], reason: "invalid_value", message: missing },
+ ]),
+ );
+ }
const mismatch =
artifactMismatch(sources, identity.sha256) ??
moduleIdentityMismatch(sources);
@@ -332,26 +340,17 @@ export const readManagedGraphProjection = (
const OPERATION = "project_managed_application_graph";
-/** Validated graph input still had no artifact source. */
-class ManagedGraphSourceError extends Error {
- readonly _tag = "ManagedGraphSourceError";
- readonly code = "missing_source" as const;
-
- constructor() {
- super("missing_source");
- this.name = "ManagedGraphSourceError";
- }
-}
-
+/** The first supplied source's artifact, or `undefined` when none was supplied. */
const chooseArtifact = (
parsed: ParsedManagedGraphInput,
-): { readonly sha256: string; readonly path: string } => {
+): { readonly sha256: string; readonly path: string } | undefined => {
const result =
parsed.artifact?.result ??
parsed.members?.result ??
parsed.boundaries?.result;
- if (result === undefined) throw new ManagedGraphSourceError();
- return { sha256: result.artifact.sha256, path: result.artifact.path };
+ return result === undefined
+ ? undefined
+ : { sha256: result.artifact.sha256, path: result.artifact.path };
};
const artifactMismatch = (
diff --git a/src/domain/propertyListKeys.test.ts b/src/domain/propertyListKeys.test.ts
index 847709b324..c63eac59d5 100644
--- a/src/domain/propertyListKeys.test.ts
+++ b/src/domain/propertyListKeys.test.ts
@@ -266,9 +266,10 @@ it("rejects XML nesting beyond the projection limit with the limit diagnostic",
failure = cause;
}
expect(failure).toBeInstanceOf(PlistNestingLimitError);
- expect(failure).toBeInstanceOf(RangeError);
expect(failure).toMatchObject({
- _tag: "PlistNestingLimitError",
+ name: "PlistNestingLimitError",
+ kind: "limit",
+ failure: { limit: { name: "plist-nesting-depth", maximum: 128 } },
maximumDepth: 128,
message: expect.stringMatching(/128 nesting levels.*no runtime override/iu),
});
diff --git a/src/domain/propertyListOpenStep.test.ts b/src/domain/propertyListOpenStep.test.ts
index 6bf80f4721..d144f39358 100644
--- a/src/domain/propertyListOpenStep.test.ts
+++ b/src/domain/propertyListOpenStep.test.ts
@@ -56,11 +56,11 @@ it.each(containerRefusals)(
"reports %s before and after a deep suffix",
(text, diagnosis, deep = diagnosis) => {
expect(syntaxFailure(() => decodeOpenStepPropertyList(text))).toMatchObject(
- { _tag: "OpenStepPropertyListError", ...diagnosis },
+ { name: "OpenStepPropertyListError", ...diagnosis },
);
expect(
syntaxFailure(() => decodeOpenStepPropertyList(text + "(".repeat(130))),
- ).toMatchObject({ _tag: "OpenStepPropertyListError", ...deep });
+ ).toMatchObject({ name: "OpenStepPropertyListError", ...deep });
},
);
@@ -75,7 +75,7 @@ it.each([
for (const text of [prefix, prefix + "(".repeat(130)]) {
const pinned = syntaxFailure(() => parseOpenStep(text));
const owned = syntaxFailure(() => decodeOpenStepPropertyList(text));
- expect(owned).not.toHaveProperty("_tag", "OpenStepPropertyListError");
+ expect(owned).not.toHaveProperty("name", "OpenStepPropertyListError");
expect(owned.constructor).toBe(pinned.constructor);
expect(owned.message).toBe(pinned.message);
}
@@ -118,7 +118,7 @@ it.each([
["{ key =", "unexpected_end", 7],
] as const)("reports incomplete %s as %s at %s", (text, code, position) => {
expect(syntaxFailure(() => decodeOpenStepPropertyList(text))).toMatchObject({
- _tag: "OpenStepPropertyListError",
+ name: "OpenStepPropertyListError",
code,
position,
});
@@ -157,7 +157,7 @@ it("does not treat nonterminating whitespace or quoted comment text as line ends
decodeOpenStepPropertyList("// comment without a line end"),
);
expect(error).toMatchObject({
- _tag: "OpenStepPropertyListError",
+ name: "OpenStepPropertyListError",
code: "unexpected_end",
});
});
diff --git a/src/domain/propertyListOpenStep.ts b/src/domain/propertyListOpenStep.ts
index 0c286b9bdc..4ec7b143c6 100644
--- a/src/domain/propertyListOpenStep.ts
+++ b/src/domain/propertyListOpenStep.ts
@@ -1,6 +1,7 @@
import { parseOpenStep } from "plist";
import { MAX_PLIST_DEPTH, PlistNestingLimitError } from "./apple/plistValue.js";
+import { ParseFailureError } from "./parseFailure.js";
import { markPlistDictionary } from "./apple/plistUid.js";
import type { PlistDuplicateKeyCollector } from "./apple/plistDuplicateKeys.js";
@@ -170,14 +171,12 @@ export const decodeOpenStepQuotedString = (token: string): string => {
export type OpenStepPropertyListCode = (typeof OPEN_STEP_SYNTAX_CODES)[number];
/** OpenStep syntax refusal. `code` is the contract; `position` is the source offset. */
-class OpenStepPropertyListError extends Error {
- readonly _tag = "OpenStepPropertyListError";
-
+class OpenStepPropertyListError extends ParseFailureError<"malformed"> {
constructor(
readonly code: OpenStepPropertyListCode,
readonly position?: number,
) {
- super(code);
+ super({ kind: "malformed", format: "openstep-plist", detail: code });
this.name = "OpenStepPropertyListError";
}
}
diff --git a/src/domain/propertyListXmlData.test.ts b/src/domain/propertyListXmlData.test.ts
index a1e0f95d04..2790bfbd43 100644
--- a/src/domain/propertyListXmlData.test.ts
+++ b/src/domain/propertyListXmlData.test.ts
@@ -28,7 +28,7 @@ it.each(["é", "😀", "\u00a0", "\u0085", "\u2028", "\u2029"])(
parseXmlPropertyList(`AQ${character}ID`),
).toThrow(
expect.objectContaining({
- _tag: "XmlPlistDataError",
+ name: "XmlPlistDataError",
reason: "non-ascii",
characterOffset: 2,
}),
diff --git a/src/domain/propertyListXmlData.ts b/src/domain/propertyListXmlData.ts
index 81d5a0a3f3..c96230c5ad 100644
--- a/src/domain/propertyListXmlData.ts
+++ b/src/domain/propertyListXmlData.ts
@@ -1,7 +1,14 @@
+import { ParseFailureError } from "./parseFailure.js";
import { err, ok, type Result } from "./result.js";
-export class XmlPlistDataError extends TypeError {
- readonly _tag = "XmlPlistDataError";
+/**
+ * An XML plist `` literal that cannot be decoded. A missing source
+ * location means this decoder cannot read the literal; the other reasons are
+ * malformed content.
+ */
+export class XmlPlistDataError extends ParseFailureError<
+ "malformed" | "unsupported"
+> {
constructor(
readonly reason:
| "non-ascii"
@@ -11,7 +18,18 @@ export class XmlPlistDataError extends TypeError {
/** UTF-16 offset within the raw data literal, when known. */
readonly characterOffset: number | null = null,
) {
- super(`Cannot decode XML plist : ${reason}`);
+ const detail = `Cannot decode XML plist : ${reason}`;
+ super(
+ reason === "source-location"
+ ? {
+ kind: "unsupported",
+ format: "xml-plist",
+ detail,
+ field: "data",
+ undecodedContent: true,
+ }
+ : { kind: "malformed", format: "xml-plist", detail, field: "data" },
+ );
this.name = "XmlPlistDataError";
}
}
diff --git a/src/domain/propertyListXmlSource.ts b/src/domain/propertyListXmlSource.ts
index 0ed1550649..6cf0e1ab5f 100644
--- a/src/domain/propertyListXmlSource.ts
+++ b/src/domain/propertyListXmlSource.ts
@@ -1,6 +1,7 @@
import type { Document, Node } from "@xmldom/xmldom";
import { MAX_PLIST_DEPTH, PlistNestingLimitError } from "./apple/plistValue.js";
import { err, ok, type Result } from "./result.js";
+import { type ParseFailureError, unsupportedInput } from "./parseFailure.js";
import { parseXmlDocument, XML_LINE_ENDING } from "./xmlDocument.js";
import {
decodeXmlPlistData,
@@ -13,12 +14,13 @@ interface ScalarSpan {
readonly selfClosing: boolean;
}
-class XmlPlistSourceError extends TypeError {
- readonly _tag = "XmlPlistSourceError";
- constructor() {
- super("Cannot locate XML plist scalar in its original source");
- }
-}
+/** The DOM node's reported position does not locate its scalar in the text. */
+const scalarSourceUnlocated = (): ParseFailureError<"unsupported"> =>
+ unsupportedInput(
+ "xml-plist",
+ "Cannot locate XML plist scalar in its original source",
+ { undecodedContent: true },
+ );
/** One source owner binds lexical scalar values to their validated DOM nodes. */
export const readXmlPlistSource = (
@@ -61,11 +63,13 @@ export const readXmlPlistSource = (
const spans = collectXmlPlistScalarSpans(document, readSpan, maximumDepth);
return {
document,
- scalarLiteral(node: Node): Result {
+ scalarLiteral(
+ node: Node,
+ ): Result> {
const span = spans.get(node);
return span?.ok === true
? ok(text.slice(span.value.start, span.value.end))
- : err(new XmlPlistSourceError());
+ : err(scalarSourceUnlocated());
},
dataValue(node: Node): Result {
const span = spans.get(node);
diff --git a/src/domain/propertyListXmlText.test.ts b/src/domain/propertyListXmlText.test.ts
index 3f44cebf1a..ba522d1e53 100644
--- a/src/domain/propertyListXmlText.test.ts
+++ b/src/domain/propertyListXmlText.test.ts
@@ -36,6 +36,7 @@ it.each([
expect.objectContaining({
name: "XmlPlistTextDecodeError",
reason,
+ kind: reason === "unsupported-encoding" ? "unsupported" : "malformed",
} satisfies Partial),
);
});
diff --git a/src/domain/propertyListXmlText.ts b/src/domain/propertyListXmlText.ts
index 3cae8c3b69..a291166295 100644
--- a/src/domain/propertyListXmlText.ts
+++ b/src/domain/propertyListXmlText.ts
@@ -1,6 +1,16 @@
+import { ParseFailureError } from "./parseFailure.js";
import { byteOrderMarkEncoding } from "./textByteOrderMark.js";
-export class XmlPlistTextDecodeError extends TypeError {
+const XML_PLIST_FORMAT = "xml-plist";
+
+/**
+ * XML plist text that cannot be decoded. An unsupported encoding holds text
+ * this decoder cannot read; invalid bytes and a contradicted declaration are
+ * malformed.
+ */
+export class XmlPlistTextDecodeError extends ParseFailureError<
+ "malformed" | "unsupported"
+> {
constructor(
readonly reason:
| "invalid-bytes"
@@ -10,7 +20,17 @@ export class XmlPlistTextDecodeError extends TypeError {
readonly declaredEncoding?: string,
options?: ErrorOptions,
) {
- super(message, options);
+ super(
+ reason === "unsupported-encoding"
+ ? {
+ kind: "unsupported",
+ format: XML_PLIST_FORMAT,
+ detail: message,
+ undecodedContent: true,
+ }
+ : { kind: "malformed", format: XML_PLIST_FORMAT, detail: message },
+ options,
+ );
this.name = "XmlPlistTextDecodeError";
}
}
diff --git a/src/domain/xmlDocument.test.ts b/src/domain/xmlDocument.test.ts
index b7c668d8a6..7e5646af84 100644
--- a/src/domain/xmlDocument.test.ts
+++ b/src/domain/xmlDocument.test.ts
@@ -45,7 +45,7 @@ it.each([
lineEndings: "preserve",
});
if (parsed.ok) throw new Error("Expected refusal");
- expect(parsed.error.reason).toBe("malformed");
+ expect(parsed.error.kind).toBe("malformed");
expect(parsed.error.cause).toBeDefined();
});
@@ -67,7 +67,7 @@ it.each([
])("rejects namespace-invalid XML before DOM projection: %j", (source) => {
expect(
parseXmlDocument(source, { doctype: "reject", lineEndings: "preserve" }),
- ).toMatchObject({ ok: false, error: { reason: "malformed" } });
+ ).toMatchObject({ ok: false, error: { kind: "malformed" } });
});
it.each([
@@ -95,7 +95,10 @@ it("applies the consumer's explicit DTD policy", () => {
{ doctype: "reject", lineEndings: "preserve" },
);
if (parsed.ok) throw new Error("Expected unsupported DTD");
- expect(parsed.error.reason).toBe("doctype");
+ expect(parsed.error.failure).toMatchObject({
+ kind: "unsupported",
+ field: "doctype",
+ });
});
it.each([
@@ -126,7 +129,10 @@ it.each([
doctype: "external",
lineEndings: "normalize",
}),
- ).toMatchObject({ ok: false, error: { reason: "internal-subset" } });
+ ).toMatchObject({
+ ok: false,
+ error: { failure: { kind: "unsupported", field: "internal-subset" } },
+ });
},
);
diff --git a/src/domain/xmlDocument.ts b/src/domain/xmlDocument.ts
index 6958e6ef37..685b639131 100644
--- a/src/domain/xmlDocument.ts
+++ b/src/domain/xmlDocument.ts
@@ -1,26 +1,50 @@
import { DOMParser, onErrorStopParsing, type Document } from "@xmldom/xmldom";
import { SaxesParser, type SaxesTagNS } from "saxes";
import { err, ok, type Result } from "./result.js";
+import {
+ malformedInput,
+ ParseFailureError,
+ unsupportedInput,
+} from "./parseFailure.js";
/** XML 1.0 literal line endings; Unicode separators remain source characters. */
export const XML_LINE_ENDING = /\r\n?|\n/gu;
-class XmlDocumentParseError extends Error {
- readonly _tag = "XmlDocumentParseError";
- constructor(
- readonly reason: "malformed" | "doctype" | "internal-subset",
- cause?: unknown,
- ) {
- super(
- reason === "doctype"
- ? "XML document types are unsupported"
- : reason === "internal-subset"
- ? "XML document type internal subsets are unsupported"
- : `XML is not well-formed${cause instanceof Error ? `: ${cause.message}` : ""}`,
- { cause },
- );
- }
-}
+const XML_FORMAT = "xml";
+
+/** How XML failed: ill-formed syntax, or a DOCTYPE the policy refuses. */
+export type XmlParseFailure =
+ | ParseFailureError<"malformed">
+ | ParseFailureError<"unsupported">;
+
+const notWellFormed = (cause?: unknown): ParseFailureError<"malformed"> =>
+ malformedInput(
+ XML_FORMAT,
+ `XML is not well-formed${cause instanceof Error ? `: ${cause.message}` : ""}`,
+ { cause },
+ );
+
+/** A DOCTYPE, or its internal subset, that the document policy refuses. */
+const unsupportedDoctype = (
+ field: "doctype" | "internal-subset",
+): ParseFailureError<"unsupported"> =>
+ unsupportedInput(
+ XML_FORMAT,
+ field === "doctype"
+ ? "XML document types are unsupported"
+ : "XML document type internal subsets are unsupported",
+ { field },
+ );
+
+/** A failure the syntax check threw itself. */
+const isXmlFailure = (cause: unknown): cause is XmlParseFailure =>
+ cause instanceof ParseFailureError &&
+ cause.failure.format === XML_FORMAT &&
+ (cause.kind === "malformed" || cause.kind === "unsupported");
+
+/** The failure the syntax check established; any other throw is ill-formed XML. */
+const xmlFailure = (cause: unknown): XmlParseFailure =>
+ isXmlFailure(cause) ? cause : notWellFormed(cause);
/** Whether a DOCTYPE's text, as saxes reports it, opens an internal subset: a `[` outside its quoted literals. */
const declaresInternalSubset = (declaration: string): boolean =>
@@ -82,7 +106,7 @@ const checkXmlSyntax = (
listen?.(syntax);
const checkName = (name: string) => {
if (nameSupported !== undefined && !nameSupported(name))
- throw new XmlDocumentParseError("malformed");
+ throw notWellFormed();
};
if (nameSupported !== undefined) {
syntax.on("opentagstart", (tag) => checkName(tag.name));
@@ -92,12 +116,11 @@ const checkXmlSyntax = (
);
}
syntax.on("doctype", (declaration) => {
- if (doctype === "reject") throw new XmlDocumentParseError("doctype");
+ if (doctype === "reject") throw unsupportedDoctype("doctype");
if (doctype !== "external") return;
if (declaresInternalSubset(declaration))
- throw new XmlDocumentParseError("internal-subset");
- if (!EXTERNAL_DOCTYPE.test(declaration))
- throw new XmlDocumentParseError("malformed");
+ throw unsupportedDoctype("internal-subset");
+ if (!EXTERNAL_DOCTYPE.test(declaration)) throw notWellFormed();
checkName(declaration.trimStart().split(/[ \t\r\n]/u, 1)[0] ?? "");
});
syntax.write(source).close();
@@ -142,7 +165,7 @@ export const xmlElementRanges = (
policy: { readonly doctype: Exclude },
): Result<
readonly { readonly start: number; readonly end: number }[],
- XmlDocumentParseError
+ XmlParseFailure
> => {
const ranges: { start: number; end: number }[] = [];
// Each open element's start, and whether it was picked.
@@ -180,11 +203,7 @@ export const xmlElementRanges = (
});
return ok(ranges.sort((left, right) => left.start - right.start));
} catch (cause: unknown) {
- return err(
- cause instanceof XmlDocumentParseError
- ? cause
- : new XmlDocumentParseError("malformed", cause),
- );
+ return err(xmlFailure(cause));
}
};
@@ -194,7 +213,7 @@ export const xmlAttributeQuoteRanges = (
): Result<
readonly { readonly start: number; readonly end: number }[],
{
- readonly error: XmlDocumentParseError;
+ readonly error: XmlParseFailure;
readonly ranges: readonly {
readonly start: number;
readonly end: number;
@@ -210,20 +229,16 @@ export const xmlAttributeQuoteRanges = (
syntax.on("attribute", () => {
const end = syntax.position - 1;
const quote = source[end];
- if (quote !== '"' && quote !== "'")
- throw new XmlDocumentParseError("malformed");
+ if (quote !== '"' && quote !== "'") throw notWellFormed();
const start = source.lastIndexOf(quote, end - 1);
- if (start < 0) throw new XmlDocumentParseError("malformed");
+ if (start < 0) throw notWellFormed();
ranges.push({ start, end });
});
});
return ok(ranges);
} catch (cause: unknown) {
return err({
- error:
- cause instanceof XmlDocumentParseError
- ? cause
- : new XmlDocumentParseError("malformed", cause),
+ error: xmlFailure(cause),
ranges,
examined: Math.max(0, (reader?.position ?? 0) - 1),
});
@@ -238,7 +253,7 @@ export const parseXmlDocument = (
readonly lineEndings: "preserve" | "normalize";
readonly nameSupported?: (name: string) => boolean;
},
-): Result => {
+): Result => {
try {
checkXmlSyntax(source, policy.doctype, undefined, policy.nameSupported);
// Saxes owns well-formedness outside DTDs. The DOM parser additionally
@@ -254,11 +269,7 @@ export const parseXmlDocument = (
}).parseFromString(source, "application/xml"),
);
} catch (cause: unknown) {
- return err(
- cause instanceof XmlDocumentParseError
- ? cause
- : new XmlDocumentParseError("malformed", cause),
- );
+ return err(xmlFailure(cause));
}
};
diff --git a/src/ghidra/GhidraClient.ts b/src/ghidra/GhidraClient.ts
index ae8e981ab7..9c6987e823 100644
--- a/src/ghidra/GhidraClient.ts
+++ b/src/ghidra/GhidraClient.ts
@@ -33,10 +33,7 @@ import {
type LinuxCgroupMemoryState,
} from "../process/LinuxCgroupMemory.js";
import { PendingOperations } from "../process/PendingOperations.js";
-import {
- Utf8NdjsonLineBuffer,
- Utf8NdjsonDecodingError,
-} from "../process/Utf8NdjsonLineBuffer.js";
+import { Utf8NdjsonLineBuffer } from "../process/Utf8NdjsonLineBuffer.js";
import { AbortedWait, waitForAbortable } from "../process/AbortablePromise.js";
import { SharedStartupAttempt } from "../process/SharedStartupAttempt.js";
import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
@@ -130,6 +127,7 @@ const SHUTDOWN_TIMEOUT_MS = 10_000;
*/
const OUTPUT_DRAIN_MS = 1_000;
const SESSION_ROOT = ghidraSessionRoot();
+const GHIDRA_RESPONSE_NOT_UTF8 = "Ghidra bridge response is not valid UTF-8";
type GhidraStartupAttempt = SharedStartupAttempt;
@@ -199,21 +197,17 @@ export class GhidraClient {
});
readonly #responseLines = new Utf8NdjsonLineBuffer();
readonly #onSocketData = (chunk: Buffer): void => {
- try {
- for (const line of this.#responseLines.push(chunk))
- this.#responseRouter.route(line);
- } catch (cause: unknown) {
- if (!(cause instanceof Utf8NdjsonDecodingError)) throw cause;
- this.#abortProtocol("Ghidra bridge response is not valid UTF-8", cause);
+ for (const line of this.#responseLines.push(chunk)) {
+ if (!line.ok) {
+ this.#abortProtocol(GHIDRA_RESPONSE_NOT_UTF8, line.error);
+ return;
+ }
+ this.#responseRouter.route(line.value);
}
};
readonly #onSocketEnd = (): void => {
- try {
- this.#responseLines.finish();
- } catch (cause: unknown) {
- if (!(cause instanceof Utf8NdjsonDecodingError)) throw cause;
- this.#abortProtocol("Ghidra bridge response is not valid UTF-8", cause);
- }
+ const tail = this.#responseLines.finish();
+ if (!tail.ok) this.#abortProtocol(GHIDRA_RESPONSE_NOT_UTF8, tail.error);
};
readonly #onSocketError = (): void => {
this.#failAll(this.#failure("process", "Ghidra bridge socket failed"));
diff --git a/src/ghidra/GhidraResponseRouter.test.ts b/src/ghidra/GhidraResponseRouter.test.ts
index bf8bcc5576..9724a921f4 100644
--- a/src/ghidra/GhidraResponseRouter.test.ts
+++ b/src/ghidra/GhidraResponseRouter.test.ts
@@ -41,7 +41,7 @@ it("routes later Ghidra response lines after an unknown response id", async () =
'{"id":2,"ok":true,"result":null}\n{"id":1,"ok":true,"result":"settled"}\n',
),
))
- router.route(line);
+ if (line.ok) router.route(line.value);
expect(protocolFailure).toHaveBeenCalledOnce();
expect(protocolFailure).toHaveBeenCalledWith(
diff --git a/src/hopper/HopperClient.ts b/src/hopper/HopperClient.ts
index 5e7f5b92e2..43b6f508d1 100644
--- a/src/hopper/HopperClient.ts
+++ b/src/hopper/HopperClient.ts
@@ -1,4 +1,3 @@
-import { Utf8NdjsonDecodingError } from "../process/Utf8NdjsonLineBuffer.js";
import { analysisSettingLimit } from "../domain/analysisSettingDefinitions.js";
import { randomBytes, randomUUID } from "node:crypto";
import { access } from "node:fs/promises";
@@ -170,20 +169,10 @@ export class HopperClient {
#startupAttempt: HopperStartupAttempt | undefined;
#closePromise: Promise> | undefined;
readonly #onSocketData = (chunk: Buffer): void => {
- try {
- this.#responses.push(chunk);
- } catch (cause: unknown) {
- if (!(cause instanceof Utf8NdjsonDecodingError)) throw cause;
- this.#abortProtocol("Hopper bridge response is not valid UTF-8", cause);
- }
+ this.#responses.push(chunk);
};
readonly #onSocketEnd = (): void => {
- try {
- this.#responses.finish();
- } catch (cause: unknown) {
- if (!(cause instanceof Utf8NdjsonDecodingError)) throw cause;
- this.#abortProtocol("Hopper bridge response is not valid UTF-8", cause);
- }
+ this.#responses.finish();
};
readonly #onSocketError = (): void => {
const error = new HopperProcessError(null, {
diff --git a/src/hopper/HopperResponseStream.ts b/src/hopper/HopperResponseStream.ts
index 1cbb041719..69dc35b96a 100644
--- a/src/hopper/HopperResponseStream.ts
+++ b/src/hopper/HopperResponseStream.ts
@@ -11,6 +11,8 @@ interface HopperResponseStreamOptions {
readonly abort: (message: string, cause?: Error) => void;
}
+const NOT_UTF8 = "Hopper bridge response is not valid UTF-8";
+
/** Incrementally validates Hopper NDJSON response frames. */
export class HopperResponseStream {
readonly #lines = new Utf8NdjsonLineBuffer();
@@ -18,12 +20,18 @@ export class HopperResponseStream {
constructor(readonly options: HopperResponseStreamOptions) {}
push(chunk: Buffer): void {
- for (const line of this.#lines.push(chunk))
- if (!this.#acceptLine(line)) break;
+ for (const line of this.#lines.push(chunk)) {
+ if (!line.ok) {
+ this.options.abort(NOT_UTF8, line.error);
+ break;
+ }
+ if (!this.#acceptLine(line.value)) break;
+ }
}
finish(): void {
- this.#lines.finish();
+ const tail = this.#lines.finish();
+ if (!tail.ok) this.options.abort(NOT_UTF8, tail.error);
}
reset(): void {
diff --git a/src/il2cpp/Il2cppBinaryImage.ts b/src/il2cpp/Il2cppBinaryImage.ts
index 13f98e5145..e0c0afc42f 100644
--- a/src/il2cpp/Il2cppBinaryImage.ts
+++ b/src/il2cpp/Il2cppBinaryImage.ts
@@ -24,10 +24,7 @@ import {
parsePointerFixupsSteps,
type PointerFixups,
} from "../native/AppleMachoFixups.js";
-import {
- parseMachoLayout,
- UnsupportedMachoMetadataFormatError,
-} from "../native/AppleMachoSelection.js";
+import { parseMachoLayout } from "../native/AppleMachoSelection.js";
import {
readElfPointerValuesSteps,
ElfPointerRelocationFailure,
@@ -161,11 +158,6 @@ export function* openImageSteps(image: Buffer): Generator {
layout.baseAddress,
);
} catch (cause) {
- if (cause instanceof UnsupportedMachoMetadataFormatError)
- throw new Il2cppBinaryFormatFailure(
- "unsupported-container",
- cause.message,
- );
const failure = parseFailureFromCause(cause);
if (failure !== undefined)
throw new Il2cppBinaryFormatFailure(
diff --git a/src/kuna/KunaDocumentError.ts b/src/kuna/KunaDocumentError.ts
index c17bcf66e2..96b02ff679 100644
--- a/src/kuna/KunaDocumentError.ts
+++ b/src/kuna/KunaDocumentError.ts
@@ -1,3 +1,5 @@
+import { ParseFailureError } from "../domain/parseFailure.js";
+
const KUNA_DOCUMENT_CODES = [
"invalid_address",
"address_exceeds_u64",
@@ -30,20 +32,49 @@ const KUNA_DOCUMENT_CODES = [
"xref_function_hex",
"xref_target",
"span_short",
- "stop_unproven",
] as const;
export type KunaDocumentCode = (typeof KUNA_DOCUMENT_CODES)[number];
-/** Kuna document or command admission failure. `code` is the stable identity. */
-export class KunaDocumentError extends Error {
- readonly _tag = "KunaDocumentError";
+const KUNA_FORMAT = "kuna-document";
+
+type KunaDocumentFacts = Readonly>;
+
+/**
+ * Kuna document failure. `code` is the stable identity. A document larger
+ * than its buffered allowance is a `limit`, a span that reads short is
+ * `truncated`, and every other code is `malformed`.
+ */
+export class KunaDocumentError extends ParseFailureError<
+ "malformed" | "truncated" | "limit"
+> {
+ readonly code: KunaDocumentCode;
+ /** Format-specific facts, such as the field that failed. */
+ readonly facts: KunaDocumentFacts | undefined;
constructor(
- readonly code: KunaDocumentCode,
- readonly detail?: Readonly>,
- ) {
- super(code);
+ code: Exclude,
+ facts?: KunaDocumentFacts,
+ );
+ constructor(code: "buffered_capacity", facts: { maximum_bytes: number });
+ constructor(code: KunaDocumentCode, facts?: KunaDocumentFacts) {
+ const field =
+ typeof facts?.field === "string" ? { field: facts.field } : {};
+ const maximum = facts?.maximum_bytes;
+ super(
+ code === "buffered_capacity" && typeof maximum === "number"
+ ? {
+ kind: "limit",
+ format: KUNA_FORMAT,
+ detail: code,
+ limit: { name: "kuna-buffered-document-bytes", maximum },
+ }
+ : code === "span_short"
+ ? { kind: "truncated", format: KUNA_FORMAT, detail: code, ...field }
+ : { kind: "malformed", format: KUNA_FORMAT, detail: code, ...field },
+ );
this.name = "KunaDocumentError";
+ this.code = code;
+ this.facts = facts;
}
}
diff --git a/src/kuna/KunaInventoryPlacement.ts b/src/kuna/KunaInventoryPlacement.ts
index 0437980472..1ef807a305 100644
--- a/src/kuna/KunaInventoryPlacement.ts
+++ b/src/kuna/KunaInventoryPlacement.ts
@@ -4,11 +4,8 @@ import {
readMachoLoadCommandTableHeader,
} from "../domain/apple/machoLoadCommands.js";
import { decodeMachoFixedName } from "../native/AppleMachoNames.js";
-import {
- MachoBinaryFormatError,
- MachoCommandNamesLimitError,
- readMachoCommandNames,
-} from "../native/MachoCommandNames.js";
+import { parseFailureFromCause } from "../domain/parseFailure.js";
+import { readMachoCommandNames } from "../native/MachoCommandNames.js";
import type { KunaInputPrefix } from "./KunaCommand.js";
import type { KunaInventoryFunction } from "./KunaProjectFiles.js";
@@ -134,11 +131,8 @@ export const readKunaMachoLayout = async (head: {
MAX_LAYOUT_RECORDS,
));
} catch (cause: unknown) {
- if (
- cause instanceof MachoBinaryFormatError ||
- cause instanceof MachoCommandNamesLimitError
- )
- return unavailable(cause.message);
+ const failure = parseFailureFromCause(cause);
+ if (failure !== undefined) return unavailable(failure.message);
throw cause;
}
const name = (field: Uint8Array) =>
diff --git a/src/kuna/KunaJson.test.ts b/src/kuna/KunaJson.test.ts
new file mode 100644
index 0000000000..a2f799b473
--- /dev/null
+++ b/src/kuna/KunaJson.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+
+import { ParseFailureError } from "../domain/parseFailure.js";
+import { KunaDocumentError } from "./KunaDocumentError.js";
+import { parseKunaJson } from "./KunaJson.js";
+
+const failureOf = (run: () => unknown): KunaDocumentError => {
+ try {
+ run();
+ } catch (cause: unknown) {
+ if (cause instanceof KunaDocumentError) return cause;
+ throw cause;
+ }
+ throw new Error("expected a Kuna document failure");
+};
+
+describe("Kuna document failures", () => {
+ it("reports a document over its buffered allowance as a limit with the caller's maximum", () => {
+ const failure = failureOf(() =>
+ parseKunaJson('{"address":1}', 4, new Set(["address"])),
+ );
+ expect(failure).toBeInstanceOf(ParseFailureError);
+ expect(failure.code).toBe("buffered_capacity");
+ expect(failure.failure).toEqual({
+ kind: "limit",
+ format: "kuna-document",
+ detail: "buffered_capacity",
+ limit: { name: "kuna-buffered-document-bytes", maximum: 4 },
+ });
+ });
+
+ it("reports a non-numeric address as malformed and names its field", () => {
+ const failure = failureOf(() =>
+ parseKunaJson('{"address":"0x10"}', 1024, new Set(["address"])),
+ );
+ expect(failure.code).toBe("invalid_address");
+ expect(failure.facts).toEqual({ field: "address" });
+ expect(failure.failure).toEqual({
+ kind: "malformed",
+ format: "kuna-document",
+ detail: "invalid_address",
+ field: "address",
+ });
+ });
+});
diff --git a/src/kuna/KunaJson.ts b/src/kuna/KunaJson.ts
index c9e62316c3..76aba96cd0 100644
--- a/src/kuna/KunaJson.ts
+++ b/src/kuna/KunaJson.ts
@@ -24,7 +24,7 @@ export const parseKunaJson = (
addressKeys: ReadonlySet,
): unknown => {
if (Buffer.byteLength(text) > limit)
- throw new KunaDocumentError("buffered_capacity");
+ throw new KunaDocumentError("buffered_capacity", { maximum_bytes: limit });
return JSON.parse(
text,
(
diff --git a/src/kuna/KunaJsonStream.ts b/src/kuna/KunaJsonStream.ts
index 64c26e3546..b113ac725f 100644
--- a/src/kuna/KunaJsonStream.ts
+++ b/src/kuna/KunaJsonStream.ts
@@ -255,7 +255,7 @@ export abstract class KunaJsonDocumentReader extends Writable {
: cause instanceof KunaDocumentError
? new AnalysisOutputError(this.producer, cause.code, {
cause,
- diagnostics: { code: cause.code, ...cause.detail },
+ diagnostics: { code: cause.code, ...cause.facts },
userMessage: `${this.label} cannot be used`,
})
: this.unusable(describe(cause));
diff --git a/src/kuna/KunaReferenceFiles.ts b/src/kuna/KunaReferenceFiles.ts
index 5d52b881ed..161d01ab6f 100644
--- a/src/kuna/KunaReferenceFiles.ts
+++ b/src/kuna/KunaReferenceFiles.ts
@@ -379,7 +379,7 @@ export const parseKunaIncomingReferences = (
});
} catch (cause: unknown) {
if (cause instanceof KunaDocumentError) {
- const field = cause.detail?.field;
+ const field = cause.facts?.field;
return err(
typeof field === "string"
? { code: cause.code, field }
diff --git a/src/kuna/KunaTargetCommands.ts b/src/kuna/KunaTargetCommands.ts
index f28b1beead..0a44beffef 100644
--- a/src/kuna/KunaTargetCommands.ts
+++ b/src/kuna/KunaTargetCommands.ts
@@ -19,7 +19,6 @@ import {
OwnerCancellation,
} from "../domain/analysisErrorCore.js";
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
-import { KunaDocumentError } from "./KunaDocumentError.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
@@ -200,8 +199,10 @@ export class KunaTargetCommands {
if (outcome.kind === "retained") {
const process = new AnalysisCleanupLease(async () => {
const stopped = await outcome.owner?.stop();
- if (stopped === undefined || stopped.status === "incomplete")
- throw new KunaDocumentError("stop_unproven");
+ if (stopped === undefined)
+ throw new Error("Kuna process ownership remains unresolved");
+ if (stopped.status === "incomplete")
+ throw new Error(stopped.reason, { cause: stopped });
releaseRun?.();
}, outcome.processResources);
new AnalysisCleanupLeaseGroup(outcome.error, [
diff --git a/src/native/AppleDispatchMetadata.ts b/src/native/AppleDispatchMetadata.ts
index ec7b29520a..c31afd3c0d 100644
--- a/src/native/AppleDispatchMetadata.ts
+++ b/src/native/AppleDispatchMetadata.ts
@@ -49,7 +49,6 @@ import { parsePointerFixupsSteps } from "./AppleMachoFixups.js";
import { BinaryFormatFailure } from "./metadata/BinaryContainer.js";
import {
parseMachoLayout,
- UnsupportedMachoMetadataFormatError,
type AdmittedMachoSlice,
} from "./AppleMachoSelection.js";
import { decodeObjcDispatchFacets } from "./AppleObjcDispatchFacets.js";
@@ -466,6 +465,15 @@ const appleDispatchMetadataPrimaryFailure = (
): AnalysisError => {
if (origin === "owned-or-classified") {
if (cause instanceof AnalysisError) return cause;
+ // A recognized Mach-O class this reader cannot decode still holds metadata
+ // another reader may recover.
+ if (cause instanceof BinaryFormatFailure && cause.undecodedContent)
+ return new AnalysisCapabilityUnavailableError(
+ IDENTITY.id,
+ OPERATION,
+ cause.message,
+ { cause },
+ );
if (cause instanceof BinaryFormatFailure)
return new AnalysisUnsupportedTargetError(
OPERATION,
@@ -479,13 +487,6 @@ const appleDispatchMetadataPrimaryFailure = (
: "Select a supported little-endian 64-bit Mach-O artifact, reopen the target, then retry.",
},
);
- if (cause instanceof UnsupportedMachoMetadataFormatError)
- return new AnalysisCapabilityUnavailableError(
- IDENTITY.id,
- OPERATION,
- cause.message,
- { cause },
- );
if (cause instanceof ArtifactReaderFailure && cause.reason === "cancelled")
return cancelledBy(
OPERATION,
diff --git a/src/native/AppleMachoSelection.test.ts b/src/native/AppleMachoSelection.test.ts
index 0a6fa509c8..052a4a80e5 100644
--- a/src/native/AppleMachoSelection.test.ts
+++ b/src/native/AppleMachoSelection.test.ts
@@ -18,11 +18,8 @@ import {
} from "../artifacts/apple/MachoImage.fixture.js";
import { readMachoImage } from "../artifacts/apple/MachoLoadCommandReader.js";
import { readMachoImage as readMachoMetadataImage } from "./metadata/MachoImage.js";
-import {
- parseMachoLayout,
- selectMachoSlice,
- UnsupportedMachoMetadataFormatError,
-} from "./AppleMachoSelection.js";
+import { parseMachoLayout, selectMachoSlice } from "./AppleMachoSelection.js";
+import { BinaryFormatFailure } from "./metadata/BinaryContainer.js";
import { parsePointerFixups } from "./AppleMachoFixups.fixture.js";
import { decodeAppleDispatchMetadata } from "./AppleDispatchMetadata.fixture.js";
@@ -43,7 +40,7 @@ it("keeps unknown magic distinct from recognized unsupported Mach-O formats", ()
failure = error;
}
expect(failure).toBeInstanceOf(TypeError);
- expect(failure).not.toBeInstanceOf(UnsupportedMachoMetadataFormatError);
+ expect(failure).not.toBeInstanceOf(BinaryFormatFailure);
});
it.each([
diff --git a/src/native/AppleMachoSelection.ts b/src/native/AppleMachoSelection.ts
index 259260cf95..f0da4b4310 100644
--- a/src/native/AppleMachoSelection.ts
+++ b/src/native/AppleMachoSelection.ts
@@ -146,14 +146,6 @@ export const selectMachoSlice = (
};
};
-/** A recognized Mach-O class outside this metadata reader's supported formats. */
-export class UnsupportedMachoMetadataFormatError extends Error {
- constructor(message: string) {
- super(message);
- this.name = "UnsupportedMachoMetadataFormatError";
- }
-}
-
/** Parse segments/sections for a little-endian 64-bit Mach-O architecture slice. */
export const parseMachoLayout = (
bytes: Buffer,
@@ -196,8 +188,13 @@ export const parseMachoLayout = (
"unsupported",
"Unsupported big-endian Mach-O CPU type",
);
- throw new UnsupportedMachoMetadataFormatError(
+ throw new BinaryFormatFailure(
+ "unsupported",
"Unsupported big-endian 64-bit PowerPC Mach-O metadata",
+ {
+ format: "macho",
+ undecodedContent: true,
+ },
);
}
// A thin image has no FAT declaration to bind the requested CPU family.
@@ -207,8 +204,13 @@ export const parseMachoLayout = (
`Mach-O CPU type does not match requested architecture ${architecture}`,
);
if (!table.wide)
- throw new UnsupportedMachoMetadataFormatError(
+ throw new BinaryFormatFailure(
+ "unsupported",
`Unsupported 32-bit Mach-O metadata for requested CPU type ${architecture}`,
+ {
+ format: "macho",
+ undecodedContent: true,
+ },
);
const commandEnd = slice + table.headerSize + table.commandBytes;
if (commandEnd > sliceEnd)
@@ -237,12 +239,12 @@ export const parseMachoLayout = (
kind: frame.value.command,
size: frame.value.size,
};
- if (command.kind === 1)
+ if (command.kind === LC.SEGMENT)
throw malformedInput(
"macho",
"Mach-O segment command does not match the header width",
);
- if (command.kind === 0x19) collectSegment(bytes, command, state);
+ if (command.kind === LC.SEGMENT_64) collectSegment(bytes, command, state);
else collectFixupCommand(bytes, command, state);
}
const complete = framing.finish();
diff --git a/src/native/MachoBinaryProjection.test.ts b/src/native/MachoBinaryProjection.test.ts
index f23e54af96..843f881911 100644
--- a/src/native/MachoBinaryProjection.test.ts
+++ b/src/native/MachoBinaryProjection.test.ts
@@ -321,7 +321,7 @@ it("retains legacy command metadata and derives simulator platform from CPU", ()
offset: 64,
size: 16,
rawSha256: null,
- legacyBuild: { version: 0x000e0200, sdk: 0x000f0000 },
+ legacyBuild: { platform: 2, version: 0x000e0200, sdk: 0x000f0000 },
},
],
});
diff --git a/src/native/MachoBinaryProjection.ts b/src/native/MachoBinaryProjection.ts
index 72343f0c39..00c387e80e 100644
--- a/src/native/MachoBinaryProjection.ts
+++ b/src/native/MachoBinaryProjection.ts
@@ -1,8 +1,8 @@
+import { legacyMachoPlatform } from "../domain/apple/machoPlatform.js";
import {
- legacyMachoPlatform,
- type MachoVersionMinPlatform,
-} from "../domain/apple/machoPlatform.js";
-import { machoLoadCommandName } from "../domain/apple/machoLoadCommandCodes.js";
+ LC,
+ machoLoadCommandName,
+} from "../domain/apple/machoLoadCommandCodes.js";
import type { MachoCommandNames } from "./MachoCommandNames.js";
const PLATFORM_NAMES = new Map([
@@ -53,26 +53,34 @@ const DYLIBS = new Set([
"LC_LOADFVMLIB",
"LC_PREBOUND_DYLIB",
]);
+// Fixed-VM and prebound library commands carry fields after the name that this
+// projection does not decode.
+const UNDECODED_STRING_COMMANDS = new Set([
+ LC.LOADFVMLIB,
+ LC.IDFVMLIB,
+ LC.FVMFILE,
+ LC.PREBOUND_DYLIB,
+]);
const STRING_FIELDS = new Map([
- [0x6, "name"],
- [0x7, "name"],
- [0x9, "name"],
- [0x10, "name"],
- [0xc, "name"],
- [0xd, "name"],
- [0x80000018, "name"],
- [0x8000001f, "name"],
- [0x20, "name"],
- [0x80000023, "name"],
- [0xe, "name"],
- [0xf, "name"],
- [0x12, "umbrella"],
- [0x13, "sub_umbrella"],
- [0x14, "client"],
- [0x15, "sub_library"],
- [0x8000001c, "path"],
- [0x27, "name"],
- [0x39, "triple"],
+ [LC.LOADFVMLIB, "name"],
+ [LC.IDFVMLIB, "name"],
+ [LC.FVMFILE, "name"],
+ [LC.PREBOUND_DYLIB, "name"],
+ [LC.LOAD_DYLIB, "name"],
+ [LC.ID_DYLIB, "name"],
+ [LC.LOAD_WEAK_DYLIB, "name"],
+ [LC.REEXPORT_DYLIB, "name"],
+ [LC.LAZY_LOAD_DYLIB, "name"],
+ [LC.LOAD_UPWARD_DYLIB, "name"],
+ [LC.LOAD_DYLINKER, "name"],
+ [LC.ID_DYLINKER, "name"],
+ [LC.SUB_FRAMEWORK, "umbrella"],
+ [LC.SUB_UMBRELLA, "sub_umbrella"],
+ [LC.SUB_CLIENT, "client"],
+ [LC.SUB_LIBRARY, "sub_library"],
+ [LC.RPATH, "path"],
+ [LC.DYLD_ENVIRONMENT, "name"],
+ [LC.TARGET_TRIPLE, "triple"],
]);
const bytesText = (input: Uint8Array, fixed: boolean) => {
@@ -344,7 +352,7 @@ export const projectMachoBinary = (
});
}
if (row.commandString !== undefined) {
- decoded = ![0x6, 0x7, 0x9, 0x10].includes(row.command);
+ decoded = !UNDECODED_STRING_COMMANDS.has(row.command);
const name = textFact(row.commandString, false, commandLimitations);
const field = STRING_FIELDS.get(row.command) ?? "name";
fields[field] =
@@ -441,8 +449,7 @@ export const projectMachoBinary = (
decoded = true;
fields.version = version(row.legacyBuild.version);
fields.sdk = version(row.legacyBuild.sdk);
- const platform = ([0x24, 0x25, 0x2f, 0x30].indexOf(row.command) +
- 1) as MachoVersionMinPlatform;
+ const platform = row.legacyBuild.platform;
const effective = legacyMachoPlatform(platform, binary.header.cpuType);
builds.push({
platform:
diff --git a/src/native/MachoCommandNames.test.ts b/src/native/MachoCommandNames.test.ts
index cf5cb7ca25..28eb92a48f 100644
--- a/src/native/MachoCommandNames.test.ts
+++ b/src/native/MachoCommandNames.test.ts
@@ -186,6 +186,7 @@ it("retains alternate dylib flags and legacy platform versions", async () => {
encoding: { kind: "use", flags: 9 },
});
expect(result.commands[1]?.legacyBuild).toEqual({
+ platform: 1,
version: 0x000d0102,
sdk: 0x000f0000,
});
diff --git a/src/native/MachoCommandNames.ts b/src/native/MachoCommandNames.ts
index 764789bb29..772a0d89e2 100644
--- a/src/native/MachoCommandNames.ts
+++ b/src/native/MachoCommandNames.ts
@@ -1,31 +1,51 @@
+import { LC, LC_REQ_DYLD } from "../domain/apple/machoLoadCommandCodes.js";
import {
MachoLoadCommandCursor,
decodeMachoFixedWordFields,
machoFixedWordFieldNames,
readMachoLoadCommandTableHeader,
} from "../domain/apple/machoLoadCommands.js";
+import {
+ MACHO_VERSION_MIN_PLATFORMS,
+ type MachoVersionMinPlatform,
+} from "../domain/apple/machoPlatform.js";
import { readMachoSegmentHeader } from "../domain/apple/machoSegmentHeader.js";
import { readMachoSectionHeader } from "../domain/apple/machoSectionHeader.js";
import { createHash } from "node:crypto";
+import {
+ malformedInput,
+ ParseFailureError,
+ truncatedInput,
+} from "../domain/parseFailure.js";
+/** loader.h defines these with LC_REQ_DYLD; the reader also accepts each code without that bit. */
+const withoutRequiredByDyld = (code: number): number => code & ~LC_REQ_DYLD;
const DYLIB_COMMANDS = new Set([
- 0xc, 0xd, 0x18, 0x80000018, 0x1f, 0x8000001f, 0x20, 0x23, 0x80000023,
+ LC.LOAD_DYLIB,
+ LC.ID_DYLIB,
+ withoutRequiredByDyld(LC.LOAD_WEAK_DYLIB),
+ LC.LOAD_WEAK_DYLIB,
+ withoutRequiredByDyld(LC.REEXPORT_DYLIB),
+ LC.REEXPORT_DYLIB,
+ LC.LAZY_LOAD_DYLIB,
+ withoutRequiredByDyld(LC.LOAD_UPWARD_DYLIB),
+ LC.LOAD_UPWARD_DYLIB,
]);
const LC_STR_COMMANDS = new Set([
...DYLIB_COMMANDS,
- 0x6,
- 0x7,
- 0x9,
- 0x10,
- 0xe,
- 0xf,
- 0x12,
- 0x13,
- 0x14,
- 0x15,
- 0x8000001c,
- 0x27,
- 0x39,
+ LC.LOADFVMLIB,
+ LC.IDFVMLIB,
+ LC.FVMFILE,
+ LC.PREBOUND_DYLIB,
+ LC.LOAD_DYLINKER,
+ LC.ID_DYLINKER,
+ LC.SUB_FRAMEWORK,
+ LC.SUB_UMBRELLA,
+ LC.SUB_CLIENT,
+ LC.SUB_LIBRARY,
+ LC.RPATH,
+ LC.DYLD_ENVIRONMENT,
+ LC.TARGET_TRIPLE,
]);
/** Read exact ranges from an already admitted and identity-verified slice. */
@@ -34,18 +54,22 @@ export type MachoRangeReader = (
size: number,
) => Promise;
-/** Invalid on-disk Mach-O framing or payload at the binary producer boundary. */
-export class MachoBinaryFormatError extends Error {}
-
-/** Producer-derived output capacity exceeded while retaining binary strings. */
-export class MachoCommandNamesLimitError extends Error {
+/**
+ * Producer-derived output capacity exceeded while retaining binary strings,
+ * with the unit its maximum counts.
+ */
+export class MachoCommandNamesLimitError extends ParseFailureError<"limit"> {
constructor(
readonly maximum: number,
readonly unit: "bytes" | "records" | "projected_bytes",
) {
- super(
- `Mach-O load-command ${unit === "projected_bytes" ? "projected bytes" : unit} exceed the retained output budget`,
- );
+ super({
+ kind: "limit",
+ format: "macho",
+ detail: `Mach-O load-command ${unit === "projected_bytes" ? "projected bytes" : unit} exceed the retained output budget`,
+ limit: { name: `macho_load_command_${unit}`, maximum },
+ });
+ this.name = "MachoCommandNamesLimitError";
}
}
@@ -116,6 +140,7 @@ export interface MachoCommandNames {
| { readonly kind: "use"; readonly flags: number };
};
readonly legacyBuild?: {
+ readonly platform: MachoVersionMinPlatform;
readonly version: number;
readonly sdk: number;
};
@@ -186,17 +211,17 @@ export const readMachoCommandNames = async (
size < 0 ||
offset > imageSize - size
)
- throw new MachoBinaryFormatError("Mach-O range exceeds selected slice");
+ throw malformedInput("macho", "Mach-O range exceeds selected slice");
const value = await read(offset, size);
if (value.byteLength !== size)
- throw new MachoBinaryFormatError("Mach-O range is truncated");
+ throw truncatedInput("macho", "Mach-O range is truncated");
return value;
};
const header = await exact(0, Math.min(32, imageSize));
const parsed = readMachoLoadCommandTableHeader(header, imageSize);
- if (!parsed.ok) throw new MachoBinaryFormatError(parsed.error);
+ if (!parsed.ok) throw malformedInput("macho", parsed.error);
if (parsed.value === null)
- throw new MachoBinaryFormatError("Selected slice is not Mach-O");
+ throw malformedInput("macho", "Selected slice is not Mach-O");
const table = parsed.value;
const cursor = new MachoLoadCommandCursor(table);
if (table.commandCount > maximumRecords)
@@ -248,7 +273,7 @@ export const readMachoCommandNames = async (
const end = bytes.indexOf(0);
if (end < 0) {
if (length < extent) admitStringBytes(length);
- throw new MachoBinaryFormatError(`${label} is unterminated`);
+ throw malformedInput("macho", `${label} is unterminated`);
}
return retain(bytes.subarray(0, end));
};
@@ -257,7 +282,7 @@ export const readMachoCommandNames = async (
const row = cursor.read(
await exact(table.headerSize + cursor.nextOffset, 8),
);
- if (!row.ok) throw new MachoBinaryFormatError(row.error);
+ if (!row.ok) throw malformedInput("macho", row.error);
const frame = row.value;
const at = table.headerSize + frame.offset;
const fixedNames = machoFixedWordFieldNames(frame.command);
@@ -273,13 +298,18 @@ export const readMachoCommandNames = async (
table.littleEndian,
);
if (decoded === null)
- throw new MachoBinaryFormatError(
+ throw malformedInput(
+ "macho",
"Mach-O fixed command fields are truncated",
);
fixedFields = decoded;
}
const segmentWide =
- frame.command === 0x19 ? true : frame.command === 1 ? false : null;
+ frame.command === LC.SEGMENT_64
+ ? true
+ : frame.command === LC.SEGMENT
+ ? false
+ : null;
let segmentName: Uint8Array | undefined;
let segmentFacts: MachoCommandNames["commands"][number]["segment"];
let sections:
@@ -288,20 +318,20 @@ export const readMachoCommandNames = async (
if (segmentWide !== null) {
const segmentHeaderSize = segmentWide ? 72 : 56;
if (frame.size < segmentHeaderSize)
- throw new MachoBinaryFormatError("Mach-O segment is truncated");
+ throw malformedInput("macho", "Mach-O segment is truncated");
const segmentBytes = await exact(at, segmentHeaderSize);
const segment = readMachoSegmentHeader(
segmentBytes,
segmentWide,
table.littleEndian,
);
- if (!segment.ok) throw new MachoBinaryFormatError(segment.error.message);
+ if (!segment.ok) throw malformedInput("macho", segment.error.message);
const width = segmentWide ? 80 : 68;
if (
segment.value.sectionCount >
Math.floor((frame.size - segmentHeaderSize) / width)
)
- throw new MachoBinaryFormatError("Mach-O section table is truncated");
+ throw malformedInput("macho", "Mach-O section table is truncated");
if (segment.value.sectionCount > maximumRecords - records)
throw new MachoCommandNamesLimitError(maximumRecords, "records");
chargeProjection(segment.value.sectionCount, PROJECTED_SECTION_BYTES);
@@ -332,8 +362,7 @@ export const readMachoCommandNames = async (
segmentWide,
table.littleEndian,
);
- if (!section.ok)
- throw new MachoBinaryFormatError(section.error.message);
+ if (!section.ok) throw malformedInput("macho", section.error.message);
const sectionView = new DataView(
sectionBytes.buffer,
sectionBytes.byteOffset,
@@ -379,7 +408,8 @@ export const readMachoCommandNames = async (
let dylib: MachoCommandNames["commands"][number]["dylib"];
if (LC_STR_COMMANDS.has(frame.command)) {
if (frame.size < 12)
- throw new MachoBinaryFormatError(
+ throw malformedInput(
+ "macho",
"Mach-O command string offset is truncated",
);
const data = await exact(at + 8, 4);
@@ -390,15 +420,16 @@ export const readMachoCommandNames = async (
).getUint32(0, table.littleEndian);
const minimum = DYLIB_COMMANDS.has(frame.command)
? 24
- : frame.command === 0x6 ||
- frame.command === 0x7 ||
- frame.command === 0x10
+ : frame.command === LC.LOADFVMLIB ||
+ frame.command === LC.IDFVMLIB ||
+ frame.command === LC.PREBOUND_DYLIB
? 20
- : frame.command === 0x9
+ : frame.command === LC.FVMFILE
? 16
: 12;
if (offset < minimum || offset >= frame.size)
- throw new MachoBinaryFormatError(
+ throw malformedInput(
+ "macho",
"Mach-O command string offset is invalid",
);
commandString = await readString(
@@ -416,11 +447,13 @@ export const readMachoCommandNames = async (
);
const marker = view.getUint32(0, table.littleEndian);
const useEncoding =
- (frame.command === 0xc || frame.command === 0x80000018) &&
+ (frame.command === LC.LOAD_DYLIB ||
+ frame.command === LC.LOAD_WEAK_DYLIB) &&
offset === 28 &&
marker === 0x1a741800;
if (useEncoding && frame.size < 28)
- throw new MachoBinaryFormatError(
+ throw malformedInput(
+ "macho",
"Mach-O dylib use command is truncated",
);
const flags = useEncoding ? await exact(at + 24, 4) : undefined;
@@ -443,9 +476,10 @@ export const readMachoCommandNames = async (
}
}
let prebound: MachoCommandNames["commands"][number]["prebound"];
- if (frame.command === 0x10) {
+ if (frame.command === LC.PREBOUND_DYLIB) {
if (frame.size < 20)
- throw new MachoBinaryFormatError(
+ throw malformedInput(
+ "macho",
"Mach-O prebound dylib command is truncated",
);
const data = await exact(at + 12, 8);
@@ -454,7 +488,8 @@ export const readMachoCommandNames = async (
const linkedModulesOffset = view.getUint32(4, table.littleEndian);
const length = Math.ceil(moduleCount / 8);
if (linkedModulesOffset < 20 || linkedModulesOffset > frame.size - length)
- throw new MachoBinaryFormatError(
+ throw malformedInput(
+ "macho",
"Mach-O prebound module bitmap exceeds its command",
);
admitStringBytes(length);
@@ -465,9 +500,9 @@ export const readMachoCommandNames = async (
};
}
let fvmlib: MachoCommandNames["commands"][number]["fvmlib"];
- if (frame.command === 0x6 || frame.command === 0x7) {
+ if (frame.command === LC.LOADFVMLIB || frame.command === LC.IDFVMLIB) {
if (frame.size < 20)
- throw new MachoBinaryFormatError("Mach-O fvmlib command is truncated");
+ throw malformedInput("macho", "Mach-O fvmlib command is truncated");
const data = await exact(at + 12, 8);
const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
fvmlib = {
@@ -476,9 +511,9 @@ export const readMachoCommandNames = async (
};
}
let fvmfile: MachoCommandNames["commands"][number]["fvmfile"];
- if (frame.command === 0x9) {
+ if (frame.command === LC.FVMFILE) {
if (frame.size < 16)
- throw new MachoBinaryFormatError("Mach-O fvmfile command is truncated");
+ throw malformedInput("macho", "Mach-O fvmfile command is truncated");
const data = await exact(at + 12, 4);
fvmfile = {
headerAddress: new DataView(
@@ -489,9 +524,10 @@ export const readMachoCommandNames = async (
};
}
let linkerOptions: Uint8Array[] | undefined;
- if (frame.command === 0x2d) {
+ if (frame.command === LC.LINKER_OPTION) {
if (frame.size < 12)
- throw new MachoBinaryFormatError(
+ throw malformedInput(
+ "macho",
"Mach-O linker option count is truncated",
);
const countBytes = await exact(at + 8, 4);
@@ -503,7 +539,8 @@ export const readMachoCommandNames = async (
if (count > maximumRecords - records)
throw new MachoCommandNamesLimitError(maximumRecords, "records");
if (count > frame.size - 12)
- throw new MachoBinaryFormatError(
+ throw malformedInput(
+ "macho",
"Mach-O linker option table is truncated",
);
chargeProjection(count, PROJECTED_CHILD_BYTES);
@@ -539,14 +576,14 @@ export const readMachoCommandNames = async (
}
}
if (linkerOptions.length !== count)
- throw new MachoBinaryFormatError(
- "Mach-O linker option is unterminated",
- );
+ throw malformedInput("macho", "Mach-O linker option is unterminated");
}
let legacyBuild: MachoCommandNames["commands"][number]["legacyBuild"];
- if ([0x24, 0x25, 0x2f, 0x30].includes(frame.command)) {
+ const legacyPlatform = MACHO_VERSION_MIN_PLATFORMS.get(frame.command);
+ if (legacyPlatform !== undefined) {
if (frame.size < 16)
- throw new MachoBinaryFormatError(
+ throw malformedInput(
+ "macho",
"Mach-O minimum version command is truncated",
);
const bytes = await exact(at + 8, 8);
@@ -556,14 +593,15 @@ export const readMachoCommandNames = async (
bytes.byteLength,
);
legacyBuild = {
+ platform: legacyPlatform,
version: view.getUint32(0, table.littleEndian),
sdk: view.getUint32(4, table.littleEndian),
};
}
let note: MachoCommandNames["commands"][number]["note"];
- if (frame.command === 0x31) {
+ if (frame.command === LC.NOTE) {
if (frame.size < 40)
- throw new MachoBinaryFormatError("Mach-O note command is truncated");
+ throw malformedInput("macho", "Mach-O note command is truncated");
const data = await exact(at + 8, 32);
const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
note = {
@@ -575,14 +613,15 @@ export const readMachoCommandNames = async (
let fileset: MachoCommandNames["commands"][number]["fileset"];
let filesetStringStartsAfterHeader = false;
let filesetStringEnd: number | undefined;
- if (frame.command === 0x80000035) {
+ if (frame.command === LC.FILESET_ENTRY) {
if (frame.size < 32)
- throw new MachoBinaryFormatError("Mach-O fileset command is truncated");
+ throw malformedInput("macho", "Mach-O fileset command is truncated");
const data = await exact(at + 8, 24);
const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
const offset = view.getUint32(16, table.littleEndian);
if (offset < 32 || offset >= frame.size)
- throw new MachoBinaryFormatError(
+ throw malformedInput(
+ "macho",
"Mach-O fileset entry string offset is invalid",
);
filesetStringStartsAfterHeader = offset === 32;
@@ -600,17 +639,15 @@ export const readMachoCommandNames = async (
filesetStringEnd = offset + entryId.byteLength + 1;
}
let uuid: Uint8Array | undefined;
- if (frame.command === 0x1b) {
+ if (frame.command === LC.UUID) {
if (frame.size < 24)
- throw new MachoBinaryFormatError("Mach-O UUID command is truncated");
+ throw malformedInput("macho", "Mach-O UUID command is truncated");
uuid = Uint8Array.from(await exact(at + 8, 16));
}
let entrypoint: MachoCommandNames["commands"][number]["entrypoint"];
- if (frame.command === 0x80000028) {
+ if (frame.command === LC.MAIN) {
if (frame.size < 24)
- throw new MachoBinaryFormatError(
- "Mach-O entrypoint command is truncated",
- );
+ throw malformedInput("macho", "Mach-O entrypoint command is truncated");
const bytes = await exact(at + 8, 16);
const view = new DataView(
bytes.buffer,
@@ -623,9 +660,10 @@ export const readMachoCommandNames = async (
};
}
let build: MachoCommandNames["commands"][number]["build"];
- if (frame.command === 0x32) {
+ if (frame.command === LC.BUILD_VERSION) {
if (frame.size < 24)
- throw new MachoBinaryFormatError(
+ throw malformedInput(
+ "macho",
"Mach-O build version command is truncated",
);
const header = await exact(at + 8, 16);
@@ -636,9 +674,7 @@ export const readMachoCommandNames = async (
);
const toolCount = view.getUint32(12, table.littleEndian);
if (toolCount > Math.floor((frame.size - 24) / 8))
- throw new MachoBinaryFormatError(
- "Mach-O build tool table is truncated",
- );
+ throw malformedInput("macho", "Mach-O build tool table is truncated");
if (toolCount > maximumRecords - records)
throw new MachoCommandNamesLimitError(maximumRecords, "records");
chargeProjection(toolCount, PROJECTED_CHILD_BYTES);
@@ -724,7 +760,7 @@ export const readMachoCommandNames = async (
});
}
const end = cursor.finish();
- if (!end.ok) throw new MachoBinaryFormatError(end.error);
+ if (!end.ok) throw malformedInput("macho", end.error);
return {
sliceSize: imageSize,
header: {
diff --git a/src/native/NativeMacOSProvider.ts b/src/native/NativeMacOSProvider.ts
index e3032b0c43..f8de9fad16 100644
--- a/src/native/NativeMacOSProvider.ts
+++ b/src/native/NativeMacOSProvider.ts
@@ -152,8 +152,8 @@ import {
withNativeMachoSource,
NativeMachoSourceVerificationFailure,
} from "./NativeMachoSource.js";
+import { parseFailureAnalysisError } from "../domain/parseFailureAnalysisError.js";
import {
- MachoBinaryFormatError,
MachoCommandNamesLimitError,
readMachoCommandNames,
} from "./MachoCommandNames.js";
@@ -1729,8 +1729,6 @@ const nativeMachoSourcePrimary = (
operation: "inspect_macho" | "list_architectures",
): AnalysisError => {
if (cause instanceof AnalysisError) return cause;
- if (cause instanceof MachoBinaryFormatError)
- return new AnalysisOutputError(operation, cause.message, { cause });
if (cause instanceof MachoCommandNamesLimitError)
return new AnalysisResourceConstraintError(
operation,
@@ -1739,6 +1737,9 @@ const nativeMachoSourcePrimary = (
{ maximum: cause.maximum, unit: cause.unit },
{ cause, retryable: false },
);
+ // The selected Mach-O's own bytes failed to parse; a limit falls through.
+ const formatFailure = parseFailureAnalysisError(operation, path, cause);
+ if (formatFailure !== undefined) return formatFailure;
const completed =
cause instanceof NativeMachoSourceVerificationFailure
? cause.completed
diff --git a/src/native/NativeMachoSelectedSlice.ts b/src/native/NativeMachoSelectedSlice.ts
index 2ec689d507..51d3c736fe 100644
--- a/src/native/NativeMachoSelectedSlice.ts
+++ b/src/native/NativeMachoSelectedSlice.ts
@@ -5,8 +5,8 @@ import {
validateFatSlice,
type FatSliceDeclaration,
} from "../domain/apple/machoContainer.js";
+import { malformedInput } from "../domain/parseFailure.js";
import {
- MachoBinaryFormatError,
MachoCommandNamesLimitError,
type MachoCommandNames,
} from "./MachoCommandNames.js";
@@ -30,14 +30,16 @@ export const resolveSelectedMachoSlice = async (
selected.cpu_type_code === null &&
(selected.file_offset === null || selected.size === null)
)
- throw new MachoBinaryFormatError(
+ throw malformedInput(
+ "macho",
"Selected Mach-O slice CPU identity is unavailable",
);
const prefix = readFatHeaderPrefix(
await source.readSlice(0, source.bytes, 0, Math.min(8, source.bytes)),
);
if (prefix.state !== "parsed")
- throw new MachoBinaryFormatError(
+ throw malformedInput(
+ "macho",
"Selected Mach-O universal header is unavailable",
);
const rows = prefix.count + (selected.hidden ? 1 : 0);
@@ -46,7 +48,8 @@ export const resolveSelectedMachoSlice = async (
const entrySize = prefix.wide ? 32 : 20;
const tableEnd = 8 + rows * entrySize;
if (!Number.isSafeInteger(tableEnd) || tableEnd > source.bytes)
- throw new MachoBinaryFormatError(
+ throw malformedInput(
+ "macho",
"Selected Mach-O universal table is truncated",
);
const matches: FatSliceDeclaration[] = [];
@@ -65,7 +68,7 @@ export const resolveSelectedMachoSlice = async (
littleEndian: prefix.littleEndian,
});
if (parsed.status !== "parsed")
- throw new MachoBinaryFormatError(parsed.reason);
+ throw malformedInput("macho", parsed.reason);
for (const row of parsed.slices) {
declarations.push(row);
if (
@@ -86,7 +89,8 @@ export const resolveSelectedMachoSlice = async (
}
}
if (matches.length !== 1)
- throw new MachoBinaryFormatError(
+ throw malformedInput(
+ "macho",
"Selected lipo slice does not identify exactly one FAT entry",
);
const declaration = matches[0]!;
@@ -98,7 +102,8 @@ export const resolveSelectedMachoSlice = async (
declaration.offset < row.offset + row.size,
)
)
- throw new MachoBinaryFormatError(
+ throw malformedInput(
+ "macho",
"Selected Mach-O slice overlaps another FAT entry",
);
return {
@@ -121,5 +126,5 @@ export const assertSelectedMachoSlice = (
selected.tableEnd,
binary.header,
);
- if (failure !== null) throw new MachoBinaryFormatError(failure);
+ if (failure !== null) throw malformedInput("macho", failure);
};
diff --git a/src/native/NativeMachoSourceProvider.test.ts b/src/native/NativeMachoSourceProvider.test.ts
index e8f034cfd8..cff5ef9108 100644
--- a/src/native/NativeMachoSourceProvider.test.ts
+++ b/src/native/NativeMachoSourceProvider.test.ts
@@ -463,7 +463,7 @@ it.each([
["truncated fixed fields", "Mach-O fixed command fields are truncated", 1],
["invalid string offset", "Mach-O command string offset is invalid", 2],
] as const)(
- "reports malformed binary %s as output failure with its reason",
+ "reports malformed binary %s as invalid input with its reason",
async (_case, reason, mode) => {
const { machoImage, dylibCommand, LC } =
await import("../artifacts/apple/MachoImage.fixture.js");
@@ -486,9 +486,16 @@ it.each([
try {
const result = await client.execute("inspect_macho", {});
if (result.ok) throw new Error("Expected malformed input refusal");
- expect(projectAnalysisError(result.error)).toMatchObject({
- code: "unreadable_output",
- details: { operation: "inspect_macho", reason },
+ expect(result.error).toMatchObject({
+ _tag: "AnalysisInputError",
+ operation: "inspect_macho",
+ issues: [
+ {
+ path: ["path"],
+ reason: "invalid_format",
+ message: `Selected artifact ${path}: ${reason}`,
+ },
+ ],
});
} finally {
await client.close();
diff --git a/src/native/metadata/MachoImage.ts b/src/native/metadata/MachoImage.ts
index c0bc408748..23c5690f19 100644
--- a/src/native/metadata/MachoImage.ts
+++ b/src/native/metadata/MachoImage.ts
@@ -1,3 +1,4 @@
+import { LC } from "../../domain/apple/machoLoadCommandCodes.js";
import type {
FileMapping,
ZeroFillMapping,
@@ -53,9 +54,9 @@ export const readMachoImage = (bytes: Buffer): BinaryContainer => {
const frame = commands.read(bytes.subarray(offset, offset + 8));
if (!frame.ok) throw new BinaryFormatFailure("malformed", frame.error);
const { command, size } = frame.value;
- if (command === 0x80000034) chainedFixups = true;
- if (command === 1 || command === 0x19) {
- const wide = command === 0x19;
+ if (command === LC.DYLD_CHAINED_FIXUPS) chainedFixups = true;
+ if (command === LC.SEGMENT || command === LC.SEGMENT_64) {
+ const wide = command === LC.SEGMENT_64;
if (wide !== (bits === 64))
throw new BinaryFormatFailure(
"malformed",
diff --git a/src/native/parsers/plist.ts b/src/native/parsers/plist.ts
index 7ddeb0b1cf..3534f1baa8 100644
--- a/src/native/parsers/plist.ts
+++ b/src/native/parsers/plist.ts
@@ -23,6 +23,7 @@ import {
PlistNestingLimitError,
} from "../../domain/apple/plistValue.js";
import { parseXmlPropertyList } from "../../domain/propertyListKeys.js";
+import { malformedInput } from "../../domain/parseFailure.js";
import { err, ok, type Result } from "../../domain/result.js";
import {
@@ -34,8 +35,8 @@ import {
import { UnsupportedBinaryPlistUidError } from "../../artifacts/apple/PlistScalars.js";
import {
estimateBinaryPlistExpansion,
+ isPlistDecodeBudgetFailure,
preflightPropertyListDecode,
- PropertyListDecodeBudgetFailure,
} from "../../artifacts/apple/PropertyListDecodeBudget.js";
import { hasBinaryPlistSignature } from "../../domain/apple/appleArchiveFormat.js";
import {
@@ -110,6 +111,24 @@ const plistNestingError = (cause: unknown): AnalysisResourceConstraintError =>
},
);
+const plistDecodeBudgetError = (
+ cause: Error,
+ encoding: "XML" | "binary",
+): AnalysisResourceConstraintError =>
+ new AnalysisResourceConstraintError(
+ "inspect_plist",
+ "memory",
+ cause.message,
+ { maximum_decoded_bytes: MAX_NATIVE_PLIST_DECODE_BYTES },
+ {
+ cause,
+ ...fixedAllowanceOptions(
+ `The ${mebibytes(MAX_NATIVE_PLIST_DECODE_BYTES)} (${String(MAX_NATIVE_PLIST_DECODE_BYTES)}-byte) native ${encoding} plist decode allowance (no runtime override)`,
+ "parser",
+ ),
+ },
+ );
+
const plistOutputError = (cause: unknown, reason?: string): PlistParseError =>
cause instanceof PlistNestingLimitError
? plistNestingError(cause)
@@ -287,22 +306,8 @@ export const parsePlistXmlSource = (
return projectPlistXml(text);
} catch (cause: unknown) {
if (cause instanceof XmlPlistTextDecodeError) return err(cause);
- if (cause instanceof PropertyListDecodeBudgetFailure)
- return err(
- new AnalysisResourceConstraintError(
- "inspect_plist",
- "memory",
- cause.message,
- { maximum_decoded_bytes: MAX_NATIVE_PLIST_DECODE_BYTES },
- {
- cause,
- ...fixedAllowanceOptions(
- `The ${mebibytes(MAX_NATIVE_PLIST_DECODE_BYTES)} (${String(MAX_NATIVE_PLIST_DECODE_BYTES)}-byte) native XML plist decode allowance (no runtime override)`,
- "parser",
- ),
- },
- ),
- );
+ if (isPlistDecodeBudgetFailure(cause))
+ return err(plistDecodeBudgetError(cause, "XML"));
return err(plistOutputError(cause));
}
};
@@ -366,7 +371,10 @@ export const parsePlistBinary = (
> => {
try {
if (!hasBinaryPlistSignature(bytes))
- throw new TypeError("selected file does not have a binary plist header");
+ throw malformedInput(
+ "plist",
+ "selected file does not have a binary plist header",
+ );
const expansion = estimateBinaryPlistExpansion(
bytes,
MAX_NATIVE_PLIST_DECODE_BYTES,
@@ -375,12 +383,6 @@ export const parsePlistBinary = (
numberProjection: true,
uidProjection: true,
maximumDepth: MAX_NATIVE_PLIST_NESTING_DEPTH,
- fail: (kind, message) =>
- kind === "cycle"
- ? new TypeError(
- "binary plist object references form a cycle, which a property list cannot represent",
- )
- : new PropertyListDecodeBudgetFailure(kind, message),
},
);
const decoded = decodeBinaryPropertyList(bytes, expansion);
@@ -409,28 +411,10 @@ export const parsePlistBinary = (
});
} catch (cause: unknown) {
if (cause instanceof UnsupportedBinaryPlistUidError) return err(cause);
- if (
- cause instanceof PlistNestingLimitError ||
- (cause instanceof PropertyListDecodeBudgetFailure &&
- cause.kind === "depth")
- )
+ if (cause instanceof PlistNestingLimitError)
return err(plistNestingError(cause));
- if (cause instanceof PropertyListDecodeBudgetFailure)
- return err(
- new AnalysisResourceConstraintError(
- "inspect_plist",
- "memory",
- cause.message,
- { maximum_decoded_bytes: MAX_NATIVE_PLIST_DECODE_BYTES },
- {
- cause,
- ...fixedAllowanceOptions(
- `The ${mebibytes(MAX_NATIVE_PLIST_DECODE_BYTES)} (${String(MAX_NATIVE_PLIST_DECODE_BYTES)}-byte) native binary plist decode allowance (no runtime override)`,
- "parser",
- ),
- },
- ),
- );
+ if (isPlistDecodeBudgetFailure(cause))
+ return err(plistDecodeBudgetError(cause, "binary"));
return err(
new AnalysisOutputError(
"inspect_plist",
diff --git a/src/process/Utf8NdjsonLineBuffer.test.ts b/src/process/Utf8NdjsonLineBuffer.test.ts
index 967f929d7c..871ccaf820 100644
--- a/src/process/Utf8NdjsonLineBuffer.test.ts
+++ b/src/process/Utf8NdjsonLineBuffer.test.ts
@@ -1,26 +1,35 @@
import { describe, expect, it, vi } from "vitest";
+import { ParseFailureError } from "../domain/parseFailure.js";
+import { ok } from "../domain/result.js";
import { Utf8NdjsonLineBuffer } from "./Utf8NdjsonLineBuffer.js";
+const texts = (lines: Iterable<{ ok: boolean; value?: string }>): string[] =>
+ Array.from(lines, (line) => {
+ if (!line.ok || line.value === undefined)
+ throw new Error("expected a decoded line");
+ return line.value;
+ });
+
describe("UTF-8 NDJSON line buffer", () => {
it("drains complete buffered lines on an empty push after iteration stops", () => {
const lines = new Utf8NdjsonLineBuffer();
const iterator = lines.push(Buffer.from("first\nsecond\nthird\npartial"));
- expect(iterator.next()).toEqual({ value: "first", done: false });
+ expect(iterator.next()).toEqual({ value: ok("first"), done: false });
iterator.return(undefined);
- expect([...lines.push(Buffer.from(""))]).toEqual(["second", "third"]);
- expect([...lines.push(Buffer.from(" line\n"))]).toEqual(["partial line"]);
+ expect(texts(lines.push(Buffer.from("")))).toEqual(["second", "third"]);
+ expect(texts(lines.push(Buffer.from(" line\n")))).toEqual(["partial line"]);
});
it("joins fragments and yields trimmed nonblank complete lines", () => {
const lines = new Utf8NdjsonLineBuffer();
- expect([...lines.push(Buffer.from(" first "))]).toEqual([]);
- expect([
- ...lines.push(Buffer.from("\n \t\n second \n unfinished")),
- ]).toEqual(["first", "second"]);
- expect([...lines.push(Buffer.from(" line\n"))]).toEqual([
+ expect(texts(lines.push(Buffer.from(" first ")))).toEqual([]);
+ expect(
+ texts(lines.push(Buffer.from("\n \t\n second \n unfinished"))),
+ ).toEqual(["first", "second"]);
+ expect(texts(lines.push(Buffer.from(" line\n")))).toEqual([
"unfinished line",
]);
});
@@ -46,13 +55,42 @@ describe("UTF-8 NDJSON line buffer", () => {
}
});
+ it("yields a line that is not UTF-8 as a malformed parse failure and stops", () => {
+ const lines = new Utf8NdjsonLineBuffer();
+ const yielded = Array.from(
+ lines.push(Buffer.from([0x61, 0x0a, 0xff, 0x0a, 0x62, 0x0a])),
+ );
+ expect(yielded).toHaveLength(2);
+ expect(yielded[0]).toEqual(ok("a"));
+ const failure = yielded[1];
+ expect(failure?.ok).toBe(false);
+ if (failure === undefined || failure.ok) return;
+ expect(failure.error).toBeInstanceOf(ParseFailureError);
+ expect(failure.error.failure).toMatchObject({
+ kind: "malformed",
+ format: "ndjson",
+ });
+ expect(texts(lines.push(Buffer.alloc(0)))).toEqual(["b"]);
+ });
+
+ it("reports an unfinished tail that is not UTF-8 at EOF", () => {
+ const lines = new Utf8NdjsonLineBuffer();
+ expect(texts(lines.push(Buffer.from([0x61, 0x0a, 0xff])))).toEqual(["a"]);
+ const tail = lines.finish();
+ expect(tail.ok).toBe(false);
+ if (tail.ok) return;
+ expect(tail.error.kind).toBe("malformed");
+ lines.reset();
+ expect(lines.finish()).toEqual(ok(null));
+ });
+
it("retains unconsumed complete lines and reset discards them", () => {
const lines = new Utf8NdjsonLineBuffer();
const iterator = lines.push(Buffer.from('invalid\n{"id":2}\n'));
- expect(iterator.next()).toEqual({ value: "invalid", done: false });
+ expect(iterator.next()).toEqual({ value: ok("invalid"), done: false });
iterator.return(undefined);
- expect([...lines.push(Buffer.from('{"id":3}\n'))]).toEqual([
+ expect(texts(lines.push(Buffer.from('{"id":3}\n')))).toEqual([
'{"id":2}',
'{"id":3}',
]);
@@ -60,10 +98,13 @@ describe("UTF-8 NDJSON line buffer", () => {
const nextIterator = lines.push(
Buffer.from("discard me\nwill also be discarded\nkeep partial"),
);
- expect(nextIterator.next()).toEqual({ value: "discard me", done: false });
+ expect(nextIterator.next()).toEqual({
+ value: ok("discard me"),
+ done: false,
+ });
nextIterator.return(undefined);
lines.reset();
- expect([...lines.push(Buffer.from("after reset\n"))]).toEqual([
+ expect(texts(lines.push(Buffer.from("after reset\n")))).toEqual([
"after reset",
]);
});
@@ -72,13 +113,13 @@ describe("UTF-8 NDJSON line buffer", () => {
const lines = new Utf8NdjsonLineBuffer();
const frame = Buffer.alloc(64 * 1024, 0x78);
frame[frame.length - 1] = 0x0a;
- expect([...lines.push(frame)]).toEqual([
+ expect(texts(lines.push(frame))).toEqual([
frame.subarray(0, frame.length - 1).toString("utf8"),
]);
expect(lines.retainedTail()).toEqual({ pendingBytes: 0, backingBytes: 0 });
const tail = Buffer.from("next");
- expect([...lines.push(tail)]).toEqual([]);
+ expect(texts(lines.push(tail))).toEqual([]);
expect(lines.retainedTail()).toEqual({
pendingBytes: tail.length,
backingBytes: tail.buffer.byteLength,
diff --git a/src/process/Utf8NdjsonLineBuffer.ts b/src/process/Utf8NdjsonLineBuffer.ts
index dff5636585..db46d5e4f4 100644
--- a/src/process/Utf8NdjsonLineBuffer.ts
+++ b/src/process/Utf8NdjsonLineBuffer.ts
@@ -1,9 +1,11 @@
-/** A byte decoding failure, separate from exceptions raised by a line consumer. */
-export class Utf8NdjsonDecodingError extends Error {
- constructor(cause: unknown) {
- super("NDJSON frame is not valid UTF-8", { cause });
- }
-}
+import {
+ malformedInput,
+ type ParseFailureError,
+} from "../domain/parseFailure.js";
+import { err, ok, type Result } from "../domain/result.js";
+
+/** A frame that is not UTF-8; a value, so it cannot be confused with a consumer's exception. */
+type Utf8NdjsonLine = Result>;
/** Frame socket bytes before decoding, so later malformed frames cannot erase earlier lines. */
export class Utf8NdjsonLineBuffer {
@@ -15,8 +17,12 @@ export class Utf8NdjsonLineBuffer {
ignoreBOM: true,
});
- /** Yield each complete trimmed nonblank line; preserve unconsumed lines on early return. */
- *push(chunk: Buffer): Generator {
+ /**
+ * Yield each complete trimmed nonblank line; preserve unconsumed lines on
+ * early return. A line that is not UTF-8 is yielded as a failure and ends
+ * the iteration.
+ */
+ *push(chunk: Buffer): Generator {
this.#fragments.push(chunk);
if (!chunk.includes(10) && this.#nextNewline < 0) return;
this.#buffer = Buffer.concat([this.#buffer, ...this.#fragments]);
@@ -28,22 +34,32 @@ export class Utf8NdjsonLineBuffer {
// An empty view would keep the drained frame's allocation for the session.
this.#buffer = rest.length === 0 ? Buffer.alloc(0) : rest;
this.#nextNewline = this.#buffer.indexOf(10);
- const line = this.#decode(encodedLine).trim();
- if (line.length > 0) yield line;
+ const line = this.#decode(encodedLine);
+ if (!line.ok) {
+ yield line;
+ return;
+ }
+ const trimmed = line.value.trim();
+ if (trimmed.length > 0) yield ok(trimmed);
}
}
/** Validate the unfinished tail at EOF without treating it as a complete response. */
- finish(): void {
- this.#decode(Buffer.concat([this.#buffer, ...this.#fragments]));
+ finish(): Result> {
+ const tail = this.#decode(
+ Buffer.concat([this.#buffer, ...this.#fragments]),
+ );
+ return tail.ok ? ok(null) : tail;
}
- #decode(bytes: Buffer): string {
+ #decode(bytes: Buffer): Utf8NdjsonLine {
try {
- return this.#decoder.decode(bytes);
+ return ok(this.#decoder.decode(bytes));
} catch (cause: unknown) {
if (!(cause instanceof TypeError)) throw cause;
- throw new Utf8NdjsonDecodingError(cause);
+ return err(
+ malformedInput("ndjson", "NDJSON frame is not valid UTF-8", { cause }),
+ );
}
}
diff --git a/tests/boundary/filesystem/keyedArchiveXmlNesting.test.ts b/tests/boundary/filesystem/keyedArchiveXmlNesting.test.ts
index 51072ebc24..17476f71af 100644
--- a/tests/boundary/filesystem/keyedArchiveXmlNesting.test.ts
+++ b/tests/boundary/filesystem/keyedArchiveXmlNesting.test.ts
@@ -49,7 +49,7 @@ it.each([
expect(rejected).toMatchObject({
reason: "format",
cause: {
- _tag: "OpenStepPropertyListError",
+ name: "OpenStepPropertyListError",
code,
position,
},
diff --git a/tests/boundary/filesystem/keyedArchiveXmlSyntax.test.ts b/tests/boundary/filesystem/keyedArchiveXmlSyntax.test.ts
index 90c33c25fe..0b17cc0594 100644
--- a/tests/boundary/filesystem/keyedArchiveXmlSyntax.test.ts
+++ b/tests/boundary/filesystem/keyedArchiveXmlSyntax.test.ts
@@ -43,7 +43,7 @@ it.each([
}),
).rejects.toMatchObject({
reason: "format",
- cause: { _tag: "XmlDocumentParseError", reason: "malformed" },
+ cause: { _tag: "ParseFailureError", kind: "malformed" },
});
});
diff --git a/tests/boundary/providers/kuna/kunaSpanCloseOwnership.test.ts b/tests/boundary/providers/kuna/kunaSpanCloseOwnership.test.ts
index 94019d817c..7e81f67fe0 100644
--- a/tests/boundary/providers/kuna/kunaSpanCloseOwnership.test.ts
+++ b/tests/boundary/providers/kuna/kunaSpanCloseOwnership.test.ts
@@ -145,7 +145,8 @@ it.each([
if (handle === undefined) throw new Error("missing span descriptor");
if (short) {
expect(result.error.cleanupPrimary?.cause).toMatchObject({
- _tag: "KunaDocumentError",
+ name: "KunaDocumentError",
+ kind: "truncated",
code: "span_short",
});
expect(result.error.diagnostics?.span_read).toBeUndefined();
diff --git a/tests/boundary/providers/native/nativePlistBinarySource.test.ts b/tests/boundary/providers/native/nativePlistBinarySource.test.ts
index 81a7c3eaf7..0a0f0f1902 100644
--- a/tests/boundary/providers/native/nativePlistBinarySource.test.ts
+++ b/tests/boundary/providers/native/nativePlistBinarySource.test.ts
@@ -95,7 +95,7 @@ it.each([
{
budget: "nesting",
value: nested(MAX_JSON_DEPTH - 1),
- reason: /binary plist nesting.*decode budget/iu,
+ reason: /plist exceeds 997 nesting levels/iu,
limits: { maximum_nesting_depth: MAX_JSON_DEPTH - 3 },
allowance: /997-level.*plist nesting.*no runtime override/iu,
},
diff --git a/tests/boundary/providers/native/nativeSelectedArchitecture.test.ts b/tests/boundary/providers/native/nativeSelectedArchitecture.test.ts
index 6abfb67353..a25ab8b6f3 100644
--- a/tests/boundary/providers/native/nativeSelectedArchitecture.test.ts
+++ b/tests/boundary/providers/native/nativeSelectedArchitecture.test.ts
@@ -343,9 +343,18 @@ it.each([
);
expect(result.ok).toBe(false);
if (result.ok) throw new Error("Mismatched FAT slice was admitted");
- expect(result.error.message).toContain(
- "Selected lipo slice does not identify exactly one FAT entry",
- );
+ expect(result.error).toMatchObject({
+ _tag: "AnalysisInputError",
+ issues: [
+ {
+ path: ["path"],
+ reason: "invalid_format",
+ message: expect.stringContaining(
+ "Selected lipo slice does not identify exactly one FAT entry",
+ ),
+ },
+ ],
+ });
},
);
diff --git a/tests/boundary/providers/native/objcClassMetadataFallback.test.ts b/tests/boundary/providers/native/objcClassMetadataFallback.test.ts
index d3df378ae6..6f6d5cff50 100644
--- a/tests/boundary/providers/native/objcClassMetadataFallback.test.ts
+++ b/tests/boundary/providers/native/objcClassMetadataFallback.test.ts
@@ -10,10 +10,7 @@ import type {
} from "../../../../src/application/AnalysisProvider.js";
import { createAnalysisExecution } from "../../../../src/application/AnalysisProvider.js";
import { EnhancedTools } from "../../../../src/application/EnhancedTools.js";
-import {
- UnsupportedMachoMetadataFormatError,
- parseMachoLayout,
-} from "../../../../src/native/AppleMachoSelection.js";
+import { parseMachoLayout } from "../../../../src/native/AppleMachoSelection.js";
import { NativeMacOSProvider } from "../../../../src/native/NativeMacOSProvider.js";
import { BinaryFormatFailure } from "../../../../src/native/metadata/BinaryContainer.js";
import { NativeFixtureRunner } from "../../../fixtures/nativeCommands.js";
@@ -121,7 +118,11 @@ describe("native Objective-C class metadata capability fallback", () => {
} catch (cause: unknown) {
failure = cause;
}
- expect(failure).toBeInstanceOf(UnsupportedMachoMetadataFormatError);
+ expect(failure).toBeInstanceOf(BinaryFormatFailure);
+ expect(failure).toMatchObject({
+ kind: "unsupported",
+ undecodedContent: true,
+ });
});
it("keeps truncated 32-bit and 64-bit headers as errors", async () => {
@@ -163,7 +164,11 @@ describe("native Objective-C class metadata capability fallback", () => {
} catch (cause: unknown) {
failure = cause;
}
- expect(failure).toBeInstanceOf(UnsupportedMachoMetadataFormatError);
+ expect(failure).toBeInstanceOf(BinaryFormatFailure);
+ expect(failure).toMatchObject({
+ kind: "unsupported",
+ undecodedContent: true,
+ });
bytes.writeUInt32BE(0x01000007, 4);
let mismatchedCpuFailure: unknown;
@@ -174,8 +179,6 @@ describe("native Objective-C class metadata capability fallback", () => {
}
expect(mismatchedCpuFailure).toBeInstanceOf(BinaryFormatFailure);
expect(mismatchedCpuFailure).toMatchObject({ kind: "unsupported" });
- expect(mismatchedCpuFailure).not.toBeInstanceOf(
- UnsupportedMachoMetadataFormatError,
- );
+ expect(mismatchedCpuFailure).toMatchObject({ undecodedContent: false });
});
});