@scanmate/merge 0.8.0 → 0.9.0

package/README.md

@@ -51,6 +51,7 @@ By default each image page is the image at its resolution. A 2480 × 3508 scan a
 | `quality` | `92` | JPEG quality. |
 | `passThrough` | `true` | Return a lone PDF unchanged. |
 | `metadata` | none | Title, author, subject, keywords, creator. The producer is always `@scanmate/merge`. |
+| `password` | none | Opens an encrypted PDF source that needs a password to be read. A signed or permission-restricted PDF - locked with an owner password alone - needs none. Tried on every encrypted source; one it does not open is tried with no password instead, so it cannot lock out a source that needed nothing. |
 
 Each entry in `pages` says which source and source page it came from, how it was embedded, and its size. A source that cannot be used raises a `MergeSourceError` carrying its `index`.
 
@@ -72,6 +73,8 @@ const { pdf, drawn, warnings } = await markPages('issued.pdf', [
 
 It exists to check that the regions a validation will measure are where the document's fields actually are - most people reach it as `Scanmate.mark` in `@scanmate/scan`, whose README has a worked example on the W-9.
 
+**Signed documents open as they are.** They usually arrive encrypted - an owner password restricting editing, none needed to read - which pdf-lib refuses by default. They are decrypted as they are read, with nothing to pass; `password` is only for a PDF that needs one to be read at all.
+
 Two things it gets right that a naive version would not. **Rotation and crop box:** a region is in points from the top-left of the page *as displayed*, which is how `@scanmate/extract` reports text, while pdf-lib draws from the bottom-left of the unrotated media box. The conversion between the two is pdf.js's own page transform, ported line for line and inverted, and its spec pins it to values read off real pdf.js for every quarter turn, with and without an offset crop box. **Bleed:** it is resolved by `resolveBleed` from `@scanmate/ink`, the same function the pixel comparison uses, so the band drawn is the band measured.
 
 ## How it decides

package/dist/index.esm.js

@@ -1,4 +1,4 @@
-import { PDFDocument, EncryptedPDFError, rgb, StandardFonts, degrees } from '@cantoo/pdf-lib';
+import { PDFDocument, rgb, StandardFonts, degrees } from '@cantoo/pdf-lib';
 import { isRaster, decodeImage, readImageMetadata, encodeImage, resolveBleed, hasBleed, growBy } from '@scanmate/ink';
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
@@ -125,6 +125,60 @@ async function readBytes(source, index) {
   throw new MergeSourceError(index, 'expected a path, a file URL, bytes, a raster or { raster, dpi }');
 }
 
+/** A PDF that needs a password to open, which was not given or did not work. */
+class PdfPasswordError extends Error {
+  /** Whether a password was given at all - wrong, or missing. */
+  given;
+  constructor(given) {
+    super(given ? 'this PDF is encrypted, and the password given does not open it' : 'this PDF is encrypted with a password it needs to be opened - pass `password`');
+    this.name = 'PdfPasswordError';
+    this.given = given;
+  }
+}
+/**
+ * Opens a PDF for writing, decrypting it if it is encrypted.
+ *
+ * Signed documents usually arrive encrypted: an owner password restricting
+ * what may be done with them, and no password needed to read them. pdf-lib
+ * refuses those outright, and its own error suggests `ignoreEncryption: true`.
+ * That is not taken here, because it is measured to be wrong for anything that
+ * writes: the document loads and saves and still opens, with its text intact,
+ * but whatever was drawn on it is silently missing - written unencrypted into a
+ * file that still declares itself encrypted, so a viewer "decrypts" it into
+ * nothing. A helper that draws marks would hand back a clean PDF with no marks
+ * and no error.
+ *
+ * Decrypting instead is correct, and costs a caller nothing in the common case:
+ * the empty password opens an owner-password-only document. Only a PDF that
+ * needs a password to be read at all needs one given.
+ *
+ * Nor is the document loaded for incremental update, which would keep the
+ * original bytes intact and with them an existing digital signature. That is
+ * measured too: on an encrypted document the original page content does not
+ * survive it. A marked copy is for looking at; it is not the signed document,
+ * and does not pretend to be.
+ */
+async function openPdf(bytes, {
+  password
+} = {}) {
+  // The password given first, then none. A caller's password is for the document
+  // that needs one; tried alone it would lock out the owner-password-only PDF that
+  // needed nothing - which is what happened when one password was applied to every
+  // source of a merge. The empty password opens only what anyone may read anyway.
+  const attempts = password === undefined || password === '' ? [''] : [password, ''];
+  for (const attempt of attempts) try {
+    // An empty password changes nothing for a document that is not encrypted.
+    return await PDFDocument.load(bytes, {
+      password: attempt,
+      updateMetadata: false
+    });
+  } catch (error) {
+    // pdf-lib reports these as plain errors: "NEEDS PASSWORD", "Password incorrect".
+    if (!(error instanceof Error) || !/password/i.test(error.message)) throw error;
+  }
+  throw new PdfPasswordError(password !== undefined);
+}
+
 /**
  * Many files in, one PDF out: PDFs, images and rasters, in the order given,
  * mixed freely.
@@ -148,6 +202,7 @@ async function mergeDocuments(sources, options = {}) {
     quality = 92,
     passThrough = true,
     metadata,
+    password,
     onProgress
   } = options;
   if (sources.length === 0) throw new RangeError('nothing to merge');
@@ -160,7 +215,8 @@ async function mergeDocuments(sources, options = {}) {
     margin,
     imageDpi,
     encoding,
-    quality
+    quality,
+    password
   };
   for (const [index, source] of resolved.entries()) {
     const started = Date.now();
@@ -210,7 +266,7 @@ async function mergeDocuments(sources, options = {}) {
   };
 }
 async function appendPdf(context, bytes, index) {
-  const source = await loadPdf(bytes, index);
+  const source = await loadPdf(bytes, index, context.password);
   const copied = await context.merged.copyPages(source, source.getPageIndices());
   for (const [i, page] of copied.entries()) {
     context.merged.addPage(page);
@@ -230,13 +286,18 @@ async function appendPdf(context, bytes, index) {
     });
   }
 }
-async function loadPdf(bytes, index) {
+/**
+ * A source PDF, decrypted if it is encrypted - an owner-password-only document,
+ * the usual signed or restricted PDF, needs nothing given. The merged document
+ * is a new one, so it comes out unencrypted whatever went in.
+ */
+async function loadPdf(bytes, index, password) {
   try {
-    return await PDFDocument.load(bytes, {
-      updateMetadata: false
+    return await openPdf(bytes, {
+      password
     });
   } catch (error) {
-    if (error instanceof EncryptedPDFError) throw new MergeSourceError(index, 'it is an encrypted PDF, which cannot be copied without its password');
+    if (error instanceof PdfPasswordError) throw new MergeSourceError(index, error.given ? 'it is an encrypted PDF, and `password` does not open it' : 'it is an encrypted PDF that needs a password to open - pass `password`');
     throw new MergeSourceError(index, `it is not a readable PDF (${error instanceof Error ? error.message : String(error)})`);
   }
 }
@@ -445,7 +506,11 @@ const LABEL_SIZE = 7;
 async function markPages(pdf, marks, options = {}) {
   const source = await readSource(pdf, 0);
   if (source.kind !== 'pdf') throw new TypeError('marks are drawn on a PDF, and this is not one');
-  const document = await PDFDocument.load(source.bytes);
+  // Decrypted if encrypted, as a signed document usually is - see `openPdf` for
+  // why that and not `ignoreEncryption`, which would silently drop every mark.
+  const document = await openPdf(source.bytes, {
+    password: options.password
+  });
   const font = options.labels === false ? null : await document.embedFont(StandardFonts.Helvetica);
   const bleed = resolveBleed(options);
   const pages = document.getPages();
@@ -548,5 +613,5 @@ function round(value) {
   return Math.round(value * 10) / 10;
 }
 
-export { MIN_RECORDED_DPI, MergeSourceError, PAPER, isPdf, markPages, mergeDocuments, placeImage, readSource, resolveDpi, toUserSpace, viewportSize, viewportTransform };
+export { MIN_RECORDED_DPI, MergeSourceError, PAPER, PdfPasswordError, isPdf, markPages, mergeDocuments, openPdf, placeImage, readSource, resolveDpi, toUserSpace, viewportSize, viewportTransform };
 //# sourceMappingURL=index.esm.js.map

package/dist/src/document-merge/merge-result.contract.d.ts

@@ -2,6 +2,13 @@ import type { ProgressCallback } from '@scanmate/ink';
 import type { PageSize } from '../page-placement/index.js';
 import type { SourceKind } from '../source-reading/index.js';
 export interface MergeOptions {
+    /**
+     * Opens an encrypted PDF source that needs a password to be read. The usual
+     * encrypted PDF - a signed or permission-restricted document, locked with an
+     * owner password alone - needs none and is decrypted as it is copied. The
+     * same password is tried on every encrypted source.
+     */
+    password?: string;
     /** Size of each image page: the image at its resolution (`'image'`, the default), or a paper size to fit it in. */
     pageSize?: PageSize;
     /** Points of white kept around an image on a paper-size page. Default `0`. */

package/dist/src/index.d.ts

@@ -21,7 +21,8 @@
  */
 export { mergeDocuments } from './document-merge/index.js';
 export type { Embedding, MergedPage, MergeOptions, MergeResult } from './document-merge/index.js';
-export { MergeSourceError } from './source-reading/index.js';
+export { MergeSourceError, openPdf, PdfPasswordError } from './source-reading/index.js';
+export type { OpenPdfOptions } from './source-reading/index.js';
 export type { SourceKind } from './source-reading/index.js';
 export { markPages } from './page-marking/index.js';
 export type { MarkOptions, MarkResult, PageMark } from './page-marking/index.js';

package/dist/src/page-marking/page-mark.contract.d.ts

@@ -23,6 +23,12 @@ export interface PageMark extends ScanmateRect {
 export interface MarkOptions extends Bleed {
     /** Write each mark's `id` beside it. Default `true`. */
     labels?: boolean;
+    /**
+     * Opens a PDF encrypted with a password it needs to be read. A signed or
+     * permission-restricted document, locked with an owner password alone, needs
+     * none: it is decrypted as it is read, and the marks are drawn on it.
+     */
+    password?: string;
 }
 export interface MarkResult {
     /** The original, with the marks drawn on it. Nothing else about it changes. */

package/dist/src/source-reading/index.d.ts

@@ -2,5 +2,7 @@
 export { MergeSourceError } from './merge-source.contract.js';
 export type { SourceKind } from './merge-source.contract.js';
 export { isPdf, readSource } from './read-source.use-case.js';
+export { openPdf, PdfPasswordError } from './open-pdf.use-case.js';
+export type { OpenPdfOptions } from './open-pdf.use-case.js';
 export type { ResolvedSource } from './read-source.use-case.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/source-reading/open-pdf.use-case.d.ts

@@ -0,0 +1,42 @@
+import { PDFDocument } from '@cantoo/pdf-lib';
+/** A PDF that needs a password to open, which was not given or did not work. */
+export declare class PdfPasswordError extends Error {
+    /** Whether a password was given at all - wrong, or missing. */
+    readonly given: boolean;
+    constructor(given: boolean);
+}
+export interface OpenPdfOptions {
+    /**
+     * The password that opens the document, for a PDF encrypted with one.
+     *
+     * Not needed for the usual encrypted PDF - a signed or permission-restricted
+     * document, locked with an owner password and nothing else - which opens with
+     * no password at all and is decrypted as it is read.
+     */
+    password?: string;
+}
+/**
+ * Opens a PDF for writing, decrypting it if it is encrypted.
+ *
+ * Signed documents usually arrive encrypted: an owner password restricting
+ * what may be done with them, and no password needed to read them. pdf-lib
+ * refuses those outright, and its own error suggests `ignoreEncryption: true`.
+ * That is not taken here, because it is measured to be wrong for anything that
+ * writes: the document loads and saves and still opens, with its text intact,
+ * but whatever was drawn on it is silently missing - written unencrypted into a
+ * file that still declares itself encrypted, so a viewer "decrypts" it into
+ * nothing. A helper that draws marks would hand back a clean PDF with no marks
+ * and no error.
+ *
+ * Decrypting instead is correct, and costs a caller nothing in the common case:
+ * the empty password opens an owner-password-only document. Only a PDF that
+ * needs a password to be read at all needs one given.
+ *
+ * Nor is the document loaded for incremental update, which would keep the
+ * original bytes intact and with them an existing digital signature. That is
+ * measured too: on an encrypted document the original page content does not
+ * survive it. A marked copy is for looking at; it is not the signed document,
+ * and does not pretend to be.
+ */
+export declare function openPdf(bytes: Uint8Array, { password }?: OpenPdfOptions): Promise<PDFDocument>;
+//# sourceMappingURL=open-pdf.use-case.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scanmate/merge",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Merge PDFs, images and rasters into one PDF: PDF pages copied as they are, JPEGs embedded without recompression, every page of a TIFF.",
   "license": "MIT",
   "author": "Eduardo Russo",
@@ -41,7 +41,7 @@
   ],
   "dependencies": {
     "@cantoo/pdf-lib": "^2.11.1",
-    "@scanmate/ink": "^0.8.0"
+    "@scanmate/ink": "^0.9.0"
   },
   "publishConfig": {
     "access": "public"