hookarmor 1.0.2 → 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!
 ```
 
 ---
@@ -242,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.2",
+  "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/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,