@stll/folio-core 0.11.0 → 0.12.0

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