@kya-os/mcp-i-core 1.3.12 → 1.3.14

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

@@ -1,526 +0,0 @@
-/**
- * User DID Manager
- *
- * Manages user DIDs for MCP-I sessions.
- *
- * Phase 5: Anonymous Sessions Until OAuth
- * - Sessions start anonymous (no userDid) until OAuth completes
- * - User DIDs are resolved via AgentShield identity/resolve after OAuth
- * - Eliminates DID fragmentation (same user = same DID across sessions)
- *
- * DID Resolution Priority:
- * 1. OAuth mapping lookup (persistent)
- * 2. Session storage lookup
- * 3. Return null (session stays anonymous)
- */
-
-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 key pair for signing VCs
- *
- * Contains both public and private keys in base64 format.
- * SECURITY: Private keys should be encrypted at rest.
- */
-export interface UserKeyPair {
-  /**
-   * User DID (did:key format)
-   */
-  did: string;
-
-  /**
-   * Public key in base64 format
-   */
-  publicKey: string;
-
-  /**
-   * Private key in base64 format
-   * SECURITY: Should be encrypted at rest in production
-   */
-  privateKey: string;
-
-  /**
-   * Key ID (for JWS header)
-   */
-  keyId: 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>;
-
-  /**
-   * Get user key pair for a session (optional - for VC signing)
-   * If not implemented, VC issuance will not be available for this session
-   */
-  getKeyPair?(sessionId: string): Promise<UserKeyPair | null>;
-
-  /**
-   * Store user key pair for a session (optional - for VC signing)
-   * SECURITY: Implementation should encrypt private keys at rest
-   */
-  setKeyPair?(sessionId: string, keyPair: UserKeyPair, ttl?: number): Promise<void>;
-
-  /**
-   * Get user key pair by OAuth identity (optional - for persistent key storage)
-   * If not implemented, OAuth-based key lookup will be skipped
-   */
-  getKeyPairByOAuth?(provider: string, subject: string): Promise<UserKeyPair | null>;
-
-  /**
-   * Store user key pair for OAuth identity (optional - for persistent key storage)
-   * SECURITY: Implementation should encrypt private keys at rest
-   */
-  setKeyPairByOAuth?(
-    provider: string,
-    subject: string,
-    keyPair: UserKeyPair,
-    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>();
-  private sessionKeyPairCache = new Map<string, UserKeyPair>();
-
-  constructor(config: UserDidManagerConfig) {
-    this.config = config;
-  }
-
-  /**
-   * Get key pair for a session (for VC signing)
-   *
-   * Returns the key pair if available, null otherwise.
-   * Key pairs are stored when DIDs are generated.
-   *
-   * @param sessionId - MCP session ID
-   * @param oauthIdentity - Optional OAuth identity for persistent lookup
-   * @returns UserKeyPair or null if not available
-   */
-  async getKeyPairForSession(
-    sessionId: string,
-    oauthIdentity?: OAuthIdentity | null
-  ): Promise<UserKeyPair | null> {
-    // Check in-memory cache first
-    if (this.sessionKeyPairCache.has(sessionId)) {
-      return this.sessionKeyPairCache.get(sessionId)!;
-    }
-
-    // Check OAuth-based persistent storage if available
-    if (
-      oauthIdentity?.provider &&
-      oauthIdentity?.subject &&
-      this.config.storage?.getKeyPairByOAuth
-    ) {
-      try {
-        const keyPair = await this.config.storage.getKeyPairByOAuth(
-          oauthIdentity.provider,
-          oauthIdentity.subject
-        );
-        if (keyPair) {
-          this.sessionKeyPairCache.set(sessionId, keyPair);
-          return keyPair;
-        }
-      } catch (error) {
-        console.warn('[UserDidManager] OAuth key pair lookup failed:', error);
-      }
-    }
-
-    // Check session storage if available
-    if (this.config.storage?.getKeyPair) {
-      try {
-        const keyPair = await this.config.storage.getKeyPair(sessionId);
-        if (keyPair) {
-          this.sessionKeyPairCache.set(sessionId, keyPair);
-          return keyPair;
-        }
-      } catch (error) {
-        console.warn('[UserDidManager] Session key pair lookup failed:', error);
-      }
-    }
-
-    return null;
-  }
-
-  /**
-   * Get user DID for a session (Phase 5: No ephemeral generation)
-   *
-   * If a user DID already exists for the session, it is returned.
-   * If OAuth identity is provided, checks for persistent user DID mapping.
-   * Returns null if no DID found - session stays anonymous until OAuth completes.
-   *
-   * @param sessionId - MCP session ID
-   * @param oauthIdentity - Optional OAuth identity for persistent user DID lookup
-   * @returns User DID (did:key format) or null if session is anonymous
-   *
-   * @remarks
-   * - Phase 5: Sessions start anonymous, no ephemeral DID generation
-   * - User DIDs are resolved via AgentShield after OAuth completes
-   * - Returns null if no existing DID found (instead of generating ephemeral)
-   */
-  async getOrCreateUserDid(sessionId: string, oauthIdentity?: OAuthIdentity | null): Promise<string | null> {
-    // 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 - session will be anonymous
-        console.warn('[UserDidManager] Storage.get failed:', error);
-      }
-    }
-
-    // PHASE 5: No ephemeral DID generation - session stays anonymous
-    // User DID will be resolved via AgentShield after OAuth completes
-    return null;
-  }
-
-  /**
-   * Set user DID for a session (Phase 5: After OAuth resolution)
-   *
-   * Called after AgentShield identity/resolve returns a persistent user DID.
-   * Caches the DID and optionally stores in session storage.
-   *
-   * @param sessionId - MCP session ID
-   * @param userDid - Persistent user DID from AgentShield
-   * @param oauthIdentity - OAuth identity for creating persistent mappings
-   */
-  async setUserDidForSession(
-    sessionId: string,
-    userDid: string,
-    oauthIdentity?: OAuthIdentity | null
-  ): Promise<void> {
-    // Cache in memory
-    this.sessionDidCache.set(sessionId, userDid);
-
-    // Store in session storage if available
-    if (this.config.storage) {
-      try {
-        await this.config.storage.set(sessionId, userDid, 1800); // 30 minutes TTL
-      } catch (error) {
-        console.warn('[UserDidManager] Failed to store user DID in session storage:', error);
-      }
-    }
-
-    // Create OAuth mapping if provided
-    if (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 OAuth → DID mapping:', {
-          provider: oauthIdentity.provider,
-          userDid: userDid.substring(0, 20) + '...',
-        });
-      } catch (error) {
-        console.warn('[UserDidManager] Failed to create OAuth mapping:', error);
-      }
-    }
-  }
-
-  /**
-   * 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> {
-    const keyPairData = await this.generateUserDidWithKeyPair();
-    return keyPairData.did;
-  }
-
-  /**
-   * Generate a new ephemeral user DID with full key pair
-   *
-   * Returns the DID along with the key pair for VC signing.
-   * Uses did:key format by default.
-   *
-   * @returns UserKeyPair containing DID, public key, private key, and key ID
-   */
-  private async generateUserDidWithKeyPair(): Promise<UserKeyPair> {
-    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
-    const did = this.generateDidKeyFromPublicKey(publicKeyBytes);
-
-    // Key ID is the DID with #keys-1 fragment (standard for did:key)
-    const keyId = `${did}#keys-1`;
-
-    return {
-      did,
-      publicKey: keyPair.publicKey,
-      privateKey: keyPair.privateKey,
-      keyId,
-    };
-  }
-
-  /**
-   * 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();
-  }
-}
-