hookarmor 1.0.1 → 1.0.3

package/README.md

@@ -3,8 +3,8 @@
 > **Zero-loss Webhook Dead-Letter Queue (DLQ), Reliability Proxy, and Replay Gateway for Stripe, Shopify, Clerk, and modern B2B SaaS.**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Tests: Passing](https://img.shields.io/badge/Tests-7%20Passing-brightgreen.svg)]()
-[![Status: Production Ready](https://img.shields.io/badge/Status-v1.0.0-blueviolet.svg)]()
+[![Tests: Passing](https://img.shields.io/badge/Tests-8%20Passing-brightgreen.svg)]()
+[![Status: Production Ready](https://img.shields.io/badge/Status-v1.0.3-blueviolet.svg)]()
 
 ---
 
@@ -102,7 +102,7 @@ npx hookarmor replay evt_1758513516086_m8r0e7
 
 ## 📊 Verification Test Suite
 
-HookArmor includes a 7-scenario automated verification test suite covering edge cases, replay re-signing, and pool protection:
+HookArmor includes an 8-scenario automated verification test suite covering edge cases, replay re-signing, and pool protection:
 ```bash
 npm test
 ```
@@ -120,7 +120,8 @@ Test 2: Testing Ingress Signature Verification (Security Boundary)...
 Test 3: Testing 5-Minute Expiration Defeat (Fresh Outbound Re-Signing)...
   ✅ HookArmor defeated the 5-minute Stripe expiration trap:
      Stored in DB: t=1600000000 (Expired 5+ years ago)
-     Re-signed on replay: t=1790143178 (Current) -> stripe.webhooks.constructEvent succeeds!
+     Re-signed on replay: t=1790970445 (Current) -> stripe.webhooks.constructEvent succeeds!
+     Provenance verified: is-replay=true, orig-sig preserved.
 
 Test 4: Simulating Downstream Failure (500) -> Dead-Letter Queue...
   ✅ Event safely quarantined in Dead-Letter Queue with HTTP 500.
@@ -135,7 +136,12 @@ Test 6: Testing Concurrency Limiting (Pool Protection)...
 Test 7: Testing Safe Idempotency Key Deduplication...
   ✅ Duplicate event intercepted and suppressed cleanly.
 
-🎉 ALL 7 HARDENED HOOKARMOR VERIFICATION TESTS PASSED PERFECTLY!
+Test 8: Testing API Key Authentication & Route Lockdown...
+  ✅ Unauthenticated reads and replays rejected with 401.
+  ✅ Bearer token and x-api-key headers validated with 200.
+  ✅ Ingress gateway remains open for external webhook providers.
+
+🎉 ALL 8 HARDENED HOOKARMOR VERIFICATION TESTS PASSED PERFECTLY!
 ```
 
 ---
@@ -153,6 +159,63 @@ HookArmor solves this automatically:
 
 ---
 
+## 🛡️ Provenance Headers & Out-of-Order Replay Protection
+
+When replaying dead-letter events hours or days later, applying payloads out of order can accidentally clobber newer database state (e.g., an older `customer.subscription.updated` event overwriting a newer cancellation).
+
+To protect downstream handlers against state drift, HookArmor injects explicit provenance headers on every forward and replay:
+
+* `x-hookarmor-delivery-id`: Unique HookArmor event delivery ID.
+* `x-hookarmor-attempt`: Current delivery attempt number (e.g., `1` on initial, `2+` on retries).
+* `x-hookarmor-original-timestamp`: The exact ISO-8601 timestamp when the webhook originally arrived at the ingress edge.
+* `x-hookarmor-is-replay`: Set to `'true'` during automated retries and manual dashboard replays (`'false'` on initial delivery).
+* `x-hookarmor-original-stripe-signature`: Preserves the authentic original Stripe signature for audit logs and forensic verification.
+
+**Recommended Downstream Handler Pattern:**
+```javascript
+app.post('/api/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
+  // Standard verification passes 100% of the time
+  const event = stripe.webhooks.constructEvent(req.body, req.headers['stripe-signature'], endpointSecret);
+
+  // If this is a replay, verify you are not clobbering newer database state:
+  if (req.headers['x-hookarmor-is-replay'] === 'true') {
+    const originalTime = new Date(req.headers['x-hookarmor-original-timestamp']).getTime();
+    // Fetch latest object from Stripe API or check if local DB already has a newer updated_at timestamp
+  }
+
+  res.json({ received: true });
+});
+```
+
+---
+
+## 🏛️ Dual Trust Boundaries: Transparent vs. Isolated Mode
+
+HookArmor supports two forwarding architectures depending on your team's security posture:
+
+1. **Mode A: Transparent Proxy (Default · Zero Code Changes)**
+   * HookArmor re-signs the outbound request using your provider secret with `t=now`.
+   * Your existing application code (`stripe.webhooks.constructEvent()`) runs unmodified.
+   * Original signatures are preserved in `x-hookarmor-original-stripe-signature`.
+
+2. **Mode B: Isolated Trust Boundary (Enterprise Security)**
+   * Set the `HOOKARMOR_SIGNING_SECRET` environment variable.
+   * HookArmor attaches an isolated `x-hookarmor-signature: t=..., v1=...` HMAC header using your internal secret.
+   * Downstream handlers verify HookArmor as the internal sender, maintaining strict separation between external Stripe signatures and internal relay deliveries.
+
+---
+
+## ⚠️ Production Durability: The Early 200 OK Tradeoff
+
+HookArmor returns an immediate `200 OK` to Stripe and Shopify in `<10ms` to protect your ingress latency and prevent providers from marking your endpoint failed during downstream outages.
+
+**What this means for production operators:**
+* Once HookArmor returns `200 OK`, Stripe considers the webhook delivered and **halts its external retry backup**.
+* HookArmor's embedded SQLite database assumes **sole custody** of that event.
+* **Persistent storage is mandatory:** When deploying via Docker, you must mount the data volume (`-v $(pwd)/data:/app/data`) and ensure host-level backups are active.
+
+---
+
 ## 📦 Hosted Cloud & Self-Hosting
 
 | Feature | Self-Hosted (MIT) | Hosted Cloud Starter ($29/mo) | Hosted Cloud Pro ($79/mo) |
@@ -185,7 +248,9 @@ HOOKARMOR_API_KEY=ha_sec_your_secure_random_key_here
 ```
 
 When `HOOKARMOR_API_KEY` is present:
-* Management endpoints (`/api/endpoints`, `/api/events/replay-all`, and waitlist exports) strictly reject unauthenticated requests and require an `Authorization: Bearer <key>` header.
+* All management and inspection endpoints (`/api/stats`, `/api/endpoints`, `/api/events`, `/api/events/:id/replay`, `/api/events/replay-all`) strictly reject unauthenticated requests with `401 Unauthorized` and require `Authorization: Bearer <key>` or `X-Api-Key: <key>`.
+* Ingress webhook receiving (`/in/:endpointId`) and public waitlist signups remain open for incoming traffic.
+* Public read-only demo access can only be enabled if explicitly running with `HOOKARMOR_DEMO_MODE=true` (for isolated marketing sandboxes).
 * Query parameter authentication (`?api_key=...`) is strictly prohibited to avoid leaking tokens into browser history and proxy access logs.
 * The web dashboard displays an **Admin Login** prompt storing your key only in ephemeral session memory.
 

package/bin/hookarmor.js

@@ -11,12 +11,12 @@ const program = new Command();
 program
   .name('hookarmor')
   .description('🛡️ HookArmor: Webhook Dead-Letter Queue & Replay Sentinel')
-  .version('1.0.0');
+  .version('1.0.3');
 
 program
   .command('start')
   .description('Start HookArmor server with web dashboard and ingress proxy')
-  .option('-p, --port <number>', 'Port to listen on', '4000')
+  .option('-p, --port <number>', 'Port to listen on', process.env.PORT || '4000')
   .action((options) => {
     const port = parseInt(options.port, 10);
     const { server, storage } = createServer();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hookarmor",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Zero-loss Webhook Dead-Letter Queue (DLQ), Reliability Proxy, and Replay Gateway for Stripe, Shopify, Clerk, and B2B SaaS.",
   "main": "index.js",
   "bin": {

package/src/dispatcher.js

@@ -164,11 +164,27 @@ class Dispatcher extends EventEmitter {
 
     let headers = { ...event.headers };
 
-    // Re-sign outbound headers if endpoint secret is configured
+    // Preserve original raw signatures before re-signing for audit and forensic trace
+    if (event.headers && event.headers['stripe-signature']) {
+      headers['x-hookarmor-original-stripe-signature'] = event.headers['stripe-signature'];
+    }
+    if (event.headers && event.headers['x-shopify-hmac-sha256']) {
+      headers['x-hookarmor-original-shopify-hmac'] = event.headers['x-shopify-hmac-sha256'];
+    }
+
+    // Re-sign outbound headers if endpoint secret is configured (Transparent Zero-Code-Change Mode)
     if (endpoint.secret) {
       headers = this.signHeaders(event.provider, event.raw_body, headers, endpoint.secret);
     }
 
+    // Optional Isolated Trust Domain mode: if HOOKARMOR_SIGNING_SECRET is provided
+    const internalSecret = process.env.HOOKARMOR_SIGNING_SECRET || endpoint.internal_secret;
+    if (internalSecret) {
+      const freshTs = Math.floor(Date.now() / 1000);
+      const internalSig = crypto.createHmac('sha256', internalSecret).update(`${freshTs}.${event.raw_body}`).digest('hex');
+      headers['x-hookarmor-signature'] = `t=${freshTs},v1=${internalSig}`;
+    }
+
     // Remove hop-by-hop and encoding headers
     delete headers['host'];
     delete headers['connection'];
@@ -180,6 +196,9 @@ class Dispatcher extends EventEmitter {
     headers['content-length'] = rawBuffer.length;
     headers['x-hookarmor-delivery-id'] = event.id;
     headers['x-hookarmor-attempt'] = String(event.attempts + 1);
+    headers['x-hookarmor-original-timestamp'] = event.created_at;
+    const isReplay = (event.attempts > 0 || event.status === 'replaying');
+    headers['x-hookarmor-is-replay'] = isReplay ? 'true' : 'false';
 
     return new Promise((resolve) => {
       try {

package/src/server.js

@@ -10,7 +10,7 @@ const Storage = require('./storage');
 const Dispatcher = require('./dispatcher');
 const RetryWorker = require('./worker');
 
-function isPrivateOrMetadataUrl(urlString) {
+function isPrivateOrMetadataUrl(urlString, strictSSRF = false) {
   try {
     const parsed = new URL(urlString);
     const hostname = parsed.hostname.toLowerCase();
@@ -22,6 +22,19 @@ function isPrivateOrMetadataUrl(urlString) {
     ) {
       return true;
     }
+    if (strictSSRF) {
+      if (
+        hostname === 'localhost' ||
+        hostname === '127.0.0.1' ||
+        hostname === '::1' ||
+        hostname === '0.0.0.0' ||
+        hostname.startsWith('10.') ||
+        hostname.startsWith('192.168.') ||
+        /^172\.(1[6-9]|2[0-9]|3[0-1])\./.test(hostname)
+      ) {
+        return true;
+      }
+    }
     return false;
   } catch (e) {
     return true;
@@ -186,22 +199,32 @@ function createServer(options = {}) {
   // REST API: JSON Body Parser for Dashboard / Management
   app.use(express.json());
 
-  // Management API Authentication Middleware (optional, active when HOOKARMOR_API_KEY is configured)
+  // Management API Authentication Middleware (active when HOOKARMOR_API_KEY is configured)
   const apiKey = options.apiKey || process.env.HOOKARMOR_API_KEY || null;
+  const isDemoMode = options.demoMode !== undefined 
+    ? options.demoMode 
+    : (process.env.HOOKARMOR_DEMO_MODE === 'true');
+  const strictSSRF = options.strictSSRF !== undefined
+    ? options.strictSSRF
+    : (process.env.HOOKARMOR_STRICT_SSRF === 'true');
+
   app.use('/api', (req, res, next) => {
     // Keep public waitlist signup open for landing page
     if (req.path === '/waitlist' && req.method === 'POST') return next();
 
-    // Allow public read-only demo access & replay simulation so prospective users can explore live
-    const isPublicDemo =
-      (req.method === 'GET' && (req.path === '/stats' || req.path === '/endpoints' || req.path === '/events' || /^\/events\/[^\/]+$/.test(req.path))) ||
-      (req.method === 'POST' && (req.path === '/events/replay-all' || /^\/events\/[^\/]+\/replay$/.test(req.path)));
+    // If apiKey is NOT configured and demo mode is NOT forced, allow open local dev access
+    if (!apiKey && !isDemoMode) return next();
 
-    if (isPublicDemo) return next();
+    // If explicit demo mode is active (e.g. public marketing demo sandbox), allow read-only & replay simulation
+    if (isDemoMode) {
+      const isPublicDemo =
+        (req.method === 'GET' && (req.path === '/stats' || req.path === '/endpoints' || req.path === '/events' || /^\/events\/[^\/]+$/.test(req.path))) ||
+        (req.method === 'POST' && (req.path === '/events/replay-all' || /^\/events\/[^\/]+\/replay$/.test(req.path)));
 
-    if (!apiKey) return next();
+      if (isPublicDemo) return next();
+    }
 
-    // Accept API token strictly via Authorization or X-Api-Key headers (NEVER query string URL)
+    // When apiKey is configured (production mode), strictly require authentication
     const authHeader = req.headers['authorization'] || '';
     const token = authHeader.replace(/^Bearer\s+/i, '').trim() || req.headers['x-api-key'] || '';
     if (!token || token !== apiKey) {
@@ -226,8 +249,8 @@ function createServer(options = {}) {
     if (!id || !name || !targetUrl) {
       return res.status(400).json({ error: 'id, name, and targetUrl are required' });
     }
-    if (isPrivateOrMetadataUrl(targetUrl)) {
-      return res.status(400).json({ error: 'targetUrl cannot target cloud metadata or link-local addresses (SSRF blocked)' });
+    if (isPrivateOrMetadataUrl(targetUrl, strictSSRF)) {
+      return res.status(400).json({ error: 'targetUrl cannot target cloud metadata or private network addresses (SSRF blocked)' });
     }
     const endpoint = storage.createEndpoint({
       id,