@patrickdk77/pdf-defuse 0.0.0-stage → 0.1.0

package/dist/uri.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LabelSites = void 0;
+exports.checkUri = checkUri;
+exports.hostsIn = hostsIn;
+const types_1 = require("./types");
+const IPV4 = /^\d{1,3}(\.\d{1,3}){3}$/;
+/** A host as LabelSites compares it. */
+const siteName = (h) => h
+    .toLowerCase()
+    .replace(/^www\./, '')
+    .replace(/\.$/, '');
+/**
+ * The hosts a label names, as a lookup: has() answers whether a host is one of them or a subdomain of one, or one of
+ * them is a subdomain of the host, at a cost that depends on the host and not on how many the label names. No
+ * public-suffix list is needed: evil.co.uk is not under mybank.co.uk.
+ */
+class LabelSites {
+    hosts = new Set();
+    /** Every domain some label host is a subdomain of. */
+    parents = new Set();
+    constructor(names) {
+        for (const n of names) {
+            const x = siteName(n);
+            this.hosts.add(x);
+            for (let i = x.indexOf('.'); i >= 0; i = x.indexOf('.', i + 1))
+                this.parents.add(x.slice(i + 1));
+        }
+    }
+    get size() {
+        return this.hosts.size;
+    }
+    has(host) {
+        const y = siteName(host);
+        if (this.hosts.has(y) || this.parents.has(y))
+            return true;
+        for (let i = y.indexOf('.'); i >= 0; i = y.indexOf('.', i + 1))
+            if (this.hosts.has(y.slice(i + 1)))
+                return true;
+        return false;
+    }
+}
+exports.LabelSites = LabelSites;
+/**
+ * Classifies a link target. `base` is the catalog's URI Base, if any. The walker compares a safe target's `sites`
+ * with the hosts a link's labels name.
+ */
+function checkUri(rawUri, base) {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: removes the control characters a browser drops from a URL.
+    let uri = rawUri.trim().replace(/[\x00-\x1f\x7f]/g, '');
+    if (uri.startsWith('\\\\') || uri.startsWith('//') || uri.startsWith('\\/') || uri.startsWith('/\\'))
+        return { detail: types_1.PdfDetail.NetworkPath };
+    let m = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(uri);
+    let www;
+    if (!m) {
+        // pdf.js reads "www." with two or more dots as an http address before any base applies. Both readings must pass.
+        if (uri.startsWith('www.') && (uri.match(/\./g)?.length ?? 0) >= 2) {
+            const v = checkUri(`http://${uri}`);
+            if (v.detail !== types_1.PdfDetail.Safe)
+                return v;
+            www = v.host;
+        }
+        if (base) {
+            const b = checkUri(base);
+            if (b.detail !== types_1.PdfDetail.Safe)
+                return { detail: types_1.PdfDetail.Relative };
+            try {
+                uri = new URL(uri, base.trim()).toString();
+                m = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(uri);
+            }
+            catch {
+                return { detail: types_1.PdfDetail.Relative };
+            }
+        }
+        if (!m)
+            return { detail: types_1.PdfDetail.Relative };
+    }
+    const scheme = m[1].toLowerCase();
+    if (scheme === 'javascript' || scheme === 'vbscript')
+        return { detail: types_1.PdfDetail.Url };
+    if (scheme === 'data')
+        return { detail: types_1.PdfDetail.DataUrl };
+    if (scheme === 'smb' || scheme === 'cifs' || scheme === 'afp' || scheme === 'nfs')
+        return { detail: types_1.PdfDetail.NetworkPath };
+    if (scheme === 'file') {
+        let host = '';
+        try {
+            host = new URL(uri).hostname;
+        }
+        catch {
+            /* treat as local */
+        }
+        if (host && host.toLowerCase() !== 'localhost')
+            return { detail: types_1.PdfDetail.NetworkPath };
+        return { detail: types_1.PdfDetail.FileUrl };
+    }
+    if (scheme === 'mailto') {
+        let addr = uri.slice(7).split('?')[0];
+        try {
+            addr = decodeURIComponent(addr);
+        }
+        catch {
+            /* keep the address as written */
+        }
+        const domain = addr.includes('@') ? addr.slice(addr.lastIndexOf('@') + 1).toLowerCase() : '';
+        const v = hostVerdict(domain, domain);
+        return v ?? { detail: types_1.PdfDetail.Safe, host: domain, sites: www ? [www, domain] : [domain] };
+    }
+    if (scheme !== 'http' && scheme !== 'https')
+        return { detail: types_1.PdfDetail.OtherScheme };
+    // Raw authority, as written, before the URL parser normalizes it.
+    const rawAuth = /^[a-zA-Z]+:[\\/]*([^/\\?#]*)/.exec(uri)?.[1] ?? '';
+    let parsed;
+    try {
+        parsed = new URL(uri);
+    }
+    catch {
+        return { detail: types_1.PdfDetail.OtherScheme };
+    }
+    if (parsed.username || parsed.password || rawAuth.includes('@'))
+        return { detail: types_1.PdfDetail.Credentials };
+    // The parser lowercases, punycodes and turns every IPv4 shorthand into dotted form, as browsers do.
+    const host = parsed.hostname.replace(/\.$/, '');
+    const v = hostVerdict(host, rawAuth);
+    return v ?? { detail: types_1.PdfDetail.Safe, host, sites: www ? [www, host] : [host] };
+}
+function hostVerdict(host, raw) {
+    if (!host)
+        return { detail: types_1.PdfDetail.OtherScheme };
+    if (raw.includes('%'))
+        return { detail: types_1.PdfDetail.EncodedHost };
+    if (host.startsWith('[') || IPV4.test(host))
+        return { detail: types_1.PdfDetail.IpHost };
+    if (/^\d+$/.test(host) || /^0x[0-9a-f]+$/i.test(host))
+        return { detail: types_1.PdfDetail.IpHost };
+    if (/\P{ASCII}/u.test(host) || host.split('.').some(label => label.startsWith('xn--')))
+        return { detail: types_1.PdfDetail.LookalikeHost };
+    return undefined;
+}
+/** Host names written in free text, such as a tooltip. */
+function hostsIn(text) {
+    const out = [];
+    // The first lookahead caps a candidate at a DNS name's length, so a long run of host characters costs linear time.
+    // A host ends at any character that cannot continue it, after any dots, except "@" or "_", which make it part of
+    // an address or a name.
+    const re = /\b(?:https?:\/\/)?(?=[a-z0-9.-]{1,254}(?![a-z0-9.-]))((?:[a-z0-9-]+\.)+[a-z]{2,})(?=\.*(?:[^a-z0-9.@_-]|$))/gi;
+    for (let m = re.exec(text); m; m = re.exec(text))
+        out.push(m[1].toLowerCase());
+    return out;
+}

package/dist/walker.d.ts

@@ -0,0 +1,302 @@
+import { type PdfDocument } from './document';
+import { type FindingFactory } from './findings';
+import { type TempDir } from './io';
+import { type ByteSink, type DefuseFinding, type PdfOptions, type PluginContext } from './types';
+/** A script or file a plugin kept, as the output verification expects to meet it again. */
+interface KeptItem {
+    result: 'passed' | 'scrubbed';
+    plugin: string;
+    /** For a file: the findings inside the kept bytes, which go into the output's report. */
+    findings?: DefuseFinding[];
+}
+export interface VerifyExpectations {
+    /** Keyed by script text. */
+    scripts: Map<string, KeptItem>;
+    /** Keyed by the MD5 of the decoded file. */
+    files: Map<string, KeptItem>;
+}
+interface WalkerConfig {
+    options: PdfOptions;
+    depth: number;
+    temp: TempDir;
+    factory: FindingFactory;
+    verify?: VerifyExpectations;
+    deadline?: number;
+}
+/** Thrown when a contained file plugin's nested run hits the nesting limit. The code makes every package pass it up. */
+export declare class NestingLimitError extends Error {
+    readonly code = "DEFUSE_LIMIT";
+    readonly limit = "nesting";
+}
+/** An I/O error inside an attached PDF's own run, carried up so the upload's run fails on it as on its own. */
+export declare class NestedIoError extends Error {
+    readonly code = "DEFUSE_IO";
+    constructor(cause: unknown);
+}
+/**
+ * The code of an error that stops the whole tree of files, from any package: DEFUSE_LIMIT for a time or nesting
+ * limit, DEFUSE_IO for an I/O error. Packages cannot share error classes, so the code alone marks one.
+ */
+export declare function stopsTree(e: unknown): 'DEFUSE_LIMIT' | 'DEFUSE_IO' | undefined;
+/** The key under which the walker hands its run's options to a plugin. No other package can name it. */
+export declare const RUN_OPTIONS: unique symbol;
+/** A plugin context as the walker makes it. */
+export type RunContext = PluginContext & {
+    [RUN_OPTIONS]?: PdfOptions;
+};
+export declare class Walker {
+    private readonly doc;
+    private readonly cfg;
+    readonly findings: DefuseFinding[];
+    /** A time or nesting limit a plugin threw, which a nested run passes up instead of reporting. */
+    passedOn?: unknown;
+    pages: number;
+    /** Per page, the total length of its content streams, for verifying the output. */
+    pageContent: number[];
+    /** Scripts and files kept by plugins, for verifying the output. */
+    readonly kept: VerifyExpectations;
+    /** Actions with a script down their chains, once fully read, which a further slot asks about again. */
+    private readonly scriptActions;
+    /**
+     * Where the walk first removed something, found by comparing what it would write with what it read. The engine
+     * never passes an upload through unchanged once this is set.
+     */
+    removedAt?: string;
+    /**
+     * Set when a signature field the walk reached holds a signature over every byte of the file but its own /Contents,
+     * so nothing was added after signing.
+     */
+    signed: boolean;
+    private phase;
+    private readonly perKey;
+    private readonly aggregates;
+    private readonly pageInfo;
+    /** Pages written directly in /Kids, by the owner and path the walk reaches them at. */
+    private readonly inlinePages;
+    /** Objects first reached as file specifications, which stay file specifications whatever their content says. */
+    private readonly fileRole;
+    /** Objects listed in /Annots and kept there though they are not annotations, which get the annotation rules. */
+    private readonly annotRole;
+    /** Objects that only removed content refers to, which are not unreferenced. */
+    private readonly reached;
+    /** Pages in document order: an object number, or the dictionary of a page written directly in /Kids. */
+    private readonly pageOrder;
+    /** Objects whose role comes from the referrer that defines it, whatever else reaches them first. */
+    private rootNum?;
+    private namesNum?;
+    private infoNum?;
+    /** Slots that lose their reference to a shared object that other slots keep. Keyed by owner and path. */
+    private readonly refusedSlots;
+    /** Bumped each time a script is asked again for another slot and would not be kept there. */
+    private refusals;
+    /** The refusals that reported nothing themselves: past the work budget, or for a different rewrite. */
+    private quiet;
+    private deciding;
+    /**
+     * Actions and additional-actions dictionaries with no script anywhere down their chains, once fully read. Only a
+     * script can be decided differently for another slot, so these are never asked about again.
+     */
+    private readonly scriptFree;
+    /** Work allowed for deciding shared scripts again, in units: 1024 per slot, 64 per step down a chain, 1 per 16 decoded bytes. */
+    private againBudget;
+    /** A script's findings from visits of removed content, held until the walk ends so a later real visit that keeps it can correct them. */
+    private readonly shadowScripts;
+    /** Information dictionaries and XMP streams removed for the caller. */
+    private readonly strippedMeta;
+    /** Bytes of scrubbed attachments held in memory until the write. */
+    private retained;
+    /** A second name for a contained file whose content was already decided, by stream number and name. */
+    private readonly nameDecisions;
+    /** Per annotation, the first page that shows it, and the smallest page box among the pages that show it. */
+    private readonly annotPage;
+    /**
+     * Per annotations array, keyed by the owner and path the walk reaches it at: the first page that shows it, and the
+     * smallest page box among the pages that show it, whether as their own /Annots or inherited.
+     */
+    private readonly annotLists;
+    private readonly altText;
+    private readonly special;
+    private order;
+    private readonly visited;
+    private readonly shadowVisited;
+    private readonly dropped;
+    /** `slot` is the owner and path of an ordinary key that queued the reference. */
+    private queue;
+    private qhead;
+    private readonly scriptDecisions;
+    /**
+     * `types` is set when the content went through the type check, so a further name can be checked against it:
+     * `name` is the name the content was decided under, and `plugin` the plugin that decided it. `size` is known once
+     * the whole file was decoded, which happens only when a plugin or the output check reads it. `decoded` is the
+     * content decoded again for the further names, once a plugin read it under one, until the walk ends.
+     */
+    private readonly fileDecisions;
+    private readonly jsReplace;
+    private jsTree?;
+    private efTree?;
+    private readonly keptDocScripts;
+    /** What a link's label check found, by chain object and a hash of the labels: a finding's data, or null. */
+    private readonly labelChecks;
+    /** Per web link action object, the hosts a label is compared with and the address each comes from. */
+    private readonly chainSites;
+    private readonly keptCalcFields;
+    /** Set once a field's calculation script is removed, so the calculation order is narrowed. */
+    private calcRemoved;
+    /** The fields the calculation order lists, by object number. */
+    private readonly coFields;
+    private coPresent;
+    private readonly treeNodes;
+    private uriBase?;
+    private readonly newNum;
+    private synthJs;
+    private synthEf;
+    constructor(doc: PdfDocument, cfg: WalkerConfig);
+    private get options();
+    private emit;
+    /**
+     * Records a finding whose action is final. Past 200 of one kind, further ones only raise a count, on a finding
+     * that carries the strictest action among those it counts.
+     */
+    private push;
+    /**
+     * Reports content that goes whatever the overrides say, such as a slot refused past the work budget. Its action is
+     * strip, or reject when the caller asked for that.
+     */
+    private emitRemoval;
+    /**
+     * Adds the findings a plugin reported from inside a contained file, labeled with the file's name and place.
+     * A reject inside the file means the file goes, not the upload, so it is recorded here as strip.
+     */
+    private pushContained;
+    /**
+     * Throws on an error a plugin threw that stops the whole tree. An I/O error fails this run as one of its own would,
+     * so its cause goes up.
+     */
+    private passOn;
+    private aggregate;
+    analyze(): Promise<void>;
+    private enqueue;
+    private drain;
+    /**
+     * A slot that reaches an action through a key the action rules do not cover, such as the /A of a dictionary of no
+     * known kind. Readers run the action from there, so a script down its chain, decided from another slot, is asked
+     * about again for this one.
+     */
+    private reachAgain;
+    /** An action's type as readers read it, resolving an /S that is a reference. */
+    private actionType;
+    /** Follows references, as far as 32, to a value and the number of the object that holds it. */
+    private lastRef;
+    /** Visits one indirect object: findings, keep or drop, children. */
+    private processRef;
+    /**
+     * Marks what removed content refers to, so it does not count as unreferenced. Nothing is reported or decided: what
+     * only removed content reaches is not written either way, and a real visit still reads it.
+     */
+    private reach;
+    /** A rectangle as pdf.js reads one: four numbers, the array and each number resolved one level, with an area. */
+    private box;
+    /**
+     * Reads the page tree in document order as pdf.js does, and records which page every annotation sits on. What a
+     * page inherits comes up its /Parent chain, as readers look it up.
+     */
+    private walkPageTree;
+    /** Maps annotations to the alt text of the structure element that holds them. */
+    private buildAltText;
+    /**
+     * Collects name-tree entries with any key form: strings, names or references to them. pdf.js reads an entry whatever
+     * its key, so any other key is reported and read as an empty string, and its entry is collected all the same.
+     */
+    private collectNameTree;
+    private prepassDocumentScripts;
+    private postWalk;
+    /** Total content-stream length of every page, so the output can be checked page by page. */
+    contentSignature(): Promise<number[]>;
+    /**
+     * What an object is: the catalog and the pages by the role the trailer and the page tree give them, anything
+     * else by its content. A page whose content is an annotation stays an annotation, so the annotation rules apply.
+     */
+    private kindOf;
+    private transformTop;
+    /**
+     * Whether no script lies down an action's chain. A reference counts only once its object was read to the end of its
+     * own chain, so a chain that loops back counts as holding one.
+     */
+    private scriptFreeChain;
+    /** Transforms any value. Returns undefined when the value must be removed. */
+    private tv;
+    /** Rules every dictionary gets, applied to the keys a specific handler did not take. */
+    private handleGeneric;
+    private handleCatalog;
+    /**
+     * `num` is undefined for a page written directly in /Kids. `node` is a /Pages node, whose /Annots and /AA its pages
+     * inherit, as pdf.js reads them.
+     */
+    private handlePage;
+    /** Keeps only references to real, kept annotations. */
+    private handleAnnotsArray;
+    private handleOutline;
+    private handleNames;
+    private handleAcroForm;
+    private handleField;
+    /** Whether a signature value covers every byte of the file but its own /Contents, which sits right after its key. */
+    private signsWholeFile;
+    private handleAnnot;
+    /**
+     * A link whose tooltip or alt text names a different site than a web address its click opens. Readers perform
+     * the /Next actions too, so the whole chain is checked; a chain too long to check counts as a mismatch.
+     */
+    private labelMismatch;
+    /** Walks content being removed, so its findings are still reported. */
+    private shadowScan;
+    /**
+     * A reference that must lead to an action. Anything else loses the reference but is not dropped,
+     * since it may be legitimate where else it is used. In additional-actions dictionaries only kept scripts stay.
+     */
+    private actionRef;
+    /**
+     * For a slot that reaches an object already decided from another slot: `run` asks the plugins again under this
+     * slot's trigger. The object keeps its first decision, and this slot loses its reference when a script under it
+     * would not be kept here. Past a set budget of this work, the slot loses it without asking.
+     */
+    private decideForSlot;
+    /**
+     * An annotation, catalog, page or names dictionary whose content also makes it an action runs as that action
+     * from any slot that points at it. Its action keys get the action rules. When those remove the action, /S goes,
+     * so no reader runs it.
+     */
+    private alsoAction;
+    private handleAA;
+    /**
+     * Decodes a script only when something will read it, and never past the memory threshold. `num` is the object
+     * that holds the text, at the end of any chain of references, so a rewrite lands where a reader looks.
+     */
+    private scriptText;
+    /**
+     * Runs the script plugins. Returns whether the script stays. A script already decided under `key` is asked about
+     * again for another trigger that reaches it: it keeps its first decision, and a different answer counts as a refusal.
+     */
+    private decideScript;
+    /** `rest` false handles only the action's own keys (/S, /JS, /Next), for an object that is also something else. */
+    private handleAction;
+    private handleFilespecList;
+    /**
+     * A value whose key makes it a file specification, under /FS, /AF or the EmbeddedFiles tree. That key decides what
+     * it is, whatever its content also looks like, so its file is always decided; only the catalog, a page and the
+     * names and information dictionaries keep the roles they have.
+     */
+    private handleFilespecValue;
+    private handleFilespec;
+    /**
+     * Decodes a contained file and runs the file plugins. The content is decided once per embedded file stream; every
+     * further name that reaches it is still checked against that content.
+     */
+    private decideFile;
+    /** Writes the kept objects as a new single-revision PDF. */
+    write(sink: ByteSink): Promise<void>;
+    private writeStream;
+    /** Frees per-object state once the output is written; only the plugin expectations stay. */
+    releaseState(): Promise<void>;
+    cleanup(): Promise<void>;
+}
+export {};