@kya-os/mcp-i-core 1.3.10-canary.clientinfo.20251126124133 → 1.3.10

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

@@ -1,11 +1,17 @@
 /**
  * User DID Manager
  *
- * Handles ephemeral user DID generation for MCP-I sessions.
- * Generates did:key DIDs for users when they join a chat session.
+ * Manages user DIDs for MCP-I sessions.
  *
- * This enables tracking which client/user initiated tool calls without
- * requiring user registration or persistent identity.
+ * 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';
@@ -35,6 +41,35 @@ export interface OAuthIdentity {
   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
  */
@@ -65,6 +100,35 @@ export interface UserDidStorage {
    * 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>;
 }
 
 /**
@@ -102,28 +166,84 @@ export interface UserDidManagerConfig {
 export class UserDidManager {
   private config: UserDidManagerConfig;
   private sessionDidCache = new Map<string, string>();
+  private sessionKeyPairCache = new Map<string, UserKeyPair>();
 
   constructor(config: UserDidManagerConfig) {
     this.config = config;
   }
 
   /**
-   * Generate or retrieve user DID for a session
+   * 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 first.
-   * Otherwise, a new ephemeral did:key is generated.
+   * 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)
+   * @returns User DID (did:key format) or null if session is anonymous
    *
    * @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
+   * - 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> {
+  async getOrCreateUserDid(sessionId: string, oauthIdentity?: OAuthIdentity | null): Promise<string | null> {
     // Check cache first
     if (this.sessionDidCache.has(sessionId)) {
       return this.sessionDidCache.get(sessionId)!;
@@ -187,29 +307,45 @@ export class UserDidManager {
           return storedDid;
         }
       } catch (error) {
-        // Log but continue - will generate new DID
-        console.warn('[UserDidManager] Storage.get failed, generating new DID:', error);
+        // Log but continue - session will be anonymous
+        console.warn('[UserDidManager] Storage.get failed:', error);
       }
     }
 
-    // PRIORITY 3: Generate new user DID
-    const userDid = await this.generateUserDid();
+    // PHASE 5: No ephemeral DID generation - session stays anonymous
+    // User DID will be resolved via AgentShield after OAuth completes
+    return null;
+  }
 
-    // Cache it
+  /**
+   * 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 it if storage is available
+    // Store in session storage if 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);
+        console.warn('[UserDidManager] Failed to store user DID in session storage:', error);
       }
     }
 
-    // If OAuth identity provided, create persistent mapping
-    if (oauthIdentity && oauthIdentity.provider && oauthIdentity.subject && this.config.storage?.setByOAuth) {
+    // Create OAuth mapping if provided
+    if (oauthIdentity?.provider && oauthIdentity?.subject && this.config.storage?.setByOAuth) {
       try {
         await this.config.storage.setByOAuth(
           oauthIdentity.provider,
@@ -217,17 +353,14 @@ export class UserDidManager {
           userDid,
           90 * 24 * 60 * 60 // 90 days TTL for persistent mapping
         );
-        console.log('[UserDidManager] Created persistent OAuth mapping for new user DID:', {
+        console.log('[UserDidManager] Created OAuth → DID mapping:', {
           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;
   }
 
   /**
@@ -237,6 +370,19 @@ export class UserDidManager {
    * 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
@@ -246,12 +392,22 @@ export class UserDidManager {
 
     // 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);
+    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,
+    };
   }
 
   /**

package/src/index.ts

@@ -201,6 +201,22 @@ export { MemoryStatusListStorage } from "./delegation/storage/memory-statuslist-
 
 export { MemoryDelegationGraphStorage } from "./delegation/storage/memory-graph-storage";
 
+// DID:key Resolver (Phase 3 VC Verification)
+export {
+  createDidKeyResolver,
+  isEd25519DidKey,
+  extractPublicKeyFromDidKey,
+  publicKeyToJwk,
+  resolveDidKeySync,
+} from "./delegation/did-key-resolver";
+
+// Base58 Utilities (for did:key encoding/decoding)
+export {
+  base58Encode,
+  base58Decode,
+  isValidBase58,
+} from "./utils/base58";
+
 // Compliance Verification (with JSON Schema draft-07 support)
 export {
   SchemaVerifier,
@@ -220,7 +236,24 @@ export {
   getSchemaStats,
 } from "./compliance/schema-registry";
 
-export { canonicalizeJSON } from "./delegation/utils";
+export {
+  canonicalizeJSON,
+  createUnsignedVCJWT,
+  completeVCJWT,
+  parseVCJWT,
+  type VCJWTHeader,
+  type VCJWTPayload,
+  type EncodeVCAsJWTOptions,
+} from "./delegation/utils";
+
+// Base64 utilities for VC JWT encoding
+export {
+  base64urlEncodeFromBytes,
+  base64urlEncodeFromString,
+  base64urlDecodeToBytes,
+  base64urlDecodeToString,
+  bytesToBase64,
+} from "./utils/base64";
 
 // Re-export commonly used types from contracts
 // Note: @kya-os/contracts exports are at the root level
@@ -263,6 +296,8 @@ export { UserDidManager } from "./identity/user-did-manager";
 export type {
   UserDidStorage,
   UserDidManagerConfig,
+  UserKeyPair,
+  OAuthIdentity,
 } from "./identity/user-did-manager";
 
 // IDP Token Resolver (Phase 1 - MH-7)

package/src/runtime/base.ts

@@ -130,19 +130,16 @@ export class MCPIRuntimeBase {
     return this.cachedIdentity;
   }
 
-  /**
-   * Handle handshake request
-   */
   /**
    * Handle MCP handshake request
    *
+   * Phase 5: Anonymous Sessions Until OAuth
+   * - Sessions start anonymous (no userDid) unless OAuth identity provided
+   * - User DID is resolved via AgentShield after OAuth completes
+   * - Eliminates DID fragmentation (same user = same DID across sessions)
+   *
    * @param request - Handshake request object (may include oauthIdentity for persistent user DID lookup)
    * @returns Handshake response with session ID and agent DID
-   *
-   * @remarks
-   * - Accepts optional oauthIdentity via request.oauthIdentity (backward compatible)
-   * - If OAuth identity provided, uses it to retrieve/create persistent user DID
-   * - Falls back to ephemeral user DID generation if OAuth unavailable
    */
   async handleHandshake(
     request: any & {
@@ -155,26 +152,36 @@ export class MCPIRuntimeBase {
     const timestamp = this.clock.now();
     const sessionId = await this.generateSessionId();
 
-    // Generate user DID if user DID generation is enabled
-    // Use OAuth identity if provided for persistent user DID lookup
+    // Phase 5: Try to resolve user DID from existing OAuth mapping
+    // Sessions start anonymous - no ephemeral generation
     let userDid: string | undefined;
     if (this.userDidManager) {
       try {
         const oauthIdentity = request.oauthIdentity;
-        userDid = await this.userDidManager.getOrCreateUserDid(
+        const resolvedDid = await this.userDidManager.getOrCreateUserDid(
           sessionId,
           oauthIdentity
         );
+        // Convert null to undefined for session storage
+        userDid = resolvedDid ?? undefined;
+
         if (this.config.audit?.enabled) {
-          console.log("[MCP-I] Generated user DID for session:", {
-            userDid: userDid.substring(0, 20) + "...",
-            hasOAuth: !!oauthIdentity,
-            provider: oauthIdentity?.provider,
-          });
+          if (userDid) {
+            console.log("[MCP-I] Resolved existing user DID for session:", {
+              userDid: userDid.substring(0, 20) + "...",
+              hasOAuth: !!oauthIdentity,
+              provider: oauthIdentity?.provider,
+            });
+          } else {
+            console.log("[MCP-I] Session started anonymous (no userDid):", {
+              sessionId: sessionId.substring(0, 8) + "...",
+              hasOAuth: !!oauthIdentity,
+            });
+          }
         }
       } catch (error) {
-        console.warn("[MCP-I] Failed to generate user DID:", error);
-        // Continue without user DID - not critical
+        console.warn("[MCP-I] Failed to resolve user DID:", error);
+        // Continue without user DID - session is anonymous
       }
     }
 
@@ -211,11 +218,11 @@ export class MCPIRuntimeBase {
         }
       : undefined;
 
-    // Create session
+    // Create session with Phase 5 identity state
     const session = {
       id: sessionId,
       clientDid: request.clientDid || userDid, // Use provided clientDid or generated userDid
-      userDid: userDid, // Store generated user DID separately
+      userDid: userDid, // Store user DID (may be undefined for anonymous sessions)
       agentDid: request.agentDid, // ✅ FIXED: Only agent DID, no fallback
       serverDid: identity.did, // ✅ NEW: Server's DID (for clarity)
       audience: request.audience,
@@ -223,7 +230,10 @@ export class MCPIRuntimeBase {
       expiresAt: this.clock.calculateExpiry(
         (this.config.session?.ttlMinutes || 30) * 60
       ),
-      clientInfo, // NEW: Store client information
+      clientInfo, // Store client information
+      // Phase 5: Identity state tracking
+      identityState: userDid ? "authenticated" : "anonymous",
+      oauthIdentity: request.oauthIdentity ?? undefined,
     };
 
     this.sessions.set(sessionId, session);
@@ -246,6 +256,59 @@ export class MCPIRuntimeBase {
     };
   }
 
+  /**
+   * Update session identity after OAuth resolution (Phase 5)
+   *
+   * Called after AgentShield identity/resolve returns a persistent user DID.
+   * Updates the session to authenticated state with the resolved DID.
+   *
+   * @param sessionId - MCP session ID
+   * @param userDid - Persistent user DID from AgentShield
+   * @param oauthIdentity - OAuth identity information
+   * @throws Error if session not found
+   */
+  async updateSessionIdentity(
+    sessionId: string,
+    userDid: string,
+    oauthIdentity?: { provider: string; subject: string; email?: string }
+  ): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${sessionId}`);
+    }
+
+    // Update session with resolved identity
+    session.userDid = userDid;
+    session.identityState = "authenticated";
+    if (oauthIdentity) {
+      session.oauthIdentity = oauthIdentity;
+    }
+
+    // Update the sessions map
+    this.sessions.set(sessionId, session);
+
+    // Also update UserDidManager cache if available
+    if (this.userDidManager) {
+      await this.userDidManager.setUserDidForSession(sessionId, userDid, oauthIdentity);
+    }
+
+    if (this.config.audit?.enabled) {
+      console.log("[MCP-I] Session identity updated (Phase 5):", {
+        sessionId: sessionId.substring(0, 8) + "...",
+        userDid: userDid.substring(0, 20) + "...",
+        provider: oauthIdentity?.provider,
+        identityState: "authenticated",
+      });
+    }
+  }
+
+  /**
+   * Get session by ID
+   */
+  getSession(sessionId: string): any | undefined {
+    return this.sessions.get(sessionId);
+  }
+
   /**
    * Process tool call with automatic proof generation
    * Returns clean result only - proof is stored for out-of-band retrieval