@patrickdk77/pdf-defuse 0.0.0-stage → 0.1.0

package/dist/engine.d.ts

@@ -0,0 +1,16 @@
+import { type ByteSink, type ByteSource, type PdfDisarmResult, type PdfInspection, type PdfOptions } from './types';
+/** Inspects a PDF without changing it. The source is closed when the run ends. */
+export declare function inspectPdfSource(source: ByteSource, options?: PdfOptions): Promise<PdfInspection>;
+/**
+ * Writes a defused copy of `source` to `sink`. Nothing reaches the sink unless the output passes inspection. The
+ * source is closed when the run ends.
+ */
+export declare function disarmPdfSource(source: ByteSource, sink: ByteSink, options?: PdfOptions): Promise<PdfDisarmResult>;
+/** Internal entry that carries the nesting depth for attached PDFs, and the deadline they share with the upload. */
+export declare function disarmAtDepth(source: ByteSource, sink: ByteSink, options: PdfOptions, depth: number, deadline?: number | undefined): Promise<PdfDisarmResult>;
+/** Inspects PDF bytes. */
+export declare function inspectPdf(bytes: Uint8Array, options?: PdfOptions): Promise<PdfInspection>;
+/** Defuses PDF bytes. `bytes` holds the output unless the file was rejected. */
+export declare function disarmPdf(bytes: Uint8Array, options?: PdfOptions): Promise<PdfDisarmResult & {
+    bytes?: Uint8Array;
+}>;

package/dist/engine.js

