@stll/folio-core 0.10.0 → 0.12.0

package/dist/docx/serializer/tableSerializer.js

@@ -1,6 +1,5 @@
 import { escapeXml, intAttr } from "./xmlUtils.js";
 import { serializeBorder } from "./borderSerializer.js";
-import { serializeParagraph } from "./paragraphSerializer.js";
 //#region src/docx/serializer/tableSerializer.ts
 function normalizeTrackedChangeInfo(info) {
 	const normalizedId = Number.isInteger(info.id) && info.id >= 0 ? info.id : 0;
@@ -247,12 +246,17 @@ function serializeTableCellFormatting(formatting, propertyChanges, structuralCha
 		if (formatting.textDirection) parts.push(`<w:textDirection w:val="${formatting.textDirection}"/>`);
 		if (formatting.fitText) parts.push("<w:tcFitText/>");
 		if (formatting.verticalAlign) parts.push(`<w:vAlign w:val="${formatting.verticalAlign}"/>`);
-		if (formatting.hideMark) parts.push("<w:hideMark/>");
+		if (formatting.hideMark !== void 0) parts.push(formatting.hideMark ? "<w:hideMark/>" : "<w:hideMark w:val=\"false\"/>");
 	}
 	if (structuralChange) {
 		if (structuralChange.type === "tableCellInsertion") parts.push(`<w:cellIns ${serializeTrackedChangeAttributes(structuralChange.info)}/>`);
 		else if (structuralChange.type === "tableCellDeletion") parts.push(`<w:cellDel ${serializeTrackedChangeAttributes(structuralChange.info)}/>`);
-		else if (structuralChange.type === "tableCellMerge") parts.push(`<w:cellMerge ${serializeTrackedChangeAttributes(structuralChange.info)}/>`);
+		else if (structuralChange.type === "tableCellMerge") {
+			const attrs = [serializeTrackedChangeAttributes(structuralChange.info)];
+			if (structuralChange.verticalMerge) attrs.push(`w:vMerge="${structuralChange.verticalMerge === "continue" ? "cont" : "rest"}"`);
+			if (structuralChange.verticalMergeOriginal) attrs.push(`w:vMergeOrig="${structuralChange.verticalMergeOriginal === "continue" ? "cont" : "rest"}"`);
+			parts.push(`<w:cellMerge ${attrs.join(" ")}/>`);
+		}
 	}
 	if (propertyChanges && propertyChanges.length > 0) parts.push(...propertyChanges.map((change) => serializeTableCellPropertyChange(change)));
 	if (parts.length === 0) return "";
@@ -277,31 +281,31 @@ function serializeTableGrid(columnWidths) {
 /**
 * Serialize cell content (paragraphs, nested tables)
 */
-function serializeCellContent(content) {
+function serializeCellContent(content, serializeParagraph) {
 	const parts = [];
 	for (const item of content) if (item.type === "paragraph") parts.push(serializeParagraph(item));
-	else parts.push(serializeTable(item));
+	else parts.push(serializeTable(item, serializeParagraph));
 	if (parts.length === 0) parts.push("<w:p/>");
 	return parts.join("");
 }
 /**
 * Serialize a table cell (w:tc)
 */
-function serializeTableCell(cell) {
+function serializeTableCell(cell, serializeParagraph) {
 	const parts = [];
 	const tcPrXml = serializeTableCellFormatting(cell.formatting, cell.propertyChanges, cell.structuralChange);
 	if (tcPrXml) parts.push(tcPrXml);
-	parts.push(serializeCellContent(cell.content));
+	parts.push(serializeCellContent(cell.content, serializeParagraph));
 	return `<w:tc>${parts.join("")}</w:tc>`;
 }
 /**
 * Serialize a table row (w:tr)
 */
-function serializeTableRow(row) {
+function serializeTableRow(row, serializeParagraph) {
 	const parts = [];
 	const trPrXml = serializeTableRowFormatting(row.formatting, row.propertyChanges, row.structuralChange);
 	if (trPrXml) parts.push(trPrXml);
-	for (const cell of row.cells) parts.push(serializeTableCell(cell));
+	for (const cell of row.cells) parts.push(serializeTableCell(cell, serializeParagraph));
 	return `<w:tr>${parts.join("")}</w:tr>`;
 }
 /**
@@ -310,13 +314,13 @@ function serializeTableRow(row) {
 * @param table - The table to serialize
 * @returns XML string for the table
 */
-function serializeTable(table) {
+function serializeTable(table, serializeParagraph) {
 	const parts = [];
 	const tblPrXml = serializeTableFormatting(table.formatting, table.propertyChanges);
 	if (tblPrXml) parts.push(tblPrXml);
 	const tblGridXml = serializeTableGrid(table.columnWidths);
 	if (tblGridXml) parts.push(tblGridXml);
-	for (const row of table.rows) parts.push(serializeTableRow(row));
+	for (const row of table.rows) parts.push(serializeTableRow(row, serializeParagraph));
 	return `<w:tbl>${parts.join("")}</w:tbl>`;
 }
 /**
@@ -325,8 +329,8 @@ function serializeTable(table) {
 * @param tables - The tables to serialize
 * @returns XML string for all tables
 */
-function serializeTables(tables) {
-	return tables.map(serializeTable).join("");
+function serializeTables(tables, serializeParagraph) {
+	return tables.map((table) => serializeTable(table, serializeParagraph)).join("");
 }
 /**
 * Check if a table has any rows

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

@@ -0,0 +1,87 @@
+import { DocxArchiveOptions } from "./boundedArchive.js";
+import { FOLIO_DOCX_XML_PATCH_PROPOSAL_PROFILE, FolioDocxPreparedXmlReplacement, FolioDocxXmlPatchProposalEvaluation, FolioDocxXmlPatchProposalLimits } from "./evaluateDocxXmlPatchProposal.js";
+import { FOLIO_DOCX_CONFORMANCE_PROFILE, FolioDocxConformanceReport } from "./validateDocxConformance.js";
+
+//#region src/docx/server/applyDocxXmlPatchProposal.d.ts
+declare const FOLIO_DOCX_XML_PATCH_APPLICATION_VERSION: 1;
+declare const FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE: "folio-xml-patch-application-v1";
+type ApplyDocxXmlPatchProposalArgs = {
+  readonly bytes: ArrayBuffer | Uint8Array;
+  readonly proposal: unknown; /** Exact package paths authorized by the server-side caller. */
+  readonly allowedParts: readonly string[];
+  readonly validationProfile: typeof FOLIO_DOCX_CONFORMANCE_PROFILE;
+  readonly archive?: DocxArchiveOptions;
+  readonly limits?: FolioDocxXmlPatchProposalLimits;
+};
+type FolioDocxXmlPatchApplicationReceipt = {
+  readonly version: typeof FOLIO_DOCX_XML_PATCH_APPLICATION_VERSION;
+  readonly profile: typeof FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE;
+  readonly proposalProfile: typeof FOLIO_DOCX_XML_PATCH_PROPOSAL_PROFILE;
+  readonly validationProfile: typeof FOLIO_DOCX_CONFORMANCE_PROFILE;
+  readonly input: {
+    readonly sha256: string;
+    readonly byteLength: number;
+  };
+  readonly output: {
+    readonly sha256: string;
+    readonly byteLength: number;
+  };
+  readonly replacements: readonly [FolioDocxPreparedXmlReplacement, ...FolioDocxPreparedXmlReplacement[]];
+};
+type FolioDocxXmlPatchApplication = {
+  readonly version: typeof FOLIO_DOCX_XML_PATCH_APPLICATION_VERSION;
+  readonly profile: typeof FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE;
+  readonly status: "proposal-rejected";
+  readonly producesOutput: false;
+  readonly evaluation: Extract<FolioDocxXmlPatchProposalEvaluation, {
+    status: "rejected";
+  }>;
+  readonly conformance: null;
+  readonly receipt: null;
+} | {
+  readonly version: typeof FOLIO_DOCX_XML_PATCH_APPLICATION_VERSION;
+  readonly profile: typeof FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE;
+  readonly status: "output-rejected";
+  readonly producesOutput: false;
+  readonly evaluation: Extract<FolioDocxXmlPatchProposalEvaluation, {
+    status: "accepted";
+  }>;
+  readonly conformance: FolioDocxConformanceReport;
+  readonly receipt: null;
+} | {
+  readonly version: typeof FOLIO_DOCX_XML_PATCH_APPLICATION_VERSION;
+  readonly profile: typeof FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE;
+  readonly status: "applied";
+  readonly producesOutput: true;
+  readonly evaluation: Extract<FolioDocxXmlPatchProposalEvaluation, {
+    status: "accepted";
+  }>;
+  readonly conformance: FolioDocxConformanceReport & {
+    readonly status: "conformant";
+  };
+  readonly receipt: FolioDocxXmlPatchApplicationReceipt;
+  readonly bytes: Uint8Array;
+};
+declare const UnsupportedFolioDocxXmlPatchApplicationProfileError_base: import("better-result").TaggedErrorClass<"UnsupportedFolioDocxXmlPatchApplicationProfileError", {
+  message: string;
+  profile: unknown;
+}>;
+declare class UnsupportedFolioDocxXmlPatchApplicationProfileError extends UnsupportedFolioDocxXmlPatchApplicationProfileError_base {}
+declare const FolioDocxXmlPatchApplicationError_base: import("better-result").TaggedErrorClass<"FolioDocxXmlPatchApplicationError", {
+  message: string;
+  stage: "verify" | "load" | "replace" | "generate";
+  part?: string;
+  cause?: unknown;
+}>;
+declare class FolioDocxXmlPatchApplicationError extends FolioDocxXmlPatchApplicationError_base {}
+/** Apply a guarded XML proposal and return output only after full profile validation. */
+declare const applyDocxXmlPatchProposal: ({
+  bytes,
+  proposal: rawProposal,
+  allowedParts,
+  validationProfile,
+  archive,
+  limits
+}: ApplyDocxXmlPatchProposalArgs) => Promise<FolioDocxXmlPatchApplication>;
+//#endregion
+export { ApplyDocxXmlPatchProposalArgs, FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE, FOLIO_DOCX_XML_PATCH_APPLICATION_VERSION, FolioDocxXmlPatchApplication, FolioDocxXmlPatchApplicationError, FolioDocxXmlPatchApplicationReceipt, UnsupportedFolioDocxXmlPatchApplicationProfileError, applyDocxXmlPatchProposal };

package/dist/docx/server/applyDocxXmlPatchProposal.js

@@ -0,0 +1,204 @@
+import { loadDocxArchive } from "./boundedArchive.js";
+import { FOLIO_DOCX_XML_PATCH_PROPOSAL_PROFILE, InvalidFolioDocxXmlPatchProposalError, evaluateDocxXmlPatchProposal, parseFolioDocxXmlPatchProposal } from "./evaluateDocxXmlPatchProposal.js";
+import { FOLIO_DOCX_CONFORMANCE_PROFILE, validateDocxConformance } from "./validateDocxConformance.js";
+import { TaggedError, panic } from "better-result";
+import JSZip from "jszip";
+import { createHash } from "node:crypto";
+//#region src/docx/server/applyDocxXmlPatchProposal.ts
+const FOLIO_DOCX_XML_PATCH_APPLICATION_VERSION = 1;
+const FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE = "folio-xml-patch-application-v1";
+const isConformantReport = (report) => report.status === "conformant";
+var UnsupportedFolioDocxXmlPatchApplicationProfileError = class extends TaggedError("UnsupportedFolioDocxXmlPatchApplicationProfileError")() {};
+var FolioDocxXmlPatchApplicationError = class extends TaggedError("FolioDocxXmlPatchApplicationError")() {};
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const snapshotInput = (bytes) => Uint8Array.from(bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes));
+const snapshotArchiveOptions = (archive) => {
+	if (archive === void 0) return;
+	return {
+		...archive.maxInputBytes === void 0 ? {} : { maxInputBytes: archive.maxInputBytes },
+		...archive.maxEntryBytes === void 0 ? {} : { maxEntryBytes: archive.maxEntryBytes },
+		...archive.maxTotalBytes === void 0 ? {} : { maxTotalBytes: archive.maxTotalBytes },
+		...archive.maxEntries === void 0 ? {} : { maxEntries: archive.maxEntries }
+	};
+};
+const snapshotProposalLimits = (limits) => {
+	if (limits === void 0) return;
+	return {
+		...limits.maxReplacements === void 0 ? {} : { maxReplacements: limits.maxReplacements },
+		...limits.maxPartBytes === void 0 ? {} : { maxPartBytes: limits.maxPartBytes },
+		...limits.maxTotalBytes === void 0 ? {} : { maxTotalBytes: limits.maxTotalBytes }
+	};
+};
+const evaluateProposal = async ({ bytes, proposal, allowedParts, archive, limits }) => await evaluateDocxXmlPatchProposal({
+	bytes,
+	proposal,
+	allowedParts,
+	...archive === void 0 ? {} : { archive },
+	...limits === void 0 ? {} : { limits }
+});
+const proposalRejected = ({ evaluation }) => ({
+	version: 1,
+	profile: FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE,
+	status: "proposal-rejected",
+	producesOutput: false,
+	evaluation,
+	conformance: null,
+	receipt: null
+});
+const verifyArchiveContents = async (bytes, options) => {
+	let archive;
+	try {
+		archive = await loadDocxArchive(bytes, options);
+	} catch (cause) {
+		throw new FolioDocxXmlPatchApplicationError({
+			message: "The evaluated package could not be verified within the archive limits.",
+			stage: "verify",
+			cause
+		});
+	}
+	for (const entry of archive.entryMetadata.toSorted(({ path: left }, { path: right }) => left < right ? -1 : Number(left > right))) {
+		if (entry.directory) continue;
+		try {
+			if (await archive.readEntryUint8(entry.path) === null) throw new FolioDocxXmlPatchApplicationError({
+				message: "An archive entry disappeared during verification.",
+				stage: "verify",
+				part: entry.path
+			});
+		} catch (cause) {
+			if (cause instanceof FolioDocxXmlPatchApplicationError) throw cause;
+			throw new FolioDocxXmlPatchApplicationError({
+				message: "An archive entry could not be verified within the configured limits.",
+				stage: "verify",
+				part: entry.path,
+				cause
+			});
+		}
+	}
+};
+const applyReplacements = async ({ bytes, proposal }) => {
+	let zip;
+	try {
+		zip = await JSZip.loadAsync(bytes);
+	} catch (cause) {
+		throw new FolioDocxXmlPatchApplicationError({
+			message: "The evaluated package could not be loaded for replacement.",
+			stage: "load",
+			cause
+		});
+	}
+	for (const replacement of proposal.replacements) {
+		const current = zip.file(replacement.path);
+		if (current === null) throw new FolioDocxXmlPatchApplicationError({
+			message: "An evaluated package part was unavailable during replacement.",
+			stage: "replace"
+		});
+		zip.file(replacement.path, new TextEncoder().encode(replacement.replacementXml), {
+			binary: true,
+			date: current.date,
+			comment: current.comment,
+			createFolders: false,
+			unixPermissions: current.unixPermissions,
+			dosPermissions: current.dosPermissions,
+			compression: "DEFLATE",
+			compressionOptions: { level: 6 }
+		});
+	}
+	try {
+		return await zip.generateAsync({
+			type: "uint8array",
+			compression: "DEFLATE",
+			compressionOptions: { level: 6 }
+		});
+	} catch (cause) {
+		throw new FolioDocxXmlPatchApplicationError({
+			message: "The replacement package could not be generated.",
+			stage: "generate",
+			cause
+		});
+	}
+};
+const outputRejected = ({ evaluation, conformance }) => ({
+	version: 1,
+	profile: FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE,
+	status: "output-rejected",
+	producesOutput: false,
+	evaluation,
+	conformance,
+	receipt: null
+});
+const applied = ({ input, output, evaluation, conformance }) => ({
+	version: 1,
+	profile: FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE,
+	status: "applied",
+	producesOutput: true,
+	evaluation,
+	conformance,
+	receipt: {
+		version: 1,
+		profile: FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE,
+		proposalProfile: FOLIO_DOCX_XML_PATCH_PROPOSAL_PROFILE,
+		validationProfile: FOLIO_DOCX_CONFORMANCE_PROFILE,
+		input: {
+			sha256: sha256(input),
+			byteLength: input.byteLength
+		},
+		output: {
+			sha256: sha256(output),
+			byteLength: output.byteLength
+		},
+		replacements: evaluation.replacements
+	},
+	bytes: output
+});
+/** Apply a guarded XML proposal and return output only after full profile validation. */
+const applyDocxXmlPatchProposal = async ({ bytes, proposal: rawProposal, allowedParts, validationProfile, archive, limits }) => {
+	if (validationProfile !== "folio-supported-v1") throw new UnsupportedFolioDocxXmlPatchApplicationProfileError({
+		message: "The requested package validation profile is not supported.",
+		profile: validationProfile
+	});
+	const input = snapshotInput(bytes);
+	const policyAllowedParts = [...allowedParts];
+	const policyArchive = snapshotArchiveOptions(archive);
+	const policyLimits = snapshotProposalLimits(limits);
+	let proposal;
+	try {
+		proposal = parseFolioDocxXmlPatchProposal(rawProposal);
+	} catch (error) {
+		if (!(error instanceof InvalidFolioDocxXmlPatchProposalError)) throw error;
+		const evaluation = await evaluateProposal({
+			bytes: input,
+			proposal: rawProposal,
+			allowedParts: policyAllowedParts,
+			archive: policyArchive,
+			limits: policyLimits
+		});
+		if (evaluation.status !== "rejected") return panic("An invalid XML proposal produced an accepted evaluation");
+		return proposalRejected({ evaluation });
+	}
+	const evaluation = await evaluateProposal({
+		bytes: input,
+		proposal,
+		allowedParts: policyAllowedParts,
+		archive: policyArchive,
+		limits: policyLimits
+	});
+	if (evaluation.status === "rejected") return proposalRejected({ evaluation });
+	await verifyArchiveContents(input, policyArchive);
+	const output = await applyReplacements({
+		bytes: input,
+		proposal
+	});
+	const conformance = await validateDocxConformance(output, { ...policyArchive === void 0 ? {} : { archive: policyArchive } });
+	if (!isConformantReport(conformance)) return outputRejected({
+		evaluation,
+		conformance
+	});
+	return applied({
+		input,
+		output,
+		evaluation,
+		conformance
+	});
+};
+//#endregion
+export { FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE, FOLIO_DOCX_XML_PATCH_APPLICATION_VERSION, FolioDocxXmlPatchApplicationError, UnsupportedFolioDocxXmlPatchApplicationProfileError, applyDocxXmlPatchProposal };

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

@@ -2,23 +2,34 @@
 declare const DOCX_MAX_ENTRY_BYTES: number;
 declare const DOCX_MAX_TOTAL_BYTES: number;
 declare const DOCX_MAX_ENTRIES = 4096;
+declare const DOCX_MAX_INPUT_BYTES: number;
 declare const DocxArchiveError_base: import("better-result").TaggedErrorClass<"DocxArchiveError", {
   message: string;
-  reason: "load-failed" | "too-many-entries" | "entry-too-large" | "total-too-large";
+  reason: "load-failed" | "input-too-large" | "too-many-entries" | "entry-too-large" | "total-too-large" | "invalid-options";
   cause?: unknown;
 }>;
 /** Error raised when a DOCX archive cannot be loaded within configured limits. */
 declare class DocxArchiveError extends DocxArchiveError_base {}
 type DocxArchiveOptions = {
+  maxInputBytes?: number;
   maxEntryBytes?: number;
   maxTotalBytes?: number;
   maxEntries?: number;
 };
+type DocxArchiveEntry = {
+  readonly path: string;
+  readonly directory: boolean;
+  readonly declaredUncompressedBytes: number | null;
+};
+type DocxArchiveReadOptions = {
+  maxBytes?: number;
+};
 type DocxArchive = {
   entries: readonly string[];
+  entryMetadata: readonly DocxArchiveEntry[];
   readEntryString: (path: string) => Promise<string | null>;
-  readEntryUint8: (path: string) => Promise<Uint8Array | null>;
+  readEntryUint8: (path: string, options?: DocxArchiveReadOptions) => Promise<Uint8Array | null>;
 };
 declare const loadDocxArchive: (bytes: ArrayBuffer | Uint8Array, options?: DocxArchiveOptions) => Promise<DocxArchive>;
 //#endregion
-export { DOCX_MAX_ENTRIES, DOCX_MAX_ENTRY_BYTES, DOCX_MAX_TOTAL_BYTES, DocxArchive, DocxArchiveError, DocxArchiveOptions, loadDocxArchive };
+export { DOCX_MAX_ENTRIES, DOCX_MAX_ENTRY_BYTES, DOCX_MAX_INPUT_BYTES, DOCX_MAX_TOTAL_BYTES, DocxArchive, DocxArchiveEntry, DocxArchiveError, DocxArchiveOptions, DocxArchiveReadOptions, loadDocxArchive };

package/dist/docx/server/boundedArchive.js

@@ -4,6 +4,7 @@ import JSZip from "jszip";
 const DOCX_MAX_ENTRY_BYTES = 128 * 1024 * 1024;
 const DOCX_MAX_TOTAL_BYTES = 256 * 1024 * 1024;
 const DOCX_MAX_ENTRIES = 4096;
+const DOCX_MAX_INPUT_BYTES = 50 * 1024 * 1024;
 /** Error raised when a DOCX archive cannot be loaded within configured limits. */
 var DocxArchiveError = class extends TaggedError("DocxArchiveError")() {};
 const collectStream = async ({ stream, maxEntryBytes, remainingBytes, maxTotalBytes, path }) => await new Promise((resolve, reject) => {
@@ -33,10 +34,44 @@ const collectStream = async ({ stream, maxEntryBytes, remainingBytes, maxTotalBy
 	stream.on("end", () => resolve(Buffer.concat(chunks)));
 	stream.on("error", reject);
 });
+const getDeclaredUncompressedBytes = (entry) => {
+	const data = "_data" in entry ? entry._data : void 0;
+	const declaredBytes = typeof data === "object" && data !== null && "uncompressedSize" in data ? data.uncompressedSize : void 0;
+	return typeof declaredBytes === "number" && Number.isFinite(declaredBytes) ? declaredBytes : null;
+};
+const resolveByteLimit = ({ value, fallback, name }) => {
+	const limit = value ?? fallback;
+	if (!Number.isSafeInteger(limit) || limit < 0) throw new DocxArchiveError({
+		message: `${name} must be a non-negative safe integer`,
+		reason: "invalid-options"
+	});
+	return limit;
+};
 const loadDocxArchive = async (bytes, options = {}) => {
-	const maxEntryBytes = options.maxEntryBytes ?? 134217728;
-	const maxTotalBytes = options.maxTotalBytes ?? 268435456;
-	const maxEntries = options.maxEntries ?? 4096;
+	const maxInputBytes = resolveByteLimit({
+		value: options.maxInputBytes,
+		fallback: DOCX_MAX_INPUT_BYTES,
+		name: "DOCX input byte limit"
+	});
+	const maxEntryBytes = resolveByteLimit({
+		value: options.maxEntryBytes,
+		fallback: DOCX_MAX_ENTRY_BYTES,
+		name: "DOCX entry byte limit"
+	});
+	const maxTotalBytes = resolveByteLimit({
+		value: options.maxTotalBytes,
+		fallback: DOCX_MAX_TOTAL_BYTES,
+		name: "DOCX cumulative byte limit"
+	});
+	const maxEntries = resolveByteLimit({
+		value: options.maxEntries,
+		fallback: DOCX_MAX_ENTRIES,
+		name: "DOCX entry limit"
+	});
+	if (bytes.byteLength > maxInputBytes) throw new DocxArchiveError({
+		message: `DOCX input contains ${bytes.byteLength} bytes (max ${maxInputBytes})`,
+		reason: "input-too-large"
+	});
 	let zip;
 	try {
 		zip = await JSZip.loadAsync(bytes);
@@ -54,9 +89,9 @@ const loadDocxArchive = async (bytes, options = {}) => {
 	});
 	let declaredTotalBytes = 0;
 	for (const entry of archiveEntries) {
-		const data = "_data" in entry ? entry._data : void 0;
-		const declaredBytes = typeof data === "object" && data !== null && "uncompressedSize" in data ? data.uncompressedSize : void 0;
-		if (typeof declaredBytes !== "number" || !Number.isFinite(declaredBytes)) {
+		if (entry.dir) continue;
+		const declaredBytes = getDeclaredUncompressedBytes(entry);
+		if (declaredBytes === null) {
 			declaredTotalBytes = NaN;
 			break;
 		}
@@ -72,13 +107,18 @@ const loadDocxArchive = async (bytes, options = {}) => {
 	});
 	let totalBytesRead = 0;
 	let readChain = Promise.resolve();
-	const readEntry = async (path) => {
+	const readEntry = async (path, readOptions = {}) => {
+		const requestedMaxBytes = resolveByteLimit({
+			value: readOptions.maxBytes,
+			fallback: maxEntryBytes,
+			name: "DOCX entry read byte limit"
+		});
 		const work = async () => {
 			const entry = zip.file(path);
 			if (!entry) return null;
 			const buffer = await collectStream({
 				stream: entry.nodeStream("nodebuffer"),
-				maxEntryBytes,
+				maxEntryBytes: Math.min(requestedMaxBytes, maxEntryBytes),
 				remainingBytes: maxTotalBytes - totalBytesRead,
 				maxTotalBytes,
 				path
@@ -92,15 +132,20 @@ const loadDocxArchive = async (bytes, options = {}) => {
 	};
 	return {
 		entries: Object.freeze(archiveEntries.map(({ name }) => name)),
+		entryMetadata: Object.freeze(archiveEntries.map((entry) => ({
+			path: entry.name,
+			directory: entry.dir,
+			declaredUncompressedBytes: getDeclaredUncompressedBytes(entry)
+		}))),
 		async readEntryString(path) {
 			const buffer = await readEntry(path);
 			return buffer === null ? null : buffer.toString("utf-8");
 		},
-		async readEntryUint8(path) {
-			const buffer = await readEntry(path);
+		async readEntryUint8(path, readOptions) {
+			const buffer = await readEntry(path, readOptions);
 			return buffer === null ? null : new Uint8Array(buffer);
 		}
 	};
 };
 //#endregion
-export { DOCX_MAX_ENTRIES, DOCX_MAX_ENTRY_BYTES, DOCX_MAX_TOTAL_BYTES, DocxArchiveError, loadDocxArchive };
+export { DOCX_MAX_ENTRIES, DOCX_MAX_ENTRY_BYTES, DOCX_MAX_INPUT_BYTES, DOCX_MAX_TOTAL_BYTES, DocxArchiveError, loadDocxArchive };

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

@@ -0,0 +1,85 @@
+import { DocxArchiveOptions } from "./boundedArchive.js";
+
+//#region src/docx/server/evaluateDocxXmlPatchProposal.d.ts
+declare const FOLIO_DOCX_XML_PATCH_PROPOSAL_VERSION: 1;
+declare const FOLIO_DOCX_XML_PATCH_PROPOSAL_PROFILE: "folio-xml-patch-proposal-v1";
+declare const FOLIO_DOCX_XML_PATCH_PROPOSAL_DEFAULTS: Readonly<{
+  readonly maxReplacements: 16;
+  readonly maxPartBytes: number;
+  readonly maxTotalBytes: number;
+}>;
+declare const FOLIO_DOCX_XML_PATCH_PROPOSAL_ISSUE_CODES: readonly ["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"];
+type FolioDocxXmlPatchProposalIssueCode = (typeof FOLIO_DOCX_XML_PATCH_PROPOSAL_ISSUE_CODES)[number];
+type FolioDocxXmlReplacement = {
+  readonly path: string;
+  readonly baseSha256: string;
+  readonly replacementXml: string;
+};
+type FolioDocxXmlPatchProposal = {
+  readonly version: typeof FOLIO_DOCX_XML_PATCH_PROPOSAL_VERSION;
+  readonly replacements: readonly [FolioDocxXmlReplacement, ...FolioDocxXmlReplacement[]];
+};
+type FolioDocxXmlPatchProposalLimits = {
+  readonly maxReplacements?: number;
+  readonly maxPartBytes?: number;
+  readonly maxTotalBytes?: number;
+};
+type EvaluateDocxXmlPatchProposalArgs = {
+  readonly bytes: ArrayBuffer | Uint8Array;
+  readonly proposal: unknown; /** Exact package paths authorized by the server-side caller. */
+  readonly allowedParts: readonly string[];
+  readonly archive?: DocxArchiveOptions;
+  readonly limits?: FolioDocxXmlPatchProposalLimits;
+};
+type FolioDocxXmlPatchProposalIssue = {
+  readonly code: FolioDocxXmlPatchProposalIssueCode;
+  readonly message: string;
+  readonly proposalPath?: string;
+  readonly part?: string;
+};
+type FolioDocxPreparedXmlReplacement = {
+  readonly path: string;
+  readonly baseSha256: string;
+  readonly currentSha256: string;
+  readonly replacementSha256: string;
+  readonly replacementByteLength: number;
+  readonly encoding: "utf-8";
+};
+type FolioDocxXmlPatchProposalEvaluation = {
+  readonly version: typeof FOLIO_DOCX_XML_PATCH_PROPOSAL_VERSION;
+  readonly profile: typeof FOLIO_DOCX_XML_PATCH_PROPOSAL_PROFILE;
+  readonly status: "accepted";
+  readonly producesOutput: false;
+  readonly issues: readonly [];
+  readonly replacements: readonly [FolioDocxPreparedXmlReplacement, ...FolioDocxPreparedXmlReplacement[]];
+  readonly limits: Required<FolioDocxXmlPatchProposalLimits>;
+} | {
+  readonly version: typeof FOLIO_DOCX_XML_PATCH_PROPOSAL_VERSION;
+  readonly profile: typeof FOLIO_DOCX_XML_PATCH_PROPOSAL_PROFILE;
+  readonly status: "rejected";
+  readonly producesOutput: false;
+  readonly issues: readonly [FolioDocxXmlPatchProposalIssue, ...FolioDocxXmlPatchProposalIssue[]];
+  readonly replacements: readonly [];
+  readonly limits: Required<FolioDocxXmlPatchProposalLimits>;
+};
+declare const InvalidFolioDocxXmlPatchProposalError_base: import("better-result").TaggedErrorClass<"InvalidFolioDocxXmlPatchProposalError", {
+  message: string;
+  path: string;
+  reason: string;
+}>;
+declare class InvalidFolioDocxXmlPatchProposalError extends InvalidFolioDocxXmlPatchProposalError_base {}
+declare const InvalidFolioDocxXmlPatchProposalOptionsError_base: import("better-result").TaggedErrorClass<"InvalidFolioDocxXmlPatchProposalOptionsError", {
+  message: string;
+  path: string;
+}>;
+declare class InvalidFolioDocxXmlPatchProposalOptionsError extends InvalidFolioDocxXmlPatchProposalOptionsError_base {}
+declare const parseFolioDocxXmlPatchProposal: (value: unknown) => FolioDocxXmlPatchProposal;
+declare const evaluateDocxXmlPatchProposal: ({
+  bytes,
+  proposal: rawProposal,
+  allowedParts,
+  archive,
+  limits: rawLimits
+}: EvaluateDocxXmlPatchProposalArgs) => Promise<FolioDocxXmlPatchProposalEvaluation>;
+//#endregion
+export { EvaluateDocxXmlPatchProposalArgs, 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, FolioDocxPreparedXmlReplacement, FolioDocxXmlPatchProposal, FolioDocxXmlPatchProposalEvaluation, FolioDocxXmlPatchProposalIssue, FolioDocxXmlPatchProposalIssueCode, FolioDocxXmlPatchProposalLimits, FolioDocxXmlReplacement, InvalidFolioDocxXmlPatchProposalError, InvalidFolioDocxXmlPatchProposalOptionsError, evaluateDocxXmlPatchProposal, parseFolioDocxXmlPatchProposal };