@tangle-network/agent-gateway 0.7.0 → 0.8.0

package/README.md

@@ -1,6 +1,7 @@
 # @tangle-network/agent-gateway
 
-Hono middleware that turns any Tangle agent app into a paid API. Wrap your chat endpoint to accept API keys, x402 SpendAuth, or MPP credentials — with scope enforcement, per-key rate limits, nonce replay protection, prompt-injection detection, and publish routes for the marketplace.
+Hono middleware that turns any Tangle agent app into a paid API.
+It exposes one shared request pipeline for API keys, x402 SpendAuth, and MPP credentials, with scope enforcement, per-key rate limits, nonce replay protection, prompt-injection detection, and publish routes for the marketplace.
 
 ## Install
 
@@ -11,20 +12,121 @@ npm install @tangle-network/agent-gateway
 ## Usage
 
 ```ts
-import { createAgentGateway } from '@tangle-network/agent-gateway'
+import {
+  createAgentGateway,
+  recoverPayments,
+  SqlPaymentRecoveryStore,
+  verifyApiKeyFromStore,
+} from '@tangle-network/agent-gateway'
 import { Hono } from 'hono'
 
 const app = new Hono()
-app.use('/chat/*', createAgentGateway({
-  apiKeyStore: myKeyStore,
-  x402: { verifierUrl: 'https://router.tangle.tools/x402/verify' },
-  rateLimits: { perKey: { rpm: 60 } },
+const paymentRecoveryStore = new SqlPaymentRecoveryStore(sqlAdapter)
+await paymentRecoveryStore.migrate()
+app.route('/v1/agents', createAgentGateway({
+  resolveAgent: loadPublishedAgent,
+  getSandbox: openAgentSandbox,
+  recordUsage: recordUsageEvent,
+  x402: {
+    operatorAddress: '0x…',
+    chainId: 3799,
+    currencyDecimals: 6,
+    verifySigner: verifySpendAuthSignature,
+    paymentProtocolVersion: 2,
+    paymentOperations,
+    authorizePayment: reserveSpendAuthorization,
+  },
+  paymentRecovery: { store: paymentRecoveryStore },
+  defaultOutputTokens: 1024,
+  maxOutputTokens: 4096,
+  verifyApiKey: (authHeader) => verifyApiKeyFromStore(authHeader, apiKeyStore),
 }))
 ```
 
