Files
reverse-engineering-anything/src/domain/xmlDocument.ts
T
morluto 78fd365bdd 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.
2026-11-15 18:24:35 +08:00

307 lines
11 KiB
TypeScript

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;
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 =>
declaration.replace(/"[^"]*"|'[^']*'/gu, "").includes("[");
/** XML 1.0's `NameStartChar`, and the further characters `NameChar` allows. */
const NAME_START = String.raw`:A-Z_a-z\u{C0}-\u{D6}\u{D8}-\u{F6}\u{F8}-\u{2FF}\u{370}-\u{37D}\u{37F}-\u{1FFF}\u{200C}\u{200D}\u{2070}-\u{218F}\u{2C00}-\u{2FEF}\u{3001}-\u{D7FF}\u{F900}-\u{FDCF}\u{FDF0}-\u{FFFD}\u{10000}-\u{EFFFF}`;
const NAME_MORE = String.raw`\-.0-9\u{B7}\u{300}-\u{36F}\u{203F}\u{2040}`;
/** XML element opening grammar shared by the desktop format readers. */
export const XML_ELEMENT_OPENING = String.raw`<[${NAME_START}][${NAME_START}${NAME_MORE}]*(?=[ \t\r\n]|/?>)`;
const XML_OPENING = new RegExp(
`^(?:<\\?xml\\b|<!DOCTYPE\\b|${XML_ELEMENT_OPENING})`,
"u",
);
/** Whether text begins with a possible XML declaration, DOCTYPE or start tag. */
export const opensLikeXml = (source: string): boolean =>
XML_OPENING.test(source);
/** XML 1.0's `PubidChar` but the apostrophe, which only a double-quoted literal may hold. */
const PUBID = String.raw`\n\r a-zA-Z0-9\-()+,./:=?;!*#@$_%`;
const SPACE = String.raw`[ \t\r\n]`;
/**
* A DOCTYPE without an internal subset, as XML 1.0's `doctypedecl` spells it
* between `<!DOCTYPE` and `>`: a name, then optionally `SYSTEM` and a literal,
* or `PUBLIC` and a public identifier and a literal.
*/
const EXTERNAL_DOCTYPE = new RegExp(
`^${SPACE}+[${NAME_START}][${NAME_START}${NAME_MORE}]*` +
`(?:${SPACE}+(?:SYSTEM|PUBLIC${SPACE}+(?:"[${PUBID}']*"|'[${PUBID}]*'))` +
`${SPACE}+(?:"[^"]*"|'[^']*'))?${SPACE}*$`,
"u",
);
/**
* Which DOCTYPE a document may have: any, none, or with `external` one
* without an internal subset, so the document declares no entity. Neither
* parser reads an external DTD.
*/
type DoctypePolicy = "allow" | "reject" | "external";
/**
* Read XML syntax as a stream, throwing at the first error; it holds only the
* open elements. Saxes reads a DOCTYPE without checking it, so the policy
* checks one it admits without an internal subset against XML's grammar.
*/
const checkXmlSyntax = (
source: string,
doctype: DoctypePolicy,
listen?: (syntax: SaxesParser<{ xmlns: true }>) => void,
nameSupported?: (name: string) => boolean,
): void => {
const syntax = new SaxesParser({
xmlns: true,
defaultXMLVersion: "1.0",
forceXMLVersion: true,
});
listen?.(syntax);
const checkName = (name: string) => {
if (nameSupported !== undefined && !nameSupported(name))
throw notWellFormed();
};
if (nameSupported !== undefined) {
syntax.on("opentagstart", (tag) => checkName(tag.name));
syntax.on("attribute", (attribute) => checkName(attribute.name));
syntax.on("processinginstruction", (instruction) =>
checkName(instruction.target),
);
}
syntax.on("doctype", (declaration) => {
if (doctype === "reject") throw unsupportedDoctype("doctype");
if (doctype !== "external") return;
if (declaresInternalSubset(declaration))
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();
};
/**
* Whether XML passes the syntax check `parseXmlDocument` makes, without
* building a document. An internal subset's syntax needs the DOM parser, so
* the policy must refuse one.
*/
export const isWellFormedXml = (
source: string,
policy: {
readonly doctype: Exclude<DoctypePolicy, "allow">;
readonly nameSupported?: (name: string) => boolean;
},
): boolean => {
try {
checkXmlSyntax(source, policy.doctype, undefined, policy.nameSupported);
return true;
} catch {
return false;
}
};
/** An element as `xmlElementRanges` offers it: its namespace and local name, and an attribute's value by namespace and local name. */
export interface XmlElementFacts {
readonly uri: string;
readonly local: string;
readonly attribute: (uri: string, local: string) => string | undefined;
}
/**
* The source ranges of the elements `select` picks, from the `<` of the start
* tag to the `>` that ends the element, outermost first and none inside
* another picked one; read with the syntax check `parseXmlDocument` makes, so
* text in a comment, CDATA or an attribute is never an element.
*/
export const xmlElementRanges = (
source: string,
select: (element: XmlElementFacts) => boolean,
policy: { readonly doctype: Exclude<DoctypePolicy, "allow"> },
): Result<
readonly { readonly start: number; readonly end: number }[],
XmlParseFailure
> => {
const ranges: { start: number; end: number }[] = [];
// Each open element's start, and whether it was picked.
const open: { start: number; picked: boolean }[] = [];
let selectedAncestor = false;
try {
checkXmlSyntax(source, policy.doctype, (syntax) => {
// Saxes reports the opening after reading the name and one character past it, none of which is `<`.
syntax.on("opentagstart", () => {
open.push({
start: source.lastIndexOf("<", syntax.position - 1),
picked: false,
});
});
syntax.on("opentag", (tag: SaxesTagNS) => {
const element = open.at(-1);
if (element === undefined || selectedAncestor) return;
element.picked = select({
uri: tag.uri,
local: tag.local,
attribute: (uri, local) =>
Object.values(tag.attributes).find(
(attribute) => attribute.uri === uri && attribute.local === local,
)?.value,
});
selectedAncestor = element.picked;
});
syntax.on("closetag", () => {
const element = open.pop();
if (element?.picked === true) {
ranges.push({ start: element.start, end: syntax.position });
selectedAncestor = false;
}
});
});
return ok(ranges.sort((left, right) => left.start - right.start));
} catch (cause: unknown) {
return err(xmlFailure(cause));
}
};
/** Inclusive source ranges of attribute quotes, parsed without reading a DTD. */
export const xmlAttributeQuoteRanges = (
source: string,
): Result<
readonly { readonly start: number; readonly end: number }[],
{
readonly error: XmlParseFailure;
readonly ranges: readonly {
readonly start: number;
readonly end: number;
}[];
readonly examined: number;
}
> => {
const ranges: { start: number; end: number }[] = [];
let reader: SaxesParser<{ xmlns: true }> | undefined;
try {
checkXmlSyntax(source, "allow", (syntax) => {
reader = syntax;
syntax.on("attribute", () => {
const end = syntax.position - 1;
const quote = source[end];
if (quote !== '"' && quote !== "'") throw notWellFormed();
const start = source.lastIndexOf(quote, end - 1);
if (start < 0) throw notWellFormed();
ranges.push({ start, end });
});
});
return ok(ranges);
} catch (cause: unknown) {
return err({
error: xmlFailure(cause),
ranges,
examined: Math.max(0, (reader?.position ?? 0) - 1),
});
}
};
/** One boundary owns strict XML syntax, under a DOCTYPE policy, and the source-located DOM projection. */
export const parseXmlDocument = (
source: string,
policy: {
readonly doctype: DoctypePolicy;
readonly lineEndings: "preserve" | "normalize";
readonly nameSupported?: (name: string) => boolean;
},
): Result<Document, XmlParseFailure> => {
try {
checkXmlSyntax(source, policy.doctype, undefined, policy.nameSupported);
// Saxes owns well-formedness outside DTDs. The DOM parser additionally
// checks DTD syntax and builds source-located nodes; its advisory warnings
// (including literal U+FFFD) are not byte-decoding or syntax failures.
return ok(
new DOMParser({
normalizeLineEndings:
policy.lineEndings === "preserve"
? (text) => text
: (text) => text.replace(XML_LINE_ENDING, "\n"),
onError: onErrorStopParsing,
}).parseFromString(source, "application/xml"),
);
} catch (cause: unknown) {
return err(xmlFailure(cause));
}
};
/** A DOCTYPE's name and external identifiers, null where it gives none. */
export interface DeclaredDocumentType {
readonly name: string;
readonly publicId: string | null;
readonly systemId: string | null;
}
/** A quoted literal's value; the DOM keeps the quotes, and holds "" where there is no literal. */
const literalValue = (literal: string): string | null =>
literal === "" ? null : literal.slice(1, -1);
/**
* The document's DOCTYPE as declared, or undefined without one. The public
* identifier is normalized as XML matches it, and as expat reports it: each
* run of spaces and line breaks becomes one space, and the ends are trimmed.
*/
export const declaredDocumentType = (
document: Document,
): DeclaredDocumentType | undefined => {
const doctype = document.doctype;
if (doctype === null) return undefined;
const publicId = literalValue(doctype.publicId);
return {
name: doctype.name,
publicId:
publicId === null
? null
: publicId.replace(/[ \r\n]+/gu, " ").replace(/^ | $/gu, ""),
systemId: literalValue(doctype.systemId),
};
};