@stll/folio-core 0.10.0 → 0.12.0

package/dist/docx/server/evaluateDocxXmlPatchProposal.js

@@ -0,0 +1,361 @@
+import { DocxArchiveError } from "./boundedArchive.js";
+import { getDocxXmlSafetyIssue } from "../xmlSafety.js";
+import { FolioDocxPackageInspectionError, inspectDocxPackage } from "./inspectDocxPackage.js";
+import { TaggedError, panic } from "better-result";
+import { createHash } from "node:crypto";
+//#region src/docx/server/evaluateDocxXmlPatchProposal.ts
+const FOLIO_DOCX_XML_PATCH_PROPOSAL_VERSION = 1;
+const FOLIO_DOCX_XML_PATCH_PROPOSAL_PROFILE = "folio-xml-patch-proposal-v1";
+const FOLIO_DOCX_XML_PATCH_PROPOSAL_DEFAULTS = Object.freeze({
+	maxReplacements: 16,
+	maxPartBytes: 8 * 1024 * 1024,
+	maxTotalBytes: 16 * 1024 * 1024
+});
+const FOLIO_DOCX_XML_PATCH_PROPOSAL_ISSUE_CODES = Object.freeze([
+	"invalid-proposal",
+	"unsupported-version",
+	"too-many-replacements",
+	"duplicate-part",
+	"invalid-part-path",
+	"invalid-base-sha256",
+	"part-not-allowed",
+	"part-not-found",
+	"part-not-xml",
+	"replacement-too-large",
+	"replacements-too-large",
+	"xml-doctype-forbidden",
+	"xml-not-well-formed",
+	"xml-encoding-mismatch",
+	"base-hash-mismatch",
+	"package-inspection-failed"
+]);
+var InvalidFolioDocxXmlPatchProposalError = class extends TaggedError("InvalidFolioDocxXmlPatchProposalError")() {};
+var InvalidFolioDocxXmlPatchProposalOptionsError = class extends TaggedError("InvalidFolioDocxXmlPatchProposalOptionsError")() {};
+const SHA256_PATTERN = /^[\da-f]{64}$/u;
+const XML_DECLARED_ENCODING_PATTERN = /^\uFEFF?<\?xml[^>]*\bencoding\s*=\s*["']([^"']+)["'][^>]*\?>/iu;
+const MAX_PACKAGE_PATH_CODE_UNITS = 1024;
+const prepareXmlReplacement = ({ replacement, encodedByPath, inspectedByPath }) => {
+	const replacementBytes = encodedByPath.get(replacement.path);
+	const current = inspectedByPath.get(replacement.path);
+	if (replacementBytes === void 0 || current === void 0) return panic("Accepted XML replacement is missing prepared package data");
+	return {
+		path: replacement.path,
+		baseSha256: replacement.baseSha256,
+		currentSha256: current.sha256,
+		replacementSha256: createHash("sha256").update(replacementBytes).digest("hex"),
+		replacementByteLength: replacementBytes.byteLength,
+		encoding: "utf-8"
+	};
+};
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const invalidProposal = (path, reason) => {
+	throw new InvalidFolioDocxXmlPatchProposalError({
+		message: `Invalid XML patch proposal at ${path}: ${reason}.`,
+		path,
+		reason
+	});
+};
+const assertAllowedKeys = (value, path, allowedKeys) => {
+	const allowed = new Set(allowedKeys);
+	const unexpected = Object.keys(value).find((key) => !allowed.has(key));
+	if (unexpected !== void 0) invalidProposal(`${path}.${unexpected}`, "unexpected property");
+};
+const readString = (value, key, path) => {
+	const result = value[key];
+	if (typeof result !== "string") return invalidProposal(`${path}.${key}`, "expected a string");
+	return result;
+};
+const parseXmlReplacement = (value, index) => {
+	const path = `$.replacements[${index}]`;
+	if (!isPlainObject(value)) return invalidProposal(path, "expected an object");
+	assertAllowedKeys(value, path, [
+		"path",
+		"baseSha256",
+		"replacementXml"
+	]);
+	return {
+		path: readString(value, "path", path),
+		baseSha256: readString(value, "baseSha256", path),
+		replacementXml: readString(value, "replacementXml", path)
+	};
+};
+const parseFolioDocxXmlPatchProposal = (value) => {
+	if (!isPlainObject(value)) return invalidProposal("$", "expected an object");
+	assertAllowedKeys(value, "$", ["version", "replacements"]);
+	const version = value["version"];
+	if (typeof version !== "number" || !Number.isSafeInteger(version)) return invalidProposal("$.version", "expected an integer contract version");
+	if (version !== 1) return invalidProposal("$.version", "unsupported contract version");
+	const replacements = value["replacements"];
+	if (!Array.isArray(replacements) || replacements.length === 0) return invalidProposal("$.replacements", "expected a non-empty array");
+	if (replacements.length > FOLIO_DOCX_XML_PATCH_PROPOSAL_DEFAULTS.maxReplacements) return invalidProposal("$.replacements", `expected at most ${FOLIO_DOCX_XML_PATCH_PROPOSAL_DEFAULTS.maxReplacements} replacements`);
+	const firstReplacement = replacements.at(0);
+	if (firstReplacement === void 0) return invalidProposal("$.replacements", "expected a non-empty array");
+	return {
+		version: 1,
+		replacements: [parseXmlReplacement(firstReplacement, 0), ...replacements.slice(1).map((replacement, index) => parseXmlReplacement(replacement, index + 1))]
+	};
+};
+const resolveLimit = ({ value, fallback, path }) => {
+	const limit = value ?? fallback;
+	if (!Number.isSafeInteger(limit) || limit < 0) throw new InvalidFolioDocxXmlPatchProposalOptionsError({
+		message: `${path} must be a non-negative safe integer.`,
+		path
+	});
+	return limit;
+};
+const resolveLimits = (limits) => {
+	const maxReplacements = resolveLimit({
+		value: limits?.maxReplacements,
+		fallback: FOLIO_DOCX_XML_PATCH_PROPOSAL_DEFAULTS.maxReplacements,
+		path: "limits.maxReplacements"
+	});
+	if (maxReplacements > FOLIO_DOCX_XML_PATCH_PROPOSAL_DEFAULTS.maxReplacements) throw new InvalidFolioDocxXmlPatchProposalOptionsError({
+		message: `limits.maxReplacements must not exceed ${FOLIO_DOCX_XML_PATCH_PROPOSAL_DEFAULTS.maxReplacements}.`,
+		path: "limits.maxReplacements"
+	});
+	return {
+		maxReplacements,
+		maxPartBytes: resolveLimit({
+			value: limits?.maxPartBytes,
+			fallback: FOLIO_DOCX_XML_PATCH_PROPOSAL_DEFAULTS.maxPartBytes,
+			path: "limits.maxPartBytes"
+		}),
+		maxTotalBytes: resolveLimit({
+			value: limits?.maxTotalBytes,
+			fallback: FOLIO_DOCX_XML_PATCH_PROPOSAL_DEFAULTS.maxTotalBytes,
+			path: "limits.maxTotalBytes"
+		})
+	};
+};
+const isNormalizedPackagePath = (path) => path.length > 0 && path.length <= MAX_PACKAGE_PATH_CODE_UNITS && !path.startsWith("/") && !path.endsWith("/") && !path.includes("\\") && path.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+const resolveAllowedParts = (allowedParts) => {
+	const resolved = /* @__PURE__ */ new Set();
+	for (const [index, path] of allowedParts.entries()) {
+		if (typeof path !== "string" || !isNormalizedPackagePath(path)) throw new InvalidFolioDocxXmlPatchProposalOptionsError({
+			message: `allowedParts[${index}] must be a normalized package path.`,
+			path: `allowedParts[${index}]`
+		});
+		if (resolved.has(path)) throw new InvalidFolioDocxXmlPatchProposalOptionsError({
+			message: `allowedParts[${index}] must be unique.`,
+			path: `allowedParts[${index}]`
+		});
+		resolved.add(path);
+	}
+	return resolved;
+};
+const rejectedEvaluation = ({ issues, limits }) => ({
+	version: 1,
+	profile: FOLIO_DOCX_XML_PATCH_PROPOSAL_PROFILE,
+	status: "rejected",
+	producesOutput: false,
+	issues,
+	replacements: [],
+	limits
+});
+const acceptedEvaluation = ({ replacements, limits }) => ({
+	version: 1,
+	profile: FOLIO_DOCX_XML_PATCH_PROPOSAL_PROFILE,
+	status: "accepted",
+	producesOutput: false,
+	issues: [],
+	replacements,
+	limits
+});
+const inspectionIssue = (error) => {
+	if (error.code === "part-not-found" || error.code === "part-not-xml") return {
+		code: error.code,
+		message: error.message,
+		...error.part !== void 0 && { part: error.part }
+	};
+	return {
+		code: "package-inspection-failed",
+		message: "The package could not be inspected within the configured limits.",
+		...error.part !== void 0 && { part: error.part }
+	};
+};
+const evaluateDocxXmlPatchProposal = async ({ bytes, proposal: rawProposal, allowedParts, archive, limits: rawLimits }) => {
+	const limits = resolveLimits(rawLimits);
+	const allowed = resolveAllowedParts(allowedParts);
+	const rawReplacements = isPlainObject(rawProposal) ? rawProposal["replacements"] : void 0;
+	if (isPlainObject(rawProposal) && rawProposal["version"] === 1 && Array.isArray(rawReplacements) && rawReplacements.length > limits.maxReplacements) return rejectedEvaluation({
+		issues: [{
+			code: "too-many-replacements",
+			message: `Proposal contains ${rawReplacements.length} replacements (max ${limits.maxReplacements}).`,
+			proposalPath: "$.replacements"
+		}],
+		limits
+	});
+	let proposal;
+	try {
+		proposal = parseFolioDocxXmlPatchProposal(rawProposal);
+	} catch (error) {
+		if (!(error instanceof InvalidFolioDocxXmlPatchProposalError)) throw error;
+		return rejectedEvaluation({
+			issues: [{
+				code: error.path === "$.version" && isPlainObject(rawProposal) && typeof rawProposal["version"] === "number" && Number.isSafeInteger(rawProposal["version"]) ? "unsupported-version" : "invalid-proposal",
+				message: error.message,
+				proposalPath: error.path
+			}],
+			limits
+		});
+	}
+	const issues = [];
+	const seen = /* @__PURE__ */ new Set();
+	const encodedByPath = /* @__PURE__ */ new Map();
+	let encodedTotalBytes = 0;
+	let totalCodeUnits = 0;
+	let totalLimitReported = false;
+	for (const [index, replacement] of proposal.replacements.entries()) {
+		const proposalPath = `$.replacements[${index}]`;
+		if (seen.has(replacement.path)) issues.push({
+			code: "duplicate-part",
+			message: "Each package part may appear only once in a proposal.",
+			proposalPath: `${proposalPath}.path`,
+			part: replacement.path
+		});
+		seen.add(replacement.path);
+		if (!isNormalizedPackagePath(replacement.path)) issues.push({
+			code: "invalid-part-path",
+			message: "Replacement paths must be normalized package paths.",
+			proposalPath: `${proposalPath}.path`,
+			part: replacement.path
+		});
+		else if (!allowed.has(replacement.path)) issues.push({
+			code: "part-not-allowed",
+			message: "The server-side policy does not allow replacing this package part.",
+			proposalPath: `${proposalPath}.path`,
+			part: replacement.path
+		});
+		if (replacement.baseSha256.length !== 64 || !SHA256_PATTERN.test(replacement.baseSha256)) issues.push({
+			code: "invalid-base-sha256",
+			message: "baseSha256 must be a lowercase hexadecimal SHA-256 digest.",
+			proposalPath: `${proposalPath}.baseSha256`,
+			part: replacement.path
+		});
+		const replacementCodeUnits = replacement.replacementXml.length;
+		const exceedsPartLowerBound = replacementCodeUnits > limits.maxPartBytes;
+		if (exceedsPartLowerBound) issues.push({
+			code: "replacement-too-large",
+			message: `Replacement XML exceeds the ${limits.maxPartBytes}-byte per-part limit.`,
+			proposalPath: `${proposalPath}.replacementXml`,
+			part: replacement.path
+		});
+		totalCodeUnits += replacementCodeUnits;
+		if (totalCodeUnits > limits.maxTotalBytes && !totalLimitReported) {
+			totalLimitReported = true;
+			issues.push({
+				code: "replacements-too-large",
+				message: `Replacement XML exceeds the ${limits.maxTotalBytes}-byte cumulative limit.`,
+				proposalPath: "$.replacements"
+			});
+		}
+		if (exceedsPartLowerBound || totalLimitReported) continue;
+		const replacementBytes = new TextEncoder().encode(replacement.replacementXml);
+		const exceedsEncodedPart = replacementBytes.byteLength > limits.maxPartBytes;
+		const nextEncodedTotalBytes = encodedTotalBytes + replacementBytes.byteLength;
+		if (exceedsEncodedPart) issues.push({
+			code: "replacement-too-large",
+			message: `Replacement XML exceeds the ${limits.maxPartBytes}-byte per-part limit.`,
+			proposalPath: `${proposalPath}.replacementXml`,
+			part: replacement.path
+		});
+		if (nextEncodedTotalBytes > limits.maxTotalBytes) {
+			totalLimitReported = true;
+			issues.push({
+				code: "replacements-too-large",
+				message: `Replacement XML exceeds the ${limits.maxTotalBytes}-byte cumulative limit.`,
+				proposalPath: "$.replacements"
+			});
+		}
+		encodedTotalBytes = nextEncodedTotalBytes;
+		if (exceedsEncodedPart || totalLimitReported) continue;
+		encodedByPath.set(replacement.path, replacementBytes);
+		const safetyIssue = getDocxXmlSafetyIssue(replacement.replacementXml);
+		if (safetyIssue === "doctype-forbidden") issues.push({
+			code: "xml-doctype-forbidden",
+			message: "Replacement XML must not declare a document type.",
+			proposalPath: `${proposalPath}.replacementXml`,
+			part: replacement.path
+		});
+		else if (safetyIssue === "not-well-formed") issues.push({
+			code: "xml-not-well-formed",
+			message: "Replacement XML must be well formed.",
+			proposalPath: `${proposalPath}.replacementXml`,
+			part: replacement.path
+		});
+		else {
+			const declaredEncoding = replacement.replacementXml.match(XML_DECLARED_ENCODING_PATTERN)?.at(1);
+			if (declaredEncoding !== void 0 && declaredEncoding.toLowerCase() !== "utf-8" && declaredEncoding.toLowerCase() !== "utf8") issues.push({
+				code: "xml-encoding-mismatch",
+				message: "Replacement XML declarations must use UTF-8 encoding.",
+				proposalPath: `${proposalPath}.replacementXml`,
+				part: replacement.path
+			});
+		}
+	}
+	if (issues.length > 0) {
+		const firstIssue = issues.at(0);
+		if (firstIssue === void 0) return panic("Rejected XML patch proposal is missing an issue");
+		return rejectedEvaluation({
+			issues: [firstIssue, ...issues.slice(1)],
+			limits
+		});
+	}
+	let inspected;
+	try {
+		inspected = await inspectDocxPackage(bytes, {
+			...archive === void 0 ? {} : { archive },
+			xmlParts: proposal.replacements.map(({ path }) => path),
+			limits: {
+				maxXmlParts: limits.maxReplacements,
+				maxXmlPartBytes: limits.maxPartBytes,
+				maxXmlTotalBytes: limits.maxTotalBytes
+			}
+		});
+	} catch (error) {
+		if (error instanceof FolioDocxPackageInspectionError) return rejectedEvaluation({
+			issues: [inspectionIssue(error)],
+			limits
+		});
+		if (error instanceof DocxArchiveError) return rejectedEvaluation({
+			issues: [{
+				code: "package-inspection-failed",
+				message: "The package could not be inspected within the configured limits."
+			}],
+			limits
+		});
+		throw error;
+	}
+	const inspectedByPath = new Map(inspected.xmlParts.map((part) => [part.path, part]));
+	for (const [index, replacement] of proposal.replacements.entries()) {
+		const current = inspectedByPath.get(replacement.path);
+		if (current === void 0 || current.sha256 === replacement.baseSha256) continue;
+		issues.push({
+			code: "base-hash-mismatch",
+			message: "The package part changed after the proposal base was inspected.",
+			proposalPath: `$.replacements[${index}].baseSha256`,
+			part: replacement.path
+		});
+	}
+	if (issues.length > 0) {
+		const firstIssue = issues.at(0);
+		if (firstIssue === void 0) return panic("Rejected XML patch proposal is missing an issue");
+		return rejectedEvaluation({
+			issues: [firstIssue, ...issues.slice(1)],
+			limits
+		});
+	}
+	const preparedReplacements = proposal.replacements.map((replacement) => prepareXmlReplacement({
+		replacement,
+		encodedByPath,
+		inspectedByPath
+	}));
+	const firstPreparedReplacement = preparedReplacements.at(0);
+	if (firstPreparedReplacement === void 0) return panic("Accepted XML patch proposal is missing a prepared replacement");
+	return acceptedEvaluation({
+		replacements: [firstPreparedReplacement, ...preparedReplacements.slice(1)],
+		limits
+	});
+};
+//#endregion
+export { FOLIO_DOCX_XML_PATCH_PROPOSAL_DEFAULTS, FOLIO_DOCX_XML_PATCH_PROPOSAL_ISSUE_CODES, FOLIO_DOCX_XML_PATCH_PROPOSAL_PROFILE, FOLIO_DOCX_XML_PATCH_PROPOSAL_VERSION, InvalidFolioDocxXmlPatchProposalError, InvalidFolioDocxXmlPatchProposalOptionsError, evaluateDocxXmlPatchProposal, parseFolioDocxXmlPatchProposal };

