@stll/folio-core 0.11.0 → 0.13.0

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

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

@@ -0,0 +1,41 @@
+import { document_d_exports } from "../../types/document.js";
+import { DocxArchiveOptions } from "./boundedArchive.js";
+
+//#region src/docx/server/validateDocxConformance.d.ts
+declare const FOLIO_DOCX_CONFORMANCE_REPORT_VERSION: 1;
+declare const FOLIO_DOCX_CONFORMANCE_PROFILE: "folio-supported-v1";
+declare const FOLIO_DOCX_CONFORMANCE_CHECKS: readonly ["archive-safety", "required-parts", "xml-well-formedness", "package-roots", "conformance-class", "canonical-model"];
+declare const FOLIO_DOCX_CONFORMANCE_ISSUE_CODES: readonly ["archive-load-failed", "archive-invalid-options", "archive-input-too-large", "archive-too-many-entries", "archive-entry-too-large", "archive-total-too-large", "required-part-missing", "xml-doctype-forbidden", "xml-not-well-formed", "xml-read-failed", "required-xml-unreadable", "package-root-invalid", "conformance-class-unknown", "model-invalid", "model-warning", "parser-recovery", "parser-unsupported", "parser-failed", "encrypted-container", "container-not-zip"];
+type FolioDocxConformanceCheckId = (typeof FOLIO_DOCX_CONFORMANCE_CHECKS)[number];
+type FolioDocxConformanceIssueCode = (typeof FOLIO_DOCX_CONFORMANCE_ISSUE_CODES)[number];
+type FolioDocxConformanceCheckStatus = "passed" | "failed" | "indeterminate" | "not-run";
+type FolioDocxConformanceStatus = "invalid" | "conformant" | "indeterminate";
+type FolioDocxConformanceIssue = {
+  readonly check: FolioDocxConformanceCheckId;
+  readonly code: FolioDocxConformanceIssueCode;
+  readonly message: string;
+  readonly severity: "error" | "warning";
+  readonly part?: string;
+  readonly modelPath?: string;
+  readonly count?: number;
+};
+type FolioDocxConformanceCheck = {
+  readonly id: FolioDocxConformanceCheckId;
+  readonly status: FolioDocxConformanceCheckStatus;
+};
+type FolioDocxConformanceReport = {
+  readonly version: typeof FOLIO_DOCX_CONFORMANCE_REPORT_VERSION;
+  readonly profile: typeof FOLIO_DOCX_CONFORMANCE_PROFILE;
+  readonly status: FolioDocxConformanceStatus;
+  readonly conformanceClass: document_d_exports.DocxConformanceClass;
+  readonly checks: readonly FolioDocxConformanceCheck[];
+  readonly issues: readonly FolioDocxConformanceIssue[];
+  readonly unverifiedStandardsDimensions: readonly ["complete-schema-constraints", "markup-compatibility-processing", "consumer-specific-rendering"];
+};
+type ValidateDocxConformanceOptions = {
+  readonly archive?: DocxArchiveOptions;
+};
+/** Assess a DOCX package against Folio's named, versioned support profile. */
+declare const validateDocxConformance: (bytes: ArrayBuffer | Uint8Array, options?: ValidateDocxConformanceOptions) => Promise<FolioDocxConformanceReport>;
+//#endregion
+export { FOLIO_DOCX_CONFORMANCE_CHECKS, FOLIO_DOCX_CONFORMANCE_ISSUE_CODES, FOLIO_DOCX_CONFORMANCE_PROFILE, FOLIO_DOCX_CONFORMANCE_REPORT_VERSION, FolioDocxConformanceCheck, FolioDocxConformanceCheckId, FolioDocxConformanceCheckStatus, FolioDocxConformanceIssue, FolioDocxConformanceIssueCode, FolioDocxConformanceReport, FolioDocxConformanceStatus, ValidateDocxConformanceOptions, validateDocxConformance };

package/dist/docx/server/validateDocxConformance.js

