@tangle-network/agent-gateway 0.7.1 → 0.8.1

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":[]}

package/dist/index.d.ts

@@ -1,17 +1,57 @@
 export { createAgentGateway } from './middleware.js';
-import { A as ApiKeyInfo, G as GatewayConfig, M as MppConfig, X as X402Config, C as ChatMessage } from './types-DEsMmS-X.js';
-export { a as A2A_ERROR_CODES, b as AgentCapabilities, c as AgentCard, d as AgentCardAuthentication, e as AgentMeta, f as AgentProvider, g as AgentSkill, h as Artifact, i as AuthFailureReason, j as ChatCompletionChunk, k as ChatCompletionRequest, l as CompositeObserver, m as ConsoleObserver, D as D1DatabaseLike, n as D1StmtLike, o as DataPart, F as FilePart, p as GatewayObserver, q as GatewayUsageEvent, I as InMemoryPushNotificationStore, r as InMemoryTaskStore, J as JSONRPCErrorResponse, s as JSONRPCRequest, t as JSONRPCResponse, u as JSONRPCSuccessResponse, v as Message, w as MessageSendParams, P as Part, x as PaymentMethod, y as PaymentResult, z as PushDeliveryResult, B as PushNotificationAuthentication, E as PushNotificationConfig, H as PushNotificationStore, R as RequestContext, S as SandboxBox, K as SandboxStreamEvent, L as SqlAdapter, N as SqlPushNotificationStore, O as SqlTaskStore, Q as StreamingEvent, T as Task, U as TaskArtifactUpdateEvent, V as TaskIdParams, W as TaskPushNotificationConfig, Y as TaskPushNotificationConfigGetParams, Z as TaskState, _ as TaskStatus, $ as TaskStatusUpdateEvent, a0 as TaskStore, a1 as TextPart, a2 as d1ToSqlAdapter, a3 as deliverPushNotifications, a4 as generateRequestId } from './types-DEsMmS-X.js';
+import { G as GatewayConfig, P as PaymentOperationRecoveryResult, a as PaymentRecoveryRecord, M as MppAuthenticatedCredential, A as ApiKeyInfo, b as MppConfig, X as X402Config, c as PaymentRecoveryStore, S as SqlAdapter, C as ChatMessage } from './types-oQ58UakD.js';
+export { d as A2A_ERROR_CODES, e as AgentCapabilities, f as AgentCard, g as AgentCardAuthentication, h as AgentMeta, i as AgentProvider, j as AgentSkill, k as ApiKeyGatewayConfig, l as Artifact, m as ChatCompletionChunk, n as ChatCompletionRequest, o as CreateAgentGatewayConfig, D as D1DatabaseLike, p as D1StmtLike, q as DataPart, F as FilePart, I as InMemoryPushNotificationStore, r as InMemoryTaskStore, J as JSONRPCErrorResponse, s as JSONRPCRequest, t as JSONRPCResponse, u as JSONRPCSuccessResponse, v as MPP_CHARGE_PROTOCOL_VERSION, w as MemoryPaymentOperations, x as MemoryPaymentOperationsOptions, y as MemoryPaymentRecoveryStore, z as Message, B as MessageSendParams, E as MppChargeLifecycle, H as MppChargeOperation, K as MppChargeOperationState, L as MppChargeRecoveryResult, N as MppChargeRequest, O as PAYMENT_PROTOCOL_VERSION, Q as PAYMENT_RECOVERY_VERSION, R as Part, T as PaymentAuthorizationContext, U as PaymentOperation, V as PaymentOperationNotFound, W as PaymentOperationState, Y as PaymentOperations, Z as PaymentRecoveryAttribution, _ as PaymentRecoveryConfig, $ as PaymentRecoveryFenceError, a0 as PaymentRecoveryState, a1 as PaymentRecoveryTarget, a2 as PaymentResult, a3 as PaymentSettlementInput, a4 as PushDeliveryResult, a5 as PushNotificationAuthentication, a6 as PushNotificationConfig, a7 as PushNotificationDeliveryOptions, a8 as PushNotificationStore, a9 as SandboxBox, aa as SandboxStreamEvent, ab as SqlPushNotificationStore, ac as SqlTaskStore, ad as StreamingEvent, ae as Task, af as TaskArtifactUpdateEvent, ag as TaskIdParams, ah as TaskPushNotificationConfig, ai as TaskPushNotificationConfigGetParams, aj as TaskState, ak as TaskStatus, al as TaskStatusUpdateEvent, am as TaskStore, an as TextPart, ao as d1ToSqlAdapter, ap as deliverDemoPushNotifications, aq as deliverPushNotifications, ar as mppPaymentOperationId, as as validatePushNotificationUrl } from './types-oQ58UakD.js';
 import { NonceStore } from './nonce-store.js';