package/dist/docx/server/inspectDocxPackage.d.ts

@@ -0,0 +1,70 @@
+import { DocxArchiveOptions } from "./boundedArchive.js";
+
+//#region src/docx/server/inspectDocxPackage.d.ts
+declare const FOLIO_DOCX_PACKAGE_INSPECTION_VERSION: 1;
+declare const FOLIO_DOCX_PACKAGE_INSPECTION_DEFAULTS: Readonly<{
+  readonly maxXmlParts: 16;
+  readonly maxXmlPartBytes: number;
+  readonly maxXmlTotalBytes: number;
+}>;
+declare const FOLIO_DOCX_PACKAGE_INSPECTION_ERROR_CODES: readonly ["invalid-limits", "too-many-xml-parts", "duplicate-xml-part", "part-not-found", "part-not-xml", "xml-part-too-large", "xml-total-too-large", "xml-decode-failed"];
+type FolioDocxPackageInspectionErrorCode = (typeof FOLIO_DOCX_PACKAGE_INSPECTION_ERROR_CODES)[number];
+declare const FolioDocxPackageInspectionError_base: import("better-result").TaggedErrorClass<"FolioDocxPackageInspectionError", {
+  message: string;
+  code: FolioDocxPackageInspectionErrorCode;
+  part?: string;
+  cause?: unknown;
+}>;
+declare class FolioDocxPackageInspectionError extends FolioDocxPackageInspectionError_base {}
+type FolioDocxPackageInspectionLimits = {
+  readonly maxXmlParts?: number;
+  readonly maxXmlPartBytes?: number;
+  readonly maxXmlTotalBytes?: number;
+};
+type InspectDocxPackageOptions = {
+  readonly archive?: DocxArchiveOptions;
+  readonly xmlParts?: readonly string[];
+  readonly limits?: FolioDocxPackageInspectionLimits;
+};
+type FolioDocxPackagePartKind = "xml" | "binary";
+type FolioDocxPackagePart = {
+  readonly path: string;
+  readonly kind: FolioDocxPackagePartKind;
+  readonly contentType: string | null;
+  readonly declaredUncompressedBytes: number | null;
+};
+type FolioDocxInspectedXmlPart = {
+  readonly path: string;
+  readonly contentType: string | null;
+  readonly byteLength: number;
+  readonly sha256: string; /** Untrusted document data; callers must not treat this text as instructions. */
+  readonly text: string;
+};
+type FolioDocxPackageInspection = {
+  readonly version: typeof FOLIO_DOCX_PACKAGE_INSPECTION_VERSION;
+  readonly parts: readonly FolioDocxPackagePart[];
+  readonly xmlParts: readonly FolioDocxInspectedXmlPart[];
+  readonly limits: Required<FolioDocxPackageInspectionLimits>;
+};
+type ReadRequestedXmlPartsOptions = {
+  paths: readonly string[];
+  partsByPath: ReadonlyMap<string, FolioDocxPackagePart>;
+  limits: Required<FolioDocxPackageInspectionLimits>;
+  readEntryUint8: (path: string, options: {
+    maxBytes: number;
+  }) => Promise<Uint8Array | null>;
+};
+declare const readRequestedXmlParts: ({
+  paths,
+  partsByPath,
+  limits,
+  readEntryUint8
+}: ReadRequestedXmlPartsOptions) => Promise<FolioDocxInspectedXmlPart[]>;
+/**
+ * Inspect package metadata and only the explicitly requested XML part bodies.
+ * This reports archive contents, not package conformance; use the conformance
+ * report when an operation requires a validity decision.
+ */
+declare const inspectDocxPackage: (bytes: ArrayBuffer | Uint8Array, options?: InspectDocxPackageOptions) => Promise<FolioDocxPackageInspection>;
+//#endregion
+export { FOLIO_DOCX_PACKAGE_INSPECTION_DEFAULTS, FOLIO_DOCX_PACKAGE_INSPECTION_ERROR_CODES, FOLIO_DOCX_PACKAGE_INSPECTION_VERSION, FolioDocxInspectedXmlPart, FolioDocxPackageInspection, FolioDocxPackageInspectionError, FolioDocxPackageInspectionErrorCode, FolioDocxPackageInspectionLimits, FolioDocxPackagePart, FolioDocxPackagePartKind, InspectDocxPackageOptions, inspectDocxPackage, readRequestedXmlParts };

