@doccloak/core 0.11.0 → 0.12.0

package/dist/dom/docx.d.ts

@@ -9,25 +9,43 @@
 import JSZip from 'jszip';
 import { normalizeReplacements } from '../docx.js';
 import type { ValueReplacement } from '../docx.js';
+import type { UnredactablePart } from './errors.js';
 export { normalizeReplacements };
 export type { ValueReplacement };
 /**
- * Represents a text node in the docx XML with its position in the flat text.
+ * Represents one unit of document text with its position in the flat text.
  * Also reused by the xlsx module (T110): the same flat-text replacement
  * machinery applies to any XML part whose text lives in leaf elements.
+ *
+ * Two variants (T174):
+ * - element text: the unit is `element.textContent` (a w:t, w:instrText,
+ *   m:t, ...); `attr` is unset.
+ * - attribute text: the unit is a slice of `attr.value` on `element`,
+ *   starting at `attrOffset` (0 unless the attribute holds several units, as
+ *   a field instruction with several arguments does). Values that live only
+ *   in attributes (field arguments, alt text, bookmark names, content control
+ *   aliases, numbering level text) reach the detector this way instead of
+ *   depending on a known-value scrub.
  */
 export interface TextNodeMapping {
-    /** The <w:t> element */
+    /** The element that carries the text (or the attribute) */
     element: Element;
     /** Start index in the flat text */
     flatStart: number;
     /** End index in the flat text */
     flatEnd: number;
+    /** When set, the unit is a slice of this attribute's value, not element text */
+    attr?: Attr;
+    /** Offset of the unit inside attr.value (attribute variant only) */
+    attrOffset?: number;
 }
 /**
- * Tracks the boundary between paragraphs in the flat text (newline positions).
+ * Position of an unmapped newline in the flat text: a paragraph boundary, a
+ * text-box boundary, a w:br / w:cr line break or the separator between two
+ * content parts. No TextNodeMapping covers these indices, and a replacement
+ * never spans one (T172): an entity that contains a newline is split at it.
  */
-interface ParagraphBreak {
+export interface ParagraphBreak {
     flatIndex: number;
 }
 /**
@@ -48,6 +66,19 @@ export interface DocxExtraction {
     documentXmlPath: string;
     /** All content XML paths (document, headers, footers) and their extractions */
     contentParts: ContentPartExtraction[];
+    /**
+     * True when no text-bearing content was found (no paragraphs, or only
+     * empty ones). Hosts show "nothing to redact" instead of exporting (T172).
+     */
+    empty: boolean;
+    /**
+     * Parts the writer cannot redact (embedded objects, macros, HTML chunks,
+     * printer settings, unknown parts), from the package policy (T177). The
+     * writer refuses to export them unless allowUnredactable is passed.
+     */
+    unredactable: UnredactablePart[];
+    /** Read-time notes: secondary parts skipped because they did not parse. */
+    warnings: string[];
 }
 interface ContentPartExtraction {
     path: string;
@@ -57,10 +88,38 @@ interface ContentPartExtraction {
     flatTextStart: number;
     flatTextEnd: number;
 }
+/** True for a WordprocessingML element (transitional or strict namespace). */
+export declare function isWordEl(el: Element, localName: string): boolean;
+/** True for an Office Math (OMML) element (transitional or strict namespace). */
+export declare function isMathEl(el: Element, localName: string): boolean;
+/**
+ * The redactable arguments of a field instruction (w:fldSimple@w:instr or
+ * the joined w:instrText of a complex field): the content of every quoted
+ * string and every bare token that is neither the field keyword (the first
+ * token) nor a switch (a token starting with a backslash). Offsets refer to
+ * the instruction string. ` HYPERLINK "mailto:a@b" \o "Mail" ` yields
+ * "mailto:a@b" and "Mail"; ` REF Bookmark1 \h ` yields "Bookmark1". The
+ * keyword is never an argument, so a replacement can never turn a HYPERLINK
+ * into something Word cannot evaluate (T174).
+ */
+export declare function fieldInstructionArguments(instr: string): Array<{
+    offset: number;
+    text: string;
+}>;
+/** Options for readDocx (T177). */
+export interface DocxReadOptions {
+    /**
+     * Limit on the sum of the declared uncompressed sizes of all zip entries
+     * (zip-bomb guard, L4). Above it the reader throws
+     * UnsupportedDocumentError('too-large') before parsing any part.
+     * Defaults to MAX_UNPACKED_BYTES (200 MB).
+     */
+    maxUnpackedBytes?: number;
+}
 /**
  * Read a .docx file and extract its text content with position mapping.
  */
-export declare function readDocx(file: File): Promise<DocxExtraction>;
+export declare function readDocx(file: File, options?: DocxReadOptions): Promise<DocxExtraction>;
 /**
  * Options for writeAnonymizedDocx (T110). All default to off, preserving the
  * historical output byte-for-byte for existing callers.
@@ -74,31 +133,100 @@ export interface DocxWriteOptions {
      * identifying, so the file-redaction flow turns this on.
      */
     acceptTrackedChanges?: boolean;
+    /**
+     * Export even though extraction.unredactable is non-empty (T177). The
+     * listed parts (embedded workbooks, OLE objects, macros, HTML chunks,
+     * printer settings, unknown parts) are copied verbatim and named in
+     * result.warnings. Default false: the writer throws
+     * UnsupportedDocumentError('unredactable-parts') with the part names in
+     * `details` before touching the extraction, so a host can ask the user
+     * and call again with the same extraction. Hosts that never ask keep
+     * fail-closed behaviour.
+     */
+    allowUnredactable?: boolean;
 }
