web-agent-bridge 3.3.0 → 3.4.0

package/sdk/auto-discovery.js

@@ -0,0 +1,288 @@
+/**
+ * WAB SDK — Auto-Discovery Fallback
+ *
+ * For sites that haven't installed WAB yet (no /.well-known/wab.json,
+ * no _wab DNS TXT), this module produces a normalized capabilities envelope
+ * by parsing publicly available metadata:
+ *   1. /.well-known/wab.json   (canonical)
+ *   2. <script type="application/ld+json">   (JSON-LD / Schema.org)
+ *   3. <meta property="og:*">  (OpenGraph)
+ *   4. <meta name="description"> / <title>
+ *   5. /sitemap.xml            (URL inventory)
+ *   6. /robots.txt             (allow/disallow + Sitemap directives)
+ *
+ * The resulting envelope shape mirrors a minimal wab.json so downstream
+ * code can treat unsigned sites uniformly:
+ *
+ *   {
+ *     ok: boolean,
+ *     source: 'wab.json' | 'auto-discovery',
+ *     site: { name, description, url },
+ *     trust: { signed: false, ssl: { ... } },
+ *     actions: [ { name, description, source } ],
+ *     products: [ { name, sku, offers } ],
+ *     sitemap: [ url, ... ],
+ *     robots: { allow: [], disallow: [], sitemaps: [] }
+ *   }
+ *
+ * Pure JS, no external deps. Works in Node (with global fetch).
+ */
+
+const { extractJsonLdBlocks, extractProductsFromHtml, suggestWabActionsFromProducts } =
+  require('./schema-discovery');
+
+/* ------------------------------------------------------------------ */
+/* Helpers                                                            */
+/* ------------------------------------------------------------------ */
+
+function _abs(base, path) {
+  try {
+    return new URL(path, base).toString();
+  } catch {
+    return null;
+  }
+}
+
+async function _fetchText(url, { timeoutMs = 8000 } = {}) {
+  if (typeof fetch !== 'function') {
+    throw new Error('global fetch() is required (Node 18+) for auto-discovery');
+  }
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const r = await fetch(url, {
+      redirect: 'follow',
+      signal: ctrl.signal,
+      headers: { 'user-agent': 'wab-auto-discovery/1.0 (+https://webagentbridge.com)' }
+    });
+    if (!r.ok) return { ok: false, status: r.status, text: '' };
+    return { ok: true, status: r.status, text: await r.text() };
+  } catch (e) {
+    return { ok: false, status: 0, text: '', error: e.message };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* HTML metadata extractors                                            */
+/* ------------------------------------------------------------------ */
+
+function extractMetaTags(html) {
+  const out = { og: {}, twitter: {}, description: null, title: null };
+  if (!html) return out;
+
+  const titleM = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+  if (titleM) out.title = titleM[1].trim();
+
+  const metaRe = /<meta\b[^>]*>/gi;
+  let m;
+  while ((m = metaRe.exec(html)) !== null) {
+    const tag = m[0];
+    const nameM = tag.match(/\bname\s*=\s*["']([^"']+)["']/i);
+    const propM = tag.match(/\bproperty\s*=\s*["']([^"']+)["']/i);
+    const contentM = tag.match(/\bcontent\s*=\s*["']([^"']*)["']/i);
+    if (!contentM) continue;
+    const content = contentM[1];
+    const key = (propM && propM[1]) || (nameM && nameM[1]) || '';
+    if (!key) continue;
+    const lk = key.toLowerCase();
+    if (lk === 'description') out.description = content;
+    else if (lk.startsWith('og:')) out.og[lk.slice(3)] = content;
+    else if (lk.startsWith('twitter:')) out.twitter[lk.slice(8)] = content;
+  }
+  return out;
+}
+
+/* ------------------------------------------------------------------ */
+/* Sitemap / robots                                                   */
+/* ------------------------------------------------------------------ */
+
+function parseSitemap(xml, { limit = 200 } = {}) {
+  if (!xml) return [];
+  const urls = [];
+  const re = /<loc>\s*([^<\s]+)\s*<\/loc>/gi;
+  let m;
+  while ((m = re.exec(xml)) !== null && urls.length < limit) {
+    urls.push(m[1]);
+  }
+  return urls;
+}
+
+function parseRobots(text) {
+  const out = { allow: [], disallow: [], sitemaps: [], userAgents: [] };
+  if (!text) return out;
+  let currentUA = '*';
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.replace(/#.*$/, '').trim();
+    if (!line) continue;
+    const idx = line.indexOf(':');
+    if (idx < 0) continue;
+    const key = line.slice(0, idx).trim().toLowerCase();
+    const val = line.slice(idx + 1).trim();
+    if (key === 'user-agent') {
+      currentUA = val;
+      if (!out.userAgents.includes(val)) out.userAgents.push(val);
+    } else if (key === 'allow') out.allow.push({ ua: currentUA, path: val });
+    else if (key === 'disallow') out.disallow.push({ ua: currentUA, path: val });
+    else if (key === 'sitemap') out.sitemaps.push(val);
+  }
+  return out;
+}
+
+/* ------------------------------------------------------------------ */
+/* JSON-LD extras: WebSite + Organization + SearchAction               */
+/* ------------------------------------------------------------------ */
+
+function extractSiteIdentity(html) {
+  const blocks = extractJsonLdBlocks(html);
+  const out = { name: null, description: null, url: null, search: null, organization: null };
+  for (const text of blocks) {
+    let data;
+    try { data = JSON.parse(text); } catch { continue; }
+    const items = Array.isArray(data) ? data : Array.isArray(data['@graph']) ? data['@graph'] : [data];
+    for (const node of items) {
+      if (!node || typeof node !== 'object') continue;
+      let types = node['@type'];
+      if (typeof types === 'string') types = [types];
+      if (!Array.isArray(types)) types = [];
+      if (types.includes('WebSite')) {
+        out.name = out.name || node.name;
+        out.url = out.url || node.url;
+        out.description = out.description || node.description;
+        const action = node.potentialAction;
+        if (action && (Array.isArray(action) ? action[0] : action)) {
+          const a = Array.isArray(action) ? action[0] : action;
+          if (a && (a['@type'] === 'SearchAction' || /SearchAction/.test(String(a['@type'])))) {
+            out.search = {
+              target: typeof a.target === 'string' ? a.target : (a.target && a.target.urlTemplate),
+              queryParam: a['query-input'] || a.queryInput || null
+            };
+          }
+        }
+      } else if (types.includes('Organization')) {
+        out.organization = out.organization || { name: node.name, url: node.url, logo: node.logo };
+      }
+    }
+  }
+  return out;
+}
+
+/* ------------------------------------------------------------------ */
+/* Main entry                                                         */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Discover capabilities for a site. Tries /.well-known/wab.json first;
+ * falls back to HTML/sitemap/robots scraping.
+ *
+ * @param {string} siteUrl  e.g. "https://example.com"
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs=8000]
+ * @param {number} [opts.sitemapLimit=200]
+ * @param {boolean} [opts.skipWabJson=false]
+ * @returns {Promise<object>} normalized envelope
+ */
+async function discover(siteUrl, opts = {}) {
+  const timeoutMs = opts.timeoutMs || 8000;
+  const sitemapLimit = opts.sitemapLimit || 200;
+
+  let baseUrl;
+  try { baseUrl = new URL(siteUrl).origin; }
+  catch { return { ok: false, error: 'invalid_url', source: 'auto-discovery' }; }
+
+  // 1) Canonical wab.json — if present, use as authoritative source.
+  if (!opts.skipWabJson) {
+    const wabUrl = _abs(baseUrl, '/.well-known/wab.json');
+    const wabRes = await _fetchText(wabUrl, { timeoutMs });
+    if (wabRes.ok && wabRes.text) {
+      try {
+        const parsed = JSON.parse(wabRes.text);
+        return {
+          ok: true,
+          source: 'wab.json',
+          site: { name: parsed.site || parsed.name, description: parsed.description, url: baseUrl },
+          trust: { signed: !!parsed.sig, ...(parsed.trust || {}) },
+          actions: Array.isArray(parsed.actions) ? parsed.actions : [],
+          products: [],
+          sitemap: [],
+          robots: null,
+          raw: parsed
+        };
+      } catch { /* fall through to auto-discovery */ }
+    }
+  }
+
+  // 2) Fetch homepage HTML in parallel with sitemap + robots.
+  const [homeRes, sitemapRes, robotsRes] = await Promise.all([
+    _fetchText(baseUrl, { timeoutMs }),
+    _fetchText(_abs(baseUrl, '/sitemap.xml'), { timeoutMs }),
+    _fetchText(_abs(baseUrl, '/robots.txt'), { timeoutMs })
+  ]);
+
+  const html = homeRes.text || '';
+  const meta = extractMetaTags(html);
+  const ident = extractSiteIdentity(html);
+  const products = extractProductsFromHtml(html);
+  const robots = parseRobots(robotsRes.text || '');
+  let sitemap = parseSitemap(sitemapRes.text || '', { limit: sitemapLimit });
+
+  // Discover additional sitemaps from robots.
+  if (sitemap.length === 0 && robots.sitemaps.length) {
+    for (const sm of robots.sitemaps.slice(0, 3)) {
+      const r = await _fetchText(sm, { timeoutMs });
+      if (r.ok) sitemap = sitemap.concat(parseSitemap(r.text, { limit: sitemapLimit }));
+      if (sitemap.length >= sitemapLimit) break;
+    }
+  }
+
+  // Build action hints.
+  const actions = suggestWabActionsFromProducts(products);
+  if (ident.search && ident.search.target) {
+    actions.push({
+      name: 'searchSite',
+      description: 'Schema.org SearchAction: ' + ident.search.target,
+      source: 'schema.org/SearchAction',
+      template: ident.search.target
+    });
+  }
+  if (sitemap.length) {
+    actions.push({
+      name: 'browseSitemap',
+      description: `${sitemap.length} URLs discovered from sitemap.xml`,
+      source: 'sitemap.xml'
+    });
+  }
+  if (meta.og && meta.og.url) {
+    actions.push({
+      name: 'getOpenGraph',
+      description: 'OpenGraph metadata available',
+      source: 'opengraph'
+    });
+  }
+
+  return {
+    ok: true,
+    source: 'auto-discovery',
+    site: {
+      name: ident.name || meta.og.site_name || meta.title || baseUrl,
+      description: ident.description || meta.description || meta.og.description || null,
+      url: ident.url || meta.og.url || baseUrl
+    },
+    trust: { signed: false, auto: true },
+    actions,
+    products,
+    sitemap,
+    robots,
+    meta: { og: meta.og, twitter: meta.twitter, title: meta.title, description: meta.description },
+    organization: ident.organization || null
+  };
+}
+
+module.exports = {
+  discover,
+  extractMetaTags,
+  parseSitemap,
+  parseRobots,
+  extractSiteIdentity
+};

