web-agent-bridge 3.0.0 → 3.3.0

package/server/security/dry-run.js

@@ -0,0 +1,180 @@
+'use strict';
+
+/**
+ * WAB Safety Shield — Mandatory Dry-Run
+ *
+ * Implements WAB SPEC §8.10. For commands the site classifies as
+ * destructive (or which match the SPEC default destructive verb list,
+ * see token-scope.js), the Bridge MUST refuse `dry_run: false` until a
+ * preceding `dry_run: true` plan has been produced AND has not expired.
+ *
+ * Wire format:
+ *   - Request:  body.dry_run === true | false   (default: undefined)
+ *               body.plan_id   (required when dry_run === false)
+ *   - Response (dry_run=true):
+ *       { type:'success', result:{ dry_run:true, plan_id, expires_at,
+ *         simulated:{ would_affect:[...], side_effects:[...], reversible:bool }}}
+ *
+ * Plan expiry:
+ *   - Plans are short-lived (default 5 min, max 60 min) so an attacker
+ *     who steals a session cannot replay an old plan against a changed
+ *     target.
+ *   - Plans are bound to (sessionToken, siteId, actionName, paramsHash)
+ *     — any drift invalidates them.
+ *
+ * Errors:
+ *   DRY_RUN_REQUIRED         — destructive action invoked without a plan
+ *   DRY_RUN_PLAN_NOT_FOUND   — plan_id supplied but unknown / expired
+ *   DRY_RUN_PLAN_MISMATCH    — plan exists but params/action drifted
+ *   DRY_RUN_PLAN_EXPIRED     — plan past TTL
+ *
+ * The simulator is a pluggable function passed by the caller — this
+ * module only owns the policy + plan-store. Sites/adapters provide the
+ * actual "what would this do" answer.
+ */
+
+const crypto = require('crypto');
+const { isDestructiveAction } = require('./token-scope');
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000;       // 5 min
+const MAX_TTL_MS = 60 * 60 * 1000;          // 60 min hard cap
+const PLAN_STORE_MAX = 5000;                // LRU bound
+
+// ─── Plan store (in-memory, single-process) ──────────────────────────
+// In a multi-process deployment this should be backed by Redis; the
+// interface is intentionally minimal so swap-out is trivial.
+
+const _plans = new Map();   // plan_id -> entry
+
+function _evictIfFull() {
+  if (_plans.size <= PLAN_STORE_MAX) return;
+  // Evict ~10% of oldest entries.
+  const drop = Math.ceil(PLAN_STORE_MAX * 0.1);
+  let i = 0;
+  for (const k of _plans.keys()) {
+    if (i++ >= drop) break;
+    _plans.delete(k);
+  }
+}
+
+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;
+}
+
+// ─── Public API ──────────────────────────────────────────────────────
+
+/**
+ * Decide whether `actionName` requires dry-run. Site config may EXPAND
+ * the default destructive list (token-scope.DEFAULT_DESTRUCTIVE_VERBS)
+ * via `destructiveActions[]` and may SUPPRESS via `nonDestructiveActions[]`.
+ *
+ * Sites can also explicitly opt OUT (rare, usually only for read-only
+ * mirror/staging sandboxes) by setting `dryRunPolicy: "off"`.
+ * They can opt IN universally with `dryRunPolicy: "always"`.
+ */
+function requiresDryRun(actionName, siteConfig = {}) {
+  const policy = String(siteConfig.dryRunPolicy || 'auto').toLowerCase();
+  if (policy === 'off') return false;
+  if (policy === 'always') return true;
+  // auto = use destructive-verb classification.
+  return isDestructiveAction(actionName, siteConfig);
+}
+
+/**
+ * Create a plan. Returns the plan envelope to be sent back to the agent.
+ *
+ * @param {object} ctx        { sessionToken, siteId, actionName, params }
+ * @param {object} simulation { would_affect, side_effects, reversible, summary? }
+ * @param {object} opts       { ttlMs }
+ */
+function createPlan(ctx, simulation, opts = {}) {
+  const ttl = Math.min(Math.max(opts.ttlMs || DEFAULT_TTL_MS, 1_000), MAX_TTL_MS);
+  const plan_id = 'wabp_' + crypto.randomBytes(16).toString('hex');
+  const now = Date.now();
+  const params_hash = _hashParams(ctx.params);
+  const entry = {
+    plan_id,
+    session_fingerprint: _sessionFingerprint(ctx.sessionToken),
+    site_id: ctx.siteId,
+    action_name: ctx.actionName,
+    params_hash,
+    simulation: {
+      would_affect: simulation.would_affect || [],
+      side_effects: simulation.side_effects || [],
+      reversible: simulation.reversible !== false,
+      summary: simulation.summary || null,
+    },
+    created_at: now,
+    expires_at: now + ttl,
+  };
+  _plans.set(plan_id, entry);
+  _evictIfFull();
+  return {
+    dry_run: true,
+    plan_id,
+    expires_at: new Date(entry.expires_at).toISOString(),
+    simulated: entry.simulation,
+  };
+}
+
+/**
+ * Validate a plan against a real (dry_run=false) request.
+ *
+ * Returns { ok: true, plan } on success; otherwise
+ * { ok: false, code, message }.
+ */
+function consumePlan(planId, ctx) {
+  if (!planId) return { ok: false, code: 'DRY_RUN_REQUIRED', message: 'destructive action requires a prior dry_run plan' };
+  const entry = _plans.get(planId);
+  if (!entry) return { ok: false, code: 'DRY_RUN_PLAN_NOT_FOUND', message: 'plan_id unknown or already consumed' };
+  const now = Date.now();
+  if (now > entry.expires_at) {
+    _plans.delete(planId);
+    return { ok: false, code: 'DRY_RUN_PLAN_EXPIRED', message: 'plan expired, please re-run dry_run' };
+  }
+  if (entry.session_fingerprint !== _sessionFingerprint(ctx.sessionToken)) {
+    return { ok: false, code: 'DRY_RUN_PLAN_MISMATCH', message: 'plan was issued to a different session' };
+  }
+  if (entry.site_id !== ctx.siteId) {
+    return { ok: false, code: 'DRY_RUN_PLAN_MISMATCH', message: 'plan was issued for a different site' };
+  }
+  if (entry.action_name !== ctx.actionName) {
+    return { ok: false, code: 'DRY_RUN_PLAN_MISMATCH', message: 'plan was issued for a different action' };
+  }
+  if (entry.params_hash !== _hashParams(ctx.params)) {
+    return { ok: false, code: 'DRY_RUN_PLAN_MISMATCH', message: 'parameters changed since plan was generated' };
+  }
+  // Single-use: consume.
+  _plans.delete(planId);
+  return { ok: true, plan: entry };
+}
+
+/** Test helper. */
+function _resetForTests() {
+  _plans.clear();
+}
+
+function _sessionFingerprint(token) {
+  if (!token) return null;
+  return crypto.createHash('sha256').update(String(token)).digest('hex').slice(0, 16);
+}
+
+module.exports = {
+  requiresDryRun,
+  createPlan,
+  consumePlan,
+  // helpers exposed for tests
+  _resetForTests,
+  _hashParams,
+  DEFAULT_TTL_MS,
+  MAX_TTL_MS,
+};