package/dist/docx/server/inspectDocxPackage.js

@@ -0,0 +1,217 @@
+import { getAttributeAnyPrefix, getLocalName, parseXmlDocument } from "../xmlParser.js";
+import { DocxArchiveError, loadDocxArchive } from "./boundedArchive.js";
+import { TaggedError } from "better-result";
+import { createHash } from "node:crypto";
+//#region src/docx/server/inspectDocxPackage.ts
+const FOLIO_DOCX_PACKAGE_INSPECTION_VERSION = 1;
+const FOLIO_DOCX_PACKAGE_INSPECTION_DEFAULTS = Object.freeze({
+	maxXmlParts: 16,
+	maxXmlPartBytes: 8 * 1024 * 1024,
+	maxXmlTotalBytes: 16 * 1024 * 1024
+});
+const FOLIO_DOCX_PACKAGE_INSPECTION_ERROR_CODES = Object.freeze([
+	"invalid-limits",
+	"too-many-xml-parts",
+	"duplicate-xml-part",
+	"part-not-found",
+	"part-not-xml",
+	"xml-part-too-large",
+	"xml-total-too-large",
+	"xml-decode-failed"
+]);
+var FolioDocxPackageInspectionError = class extends TaggedError("FolioDocxPackageInspectionError")() {};
+const CONTENT_TYPES_PATH = "[Content_Types].xml";
+const CONTENT_TYPES_READ_LIMIT = 4 * 1024 * 1024;
+const XML_PATH_PATTERN = /(?:\.xml|\.rels)$/iu;
+const XML_CONTENT_TYPES = /* @__PURE__ */ new Set(["application/xml", "text/xml"]);
+const comparePackagePaths = (left, right) => {
+	if (left < right) return -1;
+	return left === right ? 0 : 1;
+};
+const decodeXml = (bytes, part) => {
+	let encoding = "utf-8";
+	if (bytes.length >= 2 && (bytes[0] === 255 && bytes[1] === 254 || bytes[0] === 60 && bytes[1] === 0)) encoding = "utf-16le";
+	else if (bytes.length >= 2 && (bytes[0] === 254 && bytes[1] === 255 || bytes[0] === 0 && bytes[1] === 60)) encoding = "utf-16be";
+	try {
+		return new TextDecoder(encoding, { fatal: true }).decode(bytes);
+	} catch (cause) {
+		throw new FolioDocxPackageInspectionError({
+			message: `Failed to decode XML package part "${part}"`,
+			code: "xml-decode-failed",
+			part,
+			cause
+		});
+	}
+};
+const parseContentTypes = (xml) => {
+	const declarations = {
+		defaults: /* @__PURE__ */ new Map(),
+		overrides: /* @__PURE__ */ new Map()
+	};
+	if (xml === null) return declarations;
+	const root = parseXmlDocument(xml);
+	if (root === null || getLocalName(root.name ?? "") !== "Types") return declarations;
+	for (const element of root.elements ?? []) {
+		if (element.type !== "element") continue;
+		const localName = getLocalName(element.name ?? "");
+		if (localName === "Default") {
+			const extension = getAttributeAnyPrefix(element, "Extension")?.toLowerCase();
+			const contentType = getAttributeAnyPrefix(element, "ContentType");
+			if (extension !== void 0 && contentType !== null) declarations.defaults.set(extension, contentType);
+			continue;
+		}
+		if (localName !== "Override") continue;
+		const partName = getAttributeAnyPrefix(element, "PartName")?.replace(/^\//u, "");
+		const contentType = getAttributeAnyPrefix(element, "ContentType");
+		if (partName !== void 0 && contentType !== null) declarations.overrides.set(partName, contentType);
+	}
+	return declarations;
+};
+const extensionFor = (path) => {
+	const filename = path.slice(path.lastIndexOf("/") + 1);
+	const separator = filename.lastIndexOf(".");
+	return separator === -1 ? null : filename.slice(separator + 1).toLowerCase();
+};
+const contentTypeFor = (path, declarations) => {
+	const override = declarations.overrides.get(path);
+	if (override !== void 0) return override;
+	const extension = extensionFor(path);
+	return extension === null ? null : declarations.defaults.get(extension) ?? null;
+};
+const isXmlPart = (path, contentType) => {
+	if (contentType !== null) return XML_CONTENT_TYPES.has(contentType) || contentType.endsWith("+xml");
+	return XML_PATH_PATTERN.test(path);
+};
+const toPackagePart = (entry, declarations) => {
+	const contentType = contentTypeFor(entry.path, declarations);
+	return {
+		path: entry.path,
+		kind: isXmlPart(entry.path, contentType) ? "xml" : "binary",
+		contentType,
+		declaredUncompressedBytes: entry.declaredUncompressedBytes
+	};
+};
+const requireNonNegativeInteger = (value, name) => {
+	if (Number.isSafeInteger(value) && value >= 0) return value;
+	throw new FolioDocxPackageInspectionError({
+		message: `${name} must be a non-negative safe integer`,
+		code: "invalid-limits"
+	});
+};
+const resolveLimits = (limits) => ({
+	maxXmlParts: requireNonNegativeInteger(limits?.maxXmlParts ?? FOLIO_DOCX_PACKAGE_INSPECTION_DEFAULTS.maxXmlParts, "maxXmlParts"),
+	maxXmlPartBytes: requireNonNegativeInteger(limits?.maxXmlPartBytes ?? FOLIO_DOCX_PACKAGE_INSPECTION_DEFAULTS.maxXmlPartBytes, "maxXmlPartBytes"),
+	maxXmlTotalBytes: requireNonNegativeInteger(limits?.maxXmlTotalBytes ?? FOLIO_DOCX_PACKAGE_INSPECTION_DEFAULTS.maxXmlTotalBytes, "maxXmlTotalBytes")
+});
+const validateRequestedParts = ({ requestedPaths, partsByPath, limits }) => {
+	if (requestedPaths.length > limits.maxXmlParts) throw new FolioDocxPackageInspectionError({
+		message: `Requested ${requestedPaths.length} XML parts (max ${limits.maxXmlParts})`,
+		code: "too-many-xml-parts"
+	});
+	const seen = /* @__PURE__ */ new Set();
+	let declaredTotalBytes = 0;
+	for (const path of requestedPaths) {
+		if (seen.has(path)) throw new FolioDocxPackageInspectionError({
+			message: `XML package part "${path}" was requested more than once`,
+			code: "duplicate-xml-part",
+			part: path
+		});
+		seen.add(path);
+		const part = partsByPath.get(path);
+		if (part === void 0) throw new FolioDocxPackageInspectionError({
+			message: `Package part "${path}" does not exist`,
+			code: "part-not-found",
+			part: path
+		});
+		if (part.kind !== "xml") throw new FolioDocxPackageInspectionError({
+			message: `Package part "${path}" is not declared as XML`,
+			code: "part-not-xml",
+			part: path
+		});
+		const declaredBytes = part.declaredUncompressedBytes;
+		if (declaredBytes === null) continue;
+		if (declaredBytes > limits.maxXmlPartBytes) throw new FolioDocxPackageInspectionError({
+			message: `XML package part "${path}" exceeds the per-part inspection limit`,
+			code: "xml-part-too-large",
+			part: path
+		});
+		declaredTotalBytes += declaredBytes;
+		if (declaredTotalBytes > limits.maxXmlTotalBytes) throw new FolioDocxPackageInspectionError({
+			message: "Requested XML package parts exceed the cumulative inspection limit",
+			code: "xml-total-too-large"
+		});
+	}
+};
+const readRequestedXmlParts = async ({ paths, partsByPath, limits, readEntryUint8 }) => {
+	const selected = [];
+	let totalBytes = 0;
+	for (const path of paths) {
+		const remainingTotalBytes = limits.maxXmlTotalBytes - totalBytes;
+		const readLimit = Math.min(limits.maxXmlPartBytes, remainingTotalBytes);
+		let bytes;
+		try {
+			bytes = await readEntryUint8(path, { maxBytes: readLimit });
+		} catch (cause) {
+			if (cause instanceof DocxArchiveError && cause.reason === "entry-too-large") {
+				const cumulativeLimitReached = readLimit < limits.maxXmlPartBytes;
+				throw new FolioDocxPackageInspectionError({
+					message: cumulativeLimitReached ? "Requested XML package parts exceed the cumulative inspection limit" : `XML package part "${path}" exceeds the per-part inspection limit`,
+					code: cumulativeLimitReached ? "xml-total-too-large" : "xml-part-too-large",
+					part: path,
+					cause
+				});
+			}
+			throw cause;
+		}
+		if (bytes === null) throw new FolioDocxPackageInspectionError({
+			message: `Package part "${path}" does not exist`,
+			code: "part-not-found",
+			part: path
+		});
+		totalBytes += bytes.byteLength;
+		if (totalBytes > limits.maxXmlTotalBytes) throw new FolioDocxPackageInspectionError({
+			message: "Requested XML package parts exceed the cumulative inspection limit",
+			code: "xml-total-too-large"
+		});
+		selected.push({
+			path,
+			contentType: partsByPath.get(path)?.contentType ?? null,
+			byteLength: bytes.byteLength,
+			sha256: createHash("sha256").update(bytes).digest("hex"),
+			text: decodeXml(bytes, path)
+		});
+	}
+	return selected;
+};
+/**
+* Inspect package metadata and only the explicitly requested XML part bodies.
+* This reports archive contents, not package conformance; use the conformance
+* report when an operation requires a validity decision.
+*/
+const inspectDocxPackage = async (bytes, options = {}) => {
+	const limits = resolveLimits(options.limits);
+	const requestedPaths = options.xmlParts ?? [];
+	const archive = await loadDocxArchive(bytes, options.archive);
+	const contentTypesBytes = await archive.readEntryUint8(CONTENT_TYPES_PATH, { maxBytes: CONTENT_TYPES_READ_LIMIT });
+	const declarations = parseContentTypes(contentTypesBytes === null ? null : decodeXml(contentTypesBytes, CONTENT_TYPES_PATH));
+	const parts = archive.entryMetadata.filter(({ directory }) => !directory).map((entry) => toPackagePart(entry, declarations)).toSorted(({ path: left }, { path: right }) => comparePackagePaths(left, right));
+	const partsByPath = new Map(parts.map((part) => [part.path, part]));
+	validateRequestedParts({
+		requestedPaths,
+		partsByPath,
+		limits
+	});
+	return {
+		version: 1,
+		parts,
+		xmlParts: await readRequestedXmlParts({
+			paths: requestedPaths,
+			partsByPath,
+			limits,
+			readEntryUint8: archive.readEntryUint8
+		}),
+		limits
+	};
+};
+//#endregion
+export { FOLIO_DOCX_PACKAGE_INSPECTION_DEFAULTS, FOLIO_DOCX_PACKAGE_INSPECTION_ERROR_CODES, FOLIO_DOCX_PACKAGE_INSPECTION_VERSION, FolioDocxPackageInspectionError, inspectDocxPackage, readRequestedXmlParts };