@tangle-network/agent-gateway 0.7.1 → 0.8.0

package/dist/nonce-store.d.ts

@@ -3,16 +3,33 @@
  * Tracks seen nonces to prevent the same payment from being used twice.
  */
 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>;
+}
+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.
+ */
+declare function nonceTtlSeconds(expiry: bigint, nowSeconds?: number): number | undefined;
 /** In-memory nonce store with automatic eviction. Use in tests or single-worker deploys. */
 declare class MemoryNonceStore implements NonceStore {
     private seen;
     private lastEviction;
     hasSeen(nonce: string): Promise<boolean>;
+    claim(nonce: string, ttlSeconds: number, ownerId?: string): Promise<boolean>;
     markSeen(nonce: string, ttlSeconds: number): Promise<void>;
     private evictExpired;
 }
@@ -28,20 +45,31 @@ interface KVNamespace {
     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. */
+type AtomicKvNonceClaim = (key: string, ttlSeconds: number, ownerId?: string) => Promise<boolean>;
+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')
@@ -51,12 +79,20 @@ declare class KvNonceStore implements NonceStore {
     private readonly kv;
     /** Key prefix to namespace within a shared KV (default: "nonce"). */
     private readonly prefix;
+    private readonly atomicClaim?;
     constructor(kv: KVNamespace, 
     /** Key prefix to namespace within a shared KV (default: "nonce"). */
-    prefix?: string);
+    prefix?: string, options?: KvNonceStoreOptions);
     hasSeen(nonce: string): Promise<boolean>;
     markSeen(nonce: string, ttlSeconds: number): Promise<void>;
+    claim(nonce: string, ttlSeconds: number, ownerId?: string): Promise<boolean>;
+    /** Used by gateway validation to reject plain, non-atomic KV bindings. */
+    hasAtomicClaim(): boolean;
     private key;
 }
+/** Claim through the one atomic contract used by every payment path. */
+declare function claimStoredNonce(store: NonceStore, nonce: string, ttlSeconds: number, ownerId?: string): Promise<boolean>;
+/** Durable payment paths must use a store with a single atomic claim operation. */
+declare function isAtomicNonceStore(store: NonceStore): store is AtomicNonceStore;
 
-export { type KVNamespace, KvNonceStore, MemoryNonceStore, type NonceStore };
+export { type AtomicKvNonceClaim, type AtomicNonceStore, type KVNamespace, KvNonceStore, type KvNonceStoreOptions, MemoryNonceStore, type NonceStore, claimStoredNonce, isAtomicNonceStore, nonceTtlSeconds };

package/dist/nonce-store.js

@@ -1,9 +1,15 @@
 import {
   KvNonceStore,
-  MemoryNonceStore
-} from "./chunk-M7ZJAK4K.js";
+  MemoryNonceStore,
+  claimStoredNonce,
+  isAtomicNonceStore,
+  nonceTtlSeconds
+} from "./chunk-J5SDVHOL.js";
 export {
   KvNonceStore,
-  MemoryNonceStore
+  MemoryNonceStore,
+  claimStoredNonce,
+  isAtomicNonceStore,
+  nonceTtlSeconds
 };
 //# sourceMappingURL=nonce-store.js.map

package/dist/observer-types-A0RtA8uL.d.ts

@@ -0,0 +1,95 @@
+type PaymentMethod = 'x402' | 'mpp' | 'apikey' | 'none';
+interface SandboxExecutionBudget {
+    maxInputTokens: number;
+    maxOutputTokens: number;
+    maxReasoningTokens: number;
+    maxToolTokens: number;
+    maxToolCalls: number;
+    maxProviderCostUsd: number;
+}
+interface SandboxUsageReceipt {
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    toolTokens: number;
+    toolCallCount: number;
+    providerCostUsd: number;
+    /** True only when the provider/adapter enforced every supplied budget. */
+    budgetEnforced: boolean;
+}
+type PaymentSettlementBasis = 'usage-receipt' | 'quoted-ceiling';
+interface GatewayUsageEvent {
+    /** Correlates usage, settlement, and observer records for one request. */
+    requestId: string;
+    agentId: string;
+    agentSlug: string;
+    consumerId: string;
+    paymentMethod: PaymentMethod;
+    inputTokens: number;
+    outputTokens: number;
+    /** Optional in 0.7.2 so 0.7.1 event constructors remain source-compatible. */
+    reasoningTokens?: number;
+    /** Optional in 0.7.2 so 0.7.1 event constructors remain source-compatible. */
+    toolTokens?: number;
+    /** Optional in 0.7.2 so 0.7.1 event constructors remain source-compatible. */
+    toolCallCount?: number;
+    /** Optional in 0.7.2 so 0.7.1 event constructors remain source-compatible. */
+    providerCostUsd?: number;
+    totalCostUsd: number;
+    ownerEarnedUsd: number;
+    platformFeeUsd: number;
+    durationMs: number;
+    /** Exact receipt in normal operation; quoted ceiling only after receipt timeout. */
+    settlementBasis?: PaymentSettlementBasis;
+}
+
+interface RequestContext {
+    requestId: string;
+    agentSlug: string;
+    startMs: number;
+}
+interface AuthFailureReason {
+    method: PaymentMethod;
+    code: string;
+    httpStatus: number;
+}
+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>;
+}
+
+export type { AuthFailureReason as A, GatewayObserver as G, PaymentMethod as P, RequestContext as R, SandboxUsageReceipt as S, GatewayUsageEvent as a, PaymentSettlementBasis as b, SandboxExecutionBudget as c };

