@doccloak/core 0.11.0 → 0.12.1

package/dist/dom/drawingml.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @doccloak/core/dom - DrawingML, chart, SmartArt and custom XML text units
+ * (T175, security remediation 2026-09, finding H3).
+ *
+ * PII that appears for the first time in a chart (title, category cache,
+ * series name), a SmartArt node, a chart user shape or a custom XML data
+ * store was previously invisible to the detector: only the layer-zero value
+ * scrub (T172) could remove it, and only when the same value had been
+ * detected elsewhere. These helpers turn those parts into text units the
+ * docx and xlsx readers register as content parts, so the detector sees the
+ * text and the writer applies offset replacements to it.
+ *
+ * A unit is the list of leaf elements whose concatenated text forms one
+ * independent string. Units are separated by newlines in the flat text and
+ * every separator is a paragraph break, so a replacement never crosses two
+ * units (the T172 rule).
+ */
+import type { TextNodeMapping, ParagraphBreak } from './docx.js';
+/** Leaf elements whose concatenated text is one independent string. */
+export type TextUnit = Element[];
+/**
+ * Text units of a DrawingML part, in document order:
+ * - every a:p (DrawingML paragraph) as one unit of its a:t leaves: chart
+ *   titles, axis titles, data labels, text boxes, SmartArt node text
+ *   (dgm:t wraps a:p), chart user shapes;
+ * - every c:v inside c:strCache / c:multiLvlStrCache (category and series
+ *   name caches) or c:tx (literal series names) as its own unit; numeric
+ *   caches (c:numCache) are left alone so a chart's numbers stay numbers;
+ * - every chartEx cx:pt (string dimension point) and cx:v (text data).
+ * Applies to word/charts, word/diagrams, word/drawings, xl/charts and
+ * xl/drawings parts.
+ */
+export declare function drawingUnits(doc: Document): TextUnit[];
+/**
+ * Every non-empty leaf text node of an arbitrary XML part as its own unit
+ * (customXml/item*.xml: cover page properties, bibliography sources,
+ * SharePoint document properties). Element and attribute names are never
+ * units; attribute values are covered by layer zero.
+ */
+export declare function leafTextUnits(doc: Document): TextUnit[];
+/**
+ * Flatten units into the reader's shape: one line per unit, a
+ * TextNodeMapping per non-empty leaf, and a ParagraphBreak at every
+ * separating newline so no replacement can span two units.
+ */
+export declare function flattenUnits(units: TextUnit[]): {
+    plainText: string;
+    textNodes: TextNodeMapping[];
+    paragraphBreaks: ParagraphBreak[];
+};
+/**
+ * Remove every c:externalData element (with its c:autoUpdate child) from a
+ * chart part so Word never tries to open the embedded workbook the chart
+ * was built from. The string and number caches stay, so the chart still
+ * renders, and they are redacted like any other unit. Returns the number of
+ * elements removed. The embedded workbook itself is reported by the package
+ * policy (T177) and removed by T199.
+ */
+export declare function stripChartExternalData(doc: Document): number;

package/dist/dom/drawingml.js