@@ -0,0 +1,392 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inspectPdfSource = inspectPdfSource;
+exports.disarmPdfSource = disarmPdfSource;
+exports.disarmAtDepth = disarmAtDepth;
+exports.inspectPdf = inspectPdf;
+exports.disarmPdf = disarmPdf;
+const document_1 = require("./document");
+const filters_1 = require("./filters");
+const findings_1 = require("./findings");
+const io_1 = require("./io");
+const score_1 = require("./score");
+const types_1 = require("./types");
+const walker_1 = require("./walker");
+async function endRun(run) {
+    try {
+        await run.doc?.release();
+        await run.walker?.cleanup();
+    }
+    finally {
+        await run.temp.cleanup();
+    }
+}
+/** An error from the operating system, such as EIO or ENOSPC, which says nothing about the PDF. */
+const isIoError = (e) => typeof e?.code === 'string' && /^E[A-Z]+$/.test(e.code);
+function limitFinding(factory, e) {
+    if (e instanceof filters_1.DecompressionLimitError)
+        return factory.make(types_1.PdfCategory.Limit, types_1.PdfDetail.DecompressedSize);
+    if (e instanceof document_1.ObjectLimitError)
+        return factory.make(types_1.PdfCategory.Limit, types_1.PdfDetail.ObjectCount);
+    // A time or nesting limit from any package goes by its code.
+    if ((0, walker_1.stopsTree)(e) === 'DEFUSE_LIMIT')
+        return factory.make(types_1.PdfCategory.Limit, e.limit === 'nesting' ? types_1.PdfDetail.NestingDepth : types_1.PdfDetail.Time);
+    return undefined;
+}
+function encryptionFindings(doc, factory) {
+    const r = doc.securityResult;
+    if (!r)
+        return [];
+    const out = [];
+    if (r.status === 'ok') {
+        out.push(factory.make(types_1.PdfCategory.Encrypted, r.password === 'empty' ? types_1.PdfDetail.EmptyPassword : r.password === 'owner' ? types_1.PdfDetail.OwnerPassword : types_1.PdfDetail.UserPassword));
+        const bits = r.handler.keyBits;
+        const method = r.handler.streamMethod === 'Identity' ? r.handler.stringMethod : r.handler.streamMethod;
+        if (method === 'AES256')
+            out.push(factory.make(types_1.PdfCategory.Encrypted, types_1.PdfDetail.Aes256));
+        else if (method === 'AES128')
+            out.push(factory.make(types_1.PdfCategory.Encrypted, types_1.PdfDetail.Aes128));
+        else if (method === 'RC4')
+            out.push(factory.make(types_1.PdfCategory.Encrypted, bits === 40 ? types_1.PdfDetail.Rc4_40 : bits === 128 ? types_1.PdfDetail.Rc4_128 : types_1.PdfDetail.Rc4Other, undefined, bits === 40 || bits === 128 ? undefined : { bits }));
+        if (!r.handler.encryptMetadata)
+            out.push(factory.make(types_1.PdfCategory.Encrypted, types_1.PdfDetail.MetadataUnencrypted));
+    }
+    else if (r.status === 'password-required')
+        out.push(factory.make(types_1.PdfCategory.Encrypted, types_1.PdfDetail.PasswordRequired));
+    else if (r.status === 'certificate-handler')
+        out.push(factory.make(types_1.PdfCategory.Encrypted, types_1.PdfDetail.CertificateHandler));
+    else if (r.status === 'unknown-handler')
+        out.push(factory.make(types_1.PdfCategory.Encrypted, types_1.PdfDetail.UnknownHandler, undefined, r.detail ? { handler: r.detail } : undefined));
+    else
+        out.push(factory.make(types_1.PdfCategory.Encrypted, types_1.PdfDetail.UnknownCryptFilter, undefined, r.detail ? { filter: r.detail } : undefined));
+    return out;
+}
+const PLUGIN_KEPT = new Set([types_1.PdfDetail.PluginPassed, types_1.PdfDetail.PluginScrubbed]);
+/**
+ * `incomplete` marks a run that could not inspect the file: it stopped early, or found no page to read. finish()
+ * then rejects it without a score, whatever the actions say, because an override can make the finding that stopped
+ * it look harmless.
+ */
+function finish(findings, options, incomplete, version = '', pages, isOutput = false) {
+    if (incomplete)
+        return { status: 'rejected', score: null, risk: types_1.PdfRisk.Unknown, findings, version, pages };
+    const rejected = findings.some(f => f.action === 'reject');
+    // In an upload, a plugin rewrite or a metadata strip changes the file, so the output must be written.
+    // In an output being verified, the change is already there.
+    const strippable = findings.some(f => f.action === 'strip' || (!isOutput && (f.detail === types_1.PdfDetail.PluginScrubbed || f.detail === types_1.PdfDetail.Stripped)));
+    // The upload's score leaves out what plugins kept; the output's score counts it.
+    const { score, risk } = (0, score_1.scoreFindings)(isOutput ? findings : findings.filter(f => !PLUGIN_KEPT.has(f.detail)), options);
+    return { status: rejected ? 'rejected' : strippable ? 'strippable' : 'clean', score, risk, findings, version, pages };
+}
+/**
+ * Inspects `source` and leaves what it opens in `run`. It throws an I/O error instead of reporting a verdict on the
+ * PDF. That includes an error the parser recovered from as if the file were damaged, which `run.temp` keeps.
+ */
+async function analyze(run, source, options, depth, deadline, verify) {
+    let inspection;
+    try {
+        inspection = await analyzeInner(run, run.temp.watch(source), options, depth, deadline, verify);
+    }
+    catch (e) {
+        if (run.temp.ioError !== undefined)
+            throw run.temp.ioError;
+        if ((0, walker_1.stopsTree)(e) === 'DEFUSE_LIMIT' || isIoError(e))
+            throw e;
+        // Anything unexpected rejects the file rather than escaping as an exception.
+        const factory = new findings_1.FindingFactory(options.actionOverrides);
+        const f = limitFinding(factory, e) ?? factory.make(types_1.PdfCategory.Corrupted, types_1.PdfDetail.Unparseable, undefined, { reason: String(e?.message ?? e).slice(0, 120) });
+        inspection = finish([f], options, true);
+    }
+    if (run.temp.ioError !== undefined)
+        throw run.temp.ioError;
+    return inspection;
+}
+async function analyzeInner(run, source, options, depth, deadline, verify) {
+    const factory = new findings_1.FindingFactory(options.actionOverrides);
+    const limits = options.limits ?? {};
+    const findings = [];
+    if (limits.nestingDepth !== undefined && depth > limits.nestingDepth)
+        throw new walker_1.NestingLimitError('Nesting limit exceeded');
+    const size = await source.size();
+    if (limits.fileSize !== undefined && size > limits.fileSize)
+        return finish([factory.make(types_1.PdfCategory.Limit, types_1.PdfDetail.FileSize, undefined, { size })], options, true);
+    let doc;
+    try {
+        doc = await document_1.PdfDocument.open(source, {
+            password: options.password ?? '',
+            decompressedBytes: limits.decompressedBytes,
+            objectLimit: limits.objects,
+            deadline,
+            temp: run.temp,
+            memoryThreshold: options.memoryThreshold,
+        });
+    }
+    catch (e) {
+        const lf = limitFinding(factory, e);
+        if (lf)
+            findings.push(lf);
+        else if (e instanceof document_1.OpenError && e.kind === 'truncated')
+            findings.push(factory.make(types_1.PdfCategory.Corrupted, types_1.PdfDetail.Truncated));
+        else
+            findings.push(factory.make(types_1.PdfCategory.Corrupted, types_1.PdfDetail.Unparseable, undefined, { reason: String(e?.message ?? e).slice(0, 120) }));
+        return finish(findings, options, true);
+    }
+    run.doc = doc;
+    findings.push(...encryptionFindings(doc, factory));
+    if (doc.securityResult && doc.securityResult.status !== 'ok')
+        return finish(findings, options, true, doc.headerVersion);
+    if (doc.headerOffset > 0)
+        findings.push(factory.make(types_1.PdfCategory.Corrupted, types_1.PdfDetail.LeadingBytes, undefined, { bytes: doc.headerOffset }));
+    if (doc.trailingBytes > 0)
+        findings.push(factory.make(types_1.PdfCategory.Corrupted, types_1.PdfDetail.TrailingBytes, undefined, { bytes: doc.trailingBytes }));
+    if (doc.rebuilt)
+        findings.push(factory.make(types_1.PdfCategory.Corrupted, types_1.PdfDetail.XrefRebuilt));
+    // Earlier revisions matter when a newer one replaced or freed their objects; a pure addition hides nothing.
+    if (doc.issues.superseded)
+        findings.push(factory.make(types_1.PdfCategory.Structure, types_1.PdfDetail.IncrementalUpdates, undefined, { revisions: doc.sections, superseded: doc.issues.superseded }));
+    const walker = new walker_1.Walker(doc, { options, depth, temp: run.temp, factory, verify, deadline });
+    run.walker = walker;
+    let dead = 0;
+    try {
+        await walker.analyze();
+        dead = await doc.countDeadDefinitions();
+        // A signature keeps the bytes only when no other definition of an object sits anywhere in them, not even inside a
+        // live object, where it is harmless only to readers that keep to the cross-reference table.
+        run.signed = walker.signed && dead === 0 && verify === undefined && (await doc.countDeadDefinitions(true)) === 0;
+    }
+    catch (e) {
+        // A limit a plugin threw, such as a nested PDF over the nesting limit, rejects the whole upload, not just the attachment.
+        if (depth > 0 && e === walker.passedOn)
+            throw e;
+        const lf = limitFinding(factory, e) ?? factory.make(types_1.PdfCategory.Corrupted, types_1.PdfDetail.Unparseable, undefined, { reason: String(e?.message ?? e).slice(0, 120) });
+        findings.push(...walker.findings, lf);
+        return finish(findings, options, true, doc.headerVersion, walker.pages);
+    }
+    findings.push(...walker.findings);
+    const issues = doc.issues;
+    if (dead)
+        findings.push(factory.make(types_1.PdfCategory.Structure, types_1.PdfDetail.ShadowedObjects, undefined, { count: dead }));
+    if (issues.streamLengthWrong)
+        findings.push(factory.make(types_1.PdfCategory.Corrupted, types_1.PdfDetail.StreamLengthWrong, undefined, { count: issues.streamLengthWrong }));
+    if (issues.malformed)
+        findings.push(factory.make(types_1.PdfCategory.Corrupted, types_1.PdfDetail.MalformedObject, undefined, { count: issues.malformed }));
+    if (issues.badOffsets)
+        findings.push(factory.make(types_1.PdfCategory.Corrupted, types_1.PdfDetail.MalformedObject, 'cross-reference table', { reason: 'entries that do not point at their object', count: issues.badOffsets }));
+    if (issues.genMismatch)
+        findings.push(factory.make(types_1.PdfCategory.Corrupted, types_1.PdfDetail.MalformedObject, 'cross-reference table', { reason: 'generation numbers that do not match', count: issues.genMismatch }));
+    if (issues.badXRefStm)
+        findings.push(factory.make(types_1.PdfCategory.Corrupted, types_1.PdfDetail.MalformedObject, 'cross-reference table', { reason: '/XRefStm that leads to no xref stream', count: issues.badXRefStm }));
+    if (issues.xrefStmOverFree)
+        findings.push(factory.make(types_1.PdfCategory.Corrupted, types_1.PdfDetail.MalformedObject, 'cross-reference table', { reason: '/XRefStm entries for objects the table marks free', count: issues.xrefStmOverFree }));
+    if (issues.badObjStm.size)
+        findings.push(factory.make(types_1.PdfCategory.Corrupted, types_1.PdfDetail.MalformedObject, 'object stream', { reason: 'a header pdf.js cannot follow', count: issues.badObjStm.size }));
+    if (issues.refGen.size)
+        findings.push(factory.make(types_1.PdfCategory.Corrupted, types_1.PdfDetail.MalformedObject, undefined, { reason: 'references whose generation does not match the object', count: issues.refGen.size }));
+    if (issues.duplicateKeys.size)
+        findings.push(factory.make(types_1.PdfCategory.Corrupted, types_1.PdfDetail.MalformedObject, undefined, { reason: 'repeated dictionary keys', keys: [...issues.duplicateKeys].slice(0, 10).join(', ') }));
+    if (issues.structuralRefs) {
+        // The writer cannot keep a reference to an object or xref stream, so it goes whatever the override says.
+        const f = factory.make(types_1.PdfCategory.Corrupted, types_1.PdfDetail.MalformedObject, undefined, { reason: 'references to object or xref streams', count: issues.structuralRefs });
+        if (f.action === 'info')
+            f.action = 'strip';
+        findings.push(f);
+    }
+    for (const part of issues.memoryFallback)
+        findings.push(factory.make(types_1.PdfCategory.Processing, types_1.PdfDetail.MemoryFallback, undefined, { part }));
+    if (walker.pages === 0)
+        findings.push(factory.make(types_1.PdfCategory.Corrupted, types_1.PdfDetail.Unparseable, undefined, { reason: 'no pages' }));
+    const result = finish(findings, options, walker.pages === 0, doc.headerVersion, walker.pages, verify !== undefined);
+    if (result.status !== 'clean' || walker.removedAt === undefined)
+        return result;
+    // A removal no finding reported still shows in the status, and keeps a signed file from passing through unchanged.
+    const f = factory.make(types_1.PdfCategory.Processing, types_1.PdfDetail.ContentRemoved, walker.removedAt);
+    if (f.action === 'info')
+        f.action = 'strip';
+    findings.push(f);
+    return finish(findings, options, false, doc.headerVersion, walker.pages, verify !== undefined);
+}
+async function closeSource(source) {
+    try {
+        await source.close?.();
+    }
+    catch {
+        /* ignore */
+    }
+}
+/** Inspects a PDF without changing it. The source is closed when the run ends. */
+async function inspectPdfSource(source, options = {}) {
+    const run = { temp: new io_1.TempDir(options.tempDir) };
+    const deadline = options.limits?.timeMs !== undefined ? Date.now() + options.limits.timeMs : undefined;
+    try {
+        return await analyze(run, source, options, 0, deadline).catch(e => rethrowOrReject(e, options));
+    }
+    finally {
+        await closeSource(source);
+        await endRun(run);
+    }
+}
+function rethrowOrReject(e, options) {
+    const lf = limitFinding(new findings_1.FindingFactory(options.actionOverrides), e);
+    if (!lf)
+        throw e;
+    return finish([lf], options, true);
+}
+/** Copies to the caller's sink. On failure it aborts the sink instead of closing it, so a partial copy does not look whole. */
+async function deliver(from, sink) {
+    try {
+        await (0, io_1.copyToSink)(from, sink);
+    }
+    catch (e) {
+        try {
+            await sink.abort?.(e);
+        }
+        catch {
+            /* the copy's error is the one to report */
+        }
+        throw e;
+    }
+    await sink.close();
+}
+/**
+ * Writes a defused copy of `source` to `sink`. Nothing reaches the sink unless the output passes inspection. The
+ * source is closed when the run ends.
+ */
+async function disarmPdfSource(source, sink, options = {}) {
+    return disarmAtDepth(source, sink, options, 0);
+}
+/** Internal entry that carries the nesting depth for attached PDFs, and the deadline they share with the upload. */
+async function disarmAtDepth(source, sink, options, depth, deadline = options.limits?.timeMs !== undefined ? Date.now() + options.limits.timeMs : undefined) {
+    const run = { temp: new io_1.TempDir(options.tempDir) };
+    let input = source;
+    try {
+        let before;
+        try {
+            // A caller's source can change between reads, so analysis and the copy to the sink read one snapshot. An
+            // attached PDF's source already belongs to the engine, and analysis rejects a file over the size limit unread.
+            const fileSize = options.limits?.fileSize;
+            if (depth === 0 && (fileSize === undefined || (await source.size()) <= fileSize)) {
+                const snapshot = new io_1.SpillSink(run.temp, options.memoryThreshold ?? 8 * 1024 * 1024);
+                try {
+                    await (0, io_1.copyToSink)(source, snapshot, () => {
+                        if (deadline !== undefined && Date.now() > deadline)
+                            throw new document_1.TimeLimitError('Time limit exceeded');
+                    });
+                }
+                finally {
+                    await snapshot.close();
+                }
+                input = snapshot.source();
+            }
+            before = await analyze(run, input, options, depth, deadline);
+        }
+        catch (e) {
+            if (depth > 0 && (0, walker_1.stopsTree)(e) === 'DEFUSE_LIMIT')
+                throw e;
+            before = rethrowOrReject(e, options);
+        }
+        const walker = run.walker;
+        if (before.status === 'rejected' || !walker)
+            return { status: 'rejected', before, removed: [] };
+        // Any other file is rewritten, so the output holds only what the walk understood. A signature over the whole
+        // file keeps a clean file byte for byte, since a rewrite would break it. A file that needed any repair to read
+        // does not qualify, whatever the overrides say, because other readers may repair it another way.
+        if (before.status === 'clean' && run.signed && options.preserveSignatures !== false && !before.findings.some(f => f.category === types_1.PdfCategory.Corrupted)) {
+            await deliver(input, sink);
+            return { status: 'clean', before, after: before, removed: [] };
+        }
+        const factory = new findings_1.FindingFactory(options.actionOverrides);
+        const outPath = await run.temp.file('.pdf');
+        const out = (0, io_1.fileSink)(outPath);
+        const expectedContent = walker.pageContent;
+        try {
+            await walker.write(out);
+        }
+        catch (e) {
+            await out.close().catch(() => {
+                // The write's failure, handled below, is the one that counts.
+            });
+            if (run.temp.ioError !== undefined)
+                throw run.temp.ioError;
+            if (isIoError(e))
+                throw e;
+            const lf = limitFinding(factory, e);
+            before.findings.push(lf ?? factory.make(types_1.PdfCategory.Processing, types_1.PdfDetail.VerificationFailed, undefined, { reasons: `write failed: ${String(e?.message ?? e).slice(0, 100)}` }));
+            before.status = 'rejected';
+            // A limit stopped the run. A write that failed otherwise leaves the upload fully inspected, so its score stands.
+            if (lf) {
+                before.score = null;
+                before.risk = types_1.PdfRisk.Unknown;
+            }
+            return { status: 'rejected', before, removed: [] };
+        }
+        await out.close();
+        // A read the writer recovered from leaves an object out of the output.
+        if (run.temp.ioError !== undefined)
+            throw run.temp.ioError;
+        // The input document is no longer read; free its index before the output is analyzed.
+        await walker.releaseState();
+        const verifyOptions = {
+            actionOverrides: options.actionOverrides,
+            scoreWeights: options.scoreWeights,
+            scoreBands: options.scoreBands,
+            tempDir: options.tempDir,
+            memoryThreshold: options.memoryThreshold,
+        };
+        const outSource = (0, io_1.fileSource)(outPath);
+        try {
+            const check = { temp: new io_1.TempDir(options.tempDir) };
+            let after;
+            let outContent;
+            try {
+                after = await analyze(check, outSource, verifyOptions, depth, deadline, walker.kept);
+                outContent = check.walker?.pageContent ?? [];
+            }
+            finally {
+                await endRun(check);
+            }
+            const reasons = after.findings.filter(f => f.action !== 'info').map(f => `${f.category}/${f.detail}`);
+            // A check that stopped early verified nothing, even when the caller overrode the finding that stopped it to info.
+            if (after.status === 'rejected' && !reasons.length)
+                reasons.push('the output check stopped early');
+            if (after.pages !== before.pages)
+                reasons.push(`pages ${before.pages} -> ${after.pages}`);
+            // Every page must keep exactly the content it had; a lost content stream fails here.
+            if (outContent.length !== expectedContent.length || outContent.some((n, i) => n !== expectedContent[i]))
+                reasons.push('page content changed');
+            if (reasons.length) {
+                before.findings.push(factory.make(types_1.PdfCategory.Processing, types_1.PdfDetail.VerificationFailed, undefined, { reasons: reasons.slice(0, 10).join(', ') }));
+                before.status = 'rejected';
+                return { status: 'rejected', before, removed: [] };
+            }
+            await deliver(outSource, sink);
+            return { status: before.status === 'clean' ? 'clean' : 'defused', before, after, removed: before.findings.filter(f => f.action === 'strip') };
+        }
+        finally {
+            await closeSource(outSource);
+        }
+    }
+    catch (e) {
+        // An attached PDF's I/O error fails the upload's run too, instead of counting as a failed plugin.
+        if (depth > 0 && (isIoError(e) || (e !== undefined && e === run.temp.ioError)))
+            throw new walker_1.NestedIoError(e);
+        throw e;
+    }
+    finally {
+        if (input !== source)
+            await closeSource(input);
+        // An attached PDF's source belongs to the walker that decoded it.
+        if (depth === 0)
+            await closeSource(source);
+        await endRun(run);
+    }
+}
+/** Inspects PDF bytes. */
+async function inspectPdf(bytes, options = {}) {
+    return inspectPdfSource((0, io_1.bufferSource)(bytes), options);
+}
+/** Defuses PDF bytes. `bytes` holds the output unless the file was rejected. */
+async function disarmPdf(bytes, options = {}) {
+    const sink = (0, io_1.bufferSink)();
+    const result = await disarmPdfSource((0, io_1.bufferSource)(bytes), sink, options);
+    return result.status === 'rejected' ? result : { ...result, bytes: sink.result() };
+}

package/dist/filters.d.ts

@@ -0,0 +1,27 @@
+import { PdfDict } from './objects';
+export declare class DecompressionLimitError extends Error {
+}
+export declare class UnsupportedFilterError extends Error {
+}
+/**
+ * Lists a stream's filters and their parameter dictionaries. A filter that is not a name, such as a reference left
+ * unresolved, gets an empty name that no decoder accepts: its bytes are still encoded, not plain.
+ */
+export declare function filtersOf(dict: PdfDict): Array<{
+    name: string;
+    parms?: PdfDict;
+}>;
+/** Growable byte buffer: one byte of memory per byte, where a JS number array costs a slot each. */
+export declare class Out {
+    private buf;
+    len: number;
+    constructor(size?: number);
+    push(b: number): void;
+    take(): Uint8Array;
+}
+export declare const hexVal: (c: number) => number;
+/**
+ * Decodes a stream chunk by chunk through its whole filter chain. No stage may produce more than `limit` bytes, and
+ * `checkTime` runs between pieces of work in every stage.
+ */
+export declare function decodeChunks(input: AsyncIterable<Uint8Array>, dict: PdfDict, limit?: number, checkTime?: () => void): AsyncGenerator<Uint8Array>;