hookarmor 1.2.0 → 1.2.1

package/README.md

@@ -211,7 +211,7 @@ HookArmor supports two forwarding architectures depending on your team's securit
 
 ## ⚠️ 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.
+HookArmor returns an immediate `200 OK` to Stripe and Shopify (sub-10ms when idle; measured p50 64ms, p90 153ms under concurrency 50 with `synchronous=FULL` fsync commits, sustaining ~360 events/s) 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**.
@@ -228,16 +228,16 @@ HookArmor is 100% free and open-source under the MIT license, architected specif
 
 * **Single-Process Simplicity**: Operates entirely in a single Node.js process using embedded SQLite with Write-Ahead Logging (`WAL`) and `synchronous=FULL`. It consumes <50MB RAM and eliminates the operational overhead of running external message brokers (Kafka, RabbitMQ, SQS, or Redis).
 * **Scope & Boundaries**: HookArmor is intended to run on the same VPS, container host, or private network cluster as your downstream web application. It is **not** a distributed multi-region cluster broker.
-* **Persistent Disk Required**: Because events are durably acknowledged to providers in `<5ms`, your container volume (`/app/data`) must be backed by a persistent disk or volume mount.
+* **Persistent Disk Required**: Because events are durably acknowledged to providers with immediate fsync commits, your container volume (`/app/data`) must be backed by a persistent disk or volume mount.
 
 ---
 
 ## 📊 Prometheus & Grafana Metrics
 