+`x402.verifySigner` is required for production.
+Set `x402.demoMode: true` only for local development and tests; that explicit mode also enables the built-in `sk_agent_*` demo key verifier.
+Keep `verifySigner` free of side effects.
+Use version 2's `authorizePayment` to reserve or claim funds after rate limits, content checks, and product authorization succeed.
+For production version 2, set `x402.paymentProtocolVersion: 2`, provide `paymentOperations`, and return its operation from `authorizePayment`.
+Production version 2 also requires a durable `paymentRecovery.store`.
+Production version 1 is read-only and must not configure `authorizePayment`.
+Production x402 version 1 also rejects the legacy `settlePayment` callback before it consumes a nonce.
+Use version 2 whenever authorization can reserve, charge, or otherwise mutate external funds.
+Run `recoverPayments(config)` from a private scheduled worker.
+Every live request and worker uses a unique durable fence token.
+A stale request or worker cannot update a row after another worker takes its lease.
+Provider settlement, recovery, and release methods must still use the operation ID idempotently.
+`paymentOperations.getPaymentOperation` must read the authoritative provider state by operation ID without changing it.
+This read is required for recovery of older A2A finalization records that predate the shared payment outbox.
+The operation store owns claim, execution start, receipt retention, partial settle, release, and expiry reclaim.
+An executing or retained operation cannot expire into a refund.
+A retained operation settles from its receipt when one exists.
+If the receipt does not arrive before `receiptTimeoutMs`, recovery settles the original quoted ceiling.
+The fallback never settles the payer's larger authorization amount.
+Keep version 1 explicitly configured while old and new gateways coexist; shared nonce storage must reject a version 1 claim owned by a version 2 operation.
+Before it calls the verifier, the gateway requires the signed amount to cover the complete filtered conversation plus the requested output limit.
+The default bound includes system text, message roles, and JSON framing.
+Set `inputTokenBound` when the provider adds harness, tool, workspace, or other hidden context.
+The gateway rejects `max_tokens` above `maxOutputTokens` and stops the sandbox stream at the accepted limit.
+An unpaid request receives `required_amount`, `currency_decimals`, and `max_output_tokens` in the 402 response.
+Sandbox adapters should emit a complete `sandbox.usage` receipt.
+Requests with a version 2 operation or generic MPP charge reject missing receipts.
+API-key requests keep the legacy visible-token estimate path.
+recordUsage must atomically upsert by event.requestId; recovery may retry an event after its acknowledgement is lost.
+The default gateway still exposes A2A with an in-memory task store.
+Older custom A2A task stores remain source-compatible at the type boundary.
+The OpenAI surface stays available when such a store is configured, while A2A returns `503` until its owner supplies atomic methods.
+Use an atomic task store for multi-worker production deployments.
+
+MPP is method-specific.
+Configure `mpp.authenticateCredential` for production MPP credentials.
+This callback receives the decoded payload and live credential.
+It returns `{ consumerId, paymentIdentity }` or `null`.
+`paymentIdentity` must be a stable, non-secret processor identity.
+Equivalent encodings of one credential must return the same payment identity.
+It must not reserve, confirm, or consume payment.
+The default `blueprintevm` method may reuse `x402.verifySigner` when its credential has the compatible x402 payload shape.
+Every other method requires an `mpp.charge` lifecycle.
+The lifecycle confirms payment after all request denials.
+The gateway then acquires its execution fence before it returns a response or starts sandbox work.
+`confirmPayment` must bind the provider operation to the supplied `operationId` before confirmation.
+It must return only after it verifies final payment success.
+`recoverPayment` must inspect that operation ID and must never create another charge.
+An authoritative `not-found` result must fence the operation ID against a later charge.
+`releasePayment` must perform an idempotent refund or release.
+The live credential is passed to `confirmPayment` only on the original request.
+The nonce and recovery stores persist only the SHA-256 digest of `paymentIdentity`.
+`Payment-Receipt` values must contain visible ASCII only.
+
+`NonceStore` remains source-compatible with 0.7.1 `hasSeen`/`markSeen` stores.
+Payment requests now require its atomic `claim` method, including version 1.
+This is a deliberate safety boundary: a check followed by a write can accept two concurrent payments.
+`KvNonceStore` with plain Cloudflare KV is not atomic and is rejected by `createAgentGateway`.
+Provide `KvNonceStore` an `atomicClaim` callback backed by D1, a Durable Object, or another linearizable store.
+Payment paths fail closed unless the store also provides one atomic `claim` method.
+The 0.7.1 `mpp.verifySigner` callback is also supported; the gateway derives a stable identity until the integration moves to `authenticateCredential`.
+
+The same authentication, authorization, rate-limit, filtering, sandbox, settlement, and usage-recording pipeline is used by the OpenAI-compatible and A2A endpoints.
+Wire protocol handlers only translate their request and response shapes.
+
 ## A2A protocol
 
 The gateway speaks Google's A2A protocol alongside its OpenAI-compatible surface: discovery via `.well-known/agent.json`, JSON-RPC 2.0 dispatch for `message/send`, `message/stream`, `tasks/get`, `tasks/cancel`, `tasks/resubscribe`, and the four `tasks/pushNotificationConfig/*` methods. Long-horizon agents — durable tasks across worker restarts, webhook delivery on terminal state, `input-required` pauses with multi-turn continuation — are documented in [`docs/a2a-long-horizon.md`](./docs/a2a-long-horizon.md).
+Production A2A task control requires `a2a.authorizeTaskAccess`; explicit demo mode is the local-test exception.
+Custom production task stores must implement atomic `createIfAbsent`, `compareAndSet`, and `compareAndSetExecution` methods.
+`compareAndSetExecution` must reject a renewal when the stored owner lease has expired.
+Task stores must retain payment recovery metadata until reconciliation clears it.
+The short-lived `gatewaySubmission` marker is not a payment recovery record and may expire with its task.
+The bundled memory and SQL stores enforce this rule even after the normal task TTL.
+Push destinations must use HTTPS without URL credentials.
+Push delivery does not follow redirects.
+Production push delivery also requires `a2a.pushUrlValidator` to reject private DNS destinations.
+Production push delivery requires `a2a.webhookSecret` so every webhook has an HMAC signature.
+The exported `deliverPushNotifications` function also requires a non-empty secret.
+Use `deliverDemoPushNotifications` only for explicit local demo mode.
+Tasks created before this release have no recorded origin and fail closed; migrate them with a verified owner binding or let them expire.
+The payment claim keeps its submission lease until the atomic submitted-to-working transition.
+An expired execution lease fails the working task and preserves its payment recovery markers.
 
 ## Tier
 