@@ -0,0 +1,176 @@
+/**
+ * @doccloak/core/dom - DrawingML, chart, SmartArt and custom XML text units
+ * (T175, security remediation 2026-09, finding H3).
+ *
+ * PII that appears for the first time in a chart (title, category cache,
+ * series name), a SmartArt node, a chart user shape or a custom XML data
+ * store was previously invisible to the detector: only the layer-zero value
+ * scrub (T172) could remove it, and only when the same value had been
+ * detected elsewhere. These helpers turn those parts into text units the
+ * docx and xlsx readers register as content parts, so the detector sees the
+ * text and the writer applies offset replacements to it.
+ *
+ * A unit is the list of leaf elements whose concatenated text forms one
+ * independent string. Units are separated by newlines in the flat text and
+ * every separator is a paragraph break, so a replacement never crosses two
+ * units (the T172 rule).
+ */
+import { OOXML_NS, isElementIn } from "./opc.js";
+/** chartEx (Office 2016+ chart types: waterfall, treemap, sunburst, funnel). */
+const CHARTEX_NS = new Set([
+    'http://schemas.microsoft.com/office/drawing/2014/chartex',
+]);
+/** Chart containers whose c:v children hold strings, not numbers. */
+const CHART_STRING_CONTAINERS = new Set(['strCache', 'multiLvlStrCache', 'tx']);
+/** True for a c:v that holds a string: inside a string cache or a c:tx literal. */
+function isChartStringValue(el) {
+    if (!isElementIn(el, OOXML_NS.c, 'v'))
+        return false;
+    for (let p = el.parentElement; p; p = p.parentElement) {
+        if (p.namespaceURI === null || !OOXML_NS.c.has(p.namespaceURI))
+            continue;
+        if (CHART_STRING_CONTAINERS.has(p.localName))
+            return true;
+        if (p.localName === 'numCache' || p.localName === 'numLit')
+            return false;
+    }
+    return false;
+}
+/** Every a:t under a DrawingML paragraph, in document order, non-empty. */
+function paragraphLeaves(p) {
+    const leaves = [];
+    const all = p.getElementsByTagName('*');
+    for (let i = 0; i < all.length; i++) {
+        const el = all[i];
+        if (isElementIn(el, OOXML_NS.a, 't') && (el.textContent ?? '').length > 0)
+            leaves.push(el);
+    }
+    return leaves;
+}
+function hasText(el) {
+    return (el.textContent ?? '').trim().length > 0;
+}
+/**
+ * Text units of a DrawingML part, in document order:
+ * - every a:p (DrawingML paragraph) as one unit of its a:t leaves: chart
+ *   titles, axis titles, data labels, text boxes, SmartArt node text
+ *   (dgm:t wraps a:p), chart user shapes;
+ * - every c:v inside c:strCache / c:multiLvlStrCache (category and series
+ *   name caches) or c:tx (literal series names) as its own unit; numeric
+ *   caches (c:numCache) are left alone so a chart's numbers stay numbers;
+ * - every chartEx cx:pt (string dimension point) and cx:v (text data).
+ * Applies to word/charts, word/diagrams, word/drawings, xl/charts and
+ * xl/drawings parts.
+ */
+export function drawingUnits(doc) {
+    const units = [];
+    const walk = (parent) => {
+        for (let child = parent.firstElementChild; child; child = child.nextElementSibling) {
+            if (isElementIn(child, OOXML_NS.a, 'p')) {
+                const leaves = paragraphLeaves(child);
+                if (leaves.length > 0)
+                    units.push(leaves);
+                continue;
+            }
+            if (isChartStringValue(child)) {
+                if (hasText(child))
+                    units.push([child]);
+                continue;
+            }
+            if (isElementIn(child, CHARTEX_NS, 'pt') || isElementIn(child, CHARTEX_NS, 'v')) {
+                if (child.childElementCount === 0 && hasText(child))
+                    units.push([child]);
+                continue;
+            }
+            walk(child);
+        }
+    };
+    if (doc.documentElement)
+        walk(doc.documentElement);
+    return units;
+}
+/**
+ * Leaf text this long with only base64 characters is an encoded payload
+ * (Power Query mashup, serialized add-in state), not user text: it would
+ * flood the editor and the detector without ever matching an entity. The
+ * layer-zero value scrub still visits it.
+ */
+const BLOB_MIN_LENGTH = 256;
+const BLOB_PATTERN = /^[A-Za-z0-9+/=\r\n]+$/;
+function looksLikeBlob(text) {
+    return text.length >= BLOB_MIN_LENGTH && BLOB_PATTERN.test(text);
+}
+/**
+ * Every non-empty leaf text node of an arbitrary XML part as its own unit
+ * (customXml/item*.xml: cover page properties, bibliography sources,
+ * SharePoint document properties). Element and attribute names are never
+ * units; attribute values are covered by layer zero.
+ */
+export function leafTextUnits(doc) {
+    const units = [];
+    const all = doc.getElementsByTagName('*');
+    for (let i = 0; i < all.length; i++) {
+        const el = all[i];
+        if (el.childElementCount !== 0)
+            continue;
+        const text = el.textContent ?? '';
+        if (text.trim().length === 0 || looksLikeBlob(text))
+            continue;
+        units.push([el]);
+    }
+    return units;
+}
+/**
+ * Flatten units into the reader's shape: one line per unit, a
+ * TextNodeMapping per non-empty leaf, and a ParagraphBreak at every
+ * separating newline so no replacement can span two units.
+ */
+export function flattenUnits(units) {
+    const textNodes = [];
+    const paragraphBreaks = [];
+    let plainText = '';
+    for (const unit of units) {
+        const nodes = [];
+        let unitLength = 0;
+        for (const element of unit) {
+            const text = element.textContent ?? '';
+            if (text.length === 0)
+                continue;
+            nodes.push({ element, flatStart: unitLength, flatEnd: unitLength + text.length });
+            unitLength += text.length;
+        }
+        if (unitLength === 0)
+            continue;
+        if (plainText.length > 0) {
+            paragraphBreaks.push({ flatIndex: plainText.length });
+            plainText += '\n';
+        }
+        const base = plainText.length;
+        for (const node of nodes) {
+            node.flatStart += base;
+            node.flatEnd += base;
+            plainText += node.element.textContent ?? '';
+            textNodes.push(node);
+        }
+    }
+    return { plainText, textNodes, paragraphBreaks };
+}
+/**
+ * Remove every c:externalData element (with its c:autoUpdate child) from a
+ * chart part so Word never tries to open the embedded workbook the chart
+ * was built from. The string and number caches stay, so the chart still
+ * renders, and they are redacted like any other unit. Returns the number of
+ * elements removed. The embedded workbook itself is reported by the package
+ * policy (T177) and removed by T199.
+ */
+export function stripChartExternalData(doc) {
+    const doomed = [];
+    const all = doc.getElementsByTagName('*');
+    for (let i = 0; i < all.length; i++) {
+        if (isElementIn(all[i], OOXML_NS.c, 'externalData'))
+            doomed.push(all[i]);
+    }
+    for (const el of doomed)
+        el.parentNode?.removeChild(el);
+    return doomed.length;
+}

