@agentsbloom/sdk 0.2.0 → 0.4.0

package/lib/ap2.js

@@ -1,4 +1,5 @@
 import crypto from 'crypto';
+import { createReplayCache } from './shared-store.js';
 
 /**
  * Hardened AP2 (Agent Payments Protocol) mandate verification.
@@ -130,37 +131,50 @@ export function ed25519PublicKeyFromDidKey(didKey) {
 }
 
 // --- Replay protection ---
-// A bounded, TTL-cleaned cache of mandate `jti`s that have already been
-// consumed. Sized generously; entries are removed once the mandate they
-// belonged to would have expired anyway, so the cache cannot grow forever
-// even under sustained attack traffic.
-const seenMandateJtis = new Map(); // jti -> expiresAtMs
-const REPLAY_CACHE_MAX_SIZE = 50_000;
-
-const replayCleanupInterval = setInterval(() => {
-  const now = Date.now();
-  for (const [jti, expiresAtMs] of seenMandateJtis.entries()) {
-    if (expiresAtMs < now) seenMandateJtis.delete(jti);
-  }
-}, 60 * 1000);
-replayCleanupInterval.unref?.();
+// Consumed mandate jtis. Local Map by default; when an Upstash Redis REST
+// endpoint is configured (see lib/shared-store.js) the cache becomes
+// cluster-wide so a mandate consumed on one instance cannot replay against
+// another. `has()` is maybe-async (boolean locally, Promise when shared) -
+// callers await it.
+const seenMandateJtis = createReplayCache('agentsbloom:ap2:jti', 50_000);
 
 /** Clears all replay-tracking state. Exposed for tests and shutdown(). */
 export function resetAp2ReplayCache() {
   seenMandateJtis.clear();
 }
 
-/** Stops the background cleanup timer. Called from index.js's shutdown(). */
-export function stopAp2ReplayCleanup() {
-  clearInterval(replayCleanupInterval);
-}
+/** No-op retained for shutdown() compatibility; eviction is amortized. */
+export function stopAp2ReplayCleanup() {}
 
