qpdf-compress 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -6,6 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ## [Unreleased]
 
+## [0.8.2] - 2026-09-28
+
+### Fixed
+
+- **The content-stream minifier could hang on a form feed or vertical tab.** `minifyContentStreams` skipped only four whitespace bytes (space, tab, CR, LF) in its dispatcher, while its token loops stopped on `std::isspace`, which also counts form feed (`0x0C`) and vertical tab (`0x0B`) — both legal PDF whitespace. A form feed between two operators (a valid content stream such as `q\fQ`) therefore reached the token branch, which consumed nothing, so the cursor never advanced and the loop appended a space forever until the process ran out of memory. It runs on a libuv worker thread, so a caller's `try`/`catch` cannot interrupt it — a single crafted document is a denial of service. The dispatcher now skips whatever `std::isspace` recognises, and the token branch guarantees forward progress on any byte no branch consumes (a stray unbalanced `)` stalled it the same way), so no input can wedge the loop.
+
+- **Correction to the 0.8.1 release notes.** 0.8.1 shipped with an entry claiming that 0.8.0 had been published without its prebuilt binaries and should be skipped. That was wrong. The REST `assets` array reads empty for releases flagged immutable, and an empty array was mistaken for missing files. Every 0.8.0 tarball is attached and downloadable, each one's SHA-256 matches the pin shipped inside the npm package, and `npm install qpdf-compress@0.8.0` installs the prebuilt binary without compiling anything. **0.8.0 is fine to use and is not deprecated.**
+
+## [0.8.1] - 2026-09-23
+
+### Changed
+
+- The release workflow attaches the prebuilt tarballs to a draft release and publishes it afterwards, instead of publishing first and uploading after: immutable releases reject an upload to an already-published release, so the draft ordering keeps the upload clear of that edge. A following step then confirms every tarball is downloadable from the release before the job succeeds.
+
+### Added
+
+- `npm run verify:pdfa` — a PDF/A conformance harness. It validates `compress()` output against veraPDF, the reference validator, over a real ZUGFeRD PDF/A-3a invoice, and compares the failing clauses to a recorded baseline (`scripts/pdfa-baseline.json`), failing on any difference in either direction so that neither a regression nor an improvement passes unnoticed. CI runs it on Linux / Node 22. veraPDF is GPL-3.0 / MPL-2.0 and is run as an external container pinned by digest — never vendored or linked. Groundwork for [#35](https://github.com/xonaman/nodejs-qpdf-compress/issues/35).
+
 ## [0.8.0] - 2026-09-23
 
 ### Fixed

package/README.md

@@ -160,7 +160,7 @@ Compresses a PDF document. Automatically repairs damaged PDFs.
 | `options.stripAttachments` | `boolean`          | Remove embedded file attachments. Default: `true`                   |
 | `options.output`           | `string`           | Write to file path instead of returning a `Buffer`                  |
 
-> **Hybrid invoices (ZUGFeRD / Factur-X)**: the invoice XML rides along as an attachment, so the defaults remove it. Pass `stripAttachments: false` to keep the attachment and every path readers look it up through. The result is still not a conforming PDF/A-3 — output intents and structure information are dropped in every mode, and XMP metadata too unless `stripMetadata: false` — so a file that has to stay conformant should not be compressed at all.
+> **Hybrid invoices (ZUGFeRD / Factur-X)**: the invoice XML rides along as an attachment, so the defaults remove it. Pass `stripAttachments: false` to keep the attachment and every path readers look it up through. The result is still not a conforming PDF/A-3 — output intents and structure information are dropped in every mode, and XMP metadata too unless `stripMetadata: false` — so a file that has to stay conformant should not be compressed at all. That is measured, not assumed: `npm run verify:pdfa` validates the output against veraPDF over a real PDF/A-3a invoice, and `scripts/pdfa-baseline.json` records exactly which clauses fail.
 
 **Both modes:**
 

package/THIRD-PARTY-NOTICES.md

@@ -42,3 +42,15 @@ Copyright Jean-loup Gailly and Mark Adler. Licensed under the zlib License.
 zlib provides DEFLATE compression and is statically linked into the Windows
 build (via vcpkg); on macOS and Linux the system zlib is used at build time.
 See <https://github.com/madler/zlib/blob/master/LICENSE>.
+
+## Development and test material
+
+Neither of the following is distributed in the npm package: the fixture lives under `test/`, which is excluded from the package `files` list, and veraPDF is invoked as an external tool in its own container rather than vendored or linked.
+
+### `test/fixtures/pdfa3-invoice.pdf`
+
+A real ZUGFeRD 2.1 (EN 16931) PDF/A-3a invoice, used by `npm run verify:pdfa` to measure the PDF/A conformance of compression output. Taken unmodified from the [ZUGFeRD/corpus](https://github.com/ZUGFeRD/corpus) project (Apache-2.0), path `ZUGFeRDv2/correct/symtrax/Beispiele/EN16931/zugferd_2p1_EN16931_AbweichenderZahlungsempf.pdf`, SHA-256 `a4b903d4e508a80d65276f030d0fbeab5081d62c2c2b19ffd2f13bcdae37c564`.
+
+### veraPDF
+
+Copyright the veraPDF Consortium. Licensed under the GNU General Public License v3 or the Mozilla Public License v2. The reference PDF/A validator, run by `npm run verify:pdfa` from the `verapdf/cli` container image, pinned by digest in `scripts/pdfa-baseline.json`. See <https://github.com/veraPDF/veraPDF-apps>.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qpdf-compress",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Native PDF compression for Node.js, powered by QPDF",
   "license": "Apache-2.0",
   "type": "module",
@@ -77,6 +77,7 @@
     "download:qpdf": "node scripts/download-qpdf.mjs",
     "download:harfbuzz": "node scripts/download-harfbuzz.mjs",
     "verify:checksums": "node scripts/verify-checksums.mjs",
+    "verify:pdfa": "tsc && node scripts/verify-pdfa.mjs",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",

package/scripts/pdfa-baseline.json

@@ -0,0 +1,23 @@
+{
+  "image": "verapdf/cli@sha256:d5ee329657cf9bc4b2400392dd54c7d0a0ce9980ff6fa2da5590eebeec007cdb",
+  "flavour": "3a",
+  "fixture": "pdfa3-invoice.pdf",
+  "variants": {
+    "original": {
+      "compliant": true,
+      "failedRules": []
+    },
+    "default": {
+      "compliant": false,
+      "failedRules": ["6.1.7.1-2", "6.2.4.3-2", "6.2.4.3-4", "6.6.2.1-1", "6.7.2.2-1", "6.7.3.3-1"]
+    },
+    "keep-attachments": {
+      "compliant": false,
+      "failedRules": ["6.1.7.1-2", "6.2.4.3-2", "6.2.4.3-4", "6.6.2.1-1", "6.7.2.2-1", "6.7.3.3-1"]
+    },
+    "keep-both": {
+      "compliant": false,
+      "failedRules": ["6.1.7.1-2", "6.2.4.3-2", "6.2.4.3-4", "6.7.3.3-1"]
+    }
+  }
+}

package/scripts/prebuilds.json

@@ -1,11 +1,11 @@
 {
-  "darwin-arm64": "91bce035bd98d4c5b51eb3c43bb4b3f1734768d4edb47042cce4dbb7b73bd001",
-  "darwin-x64": "fe1fdd42d8ff24e5ed3777ced647d29f9878d0dde347b3925af3b388d49f4e15",
-  "linux-arm": "478c10a51adefddc6f4cccc580edcb0d2242e8b155d495aac6ae2dc57ec96c10",
-  "linux-arm64": "6f09b7b95ffdb382430e8d474fdad4664058210863668e85130d5f76d157796e",
-  "linux-musl-arm64": "aee2f73320bb8d911be2dbfd657fd36ad7d767f27e5257fd8060d8c53b930c37",
-  "linux-musl-x64": "0fa4510d0aac780f955880bf511e086b9c88af97f87d348f97569859d65d191d",
-  "linux-x64": "75b2b183f810af513c7905406c695e325b39d5ef6125a8845465b75985515f0d",
-  "win32-arm64": "fbac6517c8ea188ea9cfb72c5daac0e6b90a5cb8e185a6e1cf7dff116b4ff032",
-  "win32-x64": "6b0a6f16c5cbe881aa3b4da12dcd138a637cf0b6764505a0e82a8b23df4d48d9"
+  "darwin-arm64": "a2fda84bd3569abf5a39b7ce30a58652b8189751cedbaf943e391c9f0b45646c",
+  "darwin-x64": "a908f0fe57b78a10e7dfa461a395da050da5499715f5aae2cf793dfe7a982e5f",
+  "linux-arm": "39531172aa069e69e3b7db3ffc2462572fddf2a725d2f9ac9abca06513111184",
+  "linux-arm64": "1216bea0d7a82fe47bcf3f77f3219f6f3a1620480ed42b3f3a9d0d688f88dbd3",
+  "linux-musl-arm64": "d0fe61e513147dced9454a590fe4c17a8f39c0ed9ed858b3f9d44d7b33ec0e86",
+  "linux-musl-x64": "865748574c08bdd74decdb7c9acd91b7a0c7e4269e3cb48811d8a9b8c654ff17",
+  "linux-x64": "2e766fd34ee2ff86d0f4e8f02008b08507b4d59081bea68185dd78e1341be91f",
+  "win32-arm64": "c6793d96feb0a272ced9ba18ec97b29dce6075fcef9692f095defa699252f657",
+  "win32-x64": "fcc1c299080e87a5932d5dbe7fcb2ec5c849cf98a094eff55f8408ed1ccce524"
 }

package/scripts/verify-pdfa.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * Validates the PDF/A conformance of compress() output against a recorded baseline.
+ *
+ * veraPDF is the reference PDF/A validator. It is GPL-3.0 / MPL-2.0, so it is neither
+ * vendored nor linked — it runs as an external tool in its own container, pinned by
+ * digest so a verdict cannot drift under us when the image is rebuilt.
+ *
+ * The baseline records which clauses each variant fails today. Any difference, in
+ * either direction, fails the run: a regression and an improvement both need the
+ * baseline updated deliberately (`--update`) rather than silently absorbed.
+ *
+ * Usage: npm run verify:pdfa [-- --update]
+ */
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { compress } from '../dist/index.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, '..');
+const baselinePath = join(__dirname, 'pdfa-baseline.json');
+const baseline = JSON.parse(readFileSync(baselinePath, 'utf8'));
+const update = process.argv.includes('--update');
+
+// the work directory must sit inside the repo: Docker Desktop shares the user's
+// own tree, not every host temp path
+const workDir = join(root, '.cache', 'pdfa');
+
+const variants = {
+  original: null,
+  default: {},
+  'keep-attachments': { stripAttachments: false },
+  'keep-both': { stripAttachments: false, stripMetadata: false },
+};
+
+function veraPdf(name) {
+  const args = [
+    'run',
+    '--rm',
+    '--platform',
+    'linux/amd64',
+    '-v',
+    `${workDir}:/data`,
+    baseline.image,
+    '--flavour',
+    baseline.flavour,
+    '--format',
+    'mrr',
+    `/data/${name}.pdf`,
+  ];
+  let xml;
+  try {
+    xml = execFileSync('docker', args, { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+  } catch (err) {
+    // veraPDF exits non-zero for a non-compliant file; the report is still on stdout
+    if (typeof err.stdout !== 'string' || !err.stdout.includes('<validationReport')) throw err;
+    xml = err.stdout;
+  }
+  const compliant = /<validationReport[^>]*isCompliant="true"/.test(xml);
+  const failed = [
+    ...new Set(
+      [
+        ...xml.matchAll(
+          /<rule\b[^>]*\bclause="([^"]+)"[^>]*\btestNumber="([^"]+)"[^>]*\bstatus="failed"/g,
+        ),
+      ].map((m) => `${m[1]}-${m[2]}`),
+    ),
+  ].sort();
+  return { compliant, failedRules: failed };
+}
+
+try {
+  execFileSync('docker', ['version', '--format', '{{.Server.Version}}'], { stdio: 'ignore' });
+} catch {
+  console.error('Docker is required to run veraPDF. Start Docker and try again.');
+  process.exit(1);
+}
+
+rmSync(workDir, { recursive: true, force: true });
+mkdirSync(workDir, { recursive: true });
+
+const fixture = readFileSync(join(root, 'test', 'fixtures', baseline.fixture));
+writeFileSync(join(workDir, 'original.pdf'), fixture);
+for (const [name, options] of Object.entries(variants)) {
+  if (!options) continue;
+  await compress(fixture, { ...options, output: join(workDir, `${name}.pdf`) });
+}
+
+const results = {};
+let failures = 0;
+
+for (const name of Object.keys(variants)) {
+  const actual = veraPdf(name);
+  results[name] = actual;
+
+  const expected = baseline.variants[name];
+  const same =
+    expected &&
+    expected.compliant === actual.compliant &&
+    expected.failedRules.join() === actual.failedRules.join();
+
+  const verdict = actual.compliant ? 'PASS' : `FAIL (${actual.failedRules.length})`;
+  console.log(
+    `${same || update ? ' ok ' : 'DIFF'}  ${name.padEnd(17)} ${verdict.padEnd(9)} ${actual.failedRules.join(' ')}`,
+  );
+
+  if (!same && !update) {
+    failures++;
+    console.log(
+      `      expected: ${expected ? `${expected.compliant ? 'PASS' : 'FAIL'} ${expected.failedRules.join(' ')}` : '(no baseline entry)'}`,
+    );
+  }
+}
+
+if (update) {
+  writeFileSync(baselinePath, `${JSON.stringify({ ...baseline, variants: results }, null, 2)}\n`);
+  // keep the committed file canonical so the pre-commit hook has nothing to say
+  try {
+    execFileSync('npx', ['prettier', '--write', baselinePath], { stdio: 'ignore' });
+  } catch {
+    // prettier is a devDependency; a missing one is not worth failing the run over
+  }
+  console.log(`\nBaseline updated: ${baselinePath}`);
+  process.exit(0);
+}
+
+if (failures) {
+  console.error(
+    `\n${failures} variant(s) differ from the baseline. Re-run with --update once the change is intended.`,
+  );
+  process.exit(1);
+}
+console.log('\nAll variants match the recorded baseline.');

package/src/content.cc

@@ -90,8 +90,10 @@ void minifyContentStreams(QPDF &qpdf) {
     while (pos < raw.size()) {
       char ch = raw[pos];
 
-      // skip whitespace
-      if (ch == ' ' || ch == '\t' || ch == '\r' || ch == '\n') {
+      // skip whitespace — use the same predicate the token loops below use
+      // (std::isspace), so a form-feed or vertical-tab can never fall through
+      // to the token branch and stall the tokenizer.
+      if (std::isspace(static_cast<unsigned char>(ch))) {
         if (!minified.empty())
           needSpace = true;
         ++pos;
@@ -203,10 +205,6 @@ void minifyContentStreams(QPDF &qpdf) {
 
       // regular token (number, operator)
       {
-        if (needSpace) {
-          minified += ' ';
-          needSpace = false;
-        }
         size_t start = pos;
         while (pos < raw.size() &&
                !std::isspace(static_cast<unsigned char>(raw[pos])) &&
@@ -215,6 +213,19 @@ void minifyContentStreams(QPDF &qpdf) {
                raw[pos] != ')')
           ++pos;
 
+        // forward-progress guard: a byte that starts no token — a stray ')'
+        // or any whitespace the dispatcher above did not catch — leaves
+        // pos == start. Without this the outer loop spins forever, appending
+        // to `minified` without bound. Skip the byte so progress is guaranteed.
+        if (pos == start) {
+          ++pos;
+          continue;
+        }
+
+        if (needSpace) {
+          minified += ' ';
+          needSpace = false;
+        }
         std::string token(raw, start, pos - start);
 
         // trim numeric formatting