package/dist/dom/errors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @doccloak/core/dom - typed refusal errors (T172, security remediation 2026-09).
+ *
+ * Fail-closed principle: a document the reader cannot interpret is refused
+ * with a stable machine-readable `code` instead of being copied through as a
+ * "redacted" file. Hosts map `code` to their own localized messages; `details`
+ * carries the specifics (offending namespaces, part names) for diagnostics.
+ */
+/**
+ * Stable refusal codes. T172 raises 'unrecognized-namespace' and
+ * 'invalid-package'; the remaining codes are reserved for T177 (package
+ * policy, size limit) and the legacy .doc reader so hosts can switch on one
+ * union from day one.
+ */
+export type UnsupportedDocumentCode = 'unrecognized-namespace' | 'invalid-package' | 'unredactable-parts' | 'too-large' | 'fast-saved' | 'encrypted';
+export declare class UnsupportedDocumentError extends Error {
+    readonly code: UnsupportedDocumentCode;
+    /** Free-form specifics: namespaces seen, part names, sizes. */
+    readonly details: string[];
+    constructor(code: UnsupportedDocumentCode, message?: string, details?: string[]);
+}
+/** True when `err` is an UnsupportedDocumentError (also across realms). */
+export declare function isUnsupportedDocumentError(err: unknown): err is UnsupportedDocumentError;
+/**
+ * A package part the writer cannot redact (embedded workbook, macros, HTML
+ * chunk). T172 only declares the shape and always reports an empty list;
+ * T177 fills it from classifyPart and gates the writer on allowUnredactable.
+ */
+export interface UnredactablePart {
+    /** Zip path of the part, e.g. 'word/embeddings/oleObject1.bin' */
+    part: string;
+    kind: 'embedded-object' | 'macros' | 'html-chunk' | 'external-data' | 'printer-settings' | 'unknown';
+    /** Human-readable label for host UIs, e.g. 'embedded Excel sheet' */
+    label: string;
+}

package/dist/dom/errors.js

