web-agent-bridge 3.2.0 → 3.4.0

package/examples/governance-agent.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * WAB Governance Demo
+ * ───────────────────
+ * Walks through the full Layer-3 governance pipeline:
+ *
+ *   1) register agent → get one-time token
+ *   2) define permission boundaries (Stripe read-only + refund <$50 + ClickUp write)
+ *   3) try a forbidden action  → DENIED
+ *   4) try an allowed action   → ALLOWED + audited
+ *   5) try a high-value refund → APPROVAL_REQUIRED → human approves → executed
+ *   6) verify audit chain      → tamper-evident
+ *   7) kill switch             → all subsequent actions DENIED
+ *
+ * Run:
+ *   node examples/governance-agent.js
+ *   WAB_API=http://localhost:3000 node examples/governance-agent.js
+ */
+
+'use strict';
+
+const { WABGovernance } = require('../sdk');
+
+const API = process.env.WAB_API || 'http://localhost:3000';
+
+const c = {
+  reset: '\x1b[0m', dim: '\x1b[2m', bold: '\x1b[1m',
+  green: '\x1b[32m', red: '\x1b[31m', yellow: '\x1b[33m',
+  blue: '\x1b[34m', cyan: '\x1b[36m', magenta: '\x1b[35m',
+};
+const log  = (msg) => console.log(msg);
+const head = (n, msg) => log(`\n${c.bold}${c.cyan}── ${n}. ${msg} ──${c.reset}`);
+const ok   = (m) => log(`  ${c.green}✓${c.reset} ${m}`);
+const no   = (m) => log(`  ${c.red}✗${c.reset} ${m}`);
+const info = (m) => log(`  ${c.dim}${m}${c.reset}`);
+
+async function main() {
+  log(`${c.bold}${c.magenta}WAB Agent Governance Demo${c.reset}  ${c.dim}(API: ${API})${c.reset}`);
+
+  // ── 1) Register a fresh agent identity
+  head(1, 'Register agent');
+  const reg = await WABGovernance.register({
+    apiBase: API,
+    displayName: 'Demo Agent — Stripe + ClickUp',
+    metadata: { demo: true, created: Date.now() },
+  });
+  ok(`agent_id   = ${reg.agent_id}`);
+  ok(`agent_token (shown ONCE) = ${reg.agent_token.slice(0, 12)}…`);
+
+  const gov = new WABGovernance({
+    apiBase:    API,
+    agentId:    reg.agent_id,
+    agentToken: reg.agent_token,
+    // Auto-approve in this demo (a real app would post to Slack/email).
+    onApprovalRequired: async (req) => {
+      info(`[human approval] resource=${req.resource} action=${req.action} amount=${req.amount}`);
+      info('[human approval] auto-approving in demo (3s think...)');
+      await sleep(3000);
+      return 'approved';
+    },
+    approvalTimeoutMs: 30_000,
+  });
+
+  // ── 2) Define policies
+  head(2, 'Define permission boundaries');
+  await gov.definePolicy({ resource: 'stripe', action: 'read',  scope: 'customers' });
+  ok('stripe:read on customers');
+  await gov.definePolicy({
+    resource: 'stripe', action: 'write', scope: 'refunds',
+    max_amount: 50, currency: 'USD', daily_cap: 200,
+  });
+  ok('stripe:write on refunds  (max $50/call, $200/day)');
+  await gov.definePolicy({
+    resource: 'stripe', action: 'write', scope: 'refunds-large',
+    max_amount: 5000, currency: 'USD', requires_approval: true,
+  });
+  ok('stripe:write on refunds-large  (≤$5000, REQUIRES HUMAN APPROVAL)');
+  await gov.definePolicy({
+    resource: 'clickup', action: 'write', scope: 'tasks', per_call_rate: 30,
+  });
+  ok('clickup:write on tasks  (rate-limited 30/min)');
+
+  // ── 3) Forbidden action
+  head(3, 'Attempt forbidden action: gmail:write');
+  try {
+    await gov.guard({ resource: 'gmail', action: 'write', scope: 'inbox' },
+      async () => { throw new Error('should not run'); });
+    no('UNEXPECTED: action ran (governance failed)');
+  } catch (e) {
+    ok(`correctly blocked: ${e.message}`);
+  }
+
+  // ── 4) Allowed read
+  head(4, 'Allowed action: stripe:read on customers');
+  const r = await gov.guard(
+    { resource: 'stripe', action: 'read', scope: 'customers' },
+    async () => ({ count: 12, sample: [{ id: 'cus_abc', email: 'demo@x' }] }),
+  );
+  ok(`executed in ${r.elapsed_ms}ms — result keys: ${Object.keys(r.result).join(', ')}`);
+
+  // ── 5) Small refund: under cap, no approval
+  head(5, 'Small refund: $9.99 (under cap)');
+  const r2 = await gov.guard(
+    { resource: 'stripe', action: 'write', scope: 'refunds',
+      amount: 9.99, currency: 'USD',
+      params: { charge: 'ch_xyz', reason: 'duplicate' } },
+    async () => ({ refund_id: 're_demo_' + Date.now(), status: 'succeeded' }),
+  );
+  ok(`refund posted: ${r2.result.refund_id}`);
+
+  // ── 6) Refund OVER per-call cap → DENIED instantly
+  head(6, 'Refund $9999 with cap=$50 → DENY');
+  try {
+    await gov.guard(
+      { resource: 'stripe', action: 'write', scope: 'refunds',
+        amount: 9999, currency: 'USD' },
+      async () => 'should not run',
+    );
+    no('UNEXPECTED: action ran');
+  } catch (e) {
+    ok(`correctly blocked: ${e.message}`);
+  }
+
+  // ── 7) Large refund routed through approval gate
+  head(7, 'Large refund $499.99 → APPROVAL GATE');
+  const r3 = await gov.guard(
+    { resource: 'stripe', action: 'write', scope: 'refunds-large',
+      amount: 499.99, currency: 'USD',
+      params: { charge: 'ch_big', reason: 'fraud_dispute' },
+      reason: 'high_value_refund_requires_review' },
+    async () => ({ refund_id: 're_big_' + Date.now(), status: 'succeeded' }),
+  );
+  ok(`approved + executed: ${r3.result.refund_id}`);
+
+  // ── 8) Audit log + chain verification
+  head(8, 'Audit log + tamper check');
+  const audit = await gov.getAudit({ limit: 20 });
+  info(`last ${audit.audit.length} events:`);
+  for (const ev of audit.audit.slice(0, 8)) {
+    const tag = ev.decision === 'deny' ? c.red : ev.decision === 'pending' ? c.yellow : c.green;
+    log(`    ${tag}${(ev.decision || '·').padEnd(8)}${c.reset}` +
+        ` ${(ev.event_type || '').padEnd(18)} ${ev.resource || ''}/${ev.action || ''}` +
+        ` ${ev.scope ? '['+ev.scope+'] ' : ''}${ev.amount ? '$'+ev.amount : ''}`);
+  }
+  const v = await gov.verifyAudit();
+  if (v.ok) ok(`chain verified: ${v.count} entries, head=${(v.head || '').slice(0, 12)}…`);
+  else      no(`chain BROKEN at id=${v.broken_at}`);
+
+  // ── 9) Kill switch
+  head(9, 'Kill switch');
+  await gov.kill('demo_complete');
+  ok('agent killed');
+  try {
+    await gov.guard({ resource: 'stripe', action: 'read', scope: 'customers' },
+      async () => 'should not run');
+    no('UNEXPECTED: action ran after kill');
+  } catch (e) {
+    ok(`post-kill action blocked: ${e.message}`);
+  }
+
+  log(`\n${c.bold}${c.green}✓ Demo complete${c.reset}\n`);
+}
+
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+main().catch((e) => {
+  console.error(`\n${c.red}Demo failed:${c.reset}`, e.message);
+  process.exit(1);
+});