@@ -0,0 +1,336 @@
+import { findChildByLocalName, getAttributeAnyPrefix, getLocalName, getNamespacePrefix, parseXmlDocument } from "../xmlParser.js";
+import { detectDocxConformanceClass } from "../conformance.js";
+import { DocxModelValidationError, validateFolioDocumentModel } from "../modelValidation.js";
+import { DOCX_CONTAINER_TYPES, detectDocxContainerType } from "../encryption/containerFormat.js";
+import { DocxParseError, parseDocx } from "../parser.js";
+import { DocxArchiveError, loadDocxArchive } from "./boundedArchive.js";
+import { getDocxXmlSafetyIssue } from "../xmlSafety.js";
+import { DOCX_CONFORMANCE_CLASSES } from "@stll/docx-core/model";
+//#region src/docx/server/validateDocxConformance.ts
+const FOLIO_DOCX_CONFORMANCE_REPORT_VERSION = 1;
+const FOLIO_DOCX_CONFORMANCE_PROFILE = "folio-supported-v1";
+const FOLIO_DOCX_CONFORMANCE_CHECKS = Object.freeze([
+	"archive-safety",
+	"required-parts",
+	"xml-well-formedness",
+	"package-roots",
+	"conformance-class",
+	"canonical-model"
+]);
+const FOLIO_DOCX_CONFORMANCE_ISSUE_CODES = Object.freeze([
+	"archive-load-failed",
+	"archive-invalid-options",
+	"archive-input-too-large",
+	"archive-too-many-entries",
+	"archive-entry-too-large",
+	"archive-total-too-large",
+	"required-part-missing",
+	"xml-doctype-forbidden",
+	"xml-not-well-formed",
+	"xml-read-failed",
+	"required-xml-unreadable",
+	"package-root-invalid",
+	"conformance-class-unknown",
+	"model-invalid",
+	"model-warning",
+	"parser-recovery",
+	"parser-unsupported",
+	"parser-failed",
+	"encrypted-container",
+	"container-not-zip"
+]);
+const REQUIRED_PARTS = Object.freeze([
+	"[Content_Types].xml",
+	"_rels/.rels",
+	"word/document.xml"
+]);
+const XML_PART_PATTERN = /(?:\.xml|\.rels)$/u;
+const DOCUMENT_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml";
+const CONTENT_TYPES_NAMESPACE = "http://schemas.openxmlformats.org/package/2006/content-types";
+const RELATIONSHIPS_NAMESPACE = "http://schemas.openxmlformats.org/package/2006/relationships";
+const UNVERIFIED_STANDARDS_DIMENSIONS = Object.freeze([
+	"complete-schema-constraints",
+	"markup-compatibility-processing",
+	"consumer-specific-rendering"
+]);
+const createMutableReport = () => ({
+	conformanceClass: DOCX_CONFORMANCE_CLASSES.UNKNOWN,
+	checks: new Map(FOLIO_DOCX_CONFORMANCE_CHECKS.map((id) => [id, "not-run"])),
+	issues: []
+});
+const addIssue = (report, issue) => {
+	report.issues.push(issue);
+};
+const finishReport = (report) => {
+	const checks = FOLIO_DOCX_CONFORMANCE_CHECKS.map((id) => ({
+		id,
+		status: report.checks.get(id) ?? "not-run"
+	}));
+	const hasFailedCheck = checks.some(({ status }) => status === "failed");
+	const hasIndeterminateCheck = checks.some(({ status }) => status === "indeterminate");
+	let status = "conformant";
+	if (hasFailedCheck) status = "invalid";
+	else if (hasIndeterminateCheck || checks.some(({ status: checkStatus }) => checkStatus === "not-run")) status = "indeterminate";
+	return {
+		version: 1,
+		profile: FOLIO_DOCX_CONFORMANCE_PROFILE,
+		status,
+		conformanceClass: report.conformanceClass,
+		checks,
+		issues: report.issues,
+		unverifiedStandardsDimensions: UNVERIFIED_STANDARDS_DIMENSIONS
+	};
+};
+const validateRequiredParts = (archive, report) => {
+	const entries = new Set(archive.entries);
+	const missingParts = REQUIRED_PARTS.filter((path) => !entries.has(path));
+	if (missingParts.length === 0) {
+		report.checks.set("required-parts", "passed");
+		return true;
+	}
+	report.checks.set("required-parts", "failed");
+	for (const part of missingParts) addIssue(report, {
+		check: "required-parts",
+		code: "required-part-missing",
+		message: "A required package part is missing.",
+		severity: "error",
+		part
+	});
+	return false;
+};
+const validateXmlParts = async (archive, report) => {
+	const xmlByPath = /* @__PURE__ */ new Map();
+	let hasInvalidXml = false;
+	for (const part of archive.entries.filter((path) => XML_PART_PATTERN.test(path)).toSorted()) {
+		const xml = await archive.readEntryString(part);
+		if (xml === null) continue;
+		xmlByPath.set(part, xml);
+		const safetyIssue = getDocxXmlSafetyIssue(xml);
+		if (safetyIssue === "doctype-forbidden") {
+			hasInvalidXml = true;
+			addIssue(report, {
+				check: "xml-well-formedness",
+				code: "xml-doctype-forbidden",
+				message: "XML package parts must not declare a document type.",
+				severity: "error",
+				part
+			});
+			continue;
+		}
+		if (safetyIssue === "not-well-formed") {
+			hasInvalidXml = true;
+			addIssue(report, {
+				check: "xml-well-formedness",
+				code: "xml-not-well-formed",
+				message: "An XML package part is not well formed.",
+				severity: "error",
+				part
+			});
+		}
+	}
+	if (hasInvalidXml) {
+		report.checks.set("xml-well-formedness", "failed");
+		return null;
+	}
+	report.checks.set("xml-well-formedness", "passed");
+	const contentTypesXml = xmlByPath.get("[Content_Types].xml");
+	const packageRelationshipsXml = xmlByPath.get("_rels/.rels");
+	const documentXml = xmlByPath.get("word/document.xml");
+	if (contentTypesXml === void 0 || packageRelationshipsXml === void 0 || documentXml === void 0) {
+		report.checks.set("xml-well-formedness", "indeterminate");
+		addIssue(report, {
+			check: "xml-well-formedness",
+			code: "required-xml-unreadable",
+			message: "A required XML package part could not be read.",
+			severity: "error"
+		});
+		return null;
+	}
+	return {
+		contentTypesXml,
+		packageRelationshipsXml,
+		documentXml
+	};
+};
+const hasRootNamespace = ({ name, attributes, expected }) => {
+	const prefix = getNamespacePrefix(name);
+	const attribute = prefix === null ? "xmlns" : `xmlns:${prefix}`;
+	return attributes?.[attribute] === expected;
+};
+const hasDocumentContentType = (contentTypesXml) => {
+	const root = parseXmlDocument(contentTypesXml);
+	if (root === null || getLocalName(root.name ?? "") !== "Types" || !hasRootNamespace({
+		name: root.name ?? "",
+		attributes: root.attributes,
+		expected: CONTENT_TYPES_NAMESPACE
+	})) return false;
+	return root.elements?.some((element) => element.type === "element" && getLocalName(element.name ?? "") === "Override" && getAttributeAnyPrefix(element, "PartName") === "/word/document.xml" && getAttributeAnyPrefix(element, "ContentType") === DOCUMENT_CONTENT_TYPE) ?? false;
+};
+const hasMainDocumentRelationship = (packageRelationshipsXml) => {
+	const root = parseXmlDocument(packageRelationshipsXml);
+	if (root === null || getLocalName(root.name ?? "") !== "Relationships" || !hasRootNamespace({
+		name: root.name ?? "",
+		attributes: root.attributes,
+		expected: RELATIONSHIPS_NAMESPACE
+	})) return false;
+	return root.elements?.some((element) => {
+		if (element.type !== "element" || getLocalName(element.name ?? "") !== "Relationship") return false;
+		const type = getAttributeAnyPrefix(element, "Type");
+		const target = getAttributeAnyPrefix(element, "Target")?.replace(/^\.?\//u, "");
+		return type?.endsWith("/officeDocument") === true && target === "word/document.xml" && getAttributeAnyPrefix(element, "TargetMode") !== "External";
+	}) ?? false;
+};
+const hasDocumentRoot = (documentXml) => {
+	const root = parseXmlDocument(documentXml);
+	return root !== null && getLocalName(root.name ?? "") === "document" && findChildByLocalName(root, "body") !== null;
+};
+const validatePackageRoots = (xml, report) => {
+	const invalidParts = [];
+	if (!hasDocumentContentType(xml.contentTypesXml)) invalidParts.push("[Content_Types].xml");
+	if (!hasMainDocumentRelationship(xml.packageRelationshipsXml)) invalidParts.push("_rels/.rels");
+	if (!hasDocumentRoot(xml.documentXml)) invalidParts.push("word/document.xml");
+	if (invalidParts.length === 0) {
+		report.checks.set("package-roots", "passed");
+		return true;
+	}
+	report.checks.set("package-roots", "failed");
+	for (const part of invalidParts) addIssue(report, {
+		check: "package-roots",
+		code: "package-root-invalid",
+		message: "A required package part does not declare the expected root or main document binding.",
+		severity: "error",
+		part
+	});
+	return false;
+};
+const validateConformanceClass = (documentXml, report) => {
+	report.conformanceClass = detectDocxConformanceClass(documentXml);
+	if (report.conformanceClass !== DOCX_CONFORMANCE_CLASSES.UNKNOWN) {
+		report.checks.set("conformance-class", "passed");
+		return;
+	}
+	report.checks.set("conformance-class", "indeterminate");
+	addIssue(report, {
+		check: "conformance-class",
+		code: "conformance-class-unknown",
+		message: "The main document namespace does not identify a supported conformance class.",
+		severity: "warning",
+		part: "word/document.xml"
+	});
+};
+const findModelValidationError = (error) => {
+	let current = error;
+	while (current instanceof Error) {
+		if (current instanceof DocxModelValidationError) return current;
+		current = "cause" in current ? current.cause : void 0;
+	}
+	return null;
+};
+const validateCanonicalModel = async (bytes, report) => {
+	try {
+		const document = await parseDocx(bytes, {
+			detectVariables: false,
+			preloadFonts: false
+		});
+		const validation = validateFolioDocumentModel(document);
+		const warningCount = document.warnings?.length ?? 0;
+		if (!validation.valid) report.checks.set("canonical-model", "failed");
+		else if (warningCount > 0) {
+			report.checks.set("canonical-model", "indeterminate");
+			addIssue(report, {
+				check: "canonical-model",
+				code: "parser-recovery",
+				message: "The canonical parser reported recovery or preservation warnings.",
+				severity: "warning",
+				count: warningCount
+			});
+		} else report.checks.set("canonical-model", "passed");
+		for (const issue of validation.issues) addIssue(report, {
+			check: "canonical-model",
+			code: issue.severity === "error" ? "model-invalid" : "model-warning",
+			message: issue.message,
+			severity: issue.severity,
+			modelPath: issue.path
+		});
+	} catch (error) {
+		const modelError = findModelValidationError(error);
+		if (modelError !== null) {
+			report.checks.set("canonical-model", "failed");
+			for (const issue of modelError.issues) addIssue(report, {
+				check: "canonical-model",
+				code: issue.severity === "error" ? "model-invalid" : "model-warning",
+				message: issue.message,
+				severity: issue.severity,
+				modelPath: issue.path
+			});
+			return;
+		}
+		report.checks.set("canonical-model", "indeterminate");
+		addIssue(report, {
+			check: "canonical-model",
+			code: error instanceof DocxParseError ? "parser-unsupported" : "parser-failed",
+			message: "The canonical document model could not be assessed.",
+			severity: "warning"
+		});
+	}
+};
+/** Assess a DOCX package against Folio's named, versioned support profile. */
+const validateDocxConformance = async (bytes, options = {}) => {
+	const report = createMutableReport();
+	const containerType = detectDocxContainerType(bytes);
+	if (containerType === DOCX_CONTAINER_TYPES.CFB) {
+		report.checks.set("archive-safety", "indeterminate");
+		addIssue(report, {
+			check: "archive-safety",
+			code: "encrypted-container",
+			message: "Encrypted containers require decryption before this profile can assess them.",
+			severity: "warning"
+		});
+		return finishReport(report);
+	}
+	if (containerType !== DOCX_CONTAINER_TYPES.ZIP) {
+		report.checks.set("archive-safety", "failed");
+		addIssue(report, {
+			check: "archive-safety",
+			code: "container-not-zip",
+			message: "The input is not a supported DOCX package container.",
+			severity: "error"
+		});
+		return finishReport(report);
+	}
+	let archive;
+	try {
+		archive = await loadDocxArchive(bytes, options.archive);
+		report.checks.set("archive-safety", "passed");
+	} catch (error) {
+		report.checks.set("archive-safety", "failed");
+		addIssue(report, {
+			check: "archive-safety",
+			code: error instanceof DocxArchiveError ? `archive-${error.reason}` : "archive-load-failed",
+			message: "The DOCX package could not be loaded within the configured safety limits.",
+			severity: "error"
+		});
+		return finishReport(report);
+	}
+	if (!validateRequiredParts(archive, report)) return finishReport(report);
+	let xml;
+	try {
+		xml = await validateXmlParts(archive, report);
+	} catch (error) {
+		report.checks.set("xml-well-formedness", "indeterminate");
+		addIssue(report, {
+			check: "xml-well-formedness",
+			code: error instanceof DocxArchiveError ? `archive-${error.reason}` : "xml-read-failed",
+			message: "The XML package parts could not be read within the configured safety limits.",
+			severity: "warning"
+		});
+		return finishReport(report);
+	}
+	if (xml === null) return finishReport(report);
+	if (!validatePackageRoots(xml, report)) return finishReport(report);
+	validateConformanceClass(xml.documentXml, report);
+	await validateCanonicalModel(bytes, report);
+	return finishReport(report);
+};
+//#endregion
+export { FOLIO_DOCX_CONFORMANCE_CHECKS, FOLIO_DOCX_CONFORMANCE_ISSUE_CODES, FOLIO_DOCX_CONFORMANCE_PROFILE, FOLIO_DOCX_CONFORMANCE_REPORT_VERSION, validateDocxConformance };

package/dist/docx/settingsParser.js

@@ -1,4 +1,4 @@
-import { findChild, getAttribute, parseBooleanElement, parseXmlDocument } from "./xmlParser.js";
+import { findChild, findChildren, getAttribute, parseBooleanElement, parseXmlDocument } from "./xmlParser.js";
 //#region src/docx/settingsParser.ts
 /** OOXML default per §17.6.13 when `w:defaultTabStop` is absent. */
 const DEFAULT_TAB_STOP_TWIPS = 720;
@@ -10,6 +10,19 @@ const DEFAULT_TAB_STOP_TWIPS = 720;
 const MAX_TAB_STOP_TWIPS = 31680;
 const MAX_HYPHENATION_ZONE_TWIPS = 31680;
 const MAX_CONSECUTIVE_HYPHEN_LIMIT = 255;
+/**
+* Floor on `w:defaultTabStop`, in twips (1/12 inch). A near-zero value would
+* force the layout engine to generate thousands of tab stops across a
+* single line; below this floor we substitute the OOXML default instead.
+*/
+const MIN_TAB_STOP_TWIPS = 120;
+/**
+* Sanity cap on parsed `w:noLineBreaksBefore`/`w:noLineBreaksAfter`
+* character lists. Typical kinsoku overrides list a handful of prohibited
+* characters; anything past this is corruption or a hostile input crafted
+* to inflate the per-character membership set built at measure time.
+*/
+const MAX_KINSOKU_CHARACTERS_LENGTH = 128;
 function parseSettings(xml) {
 	const root = xml ? parseXmlDocument(xml) : null;
 	const settings = { defaultTabStop: parseDefaultTabStop(root) };
@@ -35,6 +48,8 @@ function parseSettings(xml) {
 	const noLineBreaksBefore = parseKinsokuOverride(root, "noLineBreaksBefore");
 	const noLineBreaksAfter = parseKinsokuOverride(root, "noLineBreaksAfter");
 	const compat = root ? findChild(root, "w", "compat") : null;
+	const compatibilityMode = parseCompatibilityMode(compat);
+	if (compatibilityMode !== void 0) settings.compatibilityMode = compatibilityMode;
 	const splitPageBreakAndParagraphMark = compat ? findChild(compat, "w", "splitPgBreakAndParaMark") : null;
 	if (splitPageBreakAndParagraphMark && parseBooleanElement(splitPageBreakAndParagraphMark)) settings.splitPageBreakAndParagraphMark = true;
 	const applyBreakingRules = compat ? findChild(compat, "w", "applyBreakingRules") : null;
@@ -46,6 +61,14 @@ function parseSettings(xml) {
 	};
 	return settings;
 }
+function parseCompatibilityMode(compat) {
+	if (!compat) return;
+	const setting = findChildren(compat, "w", "compatSetting").find((candidate) => getAttribute(candidate, "w", "name") === "compatibilityMode");
+	const raw = setting ? getAttribute(setting, "w", "val") : null;
+	if (raw === null || !/^\d+$/u.test(raw)) return;
+	const parsed = Number.parseInt(raw, 10);
+	return Number.isSafeInteger(parsed) ? parsed : void 0;
+}
 function parseOnOffSetting(root, name) {
 	if (!root) return;
 	const element = findChild(root, "w", name);
@@ -66,7 +89,7 @@ function parseKinsokuOverride(root, name) {
 	if (!characters) return;
 	const language = getAttribute(element, "w", "lang") || void 0;
 	return {
-		characters,
+		characters: Array.from(characters).slice(0, MAX_KINSOKU_CHARACTERS_LENGTH).join(""),
 		...language ? { language } : {}
 	};
 }
@@ -77,7 +100,7 @@ function parseDefaultTabStop(root) {
 	const raw = getAttribute(el, "w", "val");
 	if (raw === null) return 720;
 	const parsed = Number.parseInt(raw, 10);
-	if (!Number.isFinite(parsed) || parsed <= 0 || parsed > MAX_TAB_STOP_TWIPS) return 720;
+	if (!Number.isFinite(parsed) || parsed < MIN_TAB_STOP_TWIPS || parsed > MAX_TAB_STOP_TWIPS) return 720;
 	return parsed;
 }
 //#endregion

package/dist/docx/shapeParser.js

@@ -1,5 +1,5 @@
-import { findAllDeep, findChildByLocalName, findChildrenByLocalName, getAttribute, parseNumericAttribute } from "./xmlParser.js";
 import { ShapeOutlineStyleSchema, ShapeTypeSchema, narrowEnum } from "./parserEnums.js";
+import { findAllDeep, findChildByLocalName, findChildrenByLocalName, getAttribute, parseNumericAttribute } from "./xmlParser.js";
 import { parseAnchorPosition, parseAnchorWrap, parseColorElement, parseFill } from "./drawingUtils.js";
 //#region src/docx/shapeParser.ts
 /** Convert OOXML rotation (1/60000ths of a degree) to degrees. */