@@ -0,0 +1,24 @@
+/**
+ * @doccloak/core/dom - typed refusal errors (T172, security remediation 2026-09).
+ *
+ * Fail-closed principle: a document the reader cannot interpret is refused
+ * with a stable machine-readable `code` instead of being copied through as a
+ * "redacted" file. Hosts map `code` to their own localized messages; `details`
+ * carries the specifics (offending namespaces, part names) for diagnostics.
+ */
+export class UnsupportedDocumentError extends Error {
+    constructor(code, message, details = []) {
+        super(message ?? `Unsupported document (${code})`);
+        this.name = 'UnsupportedDocumentError';
+        this.code = code;
+        this.details = details;
+        // Keep instanceof working when the package is compiled to ES5-style
+        // classes by a downstream bundler.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** True when `err` is an UnsupportedDocumentError (also across realms). */
+export function isUnsupportedDocumentError(err) {
+    return err instanceof UnsupportedDocumentError
+        || (typeof err === 'object' && err !== null && err.name === 'UnsupportedDocumentError');
+}

package/dist/dom/index.d.ts

@@ -11,3 +11,6 @@ export * from './docx.js';
 export * from './ocr.js';
 export * from './xlsx.js';
 export * from './office.js';
+export * from './errors.js';
+export * from './drawingml.js';
+export * from './package-policy.js';

package/dist/dom/index.js

@@ -12,3 +12,9 @@ export * from "./ocr.js";
 // T110: xlsx + detection-driven office file redaction
 export * from "./xlsx.js";
 export * from "./office.js";
+// T172: typed refusal errors (fail-closed readers)
+export * from "./errors.js";
+// T175: DrawingML / chart / SmartArt / custom XML text units
+export * from "./drawingml.js";
+// T177: package part policy, unredactable parts, unpacked-size guard
+export * from "./package-policy.js";

package/dist/dom/office.d.ts

@@ -12,6 +12,7 @@
  */
 import type { DetectedEntity } from '../types.js';
 import type { AnonymizationSession } from '../session.js';
+import type { UnredactablePart } from './errors.js';
 /** File kinds the office redaction flow can regenerate. */
 export type OfficeFileKind = 'docx' | 'xlsx';
 /**
@@ -22,12 +23,37 @@ export type OfficeFileKind = 'docx' | 'xlsx';
 export declare function officeFileKind(filename: string): OfficeFileKind | null;
 /** A detect function, typically DocCloakEngine.detect or detectEntities. */
 export type DetectFn = (text: string) => Promise<DetectedEntity[]>;
+/**
+ * Raised by redactOfficeFile (T179, finding M4) when supplied entities do
+ * not match the file's freshly extracted text: the analysis is stale or came
+ * from a different file. Before T179 such entities were dropped silently and
+ * the host received a "successful" copy that still held the value.
+ *
+ * `entities` lists every mismatch (value, type, offsets); the message only
+ * counts them and names their types and offsets so it can be logged without
+ * repeating the values. The session is not touched when this is thrown.
+ */
+export declare class StaleAnalysisError extends Error {
+    readonly entities: DetectedEntity[];
+    constructor(entities: DetectedEntity[], total?: number);
+}
+/** True when `err` is a StaleAnalysisError (also across realms). */
+export declare function isStaleAnalysisError(err: unknown): err is StaleAnalysisError;
 export interface OfficeAnalysis {
     kind: OfficeFileKind;
     /** Flat text extracted from every text-bearing part of the package */
     plainText: string;
     /** Entities detected in the flat text (offsets refer to plainText) */
     entities: DetectedEntity[];
+    /**
+     * Parts DocCloak cannot redact (embedded objects, macros, HTML chunks,
+     * printer settings, unknown parts; T177). Non-empty means redactOfficeFile
+     * refuses the file unless allowUnredactable is passed; hosts show the list
+     * and ask before doing so.
+     */
+    unredactable: UnredactablePart[];
+    /** Reader notes: parts skipped by the extractor (malformed XML). */
+    warnings: string[];
 }
 /**
  * Extract a file's text and run detection WITHOUT touching the session. Hosts
@@ -49,6 +75,23 @@ export interface RedactOfficeFileOptions {
     detect?: DetectFn;
     /** Accept and strip tracked changes in docx output. Default: true. */
     acceptTrackedChanges?: boolean;
+    /**
+     * What to do with a supplied entity whose offsets do not match the freshly
+     * extracted text (T179, M4). 'throw' (default): raise StaleAnalysisError
+     * listing every mismatch before the session is touched, so the host never
+     * gets a "redacted" file that still holds the value. 'drop': the historical
+     * behaviour, mismatches are filtered out and absent from result.entities.
+     */
+    onMismatch?: 'throw' | 'drop';
+    /**
+     * Export even though the package holds parts DocCloak cannot redact
+     * (T177). Default false: the writer throws
+     * UnsupportedDocumentError('unredactable-parts') with the part names in
+     * `details`. With true the parts are copied verbatim and named in
+     * result.warnings; hosts pass it only after the user saw the list from
+     * analyzeOfficeFile.
+     */
+    allowUnredactable?: boolean;
 }
 export interface OfficeRedactionResult {
     kind: OfficeFileKind;
@@ -62,6 +105,14 @@ export interface OfficeRedactionResult {
     plainText: string;
     /** The redacted flat text (placeholders applied), for preview UIs */
     redactedText: string;
+    /**
+     * Writer notes the host must show: one line per unredactable part copied
+     * verbatim (allowUnredactable) and per part the layer-zero scrub could not
+     * parse. Empty on a clean run.
+     */
+    warnings: string[];
+    /** Parts copied verbatim because allowUnredactable was passed (T177). */
+    unredactable: UnredactablePart[];
 }
 /** "report.docx" -> "report.redacted.docx"; extensionless names get a suffix. */
 export declare function redactedFileName(filename: string): string;
@@ -71,5 +122,10 @@ export declare function redactedFileName(filename: string): string;
  * with placeholders spliced into the XML, formatting preserved and metadata
  * stripped. Placeholder issuing goes through session.anonymize, so a value
  * already seen in a prompt reuses its existing placeholder and vice versa.
+ *
+ * Fail-closed (T179): supplied entities that do not match this extraction
+ * raise StaleAnalysisError unless onMismatch is 'drop'; parts that cannot be
+ * redacted raise UnsupportedDocumentError('unredactable-parts') unless
+ * allowUnredactable is passed. Both are thrown before the session changes.
  */
 export declare function redactOfficeFile(file: File, options: RedactOfficeFileOptions): Promise<OfficeRedactionResult>;

package/dist/dom/office.js

@@ -10,8 +10,9 @@
  * PDF is intentionally NOT handled here: layout-preserving PDF redaction is
  * out of scope for this module.
  */
-import { getFileExtension, readDocx, writeAnonymizedDocx } from "./docx.js";
-import { readXlsx, writeAnonymizedXlsx } from "./xlsx.js";
+import { getFileExtension, readDocx, writeAnonymizedDocxWithReport } from "./docx.js";
+import { readXlsx, writeAnonymizedXlsxWithReport } from "./xlsx.js";
+import { layerZeroValueReplacements } from "./opc.js";
 /**
  * Classify a filename into a supported office kind, or null when the format
  * cannot be regenerated by this module (.doc has its own binary writer in
@@ -25,6 +26,31 @@ export function officeFileKind(filename) {
         return 'xlsx';
     return null;
 }
+/**
+ * Raised by redactOfficeFile (T179, finding M4) when supplied entities do
+ * not match the file's freshly extracted text: the analysis is stale or came
+ * from a different file. Before T179 such entities were dropped silently and
+ * the host received a "successful" copy that still held the value.
+ *
+ * `entities` lists every mismatch (value, type, offsets); the message only
+ * counts them and names their types and offsets so it can be logged without
+ * repeating the values. The session is not touched when this is thrown.
+ */
+export class StaleAnalysisError extends Error {
+    constructor(entities, total = entities.length) {
+        const where = entities.map((e) => `${e.type}@${e.start}-${e.end}`).join(', ');
+        super(`${entities.length} of ${total} supplied entities do not match the file's text `
+            + `(stale analysis or a different file): ${where}. Re-run analyzeOfficeFile on this file.`);
+        this.name = 'StaleAnalysisError';
+        this.entities = entities;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** True when `err` is a StaleAnalysisError (also across realms). */
+export function isStaleAnalysisError(err) {
+    return err instanceof StaleAnalysisError
+        || (typeof err === 'object' && err !== null && err.name === 'StaleAnalysisError');
+}
 /**
  * Extract a file's text and run detection WITHOUT touching the session. Hosts
  * use this to show the user what was found before asking for consent to
@@ -36,11 +62,15 @@ export async function analyzeOfficeFile(file, detect) {
     const kind = officeFileKind(file.name);
     if (!kind)
         throw new Error(`Unsupported office file: ${file.name}`);
-    const plainText = kind === 'docx'
-        ? (await readDocx(file)).plainText
-        : (await readXlsx(file)).plainText;
-    const entities = await detect(plainText);
-    return { kind, plainText, entities };
+    const extraction = kind === 'docx' ? await readDocx(file) : await readXlsx(file);
+    const entities = await detect(extraction.plainText);
+    return {
+        kind,
+        plainText: extraction.plainText,
+        entities,
+        unredactable: extraction.unredactable,
+        warnings: extraction.warnings,
+    };
 }
 /** "report.docx" -> "report.redacted.docx"; extensionless names get a suffix. */
 export function redactedFileName(filename) {
@@ -49,12 +79,24 @@ export function redactedFileName(filename) {
         return `${filename}.redacted`;
     return `${filename.slice(0, dot)}.redacted${filename.slice(dot)}`;
 }
+/** True when the entity's offsets land exactly on its value in the text. */
+function matchesText(entity, plainText) {
+    return entity.start >= 0
+        && entity.end <= plainText.length
+        && entity.start < entity.end
+        && plainText.slice(entity.start, entity.end) === entity.value;
+}
 /**
  * Redact a DOCX or XLSX file: extract text, detect (or reuse supplied
  * entities), map every entity through the session, and regenerate the file
  * with placeholders spliced into the XML, formatting preserved and metadata
  * stripped. Placeholder issuing goes through session.anonymize, so a value
  * already seen in a prompt reuses its existing placeholder and vice versa.
+ *
+ * Fail-closed (T179): supplied entities that do not match this extraction
+ * raise StaleAnalysisError unless onMismatch is 'drop'; parts that cannot be
+ * redacted raise UnsupportedDocumentError('unredactable-parts') unless
+ * allowUnredactable is passed. Both are thrown before the session changes.
  */
 export async function redactOfficeFile(file, options) {
     const kind = officeFileKind(file.name);
@@ -70,14 +112,19 @@ export async function redactOfficeFile(file, options) {
         entities = await options.detect(plainText);
     }
     const { session } = options;
-    // Drop entities whose offsets do not match this extraction (defensive: a
-    // stale analysis of a different file must not splice garbage), then map
-    // through the session in reading order. Surrogate mode maps PERSON values
-    // first, mirroring AnonymizationSession.anonymizeText, so derived
+    // Entities whose offsets do not match this extraction come from a stale
+    // analysis (or a different file). Splicing them would corrupt the text and
+    // skipping them silently would ship the value (M4), so the default is to
+    // refuse; 'drop' keeps the historical filter for hosts that re-detect.
+    const mismatched = entities.filter((e) => !matchesText(e, plainText));
+    if (mismatched.length > 0 && (options.onMismatch ?? 'throw') === 'throw') {
+        throw new StaleAnalysisError(mismatched, entities.length);
+    }
+    // Map through the session in reading order. Surrogate mode maps PERSON
+    // values first, mirroring AnonymizationSession.anonymizeText, so derived
     // surrogates (emails from owner names) stay consistent with prompts.
     const valid = entities
-        .filter((e) => e.start >= 0 && e.end <= plainText.length && e.start < e.end
-        && plainText.slice(e.start, e.end) === e.value)
+        .filter((e) => matchesText(e, plainText))
         .sort((a, b) => a.start - b.start || a.end - b.end);
     if (session.getMode() === 'surrogate') {
         for (const entity of valid) {
@@ -90,27 +137,33 @@ export async function redactOfficeFile(file, options) {
         end: entity.end,
         replacement: session.anonymize(entity.value, entity.type),
     }));
-    // Value-level scrubbing (relationship targets, formulas, field instructions)
-    // uses the whole session map, so a value redacted in an earlier prompt is
-    // also caught when it hides in a hyperlink target of this file.
-    const valueReplacements = session.getEntries()
-        .filter((entry) => entry.replacement !== '________')
-        .map((entry) => ({ value: entry.original, replacement: entry.replacement }));
+    // Value-level scrubbing (relationship targets, formulas, field instructions
+    // and the package-wide layer zero) uses the whole session map, so a value
+    // redacted in an earlier prompt is also caught when it hides in a hyperlink
+    // target of this file. layerZeroValueReplacements (T172) adds the PERSON
+    // name tokens, so a bare surname in a chart cache or custom XML part is
+    // caught too. Blanked entries ('________') stay out of the value list.
+    const valueReplacements = layerZeroValueReplacements(session.getEntries().filter((entry) => entry.replacement !== '________'));
     let redactedText = plainText;
     for (const repl of [...replacements].sort((a, b) => b.start - a.start)) {
         redactedText = redactedText.slice(0, repl.start) + repl.replacement + redactedText.slice(repl.end);
     }
-    const blob = kind === 'docx'
-        ? await writeAnonymizedDocx(extraction, replacements, valueReplacements, {
+    const written = kind === 'docx'
+        ? await writeAnonymizedDocxWithReport(extraction, replacements, valueReplacements, {
             acceptTrackedChanges: options.acceptTrackedChanges ?? true,
+            allowUnredactable: options.allowUnredactable ?? false,
         })
-        : await writeAnonymizedXlsx(extraction, replacements, valueReplacements);
+        : await writeAnonymizedXlsxWithReport(extraction, replacements, valueReplacements, {
+            allowUnredactable: options.allowUnredactable ?? false,
+        });
     return {
         kind,
-        blob,
+        blob: written.blob,
         suggestedName: redactedFileName(file.name),
         entities: valid,
         plainText,
         redactedText,
+        warnings: written.warnings,
+        unredactable: extraction.unredactable,
     };
 }