package/examples/mcp-agent.js

@@ -1,94 +1,94 @@
-/**
- * Example: Using WAB sites via the MCP adapter
- *
- * The WAB-MCP adapter exposes every WAB site action as an MCP tool,
- * so any MCP-compatible AI agent (Claude, GPT, etc.) can interact
- * with WAB-enabled websites through a uniform tool interface.
- *
- * Usage:
- *   node examples/mcp-agent.js <site-url>
- */
-
-const { WABMCPAdapter } = require('../wab-mcp-adapter');
-
-const TARGET = process.argv[2] || 'http://localhost:3000';
-
-async function main() {
-  console.log('\n  WAB → MCP Adapter Demo');
-  console.log(`  Target: ${TARGET}\n`);
-
-  const adapter = new WABMCPAdapter({
-    siteUrl: TARGET,
-    transport: 'http'
-  });
-
-  // Step 1: Discover site capabilities
-  console.log('1. Discovering WAB capabilities...');
-  const discovery = await adapter.discover();
-  if (discovery) {
-    console.log(`   Provider: ${discovery.provider?.name || 'unknown'}`);
-    console.log(`   Domain:   ${discovery.provider?.domain || 'unknown'}`);
-    console.log(`   Tier:     ${discovery.capabilities?.tier || 'free'}`);
-    console.log(`   Features: ${(discovery.capabilities?.features || []).join(', ')}`);
-    if (discovery.fairness) {
-      console.log(`   Fairness: score=${discovery.fairness.neutrality_score}, independent=${discovery.fairness.is_independent}`);
-    }
-  } else {
-    console.log('   No discovery document found (site may not have WAB configured)');
-  }
-
-  // Step 2: List MCP tools
-  console.log('\n2. Available MCP tools:');
-  const tools = await adapter.getTools();
-  tools.forEach(tool => {
-    const params = tool.input_schema?.properties
-      ? Object.keys(tool.input_schema.properties).join(', ')
-      : 'none';
-    console.log(`   - ${tool.name}: ${tool.description} (params: ${params})`);
-  });
-
-  // Step 3: Execute built-in tools
-  console.log('\n3. Executing wab_get_page_info...');
-  try {
-    const infoResult = await adapter.executeTool('wab_get_page_info', {});
-    const info = infoResult.content;
-    if (infoResult.is_error) {
-      console.log(`   Error: ${info.error}`);
-    } else {
-      console.log(`   Title:   ${info.title || 'N/A'}`);
-      console.log(`   Version: ${info.bridgeVersion || 'N/A'}`);
-      console.log(`   Domain:  ${info.domain || 'N/A'}`);
-    }
-  } catch (err) {
-    console.log(`   Error: ${err.message}`);
-  }
-
-  // Step 4: Search the fairness registry
-  console.log('\n4. Fairness-weighted search (demo):');
-  try {
-    const searchResult = await adapter.executeTool('wab_fairness_search', {
-      query: 'e-commerce',
-      limit: 5
-    });
-    const search = searchResult.content;
-    if (searchResult.is_error) {
-      console.log(`   Error: ${search.error}`);
-    } else if (search.results?.length) {
-      search.results.forEach(r => {
-        console.log(`   - ${r.name} (${r.domain}) — score: ${r.final_score}`);
-      });
-    } else {
-      console.log('   No sites registered in directory yet.');
-    }
-  } catch (err) {
-    console.log(`   Registry not available: ${err.message}`);
-  }
-
-  console.log('\nDone. In a real MCP integration, these tools would be');
-  console.log('exposed to Claude/GPT via the MCP tool-use protocol.\n');
-}
-
-main().catch(err => {
-  console.error('Error:', err.message);
-  process.exit(1);
-});
+/**
+ * Example: Using WAB sites via the MCP adapter
+ *
+ * The WAB-MCP adapter exposes every WAB site action as an MCP tool,
+ * so any MCP-compatible AI agent (Claude, GPT, etc.) can interact
+ * with WAB-enabled websites through a uniform tool interface.
+ *
+ * Usage:
+ *   node examples/mcp-agent.js <site-url>
+ */
+
+const { WABMCPAdapter } = require('../wab-mcp-adapter');
+
+const TARGET = process.argv[2] || 'http://localhost:3000';
+
+async function main() {
+  console.log('\n  WAB → MCP Adapter Demo');
+  console.log(`  Target: ${TARGET}\n`);
+
+  const adapter = new WABMCPAdapter({
+    siteUrl: TARGET,
+    transport: 'http'
+  });
+
+  // Step 1: Discover site capabilities
+  console.log('1. Discovering WAB capabilities...');
+  const discovery = await adapter.discover();
+  if (discovery) {
+    console.log(`   Provider: ${discovery.provider?.name || 'unknown'}`);
+    console.log(`   Domain:   ${discovery.provider?.domain || 'unknown'}`);
+    console.log(`   Tier:     ${discovery.capabilities?.tier || 'free'}`);
+    console.log(`   Features: ${(discovery.capabilities?.features || []).join(', ')}`);
+    if (discovery.fairness) {
+      console.log(`   Fairness: score=${discovery.fairness.neutrality_score}, independent=${discovery.fairness.is_independent}`);
+    }
+  } else {
+    console.log('   No discovery document found (site may not have WAB configured)');
+  }
+
+  // Step 2: List MCP tools
+  console.log('\n2. Available MCP tools:');
+  const tools = await adapter.getTools();
+  tools.forEach(tool => {
+    const params = tool.input_schema?.properties
+      ? Object.keys(tool.input_schema.properties).join(', ')
+      : 'none';
+    console.log(`   - ${tool.name}: ${tool.description} (params: ${params})`);
+  });
+
+  // Step 3: Execute built-in tools
+  console.log('\n3. Executing wab_get_page_info...');
+  try {
+    const infoResult = await adapter.executeTool('wab_get_page_info', {});
+    const info = infoResult.content;
+    if (infoResult.is_error) {
+      console.log(`   Error: ${info.error}`);
+    } else {
+      console.log(`   Title:   ${info.title || 'N/A'}`);
+      console.log(`   Version: ${info.bridgeVersion || 'N/A'}`);
+      console.log(`   Domain:  ${info.domain || 'N/A'}`);
+    }
+  } catch (err) {
+    console.log(`   Error: ${err.message}`);
+  }
+
+  // Step 4: Search the fairness registry
+  console.log('\n4. Fairness-weighted search (demo):');
+  try {
+    const searchResult = await adapter.executeTool('wab_fairness_search', {
+      query: 'e-commerce',
+      limit: 5
+    });
+    const search = searchResult.content;
+    if (searchResult.is_error) {
+      console.log(`   Error: ${search.error}`);
+    } else if (search.results?.length) {
+      search.results.forEach(r => {
+        console.log(`   - ${r.name} (${r.domain}) — score: ${r.final_score}`);
+      });
+    } else {
+      console.log('   No sites registered in directory yet.');
+    }
+  } catch (err) {
+    console.log(`   Registry not available: ${err.message}`);
+  }
+
+  console.log('\nDone. In a real MCP integration, these tools would be');
+  console.log('exposed to Claude/GPT via the MCP tool-use protocol.\n');
+}
+
+main().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/examples/next-app-router/README.md

