web-agent-bridge 3.14.0 → 3.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-agent-bridge",
-  "version": "3.14.0",
+  "version": "3.16.0",
   "description": "Agent Transaction Bridge — the trust + transaction layer for agentic commerce. Signed intent contracts, idempotent transactions, Ed25519-verifiable receipts, explicit compensation. Plus the original WAB stack: sovereign browser, ShieldQR, SSL health, DNS discovery, agent mesh, and unified gateway for safe AI–website interaction.",
   "author": "Web Agent Bridge <dev@webagentbridge.com>",
   "main": "server/index.js",

package/server/index.js

@@ -327,6 +327,9 @@ app.use('/api/agent', apiLimiter, require('./routes/agent-prompt'));
 // (apiLimiter already applies via /api mount above; do not stack it here.)
 app.use('/api', require('./routes/network'));
 
+// ── Webhook Subscriptions v3.16.0 (Phase 4) — instant push for revocations ──
+app.use('/api/webhooks', apiLimiter, require('./routes/webhooks'));
+
 // ── WAB Commercial Foundations v3.8.0 (Partners · Trust Graph API · Governance SaaS · Enterprise Mesh) ──
 app.use('/api/partners',         apiLimiter, require('./routes/partners'));
 app.use('/api/keys',             apiLimiter, require('./routes/api-keys'));

package/server/migrations/025_revocation_webhooks.sql

