@kya-os/mcp-i 0.1.0 → 1.2.1

package/dist/cache/cloudflare-kv-nonce-cache.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloudflareKVNonceCache = void 0;
+/**
+ * Cloudflare KV-based nonce cache implementation
+ * Suitable for Cloudflare Workers deployments
+ */
+class CloudflareKVNonceCache {
+    kv; // KV namespace - type depends on Cloudflare Workers runtime
+    keyPrefix;
+    constructor(kv, keyPrefix = "nonce:") {
+        this.kv = kv;
+        this.keyPrefix = keyPrefix;
+    }
+    getKey(nonce) {
+        return `${this.keyPrefix}${nonce}`;
+    }
+    async has(nonce) {
+        const key = this.getKey(nonce);
+        const value = await this.kv.get(key);
+        if (!value) {
+            return false;
+        }
+        // Parse the stored data to check expiry
+        try {
+            const data = JSON.parse(value);
+            if (Date.now() > data.expiresAt) {
+                // Clean up expired entry
+                await this.kv.delete(key);
+                return false;
+            }
+            return true;
+        }
+        catch {
+            // If we can't parse, assume expired and clean up
+            await this.kv.delete(key);
+            return false;
+        }
+    }
+    async add(nonce, ttl) {
+        const key = this.getKey(nonce);
+        const expiresAt = Date.now() + ttl * 1000;
+        const data = {
+            nonce,
+            expiresAt,
+            createdAt: Date.now(),
+        };
+        // Cloudflare KV doesn't have native atomic add-if-absent
+        // We implement a best-effort approach with metadata checking
+        try {
+            // First, try to get the existing value with metadata
+            const existingWithMetadata = await this.kv.getWithMetadata(key);
+            if (existingWithMetadata && existingWithMetadata.value !== null) {
+                // Key exists, check if it's still valid
+                try {
+                    const existingData = JSON.parse(existingWithMetadata.value);
+                    if (Date.now() <= existingData.expiresAt) {
+                        throw new Error(`Nonce ${nonce} already exists - potential replay attack`);
+                    }
+                    // If expired, we can proceed to overwrite
+                }
+                catch {
+                    // If we can't parse existing data, assume it's corrupted and overwrite
+                }
+            }
+            // Store with KV TTL as backup (convert to seconds)
+            await this.kv.put(key, JSON.stringify(data), {
+                expirationTtl: ttl,
+            });
+        }
+        catch (error) {
+            // If getWithMetadata is not available, fall back to basic approach
+            if (error.message?.includes("getWithMetadata")) {
+                // Check if already exists first (less atomic but still functional)
+                if (await this.has(nonce)) {
+                    throw new Error(`Nonce ${nonce} already exists - potential replay attack`);
+                }
+                // Store with KV TTL as backup (convert to seconds)
+                await this.kv.put(key, JSON.stringify(data), {
+                    expirationTtl: ttl,
+                });
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    async cleanup() {
+        // Cloudflare KV handles expiry automatically via TTL, so this is a no-op
+        // This method exists to satisfy the interface
+    }
+}
+exports.CloudflareKVNonceCache = CloudflareKVNonceCache;

package/dist/cache/dynamodb-nonce-cache.d.ts

@@ -0,0 +1,15 @@
+import { NonceCache } from "@kya-os/contracts/handshake";
+/**
+ * DynamoDB-based nonce cache implementation
+ * Suitable for AWS Lambda deployments
+ */
+export declare class DynamoNonceCache implements NonceCache {
+    private dynamodb;
+    private tableName;
+    private keyAttribute;
+    private ttlAttribute;
+    constructor(dynamodb: any, tableName: string, keyAttribute?: string, ttlAttribute?: string);
+    has(nonce: string): Promise<boolean>;
+    add(nonce: string, ttl: number): Promise<void>;
+    cleanup(): Promise<void>;
+}

package/dist/cache/dynamodb-nonce-cache.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamoNonceCache = void 0;
+/**
+ * DynamoDB-based nonce cache implementation
+ * Suitable for AWS Lambda deployments
+ */
+class DynamoNonceCache {
+    dynamodb; // DynamoDB client - type depends on AWS SDK version
+    tableName;
+    keyAttribute;
+    ttlAttribute;
+    constructor(dynamodb, tableName, keyAttribute = "nonce", ttlAttribute = "expiresAt") {
+        this.dynamodb = dynamodb;
+        this.tableName = tableName;
+        this.keyAttribute = keyAttribute;
+        this.ttlAttribute = ttlAttribute;
+    }
+    async has(nonce) {
+        try {
+            const result = await this.dynamodb
+                .getItem({
+                TableName: this.tableName,
+                Key: {
+                    [this.keyAttribute]: { S: nonce },
+                },
+                ConsistentRead: true, // Ensure we get the latest data
+            })
+                .promise();
+            if (!result.Item) {
+                return false;
+            }
+            // Check if expired (DynamoDB TTL might not have cleaned up yet)
+            const expiresAt = parseInt(result.Item[this.ttlAttribute].N);
+            if (Date.now() / 1000 > expiresAt) {
+                return false;
+            }
+            return true;
+        }
+        catch (error) {
+            // Log error but don't expose internal details
+            console.error("DynamoDB has() operation failed:", error);
+            // For certain errors, we can safely return false
+            if (error.code === "ResourceNotFoundException" ||
+                error.code === "ItemCollectionSizeLimitExceededException") {
+                return false;
+            }
+            // For other errors, we should throw to avoid security issues
+            throw new Error(`Failed to check nonce existence: ${error.code || error.message}`);
+        }
+    }
+    async add(nonce, ttl) {
+        const expiresAt = Math.floor(Date.now() / 1000) + ttl;
+        try {
+            // Use conditional write to ensure atomic add-if-absent
+            // This is truly atomic in DynamoDB
+            await this.dynamodb
+                .putItem({
+                TableName: this.tableName,
+                Item: {
+                    [this.keyAttribute]: { S: nonce },
+                    [this.ttlAttribute]: { N: expiresAt.toString() },
+                    createdAt: { N: Math.floor(Date.now() / 1000).toString() },
+                },
+                ConditionExpression: `attribute_not_exists(${this.keyAttribute})`,
+            })
+                .promise();
+        }
+        catch (error) {
+            if (error.code === "ConditionalCheckFailedException") {
+                throw new Error(`Nonce ${nonce} already exists - potential replay attack`);
+            }
+            console.error("DynamoDB add() operation failed:", error);
+            // Provide more specific error messages for common issues
+            if (error.code === "ResourceNotFoundException") {
+                throw new Error(`DynamoDB table ${this.tableName} not found`);
+            }
+            else if (error.code === "ValidationException") {
+                throw new Error(`Invalid DynamoDB operation: ${error.message}`);
+            }
+            else if (error.code === "ProvisionedThroughputExceededException") {
+                throw new Error("DynamoDB throughput exceeded - consider increasing capacity");
+            }
+            throw new Error(`Failed to add nonce to cache: ${error.code || error.message}`);
+        }
+    }
+    async cleanup() {
+        // DynamoDB handles TTL cleanup automatically, so this is a no-op
+        // This method exists to satisfy the interface
+    }
+}
+exports.DynamoNonceCache = DynamoNonceCache;

package/dist/cache/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pluggable nonce cache architecture for XMCP-I
+ *
+ * Provides replay prevention through various cache backends:
+ * - Memory (development, single instance)
+ * - Redis (production, multi-instance)
+ * - DynamoDB (AWS Lambda)
+ * - Cloudflare KV (Cloudflare Workers)
+ */
+export type { SessionContext, HandshakeRequest, NonceCacheEntry, NonceCache, NonceCacheConfig, } from "@kya-os/contracts/handshake";
+export { SessionContextSchema, HandshakeRequestSchema, NonceCacheEntrySchema, NonceCacheConfigSchema, } from "@kya-os/contracts/handshake";
+export { MemoryNonceCache } from "./memory-nonce-cache";
+export { RedisNonceCache } from "./redis-nonce-cache";
+export { DynamoNonceCache } from "./dynamodb-nonce-cache";
+export { CloudflareKVNonceCache } from "./cloudflare-kv-nonce-cache";
+export { createNonceCache, createNonceCacheWithConfig, detectCacheType, type NonceCacheOptions, } from "./nonce-cache-factory";

package/dist/cache/index.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Pluggable nonce cache architecture for XMCP-I
+ *
+ * Provides replay prevention through various cache backends:
+ * - Memory (development, single instance)
+ * - Redis (production, multi-instance)
+ * - DynamoDB (AWS Lambda)
+ * - Cloudflare KV (Cloudflare Workers)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectCacheType = exports.createNonceCacheWithConfig = exports.createNonceCache = exports.CloudflareKVNonceCache = exports.DynamoNonceCache = exports.RedisNonceCache = exports.MemoryNonceCache = exports.NonceCacheConfigSchema = exports.NonceCacheEntrySchema = exports.HandshakeRequestSchema = exports.SessionContextSchema = void 0;
+// Re-export schemas
+var handshake_1 = require("@kya-os/contracts/handshake");
+Object.defineProperty(exports, "SessionContextSchema", { enumerable: true, get: function () { return handshake_1.SessionContextSchema; } });
+Object.defineProperty(exports, "HandshakeRequestSchema", { enumerable: true, get: function () { return handshake_1.HandshakeRequestSchema; } });
+Object.defineProperty(exports, "NonceCacheEntrySchema", { enumerable: true, get: function () { return handshake_1.NonceCacheEntrySchema; } });
+Object.defineProperty(exports, "NonceCacheConfigSchema", { enumerable: true, get: function () { return handshake_1.NonceCacheConfigSchema; } });
+// Cache implementations
+var memory_nonce_cache_1 = require("./memory-nonce-cache");
+Object.defineProperty(exports, "MemoryNonceCache", { enumerable: true, get: function () { return memory_nonce_cache_1.MemoryNonceCache; } });
+var redis_nonce_cache_1 = require("./redis-nonce-cache");
+Object.defineProperty(exports, "RedisNonceCache", { enumerable: true, get: function () { return redis_nonce_cache_1.RedisNonceCache; } });
+var dynamodb_nonce_cache_1 = require("./dynamodb-nonce-cache");
+Object.defineProperty(exports, "DynamoNonceCache", { enumerable: true, get: function () { return dynamodb_nonce_cache_1.DynamoNonceCache; } });
+var cloudflare_kv_nonce_cache_1 = require("./cloudflare-kv-nonce-cache");
+Object.defineProperty(exports, "CloudflareKVNonceCache", { enumerable: true, get: function () { return cloudflare_kv_nonce_cache_1.CloudflareKVNonceCache; } });
+// Factory and auto-detection
+var nonce_cache_factory_1 = require("./nonce-cache-factory");
+Object.defineProperty(exports, "createNonceCache", { enumerable: true, get: function () { return nonce_cache_factory_1.createNonceCache; } });
+Object.defineProperty(exports, "createNonceCacheWithConfig", { enumerable: true, get: function () { return nonce_cache_factory_1.createNonceCacheWithConfig; } });
+Object.defineProperty(exports, "detectCacheType", { enumerable: true, get: function () { return nonce_cache_factory_1.detectCacheType; } });

package/dist/cache/memory-nonce-cache.d.ts

@@ -0,0 +1,44 @@
+/**
+ * In-memory nonce cache implementation
+ *
+ * WARNING: This implementation is only suitable for single-instance deployments.
+ * For multi-instance deployments, use Redis, DynamoDB, or Cloudflare KV implementations.
+ */
+import { NonceCache } from "@kya-os/contracts/handshake";
+/**
+ * In-memory nonce cache with TTL support
+ */
+export declare class MemoryNonceCache implements NonceCache {
+    private cache;
+    private cleanupInterval?;
+    constructor(cleanupIntervalMs?: number);
+    /**
+     * Check if a nonce exists in the cache
+     */
+    has(nonce: string): Promise<boolean>;
+    /**
+     * Add a nonce to the cache with TTL
+     * MUST ensure atomic add-if-absent semantics for replay prevention
+     */
+    add(nonce: string, ttlSeconds: number): Promise<void>;
+    /**
+     * Clean up expired entries
+     * Safe to call frequently and should be no-op for backends that auto-expire
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        expired: number;
+    };
+    /**
+     * Clear all entries (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Destroy the cache and stop cleanup interval
+     */
+    destroy(): void;
+}

package/dist/cache/memory-nonce-cache.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * In-memory nonce cache implementation
+ *
+ * WARNING: This implementation is only suitable for single-instance deployments.
+ * For multi-instance deployments, use Redis, DynamoDB, or Cloudflare KV implementations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryNonceCache = void 0;
+/**
+ * In-memory nonce cache with TTL support
+ */
+class MemoryNonceCache {
+    cache = new Map();
+    cleanupInterval;
+    constructor(cleanupIntervalMs = 60000) {
+        // Default: 1 minute cleanup
+        // Start periodic cleanup
+        this.cleanupInterval = setInterval(() => {
+            this.cleanup().catch(console.error);
+        }, cleanupIntervalMs);
+    }
+    /**
+     * Check if a nonce exists in the cache
+     */
+    async has(nonce) {
+        const entry = this.cache.get(nonce);
+        if (!entry) {
+            return false;
+        }
+        // Check if expired
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(nonce);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Add a nonce to the cache with TTL
+     * MUST ensure atomic add-if-absent semantics for replay prevention
+     */
+    async add(nonce, ttlSeconds) {
+        // Check if nonce already exists (atomic check-and-set)
+        const existing = this.cache.get(nonce);
+        if (existing && Date.now() <= existing.expiresAt) {
+            throw new Error(`Nonce ${nonce} already exists`);
+        }
+        // Handle zero or negative TTL - set expiration to past time
+        const expiresAt = ttlSeconds <= 0 ? Date.now() - 1 : Date.now() + ttlSeconds * 1000;
+        const entry = {
+            sessionId: `mem_${Date.now()}_${Math.random().toString(36).substring(2)}`,
+            expiresAt,
+        };
+        this.cache.set(nonce, entry);
+    }
+    /**
+     * Clean up expired entries
+     * Safe to call frequently and should be no-op for backends that auto-expire
+     */
+    async cleanup() {
+        const now = Date.now();
+        const expiredKeys = [];
+        for (const [nonce, entry] of this.cache.entries()) {
+            if (now > entry.expiresAt) {
+                expiredKeys.push(nonce);
+            }
+        }
+        for (const key of expiredKeys) {
+            this.cache.delete(key);
+        }
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        const now = Date.now();
+        let expired = 0;
+        for (const entry of this.cache.values()) {
+            if (now > entry.expiresAt) {
+                expired++;
+            }
+        }
+        return {
+            size: this.cache.size,
+            expired,
+        };
+    }
+    /**
+     * Clear all entries (useful for testing)
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Destroy the cache and stop cleanup interval
+     */
+    destroy() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = undefined;
+        }
+        this.cache.clear();
+    }
+}
+exports.MemoryNonceCache = MemoryNonceCache;

package/dist/cache/nonce-cache-factory.d.ts

@@ -0,0 +1,20 @@
+import { NonceCache, NonceCacheConfig } from "@kya-os/contracts/handshake";
+/**
+ * Environment-based cache type detection
+ */
+export declare function detectCacheType(): "memory" | "redis" | "dynamodb" | "cloudflare-kv";
+/**
+ * Create a nonce cache instance based on configuration or environment detection
+ */
+export declare function createNonceCache(config?: NonceCacheConfig): Promise<NonceCache>;
+/**
+ * Configuration override options for nonce cache
+ */
+export interface NonceCacheOptions {
+    config?: NonceCacheConfig;
+    fallbackToMemory?: boolean;
+}
+/**
+ * Create nonce cache with explicit configuration override
+ */
+export declare function createNonceCacheWithConfig(options?: NonceCacheOptions): Promise<NonceCache>;

package/dist/cache/nonce-cache-factory.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectCacheType = detectCacheType;
+exports.createNonceCache = createNonceCache;
+exports.createNonceCacheWithConfig = createNonceCacheWithConfig;
+const memory_nonce_cache_1 = require("./memory-nonce-cache");
+const redis_nonce_cache_1 = require("./redis-nonce-cache");
+const dynamodb_nonce_cache_1 = require("./dynamodb-nonce-cache");
+const cloudflare_kv_nonce_cache_1 = require("./cloudflare-kv-nonce-cache");
+/**
+ * Get environment variable with fallback support for old naming
+ * Supports migration from XMCPI_ to MCPI_ prefixes
+ */
+function getEnvWithFallback(newKey, oldKey) {
+    const newValue = process.env[newKey];
+    if (newValue !== undefined) {
+        return newValue;
+    }
+    if (oldKey) {
+        const oldValue = process.env[oldKey];
+        if (oldValue !== undefined) {
+            console.warn(`⚠️  Environment variable ${oldKey} is deprecated. Please use ${newKey} instead.`);
+            return oldValue;
+        }
+    }
+    return undefined;
+}
+/**
+ * Environment-based cache type detection
+ */
+function detectCacheType() {
+    // Check for explicit configuration (with fallback support)
+    const explicitType = getEnvWithFallback("MCPI_NONCE_CACHE_TYPE", "XMCPI_NONCE_CACHE_TYPE");
+    if (explicitType &&
+        ["memory", "redis", "dynamodb", "cloudflare-kv"].includes(explicitType)) {
+        return explicitType;
+    }
+    // Auto-detect based on environment (most specific first)
+    // Redis detection
+    if (process.env.REDIS_URL ||
+        getEnvWithFallback("MCPI_REDIS_URL", "XMCPI_REDIS_URL")) {
+        return "redis";
+    }
+    // DynamoDB detection (AWS Lambda environment)
+    if ((process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION) &&
+        getEnvWithFallback("MCPI_DYNAMODB_TABLE", "XMCPI_DYNAMODB_TABLE")) {
+        return "dynamodb";
+    }
+    // Cloudflare Workers detection (more robust)
+    if (typeof globalThis !== "undefined") {
+        // Check for Cloudflare Workers specific globals
+        const globalScope = globalThis;
+        if ("caches" in globalThis &&
+            typeof globalScope.fetch === "function" &&
+            (typeof globalScope.addEventListener === "function" ||
+                typeof globalScope.Response === "function")) {
+            return "cloudflare-kv";
+        }
+    }
+    // Warn about memory cache in production
+    if (process.env.NODE_ENV === "production" ||
+        getEnvWithFallback("MCPI_ENV", "XMCPI_ENV") === "production") {
+        console.warn("mcpi: Using memory cache in production environment. " +
+            "For multi-instance deployments, configure Redis (REDIS_URL), " +
+            "DynamoDB (AWS_REGION + MCPI_DYNAMODB_TABLE), or " +
+            "Cloudflare KV (MCPI_KV_NAMESPACE).");
+    }
+    return "memory";
+}
+/**
+ * Create a nonce cache instance based on configuration or environment detection
+ */
+async function createNonceCache(config) {
+    const cacheType = config?.type || detectCacheType();
+    switch (cacheType) {
+        case "redis": {
+            const redisUrl = config?.redis?.url ||
+                process.env.REDIS_URL ||
+                getEnvWithFallback("MCPI_REDIS_URL", "XMCPI_REDIS_URL");
+            if (!redisUrl) {
+                console.warn("Redis URL not found, falling back to memory cache");
+                return new memory_nonce_cache_1.MemoryNonceCache();
+            }
+            try {
+                // Dynamic import to avoid bundling Redis in environments that don't need it
+                const { createClient } = await import("redis");
+                const redis = createClient({
+                    url: redisUrl,
+                    socket: {
+                        connectTimeout: 5000, // 5 second timeout
+                    },
+                });
+                // Test connection
+                await redis.connect();
+                // Verify basic operations work
+                await redis.ping();
+                return new redis_nonce_cache_1.RedisNonceCache(redis, config?.redis?.keyPrefix);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.warn("Failed to connect to Redis, falling back to memory cache:", errorMessage);
+                return new memory_nonce_cache_1.MemoryNonceCache();
+            }
+        }
+        case "dynamodb": {
+            const tableName = config?.dynamodb?.tableName ||
+                getEnvWithFallback("MCPI_DYNAMODB_TABLE", "XMCPI_DYNAMODB_TABLE");
+            if (!tableName) {
+                console.warn("DynamoDB table name not found, falling back to memory cache");
+                return new memory_nonce_cache_1.MemoryNonceCache();
+            }
+            try {
+                // Dynamic import to avoid bundling AWS SDK in environments that don't need it
+                const awsSdk = await import("@aws-sdk/client-dynamodb");
+                // Extract types from dynamic import - handle both ESM and CJS exports
+                const DynamoDBClient = awsSdk.DynamoDBClient ||
+                    awsSdk.default?.DynamoDBClient;
+                const DescribeTableCommand = awsSdk.DescribeTableCommand ||
+                    awsSdk.default?.DescribeTableCommand;
+                const region = config?.dynamodb?.region ||
+                    process.env.AWS_REGION ||
+                    process.env.AWS_DEFAULT_REGION ||
+                    "us-east-1";
+                const dynamodb = new DynamoDBClient({
+                    region,
+                    maxAttempts: 3,
+                });
+                // Verify table exists and is accessible
+                try {
+                    await dynamodb.send(new DescribeTableCommand({ TableName: tableName }));
+                }
+                catch (tableError) {
+                    const error = tableError;
+                    if (error.name === "ResourceNotFoundException") {
+                        throw new Error(`DynamoDB table '${tableName}' not found in region '${region}'`);
+                    }
+                    throw tableError;
+                }
+                return new dynamodb_nonce_cache_1.DynamoNonceCache(dynamodb, tableName, config?.dynamodb?.keyAttribute, config?.dynamodb?.ttlAttribute);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.warn("Failed to initialize DynamoDB, falling back to memory cache:", errorMessage);
+                return new memory_nonce_cache_1.MemoryNonceCache();
+            }
+        }
+        case "cloudflare-kv": {
+            const namespace = config?.cloudflareKv?.namespace ||
+                getEnvWithFallback("MCPI_KV_NAMESPACE", "XMCPI_KV_NAMESPACE");
+            if (!namespace) {
+                console.warn("Cloudflare KV namespace not found, falling back to memory cache");
+                return new memory_nonce_cache_1.MemoryNonceCache();
+            }
+            try {
+                // In Cloudflare Workers, KV namespaces are available as globals
+                const globalScope = globalThis;
+                const kv = globalScope[namespace];
+                if (!kv) {
+                    throw new Error(`KV namespace '${namespace}' not found in global scope`);
+                }
+                // Verify KV namespace has required methods
+                const kvInterface = kv;
+                if (typeof kvInterface.get !== "function" ||
+                    typeof kvInterface.put !== "function") {
+                    throw new Error(`KV namespace '${namespace}' does not have required methods`);
+                }
+                // Test basic KV operation (this will be very fast in Workers)
+                try {
+                    const kvInterface = kv;
+                    await kvInterface.get("__mcpi_test_key__");
+                }
+                catch (kvError) {
+                    const error = kvError;
+                    // Some KV errors are expected (like key not found), but connection errors are not
+                    if (error.message?.includes("network") ||
+                        error.message?.includes("timeout")) {
+                        throw kvError;
+                    }
+                    // Other errors (like key not found) are fine
+                }
+                return new cloudflare_kv_nonce_cache_1.CloudflareKVNonceCache(kv, config?.cloudflareKv?.keyPrefix);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.warn("Failed to initialize Cloudflare KV, falling back to memory cache:", errorMessage);
+                return new memory_nonce_cache_1.MemoryNonceCache();
+            }
+        }
+        case "memory":
+        default:
+            return new memory_nonce_cache_1.MemoryNonceCache();
+    }
+}
+/**
+ * Create nonce cache with explicit configuration override
+ */
+async function createNonceCacheWithConfig(options = {}) {
+    try {
+        return await createNonceCache(options.config);
+    }
+    catch (error) {
+        if (options.fallbackToMemory !== false) {
+            console.warn("Failed to create configured nonce cache, falling back to memory:", error);
+            return new memory_nonce_cache_1.MemoryNonceCache();
+        }
+        throw error;
+    }
+}

package/dist/cache/redis-nonce-cache.d.ts

@@ -0,0 +1,14 @@
+import { NonceCache } from "@kya-os/contracts/handshake";
+/**
+ * Redis-based nonce cache implementation
+ * Suitable for multi-instance deployments
+ */
+export declare class RedisNonceCache implements NonceCache {
+    private redis;
+    private keyPrefix;
+    constructor(redis: any, keyPrefix?: string);
+    private getKey;
+    has(nonce: string): Promise<boolean>;
+    add(nonce: string, ttl: number): Promise<void>;
+    cleanup(): Promise<void>;
+}