package/dist/observer.d.ts

@@ -0,0 +1,79 @@
+import { G as GatewayObserver, R as RequestContext, A as AuthFailureReason, a as GatewayUsageEvent, P as PaymentMethod } from './observer-types-A0RtA8uL.js';
+
+/**
+ * Observability hook surface.
+ *
+ * Consumers implement GatewayObserver to wire the gateway into their existing
+ * telemetry stack (Langfuse, OTEL, structured logs, Prometheus, etc.) without
+ * the gateway itself depending on any of those libraries.
+ *
+ * Every event carries a requestId so downstream metrics can correlate the
+ * payment verification, sandbox execution, and settlement for one request.
+ * When no observer is configured, the gateway stays silent.
+ */
+
+/**
+ * Structured-log observer. Emits one JSON line per event on the `log` function.
+ * Default sink: console.log. Production consumers usually pipe their own
+ * structured logger (pino, winston, the cf Logs binding).
+ *
+ * Usage:
+ *   new ConsoleObserver(({ level, event, ...rest }) => logger.info({ event, ...rest }))
+ */
+declare class ConsoleObserver implements GatewayObserver {
+    private readonly log;
+    constructor(log?: (entry: Record<string, unknown>) => void);
+    private emit;
+    onRequestStart(ctx: RequestContext): void;
+    onPaymentVerified(ctx: RequestContext, info: {
+        method: PaymentMethod;
+        consumerId: string;
+        keyId?: string;
+    }): void;
+    onAuthFailure(ctx: RequestContext, reason: AuthFailureReason): void;
+    onRateLimited(ctx: RequestContext, info: {
+        consumerId: string;
+        retryAfterSeconds: number;
+    }): void;
+    onBodyTooLarge(ctx: RequestContext, contentLength: number): void;
+    onInjectionDetected(ctx: RequestContext, info: {
+        consumerId: string;
+        patterns: string[];
+        blocked: boolean;
+    }): void;
+    onRequestComplete(ctx: RequestContext, usage: GatewayUsageEvent): void;
+    onStreamError(ctx: RequestContext, info: {
+        consumerId: string;
+        errorMessage: string;
+    }): void;
+    onSettlementError(ctx: RequestContext, info: {
+        consumerId: string;
+        method: PaymentMethod;
+        errorMessage: string;
+    }): void;
+}
+/**
+ * Compose multiple observers into one. Errors in any individual observer
+ * don't break the others (fire-and-forget telemetry).
+ */
+declare class CompositeObserver implements GatewayObserver {
+    private readonly observers;
+    constructor(observers: GatewayObserver[]);
+    private fanOut;
+    onRequestStart: (ctx: RequestContext) => Promise<void>;
+    onPaymentVerified: (ctx: RequestContext, info: Parameters<Required<GatewayObserver>["onPaymentVerified"]>[1]) => Promise<void>;
+    onAuthFailure: (ctx: RequestContext, reason: AuthFailureReason) => Promise<void>;
+    onRateLimited: (ctx: RequestContext, info: Parameters<Required<GatewayObserver>["onRateLimited"]>[1]) => Promise<void>;
+    onBodyTooLarge: (ctx: RequestContext, contentLength: number) => Promise<void>;
+    onInjectionDetected: (ctx: RequestContext, info: Parameters<Required<GatewayObserver>["onInjectionDetected"]>[1]) => Promise<void>;
+    onRequestComplete: (ctx: RequestContext, usage: GatewayUsageEvent) => Promise<void>;
+    onStreamError: (ctx: RequestContext, info: Parameters<Required<GatewayObserver>["onStreamError"]>[1]) => Promise<void>;
+    onSettlementError: (ctx: RequestContext, info: Parameters<Required<GatewayObserver>["onSettlementError"]>[1]) => Promise<void>;
+}
+/**
+ * Generate a request-id. Crypto-random 16 bytes, hex-encoded with an `req_` prefix.
+ * Works in Workers, Node, and browsers — all have globalThis.crypto.
+ */
+declare function generateRequestId(): string;
+
+export { AuthFailureReason, CompositeObserver, ConsoleObserver, GatewayObserver, RequestContext, generateRequestId };

package/dist/observer.js

@@ -0,0 +1,11 @@
+import {
+  CompositeObserver,
+  ConsoleObserver,
+  generateRequestId
+} from "./chunk-GITV7CPT.js";
+export {
+  CompositeObserver,
+  ConsoleObserver,
+  generateRequestId
+};
+//# sourceMappingURL=observer.js.map

package/dist/observer.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}