@@ -0,0 +1,55 @@
+-- ─────────────────────────────────────────────────────────────────────────────
+-- Migration 025 — Webhook Subscriptions for Revocations (v3.16.0)
+--
+-- Lets ecosystem participants (agent frameworks, security tools, allow-list
+-- mirrors) subscribe to instant push notifications for revocation events
+-- instead of polling /api/trusted-domains.json every hour.
+--
+-- Delivery is best-effort with retries (3 attempts: t+0, t+30s, t+5m).
+-- Every delivery is HMAC-SHA256 signed using the subscription secret.
+-- ─────────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS webhook_subscriptions (
+  id            TEXT PRIMARY KEY,                       -- whsub_<ulid>
+  user_id       TEXT NOT NULL,
+  url           TEXT NOT NULL,                          -- HTTPS endpoint
+  secret        TEXT NOT NULL,                          -- shared HMAC secret (base64, 32 bytes)
+  events        TEXT NOT NULL DEFAULT 'revocation.opened,revocation.reinstated,revocation.appeal_decided',
+  active        INTEGER NOT NULL DEFAULT 1,
+  description   TEXT,
+  last_success_at TEXT,
+  last_error_at TEXT,
+  last_error    TEXT,
+  consecutive_failures INTEGER NOT NULL DEFAULT 0,
+  created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at    TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_webhook_subs_user
+  ON webhook_subscriptions(user_id, active);
+
+CREATE INDEX IF NOT EXISTS idx_webhook_subs_active
+  ON webhook_subscriptions(active);
+
+CREATE TABLE IF NOT EXISTS webhook_deliveries (
+  id            TEXT PRIMARY KEY,                       -- whd_<ulid>
+  subscription_id TEXT NOT NULL,
+  event_id      TEXT NOT NULL,                          -- evt_<ulid>
+  event_type    TEXT NOT NULL,
+  payload       TEXT NOT NULL,                          -- raw JSON body sent
+  status        TEXT NOT NULL DEFAULT 'pending'
+                CHECK (status IN ('pending','success','failed')),
+  attempts      INTEGER NOT NULL DEFAULT 0,
+  last_status_code INTEGER,
+  last_error    TEXT,
+  next_retry_at TEXT,
+  created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+  delivered_at  TEXT,
+  FOREIGN KEY (subscription_id) REFERENCES webhook_subscriptions(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_webhook_deliveries_sub
+  ON webhook_deliveries(subscription_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_webhook_deliveries_status
+  ON webhook_deliveries(status, next_retry_at);

package/server/routes/network.js

@@ -1,25 +1,46 @@
 'use strict';
 
 /**
- * Network-effect public endpoints (v3.14.0).
+ * Network-effect public endpoints (v3.14.0 + signed snapshots v3.15.0).
  *
- *   GET /api/trusted-domains.json — snapshot of currently-attested,
+ *   GET /api/trusted-domains.json — signed snapshot of currently-attested,
  *     non-revoked WAB sites. Cached 1 hour. Designed for agent bootstrap
  *     and third-party crawlers building "verified web" indexes.
  *   GET /api/trusted-domains.txt  — same data, newline-separated domains.
- *   GET /api/revocations/feed.json — JSON Feed 1.1 of the transparency log.
- *   GET /api/revocations/feed.xml  — Atom 1.0 of the transparency log.
+ *   GET /api/trusted-domains/archive.json — manifest of available daily snapshots.
+ *   GET /api/trusted-domains/:date.json    — historical signed snapshot.
+ *   GET /api/transparency/feed.json — JSON Feed 1.1 of the transparency log.
+ *   GET /api/transparency/feed.xml  — Atom 1.0 of the transparency log.
+ *   GET /api/operator-key.json — operator Ed25519 public key (b64 + JWK).
  *
  * Mounted at /api in server/index.js.
  */
 
 const express = require('express');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
 const router = express.Router();
 const { db } = require('../models/db');
+const { canonicalize } = require('../services/canonical-json');
+const signer = require('../services/operator-signer');
 
 const SNAPSHOT_TTL_MS = 60 * 60 * 1000; // 1h
+const ARCHIVE_DIR = process.env.WAB_SNAPSHOT_DIR ||
+  path.join(__dirname, '..', '..',
+    (process.env.NODE_ENV === 'test' ? 'data-test' : 'data'),
+    'snapshots');
+
 let _snapshotCache = { ts: 0, data: null };
 
+function _ensureArchiveDir() {
+  try { fs.mkdirSync(ARCHIVE_DIR, { recursive: true }); } catch (_) { /* ignore */ }
+}
+
+function _todayUtc() {
+  return new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+}
+
 function buildSnapshot() {
   // Active sites that have no active blocking revocation.
   let rows = [];
@@ -37,16 +58,18 @@ function buildSnapshot() {
       ORDER BY s.created_at ASC
     `).all();
   } catch (_) {
-    // site_revocations may not yet exist on a very first boot
     rows = db.prepare(`
       SELECT id, domain, name, description, tier, created_at
       FROM sites WHERE active = 1 ORDER BY created_at ASC
     `).all();
   }
 
-  return {
+  const generated_at = new Date().toISOString();
+  const date = generated_at.slice(0, 10);
+  const payload = {
     schema: 'wab-trusted-domains/v1',
-    generated_at: new Date().toISOString(),
+    generated_at,
+    date,
     total: rows.length,
     domains: rows.map(r => ({
       domain: r.domain,
@@ -57,6 +80,29 @@ function buildSnapshot() {
       badge_url: 'https://webagentbridge.com/api/discovery/badge/' + r.domain + '.svg'
     }))
   };
+
+  // Hash + sign over the canonical bytes of `payload` (without signature fields).
+  const canonical = canonicalize(payload);
+  const content_hash = 'sha256:' + crypto.createHash('sha256').update(canonical, 'utf8').digest('hex');
+  const signature = signer.sign(payload);
+
+  const out = Object.assign({}, payload, {
+    content_hash,
+    signature: signature
+      ? { alg: signer.ALGORITHM, value: signature, key_url: '/api/operator-key.json' }
+      : null,
+  });
+
+  // Persist today's snapshot to disk for time-machine queries (idempotent overwrite).
+  try {
+    _ensureArchiveDir();
+    const file = path.join(ARCHIVE_DIR, date + '.json');
+    fs.writeFileSync(file, JSON.stringify(out, null, 2) + '\n', 'utf8');
+  } catch (e) {
+    console.warn('[network] snapshot archive write failed (non-fatal):', e.message);
+  }
+
+  return out;
 }
 
 function getSnapshot() {
@@ -73,6 +119,8 @@ router.get('/trusted-domains.json', (req, res) => {
   const snap = getSnapshot();
   res.set('Cache-Control', 'public, max-age=3600, s-maxage=3600');
   res.set('X-WAB-Snapshot-Schema', snap.schema);
+  res.set('X-WAB-Snapshot-Hash', snap.content_hash);
+  if (snap.signature) res.set('X-WAB-Snapshot-Signature', snap.signature.value);
   res.json(snap);
 });
 
@@ -83,6 +131,75 @@ router.get('/trusted-domains.txt', (req, res) => {
   res.send(snap.domains.map(d => d.domain).join('\n') + '\n');
 });
 
+// ── Daily archive ────────────────────────────────────────────────────
+
+function _listArchiveDates() {
+  try {
+    _ensureArchiveDir();
+    return fs.readdirSync(ARCHIVE_DIR)
+      .filter(f => /^\d{4}-\d{2}-\d{2}\.json$/.test(f))
+      .map(f => f.replace(/\.json$/, ''))
+      .sort();
+  } catch (_) { return []; }
+}
+
+router.get('/trusted-domains/archive.json', (req, res) => {
+  // Touch today's snapshot to ensure at least today is archived.
+  getSnapshot();
+  const dates = _listArchiveDates();
+  const manifest = {
+    schema: 'wab-trusted-domains-archive/v1',
+    generated_at: new Date().toISOString(),
+    total: dates.length,
+    snapshots: dates.map(d => ({
+      date: d,
+      url: '/api/trusted-domains/' + d + '.json',
+    })),
+  };
+  const sig = signer.sign(manifest);
+  if (sig) manifest.signature = { alg: signer.ALGORITHM, value: sig, key_url: '/api/operator-key.json' };
+  res.set('Cache-Control', 'public, max-age=3600, s-maxage=3600');
+  res.json(manifest);
+});
+
+router.get('/trusted-domains/:date.json', (req, res) => {
+  const date = req.params.date;
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+    return res.status(400).json({ error: 'invalid_date', hint: 'Use YYYY-MM-DD.' });
+  }
+  // Serve today live (so a fresh boot doesn't return 404 before the first snapshot).
+  if (date === _todayUtc()) {
+    return res.json(getSnapshot());
+  }
+  _ensureArchiveDir();
+  const file = path.join(ARCHIVE_DIR, date + '.json');
+  if (!fs.existsSync(file)) {
+    return res.status(404).json({ error: 'snapshot_not_found', date });
+  }
+  res.set('Cache-Control', 'public, max-age=86400, s-maxage=86400, immutable');
+  res.type('application/json; charset=utf-8');
+  res.send(fs.readFileSync(file, 'utf8'));
+});
+
+// ── Operator public key ──────────────────────────────────────────────
+
+router.get('/operator-key.json', (req, res) => {
+  const pub = signer.publicKey();
+  if (!pub) {
+    return res.status(503).json({ error: 'signing_not_configured' });
+  }
+  res.set('Cache-Control', 'public, max-age=86400, s-maxage=86400');
+  res.json({
+    schema: 'wab-operator-key/v1',
+    alg: signer.ALGORITHM,
+    public_key_b64: pub.b64,
+    jwk: pub.jwk,
+    issued_at: new Date().toISOString(),
+    notice: 'Use this key to verify signatures on /api/trusted-domains.json and /api/trusted-domains/*.json.',
+  });
+});
+
+
 // ── Revocation feeds ─────────────────────────────────────────────────
 
 function listRecentRevocations(limit) {

package/server/routes/webhooks.js

@@ -0,0 +1,75 @@
+/**
+ * Webhook Subscriptions API (v3.16.0 — Phase 4)
+ *
+ *   POST   /api/webhooks                  — create subscription (returns secret once)
+ *   GET    /api/webhooks                  — list user's subscriptions
+ *   GET    /api/webhooks/:id              — get one
+ *   PATCH  /api/webhooks/:id              — update url/events/active/description
+ *   DELETE /api/webhooks/:id              — delete
+ *   GET    /api/webhooks/:id/deliveries   — recent delivery log
+ *   GET    /api/webhooks/events           — list supported event types
+ */
+
+'use strict';
+
+const express = require('express');
+const router = express.Router();
+
+const { authenticateToken } = require('../middleware/auth');
+const webhooks = require('../services/webhooks');
+
+function _handle(res, fn) {
+  try {
+    const out = fn();
+    res.json({ ok: true, data: out });
+  } catch (e) {
+    const status = e.statusCode || 500;
+    res.status(status).json({ ok: false, error: e.code || 'internal_error', message: e.message });
+  }
+}
+
+router.get('/events', (req, res) => {
+  res.json({ ok: true, data: { events: Array.from(webhooks.VALID_EVENTS) } });
+});
+
+router.post('/', authenticateToken, express.json({ limit: '8kb' }), (req, res) => {
+  _handle(res, () => webhooks.createSubscription({
+    userId: req.user.id,
+    url: req.body.url,
+    events: req.body.events,
+    description: req.body.description,
+  }));
+});
+
+router.get('/', authenticateToken, (req, res) => {
+  _handle(res, () => webhooks.listSubscriptions(req.user.id));
+});
+
+router.get('/:id', authenticateToken, (req, res) => {
+  _handle(res, () => webhooks.getSubscription({ id: req.params.id, userId: req.user.id }));
+});
+
+router.patch('/:id', authenticateToken, express.json({ limit: '8kb' }), (req, res) => {
+  _handle(res, () => webhooks.updateSubscription({
+    id: req.params.id,
+    userId: req.user.id,
+    url: req.body.url,
+    events: req.body.events,
+    active: req.body.active,
+    description: req.body.description,
+  }));
+});
+
+router.delete('/:id', authenticateToken, (req, res) => {
+  _handle(res, () => webhooks.deleteSubscription({ id: req.params.id, userId: req.user.id }));
+});
+
+router.get('/:id/deliveries', authenticateToken, (req, res) => {
+  _handle(res, () => webhooks.listDeliveries({
+    subscriptionId: req.params.id,
+    userId: req.user.id,
+    limit: parseInt(req.query.limit, 10) || 50,
+  }));
+});
+
+module.exports = router;

package/server/services/operator-signer.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * Operator signing service — Ed25519 + RFC 8785.
+ *
+ * Loads WAB_OPERATOR_ED25519_PRIV (PKCS8 base64-DER) once and exposes:
+ *   sign(payload)        — returns base64 Ed25519 signature over canonicalize(payload).
+ *   publicKey()          — returns the operator's public key as {b64, jwk} (raw 32-byte b64 + JWK).
+ *   isConfigured()       — whether a signing key is available.
+ *   ALGORITHM            — 'ed25519' constant.
+ *
+ * The same private key is already used by services/revocations.js to sign revocation
+ * decisions; this module unifies usage so other surfaces (snapshots, manifests) can
+ * sign with the same identity.
+ */
+
+const crypto = require('crypto');
+const { canonicalize } = require('./canonical-json');
+
+const ALGORITHM = 'ed25519';
+const PRIV_B64 = process.env.WAB_OPERATOR_ED25519_PRIV || '';
+
+let _priv = null;
+let _pub = null;
+
+function _load() {
+  if (_priv || !PRIV_B64) return;
+  try {
+    const der = Buffer.from(PRIV_B64, 'base64');
+    _priv = crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
+    const pubKey = crypto.createPublicKey(_priv);
+    const rawDer = pubKey.export({ format: 'der', type: 'spki' });
+    // SPKI for Ed25519 is 44 bytes; raw key is the last 32.
+    const raw = rawDer.slice(-32);
+    _pub = {
+      b64: raw.toString('base64'),
+      jwk: {
+        kty: 'OKP',
+        crv: 'Ed25519',
+        x: raw.toString('base64url'),
+        alg: 'EdDSA',
+        use: 'sig',
+      },
+    };
+  } catch (e) {
+    console.warn('[operator-signer] key load failed (non-fatal):', e.message);
+  }
+}
+
+function isConfigured() {
+  _load();
+  return !!_priv;
+}
+
+function sign(payload) {
+  _load();
+  if (!_priv) return null;
+  try {
+    const sig = crypto.sign(null, Buffer.from(canonicalize(payload), 'utf8'), _priv);
+    return sig.toString('base64');
+  } catch (e) {
+    console.warn('[operator-signer] sign failed:', e.message);
+    return null;
+  }
+}
+
+function publicKey() {
+  _load();
+  return _pub;
+}
+
+/**
+ * Verify a signature against a payload using the operator's public key.
+ * Returns true/false. Convenience helper for tests and self-verification.
+ */
+function verify(payload, signatureB64) {
+  _load();
+  if (!_pub) return false;
+  try {
+    const der = Buffer.from(PRIV_B64, 'base64');
+    const priv = crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
+    const pubKey = crypto.createPublicKey(priv);
+    return crypto.verify(
+      null,
+      Buffer.from(canonicalize(payload), 'utf8'),
+      pubKey,
+      Buffer.from(signatureB64, 'base64')
+    );
+  } catch (_) { return false; }
+}
+
+module.exports = {
+  ALGORITHM,
+  sign,
+  verify,
+  publicKey,
+  isConfigured,
+};

package/server/services/revocations.js

@@ -33,6 +33,29 @@ const { db } = require('../models/db');
 const { canonicalize } = require('./canonical-json');
 const { auditLog } = require('./security');
 
+function _emitWebhook(eventType, row) {
+  try {
+    const webhooks = require('./webhooks');
+    webhooks.emit(eventType, { revocation: _publicRevocationView(row) });
+  } catch (e) {
+    if (process.env.NODE_ENV !== 'test') {
+      console.warn('[revocations] webhook emit failed:', e.message);
+    }
+  }
+}
+
+function _publicRevocationView(r) {
+  if (!r) return null;
+  return {
+    id: r.id, domain: r.domain, type: r.type,
+    reason_code: r.reason_code, reason_text: r.reason_text,
+    evidence_url: r.evidence_url,
+    decided_at: r.decided_at, appeal_deadline: r.appeal_deadline,
+    status: r.status, finalized_at: r.finalized_at,
+    reinstated_at: r.reinstated_at,
+  };
+}
+
 const APPEAL_WINDOW_DAYS = Number(process.env.WAB_REVOCATION_APPEAL_DAYS || 7);
 const APPEAL_WINDOW_MS   = APPEAL_WINDOW_DAYS * 24 * 60 * 60 * 1000;
 const OPERATOR_KEY_B64   = process.env.WAB_OPERATOR_ED25519_PRIV || '';
@@ -139,7 +162,9 @@ function openRevocation({ siteId, type, reasonCode, reasonText, decidedBy, evide
     severity: type === 'revoked' ? 'critical' : 'warning',
   });
 
-  return db.prepare(`SELECT * FROM site_revocations WHERE id = ?`).get(id);
+  const inserted = db.prepare(`SELECT * FROM site_revocations WHERE id = ?`).get(id);
+  if (type !== 'owner_disable') _emitWebhook('revocation.opened', inserted);
+  return inserted;
 }
 
 /**
@@ -253,7 +278,10 @@ function decideAppeal({ revocationId, decision, decisionReason, adminId }) {
     severity: decision === 'rejected' ? 'warning' : 'info',
   });
 
-  return db.prepare(`SELECT * FROM site_revocations WHERE id = ?`).get(revocationId);
+  const updated = db.prepare(`SELECT * FROM site_revocations WHERE id = ?`).get(revocationId);
+  _emitWebhook('revocation.appeal_decided', { ...updated, _decision: decision });
+  if (decision === 'upheld') _emitWebhook('revocation.reinstated', updated);
+  return updated;
 }
 
 /**
@@ -280,7 +308,9 @@ function reinstate({ revocationId, actorId, actorType = 'admin', reason }) {
     details: { domain: rev.domain, reason: reason || null },
   });
 
-  return db.prepare(`SELECT * FROM site_revocations WHERE id = ?`).get(revocationId);
+  const updated = db.prepare(`SELECT * FROM site_revocations WHERE id = ?`).get(revocationId);
+  _emitWebhook('revocation.reinstated', updated);
+  return updated;
 }
 
 /**

package/server/services/webhooks.js

@@ -0,0 +1,313 @@
+/**
+ * Webhook Subscriptions Service (v3.16.0 — Phase 4)
+ * ───────────────────────────────────────────────────────────────────────────
+ * Lets users subscribe HTTPS endpoints to revocation events for instant push
+ * delivery instead of polling /api/trusted-domains.json.
+ *
+ * Events:
+ *   revocation.opened           — a new suspension/revocation is issued
+ *   revocation.reinstated       — a revocation is lifted
+ *   revocation.appeal_decided   — an admin ruled on an appeal
+ *
+ * Each delivery is signed with HMAC-SHA256:
+ *   X-WAB-Webhook-Signature: t=<unix_ts>,v1=<hex>
+ *   where hex = HMAC_SHA256(secret, `${t}.${body}`)
+ *
+ * Retry policy: 3 attempts at t+0, t+30s, t+5m.
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const { db } = require('../models/db');
+
+const VALID_EVENTS = new Set([
+  'revocation.opened',
+  'revocation.reinstated',
+  'revocation.appeal_decided',
+]);
+
+const RETRY_DELAYS_MS = [0, 30_000, 300_000];
+const REQUEST_TIMEOUT_MS = Number(process.env.WAB_WEBHOOK_TIMEOUT_MS || 8000);
+const MAX_SUBS_PER_USER = Number(process.env.WAB_WEBHOOK_MAX_PER_USER || 10);
+
+function _ulid(prefix) {
+  return `${prefix}_${Date.now().toString(36)}${crypto.randomBytes(8).toString('hex')}`;
+}
+
+function _normalizeUrl(url) {
+  if (!url || typeof url !== 'string') throw _err('url required', 'bad_request', 400);
+  let u;
+  try { u = new URL(url); } catch (_) { throw _err('invalid url', 'bad_request', 400); }
+  if (u.protocol !== 'https:' && !(process.env.NODE_ENV === 'test' && u.protocol === 'http:')) {
+    throw _err('url must be https', 'bad_request', 400);
+  }
+  return u.toString();
+}
+
+function _err(msg, code, status) {
+  const e = new Error(msg); e.code = code; e.statusCode = status; return e;
+}
+
+function _normalizeEvents(events) {
+  if (!events) return Array.from(VALID_EVENTS);
+  const list = Array.isArray(events) ? events : String(events).split(',').map((s) => s.trim()).filter(Boolean);
+  if (!list.length) return Array.from(VALID_EVENTS);
+  for (const e of list) {
+    if (!VALID_EVENTS.has(e)) throw _err(`unknown event: ${e}`, 'bad_event', 400);
+  }
+  return list;
+}
+
+function _publicView(row) {
+  if (!row) return null;
+  return {
+    id: row.id,
+    url: row.url,
+    events: (row.events || '').split(',').filter(Boolean),
+    active: !!row.active,
+    description: row.description || null,
+    last_success_at: row.last_success_at,
+    last_error_at: row.last_error_at,
+    last_error: row.last_error,
+    consecutive_failures: row.consecutive_failures || 0,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+  };
+}
+
+function createSubscription({ userId, url, events, description }) {
+  if (!userId) throw _err('userId required', 'bad_request', 400);
+  const normalized = _normalizeUrl(url);
+  const eventList = _normalizeEvents(events);
+  const existing = db.prepare(
+    `SELECT COUNT(*) AS n FROM webhook_subscriptions WHERE user_id = ? AND active = 1`,
+  ).get(userId).n;
+  if (existing >= MAX_SUBS_PER_USER) {
+    throw _err(`max ${MAX_SUBS_PER_USER} active subscriptions per user`, 'limit_exceeded', 429);
+  }
+  const id = _ulid('whsub');
+  const secret = crypto.randomBytes(32).toString('base64');
+  db.prepare(`
+    INSERT INTO webhook_subscriptions (id, user_id, url, secret, events, description)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(id, String(userId), normalized, secret, eventList.join(','), description || null);
+  const row = db.prepare(`SELECT * FROM webhook_subscriptions WHERE id = ?`).get(id);
+  // Return secret only on create — never on list/get.
+  return { ..._publicView(row), secret };
+}
+
+function listSubscriptions(userId) {
+  return db.prepare(`
+    SELECT * FROM webhook_subscriptions WHERE user_id = ? ORDER BY created_at DESC
+  `).all(String(userId)).map(_publicView);
+}
+
+function getSubscription({ id, userId }) {
+  const row = db.prepare(`SELECT * FROM webhook_subscriptions WHERE id = ?`).get(id);
+  if (!row) throw _err('not found', 'not_found', 404);
+  if (String(row.user_id) !== String(userId)) throw _err('forbidden', 'forbidden', 403);
+  return _publicView(row);
+}
+
+function updateSubscription({ id, userId, url, events, active, description }) {
+  const row = db.prepare(`SELECT * FROM webhook_subscriptions WHERE id = ?`).get(id);
+  if (!row) throw _err('not found', 'not_found', 404);
+  if (String(row.user_id) !== String(userId)) throw _err('forbidden', 'forbidden', 403);
+  const patch = {};
+  if (url !== undefined) patch.url = _normalizeUrl(url);
+  if (events !== undefined) patch.events = _normalizeEvents(events).join(',');
+  if (active !== undefined) patch.active = active ? 1 : 0;
+  if (description !== undefined) patch.description = description || null;
+  if (!Object.keys(patch).length) return _publicView(row);
+  const sets = Object.keys(patch).map((k) => `${k} = ?`).join(', ');
+  db.prepare(`UPDATE webhook_subscriptions SET ${sets}, updated_at = datetime('now') WHERE id = ?`)
+    .run(...Object.values(patch), id);
+  return _publicView(db.prepare(`SELECT * FROM webhook_subscriptions WHERE id = ?`).get(id));
+}
+
+function deleteSubscription({ id, userId }) {
+  const row = db.prepare(`SELECT user_id FROM webhook_subscriptions WHERE id = ?`).get(id);
+  if (!row) throw _err('not found', 'not_found', 404);
+  if (String(row.user_id) !== String(userId)) throw _err('forbidden', 'forbidden', 403);
+  db.prepare(`DELETE FROM webhook_subscriptions WHERE id = ?`).run(id);
+  return { id, deleted: true };
+}
+
+function listDeliveries({ subscriptionId, userId, limit = 50 }) {
+  const sub = db.prepare(`SELECT user_id FROM webhook_subscriptions WHERE id = ?`).get(subscriptionId);
+  if (!sub) throw _err('not found', 'not_found', 404);
+  if (String(sub.user_id) !== String(userId)) throw _err('forbidden', 'forbidden', 403);
+  return db.prepare(`
+    SELECT id, event_id, event_type, status, attempts, last_status_code,
+           last_error, next_retry_at, created_at, delivered_at
+      FROM webhook_deliveries
+     WHERE subscription_id = ?
+     ORDER BY created_at DESC LIMIT ?
+  `).all(subscriptionId, Math.min(Math.max(limit, 1), 200));
+}
+
+// ── Dispatch ────────────────────────────────────────────────────────────────
+
+function _sign(secret, body) {
+  const t = Math.floor(Date.now() / 1000);
+  const mac = crypto.createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
+  return { header: `t=${t},v1=${mac}`, t, mac };
+}
+
+async function _httpPost(url, body, headers) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...headers },
+      body,
+      signal: ctrl.signal,
+      redirect: 'manual',
+    });
+    let text = '';
+    try { text = await res.text(); } catch (_) {}
+    return { ok: res.ok, status: res.status, body: text.slice(0, 512) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function _attemptDelivery(deliveryId, subscription, body) {
+  const { header } = _sign(subscription.secret, body);
+  const headers = {
+    'X-WAB-Webhook-Signature': header,
+    'X-WAB-Webhook-Event': subscription._eventType,
+    'X-WAB-Webhook-Id': subscription._eventId,
+    'X-WAB-Webhook-Delivery': deliveryId,
+    'User-Agent': 'web-agent-bridge-webhooks/1.0',
+  };
+  try {
+    const res = await _httpPost(subscription.url, body, headers);
+    if (res.ok) {
+      db.prepare(`
+        UPDATE webhook_deliveries
+           SET status = 'success', attempts = attempts + 1,
+               last_status_code = ?, last_error = NULL, delivered_at = datetime('now'),
+               next_retry_at = NULL
+         WHERE id = ?
+      `).run(res.status, deliveryId);
+      db.prepare(`
+        UPDATE webhook_subscriptions
+           SET last_success_at = datetime('now'), consecutive_failures = 0,
+               updated_at = datetime('now')
+         WHERE id = ?
+      `).run(subscription.id);
+      return true;
+    }
+    _recordFailure(deliveryId, subscription.id, res.status, `HTTP ${res.status}: ${res.body}`);
+    return false;
+  } catch (e) {
+    _recordFailure(deliveryId, subscription.id, null, String(e.message || e));
+    return false;
+  }
+}
+
+function _recordFailure(deliveryId, subscriptionId, statusCode, errMsg) {
+  const row = db.prepare(`SELECT attempts FROM webhook_deliveries WHERE id = ?`).get(deliveryId);
+  const attempts = (row ? row.attempts : 0) + 1;
+  const isFinal = attempts >= RETRY_DELAYS_MS.length;
+  db.prepare(`
+    UPDATE webhook_deliveries
+       SET status = ?, attempts = ?, last_status_code = ?, last_error = ?,
+           next_retry_at = ?
+     WHERE id = ?
+  `).run(
+    isFinal ? 'failed' : 'pending',
+    attempts,
+    statusCode,
+    errMsg.slice(0, 1024),
+    isFinal ? null : new Date(Date.now() + RETRY_DELAYS_MS[attempts]).toISOString(),
+    deliveryId,
+  );
+  db.prepare(`
+    UPDATE webhook_subscriptions
+       SET last_error_at = datetime('now'), last_error = ?,
+           consecutive_failures = consecutive_failures + 1,
+           updated_at = datetime('now')
+     WHERE id = ?
+  `).run(errMsg.slice(0, 512), subscriptionId);
+}
+
+function _scheduleRetry(deliveryId, subscription, body, attempt) {
+  const delay = RETRY_DELAYS_MS[attempt];
+  if (delay === undefined) return;
+  const t = setTimeout(async () => {
+    const ok = await _attemptDelivery(deliveryId, subscription, body);
+    if (!ok) _scheduleRetry(deliveryId, subscription, body, attempt + 1);
+  }, delay);
+  if (t.unref) t.unref();
+}
+
+/**
+ * Emit an event to all matching active subscriptions. Non-blocking — schedules
+ * deliveries via setImmediate so callers (revocation flows) return fast.
+ */
+function emit(eventType, data) {
+  if (!VALID_EVENTS.has(eventType)) return 0;
+  const subs = db.prepare(`
+    SELECT * FROM webhook_subscriptions
+     WHERE active = 1 AND (',' || events || ',') LIKE ?
+  `).all(`%,${eventType},%`);
+  if (!subs.length) return 0;
+
+  const eventId = _ulid('evt');
+  const payload = {
+    id: eventId,
+    type: eventType,
+    created_at: new Date().toISOString(),
+    data,
+  };
+  const body = JSON.stringify(payload);
+
+  for (const sub of subs) {
+    const deliveryId = _ulid('whd');
+    db.prepare(`
+      INSERT INTO webhook_deliveries
+        (id, subscription_id, event_id, event_type, payload, status, attempts)
+      VALUES (?, ?, ?, ?, ?, 'pending', 0)
+    `).run(deliveryId, sub.id, eventId, eventType, body);
+    const enriched = { ...sub, _eventId: eventId, _eventType: eventType };
+    setImmediate(async () => {
+      const ok = await _attemptDelivery(deliveryId, enriched, body);
+      if (!ok) _scheduleRetry(deliveryId, enriched, body, 1);
+    });
+  }
+  return subs.length;
+}
+
+/** Verify a delivery signature server-side (for tests + receiver SDKs). */
+function verifySignature({ secret, header, body, toleranceSec = 300 }) {
+  if (!header || typeof header !== 'string') return false;
+  const parts = Object.fromEntries(
+    header.split(',').map((p) => p.split('=').map((s) => s.trim())),
+  );
+  const t = Number(parts.t);
+  const v1 = parts.v1;
+  if (!t || !v1) return false;
+  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSec) return false;
+  const expected = crypto.createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
+  try {
+    return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(v1, 'hex'));
+  } catch (_) { return false; }
+}
+
+module.exports = {
+  createSubscription,
+  listSubscriptions,
+  getSubscription,
+  updateSubscription,
+  deleteSubscription,
+  listDeliveries,
+  emit,
+  verifySignature,
+  VALID_EVENTS,
+  // exposed for tests
+  _attemptDelivery,
+};