@patrickdk77/pdf-defuse 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const fs = __importStar(require("node:fs"));
+const fsp = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const promises_1 = require("node:stream/promises");
+const node_url_1 = require("node:url");
+const data_plugins_1 = require("./data-plugins");
+const document_1 = require("./document");
+const engine_1 = require("./engine");
+const io_1 = require("./io");
+const plugins_1 = require("./plugins");
+const USAGE = `Usage:
+  pdf-defuse inspect <file> [options]
+  pdf-defuse defuse <in> <out> [options]
+
+Options:
+  --password-file <path>   read the password from a file, or set PDF_DEFUSE_PASSWORD
+  --plugin <module>        load plugins from a file or an installed package, repeatable
+  --config <module>        load a whole options object, repeatable; the other options apply on top
+  --keep-type <type>       keep contained files of this MIME type or file extension unchanged, repeatable
+  --defuse-attached-pdfs   defuse PDFs attached inside the PDF
+  --scrub-attached-csv     keep attached CSV files, escaping cells a spreadsheet would run as formulas
+  --scrub-attached-tsv     the same for tab-separated files
+  --keep-attached-json     keep attached JSON files that parse
+  --csv-formulas <mode>    escape (default), keep or remove, for the CSV and TSV options
+  --strip-metadata
+  --limit <name>=<value>   fileSize, objects, decompressedBytes, nestingDepth, timeMs; sizes accept kb, mb, gb
+  --json                   print the result as JSON
+
+Use - for stdin or stdout.
+Exit codes: 0 clean, 1 stripped or strippable, 2 rejected, 3 usage or I/O error.`;
+class UsageError extends Error {
+}
+function parseSize(v) {
+    const m = /^(\d+(?:\.\d+)?)\s*(b|kb|k|mb|m|gb|g)?$/i.exec(v.trim());
+    if (!m)
+        throw new UsageError(`Bad size "${v}"`);
+    const mult = { b: 1, k: 1024, kb: 1024, m: 1024 ** 2, mb: 1024 ** 2, g: 1024 ** 3, gb: 1024 ** 3 };
+    return Math.round(Number(m[1]) * mult[(m[2] ?? 'b').toLowerCase()]);
+}
+// A real dynamic import. TypeScript would compile import() to require() for CommonJS output,
+// and require() cannot load ES modules or file URLs.
+const dynamicImport = new Function('specifier', 'return import(specifier)');
+/** Reads `key` from `v` the way `v?.[key]` does, for a value whose shape is not known. */
+function prop(v, key) {
+    return (typeof v === 'object' && v !== null) || typeof v === 'function' ? v[key] : undefined;
+}
+const isObject = (v) => typeof v === 'object' && v !== null;
+async function loadModule(spec) {
+    // A bare name ending in .js can be a file in the working directory or a package with that name. The file wins.
+    const looksLikePath = spec.startsWith('.') || path.isAbsolute(spec) || (/\.(c|m)?js$/.test(spec) && fs.statSync(spec, { throwIfNoEntry: false })?.isFile() === true);
+    let resolved;
+    if (looksLikePath)
+        resolved = path.resolve(process.cwd(), spec);
+    else {
+        try {
+            resolved = require.resolve(spec, { paths: [process.cwd()] });
+        }
+        catch (e) {
+            // require.resolve applies only the "require" condition, so a package that exports only "import" ends up here.
+            if (e.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED')
+                throw e;
+            const name = spec
+                .split('/')
+                .slice(0, spec.startsWith('@') ? 2 : 1)
+                .join('/');
+            const subpath = `.${spec.slice(name.length)}`;
+            for (let dir = process.cwd(); resolved === undefined; dir = path.dirname(dir)) {
+                const pkg = path.join(dir, 'node_modules', name);
+                if (fs.existsSync(path.join(pkg, 'package.json'))) {
+                    const exp = JSON.parse(fs.readFileSync(path.join(pkg, 'package.json'), 'utf8')).exports;
+                    const isMap = isObject(exp) && Object.keys(exp).some(k => k.startsWith('.'));
+                    let target;
+                    let match;
+                    if (!isMap)
+                        target = subpath === '.' ? exp : undefined;
+                    else if (Object.hasOwn(exp, subpath) && !subpath.includes('*'))
+                        target = exp[subpath];
+                    else {
+                        // A pattern key holds one "*". Node prefers the longest text before the "*", then the longest key, and puts
+                        // what the "*" matched into the target.
+                        let best = '';
+                        for (const k of Object.keys(exp)) {
+                            const star = k.indexOf('*');
+                            const trailer = k.slice(star + 1);
+                            if (star < 0 || trailer.includes('*') || !subpath.startsWith(k.slice(0, star)) || subpath.length === star)
+                                continue;
+                            if (trailer && (!subpath.endsWith(trailer) || subpath.length < k.length))
+                                continue;
+                            if (!best || star > best.indexOf('*') || (star === best.indexOf('*') && k.length > best.length))
+                                best = k;
+                        }
+                        if (best) {
+                            target = exp[best];
+                            match = subpath.slice(best.indexOf('*'), subpath.length - (best.length - best.indexOf('*') - 1));
+                            // Node refuses a match that would step outside the pattern's directory.
+                            if (match.split(/[/\\]/).some(s => s === '' || s === '.' || s === '..' || s.toLowerCase() === 'node_modules'))
+                                throw e;
+                        }
+                    }
+                    // Node takes the first condition it supports, in the order the package lists them.
+                    while (isObject(target) && !Array.isArray(target))
+                        target = target[Object.keys(target).find(k => k === 'node' || k === 'import' || k === 'default') ?? ''];
+                    if (typeof target !== 'string')
+                        throw e;
+                    resolved = path.resolve(pkg, match === undefined ? target : target.replaceAll('*', match));
+                }
+                else if (path.dirname(dir) === dir)
+                    throw e;
+            }
+        }
+    }
+    return dynamicImport((0, node_url_1.pathToFileURL)(resolved).href);
+}
+function pluginsFrom(mod) {
+    // import() gives a CommonJS module a default export holding module.exports, so the named exports come first.
+    const value = prop(mod, 'plugins') ?? prop(prop(mod, 'default'), 'plugins') ?? prop(mod, 'plugin') ?? prop(prop(mod, 'default'), 'plugin') ?? prop(mod, 'default');
+    const list = Array.isArray(value) ? value : [value];
+    for (const p of list)
+        if (!p || (prop(p, 'kind') !== 'file' && prop(p, 'kind') !== 'script'))
+            throw new UsageError('A plugin module must export plugins with kind "file" or "script"');
+    // The loop above checked each entry's kind, which is as far as a plugin's shape can be checked here.
+    return list;
+}
+async function parse(argv) {
+    const [command, ...rest] = argv;
+    if (command !== 'inspect' && command !== 'defuse')
+        throw new UsageError(command ? `Unknown command "${command}"` : 'No command');
+    const positional = [];
+    // Every --config module goes in first and the flags apply on top, wherever they sit on the command line.
+    const options = {};
+    const ordered = [];
+    const limits = {};
+    let stripMetadata = false;
+    let json = false;
+    const delimited = {};
+    let password = process.env.PDF_DEFUSE_PASSWORD;
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        const next = () => {
+            const v = rest[++i];
+            if (v === undefined)
+                throw new UsageError(`${a} needs a value`);
+            return v;
+        };
+        switch (a) {
+            case '--password-file':
+                password = (await fsp.readFile(next(), 'utf8')).replace(/\r?\n$/, '');
+                break;
+            case '--plugin':
+                ordered.push(...pluginsFrom(await loadModule(next())));
+                break;
+            case '--config': {
+                const mod = await loadModule(next());
+                // The module's shape is the caller's to get right, as PdfOptions documents it.
+                const cfg = (prop(mod, 'default') ?? mod);
+                // Modules combine: plugin lists join in order and limits merge. For any other option the later module wins.
+                Object.assign(options, cfg, {
+                    filePlugins: [...(options.filePlugins ?? []), ...(cfg.filePlugins ?? [])],
+                    scriptPlugins: [...(options.scriptPlugins ?? []), ...(cfg.scriptPlugins ?? [])],
+                    limits: { ...options.limits, ...cfg.limits },
+                });
+                break;
+            }
+            case '--keep-type':
+                ordered.push((0, plugins_1.passThrough)([next()]));
+                break;
+            case '--defuse-attached-pdfs':
+                ordered.push((0, plugins_1.pdfPlugin)());
+                break;
+            case '--scrub-attached-csv':
+                ordered.push((0, data_plugins_1.csvPlugin)(delimited));
+                break;
+            case '--scrub-attached-tsv':
+                ordered.push((0, data_plugins_1.tsvPlugin)(delimited));
+                break;
+            case '--keep-attached-json':
+                ordered.push((0, data_plugins_1.jsonPlugin)());
+                break;
+            case '--csv-formulas': {
+                const mode = next();
+                if (mode !== 'escape' && mode !== 'keep' && mode !== 'remove')
+                    throw new UsageError(`--csv-formulas expects escape, keep or remove, not "${mode}"`);
+                delimited.formulas = mode;
+                break;
+            }
+            case '--strip-metadata':
+                stripMetadata = true;
+                break;
+            case '--limit': {
+                const [name, value] = next().split('=');
+                if (value === undefined)
+                    throw new UsageError('--limit expects name=value');
+                if (name === 'fileSize' || name === 'decompressedBytes')
+                    limits[name] = parseSize(value);
+                else if (name === 'objects' || name === 'nestingDepth' || name === 'timeMs') {
+                    // Number('abc') is NaN, and no comparison with NaN is true, so the limit would never apply.
+                    if (!/^\d+$/.test(value.trim()))
+                        throw new UsageError(`Bad value for ${name}: "${value}"`);
+                    limits[name] = Number(value);
+                }
+                else
+                    throw new UsageError(`Unknown limit "${name}"`);
+                break;
+            }
+            case '--json':
+                json = true;
+                break;
+            default:
+                if (a === '--password' || a.startsWith('--password='))
+                    throw new UsageError('Pass the password with --password-file or PDF_DEFUSE_PASSWORD, not on the command line');
+                // What follows "=" can be a secret typed in the wrong place, and stderr often ends up in a log.
+                if (a.startsWith('--'))
+                    throw new UsageError(`Unknown option ${a.replace(/=.*/s, '=...')}`);
+                positional.push(a);
+        }
+    }
+    if (stripMetadata)
+        options.stripMetadata = true;
+    for (const p of ordered) {
+        if (p.kind === 'file') {
+            options.filePlugins ??= [];
+            options.filePlugins.push(p);
+        }
+        else {
+            options.scriptPlugins ??= [];
+            options.scriptPlugins.push(p);
+        }
+    }
+    if (Object.keys(limits).length)
+        options.limits = { ...(options.limits ?? {}), ...limits };
+    if (password !== undefined)
+        options.password = password;
+    return { command, positional, options, json };
+}
+/**
+ * The input as a source. stdin is copied to a temporary file first. The copy stops one byte past `fileSize`, so the
+ * engine rejects the upload as too large without the rest being read, and at the deadline, where the source then
+ * fails the run for time.
+ */
+async function inputSource(p, tempDir, fileSize, deadline) {
+    if (p !== '-') {
+        return {
+            source: (0, io_1.fileSource)(p),
+            cleanup: async () => {
+                // The caller's own file stays.
+            },
+        };
+    }
+    const temp = new io_1.TempDir(tempDir);
+    try {
+        const file = await temp.file('.pdf');
+        let room = (fileSize ?? Number.POSITIVE_INFINITY) + 1;
+        try {
+            await (0, promises_1.pipeline)(process.stdin, async function* (chunks) {
+                for await (const c of chunks) {
+                    yield c.subarray(0, room);
+                    room -= c.length;
+                    if (room <= 0)
+                        return;
+                }
+            }, fs.createWriteStream(file), { signal: deadline === undefined ? undefined : AbortSignal.timeout(Math.max(0, deadline - Date.now())) });
+        }
+        catch (e) {
+            if (e.name !== 'AbortError')
+                throw e;
+            const late = () => Promise.reject(new document_1.TimeLimitError('Time limit exceeded'));
+            return { source: { size: late, read: late }, cleanup: () => temp.cleanup() };
+        }
+        return { source: (0, io_1.fileSource)(file), cleanup: () => temp.cleanup() };
+    }
+    catch (e) {
+        await temp.cleanup();
+        throw e;
+    }
+}
+/** Writes a control character as a JSON escape, since text from the PDF could otherwise drive the terminal. */
+const escaped = (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`;
+function report(label, i) {
+    const lines = [`${label}: ${i.status}, risk ${i.risk}${i.score === null ? '' : ` (score ${i.score})`}, PDF ${i.version || '?'}, ${i.pages ?? 0} pages`];
+    for (const f of i.findings)
+        lines.push(`  ${f.action.padEnd(6)} ${f.category}/${f.detail}${f.location ? ` [${f.location}]` : ''}: ${f.description}`);
+    // A location can hold a field name or a title from the PDF. A line break in one would print a line of its own.
+    return lines.map(l => l.replace(/\p{Cc}/gu, escaped)).join('\n');
+}
+async function main(argv) {
+    let parsed;
+    try {
+        parsed = await parse(argv);
+    }
+    catch (e) {
+        process.stderr.write(`${e.message}\n\n${USAGE}\n`);
+        return 3;
+    }
+    const { command, positional, options, json } = parsed;
+    try {
+        if (command === 'inspect' && positional.length !== 1)
+            throw new UsageError('inspect takes one file');
+        if (command === 'defuse' && positional.length !== 2)
+            throw new UsageError('defuse takes an input and an output');
+        const toStdout = command === 'defuse' && positional[1] === '-';
+        if (command === 'defuse' && positional[0] !== '-' && !toStdout) {
+            // A failed write deletes the partial output, which here would be the only copy of the input.
+            const [a, b] = await Promise.all([fsp.stat(positional[0]), fsp.stat(positional[1]).catch(() => undefined)]);
+            if (b && a.dev === b.dev && a.ino === b.ino)
+                throw new UsageError('The input and the output are the same file');
+        }
+        // Reading stdin counts toward the time limit, so the run gets what is left of it.
+        const deadline = options.limits?.timeMs === undefined ? undefined : Date.now() + options.limits.timeMs;
+        const input = await inputSource(positional[0], options.tempDir, options.limits?.fileSize, deadline);
+        const runOptions = deadline === undefined ? options : { ...options, limits: { ...options.limits, timeMs: deadline - Date.now() } };
+        let text;
+        let code;
+        try {
+            if (command === 'inspect') {
+                const r = await (0, engine_1.inspectPdfSource)(input.source, runOptions);
+                text = json ? JSON.stringify(r, null, 2) : report('inspection', r);
+                code = r.status === 'clean' ? 0 : r.status === 'strippable' ? 1 : 2;
+            }
+            else {
+                const r = await (0, engine_1.disarmPdfSource)(input.source, toStdout ? (0, io_1.writableSink)(process.stdout) : (0, io_1.fileSink)(positional[1]), runOptions);
+                text = json ? JSON.stringify(r, null, 2) : [`result: ${r.status}`, report('before', r.before), ...(r.after && r.status === 'defused' ? [report('after', r.after)] : [])].join('\n');
+                code = r.status === 'clean' ? 0 : r.status === 'defused' ? 1 : 2;
+            }
+        }
+        finally {
+            await input.source.close?.();
+            await input.cleanup();
+        }
+        // JSON.stringify escapes C0 controls but not DEL or the C1 range.
+        if (json)
+            text = text.replace(/[\u007f-\u009f]/g, escaped);
+        // The report shares stdout only when the PDF goes elsewhere. A report nobody can read is an I/O error.
+        const out = toStdout ? process.stderr : process.stdout;
+        await new Promise((resolve, reject) => out.write(`${text}\n`, e => (e ? reject(e) : resolve())));
+        return code;
+    }
+    catch (e) {
+        process.stderr.write(`${e instanceof UsageError ? `${e.message}\n\n${USAGE}` : `Error: ${e.message}`}\n`);
+        return 3;
+    }
+}
+if (require.main === module) {
+    // main() learns of a failed write from its callback. Node emits the failure as an 'error' event as well, which
+    // with no listener would end the process with exit code 1.
+    for (const stream of [process.stdout, process.stderr]) {
+        stream.on('error', () => {
+            process.exitCode = 3;
+        });
+    }
+    main(process.argv.slice(2)).then(code => {
+        process.exitCode = code;
+    });
+}

package/dist/crypto.d.ts

@@ -0,0 +1,51 @@
+import { PdfDict, type PdfStream } from './objects';
+/** RC4 with state, so a stream can be decrypted in chunks. Node 24's OpenSSL 3 refuses RC4, so it is written here. */
+export declare class Rc4 {
+    private readonly s;
+    private i;
+    private j;
+    constructor(key: Uint8Array);
+    update(data: Uint8Array): Buffer;
+}
+export declare const rc4: (key: Uint8Array, data: Uint8Array) => Buffer<ArrayBufferLike>;
+type CryptMethod = 'RC4' | 'AES128' | 'AES256' | 'Identity';
+export type OpenResult = {
+    status: 'ok';
+    handler: SecurityHandler;
+    password: 'empty' | 'user' | 'owner';
+} | {
+    status: 'password-required' | 'certificate-handler' | 'unknown-handler' | 'unknown-filter';
+    detail?: string;
+};
+/** A stream decryptor that works chunk by chunk. */
+export interface ChunkDecryptor {
+    update(chunk: Uint8Array): Buffer;
+    final(): Buffer;
+}
+export declare class SecurityHandler {
+    private readonly version;
+    readonly keyBits: number;
+    private readonly fileKey;
+    readonly streamMethod: CryptMethod;
+    readonly stringMethod: CryptMethod;
+    readonly embeddedFileMethod: CryptMethod;
+    readonly encryptMetadata: boolean;
+    private readonly cryptFilters;
+    /** Crypt filters with a /CFM this package cannot decrypt, mapped to that /CFM. Harmless until something selects one. */
+    private readonly unknownFilters;
+    private constructor();
+    static open(enc: PdfDict, id0: Uint8Array, password: string): OpenResult;
+    private readonly keyCache;
+    private objectKey;
+    decryptWith(method: CryptMethod, data: Uint8Array, num: number, gen: number): Uint8Array;
+    /** The crypt method for a stream, honoring a /Crypt filter in its own Filter array and the embedded-file default. */
+    methodForStream(stream: PdfStream): CryptMethod;
+    /**
+     * Plaintext length of a stream, read without decrypting the whole body. For AES the last two
+     * blocks are decrypted to learn the padding length.
+     */
+    plainLength(stream: PdfStream, num: number, gen: number, readRaw: (offset: number, length: number) => Promise<Uint8Array>): Promise<number>;
+    /** A decryptor that emits exactly `plainLength` bytes across all chunks. */
+    chunkDecryptor(stream: PdfStream, num: number, gen: number, plainLength: number): ChunkDecryptor;
+}
+export {};