-export { KvNonceStore, MemoryNonceStore } from './nonce-store.js';
+export { AtomicKvNonceClaim, AtomicNonceStore, KvNonceStore, KvNonceStoreOptions, MemoryNonceStore, isAtomicNonceStore } from './nonce-store.js';
+export { CompositeObserver, ConsoleObserver, generateRequestId } from './observer.js';
 export { KvRateLimitStore, MemoryRateLimitStore, RateLimitConfig, RateLimitResult, RateLimitStore, checkRateLimit } from './rate-limit.js';
+import { S as SandboxUsageReceipt } from './observer-types-A0RtA8uL.js';
+export { A as AuthFailureReason, G as GatewayObserver, a as GatewayUsageEvent, P as PaymentMethod, b as PaymentSettlementBasis, R as RequestContext, c as SandboxExecutionBudget } from './observer-types-A0RtA8uL.js';
 export { ApiKey, ApiKeyCreateRequest, ApiKeyRoutesConfig, ApiKeyStore, createApiKeyRoutes, verifyApiKeyFromStore } from './api-keys.js';
 export { PublishRequest, PublishRoutesConfig, PublishStore, PublishedConfig, createPublishRoutes } from './publish.js';
 import 'hono/types';
 import 'hono';
 
+declare function reclaimPayment(operationId: string, config: GatewayConfig): Promise<PaymentOperationRecoveryResult>;
+
+interface RecoveryWorkerOptions {
+    now?: number;
+    /** Fresh wall-clock source for each row's lease and retry timestamps. */
+    clock?: () => number;
+    workerId?: string;
+}
+interface RecoverPaymentOptions extends RecoveryWorkerOptions {
+    /** Process one requested row even when its normal retry time is later. */
+    force?: boolean;
+    /** Exact receipt recovered from a durable protocol record, such as an A2A task. */
+    usage?: SandboxUsageReceipt;
+}
+/** Batch recovery never accepts receipt data because each receipt belongs to one row. */
+interface RecoverPaymentsOptions extends RecoveryWorkerOptions {
+    limit?: number;
+}
+interface PaymentRecoveryRun {
+    scanned: number;
+    reconciled: number;
+    deferred: number;
+    failed: number;
+}
+/** Scan and reconcile due payment rows. Safe to run concurrently on many workers. */
+declare function recoverPayments(config: GatewayConfig, options?: RecoverPaymentsOptions): Promise<PaymentRecoveryRun>;
+/** Reconcile one payment identity. Hosts can expose this through a private worker API. */
+declare function recoverPayment(recoveryId: string, config: GatewayConfig, options?: RecoverPaymentOptions): Promise<PaymentRecoveryRecord | undefined>;
+
+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. */
+declare function mppReplayNonceKey(authHeader: string): string | undefined;
+/** Return the decoded method credential for the post-guard charge lifecycle. */
+declare function mppPaymentCredential(authHeader: string): string | undefined;
 /** Pure capability checks shared by discovery and every request protocol. */
 declare function isApiKeyAuthEnabled(config: Pick<GatewayConfig, 'verifyApiKey' | 'x402'>): boolean;
