qpdf-compress 0.6.4 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [0.7.0] - 2026-06-27
+
+### Added
+
+- Typed error hierarchy: `QpdfError` with `QpdfFileError`, `QpdfFormatError`, and `QpdfPasswordError` subclasses for actionable compression failures
+- `.nvmrc`, `.editorconfig`, and a `packageManager` field for reproducible toolchains
+- `typecheck` CI step and a weekly `windows-latest` canary job that re-tests the `windows-2022` pin
+- `./package.json` to the package `exports` map
+
+### Changed
+
+- Raised the Node.js `engines` floor to `>=22.0.0`, dropping end-of-life Node 20
+- Modernized `tsconfig`: `nodenext` module resolution, `es2023` target, and stricter type-checking (`verbatimModuleSyntax`, `exactOptionalPropertyTypes`, `noUnusedLocals`/`noUnusedParameters`, `noImplicitOverride`, `noFallthroughCasesInSwitch`)
+- Reworked ESLint to type-aware linting for `lib/`, adopted the `globals` package, and dropped `eslint-plugin-prettier`; switched coverage to Vitest's v8 provider
+- Bumped the native build to C++20 and Node-API 9 (C++ standard defined once via a gyp variable)
+- Hardened and sped up CI/CD: pinned all GitHub Actions to commit SHAs, added npm and native-dependency caching, a concurrency group, job timeouts, and top-level least-privilege permissions
+- Migrated npm publish to OIDC trusted publishing (dropped `NPM_TOKEN`)
+- Switched QPDF's source download to the official byte-stable release tarball; HarfBuzz uses the SHA-256-pinned GitHub git-archive `.tar.gz` (its only release asset is `.tar.xz`, which hangs Windows `tar` during extraction)
+
+### Security
+
+- Pin and verify the SHA-256 of every downloaded native dependency (`scripts/native-deps.json`) via a hardened downloader (timeout, retry, atomic writes, origin pinning), with an `npm run verify:checksums` tripwire
+- Added OpenSSF Scorecard scanning, Dependabot updates, and a `SECURITY.md` policy (CodeQL code scanning runs via GitHub's default setup)
+
+### Fixed
+
+- **Windows build**: upgraded node-gyp to 13 and dropped Node 20 from the CI matrix; pinned Windows CI to `windows-2022` to avoid the VS 2026 MSVC internal compiler error (C1001); fixed Windows zlib detection and addon linking
+
+## [0.6.4] - 2026-06-26
+
+### Fixed
+
+- **Double-free on teardown**: fixed a double free of the addon instance data during Node.js environment teardown
+
 ## [0.6.3] - 2026-04-26
 
 ### Changed
@@ -156,3 +192,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 - Release pipeline with prebuild generation and npm provenance
 - QEMU-based cross-compilation for Linux arm64/arm and musl variants
 - vcpkg integration for Windows static linking
+
+[Unreleased]: https://github.com/xonaman/nodejs-qpdf-compress/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/xonaman/nodejs-qpdf-compress/compare/v0.6.4...v0.7.0
+[0.6.4]: https://github.com/xonaman/nodejs-qpdf-compress/compare/v0.6.3...v0.6.4
+[0.6.3]: https://github.com/xonaman/nodejs-qpdf-compress/compare/v0.6.2...v0.6.3
+[0.6.2]: https://github.com/xonaman/nodejs-qpdf-compress/compare/v0.6.1...v0.6.2
+[0.6.1]: https://github.com/xonaman/nodejs-qpdf-compress/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/xonaman/nodejs-qpdf-compress/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/xonaman/nodejs-qpdf-compress/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/xonaman/nodejs-qpdf-compress/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/xonaman/nodejs-qpdf-compress/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/xonaman/nodejs-qpdf-compress/compare/v0.1.3...v0.2.0
+[0.1.3]: https://github.com/xonaman/nodejs-qpdf-compress/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/xonaman/nodejs-qpdf-compress/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/xonaman/nodejs-qpdf-compress/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/xonaman/nodejs-qpdf-compress/releases/tag/v0.1.0

package/README.md

@@ -1,9 +1,10 @@
 # qpdf-compress
 
+[![CI](https://github.com/xonaman/nodejs-qpdf-compress/actions/workflows/ci.yml/badge.svg)](https://github.com/xonaman/nodejs-qpdf-compress/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/qpdf-compress)](https://www.npmjs.com/package/qpdf-compress)
 [![Node.js](https://img.shields.io/node/v/qpdf-compress)](https://nodejs.org)
 [![License](https://img.shields.io/npm/l/qpdf-compress)](https://github.com/xonaman/nodejs-qpdf-compress/blob/main/LICENSE)
-[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue)]()
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue)](#-supported-platforms)
 
 Native PDF compression for Node.js — powered by [QPDF](https://qpdf.sourceforge.io/), the industry-standard PDF transformation library. Built as a C++ addon with N-API for ABI stability across Node.js versions.
 
@@ -40,7 +41,7 @@ const smaller = await compress(pdfBuffer, { lossy: true });
 **🔒 Reliability**
 
 - Built on QPDF — the most widely used PDF structural transformation library
-- ABI-stable via N-API — works across Node.js 18–24 without recompilation
+- ABI-stable via N-API — works across Node.js 22+ without recompilation
 - Automatic repair — damaged PDFs are reconstructed during compression
 - Apache-2.0 licensed — no AGPL/copyleft concerns
 

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,44 @@
+# Third-Party Notices
+
+`qpdf-compress` is distributed under the [Apache-2.0](./LICENSE) license. The
+published package and its prebuilt native binaries statically link the
+third-party libraries listed below. Each remains under its own license, and the
+full license text of each is available from the upstream project linked.
+
+| Library  | Version            | License                                                   | Source                                 |
+| -------- | ------------------ | --------------------------------------------------------- | -------------------------------------- |
+| QPDF     | 12.3.2             | Apache-2.0                                                | <https://github.com/qpdf/qpdf>         |
+| mozjpeg  | 4.1.1              | BSD-3-Clause and IJG (with zlib-licensed SIMD components) | <https://github.com/mozilla/mozjpeg>   |
+| HarfBuzz | 14.1.0             | MIT ("Old MIT")                                           | <https://github.com/harfbuzz/harfbuzz> |
+| zlib     | bundled on Windows | zlib License                                              | <https://github.com/madler/zlib>       |
+
+## Details
+
+### QPDF
+
+Copyright Jay Berkenbilt and QPDF contributors. Licensed under the Apache
+License, Version 2.0. QPDF performs the structural PDF transformation and
+compression. See <https://github.com/qpdf/qpdf/blob/main/LICENSE.txt>.
+
+### mozjpeg
+
+Copyright the Mozilla Foundation and contributors; derived from libjpeg-turbo
+and the Independent JPEG Group (IJG) library. mozjpeg is covered by three
+licenses: the IJG License, a BSD-3-Clause-style license for libjpeg-turbo
+modifications, and the zlib License for the SIMD extensions. mozjpeg is used for
+lossless JPEG Huffman optimization and lossy JPEG re-encoding. See
+<https://github.com/mozilla/mozjpeg/blob/master/LICENSE.md>.
+
+### HarfBuzz
+
+Copyright the HarfBuzz contributors. Licensed under the "Old MIT" license. Used
+for TrueType/OpenType font handling and subsetting (`harfbuzz` and
+`harfbuzz-subset`). See
+<https://github.com/harfbuzz/harfbuzz/blob/main/COPYING>.
+
+### zlib
+
+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>.

package/binding.gyp

@@ -2,6 +2,9 @@
   "targets": [
     {
       "target_name": "qpdf_compress",
+      "variables": {
+        "cpp_std%": "c++20"
+      },
       "sources": [
         "src/qpdf_addon.cc",
         "src/jpeg.cc",
@@ -20,7 +23,7 @@
         "src"
       ],
       "defines": [
-        "NAPI_VERSION=8"
+        "NAPI_VERSION=9"
       ],
       "cflags!": [
         "-fno-exceptions"
@@ -35,7 +38,7 @@
         "-fno-exceptions"
       ],
       "cflags_cc": [
-        "-std=c++17",
+        "-std=<(cpp_std)",
         "-fvisibility=hidden"
       ],
       "conditions": [
@@ -49,7 +52,7 @@
             ],
             "xcode_settings": {
               "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
-              "CLANG_CXX_LANGUAGE_STANDARD": "c++17",
+              "CLANG_CXX_LANGUAGE_STANDARD": "<(cpp_std)",
               "GCC_SYMBOLS_PRIVATE_EXTERN": "YES",
               "DEAD_CODE_STRIPPING": "YES",
               "LLVM_LTO": "YES",
@@ -106,7 +109,7 @@
                 "WholeProgramOptimization": "true",
                 "RuntimeLibrary": 0,
                 "AdditionalOptions": [
-                  "/std:c++17"
+                  "/std:<(cpp_std)"
                 ]
               },
               "VCLinkerTool": {

package/dist/concurrency.js

@@ -1,5 +1,5 @@
 import { availableParallelism } from 'node:os';
-import pLimit from 'p-limit';
+import pLimit, {} from 'p-limit';
 let limit = pLimit(availableParallelism());
 /**
  * Gets or sets the maximum number of concurrent operations.

package/dist/concurrency.js.map

@@ -1 +1 @@
-{"version":3,"file":"concurrency.js","sourceRoot":"","sources":["../lib/concurrency.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,MAA8B,MAAM,SAAS,CAAC;AAErD,IAAI,KAAK,GAAkB,MAAM,CAAC,oBAAoB,EAAE,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,SAAS,CAAC,4CAA4C,CAAC,CAAC;QACpE,CAAC;QACD,KAAK,GAAG,MAAM,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,oBAAoB,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,KAAK,CAAC,WAAW,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,eAAe,CAAI,EAAoB;IACrD,OAAO,KAAK,CAAC,EAAE,CAAC,CAAC;AACnB,CAAC"}
+{"version":3,"file":"concurrency.js","sourceRoot":"","sources":["../lib/concurrency.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,MAAM,EAAE,EAAsB,MAAM,SAAS,CAAC;AAErD,IAAI,KAAK,GAAkB,MAAM,CAAC,oBAAoB,EAAE,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,SAAS,CAAC,4CAA4C,CAAC,CAAC;QACpE,CAAC;QACD,KAAK,GAAG,MAAM,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,oBAAoB,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,KAAK,CAAC,WAAW,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,eAAe,CAAI,EAAoB;IACrD,OAAO,KAAK,CAAC,EAAE,CAAC,CAAC;AACnB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+/** Base error for all qpdf-compress operations. */
+export declare class QpdfError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Thrown when an input or output file cannot be read or written. */
+export declare class QpdfFileError extends QpdfError {
+    constructor(message: string);
+}
+/** Thrown when the input is not a valid PDF or is too damaged to recover. */
+export declare class QpdfFormatError extends QpdfError {
+    constructor(message: string);
+}
+/** Thrown when the PDF is encrypted and cannot be opened without a password. */
+export declare class QpdfPasswordError extends QpdfError {
+    constructor(message: string);
+}
+/** Decode the native "CODE:message" convention into a typed error. */
+export declare function parseNativeError(err: unknown): QpdfError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../lib/errors.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED,qEAAqE;AACrE,qBAAa,aAAc,SAAQ,SAAS;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,6EAA6E;AAC7E,qBAAa,eAAgB,SAAQ,SAAS;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED,gFAAgF;AAChF,qBAAa,iBAAkB,SAAQ,SAAS;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,CAkBxD"}

package/dist/errors.js

@@ -0,0 +1,50 @@
+/** Base error for all qpdf-compress operations. */
+export class QpdfError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'QpdfError';
+        this.code = code;
+    }
+}
+/** Thrown when an input or output file cannot be read or written. */
+export class QpdfFileError extends QpdfError {
+    constructor(message) {
+        super('FILE', message);
+        this.name = 'QpdfFileError';
+    }
+}
+/** Thrown when the input is not a valid PDF or is too damaged to recover. */
+export class QpdfFormatError extends QpdfError {
+    constructor(message) {
+        super('FORMAT', message);
+        this.name = 'QpdfFormatError';
+    }
+}
+/** Thrown when the PDF is encrypted and cannot be opened without a password. */
+export class QpdfPasswordError extends QpdfError {
+    constructor(message) {
+        super('PASSWORD', message);
+        this.name = 'QpdfPasswordError';
+    }
+}
+/** Decode the native "CODE:message" convention into a typed error. */
+export function parseNativeError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const colonIdx = msg.indexOf(':');
+    if (colonIdx === -1)
+        return new QpdfError('UNKNOWN', msg);
+    const code = msg.slice(0, colonIdx);
+    const text = msg.slice(colonIdx + 1);
+    switch (code) {
+        case 'FILE':
+            return new QpdfFileError(text);
+        case 'FORMAT':
+            return new QpdfFormatError(text);
+        case 'PASSWORD':
+            return new QpdfPasswordError(text);
+        default:
+            return new QpdfError(code, text);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../lib/errors.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,MAAM,OAAO,SAAU,SAAQ,KAAK;IACzB,IAAI,CAAS;IACtB,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,qEAAqE;AACrE,MAAM,OAAO,aAAc,SAAQ,SAAS;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,6EAA6E;AAC7E,MAAM,OAAO,eAAgB,SAAQ,SAAS;IAC5C,YAAY,OAAe;QACzB,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,gFAAgF;AAChF,MAAM,OAAO,iBAAkB,SAAQ,SAAS;IAC9C,YAAY,OAAe;QACzB,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,sEAAsE;AACtE,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7D,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,QAAQ,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,SAAS,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAE1D,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;IAErC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,MAAM;YACT,OAAO,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC;QACjC,KAAK,QAAQ;YACX,OAAO,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;QACnC,KAAK,UAAU;YACb,OAAO,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACrC;YACE,OAAO,IAAI,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACrC,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -17,5 +17,6 @@ export declare function compress(input: PdfInput, options: CompressOptions & {
 }): Promise<void>;
 export declare function compress(input: PdfInput, options?: CompressOptions): Promise<Buffer>;
 export { concurrency } from './concurrency.js';
+export { QpdfError, QpdfFileError, QpdfFormatError, QpdfPasswordError } from './errors.js';
 export type { CompressOptions } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAe,MAAM,YAAY,CAAC;AAY/D,KAAK,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhC;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,eAAe,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAC5C,OAAO,CAAC,IAAI,CAAC,CAAC;AACjB,wBAAgB,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAuBtF,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAe,MAAM,YAAY,CAAC;AAc/D,KAAK,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhC;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,eAAe,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAC5C,OAAO,CAAC,IAAI,CAAC,CAAC;AACjB,wBAAgB,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AA2BtF,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC3F,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -2,12 +2,15 @@ import { createRequire } from 'node:module';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { withConcurrency } from './concurrency.js';
+import { parseNativeError } from './errors.js';
 const require = createRequire(import.meta.url);
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const addonDir = resolve(__dirname, '..', 'build', 'Release');
 if (process.platform === 'win32') {
     process.env.PATH = `${addonDir};${process.env.PATH ?? ''}`;
 }
+// The native addon is loaded through createRequire, so its export is `any` at
+// the module boundary; assert it to the typed surface once, here.
 const addon = require('../build/Release/qpdf_compress.node');
 export async function compress(input, options) {
     if (Buffer.isBuffer(input)) {
@@ -24,11 +27,17 @@ export async function compress(input, options) {
         throw new TypeError('Input must be a Buffer or file path string');
     }
     const stripMetadata = options?.stripMetadata ?? true;
-    return withConcurrency(() => addon.compress(input, {
-        ...(options?.lossy ? { lossy: true } : {}),
-        ...(stripMetadata ? { stripMetadata: true } : {}),
-        ...(options?.output ? { output: options.output } : {}),
-    }));
+    try {
+        return await withConcurrency(() => addon.compress(input, {
+            ...(options?.lossy ? { lossy: true } : {}),
+            ...(stripMetadata ? { stripMetadata: true } : {}),
+            ...(options?.output ? { output: options.output } : {}),
+        }));
+    }
+    catch (err) {
+        throw parseNativeError(err);
+    }
 }
 export { concurrency } from './concurrency.js';
+export { QpdfError, QpdfFileError, QpdfFormatError, QpdfPasswordError } from './errors.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGnD,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;AAC9D,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;IACjC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;AAC7D,CAAC;AAED,MAAM,KAAK,GAAgB,OAAO,CAAC,qCAAqC,CAAC,CAAC;AAqB1E,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,KAAe,EAAE,OAAyB;IACvE,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,SAAS,CAAC,8BAA8B,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;SAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACrC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,SAAS,CAAC,4BAA4B,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,SAAS,CAAC,4CAA4C,CAAC,CAAC;IACpE,CAAC;IACD,MAAM,aAAa,GAAG,OAAO,EAAE,aAAa,IAAI,IAAI,CAAC;IACrD,OAAO,eAAe,CAAC,GAAG,EAAE,CAC1B,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE;QACpB,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1C,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjD,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvD,CAAC,CACuB,CAAC;AAC9B,CAAC;AAED,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;AAC9D,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;IACjC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;AAC7D,CAAC;AAED,8EAA8E;AAC9E,kEAAkE;AAClE,MAAM,KAAK,GAAG,OAAO,CAAC,qCAAqC,CAAgB,CAAC;AAqB5E,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,KAAe,EAAE,OAAyB;IACvE,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,SAAS,CAAC,8BAA8B,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;SAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACrC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,SAAS,CAAC,4BAA4B,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,SAAS,CAAC,4CAA4C,CAAC,CAAC;IACpE,CAAC;IACD,MAAM,aAAa,GAAG,OAAO,EAAE,aAAa,IAAI,IAAI,CAAC;IACrD,IAAI,CAAC;QACH,OAAO,MAAM,eAAe,CAAC,GAAG,EAAE,CAChC,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE;YACpB,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1C,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjD,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACvD,CAAC,CACH,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC;AAED,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/lib/errors.ts

@@ -0,0 +1,54 @@
+/** Base error for all qpdf-compress operations. */
+export class QpdfError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'QpdfError';
+    this.code = code;
+  }
+}
+
+/** Thrown when an input or output file cannot be read or written. */
+export class QpdfFileError extends QpdfError {
+  constructor(message: string) {
+    super('FILE', message);
+    this.name = 'QpdfFileError';
+  }
+}
+
+/** Thrown when the input is not a valid PDF or is too damaged to recover. */
+export class QpdfFormatError extends QpdfError {
+  constructor(message: string) {
+    super('FORMAT', message);
+    this.name = 'QpdfFormatError';
+  }
+}
+
+/** Thrown when the PDF is encrypted and cannot be opened without a password. */
+export class QpdfPasswordError extends QpdfError {
+  constructor(message: string) {
+    super('PASSWORD', message);
+    this.name = 'QpdfPasswordError';
+  }
+}
+
+/** Decode the native "CODE:message" convention into a typed error. */
+export function parseNativeError(err: unknown): QpdfError {
+  const msg = err instanceof Error ? err.message : String(err);
+  const colonIdx = msg.indexOf(':');
+  if (colonIdx === -1) return new QpdfError('UNKNOWN', msg);
+
+  const code = msg.slice(0, colonIdx);
+  const text = msg.slice(colonIdx + 1);
+
+  switch (code) {
+    case 'FILE':
+      return new QpdfFileError(text);
+    case 'FORMAT':
+      return new QpdfFormatError(text);
+    case 'PASSWORD':
+      return new QpdfPasswordError(text);
+    default:
+      return new QpdfError(code, text);
+  }
+}

package/lib/index.ts

@@ -2,6 +2,7 @@ import { createRequire } from 'node:module';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { withConcurrency } from './concurrency.js';
+import { parseNativeError } from './errors.js';
 import type { CompressOptions, NativeAddon } from './types.js';
 
 const require = createRequire(import.meta.url);
@@ -12,7 +13,9 @@ if (process.platform === 'win32') {
   process.env.PATH = `${addonDir};${process.env.PATH ?? ''}`;
 }
 
-const addon: NativeAddon = require('../build/Release/qpdf_compress.node');
+// The native addon is loaded through createRequire, so its export is `any` at
+// the module boundary; assert it to the typed surface once, here.
+const addon = require('../build/Release/qpdf_compress.node') as NativeAddon;
 
 type PdfInput = Buffer | string;
 
@@ -46,14 +49,19 @@ export async function compress(input: PdfInput, options?: CompressOptions): Prom
     throw new TypeError('Input must be a Buffer or file path string');
   }
   const stripMetadata = options?.stripMetadata ?? true;
-  return withConcurrency(() =>
-    addon.compress(input, {
-      ...(options?.lossy ? { lossy: true } : {}),
-      ...(stripMetadata ? { stripMetadata: true } : {}),
-      ...(options?.output ? { output: options.output } : {}),
-    }),
-  ) as Promise<Buffer | void>;
+  try {
+    return await withConcurrency(() =>
+      addon.compress(input, {
+        ...(options?.lossy ? { lossy: true } : {}),
+        ...(stripMetadata ? { stripMetadata: true } : {}),
+        ...(options?.output ? { output: options.output } : {}),
+      }),
+    );
+  } catch (err) {
+    throw parseNativeError(err);
+  }
 }
 
 export { concurrency } from './concurrency.js';
+export { QpdfError, QpdfFileError, QpdfFormatError, QpdfPasswordError } from './errors.js';
 export type { CompressOptions } from './types.js';

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "qpdf-compress",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "description": "Native PDF compression for Node.js, powered by QPDF",
   "license": "Apache-2.0",
   "type": "module",
+  "packageManager": "npm@11.17.0",
   "engines": {
-    "node": ">=20.11.0"
+    "node": ">=22.0.0"
   },
   "keywords": [
     "pdf",
@@ -31,7 +32,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -41,6 +43,7 @@
     "binding.gyp",
     "README.md",
     "CHANGELOG.md",
+    "THIRD-PARTY-NOTICES.md",
     "LICENSE"
   ],
   "repository": {
@@ -73,7 +76,10 @@
     "download:mozjpeg": "node scripts/download-mozjpeg.mjs",
     "download:qpdf": "node scripts/download-qpdf.mjs",
     "download:harfbuzz": "node scripts/download-harfbuzz.mjs",
+    "verify:checksums": "node scripts/verify-checksums.mjs",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
     "lint": "eslint --fix .",
     "lint:check": "eslint .",
     "format": "prettier --write .",
@@ -81,8 +87,8 @@
     "prepare": "husky && tsc"
   },
   "lint-staged": {
-    "*.{ts,js,json,md,yaml,yml}": "prettier --write",
-    "*.{ts,js}": "eslint --max-warnings 0"
+    "*.{ts,js,mjs,cjs,json,md,yaml,yml}": "prettier --write",
+    "*.{ts,js,mjs,cjs}": "eslint --max-warnings 0"
   },
   "dependencies": {
     "node-addon-api": "^8.0.0",
@@ -91,15 +97,16 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^4.1.4",
     "eslint": "^10.1.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.5",
+    "globals": "^17.0.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.4.0",
     "node-gyp": "^13.0.0",
     "prettier": "^3.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.57.2",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.4"
   }
 }

package/scripts/download-harfbuzz.mjs

@@ -1,11 +1,10 @@
 import { execFileSync } from 'node:child_process';
-import { createWriteStream, mkdirSync, existsSync, rmSync, cpSync, readdirSync } from 'node:fs';
-import { pipeline } from 'node:stream/promises';
-import { Readable } from 'node:stream';
+import { mkdirSync, existsSync, rmSync, cpSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { downloadFile, extractTarball, loadManifest } from './lib/integrity.mjs';
 
-const HARFBUZZ_VERSION = '14.1.0';
-const BASE_URL = 'https://github.com/harfbuzz/harfbuzz/archive/refs/tags';
+const { harfbuzz: dep } = loadManifest();
+const HARFBUZZ_VERSION = dep.version;
 
 const root = join(import.meta.dirname, '..');
 const depsDir = join(root, 'deps', 'harfbuzz');
@@ -21,27 +20,19 @@ if (!/^\d+\.\d+\.\d+$/.test(HARFBUZZ_VERSION)) {
   process.exit(1);
 }
 
-const url = `${BASE_URL}/${HARFBUZZ_VERSION}.tar.gz`;
 const tarball = join(root, `harfbuzz-${HARFBUZZ_VERSION}.tar.gz`);
 const srcDir = join(root, `harfbuzz-${HARFBUZZ_VERSION}`);
 const buildDir = join(root, 'build-harfbuzz');
 
-// step 1: download
+// step 1: download (origin- and SHA-256-pinned via native-deps.json)
 console.log(`Downloading HarfBuzz ${HARFBUZZ_VERSION}...`);
-console.log(`URL: ${url}`);
-
-const response = await fetch(url, { redirect: 'follow' });
-if (!response.ok) {
-  console.error(`Download failed: ${response.status} ${response.statusText}`);
-  process.exit(1);
-}
+console.log(`URL: ${dep.url}`);
 
 mkdirSync(join(root, 'deps'), { recursive: true });
-await pipeline(Readable.fromWeb(response.body), createWriteStream(tarball));
-
-console.log('Extracting...');
-execFileSync('tar', ['-xzf', tarball, '-C', root], { stdio: 'inherit' });
-rmSync(tarball);
+await downloadFile(dep.url, tarball, { expectedSha256: dep.sha256, allowedOrigin: dep.origin });
+console.log('Checksum verified. Extracting...');
+extractTarball(tarball, root);
+rmSync(tarball, { force: true });
 
 // GitHub archive tarballs extract to `harfbuzz-{tag}` — find it
 if (!existsSync(srcDir)) {

package/scripts/download-mozjpeg.mjs

@@ -1,11 +1,10 @@
 import { execFileSync } from 'node:child_process';
-import { createWriteStream, mkdirSync, existsSync, rmSync, readdirSync } from 'node:fs';
-import { pipeline } from 'node:stream/promises';
-import { Readable } from 'node:stream';
+import { mkdirSync, existsSync, rmSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { downloadFile, extractTarball, loadManifest } from './lib/integrity.mjs';
 
-const MOZJPEG_VERSION = '4.1.1';
-const BASE_URL = 'https://github.com/mozilla/mozjpeg/archive/refs/tags';
+const { mozjpeg: dep } = loadManifest();
+const MOZJPEG_VERSION = dep.version;
 
 const root = join(import.meta.dirname, '..');
 const depsDir = join(root, 'deps', 'mozjpeg');
@@ -21,27 +20,19 @@ if (!/^\d+\.\d+\.\d+$/.test(MOZJPEG_VERSION)) {
   process.exit(1);
 }
 
-const url = `${BASE_URL}/v${MOZJPEG_VERSION}.tar.gz`;
 const tarball = join(root, `mozjpeg-${MOZJPEG_VERSION}.tar.gz`);
 const srcDir = join(root, `mozjpeg-${MOZJPEG_VERSION}`);
 const buildDir = join(root, 'build-mozjpeg');
 
-// step 1: download
+// step 1: download (origin- and SHA-256-pinned via native-deps.json)
 console.log(`Downloading mozjpeg ${MOZJPEG_VERSION}...`);
-console.log(`URL: ${url}`);
-
-const response = await fetch(url, { redirect: 'follow' });
-if (!response.ok) {
-  console.error(`Download failed: ${response.status} ${response.statusText}`);
-  process.exit(1);
-}
+console.log(`URL: ${dep.url}`);
 
 mkdirSync(join(root, 'deps'), { recursive: true });
-await pipeline(Readable.fromWeb(response.body), createWriteStream(tarball));
-
-console.log('Extracting...');
-execFileSync('tar', ['-xzf', tarball, '-C', root], { stdio: 'inherit' });
-rmSync(tarball);
+await downloadFile(dep.url, tarball, { expectedSha256: dep.sha256, allowedOrigin: dep.origin });
+console.log('Checksum verified. Extracting...');
+extractTarball(tarball, root);
+rmSync(tarball, { force: true });
 
 // GitHub archive tarballs extract to `mozjpeg-{tag}` — find the directory
 if (!existsSync(srcDir)) {

package/scripts/download-qpdf.mjs

@@ -1,11 +1,10 @@
 import { execFileSync } from 'node:child_process';
-import { createWriteStream, mkdirSync, existsSync, rmSync, cpSync, readdirSync } from 'node:fs';
-import { pipeline } from 'node:stream/promises';
-import { Readable } from 'node:stream';
+import { mkdirSync, existsSync, rmSync, cpSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { downloadFile, extractTarball, loadManifest } from './lib/integrity.mjs';
 
-const QPDF_VERSION = '12.3.2';
-const BASE_URL = 'https://github.com/qpdf/qpdf/archive/refs/tags';
+const { qpdf: dep } = loadManifest();
+const QPDF_VERSION = dep.version;
 
 const root = join(import.meta.dirname, '..');
 const depsDir = join(root, 'deps', 'qpdf');
@@ -21,27 +20,19 @@ if (!/^\d+\.\d+\.\d+$/.test(QPDF_VERSION)) {
   process.exit(1);
 }
 
-const url = `${BASE_URL}/v${QPDF_VERSION}.tar.gz`;
 const tarball = join(root, `qpdf-${QPDF_VERSION}.tar.gz`);
 const srcDir = join(root, `qpdf-${QPDF_VERSION}`);
 const buildDir = join(root, 'build-qpdf');
 
-// step 1: download
+// step 1: download (origin- and SHA-256-pinned via native-deps.json)
 console.log(`Downloading QPDF ${QPDF_VERSION}...`);
-console.log(`URL: ${url}`);
-
-const response = await fetch(url, { redirect: 'follow' });
-if (!response.ok) {
-  console.error(`Download failed: ${response.status} ${response.statusText}`);
-  process.exit(1);
-}
+console.log(`URL: ${dep.url}`);
 
 mkdirSync(join(root, 'deps'), { recursive: true });
-await pipeline(Readable.fromWeb(response.body), createWriteStream(tarball));
-
-console.log('Extracting...');
-execFileSync('tar', ['-xzf', tarball, '-C', root], { stdio: 'inherit' });
-rmSync(tarball);
+await downloadFile(dep.url, tarball, { expectedSha256: dep.sha256, allowedOrigin: dep.origin });
+console.log('Checksum verified. Extracting...');
+extractTarball(tarball, root);
+rmSync(tarball, { force: true });
 
 // GitHub archive tarballs extract to `qpdf-{tag}` (without 'v' prefix)
 // but may also be `qpdf-qpdf-{ver}` depending on repo naming — find it

package/scripts/install.mjs

@@ -6,11 +6,12 @@
  * Musl (Alpine) naming:    qpdf-compress-v{version}-linux-musl-{arch}.tar.gz
  * Contents: build/Release/qpdf_compress.node
  */
-import { execFileSync, execSync } from 'node:child_process';
+import { execSync } from 'node:child_process';
 import { createWriteStream, existsSync, mkdirSync, readFileSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
+import { extractTarball } from './lib/integrity.mjs';
 
 const root = join(import.meta.dirname, '..');
 const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
@@ -57,7 +58,7 @@ async function tryDownload() {
     if (releaseUrl.origin !== releaseOrigin) {
       throw new Error(`Unexpected URL origin: ${releaseUrl.origin}`);
     }
-    const res = await fetch(releaseUrl, { redirect: 'follow' });
+    const res = await fetch(releaseUrl, { redirect: 'follow', signal: AbortSignal.timeout(60000) });
     if (!res.ok) {
       console.log(`No prebuilt binary found (HTTP ${res.status}), will compile from source.`);
       return false;
@@ -73,8 +74,8 @@ async function tryDownload() {
 
     await pipeline(Readable.fromWeb(body), fileStream);
 
-    // extract tar.gz into project root
-    execFileSync('tar', ['xzf', tmpTar, '-C', root], { stdio: 'inherit' });
+    // extract tar.gz into project root (hardened: no -P, no archived ownership)
+    extractTarball(tmpTar, root);
     unlinkSync(tmpTar);
 
     // verify the .node file exists

package/scripts/lib/integrity.mjs

@@ -0,0 +1,109 @@
+/**
+ * Shared download/verify helpers for the install and dependency-build scripts.
+ *
+ * Goals:
+ *  - never trust the network blindly: verify a pinned SHA-256 before use,
+ *  - survive flaky connections: timeout + exponential-backoff retry,
+ *  - never leave a half-written file behind: download to `<dest>.part` and
+ *    rename atomically only after the checksum passes,
+ *  - extract archives without restoring archived ownership or honouring
+ *    absolute/`..` paths (tar's default, kept by NOT passing -P).
+ */
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  createReadStream,
+  createWriteStream,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  renameSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Compute the SHA-256 of a file as a lowercase hex string. */
+export async function sha256File(path) {
+  const hash = createHash('sha256');
+  await pipeline(createReadStream(path), hash);
+  return hash.digest('hex');
+}
+
+/** Read the native-dependency manifest (scripts/native-deps.json). */
+export function loadManifest() {
+  return JSON.parse(readFileSync(join(import.meta.dirname, '..', 'native-deps.json'), 'utf8'));
+}
+
+/**
+ * Download `url` to `dest` with a per-attempt timeout and exponential-backoff
+ * retry. Writes to `<dest>.part` (same filesystem, so the rename is atomic) and
+ * only promotes it once the optional `expectedSha256` matches. A checksum
+ * mismatch or unexpected origin fails immediately (not retried).
+ *
+ * @param {string} url
+ * @param {string} dest
+ * @param {{ expectedSha256?: string, allowedOrigin?: string, timeoutMs?: number, retries?: number }} [opts]
+ */
+export async function downloadFile(url, dest, opts = {}) {
+  const { expectedSha256, allowedOrigin, timeoutMs = 60000, retries = 4 } = opts;
+
+  const u = new URL(url);
+  if (allowedOrigin && u.origin !== allowedOrigin) {
+    throw new Error(`Refusing to download from unexpected origin: ${u.origin}`);
+  }
+
+  mkdirSync(dirname(dest), { recursive: true });
+  const tmp = `${dest}.part`;
+
+  let lastErr;
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      const res = await fetch(u, { redirect: 'follow', signal: AbortSignal.timeout(timeoutMs) });
+      if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
+      if (!res.body) throw new Error('empty response body');
+      await pipeline(Readable.fromWeb(res.body), createWriteStream(tmp));
+
+      if (expectedSha256) {
+        const actual = await sha256File(tmp);
+        if (actual !== expectedSha256.toLowerCase()) {
+          throw new Error(
+            `checksum mismatch for ${u.href}\n  expected ${expectedSha256}\n  actual   ${actual}`,
+          );
+        }
+      }
+
+      renameSync(tmp, dest);
+      return dest;
+    } catch (err) {
+      lastErr = err;
+      rmSync(tmp, { force: true });
+      const msg = String(err?.message ?? err);
+      // integrity failures are not transient — surface them immediately
+      if (msg.includes('checksum mismatch') || msg.includes('unexpected origin')) throw err;
+      if (attempt < retries) {
+        const backoff = Math.min(1000 * 2 ** (attempt - 1), 8000);
+        console.warn(`  attempt ${attempt}/${retries} failed (${msg}); retrying in ${backoff}ms`);
+        await sleep(backoff);
+      }
+    }
+  }
+  throw new Error(`Failed to download ${u.href} after ${retries} attempts: ${lastErr?.message}`);
+}
+
+/**
+ * Extract a .tar.gz / .tar.xz into `destDir`. Compression is auto-detected.
+ * Not passing `-P` keeps tar's default refusal of absolute and `..` paths;
+ * `--no-same-owner` avoids restoring archived uid/gid.
+ *
+ * stdin is redirected from /dev/null: tar never reads it for `-xf`, and on
+ * Windows an inherited console stdin can deadlock a spawned decompressor.
+ */
+export function extractTarball(tarball, destDir, { strip } = {}) {
+  mkdirSync(destDir, { recursive: true });
+  const args = ['-xf', tarball, '-C', destDir, '--no-same-owner'];
+  if (strip) args.push('--strip-components', String(strip));
+  execFileSync('tar', args, { stdio: ['ignore', 'inherit', 'inherit'] });
+}

package/scripts/native-deps.json

@@ -0,0 +1,23 @@
+{
+  "qpdf": {
+    "version": "12.3.2",
+    "origin": "https://github.com",
+    "url": "https://github.com/qpdf/qpdf/releases/download/v12.3.2/qpdf-12.3.2.tar.gz",
+    "sha256": "6cba2f9f2cd887d905faeb99e0e51a307b217920d1bbf3e9cfbb2e8178a2deda",
+    "checksumSource": "official PGP-signed release manifest (qpdf-12.3.2.sha256)"
+  },
+  "harfbuzz": {
+    "version": "14.1.0",
+    "origin": "https://github.com",
+    "url": "https://github.com/harfbuzz/harfbuzz/archive/refs/tags/14.1.0.tar.gz",
+    "sha256": "9deffe9dded3c367c7d08265fd0a64193fad505a362a4889d898568c1cd46812",
+    "checksumSource": "self-computed from the GitHub git-archive tarball; HarfBuzz's only release asset is .tar.xz, whose extraction hangs Windows bsdtar — the gzip git-archive builds identically"
+  },
+  "mozjpeg": {
+    "version": "4.1.1",
+    "origin": "https://github.com",
+    "url": "https://github.com/mozilla/mozjpeg/archive/refs/tags/v4.1.1.tar.gz",
+    "sha256": "66b1b8d6b55d263f35f27f55acaaa3234df2a401232de99b6d099e2bb0a9d196",
+    "checksumSource": "self-computed from the GitHub archive tarball (mozilla/mozjpeg publishes no release asset or checksum)"
+  }
+}

package/scripts/verify-checksums.mjs

@@ -0,0 +1,58 @@
+/**
+ * Verify that the SHA-256 hashes pinned in native-deps.json still match what
+ * the upstream URLs serve. Use after a version bump, or in CI as a supply-chain
+ * tripwire. By default only this platform's artifacts are checked; pass --all
+ * to verify every pinned target (large download for prebuilt-binary deps).
+ */
+import { rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { downloadFile, loadManifest } from './lib/integrity.mjs';
+
+const all = process.argv.includes('--all');
+const manifest = loadManifest();
+const platform = process.platform;
+const arch = process.arch;
+
+const checks = [];
+for (const [name, dep] of Object.entries(manifest)) {
+  if (dep.targets) {
+    for (const [key, t] of Object.entries(dep.targets)) {
+      if (!all && key !== `${platform}-${arch}` && key !== `${platform}-musl-${arch}`) continue;
+      checks.push({
+        label: `${name} ${key}`,
+        url: `${dep.baseUrl}/${encodeURIComponent(dep.version)}/${t.asset}`,
+        sha256: t.sha256,
+        origin: dep.origin,
+      });
+    }
+  } else {
+    checks.push({
+      label: `${name} ${dep.version}`,
+      url: dep.url,
+      sha256: dep.sha256,
+      origin: dep.origin,
+    });
+  }
+}
+
+let failed = 0;
+for (const c of checks) {
+  const tmp = join(tmpdir(), `verify-${c.label.replace(/\W+/g, '-')}`);
+  try {
+    process.stdout.write(`Verifying ${c.label} ... `);
+    await downloadFile(c.url, tmp, { expectedSha256: c.sha256, allowedOrigin: c.origin });
+    console.log('OK');
+  } catch (err) {
+    console.log(`FAIL\n  ${err.message}`);
+    failed++;
+  } finally {
+    rmSync(tmp, { force: true });
+  }
+}
+
+if (failed) {
+  console.error(`\n${failed} checksum(s) did not match.`);
+  process.exit(1);
+}
+console.log(`\nAll ${checks.length} checksum(s) verified.`);

package/src/qpdf_addon.cc

@@ -1,6 +1,8 @@
 #include <napi.h>
 
+#include <algorithm>
 #include <atomic>
+#include <cctype>
 #include <cerrno>
 #include <cstdio>
 #include <cstdlib>
@@ -52,6 +54,28 @@ static std::string writeToFile(const std::string &path, const uint8_t *data,
   return {};
 }
 
+// ---------------------------------------------------------------------------
+// Error classification — prefix a native error message with a stable CODE so
+// the JS layer (parseNativeError) can map it to a typed QpdfError subclass.
+// Mirrors the "CODE:message" convention used by pdfium-native.
+// ---------------------------------------------------------------------------
+
+static std::string classifyError(const std::string &what) {
+  std::string lower = what;
+  std::transform(lower.begin(), lower.end(), lower.begin(),
+                 [](unsigned char c) { return std::tolower(c); });
+  auto has = [&](const char *needle) {
+    return lower.find(needle) != std::string::npos;
+  };
+  if (has("password") || has("encrypted"))
+    return "PASSWORD:" + what;
+  if (has("damaged") || has("not a pdf") || has("not well-formed") ||
+      has("invalid pdf") || has("corrupt") || has("xref") ||
+      has("unable to find") || has("/root"))
+    return "FORMAT:" + what;
+  return "COMPRESS:" + what;
+}
+
 // ---------------------------------------------------------------------------
 // Per-environment alive flag for worker thread safety.
 // When a Node.js worker thread is terminated, the V8 isolate tears down but
@@ -125,7 +149,7 @@ protected:
 
       if (useFile_) {
         if (access(filePath_.c_str(), F_OK) != 0) {
-          SetError("Input file not found: " + filePath_);
+          SetError("FILE:Input file not found: " + filePath_);
           return;
         }
         qpdf->processFile(filePath_.c_str());
@@ -192,7 +216,7 @@ protected:
         auto err = writeToFile(outputPath_, writerBuf_->getBuffer(),
                                writerBuf_->getSize());
         if (!err.empty()) {
-          SetError(err);
+          SetError("FILE:" + err);
           return;
         }
         writerBuf_.reset();
@@ -204,7 +228,7 @@ protected:
         qpdf.reset();
       } catch (...) {
       }
-      SetError(e.what());
+      SetError(classifyError(e.what()));
     } catch (...) {
       // on macOS/libc++, catch(std::exception&) may fail to match QPDFExc
       // due to typeinfo visibility mismatch between the static library and
@@ -213,7 +237,7 @@ protected:
         qpdf.reset();
       } catch (...) {
       }
-      SetError("PDF compression failed");
+      SetError("UNKNOWN:PDF compression failed");
     }
   }