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

package/src/identity/idp-token-storage.interface.ts

@@ -0,0 +1,59 @@
+/**
+ * IDP Token Storage Interface
+ *
+ * Platform-agnostic interface for storing and retrieving IDP tokens.
+ * Platform-specific implementations (Cloudflare KV, Node.js database, etc.)
+ * implement this interface.
+ *
+ * @package @kya-os/mcp-i-core
+ */
+
+import type { IdpTokens } from "@kya-os/contracts/config";
+
+/**
+ * Interface for IDP token storage
+ */
+export interface IIdpTokenStorage {
+  /**
+   * Store IDP tokens
+   *
+   * @param userDid - User DID to associate tokens with
+   * @param provider - OAuth provider name
+   * @param scopes - Scopes granted for these tokens
+   * @param tokens - IDP tokens to store
+   */
+  storeToken(
+    userDid: string,
+    provider: string,
+    scopes: string[],
+    tokens: IdpTokens
+  ): Promise<void>;
+
+  /**
+   * Retrieve IDP tokens
+   *
+   * @param userDid - User DID to retrieve tokens for
+   * @param provider - OAuth provider name
+   * @param scopes - Scopes to retrieve tokens for
+   * @returns IDP tokens or null if not found
+   */
+  getToken(
+    userDid: string,
+    provider: string,
+    scopes: string[]
+  ): Promise<IdpTokens | null>;
+
+  /**
+   * Delete IDP tokens
+   *
+   * @param userDid - User DID
+   * @param provider - OAuth provider name
+   * @param scopes - Scopes
+   */
+  deleteToken(
+    userDid: string,
+    provider: string,
+    scopes: string[]
+  ): Promise<void>;
+}
+

package/src/identity/user-did-manager.ts

