fix(artifacts): preserve keyed archive integer precision

Integrate the numeric precision correction from #1135 with complete supplemental
metadata handling. Keep decoded numbers with an explicit limitation for mixed XML
content or unclassified integer text, rather than assigning another literal's
exact decimal. Project nonnumeric UID and CF$UID dictionary values recursively
while preserving numeric references, graph identity and original byte digests.

Add filesystem, built CLI and MCP regressions for the review findings, adjacent
XML representations and numeric reference controls. Retain the original native
Foundation qualification fixtures and verifier.

Verification: 84 focused tests; npm run check; npm run docs:check;
npm run verify:test-discovery; npm run verify:keyed-archive (real Foundation,
CLI and stdio MCP). No real Hopper or Ghidra verification was needed or run.

Co-authored-by: Rudy Mizrahi Celekli <47457359+rudycelekli@users.noreply.github.com>
Signed-off-by: morluto <76467478+morluto@users.noreply.github.com>
This commit is contained in:
morluto
2026-10-09 07:13:32 +08:00
co-authored by Rudy Mizrahi Celekli
parent 1d7115b7b4
commit 4034883e98
14 changed files with 1189 additions and 3 deletions
+27 -1
View File
@@ -4,6 +4,11 @@ import { z } from "zod";
import { AnalysisInputError } from "../../domain/analysisErrorCore.js";
import type { JsonValue } from "../../domain/jsonValue.js";
import { projectPlistValue } from "../../domain/apple/plistValue.js";
import { createPlistNumberProjection } from "../../domain/apple/plistNumbers.js";
import {
binaryPlistNumberLiterals,
xmlPlistNumberLiterals,
} from "./PlistNumberLiterals.js";
import {
omittedPrototypeKeysLimitation,
parseXmlPropertyList,
@@ -32,15 +37,36 @@ export const decodeKeyedArchiveBytes = (
"Selected file is a compiled NIBArchive, not a Foundation plist archive; decode it with decode_interface_builder",
);
const binary = bytes.subarray(0, 8).toString("ascii") === "bplist00";
const xmlText = binary ? undefined : decodeXmlPlistText(bytes);
const parsed = binary
? { value: parseBinary(bytes), omittedPrototypeKeys: 0 }
: parseXmlPropertyList(decodeXmlPlistText(bytes));
: parseXmlPropertyList(xmlText ?? "");
const graph = projectKeyedArchive(normalizePlist(parsed.value), selection);
const numbers = createPlistNumberProjection(
binary
? binaryPlistNumberLiterals(bytes)
: xmlPlistNumberLiterals(xmlText ?? ""),
);
// Classify the serialized graph before projecting values to typed decimals.
// Numeric IDs, node kinds, references and pagination retain their original meaning.
const roots = Object.fromEntries(
Object.entries(graph.roots).map(([name, value]) => [
name,
numbers.project(value),
]),
);
const objects = graph.objects.map((object) => ({
...object,
value: numbers.project(object.value),
}));
return {
archive_format: binary ? ("binary-plist" as const) : ("xml-plist" as const),
...graph,
roots,
objects,
limitations: [
...graph.limitations,
...numbers.limitations(),
...(parsed.omittedPrototypeKeys === 0
? []
: [omittedPrototypeKeysLimitation(parsed.omittedPrototypeKeys)]),
+174
View File
@@ -0,0 +1,174 @@
import type { PlistNumberLiterals } from "../../domain/apple/plistNumbers.js";
import { decodeXmlText } from "../../domain/propertyListKeys.js";
const collector = () => {
const integers = new Map<number, Set<string>>();
const reals = new Set<number>();
let unsafeIntegerLiterals = 0;
let incompleteMetadata = false;
return {
integer: (literal: string) => {
if (!/^[+-]?\d+$/u.test(literal)) {
incompleteMetadata = true;
return;
}
const exact = BigInt(literal);
if (
exact >= BigInt(Number.MIN_SAFE_INTEGER) &&
exact <= BigInt(Number.MAX_SAFE_INTEGER)
)
return;
unsafeIntegerLiterals += 1;
const rounded = Number(exact);
integers.set(
rounded,
(integers.get(rounded) ?? new Set()).add(exact.toString()),
);
},
real: (value: number) => {
reals.add(value);
},
markIncomplete: () => {
incompleteMetadata = true;
},
result: (incomplete = false): PlistNumberLiterals => ({
incomplete: incomplete || incompleteMetadata,
integers,
reals,
unsafeIntegerLiterals,
}),
};
};
// Consume quoted tag attributes and opaque comment/CDATA tokens whole.
const XML_TOKEN =
/<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<(?:[^>"']|"[^"]*"|'[^']*')*>/gu;
const OPAQUE_ELEMENTS = new Set(["string", "key", "data", "date"]);
/** Observe plist number element types without interpreting strings or class code. */
export const xmlPlistNumberLiterals = (xml: string): PlistNumberLiterals => {
const output = collector();
const elements: string[] = [];
let number:
| {
kind: "integer" | "real";
text: string;
depth: number;
plainText: boolean;
}
| undefined;
let cursor = 0;
for (const match of xml.matchAll(XML_TOKEN)) {
const index = match.index;
if (number !== undefined) number.text += xml.slice(cursor, index);
const token = match[0];
cursor = index + token.length;
if (token.startsWith("<!--") || token.startsWith("<![CDATA[")) {
if (number !== undefined) {
number.plainText = false;
output.markIncomplete();
}
continue;
}
const tag = /^<\s*(\/?)\s*([\w:-]+)/u.exec(token);
if (tag === null) {
if (number !== undefined) {
number.plainText = false;
output.markIncomplete();
}
continue;
}
const closing = tag[1] === "/";
const name = tag[2];
if (name === undefined) continue;
if (closing) {
if (
number !== undefined &&
number.kind === name &&
number.depth === elements.length
) {
if (number.plainText) {
const text = decodeXmlText(number.text).trim();
if (number.kind === "integer") output.integer(text);
else output.real(Number.parseFloat(text));
}
number = undefined;
}
elements.pop();
continue;
}
// The pinned decoder reads only the first child for integers and only text
// nodes for reals. Mixed content cannot establish an exact association.
if (number !== undefined) {
number.plainText = false;
output.markIncomplete();
}
if (/\/\s*>$/u.test(token)) continue;
if (
number === undefined &&
(name === "integer" || name === "real") &&
!elements.some((parent) => OPAQUE_ELEMENTS.has(parent))
)
number = {
kind: name,
text: "",
depth: elements.length + 1,
plainText: true,
};
elements.push(name);
}
return output.result();
};
/** Observe bounded binary number markers without changing primary decode acceptance. */
export const binaryPlistNumberLiterals = (
bytes: Buffer,
): PlistNumberLiterals => {
const output = collector();
if (
bytes.length < 40 ||
bytes.subarray(0, 8).toString("ascii") !== "bplist00"
)
return output.result(true);
const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
const trailer = bytes.length - 32;
const offsetWidth = bytes[trailer + 6] ?? 0;
if (![1, 2, 4, 8].includes(offsetWidth)) return output.result(true);
const countRaw = view.getBigUint64(trailer + 8);
const tableRaw = view.getBigUint64(trailer + 24);
const safeMaximum = BigInt(Number.MAX_SAFE_INTEGER);
if (countRaw === 0n || countRaw > safeMaximum || tableRaw > safeMaximum)
return output.result(true);
if (tableRaw < 8n || tableRaw >= BigInt(trailer)) return output.result(true);
const offsetTable = Number(tableRaw);
const capacity = Math.floor((trailer - offsetTable) / offsetWidth);
if (countRaw > BigInt(capacity)) return output.result(true);
const count = Number(countRaw);
const unsigned = (offset: number): number | undefined => {
if (offset < offsetTable || offset + offsetWidth > trailer)
return undefined;
if (offsetWidth === 1) return view.getUint8(offset);
if (offsetWidth === 2) return view.getUint16(offset);
if (offsetWidth === 4) return view.getUint32(offset);
const value = view.getBigUint64(offset);
return value > safeMaximum ? undefined : Number(value);
};
for (let index = 0; index < count; index += 1) {
const offset = unsigned(offsetTable + index * offsetWidth);
if (offset === undefined || offset < 8 || offset >= offsetTable)
return output.result(true);
const marker = bytes[offset] ?? 0;
const type = marker >> 4;
if (type !== 1 && type !== 2) continue;
const width = 2 ** (marker & 0xf);
if (offset + 1 + width > offsetTable) return output.result(true);
if (type === 1 && width === 8)
output.integer(view.getBigInt64(offset + 1).toString());
else if (type === 1 && width > 4) return output.result(true);
else if (type === 2 && width === 4)
output.real(view.getFloat32(offset + 1));
else if (type === 2 && width === 8)
output.real(view.getFloat64(offset + 1));
else if (type === 2) return output.result(true);
}
return output.result();
};
+91
View File
@@ -0,0 +1,91 @@
import type { JsonValue } from "../jsonValue.js";
/** Source element types needed to distinguish large integers from integral reals. */
export interface PlistNumberLiterals {
readonly integers: ReadonlyMap<number, ReadonlySet<string>>;
readonly reals: ReadonlySet<number>;
/** Integer literals in the original serialized plist, not decoded graph slots. */
readonly unsafeIntegerLiterals: number;
/** Supplemental byte metadata was not completely observable. */
readonly incomplete: boolean;
}
/** Preserve unambiguous exact integers; disclose rounded or unclassified numbers. */
export const createPlistNumberProjection = (literals: PlistNumberLiterals) => {
let exactIntegerCount = 0;
let ambiguousNumberCount = 0;
const mapNumber = (item: number): JsonValue => {
if (Number.isSafeInteger(item) || !Number.isInteger(item)) return item;
if (literals.incomplete) {
ambiguousNumberCount += 1;
return item;
}
const decimals = literals.integers.get(item);
if (decimals === undefined) {
if (!literals.reals.has(item)) ambiguousNumberCount += 1;
return item;
}
const [decimal] = decimals;
if (
decimals.size !== 1 ||
decimal === undefined ||
literals.reals.has(item)
) {
ambiguousNumberCount += 1;
return item;
}
exactIntegerCount += 1;
return { $plist_type: "integer", decimal };
};
const map = (item: JsonValue): JsonValue => {
if (typeof item === "number") return mapNumber(item);
if (Array.isArray(item)) return item.map(map);
if (item !== null && typeof item === "object") {
const keys = Object.keys(item);
const marker = item[keys[0] ?? ""];
const reference =
keys.length === 1 &&
(keys[0] === "UID" || keys[0] === "CF$UID") &&
typeof marker === "number";
if (reference) {
// Keep malformed numeric reference markers recognizable by the graph reader.
if (
typeof marker === "number" &&
!Number.isSafeInteger(marker) &&
(literals.integers.has(marker) || !literals.reals.has(marker))
)
ambiguousNumberCount += 1;
return item;
}
return Object.fromEntries(
Object.entries(item).map(([key, child]) => [key, map(child)]),
);
}
return item;
};
return {
project: map,
limitations: () => [
...(literals.incomplete
? [
"Original archive number metadata could not be completely observed; decoded numbers may lose integer precision and exact integer/real association is unavailable.",
]
: []),
...(literals.unsafeIntegerLiterals === 0
? []
: [
`${String(literals.unsafeIntegerLiterals)} observed integer literal(s) in the original archive exceed the exact range of a JSON number. Decoded numbers may lose integer precision unless represented as { "$plist_type": "integer", "decimal": "<exact digits>" }; the original archive bytes retain those literals.`,
]),
...(exactIntegerCount === 0
? []
: [
`${String(exactIntegerCount)} unambiguous integer value(s) are reported with exact decimal text as { "$plist_type": "integer", "decimal": "<exact digits>" }.`,
]),
...(ambiguousNumberCount === 0
? []
: [
`${String(ambiguousNumberCount)} number(s) beyond the exact integer range remain as decoded because their source integer/real type or reference marker cannot be associated unambiguously; integer precision loss remains possible.`,
]),
],
};
};
+1 -1
View File
@@ -61,7 +61,7 @@ const XML_ENTITIES: Readonly<Record<string, string>> = {
* Unicode stays as written: comments and CDATA may hold such text literally,
* and the XML decoder rejects it anywhere else.
*/
const decodeXmlText = (text: string): string =>
export const decodeXmlText = (text: string): string =>
text.replace(
/&(?:#x([\da-f]+)|#(\d+)|([a-z]+));/giu,
(entity, hex?: string, decimal?: string, name?: string) => {