@kya-os/mcp-i-core 1.3.13 → 1.3.15

package/src/utils/cors.ts

@@ -1,83 +0,0 @@
-/**
- * CORS Header Utilities
- *
- * Centralized CORS header management for MCP-I services.
- * Includes Vary: Origin for cache optimization when origin scoping is implemented.
- */
-
-/**
- * Type-safe CORS headers
- * Compatible with Response headers and HeadersInit
- */
-export type CORSHeaders = Record<string, string>;
-
-/**
- * Standard CORS headers for well-known endpoints (.well-known/*)
- * Includes Vary: Origin for future cache optimization when origin scoping is added
- */
-export const WELL_KNOWN_CORS_HEADERS: CORSHeaders = {
-  'Access-Control-Allow-Origin': '*',
-  'Vary': 'Origin'
-};
-
-/**
- * CORS headers for MCP protocol responses
- * Includes exposed headers for session management
- */
-export const MCP_CORS_HEADERS: CORSHeaders = {
-  'Access-Control-Allow-Origin': '*',
-  'Access-Control-Expose-Headers': 'mcp-session-id',
-  'Vary': 'Origin'
-};
-
-/**
- * CORS preflight headers for OPTIONS requests
- * Comprehensive header allowlist for MCP protocol
- */
-export const PREFLIGHT_CORS_HEADERS: CORSHeaders = {
-  'Access-Control-Allow-Origin': '*',
-  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-  'Access-Control-Allow-Headers': 'Content-Type, Authorization, mcp-session-id, mcp-protocol-version',
-  'Vary': 'Origin'
-};
-
-/**
- * CORS headers for OAuth endpoints
- * Includes additional headers required for OAuth 2.0 flows
- */
-export const OAUTH_CORS_HEADERS: CORSHeaders = {
-  'Access-Control-Allow-Origin': '*',
-  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-  'Access-Control-Allow-Headers': 'Content-Type, Authorization, Accept, mcp-protocol-version',
-  'Access-Control-Expose-Headers': 'Content-Type',
-  'Vary': 'Origin'
-};
-
-/**
- * Merge CORS headers with existing headers
- * Ensures CORS headers take precedence
- */
-export function mergeCORSHeaders(
-  existingHeaders: Record<string, string>,
-  corsHeaders: CORSHeaders = WELL_KNOWN_CORS_HEADERS
-): Record<string, string> {
-  return {
-    ...existingHeaders,
-    ...corsHeaders
-  };
-}
-
-/**
- * Apply CORS headers to an Express Response object
- * For use with Express middleware
- */
-export function applyCORSHeaders(
-  res: { setHeader: (name: string, value: string) => void },
-  corsHeaders: CORSHeaders = MCP_CORS_HEADERS
-): void {
-  Object.entries(corsHeaders).forEach(([key, value]) => {
-    if (value !== undefined) {
-      res.setHeader(key, value);
-    }
-  });
-}

package/src/utils/did-helpers.ts