@@ -0,0 +1,370 @@
+/**
+ * User DID Manager
+ *
+ * Handles ephemeral user DID generation for MCP-I sessions.
+ * Generates did:key DIDs for users when they join a chat session.
+ *
+ * This enables tracking which client/user initiated tool calls without
+ * requiring user registration or persistent identity.
+ */
+
+import { CryptoProvider } from '../providers/base';
+
+/**
+ * OAuth identity for persistent user DID lookup
+ */
+export interface OAuthIdentity {
+  /**
+   * OAuth provider name (e.g., "google", "github", "microsoft")
+   */
+  provider: string;
+
+  /**
+   * OAuth subject identifier (unique user ID from provider)
+   */
+  subject: string;
+
+  /**
+   * User's email address from OAuth provider (optional)
+   */
+  email?: string;
+
+  /**
+   * User's display name from OAuth provider (optional)
+   */
+  name?: string;
+}
+
+/**
+ * User DID storage interface
+ */
+export interface UserDidStorage {
+  /**
+   * Get user DID for a session
+   */
+  get(sessionId: string): Promise<string | null>;
+
+  /**
+   * Store user DID for a session
+   */
+  set(sessionId: string, did: string, ttl?: number): Promise<void>;
+
+  /**
+   * Delete user DID for a session
+   */
+  delete(sessionId: string): Promise<void>;
+
+  /**
+   * Get user DID by OAuth identity (optional - for persistent user DID lookup)
+   * If not implemented, OAuth-based lookup will be skipped
+   */
+  getByOAuth?(provider: string, subject: string): Promise<string | null>;
+
+  /**
+   * Store user DID mapping for OAuth identity (optional - for persistent user DID storage)
+   * If not implemented, OAuth-based storage will be skipped
+   */
+  setByOAuth?(provider: string, subject: string, did: string, ttl?: number): Promise<void>;
+}
+
+/**
+ * User DID Manager configuration
+ */
+export interface UserDidManagerConfig {
+  /**
+   * Storage provider for user DIDs (optional)
+   * If not provided, user DIDs are ephemeral (not persisted)
+   */
+  storage?: UserDidStorage;
+
+  /**
+   * Crypto provider for DID generation
+   */
+  crypto: CryptoProvider;
+
+  /**
+   * Generate did:web format instead of did:key (requires additional setup)
+   */
+  useDidWeb?: boolean;
+
+  /**
+   * Base URL for did:web (required if useDidWeb is true)
+   */
+  didWebBaseUrl?: string;
+}
+
+/**
+ * User DID Manager
+ *
+ * Generates and manages user DIDs for MCP-I sessions.
+ * Supports both ephemeral (did:key) and persistent (did:web) formats.
+ */
+export class UserDidManager {
+  private config: UserDidManagerConfig;
+  private sessionDidCache = new Map<string, string>();
+
+  constructor(config: UserDidManagerConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Generate or retrieve user DID for a session
+   *
+   * If a user DID already exists for the session, it is returned.
+   * If OAuth identity is provided, checks for persistent user DID mapping first.
+   * Otherwise, a new ephemeral did:key is generated.
+   *
+   * @param sessionId - MCP session ID
+   * @param oauthIdentity - Optional OAuth identity for persistent user DID lookup
+   * @returns User DID (did:key format)
+   *
+   * @remarks
+   * - If OAuth identity provided, checks for existing mapping first
+   * - Falls back to ephemeral DID generation if OAuth unavailable
+   * - Caches result in session storage for performance
+   */
+  async getOrCreateUserDid(sessionId: string, oauthIdentity?: OAuthIdentity | null): Promise<string> {
+    // Check cache first
+    if (this.sessionDidCache.has(sessionId)) {
+      return this.sessionDidCache.get(sessionId)!;
+    }
+
+    // PRIORITY 1: If OAuth identity provided, check for persistent user DID mapping
+    if (oauthIdentity && oauthIdentity.provider && oauthIdentity.subject && this.config.storage?.getByOAuth) {
+      try {
+        const persistentUserDid = await this.config.storage.getByOAuth(
+          oauthIdentity.provider,
+          oauthIdentity.subject
+        );
+        if (persistentUserDid) {
+          console.log('[UserDidManager] Found persistent user DID from OAuth mapping:', {
+            provider: oauthIdentity.provider,
+            userDid: persistentUserDid.substring(0, 20) + '...',
+          });
+          // Cache it for this session
+          this.sessionDidCache.set(sessionId, persistentUserDid);
+          // Also store in session storage for faster future lookups
+          if (this.config.storage) {
+            try {
+              await this.config.storage.set(sessionId, persistentUserDid, 1800); // 30 minutes TTL
+            } catch (error) {
+              // Log but continue - DID is cached and will be returned
+              console.warn('[UserDidManager] Failed to cache persistent DID in session storage:', error);
+            }
+          }
+          return persistentUserDid;
+        }
+      } catch (error) {
+        // Log but continue - will check session storage or generate new DID
+        console.warn('[UserDidManager] OAuth lookup failed, falling back to session storage:', error);
+      }
+    }
+
+    // PRIORITY 2: Check session storage if available
+    if (this.config.storage) {
+      try {
+        const storedDid = await this.config.storage.get(sessionId);
+        if (storedDid) {
+          this.sessionDidCache.set(sessionId, storedDid);
+          // If OAuth identity provided but no persistent mapping found, create one now
+          if (oauthIdentity && oauthIdentity.provider && oauthIdentity.subject && this.config.storage.setByOAuth) {
+            try {
+              await this.config.storage.setByOAuth(
+                oauthIdentity.provider,
+                oauthIdentity.subject,
+                storedDid,
+                90 * 24 * 60 * 60 // 90 days TTL for persistent mapping
+              );
+              console.log('[UserDidManager] Created persistent OAuth mapping for existing user DID:', {
+                provider: oauthIdentity.provider,
+                userDid: storedDid.substring(0, 20) + '...',
+              });
+            } catch (error) {
+              // Log but continue - mapping creation failed, but DID is still valid
+              console.warn('[UserDidManager] Failed to create OAuth mapping:', error);
+            }
+          }
+          return storedDid;
+        }
+      } catch (error) {
+        // Log but continue - will generate new DID
+        console.warn('[UserDidManager] Storage.get failed, generating new DID:', error);
+      }
+    }
+
+    // PRIORITY 3: Generate new user DID
+    const userDid = await this.generateUserDid();
+
+    // Cache it
+    this.sessionDidCache.set(sessionId, userDid);
+
+    // Store it if storage is available
+    if (this.config.storage) {
+      try {
+        await this.config.storage.set(sessionId, userDid, 1800); // 30 minutes TTL
+      } catch (error) {
+        // Log but continue - DID is cached and will be returned
+        console.warn('[UserDidManager] Storage.set failed, continuing with cached DID:', error);
+      }
+    }
+
+    // If OAuth identity provided, create persistent mapping
+    if (oauthIdentity && oauthIdentity.provider && oauthIdentity.subject && this.config.storage?.setByOAuth) {
+      try {
+        await this.config.storage.setByOAuth(
+          oauthIdentity.provider,
+          oauthIdentity.subject,
+          userDid,
+          90 * 24 * 60 * 60 // 90 days TTL for persistent mapping
+        );
+        console.log('[UserDidManager] Created persistent OAuth mapping for new user DID:', {
+          provider: oauthIdentity.provider,
+          userDid: userDid.substring(0, 20) + '...',
+        });
+      } catch (error) {
+        // Log but continue - mapping creation failed, but DID is still valid
+        console.warn('[UserDidManager] Failed to create OAuth mapping:', error);
+      }
+    }
+
+    return userDid;
+  }
+
+  /**
+   * Generate a new ephemeral user DID
+   *
+   * Uses did:key format by default for simplicity.
+   * did:web can be used if configured, but requires additional setup.
+   */
+  private async generateUserDid(): Promise<string> {
+    if (this.config.useDidWeb && this.config.didWebBaseUrl) {
+      // Generate did:web (requires web server setup)
+      // For now, fall back to did:key
+      // TODO: Implement did:web generation if needed
+      console.warn('[UserDidManager] did:web not yet implemented, using did:key');
+    }
+
+    // Generate Ed25519 keypair for user DID
+    const keyPair = await this.config.crypto.generateKeyPair();
+    
+    // Extract public key bytes (32 bytes for Ed25519)
+    const publicKeyBytes = this.base64ToBytes(keyPair.publicKey);
+    
+    // Generate did:key from public key
+    return this.generateDidKeyFromPublicKey(publicKeyBytes);
+  }
+
+  /**
+   * Generate 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>)>
+   */
+  private generateDidKeyFromPublicKey(publicKeyBytes: Uint8Array): string {
+    // Ed25519 multicodec prefix (0xed 0x01)
+    const multicodecPrefix = new Uint8Array([0xed, 0x01]);
+
+    // Combine prefix + public key
+    const multicodecKey = new Uint8Array(multicodecPrefix.length + publicKeyBytes.length);
+    multicodecKey.set(multicodecPrefix);
+    multicodecKey.set(publicKeyBytes, multicodecPrefix.length);
+
+    // Base58 encode (using a simple implementation)
+    // Note: For production, consider using base-x library
+    const base58Encoded = this.base58Encode(multicodecKey);
+
+    // Add multibase prefix 'z' for base58-btc
+    return `did:key:z${base58Encoded}`;
+  }
+
+  /**
+   * Base58 encode (Bitcoin alphabet)
+   * Simple implementation for did:key generation
+   */
+  private base58Encode(bytes: Uint8Array): string {
+    const alphabet = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+    let num = BigInt(0);
+    
+    // Convert bytes to big integer
+    for (let i = 0; i < bytes.length; i++) {
+      num = num * BigInt(256) + BigInt(bytes[i]);
+    }
+    
+    // Convert to base58
+    let result = '';
+    while (num > 0) {
+      result = alphabet[Number(num % BigInt(58))] + result;
+      num = num / BigInt(58);
+    }
+    
+    // Add leading zeros
+    for (let i = 0; i < bytes.length && bytes[i] === 0; i++) {
+      result = '1' + result;
+    }
+    
+    return result;
+  }
+
+  /**
+   * Convert base64 string to Uint8Array
+   */
+  private base64ToBytes(base64: string): Uint8Array {
+    if (typeof Buffer !== 'undefined') {
+      // Node.js environment
+      return new Uint8Array(Buffer.from(base64, 'base64'));
+    } else {
+      // Browser/Workers environment
+      const binaryString = atob(base64);
+      const bytes = new Uint8Array(binaryString.length);
+      for (let i = 0; i < binaryString.length; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+      }
+      return bytes;
+    }
+  }
+
+  /**
+   * Get user DID for a session without creating one
+   */
+  async getUserDid(sessionId: string): Promise<string | null> {
+    // Check cache
+    if (this.sessionDidCache.has(sessionId)) {
+      return this.sessionDidCache.get(sessionId)!;
+    }
+
+    // Check storage
+    if (this.config.storage) {
+      const storedDid = await this.config.storage.get(sessionId);
+      if (storedDid) {
+        this.sessionDidCache.set(sessionId, storedDid);
+        return storedDid;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Clear user DID for a session
+   */
+  async clearUserDid(sessionId: string): Promise<void> {
+    this.sessionDidCache.delete(sessionId);
+
+    if (this.config.storage) {
+      try {
+        await this.config.storage.delete(sessionId);
+      } catch (error) {
+        // Log but continue - cache is already cleared
+        console.warn('[UserDidManager] Storage.delete failed, continuing:', error);
+      }
+    }
+  }
+
+  /**
+   * Clear all cached user DIDs (useful for testing)
+   */
+  clearCache(): void {
+    this.sessionDidCache.clear();
+  }
+}
+

package/src/index.ts

@@ -0,0 +1,260 @@
+/**
+ * @kya-os/mcp-i-core
+ *
+ * Core provider-based architecture for MCP-I framework.
+ * Platform-agnostic runtime that can be extended for any environment.
+ */
+
+// Base providers
+export {
+  CryptoProvider,
+  ClockProvider,
+  FetchProvider,
+  StorageProvider,
+  NonceCacheProvider,
+  IdentityProvider,
+  type AgentIdentity,
+} from "./providers/base";
+
+// Memory providers
+export {
+  MemoryStorageProvider,
+  MemoryNonceCacheProvider,
+  MemoryIdentityProvider,
+} from "./providers/memory";
+
+// Runtime
+export { MCPIRuntimeBase } from "./runtime/base";
+export type { RuntimeWithAccessControl } from "./runtime/base";
+
+// Audit Logger Interface
+export type { IAuditLogger } from "./runtime/audit-logger";
+
+// Utilities
+export * from "./utils";
+// Tool Protection
+export { ToolProtectionService } from "./services/tool-protection.service";
+
+// Crypto Service
+export { CryptoService } from "./services/crypto.service";
+
+export type { Ed25519JWK, ParsedJWS } from "./services/crypto.service";
+
+// Proof Verifier Service
+export { ProofVerifier } from "./services/proof-verifier";
+
+export type {
+  ProofVerificationResult,
+  ProofVerifierConfig,
+} from "./services/proof-verifier";
+
+// Access Control API Service (stub for Phase 3)
+export { AccessControlApiService } from "./services/access-control.service";
+
+export type {
+  AccessControlApiServiceConfig,
+  AccessControlApiServiceMetrics,
+} from "./services/access-control.service";
+
+// OAuth Config Service (Phase 1)
+export { OAuthConfigService } from "./services/oauth-config.service";
+
+export type { OAuthConfigServiceConfig } from "./services/oauth-config.service";
+
+// OAuth Service (Phase 1)
+export { OAuthService } from "./services/oauth-service";
+
+export type { OAuthServiceConfig } from "./services/oauth-service";
+
+// Tool Context Builder (Phase 1)
+export { ToolContextBuilder } from "./services/tool-context-builder";
+
+export type { ToolContextBuilderConfig } from "./services/tool-context-builder";
+
+// OAuth Provider Registry (Phase 2)
+export { OAuthProviderRegistry } from "./services/oauth-provider-registry";
+
+// Provider Resolver (Phase 2)
+export { ProviderResolver } from "./services/provider-resolver";
+
+// Provider Validator (Phase 3)
+export { ProviderValidator, ProviderValidationError } from "./services/provider-validator";
+
+// OAuth Token Retrieval Service (Phase 3)
+export { OAuthTokenRetrievalService } from "./services/oauth-token-retrieval.service";
+export type { OAuthTokenRetrievalServiceConfig } from "./services/oauth-token-retrieval.service";
+
+// Batch Delegation Service (Phase 2)
+export { BatchDelegationService } from "./services/batch-delegation.service";
+export type { ToolGroup } from "./services/batch-delegation.service";
+
+// OAuth Config Cache
+export {
+  InMemoryOAuthConfigCache,
+  NoOpOAuthConfigCache,
+} from "./cache/oauth-config-cache";
+
+export type { OAuthConfigCache } from "./cache/oauth-config-cache";
+
+// Storage Service Factory
+export {
+  createStorageProviders,
+  StorageKeyHelpers,
+  migrateLegacyKeys,
+} from "./services/storage.service";
+
+export type {
+  StorageServiceConfig,
+  StorageProviders,
+} from "./services/storage.service";
+
+// Proof Verification Errors
+export {
+  ProofVerificationError,
+  PROOF_VERIFICATION_ERROR_CODES,
+  createProofVerificationError,
+} from "./services/errors";
+
+export type { ProofVerificationErrorCode } from "./services/errors";
+
+export {
+  ToolProtectionCache,
+  InMemoryToolProtectionCache,
+  NoOpToolProtectionCache,
+} from "./cache/tool-protection-cache";
+
+export type {
+  ToolProtection,
+  ToolProtectionConfig,
+  ToolProtectionServiceConfig,
+} from "./types/tool-protection";
+
+export { DelegationRequiredError } from "./types/tool-protection";
+export { OAuthRequiredError } from "./types/oauth-required-error";
+export type { OAuthRequiredErrorOptions } from "./types/oauth-required-error";
+
+// Delegation (W3C VC-based)
+export {
+  DelegationCredentialIssuer,
+  createDelegationIssuer,
+  type IssueDelegationOptions,
+  type VCSigningFunction,
+  type IdentityProvider as DelegationIdentityProvider,
+} from "./delegation/vc-issuer";
+
+export {
+  DelegationCredentialVerifier,
+  createDelegationVerifier,
+  type DelegationVCVerificationResult,
+  type VerifyDelegationVCOptions,
+  type DIDResolver,
+  type DIDDocument,
+  type VerificationMethod,
+  type StatusListResolver,
+  type SignatureVerificationFunction,
+} from "./delegation/vc-verifier";
+
+// StatusList2021
+export {
+  StatusList2021Manager,
+  createStatusListManager,
+  type StatusListStorageProvider,
+  type StatusListIdentityProvider,
+} from "./delegation/statuslist-manager";
+
+export {
+  BitstringManager,
+  isIndexSet,
+  type CompressionFunction,
+  type DecompressionFunction,
+} from "./delegation/bitstring";
+
+// Delegation Graph & Cascading Revocation
+export {
+  DelegationGraphManager,
+  createDelegationGraph,
+  type DelegationNode,
+  type DelegationGraphStorageProvider,
+} from "./delegation/delegation-graph";
+
+export {
+  CascadingRevocationManager,
+  createCascadingRevocationManager,
+  type RevocationEvent,
+  type RevocationHook,
+  type CascadingRevocationOptions,
+} from "./delegation/cascading-revocation";
+
+// Storage Implementations (for testing and examples)
+export { MemoryStatusListStorage } from "./delegation/storage/memory-statuslist-storage";
+
+export { MemoryDelegationGraphStorage } from "./delegation/storage/memory-graph-storage";
+
+// Compliance Verification (with JSON Schema draft-07 support)
+export {
+  SchemaVerifier,
+  createSchemaVerifier,
+  type SchemaMetadata,
+  type FieldComplianceResult,
+  type SchemaComplianceReport,
+  type FullComplianceReport,
+} from "./compliance/schema-verifier";
+
+export {
+  SCHEMA_REGISTRY,
+  getAllSchemas,
+  getSchemasByCategory,
+  getSchemaById,
+  getCriticalSchemas,
+  getSchemaStats,
+} from "./compliance/schema-registry";
+
+export { canonicalizeJSON } from "./delegation/utils";
+
+// Re-export commonly used types from contracts
+// Note: @kya-os/contracts exports are at the root level
+import type {
+  HandshakeRequest,
+  SessionContext,
+  NonceCache,
+  NonceCacheEntry,
+  NonceCacheConfig,
+  ProofMeta,
+  DetachedProof,
+  CanonicalHashes,
+  AuditRecord,
+} from "@kya-os/contracts";
+
+export type {
+  HandshakeRequest,
+  SessionContext,
+  NonceCache,
+  NonceCacheEntry,
+  NonceCacheConfig,
+  ProofMeta,
+  DetachedProof,
+  CanonicalHashes,
+  AuditRecord,
+};
+
+// Configuration types and utilities
+export * from "./config";
+
+// Remote configuration fetching
+export {
+  fetchRemoteConfig,
+  type RemoteConfigCache,
+  type RemoteConfigOptions,
+} from "./config/remote-config";
+
+// User DID Manager (Phase 4)
+export { UserDidManager } from "./identity/user-did-manager";
+export type {
+  UserDidStorage,
+  UserDidManagerConfig,
+} from "./identity/user-did-manager";
+
+// IDP Token Resolver (Phase 1 - MH-7)
+export { IdpTokenResolver } from "./identity/idp-token-resolver";
+export type { IdpTokenResolverConfig } from "./identity/idp-token-resolver";
+export type { IIdpTokenStorage } from "./identity/idp-token-storage.interface";