@patrickdk77/pdf-defuse 0.2.2 → 0.2.3

package/README.md

@@ -254,6 +254,8 @@ const result = await router.process(upload, sink, { depth: 0, deadline: Date.now
 
 `pdfPlugin(options)` runs every PDF it gets with those options. Built without options, it takes the options of the pdf-defuse run that found the file, which pdf-defuse passes under a symbol only it can read. A `pdfPlugin()` that another package calls with a context of its own runs with no options at all, so a master builds it with options.
 
+`detectPdf(bytes, options)` and `detectPdfSource(source, options)` tell a router whether pdf-defuse reads a file. They return `{ mimeType, extension, offset }`, or undefined. A header in the first 1024 bytes makes the file a PDF at the header's offset. A file without one is a PDF only when `options.name` or `options.declaredType` says PDF and pdf-defuse opens it, the way pdf.js opens a file without a header. That open reads the whole file, and the answer then carries `heuristic`. A file that opens but is too broken to inspect still counts, and the inspection rejects it. `pdfPlugin` takes what detection finds. `detectPdfSource` leaves the source open, and throws with the `DEFUSE_LIMIT` code once `options.deadline` passes.
+
 The context holds `depth` and `deadline` and nothing PDF-specific, so any package can make one. `depth` is the depth of the file itself, the same number as `file.depth`. The upload is 0 and a file inside it is 1, whatever the formats. A container gives each file it finds its own depth plus one. `pdfPlugin` runs a PDF at the depth in its context and checks `limits.nestingDepth` against it, so a PDF in a ZIP in a PDF counts as depth 2. `deadline` is the `Date.now()` value the whole upload must finish by, and a container passes it on unchanged.
 
 A plugin returns its findings as `DefuseFinding` objects, whose `category` and `detail` are plain strings. The string enums of two packages never match each other. `PdfFinding`, with pdf-defuse's enums, fits `DefuseFinding`. pdf-defuse adds a contained file's findings to its own report with `attachment` set, and keeps the action each came with, except that `reject` becomes `strip`. `actionOverrides` apply to the findings a pdf-defuse run makes, never to those a plugin returns.

package/dist/detect.d.ts

@@ -0,0 +1,9 @@
+import type { ByteSource, DetectOptions, FormatDetection } from './types';
+/**
+ * Whether pdf-defuse reads `source` as a PDF. A header in the first 1024 bytes makes it one, at the header's offset.
+ * A file without one is a PDF only when its name or declared type says PDF and it opens as one, the way pdf.js opens
+ * a file without a header. That open reads the whole file. The source stays open.
+ */
+export declare function detectPdfSource(source: ByteSource, options?: DetectOptions): Promise<FormatDetection | undefined>;
+/** `detectPdfSource` over bytes in memory. */
+export declare function detectPdf(bytes: Uint8Array, options?: DetectOptions): Promise<FormatDetection | undefined>;

package/dist/detect.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectPdfSource = detectPdfSource;
+exports.detectPdf = detectPdf;
+const document_1 = require("./document");
+const io_1 = require("./io");
+const sniff_1 = require("./sniff");
+const walker_1 = require("./walker");
+/** PDF readers look for the header in the first 1024 bytes, and so does PdfDocument when it opens a file. */
+const HEADER_WINDOW = 1024;
+const HEADER = Buffer.from('%PDF-', 'latin1');
+const isIoError = (e) => typeof e?.code === 'string' && /^E[A-Z]+$/.test(e.code);
+/**
+ * Whether pdf-defuse reads `source` as a PDF. A header in the first 1024 bytes makes it one, at the header's offset.
+ * A file without one is a PDF only when its name or declared type says PDF and it opens as one, the way pdf.js opens
+ * a file without a header. That open reads the whole file. The source stays open.
+ */
+async function detectPdfSource(source, options = {}) {
+    const size = await source.size();
+    const head = await source.read(0, Math.min(size, HEADER_WINDOW));
+    const at = Buffer.from(head.buffer, head.byteOffset, head.byteLength).indexOf(HEADER);
+    if (at >= 0)
+        return { mimeType: 'application/pdf', extension: 'pdf', offset: at };
+    const claimed = [options.declaredType, (0, sniff_1.typeFromName)(options.name)].some(t => t !== undefined && (0, sniff_1.family)(t) === 'application/pdf');
+    if (!claimed)
+        return undefined;
+    const temp = new io_1.TempDir(options.tempDir);
+    try {
+        const doc = await document_1.PdfDocument.open(temp.watch(source), { deadline: options.deadline, temp, memoryThreshold: options.memoryThreshold });
+        await doc.release();
+        if (temp.ioError !== undefined)
+            throw temp.ioError;
+        return { mimeType: 'application/pdf', extension: 'pdf', offset: 0, heuristic: 'no PDF header, but the name or declared type says PDF and the file opens as one' };
+    }
+    catch (e) {
+        if (temp.ioError !== undefined)
+            throw temp.ioError;
+        if ((0, walker_1.stopsTree)(e) !== undefined || isIoError(e))
+            throw e;
+        // Any other failure to open, as in an inspection, means pdf-defuse does not read the file as a PDF.
+        return undefined;
+    }
+    finally {
+        await temp.cleanup();
+    }
+}
+/** `detectPdfSource` over bytes in memory. */
+function detectPdf(bytes, options = {}) {
+    return detectPdfSource((0, io_1.bufferSource)(bytes), options);
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export type { DelimitedOptions, FormulaHandling } from './data-plugins';
 export { csvPlugin, jsonPlugin, tsvPlugin } from './data-plugins';
+export { detectPdf, detectPdfSource } from './detect';
 export { disarmPdf, disarmPdfSource, inspectPdf, inspectPdfSource } from './engine';
 export { allFindingSpecs } from './findings';
 export { bufferSink, bufferSource, fileSink, fileSource, writableSink } from './io';

package/dist/index.js

@@ -14,11 +14,14 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.scoreFindings = exports.DEFAULT_BANDS = exports.COMBINATIONS = exports.pdfPlugin = exports.passThrough = exports.writableSink = exports.fileSource = exports.fileSink = exports.bufferSource = exports.bufferSink = exports.allFindingSpecs = exports.inspectPdfSource = exports.inspectPdf = exports.disarmPdfSource = exports.disarmPdf = exports.tsvPlugin = exports.jsonPlugin = exports.csvPlugin = void 0;
+exports.scoreFindings = exports.DEFAULT_BANDS = exports.COMBINATIONS = exports.pdfPlugin = exports.passThrough = exports.writableSink = exports.fileSource = exports.fileSink = exports.bufferSource = exports.bufferSink = exports.allFindingSpecs = exports.inspectPdfSource = exports.inspectPdf = exports.disarmPdfSource = exports.disarmPdf = exports.detectPdfSource = exports.detectPdf = exports.tsvPlugin = exports.jsonPlugin = exports.csvPlugin = void 0;
 var data_plugins_1 = require("./data-plugins");
 Object.defineProperty(exports, "csvPlugin", { enumerable: true, get: function () { return data_plugins_1.csvPlugin; } });
 Object.defineProperty(exports, "jsonPlugin", { enumerable: true, get: function () { return data_plugins_1.jsonPlugin; } });
 Object.defineProperty(exports, "tsvPlugin", { enumerable: true, get: function () { return data_plugins_1.tsvPlugin; } });
+var detect_1 = require("./detect");
+Object.defineProperty(exports, "detectPdf", { enumerable: true, get: function () { return detect_1.detectPdf; } });
+Object.defineProperty(exports, "detectPdfSource", { enumerable: true, get: function () { return detect_1.detectPdfSource; } });
 var engine_1 = require("./engine");
 Object.defineProperty(exports, "disarmPdf", { enumerable: true, get: function () { return engine_1.disarmPdf; } });
 Object.defineProperty(exports, "disarmPdfSource", { enumerable: true, get: function () { return engine_1.disarmPdfSource; } });

package/dist/index.mjs

@@ -1,3 +1,3 @@
 import cjs from './index.js';
-export const { csvPlugin, jsonPlugin, tsvPlugin, disarmPdf, disarmPdfSource, inspectPdf, inspectPdfSource, allFindingSpecs, bufferSink, bufferSource, fileSink, fileSource, writableSink, passThrough, pdfPlugin, COMBINATIONS, DEFAULT_BANDS, scoreFindings, PdfCategory, PdfDetail, PdfRisk } = cjs;
+export const { csvPlugin, jsonPlugin, tsvPlugin, detectPdf, detectPdfSource, disarmPdf, disarmPdfSource, inspectPdf, inspectPdfSource, allFindingSpecs, bufferSink, bufferSource, fileSink, fileSource, writableSink, passThrough, pdfPlugin, COMBINATIONS, DEFAULT_BANDS, scoreFindings, PdfCategory, PdfDetail, PdfRisk } = cjs;
 export default cjs;

package/dist/plugins.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.passThrough = passThrough;
 exports.pdfPlugin = pdfPlugin;
+const detect_1 = require("./detect");
 const engine_1 = require("./engine");
 const score_1 = require("./score");
 const sniff_1 = require("./sniff");
@@ -36,8 +37,9 @@ function pdfPlugin(options) {
     return {
         kind: 'file',
         name: 'pdf',
-        // It can only read PDF bytes, so the content decides, whatever the name says.
-        accepts: f => f.sniffedType === 'application/pdf',
+        // It takes what detectPdf finds to be a PDF: a header in the first 1024 bytes, or no header, a name or declared
+        // type that says PDF, and content that opens as one.
+        accepts: async (f) => f.sniffedType === 'application/pdf' || (await (0, detect_1.detectPdfSource)(f.source, { name: f.name, declaredType: f.declaredType })) !== undefined,
         async process(file, sink, context) {
             const run = options ?? context[walker_1.RUN_OPTIONS] ?? {};
             const r = await (0, engine_1.disarmAtDepth)(file.source, sink, run, context.depth, context.deadline);

package/dist/types.d.ts

@@ -298,3 +298,30 @@ export interface PdfOptions {
      */
     preserveSignatures?: boolean;
 }
+/**
+ * A file's format as a package of the family finds it, among the formats that package reads. The family's router asks
+ * each package and routes the file by the answers.
+ */
+export interface FormatDetection {
+    /** The format's MIME type, such as application/pdf. */
+    mimeType: string;
+    /** The format's usual extension, lowercase and without the dot. */
+    extension: string;
+    /** Where the format starts in the file: 0, or the offset of its data when other data comes first. */
+    offset: number;
+    /** Set when the match rests on more than the content, and says what it rests on. */
+    heuristic?: string;
+}
+/** What a detect function may know of a file besides its content. */
+export interface DetectOptions {
+    /** The file's name, as the upload or the container that holds it gives it. */
+    name?: string;
+    /** The MIME type the upload or the container declares. */
+    declaredType?: string;
+    /** The Date.now() value detection must finish by, as `PluginContext.deadline`. */
+    deadline?: number;
+    /** Folder for temporary files. Defaults to `os.tmpdir()`. */
+    tempDir?: string;
+    /** Bytes held in memory before a temporary file takes over. */
+    memoryThreshold?: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patrickdk77/pdf-defuse",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Sanitize and clean PDF files. Detects and removes JavaScript, attached files, launch actions, unsafe links and empty-password encryption, scores the risk, and writes a disarmed copy with bounded memory and no runtime dependencies.",
   "license": "MIT",
   "author": "patrickdk77",