web-agent-bridge 3.8.1 → 3.9.1

package/sdk/index.js

@@ -630,6 +630,8 @@ const { WABSafeMode, WABSafeModeError, POLICIES: WAB_SAFE_POLICIES } = require('
 const { WABGovernance, WABGovernanceError } = require('./governance');
 // Zero-Config Adoption — Auto-Discovery fallback for sites without /.well-known/wab.json
 const autoDiscovery = require('./auto-discovery');
+// Agent Transaction Primitive (v3.9.0) — intent → authorization → execution → receipt.
+const { ATPClient, ATPError } = require('./atp');
 
 module.exports = {
   WABAgent,
@@ -646,4 +648,6 @@ module.exports = {
   WABGovernanceError,
   autoDiscovery,
   discover: autoDiscovery.discover,
+  ATPClient,
+  ATPError,
 };

package/server/index.js

@@ -305,6 +305,9 @@ const { wabTrustMiddleware } = require('./middleware/wab-trust');
 app.use(wabTrustMiddleware);
 app.use('/api/ring4', apiLimiter, ring4Router);
 
+// ── Agent Transaction Primitive (ATP) v3.9.0 — intents · transactions · signed receipts ──
+app.use('/api/atp', apiLimiter, require('./routes/transactions'));
+
 // ── WAB Commercial Foundations v3.8.0 (Partners · Trust Graph API · Governance SaaS · Enterprise Mesh) ──
 app.use('/api/partners',         apiLimiter, require('./routes/partners'));
 app.use('/api/keys',             apiLimiter, require('./routes/api-keys'));

package/server/migrations/020_agent_transaction_primitive.sql

@@ -0,0 +1,119 @@
+-- ─────────────────────────────────────────────────────────────────────────────
+-- Migration 020 — Agent Transaction Primitive (ATP) — v3.9.0
+--
+-- Promotes WAB from "discover + execute" to "trust + transaction" by
+-- introducing intents, transactions, steps and signed receipts as
+-- first-class primitives.
+--
+--   * atp_intents       — signed human → agent authorization contracts
+--   * atp_transactions  — executions performed under an intent
+--   * atp_steps         — per-step ledger inside a transaction (retry/comp)
+--   * atp_receipts      — cryptographically signed proofs of outcome
+--   * atp_nonces        — single-use nonces to prevent replay
+--
+-- All state machines enforced by CHECK constraints so the DB itself
+-- refuses illegal transitions.
+-- ─────────────────────────────────────────────────────────────────────────────
+
+-- ── 1) Intents (the human → agent contract) ──────────────────────────────────
+CREATE TABLE IF NOT EXISTS atp_intents (
+  id              TEXT PRIMARY KEY,                     -- atp_int_<ulid>
+  user_id         TEXT NOT NULL,                        -- principal (the human)
+  site_id         TEXT,                                 -- optional binding
+  agent_id        TEXT,                                 -- optional binding (the delegate)
+  purpose         TEXT NOT NULL,                        -- short human-readable purpose
+  scope           TEXT NOT NULL,                        -- JSON: { actions:[], domains:[], constraints:{} }
+  spend_cap_cents INTEGER NOT NULL DEFAULT 0,           -- 0 = no cap (must be explicit)
+  spend_currency  TEXT NOT NULL DEFAULT 'EUR',
+  spent_cents     INTEGER NOT NULL DEFAULT 0,           -- running total against the cap
+  max_executions  INTEGER NOT NULL DEFAULT 1,           -- how many transactions allowed
+  used_executions INTEGER NOT NULL DEFAULT 0,
+  expires_at      TEXT NOT NULL,                        -- ISO-8601, hard cutoff
+  nonce           TEXT NOT NULL UNIQUE,                 -- prevents replay across intents
+  status          TEXT NOT NULL DEFAULT 'draft'
+                  CHECK (status IN ('draft','authorized','consumed','revoked','expired')),
+  authorized_at   TEXT,
+  authorized_by   TEXT,                                 -- user_id of the approver
+  user_signature  TEXT,                                 -- base64 Ed25519 sig of canonical body
+  revoked_at      TEXT,
+  revoked_reason  TEXT,
+  metadata        TEXT NOT NULL DEFAULT '{}',           -- JSON
+  created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at      TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_atp_intents_user   ON atp_intents(user_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_atp_intents_status ON atp_intents(status, expires_at);
+CREATE INDEX IF NOT EXISTS idx_atp_intents_site   ON atp_intents(site_id);
+
+-- ── 2) Transactions (executions under an intent) ─────────────────────────────
+CREATE TABLE IF NOT EXISTS atp_transactions (
+  id               TEXT PRIMARY KEY,                    -- atp_tx_<ulid>
+  intent_id        TEXT NOT NULL,
+  site_id          TEXT,
+  agent_id         TEXT,
+  idempotency_key  TEXT NOT NULL,                       -- caller-supplied, unique per intent
+  status           TEXT NOT NULL DEFAULT 'pending'
+                   CHECK (status IN ('pending','executing','executed','settled','failed','compensated')),
+  amount_cents     INTEGER NOT NULL DEFAULT 0,          -- net effect against intent.spend_cap
+  currency         TEXT NOT NULL DEFAULT 'EUR',
+  summary          TEXT,                                -- one-line outcome summary
+  error            TEXT,                                -- failure reason if status='failed'
+  started_at       TEXT,
+  completed_at     TEXT,
+  settled_at       TEXT,
+  compensated_at   TEXT,
+  metadata         TEXT NOT NULL DEFAULT '{}',
+  created_at       TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at       TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (intent_id) REFERENCES atp_intents(id) ON DELETE CASCADE,
+  UNIQUE (intent_id, idempotency_key)                   -- the core safety guarantee
+);
+CREATE INDEX IF NOT EXISTS idx_atp_tx_intent ON atp_transactions(intent_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_atp_tx_status ON atp_transactions(status, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_atp_tx_site   ON atp_transactions(site_id, created_at DESC);
+
+-- ── 3) Steps (granular ledger for retry / compensation) ──────────────────────
+CREATE TABLE IF NOT EXISTS atp_steps (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  transaction_id  TEXT NOT NULL,
+  seq             INTEGER NOT NULL,                     -- step order, 1..N
+  action          TEXT NOT NULL,                        -- WAB action name (e.g. "checkout.confirm")
+  state           TEXT NOT NULL DEFAULT 'pending'
+                  CHECK (state IN ('pending','running','succeeded','failed','skipped','compensated')),
+  before_snapshot TEXT,                                 -- JSON: site state before step (optional)
+  after_snapshot  TEXT,                                 -- JSON: site state after step
+  evidence        TEXT,                                 -- JSON: arbitrary proof (DOM hash, http trace, …)
+  compensation    TEXT,                                 -- JSON: rollback action descriptor
+  attempts        INTEGER NOT NULL DEFAULT 0,
+  last_error      TEXT,
+  started_at      TEXT,
+  ended_at        TEXT,
+  created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (transaction_id) REFERENCES atp_transactions(id) ON DELETE CASCADE,
+  UNIQUE (transaction_id, seq)
+);
+CREATE INDEX IF NOT EXISTS idx_atp_steps_tx ON atp_steps(transaction_id, seq);
+
+-- ── 4) Receipts (signed proofs of outcome) ───────────────────────────────────
+CREATE TABLE IF NOT EXISTS atp_receipts (
+  id              TEXT PRIMARY KEY,                     -- atp_rcpt_<ulid>
+  transaction_id  TEXT NOT NULL UNIQUE,
+  site_id         TEXT,                                 -- the signing party (if any)
+  algorithm       TEXT NOT NULL DEFAULT 'ed25519',
+  key_id          TEXT,                                 -- fingerprint of signing key
+  canonical_body  TEXT NOT NULL,                        -- the canonicalized JSON that was signed
+  signature       TEXT NOT NULL,                        -- base64 Ed25519 signature
+  public_key      TEXT,                                 -- embedded pub key for offline verification
+  issued_at       TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (transaction_id) REFERENCES atp_transactions(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_atp_receipts_site ON atp_receipts(site_id, issued_at DESC);
+
+-- ── 5) Nonces (single-use, replay protection) ────────────────────────────────
+CREATE TABLE IF NOT EXISTS atp_nonces (
+  nonce       TEXT PRIMARY KEY,
+  user_id     TEXT NOT NULL,
+  consumed_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_atp_nonces_user ON atp_nonces(user_id, consumed_at DESC);

package/server/routes/transactions.js

@@ -0,0 +1,248 @@
+'use strict';
+
+/**
+ * /api/atp — Agent Transaction Primitive REST surface.
+ *
+ * Authenticated endpoints (Bearer JWT, /me-scoped):
+ *   POST   /intents                      create draft intent
+ *   GET    /intents                      list my intents
+ *   GET    /intents/:id                  fetch one
+ *   POST   /intents/:id/authorize        approve (single-use nonce burned)
+ *   POST   /intents/:id/revoke           revoke
+ *   POST   /transactions                 begin tx under an authorized intent
+ *   GET    /transactions/:id             fetch tx + steps
+ *   POST   /transactions/:id/steps       append step
+ *   POST   /transactions/:id/transition  move state machine
+ *   POST   /transactions/:id/compensate  rollback
+ *   POST   /transactions/:id/receipt     issue signed receipt
+ *
+ * Public endpoints (no auth — these ARE the trust primitive):
+ *   GET    /receipts/:id                 fetch a receipt (id only, no contents leak)
+ *   POST   /receipts/verify              verify any signed receipt JSON offline-style
+ */
+
+const express = require('express');
+const router  = express.Router();
+
+const { authenticateToken } = require('../middleware/auth');
+const transactions = require('../services/transactions');
+const { db } = require('../models/db');
+
+// ─── Tier gating ─────────────────────────────────────────────────────────────
+// ATP is positioned at the open/paid boundary: intent creation and public
+// verification are open (the protocol must spread), while throughput and
+// advanced features are paid.
+const ATP_INTENT_LIMITS = { free: 10, starter: 50, pro: 500, business: 5000, enterprise: 100000 };
+
+function getUserTier(userId) {
+  try {
+    const row = db.prepare(`SELECT tier FROM sites WHERE user_id=? AND active=1 ORDER BY created_at ASC LIMIT 1`).get(userId);
+    return (row && row.tier) || 'free';
+  } catch { return 'free'; }
+}
+
+function checkDailyIntentQuota(userId) {
+  const tier = getUserTier(userId);
+  const cap = ATP_INTENT_LIMITS[tier] ?? ATP_INTENT_LIMITS.free;
+  const row = db.prepare(`
+    SELECT COUNT(*) AS n FROM atp_intents
+     WHERE user_id=? AND datetime(created_at) >= datetime('now','-1 day')
+  `).get(userId);
+  return { tier, used: row.n, cap, ok: row.n < cap };
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function send(res, fn) {
+  try {
+    const out = fn();
+    res.json({ ok: true, ...(out && typeof out === 'object' ? { data: out } : {}) });
+  } catch (e) {
+    const code = e.statusCode || 500;
+    res.status(code).json({ ok: false, error: e.code || 'internal_error', message: e.message });
+  }
+}
+
+// ─── Intents ─────────────────────────────────────────────────────────────────
+router.post('/intents', authenticateToken, express.json({ limit: '32kb' }), (req, res) => {
+  const q = checkDailyIntentQuota(req.user.id);
+  if (!q.ok) {
+    return res.status(429).json({
+      ok: false, error: 'quota_exceeded',
+      message: `Daily intent quota reached (${q.used}/${q.cap} on '${q.tier}' tier).`,
+      tier: q.tier, used: q.used, limit: q.cap,
+      upgrade_url: '/premium.html',
+    });
+  }
+  send(res, () => transactions.createIntent({
+    userId: req.user.id,
+    siteId: req.body.site_id || null,
+    agentId: req.body.agent_id || null,
+    purpose: req.body.purpose,
+    scope: req.body.scope,
+    spendCapCents: req.body.spend_cap_cents ?? 0,
+    spendCurrency: req.body.currency || 'EUR',
+    maxExecutions: req.body.max_executions ?? 1,
+    ttlSeconds: req.body.ttl_seconds ?? 3600,
+    metadata: req.body.metadata || {},
+  }));
+});
+
+router.get('/intents', authenticateToken, (req, res) => {
+  send(res, () => transactions.listIntentsForUser(req.user.id, {
+    limit: Math.min(parseInt(req.query.limit, 10) || 50, 200),
+    offset: parseInt(req.query.offset, 10) || 0,
+  }));
+});
+
+router.get('/intents/:id', authenticateToken, (req, res) => {
+  const intent = transactions.getIntent(req.params.id);
+  if (!intent) return res.status(404).json({ ok: false, error: 'not_found' });
+  if (intent.user_id !== req.user.id) return res.status(403).json({ ok: false, error: 'forbidden' });
+  res.json({ ok: true, data: intent });
+});
+
+router.post('/intents/:id/authorize', authenticateToken, (req, res) => {
+  send(res, () => transactions.authorizeIntent(req.params.id, { userId: req.user.id }));
+});
+
+router.post('/intents/:id/revoke', authenticateToken, express.json({ limit: '4kb' }), (req, res) => {
+  send(res, () => transactions.revokeIntent(req.params.id, { userId: req.user.id, reason: req.body.reason }));
+});
+
+// ─── Transactions ────────────────────────────────────────────────────────────
+function loadIntentAuthorized(intentId, userId) {
+  const intent = transactions.getIntent(intentId);
+  if (!intent) { const e = new Error('intent not found'); e.statusCode = 404; e.code = 'not_found'; throw e; }
+  if (intent.user_id !== userId) { const e = new Error('forbidden'); e.statusCode = 403; e.code = 'forbidden'; throw e; }
+  return intent;
+}
+
+function loadTxOwned(txId, userId) {
+  const tx = transactions.getTransaction(txId);
+  if (!tx) { const e = new Error('transaction not found'); e.statusCode = 404; e.code = 'not_found'; throw e; }
+  const intent = transactions.getIntent(tx.intent_id);
+  if (!intent || intent.user_id !== userId) { const e = new Error('forbidden'); e.statusCode = 403; e.code = 'forbidden'; throw e; }
+  return { tx, intent };
+}
+
+router.post('/transactions', authenticateToken, express.json({ limit: '32kb' }), (req, res) => {
+  send(res, () => {
+    const intent = loadIntentAuthorized(req.body.intent_id, req.user.id);
+    const idem = req.headers['idempotency-key'] || req.body.idempotency_key;
+    return transactions.beginTransaction({
+      intentId: intent.id,
+      idempotencyKey: idem,
+      siteId: req.body.site_id,
+      agentId: req.body.agent_id,
+      amountCents: req.body.amount_cents ?? 0,
+      currency: req.body.currency || intent.spend_currency,
+      summary: req.body.summary,
+      metadata: req.body.metadata || {},
+    });
+  });
+});
+
+router.get('/transactions/:id', authenticateToken, (req, res) => {
+  send(res, () => {
+    const { tx } = loadTxOwned(req.params.id, req.user.id);
+    return { ...tx, steps: transactions.listSteps(tx.id) };
+  });
+});
+
+router.post('/transactions/:id/steps', authenticateToken, express.json({ limit: '256kb' }), (req, res) => {
+  send(res, () => {
+    loadTxOwned(req.params.id, req.user.id);
+    return transactions.appendStep(req.params.id, {
+      action: req.body.action,
+      evidence: req.body.evidence,
+      before: req.body.before,
+      after: req.body.after,
+      compensation: req.body.compensation,
+    });
+  });
+});
+
+const VALID_TARGETS = new Set(['executing','executed','settled','failed','compensated']);
+router.post('/transactions/:id/transition', authenticateToken, express.json({ limit: '8kb' }), (req, res) => {
+  send(res, () => {
+    loadTxOwned(req.params.id, req.user.id);
+    const to = req.body.to;
+    if (!VALID_TARGETS.has(to)) {
+      const e = new Error(`invalid target state '${to}'`); e.statusCode = 400; e.code = 'invalid_request'; throw e;
+    }
+    return transactions.transitionTransaction(req.params.id, to, { error: req.body.error, summary: req.body.summary });
+  });
+});
+
+router.post('/transactions/:id/compensate', authenticateToken, express.json({ limit: '4kb' }), (req, res) => {
+  send(res, () => {
+    loadTxOwned(req.params.id, req.user.id);
+    return transactions.compensateTransaction(req.params.id, { reason: req.body.reason });
+  });
+});
+
+// Receipts — issuance requires Pro+ for persistent key binding;
+// free tier gets ephemeral-key receipts (still verifiable, just not pinned).
+router.post('/transactions/:id/receipt', authenticateToken, express.json({ limit: '4kb' }), (req, res) => {
+  send(res, () => {
+    const { tx } = loadTxOwned(req.params.id, req.user.id);
+    return transactions.issueReceipt(tx.id, { embedPublicKey: true });
+  });
+});
+
+// ─── Public verification (the trust primitive) ───────────────────────────────
+const publicReceiptLimiter = (() => {
+  const buckets = new Map();
+  const WINDOW_MS = 60_000;
+  const MAX = 120;
+  return (req, res, next) => {
+    const key = req.ip;
+    const now = Date.now();
+    let b = buckets.get(key);
+    if (!b || (now - b.t) > WINDOW_MS) { b = { t: now, n: 0 }; buckets.set(key, b); }
+    b.n++;
+    if (b.n > MAX) return res.status(429).json({ ok: false, error: 'rate_limited' });
+    next();
+  };
+})();
+
+router.get('/receipts/:id', publicReceiptLimiter, (req, res) => {
+  const r = transactions.getReceipt(req.params.id);
+  if (!r) return res.status(404).json({ ok: false, error: 'not_found' });
+  res.json({ ok: true, data: { id: r.id, transaction_id: r.transaction_id, issued_at: r.issued_at, body: r.body } });
+});
+
+router.post('/receipts/verify', publicReceiptLimiter, express.json({ limit: '256kb' }), (req, res) => {
+  const input = req.body && (req.body.receipt || req.body);
+  let target = input;
+  // Allow lookup by id: { receipt_id: "..." } or { id: "..." } with no signature attached
+  const lookupId = typeof input === 'object' && input
+    ? (input.receipt_id || input.id)
+    : (typeof input === 'string' ? input : null);
+  if (lookupId && (typeof input !== 'object' || !input.signature)) {
+    const stored = transactions.getReceipt(lookupId);
+    if (!stored) return res.status(404).json({ ok: false, error: 'not_found' });
+    target = stored.body;
+  }
+  const r = transactions.verifyReceipt(target);
+  res.json({ ok: r.ok === true, verification: r });
+});
+
+router.get('/health', (req, res) => res.json({ ok: true, service: 'atp', version: '1.0.0' }));
+
+// ─── Public transparency feed ─────────────────────────────────────────────
+// WAB dogfoods ATP: every subscription payment processed via webagentbridge.com
+// produces a publicly-verifiable Ed25519 receipt. This feed lists them.
+router.get('/platform/receipts', publicReceiptLimiter, (req, res) => {
+  const limit  = Math.min(100, Math.max(1, parseInt(req.query.limit, 10) || 20));
+  const offset = Math.max(0, parseInt(req.query.offset, 10) || 0);
+  const items = transactions.listPlatformReceipts({ limit, offset });
+  res.json({ ok: true, data: items, limit, offset });
+});
+
+router.get('/platform/stats', publicReceiptLimiter, (req, res) => {
+  const stats = transactions.getPlatformStats();
+  res.json({ ok: true, data: stats });
+});
+
+module.exports = router;

package/server/services/stripe.js

@@ -138,6 +138,25 @@ function handleWebhookEvent(event) {
             periodStart: new Date(invoice.period_start * 1000).toISOString(),
             periodEnd: new Date(invoice.period_end * 1000).toISOString()
           });
+          // ── WAB dogfooding: record this real money event as an ATP receipt ──
+          // Every dollar that flows into WAB is itself a publicly-verifiable
+          // Ed25519 receipt. Failure here MUST NOT block payment confirmation.
+          try {
+            const transactions = require('./transactions');
+            transactions.recordPlatformPayment({
+              userId: sub.user_id,
+              amountCents: invoice.amount_paid,
+              currency: (invoice.currency || 'USD').toUpperCase(),
+              tier: sub.tier,
+              externalRef: invoice.id || invoice.payment_intent,
+              description: `WAB ${sub.tier} subscription`,
+              periodStart: invoice.period_start ? new Date(invoice.period_start * 1000).toISOString() : null,
+              periodEnd:   invoice.period_end   ? new Date(invoice.period_end * 1000).toISOString()   : null,
+              provider: 'stripe',
+            });
+          } catch (e) {
+            console.error('[atp] recordPlatformPayment failed (non-fatal):', e.message);
+          }
         }
       }
       break;