@patrickdk77/pdf-defuse 0.0.0-stage → 0.1.0

package/dist/document.d.ts

@@ -0,0 +1,191 @@
+import { type OpenResult, SecurityHandler } from './crypto';
+import { Reader, TempDir } from './io';
+import { PdfDict, type PdfObject, PdfRef, PdfStream } from './objects';
+import type { ByteSource } from './types';
+type XrefEntry = {
+    type: 1;
+    offset: number;
+    gen: number;
+} | {
+    type: 2;
+    stream: number;
+};
+/** Entries are packed into one number each, so the index costs a few bytes per object. */
+export declare const packOffset: (offset: number, gen: number) => number;
+export declare const packStream: (stream: number) => number;
+export declare function unpack(v: number | undefined): XrefEntry | undefined;
+export declare class OpenError extends Error {
+    readonly kind: 'unparseable' | 'truncated' | 'not-pdf';
+    constructor(kind: 'unparseable' | 'truncated' | 'not-pdf', message: string);
+}
+/** Past the deadline. The code makes every package of the family pass it up to the top. */
+export declare class TimeLimitError extends Error {
+    readonly code = "DEFUSE_LIMIT";
+    readonly limit = "time";
+}
+export declare class ObjectLimitError extends Error {
+}
+interface DocumentIssues {
+    escapedNames: Set<string>;
+    streamLengthWrong: number;
+    malformed: number;
+    /** An object whose header generation differs from its xref entry. */
+    genMismatch: number;
+    /** An xref entry that does not point at its object. */
+    badOffsets: number;
+    /** Dictionaries that repeat a key. */
+    duplicateKeys: Set<string>;
+    /** Object definitions in older revisions that a newer revision replaced or freed. */
+    superseded: number;
+    /** References to object streams or xref streams as if they were ordinary objects. */
+    structuralRefs: number;
+    /** /XRefStm entries that lead to no xref stream. qpdf and the readers built on it then rebuild the map by scanning. */
+    badXRefStm: number;
+    /** Rows /XRefStm gives for numbers its own table marks free. pdf.js keeps the free row and qpdf takes the stream's. */
+    xrefStmOverFree: number;
+    /** Object streams whose header pdf.js refuses, offsets that do not increase or numbers that are not whole. */
+    badObjStm: Set<number>;
+    /** Objects referenced with a generation their entry does not have, which pdf.js refuses to resolve. */
+    refGen: Set<number>;
+    /** Parts held in a temporary file instead of memory. */
+    memoryFallback: string[];
+}
+interface OpenOptions {
+    password?: string;
+    decompressedBytes?: number;
+    objectLimit?: number;
+    deadline?: number;
+    temp?: TempDir;
+    memoryThreshold?: number;
+}
+/** A PDF opened for random access. Objects are read on demand and never all held at once. */
+export declare class PdfDocument {
+    readonly reader: Reader;
+    readonly size: number;
+    private readonly opts;
+    headerOffset: number;
+    headerVersion: string;
+    /** Added to every offset when the file has bytes before its header and the xref ignores them. */
+    private base;
+    /** Object number to packed entry. */
+    readonly xref: Map<number, number>;
+    trailer: PdfDict;
+    sections: number;
+    rebuilt: boolean;
+    hasEof: boolean;
+    trailingBytes: number;
+    security?: SecurityHandler;
+    securityResult?: OpenResult;
+    encryptRef?: PdfRef;
+    readonly issues: DocumentIssues;
+    /** Body offsets of the streams already counted in issues.streamLengthWrong, so a second read adds nothing. */
+    private readonly lengthWrongAt;
+    private objCache;
+    private objStmCache;
+    /** Object streams that spilled to a temporary file. Kept for the life of the document, so each is decoded once. */
+    private readonly spilledObjStm;
+    /** Object streams found by scan(), indexed once the key exists. */
+    private pendingObjStm;
+    /** Streams whose indirect /Length or filter entries are being resolved, so a cycle ends after one lap. */
+    private readonly lengthResolving;
+    /**
+     * Stream number to the objects its filter entries name. Their values are copied into the stream, so the objects
+     * are referenced when the walk visits the stream, though it never visits them.
+     */
+    readonly filterRefs: Map<number, number[]>;
+    /** Objects read for the Encrypt dictionary, which the walk never visits. */
+    readonly encryptRefs: Set<number>;
+    /** Set while a lookup must leave the issues as they are. */
+    private quiet;
+    private readonly hooks;
+    /** Where the objects whose bad tokens are already in issues.malformed were read, so a second read adds nothing. */
+    private readonly badTokensCounted;
+    private scanned;
+    /** Offsets of the xref sections and xref streams that read, which are not ordinary object definitions. */
+    readonly structuralOffsets: Set<number>;
+    /** The definitions that older xref sections use and newer ones replaced or freed, as object number then offset. */
+    private readonly supersededAt;
+    private sortedOffsets?;
+    /** Live uncompressed objects sorted by offset, for finding the object around a position. */
+    private liveByOffset?;
+    /** The extent of the live object insideLiveObject() read last, empty when it does not parse. */
+    private lastLive?;
+    private unboundedScanBudget;
+    /** Bytes parseWindowed() may still read past the next known object. */
+    private parseBudget;
+    private constructor();
+    static open(source: ByteSource, opts?: OpenOptions): Promise<PdfDocument>;
+    checkTime(): void;
+    private checkObjectLimit;
+    private init;
+    private initSecurity;
+    private loadXrefChain;
+    /** Reads one section; for hybrid files its XRefStm entries add the objects the table does not give. */
+    private readXrefSection;
+    private readXrefTable;
+    /** `at` is where the stream's object header starts, which can be past whitespace at `offset`. */
+    private readXrefStream;
+    /** Rebuilds the object map by scanning every byte. Used when the xref is missing or wrong. */
+    private scan;
+    /** Adds the objects held in the object streams scan() found. Their bodies may be encrypted, so this runs after initSecurity(). */
+    private indexObjStms;
+    /**
+     * Parses the indirect object ("N G obj ...") at a source offset. `at` is where its header starts, past any
+     * whitespace, and `end` where its value or its stream body ends.
+     */
+    private parseIndirectAt;
+    /** Finds a stream body's true length, trusting /Length only when "endstream" follows it. */
+    private locateStream;
+    /** Position just before the EOL that precedes "endstream" in [from, to), or -1. */
+    private findEndstream;
+    /** The smallest known object or xref offset after `pos`, or the end of the file. */
+    private nextOffsetAfter;
+    /** Loads an object by reference, decrypted. Missing and free objects are null. */
+    getObject(ref: PdfRef, raw?: boolean): Promise<PdfObject>;
+    private decryptObject;
+    private getFromObjStm;
+    /** Decodes an object stream in chunks; large ones go to a temporary file instead of memory. */
+    private loadObjStm;
+    private ownTemp?;
+    /**
+     * Parses at an offset in any reader, growing the window as needed. A window that reaches `bound`, the next known
+     * object, grows further only while a budget for the whole file lasts, so damaged files still parse and crafted
+     * ones stay linear. `key` names the place read, so its bad tokens count once however often it is parsed.
+     */
+    private parseWindowed;
+    resolve(v: PdfObject | undefined): Promise<PdfObject | undefined>;
+    /** The generation of a live object's entry, 0 for one in an object stream or none. */
+    genOf(num: number): number;
+    /** Length of the stream once decrypted, which is what gets written out. */
+    plainLength(stream: PdfStream, num: number): Promise<number>;
+    /** Yields the decrypted, still-encoded body in chunks. */
+    plainChunks(stream: PdfStream, num: number): AsyncGenerator<Uint8Array>;
+    /** Decrypts and decodes a whole stream body into memory, subject to the decompression limit and an optional cap. */
+    decode(stream: PdfStream, num: number, limit?: number | undefined, cap?: number): Promise<Uint8Array>;
+    /**
+     * Counts object definitions in the file body that no xref section uses. Reads the whole file once, in chunks.
+     * Definitions an older section uses are left to the superseded count. A header inside a live object counts only
+     * with `inLive`, since only a reader that rebuilds the map by scanning takes it.
+     */
+    countDeadDefinitions(inLive?: boolean): Promise<number>;
+    /**
+     * Yields every "N G obj" header in the file, with the byte before it or -1 at the start of the file, and where its
+     * "obj" ends. Each "obj" is read back to its two numbers. The whitespace inside a header can run to any length, as
+     * other readers allow, so the read back can reach into earlier chunks: chunks that overlap by a fixed amount miss
+     * such a header. `onChunk` sees each chunk once.
+     */
+    private objectHeaders;
+    /**
+     * True when [pos, end) lies inside a live object, from its header to the end of its value or stream body. An object
+     * header there is data, such as text quoted in a string or an uncompressed attached PDF, not a definition in this
+     * file. Parsing the object must not change the issue counts, which describe the walked document and are final by now.
+     */
+    private insideLiveObject;
+    /** Live object numbers, for the unreferenced-object count. */
+    liveNumbers(): IterableIterator<number>;
+    /** Drops caches and the object index once the document is no longer read, and deletes spilled object streams. */
+    release(): Promise<void>;
+    /** Forgets every decoded object stream, closing and deleting the ones that spilled to a temporary file. */
+    private dropObjStms;
+}
+export {};