@doccloak/core 0.12.1 → 0.14.0

package/dist/dom/ocr.d.ts

@@ -85,22 +85,48 @@ interface BlockLike {
  * Exported for tests.
  */
 export declare function buildTextFromBlocks(blocks: BlockLike[]): OcrExtraction;
+type PixelBox = {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+};
+/**
+ * For each pair of consecutive OCR words, whether they are really one token
+ * that OCR split by dropping a character. Tesseract reads the dot in
+ * "t.zielinski@firma.pl" as a space and returns "t" + "zielinski@firma.pl",
+ * with the dot's pixels inside the second box; the e-mail rule then matches
+ * only the second word, and without this the "t" would stay visible. Such a
+ * split leaves a sliver between the boxes, far narrower than a real space: a
+ * pair on the same line is one token when its gap is at most
+ * TIGHT_GAP_SHARE of the line's typical word gap (boxes that touch or
+ * overlap included). Boxes much taller than the line (MAX_JOIN_HEIGHT_RATIO)
+ * are OCR noise and never join, so the fix cannot paint a bar across
+ * neighbouring lines.
+ *
+ * Not covered: a lost glyph that stays in a normal-width gap (seen only on
+ * low-resolution images, around 120 dpi). Telling it from a glyph edge that
+ * Tesseract cut off its own box needs pixels and misfired on real scans
+ * ("w terminie", "nr wpisu"), so gap width alone decides.
+ *
+ * Returns an array of length words.length - 1: entry i joins words i and i+1.
+ * Exported for tests.
+ */
+export declare function findSplitTokens(words: OcrWord[]): boolean[];
 /**
  * Pick the bounding boxes of every OCR word that overlaps one of the given
  * character ranges. A word partially covered by a range is fully redacted
- * (over-redaction is safer than leaking half an identifier).
+ * (over-redaction is safer than leaking half an identifier). A selected
+ * word also pulls in the same-line neighbours OCR split off by dropping a
+ * character (findSplitTokens), so "t" + "zielinski@firma.pl" is redacted
+ * as one token.
  *
  * Exported for tests.
  */
 export declare function selectRedactionBoxes(words: OcrWord[], ranges: {
     start: number;
     end: number;
-}[]): {
-    x0: number;
-    y0: number;
-    x1: number;
-    y1: number;
-}[];
+}[]): PixelBox[];
 /**
  * Draw black boxes over the given character ranges and return the redacted
  * image as a PNG blob.

package/dist/dom/ocr.js

@@ -174,17 +174,111 @@ export function buildTextFromBlocks(blocks) {
     }
     return { text: text.trimEnd(), words };
 }
+/** Share of the smaller box height two boxes must overlap to sit on one line. */
+const SAME_LINE_OVERLAP = 0.5;
+/**
+ * A gap at most this share of the line's typical word gap is not a space:
+ * OCR split one token there and the lost glyph went into a neighbour's box.
+ */
+const TIGHT_GAP_SHARE = 0.3;
+/** Typical word gap as a share of the line's box height, for lines too short to measure. */
+const FALLBACK_GAP_SHARE = 0.4;
+/** Lines with fewer measured gaps than this use the height-based fallback. */
+const MIN_GAPS_FOR_MEDIAN = 3;
+/**
+ * Boxes taller than this multiple of the line's median height are OCR noise
+ * (a stray mark or a punctuation box spanning lines); they never join, so a
+ * split-token fix does not paint a bar across the neighbouring lines.
+ */
+const MAX_JOIN_HEIGHT_RATIO = 1.6;
+/** Whether `right` continues `left` on the same OCR line (adjacent in the text, overlapping vertically). */
+function continuesLine(left, right) {
+    if (right.start !== left.end + 1)
+        return false;
+    const a = left.bbox;
+    const b = right.bbox;
+    const minHeight = Math.min(a.y1 - a.y0, b.y1 - b.y0);
+    if (minHeight <= 0)
+        return false;
+    const overlap = Math.min(a.y1, b.y1) - Math.max(a.y0, b.y0);
+    return overlap >= minHeight * SAME_LINE_OVERLAP && b.x1 > a.x1;
+}
+function median(values) {
+    const sorted = [...values].sort((x, y) => x - y);
+    return sorted[Math.floor(sorted.length / 2)];
+}
+/**
+ * For each pair of consecutive OCR words, whether they are really one token
+ * that OCR split by dropping a character. Tesseract reads the dot in
+ * "t.zielinski@firma.pl" as a space and returns "t" + "zielinski@firma.pl",
+ * with the dot's pixels inside the second box; the e-mail rule then matches
+ * only the second word, and without this the "t" would stay visible. Such a
+ * split leaves a sliver between the boxes, far narrower than a real space: a
+ * pair on the same line is one token when its gap is at most
+ * TIGHT_GAP_SHARE of the line's typical word gap (boxes that touch or
+ * overlap included). Boxes much taller than the line (MAX_JOIN_HEIGHT_RATIO)
+ * are OCR noise and never join, so the fix cannot paint a bar across
+ * neighbouring lines.
+ *
+ * Not covered: a lost glyph that stays in a normal-width gap (seen only on
+ * low-resolution images, around 120 dpi). Telling it from a glyph edge that
+ * Tesseract cut off its own box needs pixels and misfired on real scans
+ * ("w terminie", "nr wpisu"), so gap width alone decides.
+ *
+ * Returns an array of length words.length - 1: entry i joins words i and i+1.
+ * Exported for tests.
+ */
+export function findSplitTokens(words) {
+    const joined = new Array(Math.max(0, words.length - 1)).fill(false);
+    const height = (w) => w.bbox.y1 - w.bbox.y0;
+    let i = 0;
+    while (i < words.length - 1) {
+        if (!continuesLine(words[i], words[i + 1])) {
+            i++;
+            continue;
+        }
+        let end = i + 1; // the line runs from word i to word end
+        while (end < words.length - 1 && continuesLine(words[end], words[end + 1]))
+            end++;
+        const gaps = [];
+        for (let k = i; k < end; k++)
+            gaps.push(words[k + 1].bbox.x0 - words[k].bbox.x1);
+        const lineHeight = median(words.slice(i, end + 1).map(height));
+        const typicalGap = gaps.length >= MIN_GAPS_FOR_MEDIAN ? median(gaps) : lineHeight * FALLBACK_GAP_SHARE;
+        const tightGap = Math.max(1, typicalGap * TIGHT_GAP_SHARE);
+        const maxHeight = lineHeight * MAX_JOIN_HEIGHT_RATIO;
+        for (let k = i; k < end; k++) {
+            joined[k] = gaps[k - i] <= tightGap
+                && height(words[k]) <= maxHeight
+                && height(words[k + 1]) <= maxHeight;
+        }
+        i = end;
+    }
+    return joined;
+}
 /**
  * Pick the bounding boxes of every OCR word that overlaps one of the given
  * character ranges. A word partially covered by a range is fully redacted
- * (over-redaction is safer than leaking half an identifier).
+ * (over-redaction is safer than leaking half an identifier). A selected
+ * word also pulls in the same-line neighbours OCR split off by dropping a
+ * character (findSplitTokens), so "t" + "zielinski@firma.pl" is redacted
+ * as one token.
  *
  * Exported for tests.
  */
 export function selectRedactionBoxes(words, ranges) {
-    return words
-        .filter((w) => ranges.some((r) => w.start < r.end && w.end > r.start))
-        .map((w) => w.bbox);
+    const selected = words.map((w) => ranges.some((r) => w.start < r.end && w.end > r.start));
+    if (selected.some(Boolean)) {
+        const joined = findSplitTokens(words);
+        // Spread each selection across its split pieces, left to right then back.
+        for (let i = 0; i < joined.length; i++)
+            if (joined[i] && selected[i])
+                selected[i + 1] = true;
+        for (let i = joined.length - 1; i >= 0; i--)
+            if (joined[i] && selected[i + 1])
+                selected[i] = true;
+    }
+    return words.filter((_, i) => selected[i]).map((w) => w.bbox);
 }
 /** Encode a canvas as a PNG blob, whichever canvas flavor it is. */
 function canvasToPngBlob(canvas) {

package/dist/dom/office.d.ts

@@ -1,24 +1,26 @@
 /**
  * @doccloak/core/dom - detection-driven office file redaction (T110).
  *
- * Ties the format modules (docx.ts, xlsx.ts) to the detection pipeline and an
+ * Ties the format modules (docx.ts, xlsx.ts, and the PDF module behind
+ * '@doccloak/core/pdf', T215) to the detection pipeline and an
  * AnonymizationSession, so a host can hand over a File plus its live session
  * and get back a redacted copy whose placeholders are consistent with every
  * prompt redacted in the same session: an AI reply that mentions the file's
  * placeholders restores through the same session map.
  *
- * PDF is intentionally NOT handled here: layout-preserving PDF redaction is
- * out of scope for this module.
+ * The PDF module is imported lazily so hosts that never see a PDF do not
+ * load pdf-lib, pdf.js and fontkit.
  */
 import type { DetectedEntity } from '../types.js';
 import type { AnonymizationSession } from '../session.js';
 import type { UnredactablePart } from './errors.js';
+import type { PdfReadOptions, PdfWriteOptions, RemovedPart } from '../pdf/types.js';
 /** File kinds the office redaction flow can regenerate. */
-export type OfficeFileKind = 'docx' | 'xlsx';
+export type OfficeFileKind = 'docx' | 'xlsx' | 'pdf';
 /**
  * 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
- * src/doc.ts; PDF output is permanently out of scope for browser hosts).
+ * src/doc.ts).
  */
 export declare function officeFileKind(filename: string): OfficeFileKind | null;
 /** A detect function, typically DocCloakEngine.detect or detectEntities. */
@@ -54,6 +56,12 @@ export interface OfficeAnalysis {
     unredactable: UnredactablePart[];
     /** Reader notes: parts skipped by the extractor (malformed XML). */
     warnings: string[];
+    /** PDF only: parts the writer will drop (annotations, forms, bookmarks, ...). */
+    removed?: RemovedPart[];
+}
+export interface AnalyzeOfficeFileOptions {
+    /** PDF reader options (asset URLs for pdf.js and the fallback fonts, password, caps). */
+    pdf?: PdfReadOptions;
 }
 /**
  * Extract a file's text and run detection WITHOUT touching the session. Hosts
@@ -62,7 +70,7 @@ export interface OfficeAnalysis {
  * Extraction is deterministic, so entities returned here can be passed to
  * redactOfficeFile later and land on identical offsets.
  */
-export declare function analyzeOfficeFile(file: File, detect: DetectFn): Promise<OfficeAnalysis>;
+export declare function analyzeOfficeFile(file: File, detect: DetectFn, options?: AnalyzeOfficeFileOptions): Promise<OfficeAnalysis>;
 export interface RedactOfficeFileOptions {
     /** The live session; file placeholders join the same map as prompt ones. */
     session: AnonymizationSession;
@@ -92,6 +100,8 @@ export interface RedactOfficeFileOptions {
      * analyzeOfficeFile.
      */
     allowUnredactable?: boolean;
+    /** PDF only: reader options (assets, password) and writer options (fit policy, raster DPI). */
+    pdf?: PdfReadOptions & PdfWriteOptions;
 }
 export interface OfficeRedactionResult {
     kind: OfficeFileKind;
@@ -113,6 +123,12 @@ export interface OfficeRedactionResult {
     warnings: string[];
     /** Parts copied verbatim because allowUnredactable was passed (T177). */
     unredactable: UnredactablePart[];
+    /** PDF only: parts dropped from the output. */
+    removed?: RemovedPart[];
+    /** PDF only: 0-based pages that were rasterized because they could not be edited safely. */
+    rasterizedPages?: number[];
+    /** PDF only: 0-based scan pages whose OCR-found values were painted over in the picture. */
+    scanPages?: number[];
 }
 /** "report.docx" -> "report.redacted.docx"; extensionless names get a suffix. */
 export declare function redactedFileName(filename: string): string;

package/dist/dom/office.js

@@ -1,14 +1,15 @@
 /**
  * @doccloak/core/dom - detection-driven office file redaction (T110).
  *
- * Ties the format modules (docx.ts, xlsx.ts) to the detection pipeline and an
+ * Ties the format modules (docx.ts, xlsx.ts, and the PDF module behind
+ * '@doccloak/core/pdf', T215) to the detection pipeline and an
  * AnonymizationSession, so a host can hand over a File plus its live session
  * and get back a redacted copy whose placeholders are consistent with every
  * prompt redacted in the same session: an AI reply that mentions the file's
  * placeholders restores through the same session map.
  *
- * PDF is intentionally NOT handled here: layout-preserving PDF redaction is
- * out of scope for this module.
+ * The PDF module is imported lazily so hosts that never see a PDF do not
+ * load pdf-lib, pdf.js and fontkit.
  */
 import { getFileExtension, readDocx, writeAnonymizedDocxWithReport } from "./docx.js";
 import { readXlsx, writeAnonymizedXlsxWithReport } from "./xlsx.js";
@@ -16,7 +17,7 @@ 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
- * src/doc.ts; PDF output is permanently out of scope for browser hosts).
+ * src/doc.ts).
  */
 export function officeFileKind(filename) {
     const ext = getFileExtension(filename);
@@ -24,8 +25,26 @@ export function officeFileKind(filename) {
         return 'docx';
     if (ext === 'xlsx')
         return 'xlsx';
+    if (ext === 'pdf')
+        return 'pdf';
     return null;
 }
+/** Lazy loader of the PDF module (keeps pdf-lib/pdf.js/fontkit out of hosts that never see a PDF). */
+async function pdfModule() {
+    return import("../pdf/index.js");
+}
+async function readByKind(kind, file, pdf) {
+    if (kind === 'docx')
+        return readDocx(file);
+    if (kind === 'xlsx')
+        return readXlsx(file);
+    // A host that has not wired the PDF assets (pdf.js worker, fallback fonts) cannot redact PDFs; refuse
+    // the way an unsupported format is refused instead of failing deep inside pdf.js.
+    if (!pdf)
+        throw new Error(`Unsupported office file: ${file.name} (this host has no PDF support configured)`);
+    const { readPdf } = await pdfModule();
+    return readPdf(file, pdf);
+}
 /**
  * Raised by redactOfficeFile (T179, finding M4) when supplied entities do
  * not match the file's freshly extracted text: the analysis is stale or came
@@ -58,11 +77,11 @@ export function isStaleAnalysisError(err) {
  * Extraction is deterministic, so entities returned here can be passed to
  * redactOfficeFile later and land on identical offsets.
  */
-export async function analyzeOfficeFile(file, detect) {
+export async function analyzeOfficeFile(file, detect, options = {}) {
     const kind = officeFileKind(file.name);
     if (!kind)
         throw new Error(`Unsupported office file: ${file.name}`);
-    const extraction = kind === 'docx' ? await readDocx(file) : await readXlsx(file);
+    const extraction = await readByKind(kind, file, options.pdf);
     const entities = await detect(extraction.plainText);
     return {
         kind,
@@ -70,6 +89,7 @@ export async function analyzeOfficeFile(file, detect) {
         entities,
         unredactable: extraction.unredactable,
         warnings: extraction.warnings,
+        removed: kind === 'pdf' ? extraction.removed : undefined,
     };
 }
 /** "report.docx" -> "report.redacted.docx"; extensionless names get a suffix. */
@@ -102,7 +122,7 @@ export async function redactOfficeFile(file, options) {
     const kind = officeFileKind(file.name);
     if (!kind)
         throw new Error(`Unsupported office file: ${file.name}`);
-    const extraction = kind === 'docx' ? await readDocx(file) : await readXlsx(file);
+    const extraction = await readByKind(kind, file, options.pdf);
     const plainText = extraction.plainText;
     let entities = options.entities;
     if (!entities) {
@@ -148,14 +168,25 @@ export async function redactOfficeFile(file, options) {
     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 written = kind === 'docx'
-        ? await writeAnonymizedDocxWithReport(extraction, replacements, valueReplacements, {
+    let written;
+    if (kind === 'docx') {
+        written = await writeAnonymizedDocxWithReport(extraction, replacements, valueReplacements, {
             acceptTrackedChanges: options.acceptTrackedChanges ?? true,
             allowUnredactable: options.allowUnredactable ?? false,
-        })
-        : await writeAnonymizedXlsxWithReport(extraction, replacements, valueReplacements, {
+        });
+    }
+    else if (kind === 'xlsx') {
+        written = await writeAnonymizedXlsxWithReport(extraction, replacements, valueReplacements, {
+            allowUnredactable: options.allowUnredactable ?? false,
+        });
+    }
+    else {
+        const { writeAnonymizedPdfWithReport } = await pdfModule();
+        written = await writeAnonymizedPdfWithReport(extraction, replacements, valueReplacements, {
+            ...(options.pdf ?? {}),
             allowUnredactable: options.allowUnredactable ?? false,
         });
+    }
     return {
         kind,
         blob: written.blob,
@@ -165,5 +196,8 @@ export async function redactOfficeFile(file, options) {
         redactedText,
         warnings: written.warnings,
         unredactable: extraction.unredactable,
+        removed: written.removed,
+        rasterizedPages: written.rasterizedPages,
+        scanPages: written.scanPages,
     };
 }

package/dist/engine.js

@@ -13,6 +13,7 @@
  * PortLike transport (Web Worker postMessage, MessageChannel, extension
  * ports).
  */
+import { throwIfAborted } from "./types.js";
 import { detectWithRegex, detectEntities } from "./pipeline.js";
 import { GlinerProvider } from "./providers/gliner.js";
 import { GlinerBaseProvider } from "./providers/gliner-base.js";
@@ -264,8 +265,7 @@ export function createEngine(env, initial, options) {
     }
     async function detect(text, signal, onProgress) {
         await ready;
-        if (signal?.aborted)
-            throw new Error('Detection aborted');
+        throwIfAborted(signal);
         if (!text.trim())
             return [];
         const p = ensureProvider();
@@ -282,9 +282,8 @@ export function createEngine(env, initial, options) {
             onProgress?.(progress);
             for (const cb of detectionListeners)
                 cb(progress);
-        });
-        if (signal?.aborted)
-            throw new Error('Detection aborted');
+        }, signal);
+        throwIfAborted(signal);
         const regexResults = settings.regexEnabled ? detectWithRegex(text, settings.regexRegion) : [];
         return detectEntities(text, mlResults, regexResults);
     }

package/dist/env.d.ts

@@ -41,12 +41,12 @@ export interface CoreEnv {
      * `new PreTrainedTokenizer(tokenizerJson, tokenizerConfig)` (or the class
      * named by `tokenizerConfig.tokenizer_class`). May return a promise.
      *
-     * Optional in 0.12.0 only so hosts still on loadTokenizer keep compiling;
-     * required from 0.13.0.
+     * Optional so hosts still on loadTokenizer keep compiling; required once
+     * loadTokenizer is removed (planned for a later release).
      */
     buildTokenizer?(tokenizerJson: unknown, tokenizerConfig: unknown): unknown | Promise<unknown>;
     /**
-     * @deprecated since 0.12.0, removed in 0.13.0. Used only when
+     * @deprecated since 0.12.0, removal planned for 0.14.0. Used only when
      * buildTokenizer is absent. Loading by Hugging Face model id lets the
      * host library probe mutable `resolve/main` and keep an unverified
      * second cache (security report S1/S3); implement buildTokenizer.

package/dist/pdf/cmap.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @doccloak/core/pdf - CMap parser, decoder and ToUnicode serializer (T208).
+ *
+ * Handles the CMap syntax of ISO 32000-1 section 9.7.5 (embedded CMap
+ * streams) and 9.10.3 (ToUnicode CMaps): codespace ranges, cidrange /
+ * cidchar, bfchar / bfrange (both the incrementing and the array form,
+ * multi-code-unit UTF-16BE destinations with surrogates), /WMode, /CMapName.
+ * `usecmap` and predefined CMaps other than Identity-H/V are refused: the
+ * caller reports the font as unredactable rather than guessing.
+ *
+ * The parser is strict: malformed input throws CMapParseError, it never
+ * returns a partial map silently. A missing codespace section is the one
+ * tolerated defect (common in real ToUnicode CMaps): the ranges are then
+ * derived from the byte lengths of the codes seen.
+ */
+export interface CodespaceRange {
+    /** Code length in bytes (1..4). */
+    numBytes: number;
+    /** Inclusive bounds as big-endian integers of `numBytes` bytes. */
+    low: number;
+    high: number;
+}
+export interface CMap {
+    codespace: CodespaceRange[];
+    /** code -> CID for CID CMaps. null means identity (Identity-H/V or a CMap without cid entries). */
+    cidMap: Map<number, number> | null;
+    /** code -> unicode string for ToUnicode CMaps. null when the CMap has no bf entries. */
+    unicodeMap: Map<number, string> | null;
+    /** True for vertical writing mode (/WMode 1, Identity-V). */
+    vertical: boolean;
+    /** /CMapName when present. */
+    name?: string;
+    /** Code lengths (in bytes, 1..4) seen in codespace ranges and mapping entries. */
+    codeLengths: Set<number>;
+}
+export declare class CMapParseError extends Error {
+    constructor(message: string);
+}
+/** Largest number of entries one range (cidrange / bfrange) may expand to. Guards against memory bombs. */
+export declare const MAX_RANGE_ENTRIES = 65536;
+/** Parse an embedded CMap / ToUnicode stream. Throws CMapParseError on malformed input or `usecmap`. */
+export declare function parseCMap(bytes: Uint8Array): CMap;
+/** The 2-byte Identity CMap: every code is its own CID. */
+export declare function identityCMap(vertical: boolean): CMap;
+/** Only Identity-H / Identity-V are built in; any other predefined name is refused by the caller. */
+export declare function predefinedCMap(name: string): CMap | undefined;
+export interface DecodedCode {
+    /** Big-endian value of the code bytes. */
+    code: number;
+    /** Number of bytes consumed (1..4). */
+    length: number;
+    /** Byte offset of the code inside the string operand. */
+    offset: number;
+}
+/**
+ * Split a string operand into character codes (ISO 32000-1 9.7.6.3). For each
+ * position the shortest byte length whose codespace range contains the value
+ * wins; with no full match, the shortest range that matches on the first byte
+ * decides the length; otherwise 1 byte. Unmapped codes are still returned, the
+ * caller treats them as notdef. A code cut short by the end of the string takes
+ * the remaining bytes.
+ */
+export declare function splitCodes(cmap: CMap, bytes: Uint8Array): DecodedCode[];
+/** CID of a code: identity when the CMap has no cid entries, 0 (notdef) when the code is unmapped. */
+export declare function cidOf(cmap: CMap, code: number): number;
+/** Unicode text of a code from a ToUnicode CMap; undefined when unmapped (or when the CMap has no bf entries). */
+export declare function unicodeOf(cmap: CMap, code: number): string | undefined;
+export interface ToUnicodeEntry {
+    code: number;
+    /** Code length in bytes (1..4). */
+    length: number;
+    unicode: string;
+}
+/**
+ * Write a ToUnicode CMap holding exactly the given codes. One full-width
+ * codespace range per code length present, bfchar entries in groups of at most
+ * 100, UTF-16BE destinations. Output is deterministic (sorted by length, then
+ * code; later duplicates win) and reads back with parseCMap to the same map.
+ */
+export declare function serializeToUnicode(entries: ToUnicodeEntry[], options?: {
+    name?: string;
+    codespace?: readonly CodespaceRange[];
+}): Uint8Array;