+/**
+ * Refuse to export while unredactable parts are present and the host did
+ * not opt in. Shared by the docx and xlsx writers; runs before any mutation.
+ */
+export declare function assertUnredactableAllowed(unredactable: ReadonlyArray<UnredactablePart>, allowUnredactable: boolean | undefined): void;
+/** Warning line per unredactable part copied verbatim (allowUnredactable). */
+export declare function unredactableWarnings(unredactable: ReadonlyArray<UnredactablePart>): string[];
 /**
  * Apply a list of flat-text replacements to mapped text nodes, handling
  * replacements that span multiple elements. Ranges are normalized (sorted,
  * overlaps clamped) and applied end-to-start so earlier positions stay valid.
  * Shared by the docx and xlsx writers (T110).
+ *
+ * `breaks` (T172) lists the flat indices of unmapped newlines (paragraph and
+ * text-box boundaries, line breaks, part separators). A replacement never
+ * crosses one: a range that contains a break is split at it, the first piece
+ * receives the replacement and the following pieces are emptied, so text is
+ * never moved from one paragraph (or text box) into another. Restoring the
+ * placeholder then yields the original value once, not once per piece.
  */
 export declare function applyTextReplacements(textNodes: TextNodeMapping[], replacements: Array<{
     start: number;
     end: number;
     replacement: string;
-}>): void;
+}>, breaks?: ReadonlyArray<number>): void;
+/** Result of writeAnonymizedDocxWithReport (T172). */
+export interface DocxWriteResult {
+    /** The redacted .docx */
+    blob: Blob;
+    /**
+     * Human-readable notes about parts the layer-zero scrub could not parse and
+     * therefore left untouched. Empty on a clean run.
+     */
+    warnings: string[];
+}
 /**
  * Apply text replacements to the docx XML, preserving all formatting.
  * Takes the original extraction and a list of replacements (sorted by position),
  * and modifies the XML in-place. Also scrubs document metadata and relationship
  * targets that can leak identities (authors, revision names, hyperlink emails).
  *
- * Returns a new .docx file as a Blob.
+ * Returns a new .docx file as a Blob. writeAnonymizedDocxWithReport returns
+ * the same Blob together with the layer-zero warnings.
  */
 export declare function writeAnonymizedDocx(extraction: DocxExtraction, replacements: Array<{
     start: number;
     end: number;
     replacement: string;
 }>, valueReplacements?: ValueReplacement[], options?: DocxWriteOptions): Promise<Blob>;
+/**
+ * Same as writeAnonymizedDocx, with the write report. Pipeline (T172, T174):
+ * 1. offset replacements in the mapped text and attribute units (never
+ *    across a break);
+ * 2. bookmark rename: a bookmark whose name changed gets a valid identifier,
+ *    and every reference to it (w:hyperlink@w:anchor, REF / PAGEREF /
+ *    NOTEREF / HYPERLINK \l instructions) is updated across all parts;
+ * 3. per content part: attribute scrub (authors, field arguments, alt
+ *    text), reference update, always-scrub group (tooltips, content control
+ *    tags without a data binding), optional tracked-change acceptance,
+ *    serialize;
+ * 4. metadata scrub (docProps, people, settings incl. docVars, rels incl.
+ *    the mailto rule, thumbnail);
+ * 5. layer zero: every known value scrubbed from every other XML/rels/vml
+ *    part in the package (charts, diagrams, customXml, docVars, glossary,
+ *    docProps), so a value the extractors never saw cannot leave in a part
+ *    they do not read;
+ * 6. container normalisation (T179): every zip entry dated 1980-01-01 with
+ *    an empty comment, empty archive comment; then zip generation.
+ */
+export declare function writeAnonymizedDocxWithReport(extraction: DocxExtraction, replacements: Array<{
+    start: number;
+    end: number;
+    replacement: string;
+}>, valueReplacements?: ValueReplacement[], options?: DocxWriteOptions): Promise<DocxWriteResult>;
+/**
+ * Turn a replacement into a valid Word bookmark identifier: ASCII letters,
+ * digits and underscores, starting with a letter, at most 40 characters,
+ * unique among the names in `used` (which it extends). '[PERSON_1]' becomes
+ * 'PERSON_1'; a replacement that starts with a digit or underscore gets the
+ * 'bm_' prefix.
+ */
+export declare function bookmarkIdentifier(replacement: string, used?: Set<string>): string;
 /**
  * Get the file extension from a filename.
  */