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

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

package/src/services/session-registration.service.ts

@@ -109,55 +109,9 @@ export class SessionRegistrationService {
         sessionId,
         agentDid: request.agent_did,
         clientName: request.client_info.name,
-        clientVersion: request.client_info.version,
-        hasClientIdentity: !!request.client_identity,
         url,
       });
 
-      // ✅ EMPIRICAL PROOF: Prepare request headers
-      // Try Authorization: Bearer first (same as proofs endpoint)
-      // If that fails, AgentShield may need X-AgentShield-Key instead
-      const requestHeaders = {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.config.apiKey}`, // Use same auth as proofs endpoint
-      };
-
-      // ✅ EMPIRICAL PROOF: Log exact request details (sanitized for security)
-      const sanitizedHeaders = {
-        ...requestHeaders,
-        Authorization: `Bearer ${this.config.apiKey.slice(0, 8)}...${this.config.apiKey.slice(-4)}`, // Show first 8 and last 4 chars
-      };
-
-      const sanitizedBody = {
-        session_id: request.session_id,
-        agent_did: request.agent_did,
-        project_id: request.project_id,
-        created_at: request.created_at,
-        client_info: request.client_info,
-        client_identity: request.client_identity,
-        server_did: request.server_did,
-        ttl_minutes: request.ttl_minutes,
-      };
-
-      this.config.logger(
-        "[SessionRegistration] 🔍 EMPIRICAL DEBUG - Request details",
-        {
-          url,
-          method: "POST",
-          headers: sanitizedHeaders,
-          headerKeys: Object.keys(requestHeaders),
-          authHeaderPresent: !!requestHeaders["Authorization"],
-          authHeaderName: "Authorization",
-          authHeaderFormat: requestHeaders["Authorization"]?.startsWith(
-            "Bearer "
-          )
-            ? "Bearer"
-            : "Other",
-          body: sanitizedBody,
-          bodySize: JSON.stringify(request).length,
-        }
-      );
-
       // Make the request with timeout
       const controller = new AbortController();
       const timeoutId = setTimeout(
@@ -168,89 +122,47 @@ export class SessionRegistrationService {
       try {
         const response = await this.config.fetchProvider.fetch(url, {
           method: "POST",
-          headers: requestHeaders,
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.config.apiKey}`,
+          },
           body: JSON.stringify(request),
           signal: controller.signal,
         });
 
         clearTimeout(timeoutId);
 
-        // ✅ EMPIRICAL PROOF: Capture exact response details
-        const responseHeaders: Record<string, string> = {};
-        response.headers.forEach((value, key) => {
-          responseHeaders[key] = value;
-        });
-
-        const responseText = await response
-          .text()
-          .catch(() => "Failed to read response");
-        let responseBody: unknown;
-        try {
-          responseBody = JSON.parse(responseText);
-        } catch {
-          responseBody = responseText;
-        }
-
-        // ✅ EMPIRICAL PROOF: Log exact response details
-        this.config.logger(
-          "[SessionRegistration] 🔍 EMPIRICAL DEBUG - Response details",
-          {
-            status: response.status,
-            statusText: response.statusText,
-            ok: response.ok,
-            headers: responseHeaders,
-            body: responseBody,
-            bodyLength: responseText.length,
-            clientName: request.client_info.name,
-            // ✅ DEBUG: Include request ID from response headers for AgentShield support
-            requestId:
-              responseHeaders["x-request-id"] ||
-              responseHeaders["X-Request-ID"] ||
-              "not-provided",
-            // ✅ DEBUG: Full response text for AgentShield team
-            fullResponseText: responseText,
-          }
-        );
-
         if (!response.ok) {
           // Log error but don't throw - this is fire-and-forget
+          const errorText = await response.text().catch(() => "Unknown error");
           this.config.logger("[SessionRegistration] Registration failed", {
             sessionId,
             status: response.status,
-            error: responseText,
-            // ✅ DEBUG: EMPIRICAL: Include full response details
-            responseHeaders,
-            responseBody,
-            clientName: request.client_info.name,
-            // ✅ DEBUG: Request ID for AgentShield support ticket
-            requestId:
-              responseHeaders["x-request-id"] ||
-              responseHeaders["X-Request-ID"] ||
-              "not-provided",
-            // ✅ DEBUG: Full request body for AgentShield team
-            fullRequestBody: JSON.stringify(request, null, 2),
+            error: errorText,
           });
           return {
             success: false,
             sessionId,
-            error: `HTTP ${response.status}: ${responseText}`,
+            error: `HTTP ${response.status}: ${errorText}`,
           };
         }
 