-/** MPP is enabled only when a real verifier or explicit demo mode exists. */
+/** MPP is enabled only when authentication and method settlement are complete. */
 declare function isMppAuthEnabled(config: Pick<GatewayConfig, 'mpp' | 'x402'>): boolean;
 /**
  * Verify x402 SpendAuth signature (EIP-712).
@@ -24,25 +64,45 @@ declare function isMppAuthEnabled(config: Pick<GatewayConfig, 'mpp' | 'x402'>):
  *   neither                      — rejected by createAgentGateway and
  *                                  by this function as defense-in-depth.
  */
-declare function verifyX402(spendAuthHeader: string, config: X402Config, nonceStore?: NonceStore): Promise<string | null>;
+declare function verifyX402(spendAuthHeader: string, config: X402Config, nonceStore?: NonceStore, minimumAmount?: bigint, markNonce?: boolean): Promise<string | null>;
 /**
  * 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.
  */
-declare function verifyMpp(authHeader: string, config: MppConfig, x402Config: X402Config, nonceStore?: NonceStore): Promise<string | null>;
+declare function verifyMppCredential(authHeader: string, config: MppConfig, x402Config: X402Config, nonceStore?: NonceStore, minimumAmount?: bigint, markNonce?: boolean): Promise<VerifiedMppCredential | null>;
+/**
+ * Verify an MPP credential using the 0.7.1 public return shape.
+ * Rich durable callers use verifyMppCredential instead.
+ */
+declare function verifyMpp(authHeader: string, config: MppConfig, x402Config: X402Config, nonceStore?: NonceStore, minimumAmount?: bigint, markNonce?: boolean): Promise<string | null>;
 /**
  * Default API key verifier — accepts any `sk_agent_*` key (demo mode).
  * Override in GatewayConfig.verifyApiKey for production.
  */
 declare function defaultVerifyApiKey(authHeader: string): Promise<ApiKeyInfo | null>;
 
+/** Durable recovery outbox for D1, sqlite, libSQL, or an adapted SQL driver. */
+declare class SqlPaymentRecoveryStore implements PaymentRecoveryStore {
+    private readonly db;
+    private readonly table;
+    constructor(db: SqlAdapter, options?: {
+        table?: string;
+    });
+    /** Idempotent. Run this before the gateway starts accepting traffic. */
+    migrate(): Promise<void>;
+    createIfAbsent(record: PaymentRecoveryRecord): Promise<boolean>;
+    get(id: string): Promise<PaymentRecoveryRecord | undefined>;
+    compareAndSet(expected: PaymentRecoveryRecord, next: PaymentRecoveryRecord): Promise<boolean>;
+    listDue(now: number, limit: number): Promise<PaymentRecoveryRecord[]>;
+}
+
 /**
  * Detect prompt injection attempts.
  * Returns array of matched pattern descriptions, empty if clean.
@@ -85,4 +145,4 @@ declare function filterConsumerMessagesStrict(messages: ChatMessage[], maxLength
  */
 declare function redactSystemPromptFromOutput(output: string, systemPrompt: string | undefined): string;
 
-export { ApiKeyInfo, ChatMessage, GatewayConfig, MppConfig, NonceStore, X402Config, defaultVerifyApiKey, detectInjection, filterConsumerMessages, filterConsumerMessagesStrict, isApiKeyAuthEnabled, isMppAuthEnabled, redactSystemPromptFromOutput, verifyMpp, verifyX402 };
+export { ApiKeyInfo, ChatMessage, GatewayConfig, MppAuthenticatedCredential, MppConfig, NonceStore, PaymentOperationRecoveryResult, PaymentRecoveryRecord, type PaymentRecoveryRun, PaymentRecoveryStore, type RecoverPaymentOptions, type RecoverPaymentsOptions, SandboxUsageReceipt, SqlAdapter, SqlPaymentRecoveryStore, type VerifiedMppCredential, X402Config, defaultVerifyApiKey, detectInjection, filterConsumerMessages, filterConsumerMessagesStrict, isApiKeyAuthEnabled, isMppAuthEnabled, mppPaymentCredential, mppReplayNonceKey, reclaimPayment, recoverPayment, recoverPayments, redactSystemPromptFromOutput, verifyMpp, verifyMppCredential, verifyX402 };