@tangle-network/agent-gateway 0.7.0 → 0.8.0

package/src/nonce-store.ts

@@ -4,10 +4,35 @@
  */
 
 export interface NonceStore {
-  /** Check if nonce has been seen. Returns true if already used (reject). */
+  /** Check if nonce has been seen. This method never grants ownership. */
   hasSeen(nonce: string): Promise<boolean>
-  /** Mark nonce as used. TTL = how long to remember it (seconds). */
-  markSeen(nonce: string, ttlSeconds: number): Promise<void>
+  /**
+   * Atomically claim a nonce. An owner id makes a retry by the same payment
+   * operation idempotent. This is optional only for the 0.7.1 check-and-mark
+   * compatibility contract; durable owner claims require this method.
+   */
+  claim?(nonce: string, ttlSeconds: number, ownerId?: string): Promise<boolean>
+  /** @deprecated Use claim() for atomic ownership in new stores. */
+  markSeen?(nonce: string, ttlSeconds: number): Promise<void>
+}
+
+export interface AtomicNonceStore extends NonceStore {
+  claim(nonce: string, ttlSeconds: number, ownerId?: string): Promise<boolean>
+}
+
+/**
+ * Return the seconds for which a signed nonce must remain stored.
+ *
+ * The signed expiry is the replay boundary. A fixed one-hour cap would allow
+ * a still-valid authorization to replay after the nonce entry expires.
+ */
+export function nonceTtlSeconds(
+  expiry: bigint,
+  nowSeconds = Math.floor(Date.now() / 1000),
+): number | undefined {
+  const remaining = expiry - BigInt(nowSeconds)
+  if (remaining <= 0n || remaining > BigInt(Number.MAX_SAFE_INTEGER)) return undefined
+  return Math.max(Number(remaining), 60)
 }
 
 // ---------------------------------------------------------------------------