package/dist/chunk-GITV7CPT.js

@@ -0,0 +1,84 @@
+// src/observer.ts
+var ConsoleObserver = class {
+  constructor(log = (e) => console.log(JSON.stringify(e))) {
+    this.log = log;
+  }
+  log;
+  emit(level, event, ctx, rest = {}) {
+    this.log({
+      level,
+      event,
+      time: (/* @__PURE__ */ new Date()).toISOString(),
+      requestId: ctx.requestId,
+      agentSlug: ctx.agentSlug,
+      durationMs: Date.now() - ctx.startMs,
+      ...rest
+    });
+  }
+  onRequestStart(ctx) {
+    this.emit("info", "gateway.request.start", ctx);
+  }
+  onPaymentVerified(ctx, info) {
+    this.emit("info", "gateway.payment.verified", ctx, info);
+  }
+  onAuthFailure(ctx, reason) {
+    this.emit("warn", "gateway.auth.failure", ctx, reason);
+  }
+  onRateLimited(ctx, info) {
+    this.emit("warn", "gateway.rate_limit", ctx, info);
+  }
+  onBodyTooLarge(ctx, contentLength) {
+    this.emit("warn", "gateway.body_too_large", ctx, { contentLength });
+  }
+  onInjectionDetected(ctx, info) {
+    this.emit("warn", "gateway.injection", ctx, info);
+  }
+  onRequestComplete(ctx, usage) {
+    this.emit("info", "gateway.request.complete", ctx, usage);
+  }
+  onStreamError(ctx, info) {
+    this.emit("error", "gateway.stream.error", ctx, info);
+  }
+  onSettlementError(ctx, info) {
+    this.emit("error", "gateway.settlement.error", ctx, info);
+  }
+};
+var CompositeObserver = class {
+  constructor(observers) {
+    this.observers = observers;
+  }
+  observers;
+  async fanOut(event, ...args) {
+    for (const obs of this.observers) {
+      const fn = obs[event];
+      if (!fn) continue;
+      try {
+        await fn.apply(obs, args);
+      } catch (err) {
+        console.warn(`[agent-gateway] observer ${event} threw:`, err instanceof Error ? err.message : err);
+      }
+    }
+  }
+  onRequestStart = (ctx) => this.fanOut("onRequestStart", ctx);
+  onPaymentVerified = (ctx, info) => this.fanOut("onPaymentVerified", ctx, info);
+  onAuthFailure = (ctx, reason) => this.fanOut("onAuthFailure", ctx, reason);
+  onRateLimited = (ctx, info) => this.fanOut("onRateLimited", ctx, info);
+  onBodyTooLarge = (ctx, contentLength) => this.fanOut("onBodyTooLarge", ctx, contentLength);
+  onInjectionDetected = (ctx, info) => this.fanOut("onInjectionDetected", ctx, info);
+  onRequestComplete = (ctx, usage) => this.fanOut("onRequestComplete", ctx, usage);
+  onStreamError = (ctx, info) => this.fanOut("onStreamError", ctx, info);
+  onSettlementError = (ctx, info) => this.fanOut("onSettlementError", ctx, info);
+};
+function generateRequestId() {
+  const bytes = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(bytes);
+  const hex = Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+  return `req_${hex}`;
+}
+
+export {
+  ConsoleObserver,
+  CompositeObserver,
+  generateRequestId
+};
+//# sourceMappingURL=chunk-GITV7CPT.js.map

