@stll/docx-utils 0.1.1 → 0.1.2

package/dist/index.d.ts

@@ -6,7 +6,7 @@ import JSZip from "jszip";
  * Canonical source for namespace constants shared across
  * the editor (folio) and the backend (api).
  */
-declare const OOXML_NS: {
+export declare const OOXML_NS: {
   readonly w: "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
   readonly a: "http://schemas.openxmlformats.org/drawingml/2006/main";
   readonly r: "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
@@ -29,7 +29,7 @@ type OoxmlPrefix = keyof typeof OOXML_NS;
 //#endregion
 //#region src/zip.d.ts
 /** Standard DOCX compression options */
-declare const DOCX_COMPRESSION: {
+export declare const DOCX_COMPRESSION: {
   type: "arraybuffer";
   compression: "DEFLATE";
   compressionOptions: {
@@ -37,20 +37,59 @@ declare const DOCX_COMPRESSION: {
   };
 };
 /** Load a DOCX file (ArrayBuffer) into a JSZip instance */
-declare const loadDocx: (buffer: ArrayBuffer) => Promise<JSZip>;
+export declare const loadDocx: (buffer: ArrayBuffer) => Promise<JSZip>;
 /** Extract a text file from a ZIP */
-declare const extractText: (zip: JSZip, path: string) => Promise<string | null>;
+export declare const extractText: (zip: JSZip, path: string) => Promise<string | null>;
 /** Extract a binary file from a ZIP */
-declare const extractBinary: (zip: JSZip, path: string) => Promise<ArrayBuffer | null>;
+export declare const extractBinary: (zip: JSZip, path: string) => Promise<ArrayBuffer | null>;
 /** Repack a ZIP to ArrayBuffer with standard DOCX compression */
-declare const repackZip: (zip: JSZip) => Promise<ArrayBuffer>;
+export declare const repackZip: (zip: JSZip) => Promise<ArrayBuffer>;
 //#endregion
 //#region src/relationships.d.ts
 /** Find the next available rId in a relationships XML string */
-declare const findNextRId: (relsXml: string) => string;
+export declare const findNextRId: (relsXml: string) => string;
 /** Ensure a content type entry exists in [Content_Types].xml */
-declare const ensureContentType: (contentTypesXml: string, partName: string, contentType: string) => string;
+export declare const ensureContentType: (contentTypesXml: string, partName: string, contentType: string) => string;
 /** Ensure a relationship entry exists */
-declare const ensureRelationship: (relsXml: string, rId: string, type: string, target: string) => string;
+export declare const ensureRelationship: (relsXml: string, rId: string, type: string, target: string) => string;
 //#endregion
-export { DOCX_COMPRESSION, OOXML_NS, type OoxmlPrefix, ensureContentType, ensureRelationship, extractBinary, extractText, findNextRId, loadDocx, repackZip };
+//#region src/attached-template.d.ts
+export declare const ATTACHED_TEMPLATE_SECURITY_RULE: "ooxml_attached_template";
+export declare const ATTACHED_TEMPLATE_TARGET_KIND: {
+  readonly local: "local";
+  readonly network: "network";
+  readonly unknown: "unknown";
+};
+type AttachedTemplateTargetKind = (typeof ATTACHED_TEMPLATE_TARGET_KIND)[keyof typeof ATTACHED_TEMPLATE_TARGET_KIND];
+type AttachedTemplateRelationshipFinding = {
+  rule: typeof ATTACHED_TEMPLATE_SECURITY_RULE;
+  targetKind: AttachedTemplateTargetKind;
+};
+type SanitizedAttachedTemplateRelationships = {
+  findings: readonly AttachedTemplateRelationshipFinding[];
+  removedRelationshipIds: readonly string[];
+  sourcePartPath: string | null;
+  xml: string;
+};
+type SanitizedAttachedTemplateSource = {
+  removed: number;
+  xml: string;
+};
+/**
+ * Classify where Word would resolve an attached template without retaining or
+ * returning the target itself. Template targets can contain usernames, host
+ * names, and internal paths, none of which belong in findings or telemetry.
+ */
+export declare const classifyAttachedTemplateTarget: (target: string | null) => AttachedTemplateTargetKind;
+/** Resolve `word/_rels/settings.xml.rels` to its owning `word/settings.xml`. */
+export declare const relationshipSourcePartPath: (relationshipsPartPath: string) => string | null;
+export declare const isOpcRelationshipPartPath: (path: string) => boolean;
+/**
+ * Find and remove every attached-template relationship in one `.rels` part.
+ * Unchanged XML is returned byte-for-byte when no relationship is present.
+ */
+export declare const sanitizeAttachedTemplateRelationships: (xml: string, relationshipsPartPath: string) => SanitizedAttachedTemplateRelationships;
+/** Remove WordprocessingML references to the relationships removed above. */
+export declare const sanitizeAttachedTemplateSource: (xml: string, removedRelationshipIds: readonly string[]) => SanitizedAttachedTemplateSource;
+//#endregion
+export type { AttachedTemplateRelationshipFinding, AttachedTemplateTargetKind, OoxmlPrefix };

package/dist/index.js

@@ -1,4 +1,5 @@
 import JSZip from "jszip";
+import * as slimdom from "slimdom";
 //#region src/namespaces.ts
 /**
 * Common OOXML namespace URIs.
@@ -82,4 +83,127 @@ const ensureRelationship = (relsXml, rId, type, target) => {
 	return relsXml.replace("</Relationships>", () => `${rel}\n</Relationships>`);
 };
 //#endregion
-export { DOCX_COMPRESSION, OOXML_NS, ensureContentType, ensureRelationship, extractBinary, extractText, findNextRId, loadDocx, repackZip };
+//#region src/attached-template.ts
+const ATTACHED_TEMPLATE_SECURITY_RULE = "ooxml_attached_template";
+const ATTACHED_TEMPLATE_TARGET_KIND = {
+	local: "local",
+	network: "network",
+	unknown: "unknown"
+};
+const PACKAGE_RELATIONSHIPS_NAMESPACE = "http://schemas.openxmlformats.org/package/2006/relationships";
+const ATTACHED_TEMPLATE_RELATIONSHIP_TYPES = ["http://schemas.openxmlformats.org/officeDocument/2006/relationships/attachedTemplate", "http://purl.oclc.org/ooxml/officeDocument/relationships/attachedTemplate"];
+const WORDPROCESSINGML_NAMESPACES = ["http://schemas.openxmlformats.org/wordprocessingml/2006/main", "http://purl.oclc.org/ooxml/wordprocessingml/main"];
+const OFFICE_RELATIONSHIPS_NAMESPACES = ["http://schemas.openxmlformats.org/officeDocument/2006/relationships", "http://purl.oclc.org/ooxml/officeDocument/relationships"];
+const RELATIONSHIPS_SUFFIX = ".rels";
+const RELATIONSHIPS_DIRECTORY = "_rels";
+const ROOT_RELATIONSHIPS_PATH = "_rels/.rels";
+const WINDOWS_DRIVE_PATH_RE = /^[a-z]:[\\/]/iu;
+const UNC_PATH_RE = /^(?:\\\\|\/\/)[^\\/]/u;
+const isAttachedTemplateRelationship = (element) => {
+	if (element.localName !== "Relationship" || element.namespaceURI !== PACKAGE_RELATIONSHIPS_NAMESPACE) return false;
+	const type = element.getAttribute("Type")?.trim();
+	return ATTACHED_TEMPLATE_RELATIONSHIP_TYPES.some((attachedTemplateType) => attachedTemplateType === type);
+};
+const descendantElements = (root) => {
+	const elements = [];
+	const pending = [...root.childNodes];
+	while (pending.length > 0) {
+		const node = pending.pop();
+		if (node === void 0) break;
+		if (node instanceof slimdom.Element) elements.push(node);
+		for (const child of node.childNodes) pending.push(child);
+	}
+	return elements;
+};
+/**
+* Classify where Word would resolve an attached template without retaining or
+* returning the target itself. Template targets can contain usernames, host
+* names, and internal paths, none of which belong in findings or telemetry.
+*/
+const classifyAttachedTemplateTarget = (target) => {
+	const normalized = target?.trim();
+	if (!normalized || normalized.includes("\0")) return ATTACHED_TEMPLATE_TARGET_KIND.unknown;
+	if (UNC_PATH_RE.test(normalized)) return ATTACHED_TEMPLATE_TARGET_KIND.network;
+	if (WINDOWS_DRIVE_PATH_RE.test(normalized)) return ATTACHED_TEMPLATE_TARGET_KIND.local;
+	if (!URL.canParse(normalized)) return ATTACHED_TEMPLATE_TARGET_KIND.local;
+	const url = new URL(normalized);
+	if (url.protocol !== "file:") return ATTACHED_TEMPLATE_TARGET_KIND.network;
+	if (url.pathname.startsWith("//")) return ATTACHED_TEMPLATE_TARGET_KIND.network;
+	return url.hostname === "" || url.hostname.toLowerCase() === "localhost" ? ATTACHED_TEMPLATE_TARGET_KIND.local : ATTACHED_TEMPLATE_TARGET_KIND.network;
+};
+/** Resolve `word/_rels/settings.xml.rels` to its owning `word/settings.xml`. */
+const relationshipSourcePartPath = (relationshipsPartPath) => {
+	if (relationshipsPartPath.includes("\\") || relationshipsPartPath.startsWith("/")) return null;
+	if (relationshipsPartPath === ROOT_RELATIONSHIPS_PATH) return null;
+	const segments = relationshipsPartPath.split("/");
+	if (segments.length < 2 || segments.some((segment) => segment === "" || segment === "." || segment === "..")) return null;
+	const relationshipDirectory = segments.at(-2);
+	const relationshipFileName = segments.at(-1);
+	if (relationshipDirectory !== RELATIONSHIPS_DIRECTORY || relationshipFileName === void 0 || !relationshipFileName.endsWith(RELATIONSHIPS_SUFFIX)) return null;
+	const sourceFileName = relationshipFileName.slice(0, -5);
+	if (sourceFileName === "") return null;
+	return [...segments.slice(0, -2), sourceFileName].join("/");
+};
+const isOpcRelationshipPartPath = (path) => path === ROOT_RELATIONSHIPS_PATH || relationshipSourcePartPath(path) !== null;
+/**
+* Find and remove every attached-template relationship in one `.rels` part.
+* Unchanged XML is returned byte-for-byte when no relationship is present.
+*/
+const sanitizeAttachedTemplateRelationships = (xml, relationshipsPartPath) => {
+	const document = slimdom.parseXmlDocument(xml);
+	const relationships = descendantElements(document).filter(isAttachedTemplateRelationship);
+	if (relationships.length === 0) return {
+		findings: [],
+		removedRelationshipIds: [],
+		sourcePartPath: relationshipSourcePartPath(relationshipsPartPath),
+		xml
+	};
+	const findings = relationships.map((relationship) => ({
+		rule: ATTACHED_TEMPLATE_SECURITY_RULE,
+		targetKind: classifyAttachedTemplateTarget(relationship.getAttribute("Target"))
+	}));
+	const removedRelationshipIds = relationships.flatMap((relationship) => {
+		const id = relationship.getAttribute("Id")?.trim();
+		return id ? [id] : [];
+	});
+	for (const relationship of relationships) relationship.remove();
+	return {
+		findings,
+		removedRelationshipIds,
+		sourcePartPath: relationshipSourcePartPath(relationshipsPartPath),
+		xml: slimdom.serializeToWellFormedString(document)
+	};
+};
+const relationshipReferenceId = (element) => {
+	for (const namespace of OFFICE_RELATIONSHIPS_NAMESPACES) {
+		const id = element.getAttributeNS(namespace, "id");
+		if (id !== null) return id;
+	}
+	return null;
+};
+/** Remove WordprocessingML references to the relationships removed above. */
+const sanitizeAttachedTemplateSource = (xml, removedRelationshipIds) => {
+	if (removedRelationshipIds.length === 0) return {
+		removed: 0,
+		xml
+	};
+	const document = slimdom.parseXmlDocument(xml);
+	const root = document.documentElement;
+	if (root?.localName !== "settings" || !WORDPROCESSINGML_NAMESPACES.some((namespace) => namespace === root.namespaceURI)) return {
+		removed: 0,
+		xml
+	};
+	const relationshipIds = new Set(removedRelationshipIds);
+	const references = descendantElements(document).filter((element) => element.localName === "attachedTemplate" && element.namespaceURI === root.namespaceURI && relationshipIds.has(relationshipReferenceId(element) ?? ""));
+	if (references.length === 0) return {
+		removed: 0,
+		xml
+	};
+	for (const reference of references) reference.remove();
+	return {
+		removed: references.length,
+		xml: slimdom.serializeToWellFormedString(document)
+	};
+};
+//#endregion
+export { ATTACHED_TEMPLATE_SECURITY_RULE, ATTACHED_TEMPLATE_TARGET_KIND, DOCX_COMPRESSION, OOXML_NS, classifyAttachedTemplateTarget, ensureContentType, ensureRelationship, extractBinary, extractText, findNextRId, isOpcRelationshipPartPath, loadDocx, relationshipSourcePartPath, repackZip, sanitizeAttachedTemplateRelationships, sanitizeAttachedTemplateSource };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/docx-utils",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Low-level helpers for reading and writing DOCX/OOXML zip packages: text and binary extraction, relationship and content-type management, and namespace constants.",
   "keywords": [
     "docx",
@@ -43,16 +43,17 @@
     "typecheck": "bun ../../packages/scripts/src/tsc-native.ts --noEmit",
     "lint": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --deny-warnings --type-aware packages/docx-utils",
     "lint:fix": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --type-aware --fix packages/docx-utils",
-    "format": "oxfmt .",
+    "format": "bun ../../scripts/run-oxfmt.ts .",
     "prepack": "bun run build"
   },
   "dependencies": {
-    "jszip": "3.10.1"
+    "jszip": "3.10.1",
+    "slimdom": "^4.3.5"
   },
   "devDependencies": {
     "@stll/typescript-config": "0.0.0",
-    "@types/bun": "1.3.14",
-    "tsdown": "0.22.14"
+    "bun-types": "1.4.2",
+    "tsdown": "0.23.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts"