@jasy/pdf 1.0.0-alpha.7 → 1.0.0-alpha.9

package/dist/edit/document.d.ts

@@ -0,0 +1,145 @@
+import { type PdfDict, type PdfObject, type PdfStream } from "./objects.js";
+declare const EMPTY: Uint8Array<ArrayBuffer>;
+/** What `PdfDocument.load` accepts. */
+export interface LoadOptions {
+    /** Ceiling on what ONE stream may inflate to, in bytes (default 64 MB). Raise it for a document that
+     *  is genuinely enormous; a stream past it throws `PdfStreamTooLargeError` rather than being read. */
+    maxStreamSize?: number;
+}
+/** What `PdfDocument.open` accepts - everything `load` takes, plus the password. */
+export interface OpenOptions extends LoadOptions {
+    password?: string;
+}
+/** Thrown when a file cannot be opened because of its encryption - always saying which of the reasons it
+ *  is: no password, wrong password, or a revision we do not implement. */
+export declare class PdfEncryptedError extends Error {
+    constructor(message: string);
+}
+export declare class PdfDocument {
+    readonly bytes: Uint8Array;
+    private readonly xref;
+    private readonly cache;
+    /** Object streams already unpacked, by their object number. */
+    private readonly objStmCache;
+    /** Set once an encrypted file has been opened with its password. */
+    private security?;
+    /** Decrypted stream payloads, keyed by the stream's data offset (unique per stream). */
+    private readonly plainStreams;
+    /** True when the cross-reference index was unusable and had to be rebuilt by scanning. Surfaced so
+     *  a caller can report it - a silently repaired file is exactly the kind of guess we avoid. */
+    recovered: boolean;
+    trailer: PdfDict;
+    /** Whether this file indexes itself with an xref STREAM rather than a classic table. An incremental
+     *  update has to follow suit: mixing the two leaves readers that understand only one kind unable to
+     *  walk the chain back. */
+    usesXrefStream: boolean;
+    /** Ceiling on what one stream may inflate to; see `inflate.ts`. */
+    private maxStreamSize;
+    private constructor();
+    static load(bytes: Uint8Array, opts?: LoadOptions): PdfDocument;
+    /**
+     * Open a document, decrypting it when it is password-protected.
+     *
+     * Async because key derivation and AES are (WebCrypto), and because decryption happens ONCE here,
+     * eagerly, rather than at every read: that keeps `getObject`, `streamData` and the whole form layer
+     * above them synchronous, which is the same trade the writer makes (`structure.ts` builds the handler
+     * before the synchronous constructor).
+     */
+    static open(bytes: Uint8Array, opts?: OpenOptions): Promise<PdfDocument>;
+    /**
+     * Build the handler for this file's `/Encrypt` dictionary, or say precisely why we cannot.
+     *
+     * Every refusal names its reason: no password given, wrong password, or an encryption revision we do
+     * not implement. "Cannot open this file" would be the unhelpful answer, and guessing would be worse.
+     */
+    private securityHandlerFor;
+    /**
+     * Which cipher and key length actually apply to the streams.
+     *
+     * For V4 the answer is NOT the top-level `/Length`: the document names a crypt filter in `/StmF` and
+     * that filter carries its own `/CFM` and `/Length` (in BYTES, where the top-level one is in bits).
+     * `/Identity` means the streams are not enciphered at all - decrypting them anyway would destroy them.
+     */
+    private streamCipher;
+    /**
+     * Decrypt every string and stream, once, in place.
+     *
+     * Three things are deliberately NOT decrypted, because they were never encrypted (ISO 32000-1 7.6.2):
+     * the `/Encrypt` dictionary's own strings, a cross-reference stream, and strings of objects that live
+     * inside an object stream - the object stream was enciphered as a whole, so its members come out in
+     * the clear already.
+     */
+    private decryptEverything;
+    /** The byte offset in the `startxref` trailer at the very end of the file. */
+    private findStartXref;
+    /** Read the index at `startxref`, then walk `/Prev` back through earlier revisions. Entries already
+     *  known win: the NEWEST revision is read first, and an older one must not overwrite it. */
+    private readXrefChain;
+    /** One index section, either format. Returns its trailer dictionary. */
+    private readXrefSection;
+    /** The classic table: `xref`, then `start count` subsections of 20-byte entries, then `trailer`. */
+    private readXrefTable;
+    /**
+     * An xref STREAM: fixed-width binary rows, widths in `/W`, object numbers from `/Index`. Row type 1
+     * is a plain byte offset, type 2 points into an object stream, type 0 is a free slot.
+     */
+    private readXrefStream;
+    /** Record an entry unless a NEWER revision already claimed that object number. */
+    private note;
+    /**
+     * Last resort: scan the whole file for `N G obj` headers and believe those. Used when the index is
+     * missing or does not lead anywhere - and flagged via `recovered`, never silently.
+     */
+    private rebuildByScanning;
+    /** The object with that number, or `undefined` when the file does not have it. */
+    getObject(num: number): PdfObject | undefined;
+    /** Parse `N G obj … endobj` at a byte offset, checking that it really is object `num`. */
+    private parseObjectAt;
+    /** Unpack an object stream once, then serve its members from the cache. */
+    private objectFromStream;
+    /** Follow indirect references until a direct object is reached. */
+    resolve(o: PdfObject | undefined): PdfObject | undefined;
+    /** A dictionary entry, with the reference already followed. */
+    lookup(o: PdfObject | undefined, key: string): PdfObject | undefined;
+    /**
+     * The file is password-protected. Every string and stream in it is enciphered, so anything read out
+     * of it is ciphertext until a decryption path exists - which is why the form layer refuses rather
+     * than handing back nonsense field names.
+     */
+    get isEncrypted(): boolean;
+    /** True once the password has been accepted and the contents decrypted, so what is read is plaintext.
+     *  Always true for a document that was never encrypted. */
+    get isReadable(): boolean;
+    /**
+     * Encipher a value that is about to be written back INTO this document, or `undefined` when the
+     * document is not encrypted and the value goes in as it is.
+     *
+     * Needed because we decrypt everything on open: a string we then hand back to the writer is plaintext
+     * in memory, and writing it into an encrypted file unchanged would both leak it and produce a document
+     * that contradicts its own /Encrypt declaration.
+     */
+    encryptForWrite(data: Uint8Array): Promise<Uint8Array | undefined>;
+    /**
+     * Whether values written back into this document can be enciphered again.
+     *
+     * False for a legacy-encrypted file: we can READ RC4 and AES-128, but writing one would downgrade the
+     * user's document to a broken cipher. Asked BEFORE any work is done - otherwise the refusal depends on
+     * a string happening to be present in whatever we rewrite, which is a guarantee by accident.
+     */
+    get canReEncrypt(): boolean;
+    /** The generation of an object as the file records it. Members of an object stream are always 0. */
+    generationOf(num: number): number;
+    get catalog(): PdfObject | undefined;
+    /** A stream's bytes as they sit in the file: sliced by `/Length`, still filtered and still encrypted. */
+    private rawStream;
+    /** A stream's DECODED bytes: deciphered if the document is encrypted, then run through its filters. */
+    streamData(stream: PdfStream): Uint8Array;
+    /**
+     * Undo a PNG predictor (`/Predictor` 10-15), which xref streams almost always use - the IRS form in
+     * our fixtures does. Each row is prefixed with its filter type and is decoded against the row above.
+     */
+    private undoPredictor;
+    /** Every object number the index knows, ascending - for walking a whole document. */
+    objectNumbers(): number[];
+}
+export { EMPTY };