@kya-os/mcp-i/dist/cache/cloudflare-kv.d.ts

The TypeScript MCP framework with identity features built-in

/**
 * Cloudflare KV-based nonce cache implementation for Workers
 *
 * This cache prevents replay attacks by tracking used nonces in Cloudflare KV.
 * Each nonce is stored with a TTL matching the session timeout.
 */
import type { NonceCache } from "@kya-os/contracts/handshake";
/**
 * Cloudflare KV namespace interface
 */
export interface KVNamespace {
    get(key: string, options?: {
        type?: "text" | "json" | "arrayBuffer" | "stream";
    }): Promise<string | null>;
    put(key: string, value: string | ArrayBuffer | ReadableStream, options?: {
        expiration?: number;
        expirationTtl?: number;
    }): Promise<void>;
    delete(key: string): Promise<void>;
}
/**
 * Configuration for Cloudflare KV nonce cache
 */
export interface CloudflareKVNonceCacheConfig {
    /**
     * KV namespace binding from Worker environment
     */
    namespace: KVNamespace;
    /**
     * TTL for nonce entries in seconds
     * Should match or exceed session timeout
     * @default 1800 (30 minutes)
     */
    ttl?: number;
    /**
     * Key prefix for nonce entries
     * @default "nonce:"
     */
    keyPrefix?: string;
}
/**
 * Cloudflare KV nonce cache for Workers
 *
 * Usage in Worker:
 * ```typescript
 * export interface Env {
 *   NONCE_CACHE: KVNamespace;
 * }
 *
 * export default {
 *   async fetch(request: Request, env: Env): Promise<Response> {
 *     const nonceCache = new CloudflareKVNonceCache({
 *       namespace: env.NONCE_CACHE,
 *       ttl: 1800, // 30 minutes
 *     });
 *
 *     // Use with verifier or MCP-I runtime
 *     const runtime = new MCPIRuntime({
 *       nonce: { cache: nonceCache }
 *     });
 *   }
 * }
 * ```
 */
export declare class CloudflareKVNonceCache implements NonceCache {
    private kv;
    private ttl;
    private keyPrefix;
    constructor(config: CloudflareKVNonceCacheConfig);
    /**
     * Check if a nonce exists in the cache
     *
     * @param nonce - The nonce to check
     * @param agentDid - Optional agent DID for agent-scoped nonces (prevents cross-agent replay attacks)
     * @returns Promise<boolean> - true if exists, false if not
     */
    has(nonce: string, agentDid?: string): Promise<boolean>;
    /**
     * Add a nonce to the cache with TTL
     * Implements atomic add-if-absent semantics for replay prevention
     *
     * @param nonce - The nonce to add
     * @param ttl - Time-to-live in seconds
     * @param agentDid - Optional agent DID for agent-scoped nonces (prevents cross-agent replay attacks)
     */
    add(nonce: string, ttl: number, agentDid?: string): Promise<void>;
    /**
     * Cleanup expired nonces
     * Note: Cloudflare KV handles expiration automatically via TTL
     */
    cleanup(): Promise<void>;
}