package/server/security/human-gate-rate-limit.js

@@ -0,0 +1,147 @@
+'use strict';
+
+/**
+ * WAB Safety Shield — IP rate-limiter for /human-gate/approve (SPEC §8.11)
+ *
+ * Module 1's per-challenge 5-attempt lockout is sufficient against a
+ * single attacker spamming one challenge_id. But it does NOT prevent an
+ * attacker from rotating across many challenge_ids (or guessing on
+ * leaked ones) at high rate. This sliding-window IP limiter caps the
+ * approval rate per-IP across all challenges.
+ *
+ * Defaults — tuned for human use:
+ *   • 30 attempts per 10 minutes per IP  (≈1 every 20s)
+ *   • 5  approvals  per 10 minutes per IP (success-only sub-cap)
+ *
+ * Pure in-memory; safe for single-process pm2 deployment we use today.
+ * For multi-process scale-out, swap the store for Redis ZSET (TODO).
+ */
+
+const DEFAULT_ATTEMPT_WINDOW_MS = 10 * 60 * 1000;
+const DEFAULT_ATTEMPT_LIMIT = 30;
+const DEFAULT_SUCCESS_LIMIT = 5;
+const STORE_MAX_IPS = 10_000;
+
+const _attempts = new Map();   // ip -> [timestamps]
+const _successes = new Map();  // ip -> [timestamps]
+
+let _config = {
+  windowMs: DEFAULT_ATTEMPT_WINDOW_MS,
+  attemptLimit: DEFAULT_ATTEMPT_LIMIT,
+  successLimit: DEFAULT_SUCCESS_LIMIT,
+};
+
+function configure(opts = {}) {
+  const w = Number.isFinite(opts.windowMs) ? opts.windowMs : _config.windowMs;
+  const a = Number.isFinite(opts.attemptLimit) ? opts.attemptLimit : _config.attemptLimit;
+  const s = Number.isFinite(opts.successLimit) ? opts.successLimit : _config.successLimit;
+  _config = {
+    windowMs: Math.max(10, Math.min(60 * 60 * 1000, w)),
+    attemptLimit: Math.max(1, a),
+    successLimit: Math.max(1, s),
+  };
+}
+
+function _prune(map, ip, windowMs, now) {
+  const arr = map.get(ip);
+  if (!arr) return [];
+  const cutoff = now - windowMs;
+  const fresh = arr.filter((t) => t > cutoff);
+  if (fresh.length === 0) map.delete(ip);
+  else map.set(ip, fresh);
+  return fresh;
+}
+
+function _evictIfFull(map) {
+  if (map.size <= STORE_MAX_IPS) return;
+  const drop = Math.ceil(STORE_MAX_IPS * 0.1);
+  let i = 0;
+  for (const k of map.keys()) {
+    if (i++ >= drop) break;
+    map.delete(k);
+  }
+}
+
+/**
+ * Returns one of:
+ *   { allowed: true,  remaining_attempts, remaining_successes }
+ *   { allowed: false, code: 'RATE_LIMIT_TOO_MANY_ATTEMPTS', retry_after_ms }
+ *   { allowed: false, code: 'RATE_LIMIT_TOO_MANY_APPROVALS', retry_after_ms }
+ *
+ * Call BEFORE attempting humanGate.approveChallenge().
+ */
+function checkBeforeAttempt(ip) {
+  if (!ip) return { allowed: true, remaining_attempts: _config.attemptLimit, remaining_successes: _config.successLimit };
+  const now = Date.now();
+  const attempts = _prune(_attempts, ip, _config.windowMs, now);
+  const successes = _prune(_successes, ip, _config.windowMs, now);
+
+  if (successes.length >= _config.successLimit) {
+    return {
+      allowed: false,
+      code: 'RATE_LIMIT_TOO_MANY_APPROVALS',
+      retry_after_ms: _config.windowMs - (now - successes[0]),
+    };
+  }
+  if (attempts.length >= _config.attemptLimit) {
+    return {
+      allowed: false,
+      code: 'RATE_LIMIT_TOO_MANY_ATTEMPTS',
+      retry_after_ms: _config.windowMs - (now - attempts[0]),
+    };
+  }
+  return {
+    allowed: true,
+    remaining_attempts: _config.attemptLimit - attempts.length,
+    remaining_successes: _config.successLimit - successes.length,
+  };
+}
+
+/**
+ * Record an attempt outcome AFTER calling approveChallenge.
+ *  - Always records the attempt timestamp.
+ *  - Additionally records a success timestamp when ok===true.
+ */
+function recordAttempt(ip, ok) {
+  if (!ip) return;
+  const now = Date.now();
+  const arr = _attempts.get(ip) || [];
+  arr.push(now);
+  _attempts.set(ip, arr);
+  _evictIfFull(_attempts);
+  if (ok) {
+    const sarr = _successes.get(ip) || [];
+    sarr.push(now);
+    _successes.set(ip, sarr);
+    _evictIfFull(_successes);
+  }
+}
+
+function _resetForTests() {
+  _attempts.clear();
+  _successes.clear();
+  _config = {
+    windowMs: DEFAULT_ATTEMPT_WINDOW_MS,
+    attemptLimit: DEFAULT_ATTEMPT_LIMIT,
+    successLimit: DEFAULT_SUCCESS_LIMIT,
+  };
+}
+
+function _stats() {
+  return {
+    config: { ..._config },
+    ips_with_attempts: _attempts.size,
+    ips_with_successes: _successes.size,
+  };
+}
+
+module.exports = {
+  configure,
+  checkBeforeAttempt,
+  recordAttempt,
+  _resetForTests,
+  _stats,
+  DEFAULT_ATTEMPT_WINDOW_MS,
+  DEFAULT_ATTEMPT_LIMIT,
+  DEFAULT_SUCCESS_LIMIT,
+};

