@patrickdk77/pdf-defuse 0.2.3 → 0.3.0

package/README.md

@@ -67,12 +67,24 @@ Removed by default:
 
 - JavaScript wherever it lives: document scripts, open actions, page, annotation and field triggers, links, bookmarks, chained actions and media actions.
 - Actions that reach outside the document: launching programs, links to other or embedded files, form submit and import, show and hide toggles, layer toggles, menu commands and media.
-- Links other than http, https and mailto, and links built to mislead. That covers credentials before the host, IP hosts, punycode or mixed-script hosts, encoded hosts, tooltips or alternate text that name a different site, links and push buttons that cover most of a page, and relative links with no base address.
-- Attached files, portfolios, XFA forms, slideshows, media and 3D annotations, and annotation types outside an allowlist.
+- Links other than http, https and mailto, and links built to mislead. That covers credentials before the host, IP hosts, punycode or mixed-script hosts, encoded hosts, tooltips or alternate text that name a different site, links and push buttons that cover most of a page, and relative links whose path is written to read as another path.
+- Attached files, portfolios, slideshows, media and 3D annotations, and annotation types outside an allowlist.
+- From XFA forms, the scripts no plugin keeps, submits, web service calls, data connections, external objects and anything that names a file or address outside the PDF. The form itself stays, as XFA forms below describes.
 - Encryption with an empty password, or with a password you pass.
 - Earlier revisions, unreferenced objects and damaged structure. The output is one clean revision, unless it is a signed file that keeps its bytes, as described below.
 
-Kept: text, images, fonts, layout, bookmarks, form fields and their values, safe links and metadata.
+Kept: text, images, fonts, layout, bookmarks, form fields and their values, XFA forms and their data, safe links, relative links and metadata.
+
+A relative link is an ordinary way to point at a file beside the PDF, so it stays and LINK/RELATIVE reports it as `info`. Climbing with `..` from the start, as `../manual/page.html` does, is ordinary too. LINK/PATH_TRICK removes a relative link whose path is written to read as another path, and its `reason` says which of these it found:
+
+- a control character, which readers drop before they read the address;
+- a backslash, which browsers read as a slash;
+- an encoded dot, slash, backslash or NUL;
+- a segment of only dots and spaces, which Windows reads as `..` or as nothing;
+- a path that names a folder and then climbs above where it started;
+- a colon in the first segment, which reads as a scheme once the address is decoded, as `%6Aavascript:` does.
+
+The catalog's `/URI /Base` stays in the output, so a relative link resolved against a hostile base gets the base's verdict. A link given as a name has two readings, `/x` and `x`, and both must pass. Override LINK/RELATIVE to `strip` to remove relative links as well.
 
 Every file that is not rejected is rewritten, so the output holds only what pdf-defuse read. That includes a file with nothing to remove, whose status stays `clean`.
 
@@ -86,6 +98,23 @@ A rewrite invalidates a signature, so a signed file can keep its bytes instead.
 
 Before anything reaches your sink, pdf-defuse inspects its own output. It rejects the file if anything removable is left, if the page count changed, or if any page's content changed length.
 
