gatekeeper-cdr 0.4.0 → 0.4.6

package/README.md

@@ -0,0 +1,42 @@
+# Gatekeeper CDR (Node.js)
+
+This package provides native Node.js bindings to the Gatekeeper CDR core, a zero-trust Content Disarm and Reconstruction engine. It sanitizes potentially malicious files by deeply inspecting and rebuilding them from raw pixel data, effectively stripping away any steganography, macros, or hidden exploits.
+
+## Installation
+
+```bash
+npm install gatekeeper-cdr
+```
+
+*(Note: Because this is a native Rust addon, pre-built binaries are downloaded automatically during installation for Linux, macOS, and Windows. You do not need Rust installed to use this package).*
+
+## Usage
+
+```javascript
+const fs = require('fs');
+const gatekeeper = require('gatekeeper-cdr');
+
+// 1. Read a suspicious file
+const rawPayload = fs.readFileSync('suspicious.jpg');
+
+// 2. Detect the true format of the file without fully parsing it
+try {
+  const format = gatekeeper.sniffFormat(rawPayload);
+  console.log(`Detected Format: ${format}`); // "Jpeg", "Png", etc.
+} catch (err) {
+  console.error("Unknown or invalid format:", err);
+}
+
+// 3. Disarm the file (returns a clean Buffer)
+try {
+  const cleanPayload = gatekeeper.disarm(rawPayload);
+  fs.writeFileSync('clean.png', cleanPayload);
+  console.log("File successfully sanitized and saved as clean.png!");
+} catch (err) {
+  console.error("Failed to sanitize file:", err);
+}
+```
+
+## Security
+
+If the file is malformed, structurally invalid, or contains an unknown format, Gatekeeper will intentionally throw an error rather than attempting to process it. This default-deny stance ensures that only provably safe files make it into your application's storage.

package/index.d.ts

@@ -18,3 +18,22 @@ export interface NodeDisarmResult {
  * @param expectedFormat (Optional) Strict format hint (e.g. "pdf", "png"). Rejects if mismatch.
  */
 export declare function disarm(rawBuffer: Uint8Array, expectedFormat?: string | undefined | null): NodeDisarmResult
+/**
+ * Async, non-blocking Content Disarm and Reconstruction pipeline.
+ *
+ * Returns a `Promise<NodeDisarmResult>` that resolves on a background
+ * thread pool, leaving the Node.js event loop completely free.
+ *
+ * @example
+ * ```js
+ * const { disarmAsync } = require('gatekeeper-cdr');
+ * const fs = require('fs');
+ *
+ * async function sanitize(path) {
+ *   const input = fs.readFileSync(path);
+ *   const result = await disarmAsync(input);
+ *   return result.buffer; // clean, safe bytes
+ * }
+ * ```
+ */
+export declare function disarmAsync(rawBuffer: Buffer): Promise<unknown>

package/index.js

@@ -310,6 +310,7 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { disarm } = nativeBinding
+const { disarm, disarmAsync } = nativeBinding
 
 module.exports.disarm = disarm
+module.exports.disarmAsync = disarmAsync

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "gatekeeper-cdr",
-  "version": "0.4.0",
+  "version": "0.4.6",
   "description": "Zero-trust Content Disarm and Reconstruction native Node.js addon",
   "main": "index.js",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "*.node"
+  ],
   "napi": {
     "name": "gatekeeper"
   },

package/test.js

@@ -1,36 +0,0 @@
-const gatekeeper = require('./index.js');
-const fs = require('fs');
-
-console.log("Testing Gatekeeper CDR Node.js Bindings...\n");
-
-// 1. Test garbage bytes (Expect Exception)
-const garbage = Buffer.from("UNKNOWN_MAGIC_BYTES_123");
-try {
-    gatekeeper.disarm(garbage, null);
-    console.error("❌ FAILED: Should have rejected garbage bytes.");
-} catch (e) {
-    console.log("✅ Passed: Caught expected error for garbage:");
-    console.log("   ->", e.message);
-}
-
-// 2. Test FormatMismatch (Expect Exception)
-const pngSignature = Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0x00, 0x00, 0x00, 0x0D, 0x49, 0x48, 0x44, 0x52]);
-try {
-    gatekeeper.disarm(pngSignature, "pdf");
-    console.error("❌ FAILED: Should have rejected due to FormatMismatch.");
-} catch (e) {
-    console.log("✅ Passed: Caught expected error for FormatMismatch:");
-    console.log("   ->", e.message);
-}
-
-// 3. Test Minimal PDF (FFI check)
-const validPdf = Buffer.from("%PDF-1.4\nTrailer << /Root << >> >>\n%%EOF");
-try {
-    const result = gatekeeper.disarm(validPdf, "pdf");
-    console.log("✅ Passed: Sanitized PDF.");
-    console.log(`   -> Output Size: ${result.finalSizeBytes} bytes`);
-    console.log(`   -> Detected: ${result.detectedFormat}`);
-} catch (e) {
-    console.log("✅ Passed FFI (Handled gracefully via CdrError):");
-    console.log("   ->", e.message);
-}