hookarmor 1.0.0 → 1.0.2

package/README.md

@@ -153,6 +153,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) |
@@ -169,5 +226,27 @@ HookArmor solves this automatically:
 
 ---
 
+## 🔐 Production Security & Admin Authentication
+
+When running HookArmor locally on your laptop (`localhost`), management endpoints and the replay dashboard operate without authentication for fast developer onboarding.
+
+> [!WARNING]
+> **When deploying HookArmor to a public server or self-hosted cloud container (Railway, Render, VPS), you MUST set the `HOOKARMOR_API_KEY` environment variable.**
+
+```bash
+# Generate a strong 256-bit random key
+openssl rand -hex 32
+
+# Set in your production environment / Docker container:
+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.
+* 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.
+
+---
+
 ## 📄 License
 MIT License. Created by the HookArmor Team.

package/bin/hookarmor.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 const { Command } = require('commander');
-const chalk = require('chalk');
+const _chalk = require('chalk');
+const chalk = _chalk.default || _chalk;
 const { createServer } = require('../src/server');
 const http = require('http');
 
@@ -34,7 +35,7 @@ program
     }
 
     server.listen(port, () => {
-      console.log(chalk.bold.blue('\n🛡️  HookArmor Webhook Sentinel is LIVE!'));
+      console.log(chalk.blue.bold('\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}`)}`);
@@ -73,7 +74,7 @@ program
     });
 
     server.listen(port, () => {
-      console.log(chalk.bold.cyan(`\n⚡ HookArmor Listen Active`));
+      console.log(chalk.cyan.bold(`\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`);
     });
@@ -117,7 +118,7 @@ program
     try {
       const res = await fetch(`${baseUrl}/api/stats`);
       const data = await res.json();
-      console.log(chalk.bold.blue('\n🛡️  HookArmor Metrics'));
+      console.log(chalk.blue.bold('\n🛡️  HookArmor Metrics'));
       console.log(chalk.gray('───────────────────────'));
       console.log(`Total Ingested : ${chalk.cyan(data.total)}`);
       console.log(`Delivered      : ${chalk.green(data.delivered)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hookarmor",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Zero-loss Webhook Dead-Letter Queue (DLQ), Reliability Proxy, and Replay Gateway for Stripe, Shopify, Clerk, and B2B SaaS.",
   "main": "index.js",
   "bin": {
@@ -18,7 +18,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/pkdoddamani/hookarmor.git"
+    "url": "git+https://github.com/pkdoddamani/hookarmor.git"
   },
   "homepage": "https://hookarmour.dev",
   "bugs": {

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/public/landing.html

@@ -371,13 +371,13 @@
       </div>
     </div>
 
-    <div class="terminal-box" style="flex-direction: column; align-items: flex-start; gap: 0.5rem; width: 100%; max-width: 620px;">
+    <div class="terminal-box" style="flex-direction: column; align-items: flex-start; gap: 0.5rem; width: 100%; max-width: 520px;">
       <div style="display: flex; justify-content: space-between; width: 100%; align-items: center;">
-        <span style="font-size: 0.75rem; color: #64748b; text-transform: uppercase; letter-spacing: 0.05em; font-family: var(--font-sans); font-weight: 600;">Self-Host Quickstart (Zero Dependencies)</span>
-        <button class="copy-btn" onclick="navigator.clipboard.writeText('git clone https://github.com/pkdoddamani/hookarmor.git && cd hookarmor && npm install && npm start')">Copy</button>
+        <span style="font-size: 0.75rem; color: #10b981; text-transform: uppercase; letter-spacing: 0.05em; font-family: var(--font-sans); font-weight: 700;">● Verified on npm (Zero Config)</span>
+        <button class="copy-btn" onclick="navigator.clipboard.writeText('npx hookarmor start')">Copy</button>
       </div>
-      <div style="color: #38bdf8; font-size: 0.85rem; word-break: break-all;">
-        $ git clone https://github.com/pkdoddamani/hookarmor.git && cd hookarmor && npm start
+      <div style="color: #38bdf8; font-size: 1.05rem; font-weight: 600;">
+        $ npx hookarmor start
       </div>
     </div>
 

package/src/server.js

@@ -322,39 +322,44 @@ function createServer(options = {}) {
   // SEO & Web Crawler Discovery
   app.get('/robots.txt', (req, res) => {
     res.type('text/plain');
-    res.sendFile(path.join(__dirname, 'public', 'robots.txt'));
+    res.sendFile('robots.txt', { root: path.join(__dirname, 'public') });
   });
 
   app.get('/sitemap.xml', (req, res) => {
     res.type('application/xml');
-    res.sendFile(path.join(__dirname, 'public', 'sitemap.xml'));
+    res.sendFile('sitemap.xml', { root: path.join(__dirname, 'public') });
   });
 
   app.get('/og-preview.png', (req, res) => {
     res.type('image/png');
-    res.sendFile(path.join(__dirname, 'public', 'og-preview.png'));
+    res.sendFile('og-preview.png', { root: path.join(__dirname, 'public') });
   });
 
-  // Landing Page Route
+  // Root Route: Dashboard if run locally via CLI; Landing page on cloud deployment
   app.get('/', (req, res) => {
-    res.sendFile(path.join(__dirname, 'public', 'landing.html'));
+    const isCloudProduction = Boolean(process.env.RAILWAY_ENVIRONMENT || process.env.RENDER || process.env.NODE_ENV === 'production');
+    if (!isCloudProduction) {
+      return res.sendFile('index.html', { root: path.join(__dirname, 'public') });
+    }
+    res.sendFile('landing.html', { root: path.join(__dirname, 'public') });
   });
 
   // Interactive Dashboard Routes
   app.get(['/dashboard', '/app'], (req, res) => {
-    res.sendFile(path.join(__dirname, 'public', 'index.html'));
+    res.sendFile('index.html', { root: path.join(__dirname, 'public') });
   });
 
   // Engineering Blog Routes
   app.get('/blog', (req, res) => {
-    res.sendFile(path.join(__dirname, 'public', 'blog', 'index.html'));
+    res.sendFile('index.html', { root: path.join(__dirname, 'public', 'blog') });
   });
 
   app.get('/blog/:slug', (req, res) => {
     const slug = req.params.slug.replace(/[^a-zA-Z0-9-_]/g, '');
-    const filePath = path.join(__dirname, 'public', 'blog', `${slug}.html`);
+    const fileName = `${slug}.html`;
+    const filePath = path.join(__dirname, 'public', 'blog', fileName);
     if (fs.existsSync(filePath)) {
-      return res.sendFile(filePath);
+      return res.sendFile(fileName, { root: path.join(__dirname, 'public', 'blog') });
     }
     res.redirect('/blog');
   });