@doccloak/core 0.12.1 → 0.13.0

package/dist/pdf/objects.js

@@ -0,0 +1,217 @@
+/**
+ * @doccloak/core/pdf - typed helpers over the pdf-lib object model (T206).
+ *
+ * pdf-lib (@cantoo/pdf-lib) parses the file into PDFContext objects; these
+ * helpers resolve indirect references and coerce values so the rest of the
+ * module never touches raw PDFObject subclasses in ad-hoc ways. All getters
+ * return undefined for missing or wrong-typed values instead of throwing:
+ * callers decide whether a missing value is an "unsafe page" or a default.
+ */
+import { PDFArray, PDFBool, PDFContext, PDFDict, PDFHexString, PDFName, PDFNumber, PDFObject, PDFRawStream, PDFRef, PDFStream, PDFString, decodePDFRawStream, } from '@cantoo/pdf-lib';
+export { PDFName, PDFNumber, PDFString, PDFHexString, PDFRawStream, PDFBool, PDFArray, PDFDict, PDFRef, PDFStream };
+/** Follow indirect references (bounded, refs can be chained). */
+export function resolve(ctx, obj) {
+    let cur = obj;
+    for (let i = 0; i < 32 && cur instanceof PDFRef; i++)
+        cur = ctx.lookup(cur);
+    return cur instanceof PDFRef ? undefined : cur;
+}
+export function getDict(ctx, dict, key) {
+    if (!dict)
+        return undefined;
+    const v = resolve(ctx, dict.get(PDFName.of(key)));
+    if (v instanceof PDFDict)
+        return v;
+    if (v instanceof PDFStream)
+        return v.dict;
+    return undefined;
+}
+export function getStream(ctx, dict, key) {
+    if (!dict)
+        return undefined;
+    const v = resolve(ctx, dict.get(PDFName.of(key)));
+    return v instanceof PDFStream ? v : undefined;
+}
+export function getArray(ctx, dict, key) {
+    if (!dict)
+        return undefined;
+    const v = resolve(ctx, dict.get(PDFName.of(key)));
+    return v instanceof PDFArray ? v : undefined;
+}
+export function getName(ctx, dict, key) {
+    if (!dict)
+        return undefined;
+    const v = resolve(ctx, dict.get(PDFName.of(key)));
+    return v instanceof PDFName ? v.decodeText() : undefined;
+}
+export function getNumber(ctx, dict, key) {
+    if (!dict)
+        return undefined;
+    const v = resolve(ctx, dict.get(PDFName.of(key)));
+    return v instanceof PDFNumber ? v.asNumber() : undefined;
+}
+export function getBool(ctx, dict, key) {
+    if (!dict)
+        return undefined;
+    const v = resolve(ctx, dict.get(PDFName.of(key)));
+    return v instanceof PDFBool ? v.asBoolean() : undefined;
+}
+/** Raw bytes of a string object (literal or hex), without text decoding. */
+export function stringBytes(obj) {
+    if (obj instanceof PDFHexString)
+        return obj.asBytes();
+    if (obj instanceof PDFString)
+        return obj.asBytes();
+    return undefined;
+}
+/** Decoded text of a string object (PDFDocEncoding / UTF-16 BOM aware). */
+export function stringText(obj) {
+    if (obj instanceof PDFHexString || obj instanceof PDFString) {
+        try {
+            return obj.decodeText();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+export function getString(ctx, dict, key) {
+    if (!dict)
+        return undefined;
+    return stringText(resolve(ctx, dict.get(PDFName.of(key))));
+}
+/** Numbers of an array (non-numbers skipped). */
+export function numbersOf(ctx, arr) {
+    if (!arr)
+        return [];
+    const out = [];
+    for (let i = 0; i < arr.size(); i++) {
+        const v = resolve(ctx, arr.get(i));
+        if (v instanceof PDFNumber)
+            out.push(v.asNumber());
+    }
+    return out;
+}
+/** Elements of an array, references resolved. */
+export function itemsOf(ctx, arr) {
+    if (!arr)
+        return [];
+    const out = [];
+    for (let i = 0; i < arr.size(); i++) {
+        const v = resolve(ctx, arr.get(i));
+        if (v)
+            out.push(v);
+    }
+    return out;
+}
+/** Names of a name-or-array-of-names value (e.g. /Filter). */
+export function namesOf(ctx, obj) {
+    const v = resolve(ctx, obj);
+    if (v instanceof PDFName)
+        return [v.decodeText()];
+    if (v instanceof PDFArray) {
+        return itemsOf(ctx, v).filter((x) => x instanceof PDFName).map((n) => n.decodeText());
+    }
+    return [];
+}
+/** Filters that decodePDFRawStream understands (image codecs are left encoded). */
+const DECODABLE_FILTERS = new Set(['FlateDecode', 'Fl', 'LZWDecode', 'LZW', 'ASCIIHexDecode', 'AHx', 'ASCII85Decode', 'A85', 'RunLengthDecode', 'RL']);
+export class StreamDecodeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'StreamDecodeError';
+    }
+}
+/**
+ * Fully decoded bytes of a stream. Throws StreamDecodeError when a filter is
+ * not decodable (JPX, DCT, CCITT, JBIG2, Crypt) or the data is corrupt, so
+ * the caller can treat the page as unsafe instead of reading garbage.
+ */
+export function decodeStream(ctx, stream) {
+    if (stream instanceof PDFRawStream) {
+        const filters = namesOf(ctx, stream.dict.get(PDFName.of('Filter')));
+        for (const f of filters) {
+            if (!DECODABLE_FILTERS.has(f))
+                throw new StreamDecodeError(`undecodable filter /${f}`);
+        }
+        try {
+            return decodePDFRawStream(stream).decode();
+        }
+        catch (err) {
+            throw new StreamDecodeError(`stream decode failed: ${err.message}`);
+        }
+    }
+    // pdf-lib's own stream classes (created streams): getContents is the decoded form
+    // for PDFContentStream; for PDFFlateStream it is the encoded form, so avoid them.
+    const maybe = stream;
+    if (typeof maybe.getUnencodedContents === 'function')
+        return maybe.getUnencodedContents();
+    if (typeof maybe.getContents === 'function')
+        return maybe.getContents();
+    throw new StreamDecodeError('unknown stream class');
+}
+/** True when the filter list contains an image codec (the stream holds pixels, not operators). */
+export function isImageEncoded(ctx, stream) {
+    const filters = namesOf(ctx, stream.dict.get(PDFName.of('Filter')));
+    return filters.some((f) => !DECODABLE_FILTERS.has(f));
+}
+/** Stable key for an object: 'r<num>g<gen>' for refs, or a synthetic key. */
+export function refKey(ref) {
+    return `r${ref.objectNumber}g${ref.generationNumber}`;
+}
+/** Find the ref of an object stored directly in a dict entry (undefined for direct objects). */
+export function refOf(dict, key) {
+    const v = dict.get(PDFName.of(key));
+    return v instanceof PDFRef ? v : undefined;
+}
+/** Iterate (key, value) pairs of a dict with references resolved. */
+export function entriesOf(ctx, dict) {
+    const out = [];
+    for (const [k, v] of dict.entries()) {
+        const r = resolve(ctx, v);
+        if (r)
+            out.push([k.decodeText(), r]);
+    }
+    return out;
+}
+/** The content streams of a page: /Contents may be a stream or an array of streams. */
+export function pageContentStreams(ctx, pageDict) {
+    const raw = pageDict.get(PDFName.of('Contents'));
+    const resolved = resolve(ctx, raw);
+    if (resolved instanceof PDFStream)
+        return [{ ref: raw instanceof PDFRef ? raw : undefined, stream: resolved }];
+    if (resolved instanceof PDFArray) {
+        const out = [];
+        for (let i = 0; i < resolved.size(); i++) {
+            const item = resolved.get(i);
+            const s = resolve(ctx, item);
+            if (s instanceof PDFStream)
+                out.push({ ref: item instanceof PDFRef ? item : undefined, stream: s });
+        }
+        return out;
+    }
+    return [];
+}
+/** Resources dict of a page, walking up the /Parent chain when inherited. */
+export function pageResources(ctx, pageDict) {
+    let node = pageDict;
+    for (let depth = 0; node && depth < 64; depth++) {
+        const res = getDict(ctx, node, 'Resources');
+        if (res)
+            return res;
+        node = getDict(ctx, node, 'Parent');
+    }
+    return undefined;
+}
+/** Inherited page attribute (MediaBox, CropBox, Rotate). */
+export function inheritedPageValue(ctx, pageDict, key) {
+    let node = pageDict;
+    for (let depth = 0; node && depth < 64; depth++) {
+        const v = resolve(ctx, node.get(PDFName.of(key)));
+        if (v)
+            return v;
+        node = getDict(ctx, node, 'Parent');
+    }
+    return undefined;
+}

package/dist/pdf/oracle.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @doccloak/core/pdf - pdf.js oracle (T212).
+ *
+ * pdf.js is the INDEPENDENT second extractor. It never edits anything; it is
+ * used (1) before a page is touched, to confirm that our own decoder read the
+ * same text pdf.js reads, (2) after writing, to verify that no redacted value
+ * is extractable from the output, and (3) to render pages for the rasterize
+ * fallback (see raster.ts).
+ *
+ * Runtime configuration:
+ * - The legacy build (`pdfjs-dist/legacy/build/pdf.mjs`) is imported lazily in
+ *   every environment: it carries the Node factories (fs-backed asset fetch,
+ *   `@napi-rs/canvas` canvas factory) as well as the browser ones and is the
+ *   build the package's typings describe. It is loaded on first use so hosts
+ *   that never open a PDF never pay for it.
+ * - Node: no worker; pdf.js runs its "fake worker" on the calling thread.
+ *   `cMapUrl` / `standardFontDataUrl` are file-system paths (or file: URLs).
+ * - Browsers: the host serves the worker file and passes its URL through
+ *   `PdfAssetPaths.pdfjsWorkerUrl`; it is applied to
+ *   `GlobalWorkerOptions.workerSrc` once. Without it pdf.js throws
+ *   'No "GlobalWorkerOptions.workerSrc" specified.' in a browser.
+ * - Fonts are never taken from the system (`useSystemFonts: false`). pdf.js 6
+ *   no longer has an eval-based PostScript compiler (`isEvalSupported` is gone).
+ * - `disableFontFace` is true wherever there is no `document` (Node, Web
+ *   Workers): glyphs are then drawn as paths, which also makes rendering
+ *   deterministic across hosts.
+ */
+import type { PdfAssetPaths } from './types.js';
+/** A 2D context as far as the raster code and pdf.js need it. */
+export type Canvas2D = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+/** A canvas created by a {@link CanvasFactory}: pdf.js draws on `context`, the raster code reads the result back. */
+export interface CanvasHandle {
+    /** The canvas object itself (HTMLCanvasElement, OffscreenCanvas, @napi-rs/canvas Canvas, or a test double). pdf.js calls `getContext('2d')` on it. */
+    canvas: unknown;
+    /** The 2D context of `canvas`. */
+    context: Canvas2D;
+    /** Encode the current pixels as PNG. */
+    toPng(): Promise<Uint8Array>;
+    /** RGBA pixels of the whole canvas, row-major, 4 bytes per pixel. */
+    getImageData(): Uint8ClampedArray;
+}
+/**
+ * Creates canvases for pdf.js. The default implementation uses OffscreenCanvas
+ * (browsers, main thread or worker) and falls back to a DOM canvas; Node
+ * hosts and tests inject their own (e.g. one built on `@napi-rs/canvas`).
+ * pdf.js also asks the factory for temporary canvases (patterns, transparency
+ * groups, smoothed images), so `create` may be called several times per page.
+ */
+export interface CanvasFactory {
+    create(width: number, height: number): CanvasHandle;
+}
+/** Result of {@link OracleDocument.render}. */
+export interface RenderedPage {
+    /** Canvas pixel size (the viewport size rounded up). */
+    widthPx: number;
+    heightPx: number;
+    /** Page size in points as displayed, i.e. the CropBox with /Rotate applied (swapped for 90/270). */
+    widthPt: number;
+    heightPt: number;
+    /** pdf.js `viewport.transform` [a b c d e f]: maps PDF user space to canvas pixels (includes the y flip, scale and /Rotate). */
+    transform: number[];
+    /** The canvas pdf.js drew on; still open for further drawing (the raster fallback paints its black boxes here). */
+    canvas: CanvasHandle;
+}
+/** One pdf.js text item with its geometry (see pdf.js TextItem). */
+export interface OracleTextItem {
+    str: string;
+    /** pdf.js bidi direction of the item ('ltr', 'rtl' or 'ttb'); `str` of an 'rtl' item is in visual order. */
+    dir?: string;
+    /** [a b c d e f]: text-space to user-space; (e, f) is the item origin, hypot(c, d) the font size. */
+    transform: number[];
+    /** Width and height in user-space units. */
+    width: number;
+    height: number;
+    hasEOL: boolean;
+    fontName: string;
+}
+export interface OracleDocument {
+    pageCount: number;
+    /** Raw pdf.js text items of the page joined in order, with '\n' appended after items flagged `hasEOL`. No normalisation: compare through {@link normalizeForCompare}. */
+    pageText(index: number): Promise<string>;
+    /** The pdf.js text items of the page with geometry (for raster-only pages). */
+    pageItems(index: number): Promise<OracleTextItem[]>;
+    /** Unrotated page box in points (pdf.js `view`, i.e. the CropBox clipped to the MediaBox) and the normalised /Rotate (0, 90, 180, 270). */
+    pageSize(index: number): Promise<{
+        width: number;
+        height: number;
+        rotate: number;
+    }>;
+    /** Render the page at `scale` (1 = 72 dpi) with /Rotate applied, annotations excluded. */
+    render(index: number, scale: number, canvasFactory?: CanvasFactory): Promise<RenderedPage>;
+    close(): Promise<void>;
+}
+/** Deadline for one pdf.js page operation (text, render). */
+export declare const ORACLE_DEADLINE_MS = 60000;
+/**
+ * Browser default: OffscreenCanvas when available (works in Web Workers and
+ * on the main thread), else an HTMLCanvasElement. Node has neither: inject a
+ * factory (tests use a recording double; hosts can wrap `@napi-rs/canvas`).
+ */
+export declare function defaultCanvasFactory(): CanvasFactory;
+/**
+ * Open `bytes` with pdf.js. The buffer is copied because pdf.js transfers
+ * (and thereby neuters) the ArrayBuffer it is given. Password-protected files
+ * without the right password raise UnsupportedDocumentError('encrypted');
+ * files pdf.js cannot parse at all raise 'invalid-package'.
+ */
+export declare function openWithOracle(bytes: Uint8Array, assets?: PdfAssetPaths, password?: string): Promise<OracleDocument>;
+/** Text of every page, in page order (see {@link OracleDocument.pageText}). */
+export declare function oracleText(doc: OracleDocument): Promise<string[]>;
+/**
+ * Bring two extractors' output onto common ground: NFC, typographic
+ * ligatures spelled out, and every whitespace / soft-hyphen / zero-width
+ * character removed. Case and punctuation are kept.
+ */
+export declare function normalizeForCompare(text: string): string;
+/**
+ * The text of a glyph as a detector should see it: typographic ligatures spelled out
+ * (fi -> fi) and CJK compatibility forms unified. Applied when glyphs are decoded, so plainText,
+ * the oracle comparison and the layer-zero search all agree.
+ */
+export declare function foldGlyphText(text: string): string;
+/**
+ * The same folding as {@link normalizeForCompare} plus a length-preserving
+ * lower-casing, with an offset map back into the input, so a search in the
+ * folded text can be turned into a replacement range of the original. Used
+ * by the writer's layer zero so that it covers exactly what the verifier
+ * would flag (a value wrapped over a line end, spaced differently, or
+ * written with a typographic ligature).
+ */
+export declare function foldForSearch(text: string): {
+    folded: string;
+    offsets: number[];
+};
+/**
+ * Every occurrence of `value` in `text` as [start, end) ranges of the original text, found in
+ * the search fold (whitespace, hyphens and zero-width characters dropped, ligatures spelled
+ * out, case folded). A value that begins or ends with a letter or digit must begin or end at a
+ * token boundary of the original text ("Nowak" is not found inside "Nowakowski", but is found
+ * in "Nowak," and across a line end); a value like "(c)" needs no boundary.
+ */
+export interface SearchIndex {
+    text: string;
+    folded: string;
+    offsets: number[];
+}
+/** The search fold of a text, reusable across many values (folding a long text once). */
+export declare function searchIndex(text: string): SearchIndex;
+export declare function findOccurrences(source: string | SearchIndex, value: string): Array<[number, number]>;