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

package/src/utils/storage-keys.ts

@@ -0,0 +1,278 @@
+/**
+ * Storage Key Migration Utilities
+ * 
+ * Provides utilities for migrating from old storage key formats to new composite formats.
+ * This supports Phase 3 Task 2 (StorageService) and Phase 4 (User DID identity linking).
+ * 
+ * @package @kya-os/mcp-i-core
+ */
+
+/**
+ * Legacy storage key format (agent-only, causes multi-tenant conflicts)
+ * Format: `agent:${agentDid}:delegation`
+ */
+export function legacyDelegationKey(agentDid: string): string {
+  return `agent:${agentDid}:delegation`;
+}
+
+/**
+ * New composite storage key format (user+agent scoped, prevents conflicts)
+ * Format: `delegation:user:${userDid}:agent:${agentDid}:project:${projectId}`
+ * 
+ * Note: projectId is optional for backward compatibility
+ */
+export function compositeDelegationKey(
+  userDid: string,
+  agentDid: string,
+  projectId?: string
+): string {
+  if (projectId) {
+    return `delegation:user:${userDid}:agent:${agentDid}:project:${projectId}`;
+  }
+  return `delegation:user:${userDid}:agent:${agentDid}`;
+}
+
+/**
+ * Session cache key format
+ * Format: `session:${sessionId}`
+ */
+export function sessionKey(sessionId: string): string {
+  return `session:${sessionId}`;
+}
+
+/**
+ * User DID storage key format
+ * Format: `userDid:oauth:${provider}:${subject}`
+ */
+export function userDidKey(provider: string, subject: string): string {
+  return `userDid:oauth:${provider}:${subject}`;
+}
+
+/**
+ * OAuth identity mapping key format
+ * Format: `oauth:${provider}:${subject}`
+ */
+export function oauthIdentityKey(provider: string, subject: string): string {
+  return `oauth:${provider}:${subject}`;
+}
+
+/**
+ * Verification cache key format
+ * Format: `verified:${tokenHash}`
+ */
+export function verificationCacheKey(tokenHash: string): string {
+  return `verified:${tokenHash}`;
+}
+
+/**
+ * Nonce tracking key format
+ * Format: `nonce:${nonce}`
+ */
+export function nonceKey(nonce: string): string {
+  return `nonce:${nonce}`;
+}
+
+/**
+ * Storage key migration result
+ */
+export interface MigrationResult {
+  /** Number of keys migrated */
+  migrated: number;
+  
+  /** Number of keys that failed to migrate */
+  failed: number;
+  
+  /** List of migrated key pairs (old -> new) */
+  migrations: Array<{ oldKey: string; newKey: string }>;
+  
+  /** List of errors encountered */
+  errors: Array<{ key: string; error: string }>;
+}
+
+/**
+ * Storage provider interface for migration operations
+ * 
+ * Matches the base StorageProvider abstract class contract.
+ */
+export interface StorageProvider {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  delete(key: string): Promise<void>;
+  exists(key: string): Promise<boolean>;
+  list(prefix?: string): Promise<string[]>;
+}
+
+/**
+ * Migrate delegation keys from legacy format to composite format
+ * 
+ * This function:
+ * 1. Finds all legacy keys (`agent:${did}:delegation`)
+ * 2. Attempts to extract userDid from session data or OAuth mappings
+ * 3. Creates new composite keys (`delegation:user:${userDid}:agent:${agentDid}`)
+ * 4. Copies values to new keys
+ * 5. Optionally deletes old keys (dry-run mode available)
+ * 
+ * @param storage - Storage provider instance
+ * @param options - Migration options
+ * @returns Migration result with statistics
+ */
+export async function migrateDelegationKeys(
+  storage: StorageProvider,
+  options: {
+    /** If true, only report what would be migrated without making changes */
+    dryRun?: boolean;
+    
+    /** If true, delete old keys after successful migration */
+    deleteOldKeys?: boolean;
+    
+    /** Optional userDid resolver function (if not provided, attempts to extract from session) */
+    resolveUserDid?: (agentDid: string, sessionId?: string) => Promise<string | null>;
+  } = {}
+): Promise<MigrationResult> {
+  const result: MigrationResult = {
+    migrated: 0,
+    failed: 0,
+    migrations: [],
+    errors: [],
+  };
+
+  try {
+    // Find all legacy delegation keys
+    const legacyKeys = await storage.list('agent:');
+    const delegationKeys = legacyKeys.filter((key) =>
+      key.match(/^agent:[^:]+:delegation$/)
+    );
+
+    console.log(`Found ${delegationKeys.length} legacy delegation keys to migrate`);
+
+    for (const oldKey of delegationKeys) {
+      try {
+        // Extract agentDid from key: `agent:${agentDid}:delegation`
+        const match = oldKey.match(/^agent:([^:]+):delegation$/);
+        if (!match) {
+          result.errors.push({
+            key: oldKey,
+            error: 'Invalid legacy key format',
+          });
+          result.failed++;
+          continue;
+        }
+
+        const agentDid = match[1];
+        
+        // Get the value from old key
+        const value = await storage.get(oldKey);
+        if (!value) {
+          // Key exists but has no value - skip
+          continue;
+        }
+
+        // Try to resolve userDid
+        let userDid: string | null = null;
+        let sessionId: string | undefined = undefined;
+        
+        // First, attempt to extract from session data to get both userDid and sessionId
+        const sessionKeys = await storage.list('session:');
+        for (const sessionKey of sessionKeys) {
+          const sessionData = await storage.get(sessionKey);
+          if (sessionData) {
+            try {
+              const parsed = JSON.parse(sessionData);
+              if (parsed.userDid && parsed.agentDid === agentDid) {
+                userDid = parsed.userDid;
+                // Extract sessionId from key: `session:${sessionId}`
+                const sessionMatch = sessionKey.match(/^session:(.+)$/);
+                if (sessionMatch) {
+                  sessionId = sessionMatch[1];
+                }
+                break;
+              }
+            } catch {
+              // Not JSON, skip
+            }
+          }
+        }
+        
+        // If custom resolver provided, use it (with sessionId context if available)
+        if (options.resolveUserDid) {
+          const resolvedUserDid = await options.resolveUserDid(agentDid, sessionId);
+          // Use resolved userDid if available, otherwise fall back to extracted one
+          if (resolvedUserDid) {
+            userDid = resolvedUserDid;
+          }
+        }
+
+        if (!userDid) {
+          // Cannot migrate without userDid - skip for now
+          result.errors.push({
+            key: oldKey,
+            error: 'Cannot resolve userDid - skipping migration',
+          });
+          result.failed++;
+          continue;
+        }
+
+        // Create new composite key
+        const newKey = compositeDelegationKey(userDid, agentDid);
+
+        if (options.dryRun) {
+          // Just record what would be migrated
+          result.migrations.push({ oldKey, newKey });
+          result.migrated++;
+        } else {
+          // Copy value to new key
+          await storage.set(newKey, value);
+          result.migrations.push({ oldKey, newKey });
+          result.migrated++;
+
+          // Optionally delete old key
+          if (options.deleteOldKeys) {
+            await storage.delete(oldKey);
+          }
+        }
+      } catch (error) {
+        result.errors.push({
+          key: oldKey,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        result.failed++;
+      }
+    }
+  } catch (error) {
+    result.errors.push({
+      key: 'migration',
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Storage key constants for consistent namespace management
+ * 
+ * These match the Phase 4 storage key architecture.
+ */
+export const STORAGE_KEYS = {
+  /** User DID storage (persistent - 90 days) */
+  userDid: userDidKey,
+  
+  /** OAuth identity mapping (persistent - 90 days) */
+  oauthIdentity: oauthIdentityKey,
+  
+  /** User+Agent delegation tokens (persistent - 7 days) */
+  delegation: compositeDelegationKey,
+  
+  /** Session cache (temporary - 30 minutes) */
+  session: sessionKey,
+  
+  /** Legacy delegation format (deprecated - 24 hours) */
+  legacyDelegation: legacyDelegationKey,
+  
+  /** Verification cache (temporary - 5 minutes) */
+  verificationCache: verificationCacheKey,
+  
+  /** Nonce tracking (temporary - 5 minutes) */
+  nonce: nonceKey,
+} as const;
+

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "moduleResolution": "node16",
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,56 @@
+import { defineConfig } from "vitest/config";
+import path from "path";
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      // Map contracts subpath exports to their actual dist paths for vitest resolution
+      // These aliases work for both source files and bundled code in node_modules
+      "@kya-os/contracts/proof": path.resolve(__dirname, "../contracts/dist/proof/index.js"),
+      "@kya-os/contracts/delegation": path.resolve(__dirname, "../contracts/dist/delegation/index.js"),
+      "@kya-os/contracts/agentshield-api": path.resolve(__dirname, "../contracts/dist/agentshield-api/index.js"),
+      "@kya-os/contracts/config": path.resolve(__dirname, "../contracts/dist/config/index.js"),
+      "@kya-os/contracts/tool-protection": path.resolve(__dirname, "../contracts/dist/tool-protection/index.js"),
+      "@kya-os/contracts/well-known": path.resolve(__dirname, "../contracts/dist/well-known/index.js"),
+      "@kya-os/contracts/runtime": path.resolve(__dirname, "../contracts/dist/runtime/index.js"),
+      "@kya-os/contracts/handshake": path.resolve(__dirname, "../contracts/dist/handshake.js"),
+      "@kya-os/contracts/test": path.resolve(__dirname, "../contracts/dist/test.js"),
+      "@kya-os/contracts": path.resolve(__dirname, "../contracts/dist/index.js"),
+    },
+    // Ensure aliases are resolved before node_modules
+    dedupe: ["@kya-os/contracts"],
+    // Force resolution to use workspace contracts
+    conditions: ["node", "import", "require"],
+  },
+  // Force vitest to inline contracts and mcp-i-core packages so aliases work
+  // This ensures that bundled code in node_modules can resolve contracts subpath exports
+  server: {
+    deps: {
+      inline: ["@kya-os/contracts", "@kya-os/mcp-i-core"],
+    },
+  },
+  test: {
+    globals: true,
+    environment: "node",
+    coverage: {
+      provider: "v8",
+      reporter: ["json", "text-summary"],
+      include: ["src/**/*.ts"],
+      exclude: [
+        "src/**/__tests__/**",
+        "src/**/*.test.ts",
+        "dist/**",
+        "node_modules/**",
+      ],
+      reportsDirectory: "./coverage",
+      clean: true,
+      // Coverage thresholds removed - will be re-enabled when coverage improves
+      // thresholds: {
+      //   lines: 80,
+      //   branches: 70,
+      //   functions: 80,
+      //   statements: 80,
+      // },
+    },
+  },
+});