@kya-os/mcp-i-core 1.2.3-canary.6 → 1.3.0

package/src/services/storage.service.ts

@@ -0,0 +1,566 @@
+/**
+ * Storage Service Factory
+ *
+ * Auto-selects storage providers based on available configuration.
+ * Priority: Redis > Cloudflare KV > Cloudflare Durable Objects > Memory
+ *
+ * @package @kya-os/mcp-i-core
+ */
+
+import { StorageProvider, NonceCacheProvider } from "../providers/base.js";
+import {
+  MemoryStorageProvider,
+  MemoryNonceCacheProvider,
+} from "../providers/memory.js";
+
+/**
+ * Storage service configuration
+ */
+export interface StorageServiceConfig {
+  /** Redis URL (e.g., "redis://localhost:6379") */
+  redisUrl?: string;
+
+  /** Cloudflare KV namespace */
+  kvNamespace?: {
+    get(key: string): Promise<string | null>;
+    put(
+      key: string,
+      value: string,
+      options?: { expirationTtl?: number }
+    ): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(options?: {
+      prefix?: string;
+    }): Promise<{ keys: Array<{ name: string }> }>;
+  };
+
+  /** Cloudflare Durable Object state */
+  durableObjectState?: {
+    storage: {
+      get(key: string): Promise<string | undefined>;
+      put(key: string, value: string): Promise<void>;
+      delete(key: string): Promise<void>;
+      list(options?: { prefix?: string }): Promise<Map<string, string>>;
+    };
+  };
+
+  /** Fallback to memory if no external storage configured (default: true) */
+  fallbackToMemory?: boolean;
+}
+
+/**
+ * Storage providers result
+ */
+export interface StorageProviders {
+  storageProvider: StorageProvider;
+  nonceCacheProvider: NonceCacheProvider;
+}
+
+/**
+ * Key helper functions for consistent key formatting
+ */
+export class StorageKeyHelpers {
+  /**
+   * Build delegation key using composite format
+   * Format: delegation:${userDid}:${agentDid}:${projectId}
+   */
+  static buildDelegationKey(
+    userDid: string,
+    agentDid: string,
+    projectId: string
+  ): string {
+    return `delegation:${userDid}:${agentDid}:${projectId}`;
+  }
+
+  /**
+   * Build session key
+   * Format: session:${sessionId}
+   */
+  static buildSessionKey(sessionId: string): string {
+    return `session:${sessionId}`;
+  }
+
+  /**
+   * Build nonce key
+   * Format: nonce:${agentDid}:${nonce}
+   */
+  static buildNonceKey(agentDid: string, nonce: string): string {
+    return `nonce:${agentDid}:${nonce}`;
+  }
+
+  /**
+   * Parse delegation key back into components
+   *
+   * Format: delegation:${userDid}:${agentDid}:${projectId}
+   *
+   * Note: DIDs contain colons (e.g., did:key:z123), so we can't simply split by ":"
+   * Instead, we:
+   * 1. Check that key starts with "delegation:"
+   * 2. Take the last part as projectId (doesn't contain colons)
+   * 3. Find where agentDid starts (look for "did:" pattern)
+   * 4. Everything before agentDid is userDid, everything between agentDid and projectId is agentDid
+   *
+   * Strategy: Since DIDs always start with "did:", we can find the second occurrence of "did:"
+   * to determine where agentDid begins. However, this assumes userDid and agentDid both start with "did:".
+   *
+   * For keys like "delegation:did:key:user123:did:key:agent456:project-789":
+   * - Remove "delegation:" prefix → "did:key:user123:did:key:agent456:project-789"
+   * - Find last ":" → separates agentDid from projectId
+   * - projectId = "project-789"
+   * - Find second occurrence of "did:" → separates userDid from agentDid
+   * - userDid = "did:key:user123"
+   * - agentDid = "did:key:agent456"
+   */
+  static parseDelegationKey(
+    key: string
+  ): { userDid: string; agentDid: string; projectId: string } | null {
+    if (!key.startsWith("delegation:")) {
+      return null;
+    }
+
+    // Remove "delegation:" prefix
+    const rest = key.slice("delegation:".length);
+
+    // Find the last colon (separates agentDid from projectId)
+    const lastColonIndex = rest.lastIndexOf(":");
+    if (lastColonIndex === -1) {
+      return null; // No colon found, invalid format
+    }
+
+    // Last part is projectId (doesn't contain colons)
+    const projectId = rest.slice(lastColonIndex + 1);
+    if (!projectId) {
+      return null; // Empty projectId
+    }
+
+    // Everything before the last colon is userDid:agentDid
+    const userDidAndAgentDid = rest.slice(0, lastColonIndex);
+
+    // Find the second occurrence of "did:" to separate userDid from agentDid
+    // First occurrence is at the start (userDid), second is agentDid
+    const firstDidIndex = userDidAndAgentDid.indexOf("did:");
+    if (firstDidIndex !== 0) {
+      return null; // userDid must start with "did:"
+    }
+
+    // Find where the first DID ends by looking for the pattern "did:method:identifier"
+    // A DID has the format: did:method:identifier (where identifier may contain colons)
+    // We need to find the next "did:" that appears after a complete DID
+    // Strategy: Find the method separator colon (after "did:"), then search for the next "did:" after that
+    // This ensures we find the second complete DID, not a substring within the first DID's identifier
+    const firstMethodColon = userDidAndAgentDid.indexOf(
+      ":",
+      firstDidIndex + "did:".length
+    );
+    if (firstMethodColon === -1) {
+      return null; // Invalid DID format - no method separator
+    }
+
+    // Now search for the next "did:" after the first complete DID
+    // The first DID ends somewhere after the method colon, so search from there
+    const secondDidIndex = userDidAndAgentDid.indexOf(
+      "did:",
+      firstMethodColon + 1
+    );
+    if (secondDidIndex === -1) {
+      return null; // No second "did:" found, can't separate userDid and agentDid
+    }
+
+    // userDid is everything before the second "did:", agentDid is everything after
+    const userDid = userDidAndAgentDid.slice(0, secondDidIndex);
+    const agentDid = userDidAndAgentDid.slice(secondDidIndex);
+
+    // Remove trailing colon from userDid if present
+    const cleanUserDid = userDid.endsWith(":") ? userDid.slice(0, -1) : userDid;
+
+    if (!cleanUserDid || !agentDid) {
+      return null; // Empty userDid or agentDid
+    }
+
+    return {
+      userDid: cleanUserDid,
+      agentDid,
+      projectId,
+    };
+  }
+}
+
+/**
+ * Durable Object Storage Provider
+ * Wraps Cloudflare Durable Object state storage
+ */
+class DurableObjectStorageProvider extends StorageProvider {
+  private state: NonNullable<StorageServiceConfig["durableObjectState"]>;
+
+  constructor(state: NonNullable<StorageServiceConfig["durableObjectState"]>) {
+    super();
+    this.state = state;
+  }
+
+  async get(key: string): Promise<string | null> {
+    const value = await this.state.storage.get(key);
+    return value ?? null;
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    await this.state.storage.put(key, value);
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.state.storage.delete(key);
+  }
+
+  async exists(key: string): Promise<boolean> {
+    const value = await this.state.storage.get(key);
+    return value !== undefined;
+  }
+
+  async list(prefix?: string): Promise<string[]> {
+    const result = await this.state.storage.list(
+      prefix ? { prefix } : undefined
+    );
+    return Array.from(result.keys());
+  }
+}
+
+/**
+ * Durable Object Nonce Cache Provider
+ */
+class DurableObjectNonceCacheProvider extends NonceCacheProvider {
+  private state: NonNullable<StorageServiceConfig["durableObjectState"]>;
+
+  constructor(state: NonNullable<StorageServiceConfig["durableObjectState"]>) {
+    super();
+    this.state = state;
+  }
+
+  async has(nonce: string, agentDid?: string): Promise<boolean> {
+    const key = agentDid
+      ? StorageKeyHelpers.buildNonceKey(agentDid, nonce)
+      : `nonce:${nonce}`;
+    const value = await this.state.storage.get(key);
+    if (!value) {
+      return false;
+    }
+    const expiresAt = parseInt(value, 10);
+    return Date.now() < expiresAt;
+  }
+
+  async add(
+    nonce: string,
+    ttlSeconds: number,
+    agentDid?: string
+  ): Promise<void> {
+    const key = agentDid
+      ? StorageKeyHelpers.buildNonceKey(agentDid, nonce)
+      : `nonce:${nonce}`;
+    // Convert TTL seconds to absolute expiration timestamp for storage
+    const expiresAt = Date.now() + ttlSeconds * 1000;
+    await this.state.storage.put(key, expiresAt.toString());
+  }
+
+  async cleanup(): Promise<void> {
+    // Durable Objects don't support efficient bulk operations
+    // Cleanup would require listing all keys, which is expensive
+    // For now, rely on TTL checking in has() method
+  }
+
+  async destroy(): Promise<void> {
+    // Durable Objects state persists automatically
+    // No explicit cleanup needed
+  }
+}
+
+/**
+ * Redis Storage Provider
+ * Uses Redis for storage operations
+ */
+class RedisStorageProvider extends StorageProvider {
+  private redis: any; // Redis client from 'redis' package
+
+  constructor(redisClient: any) {
+    super();
+    this.redis = redisClient;
+  }
+
+  async get(key: string): Promise<string | null> {
+    return await this.redis.get(key);
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    await this.redis.set(key, value);
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.redis.del(key);
+  }
+
+  async exists(key: string): Promise<boolean> {
+    const result = await this.redis.exists(key);
+    return result === 1;
+  }
+
+  async list(prefix?: string): Promise<string[]> {
+    const pattern = prefix ? `${prefix}*` : "*";
+    const keys = await this.redis.keys(pattern);
+    return keys;
+  }
+}
+
+/**
+ * Redis Nonce Cache Provider
+ */
+class RedisNonceCacheProvider extends NonceCacheProvider {
+  private redis: any;
+  private keyPrefix: string;
+
+  constructor(redisClient: any, keyPrefix = "nonce:") {
+    super();
+    this.redis = redisClient;
+    this.keyPrefix = keyPrefix;
+  }
+
+  async has(nonce: string, agentDid?: string): Promise<boolean> {
+    const key = agentDid
+      ? StorageKeyHelpers.buildNonceKey(agentDid, nonce)
+      : `${this.keyPrefix}${nonce}`;
+    const result = await this.redis.exists(key);
+    return result === 1;
+  }
+
+  async add(
+    nonce: string,
+    ttlSeconds: number,
+    agentDid?: string
+  ): Promise<void> {
+    const key = agentDid
+      ? StorageKeyHelpers.buildNonceKey(agentDid, nonce)
+      : `${this.keyPrefix}${nonce}`;
+    // Use TTL directly in seconds (callers now pass TTL, not absolute timestamp)
+    await this.redis.setEx(key, ttlSeconds, "1");
+  }
+
+  async cleanup(): Promise<void> {
+    // Redis handles TTL automatically, no cleanup needed
+  }
+
+  async destroy(): Promise<void> {
+    // Redis connection should be managed by caller
+  }
+}
+
+/**
+ * KV Storage Provider wrapper
+ * Uses existing KVStorageProvider from mcp-i-cloudflare
+ */
+/**
+ * Create Cloudflare KV storage providers
+ *
+ * This function dynamically imports Cloudflare-specific storage providers.
+ * The @ts-ignore is necessary because @kya-os/mcp-i-cloudflare/providers/storage
+ * is an optional dependency that may not exist in Node.js environments.
+ * This is intentional for platform-specific code - the import will fail at runtime
+ * if the module doesn't exist, which is handled by the try-catch block.
+ */
+async function createKVStorageProvider(
+  kvNamespace: StorageServiceConfig["kvNamespace"]
+): Promise<{ storage: StorageProvider; nonceCache: NonceCacheProvider }> {
+  // Dynamic import to avoid bundling Cloudflare-specific code
+  // This is an optional dependency that may not exist in all environments
+  try {
+    // Use string literal to avoid TypeScript checking the module path at compile time
+    const storageModulePath = "@kya-os/mcp-i-cloudflare/providers/storage";
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore TS2307 - Optional dependency: @kya-os/mcp-i-cloudflare/providers/storage
+    // may not exist in Node.js environments. This is intentional for platform-specific code.
+    const { KVStorageProvider, KVNonceCacheProvider } = await import(
+      storageModulePath
+    );
+
+    const storage = new KVStorageProvider(kvNamespace as any);
+    const nonceCache = new KVNonceCacheProvider(kvNamespace as any);
+
+    return { storage, nonceCache };
+  } catch (error) {
+    throw new Error(
+      `Failed to import Cloudflare storage providers: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Create storage providers based on configuration
+ *
+ * Priority order:
+ * 1. Redis (if redisUrl provided)
+ * 2. Cloudflare KV (if kvNamespace provided)
+ * 3. Cloudflare Durable Objects (if durableObjectState provided)
+ * 4. In-memory fallback (if fallbackToMemory is true, default)
+ */
+export async function createStorageProviders(
+  config: StorageServiceConfig
+): Promise<StorageProviders> {
+  const fallbackToMemory = config.fallbackToMemory !== false;
+
+  // Priority 1: Redis
+  if (config.redisUrl) {
+    try {
+      // Dynamic import to avoid bundling Redis in environments that don't need it
+      // Use string literal to avoid TypeScript checking the module path at compile time
+      const redisModulePath = "redis";
+
+      // @ts-ignore TS2307 - Optional dependency: 'redis' package may not be installed.
+      // This is intentional - the import will fail at runtime if Redis is not available,
+      // which is handled by the try-catch block.
+      const redisModule = await import(redisModulePath).catch(() => null);
+      if (!redisModule) {
+        throw new Error("Redis package not available");
+      }
+
+      const { createClient } = redisModule;
+      // @ts-ignore TS2307 - Type inference from dynamic import
+      // Redis client type is inferred from the runtime module
+      const redis = createClient({
+        url: config.redisUrl,
+        socket: {
+          connectTimeout: 5000,
+        },
+      });
+
+      await redis.connect();
+      await redis.ping();
+
+      const storageProvider = new RedisStorageProvider(redis);
+      const nonceCacheProvider = new RedisNonceCacheProvider(redis);
+
+      return {
+        storageProvider,
+        nonceCacheProvider,
+      };
+    } catch (error) {
+      if (!fallbackToMemory) {
+        throw error;
+      }
+      console.warn(
+        "[StorageService] Failed to connect to Redis, falling back to memory:",
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+
+  // Priority 2: Cloudflare KV
+  if (config.kvNamespace) {
+    try {
+      const providers = await createKVStorageProvider(config.kvNamespace);
+      return {
+        storageProvider: providers.storage,
+        nonceCacheProvider: providers.nonceCache,
+      };
+    } catch (error) {
+      if (!fallbackToMemory) {
+        throw error;
+      }
+      console.warn(
+        "[StorageService] Failed to initialize KV, falling back to memory:",
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+
+  // Priority 3: Cloudflare Durable Objects
+  if (config.durableObjectState) {
+    try {
+      const storageProvider = new DurableObjectStorageProvider(
+        config.durableObjectState as NonNullable<
+          StorageServiceConfig["durableObjectState"]
+        >
+      );
+      const nonceCacheProvider = new DurableObjectNonceCacheProvider(
+        config.durableObjectState as NonNullable<
+          StorageServiceConfig["durableObjectState"]
+        >
+      );
+
+      return {
+        storageProvider,
+        nonceCacheProvider,
+      };
+    } catch (error) {
+      if (!fallbackToMemory) {
+        throw error;
+      }
+      console.warn(
+        "[StorageService] Failed to initialize Durable Objects, falling back to memory:",
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+
+  // Priority 4: In-memory fallback
+  if (fallbackToMemory) {
+    return {
+      storageProvider: new MemoryStorageProvider(),
+      nonceCacheProvider: new MemoryNonceCacheProvider(),
+    };
+  }
+
+  throw new Error(
+    "No storage provider configured and fallbackToMemory is false"
+  );
+}
+
+/**
+ * Migration utility for legacy key formats
+ *
+ * Migrates keys from old format (e.g., `agent:${did}:delegation`) to new composite format
+ */
+export async function migrateLegacyKeys(
+  oldKeyPrefix: string,
+  newKeyFormat: (oldKey: string) => string | null,
+  storageProvider: StorageProvider,
+  batchSize = 100
+): Promise<number> {
+  let migrated = 0;
+
+  try {
+    // List all keys with old prefix
+    const oldKeys = await storageProvider.list(oldKeyPrefix);
+
+    for (const oldKey of oldKeys) {
+      const newKey = newKeyFormat(oldKey);
+      if (!newKey) {
+        continue; // Skip if transformation fails
+      }
+
+      // Check if new key already exists
+      const existing = await storageProvider.exists(newKey);
+      if (existing) {
+        continue; // Skip if already migrated
+      }
+
+      // Read old value
+      const value = await storageProvider.get(oldKey);
+      if (!value) {
+        continue; // Skip if old key has no value
+      }
+
+      // Write to new key
+      await storageProvider.set(newKey, value);
+
+      // Optionally delete old key (commented out for safety)
+      // await storageProvider.delete(oldKey);
+
+      migrated++;
+
+      if (migrated % batchSize === 0) {
+        // Yield to event loop for large migrations
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      }
+    }
+  } catch (error) {
+    console.error("[StorageService] Migration error:", error);
+    throw error;
+  }
+
+  return migrated;
+}