asherah 4.0.41 → 4.0.42

package/index.d.ts

@@ -230,11 +230,20 @@ export declare function setenv(env: string): void;
  * const drr = asherah.encrypt('user-42', Buffer.from('secret'));
  * // store drr in your database
  * ```
+ *
+ * **Blocking the Node.js event loop**: this function runs on the JS
+ * thread and synchronously waits for the metastore (MySQL/Postgres/
+ * DynamoDB) and KMS round-trips. While it executes no other JavaScript
+ * — timers, network callbacks, GC scheduling — can run. For any
+ * production workload that touches the network on a cache miss, prefer
+ * {@link encryptAsync}, which offloads to the Rust tokio runtime and
+ * keeps the event loop responsive.
  */
 export declare function encrypt(partitionId: string, data: Buffer): string;
 
 /** Async variant of {@link encrypt}. The work runs on the Rust tokio
- *  runtime; the Node event loop is NOT blocked. */
+ *  runtime; the Node event loop is NOT blocked. Prefer this in any
+ *  service that handles concurrent requests. */
 export declare function encryptAsync(partitionId: string, data: Buffer): Promise<string>;
 
 /**
@@ -248,10 +257,16 @@ export declare function encryptAsync(partitionId: string, data: Buffer): Promise
  * @throws TypeError if either argument is null/undefined.
  * @throws Error if the JSON is malformed, the partition doesn't match,
  *               the parent key has been revoked, or the AEAD tag fails.
+ *
+ * **Blocking the Node.js event loop**: like {@link encrypt}, this runs
+ * synchronously on the JS thread and waits for any metastore/KMS calls.
+ * Use {@link decryptAsync} in services that handle concurrent traffic.
  */
 export declare function decrypt(partitionId: string, dataRowRecordJson: string): Buffer;
 
-/** Async variant of {@link decrypt}. */
+/** Async variant of {@link decrypt}. The work runs on the Rust tokio
+ *  runtime; the Node event loop stays responsive. Prefer this in any
+ *  service that handles concurrent requests. */
 export declare function decryptAsync(partitionId: string, dataRowRecordJson: string): Promise<Buffer>;
 
 /** UTF-8 string-typed wrapper around {@link encrypt}. Empty `string`
@@ -267,6 +282,27 @@ export declare function decryptString(partitionId: string, dataRowRecordJson: st
 /** Async variant of {@link decryptString}. */
 export declare function decryptStringAsync(partitionId: string, dataRowRecordJson: string): Promise<string>;
 
+/**
+ * Best-effort wipe of a plaintext `Buffer` returned by {@link decrypt}
+ * or {@link decryptAsync}.
+ *
+ * The native (Rust) buffer is volatile-wiped before the Buffer reaches
+ * JavaScript, but the V8 `Buffer` lives on the JS heap where the GC may
+ * have already copied the bytes during compaction. Pass the Buffer here
+ * to overwrite its current backing store with zeros via
+ * `buffer.fill(0)`. Mirrors `Zeroize([]byte)` in the Go binding,
+ * `AsherahSession.ZeroizePlaintext(byte[])` in .NET, and
+ * `Asherah.clearPlaintext(byte[])` in Java.
+ *
+ * **Caveat:** treat the plaintext as opaque within a tight scope and
+ * never copy or substring it before clearing — V8 may have aliased
+ * portions of the underlying ArrayBuffer that this call doesn't reach.
+ *
+ * T-finding "Node has no parallel `clearPlaintext`" in
+ * `docs/review-2026-05-05-findings.md`.
+ */
+export declare function clearPlaintext(plaintext: Buffer | null | undefined): void;
+
 // ─── Factory / Session API (recommended) ────────────────────────────────────
 
 /**

package/npm/index.js

@@ -154,12 +154,10 @@ const METASTORE_ALIASES = {
 
 // Legacy/debug KMS aliases.
 //
-// `test-debug-static` is intentionally NOT aliased to `static` here:
-// the Rust core has a dedicated `test-debug-static` KMS kind that
-// auto-supplies a publicly-known test key. Rewriting it to `static`
-// would trip the `KMS=static requires STATIC_MASTER_KEY_HEX`
-// validation (commit 9049fa4) and break every binding test that
-// uses the debug fixture.
+// The Rust core treats `static` and `test-debug-static` as synonyms
+// — both fall back to the publicly known test key when no hex is
+// supplied — so no JS-side normalization is needed. The map is kept
+// as a hook for future aliases.
 const KMS_ALIASES = {};
 
 function normalizeConfig(config) {
@@ -269,6 +267,23 @@ function decryptAsync(partitionId, dataRowRecord) {
   return native.decryptAsync(partitionId, toBuffer(dataRowRecord));
 }
 
+// Best-effort wipe of a plaintext Buffer. The native (Rust) buffer is
+// volatile-wiped before reaching JS; this clears the JS-side copy.
+// V8 may have aliased portions of the ArrayBuffer that this call
+// doesn't reach, so the wipe is best-effort. Mirrors Go's `Zeroize`,
+// .NET's `ZeroizePlaintext`, and Java's `clearPlaintext`. T-finding
+// "Node has no parallel clearPlaintext" in
+// docs/review-2026-05-05-findings.md.
+function clearPlaintext(plaintext) {
+  if (plaintext == null) {
+    return;
+  }
+  if (typeof plaintext.fill !== 'function') {
+    throw new TypeError('clearPlaintext: argument must be a Buffer or Uint8Array');
+  }
+  plaintext.fill(0);
+}
+
 // Export everything from native addon
 Object.assign(module.exports, native);
 
@@ -277,6 +292,7 @@ module.exports.setup = setup;
 module.exports.setupAsync = setupAsync;
 module.exports.decrypt = decrypt;
 module.exports.decryptAsync = decryptAsync;
+module.exports.clearPlaintext = clearPlaintext;
 
 // snake_case aliases for canonical API compatibility
 module.exports.setup_async = setupAsync;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asherah",
-  "version": "4.0.41",
+  "version": "4.0.42",
   "private": false,
   "description": "Asherah application-layer encryption for Node.js with automatic key rotation, powered by the native Rust implementation.",
   "author": "Jay Gowdy",
@@ -57,11 +57,12 @@
   "scripts": {
     "build": "napi build",
     "build:release": "napi build --release",
-    "test": "node test/roundtrip.js && node test/e2e-consumer.js",
-    "test:unit": "node test/roundtrip.js",
+    "test": "node test/roundtrip.js && node test/rotation.js && node test/e2e-consumer.js",
+    "test:unit": "node test/roundtrip.js && node test/rotation.js",
+    "test:rotation": "node test/rotation.js",
     "test:e2e": "node test/e2e-consumer.js",
     "test:e2e-aws": "node test/e2e-aws.js",
-    "test:bun": "bun test/roundtrip.js && bun test/e2e-consumer.js && bun test/bun-compat.js"
+    "test:bun": "bun test/roundtrip.js && bun test/rotation.js && bun test/e2e-consumer.js && bun test/bun-compat.js"
   },
   "devDependencies": {
     "@napi-rs/cli": "^2.18.0"
@@ -70,13 +71,13 @@
     "node": ">= 18"
   },
   "optionalDependencies": {
-    "asherah-darwin-arm64": "4.0.41",
-    "asherah-darwin-x64": "4.0.41",
-    "asherah-linux-x64-gnu": "4.0.41",
-    "asherah-linux-arm64-gnu": "4.0.41",
-    "asherah-linux-x64-musl": "4.0.41",
-    "asherah-linux-arm64-musl": "4.0.41",
-    "asherah-windows-x64": "4.0.41",
-    "asherah-windows-arm64": "4.0.41"
+    "asherah-darwin-arm64": "4.0.42",
+    "asherah-darwin-x64": "4.0.42",
+    "asherah-linux-x64-gnu": "4.0.42",
+    "asherah-linux-arm64-gnu": "4.0.42",
+    "asherah-linux-x64-musl": "4.0.42",
+    "asherah-linux-arm64-musl": "4.0.42",
+    "asherah-windows-x64": "4.0.42",
+    "asherah-windows-arm64": "4.0.42"
   }
 }