-HookArmor includes a native, zero-dependency Prometheus exposition endpoint at `GET /metrics`. Scrape this endpoint into your existing Prometheus or VictoriaMetrics instance to monitor webhook health:
+HookArmor includes a native, zero-dependency Prometheus exposition endpoint at `GET /metrics`. When `HOOKARMOR_API_KEY` is configured, requests must supply the key via `Authorization: Bearer <key>` or `x-api-key`. Scrape this endpoint into your existing Prometheus or VictoriaMetrics instance to monitor webhook health:
 
 ```text
-# Scraping: http://localhost:4000/metrics
+# Scraping: http://localhost:4000/metrics (Pass Authorization: Bearer <key> if enabled)
 hookarmor_uptime_seconds 8432
 hookarmor_events_total{status="delivered"} 1420
 hookarmor_events_total{status="failed"} 12

package/bin/hookarmor.js

@@ -22,7 +22,7 @@ function startServerOrExit() {
   }
 }
 
-function setupGracefulShutdown(server, dispatcher, storage) {
+function setupGracefulShutdown(server, dispatcher, storage, instanceId) {
   let shuttingDown = false;
   const shutdown = async (signal) => {
     if (shuttingDown) return;
@@ -30,11 +30,20 @@ function setupGracefulShutdown(server, dispatcher, storage) {
     console.log(chalk.yellow(`\n⏻  ${signal} received: stopping incoming traffic and draining in-flight webhooks...`));
     server.close();
     if (dispatcher && dispatcher.drain) {
-      await dispatcher.drain(15000);
+      const clean = await dispatcher.drain(15000);
+      if (!clean) {
+        console.warn(chalk.yellow(`⚠️  Drain timed out with ${dispatcher.pendingDeliveries()} deliveries still pending.`));
+      }
     }
-    if (storage && storage.db) {
+    if (storage) {
       try {
-        storage.db.pragma('wal_checkpoint(TRUNCATE)');
+        if (instanceId) {
+          storage.releaseClaimsOwnedBy(instanceId);
+          storage.deregisterInstance(instanceId);
+        }
+        if (storage.db) {
+          storage.db.pragma('wal_checkpoint(TRUNCATE)');
+        }
       } catch (_) {}
     }
     console.log(chalk.green('✔  Shutdown complete.'));
@@ -67,8 +76,8 @@ program
   .action((options) => {
     const port = parseInt(options.port, 10);
     const host = options.host;
-    const { server, storage, dispatcher, mockEnabled } = startServerOrExit();
-    setupGracefulShutdown(server, dispatcher, storage);
+    const { server, storage, dispatcher, mockEnabled, instanceId } = startServerOrExit();
+    setupGracefulShutdown(server, dispatcher, storage, instanceId);
 
     // Ensure a default mock endpoint exists for first-time onboarding (local simulation only)
     if (mockEnabled && !storage.getEndpoint('demo-stripe')) {
@@ -110,8 +119,8 @@ program
     if (host === '0.0.0.0') {
       console.warn(chalk.yellow('\n[Security Warning] hookarmor listen is bound to 0.0.0.0 — reachable by anyone on your local network. Use 127.0.0.1 for local isolation.'));
     }
-    const { server, storage, dispatcher } = startServerOrExit();
-    setupGracefulShutdown(server, dispatcher, storage);
+    const { server, storage, dispatcher, instanceId } = startServerOrExit();
+    setupGracefulShutdown(server, dispatcher, storage, instanceId);
 
     storage.createEndpoint({
       id: options.endpoint,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hookarmor",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "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

@@ -224,7 +224,11 @@ class Dispatcher extends EventEmitter {
   }
 
   pendingDeliveries() {
-    return this.activeDeliveries;
+    let queued = 0;
+    for (const q of this.waitQueues.values()) {
+      queued += q.length;
+    }
+    return this.activeDeliveries + queued;
   }
 
   async drain(timeoutMs = 15000) {

package/src/public/landing.html

@@ -486,25 +486,42 @@
           <li>✓ Web Dashboard & Inspector</li>
           <li>✓ Terminal CLI runner</li>
           <li>✓ Local Dev Tunneling</li>
-          <li>✓ Community Support</li>
+          <li>✓ Unlimited Self-Hosted Events</li>
+          <li>✓ MIT Licensed & Community Support</li>
         </ul>
         <a href="https://github.com/pkdoddamani/hookarmor" class="btn btn-outline" style="margin-top: auto;" target="_blank">Download on GitHub</a>
       </div>
 
+      <div class="pricing-card">
+        <h3>Developer Cloud</h3>
+        <div class="price">$0 <span>/ month</span></div>
+        <p style="color: var(--text-muted); font-size: 0.85rem;">Zero-setup managed buffer for side projects and prototypes.</p>
+        <ul class="feature-list">
+          <li>✓ <strong>10,000 events / month</strong></li>
+          <li>✓ <strong>7-day retention</strong> in DLQ</li>
+          <li>✓ 2 Webhook Endpoints</li>
+          <li>✓ Instant Discord & Slack Alerts</li>
+          <li>✓ Automatic Exponential Retries</li>
+          <li>✓ 1-Click UI & API Replay</li>
+        </ul>
+        <a href="#waitlist-form" onclick="focusWaitlist();" class="btn btn-outline" style="margin-top: auto;">Join Free Waitlist</a>
+      </div>
+
       <div class="pricing-card featured">
-        <div class="featured-badge">MOST POPULAR</div>
+        <div class="featured-badge">FOUNDER LOCK — $19/MO</div>
         <h3>Starter Cloud</h3>
-        <div class="price">$29 <span>/ month</span></div>
+        <div class="price">$19 <span>/ month</span></div>
         <p style="color: var(--text-muted); font-size: 0.85rem;">For growing B2B SaaS apps and indie founders.</p>
         <ul class="feature-list">
-          <li>✓ <strong>50,000 events / month</strong></li>
+          <li>✓ <strong>100,000 events / month</strong></li>
           <li>✓ <strong>30-day retention</strong> in DLQ</li>
-          <li>✓ 5 Webhook Endpoints</li>
+          <li>✓ 10 Webhook Endpoints</li>
           <li>✓ Instant Discord & Slack Alerts</li>
           <li>✓ Automatic Exponential Retries</li>
           <li>✓ 1-Click UI & API Replay</li>
+          <li>✓ <strong>Rate locked for life</strong> (First 50)</li>
         </ul>
-        <a href="#waitlist-form" onclick="focusWaitlist();" class="btn btn-primary" style="margin-top: auto;">Get Started</a>
+        <a href="#waitlist-form" onclick="focusWaitlist();" class="btn btn-primary" style="margin-top: auto;">Lock In $19/mo</a>
       </div>
 
       <div class="pricing-card">
@@ -512,12 +529,12 @@
         <div class="price">$79 <span>/ month</span></div>
         <p style="color: var(--text-muted); font-size: 0.85rem;">For high-volume e-commerce and scale-ups.</p>
         <ul class="feature-list">
-          <li>✓ <strong>250,000 events / month</strong></li>
+          <li>✓ <strong>500,000 events / month</strong></li>
           <li>✓ <strong>90-day retention</strong> in DLQ</li>
           <li>✓ Unlimited Endpoints</li>
           <li>✓ Per-Endpoint Concurrency Limiting</li>
-          <li>✓ Team Workspaces (Beta Roadmap)</li>
           <li>✓ High-Concurrency Queue Worker</li>
+          <li>✓ Priority Outbound Bandwidth</li>
         </ul>
         <a href="#waitlist-form" onclick="focusWaitlist();" class="btn btn-outline" style="margin-top: auto;">Upgrade to Scale</a>
       </div>

package/src/server.js

@@ -127,6 +127,9 @@ function createServer(options = {}) {
     console.warn(`[HookArmor] Re-queued ${recovered} event(s) that were mid-delivery when the process last stopped.`);
   }
 
+  // Fail-fast verification: ensure all endpoint secrets can be read with the active encryption key
+  storage.assertSecretsReadable(Boolean(process.env.HOOKARMOR_ALLOW_UNREADABLE_SECRETS === 'true'));
+
   // Security audit check: warn about endpoints without secrets on startup
   try {
     const initialEndpoints = storage.listEndpoints();
@@ -186,7 +189,7 @@ function createServer(options = {}) {
     socket.isAuthed = !apiKey || isDemoMode;
     let authTimer = null;
     if (!socket.isAuthed) {
-      authTimer = setTimeout(() => { if (!socket.isAuthed) socket.close(4001, 'Authentication required'); }, 15000);
+      authTimer = setTimeout(() => { if (!socket.isAuthed) socket.close(4001, 'Authentication required'); }, 5000);
       if (authTimer.unref) authTimer.unref();
     }
     // Browsers cannot set headers on WebSocket upgrades, so the key arrives as the first message
@@ -568,7 +571,7 @@ function createServer(options = {}) {
     const mockAuthMiddleware = (req, res, next) => {
       if (apiKey) {
         const header = req.headers['authorization'] || '';
-        const token = header.startsWith('Bearer ') ? header.slice(7) : (req.headers['x-api-key'] || req.query.key || '');
+        const token = header.startsWith('Bearer ') ? header.slice(7) : (req.headers['x-api-key'] || '');
         if (!tokenMatches(token)) {
           return res.status(401).json({ error: 'Unauthorized: valid API key required for /mock/config' });
         }
@@ -602,8 +605,24 @@ function createServer(options = {}) {
     });
   }
 
-  // Prometheus Metrics Exposition Endpoint
+  // Prometheus Metrics Exposition Endpoint (Requires API key if configured; otherwise loopback only)
   app.get('/metrics', (req, res) => {
+    if (apiKey) {
+      const authHeader = req.headers['authorization'] || '';
+      const token = authHeader.replace(/^Bearer\s+/i, '').trim() || req.headers['x-api-key'] || '';
+      if (!tokenMatches(token)) {
+        res.setHeader('Content-Type', 'text/plain; version=0.0.4; charset=utf-8');
+        return res.status(401).end('# Unauthorized: valid API key required for /metrics\n');
+      }
+    } else if (!isDemoMode) {
+      const remote = req.socket && req.socket.remoteAddress;
+      const isLoopbackRemote = !remote || remote === '127.0.0.1' || remote === '::1' || remote === '::ffff:127.0.0.1';
+      if (!isLoopbackRemote || !LOCAL_HOSTNAMES.has(hostnameOf(req.headers.host))) {
+        res.setHeader('Content-Type', 'text/plain; version=0.0.4; charset=utf-8');
+        return res.status(403).end('# Forbidden: loopback only without API key\n');
+      }
+    }
+
     try {
       const stats = storage.getStats();
       const endpoints = storage.listEndpoints();
@@ -642,6 +661,15 @@ function createServer(options = {}) {
     }
   });
 
+  // Health and Version Check Endpoint
+  app.get('/healthz', (req, res) => {
+    res.json({
+      status: 'ok',
+      version: require('../package.json').version,
+      uptime: Math.floor(process.uptime())
+    });
+  });
+
   // SEO & Web Crawler Discovery
   app.get('/robots.txt', (req, res) => {
     res.type('text/plain');

package/src/storage.js

@@ -429,11 +429,53 @@ class Storage {
     return info.changes > 0;
   }
 
+  // Release claims owned by a terminating instance so a successor can process them immediately
+  releaseClaimsOwnedBy(instanceId) {
+    if (!instanceId) return 0;
+    const stmt = this.db.prepare(`
+      UPDATE events
+      SET status = 'pending',
+          claimed_by = NULL,
+          claimed_at = NULL,
+          updated_at = datetime('now')
+      WHERE status = 'replaying' AND claimed_by = ?
+    `);
+    return stmt.run(instanceId).changes;
+  }
+
+  // Deregister an instance on clean shutdown
+  deregisterInstance(instanceId) {
+    if (!instanceId) return 0;
+    return this.db.prepare('DELETE FROM instances WHERE id = ?').run(instanceId).changes;
+  }
+
+  // Fail-fast assertion: verify all configured endpoint secrets can be decrypted
+  assertSecretsReadable(allowUnreadable = false) {
+    const endpoints = this.db.prepare('SELECT id, secret FROM endpoints').all();
+    const unreadable = [];
+    for (const ep of endpoints) {
+      if (!ep.secret) continue;
+      try {
+        decryptSecret(ep.secret, this.encryptionKey);
+      } catch (err) {
+        unreadable.push(ep.id);
+      }
+    }
+    if (unreadable.length > 0 && !allowUnreadable) {
+      throw new Error(
+        `Failed to decrypt signing secrets for endpoint(s): ${unreadable.join(', ')}. ` +
+        `HOOKARMOR_ENCRYPTION_KEY may be missing or invalid. ` +
+        `Set HOOKARMOR_ALLOW_UNREADABLE_SECRETS=true to start anyway.`
+      );
+    }
+    return unreadable.length === 0;
+  }
+
   // Run at startup or worker tick:
   // Reclaim events if:
   // 1. claimed_by is NULL, OR
-  // 2. claimed_by is not active in instances table (last_heartbeat < 45 seconds ago), OR
-  // 3. claimed_at is older than 180 seconds (worker hung)
+  // 2. claimed_by is not active in instances table (last_heartbeat < 45 seconds ago)
+  // NOTE: Claims held by live heartbeating instances are never reclaimed merely due to age (N1 fix).
   recoverInterruptedDeliveries() {
     const sql = `
       UPDATE events
@@ -449,7 +491,6 @@ class Storage {
           OR claimed_by NOT IN (
             SELECT id FROM instances WHERE datetime(last_heartbeat) >= datetime('now', '-45 seconds')
           )
-          OR (claimed_at IS NOT NULL AND datetime(claimed_at) < datetime('now', '-180 seconds'))
         )
     `;
     return this.db.prepare(sql).run().changes;
@@ -482,6 +523,14 @@ class Storage {
   listWaitlist() {
     return this.db.prepare('SELECT * FROM waitlist ORDER BY created_at DESC').all();
   }
+
+  close() {
+    if (this.db) {
+      try {
+        this.db.close();
+      } catch (_) {}
+    }
+  }
 }
 
 Storage.toSqliteTime = toSqliteTime;