@cairn-tool/cairn 3.1.0 → 3.3.0

package/dist/pdf/attachments.js

@@ -0,0 +1,229 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { binaryKind } from "../binary-kind.js";
+import { writeAtomically } from "../atomic-write.js";
+import { CODES, DiagnosticSink } from "./diagnostics.js";
+/**
+ * Embedded files: inventory, and extraction under `--extract`.
+ *
+ * Two rules shape the module, and both are security properties rather than
+ * conveniences.
+ *
+ * **Binary never reaches stdout.** `--extract` is the only way bytes leave this
+ * command. A command that emits UTF-8 under one flag and a binary blob under
+ * another is a contract no consumer can code against.
+ *
+ * **Extraction is planned before anything is written.** An embedded file's
+ * stored name is attacker-controlled and will contain `../` eventually. Every
+ * destination is resolved and checked over the whole set first, so a single
+ * refused path means nothing is written at all — the same plan-then-write shape
+ * `src/agent/install` uses, and deliberately not `archive extract`, which
+ * sanitizes with `path.basename` alone and has no collision handling.
+ *
+ * pdf.js already strips the path — a `/F` of `../../etc/evil.csv` arrives as
+ * `filename: "evil.csv"` with `rawFilename` preserved. That is not treated as
+ * sufficient. The sanitization here is this command's own, and the payload
+ * reports both names so a caller can see what was renamed.
+ */
+/**
+ * Total decoded attachment bytes an inventory will hold at once.
+ *
+ * The inventory fetches content because size and SHA-256 are what make it
+ * actionable, and the document is already resident so a fetch is decompression
+ * rather than I/O. The cap bounds a document that claims a thousand large
+ * embedded files, and it reports rather than truncating silently.
+ */
+export const MAX_ATTACHMENT_BYTES = 128 * 1024 * 1024;
+/** A name is refused outright rather than repaired into something surprising. */
+const RESERVED = new Set([".", "..", ""]);
+/**
+ * Windows device names, which are not writable files on that platform whatever
+ * extension follows. Refused on every platform so an extraction behaves the same
+ * everywhere rather than only failing on the host that happens to care.
+ */
+const DEVICE = /^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)/i;
+/**
+ * The basename this command is willing to write, or null when there is none.
+ *
+ * Deliberately stricter than "strip the directory": a name that still carries a
+ * separator, a NUL, or a drive letter after basename is a name whose author was
+ * trying something, and guessing at their intent is how a traversal gets through.
+ */
+export function sanitizeName(candidate) {
+    const trimmed = candidate.replace(/\0/g, "").trim();
+    if (RESERVED.has(trimmed))
+        return null;
+    // Both separators, because a Windows-authored name reaching a POSIX host keeps
+    // its backslashes and `path.basename` here would not treat them as separators.
+    const base = trimmed.split(/[/\\]/).pop() ?? "";
+    if (RESERVED.has(base))
+        return null;
+    if (/^[A-Za-z]:/.test(base))
+        return null;
+    if (DEVICE.test(base))
+        return null;
+    // Anything left is a plain file name, `.gitignore` included: a leading dot is
+    // a real name, and `.` and `..` were already refused above.
+    return base || null;
+}
+/** `name-2.csv`, `name-3.csv`, … — never an overwrite. */
+function disambiguate(name, taken, directory) {
+    const extension = path.extname(name);
+    const stem = name.slice(0, name.length - extension.length);
+    let candidate = name;
+    let counter = 2;
+    while (taken.has(candidate.toLowerCase()) || fs.existsSync(path.join(directory, candidate))) {
+        candidate = `${stem}-${counter}${extension}`;
+        counter += 1;
+    }
+    return candidate;
+}
+export async function readAttachments(handle, options = {}) {
+    const sink = new DiagnosticSink();
+    const entries = await handle.within(() => handle.doc.getAttachments());
+    if (!entries || entries.size === 0)
+        return { attachments: [], diagnostics: sink.all() };
+    const keys = [...entries.keys()].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const attachments = [];
+    const contents = new Map();
+    let budget = 0;
+    for (const id of keys) {
+        const entry = entries.get(id) ?? {};
+        const rawFilename = entry.rawFilename ?? entry.filename ?? id;
+        const filename = entry.filename ?? id;
+        const attachment = {
+            id,
+            filename,
+            rawFilename,
+            ...(entry.description ? { description: entry.description } : {}),
+        };
+        if (budget >= MAX_ATTACHMENT_BYTES) {
+            sink.add({
+                code: CODES.attachmentBudgetReached,
+                quality: "approximate",
+                construct: filename,
+                message: `Attachment budget of ${MAX_ATTACHMENT_BYTES} bytes reached; '${filename}' was listed without size or hash`,
+                remediation: "Extract the earlier attachments first, or read the document in parts.",
+            });
+            attachments.push(attachment);
+            continue;
+        }
+        let content;
+        try {
+            content = await handle.within(() => handle.doc.getAttachmentContent(id));
+        }
+        catch {
+            content = null;
+        }
+        if (!content) {
+            sink.add({
+                code: CODES.attachmentUnreadable,
+                quality: "approximate",
+                construct: filename,
+                message: `Attachment '${filename}' could not be decoded; it is listed without size or hash`,
+            });
+            attachments.push(attachment);
+            continue;
+        }
+        const buffer = Buffer.from(content.buffer, content.byteOffset, content.byteLength);
+        budget += buffer.byteLength;
+        attachment.bytes = buffer.byteLength;
+        attachment.sha256 = crypto.createHash("sha256").update(buffer).digest("hex");
+        const kind = binaryKind(buffer);
+        if (kind)
+            attachment.binary = kind;
+        contents.set(id, content);
+        attachments.push(attachment);
+    }
+    if (!options.extract)
+        return { attachments, diagnostics: sink.all() };
+    // ---- Planning. Nothing below this line writes until every entry is resolved.
+    const directory = path.resolve(options.extract);
+    const real = fs.existsSync(directory) ? fs.realpathSync(directory) : directory;
+    if (fs.existsSync(real) && !fs.statSync(real).isDirectory())
+        throw new Error(`--extract is not a directory: ${options.extract}`);
+    const taken = new Set();
+    const plan = [];
+    let refused = false;
+    for (const attachment of attachments) {
+        const content = contents.get(attachment.id);
+        if (!content)
+            continue;
+        const safe = sanitizeName(attachment.filename) ?? sanitizeName(attachment.rawFilename);
+        if (!safe) {
+            sink.add({
+                code: CODES.attachmentPathRefused,
+                severity: "error",
+                quality: "unsupported",
+                construct: attachment.rawFilename,
+                message: `Attachment '${attachment.rawFilename}' has no name that can be safely written`,
+                remediation: "Nothing was extracted. Inspect the document before trusting its file names.",
+            });
+            refused = true;
+            continue;
+        }
+        if (safe !== attachment.rawFilename)
+            sink.add({
+                code: CODES.attachmentNameSanitized,
+                quality: "approximate",
+                construct: attachment.rawFilename,
+                message: `Stored name '${attachment.rawFilename}' was sanitized to '${safe}' before writing`,
+            });
+        const chosen = disambiguate(safe, taken, real);
+        if (chosen !== safe)
+            sink.add({
+                code: CODES.attachmentNameCollided,
+                quality: "exact",
+                construct: safe,
+                message: `'${safe}' already exists or was already claimed; written as '${chosen}'`,
+            });
+        const destination = path.resolve(real, chosen);
+        // Belt and braces: `chosen` carries no separator by construction, so this
+        // cannot fail — which is exactly why it is cheap to assert rather than trust.
+        const relative = path.relative(real, destination);
+        if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+            sink.add({
+                code: CODES.attachmentPathRefused,
+                severity: "error",
+                quality: "unsupported",
+                construct: chosen,
+                message: `Destination for '${chosen}' escapes ${options.extract}`,
+                remediation: "Nothing was extracted.",
+            });
+            refused = true;
+            continue;
+        }
+        taken.add(chosen.toLowerCase());
+        plan.push({ attachment, content, destination });
+    }
+    if (refused)
+        return { attachments, diagnostics: sink.all() };
+    // The collision check above ran during planning, so a file appearing in the
+    // target between then and now would still be replaced. That window is left
+    // open deliberately: closing it means either writing some files and refusing
+    // others — which breaks the all-or-nothing property that makes a refusal
+    // safe to act on — or holding the directory locked, which a local extraction
+    // tool has no business doing.
+    fs.mkdirSync(real, { recursive: true });
+    for (const item of plan) {
+        writeAtomically(item.destination, item.content);
+        item.attachment.written = item.destination;
+    }
+    return { attachments, diagnostics: sink.all() };
+}
+/** The human and llm rendering: one line per embedded file. */
+export function formatAttachments(attachments) {
+    if (attachments.length === 0)
+        return "no embedded files\n";
+    const width = Math.max(...attachments.map((item) => item.filename.length));
+    const lines = attachments.map((item) => {
+        const size = item.bytes === undefined ? "        ?" : String(item.bytes).padStart(9);
+        const hash = item.sha256 ? ` ${item.sha256.slice(0, 12)}` : " ".repeat(13);
+        const flags = [item.binary ?? "", item.written ? `-> ${item.written}` : ""].filter(Boolean);
+        const suffix = flags.length ? `  ${flags.join("  ")}` : "";
+        return `${size}${hash}  ${item.filename.padEnd(width)}${suffix}`;
+    });
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=attachments.js.map

package/dist/pdf/attachments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.js","sourceRoot":"","sources":["../../src/pdf/attachments.ts"],"names":[],"mappings":"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"}

package/dist/pdf/diagnostics.d.ts

@@ -0,0 +1,110 @@
+import type { MappingQuality, PdfDiagnostic } from "./types.js";
+/**
+ * Every `AP###` code, grouped by where the condition is detected.
+ *
+ * The range follows the detection site, never the command the user typed — the
+ * same rule the `AB` and `AD` families follow, which is why `AP020` is emitted
+ * by both `pdf text` and `pdf validate`. A retired code is never reused: a
+ * consumer may still be suppressing it.
+ *
+ * `tests/unit/diagnostic-codes.test.ts` fails on a code emitted here that
+ * `docs/formats/diagnostic-codes.md` does not document, *and* on a documented
+ * code nothing emits. Add both halves in the same change.
+ */
+export declare const CODES: {
+    readonly failure: "AP001";
+    readonly notAPdf: "AP002";
+    readonly tooLarge: "AP003";
+    readonly notRegularFile: "AP004";
+    readonly timedOut: "AP005";
+    readonly emptyInput: "AP006";
+    readonly leadingBytesIgnored: "AP007";
+    readonly passwordRequired: "AP010";
+    readonly passwordIncorrect: "AP011";
+    readonly tooManyPages: "AP012";
+    readonly pageRangeInvalid: "AP013";
+    readonly pageUnreadable: "AP020";
+    readonly contentUndecodable: "AP021";
+    readonly noTextLayer: "AP050";
+    readonly destinationUnresolved: "AP080";
+    readonly outlineTooDeep: "AP081";
+    readonly unparseable: "AP100";
+    readonly xrefReconstructed: "AP101";
+    readonly fontSubstituted: "AP110";
+    readonly filterUnsupported: "AP111";
+    readonly metadataUnreadable: "AP112";
+    readonly encryptedOpenPassword: "AP113";
+    readonly taggedButEmpty: "AP114";
+    readonly structPartial: "AP115";
+    readonly parserWarning: "AP120";
+    readonly conversionPath: "AP200";
+    readonly readingOrderUncertain: "AP201";
+    readonly tableFlattened: "AP202";
+    readonly rotatedTextDropped: "AP203";
+    readonly artifactsRemoved: "AP205";
+    readonly paragraphSpansPages: "AP206";
+    readonly pageSubsetConverted: "AP208";
+    readonly columnsDetected: "AP210";
+    readonly headingLevelsCollapsed: "AP211";
+    readonly listNumberingLost: "AP213";
+    readonly hyphenationRejoined: "AP214";
+    readonly figureTextOnly: "AP216";
+    readonly unknownRole: "AP219";
+    readonly cellSpanDropped: "AP220";
+    readonly headingLevelInferred: "AP224";
+    readonly listOrderingInferred: "AP225";
+    readonly inlineStyleInferred: "AP230";
+    readonly ligaturesExpanded: "AP231";
+    readonly controlCharactersStripped: "AP232";
+    readonly attachmentUnreadable: "AP300";
+    readonly attachmentNameSanitized: "AP301";
+    readonly attachmentNameCollided: "AP302";
+    readonly attachmentPathRefused: "AP303";
+    readonly attachmentBudgetReached: "AP304";
+    readonly formXfa: "AP311";
+    readonly formFieldPageUnresolved: "AP312";
+};
+export interface DiagnosticInput {
+    code: string;
+    message: string;
+    quality: MappingQuality;
+    page?: number;
+    construct?: string;
+    remediation?: string;
+    /** Overrides the quality-derived severity. Use only to refuse. */
+    severity?: DiagnosticSeverityOverride;
+}
+type DiagnosticSeverityOverride = PdfDiagnostic["severity"];
+/**
+ * Builds a finding, deriving severity from quality unless overridden.
+ *
+ * Optional fields are spread conditionally so an absent one never serializes as
+ * `undefined` — the payload is published and a null-ish key is a contract
+ * change nobody meant to make.
+ */
+export declare function diagnostic(input: DiagnosticInput): PdfDiagnostic;
+/**
+ * Collects findings, deduplicating and ordering them.
+ *
+ * Deliberately a copy of `src/jira/adf/diagnostics.ts`'s sink rather than a
+ * shared generic. The two differ in the one place that matters: this one orders
+ * by *numeric* page before the construct, because a bytewise sort puts page 10
+ * before page 2 and a reader scanning a 300-page document's findings would be
+ * reading them out of order. Parameterizing a shared sink on a key function and
+ * a comparator is more type noise than the twenty-five duplicated lines remove.
+ */
+export declare class DiagnosticSink {
+    private readonly items;
+    private readonly seen;
+    add(input: DiagnosticInput): void;
+    get length(): number;
+    /**
+     * A copy, ordered by code, then page, then construct.
+     *
+     * The construct comparison is byte comparison, never `localeCompare`: that is
+     * ICU-build and locale dependent, so a differently configured CI runner would
+     * reorder the payload.
+     */
+    all(): PdfDiagnostic[];
+}
+export {};

package/dist/pdf/diagnostics.js

@@ -0,0 +1,137 @@
+import { severityFor } from "../mapping-quality.js";
+/**
+ * Every `AP###` code, grouped by where the condition is detected.
+ *
+ * The range follows the detection site, never the command the user typed — the
+ * same rule the `AB` and `AD` families follow, which is why `AP020` is emitted
+ * by both `pdf text` and `pdf validate`. A retired code is never reused: a
+ * consumer may still be suppressing it.
+ *
+ * `tests/unit/diagnostic-codes.test.ts` fails on a code emitted here that
+ * `docs/formats/diagnostic-codes.md` does not document, *and* on a documented
+ * code nothing emits. Add both halves in the same change.
+ */
+export const CODES = {
+    // AP0xx  invocation, input bounds, and opening the document
+    failure: "AP001",
+    notAPdf: "AP002",
+    tooLarge: "AP003",
+    notRegularFile: "AP004",
+    timedOut: "AP005",
+    emptyInput: "AP006",
+    leadingBytesIgnored: "AP007",
+    passwordRequired: "AP010",
+    passwordIncorrect: "AP011",
+    tooManyPages: "AP012",
+    pageRangeInvalid: "AP013",
+    // AP02x  the page tree and per-page decoding
+    pageUnreadable: "AP020",
+    contentUndecodable: "AP021",
+    // AP05x  the text layer
+    noTextLayer: "AP050",
+    // AP08x  the outline
+    destinationUnresolved: "AP080",
+    outlineTooDeep: "AP081",
+    // AP1xx  structural integrity, reported by validate
+    unparseable: "AP100",
+    xrefReconstructed: "AP101",
+    fontSubstituted: "AP110",
+    filterUnsupported: "AP111",
+    metadataUnreadable: "AP112",
+    encryptedOpenPassword: "AP113",
+    taggedButEmpty: "AP114",
+    structPartial: "AP115",
+    parserWarning: "AP120",
+    // AP2xx  conversion to Markdown
+    conversionPath: "AP200",
+    readingOrderUncertain: "AP201",
+    tableFlattened: "AP202",
+    rotatedTextDropped: "AP203",
+    artifactsRemoved: "AP205",
+    paragraphSpansPages: "AP206",
+    pageSubsetConverted: "AP208",
+    columnsDetected: "AP210",
+    headingLevelsCollapsed: "AP211",
+    listNumberingLost: "AP213",
+    hyphenationRejoined: "AP214",
+    figureTextOnly: "AP216",
+    unknownRole: "AP219",
+    cellSpanDropped: "AP220",
+    headingLevelInferred: "AP224",
+    listOrderingInferred: "AP225",
+    inlineStyleInferred: "AP230",
+    ligaturesExpanded: "AP231",
+    controlCharactersStripped: "AP232",
+    // AP3xx  embedded files and form fields
+    attachmentUnreadable: "AP300",
+    attachmentNameSanitized: "AP301",
+    attachmentNameCollided: "AP302",
+    attachmentPathRefused: "AP303",
+    attachmentBudgetReached: "AP304",
+    formXfa: "AP311",
+    formFieldPageUnresolved: "AP312",
+};
+/**
+ * Builds a finding, deriving severity from quality unless overridden.
+ *
+ * Optional fields are spread conditionally so an absent one never serializes as
+ * `undefined` — the payload is published and a null-ish key is a contract
+ * change nobody meant to make.
+ */
+export function diagnostic(input) {
+    const { code, message, quality, severity, page, construct, remediation } = input;
+    return {
+        code,
+        severity: severity ?? severityFor(quality),
+        message,
+        quality,
+        ...(page !== undefined ? { page } : {}),
+        ...(construct ? { construct } : {}),
+        ...(remediation ? { remediation } : {}),
+    };
+}
+/**
+ * Collects findings, deduplicating and ordering them.
+ *
+ * Deliberately a copy of `src/jira/adf/diagnostics.ts`'s sink rather than a
+ * shared generic. The two differ in the one place that matters: this one orders
+ * by *numeric* page before the construct, because a bytewise sort puts page 10
+ * before page 2 and a reader scanning a 300-page document's findings would be
+ * reading them out of order. Parameterizing a shared sink on a key function and
+ * a comparator is more type noise than the twenty-five duplicated lines remove.
+ */
+export class DiagnosticSink {
+    items = [];
+    seen = new Set();
+    add(input) {
+        const key = `${input.code} ${input.construct ?? ""} ${input.page ?? ""}`;
+        if (this.seen.has(key))
+            return;
+        this.seen.add(key);
+        this.items.push(diagnostic(input));
+    }
+    get length() {
+        return this.items.length;
+    }
+    /**
+     * A copy, ordered by code, then page, then construct.
+     *
+     * The construct comparison is byte comparison, never `localeCompare`: that is
+     * ICU-build and locale dependent, so a differently configured CI runner would
+     * reorder the payload.
+     */
+    all() {
+        return [...this.items].sort((a, b) => {
+            if (a.code !== b.code)
+                return a.code < b.code ? -1 : 1;
+            const pageA = a.page ?? 0;
+            const pageB = b.page ?? 0;
+            if (pageA !== pageB)
+                return pageA - pageB;
+            const left = a.construct ?? "";
+            const right = b.construct ?? "";
+            return left < right ? -1 : left > right ? 1 : 0;
+        });
+    }
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/pdf/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/pdf/diagnostics.ts"],"names":[],"mappings":"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"}

package/dist/pdf/document.d.ts

@@ -0,0 +1,159 @@
+import type { PdfDiagnostic } from "./types.js";
+/**
+ * The single place a PDF is opened.
+ *
+ * Everything hostile about the format is contained here: one hardened option
+ * set, one console capture, one deadline, one teardown, and one place a pdf.js
+ * exception becomes an `AP###`. Every other module in `src/pdf` receives an
+ * already-open handle and never imports pdfjs itself.
+ */
+/**
+ * The minimum of pdf.js this project uses, written out by hand.
+ *
+ * Same discipline as `src/sqlite.ts`: `tsconfig` sets `declaration: true`, so a
+ * pdfjs type appearing in an exported signature would put that package's types
+ * into cairn's published `.d.ts`. pdfjs's own definitions are also JSDoc-derived
+ * and `any`-heavy, which would leak straight through.
+ */
+export interface PdfTextItem {
+    str?: string;
+    dir?: string;
+    transform?: number[];
+    width?: number;
+    height?: number;
+    fontName?: string;
+    hasEOL?: boolean;
+    /** Marked-content items carry these two instead. */
+    type?: string;
+    id?: string;
+}
+export interface PdfTextStyle {
+    fontFamily?: string;
+    ascent?: number;
+    descent?: number;
+    vertical?: boolean;
+}
+export interface PdfStructNode {
+    role?: string;
+    type?: string;
+    id?: string;
+    children?: PdfStructNode[];
+}
+export interface PdfViewport {
+    width: number;
+    height: number;
+    rotation: number;
+    convertToViewportPoint(x: number, y: number): number[];
+}
+export interface PdfPageHandle {
+    getViewport(params: {
+        scale: number;
+    }): PdfViewport;
+    getTextContent(params?: {
+        includeMarkedContent?: boolean;
+    }): Promise<{
+        items: PdfTextItem[];
+        styles: Record<string, PdfTextStyle>;
+    }>;
+    getStructTree(): Promise<PdfStructNode | null>;
+    getXfa(): Promise<unknown>;
+    cleanup(): boolean;
+}
+/**
+ * One embedded file, as `getAttachments()` describes it.
+ *
+ * `content` is declared optional because pdf.js does not populate it: the
+ * lookup is metadata only and the bytes come from `getAttachmentContent`. That
+ * is what makes `pdf attachments`'s inventory cheap and its extraction the
+ * opt-in.
+ */
+export interface PdfAttachmentEntry {
+    /** Basename pdf.js derived from the file spec. Already path-stripped. */
+    filename?: string;
+    /** The stored name verbatim, traversal and all. */
+    rawFilename?: string;
+    description?: string;
+    content?: Uint8Array;
+}
+export interface PdfPageHandleExtras {
+    getXfa(): Promise<unknown>;
+}
+export interface PdfDocumentHandle {
+    numPages: number;
+    getPage(page: number): Promise<PdfPageHandle>;
+    getMetadata(): Promise<{
+        info?: Record<string, unknown>;
+        metadata?: unknown;
+    }>;
+    getOutline(): Promise<any[] | null>;
+    getDestination(id: string): Promise<any[] | null>;
+    getPageIndex(ref: unknown): Promise<number>;
+    getMarkInfo(): Promise<unknown>;
+    getPermissions(): Promise<Set<number> | null>;
+    /**
+     * A `Map`, like `getMarkInfo`, `getFieldObjects`, and `getJSActions` — never a
+     * plain object. `Object.entries()` on any of the four silently yields nothing.
+     */
+    getAttachments(): Promise<Map<string, PdfAttachmentEntry> | null>;
+    /** Bytes for one attachment, keyed by its `getAttachments()` map key. */
+    getAttachmentContent(id: string): Promise<Uint8Array | null>;
+    /** A `Map` keyed by fully-qualified field name; each value is one array of widgets. */
+    getFieldObjects(): Promise<Map<string, unknown[]> | null>;
+    /** True when the form is XFA-only, so `getFieldObjects` has nothing to report. */
+    isPureXfa: boolean;
+    cleanup(): Promise<unknown>;
+}
+/** What every command works against. */
+export interface OpenDocument {
+    doc: PdfDocumentHandle;
+    /** Warnings pdf.js emitted while this document was open, in emission order. */
+    notices: readonly string[];
+    /** True when a password was supplied and accepted, or none was needed. */
+    encrypted: boolean;
+    /** Races a pdfjs promise against the deadline. */
+    within<T>(work: () => Promise<T>): Promise<T>;
+}
+export interface OpenOptions {
+    /** Wall-clock budget in milliseconds for the whole operation. */
+    timeoutMs: number;
+    /** Refuse a document with more pages than this before touching any of them. */
+    maxPages: number;
+}
+/** Raised when the wall-clock budget expires. Classified as `AP005`. */
+export declare class DeadlineExceeded extends Error {
+    readonly ms: number;
+    constructor(ms: number);
+}
+/** Raised when the install is broken, rather than the document. */
+export declare class PdfjsUnavailableError extends Error {
+    constructor(cause: string);
+}
+/**
+ * Opens a document, runs `body`, and tears down — in that order, always.
+ *
+ * A scoped-resource function rather than an open/close pair so a caller cannot
+ * forget the teardown. On 6.3.289 pdf.js uses the main-thread fake worker in
+ * Node (no worker thread is spawned, verified), so a leaked handle does not hang
+ * the process — but `destroy()` still releases the parsed object graph, and a
+ * future version spawning a real worker would make it load-bearing.
+ */
+export declare function withDocument<T>(data: Uint8Array, options: OpenOptions, body: (handle: OpenDocument) => Promise<T>): Promise<T>;
+/** Raised before any page is touched, when the document is larger than allowed. */
+export declare class PageBudgetExceeded extends Error {
+    readonly pages: number;
+    readonly limit: number;
+    constructor(pages: number, limit: number);
+}
+/**
+ * Maps a thrown value onto a finding.
+ *
+ * Matched by class where pdf.js exports one, never by `error.name`: a name is a
+ * string that has drifted before, and the classes are exported precisely so a
+ * consumer can branch on them.
+ *
+ * The distinction between `AP002` and `AP100` is worth keeping: `AP002` means
+ * the bytes never had a `%PDF-` header, decided by `read.ts` before pdf.js ran,
+ * and `AP100` means it looked like a PDF and could not be parsed. That is the
+ * difference between "wrong file" and "damaged file".
+ */
+export declare function classify(error: unknown, page?: number): Promise<PdfDiagnostic>;