feat: harden file outputs, patch limits, and async input ownership

- All file-based diff/patch APIs now write to an exclusively-created temp
  file in the output directory and atomically rename after verification;
  failures remove the temp file and preserve any existing destination.
  This makes in-place operation (output path == input path, including
  hard-link/symlink aliases) safe.
- patch()/patchStream()/patchSingleStream() accept maxOutputBytes /
  maxWorkingMemoryBytes with finite defaults (2 GiB mem / 16 GiB file /
  256 MiB step memory); oversized header declarations are rejected before
  any allocation or output creation, and allocation failures no longer
  unwind through HDiffPatch's C frames.
- Async buffer APIs copy their inputs before queueing, so mutating or
  transferring the source buffers cannot corrupt results.
- Accept DataView inputs (checked before napi_is_buffer, which matches
  any ArrayBufferView); reject windowSize values above 2^53-1 that
  previously hit undefined float-to-integer conversion.
- Preserve the original prebuild dlopen error as err.cause when the
  node-gyp-build fallback also fails; refresh CLI help text.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: sunnylqm

README.md

@@ -12,9 +12,9 @@ npm install node-hdiffpatch
 bun add node-hdiffpatch
 ```
 
-Prebuilt binaries are bundled for: `darwin-arm64`, `darwin-x64`, `linux-x64`,
-`linux-arm64` (glibc), and `win32-x64`. Other platforms are not supported by
-the published package.
+Prebuilt binaries are bundled for: `darwin-arm64`, `linux-x64`, and
+`linux-arm64` (glibc). Other platforms (including `darwin-x64` and `win32-x64`)
+are currently not supported by the published package.
 
 ## Development
 
@@ -31,6 +31,35 @@ bun run test:bun   # run the same tests under the Bun runtime
 
 ## Usage
 
+Binary inputs accept `Buffer`, any `TypedArray`, or `DataView`.
+
+**Transactional file outputs.** Every file-based API (`diffStream`,
+`diffSingleStream`, `diffWindow`, `patchStream`, `patchSingleStream`, and the
+CLI) writes to a random temp file in the output directory, verifies the
+result, then atomically renames it over the destination. On any failure the
+temp file is removed and an existing destination file is left untouched.
+This also makes in-place operation safe: the output path may be the same file
+as an input (including via relative-path aliases, hard links, or symlinks) —
+the input is only replaced after the operation fully succeeds.
+
+**Patch resource limits.** A patch header declares its output size and
+working-memory requirement; both come from untrusted data. All patch APIs
+enforce finite caps and reject oversized declarations before allocating
+memory or creating the output file. Defaults: `maxOutputBytes` is 2 GiB for
+the in-memory `patch()` and 16 GiB for `patchStream()`/`patchSingleStream()`;
+`maxWorkingMemoryBytes` is 256 MiB. Override per call via an options object:
+
+```js
+hdiffpatch.patch(oldBuf, diffBuf, { maxOutputBytes: 64 * 1024 * 1024 });
+hdiffpatch.patchSingleStream(oldPath, diffPath, outPath, {
+  maxOutputBytes: 512 * 1024 * 1024,
+  maxWorkingMemoryBytes: 8 * 1024 * 1024,
+});
+```
+
+These limits bound resource usage; they are not a substitute for verifying
+patch provenance (signatures) and final-file hashes in your update system.
+
 ### diff(originBuf, newBuf[, options])
 
 Compare two buffers and return a new hdiffpatch patch as return value.
@@ -41,6 +70,14 @@ match finder while preserving compression level 9 and the 8 MiB dictionary.
 The default remains one thread. `diffWindow()` also accepts `windowSize` in
 the options object; the legacy positional `windowSize` remains supported.
 
+**Async behavior.** Callback-style calls run on Node's shared libuv thread
+pool: one running task occupies one pool worker (plus up to two LZMA threads
+with `compressionThreads: 2`), so many concurrent diffs can delay other
+thread-pool consumers (`fs`, `zlib`, `crypto`, DNS). Queue or cap concurrency
+for server-side batch workloads. The async buffer APIs copy their inputs
+before returning, so mutating, transferring, or detaching the source buffers
+after the call cannot affect the result.
+
 ### diffSingleStream(oldPath, newPath, outDiffPath[, cb])
 
 Create a **single-format** (same wire format as `diff()`) patch by streaming
@@ -75,23 +112,26 @@ applies and compares the generated patch before it returns, so orchestration
 layers can avoid running a redundant second round-trip check.
 `capabilities.maxCompressionThreads` is `2`.
 
-### patchSingleStream(oldPath, diffPath, outNewPath[, cb])
+### patchSingleStream(oldPath, diffPath, outNewPath[, options][, cb])
 
 Apply a single-compressed hpatch payload created by `diff` or
 `diffSingleStream` from files. This is the file-level apply path for the normal in-memory `diff`
 format. In sync mode returns `outNewPath`. In async mode, callback signature is
-`(err, outNewPath)`.
+`(err, outNewPath)`. `options` accepts `maxOutputBytes` and
+`maxWorkingMemoryBytes` (see "Patch resource limits" above).
 
 ### diffStream(oldPath, newPath, outDiffPath[, cb])
 
 Create diff file by streaming file paths (low memory). In sync mode returns
 `outDiffPath`. In async mode, callback signature is `(err, outDiffPath)`.
 The diff format is the streaming compressed format; use `patchStream` to apply it.
 
-### patchStream(oldPath, diffPath, outNewPath[, cb])
+### patchStream(oldPath, diffPath, outNewPath[, options][, cb])
 
 Apply diff file to old file and write new file by streaming. In sync mode
 returns `outNewPath`. In async mode, callback signature is `(err, outNewPath)`.
+`options` accepts `maxOutputBytes` and `maxWorkingMemoryBytes` (see "Patch
+resource limits" above).
 
 ## CLI
 

bin/hdiffpatch.js

@@ -13,13 +13,13 @@ function usage() {
       '',
       'Notes:',
       '  - Uses streaming diff/patch for low memory usage.',
-      '  - patch auto-detects the diff format (diffStream or diff/diffWithCovers output).',
+      '  - patch auto-detects the diff format (diffStream or diff/diffSingleStream output).',
       '  - Outputs are files specified by <outDiff>/<outNew>.',
     ].join('\n')
   );
 }
 
-// 两种 diff 格式的文件头:流式为 "HDIFF13",单压缩(diff()/diffWithCovers() 产物)为 "HDIFFSF20"
+// 两种 diff 格式的文件头:流式为 "HDIFF13",单压缩(diff()/diffSingleStream()/diffWindow() 产物)为 "HDIFFSF20"
 function detectDiffFormat(diffFile) {
   const header = Buffer.alloc(9);
   const fd = fs.openSync(diffFile, 'r');

index.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="node" />
 
+/** Buffer、TypedArray 和 DataView 均可作为二进制输入。 */
 export type BinaryLike = Buffer | ArrayBufferView;
 
 export type DiffCallback = (err: Error | null, result?: Buffer) => void;
@@ -15,6 +16,20 @@ export interface DiffWindowOptions extends CompressionOptions {
   windowSize?: number;
 }
 
+/**
+ * patch 侧资源上限。补丁头声明的输出大小和工作内存来自不可信输入,
+ * 超出上限的补丁在任何分配或输出文件创建之前被拒绝。
+ */
+export interface PatchOptions {
+  /**
+   * 允许的最大输出字节数。默认:内存版 patch() 2 GiB,文件版
+   * patchStream()/patchSingleStream() 16 GiB。
+   */
+  maxOutputBytes?: number;
+  /** 允许的最大补丁工作内存(stepMemSize)字节数。默认 256 MiB。 */
+  maxWorkingMemoryBytes?: number;
+}
+
 export interface NativeAddon {
   diff(oldBuf: BinaryLike, newBuf: BinaryLike): Buffer;
   diff(oldBuf: BinaryLike, newBuf: BinaryLike, options: CompressionOptions): Buffer;
@@ -26,7 +41,14 @@ export interface NativeAddon {
     cb: DiffCallback
   ): void;
   patch(oldBuf: BinaryLike, diffBuf: BinaryLike): Buffer;
+  patch(oldBuf: BinaryLike, diffBuf: BinaryLike, options: PatchOptions): Buffer;
   patch(oldBuf: BinaryLike, diffBuf: BinaryLike, cb: DiffCallback): void;
+  patch(
+    oldBuf: BinaryLike,
+    diffBuf: BinaryLike,
+    options: PatchOptions,
+    cb: DiffCallback
+  ): void;
   diffStream(oldPath: string, newPath: string, outDiffPath: string): string;
   diffStream(
     oldPath: string,
@@ -48,12 +70,25 @@ export interface NativeAddon {
     cb: StreamCallback
   ): void;
   patchStream(oldPath: string, diffPath: string, outNewPath: string): string;
+  patchStream(
+    oldPath: string,
+    diffPath: string,
+    outNewPath: string,
+    options: PatchOptions
+  ): string;
   patchStream(
     oldPath: string,
     diffPath: string,
     outNewPath: string,
     cb: StreamCallback
   ): void;
+  patchStream(
+    oldPath: string,
+    diffPath: string,
+    outNewPath: string,
+    options: PatchOptions,
+    cb: StreamCallback
+  ): void;
   diffSingleStream(oldPath: string, newPath: string, outDiffPath: string): string;
   diffSingleStream(
     oldPath: string,
@@ -79,6 +114,19 @@ export interface NativeAddon {
     oldPath: string,
     diffPath: string,
     outNewPath: string,
+    options: PatchOptions
+  ): string;
+  patchSingleStream(
+    oldPath: string,
+    diffPath: string,
+    outNewPath: string,
+    cb: StreamCallback
+  ): void;
+  patchSingleStream(
+    oldPath: string,
+    diffPath: string,
+    outNewPath: string,
+    options: PatchOptions,
     cb: StreamCallback
   ): void;
   diffWindow(
@@ -149,6 +197,17 @@ export function patch(oldBuf: BinaryLike, diffBuf: BinaryLike): Buffer;
 export function patch(
   oldBuf: BinaryLike,
   diffBuf: BinaryLike,
+  options: PatchOptions
+): Buffer;
+export function patch(
+  oldBuf: BinaryLike,
+  diffBuf: BinaryLike,
+  cb: DiffCallback
+): void;
+export function patch(
+  oldBuf: BinaryLike,
+  diffBuf: BinaryLike,
+  options: PatchOptions,
   cb: DiffCallback
 ): void;
 
@@ -182,12 +241,25 @@ export function patchStream(
   diffPath: string,
   outNewPath: string
 ): string;
+export function patchStream(
+  oldPath: string,
+  diffPath: string,
+  outNewPath: string,
+  options: PatchOptions
+): string;
 export function patchStream(
   oldPath: string,
   diffPath: string,
   outNewPath: string,
   cb: StreamCallback
 ): void;
+export function patchStream(
+  oldPath: string,
+  diffPath: string,
+  outNewPath: string,
+  options: PatchOptions,
+  cb: StreamCallback
+): void;
 export function diffSingleStream(
   oldPath: string,
   newPath: string,
@@ -221,6 +293,19 @@ export function patchSingleStream(
   oldPath: string,
   diffPath: string,
   outNewPath: string,
+  options: PatchOptions
+): string;
+export function patchSingleStream(
+  oldPath: string,
+  diffPath: string,
+  outNewPath: string,
+  cb: StreamCallback
+): void;
+export function patchSingleStream(
+  oldPath: string,
+  diffPath: string,
+  outNewPath: string,
+  options: PatchOptions,
   cb: StreamCallback
 ): void;
 

index.js

@@ -9,6 +9,7 @@ function loadNative() {
   }
 
   // 静态 require 路径便于打包工具分析；失败（缺文件、musl 等 ABI 不符）时回退 node-gyp-build
+  let prebuildError;
   try {
     switch (`${process.platform}-${process.arch}`) {
       case 'darwin-arm64':
@@ -22,9 +23,21 @@ function loadNative() {
       case 'win32-x64':
         return require('./prebuilds/win32-x64/node-hdiffpatch.node');
     }
-  } catch (err) {}
+  } catch (err) {
+    // 预编译文件存在但加载失败(GLIBC 版本、架构、缺失符号等)时,
+    // 真实的 dlopen 错误比 node-gyp-build 的笼统报错更有诊断价值,
+    // 保留为最终错误的 cause
+    prebuildError = err;
+  }
 
-  return require('node-gyp-build')(__dirname);
+  try {
+    return require('node-gyp-build')(__dirname);
+  } catch (err) {
+    if (prebuildError && err && err.cause === undefined) {
+      err.cause = prebuildError;
+    }
+    throw err;
+  }
 }
 
 const native = loadNative();

src/hdiff.cpp

@@ -1,4 +1,5 @@
 #include "hdiff.h"
+#include "temp_output.h"
 #include "../HDiffPatch/libHDiffPatch/HDiff/diff.h"
 #include "../HDiffPatch/libHDiffPatch/HPatch/patch.h"
 #include "../HDiffPatch/file_for_patch.h"
@@ -292,21 +293,25 @@ void hdiff_stream(const char* oldPath,const char* newPath,const char* outDiffPat
     TCompressPlugin_lzma2 compressPlugin;
     configure_lzma2(compressPlugin, compressionThreads);
 
+    // tempOut 先于 streams 声明:异常展开时先关流(guard 析构)再删临时文件
+    hdiffpatchNode::TempOutputFile tempOut;
     FileStreamGuard streams;
     streams.openInputs(oldPath, newPath);
-    streams.openDiffOut(outDiffPath);
+    tempOut.create(outDiffPath);
+    streams.openDiffOut(tempOut.path());
 
     create_compressed_diff_stream(&streams.newStream.base, &streams.oldStream.base,
                                   &streams.diffOutStream.base,
                                   &compressPlugin.base, kMatchBlockSize_default);
 
     streams.closeDiffOut();
-    streams.openDiffIn(outDiffPath);
+    streams.openDiffIn(tempOut.path());
     if (!check_compressed_diff(&streams.newStream.base, &streams.oldStream.base,
                                &streams.diffInStream.base, decompressPlugin)) {
         throw std::runtime_error("check_compressed_diff() failed, diff code error!");
     }
     streams.closeAllOrThrow();
+    tempOut.commit();
 }
 
 void hdiff_window(const char* oldPath,const char* newPath,const char* outDiffPath,
@@ -319,9 +324,11 @@ void hdiff_window(const char* oldPath,const char* newPath,const char* outDiffPat
     TCompressPlugin_lzma2 compressPlugin;
     configure_lzma2(compressPlugin, compressionThreads);
 
+    hdiffpatchNode::TempOutputFile tempOut;
     FileStreamGuard streams;
     streams.openInputs(oldPath, newPath);
-    streams.openDiffOut(outDiffPath);
+    tempOut.create(outDiffPath);
+    streams.openDiffOut(tempOut.path());
 
     // window 模式:大块流式匹配拿大 cover,再在 old 数据的滑动窗口内做
     // 后缀串精修。窗口默认 2MB,可调大以捕获更长距离的内容移动;
@@ -337,13 +344,14 @@ void hdiff_window(const char* oldPath,const char* newPath,const char* outDiffPat
                                          kSingleMatchScore);
 
     streams.closeDiffOut();
-    normalize_single_raw_compress_type(outDiffPath);
-    streams.openDiffIn(outDiffPath);
+    normalize_single_raw_compress_type(tempOut.path());
+    streams.openDiffIn(tempOut.path());
     if (!check_single_compressed_diff(&streams.newStream.base, &streams.oldStream.base,
                                       &streams.diffInStream.base, decompressPlugin)) {
         throw std::runtime_error("check_single_compressed_diff() failed, diff code error!");
     }
     streams.closeAllOrThrow();
+    tempOut.commit();
 }
 
 void hdiff_single_stream(const char* oldPath,const char* newPath,const char* outDiffPath,
@@ -356,21 +364,24 @@ void hdiff_single_stream(const char* oldPath,const char* newPath,const char* out
     TCompressPlugin_lzma2 compressPlugin;
     configure_lzma2(compressPlugin, compressionThreads);
 
+    hdiffpatchNode::TempOutputFile tempOut;
     FileStreamGuard streams;
     streams.openInputs(oldPath, newPath);
-    streams.openDiffOut(outDiffPath);
+    tempOut.create(outDiffPath);
+    streams.openDiffOut(tempOut.path());
 
     create_single_compressed_diff_stream(&streams.newStream.base, &streams.oldStream.base,
                                          &streams.diffOutStream.base,
                                          &compressPlugin.base, kPatchStepMemSize,
                                          kMatchBlockSize_default);
 
     streams.closeDiffOut();
-    normalize_single_raw_compress_type(outDiffPath);
-    streams.openDiffIn(outDiffPath);
+    normalize_single_raw_compress_type(tempOut.path());
+    streams.openDiffIn(tempOut.path());
     if (!check_single_compressed_diff(&streams.newStream.base, &streams.oldStream.base,
                                       &streams.diffInStream.base, decompressPlugin)) {
         throw std::runtime_error("check_single_compressed_diff() failed, diff code error!");
     }
     streams.closeAllOrThrow();
+    tempOut.commit();
 }