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

package/src/identity/idp-token-resolver.ts

@@ -4,11 +4,14 @@
  * Resolves User DID to IDP access token (MH-7 requirement).
  * Handles token lookup, expiration checking, and automatic refresh.
  *
+ * Updated for CRED-003: Returns full token data including usage metadata
+ * to support credential providers with custom token usage patterns.
+ *
  * @package @kya-os/mcp-i-core
  */
 
 import type { IdpTokens } from "@kya-os/contracts/config";
-import type { IIdpTokenStorage } from "./idp-token-storage.interface.js";
+import type { IIdpTokenStorage, IdpTokensWithMetadata } from "./idp-token-storage.interface.js";
 
 export interface IdpTokenResolverConfig {
   /** Token storage implementation */
@@ -68,6 +71,27 @@ export class IdpTokenResolver {
     provider: string,
     scopes: string[]
   ): Promise<string | null> {
+    const tokenData = await this.resolveTokenDataFromDid(userDid, provider, scopes);
+    return tokenData?.access_token ?? null;
+  }
+
+  /**
+   * Resolve User DID to full IDP token data (CRED-003)
+   *
+   * Returns the full token data including usage metadata for credential providers.
+   * This allows ToolContextBuilder to construct appropriate headers based on
+   * tokenUsage (cookie/bearer/header) and cookieFormat.
+   *
+   * @param userDid - User DID to resolve
+   * @param provider - OAuth provider name or credential provider
+   * @param scopes - Required scopes for token
+   * @returns Full token data with metadata or null if not found/expired
+   */
+  async resolveTokenDataFromDid(
+    userDid: string,
+    provider: string,
+    scopes: string[]
+  ): Promise<IdpTokensWithMetadata | null> {
     // 1. Look up token from storage
     const storedToken = await this.config.tokenStorage.getToken(
       userDid,
@@ -95,6 +119,7 @@ export class IdpTokenResolver {
       });
 
       // 3. Refresh if refresh_token available
+      // Note: Credential tokens don't support refresh - they require re-authentication
       if (storedToken.refresh_token) {
         const refreshed = await this.config.oauthService.refreshToken(
           provider,
@@ -102,12 +127,20 @@ export class IdpTokenResolver {
         );
 
         if (refreshed) {
-          // 4. Update storage with new tokens
+          // 4. Update storage with new tokens, preserving usage metadata
+          const refreshedWithMetadata: IdpTokensWithMetadata = {
+            ...refreshed,
+            tokenUsage: storedToken.tokenUsage,
+            tokenHeader: storedToken.tokenHeader,
+            cookieFormat: storedToken.cookieFormat,
+            apiHeaders: storedToken.apiHeaders,
+          };
+
           await this.config.tokenStorage.storeToken(
             userDid,
             provider,
             scopes,
-            refreshed
+            refreshedWithMetadata
           );
 
           this.config.logger("[IdpTokenResolver] Token refreshed successfully", {
@@ -116,8 +149,8 @@ export class IdpTokenResolver {
             expiresAt: new Date(refreshed.expires_at).toISOString(),
           });
 
-          // 5. Return new access_token
-          return refreshed.access_token;
+          // 5. Return new token data
+          return refreshedWithMetadata;
         } else {
           this.config.logger("[IdpTokenResolver] Token refresh failed", {
             userDid: userDid.substring(0, 20) + "...",
@@ -134,14 +167,15 @@ export class IdpTokenResolver {
       }
     }
 
-    // 4. Return valid access_token
+    // 4. Return valid token data
     this.config.logger("[IdpTokenResolver] Token resolved successfully", {
       userDid: userDid.substring(0, 20) + "...",
       provider,
       expiresAt: new Date(storedToken.expires_at).toISOString(),
+      tokenUsage: storedToken.tokenUsage,
     });
 
-    return storedToken.access_token;
+    return storedToken;
   }
 }
 

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

@@ -5,11 +5,46 @@
  * Platform-specific implementations (Cloudflare KV, Node.js database, etc.)
  * implement this interface.
  *
+ * Supports both OAuth tokens and credential-based session tokens (CRED-003).
+ *
  * @package @kya-os/mcp-i-core
  */
 
 import type { IdpTokens } from "@kya-os/contracts/config";
 
+/**
+ * Token usage metadata for credential providers (CRED-003)
+ *
+ * Specifies how the token should be used in subsequent API calls.
+ */
+export interface TokenUsageMetadata {
+  /**
+   * How to use the token in requests
+   * - "cookie": Send as Cookie header
+   * - "bearer": Send as Authorization: Bearer xxx
+   * - "header": Send as custom header (specify tokenHeader)
+   */
+  tokenUsage?: "cookie" | "bearer" | "header";
+
+  /** Custom header name when tokenUsage is "header" */
+  tokenHeader?: string;
+
+  /**
+   * Cookie format template when tokenUsage is "cookie"
+   * Use {{token}} placeholder for the token value
+   * @example "CIX={{token}}; customerCookie={{token}}"
+   */
+  cookieFormat?: string;
+
+  /** Additional headers to include in API calls */
+  apiHeaders?: Record<string, string>;
+}
+
+/**
+ * Extended IdpTokens with usage metadata (CRED-003)
+ */
+export interface IdpTokensWithMetadata extends IdpTokens, TokenUsageMetadata {}
+
 /**
  * Interface for IDP token storage
  */
@@ -18,36 +53,36 @@ export interface IIdpTokenStorage {
    * Store IDP tokens
    *
    * @param userDid - User DID to associate tokens with
-   * @param provider - OAuth provider name
+   * @param provider - OAuth provider name or credential provider
    * @param scopes - Scopes granted for these tokens
-   * @param tokens - IDP tokens to store
+   * @param tokens - IDP tokens to store (may include usage metadata for credentials)
    */
   storeToken(
     userDid: string,
     provider: string,
     scopes: string[],
-    tokens: IdpTokens
+    tokens: IdpTokens | IdpTokensWithMetadata
   ): Promise<void>;
 
   /**
    * Retrieve IDP tokens
    *
    * @param userDid - User DID to retrieve tokens for
-   * @param provider - OAuth provider name
+   * @param provider - OAuth provider name or credential provider
    * @param scopes - Scopes to retrieve tokens for
-   * @returns IDP tokens or null if not found
+   * @returns IDP tokens with optional usage metadata or null if not found
    */
   getToken(
     userDid: string,
     provider: string,
     scopes: string[]
-  ): Promise<IdpTokens | null>;
+  ): Promise<IdpTokensWithMetadata | null>;
 
   /**
    * Delete IDP tokens
    *
    * @param userDid - User DID
-   * @param provider - OAuth provider name
+   * @param provider - OAuth provider name or credential provider
    * @param scopes - Scopes
    */
   deleteToken(

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,9 +296,15 @@ 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)
+// IDP Token Resolver (Phase 1 - MH-7, updated for CRED-003)
 export { IdpTokenResolver } from "./identity/idp-token-resolver";
 export type { IdpTokenResolverConfig } from "./identity/idp-token-resolver";
-export type { IIdpTokenStorage } from "./identity/idp-token-storage.interface";
+export type {
+  IIdpTokenStorage,
+  TokenUsageMetadata,
+  IdpTokensWithMetadata,
+} from "./identity/idp-token-storage.interface";