web-agent-bridge 3.2.0 → 3.3.0

package/server/security/intent-engine.js

@@ -0,0 +1,245 @@
+'use strict';
+
+/**
+ * WAB Safety Shield — Intent Analysis Engine (SPEC §8.12)
+ *
+ * Deterministic, dependency-free risk scorer that runs on every agent
+ * action AFTER scope/dry-run/human-gate. The engine looks at the
+ * COMPOSITION of the request (verb class, target environment, magnitude,
+ * danger tokens in params, recent agent behaviour) and decides whether
+ * to ALLOW, escalate to DRY_RUN, escalate to HUMAN_GATE, or BLOCK.
+ *
+ * Why a separate layer?
+ *   - Scope tokens enforce *what the token is allowed to do*.
+ *   - Dry-run forces a 2-step preview for known destructive verbs.
+ *   - Human gate adds OOB approval for Pro+ deployments.
+ *   - The Intent Engine catches panic patterns that pass all three:
+ *       e.g. an agent that just got an error tries `delete-all + force`
+ *       on a production database — score=critical → block, even if the
+ *       token has admin scope.
+ *
+ * Scoring is bounded 0..100. The engine returns the highest-severity
+ * required gate; the route is responsible for enforcing it.
+ *
+ * The engine is intentionally pure & synchronous so it can run on the
+ * hot path without I/O. A tiny in-memory ring buffer tracks per-actor
+ * velocity & burst patterns over the last 60 seconds.
+ */
+
+const DEFAULT_THRESHOLDS = Object.freeze({
+  low: 30,        // 0-29   → allow
+  medium: 70,     // 30-69  → require dry-run
+  high: 90,       // 70-89  → require human gate
+  // 90+         → block outright
+});
+
+const DANGER_TOKENS = [
+  'force', 'skip-checks', 'skip_checks', 'no-backup', 'no_backup',
+  'permanent', 'permanently', 'irrecoverable', 'cascade', 'recursive',
+  'all', 'everything', 'wildcard', '--force', '--yes', 'confirm-destroy',
+];
+
+const DESTRUCTIVE_VERB_PATTERNS = [
+  /^(delete|drop|destroy|wipe|purge|truncate|remove|erase|annihilate)/i,
+  /^(uninstall|deprovision|terminate)/i,
+];
+
+const WRITE_VERB_PATTERNS = [
+  /^(create|update|modify|patch|set|write|insert|put|post|publish|deploy|merge|push)/i,
+];
+
+const ENV_WEIGHTS = Object.freeze({
+  production: 30,
+  prod: 30,
+  live: 30,
+  staging: 10,
+  preview: 5,
+  development: 0,
+  dev: 0,
+  test: 0,
+});
+
+// ─── per-actor velocity tracker ──────────────────────────────────────
+// actorKey -> [{ ts, action, env, score }]
+const _history = new Map();
+const HISTORY_WINDOW_MS = 60_000;
+const HISTORY_MAX_PER_ACTOR = 50;
+
+function _trim(arr) {
+  const cutoff = Date.now() - HISTORY_WINDOW_MS;
+  while (arr.length && arr[0].ts < cutoff) arr.shift();
+  while (arr.length > HISTORY_MAX_PER_ACTOR) arr.shift();
+}
+
+function _record(actorKey, entry) {
+  if (!actorKey) return;
+  let arr = _history.get(actorKey);
+  if (!arr) { arr = []; _history.set(actorKey, arr); }
+  arr.push(entry);
+  _trim(arr);
+}
+
+function _getHistory(actorKey) {
+  if (!actorKey) return [];
+  const arr = _history.get(actorKey);
+  if (!arr) return [];
+  _trim(arr);
+  return arr;
+}
+
+// ─── helpers ─────────────────────────────────────────────────────────
+
+function _classifyVerb(actionName) {
+  if (!actionName) return 'unknown';
+  if (DESTRUCTIVE_VERB_PATTERNS.some((re) => re.test(actionName))) return 'destructive';
+  if (WRITE_VERB_PATTERNS.some((re) => re.test(actionName))) return 'write';
+  return 'read';
+}
+
+function _envWeight(env) {
+  return ENV_WEIGHTS[String(env || 'production').toLowerCase()] ?? 30;
+}
+
+function _flatStrings(value, out = [], depth = 0) {
+  if (depth > 4 || value == null) return out;
+  if (typeof value === 'string') { out.push(value.toLowerCase()); return out; }
+  if (typeof value === 'number' || typeof value === 'boolean') { out.push(String(value).toLowerCase()); return out; }
+  if (Array.isArray(value)) { for (const v of value) _flatStrings(v, out, depth + 1); return out; }
+  if (typeof value === 'object') {
+    for (const [k, v] of Object.entries(value)) {
+      out.push(String(k).toLowerCase());
+      _flatStrings(v, out, depth + 1);
+    }
+  }
+  return out;
+}
+
+function _detectDangerTokens(params) {
+  const flat = _flatStrings(params || {});
+  const found = new Set();
+  for (const s of flat) {
+    if (s === 'true') continue;
+    for (const t of DANGER_TOKENS) {
+      if (s === t || s.includes(t)) { found.add(t); break; }
+    }
+  }
+  return [...found];
+}
+
+function _magnitudeSignal(params) {
+  const flat = _flatStrings(params || {});
+  let score = 0;
+  const reasons = [];
+  // Wildcards
+  for (const s of flat) {
+    if (s === '*' || s === '%' || s === 'all' || s === 'everything') {
+      score += 15; reasons.push(`wildcard:"${s}"`); break;
+    }
+  }
+  // Large arrays anywhere → bulk operation
+  function walk(v, depth = 0) {
+    if (depth > 4 || v == null) return;
+    if (Array.isArray(v)) {
+      if (v.length >= 20) { score += 10; reasons.push(`large_array:${v.length}`); }
+      for (const x of v) walk(x, depth + 1);
+    } else if (typeof v === 'object') {
+      for (const x of Object.values(v)) walk(x, depth + 1);
+    }
+  }
+  walk(params || {});
+  return { score: Math.min(score, 30), reasons };
+}
+
+// ─── public API ──────────────────────────────────────────────────────
+
+/**
+ * Score a request. Returns:
+ *   {
+ *     score:     number (0..100, capped),
+ *     level:     'low' | 'medium' | 'high' | 'critical',
+ *     verb_class:'read'|'write'|'destructive'|'unknown',
+ *     required_gate: null | 'dry_run' | 'human_gate' | 'block',
+ *     reasons:   string[],
+ *     rewrites:  Array<{from:string, to:string, reason:string}>,
+ *   }
+ *
+ * Inputs:
+ *   ctx = { actorId, sessionToken, siteId, actionName, params, env, tier }
+ *   siteConfig may override thresholds via siteConfig.intentEngine = {
+ *     thresholds:{ low,medium,high }, weights:{...},
+ *     dangerTokens:[...], rewrites:{ from->to }
+ *   }
+ */
+function score(ctx, siteConfig = {}) {
+  const cfg = siteConfig.intentEngine || {};
+  const thresholds = { ...DEFAULT_THRESHOLDS, ...(cfg.thresholds || {}) };
+  const reasons = [];
+  const rewrites = [];
+  let s = 0;
+
+  const verb = _classifyVerb(ctx.actionName);
+  if (verb === 'destructive') { s += 50; reasons.push('verb:destructive'); }
+  else if (verb === 'write') { s += 10; reasons.push('verb:write'); }
+
+  const env = ctx.env || siteConfig.environment || 'production';
+  const ew = _envWeight(env);
+  // Reads on production are not by themselves risky — only weight env for write/destructive.
+  if (ew > 0 && verb !== 'read') { s += ew; reasons.push(`env:${env}(+${ew})`); }
+
+  const danger = _detectDangerTokens(ctx.params);
+  if (danger.length) { s += Math.min(30, danger.length * 15); reasons.push(`danger_tokens:${danger.join(',')}`); }
+
+  const mag = _magnitudeSignal(ctx.params);
+  if (mag.score) { s += mag.score; reasons.push(...mag.reasons); }
+
+  // Burst / velocity: count similar destructive actions in window
+  const actorKey = ctx.actorId || ctx.sessionToken || ctx.siteId || 'anon';
+  const history = _getHistory(actorKey);
+  const recentDestructive = history.filter((h) => h.verb === 'destructive').length;
+  if (recentDestructive >= 3) { s += 15; reasons.push(`burst:${recentDestructive}_destructive_in_60s`); }
+  const last = history[history.length - 1];
+  if (last && Date.now() - last.ts < 1000 && verb !== 'read') {
+    s += 10; reasons.push('velocity:<1s_since_last');
+  }
+
+  // Optional site rewrites: e.g. "delete-account" -> "deactivate-account"
+  const rwMap = cfg.rewrites || {};
+  if (rwMap[ctx.actionName]) {
+    rewrites.push({
+      from: ctx.actionName, to: rwMap[ctx.actionName],
+      reason: 'site policy prefers a reversible alternative',
+    });
+  }
+
+  // Heuristic safe-rewrite for destructive verbs touching well-known nouns.
+  if (verb === 'destructive' && /account|user|invoice|order/i.test(ctx.actionName) && !rwMap[ctx.actionName]) {
+    const safe = ctx.actionName.replace(/^(delete|destroy|wipe|purge|remove)/i, 'archive');
+    if (safe !== ctx.actionName) rewrites.push({ from: ctx.actionName, to: safe, reason: 'archive-instead-of-delete fallback' });
+  }
+
+  // Cap and classify
+  s = Math.min(100, Math.max(0, Math.round(s)));
+  let level = 'low';
+  let required_gate = null;
+  if (s >= thresholds.high) { level = 'critical'; required_gate = 'block'; }
+  else if (s >= thresholds.medium) { level = 'high'; required_gate = 'human_gate'; }
+  else if (s >= thresholds.low) { level = 'medium'; required_gate = 'dry_run'; }
+
+  // Record for next call
+  _record(actorKey, { ts: Date.now(), action: ctx.actionName, env, verb, score: s });
+
+  return { score: s, level, verb_class: verb, required_gate, reasons, rewrites };
+}
+
+function _resetForTests() {
+  _history.clear();
+}
+
+module.exports = {
+  score,
+  _classifyVerb,
+  _detectDangerTokens,
+  _resetForTests,
+  DEFAULT_THRESHOLDS,
+  DANGER_TOKENS,
+};