+## XFA forms
+
+An XFA form keeps its layout, its fields, its data and the scripts a plugin keeps. pdf-defuse reads the form's XML from the `/XFA` stream or packet array and removes everything else that can act:
+
+- Every `<script>` in the template and form packets goes to the script plugins with `form: 'xfa'` and a `language` of `javascript` or `formcalc`. XFA reads a script with no content type as FormCalc, and so does pdf-defuse. The trigger is `xfa-` and the event, such as `xfa-click`, `xfa-calculate` or `xfa-script-object`, and `fieldName` holds the SOM path of the node the script belongs to. JAVASCRIPT/XFA reports each script. pdf-defuse empties a script no plugin keeps and leaves its element in place. A script in another language, or one with markup inside it, goes whatever the overrides say.
+- `<submit>` goes as ACTION/SUBMIT_FORM, `<execute>` as FORM/XFA_EXECUTE and `<exObject>` as FORM/XFA_EXTERNAL_OBJECT. `<connect>` goes as FORM/XFA_CONNECTION, and so does every connection in the connectionSet but the schema's `xsdConnection`.
+- FORM/XFA_EXTERNAL_REFERENCE removes what points outside the PDF. That is an `href` holding an address or an absolute path, a `usehref` to another file, the `url` and `server` attributes of the template, the schema connection's `<uri>`, and the config's `uri`, `submitUrl`, `xsl`, `outputXSL` and `base`. In government forms these are mostly paths on the designer's own machine. A relative image name such as `.\logo.png` or `..\images\seal.png` stays unless it is written to read as another path, by the rules LINK/PATH_TRICK uses, and such a name goes as FORM/XFA_EXTERNAL_REFERENCE. XFA names are Windows paths, so a backslash there separates folders.
+- A rich text link, `<a href>`, gets the checks a link action gets and the same LINK findings, so a relative one stays. An unsafe link loses its `href` and keeps its text.
+- An inline image goes to the file plugins the way an attached file does, whether it sits in the template, the form packet or a data value with an image type. Viewers decode these images with decoders of their own, and CVE-2010-0188 reached one with a crafted TIFF. FORM/XFA_IMAGE removes an image no plugin takes. FORM/PLUGIN_PASSED, PLUGIN_SCRUBBED, PLUGIN_REMOVED and PLUGIN_FAILED report what a plugin did with one.
+- pdf-defuse keeps the template, datasets, config, localeSet, connectionSet, form and xmpmeta packets, and drops xmpmeta under `stripMetadata`. Every other packet goes as FORM/XFA_PACKET, stylesheet, pdf, xfdf, sourceSet and signature among them. A packet stream left empty leaves the packet array, name and all.
+
+pdf-defuse writes each changed packet stream back compressed and keeps the catalog's `/NeedsRendering`, so a dynamic form still draws from its XFA. A changed template no longer matches the form packet's checksum, so a viewer merges the template and the data again. The values a user entered live in the data and stay.
+
+The reader is strict. The XML must be UTF-8 and well formed, under one `xdp` root element. A DOCTYPE, an entity other than the five XML defines, or anything else it cannot read exactly as a viewer would removes the whole form as FORM/XFA_UNREADABLE, whatever the overrides say. A packet array that holds anything but streams goes the same way. The reader takes the whole form into memory, so `memoryThreshold` does not apply to it. `limits.decompressedBytes` caps each packet.
+
+FORM/XFA is `info` and only reports the form. Override it to `strip` to remove every XFA form whole, as 0.2.3 did. `/NeedsRendering` goes with it.
+
 ## Findings
 
 Every finding has two enums and a string. `category` is the kind, such as `ENCRYPTED` or `JAVASCRIPT`. `detail` is the exact variant, such as `EMPTY_PASSWORD` or `OPEN_ACTION`. `description` is a plain sentence that is safe to show the uploader. A description can name the attached file it is about. pdf-defuse cuts that name to 60 characters and replaces control and direction characters with `?`, and `data` keeps the name whole.
@@ -95,7 +124,7 @@ Every finding has two enums and a string. `category` is the kind, such as `ENCRY
 { category: 'ENCRYPTED', detail: 'RC4_40', description: 'Encryption is RC4 with a 40-bit key', action: 'info' }
 ```
 
-`action` says what happens: `reject` refuses the file, `strip` removes the content and `info` only reports it. An override to `strip` removes the content for METADATA/XMP, METADATA/INFO_DICTIONARY, LINK/SAFE and EMBEDDED_FILE/TYPE_MISMATCH. Some `info` findings name content that every rewrite drops anyway, such as SIGNATURE/USAGE_RIGHTS, STRUCTURE/ESCAPED_NAMES and the ENCRYPTED findings that name the algorithm. A `strip` override on one of those changes only the status. The other `info` findings, such as FORM/FIELDS, SIGNATURE/SIGNED, STRUCTURE/VERSION_UPGRADED and the PLUGIN_PASSED and PLUGIN_SCRUBBED findings, name nothing that can be removed. A `strip` override on one of them leaves the finding in the output, so the output fails its own inspection and the upload is rejected.
+`action` says what happens: `reject` refuses the file, `strip` removes the content and `info` only reports it. An override to `strip` removes the content for METADATA/XMP, METADATA/INFO_DICTIONARY, LINK/SAFE, LINK/RELATIVE and EMBEDDED_FILE/TYPE_MISMATCH. Some `info` findings name content that every rewrite drops anyway, such as SIGNATURE/USAGE_RIGHTS, STRUCTURE/ESCAPED_NAMES and the ENCRYPTED findings that name the algorithm. A `strip` override on one of those changes only the status. The other `info` findings, such as FORM/FIELDS, SIGNATURE/SIGNED, STRUCTURE/VERSION_UPGRADED and the PLUGIN_PASSED and PLUGIN_SCRUBBED findings, name nothing that can be removed. A `strip` override on one of them leaves the finding in the output, so the output fails its own inspection and the upload is rejected.
 
 Some content goes whatever an override says. Its finding then shows `strip`, or `reject` if you override it to that. This covers a script reference an action loses under the re-checking rules described under Plugins, a reference to an object stream or cross-reference stream, and an attached file a plugin removed or failed on, or that the password does not decrypt. It also covers any other stream encrypted with a key the password does not give, which ENCRYPTED/NO_KEY reports. It also covers a reference in `/Annots` to an object that already has another role, and a reference to a file specification that is the catalog, a page, or the names or information dictionary and carries an embedded file. Such an object keeps its role and its own entries, `/EF` included, so that embedded file stays in the output. Only the reference that treated the object as a file specification goes.
 
