@tangle-network/agent-gateway 0.7.1 → 0.8.0

package/src/verify.ts

@@ -1,5 +1,105 @@
 import type { X402Config, MppConfig, ApiKeyInfo, GatewayConfig } from './types'
-import type { NonceStore } from './nonce-store'
+import { claimStoredNonce, nonceTtlSeconds, type NonceStore } from './nonce-store'
+import {
+  mppPaymentOperationId,
+  type MppAuthenticatedCredential,
+} from './mpp-payment'
+
+export interface VerifiedMppCredential extends MppAuthenticatedCredential {
+  /** Opaque replay key. BlueprinTEVM shares the x402 nonce namespace. */
+  replayKey: string
+}
+
+/** Return the legacy opaque nonce key used by older consumers. */
+export function mppReplayNonceKey(authHeader: string): string | undefined {
+  const decoded = decodeMppCredential(authHeader)
+  return decoded ? canonicalMppNonceKey(decoded.method, decoded.payload, decoded.credential) : undefined
+}
+
+/** Return the decoded MPP payload for a durable payment claim. */
+export function mppPaymentPayload(authHeader: string): Record<string, unknown> | undefined {
+  return decodeMppCredential(authHeader)?.payload
+}
+
+/** Return the decoded method credential for the post-guard charge lifecycle. */
+export function mppPaymentCredential(authHeader: string): string | undefined {
+  return decodeMppCredential(authHeader)?.credential
+}
+
+interface DecodedMppCredential {
+  method: string
+  credential: string
+  payload: Record<string, unknown>
+}
+
+function decodeMppCredential(authHeader: string): DecodedMppCredential | undefined {
+  const match = authHeader.match(/^Payment\s+(\S+)\s+(\S+)$/i)
+  if (!match) return undefined
+  const [, rawMethod, credentialB64] = match
+  if (!/^[A-Za-z0-9_-]+$/.test(credentialB64)) return undefined
+  try {
+    const decoded = Buffer.from(credentialB64, 'base64url').toString('utf-8')
+    let payload: Record<string, unknown> = {}
+    try {
+      const credential = JSON.parse(decoded) as unknown
+      if (credential && typeof credential === 'object' && !Array.isArray(credential)) {
+        const record = credential as Record<string, unknown>
+        const nested = record.payload
+        payload = nested && typeof nested === 'object' && !Array.isArray(nested)
+          ? nested as Record<string, unknown>
+          : record
+      }
+    } catch {
+      // Method-specific verifiers may accept a non-JSON credential format.
+    }
+    return { method: rawMethod.toLowerCase(), credential: decoded, payload }
+  } catch {
+    return undefined
+  }
+}
+
+function canonicalMppNonceKey(
+  method: string,
+  payload: Record<string, unknown>,
+  credential: string,
+): string {
+  if (payload.nonce === undefined) {
+    return `mpp:${method.toLowerCase()}:receipt:${Buffer.from(credential).toString('base64url')}`
+  }
+  const nonce = BigInt(String(payload.nonce)).toString()
+  const commitment = payload.commitment
+  if (method.toLowerCase() === 'blueprintevm' && typeof commitment === 'string' && commitment.length > 0) {
+    return `${commitment.toLowerCase()}:${nonce}`
+  }
+  return `mpp:${method.toLowerCase()}:${String(payload.commitment ?? payload.from ?? 'unknown').toLowerCase()}:${nonce}`
+}
+
+function blueprintevmNonceKey(payload: Record<string, unknown>): string | undefined {
+  if (payload.nonce === undefined) return undefined
+  const nonce = BigInt(String(payload.nonce)).toString()
+  const identity = payload.commitment ?? payload.from
+  if (typeof identity !== 'string' || identity.length === 0) return undefined
+  return `${identity.toLowerCase()}:${nonce}`
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`
+  if (value && typeof value === 'object') {
+    const record = value as Record<string, unknown>
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(',')}}`
+  }
+  return JSON.stringify(value)
+}
+
+function legacyMppPaymentIdentity(
+  method: string,
+  payload: Record<string, unknown>,
+  credential: string,
+): string {
+  const canonicalPayload = stableJson(payload)
+  if (canonicalPayload !== '{}') return `legacy:${method}:${canonicalPayload}`
+  return `legacy:${method}:credential:${Buffer.from(credential).toString('base64url')}`
+}
 
 /** Pure capability checks shared by discovery and every request protocol. */
 export function isApiKeyAuthEnabled(
@@ -8,17 +108,18 @@ export function isApiKeyAuthEnabled(
   return config.verifyApiKey !== undefined || config.x402.demoMode === true
 }
 
-/** MPP is enabled only when a real verifier or explicit demo mode exists. */
+/** MPP is enabled only when authentication and method settlement are complete. */
 export function isMppAuthEnabled(
   config: Pick<GatewayConfig, 'mpp' | 'x402'>,
 ): boolean {
-  const method = config.mpp?.method ?? 'blueprintevm'
-  return Boolean(
-    config.mpp &&
-      (config.mpp.verifySigner !== undefined ||
-        (method === 'blueprintevm' && config.x402.verifySigner !== undefined) ||
-        config.x402.demoMode === true),
-  )
+  const method = (config.mpp?.method ?? 'blueprintevm').toLowerCase()
+  if (!config.mpp) return false
+  const authenticated = typeof config.mpp.authenticateCredential === 'function' ||
+    typeof config.mpp.verifySigner === 'function' ||
+    (method === 'blueprintevm' && config.x402.verifySigner !== undefined) ||
+    (method === 'blueprintevm' && config.x402.demoMode === true)
+  if (!authenticated) return false
+  return method === 'blueprintevm' || config.mpp.charge !== undefined
 }
 
 /**
@@ -36,6 +137,8 @@ export async function verifyX402(
   spendAuthHeader: string,
   config: X402Config,
   nonceStore?: NonceStore,
+  minimumAmount = 1n,
+  markNonce = true,
 ): Promise<string | null> {
   try {
     const raw = JSON.parse(spendAuthHeader)
@@ -49,25 +152,30 @@ export async function verifyX402(
     // Reject expired payments
     if (expiry < BigInt(Math.floor(Date.now() / 1000))) return null
 
-    // Reject zero-amount payments
-    if (amount <= 0n) return null
+    // Reject payments that cannot cover the request's maximum charge. The
+    // check runs before the host verifier because that callback can reserve or
+    // settle funds as part of its production verification path.
+    if (amount <= 0n || minimumAmount < 0n || amount < minimumAmount) return null
 
-    const nonceKey = `${raw.commitment}:${nonce.toString()}`
-    if (nonceStore && await nonceStore.hasSeen(nonceKey)) return null
+    const nonceKey = `${String(raw.commitment).toLowerCase()}:${nonce.toString()}`
+    if (nonceStore?.hasSeen && await nonceStore.hasSeen(nonceKey)) return null
 
     if (config.verifySigner) {
-      const verified = await config.verifySigner(raw)
+      const verified = await config.verifySigner(raw, {
+        protocolVersion: config.paymentProtocolVersion ?? (config.paymentOperations ? 2 : 1),
+      })
       if (!verified) return null
     } else if (!config.demoMode) {
       return null
     }
 
-    // Check and mark only after the signature is accepted. Otherwise an
-    // invalid request can burn a valid payer nonce and deny the real request.
-    if (nonceStore) {
-      // Mark seen with TTL matching the expiry window (max 1 hour)
-      const ttl = Math.min(Number(expiry) - Math.floor(Date.now() / 1000), 3600)
-      await nonceStore.markSeen(nonceKey, Math.max(ttl, 60))
+    // Claim only after the signature is accepted. Otherwise invalid traffic
+    // can burn a valid payer nonce and deny the real request.
+    if (nonceStore && markNonce) {
+      const ttl = nonceTtlSeconds(expiry)
+      if (ttl === undefined) return null
+      const claimed = await claimStoredNonce(nonceStore, nonceKey, ttl)
+      if (!claimed) return null
     }
 
     return raw.commitment
@@ -80,92 +188,146 @@ export async function verifyX402(
  * Verify MPP (Machine Payments Protocol) Authorization: Payment header.
  *
  * MPP uses `Authorization: Payment <method> <credential>` format. The
- * credential is method-specific; `MppConfig.verifySigner` owns verification
- * and returns the consumer identity. The built-in `blueprintevm` path can
+ * credential is method-specific; `MppConfig.authenticateCredential` owns authentication
+ * and returns the consumer plus stable payment identity. The built-in `blueprintevm` path can
  * reuse the x402 verifier for credentials with the compatible payload shape.
  *
- * Returns the signer address if valid, null otherwise.
+ * Returns authenticated identity if valid, null otherwise.
  * In demo mode, accepts any well-formed Payment header with an identity.
  */
-export async function verifyMpp(
+export async function verifyMppCredential(
   authHeader: string,
   config: MppConfig,
   x402Config: X402Config,
   nonceStore?: NonceStore,
-): Promise<string | null> {
+  minimumAmount = 1n,
+  markNonce = true,
+): Promise<VerifiedMppCredential | null> {
   // MPP format: "Payment <method> <base64url-credential>"
   const match = authHeader.match(/^Payment\s+(\S+)\s+(\S+)$/i)
   if (!match) return null
 
-  const [, method, credentialB64] = match
-  if (config.method && method !== config.method) return null
+  const [, rawMethod] = match
+  const method = rawMethod.toLowerCase()
+  if (method !== (config.method ?? 'blueprintevm').toLowerCase()) return null
 
   try {
-    if (!/^[A-Za-z0-9_-]+$/.test(credentialB64)) return null
-    const decoded = Buffer.from(credentialB64, 'base64url').toString('utf-8')
-    let payload: Record<string, unknown> = {}
-    try {
-      const credential = JSON.parse(decoded) as unknown
-      if (credential && typeof credential === 'object' && !Array.isArray(credential)) {
-        const nested = (credential as Record<string, unknown>).payload
-        payload =
-          nested && typeof nested === 'object' && !Array.isArray(nested)
-            ? (nested as Record<string, unknown>)
-            : (credential as Record<string, unknown>)
+    const decodedCredential = decodeMppCredential(authHeader)
+    if (!decodedCredential) return null
+    const { credential: decoded, payload } = decodedCredential
+
+    // Validate common EVM fields before pure credential authentication.
+    // BlueprinTEVM carries x402-equivalent token amounts and must cover the
+    // same request ceiling as the X-Payment-Signature path.
+    const operator = payload.operator ?? payload.to
+    if (operator !== undefined) {
+      if (typeof operator !== 'string' || operator.toLowerCase() !== x402Config.operatorAddress.toLowerCase()) {
+        return null
       }
-    } catch {
-      // Method-specific verifiers may accept a non-JSON credential format.
+    }
+    const paymentAmount = payload.amount ?? payload.value
+    if (paymentAmount !== undefined) {
+      const amount = BigInt(String(paymentAmount))
+      if (amount <= 0n || (method === 'blueprintevm' && amount < minimumAmount)) return null
+    } else if (method === 'blueprintevm') {
+      return null
+    }
+    if (payload.nonce !== undefined) BigInt(String(payload.nonce))
+    if (payload.expiry !== undefined && BigInt(String(payload.expiry)) < BigInt(Math.floor(Date.now() / 1000))) {
+      return null
     }
 
-    const nonceKey =
-      nonceStore && payload.nonce !== undefined
-        ? `mpp:${method}:${String(payload.commitment ?? payload.from ?? 'unknown')}:${String(payload.nonce)}`
-        : null
-    if (nonceKey && await nonceStore!.hasSeen(nonceKey)) return null
+    const blueprintevmKey = method === 'blueprintevm'
+      ? blueprintevmNonceKey(payload)
+      : undefined
+    if (markNonce && blueprintevmKey && nonceStore?.hasSeen && await nonceStore.hasSeen(blueprintevmKey)) {
+      return null
+    }
 
-    let consumerId: string | null = null
-    if (config.verifySigner) {
-      consumerId = await config.verifySigner(payload, { method, credential: decoded })
+    let authenticated: MppAuthenticatedCredential | null = null
+    if (config.authenticateCredential) {
+      authenticated = await config.authenticateCredential(payload, { method, credential: decoded })
+    } else if (config.verifySigner) {
+      const consumerId = await config.verifySigner(payload, { method, credential: decoded })
+      authenticated = typeof consumerId === 'string' && consumerId.length > 0
+        ? {
+            consumerId,
+            paymentIdentity: legacyMppPaymentIdentity(method, payload, decoded),
+          }
+        : null
     } else if (method === 'blueprintevm' && x402Config.verifySigner && payload.commitment) {
-      const verified = await x402Config.verifySigner(payload)
-      consumerId = verified ? String(payload.commitment) : null
+      const verified = await x402Config.verifySigner(payload, {
+        protocolVersion: x402Config.paymentProtocolVersion ?? (x402Config.paymentOperations ? 2 : 1),
+      })
+      const paymentIdentity = blueprintevmNonceKey(payload) ?? stableJson(payload)
+      authenticated = verified
+        ? { consumerId: String(payload.commitment), paymentIdentity }
+        : null
     } else if (x402Config.demoMode) {
       const identity = payload.commitment ?? payload.from
       if (typeof identity !== 'string' || identity.length === 0) return null
-      consumerId = identity
+      const paymentIdentity = method === 'blueprintevm'
+        ? blueprintevmNonceKey(payload) ?? stableJson(payload)
+        : ''
+      if (!paymentIdentity) return null
+      authenticated = { consumerId: identity, paymentIdentity }
     } else {
       return null
     }
-    if (!consumerId) return null
+    if (
+      !authenticated ||
+      typeof authenticated.consumerId !== 'string' ||
+      authenticated.consumerId.length === 0 ||
+      typeof authenticated.paymentIdentity !== 'string' ||
+      authenticated.paymentIdentity.length === 0
+    ) return null
 
-    // Validate common EVM fields when present. Method-specific verifiers own
-    // the complete credential contract for non-EVM methods.
-    const operator = payload.operator ?? payload.to
-    if (operator !== undefined) {
-      if (typeof operator !== 'string' || operator.toLowerCase() !== x402Config.operatorAddress.toLowerCase()) {
-        return null
-      }
-    }
-    if (payload.amount !== undefined && BigInt(String(payload.amount)) <= 0n) return null
-    if (payload.nonce !== undefined) BigInt(String(payload.nonce))
-    if (payload.expiry !== undefined && BigInt(String(payload.expiry)) < BigInt(Math.floor(Date.now() / 1000))) {
-      return null
-    }
+    const replayKey = method === 'blueprintevm'
+      ? blueprintevmKey ??
+        await mppPaymentOperationId(method, authenticated.paymentIdentity)
+      : await mppPaymentOperationId(method, authenticated.paymentIdentity)
+    if (!replayKey) return null
+    if (markNonce && !blueprintevmKey && nonceStore?.hasSeen && await nonceStore.hasSeen(replayKey)) return null
 
-    if (nonceStore && payload.nonce !== undefined) {
+    if (nonceStore && markNonce) {
       const expiry = payload.expiry === undefined
-        ? Math.floor(Date.now() / 1000) + 3600
-        : Number(payload.expiry)
-      const ttl = Math.min(expiry - Math.floor(Date.now() / 1000), 3600)
-      await nonceStore.markSeen(nonceKey!, Math.max(ttl, 60))
+        ? BigInt(Math.floor(Date.now() / 1000) + 3600)
+        : BigInt(String(payload.expiry))
+      const ttl = nonceTtlSeconds(expiry)
+      if (ttl === undefined) return null
+      const claimed = await claimStoredNonce(nonceStore, replayKey, ttl)
+      if (!claimed) return null
     }
 
-    return consumerId
+    return { ...authenticated, replayKey }
   } catch {
     return null
   }
 }
 
+/**
+ * Verify an MPP credential using the 0.7.1 public return shape.
+ * Rich durable callers use verifyMppCredential instead.
+ */
+export async function verifyMpp(
+  authHeader: string,
+  config: MppConfig,
+  x402Config: X402Config,
+  nonceStore?: NonceStore,
+  minimumAmount = 1n,
+  markNonce = true,
+): Promise<string | null> {
+  const authenticated = await verifyMppCredential(
+    authHeader,
+    config,
+    x402Config,
+    nonceStore,
+    minimumAmount,
+    markNonce,
+  )
+  return authenticated?.consumerId ?? null
+}
+
 /**
  * Default API key verifier — accepts any `sk_agent_*` key (demo mode).
  * Override in GatewayConfig.verifyApiKey for production.

package/dist/chunk-M7ZJAK4K.js

@@ -1,53 +0,0 @@
-// src/nonce-store.ts
-var MemoryNonceStore = class {
-  seen = /* @__PURE__ */ new Map();
-  // nonce → expiresAt
-  lastEviction = Date.now();
-  async hasSeen(nonce) {
-    this.evictExpired();
-    const expiresAt = this.seen.get(nonce);
-    if (!expiresAt) return false;
-    if (expiresAt < Date.now()) {
-      this.seen.delete(nonce);
-      return false;
-    }
-    return true;
-  }
-  async markSeen(nonce, ttlSeconds) {
-    this.seen.set(nonce, Date.now() + ttlSeconds * 1e3);
-    this.evictExpired();
-  }
-  evictExpired() {
-    const now = Date.now();
-    if (now - this.lastEviction < 6e4) return;
-    this.lastEviction = now;
-    for (const [nonce, expiresAt] of this.seen) {
-      if (expiresAt < now) this.seen.delete(nonce);
-    }
-  }
-};
-var KvNonceStore = class {
-  constructor(kv, prefix = "nonce") {
-    this.kv = kv;
-    this.prefix = prefix;
-  }
-  kv;
-  prefix;
-  async hasSeen(nonce) {
-    const value = await this.kv.get(this.key(nonce));
-    return value !== null;
-  }
-  async markSeen(nonce, ttlSeconds) {
-    const ttl = Math.max(ttlSeconds, 60);
-    await this.kv.put(this.key(nonce), "1", { expirationTtl: ttl });
-  }
-  key(nonce) {
-    return `${this.prefix}:${nonce}`;
-  }
-};
-
-export {
-  MemoryNonceStore,
-  KvNonceStore
-};
-//# sourceMappingURL=chunk-M7ZJAK4K.js.map

package/dist/chunk-M7ZJAK4K.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/nonce-store.ts"],"sourcesContent":["/**\n * Nonce replay protection for x402/MPP payments.\n * Tracks seen nonces to prevent the same payment from being used twice.\n */\n\nexport interface NonceStore {\n  /** Check if nonce has been seen. Returns true if already used (reject). */\n  hasSeen(nonce: string): Promise<boolean>\n  /** Mark nonce as used. TTL = how long to remember it (seconds). */\n  markSeen(nonce: string, ttlSeconds: number): Promise<void>\n}\n\n// ---------------------------------------------------------------------------\n// In-memory implementation — single-worker, ephemeral\n// ---------------------------------------------------------------------------\n\n/** In-memory nonce store with automatic eviction. Use in tests or single-worker deploys. */\nexport class MemoryNonceStore implements NonceStore {\n  private seen = new Map<string, number>() // nonce → expiresAt\n  private lastEviction = Date.now()\n\n  async hasSeen(nonce: string): Promise<boolean> {\n    this.evictExpired()\n    const expiresAt = this.seen.get(nonce)\n    if (!expiresAt) return false\n    if (expiresAt < Date.now()) {\n      this.seen.delete(nonce)\n      return false\n    }\n    return true\n  }\n\n  async markSeen(nonce: string, ttlSeconds: number): Promise<void> {\n    this.seen.set(nonce, Date.now() + ttlSeconds * 1000)\n    this.evictExpired()\n  }\n\n  private evictExpired() {\n    const now = Date.now()\n    // Evict at most every 60 seconds to avoid O(n) on every request\n    if (now - this.lastEviction < 60_000) return\n    this.lastEviction = now\n    for (const [nonce, expiresAt] of this.seen) {\n      if (expiresAt < now) this.seen.delete(nonce)\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Cloudflare KV implementation — multi-worker, distributed\n// ---------------------------------------------------------------------------\n\n/**\n * Minimal KVNamespace shape — matches Cloudflare Workers' @cloudflare/workers-types\n * without pulling that package as a dep. Production consumers cast their KV\n * binding to this interface at the construction site.\n */\nexport interface KVNamespace {\n  get(key: string, options?: { type?: 'text' | 'json' }): Promise<string | null>\n  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>\n  delete(key: string): Promise<void>\n}\n\n/**\n * KV-backed NonceStore for distributed Cloudflare Workers deployments.\n *\n * Why this exists: MemoryNonceStore works on a single worker instance, but\n * Cloudflare routes requests across multiple isolates. Without shared state,\n * an attacker could retry a replayed nonce against a different isolate and\n * have it accepted. This implementation uses Workers KV with native TTL so\n * the nonce automatically expires at payment-expiry time.\n *\n * TTL precision: KV is eventually consistent (propagation ~60s). For x402\n * with 10-minute expiry windows this is fine — by the time KV propagates,\n * the payment itself would be expired anyway.\n *\n * Usage:\n *   const nonceStore = new KvNonceStore(env.NONCE_KV, 'x402')\n *   createAgentGateway({ ...config, nonceStore })\n */\nexport class KvNonceStore implements NonceStore {\n  constructor(\n    private readonly kv: KVNamespace,\n    /** Key prefix to namespace within a shared KV (default: \"nonce\"). */\n    private readonly prefix: string = 'nonce',\n  ) {}\n\n  async hasSeen(nonce: string): Promise<boolean> {\n    const value = await this.kv.get(this.key(nonce))\n    return value !== null\n  }\n\n  async markSeen(nonce: string, ttlSeconds: number): Promise<void> {\n    // KV minimum TTL is 60 seconds\n    const ttl = Math.max(ttlSeconds, 60)\n    await this.kv.put(this.key(nonce), '1', { expirationTtl: ttl })\n  }\n\n  private key(nonce: string): string {\n    return `${this.prefix}:${nonce}`\n  }\n}\n"],"mappings":";AAiBO,IAAM,mBAAN,MAA6C;AAAA,EAC1C,OAAO,oBAAI,IAAoB;AAAA;AAAA,EAC/B,eAAe,KAAK,IAAI;AAAA,EAEhC,MAAM,QAAQ,OAAiC;AAC7C,SAAK,aAAa;AAClB,UAAM,YAAY,KAAK,KAAK,IAAI,KAAK;AACrC,QAAI,CAAC,UAAW,QAAO;AACvB,QAAI,YAAY,KAAK,IAAI,GAAG;AAC1B,WAAK,KAAK,OAAO,KAAK;AACtB,aAAO;AAAA,IACT;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,SAAS,OAAe,YAAmC;AAC/D,SAAK,KAAK,IAAI,OAAO,KAAK,IAAI,IAAI,aAAa,GAAI;AACnD,SAAK,aAAa;AAAA,EACpB;AAAA,EAEQ,eAAe;AACrB,UAAM,MAAM,KAAK,IAAI;AAErB,QAAI,MAAM,KAAK,eAAe,IAAQ;AACtC,SAAK,eAAe;AACpB,eAAW,CAAC,OAAO,SAAS,KAAK,KAAK,MAAM;AAC1C,UAAI,YAAY,IAAK,MAAK,KAAK,OAAO,KAAK;AAAA,IAC7C;AAAA,EACF;AACF;AAkCO,IAAM,eAAN,MAAyC;AAAA,EAC9C,YACmB,IAEA,SAAiB,SAClC;AAHiB;AAEA;AAAA,EAChB;AAAA,EAHgB;AAAA,EAEA;AAAA,EAGnB,MAAM,QAAQ,OAAiC;AAC7C,UAAM,QAAQ,MAAM,KAAK,GAAG,IAAI,KAAK,IAAI,KAAK,CAAC;AAC/C,WAAO,UAAU;AAAA,EACnB;AAAA,EAEA,MAAM,SAAS,OAAe,YAAmC;AAE/D,UAAM,MAAM,KAAK,IAAI,YAAY,EAAE;AACnC,UAAM,KAAK,GAAG,IAAI,KAAK,IAAI,KAAK,GAAG,KAAK,EAAE,eAAe,IAAI,CAAC;AAAA,EAChE;AAAA,EAEQ,IAAI,OAAuB;AACjC,WAAO,GAAG,KAAK,MAAM,IAAI,KAAK;AAAA,EAChC;AACF;","names":[]}