@@ -16,23 +41,34 @@ export interface NonceStore {
 
 /** In-memory nonce store with automatic eviction. Use in tests or single-worker deploys. */
 export class MemoryNonceStore implements NonceStore {
-  private seen = new Map<string, number>() // nonce → expiresAt
+  private seen = new Map<string, { expiresAt: number; ownerId?: string }>()
   private lastEviction = Date.now()
 
   async hasSeen(nonce: string): Promise<boolean> {
     this.evictExpired()
-    const expiresAt = this.seen.get(nonce)
-    if (!expiresAt) return false
-    if (expiresAt < Date.now()) {
+    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: string, ttlSeconds: number, ownerId?: string): Promise<boolean> {
+    this.evictExpired()
+    const now = Date.now()
+    const entry = this.seen.get(nonce)
+    if (entry !== undefined && entry.expiresAt >= now) {
+      return ownerId !== undefined && entry.ownerId === ownerId
+    }
+    this.seen.set(nonce, { expiresAt: now + ttlSeconds * 1000, ownerId })
+    return true
+  }
+
   async markSeen(nonce: string, ttlSeconds: number): Promise<void> {
-    this.seen.set(nonce, Date.now() + ttlSeconds * 1000)
     this.evictExpired()
+    this.seen.set(nonce, { expiresAt: Date.now() + ttlSeconds * 1000 })
   }
 
   private evictExpired() {
@@ -40,8 +76,8 @@ export class MemoryNonceStore implements NonceStore {
     // Evict at most every 60 seconds to avoid O(n) on every request
     if (now - this.lastEviction < 60_000) return
     this.lastEviction = now
-    for (const [nonce, expiresAt] of this.seen) {
-      if (expiresAt < now) this.seen.delete(nonce)
+    for (const [nonce, entry] of this.seen) {
+      if (entry.expiresAt < now) this.seen.delete(nonce)
     }
   }
 }
@@ -58,45 +94,111 @@ export class MemoryNonceStore implements NonceStore {
 export interface KVNamespace {
   get(key: string, options?: { type?: 'text' | 'json' }): Promise<string | null>
   put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>
+  /** Optional linearizable create-if-absent extension. Cloudflare KV does not provide it. */
+  putIfAbsent?(key: string, value: string, options?: { expirationTtl?: number }): Promise<boolean>
   delete(key: string): Promise<void>
 }
 
+/** Atomic claim supplied by D1, a Durable Object, or another linearizable store. */
+export type AtomicKvNonceClaim = (
+  key: string,
+  ttlSeconds: number,
+  ownerId?: string,
+) => Promise<boolean>
+
+export interface KvNonceStoreOptions {
+  /**
+   * Claim the fully namespaced key atomically.
+   * The callback must make same-owner retries idempotent.
+   */
+  atomicClaim?: AtomicKvNonceClaim
+}
+
 /**
  * KV-backed NonceStore for distributed Cloudflare Workers deployments.
  *
  * Why this exists: MemoryNonceStore works on a single worker instance, but
  * Cloudflare routes requests across multiple isolates. Without shared state,
  * an attacker could retry a replayed nonce against a different isolate and
- * have it accepted. This implementation uses Workers KV with native TTL so
- * the nonce automatically expires at payment-expiry time.
- *
- * TTL precision: KV is eventually consistent (propagation ~60s). For x402
- * with 10-minute expiry windows this is fine — by the time KV propagates,
- * the payment itself would be expired anyway.
+ * have it accepted. Cloudflare KV has no conditional write, so a plain KV
+ * binding is not an atomic payment store. Supply `atomicClaim` from D1,
+ * Durable Objects, or another linearizable service before using this store
+ * for paid requests.
  *
  * Usage:
  *   const nonceStore = new KvNonceStore(env.NONCE_KV, 'x402')
  *   createAgentGateway({ ...config, nonceStore })
  */
 export class KvNonceStore implements NonceStore {
+  private readonly atomicClaim?: AtomicKvNonceClaim
+
   constructor(
     private readonly kv: KVNamespace,
     /** Key prefix to namespace within a shared KV (default: "nonce"). */
     private readonly prefix: string = 'nonce',
-  ) {}
+    options: KvNonceStoreOptions = {},
+  ) {
+    this.atomicClaim = options.atomicClaim ?? (
+      kv.putIfAbsent
+        ? async (key, ttlSeconds, ownerId) => {
+            const value = ownerId ?? '1'
+            if (ownerId !== undefined) {
+              const existing = await kv.get(key)
+              if (existing !== null) return existing === ownerId
+            }
+            const inserted = await kv.putIfAbsent!(key, value, { expirationTtl: ttlSeconds })
+            if (inserted || ownerId === undefined) return inserted
+            return (await kv.get(key)) === ownerId
+          }
+        : undefined
+    )
+  }
 
   async hasSeen(nonce: string): Promise<boolean> {
-    const value = await this.kv.get(this.key(nonce))
-    return value !== null
+    return (await this.kv.get(this.key(nonce))) !== null
   }
 
   async markSeen(nonce: string, ttlSeconds: number): Promise<void> {
-    // KV minimum TTL is 60 seconds
     const ttl = Math.max(ttlSeconds, 60)
     await this.kv.put(this.key(nonce), '1', { expirationTtl: ttl })
   }
 
+  async claim(nonce: string, ttlSeconds: number, ownerId?: string): Promise<boolean> {
+    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(): boolean {
+    return this.atomicClaim !== undefined
+  }
+
   private key(nonce: string): string {
     return `${this.prefix}:${nonce}`
   }
 }
+
+/** Claim through the one atomic contract used by every payment path. */
+export async function claimStoredNonce(
+  store: NonceStore,
+  nonce: string,
+  ttlSeconds: number,
+  ownerId?: string,
+): Promise<boolean> {
+  if (typeof store.claim !== 'function') {
+    throw new Error('NonceStore.claim is required for atomic payment replay protection')
+  }
+  return store.claim(nonce, ttlSeconds, ownerId)
+}
+
+/** Durable payment paths must use a store with a single atomic claim operation. */
+export function isAtomicNonceStore(store: NonceStore): store is AtomicNonceStore {
+  const kvStore = store as NonceStore & { hasAtomicClaim?: () => boolean }
+  if (typeof kvStore.hasAtomicClaim === 'function' && !kvStore.hasAtomicClaim()) return false
+  return typeof store.claim === 'function'
+}

package/src/observer-types.ts

@@ -0,0 +1,63 @@
+import type {
+  GatewayUsageEvent,
+  PaymentMethod,
+} from './payment-types'
+
+export interface RequestContext {
+  requestId: string
+  agentSlug: string
+  startMs: number
+}
+
+export interface AuthFailureReason {
+  method: PaymentMethod
+  code: string
+  httpStatus: number
+}
+
+export interface GatewayObserver {
+  /** Called at the start of every chat completions POST. */
+  onRequestStart?: (ctx: RequestContext) => void | Promise<void>
+
+  /** Called when a payment method has been successfully verified. */
+  onPaymentVerified?: (ctx: RequestContext, info: {
+    method: PaymentMethod
+    consumerId: string
+    keyId?: string
+  }) => void | Promise<void>
+
+  /** Called when auth fails — every branch. */
+  onAuthFailure?: (ctx: RequestContext, reason: AuthFailureReason) => void | Promise<void>
+
+  /** Called when a consumer hits the rate limit. */
+  onRateLimited?: (ctx: RequestContext, info: {
+    consumerId: string
+    retryAfterSeconds: number
+  }) => void | Promise<void>
+
+  /** Called when the request body exceeds the 64KB limit. */
+  onBodyTooLarge?: (ctx: RequestContext, contentLength: number) => void | Promise<void>
+
+  /** Called when prompt-injection patterns are detected. */
+  onInjectionDetected?: (ctx: RequestContext, info: {
+    consumerId: string
+    patterns: string[]
+    blocked: boolean
+  }) => void | Promise<void>
+
+  /** Called after a successful stream completes and recordUsage has fired. */
+  onRequestComplete?: (ctx: RequestContext, usage: GatewayUsageEvent) => void | Promise<void>
+
+  /** Called when the sandbox throws. The error message is pre-scrubbed. */
+  onStreamError?: (ctx: RequestContext, info: {
+    consumerId: string
+    errorMessage: string
+  }) => void | Promise<void>
+
+  /** Called when settlement fails. Payment already occurred; this is async bookkeeping. */
+  onSettlementError?: (ctx: RequestContext, info: {
+    consumerId: string
+    method: PaymentMethod
+    errorMessage: string
+  }) => void | Promise<void>
+}

package/src/observer.ts

@@ -10,70 +10,10 @@
  * When no observer is configured, the gateway stays silent.
  */
 
-import type { PaymentMethod, GatewayUsageEvent } from './types'
+import type { GatewayUsageEvent, PaymentMethod } from './payment-types'
+import type { AuthFailureReason, GatewayObserver, RequestContext } from './observer-types'
 
-export interface RequestContext {
-  requestId: string
-  agentSlug: string
-  startMs: number
-}
-
-export interface AuthFailureReason {
-  method: 'x402' | 'mpp' | 'apikey' | 'none'
-  code: string
-  httpStatus: number
-}
-
-export interface GatewayObserver {
-  /** Called at the start of every chat completions POST. */
-  onRequestStart?: (ctx: RequestContext) => void | Promise<void>
-
-  /** Called when a payment method has been successfully verified. */
-  onPaymentVerified?: (ctx: RequestContext, info: {
-    method: PaymentMethod
-    consumerId: string
-    keyId?: string
-  }) => void | Promise<void>
-
-  /** Called when auth fails — every branch. */
-  onAuthFailure?: (ctx: RequestContext, reason: AuthFailureReason) => void | Promise<void>
-
-  /** Called when a consumer hits the rate limit. */
-  onRateLimited?: (ctx: RequestContext, info: {
-    consumerId: string
-    retryAfterSeconds: number
-  }) => void | Promise<void>
-
-  /** Called when the request body exceeds the 64KB limit. */
-  onBodyTooLarge?: (ctx: RequestContext, contentLength: number) => void | Promise<void>
-
-  /**
-   * Called when prompt-injection patterns are detected.
-   * `blocked` is true when blockInjection config is on and the request was
-   * rejected; false when the patterns were logged but the request proceeded.
-   */
-  onInjectionDetected?: (ctx: RequestContext, info: {
-    consumerId: string
-    patterns: string[]
-    blocked: boolean
-  }) => void | Promise<void>
-
-  /** Called after a successful stream completes and recordUsage has fired. */
-  onRequestComplete?: (ctx: RequestContext, usage: GatewayUsageEvent) => void | Promise<void>
-
-  /** Called when the sandbox throws. The error message is pre-scrubbed. */
-  onStreamError?: (ctx: RequestContext, info: {
-    consumerId: string
-    errorMessage: string
-  }) => void | Promise<void>
-
-  /** Called when settlement fails. Payment already occurred; this is async bookkeeping. */
-  onSettlementError?: (ctx: RequestContext, info: {
-    consumerId: string
-    method: PaymentMethod
-    errorMessage: string
-  }) => void | Promise<void>
-}
+export type { AuthFailureReason, GatewayObserver, RequestContext } from './observer-types'
 
 // ---------------------------------------------------------------------------
 // Convenience implementations