@@ -111,6 +140,8 @@ The score runs from 0 to 100. Each kind of finding has a weight: a launch action
 
 `scoreWeights` comes first, then the built-in weights. A kind of finding pdf-defuse does not know, such as one another package's plugin returned, scores at its `weight`, or 0 without one.
 
+A script or file a plugin answered for scores only by the findings the plugin returned, at their weights. pdf-defuse adds nothing of its own for it, and the PLUGIN_PASSED and PLUGIN_SCRUBBED findings that record the answer weigh 0, in the upload's score and in the output's. A form whose scripts a plugin keeps, and in which the plugin finds nothing, scores 0. With no plugin to judge them, the same scripts score at pdf-defuse's own weights.
+
 The bands are NONE at 0, LOW from 1, MEDIUM from 25, HIGH from 50 and CRITICAL from 80.
 
 A run that stops before it has seen the whole file rejects the file with a null score and the UNKNOWN level. Runs stop at a limit, at encryption they cannot open, and at a file they cannot parse or that ends before its trailer. A file with no page to read gets the same result. This holds whatever `actionOverrides` say, because an override can make the finding that stopped the run look harmless. A file rejected for what it holds, for example JavaScript under an override that rejects it, keeps its score. So does a file whose output failed its own inspection.
@@ -128,7 +159,7 @@ A run that stops before it has seen the whole file rejects the file with a null
 | `scoreWeights`, `scoreBands` | built in | Change the scoring |
 | `filePlugins`, `scriptPlugins` | none | Keep chosen attached files or scripts |
 | `tempDir` | `os.tmpdir()` | Where temporary files go |
-| `memoryThreshold` | 8 MiB | `disarmPdfSource` keeps its copy of the upload in memory up to this size and in a temporary file above it. Each decoded attachment above this size goes through a temporary file. Decoded object streams share this much memory, and the ones that do not fit go to temporary files, so each is decoded once. A decoded attachment's file is deleted once its plugins have decided it. Scrubbed attachment copies waiting for the write, and an attachment decoded again so a plugin can check its further names, share this much memory between them. One that does not fit goes to a temporary file. A script that decodes larger than this is removed without going to the script plugins |
+| `memoryThreshold` | 8 MiB | `disarmPdfSource` keeps its copy of the upload in memory up to this size and in a temporary file above it. Each decoded attachment above this size goes through a temporary file. Decoded object streams share this much memory, and the ones that do not fit go to temporary files, so each is decoded once. A decoded attachment's file is deleted once its plugins have decided it. Scrubbed attachment copies waiting for the write, and an attachment decoded again so a plugin can check its further names, share this much memory between them. One that does not fit goes to a temporary file. A script that decodes larger than this is removed without going to the script plugins. An XFA form goes into memory whole |
 | `preserveSignatures` | `true` | Keep the bytes of a clean file that is signed over all of it, as described under What it removes and what it keeps. `false` rewrites it like any other file, which invalidates the signature |
 
 To reject every file that contains JavaScript instead of removing the scripts:
@@ -149,7 +180,9 @@ A file that encrypts only its attached files, through a crypt filter with `/Auth
 
 ## Plugins
 
-Attached files and scripts are removed unless a plugin keeps them. A plugin says which files or scripts it accepts, then scrubs them, passes them through unchanged, or removes them after all. The first plugin that accepts handles it. If a plugin throws, or scrubs and writes nothing, the item is removed. An error with a `DEFUSE_LIMIT` or `DEFUSE_IO` code stops the whole run instead, as described under The defuse family. A file plugin that passes a file keeps its original bytes, or the bytes it wrote to the sink if it wrote any.
+Attached files and scripts are removed unless a plugin keeps them. A plugin says which files or scripts it accepts, then scrubs them, passes them through unchanged, or removes them after all. The first plugin that accepts handles it. If a plugin throws, or scrubs and writes nothing, the item is removed.
+
+The plugin's answer is final. For a script, the report then holds JAVASCRIPT/PLUGIN_PASSED, PLUGIN_SCRUBBED or PLUGIN_REMOVED and the plugin's findings, and none of pdf-defuse's own, such as JAVASCRIPT/OPEN_ACTION. An attached file gets EMBEDDED_FILE/PLUGIN_PASSED, PLUGIN_SCRUBBED or PLUGIN_REMOVED and the plugin's findings. pdf-defuse reports an item itself only when no plugin answered: a script no plugin accepts gets its JAVASCRIPT finding, and one whose plugin failed gets that finding and JAVASCRIPT/PLUGIN_FAILED. A file no plugin accepts is EMBEDDED_FILE/NO_PLUGIN, and a file whose plugin failed is EMBEDDED_FILE/PLUGIN_FAILED, which weighs what NO_PLUGIN does. An error with a `DEFUSE_LIMIT` or `DEFUSE_IO` code stops the whole run instead, as described under The defuse family. A file plugin that passes a file keeps its original bytes, or the bytes it wrote to the sink if it wrote any.
 
 Five plugins are bundled:
 
@@ -210,7 +243,7 @@ const svgPlugin = {
 
 The third argument to `process` holds `depth`, the depth of the file itself, and `deadline` when `limits.timeMs` is set. `deadline` is the `Date.now()` value the whole run must finish by. `pdfPlugin` hands it to the attached PDF's run, so an upload and everything attached to it share one time limit. A plugin that keeps working past it delays the result, because the run is rejected for time only once the plugin returns.
 
-A script plugin receives each script with its trigger, location and field name. The text has its NUL characters removed, as pdf.js removes them before it runs a script. Document-level scripts arrive first, and each later script sees which of them were kept. Several actions can share one script object. Once a plugin keeps it, the plugins see it again for each other action that runs it, with that action's trigger. That includes an action reached through a key the action rules do not cover, such as the `/A` of a bookmark pdf-defuse does not recognize, which arrives with the trigger `unknown`. The script keeps its first answer. An action that gets a different answer, or a different rewrite, loses its reference to the script. Past a set amount of this re-checking, later actions lose the script without the plugins being asked. Every action that loses the script gets a `strip` finding at its own location. A chain of actions with no script in it is never checked again.
+A script plugin receives each script with its trigger, location, field name, `language` and `form`. `form` is `acroform` for the PDF's own scripts and `xfa` for an XFA form's, and only an XFA script can have the `language` `formcalc`. The text has its NUL characters removed, as pdf.js removes them before it runs a script. Document-level scripts arrive first, and each later script sees which of them were kept. Several actions can share one script object. Once a plugin keeps it, the plugins see it again for each other action that runs it, with that action's trigger. That includes an action reached through a key the action rules do not cover, such as the `/A` of a bookmark pdf-defuse does not recognize, which arrives with the trigger `unknown`. The script keeps its first answer. An action that gets a different answer, or a different rewrite, loses its reference to the script. Past a set amount of this re-checking, later actions lose the script without the plugins being asked. Every action that loses the script gets a `strip` finding at its own location. A chain of actions with no script in it is never checked again.
 
 ```js
 const scriptPlugin = {
@@ -221,6 +254,8 @@ const scriptPlugin = {
 };
 ```
 
+A script plugin can also return `findings` with its result, saying what it found in the script. They go into the report at the script's location, unless a finding gives a finer one, such as the line. A `reject` among them is recorded as `strip`, since the plugin decides one script, not the file. Their `weight` is what they add to the score. For a script the plugin passed, the output's report holds them again. [script-defuse](https://github.com/patrickdk77/script-defuse)'s `formScriptPlugin` keeps form calculations, formats and checks, and reports why it removed every other script.
+
 ## The defuse family
 
 pdf-defuse is meant to sit beside other packages that each defuse one kind of file, such as images, HTML, Office documents or archives. A master package routes each upload to the right one. A package that finds a file inside a file hands it back through the master's router, so a PDF in a ZIP in a PDF goes through the same router at every level.

package/dist/engine.js

@@ -62,7 +62,6 @@ function encryptionFindings(doc, factory) {
         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
@@ -75,8 +74,9 @@ function finish(findings, options, incomplete, version = '', pages, isOutput = f
     // 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);
+    // What a plugin decided counts at the weights of the plugin's own findings; the PLUGIN_* findings that record its
+    // answer weigh nothing.
+    const { score, risk } = (0, score_1.scoreFindings)(findings, options);
     return { status: rejected ? 'rejected' : strippable ? 'strippable' : 'clean', score, risk, findings, version, pages };
 }
 /**

package/dist/findings.js

@@ -45,8 +45,9 @@ def(types_1.PdfCategory.JavaScript, types_1.PdfDetail.Chained, 'strip', 50, 'Jav
 def(types_1.PdfCategory.JavaScript, types_1.PdfDetail.Rendition, 'strip', 50, 'A media action carries JavaScript');
 def(types_1.PdfCategory.JavaScript, types_1.PdfDetail.Url, 'strip', 50, 'A link uses a javascript: URL');
 def(types_1.PdfCategory.JavaScript, types_1.PdfDetail.Unattached, 'strip', 50, 'A JavaScript entry sits outside any action');
-def(types_1.PdfCategory.JavaScript, types_1.PdfDetail.PluginPassed, 'info', 40, 'JavaScript kept unchanged by plugin <plugin>');
-def(types_1.PdfCategory.JavaScript, types_1.PdfDetail.PluginScrubbed, 'info', 20, 'JavaScript rewritten and kept by plugin <plugin>');
+def(types_1.PdfCategory.JavaScript, types_1.PdfDetail.Xfa, 'strip', 50, 'An XFA form script, in <language>, runs on a form event');
+def(types_1.PdfCategory.JavaScript, types_1.PdfDetail.PluginPassed, 'info', 0, 'JavaScript kept unchanged by plugin <plugin>');
+def(types_1.PdfCategory.JavaScript, types_1.PdfDetail.PluginScrubbed, 'info', 0, 'JavaScript rewritten and kept by plugin <plugin>');
 def(types_1.PdfCategory.JavaScript, types_1.PdfDetail.PluginFailed, 'strip', 0, 'Plugin <plugin> failed, so the JavaScript was removed');
 def(types_1.PdfCategory.JavaScript, types_1.PdfDetail.PluginRemoved, 'strip', 0, 'JavaScript removed by plugin <plugin>');
 // ACTION
@@ -72,13 +73,14 @@ def(types_1.PdfCategory.Link, types_1.PdfDetail.LookalikeHost, 'strip', 40, "A l
 def(types_1.PdfCategory.Link, types_1.PdfDetail.EncodedHost, 'strip', 40, "A link's host is percent-encoded");
 def(types_1.PdfCategory.Link, types_1.PdfDetail.TextMismatch, 'strip', 40, "A link's tooltip names a different site");
 def(types_1.PdfCategory.Link, types_1.PdfDetail.FullPage, 'strip', 20, 'A link covers most of the page');
-def(types_1.PdfCategory.Link, types_1.PdfDetail.Relative, 'strip', 30, "A relative link with no base address, which resolves against the file's own location");
+def(types_1.PdfCategory.Link, types_1.PdfDetail.Relative, 'info', 0, "A relative link, which resolves against the file's own location");
+def(types_1.PdfCategory.Link, types_1.PdfDetail.PathTrick, 'strip', 40, 'A relative link whose path is written to read as another path<: {reason}|>');
 // EMBEDDED_FILE
 def(types_1.PdfCategory.EmbeddedFile, types_1.PdfDetail.NoPlugin, 'strip', 30, '<Attached file "{name}"|An attached file> (<{sniffed}|{type}|unknown type>) removed. No plugin accepts this type');
 def(types_1.PdfCategory.EmbeddedFile, types_1.PdfDetail.TypeMismatch, 'info', 40, 'The types of <attached file "{name}"|an unnamed attached file> disagree: <its name says {nameType}|its name has no known extension>, <it is declared {declared}|it has no declared type>, and <its content looks like {sniffed}|its content is not recognized>');
-def(types_1.PdfCategory.EmbeddedFile, types_1.PdfDetail.PluginPassed, 'info', 20, 'Attached file kept by plugin <plugin> with nothing removed');
-def(types_1.PdfCategory.EmbeddedFile, types_1.PdfDetail.PluginScrubbed, 'info', 10, 'Attached file cleaned and kept by plugin <plugin>');
-def(types_1.PdfCategory.EmbeddedFile, types_1.PdfDetail.PluginFailed, 'strip', 0, 'Plugin <plugin> failed, so the attached file was removed');
+def(types_1.PdfCategory.EmbeddedFile, types_1.PdfDetail.PluginPassed, 'info', 0, 'Attached file kept by plugin <plugin> with nothing removed');
+def(types_1.PdfCategory.EmbeddedFile, types_1.PdfDetail.PluginScrubbed, 'info', 0, 'Attached file cleaned and kept by plugin <plugin>');
+def(types_1.PdfCategory.EmbeddedFile, types_1.PdfDetail.PluginFailed, 'strip', 30, 'Plugin <plugin> failed, so the attached file was removed');
 def(types_1.PdfCategory.EmbeddedFile, types_1.PdfDetail.PluginRemoved, 'strip', 0, 'Attached file removed by plugin <plugin>');
 def(types_1.PdfCategory.EmbeddedFile, types_1.PdfDetail.Portfolio, 'strip', 30, 'PDF is a portfolio of files');
 // MEDIA
@@ -93,7 +95,18 @@ def(types_1.PdfCategory.Media, types_1.PdfDetail.Slideshow, 'strip', 30, 'Embedd
 def(types_1.PdfCategory.Annotation, types_1.PdfDetail.UnknownSubtype, 'strip', 30, 'An annotation of a type outside the allowlist');
 // FORM
 def(types_1.PdfCategory.Form, types_1.PdfDetail.Fields, 'info', 0, 'PDF has fillable form fields');
-def(types_1.PdfCategory.Form, types_1.PdfDetail.Xfa, 'strip', 40, 'PDF has an XFA form, which carries its own scripts');
+def(types_1.PdfCategory.Form, types_1.PdfDetail.Xfa, 'info', 10, 'PDF has an XFA form. Its scripts, links and connections are checked like the rest of the file');
+def(types_1.PdfCategory.Form, types_1.PdfDetail.XfaUnreadable, 'strip', 40, 'An XFA form that could not be read exactly was removed whole: <reason>');
+def(types_1.PdfCategory.Form, types_1.PdfDetail.XfaPacket, 'strip', 30, 'An XFA <packet> packet removed');
+def(types_1.PdfCategory.Form, types_1.PdfDetail.XfaExecute, 'strip', 50, 'An XFA form calls a web service or database');
+def(types_1.PdfCategory.Form, types_1.PdfDetail.XfaConnection, 'strip', 40, 'An XFA form connects to a web service or data source');
+def(types_1.PdfCategory.Form, types_1.PdfDetail.XfaExternalObject, 'strip', 60, 'An XFA form embeds an external object');
+def(types_1.PdfCategory.Form, types_1.PdfDetail.XfaExternalReference, 'strip', 40, 'An XFA form names something outside the PDF to load');
+def(types_1.PdfCategory.Form, types_1.PdfDetail.XfaImage, 'strip', 20, 'An XFA form image (<type|unknown type>) removed. <reason|No plugin accepts this type>');
+def(types_1.PdfCategory.Form, types_1.PdfDetail.PluginPassed, 'info', 0, 'XFA form image kept by plugin <plugin> with nothing removed');
+def(types_1.PdfCategory.Form, types_1.PdfDetail.PluginScrubbed, 'info', 0, 'XFA form image cleaned and kept by plugin <plugin>');
+def(types_1.PdfCategory.Form, types_1.PdfDetail.PluginFailed, 'strip', 20, 'Plugin <plugin> failed, so the XFA form image was removed');
+def(types_1.PdfCategory.Form, types_1.PdfDetail.PluginRemoved, 'strip', 0, 'XFA form image removed by plugin <plugin>');
 def(types_1.PdfCategory.Form, types_1.PdfDetail.CalculationOrder, 'strip', 20, 'Form calculation order removed with the calculation scripts it ran');
 // SIGNATURE
 def(types_1.PdfCategory.Signature, types_1.PdfDetail.Signed, 'info', 0, 'PDF is digitally signed. A rewrite invalidates the signature');

package/dist/types.d.ts

@@ -78,6 +78,7 @@ export declare enum PdfDetail {
     TextMismatch = "TEXT_MISMATCH",
     FullPage = "FULL_PAGE",
     Relative = "RELATIVE",
+    PathTrick = "PATH_TRICK",
     NoPlugin = "NO_PLUGIN",
     TypeMismatch = "TYPE_MISMATCH",
     Portfolio = "PORTFOLIO",
@@ -91,6 +92,13 @@ export declare enum PdfDetail {
     Fields = "FIELDS",
     Xfa = "XFA",
     CalculationOrder = "CALCULATION_ORDER",
+    XfaUnreadable = "XFA_UNREADABLE",
+    XfaPacket = "XFA_PACKET",
+    XfaExecute = "XFA_EXECUTE",
+    XfaConnection = "XFA_CONNECTION",
+    XfaExternalObject = "XFA_EXTERNAL_OBJECT",
+    XfaExternalReference = "XFA_EXTERNAL_REFERENCE",
+    XfaImage = "XFA_IMAGE",
     Signed = "SIGNED",
     Certified = "CERTIFIED",
     UsageRights = "USAGE_RIGHTS",
@@ -235,20 +243,27 @@ export interface ContainedFilePlugin {
 }
 export interface ContainedScript {
     text: string;
-    /** "document", "open", "page-open", "field-format", "link", "bookmark", ... */
+    /** "document", "open", "page-open", "field-format", "link", "bookmark", ... For an XFA script, "xfa-" and its event: "xfa-click", "xfa-calculate", "xfa-script-object". */
     trigger: string;
     location: string;
+    /** For an XFA script, the SOM path of the node that holds it. */
     fieldName?: string;
     /** Names of document-level scripts a plugin kept. */
     keptDocumentScripts: string[];
+    /** 'formcalc' only for an XFA script written in FormCalc. */
+    language: 'javascript' | 'formcalc';
+    /** 'xfa' for a script in an XFA form, which runs against the XFA object model instead of Acrobat's. */
+    form: 'acroform' | 'xfa';
 }
 export interface ScriptPlugin {
     kind: 'script';
     name: string;
     accepts(script: ContainedScript): boolean | Promise<boolean>;
+    /** `findings` are what the plugin found in the script. They go into the report at the script's location. */
     process(script: ContainedScript): Promise<{
         result: 'scrubbed' | 'passed' | 'removed';
         text?: string;
+        findings?: DefuseFinding[];
     }>;
 }
 export interface PdfActionOverride {

package/dist/types.js

@@ -88,6 +88,7 @@ var PdfDetail;
     PdfDetail["TextMismatch"] = "TEXT_MISMATCH";
     PdfDetail["FullPage"] = "FULL_PAGE";
     PdfDetail["Relative"] = "RELATIVE";
+    PdfDetail["PathTrick"] = "PATH_TRICK";
     // EMBEDDED_FILE
     PdfDetail["NoPlugin"] = "NO_PLUGIN";
     PdfDetail["TypeMismatch"] = "TYPE_MISMATCH";
@@ -105,6 +106,13 @@ var PdfDetail;
     PdfDetail["Fields"] = "FIELDS";
     PdfDetail["Xfa"] = "XFA";
     PdfDetail["CalculationOrder"] = "CALCULATION_ORDER";
+    PdfDetail["XfaUnreadable"] = "XFA_UNREADABLE";
+    PdfDetail["XfaPacket"] = "XFA_PACKET";
+    PdfDetail["XfaExecute"] = "XFA_EXECUTE";
+    PdfDetail["XfaConnection"] = "XFA_CONNECTION";
+    PdfDetail["XfaExternalObject"] = "XFA_EXTERNAL_OBJECT";
+    PdfDetail["XfaExternalReference"] = "XFA_EXTERNAL_REFERENCE";
+    PdfDetail["XfaImage"] = "XFA_IMAGE";
     // SIGNATURE
     PdfDetail["Signed"] = "SIGNED";
     PdfDetail["Certified"] = "CERTIFIED";

package/dist/uri.d.ts

@@ -2,6 +2,8 @@ import { PdfDetail as D } from './types';
 interface UriVerdict {
     /** LINK detail, or JAVASCRIPT URL for javascript: and vbscript: links. */
     detail: D;
+    /** Why a relative link is a PATH_TRICK. */
+    reason?: string;
     host?: string;
     /** For a safe target, the hosts a label is compared with, in order. They do not depend on the label. */
     sites?: string[];
@@ -24,6 +26,16 @@ export declare class LabelSites {
  * with the hosts a link's labels name.
  */
 export declare function checkUri(rawUri: string, base?: string): UriVerdict;
+/**
+ * Why a relative path is written to read as another path, or undefined for an ordinary one. Climbing with .. from the
+ * start, as ../images/a.png does, is ordinary. Odd is a control character a reader drops, a backslash a browser reads
+ * as a slash, an encoded dot, slash, backslash or NUL, a segment of only dots and spaces, which Windows reads as .. or
+ * as nothing, and a path that names a folder and then climbs above where it started. Taken from xml-defuse. An XFA
+ * image name is a Windows path, so `backslash: 'separator'` reads a backslash as one.
+ */
+export declare function pathTrick(raw: string, opts?: {
+    backslash?: 'trick' | 'separator';
+}): string | undefined;
 /** Host names written in free text, such as a tooltip. */
 export declare function hostsIn(text: string): string[];
 export {};

package/dist/uri.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LabelSites = void 0;
 exports.checkUri = checkUri;
+exports.pathTrick = pathTrick;
 exports.hostsIn = hostsIn;
 const types_1 = require("./types");
 const IPV4 = /^\d{1,3}(\.\d{1,3}){3}$/;
@@ -60,10 +61,19 @@ function checkUri(rawUri, base) {
                 return v;
             www = v.host;
         }
+        // A relative reference cannot have a colon in its first segment (RFC 3986), and a reader that decodes the address
+        // first, as %6Aavascript: asks it to, reads a scheme there.
+        const head = uri.split(/[/?#]/, 1)[0];
+        if (head.includes(':'))
+            return { detail: types_1.PdfDetail.PathTrick, reason: 'a colon in the first segment, which reads as a scheme once the address is decoded' };
+        const trick = pathTrick(rawUri);
+        if (trick)
+            return { detail: types_1.PdfDetail.PathTrick, reason: trick };
         if (base) {
+            // The base stays in the output, so a link resolved against a hostile one is as hostile as the base.
             const b = checkUri(base);
             if (b.detail !== types_1.PdfDetail.Safe)
-                return { detail: types_1.PdfDetail.Relative };
+                return { detail: b.detail === types_1.PdfDetail.PathTrick ? types_1.PdfDetail.PathTrick : b.detail, reason: b.reason };
             try {
                 uri = new URL(uri, base.trim()).toString();
                 m = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(uri);
@@ -137,6 +147,46 @@ function hostVerdict(host, raw) {
         return { detail: types_1.PdfDetail.LookalikeHost };
     return undefined;
 }
+/**
+ * Why a relative path is written to read as another path, or undefined for an ordinary one. Climbing with .. from the
+ * start, as ../images/a.png does, is ordinary. Odd is a control character a reader drops, a backslash a browser reads
+ * as a slash, an encoded dot, slash, backslash or NUL, a segment of only dots and spaces, which Windows reads as .. or
+ * as nothing, and a path that names a folder and then climbs above where it started. Taken from xml-defuse. An XFA
+ * image name is a Windows path, so `backslash: 'separator'` reads a backslash as one.
+ */
+function pathTrick(raw, opts = {}) {
+    const u = raw.trim();
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: finds the control characters a reader drops from a path.
+    if (/[\x00-\x1f\x7f]/.test(u))
+        return 'a control character, which readers drop before they read the address';
+    const end = u.search(/[?#]/);
+    let path = end < 0 ? u : u.slice(0, end);
+    if (path.includes('\\')) {
+        if (opts.backslash !== 'separator')
+            return 'a backslash, which browsers read as a slash';
+        path = path.replaceAll('\\', '/');
+    }
+    if (/%(2e|2f|5c|00)/i.test(path))
+        return 'an encoded dot, slash, backslash or NUL in the path';
+    let depth = 0;
+    let named = false;
+    for (const seg of path.split('/')) {
+        if (seg === '' || seg === '.')
+            continue;
+        if (seg === '..') {
+            if (depth > 0)
+                depth--;
+            else if (named)
+                return 'a path that names a folder and then climbs above where it started';
+            continue;
+        }
+        if (/^[. ]+$/.test(seg))
+            return 'a segment of only dots and spaces, which Windows reads as .. or as nothing';
+        depth++;
+        named = true;
+    }
+    return undefined;
+}
 /** Host names written in free text, such as a tooltip. */
 function hostsIn(text) {
     const out = [];

package/dist/walker.d.ts

@@ -6,7 +6,10 @@ import { type ByteSink, type DefuseFinding, type PdfOptions, type PluginContext
 interface KeptItem {
     result: 'passed' | 'scrubbed';
     plugin: string;
-    /** For a file: the findings inside the kept bytes, which go into the output's report. */
+    /**
+     * What goes into the output's report for it: for a file, the findings inside the kept bytes, and for a script the
+     * plugin passed, what the plugin found in it.
+     */
     findings?: DefuseFinding[];
 }
 export interface VerifyExpectations {
@@ -103,6 +106,8 @@ export declare class Walker {
     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;
+    /** Scripts a plugin answered for. Its answer is final, so what a shadow visit made of them is not reported. */
+    private readonly answeredScripts;
     /** Information dictionaries and XMP streams removed for the caller. */
     private readonly strippedMeta;
     /** Bytes of scrubbed attachments held in memory until the write. */
@@ -134,6 +139,14 @@ export declare class Walker {
      */
     private readonly fileDecisions;
     private readonly jsReplace;
+    /** XFA packet streams with their cleaned text, by object number. */
+    private readonly xfaReplace;
+    /** Per XFA entry, by owner and path, the value phase A decided to write, or null when the form goes whole. */
+    private readonly xfaDone;
+    /** Set once an XFA form goes into the output, so the catalog keeps NeedsRendering. */
+    private xfaKept;
+    /** XFA packet streams, which stay packets whatever their /Type says. Some producers mark them as embedded files. */
+    private readonly xfaRole;
     private jsTree?;
     private efTree?;
     private readonly keptDocScripts;
@@ -165,6 +178,8 @@ export declare class Walker {
      * strip, or reject when the caller asked for that.
      */
     private emitRemoval;
+    /** What a script plugin found in a script, at the script's location unless the plugin gave a finer one. */
+    private pushScript;
     /**
      * 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.
@@ -239,6 +254,22 @@ export declare class Walker {
     private handleAnnotsArray;
     private handleOutline;
     private handleNames;
+    /**
+     * An XFA form: its packets are read, every script goes to the script plugins, and what reaches outside the form
+     * goes. A form that cannot be read exactly goes whole, and so does every form when FORM/XFA is set to strip.
+     */
+    private handleXfa;
+    /** Returns the XFA entry to write. Cleaned packet text goes into xfaReplace, keyed by the stream that holds it. */
+    private cleanXfa;
+    /** Runs the script plugins over an XFA script. Returns whether it stays, and its new text when a plugin rewrote it. */
+    private decideXfaScript;
+    /**
+     * An image an XFA form carries inline goes to the file plugins, as an attached file does: a viewer decodes it with
+     * decoders of its own. Returns whether it stays, and its new base64 when a plugin rewrote it.
+     */
+    private decideXfaImage;
+    /** A link in an XFA form's rich text, checked as a link action's address is. Returns whether it stays. */
+    private decideXfaLink;
     private handleAcroForm;
     private handleField;
     /** Whether a signature value covers every byte of the file but its own /Contents, which sits right after its key. */