package/dist/chunk-GITV7CPT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/observer.ts"],"sourcesContent":["/**\n * Observability hook surface.\n *\n * Consumers implement GatewayObserver to wire the gateway into their existing\n * telemetry stack (Langfuse, OTEL, structured logs, Prometheus, etc.) without\n * the gateway itself depending on any of those libraries.\n *\n * Every event carries a requestId so downstream metrics can correlate the\n * payment verification, sandbox execution, and settlement for one request.\n * When no observer is configured, the gateway stays silent.\n */\n\nimport type { GatewayUsageEvent, PaymentMethod } from './payment-types'\nimport type { AuthFailureReason, GatewayObserver, RequestContext } from './observer-types'\n\nexport type { AuthFailureReason, GatewayObserver, RequestContext } from './observer-types'\n\n// ---------------------------------------------------------------------------\n// Convenience implementations\n// ---------------------------------------------------------------------------\n\n/**\n * Structured-log observer. Emits one JSON line per event on the `log` function.\n * Default sink: console.log. Production consumers usually pipe their own\n * structured logger (pino, winston, the cf Logs binding).\n *\n * Usage:\n *   new ConsoleObserver(({ level, event, ...rest }) => logger.info({ event, ...rest }))\n */\nexport class ConsoleObserver implements GatewayObserver {\n  constructor(\n    private readonly log: (entry: Record<string, unknown>) => void = (e) => console.log(JSON.stringify(e)),\n  ) {}\n\n  private emit(level: 'info' | 'warn' | 'error', event: string, ctx: RequestContext, rest: Record<string, unknown> = {}) {\n    this.log({\n      level,\n      event,\n      time: new Date().toISOString(),\n      requestId: ctx.requestId,\n      agentSlug: ctx.agentSlug,\n      durationMs: Date.now() - ctx.startMs,\n      ...rest,\n    })\n  }\n\n  onRequestStart(ctx: RequestContext) { this.emit('info', 'gateway.request.start', ctx) }\n  onPaymentVerified(ctx: RequestContext, info: { method: PaymentMethod; consumerId: string; keyId?: string }) {\n    this.emit('info', 'gateway.payment.verified', ctx, info)\n  }\n  onAuthFailure(ctx: RequestContext, reason: AuthFailureReason) {\n    this.emit('warn', 'gateway.auth.failure', ctx, reason as unknown as Record<string, unknown>)\n  }\n  onRateLimited(ctx: RequestContext, info: { consumerId: string; retryAfterSeconds: number }) {\n    this.emit('warn', 'gateway.rate_limit', ctx, info)\n  }\n  onBodyTooLarge(ctx: RequestContext, contentLength: number) {\n    this.emit('warn', 'gateway.body_too_large', ctx, { contentLength })\n  }\n  onInjectionDetected(ctx: RequestContext, info: { consumerId: string; patterns: string[]; blocked: boolean }) {\n    this.emit('warn', 'gateway.injection', ctx, info)\n  }\n  onRequestComplete(ctx: RequestContext, usage: GatewayUsageEvent) {\n    this.emit('info', 'gateway.request.complete', ctx, usage as unknown as Record<string, unknown>)\n  }\n  onStreamError(ctx: RequestContext, info: { consumerId: string; errorMessage: string }) {\n    this.emit('error', 'gateway.stream.error', ctx, info)\n  }\n  onSettlementError(ctx: RequestContext, info: { consumerId: string; method: PaymentMethod; errorMessage: string }) {\n    this.emit('error', 'gateway.settlement.error', ctx, info)\n  }\n}\n\n/**\n * Compose multiple observers into one. Errors in any individual observer\n * don't break the others (fire-and-forget telemetry).\n */\nexport class CompositeObserver implements GatewayObserver {\n  constructor(private readonly observers: GatewayObserver[]) {}\n\n  private async fanOut<K extends keyof GatewayObserver>(event: K, ...args: unknown[]): Promise<void> {\n    for (const obs of this.observers) {\n      const fn = obs[event] as ((...a: unknown[]) => void | Promise<void>) | undefined\n      if (!fn) continue\n      try {\n        await fn.apply(obs, args)\n      } catch (err) {\n        console.warn(`[agent-gateway] observer ${event} threw:`, err instanceof Error ? err.message : err)\n      }\n    }\n  }\n\n  onRequestStart = (ctx: RequestContext) => this.fanOut('onRequestStart', ctx)\n  onPaymentVerified = (ctx: RequestContext, info: Parameters<Required<GatewayObserver>['onPaymentVerified']>[1]) =>\n    this.fanOut('onPaymentVerified', ctx, info)\n  onAuthFailure = (ctx: RequestContext, reason: AuthFailureReason) =>\n    this.fanOut('onAuthFailure', ctx, reason)\n  onRateLimited = (ctx: RequestContext, info: Parameters<Required<GatewayObserver>['onRateLimited']>[1]) =>\n    this.fanOut('onRateLimited', ctx, info)\n  onBodyTooLarge = (ctx: RequestContext, contentLength: number) =>\n    this.fanOut('onBodyTooLarge', ctx, contentLength)\n  onInjectionDetected = (ctx: RequestContext, info: Parameters<Required<GatewayObserver>['onInjectionDetected']>[1]) =>\n    this.fanOut('onInjectionDetected', ctx, info)\n  onRequestComplete = (ctx: RequestContext, usage: GatewayUsageEvent) =>\n    this.fanOut('onRequestComplete', ctx, usage)\n  onStreamError = (ctx: RequestContext, info: Parameters<Required<GatewayObserver>['onStreamError']>[1]) =>\n    this.fanOut('onStreamError', ctx, info)\n  onSettlementError = (ctx: RequestContext, info: Parameters<Required<GatewayObserver>['onSettlementError']>[1]) =>\n    this.fanOut('onSettlementError', ctx, info)\n}\n\n/**\n * Generate a request-id. Crypto-random 16 bytes, hex-encoded with an `req_` prefix.\n * Works in Workers, Node, and browsers — all have globalThis.crypto.\n */\nexport function generateRequestId(): string {\n  const bytes = new Uint8Array(16)\n  globalThis.crypto.getRandomValues(bytes)\n  const hex = Array.from(bytes).map((b) => b.toString(16).padStart(2, '0')).join('')\n  return `req_${hex}`\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-J5SDVHOL.js