package/server/security/human-gate-transports.js

@@ -0,0 +1,178 @@
+'use strict';
+
+/**
+ * WAB Safety Shield — Human-Gate Transports (SPEC §8.11)
+ *
+ * Real-world delivery channels for the 6-digit confirmation code.
+ *
+ * Each transport is a pure async function:
+ *   (challenge) => Promise<{ ok: boolean, channel: string, error?: string }>
+ *
+ * Where `challenge` is:
+ *   {
+ *     challenge_id, code, site_id, action_name, actor_id,
+ *     expires_at, siteConfig
+ *   }
+ *
+ * The `siteConfig.humanGate` object configures the transport. Available
+ * built-in transports:
+ *
+ *   • null     — no-op (default; tests + offline)
+ *   • webhook  — POST signed JSON to siteConfig.humanGate.webhook.url
+ *   • email    — minimal SMTP via nodemailer (lazy-required)
+ *   • console  — stderr log (development convenience)
+ *
+ * Custom transports can still be registered with humanGate.setTransport.
+ * Transports must NEVER log the plaintext code anywhere persistent.
+ */
+
+const crypto = require('crypto');
+
+// ────────────────────────────────────────────────────────────────────
+// webhook transport
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Sign the JSON body with HMAC-SHA256(secret, body) and POST it.
+ * Receivers verify with the X-WAB-Signature header.
+ *
+ * Required: siteConfig.humanGate.webhook.url
+ * Optional: siteConfig.humanGate.webhook.secret  (HMAC key; recommended)
+ *           siteConfig.humanGate.webhook.headers (extra static headers)
+ *           siteConfig.humanGate.webhook.timeoutMs (default 5000)
+ */
+async function webhookTransport(challenge) {
+  const cfg = challenge.siteConfig?.humanGate?.webhook || {};
+  if (!cfg.url || !/^https?:\/\//i.test(cfg.url)) {
+    return { ok: false, channel: 'webhook', error: 'missing_or_invalid_webhook_url' };
+  }
+  const fetchImpl = globalThis.fetch;
+  if (typeof fetchImpl !== 'function') {
+    return { ok: false, channel: 'webhook', error: 'no_fetch_available' };
+  }
+
+  const payload = {
+    type: 'wab.human_gate.challenge',
+    spec: '8.11',
+    challenge_id: challenge.challenge_id,
+    code: challenge.code,
+    site_id: challenge.site_id,
+    action_name: challenge.action_name,
+    actor_id: challenge.actor_id || null,
+    expires_at: challenge.expires_at,
+    issued_at: new Date().toISOString(),
+  };
+  const body = JSON.stringify(payload);
+  const headers = { 'Content-Type': 'application/json', ...(cfg.headers || {}) };
+  if (cfg.secret) {
+    const sig = crypto.createHmac('sha256', cfg.secret).update(body).digest('hex');
+    headers['X-WAB-Signature'] = `sha256=${sig}`;
+  }
+
+  const timeoutMs = Math.max(500, Math.min(30000, cfg.timeoutMs || 5000));
+  const ctrl = typeof AbortController === 'function' ? new AbortController() : null;
+  const timer = ctrl ? setTimeout(() => ctrl.abort(), timeoutMs) : null;
+  try {
+    const res = await fetchImpl(cfg.url, {
+      method: 'POST',
+      headers,
+      body,
+      signal: ctrl ? ctrl.signal : undefined,
+    });
+    if (!res.ok) {
+      return { ok: false, channel: 'webhook', error: `http_${res.status}` };
+    }
+    return { ok: true, channel: 'webhook' };
+  } catch (err) {
+    return { ok: false, channel: 'webhook', error: err.name === 'AbortError' ? 'timeout' : (err.message || 'network_error') };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────
+// email transport (lazy nodemailer)
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Send the code via SMTP. Requires `nodemailer` to be installed.
+ *
+ * Required: siteConfig.humanGate.email.to
+ * Optional: siteConfig.humanGate.email.from   (default: WAB_HUMAN_GATE_FROM env or 'noreply@wab.local')
+ *           siteConfig.humanGate.email.smtp   ({ host, port, secure, auth: { user, pass } })
+ *
+ * If smtp is omitted, falls back to env-based config:
+ *   SMTP_HOST / SMTP_PORT / SMTP_SECURE / SMTP_USER / SMTP_PASS
+ */
+async function emailTransport(challenge) {
+  const cfg = challenge.siteConfig?.humanGate?.email || {};
+  if (!cfg.to) return { ok: false, channel: 'email', error: 'missing_email_to' };
+
+  let nodemailer;
+  try {
+    nodemailer = require('nodemailer');
+  } catch {
+    return { ok: false, channel: 'email', error: 'nodemailer_not_installed' };
+  }
+
+  const smtp = cfg.smtp || {
+    host: process.env.SMTP_HOST,
+    port: Number(process.env.SMTP_PORT || 587),
+    secure: String(process.env.SMTP_SECURE || '').toLowerCase() === 'true',
+    auth: process.env.SMTP_USER ? {
+      user: process.env.SMTP_USER,
+      pass: process.env.SMTP_PASS,
+    } : undefined,
+  };
+  if (!smtp.host) return { ok: false, channel: 'email', error: 'no_smtp_host' };
+
+  try {
+    const transporter = nodemailer.createTransport(smtp);
+    const from = cfg.from || process.env.WAB_HUMAN_GATE_FROM || 'noreply@wab.local';
+    const subject = `[WAB] Approval needed: ${challenge.action_name}`;
+    const text =
+      `An AI agent is requesting a high-risk action on your site.\n\n` +
+      `  Site:    ${challenge.site_id}\n` +
+      `  Action:  ${challenge.action_name}\n` +
+      `  Actor:   ${challenge.actor_id || '(unknown)'}\n` +
+      `  Expires: ${challenge.expires_at}\n\n` +
+      `Approval code: ${challenge.code}\n\n` +
+      `If you did NOT initiate this, do nothing — the request will expire.\n` +
+      `Do not share this code. SPEC: https://webagentbridge.com/docs/SPEC.md#811-out-of-band-human-gate\n`;
+    await transporter.sendMail({ from, to: cfg.to, subject, text });
+    return { ok: true, channel: 'email' };
+  } catch (err) {
+    return { ok: false, channel: 'email', error: err.message || 'smtp_error' };
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────
+// console transport (dev convenience)
+// ────────────────────────────────────────────────────────────────────
+
+async function consoleTransport(challenge) {
+  // Intentionally writes to stderr only; never to a log file or audit row.
+  process.stderr.write(
+    `[wab:human-gate] challenge=${challenge.challenge_id} ` +
+    `site=${challenge.site_id} action=${challenge.action_name} ` +
+    `code=${challenge.code} expires=${challenge.expires_at}\n`
+  );
+  return { ok: true, channel: 'console' };
+}
+
+// ────────────────────────────────────────────────────────────────────
+// public surface — register all on a humanGate instance
+// ────────────────────────────────────────────────────────────────────
+
+function registerAll(humanGate) {
+  humanGate.setTransport('webhook', webhookTransport);
+  humanGate.setTransport('email', emailTransport);
+  humanGate.setTransport('console', consoleTransport);
+}
+
+module.exports = {
+  webhookTransport,
+  emailTransport,
+  consoleTransport,
+  registerAll,
+};