package/sdk/governance.js

@@ -0,0 +1,262 @@
+/**
+ * WAB Agent Governance — Client SDK
+ * ─────────────────────────────────
+ * The Layer-3 piece that sits ABOVE the WAB Protocol.
+ *
+ *   ┌─────────────────────────────────┐
+ *   │   WABGovernance  (this module)   │  ← permissions / approval / audit
+ *   ├─────────────────────────────────┤
+ *   │   WAB Protocol  (AICommands)     │
+ *   ├─────────────────────────────────┤
+ *   │   Dynamic Shield (price / OCR)   │
+ *   └─────────────────────────────────┘
+ *
+ * Five governance primitives every agent should call:
+ *
+ *   1) Permission Boundary   await gov.check({resource,action,scope,amount})
+ *   2) Human Approval Gate   await gov.requestApproval({...}) + waitForDecision()
+ *   3) Audit Log             await gov.audit({eventType,...})
+ *   4) Kill Switch           await gov.isAlive()  /  await gov.kill('reason')
+ *   5) Spend / Rate Limits   enforced server-side via policies
+ *
+ * Convenience: gov.guard(actionDesc, fn) wraps an action with all 5 at once.
+ *
+ * Usage:
+ *   const { WABGovernance } = require('web-agent-bridge/sdk');
+ *   const gov = new WABGovernance({
+ *     apiBase: 'https://webagentbridge.com',
+ *     agentId: process.env.AGENT_ID,
+ *     agentToken: process.env.AGENT_TOKEN,
+ *   });
+ *
+ *   await gov.guard(
+ *     { resource: 'stripe', action: 'write', scope: 'refunds', amount: 49.99, currency: 'USD' },
+ *     async () => stripe.refunds.create({ ... }),
+ *   );
+ */
+
+'use strict';
+
+const DEFAULT_API = 'https://webagentbridge.com';
+
+class WABGovernanceError extends Error {
+  constructor(message, decision) {
+    super(message);
+    this.name = 'WABGovernanceError';
+    this.decision = decision || null;
+  }
+}
+
+class WABGovernance {
+  /**
+   * @param {object} opts
+   * @param {string} opts.apiBase
+   * @param {string} opts.agentId
+   * @param {string} opts.agentToken
+   * @param {function} [opts.onApprovalRequired]  — async (request) => 'approved'|'rejected'
+   *        If provided, guard() will block until human decides; otherwise it
+   *        polls the approval endpoint up to opts.approvalTimeoutMs.
+   * @param {number} [opts.approvalTimeoutMs=300000]   — 5 min default
+   * @param {number} [opts.approvalPollMs=2000]
+   * @param {number} [opts.timeoutMs=10000]
+   * @param {function} [opts.fetch]
+   */
+  constructor(opts = {}) {
+    this.apiBase    = (opts.apiBase || DEFAULT_API).replace(/\/+$/, '');
+    this.agentId    = opts.agentId;
+    this.agentToken = opts.agentToken;
+    this.onApprovalRequired = typeof opts.onApprovalRequired === 'function' ? opts.onApprovalRequired : null;
+    this.approvalTimeoutMs  = Number.isFinite(opts.approvalTimeoutMs) ? opts.approvalTimeoutMs : 300_000;
+    this.approvalPollMs     = Number.isFinite(opts.approvalPollMs)    ? opts.approvalPollMs    : 2_000;
+    this.timeoutMs          = Number.isFinite(opts.timeoutMs)         ? opts.timeoutMs         : 10_000;
+    this._fetch = opts.fetch || (typeof fetch !== 'undefined' ? fetch : null);
+    if (!this._fetch) {
+      try { this._fetch = require('node-fetch'); } catch { /* user must supply */ }
+    }
+    if (!this.agentId)    throw new Error('WABGovernance: agentId required');
+    if (!this.agentToken) throw new Error('WABGovernance: agentToken required');
+  }
+
+  // ────────────────────────────────────── HTTP plumbing ────
+  async _req(method, path, body) {
+    if (!this._fetch) throw new Error('WABGovernance: fetch not available');
+    const ctl = (typeof AbortController !== 'undefined') ? new AbortController() : null;
+    const timer = ctl ? setTimeout(() => ctl.abort(), this.timeoutMs) : null;
+    try {
+      const r = await this._fetch(this.apiBase + path, {
+        method,
+        headers: {
+          'content-type': 'application/json',
+          'authorization': 'Bearer ' + this.agentToken,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: ctl ? ctl.signal : undefined,
+      });
+      const text = await r.text();
+      const data = text ? safeParse(text) : null;
+      if (!r.ok) {
+        const e = new Error(`gov_http_${r.status}: ${data?.error || r.statusText}`);
+        e.status = r.status; e.body = data;
+        throw e;
+      }
+      return data;
+    } finally { if (timer) clearTimeout(timer); }
+  }
+
+  // ────────────────────────────────────────── lifecycle ────
+  /** Static helper to register a brand-new agent and capture its token. */
+  static async register({ apiBase = DEFAULT_API, displayName, ownerId, metadata, fetch: f } = {}) {
+    const fn = f || (typeof fetch !== 'undefined' ? fetch : require('node-fetch'));
+    const r = await fn(apiBase.replace(/\/+$/, '') + '/api/governance/agents', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ display_name: displayName, owner_id: ownerId, metadata }),
+    });
+    if (!r.ok) throw new Error('register_failed_' + r.status);
+    return r.json();   // { agent_id, agent_token, message }
+  }
+
+  status()        { return this._req('GET',  `/api/governance/agents/${this.agentId}/status`); }
+  async isAlive() {
+    const s = await this.status().catch(() => null);
+    return !!s && s.status === 'alive';
+  }
+  kill(reason)    { return this._req('POST', `/api/governance/agents/${this.agentId}/kill`,   { reason }); }
+  revive(reason)  { return this._req('POST', `/api/governance/agents/${this.agentId}/revive`, { reason }); }
+
+  // ─────────────────────────────────────── policies ────
+  policies()             { return this._req('GET',  `/api/governance/agents/${this.agentId}/policies`); }
+  definePolicy(p)        { return this._req('POST', `/api/governance/agents/${this.agentId}/policies`, p); }
+  removePolicy(id)       { return this._req('DELETE', `/api/governance/agents/${this.agentId}/policies/${id}`); }
+
+  // ────────────────────────────────────── decision ────
+  /** Pre-action permission check. */
+  check({ resource, action, scope, amount, currency }) {
+    return this._req('POST', `/api/governance/agents/${this.agentId}/check`,
+      { resource, action, scope, amount, currency });
+  }
+
+  /** Report executed action — feeds audit + spend tracker. */
+  reportExecute(payload) {
+    return this._req('POST', `/api/governance/agents/${this.agentId}/execute`, payload);
+  }
+
+  // ────────────────────────────────────── audit ────
+  audit({ eventType = 'note', resource, action, scope, decision, reason, params, result } = {}) {
+    // Convenience wrapper around reportExecute() for non-execute events.
+    return this._req('POST', `/api/governance/agents/${this.agentId}/execute`, {
+      resource: resource || 'note', action: action || eventType, scope,
+      decision: decision || 'allow', reason, params, result,
+    });
+  }
+  getAudit(opts = {}) {
+    const q = new URLSearchParams();
+    if (opts.limit) q.set('limit', String(opts.limit));
+    if (opts.since) q.set('since', opts.since);
+    if (opts.event) q.set('event', opts.event);
+    const qs = q.toString();
+    return this._req('GET', `/api/governance/agents/${this.agentId}/audit${qs ? '?' + qs : ''}`);
+  }
+  verifyAudit() {
+    return this._req('GET', `/api/governance/agents/${this.agentId}/audit/verify`);
+  }
+
+  // ─────────────────────────────────── approvals ────
+  requestApproval(payload) {
+    return this._req('POST', `/api/governance/agents/${this.agentId}/approvals`, payload);
+  }
+  pendingApprovals() {
+    return this._req('GET', `/api/governance/agents/${this.agentId}/approvals/pending`);
+  }
+  getApproval(requestId) {
+    return this._req('GET', `/api/governance/approvals/${requestId}`);
+  }
+  decideApproval(requestId, decision, note) {
+    return this._req('POST', `/api/governance/approvals/${requestId}/decide`,
+      { decision, note });
+  }
+
+  /** Block until an approval is decided or times out. */
+  async waitForDecision(requestId, { timeoutMs, pollMs } = {}) {
+    const tEnd = Date.now() + (timeoutMs || this.approvalTimeoutMs);
+    const step = pollMs || this.approvalPollMs;
+    while (Date.now() < tEnd) {
+      const r = await this.getApproval(requestId).catch(() => null);
+      if (r && r.status !== 'pending') return r;
+      await sleep(step);
+    }
+    return { request_id: requestId, status: 'timeout' };
+  }
+
+  // ────────────────────────────────────── guard (the big one) ────
+  /**
+   * Wrap an action. Runs the full governance pipeline:
+   *   1) check permission
+   *   2) if approval_required → request + wait for human
+   *   3) execute the function
+   *   4) record execute (audit + spend)
+   *   5) on throw → audit deny + rethrow
+   */
+  async guard(actionDesc, fn) {
+    const { resource, action, scope, amount, currency } = actionDesc || {};
+    if (!resource || !action) throw new WABGovernanceError('guard: resource and action required');
+
+    // 1) Pre-check
+    const v = await this.check({ resource, action, scope, amount, currency });
+
+    // 2) Approval gate
+    if (v.decision === 'approval_required') {
+      const req = await this.requestApproval({
+        resource, action, scope, amount, currency,
+        params: actionDesc.params || null,
+        reason: actionDesc.reason || 'policy_required_approval',
+        ttl_ms: actionDesc.ttlMs || null,
+      });
+      let outcome;
+      if (this.onApprovalRequired) {
+        outcome = await this.onApprovalRequired({ request_id: req.requestId, ...actionDesc });
+        if (outcome === 'approved' || outcome === 'rejected') {
+          await this.decideApproval(req.requestId, outcome, 'callback_decision');
+        }
+      }
+      const decided = await this.waitForDecision(req.requestId);
+      if (decided.status !== 'approved') {
+        throw new WABGovernanceError(
+          `Approval ${decided.status} for ${resource}/${action}`,
+          { ...v, approval: decided },
+        );
+      }
+    } else if (v.decision !== 'allow') {
+      throw new WABGovernanceError(
+        `Governance denied ${resource}/${action}: ${v.reason}`, v,
+      );
+    }
+
+    // 3) Execute
+    let result, error;
+    const t0 = Date.now();
+    try { result = await fn(v); }
+    catch (e) { error = e; }
+    const elapsed = Date.now() - t0;
+
+    // 4) Audit (always, even on error)
+    try {
+      await this.reportExecute({
+        resource, action, scope, amount, currency,
+        decision: error ? 'deny' : 'allow',
+        reason:   error ? ('exec_error: ' + (error.message || 'unknown')) : 'guard_executed',
+        params:   actionDesc.params || null,
+        result:   error ? null : (typeof result === 'object' ? result : { value: result }),
+      });
+    } catch { /* audit best-effort; don't mask the original outcome */ }
+
+    if (error) throw error;
+    return { result, elapsed_ms: elapsed };
+  }
+}
+
+// ─────────────────────────────────────────── helpers ────
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+function safeParse(s) { try { return JSON.parse(s); } catch { return null; } }
+
+module.exports = { WABGovernance, WABGovernanceError };