-        // Parse response (using already-captured responseBody)
-        const responseData = responseBody as
-          | { data?: RegisterSessionResponse }
-          | RegisterSessionResponse;
+        // Parse response
+        const responseData = (await response.json()) as {
+          data?: RegisterSessionResponse;
+        } & RegisterSessionResponse;
         const parseResult = registerSessionResponseSchema.safeParse(
-          (responseData as { data?: RegisterSessionResponse }).data ||
-            responseData
+          responseData.data || responseData
         );
 
         if (!parseResult.success) {
-          this.config.logger("[SessionRegistration] Invalid response format", {
-            sessionId,
-            response: responseData,
-          });
+          this.config.logger(
+            "[SessionRegistration] Invalid response format",
+            {
+              sessionId,
+              response: responseData,
+            }
+          );
           // Still consider it a success if we got a 200 OK
           return { success: true, sessionId };
         }
@@ -258,12 +170,6 @@ export class SessionRegistrationService {
         this.config.logger("[SessionRegistration] Session registered", {
           sessionId,
           registered: parseResult.data.registered,
-          // ✅ DEBUG: Include full response for AgentShield debugging
-          responseData: parseResult.data,
-          requestId:
-            responseHeaders["x-request-id"] ||
-            responseHeaders["X-Request-ID"] ||
-            "not-provided",
         });
 
         return { success: true, sessionId };
@@ -281,7 +187,8 @@ export class SessionRegistrationService {
       }
 
       // Log any other error
-      const errorMsg = error instanceof Error ? error.message : "Unknown error";
+      const errorMsg =
+        error instanceof Error ? error.message : "Unknown error";
       this.config.logger("[SessionRegistration] Unexpected error", {
         sessionId,
         error: errorMsg,
@@ -303,13 +210,10 @@ export class SessionRegistrationService {
     this.registerSession(request).catch((error) => {
       // This should never happen since registerSession catches all errors,
       // but just in case
-      this.config.logger(
-        "[SessionRegistration] Background registration failed",
-        {
-          sessionId: request.session_id,
-          error: error instanceof Error ? error.message : "Unknown error",
-        }
-      );
+      this.config.logger("[SessionRegistration] Background registration failed", {
+        sessionId: request.session_id,
+        error: error instanceof Error ? error.message : "Unknown error",
+      });
     });
   }
 }
@@ -344,3 +248,4 @@ export function createSessionRegistrationService(options: {
     logger: options.logger,
   });
 }
+

package/src/services/tool-context-builder.ts

@@ -4,11 +4,15 @@
  * Builds ToolExecutionContext for tool handlers by resolving IDP tokens
  * based on tool protection configuration and user identity.
  *
+ * Updated for CRED-003: Builds idpHeaders based on tokenUsage metadata
+ * to support credential providers with custom token usage patterns.
+ *
  * @package @kya-os/mcp-i-core
  */
 
 import type { ToolExecutionContext } from "@kya-os/contracts/config";
 import type { IdpTokenResolver } from "../identity/idp-token-resolver.js";
+import type { IdpTokensWithMetadata } from "../identity/idp-token-storage.interface.js";
 import type { ToolProtection } from "../types/tool-protection.js";
 import type { OAuthConfigService } from "./oauth-config.service.js";
 import type { ProviderResolver } from "./provider-resolver.js";
@@ -57,7 +61,7 @@ export class ToolContextBuilder {
    * Build tool execution context
    *
    * @param toolName - Name of the tool being executed
-   * @param userDid - User DID (optional, required for OAuth)
+   * @param userDid - User DID (optional, required for OAuth/credentials)
    * @param sessionId - Session ID (optional)
    * @param delegationToken - Delegation token (optional)
    * @param toolProtection - Tool protection configuration (optional)
@@ -70,7 +74,7 @@ export class ToolContextBuilder {
     delegationToken: string | undefined,
     toolProtection: ToolProtection | null
   ): Promise<ToolExecutionContext | undefined> {
-    // Only build context if tool requires OAuth
+    // Only build context if tool requires OAuth/credentials
     if (!toolProtection?.requiredScopes?.length || !userDid) {
       return undefined;
     }
@@ -90,15 +94,16 @@ export class ToolContextBuilder {
       return undefined;
     }
 
-    // Resolve IDP token
-    const idpToken = await this.config.tokenResolver.resolveTokenFromDid(
+    // CRED-003: Resolve full token data (not just access_token)
+    // This includes tokenUsage, cookieFormat, apiHeaders for credential providers
+    const tokenData = await this.config.tokenResolver.resolveTokenDataFromDid(
       userDid,
       provider,
       toolProtection.requiredScopes
     );
 
-    if (!idpToken) {
-      // Token not available - throw OAuthRequiredError to trigger OAuth flow
+    if (!tokenData) {
+      // Token not available - throw OAuthRequiredError to trigger auth flow
       this.config.logger("[ToolContextBuilder] Token not available, throwing OAuthRequiredError", {
         toolName,
         userDid: userDid.substring(0, 20) + "...",
@@ -107,7 +112,7 @@ export class ToolContextBuilder {
       });
       
       // Throw error with provider and scopes info
-      // OAuth URL will be built by the Cloudflare layer (agent.ts)
+      // Auth URL will be built by the Cloudflare layer (agent.ts)
       throw new OAuthRequiredError({
         toolName,
         requiredScopes: toolProtection.requiredScopes,
@@ -118,9 +123,13 @@ export class ToolContextBuilder {
       });
     }
 
-    // Build context with token
+    // CRED-003: Build headers based on tokenUsage
+    const idpHeaders = this.buildAuthHeaders(tokenData);
+
+    // Build context with token and headers
     const context: ToolExecutionContext = {
-      idpToken,
+      idpToken: tokenData.access_token,
+      idpHeaders,
       provider,
       scopes: toolProtection.requiredScopes,
       userDid,
@@ -132,12 +141,68 @@ export class ToolContextBuilder {
       toolName,
       userDid: userDid.substring(0, 20) + "...",
       provider,
-      hasToken: !!idpToken,
+      hasToken: !!tokenData.access_token,
+      tokenUsage: tokenData.tokenUsage,
+      headerKeys: Object.keys(idpHeaders),
     });
 
     return context;
   }
 
+  /**
+   * Build authentication headers based on token usage metadata (CRED-003)
+   *
+   * Supports three modes:
+   * - "cookie": Cookie header (with optional cookieFormat template)
+   * - "bearer": Authorization: Bearer xxx
+   * - "header": Custom header name
+   *
+   * Also includes any apiHeaders from provider config.
+   *
+   * @param tokenData - Token data with usage metadata
+   * @returns Headers object for API calls
+   */
+  private buildAuthHeaders(tokenData: IdpTokensWithMetadata): Record<string, string> {
+    const authHeaders: Record<string, string> = {};
+
+    const tokenUsage = tokenData.tokenUsage || "bearer"; // Default to bearer for OAuth
+    const token = tokenData.access_token;
+
+    switch (tokenUsage) {
+      case "cookie":
+        // Use cookieFormat if specified, otherwise send raw token
+        if (tokenData.cookieFormat) {
+          authHeaders["Cookie"] = tokenData.cookieFormat.replace(
+            /\{\{token\}\}/g,
+            token
+          );
+        } else {
+          authHeaders["Cookie"] = token;
+        }
+        break;
+
+      case "bearer":
+        authHeaders["Authorization"] = `Bearer ${token}`;
+        break;
+
+      case "header":
+        const headerName = tokenData.tokenHeader || "X-Session-Token";
+        authHeaders[headerName] = token;
+        break;
+
+      default:
+        // Unknown usage - default to bearer
+        authHeaders["Authorization"] = `Bearer ${token}`;
+    }
+
+    // Add any additional API headers from provider config
+    if (tokenData.apiHeaders) {
+      Object.assign(authHeaders, tokenData.apiHeaders);
+    }
+
+    return authHeaders;
+  }
+
   /**
    * Resolve OAuth provider for a tool
    *