@@ -1,210 +0,0 @@
-/**
- * DID Validation and Helper Utilities
- *
- * Centralized utilities for DID validation, normalization, and handling.
- * Promotes DRY principle and consistency across the codebase.
- *
- * @package @kya-os/mcp-i-core/utils
- */
-
-import { base58Encode } from "./base58";
-
-/**
- * Check if a string is a valid DID format
- *
- * @param did - String to validate
- * @returns true if string starts with "did:"
- *
- * @example
- * ```typescript
- * isValidDid("did:key:z6Mk...") // true
- * isValidDid("not-a-did") // false
- * ```
- */
-export function isValidDid(did: string): boolean {
-  return typeof did === "string" && did.startsWith("did:");
-}
-
-/**
- * Get the DID method from a DID string
- *
- * @param did - DID string
- * @returns DID method (e.g., "key", "web") or null if invalid
- *
- * @example
- * ```typescript
- * getDidMethod("did:key:z6Mk...") // "key"
- * getDidMethod("did:web:example.com") // "web"
- * getDidMethod("invalid") // null
- * ```
- */
-export function getDidMethod(did: string): string | null {
-  if (!isValidDid(did)) {
-    return null;
-  }
-  const match = did.match(/^did:([^:]+):/);
-  return match ? match[1] : null;
-}
-
-/**
- * Normalize a DID string (trim whitespace)
- *
- * @param did - DID string to normalize
- * @returns Normalized DID string
- *
- * @example
- * ```typescript
- * normalizeDid("  did:key:z6Mk...  ") // "did:key:z6Mk..."
- * ```
- */
-export function normalizeDid(did: string): string {
-  return did.trim();
-}
-
-/**
- * Compare two DIDs for equality (case-sensitive)
- *
- * @param did1 - First DID
- * @param did2 - Second DID
- * @returns true if DIDs are equal (after normalization)
- *
- * @example
- * ```typescript
- * compareDids("did:key:z6Mk...", "did:key:z6Mk...") // true
- * compareDids("did:key:z6Mk...", "did:web:example.com") // false
- * ```
- */
-export function compareDids(did1: string, did2: string): boolean {
-  return normalizeDid(did1) === normalizeDid(did2);
-}
-
-/**
- * Extract server DID from config (supports both old and new field names)
- *
- * Supports backward compatibility by reading both `serverDid` and deprecated `agentDid`.
- * Prefers `serverDid` if both are present.
- *
- * @param config - Config object with identity field
- * @returns Server DID string
- * @throws Error if neither serverDid nor agentDid is configured
- *
- * @example
- * ```typescript
- * // New config
- * getServerDid({ identity: { serverDid: "did:web:server.com" } }) // "did:web:server.com"
- *
- * // Old config (backward compatibility)
- * getServerDid({ identity: { agentDid: "did:web:server.com" } }) // "did:web:server.com"
- *
- * // Prefers serverDid over agentDid
- * getServerDid({ identity: { serverDid: "new", agentDid: "old" } }) // "new"
- * ```
- */
-export function getServerDid(config: {
-  identity: { serverDid?: string; agentDid?: string };
-}): string {
-  const serverDid = config.identity.serverDid || config.identity.agentDid;
-  if (!serverDid) {
-    throw new Error("Server DID not configured");
-  }
-  return serverDid;
-}
-
-/**
- * Extract agent ID from DID
- *
- * The agent ID is the last component of the DID.
- *
- * @param did - DID string
- * @returns Agent ID (last component of DID)
- *
- * @example
- * ```typescript
- * extractAgentId("did:web:knowthat.ai:agents:my-agent") // "my-agent"
- * extractAgentId("did:web:localhost:3000:agents:12912feb") // "12912feb"
- * extractAgentId("did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK") // "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
- * ```
- */
-export function extractAgentId(did: string): string {
-  const parts = did.split(':');
-  return parts[parts.length - 1];
-}
-
-/**
- * Extract agent slug from DID
- *
- * Agent slug is the same as agent ID - the last component of the DID.
- * For DID format: did:web:knowthat.ai:agents:my-agent
- * Returns: my-agent
- *
- * @param did - DID string
- * @returns Agent slug (last component of DID)
- *
- * @example
- * ```typescript
- * extractAgentSlug("did:web:knowthat.ai:agents:my-agent") // "my-agent"
- * extractAgentSlug("did:web:localhost:3000:agents:12912feb") // "12912feb"
- * ```
- */
-export function extractAgentSlug(did: string): string {
-  return extractAgentId(did);
-}
-
-/**
- * Ed25519 multicodec prefix for did:key encoding
- * As per https://w3c-ccg.github.io/did-method-key/
- */
-const ED25519_MULTICODEC_PREFIX = new Uint8Array([0xed, 0x01]);
-
-/**
- * Generate a did:key from Ed25519 public key bytes
- *
- * Following spec: https://w3c-ccg.github.io/did-method-key/
- * Format: did:key:z<multibase-base58btc(<multicodec-ed25519-pub><publicKey>)>
- *
- * @param publicKeyBytes - Ed25519 public key as Uint8Array (32 bytes)
- * @returns did:key string
- *
- * @example
- * ```typescript
- * const publicKey = new Uint8Array(32); // 32-byte Ed25519 public key
- * const did = generateDidKeyFromBytes(publicKey);
- * // did = "did:key:z6Mk..."
- * ```
- */
-export function generateDidKeyFromBytes(publicKeyBytes: Uint8Array): string {
-  // Combine multicodec prefix + public key
-  const multicodecKey = new Uint8Array(
-    ED25519_MULTICODEC_PREFIX.length + publicKeyBytes.length
-  );
-  multicodecKey.set(ED25519_MULTICODEC_PREFIX);
-  multicodecKey.set(publicKeyBytes, ED25519_MULTICODEC_PREFIX.length);
-
-  // Base58-btc encode and add multibase prefix 'z'
-  const base58Encoded = base58Encode(multicodecKey);
-  return `did:key:z${base58Encoded}`;
-}
-
-/**
- * Generate a did:key from base64-encoded Ed25519 public key
- *
- * Convenience wrapper around generateDidKeyFromBytes for base64-encoded keys.
- *
- * @param publicKeyBase64 - Ed25519 public key as base64 string
- * @returns did:key string
- *
- * @example
- * ```typescript
- * const publicKeyBase64 = "...base64 encoded key...";
- * const did = generateDidKeyFromBase64(publicKeyBase64);
- * // did = "did:key:z6Mk..."
- * ```
- */
-export function generateDidKeyFromBase64(publicKeyBase64: string): string {
-  // Decode base64 to bytes
-  const publicKeyBytes = Uint8Array.from(atob(publicKeyBase64), (c) =>
-    c.charCodeAt(0)
-  );
-  return generateDidKeyFromBytes(publicKeyBytes);
-}
-

package/src/utils/index.ts

@@ -1,8 +0,0 @@
-/**
- * Utility exports
- */
-
-export * from "./cors";
-export * from "./base64";
-export * from "./storage-keys";
-export * from "./did-helpers";

package/src/utils/storage-keys.ts

@@ -1,278 +0,0 @@
-/**
- * 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

@@ -1,21 +0,0 @@
-{
-  "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", "**/__tests__/**"]
-}

package/vitest.config.ts

@@ -1,56 +0,0 @@
-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,
-      // },
-    },
-  },
-});