@@ -0,0 +1,104 @@
+// src/nonce-store.ts
+function nonceTtlSeconds(expiry, nowSeconds = Math.floor(Date.now() / 1e3)) {
+  const remaining = expiry - BigInt(nowSeconds);
+  if (remaining <= 0n || remaining > BigInt(Number.MAX_SAFE_INTEGER)) return void 0;
+  return Math.max(Number(remaining), 60);
+}
+var MemoryNonceStore = class {
+  seen = /* @__PURE__ */ new Map();
+  lastEviction = Date.now();
+  async hasSeen(nonce) {
+    this.evictExpired();
+    const entry = this.seen.get(nonce);
+    if (!entry) return false;
+    if (entry.expiresAt < Date.now()) {
+      this.seen.delete(nonce);
+      return false;
+    }
+    return true;
+  }
+  async claim(nonce, ttlSeconds, ownerId) {
+    this.evictExpired();
+    const now = Date.now();
+    const entry = this.seen.get(nonce);
+    if (entry !== void 0 && entry.expiresAt >= now) {
+      return ownerId !== void 0 && entry.ownerId === ownerId;
+    }
+    this.seen.set(nonce, { expiresAt: now + ttlSeconds * 1e3, ownerId });
+    return true;
+  }
+  async markSeen(nonce, ttlSeconds) {
+    this.evictExpired();
+    this.seen.set(nonce, { expiresAt: Date.now() + ttlSeconds * 1e3 });
+  }
+  evictExpired() {
+    const now = Date.now();
+    if (now - this.lastEviction < 6e4) return;
+    this.lastEviction = now;
+    for (const [nonce, entry] of this.seen) {
+      if (entry.expiresAt < now) this.seen.delete(nonce);
+    }
+  }
+};
+var KvNonceStore = class {
+  constructor(kv, prefix = "nonce", options = {}) {
+    this.kv = kv;
+    this.prefix = prefix;
+    this.atomicClaim = options.atomicClaim ?? (kv.putIfAbsent ? async (key, ttlSeconds, ownerId) => {
+      const value = ownerId ?? "1";
+      if (ownerId !== void 0) {
+        const existing = await kv.get(key);
+        if (existing !== null) return existing === ownerId;
+      }
+      const inserted = await kv.putIfAbsent(key, value, { expirationTtl: ttlSeconds });
+      if (inserted || ownerId === void 0) return inserted;
+      return await kv.get(key) === ownerId;
+    } : void 0);
+  }
+  kv;
+  prefix;
+  atomicClaim;
+  async hasSeen(nonce) {
+    return await this.kv.get(this.key(nonce)) !== null;
+  }
+  async markSeen(nonce, ttlSeconds) {
+    const ttl = Math.max(ttlSeconds, 60);
+    await this.kv.put(this.key(nonce), "1", { expirationTtl: ttl });
+  }
+  async claim(nonce, ttlSeconds, ownerId) {
+    if (!this.atomicClaim) {
+      throw new Error(
+        "KvNonceStore requires an atomicClaim backed by D1, Durable Objects, or an atomic KV extension"
+      );
+    }
+    const ttl = Math.max(ttlSeconds, 60);
+    return this.atomicClaim(this.key(nonce), ttl, ownerId);
+  }
+  /** Used by gateway validation to reject plain, non-atomic KV bindings. */
+  hasAtomicClaim() {
+    return this.atomicClaim !== void 0;
+  }
+  key(nonce) {
+    return `${this.prefix}:${nonce}`;
+  }
+};
+async function claimStoredNonce(store, nonce, ttlSeconds, ownerId) {
+  if (typeof store.claim !== "function") {
+    throw new Error("NonceStore.claim is required for atomic payment replay protection");
+  }
+  return store.claim(nonce, ttlSeconds, ownerId);
+}
+function isAtomicNonceStore(store) {
+  const kvStore = store;
+  if (typeof kvStore.hasAtomicClaim === "function" && !kvStore.hasAtomicClaim()) return false;
+  return typeof store.claim === "function";
+}
+
+export {
+  nonceTtlSeconds,
+  MemoryNonceStore,
+  KvNonceStore,
+  claimStoredNonce,
+  isAtomicNonceStore
+};
+//# sourceMappingURL=chunk-J5SDVHOL.js.map