-function isReplay(jti, expMs) {
-  if (seenMandateJtis.has(jti)) return true;
-  if (seenMandateJtis.size < REPLAY_CACHE_MAX_SIZE) {
-    seenMandateJtis.set(jti, expMs);
+/**
+ * Normalizes an audience/merchantScope value for comparison. Clients that
+ * build URLs with `new URL(...).href` (the standard practice - the
+ * Test Console's dynamic target validation does exactly this) produce a
+ * trailing slash ("https://store.example.com/") while merchants configure
+ * the same audience without one. Comparing raw strings rejected those
+ * perfectly valid mandates, so both sides are normalized: URL-parsed when
+ * possible (lowercased host, trailing slashes stripped), plain
+ * slash-stripped otherwise (non-URL audience strings keep old behavior).
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+export function normalizeAudience(value) {
+  if (typeof value !== 'string') return String(value ?? '');
+  const trimmed = value.trim();
+  if (trimmed === '') return trimmed;
+  try {
+    const url = new URL(trimmed);
+    const path = url.pathname.replace(/\/+$/, '');
+    return `${url.protocol}//${url.host}${path}`;
+  } catch {
+    return trimmed.replace(/\/+$/, '');
   }
-  return false;
+}
+
+/** Audience comparison that tolerates URL-normalization differences. */
+function audienceMatches(claimed, expected) {
+  return normalizeAudience(claimed) === normalizeAudience(expected);
 }
 
 // --- Signature verification helpers ---
@@ -195,6 +209,20 @@ function hashAlgForJwtAlg(alg) {
  * @param {boolean} [options.requireJti=true] - reject mandates without a `jti` claim
  * @param {string[]} [options.requestedCategories] - if set and the mandate's
  *   `intentMandate.allowedCategories` is present, the two must overlap
+ * @param {boolean} [options.allowSelfCertifying=true] - v4: when false,
+ *   self-certifying did:key mandates are rejected and only the
+ *   merchant-configured trusted key is accepted (production-grade posture:
+ *   a self-certifying mandate proves only that the MINTER holds the key,
+ *   not that any real wallet/payer authorized the spend)
+ * @param {string} [options.expectedCurrency] - v4: when set, the mandate's
+ *   declared currency (intentMandate.currency or paymentMandate.currency)
+ *   must match it, closing unit-mismatch budget attacks (a "100" cap in a
+ *   low-value currency authorizing 100 in the merchant's currency)
+ * @param {boolean} [options.consumeJti=true] - second-pass review: when
+ *   false, a valid mandate is verified and returned WITHOUT consuming its
+ *   single-use jti. The middleware passes false for mandates presented on
+ *   non-AP2 routes so a mandate riding along on an unrelated action does
+ *   not burn itself; AP2 endpoints consume as before.
  * @returns {{ valid: boolean, verified: boolean, protocol: 'AP2', reason?: string, mandates?: object }}
  */
 export function verifyAp2Mandate(headers = {}, body = {}, options = {}) {
@@ -204,6 +232,9 @@ export function verifyAp2Mandate(headers = {}, body = {}, options = {}) {
     maxMandateLifetimeSec = 3600,
     requireJti = true,
     requestedCategories = null,
+    allowSelfCertifying = true,
+    expectedCurrency = null,
+    consumeJti = true,
   } = options;
 
   const mandateHeader = headers['x-ap2-mandate'] || headers['authorization'];
@@ -224,6 +255,21 @@ export function verifyAp2Mandate(headers = {}, body = {}, options = {}) {
     return { valid: false, reason: 'Invalid AP2 Mandate SD-JWT format', protocol: 'AP2' };
   }
 
+  // --- JOSE header sanity (v4 medium pass) ---
+  // The typ claim, when present, must be a JWT/SD-JWT type. Anything else
+  // (e.g. a nested JWT or an attacker-chosen custom typ) is rejected rather
+  // than silently processed. Selective-disclosure processing remains a
+  // documented gap - this verifier handles the signed envelope only.
+  if (
+    header.typ !== undefined &&
+    !['jwt', 'sd-jwt'].includes(String(header.typ).toLowerCase())
+  ) {
+    return { valid: false, reason: `Unsupported mandate typ: ${header.typ}`, protocol: 'AP2' };
+  }
+  if (!header.alg) {
+    return { valid: false, reason: 'Missing alg in mandate header', protocol: 'AP2' };
+  }
+
   // --- Required claims present ---
   if (!payload.iss) return { valid: false, reason: 'Missing issuer', protocol: 'AP2' };
   if (!payload.aud) return { valid: false, reason: 'Missing audience', protocol: 'AP2' };
@@ -247,6 +293,20 @@ export function verifyAp2Mandate(headers = {}, body = {}, options = {}) {
   let publicKey = null;
   let usingSelfCertifyingKey = false;
 
+  // v4: merchants can require an out-of-band-trusted issuer. A
+  // self-certifying did:key mandate is cryptographically sound but
+  // semantically self-vouched - anyone can mint one declaring any
+  // maxBudget - so production deployments that bind mandates to real
+  // wallets should set allowSelfCertifying: false.
+  const isDidKeyIssuer = String(payload.iss || '').startsWith('did:key:');
+  if (!allowSelfCertifying && isDidKeyIssuer) {
+    return {
+      valid: false,
+      reason: 'Self-certifying did:key mandates are disabled for this store; a merchant-trusted public key is required',
+      protocol: 'AP2',
+    };
+  }
+
   if (trustedPublicKey) {
     try {
       publicKey = trustedPublicKey instanceof crypto.KeyObject
@@ -258,7 +318,7 @@ export function verifyAp2Mandate(headers = {}, body = {}, options = {}) {
     if (!EXPLICIT_KEY_ALLOWED_ALGS.has(header.alg)) {
       return { valid: false, reason: `Unsupported signature algorithm: ${header.alg}`, protocol: 'AP2' };
     }
-  } else if (String(payload.iss).startsWith('did:key:')) {
+  } else if (isDidKeyIssuer) {
     usingSelfCertifyingKey = true;
     if (header.alg !== 'EdDSA') {
       return { valid: false, reason: 'did:key issuers require the EdDSA algorithm', protocol: 'AP2' };
@@ -292,7 +352,7 @@ export function verifyAp2Mandate(headers = {}, body = {}, options = {}) {
   }
 
   // --- Audience binding ---
-  if (expectedAudience && payload.aud !== expectedAudience) {
+  if (expectedAudience && !audienceMatches(payload.aud, expectedAudience)) {
     return {
       valid: false,
       reason: `Mandate audience "${payload.aud}" does not match this store ("${expectedAudience}")`,
@@ -302,7 +362,7 @@ export function verifyAp2Mandate(headers = {}, body = {}, options = {}) {
 
   // --- merchantScope binding (if the mandate declares one, it must match too) ---
   const merchantScope = payload.intentMandate?.merchantScope;
-  if (expectedAudience && merchantScope && merchantScope !== expectedAudience) {
+  if (expectedAudience && merchantScope && !audienceMatches(merchantScope, expectedAudience)) {
     return {
       valid: false,
       reason: `Mandate merchantScope "${merchantScope}" does not match this store ("${expectedAudience}")`,
@@ -310,12 +370,18 @@ export function verifyAp2Mandate(headers = {}, body = {}, options = {}) {
     };
   }
 
-  // --- Replay protection ---
-  if (payload.jti) {
-    if (isReplay(payload.jti, payload.exp * 1000)) {
-      return { valid: false, reason: 'Mandate has already been used (replay detected)', protocol: 'AP2' };
-    }
-  }
+  // --- Replay protection + final validations ---
+  // v4: the jti is now consumed with an ATOMIC claim() as the FINAL step,
+  // after every other validation passes. This preserves the 2026-08 audit
+  // semantics (an over-budget/category/audience attempt never burns the
+  // mandate - the corrected retry works) while closing the check-then-act
+  // race where two concurrent requests could both observe "not seen"
+  // before either recorded the jti. With claim(), exactly one concurrent
+  // request wins the mandate; the loser is rejected as a replay.
+  return finishVerification();
+
+  /** Everything after signature/audience verification. Maybe-async. */
+  function finishVerification() {
 
   // --- Category enforcement (only if both the mandate and caller supply it) ---
   const allowedCategories = payload.intentMandate?.allowedCategories;
@@ -340,13 +406,62 @@ export function verifyAp2Mandate(headers = {}, body = {}, options = {}) {
     }
   }
 
-  return {
-    valid: true,
+  // --- Currency binding (v4 medium pass) ---
+  // A budget number without a currency is unitless and forgeable by
+  // relabeling: a "100" cap minted in a low-value currency must not
+  // authorize "100" in the merchant's currency. When both sides declare a
+  // currency they must agree; merchants can also pin one via expectedCurrency.
+  const mandateCurrency = payload.intentMandate?.currency ?? payload.paymentMandate?.currency;
+  const normalizeCurrency = (value) => String(value || '').trim().toUpperCase();
+  if (mandateCurrency && expectedCurrency && normalizeCurrency(mandateCurrency) !== normalizeCurrency(expectedCurrency)) {
+    return {
+      valid: false,
+      reason: `Mandate currency "${mandateCurrency}" does not match this store's expected currency "${expectedCurrency}"`,
+      protocol: 'AP2',
+    };
+  }
+  if (
+    mandateCurrency &&
+    body?.currency &&
+    normalizeCurrency(mandateCurrency) !== normalizeCurrency(body.currency)
+  ) {
+    return {
+      valid: false,
+      reason: `Order currency "${body.currency}" does not match the mandate's currency "${mandateCurrency}"`,
+      protocol: 'AP2',
+    };
+  }
+
+  const replayRejection = () => ({
+    valid: false,
+    reason: 'Mandate has already been used (replay detected)',
     protocol: 'AP2',
-    verified: true,
-    selfCertifying: usingSelfCertifyingKey,
-    mandates: payload,
-  };
+  });
+
+  // --- Consume the jti: every validation above passed, so winning the
+  // atomic claim is the single successful use of this mandate. When
+  // consumeJti is false (non-AP2 routes), skip consumption entirely. ---
+  if (payload.jti && consumeJti) {
+    const claimed = seenMandateJtis.claim(payload.jti, payload.exp * 1000);
+    if (typeof claimed === 'boolean') {
+      if (!claimed) return replayRejection();
+    } else {
+      return claimed.then((won) => (won ? buildSuccess() : replayRejection()));
+    }
+  }
+
+  return buildSuccess();
+
+  function buildSuccess() {
+    return {
+      valid: true,
+      protocol: 'AP2',
+      verified: true,
+      selfCertifying: usingSelfCertifyingKey,
+      mandates: payload,
+    };
+  }
+  }
 }
 
 /**

package/lib/outcomes.js

@@ -0,0 +1,108 @@
+/**
+ * Payment-outcome reporting (migration 011 / POST /api/outcomes).
+ *
+ * AgentsBloom is the middleman: the merchant's gateway keys stay on THEIR
+ * servers, inside THEIR webhook handlers. That also means payment outcomes
+ * (paid / declined / chargeback) happen where we cannot see them - so this
+ * module lets the merchant's existing webhook handler report the outcome
+ * with one line. Those reports are what turn risk-core's decline-rate rules
+ * from theory into data, and what powers the dashboard's outcome analytics.
+ *
+ * Keys never leave the merchant: they only ever send order references,
+ * statuses, and optional amounts.
+ */
+
+const DEFAULT_STATUSES = ['paid', 'declined', 'refunded', 'chargeback', 'disputed', 'canceled'];
+
+/**
+ * Maps a Stripe webhook event to an outcome report body. Returns null for
+ * events that carry no outcome signal, so handlers can do:
+ *
+ *   const report = stripeEventToOutcome(event);
+ *   if (report) await reportPaymentOutcome(report);
+ */
+export function stripeEventToOutcome(event) {
+  const type = event?.type;
+  const wrap = (status, extra = {}) => {
+    const obj = event?.data?.object ?? {};
+    return {
+      orderRef:
+        obj.metadata?.orderRef ??
+        obj.client_reference_id ??
+        obj.id,
+      gateway: 'stripe',
+      status,
+      amount: typeof obj.amount_total === 'number'
+        ? obj.amount_total / 100
+        : typeof obj.amount === 'number'
+          ? obj.amount / 100
+          : undefined,
+      currency: typeof obj.currency === 'string' ? obj.currency : undefined,
+      reason: extra.reason ?? obj.failure_message ?? null,
+      occurredAt: event?.created ? new Date(event.created * 1000).toISOString() : undefined,
+    };
+  };
+  switch (type) {
+    case 'checkout.session.completed':
+      return wrap('paid');
+    case 'invoice.payment_failed':
+    case 'charge.failed': {
+      const rep = wrap('declined');
+      rep.reason = event?.data?.object?.failure_message ?? event?.data?.object?.failure_code ?? null;
+      return rep;
+    }
+    case 'charge.refunded':
+      return wrap('refunded');
+    case 'charge.dispute.created':
+      return wrap('chargeback');
+    default:
+      return null;
+  }
+}
+
+/**
+ * Creates a reporter bound to your AgentsBloom account key.
+ *
+ * @param {object} options
+ * @param {string} options.apiKey - partner API key (ag_live_... / ag_test_...)
+ * @param {string} [options.collectorUrl] - backend base URL
+ *   (default https://api.agentsbloom.com)
+ * @param {(url:string, init:object)=>Promise<Response>} [options.fetchImpl]
+ */
+export function createOutcomeReporter({ apiKey, collectorUrl, fetchImpl } = {}) {
+  const base = String(collectorUrl || process.env.AGENTSBLOOM_API_URL || 'https://api.agentsbloom.com').replace(/\/$/, '');
+  const doFetch = fetchImpl ?? fetch;
+
+  async function report(body) {
+    if (!apiKey) throw new Error('createOutcomeReporter requires your AgentsBloom apiKey');
+    if (!body || !body.orderRef || !DEFAULT_STATUSES.includes(body.status)) {
+      throw new Error('reportPaymentOutcome requires orderRef and status (paid|declined|refunded|chargeback|disputed|canceled)');
+    }
+    const res = await doFetch(`${base}/api/outcomes`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        gateway: 'stripe',
+        ...body,
+      }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(`outcome report failed: HTTP ${res.status} ${text.slice(0, 200)}`);
+    }
+    return res.json();
+  }
+
+  /** Reports a raw Stripe webhook event (no-op for non-outcome events). */
+  async function captureStripeOutcome(stripeEvent) {
+    const body = stripeEventToOutcome(stripeEvent);
+    if (!body) return { skipped: true };
+    return report(body);
+  }
+
+  return { report, captureStripeOutcome };
+}

package/lib/shared-store.js

@@ -0,0 +1,172 @@
+/**
+ * Shared replay-cache store for multi-instance deployments.
+ *
+ * The mandate-jti and signature-nonce replay caches were in-memory Maps:
+ * correct per process, but a second instance (or a restart mid-attack)
+ * forgets every consumed nonce, so a captured mandate/signature replays
+ * cleanly against the other instance. When an Upstash Redis REST endpoint
+ * is configured (UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN), the
+ * caches become cluster-wide through plain fetch - no new dependency.
+ *
+ * Semantics (deliberately conservative):
+ *   - Reads check the local Map first, then the shared store.
+ *   - Writes go to both; shared writes are fire-and-forget with TTL, and
+ *     shared-store OUTAGES degrade to local-only behavior (logged once)
+ *     rather than failing requests - same fail-open-with-logging posture
+ *     as the rest of the bookkeeping.
+ *   - `has()` returns a boolean in local-only mode and a Promise<boolean>
+ *     when the shared store is configured. Callers must treat it as
+ *     maybe-async (`const hit = await has(k)` works for both).
+ */
+
+const UPSTASH_URL = () => process.env.UPSTASH_REDIS_REST_URL || '';
+const UPSTASH_TOKEN = () => process.env.UPSTASH_REDIS_REST_TOKEN || '';
+
+export function isSharedStoreConfigured() {
+  return Boolean(UPSTASH_URL() && UPSTASH_TOKEN());
+}
+
+let outageLogged = false;
+
+async function sharedRequest(path, body) {
+  try {
+    const res = await fetch(`${UPSTASH_URL().replace(/\/$/, '')}${path}`, {
+      method: body === undefined ? 'GET' : 'POST',
+      headers: { Authorization: `Bearer ${UPSTASH_TOKEN()}` },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      signal: AbortSignal.timeout(3000),
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return await res.json();
+  } catch (err) {
+    if (!outageLogged) {
+      console.warn(`🌸 AgentsBloom: shared replay store unreachable (${err.message}); replay protection is local-only for this instance.`);
+      outageLogged = true;
+    }
+    return null;
+  }
+}
+/** Returns the parsed value or null. Never throws. */
+export async function sharedGetJSON(key) {
+  if (!isSharedStoreConfigured()) return null;
+  const result = await sharedRequest(`/get/${encodeURIComponent(key)}`);
+  const value = result?.result;
+  return value === null || value === undefined ? null : JSON.parse(value);
+}
+
+/** Fire-and-forget set with TTL seconds. Never throws. */
+export async function sharedSetJSON(key, value, ttlSec) {
+  if (!isSharedStoreConfigured()) return;
+  await sharedRequest(`/set/${encodeURIComponent(key)}?EX=${Math.max(1, Math.floor(ttlSec))}`, value);
+}
+
+/**
+ * A bounded local Map + optional shared-store write-through, exposing a
+ * replay-cache interface: `has(key) -> boolean | Promise<boolean>` and
+ * `set(key, expiresAtMs) -> void`.
+ *
+ * @param {string} namespace - key prefix in the shared store
+ * @param {number} maxLocalSize - bound for the in-memory Map
+ */
+export function createReplayCache(namespace, maxLocalSize = 50_000) {
+  const local = new Map(); // key -> expiresAtMs
+
+  const evict = (now) => {
+    for (const [key, expiresAtMs] of local) {
+      if (expiresAtMs < now) local.delete(key);
+    }
+  };
+
+  return {
+    /** Local-first; falls through to the shared store when configured. */
+    has(key) {
+      const now = Date.now();
+      const expiresAtMs = local.get(key);
+      if (expiresAtMs !== undefined) {
+        if (expiresAtMs >= now) return true;
+        local.delete(key);
+      }
+      if (!isSharedStoreConfigured()) {
+        // Bounded like the previous plain-Map implementation.
+        if (local.size >= maxLocalSize) {
+          evict(now);
+          if (local.size >= maxLocalSize) return false;
+        }
+        return false;
+      }
+      return sharedGetJSON(`${namespace}:${key}`).then((value) => value !== null);
+    },
+
+    /** Write-through; the shared write is fire-and-forget. */
+    set(key, expiresAtMs) {
+      if (local.size >= maxLocalSize) {
+        evict(Date.now());
+        if (local.size >= maxLocalSize) return; // refuse rather than grow unbounded
+      }
+      local.set(key, expiresAtMs);
+      if (isSharedStoreConfigured()) {
+        const ttlSec = Math.max(1, Math.ceil((expiresAtMs - Date.now()) / 1000));
+        sharedSetJSON(`${namespace}:${key}`, { e: expiresAtMs }, ttlSec);
+      }
+    },
+
+    /**
+     * v4: ATOMIC check-and-set for replay protection.
+     *
+     * The previous has()-then-set() sequence had a race window: two
+     * concurrent identical requests could both observe "not seen" before
+     * either recorded the nonce/jti, letting a captured signed request or
+     * mandate replay in parallel. claim() is a single atomic operation:
+     * locally it is a synchronous Map check-and-set; against the shared
+     * store it uses SET NX EX (set-if-not-exists), so only one of N
+     * concurrent claims across ALL instances wins.
+     *
+     * Returns true when this caller won the key (first use), false when
+     * the key was already claimed (replay). Returns a Promise<boolean>
+     * when a shared store is configured. If the shared store is
+     * unreachable, degrades to the local-only decision (same fail-open
+     * posture as the rest of the bookkeeping - documented).
+     */
+    claim(key, expiresAtMs) {
+      const now = Date.now();
+      const expiresAt = local.get(key);
+      if (expiresAt !== undefined && expiresAt >= now) return false;
+      local.delete(key);
+
+      const claimLocally = () => {
+        if (local.size >= maxLocalSize) {
+          evict(Date.now());
+          if (local.size >= maxLocalSize) {
+            // Cannot track locally; treat as claimed-but-untracked so we
+            // never fail OPEN on capacity pressure.
+            return true;
+          }
+        }
+        local.set(key, expiresAtMs);
+        return true;
+      };
+
+      if (!isSharedStoreConfigured()) {
+        return claimLocally();
+      }
+
+      const ttlSec = Math.max(1, Math.ceil((expiresAtMs - now) / 1000));
+      return sharedRequest(`/set/${encodeURIComponent(`${namespace}:${key}`)}?NX&EX=${ttlSec}`, { e: expiresAtMs })
+        .then((result) => {
+          // Upstash SET NX returns { result: 'OK' } when the key was set,
+          // { result: null } when it already existed, and null on outage.
+          if (result === null) return claimLocally(); // outage: degrade to local
+          if (result?.result === 'OK') {
+            local.set(key, expiresAtMs);
+            return true;
+          }
+          return false;
+        });
+    },
+
+    /** Test hook. */
+    clear() {
+      local.clear();
+    },
+  };
+}