@@ -1,44 +1,44 @@
-# Next.js App Router + WAB
-
-1. Install the React helpers (from repo root after publish, or `file:` link):
-
-```bash
-npm install @web-agent-bridge/react
-```
-
-2. Add a client component `components/WabShop.tsx`:
-
-```tsx
-'use client';
-
-import { WABProvider, useWAB } from '@web-agent-bridge/react';
-import { useEffect } from 'react';
-
-function WabInner() {
-  const { ready, discover, execute } = useWAB({
-    name: 'My App',
-    actions: {
-      ping: { description: 'Health check', run: () => ({ ok: true }) },
-    },
-  });
-
-  useEffect(() => {
-    if (!ready) return;
-    discover().then(console.log);
-  }, [ready, discover]);
-
-  return <p>WAB {ready ? 'ready' : 'loading…'}</p>;
-}
-
-export default function WabShop() {
-  return (
-    <WABProvider scriptSrc="https://webagentbridge.com/script/wab.min.js">
-      <WabInner />
-    </WABProvider>
-  );
-}
-```
-
-3. Import `WabShop` from any `app/.../page.tsx` (server component can import client components).
-
-Use `next/script` with `strategy="beforeInteractive"` if you prefer loading `wab.min.js` in `layout.tsx` instead of `WABProvider`.
+# Next.js App Router + WAB
+
+1. Install the React helpers (from repo root after publish, or `file:` link):
+
+```bash
+npm install @web-agent-bridge/react
+```
+
+2. Add a client component `components/WabShop.tsx`:
+
+```tsx
+'use client';
+
+import { WABProvider, useWAB } from '@web-agent-bridge/react';
+import { useEffect } from 'react';
+
+function WabInner() {
+  const { ready, discover, execute } = useWAB({
+    name: 'My App',
+    actions: {
+      ping: { description: 'Health check', run: () => ({ ok: true }) },
+    },
+  });
+
+  useEffect(() => {
+    if (!ready) return;
+    discover().then(console.log);
+  }, [ready, discover]);
+
+  return <p>WAB {ready ? 'ready' : 'loading…'}</p>;
+}
+
+export default function WabShop() {
+  return (
+    <WABProvider scriptSrc="https://webagentbridge.com/script/wab.min.js">
+      <WabInner />
+    </WABProvider>
+  );
+}
+```
+
+3. Import `WabShop` from any `app/.../page.tsx` (server component can import client components).
+
+Use `next/script` with `strategy="beforeInteractive"` if you prefer loading `wab.min.js` in `layout.tsx` instead of `WABProvider`.