package/sdk/index.js

@@ -624,6 +624,12 @@ try { WABToolkit = require('../packages/langchain').WABToolkit; } catch {
 
 // SPEC §8.10–§8.13 client helper
 const { SafetyShieldClient } = require('./safety-shield');
+// Phase 19 — Safe Mode trust gate
+const { WABSafeMode, WABSafeModeError, POLICIES: WAB_SAFE_POLICIES } = require('./safe-mode');
+// Phase 20 — Agent Governance Layer (permissions + approval + audit + kill-switch)
+const { WABGovernance, WABGovernanceError } = require('./governance');
+// Zero-Config Adoption — Auto-Discovery fallback for sites without /.well-known/wab.json
+const autoDiscovery = require('./auto-discovery');
 
 module.exports = {
   WABAgent,
@@ -633,4 +639,11 @@ module.exports = {
   WABAgentOS,
   WABToolkit,
   SafetyShieldClient,
+  WABSafeMode,
+  WABSafeModeError,
+  WAB_SAFE_POLICIES,
+  WABGovernance,
+  WABGovernanceError,
+  autoDiscovery,
+  discover: autoDiscovery.discover,
 };

package/sdk/package.json

@@ -1,7 +1,7 @@
 {
   "name": "web-agent-bridge-sdk",
-  "version": "3.1.0",
-  "description": "SDK for building AI agents that interact with Web Agent Bridge (WAB)",
+  "version": "3.2.0",
+  "description": "SDK for building AI agents that interact with Web Agent Bridge (WAB) — includes auto-discovery fallback, ShieldQR verifier, and governance layer.",
   "main": "index.js",
   "types": "index.d.ts",
   "license": "MIT",