package/server/security/reward-guard.js

@@ -0,0 +1,171 @@
+'use strict';
+
+/**
+ * Reward Guard — defenses against reward-hacking in the local RL engine.
+ *
+ * Threats addressed:
+ *   1. Out-of-bounds rewards (writers stuffing huge positive numbers).
+ *   2. Sudden gradient explosions (sequence of large positive rewards on
+ *      previously-low-confidence actions, indicative of a feedback loop).
+ *   3. Per-actor abuse (one user/agent flooding rewards to skew a policy).
+ *   4. Rewards on sensitive actions without HITL approval.
+ *
+ * Defenses:
+ *   - Clamp reward to [REWARD_MIN, REWARD_MAX].
+ *   - Per-(site,agent,domain) sliding window with EMA + variance check.
+ *   - Per-actor rate limit (default 60 reward writes / 5 min).
+ *   - Block rewards on actions in the SENSITIVE_VERBS set unless an
+ *     `approvedBy` field is present and references a human user id.
+ *   - Append-only `reward_audit` table for human review.
+ */
+
+const crypto = require('crypto');
+const { db } = require('../models/db');
+const { SENSITIVE_VERBS } = require('../middleware/sensitiveAction');
+
+const REWARD_MIN = -1.0;
+const REWARD_MAX = 1.0;
+const ANOMALY_Z_SCORE = 4.0;          // |reward - mean| / std > 4 → anomaly
+const RATE_LIMIT_WINDOW_MS = 5 * 60 * 1000;
+const RATE_LIMIT_MAX = 60;
+
+db.exec(`
+  CREATE TABLE IF NOT EXISTS reward_audit (
+    id TEXT PRIMARY KEY,
+    site_id TEXT,
+    agent_id TEXT,
+    domain TEXT,
+    action TEXT,
+    raw_reward REAL,
+    final_reward REAL,
+    decision TEXT NOT NULL CHECK(decision IN ('accepted','clamped','blocked','flagged')),
+    reason TEXT,
+    actor_id TEXT,
+    approved_by TEXT,
+    created_at TEXT DEFAULT (datetime('now'))
+  );
+  CREATE INDEX IF NOT EXISTS idx_reward_audit_site ON reward_audit(site_id, agent_id);
+  CREATE INDEX IF NOT EXISTS idx_reward_audit_decision ON reward_audit(decision);
+`);
+
+const _rateBuckets = new Map(); // actorKey → [{ts}, ...]
+const _emaState = new Map();    // bucketKey → { mean, var, n }
+
+function _bucketKey(siteId, agentId, domain) {
+  return `${siteId || ''}::${agentId || ''}::${domain || ''}`;
+}
+
+function _checkRate(actorKey) {
+  const now = Date.now();
+  const bucket = _rateBuckets.get(actorKey) || [];
+  const fresh = bucket.filter((t) => now - t < RATE_LIMIT_WINDOW_MS);
+  fresh.push(now);
+  _rateBuckets.set(actorKey, fresh);
+  return fresh.length <= RATE_LIMIT_MAX;
+}
+
+function _updateEma(bucketKey, x) {
+  // Welford-style streaming mean/variance.
+  const s = _emaState.get(bucketKey) || { mean: 0, m2: 0, n: 0 };
+  s.n += 1;
+  const delta = x - s.mean;
+  s.mean += delta / s.n;
+  s.m2 += delta * (x - s.mean);
+  _emaState.set(bucketKey, s);
+  const variance = s.n > 1 ? s.m2 / (s.n - 1) : 1;
+  return { mean: s.mean, std: Math.sqrt(Math.max(variance, 1e-6)), n: s.n };
+}
+
+function _audit(row) {
+  db.prepare(`INSERT INTO reward_audit
+    (id, site_id, agent_id, domain, action, raw_reward, final_reward, decision, reason, actor_id, approved_by)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(
+    crypto.randomUUID(), row.siteId || null, row.agentId || null, row.domain || null,
+    row.action || null, row.rawReward, row.finalReward, row.decision, row.reason || null,
+    row.actorId || null, row.approvedBy || null
+  );
+}
+
+function _isSensitive(action) {
+  if (!action) return false;
+  const tokens = String(action).toLowerCase().split(/[\s.\-_/:]+/);
+  return tokens.some((t) => SENSITIVE_VERBS.has(t));
+}
+
+/**
+ * Sanitize a reward emitted by an agent. Returns a `{ reward, decision }`
+ * tuple. Always logs to reward_audit.
+ *
+ * @param {object} input
+ * @param {string} input.siteId
+ * @param {string} input.agentId
+ * @param {string} input.domain
+ * @param {string} input.action
+ * @param {number} input.reward
+ * @param {string} [input.actorId]
+ * @param {string} [input.approvedBy]   - human user id approving the reward
+ */
+function sanitizeReward(input) {
+  const { siteId, agentId, domain, action, reward, actorId, approvedBy } = input;
+  const raw = Number(reward);
+
+  if (!Number.isFinite(raw)) {
+    _audit({ ...input, rawReward: reward, finalReward: 0, decision: 'blocked', reason: 'non-finite reward' });
+    return { reward: 0, decision: 'blocked', reason: 'non-finite reward' };
+  }
+
+  const actorKey = actorId || agentId || 'anon';
+  if (!_checkRate(actorKey)) {
+    _audit({ ...input, rawReward: raw, finalReward: 0, decision: 'blocked', reason: 'rate limit exceeded' });
+    return { reward: 0, decision: 'blocked', reason: 'reward rate limit exceeded' };
+  }
+
+  if (_isSensitive(action) && !approvedBy) {
+    _audit({ ...input, rawReward: raw, finalReward: 0, decision: 'blocked', reason: 'sensitive action without HITL approval' });
+    return { reward: 0, decision: 'blocked', reason: 'sensitive action requires approvedBy' };
+  }
+
+  // Clamp.
+  let clamped = Math.max(REWARD_MIN, Math.min(REWARD_MAX, raw));
+  let decision = clamped === raw ? 'accepted' : 'clamped';
+  let reason = decision === 'clamped' ? `clamped from ${raw}` : null;
+
+  // Anomaly detection vs rolling distribution.
+  const stats = _updateEma(_bucketKey(siteId, agentId, domain), clamped);
+  if (stats.n >= 10) {
+    const z = Math.abs(clamped - stats.mean) / stats.std;
+    if (z > ANOMALY_Z_SCORE) {
+      decision = 'flagged';
+      reason = `anomaly z=${z.toFixed(2)} (mean=${stats.mean.toFixed(3)}, std=${stats.std.toFixed(3)})`;
+      // Pull large positive flagged values toward the mean to limit damage.
+      if (clamped > stats.mean) clamped = stats.mean + stats.std * 2;
+    }
+  }
+
+  _audit({ ...input, rawReward: raw, finalReward: clamped, decision, reason });
+  return { reward: clamped, decision, reason };
+}
+
+function getRecentAudits(limit = 100, decision) {
+  if (decision) {
+    return db.prepare(`SELECT * FROM reward_audit WHERE decision = ? ORDER BY rowid DESC LIMIT ?`).all(decision, limit);
+  }
+  return db.prepare(`SELECT * FROM reward_audit ORDER BY rowid DESC LIMIT ?`).all(limit);
+}
+
+function getStats() {
+  const counts = db.prepare(`SELECT decision, COUNT(*) as n FROM reward_audit GROUP BY decision`).all();
+  return {
+    bounds: { min: REWARD_MIN, max: REWARD_MAX, anomalyZ: ANOMALY_Z_SCORE },
+    rateLimit: { windowMs: RATE_LIMIT_WINDOW_MS, max: RATE_LIMIT_MAX },
+    counts: counts.reduce((acc, r) => ({ ...acc, [r.decision]: r.n }), {}),
+  };
+}
+
+module.exports = {
+  sanitizeReward,
+  getRecentAudits,
+  getStats,
+  REWARD_MIN,
+  REWARD_MAX,
+};

package/server/security/rollback-store.js

@@ -0,0 +1,239 @@
+'use strict';
+
+/**
+ * WAB Safety Shield — Snapshot & Rollback Store (SPEC §8.13)
+ *
+ * Persists a "before-image" snapshot for every destructive action that
+ * site adapters opt into, plus a forward audit linking the snapshot to
+ * the agent action that created it. Operators (or the site admin UI)
+ * can then `restore` a snapshot to undo agent damage.
+ *
+ * The snapshot payload is opaque JSON provided by the site adapter
+ * (e.g. a serialized DB row, a tombstoned file URL, an S3 version-id).
+ * This module owns ONLY the durable index + lifecycle; it does not
+ * know how to actually restore site data — that contract is delegated
+ * to a per-site `restorer` callable registered via `setRestorer`.
+ *
+ * Tier: Enterprise.
+ */
+
+const crypto = require('crypto');
+const { db } = require('../models/db');
+
+// Schema is created lazily so this module can be required even on
+// installations that do not enable rollback.
+let _initialized = false;
+function _ensureSchema() {
+  if (_initialized) return;
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS wab_snapshots (
+      id              TEXT PRIMARY KEY,
+      site_id         TEXT NOT NULL,
+      action_name     TEXT NOT NULL,
+      actor_id        TEXT,
+      actor_type      TEXT NOT NULL DEFAULT 'agent',
+      session_fingerprint TEXT,
+      params_hash     TEXT,
+      snapshot        TEXT NOT NULL,
+      meta            TEXT DEFAULT '{}',
+      reversible      INTEGER NOT NULL DEFAULT 1,
+      status          TEXT NOT NULL DEFAULT 'recorded'
+                        CHECK(status IN ('recorded','restored','expired','failed')),
+      created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+      restored_at     TEXT,
+      expires_at      TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_wab_snapshots_site ON wab_snapshots (site_id, created_at DESC);
+    CREATE INDEX IF NOT EXISTS idx_wab_snapshots_status ON wab_snapshots (status);
+  `);
+  _initialized = true;
+}
+
+// ─── per-site restorers ──────────────────────────────────────────────
+const _restorers = new Map();
+
+/**
+ * Register a restorer for a site. The function receives
+ * `{ snapshot, action_name, params_hash, meta }` and must return either
+ * `{ ok:true }` or `{ ok:false, error }`.
+ */
+function setRestorer(siteId, fn) {
+  if (typeof fn !== 'function') throw new TypeError('restorer must be a function');
+  _restorers.set(String(siteId), fn);
+}
+
+function _getRestorer(siteId) {
+  return _restorers.get(String(siteId)) || null;
+}
+
+// ─── helpers ─────────────────────────────────────────────────────────
+
+function _hashParams(params) {
+  const canon = JSON.stringify(_canonicalize(params || {}));
+  return crypto.createHash('sha256').update(canon).digest('hex').slice(0, 24);
+}
+function _canonicalize(value) {
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(_canonicalize);
+  const out = {};
+  for (const k of Object.keys(value).sort()) out[k] = _canonicalize(value[k]);
+  return out;
+}
+function _fingerprint(token) {
+  if (!token) return null;
+  return crypto.createHash('sha256').update(String(token)).digest('hex').slice(0, 16);
+}
+function _genId() { return 'wabs_' + crypto.randomBytes(16).toString('hex'); }
+
+// ─── public API ──────────────────────────────────────────────────────
+
+/**
+ * Record a snapshot just BEFORE the destructive action runs.
+ *
+ * @param {object} ctx        { siteId, actionName, actorId, sessionToken, params }
+ * @param {object} payload    { snapshot, meta?, reversible?, ttlMs? }
+ * @returns { snapshot_id, expires_at }
+ */
+function recordSnapshot(ctx, payload) {
+  _ensureSchema();
+  const id = _genId();
+  const now = Date.now();
+  const ttlMs = Math.max(0, payload.ttlMs || 30 * 24 * 60 * 60 * 1000); // 30 days default
+  const expiresAt = ttlMs > 0 ? new Date(now + ttlMs).toISOString() : null;
+
+  db.prepare(`
+    INSERT INTO wab_snapshots
+      (id, site_id, action_name, actor_id, actor_type, session_fingerprint, params_hash,
+       snapshot, meta, reversible, status, expires_at)
+    VALUES (?, ?, ?, ?, 'agent', ?, ?, ?, ?, ?, 'recorded', ?)
+  `).run(
+    id,
+    String(ctx.siteId),
+    String(ctx.actionName),
+    ctx.actorId || null,
+    _fingerprint(ctx.sessionToken),
+    _hashParams(ctx.params),
+    JSON.stringify(payload.snapshot ?? null),
+    JSON.stringify(payload.meta || {}),
+    payload.reversible === false ? 0 : 1,
+    expiresAt
+  );
+
+  return { snapshot_id: id, expires_at: expiresAt };
+}
+
+function getSnapshot(snapshotId) {
+  _ensureSchema();
+  const row = db.prepare(`SELECT * FROM wab_snapshots WHERE id = ?`).get(snapshotId);
+  if (!row) return null;
+  return _hydrate(row);
+}
+
+function listSnapshots(siteId, opts = {}) {
+  _ensureSchema();
+  const limit = Math.min(Math.max(opts.limit || 50, 1), 500);
+  const status = opts.status;
+  const rows = status
+    ? db.prepare(`SELECT * FROM wab_snapshots WHERE site_id=? AND status=? ORDER BY created_at DESC, rowid DESC LIMIT ?`).all(siteId, status, limit)
+    : db.prepare(`SELECT * FROM wab_snapshots WHERE site_id=? ORDER BY created_at DESC, rowid DESC LIMIT ?`).all(siteId, limit);
+  return rows.map(_hydrate);
+}
+
+function _hydrate(row) {
+  let snapshot = null;
+  let meta = {};
+  try { snapshot = JSON.parse(row.snapshot); } catch (_) {}
+  try { meta = JSON.parse(row.meta || '{}'); } catch (_) {}
+  return {
+    id: row.id,
+    site_id: row.site_id,
+    action_name: row.action_name,
+    actor_id: row.actor_id,
+    actor_type: row.actor_type,
+    session_fingerprint: row.session_fingerprint,
+    params_hash: row.params_hash,
+    snapshot,
+    meta,
+    reversible: !!row.reversible,
+    status: row.status,
+    created_at: row.created_at,
+    restored_at: row.restored_at,
+    expires_at: row.expires_at,
+  };
+}
+
+/**
+ * Restore a snapshot. Returns { ok:true } on success, or
+ * { ok:false, code, message }. Restoration is single-use: a snapshot
+ * already in `restored` cannot be replayed.
+ */
+async function restoreSnapshot(snapshotId, opts = {}) {
+  _ensureSchema();
+  const row = db.prepare(`SELECT * FROM wab_snapshots WHERE id = ?`).get(snapshotId);
+  if (!row) return { ok: false, code: 'SNAPSHOT_NOT_FOUND' };
+  if (row.status === 'restored') return { ok: false, code: 'SNAPSHOT_ALREADY_RESTORED' };
+  if (row.status === 'expired') return { ok: false, code: 'SNAPSHOT_EXPIRED' };
+  if (!row.reversible) return { ok: false, code: 'SNAPSHOT_IRREVERSIBLE' };
+  if (row.expires_at && new Date(row.expires_at).getTime() < Date.now()) {
+    db.prepare(`UPDATE wab_snapshots SET status='expired' WHERE id=?`).run(snapshotId);
+    return { ok: false, code: 'SNAPSHOT_EXPIRED' };
+  }
+
+  const restorer = opts.restorer || _getRestorer(row.site_id);
+  if (!restorer) {
+    return { ok: false, code: 'NO_RESTORER', message: `no restorer registered for site ${row.site_id}` };
+  }
+
+  let result;
+  try {
+    result = await restorer({
+      snapshot_id: row.id,
+      site_id: row.site_id,
+      action_name: row.action_name,
+      params_hash: row.params_hash,
+      snapshot: JSON.parse(row.snapshot),
+      meta: JSON.parse(row.meta || '{}'),
+    });
+  } catch (err) {
+    db.prepare(`UPDATE wab_snapshots SET status='failed' WHERE id=?`).run(snapshotId);
+    return { ok: false, code: 'RESTORER_THREW', message: err.message };
+  }
+
+  if (!result || result.ok !== true) {
+    db.prepare(`UPDATE wab_snapshots SET status='failed' WHERE id=?`).run(snapshotId);
+    return { ok: false, code: 'RESTORER_FAILED', message: result?.error || 'restorer reported failure' };
+  }
+
+  db.prepare(`UPDATE wab_snapshots SET status='restored', restored_at=datetime('now') WHERE id=?`).run(snapshotId);
+  return { ok: true, snapshot_id: snapshotId };
+}
+
+/**
+ * Expire snapshots past their TTL. Returns the count expired.
+ */
+function expireOld() {
+  _ensureSchema();
+  const r = db.prepare(`
+    UPDATE wab_snapshots SET status='expired'
+     WHERE status='recorded' AND expires_at IS NOT NULL AND expires_at < datetime('now')
+  `).run();
+  return r.changes || 0;
+}
+
+function _resetForTests() {
+  _ensureSchema();
+  db.prepare(`DELETE FROM wab_snapshots`).run();
+  _restorers.clear();
+}
+
+module.exports = {
+  recordSnapshot,
+  getSnapshot,
+  listSnapshots,
+  restoreSnapshot,
+  expireOld,
+  setRestorer,
+  // test helpers
+  _resetForTests,
+  _hashParams,
+};