From 78fd365bddcf33f86853a97874ed0a5c3e0184e7 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Sun, 15 Nov 2026 18:24:35 +0800 Subject: [PATCH] refactor(macho): name load-command codes through the shared LC table (#10714) * refactor(macho): name load-command codes through the shared LC table * refactor(macho): name version-min and string commands through the shared tables * refactor(parsers): report XML, web artifact and Mach-O failures through ParseFailure (#10760) * refactor(parsers): report XML, web artifact and Mach-O failures through ParseFailure * refactor(xml): type XML parse failures as malformed or unsupported only * refactor(parsers): catch per-format document and source failure classes (#10794) * refactor(parsers): report apktool strings and XML plist source failures through ParseFailure * refactor(apktool): drop the unused ParseFailureError import * refactor(parsers): retire the Mach-O, source-map, NDJSON and managed-graph failure classes (#10818) * refactor(parsers): retire the Mach-O, source-map, NDJSON and managed-graph failure classes * refactor(plist): report property-list and keyed-archive failures through ParseFailure (#10822) * refactor(plist): report property-list and keyed-archive failures through ParseFailure * refactor(kuna): report Kuna document failures through ParseFailure (#10824) * refactor(kuna): report Kuna document failures through ParseFailure * test(kuna): pin the limit and malformed facts of Kuna document failures * refactor(plist): report plist decode budgets through ParseFailure (#10842) * refactor(plist): report plist decode budgets through ParseFailure The plist preflight owner throws a ParseFailure limit (plist-decode-bytes) for its byte budget, the shared PlistNestingLimitError for nesting depth, and a malformed failure for a reference cycle, instead of a per-format PropertyListDecodeBudgetFailure whose meaning each caller re-mapped through a fail callback. The fail option, PropertyListDecodeBudgetFailure and interfaceBuilderDecodeBudgetFailure are removed; the parser-format-failure-class baseline reaches zero. * refactor(plist): report keyed-archive allowances as typed limit failures (#10844) keyedArchive.ts and decodeKeyedArchiveBytes throw decodeLimit parse failures (keyed-archive-bytes, -object-table-entries, -values-per-object, -reference-edges) and malformed parse failures instead of plain RangeError/TypeError. KeyedArchiveReader no longer classifies every RangeError as a limit: only a limit parse failure or a host stack/capacity limit is one. The unreachable 128-level scan nesting check is removed; projectPlistValue already refuses the archive first. * test(plist): expect the nesting limit as its ParseFailure carrier * refactor(plist): report plist and NIBArchive input faults through ParseFailure and defects through invariantViolation (#10895) * refactor(plist): report plist and NIBArchive input faults through ParseFailure and defects through invariantViolation * fix(plist): report a cut-short NIB header or plist length record as truncated * fix(native): project the selected Mach-O's parse failures through the shared owner nativeMachoSourcePrimary mapped every non-limit ParseFailureError to AnalysisOutputError, so a malformed or truncated selected Mach-O was reported as unreadable tool output and an unsupported one lost its category. It now uses parseFailureAnalysisError like the ELF, Go and other byte-format providers: malformed and truncated bytes are an invalid path, unsupported bytes an unsupported target, and a limit still falls through to its producer's budget. --- .../verify/architecture-guard-baselines.json | 19 +- scripts/verify/architecture-guards.mjs | 30 ++- src/android/AndroidManifestComponents.ts | 2 +- src/apktool/ApktoolDecodeOutput.test.ts | 21 +- src/apktool/ApktoolDecodeOutput.ts | 33 +-- .../apple/BinaryPlistMaterializer.test.ts | 12 + .../apple/BinaryPlistMaterializer.ts | 12 +- .../apple/InterfaceBuilderAnalysis.ts | 17 +- .../InterfaceBuilderDecodeBudget.test.ts | 25 ++- .../apple/InterfaceBuilderDecodeBudget.ts | 10 - .../apple/KeyedArchiveReader.test.ts | 23 +- src/artifacts/apple/KeyedArchiveReader.ts | 27 ++- src/artifacts/apple/MachoLoadCommandReader.ts | 137 ++++++------ src/artifacts/apple/NibArchive.test.ts | 32 +++ src/artifacts/apple/NibArchive.ts | 89 ++++++-- src/artifacts/apple/PlistScalars.test.ts | 40 +++- src/artifacts/apple/PlistScalars.ts | 29 ++- .../apple/PropertyListDecodeBudget.ts | 211 ++++++++++++------ src/browser/WebSourceMapFetcher.test.ts | 20 ++ src/browser/WebSourceMapFetcher.ts | 57 +++-- src/browser/assets/WebArtifactReads.ts | 28 ++- src/browser/history/SazMetadata.ts | 4 +- .../apple/interfaceBuilderKeyedArchive.ts | 4 +- src/domain/apple/keyedArchive.test.ts | 10 +- src/domain/apple/keyedArchive.ts | 73 +++++- src/domain/apple/machoDylibCommand.ts | 11 +- src/domain/apple/machoLoadCommandCodes.ts | 3 + src/domain/apple/machoLoadCommands.ts | 40 ++-- src/domain/apple/machoPlatform.ts | 13 ++ src/domain/apple/plistValue.test.ts | 7 +- src/domain/apple/plistValue.ts | 20 +- src/domain/internalInvariant.ts | 21 ++ src/domain/managed/managedApplicationGraph.ts | 27 ++- src/domain/propertyListKeys.test.ts | 5 +- src/domain/propertyListOpenStep.test.ts | 10 +- src/domain/propertyListOpenStep.ts | 7 +- src/domain/propertyListXmlData.test.ts | 2 +- src/domain/propertyListXmlData.ts | 24 +- src/domain/propertyListXmlSource.ts | 20 +- src/domain/propertyListXmlText.test.ts | 1 + src/domain/propertyListXmlText.ts | 24 +- src/domain/xmlDocument.test.ts | 14 +- src/domain/xmlDocument.ts | 93 ++++---- src/ghidra/GhidraClient.ts | 26 +-- src/ghidra/GhidraResponseRouter.test.ts | 2 +- src/hopper/HopperClient.ts | 15 +- src/hopper/HopperResponseStream.ts | 14 +- src/il2cpp/Il2cppBinaryImage.ts | 10 +- src/kuna/KunaDocumentError.ts | 47 +++- src/kuna/KunaInventoryPlacement.ts | 14 +- src/kuna/KunaJson.test.ts | 45 ++++ src/kuna/KunaJson.ts | 2 +- src/kuna/KunaJsonStream.ts | 2 +- src/kuna/KunaReferenceFiles.ts | 2 +- src/kuna/KunaTargetCommands.ts | 7 +- src/native/AppleDispatchMetadata.ts | 17 +- src/native/AppleMachoSelection.test.ts | 9 +- src/native/AppleMachoSelection.ts | 26 ++- src/native/MachoBinaryProjection.test.ts | 2 +- src/native/MachoBinaryProjection.ts | 59 ++--- src/native/MachoCommandNames.test.ts | 1 + src/native/MachoCommandNames.ts | 186 ++++++++------- src/native/NativeMacOSProvider.ts | 7 +- src/native/NativeMachoSelectedSlice.ts | 21 +- src/native/NativeMachoSourceProvider.test.ts | 15 +- src/native/metadata/MachoImage.ts | 7 +- src/native/parsers/plist.ts | 74 +++--- src/process/Utf8NdjsonLineBuffer.test.ts | 69 ++++-- src/process/Utf8NdjsonLineBuffer.ts | 46 ++-- .../filesystem/keyedArchiveXmlNesting.test.ts | 2 +- .../filesystem/keyedArchiveXmlSyntax.test.ts | 2 +- .../kuna/kunaSpanCloseOwnership.test.ts | 3 +- .../native/nativePlistBinarySource.test.ts | 2 +- .../native/nativeSelectedArchitecture.test.ts | 15 +- .../native/objcClassMetadataFallback.test.ts | 21 +- 75 files changed, 1350 insertions(+), 727 deletions(-) create mode 100644 src/domain/internalInvariant.ts create mode 100644 src/kuna/KunaJson.test.ts 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 }); }); });