Add support for /AuthEvent, on-demand decryption

Normally entire PDFs are encrypted (or not).
But it is also possible to only encrypt attachments.
It is then also possible to *only* prompt for a password when the user opens
them.

In the existing flow, prompting for passwords happens because things are decrypted.
A specific error is thrown, caught, and the user is prompted.
To keep this flow working, this PR changes to decrypting attachments on demand,
instead of eagerly.
This sounds logical: to not read attachments on startup.

I’ve extensively tested this, not only with regular attachments, but also with outline items
and attachments in annotations.

This PR builds on GH-21234.
It’s an alternative to the naïve GH-20732.

Closes GH-20049.

Author: wooorm

src/core/annotation.js

@@ -79,6 +79,10 @@ import { parseMarkedContentProps } from "./evaluator_utils.js";
 import { StringStream } from "./stream.js";
 import { XFAFactory } from "./xfa/factory.js";
 
+/**
+ * @import { Catalog } from "./catalog.js";
+ */
+
 class AnnotationFactory {
   static createGlobals(pdfManager) {
     return Promise.all([
@@ -5207,11 +5211,39 @@ class FileAttachmentAnnotation extends MarkupAnnotation {
   constructor(params) {
     super(params);
 
-    const { dict } = params;
-    const file = new FileSpec(dict.get("FS"));
+    const { annotationGlobals, dict } = params;
+    const fileSpecRef = dict.getRaw("FS");
+    const fsDict = dict.get("FS");
+    const file = new FileSpec(fsDict);
+    /** @type {{catalog?: Catalog}} */
+    const { catalog } = annotationGlobals.pdfManager.pdfDocument;
+
+    // When this annotation references an embedded file that’s already in the
+    // catalog `NameTree` (such as `EFOpen`), reuse that `NameTree` id so the
+    // sidebar and annotation paths resolve the same attachment identity.
+    let fileId =
+      fileSpecRef instanceof Ref
+        ? catalog?.attachmentIdByRef.get(fileSpecRef)
+        : undefined;
+
+    // Fallback ids are namespaced to keep annotation-local ids distinct from
+    // `NameTree` ids (which are filename-based).
+    if (catalog && fsDict instanceof Dict && typeof fileId !== "string") {
+      const baseFileId = `annotation:${this.data.id}`;
+      fileId = baseFileId;
+
+      let i = 1;
+      while (catalog.attachmentDictById.has(fileId)) {
+        fileId = `${baseFileId}-${i++}`;
+      }
+
+      // Cache only fallbacks.
+      catalog.attachmentDictById.set(fileId, fsDict);
+    }
 
     this.data.hasOwnCanvas = this.data.noRotate;
     this.data.noHTML = false;
+    this.data.fileId = fileId;
     this.data.file = file.serializable;
 
     const name = dict.get("Name");

src/core/base_stream.js

@@ -25,11 +25,17 @@ class BaseStream {
     }
   }
 
+  /**
+   * @returns {number}
+   */
   // eslint-disable-next-line getter-return
   get length() {
     unreachable("Abstract getter `length` accessed");
   }
 
+  /**
+   * @returns {boolean}
+   */
   // eslint-disable-next-line getter-return
   get isEmpty() {
     unreachable("Abstract getter `isEmpty` accessed");
@@ -43,6 +49,10 @@ class BaseStream {
     unreachable("Abstract method `getByte` called");
   }
 
+  /**
+   * @param {number | undefined} [length]
+   * @returns {Uint8Array}
+   */
   getBytes(length) {
     unreachable("Abstract method `getBytes` called");
   }

src/core/catalog.js

@@ -55,6 +55,37 @@ import { MetadataParser } from "./metadata_parser.js";
 import { stringToPDFString } from "./string_utils.js";
 import { StructTreeRoot } from "./struct_tree.js";
 
+/**
+ * @import {XRef} from "./xref.js";
+ */
+
+/**
+ * @callback GetAttachmentContent
+ *   Callback used to lazily fetch attachment content.
+ * @param {string} id
+ *   Unique attachment identifier.
+ * @returns {CatalogAttachmentContent}
+ *   Result.
+ */
+
+/**
+ * @typedef {Uint8Array | null} CatalogAttachmentContent
+ *   Attachment value.
+ */
+
+/**
+ * @typedef CatalogAttachment
+ *   Attachment metadata.
+ * @property {CatalogAttachmentContent | undefined} [content]
+ *   Value, when already available.
+ * @property {string} description
+ *   Description.
+ * @property {string} filename
+ *   Filename (just the basename) for display.
+ * @property {string} rawFilename
+ *   File path.
+ */
+
 const isRef = v => v instanceof Ref;
 
 const isValidExplicitDest = _isValidExplicitDest.bind(
@@ -88,8 +119,18 @@ function fetchRemoteDest(action) {
 class Catalog {
   #actualNumPages = null;
 
+  /** @type {RefSetCache | null} */
+  #attachmentIdByRef = null;
+
   #catDict = null;
 
+  /**
+   * Attachment dictionaries keyed by attachment id.
+   *
+   * @type {Map<string, Dict>}
+   */
+  attachmentDictById = new Map();
+
   builtInCMapCache = new Map();
 
   fontCache = new RefSetCache();
@@ -123,6 +164,29 @@ class Catalog {
     this.toplevelPagesDict; // eslint-disable-line no-unused-expressions
   }
 
+  /**
+   * Attachment ids keyed by embedded-file reference.
+   *
+   * @type {RefSetCache}
+   */
+  get attachmentIdByRef() {
+    if (this.#attachmentIdByRef) {
+      return this.#attachmentIdByRef;
+    }
+
+    const attachmentIdByRef = new RefSetCache();
+    for (const [name, ref] of this.rawEmbeddedFiles || []) {
+      if (!(ref instanceof Ref)) {
+        continue;
+      }
+      attachmentIdByRef.put(
+        ref,
+        stringToPDFString(name, /* keepEscapeSequence = */ true)
+      );
+    }
+    return (this.#attachmentIdByRef = attachmentIdByRef);
+  }
+
   cloneDict() {
     return this.#catDict.clone();
   }
@@ -369,6 +433,7 @@ class Catalog {
 
       const outlineItem = {
         action: data.action,
+        attachmentId: data.attachmentId,
         attachment: data.attachment,
         dest: data.dest,
         url: data.url,
@@ -1068,8 +1133,15 @@ class Catalog {
     );
   }
 
+  /**
+   * Get attachments.
+   *
+   * @returns {Record<string, CatalogAttachment> | null}
+   *   Attachments.
+   */
   get attachments() {
     const obj = this.#catDict.get("Names");
+    /** @type {Record<string, CatalogAttachment> | null} */
     let attachments = null;
 
     if (obj instanceof Dict && obj.has("EmbeddedFiles")) {
@@ -1084,6 +1156,32 @@ class Catalog {
     return shadow(this, "attachments", attachments);
   }
 
+  /**
+   * Get content for an attachment.
+   *
+   * @param {string} id
+   *   Unique attachment identifier (required).
+   * @returns {CatalogAttachmentContent}
+   *   Content.
+   */
+  attachmentContent(id) {
+    const dict = this.attachmentDictById.get(id);
+    if (dict) {
+      return FileSpec.readContent(dict);
+    }
+
+    const obj = this.#catDict.get("Names");
+    if (obj instanceof Dict && obj.has("EmbeddedFiles")) {
+      const nameTree = new NameTree(obj.getRaw("EmbeddedFiles"), this.xref);
+      for (const [key, value] of nameTree.getAll()) {
+        if (stringToPDFString(key, /* keepEscapeSequence = */ true) === id) {
+          return FileSpec.readContent(value);
+        }
+      }
+    }
+    return null;
+  }
+
   get rawEmbeddedFiles() {
     const obj = this.#catDict.get("Names");
     if (!(obj instanceof Dict) || !obj.has("EmbeddedFiles")) {
@@ -1182,6 +1280,9 @@ class Catalog {
 
   async cleanup(manuallyTriggered = false) {
     clearGlobalCaches();
+    this.#attachmentIdByRef?.clear();
+    this.#attachmentIdByRef = null;
+    this.attachmentDictById.clear();
     this.globalColorSpaceCache.clear();
     this.globalImageCache.clear(/* onlyData = */ manuallyTriggered);
     this.pageKidsCountCache.clear();
@@ -1556,8 +1657,8 @@ class Catalog {
    *   properties will be placed.
    * @property {string} [docBaseUrl] - The document base URL that is used when
    *   attempting to recover valid absolute URLs from relative ones.
-   * @property {Object} [docAttachments] - The document attachments (may not
-   *   exist in most PDF documents).
+   * @property {Record<string, CatalogAttachment> | null} [docAttachments] - The
+   *   document attachments (may not exist in most PDF documents).
    */
 
   /**
@@ -1740,8 +1841,7 @@ class Catalog {
         case "GoToR":
           const urlDict = action.get("F");
           if (urlDict instanceof Dict) {
-            const fs = new FileSpec(urlDict, /* skipContent = */ true);
-            ({ rawFilename: url } = fs.serializable);
+            url = new FileSpec(urlDict).filename;
           } else if (typeof urlDict === "string") {
             url = urlDict;
           } else {
@@ -1766,22 +1866,21 @@ class Catalog {
 
         case "GoToE":
           const target = action.get("T");
-          let attachment;
+          /** @type {string | null} */
+          let id = null;
 
-          if (docAttachments && target instanceof Dict) {
+          if (target instanceof Dict) {
             const relationship = target.get("R");
             const name = target.get("N");
 
             if (isName(relationship, "C") && typeof name === "string") {
-              attachment =
-                docAttachments[
-                  stringToPDFString(name, /* keepEscapeSequence = */ true)
-                ];
+              id = stringToPDFString(name, /* keepEscapeSequence = */ true);
             }
           }
 
-          if (attachment) {
-            resultObj.attachment = attachment;
+          if (docAttachments && id) {
+            resultObj.attachmentId = id;
+            resultObj.attachment = docAttachments[id];
 
             // NOTE: the destination is relative to the *attachment*.
             const attachmentDest = fetchRemoteDest(action);