package/examples/plesk-wab-dns.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * plesk-wab-dns.js — enable/disable WAB DNS Discovery TXT record via Plesk REST API.
+ *
+ * Usage:
+ *   PLESK_API_KEY=… node plesk-wab-dns.js enable  example.com plesk.host.com
+ *   PLESK_API_KEY=… node plesk-wab-dns.js disable example.com plesk.host.com
+ *   node plesk-wab-dns.js status example.com
+ *
+ * Optional env vars:
+ *   PLESK_PORT=8443
+ *   PLESK_USER + PLESK_PASS (basic auth instead of API key)
+ *   WAB_BASE_URL (default: https://www.webagentbridge.com)
+ *   NODE_TLS_REJECT_UNAUTHORIZED=0 (for self-signed cert)
+ */
+
+'use strict';
+
+const fetch = (() => { try { return require('node-fetch'); } catch { return globalThis.fetch; } })();
+
+const [,, action, domain, host] = process.argv;
+const PORT     = process.env.PLESK_PORT    || '8443';
+const APIKEY   = process.env.PLESK_API_KEY;
+const USER     = process.env.PLESK_USER;
+const PASS     = process.env.PLESK_PASS;
+const WAB_BASE = process.env.WAB_BASE_URL  || 'https://www.webagentbridge.com';
+const ENDPOINT = process.env.WAB_ENDPOINT  || `https://${domain}/.well-known/wab.json`;
+
+if (!action || !domain) { console.error('Usage: node plesk-wab-dns.js <enable|disable|status> <domain> [plesk-host]'); process.exit(1); }
+if (!['enable','disable','status'].includes(action)) { console.error('Action must be: enable | disable | status'); process.exit(1); }
+if (action !== 'status' && !host) { console.error('plesk-host required for enable/disable'); process.exit(1); }
+if (action !== 'status' && !APIKEY && !(USER && PASS)) { console.error('Set PLESK_API_KEY or PLESK_USER + PLESK_PASS'); process.exit(1); }
+
+function headers() {
+  const h = { 'Content-Type': 'application/json' };
+  if (APIKEY) h['X-API-Key'] = APIKEY;
+  else h['Authorization'] = 'Basic ' + Buffer.from(`${USER}:${PASS}`).toString('base64');
+  return h;
+}
+
+const base = () => `https://${host}:${PORT}/api/v2`;
+
+async function pkReq(method, path, body) {
+  const opts = { method, headers: headers() };
+  if (body) opts.body = JSON.stringify(body);
+  const r = await fetch(`${base()}${path}`, opts);
+  const t = await r.text();
+  if (!r.ok) throw new Error(`Plesk ${r.status}: ${t.slice(0, 300)}`);
+  try { return JSON.parse(t); } catch { return t; }
+}
+
+async function getRecordTemplate() {
+  const j = await (await fetch(`${WAB_BASE}/api/discovery/provider/record-template?domain=${encodeURIComponent(domain)}&endpoint=${encodeURIComponent(ENDPOINT)}`)).json();
+  if (!j.record || !j.record.value) throw new Error('Could not fetch WAB record template');
+  return j.record.value;
+}
+
+async function listWab() {
+  const all = await pkReq('GET', `/dns/records?domain=${encodeURIComponent(domain)}&type=TXT`);
+  return (all || []).filter(r => {
+    const h = (r.host || '').replace(/\.$/, '');
+    return h === `_wab.${domain}` || h === '_wab';
+  });
+}
+
+async function main() {
+  console.log(`[WAB] Action: ${action} | Domain: ${domain}`);
+
+  if (action === 'status') {
+    const j = await (await fetch(`${WAB_BASE}/api/discovery/provider/status?domain=${encodeURIComponent(domain)}`)).json();
+    console.log(`[WAB] Status: ${j.status}`);
+    console.log(JSON.stringify(j, null, 2));
+    return;
+  }
+
+  if (action === 'enable') {
+    const txtVal = await getRecordTemplate();
+    console.log(`[WAB] TXT value: ${txtVal}`);
+    const existing = await listWab();
+    for (const rec of existing) {
+      console.log(`[Plesk] Deleting old record id=${rec.id}`);
+      await pkReq('DELETE', `/dns/records/${rec.id}`);
+    }
+    const out = await pkReq('POST', '/dns/records', {
+      domain, type: 'TXT', host: `_wab.${domain}`, value: txtVal,
+    });
+    console.log('[Plesk] Created TXT record');
+    console.log(JSON.stringify(out, null, 2));
+    console.log('[WAB] WAB Discovery ENABLED.');
+  }
+
+  if (action === 'disable') {
+    const existing = await listWab();
+    if (!existing.length) { console.log('[Plesk] No _wab record found — already disabled.'); return; }
+    for (const rec of existing) {
+      console.log(`[Plesk] Deleting record id=${rec.id}`);
+      await pkReq('DELETE', `/dns/records/${rec.id}`);
+    }
+    console.log('[WAB] WAB Discovery DISABLED.');
+  }
+}
+
+main().catch(err => { console.error('[ERROR]', err.message); process.exit(1); });