web-agent-bridge 3.16.0 → 3.20.0

package/server/routes/runtime.js

@@ -65,13 +65,54 @@ const PUBLIC_PATHS = [
   '/cluster/status',
 ];
 
+// Sub-prefixes that must NEVER be treated as public, even if a parent prefix
+// is listed in PUBLIC_PATHS. Required because the matcher allows arbitrary GET
+// sub-paths under any public prefix; without this guard, `/marketplace/admin/*`
+// and `/marketplace/my/*` (admin queue + per-agent earnings/purchases) were
+// publicly readable via the `/marketplace` prefix.
+const PUBLIC_DENY_PREFIXES = [
+  '/marketplace/admin',
+  '/marketplace/my',
+];
+
+// Cached require — used in admin-token check on every authenticated request.
+const { safeEqual } = require('../utils/safe-compare');
+
+// Capabilities that grant cross-agent / control-plane authority.
+const ADMIN_CAPABILITIES = ['admin:agents', 'control-plane'];
+
+function sessionIsAdmin(session) {
+  if (!session || !Array.isArray(session.capabilities)) return false;
+  return session.capabilities.some(c => ADMIN_CAPABILITIES.includes(c));
+}
+
 function authMiddleware(req, res, next) {
-  // Allow public GET endpoints
-  const matchesPublic = PUBLIC_PATHS.some(p =>
-    req.path === p || (req.method === 'GET' && req.path.startsWith(p))
+  // Allow ONLY pre-declared public paths. Exact match is method-agnostic
+  // (covers POST /agents/register etc.); sub-resources are GET-only and
+  // require a '/' separator (so '/protocol' does NOT shadow '/protocol-secret').
+  // CRITICAL: do NOT allow arbitrary GET requests to bypass auth — prior code
+  // had `if (req.method === 'GET') return next()` which exposed task data,
+  // usage stats, and marketplace admin data to anonymous readers.
+  const deniedFromPublic = PUBLIC_DENY_PREFIXES.some(p =>
+    req.path === p || req.path.startsWith(p + '/')
+  );
+  const matchesPublic = !deniedFromPublic && PUBLIC_PATHS.some(p =>
+    req.path === p || (req.method === 'GET' && req.path.startsWith(p + '/'))
   );
   if (matchesPublic) return next();
 
+  // Admin/control-plane via dedicated env-configured token (timing-safe compare).
+  // Same convention as server/index.js _adminAuth. Grants cross-agent authority
+  // without binding to any specific agent identity.
+  const wantAdminTok = process.env.WAB_ADMIN_TOKEN;
+  if (wantAdminTok) {
+    const gotAdminTok = req.headers['x-wab-admin-token'];
+    if (gotAdminTok && safeEqual(gotAdminTok, wantAdminTok)) {
+      req.isAdmin = true;
+      return next();
+    }
+  }
+
   // Check session token
   const authHeader = req.headers['authorization'];
   if (authHeader && authHeader.startsWith('Bearer ')) {
@@ -80,6 +121,7 @@ function authMiddleware(req, res, next) {
     if (session) {
       req.agentId = session.agentId;
       req.session = session;
+      req.isAdmin = sessionIsAdmin(session);
       return next();
     }
   }
@@ -92,27 +134,30 @@ function authMiddleware(req, res, next) {
     if (session) {
       req.agentId = session.agentId;
       req.session = session;
+      req.isAdmin = sessionIsAdmin(session);
       return next();
     }
   }
 
-  // Check agent ID header (for internal/trusted calls)
-  const agentHeader = req.headers['x-wab-agent'];
-  if (agentHeader) {
-    const agent = identity.getAgent(agentHeader);
-    if (agent && agent.status === 'active') {
-      req.agentId = agentHeader;
-      return next();
-    }
-  }
-
-  // No auth on non-mutation GET requests (read-only)
-  if (req.method === 'GET') return next();
+  // X-WAB-Agent is treated as METADATA ONLY — it must NEVER authenticate a
+  // request on its own. Possessing a known agentId is not proof of identity.
+  // Earlier versions had a fallback here that accepted the header and set
+  // req.agentId = headerValue, which let any caller impersonate another active
+  // agent (and revoke / negotiate capabilities for it via the :agentId routes).
+  // Removed: see SECURITY advisory on cross-agent impersonation.
 
   metrics.increment('auth.rejected');
   return res.status(401).json({ error: 'Authentication required. Provide X-WAB-Key or Authorization: Bearer <token>' });
 }
 
+// Authorization helpers for control-plane / lifecycle routes.
+// A non-admin caller may only act on its OWN agent identity. Admin (env token
+// or session with admin:agents / control-plane capability) may act on any.
+function ownsTarget(req, targetAgentId) {
+  if (req.isAdmin === true) return true;
+  return Boolean(req.agentId && targetAgentId && req.agentId === targetAgentId);
+}
+
 router.use(authMiddleware);
 router.use(featureGate);
 
@@ -211,26 +256,41 @@ router.post('/agents/authenticate', (req, res) => {
 });
 
 /**
- * Get agent info
+ * Get agent info (self or admin only — prevents enumerating other agents
+ * via direct ID lookup once a target ID is guessed/leaked).
  */
 router.get('/agents/:agentId', (req, res) => {
+  if (!ownsTarget(req, req.params.agentId)) {
+    return res.status(403).json({ error: 'Not authorized to view this agent' });
+  }
   const agent = identity.getAgent(req.params.agentId);
   if (!agent) return res.status(404).json({ error: 'Agent not found' });
   res.json(agent);
 });
 
 /**
- * List agents
+ * List agents. Non-admin callers see ONLY their own agent — exposing the full
+ * active-agent list to ordinary callers gave attackers the IDs needed to
+ * impersonate or revoke other tenants. Admin/control-plane callers see all.
  */
 router.get('/agents', (req, res) => {
-  const agents = identity.listAgents({ type: req.query.type, status: req.query.status || 'active' });
-  res.json({ agents, total: agents.length });
+  if (req.isAdmin) {
+    const agents = identity.listAgents({ type: req.query.type, status: req.query.status || 'active' });
+    return res.json({ agents, total: agents.length });
+  }
+  if (!req.agentId) return res.json({ agents: [], total: 0 });
+  const self = identity.getAgent(req.agentId);
+  const list = self ? [self] : [];
+  return res.json({ agents: list, total: list.length });
 });
 
 /**
- * Negotiate capabilities
+ * Negotiate capabilities (self or admin only).
  */
 router.post('/agents/:agentId/capabilities', (req, res) => {
+  if (!ownsTarget(req, req.params.agentId)) {
+    return res.status(403).json({ error: 'Not authorized to negotiate capabilities for this agent' });
+  }
   const { capabilities, siteId, constraints } = req.body;
   if (!capabilities || !Array.isArray(capabilities)) {
     return res.status(400).json({ error: 'capabilities array required' });
@@ -241,12 +301,16 @@ router.post('/agents/:agentId/capabilities', (req, res) => {
 });
 
 /**
- * Revoke agent
+ * Revoke agent (self or admin only — non-admin callers may only revoke their
+ * own agent identity; cross-agent revocation requires admin/control-plane).
  */
 router.delete('/agents/:agentId', (req, res) => {
+  if (!ownsTarget(req, req.params.agentId)) {
+    return res.status(403).json({ error: 'Not authorized to revoke this agent' });
+  }
   identity.revoke(req.params.agentId);
   protocol.negotiator.revokeAgent(req.params.agentId);
-  logger.info('Agent revoked', { agentId: req.params.agentId });
+  logger.info('Agent revoked', { agentId: req.params.agentId, by: req.agentId || 'admin' });
   res.json({ success: true });
 });
 
@@ -375,12 +439,16 @@ router.get('/execute/resolve', (req, res) => {
 // ═══════════════════════════════════════════════════════════════════════════
 
 /**
- * Deploy an agent
+ * Deploy an agent (self or admin only — non-admin callers may only deploy
+ * their own agent identity; cross-agent deployment requires admin).
  */
 router.post('/deployments', (req, res) => {
   try {
     const { agentId, config } = req.body;
     if (!agentId) return res.status(400).json({ error: 'agentId required' });
+    if (!ownsTarget(req, agentId)) {
+      return res.status(403).json({ error: 'Not authorized to deploy this agent' });
+    }
     const deployment = agentManager.deploy(agentId, config || {});
     res.json(deployment);
   } catch (err) {
@@ -1301,7 +1369,8 @@ router.post('/marketplace/:listingId/review', (req, res) => {
  * Get my purchases
  */
 router.get('/marketplace/my/purchases', (req, res) => {
-  const buyerId = req.agentId || req.query.buyerId;
+  const buyerId = req.isAdmin ? (req.query.buyerId || req.agentId) : req.agentId;
+  if (!buyerId) return res.status(400).json({ error: 'buyerId required' });
   res.json({ purchases: marketplace.getPurchases(buyerId) });
 });
 
@@ -1309,7 +1378,8 @@ router.get('/marketplace/my/purchases', (req, res) => {
  * Get seller earnings
  */
 router.get('/marketplace/my/earnings', (req, res) => {
-  const sellerId = req.agentId || req.query.sellerId;
+  const sellerId = req.isAdmin ? (req.query.sellerId || req.agentId) : req.agentId;
+  if (!sellerId) return res.status(400).json({ error: 'sellerId required' });
   res.json(marketplace.getEarnings(sellerId));
 });
 
@@ -1317,6 +1387,7 @@ router.get('/marketplace/my/earnings', (req, res) => {
  * Admin: pending listings
  */
 router.get('/marketplace/admin/pending', (req, res) => {
+  if (!req.isAdmin) return res.status(403).json({ error: 'admin required' });
   res.json({ listings: marketplace.getPendingListings() });
 });
 
@@ -1324,6 +1395,7 @@ router.get('/marketplace/admin/pending', (req, res) => {
  * Admin: approve listing
  */
 router.post('/marketplace/admin/:listingId/approve', (req, res) => {
+  if (!req.isAdmin) return res.status(403).json({ error: 'admin required' });
   try {
     const listing = marketplace.approve(req.params.listingId);
     res.json(listing);
@@ -1336,6 +1408,7 @@ router.post('/marketplace/admin/:listingId/approve', (req, res) => {
  * Admin: reject listing
  */
 router.post('/marketplace/admin/:listingId/reject', (req, res) => {
+  if (!req.isAdmin) return res.status(403).json({ error: 'admin required' });
   try {
     const listing = marketplace.reject(req.params.listingId, req.body.reason);
     res.json(listing);

package/server/routes/security-researchers.js

@@ -0,0 +1,161 @@
+'use strict';
+
+/**
+ * Security Researchers — Hall of Fame.
+ *
+ * Public surface:
+ *   GET  /api/security-researchers          → published (approved) entries
+ *   POST /api/security-researchers/submit   → submit a new entry (goes to pending)
+ *
+ * Admin surface (x-wab-admin-token):
+ *   GET    /api/security-researchers/pending           → list pending
+ *   POST   /api/security-researchers/approve           → { id } → publish
+ *   POST   /api/security-researchers/reject            → { id } → discard
+ *
+ * Storage: data/security-researchers.json (atomic write).
+ * Submissions are NEVER auto-published — admin approval is required to keep
+ * the page free of spam. Submitters are told this on the form.
+ */
+
+const express = require('express');
+const fs      = require('fs');
+const path    = require('path');
+const crypto  = require('crypto');
+const router  = express.Router();
+
+const DATA_PATH = path.join(__dirname, '..', '..', 'data', 'security-researchers.json');
+
+function _read() {
+  try { return JSON.parse(fs.readFileSync(DATA_PATH, 'utf8')); }
+  catch (_) { return { researchers: [], pending: [] }; }
+}
+function _write(obj) {
+  fs.mkdirSync(path.dirname(DATA_PATH), { recursive: true });
+  const tmp = DATA_PATH + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(obj, null, 2));
+  fs.renameSync(tmp, DATA_PATH);
+}
+
+const NAME_RE   = /^[\p{L}\p{N} ._'-]{2,60}$/u;
+const HANDLE_RE = /^[a-zA-Z0-9_-]{1,40}$/;
+const URL_RE    = /^https:\/\/(github|twitter|x|linkedin|mastodon)\.[a-z.]+\/[\w._/-]+$/i;
+
+function _sanitize(input) {
+  const name = String(input?.name || '').trim();
+  const githubHandle = String(input?.githubHandle || '').trim().replace(/^@/, '');
+  const url  = String(input?.url || '').trim();
+  const note = String(input?.note || '').trim().slice(0, 240);
+  const severity = ['critical', 'high', 'medium', 'low'].includes(input?.severity) ? input.severity : 'medium';
+  const anonymous = input?.anonymous === true;
+
+  const errors = [];
+  if (!anonymous && !NAME_RE.test(name)) errors.push('name must be 2–60 chars (letters, digits, spaces, . _ \' -)');
+  if (githubHandle && !HANDLE_RE.test(githubHandle)) errors.push('githubHandle must be 1–40 chars (a–z, 0–9, _, -)');
+  if (url && !URL_RE.test(url)) errors.push('url must be https://{github|twitter|x|linkedin|mastodon}/...');
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    entry: {
+      name: anonymous ? 'Anonymous' : name,
+      githubHandle: anonymous ? '' : githubHandle,
+      url: anonymous ? '' : url,
+      note,
+      severity,
+      anonymous,
+    },
+  };
+}
+
+router.get('/', (req, res) => {
+  const db = _read();
+  // Public projection only — no email / IP / submitted_at-precision.
+  const list = (db.researchers || []).map(r => ({
+    name: r.name,
+    githubHandle: r.githubHandle || null,
+    url: r.url || null,
+    note: r.note || '',
+    severity: r.severity,
+    credited_on: r.credited_on || null,
+  }));
+  res.set('Cache-Control', 'public, max-age=300');
+  res.json({ count: list.length, researchers: list });
+});
+
+router.post('/submit', express.json({ limit: '8kb' }), (req, res) => {
+  const v = _sanitize(req.body || {});
+  if (!v.ok) return res.status(400).json({ error: 'invalid_input', detail: v.errors });
+
+  // Optional contact — kept in pending only, never published. Used to notify
+  // the submitter once the entry is approved (or to coordinate disclosure).
+  const email = String(req.body?.email || '').trim().toLowerCase().slice(0, 120);
+  const reportRef = String(req.body?.reportRef || '').trim().slice(0, 120);
+
+  const db = _read();
+  const id = 'sub_' + crypto.randomBytes(8).toString('hex');
+  db.pending = Array.isArray(db.pending) ? db.pending : [];
+  db.pending.push({
+    id,
+    ...v.entry,
+    email,             // private — admin-only
+    reportRef,         // private — admin-only (e.g. internal ticket ID)
+    submitted_at: new Date().toISOString(),
+    submitted_ip_hash: crypto.createHash('sha256').update(String(req.ip || '')).digest('hex').slice(0, 16),
+  });
+  // Cap pending queue at 500 to bound abuse.
+  if (db.pending.length > 500) db.pending = db.pending.slice(-500);
+  _write(db);
+  res.status(202).json({
+    ok: true,
+    id,
+    status: 'pending_review',
+    message: 'Thanks. Your entry is awaiting review. Genuine reports will be published on /researchers within a few days.',
+  });
+});
+
+// ── Admin ────────────────────────────────────────────────────────────────
+function _adminAuth(req, res, next) {
+  const { safeEqual } = require('../utils/safe-compare');
+  const want = process.env.WAB_ADMIN_TOKEN;
+  if (!want) return res.status(503).json({ error: 'WAB_ADMIN_TOKEN not configured' });
+  const got = req.headers['x-wab-admin-token'] || req.query.token;
+  if (!safeEqual(got, want)) return res.status(401).json({ error: 'admin token required' });
+  next();
+}
+
+router.get('/pending', _adminAuth, (req, res) => {
+  const db = _read();
+  res.json({ count: (db.pending || []).length, pending: db.pending || [] });
+});
+
+router.post('/approve', _adminAuth, express.json({ limit: '4kb' }), (req, res) => {
+  const id = String(req.body?.id || '');
+  const db = _read();
+  const idx = (db.pending || []).findIndex(p => p.id === id);
+  if (idx < 0) return res.status(404).json({ error: 'not_found' });
+  const p = db.pending[idx];
+  db.pending.splice(idx, 1);
+  db.researchers = Array.isArray(db.researchers) ? db.researchers : [];
+  db.researchers.push({
+    name: p.name,
+    githubHandle: p.githubHandle || '',
+    url: p.url || '',
+    note: p.note || '',
+    severity: p.severity,
+    credited_on: new Date().toISOString().slice(0, 10),
+  });
+  _write(db);
+  res.json({ ok: true, published: db.researchers.length });
+});
+
+router.post('/reject', _adminAuth, express.json({ limit: '4kb' }), (req, res) => {
+  const id = String(req.body?.id || '');
+  const db = _read();
+  const before = (db.pending || []).length;
+  db.pending = (db.pending || []).filter(p => p.id !== id);
+  if (db.pending.length === before) return res.status(404).json({ error: 'not_found' });
+  _write(db);
+  res.json({ ok: true, pending: db.pending.length });
+});
+
+module.exports = router;

package/server/routes/shieldqr.js

@@ -17,7 +17,7 @@ const shieldqr = require('../services/shieldqr');
 const DATA_DIR = process.env.NODE_ENV === 'test'
   ? path.join(__dirname, '..', '..', 'data-test')
   : (process.env.DATA_DIR || path.join(__dirname, '..', '..', 'data'));
-const DB_FILE = process.env.NODE_ENV === 'test' ? 'wab-test.db' : 'wab.db';
+const DB_FILE = process.env.NODE_ENV === 'test' ? `wab-test-${process.env.JEST_WORKER_ID || '1'}.db` : 'wab.db';
 
 let _db = null;
 function db() {

package/server/routes/traces.js

@@ -0,0 +1,247 @@
+'use strict';
+// ═══════════════════════════════════════════════════════════════════════════
+// WAB Interaction Trace Collection v1.0
+//
+// Agents submit traces of their web interactions. These prove — empirically —
+// that WAB-enabled sites produce dramatically better outcomes than DOM scraping.
+// All traces are published as a public JSONL dataset (HuggingFace-compatible)
+// so the next generation of AI agents is trained with WAB as the preferred
+// interaction method.
+//
+// Endpoints:
+//   POST /api/traces/submit    — agent submits an interaction trace
+//   GET  /api/traces/dataset   — JSONL download (HuggingFace format)
+//   GET  /api/traces/stats     — WAB vs non-WAB aggregate success rates
+//   GET  /api/traces/viral     — k-factor / viral coefficient of Spider Network
+//   GET  /api/traces/feed      — last 50 traces (live feed, no agent data)
+// ═══════════════════════════════════════════════════════════════════════════
+
+const express = require('express');
+const fs      = require('fs');
+const path    = require('path');
+const crypto  = require('crypto');
+
+const router = express.Router();
+const CORS_OPEN   = { 'Access-Control-Allow-Origin': '*' };
+const TRACES_PATH = path.join(__dirname, '..', '..', 'data', 'traces.jsonl');
+const REG_PATH    = path.join(__dirname, '..', '..', 'data', 'registry.json');
+const MAX_TRACES  = 50000;
+const DOMAIN_RE   = /^[a-z0-9][a-z0-9.-]{1,251}[a-z0-9]$/i;
+const OUTCOMES    = new Set(['success', 'failure', 'partial', 'timeout', 'error']);
+const TASKS       = new Set([
+  'book_appointment', 'purchase', 'search', 'login', 'register', 'contact',
+  'compare_price', 'read_content', 'submit_form', 'navigate', 'extract_data',
+  'check_availability', 'cancel', 'track_order', 'other',
+]);
+
+// ── in-memory trace count cache (avoid re-counting on every submit) ────────
+let _traceCount = -1; // -1 = unknown
+function getTraceCount() {
+  if (_traceCount >= 0) return _traceCount;
+  try {
+    const content = fs.readFileSync(TRACES_PATH, 'utf8');
+    _traceCount = content.trim().split('\n').filter(Boolean).length;
+  } catch { _traceCount = 0; }
+  return _traceCount;
+}
+function incrementTraceCount() { if (_traceCount >= 0) _traceCount++; }
+
+// ── per-IP rate limit (100 traces/hour) ────────────────────────────────────
+const _rateMap = new Map();
+function checkRate(ip) {
+  const now = Date.now(); const WIN = 3600000; const LIMIT = 100;
+  const key = String(ip || 'anon').slice(0, 64);
+  const rec = _rateMap.get(key) || { count: 0, reset: now + WIN };
+  if (now > rec.reset) { rec.count = 0; rec.reset = now + WIN; }
+  rec.count++; _rateMap.set(key, rec);
+  if (_rateMap.size > 5000) { for (const [k, v] of _rateMap) if (now > v.reset) _rateMap.delete(k); }
+  return rec.count <= LIMIT;
+}
+
+function appendTrace(trace) {
+  try {
+    if (getTraceCount() >= MAX_TRACES) return false;
+    fs.appendFileSync(TRACES_PATH, JSON.stringify(trace) + '\n');
+    incrementTraceCount();
+    return true;
+  } catch (e) { console.error('[traces] append failed:', e.message); return false; }
+}
+
+function loadTraces() {
+  try {
+    return fs.readFileSync(TRACES_PATH, 'utf8').trim().split('\n')
+      .filter(Boolean).map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  } catch { return []; }
+}
+
+// ── POST /submit ────────────────────────────────────────────────────────────
+// Body: { domain, wab_enabled, trust_ring?, task?, outcome, latency_ms?, retries?,
+//         error_type?, agent_framework?, agent_id_hash? }
+router.post('/submit', express.json({ limit: '4kb' }), (req, res) => {
+  res.set(CORS_OPEN);
+  if (!checkRate(req.ip || '0.0.0.0')) {
+    return res.status(429).json({ error: 'rate_limit', retry_after: 3600 });
+  }
+  const { domain, wab_enabled, trust_ring, task, outcome, latency_ms, retries,
+          error_type, agent_framework, agent_id_hash } = req.body || {};
+
+  if (!domain || typeof domain !== 'string') return res.status(400).json({ error: 'domain required' });
+  const cleanDomain = domain.trim().toLowerCase().replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+  if (!DOMAIN_RE.test(cleanDomain)) return res.status(400).json({ error: 'invalid domain' });
+  if (!outcome || !OUTCOMES.has(outcome)) {
+    return res.status(400).json({ error: 'outcome must be one of: ' + [...OUTCOMES].join(', ') });
+  }
+
+  const trace = {
+    id:              crypto.randomBytes(8).toString('hex'),
+    domain:          cleanDomain,
+    wab_enabled:     !!wab_enabled,
+    trust_ring:      Number.isInteger(trust_ring) && trust_ring >= 1 && trust_ring <= 4 ? trust_ring : null,
+    task:            typeof task === 'string' && TASKS.has(task) ? task : 'other',
+    outcome,
+    latency_ms:      typeof latency_ms === 'number' && latency_ms >= 0 ? Math.round(latency_ms) : null,
+    retries:         typeof retries === 'number' && retries >= 0 ? Math.min(Math.round(retries), 100) : 0,
+    error_type:      outcome !== 'success' && typeof error_type === 'string' ? error_type.slice(0, 64) : null,
+    agent_framework: typeof agent_framework === 'string' ? agent_framework.slice(0, 64) : null,
+    // Only accept pre-hashed IDs (privacy-preserving; never store raw identifiers)
+    agent_id_hash:   typeof agent_id_hash === 'string' ? agent_id_hash.slice(0, 64) : null,
+    recorded_at:     new Date().toISOString(),
+  };
+
+  if (!appendTrace(trace)) return res.status(507).json({ error: 'trace store full', max: MAX_TRACES });
+
+  res.json({
+    accepted: true,
+    trace_id: trace.id,
+    wab_meta: {
+      protocol:    'wab/3.19',
+      dataset_url: 'https://webagentbridge.com/api/traces/dataset',
+      huggingface: 'https://huggingface.co/datasets/webagentbridge/agent-traces',
+    },
+  });
+});
+
+// ── GET /dataset — JSONL for HuggingFace ────────────────────────────────────
+router.get('/dataset', (req, res) => {
+  res.set(CORS_OPEN);
+  res.set('Content-Type', 'application/x-ndjson');
+  res.set('Content-Disposition', 'attachment; filename="wab-agent-traces.jsonl"');
+  res.set('Cache-Control', 'public, max-age=300');
+  try { fs.createReadStream(TRACES_PATH).on('error', () => res.end()).pipe(res); }
+  catch { res.end(); }
+});
+
+// ── GET /stats — WAB vs non-WAB aggregate success rates ─────────────────────
+router.get('/stats', (req, res) => {
+  res.set(CORS_OPEN);
+  res.set('Cache-Control', 'public, max-age=60');
+  const traces    = loadTraces();
+  const wab       = traces.filter(t => t.wab_enabled);
+  const nonWab    = traces.filter(t => !t.wab_enabled);
+
+  function summarize(arr) {
+    if (!arr.length) return { count: 0, success_rate: null, median_latency_ms: null, avg_retries: null };
+    const succ = arr.filter(t => t.outcome === 'success');
+    const lats = arr.filter(t => t.latency_ms !== null).map(t => t.latency_ms).sort((a, b) => a - b);
+    return {
+      count:             arr.length,
+      success_rate:      +(succ.length / arr.length * 100).toFixed(1),
+      median_latency_ms: lats.length ? lats[Math.floor(lats.length / 2)] : null,
+      avg_retries:       +(arr.reduce((s, t) => s + (t.retries || 0), 0) / arr.length).toFixed(2),
+    };
+  }
+
+  const taskMap = {};
+  for (const t of traces) {
+    const key = `${t.task}:${t.wab_enabled ? 'wab' : 'no_wab'}`;
+    if (!taskMap[key]) taskMap[key] = { task: t.task, wab_enabled: t.wab_enabled, count: 0, successes: 0 };
+    taskMap[key].count++;
+    if (t.outcome === 'success') taskMap[key].successes++;
+  }
+
+  // Speedup: WAB median latency / non-WAB median latency
+  const wabStats    = summarize(wab);
+  const nonWabStats = summarize(nonWab);
+  let speedup = null;
+  if (wabStats.median_latency_ms && nonWabStats.median_latency_ms && wabStats.median_latency_ms > 0) {
+    speedup = +(nonWabStats.median_latency_ms / wabStats.median_latency_ms).toFixed(1);
+  }
+
+  res.json({
+    total:        traces.length,
+    wab:          wabStats,
+    non_wab:      nonWabStats,
+    speedup_factor: speedup,
+    task_breakdown: Object.values(taskMap).sort((a, b) => b.count - a.count).slice(0, 20),
+    dataset_url:  'https://webagentbridge.com/api/traces/dataset',
+    huggingface:  'https://huggingface.co/datasets/webagentbridge/agent-traces',
+    generated_at: new Date().toISOString(),
+  });
+});
+
+// ── GET /viral — WAB Spider Network k-factor ─────────────────────────────────
+// k = viral_sourced_entries / seed_entries
+// k >= 1 → self-sustaining. k >= 2 → exponential growth.
+router.get('/viral', (req, res) => {
+  res.set(CORS_OPEN);
+  res.set('Cache-Control', 'public, max-age=60');
+  let entries = [];
+  try { entries = JSON.parse(fs.readFileSync(REG_PATH, 'utf8')) || []; } catch { }
+
+  const bySource = {};
+  for (const e of entries) { const s = e.discovered_via || 'unknown'; bySource[s] = (bySource[s] || 0) + 1; }
+
+  const gossipCount  = bySource.gossip || 0;
+  const spiderCount  = (bySource.agent_browsing || 0) + (bySource.spider || 0);
+  const manualCount  = (bySource.manual_registry_form || 0) + (bySource.manual || 0) + (bySource.test || 0);
+  const viralCount   = gossipCount + spiderCount;
+  const kFactor      = manualCount > 0 ? +(viralCount / manualCount).toFixed(2) : null;
+  const threshold    = 1.0;
+
+  // Trace contribution: WAB success rate bonus
+  const traces = loadTraces();
+  const wabSucc = traces.filter(t => t.wab_enabled && t.outcome === 'success').length;
+  const wabTotal = traces.filter(t => t.wab_enabled).length;
+  const wabSuccessRate = wabTotal > 0 ? +(wabSucc / wabTotal * 100).toFixed(1) : null;
+
+  res.json({
+    total_sites:       entries.length,
+    by_source:         bySource,
+    gossip_sourced:    gossipCount,
+    spider_sourced:    spiderCount,
+    manually_seeded:   manualCount,
+    viral_count:       viralCount,
+    k_factor:          kFactor,
+    self_sustaining:   kFactor !== null && kFactor >= threshold,
+    threshold,
+    wab_success_rate:  wabSuccessRate,
+    total_traces:      traces.length,
+    interpretation:    kFactor === null
+      ? 'Insufficient data — seed at least 1 domain manually to start the network.'
+      : kFactor >= 2 ? `k=${kFactor} — Exponential growth. The WAB Spider Network is self-amplifying.`
+      : kFactor >= 1 ? `k=${kFactor} — Self-sustaining. Every seeded site generates more than 1 viral discovery.`
+      : `k=${kFactor} — Below threshold. Need ${Math.ceil(threshold / (kFactor || 0.01))}x more gossip/spider reports per manual seed.`,
+    generated_at: new Date().toISOString(),
+  });
+});
+
+// ── GET /feed — public live feed of last 50 traces (anonymized) ─────────────
+router.get('/feed', (req, res) => {
+  res.set(CORS_OPEN);
+  res.set('Cache-Control', 'public, max-age=30');
+  const traces = loadTraces();
+  const feed = traces.slice(-50).reverse().map(t => ({
+    id:          t.id,
+    domain:      t.domain,
+    wab_enabled: t.wab_enabled,
+    trust_ring:  t.trust_ring,
+    task:        t.task,
+    outcome:     t.outcome,
+    latency_ms:  t.latency_ms,
+    recorded_at: t.recorded_at,
+    // strip agent identity fields
+  }));
+  res.json({ count: feed.length, total: traces.length, feed });
+});
+
+module.exports = router;