package/dist/chunk-J5SDVHOL.js.map

@@ -0,0 +1 @@
+{"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. This method never grants ownership. */\n  hasSeen(nonce: string): Promise<boolean>\n  /**\n   * Atomically claim a nonce. An owner id makes a retry by the same payment\n   * operation idempotent. This is optional only for the 0.7.1 check-and-mark\n   * compatibility contract; durable owner claims require this method.\n   */\n  claim?(nonce: string, ttlSeconds: number, ownerId?: string): Promise<boolean>\n  /** @deprecated Use claim() for atomic ownership in new stores. */\n  markSeen?(nonce: string, ttlSeconds: number): Promise<void>\n}\n\nexport interface AtomicNonceStore extends NonceStore {\n  claim(nonce: string, ttlSeconds: number, ownerId?: string): Promise<boolean>\n}\n\n/**\n * Return the seconds for which a signed nonce must remain stored.\n *\n * The signed expiry is the replay boundary. A fixed one-hour cap would allow\n * a still-valid authorization to replay after the nonce entry expires.\n */\nexport function nonceTtlSeconds(\n  expiry: bigint,\n  nowSeconds = Math.floor(Date.now() / 1000),\n): number | undefined {\n  const remaining = expiry - BigInt(nowSeconds)\n  if (remaining <= 0n || remaining > BigInt(Number.MAX_SAFE_INTEGER)) return undefined\n  return Math.max(Number(remaining), 60)\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, { expiresAt: number; ownerId?: string }>()\n  private lastEviction = Date.now()\n\n  async hasSeen(nonce: string): Promise<boolean> {\n    this.evictExpired()\n    const entry = this.seen.get(nonce)\n    if (!entry) return false\n    if (entry.expiresAt < Date.now()) {\n      this.seen.delete(nonce)\n      return false\n    }\n    return true\n  }\n\n  async claim(nonce: string, ttlSeconds: number, ownerId?: string): Promise<boolean> {\n    this.evictExpired()\n    const now = Date.now()\n    const entry = this.seen.get(nonce)\n    if (entry !== undefined && entry.expiresAt >= now) {\n      return ownerId !== undefined && entry.ownerId === ownerId\n    }\n    this.seen.set(nonce, { expiresAt: now + ttlSeconds * 1000, ownerId })\n    return true\n  }\n\n  async markSeen(nonce: string, ttlSeconds: number): Promise<void> {\n    this.evictExpired()\n    this.seen.set(nonce, { expiresAt: Date.now() + ttlSeconds * 1000 })\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, entry] of this.seen) {\n      if (entry.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  /** Optional linearizable create-if-absent extension. Cloudflare KV does not provide it. */\n  putIfAbsent?(key: string, value: string, options?: { expirationTtl?: number }): Promise<boolean>\n  delete(key: string): Promise<void>\n}\n\n/** Atomic claim supplied by D1, a Durable Object, or another linearizable store. */\nexport type AtomicKvNonceClaim = (\n  key: string,\n  ttlSeconds: number,\n  ownerId?: string,\n) => Promise<boolean>\n\nexport interface KvNonceStoreOptions {\n  /**\n   * Claim the fully namespaced key atomically.\n   * The callback must make same-owner retries idempotent.\n   */\n  atomicClaim?: AtomicKvNonceClaim\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. Cloudflare KV has no conditional write, so a plain KV\n * binding is not an atomic payment store. Supply `atomicClaim` from D1,\n * Durable Objects, or another linearizable service before using this store\n * for paid requests.\n *\n * Usage:\n *   const nonceStore = new KvNonceStore(env.NONCE_KV, 'x402')\n *   createAgentGateway({ ...config, nonceStore })\n */\nexport class KvNonceStore implements NonceStore {\n  private readonly atomicClaim?: AtomicKvNonceClaim\n\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    options: KvNonceStoreOptions = {},\n  ) {\n    this.atomicClaim = options.atomicClaim ?? (\n      kv.putIfAbsent\n        ? async (key, ttlSeconds, ownerId) => {\n            const value = ownerId ?? '1'\n            if (ownerId !== undefined) {\n              const existing = await kv.get(key)\n              if (existing !== null) return existing === ownerId\n            }\n            const inserted = await kv.putIfAbsent!(key, value, { expirationTtl: ttlSeconds })\n            if (inserted || ownerId === undefined) return inserted\n            return (await kv.get(key)) === ownerId\n          }\n        : undefined\n    )\n  }\n\n  async hasSeen(nonce: string): Promise<boolean> {\n    return (await this.kv.get(this.key(nonce))) !== null\n  }\n\n  async markSeen(nonce: string, ttlSeconds: number): Promise<void> {\n    const ttl = Math.max(ttlSeconds, 60)\n    await this.kv.put(this.key(nonce), '1', { expirationTtl: ttl })\n  }\n\n  async claim(nonce: string, ttlSeconds: number, ownerId?: string): Promise<boolean> {\n    if (!this.atomicClaim) {\n      throw new Error(\n        'KvNonceStore requires an atomicClaim backed by D1, Durable Objects, or an atomic KV extension',\n      )\n    }\n    const ttl = Math.max(ttlSeconds, 60)\n    return this.atomicClaim(this.key(nonce), ttl, ownerId)\n  }\n\n  /** Used by gateway validation to reject plain, non-atomic KV bindings. */\n  hasAtomicClaim(): boolean {\n    return this.atomicClaim !== undefined\n  }\n\n  private key(nonce: string): string {\n    return `${this.prefix}:${nonce}`\n  }\n}\n\n/** Claim through the one atomic contract used by every payment path. */\nexport async function claimStoredNonce(\n  store: NonceStore,\n  nonce: string,\n  ttlSeconds: number,\n  ownerId?: string,\n): Promise<boolean> {\n  if (typeof store.claim !== 'function') {\n    throw new Error('NonceStore.claim is required for atomic payment replay protection')\n  }\n  return store.claim(nonce, ttlSeconds, ownerId)\n}\n\n/** Durable payment paths must use a store with a single atomic claim operation. */\nexport function isAtomicNonceStore(store: NonceStore): store is AtomicNonceStore {\n  const kvStore = store as NonceStore & { hasAtomicClaim?: () => boolean }\n  if (typeof kvStore.hasAtomicClaim === 'function' && !kvStore.hasAtomicClaim()) return false\n  return typeof store.claim === 'function'\n}\n"],"mappings":"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","names":[]}