@stll/folio-core 0.11.0 → 0.13.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/extractDocxText.js

@@ -1,7 +1,8 @@
-import { findAllDeep, findChild, findDeep, getAttributeAnyPrefix, getLocalName, getTextContent, parseXml } from "../xmlParser.js";
+import { findAllDeep, findChild, findDeep, getAttribute, getAttributeAnyPrefix, getLocalName, getTextContent, parseXml } from "../xmlParser.js";
+import { RELATIONSHIP_TYPES, parseRelationships } from "../relsParser.js";
 import { loadDocxArchive } from "./boundedArchive.js";
 //#region src/docx/server/extractDocxText.ts
-const HEADER_FOOTER_PATH = /^word\/(?:header|footer)\d+\.xml$/u;
+const DOCUMENT_RELS_PATH = "word/_rels/document.xml.rels";
 const childElements = (element) => element.elements?.filter((child) => child.type === "element") ?? [];
 const collectText = (element) => {
 	let text = "";
@@ -86,12 +87,10 @@ const extractContainer = ({ container, source, startIndex }) => {
 		charCount
 	};
 };
-const extractParts = async ({ archive, source, rootName, startIndex }) => {
+const extractParts = async ({ archive, source, rootName, startIndex, paths }) => {
 	const paragraphs = [];
 	let charCount = 0;
 	let nextIndex = startIndex;
-	const prefix = `word/${source}`;
-	const paths = archive.entries.filter((path) => HEADER_FOOTER_PATH.test(path) && path.startsWith(prefix)).toSorted();
 	for (const path of paths) {
 		const xml = await archive.readEntryString(path);
 		if (xml === null) continue;
@@ -111,6 +110,50 @@ const extractParts = async ({ archive, source, rootName, startIndex }) => {
 		charCount
 	};
 };
+/** A `word/_rels/document.xml.rels` `Target` is relative to `word/`; resolve it to a full archive-entry path. */
+const resolveWordPartPath = (target) => target.startsWith("/") ? target.slice(1) : `word/${target}`;
+/**
+* Resolve the header/footer parts actually wired into the document via
+* `word/_rels/document.xml.rels` + each section's `w:headerReference` /
+* `w:footerReference`, instead of extracting every `word/header*.xml` /
+* `word/footer*.xml` entry by filename. A DOCX can carry an orphaned
+* header/footer part (stale, or planted by an attacker) that no section
+* references — reading it unconditionally would surface prompt-injection or
+* stale content that Word itself never renders.
+*/
+const resolveReferencedHeaderFooterParts = async (archive, documentRoot) => {
+	const relsXml = await archive.readEntryString(DOCUMENT_RELS_PATH);
+	if (relsXml === null) return {
+		headers: [],
+		footers: []
+	};
+	const relationships = parseRelationships(relsXml);
+	const headerRIds = /* @__PURE__ */ new Set();
+	const footerRIds = /* @__PURE__ */ new Set();
+	for (const sectPr of findAllDeep(documentRoot, "w", "sectPr")) {
+		for (const ref of findAllDeep(sectPr, "w", "headerReference")) {
+			const rId = getAttribute(ref, "r", "id");
+			if (rId !== null) headerRIds.add(rId);
+		}
+		for (const ref of findAllDeep(sectPr, "w", "footerReference")) {
+			const rId = getAttribute(ref, "r", "id");
+			if (rId !== null) footerRIds.add(rId);
+		}
+	}
+	const resolvePaths = (rIds, relationshipType) => {
+		const paths = /* @__PURE__ */ new Set();
+		for (const rId of rIds) {
+			const relationship = relationships.get(rId);
+			if (!relationship || relationship.type !== relationshipType || relationship.targetMode === "External") continue;
+			paths.add(resolveWordPartPath(relationship.target));
+		}
+		return [...paths].toSorted();
+	};
+	return {
+		headers: resolvePaths(headerRIds, RELATIONSHIP_TYPES.header),
+		footers: resolvePaths(footerRIds, RELATIONSHIP_TYPES.footer)
+	};
+};
 const createEmptyResult = () => ({
 	paragraphs: [],
 	charCount: 0,
@@ -121,13 +164,16 @@ const extractDocxText = async (bytes) => {
 	const archive = await loadDocxArchive(bytes);
 	const documentXml = await archive.readEntryString("word/document.xml");
 	if (documentXml === null) return createEmptyResult();
-	const body = findDeep(parseXml(documentXml), "w", "body");
+	const root = parseXml(documentXml);
+	const body = findDeep(root, "w", "body");
 	if (!body) return createEmptyResult();
+	const referencedParts = await resolveReferencedHeaderFooterParts(archive, root);
 	const headers = await extractParts({
 		archive,
 		source: "header",
 		rootName: "hdr",
-		startIndex: 0
+		startIndex: 0,
+		paths: referencedParts.headers
 	});
 	const bodyResult = extractContainer({
 		container: body,
@@ -138,7 +184,8 @@ const extractDocxText = async (bytes) => {
 		archive,
 		source: "footer",
 		rootName: "ftr",
-		startIndex: headers.paragraphs.length + bodyResult.paragraphs.length
+		startIndex: headers.paragraphs.length + bodyResult.paragraphs.length,
+		paths: referencedParts.footers
 	});
 	return {
 		paragraphs: [

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 };