@tangle-network/agent-gateway 0.2.0 → 0.3.0

package/dist/rate-limit.d.ts

@@ -1,6 +1,9 @@
 /**
- * Sliding window rate limiter.
- * In-memory by default. Override with KV-backed store for Workers.
+ * Sliding-window rate limiter.
+ *
+ * Two implementations:
+ *   - MemoryRateLimitStore — single-worker, ephemeral, good for tests
+ *   - KvRateLimitStore     — Cloudflare Workers KV, distributed
  */
 interface RateLimitConfig {
     /** Max requests per window (default: 60) */
@@ -28,6 +31,35 @@ declare class MemoryRateLimitStore implements RateLimitStore {
     set(key: string, timestamps: number[], ttlSeconds: number): Promise<void>;
     private evictExpired;
 }
+/** Minimal KV shape — see nonce-store.ts for rationale. */
+interface KVNamespace {
+    get(key: string, options?: {
+        type?: 'text' | 'json';
+    }): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * KV-backed RateLimitStore for distributed Cloudflare Workers deployments.
+ *
+ * Stores timestamp arrays per consumer. Reads are O(1); writes replace the
+ * full array (cap is already filtered by checkRateLimit before write).
+ *
+ * Consistency note: Workers KV is eventually consistent within ~60s. An
+ * attacker sitting on two isolates could technically exceed the limit by
+ * ~2x for that window. For payment rate limits this is acceptable; for
+ * abuse prevention on free endpoints consider Durable Objects instead.
+ */
+declare class KvRateLimitStore implements RateLimitStore {
+    private readonly kv;
+    private readonly prefix;
+    constructor(kv: KVNamespace, prefix?: string);
+    get(key: string): Promise<number[]>;
+    set(key: string, timestamps: number[], ttlSeconds: number): Promise<void>;
+    private key;
+}
 declare function checkRateLimit(consumerId: string, config: RateLimitConfig, store: RateLimitStore): Promise<RateLimitResult>;
 
-export { MemoryRateLimitStore, type RateLimitConfig, type RateLimitResult, type RateLimitStore, checkRateLimit };
+export { type KVNamespace, KvRateLimitStore, MemoryRateLimitStore, type RateLimitConfig, type RateLimitResult, type RateLimitStore, checkRateLimit };

package/dist/rate-limit.js

@@ -1,8 +1,10 @@
 import {
+  KvRateLimitStore,
   MemoryRateLimitStore,
   checkRateLimit
-} from "./chunk-4FULF5LW.js";
+} from "./chunk-XCTXHZ76.js";
 export {
+  KvRateLimitStore,
   MemoryRateLimitStore,
   checkRateLimit
 };

package/dist/types-14xV8J4G.d.ts

@@ -0,0 +1,292 @@
+import { NonceStore } from './nonce-store.js';
+import { RateLimitStore } from './rate-limit.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.
+ */
+
+interface RequestContext {
+    requestId: string;
+    agentSlug: string;
+    startMs: number;
+}
+interface AuthFailureReason {
+    method: 'x402' | 'mpp' | 'apikey' | 'none';
+    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.
+     * `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>;
+}
+/**
+ * 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;
+
+interface AgentMeta {
+    /** Unique agent identifier (workspace ID, session ID, etc.) */
+    id: string;
+    /** Owner/creator user ID */
+    ownerId: string;
+    /** Public URL slug */
+    slug: string;
+    /** System prompt for the agent (injected before consumer messages) */
+    systemPrompt?: string;
+    /** Per-token price in USD (default: 0.00002) */
+    pricePerTokenUsd: number;
+    /** Platform fee as decimal 0-1 (default: 0.20 = 20%) */
+    platformFeePercent: number;
+    /** Remote operator endpoint for sovereignty mode (null = centralized) */
+    sandboxEndpoint: string | null;
+    /** Sandbox ID on remote operator */
+    remoteSandboxId: string | null;
+    /** PASETO bearer token for remote operator auth */
+    remoteBearerToken: string | null;
+    /** Whether agent is published and accepting requests */
+    enabled: boolean;
+}
+type PaymentMethod = 'x402' | 'mpp' | 'apikey' | 'none';
+interface X402Config {
+    /** Ethereum operator address for SpendAuth verification */
+    operatorAddress: string;
+    /** Blockchain network ID (default: 3799) */
+    chainId: number;
+    /** ShieldedCredits contract address */
+    creditsAddress?: string;
+    /** RPC URL for on-chain verification (optional, demo mode skips this) */
+    rpcUrl?: string;
+    /** Demo mode: skip signature verification (default: false). NEVER enable in production. */
+    demoMode?: boolean;
+    /** Production signer verification. Called with the raw SpendAuth payload. Return true if signature is valid. */
+    verifySigner?: (payload: Record<string, unknown>) => Promise<boolean>;
+}
+interface MppConfig {
+    /** MPP realm (e.g. "agents.tangle.tools") */
+    realm: string;
+    /** MPP method name (default: "blueprintevm") */
+    method?: string;
+}
+interface PaymentResult {
+    method: PaymentMethod;
+    consumerId: string;
+}
+interface ApiKeyInfo {
+    keyId: string;
+    consumerId: string;
+    /** Scopes this key is authorized for (e.g. ["chat", "forms"]) */
+    scopes?: string[];
+    /** Per-key rate limit override (requests per minute). If set, overrides global rate limit. */
+    rateLimitPerMinute?: number;
+    /** Per-key daily limit override. */
+    dailyLimit?: number;
+}
+interface GatewayUsageEvent {
+    agentId: string;
+    agentSlug: string;
+    consumerId: string;
+    paymentMethod: PaymentMethod;
+    inputTokens: number;
+    outputTokens: number;
+    totalCostUsd: number;
+    ownerEarnedUsd: number;
+    platformFeeUsd: number;
+    durationMs: number;
+}
+interface SandboxStreamEvent {
+    type?: string;
+    data?: {
+        part?: {
+            type?: string;
+            text?: string;
+        };
+        delta?: string;
+        finalText?: string;
+    };
+}
+interface SandboxBox {
+    streamPrompt(message: string, opts?: {
+        sessionId?: string;
+        systemPrompt?: string;
+    }): AsyncIterable<SandboxStreamEvent>;
+}
+interface GatewayConfig {
+    /** Resolve agent metadata by slug. Return null if not found or not published. */
+    resolveAgent: (slug: string) => Promise<AgentMeta | null>;
+    /** Get a sandbox instance for the agent. Called after payment is verified. */
+    getSandbox: (agent: AgentMeta) => Promise<SandboxBox>;
+    /** Record a usage event after request completes. */
+    recordUsage: (event: GatewayUsageEvent) => Promise<void>;
+    /** x402 payment configuration */
+    x402: X402Config;
+    /** MPP (Machine Payments Protocol) configuration. If provided, gateway accepts Authorization: Payment headers. */
+    mpp?: MppConfig;
+    /**
+     * Verify an API key. Return key info if valid, null if invalid.
+     * Default: accepts any `sk_agent_*` key (demo mode).
+     */
+    verifyApiKey?: (authHeader: string) => Promise<ApiKeyInfo | null>;
+    /**
+     * Settle payment after successful response.
+     * For x402: call ShieldedCredits.claimPayment()
+     * For API key: deduct from spending limit
+     * Default: no-op (demo mode).
+     */
+    settlePayment?: (payment: PaymentResult, cost: number) => Promise<void>;
+    /** Base URL for API key purchase links (e.g. "https://film.tangle.tools") */
+    baseUrl?: string;
+    /** Max message length in chars (default: 8000) */
+    maxMessageLength?: number;
+    /** Required scope for chat endpoint (default: "chat"). API keys must include this scope. */
+    requiredScope?: string;
+    /** Block requests with detected injection patterns (default: false — log only) */
+    blockInjection?: boolean;
+    /** Rate limiting config. Default: 60 requests per 60 seconds per consumer. */
+    rateLimit?: {
+        limit: number;
+        windowSeconds: number;
+    };
+    /** Custom rate limit store (default: in-memory). Use KV-backed for Workers. */
+    rateLimitStore?: RateLimitStore;
+    /** Nonce replay protection store (default: in-memory). Rejects reused x402 nonces. */
+    nonceStore?: NonceStore;
+    /**
+     * Observability hook. When set, the gateway emits typed events for request
+     * lifecycle, auth outcomes, rate limits, injection detection, usage, errors,
+     * and settlement failures. See ./observer.ts for the interface and
+     * ConsoleObserver / CompositeObserver implementations.
+     */
+    observer?: GatewayObserver;
+}
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+}
+interface ChatCompletionRequest {
+    model?: string;
+    messages: ChatMessage[];
+    stream?: boolean;
+    temperature?: number;
+    max_tokens?: number;
+}
+interface ChatCompletionChunk {
+    id: string;
+    object: 'chat.completion.chunk';
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        delta: {
+            content?: string;
+            role?: string;
+        };
+        finish_reason: string | null;
+    }>;
+}
+
+export { type ApiKeyInfo as A, type ChatMessage as C, type GatewayConfig as G, type MppConfig as M, type PaymentMethod as P, type RequestContext as R, type SandboxBox as S, type X402Config as X, type AgentMeta as a, type AuthFailureReason as b, type ChatCompletionChunk as c, type ChatCompletionRequest as d, CompositeObserver as e, ConsoleObserver as f, type GatewayObserver as g, type GatewayUsageEvent as h, type PaymentResult as i, type SandboxStreamEvent as j, generateRequestId as k };

package/dist/types.d.ts

@@ -1,157 +1,3 @@
-import { NonceStore } from './nonce-store.js';
-import { RateLimitStore } from './rate-limit.js';
-
-interface AgentMeta {
-    /** Unique agent identifier (workspace ID, session ID, etc.) */
-    id: string;
-    /** Owner/creator user ID */
-    ownerId: string;
-    /** Public URL slug */
-    slug: string;
-    /** System prompt for the agent (injected before consumer messages) */
-    systemPrompt?: string;
-    /** Per-token price in USD (default: 0.00002) */
-    pricePerTokenUsd: number;
-    /** Platform fee as decimal 0-1 (default: 0.20 = 20%) */
-    platformFeePercent: number;
-    /** Remote operator endpoint for sovereignty mode (null = centralized) */
-    sandboxEndpoint: string | null;
-    /** Sandbox ID on remote operator */
-    remoteSandboxId: string | null;
-    /** PASETO bearer token for remote operator auth */
-    remoteBearerToken: string | null;
-    /** Whether agent is published and accepting requests */
-    enabled: boolean;
-}
-type PaymentMethod = 'x402' | 'mpp' | 'apikey' | 'none';
-interface X402Config {
-    /** Ethereum operator address for SpendAuth verification */
-    operatorAddress: string;
-    /** Blockchain network ID (default: 3799) */
-    chainId: number;
-    /** ShieldedCredits contract address */
-    creditsAddress?: string;
-    /** RPC URL for on-chain verification (optional, demo mode skips this) */
-    rpcUrl?: string;
-    /** Demo mode: skip signature verification (default: false). NEVER enable in production. */
-    demoMode?: boolean;
-    /** Production signer verification. Called with the raw SpendAuth payload. Return true if signature is valid. */
-    verifySigner?: (payload: Record<string, unknown>) => Promise<boolean>;
-}
-interface MppConfig {
-    /** MPP realm (e.g. "agents.tangle.tools") */
-    realm: string;
-    /** MPP method name (default: "blueprintevm") */
-    method?: string;
-}
-interface PaymentResult {
-    method: PaymentMethod;
-    consumerId: string;
-}
-interface ApiKeyInfo {
-    keyId: string;
-    consumerId: string;
-    /** Scopes this key is authorized for (e.g. ["chat", "forms"]) */
-    scopes?: string[];
-    /** Per-key rate limit override (requests per minute). If set, overrides global rate limit. */
-    rateLimitPerMinute?: number;
-    /** Per-key daily limit override. */
-    dailyLimit?: number;
-}
-interface GatewayUsageEvent {
-    agentId: string;
-    agentSlug: string;
-    consumerId: string;
-    paymentMethod: PaymentMethod;
-    inputTokens: number;
-    outputTokens: number;
-    totalCostUsd: number;
-    ownerEarnedUsd: number;
-    platformFeeUsd: number;
-    durationMs: number;
-}
-interface SandboxStreamEvent {
-    type?: string;
-    data?: {
-        part?: {
-            type?: string;
-            text?: string;
-        };
-        delta?: string;
-        finalText?: string;
-    };
-}
-interface SandboxBox {
-    streamPrompt(message: string, opts?: {
-        sessionId?: string;
-        systemPrompt?: string;
-    }): AsyncIterable<SandboxStreamEvent>;
-}
-interface GatewayConfig {
-    /** Resolve agent metadata by slug. Return null if not found or not published. */
-    resolveAgent: (slug: string) => Promise<AgentMeta | null>;
-    /** Get a sandbox instance for the agent. Called after payment is verified. */
-    getSandbox: (agent: AgentMeta) => Promise<SandboxBox>;
-    /** Record a usage event after request completes. */
-    recordUsage: (event: GatewayUsageEvent) => Promise<void>;
-    /** x402 payment configuration */
-    x402: X402Config;
-    /** MPP (Machine Payments Protocol) configuration. If provided, gateway accepts Authorization: Payment headers. */
-    mpp?: MppConfig;
-    /**
-     * Verify an API key. Return key info if valid, null if invalid.
-     * Default: accepts any `sk_agent_*` key (demo mode).
-     */
-    verifyApiKey?: (authHeader: string) => Promise<ApiKeyInfo | null>;
-    /**
-     * Settle payment after successful response.
-     * For x402: call ShieldedCredits.claimPayment()
-     * For API key: deduct from spending limit
-     * Default: no-op (demo mode).
-     */
-    settlePayment?: (payment: PaymentResult, cost: number) => Promise<void>;
-    /** Base URL for API key purchase links (e.g. "https://film.tangle.tools") */
-    baseUrl?: string;
-    /** Max message length in chars (default: 8000) */
-    maxMessageLength?: number;
-    /** Required scope for chat endpoint (default: "chat"). API keys must include this scope. */
-    requiredScope?: string;
-    /** Block requests with detected injection patterns (default: false — log only) */
-    blockInjection?: boolean;
-    /** Rate limiting config. Default: 60 requests per 60 seconds per consumer. */
-    rateLimit?: {
-        limit: number;
-        windowSeconds: number;
-    };
-    /** Custom rate limit store (default: in-memory). Use KV-backed for Workers. */
-    rateLimitStore?: RateLimitStore;
-    /** Nonce replay protection store (default: in-memory). Rejects reused x402 nonces. */
-    nonceStore?: NonceStore;
-}
-interface ChatMessage {
-    role: 'system' | 'user' | 'assistant' | 'tool';
-    content: string;
-}
-interface ChatCompletionRequest {
-    model?: string;
-    messages: ChatMessage[];
-    stream?: boolean;
-    temperature?: number;
-    max_tokens?: number;
-}
-interface ChatCompletionChunk {
-    id: string;
-    object: 'chat.completion.chunk';
-    created: number;
-    model: string;
-    choices: Array<{
-        index: number;
-        delta: {
-            content?: string;
-            role?: string;
-        };
-        finish_reason: string | null;
-    }>;
-}
-
-export type { AgentMeta, ApiKeyInfo, ChatCompletionChunk, ChatCompletionRequest, ChatMessage, GatewayConfig, GatewayUsageEvent, MppConfig, PaymentMethod, PaymentResult, SandboxBox, SandboxStreamEvent, X402Config };
+export { a as AgentMeta, A as ApiKeyInfo, c as ChatCompletionChunk, d as ChatCompletionRequest, C as ChatMessage, G as GatewayConfig, h as GatewayUsageEvent, M as MppConfig, P as PaymentMethod, i as PaymentResult, S as SandboxBox, j as SandboxStreamEvent, X as X402Config } from './types-14xV8J4G.js';
+import './nonce-store.js';
+import './rate-limit.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-gateway",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "x402 + API key payment gateway for Tangle agent products. Mount on any Hono app to expose agents as paid OpenAI-compatible endpoints.",
   "exports": {
@@ -15,6 +15,10 @@
     "./types": {
       "types": "./dist/types.d.ts",
       "import": "./dist/types.js"
+    },
+    "./observer": {
+      "types": "./dist/observer.d.ts",
+      "import": "./dist/observer.js"
     }
   },
   "files": [

package/src/index.ts

@@ -9,6 +9,7 @@ export {
 export {
   checkRateLimit,
   MemoryRateLimitStore,
+  KvRateLimitStore,
   type RateLimitConfig,
   type RateLimitResult,
   type RateLimitStore,
@@ -23,8 +24,17 @@ export {
 } from './api-keys'
 export {
   MemoryNonceStore,
+  KvNonceStore,
   type NonceStore,
 } from './nonce-store'
+export {
+  ConsoleObserver,
+  CompositeObserver,
+  generateRequestId,
+  type GatewayObserver,
+  type RequestContext,
+  type AuthFailureReason,
+} from './observer'
 export {
   createPublishRoutes,
   type PublishedConfig,