hookarmor 1.0.0

package/README.md

@@ -0,0 +1,173 @@
+# 🛡️ HookArmor
+
+> **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)]()
+
+---
+
+## 💥 The Problem HookArmor Solves
+
+Every developer using Stripe, Shopify, GitHub, Clerk, Paddle, or custom webhooks faces catastrophic silent revenue loss when:
+1. **Serverless cold starts & timeouts**: Next.js, Vercel, or AWS Lambda cold starts hit the 10-15s webhook limit.
+2. **Zero-downtime deploy reboots**: Container restarts on Render, Railway, or Fly.io return transient `502 Bad Gateway`.
+3. **Database connection pool exhaustion**: Prisma or Postgres locks during sudden traffic spikes cause unhandled `500 Internal Server Error`.
+4. **Stripe's painful retry schedule**: When Stripe receives a failure, it backs off exponentially (1 hour, then several hours, then days). Meanwhile, your paying customer logs in, sees "Free Plan", assumes a scam, and disputes the charge or issues a refund.
+
+---
+
+## ⚡ How HookArmor Works
+
+```
+[Stripe / Shopify / Clerk]
+            │ (POST webhook)
+            ▼
+┌───────────────────────────────────────┐
+│        HookArmor Ingress Edge         │
+│  - Returns immediate 200 OK (<10ms)   │
+│  - Stores raw payload in SQLite DLQ   │
+└───────────────────┬───────────────────┘
+                    │
+                    ▼
+┌───────────────────────────────────────┐
+│        Relay Dispatch Engine          │
+│  - Forwards request to user's server  │
+│  - Preserves exact headers & HMAC sigs│
+└───────┬───────────────────────┬───────┘
+        │                       │
+   (2xx Success)         (5xx / 4xx / Timeout)
+        ▼                       ▼
+┌───────────────┐       ┌─────────────────────────────────────┐
+│ Event Archive │       │          Dead-Letter Queue          │
+│ - Latency log │       │ - Capture error code & body         │
+│ - Status 200  │       │ - Instant Discord / Slack Alert     │
+│               │       │ - Smart exponential auto-retry      │
+└───────────────┘       │ - 1-Click UI & CLI Replay Engine    │
+                        └─────────────────────────────────────┘
+```
+
+1. **Sub-10ms Ingest**: HookArmor returns an immediate `200 OK` to the sender so Stripe or Shopify never marks the event failed.
+2. **Cryptographic Header & Signature Preservation**: Forwards exact raw bytes, `stripe-signature`, `x-shopify-hmac-sha256`, and timestamps.
+3. **Dead-Letter Queue (DLQ)**: If your server returns 500, 502, 504, 429, or times out, HookArmor safely preserves the raw event with full error diagnostics.
+4. **Instant Alerts**: Sends immediate Slack / Discord webhooks when an endpoint begins failing.
+5. **1-Click Bulk Replay**: As soon as you push your code fix, hit **Replay All Dead-Letter** in the Web UI or run `hookarmor replay --failed` to restore all customer transactions in 2 seconds.
+6. **Local Dev Tunnel**: `hookarmor listen http://localhost:3000/api/webhooks` to replay production webhooks straight into localhost debuggers.
+
+---
+
+## 🚀 Quickstart
+
+### 1-Click Cloud Deployment (Free & Self-Hosted)
+
+Deploy your own private, persistent HookArmor instance to the cloud with one click:
+
+[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template?template=https://github.com/pkdoddamani/hookarmor)
+[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/pkdoddamani/hookarmor)
+
+---
+
+### Local Quickstart
+
+#### Option A: Docker Compose (Zero Config)
+```bash
+git clone https://github.com/pkdoddamani/hookarmor.git
+cd hookarmor
+docker compose up -d
+```
+
+#### Option B: Terminal CLI
+```bash
+npx hookarmor start
+```
+* **Web Dashboard**: `http://localhost:4000`
+* **Ingress Gateway**: `http://localhost:4000/in/:endpointId`
+
+### 2. Tunnel Direct to Localhost
+```bash
+npx hookarmor listen http://localhost:3000/api/webhooks/stripe
+```
+
+### 3. Replay Failed Dead-Letter Events
+```bash
+# Replay all failed events across all endpoints
+npx hookarmor replay --failed
+
+# Replay a specific event ID
+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:
+```bash
+npm test
+```
+```
+🧪 Starting HookArmor Hardened Verification Test Suite (Post-Audit)...
+
+Test 1: Testing SSRF Protection & Endpoint Creation...
+  ✅ SSRF probe against 169.254.169.254 successfully blocked.
+  ✅ Valid endpoint created with secret.
+
+Test 2: Testing Ingress Signature Verification (Security Boundary)...
+  ✅ Forged signature rejected with 400 Bad Request.
+  ✅ Authentic signature verified, ingested, and delivered.
+
+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!
+
+Test 4: Simulating Downstream Failure (500) -> Dead-Letter Queue...
+  ✅ Event safely quarantined in Dead-Letter Queue with HTTP 500.
+     Next automated retry scheduled with exponential backoff + jitter.
+
+Test 5: Testing Background Retry Worker (Automatic Self-Healing)...
+  ✅ Background Retry Worker automatically claimed and delivered DLQ event! (Attempts: 2)
+
+Test 6: Testing Concurrency Limiting (Pool Protection)...
+  ✅ Concurrency capped at max 2 parallel in-flight connections (pool protected).
+
+Test 7: Testing Safe Idempotency Key Deduplication...
+  ✅ Duplicate event intercepted and suppressed cleanly.
+
+🎉 ALL 7 HARDENED HOOKARMOR VERIFICATION TESTS PASSED PERFECTLY!
+```
+
+---
+
+## 🔒 Defeating the 5-Minute Stripe Signature Expiration Trap
+
+Stripe's official SDK (`stripe.webhooks.constructEvent()`) enforces a strict 300-second (5-minute) tolerance on the `Stripe-Signature` timestamp `t=`.
+
+If you retry a failed webhook 15 minutes later, or replay a dead-letter event tomorrow, **standard Stripe handlers will throw `Webhook signature verification failed`**.
+
+HookArmor solves this automatically:
+1. **Ingress verification**: Validates the signature at ingress using your webhook signing secret (preventing unauthorized payloads).
+2. **Fresh re-signing on forward & replay**: When HookArmor delivers or replays the event, it re-signs the outbound payload using your secret with a current epoch timestamp `t=now`.
+3. **Zero code changes**: Your existing backend handler code remains completely untouched and verifies 100% of the time.
+
+---
+
+## 📦 Hosted Cloud & Self-Hosting
+
+| Feature | Self-Hosted (MIT) | Hosted Cloud Starter ($29/mo) | Hosted Cloud Pro ($79/mo) |
+|---|---|---|---|
+| **Ingress Proxy & Buffer** | Unlimited | 50,000 events/mo | 500,000 events/mo |
+| **Instant 200 OK Ack** | Yes (<10ms) | Yes (<10ms) | Yes (<10ms) |
+| **Dead-Letter Queue (DLQ)** | Yes | Yes | Yes |
+| **Stripe Signature Re-Signing** | Yes | Yes | Yes |
+| **Background Auto-Retries** | Yes | Yes | Yes |
+| **Concurrency Pool Limiter** | Yes | Yes | Yes |
+| **Event Retention** | Local Disk | 30 days | 90 days |
+| **Alerting** | Discord / Slack Webhook | Discord / Slack Webhook | Priority alerts + PagerDuty |
+| **Infrastructure** | Your own server | Fully managed & redundant | Fully managed & redundant |
+
+---
+
+## 📄 License
+MIT License. Created by the HookArmor Team.

package/bin/hookarmor.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const { createServer } = require('../src/server');
+const http = require('http');
+
+const program = new Command();
+
+program
+  .name('hookarmor')
+  .description('🛡️ HookArmor: Webhook Dead-Letter Queue & Replay Sentinel')
+  .version('1.0.0');
+
+program
+  .command('start')
+  .description('Start HookArmor server with web dashboard and ingress proxy')
+  .option('-p, --port <number>', 'Port to listen on', '4000')
+  .action((options) => {
+    const port = parseInt(options.port, 10);
+    const { server, storage } = createServer();
+
+    // Ensure a default mock endpoint exists for first-time onboarding
+    const defaultEp = storage.getEndpoint('demo-stripe');
+    if (!defaultEp) {
+      storage.createEndpoint({
+        id: 'demo-stripe',
+        name: 'Stripe Payments Demo',
+        targetUrl: `http://localhost:${port}/mock/target`,
+        alertWebhookUrl: '',
+        autoRetry: 1,
+        maxRetries: 5
+      });
+    }
+
+    server.listen(port, () => {
+      console.log(chalk.bold.blue('\n🛡️  HookArmor Webhook Sentinel is LIVE!'));
+      console.log(chalk.gray('─────────────────────────────────────────'));
+      console.log(`📡 Ingress Gateway : ${chalk.cyan(`http://localhost:${port}/in/:endpointId`)}`);
+      console.log(`📊 Web Dashboard   : ${chalk.green.bold(`http://localhost:${port}`)}`);
+      console.log(`⚙️  Mock Receiver  : ${chalk.yellow(`http://localhost:${port}/mock/target`)}`);
+      console.log(chalk.gray('─────────────────────────────────────────'));
+      console.log(chalk.white('Press Ctrl+C to stop.\n'));
+    });
+  });
+
+program
+  .command('listen')
+  .description('Tunnel incoming webhooks directly to a local or remote target')
+  .argument('<targetUrl>', 'Destination target URL (e.g. http://localhost:3000/api/webhook)')
+  .option('-p, --port <number>', 'Proxy port', '4000')
+  .option('-e, --endpoint <id>', 'Endpoint ID slug', 'local-dev')
+  .action(async (targetUrl, options) => {
+    const port = parseInt(options.port, 10);
+    const { server, storage, dispatcher } = createServer();
+
+    storage.createEndpoint({
+      id: options.endpoint,
+      name: `Local Tunnel -> ${targetUrl}`,
+      targetUrl,
+      autoRetry: 1,
+      maxRetries: 5
+    });
+
+    dispatcher.on('delivery', (res) => {
+      const statusStr = res.success
+        ? chalk.green.bold(`[${res.statusCode}] DELIVERED`)
+        : chalk.red.bold(`[${res.statusCode || 'ERR'}] DEAD-LETTER`);
+      console.log(`[${new Date().toLocaleTimeString()}] ${statusStr} ${res.eventId} -> ${targetUrl} (${res.latencyMs}ms)`);
+      if (!res.success && res.errorMessage) {
+        console.log(chalk.red(`   └─ Error: ${res.errorMessage}`));
+      }
+    });
+
+    server.listen(port, () => {
+      console.log(chalk.bold.cyan(`\n⚡ HookArmor Listen Active`));
+      console.log(`Forwarding: ${chalk.yellow(`http://localhost:${port}/in/${options.endpoint}`)} ➔ ${chalk.green(targetUrl)}`);
+      console.log(`Dashboard:  ${chalk.cyan(`http://localhost:${port}`)}\n`);
+    });
+  });
+
+program
+  .command('replay')
+  .description('Replay dead-letter events from terminal')
+  .argument('[eventId]', 'Specific event ID to replay')
+  .option('--failed', 'Replay all failed events')
+  .option('-u, --url <url>', 'HookArmor server URL', 'http://localhost:4000')
+  .action(async (eventId, options) => {
+    const baseUrl = options.url.replace(/\/$/, '');
+    try {
+      if (options.failed || !eventId) {
+        console.log(chalk.yellow('🔄 Replaying all dead-letter events...'));
+        const res = await fetch(`${baseUrl}/api/events/replay-all`, { method: 'POST', headers: { 'Content-Type': 'application/json' } });
+        const data = await res.json();
+        console.log(chalk.green(`✅ Dispatched replay for ${data.replayedCount} events.`));
+      } else {
+        console.log(chalk.yellow(`🔄 Replaying event ${eventId}...`));
+        const res = await fetch(`${baseUrl}/api/events/${eventId}/replay`, { method: 'POST' });
+        const data = await res.json();
+        if (data.success) {
+          console.log(chalk.green(`✅ Replay successful: HTTP ${data.statusCode} (${data.latencyMs}ms)`));
+        } else {
+          console.log(chalk.red(`❌ Replay failed: HTTP ${data.statusCode} (${data.errorMessage || 'Target rejected'})`));
+        }
+      }
+    } catch (err) {
+      console.error(chalk.red(`Failed to connect to HookArmor at ${baseUrl}: ${err.message}`));
+    }
+  });
+
+program
+  .command('status')
+  .description('Check HookArmor metrics and dead-letter queue count')
+  .option('-u, --url <url>', 'HookArmor server URL', 'http://localhost:4000')
+  .action(async (options) => {
+    const baseUrl = options.url.replace(/\/$/, '');
+    try {
+      const res = await fetch(`${baseUrl}/api/stats`);
+      const data = await res.json();
+      console.log(chalk.bold.blue('\n🛡️  HookArmor Metrics'));
+      console.log(chalk.gray('───────────────────────'));
+      console.log(`Total Ingested : ${chalk.cyan(data.total)}`);
+      console.log(`Delivered      : ${chalk.green(data.delivered)}`);
+      console.log(`Dead-Letter    : ${chalk.red(data.failed)}`);
+      console.log(`Pending        : ${chalk.yellow(data.pending)}`);
+      console.log(`Avg Latency    : ${chalk.white(`${data.avgLatencyMs} ms`)}\n`);
+    } catch (err) {
+      console.error(chalk.red(`Failed to connect to HookArmor at ${baseUrl}: ${err.message}`));
+    }
+  });
+
+program.parse();

package/index.js

@@ -0,0 +1,11 @@
+const { createServer } = require('./src/server');
+const Storage = require('./src/storage');
+const Dispatcher = require('./src/dispatcher');
+const Alerter = require('./src/alerter');
+
+module.exports = {
+  createServer,
+  Storage,
+  Dispatcher,
+  Alerter
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "hookarmor",
+  "version": "1.0.0",
+  "description": "Zero-loss Webhook Dead-Letter Queue (DLQ), Reliability Proxy, and Replay Gateway for Stripe, Shopify, Clerk, and B2B SaaS.",
+  "main": "index.js",
+  "bin": {
+    "hookarmor": "bin/hookarmor.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/hookarmor.js start",
+    "test": "node test/verify.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pkdoddamani/hookarmor.git"
+  },
+  "homepage": "https://hookarmour.dev",
+  "bugs": {
+    "url": "https://github.com/pkdoddamani/hookarmor/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "webhook",
+    "dead-letter-queue",
+    "stripe",
+    "shopify",
+    "clerk",
+    "reliability",
+    "replay",
+    "proxy",
+    "devops",
+    "micro-saas"
+  ],
+  "author": "HookArmor Team",
+  "license": "MIT",
+  "dependencies": {
+    "better-sqlite3": "^11.8.1",
+    "chalk": "^4.1.2",
+    "commander": "^12.1.0",
+    "cors": "^2.8.5",
+    "express": "^4.21.2",
+    "ws": "^8.18.0"
+  }
+}

package/src/alerter.js

@@ -0,0 +1,63 @@
+const http = require('http');
+const https = require('https');
+
+class Alerter {
+  static async sendAlert(alertWebhookUrl, { event, endpoint, attempt }) {
+    if (!alertWebhookUrl) return;
+
+    const payload = {
+      text: `🚨 [HookArmor Alert] Webhook delivery failed for endpoint: ${endpoint.name}`,
+      attachments: [
+        {
+          color: '#e02424',
+          title: `Event: ${event.event_type || 'Unknown'} (${event.id})`,
+          fields: [
+            { title: 'Endpoint', value: endpoint.name, short: true },
+            { title: 'Target URL', value: endpoint.target_url, short: true },
+            { title: 'Status Code', value: String(attempt.statusCode || 'Timeout/Error'), short: true },
+            { title: 'Attempt', value: `${event.attempts + 1} / ${endpoint.max_retries}`, short: true },
+            { title: 'Error', value: attempt.errorMessage || 'Unknown error', short: false }
+          ],
+          footer: 'HookArmor Webhook Sentinel',
+          ts: Math.floor(Date.now() / 1000)
+        }
+      ],
+      // Discord-compatible embed
+      embeds: [
+        {
+          title: `🚨 Webhook Delivery Failed: ${endpoint.name}`,
+          description: `**Event:** \`${event.event_type || event.id}\`\n**Target:** \`${endpoint.target_url}\`\n**HTTP Status:** \`${attempt.statusCode || 'Error'}\`\n**Error:** ${attempt.errorMessage || 'No response'}`,
+          color: 14689316,
+          timestamp: new Date().toISOString()
+        }
+      ]
+    };
+
+    try {
+      const url = new URL(alertWebhookUrl);
+      const isHttps = url.protocol === 'https:';
+      const client = isHttps ? https : http;
+
+      const postData = JSON.stringify(payload);
+      const req = client.request(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(postData)
+        },
+        timeout: 5000
+      });
+
+      req.on('error', (err) => {
+        console.error('[Alerter] Failed to send alert webhook:', err.message);
+      });
+
+      req.write(postData);
+      req.end();
+    } catch (err) {
+      console.error('[Alerter] Error parsing alert webhook URL:', err.message);
+    }
+  }
+}
+
+module.exports = Alerter;