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

package/dist/delegation/utils.js

@@ -7,6 +7,10 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.canonicalizeJSON = canonicalizeJSON;
+exports.createUnsignedVCJWT = createUnsignedVCJWT;
+exports.completeVCJWT = completeVCJWT;
+exports.parseVCJWT = parseVCJWT;
+const base64_1 = require("../utils/base64");
 /**
  * JSON canonicalization (RFC 8785)
  *
@@ -45,4 +49,117 @@ function canonicalizeJSON(obj) {
     }
     throw new Error(`Cannot canonicalize type: ${typeof obj}`);
 }
+/**
+ * Create unsigned JWT parts (header + payload) for a VC
+ *
+ * Prepares the VC for signing by extracting standard claims and
+ * encoding the header and payload as base64url strings.
+ *
+ * @param vc - The Verifiable Credential (without proof)
+ * @param options - Encoding options
+ * @returns Object with encoded parts and signing input
+ */
+function createUnsignedVCJWT(vc, options = {}) {
+    // Create JWT header
+    const header = {
+        alg: 'EdDSA',
+        typ: 'JWT',
+    };
+    if (options.keyId) {
+        header.kid = options.keyId;
+    }
+    // Extract standard claims from VC
+    const issuer = typeof vc.issuer === 'string' ? vc.issuer : vc.issuer?.id;
+    const subject = vc.credentialSubject?.id;
+    // Parse dates to Unix timestamps
+    let exp;
+    let iat;
+    if (vc.expirationDate && typeof vc.expirationDate === 'string') {
+        exp = Math.floor(new Date(vc.expirationDate).getTime() / 1000);
+    }
+    if (vc.issuanceDate && typeof vc.issuanceDate === 'string') {
+        iat = Math.floor(new Date(vc.issuanceDate).getTime() / 1000);
+    }
+    // Remove proof from VC for JWT payload (signature is in JWT itself)
+    const vcWithoutProof = { ...vc };
+    delete vcWithoutProof.proof;
+    // Build JWT payload
+    const payload = {
+        iss: issuer,
+        vc: vcWithoutProof,
+    };
+    if (subject)
+        payload.sub = subject;
+    if (exp)
+        payload.exp = exp;
+    if (iat)
+        payload.iat = iat;
+    if (vc.id && typeof vc.id === 'string')
+        payload.jti = vc.id;
+    // Encode header and payload
+    const encodedHeader = (0, base64_1.base64urlEncodeFromString)(JSON.stringify(header));
+    const encodedPayload = (0, base64_1.base64urlEncodeFromString)(JSON.stringify(payload));
+    const signingInput = `${encodedHeader}.${encodedPayload}`;
+    return {
+        header,
+        payload,
+        encodedHeader,
+        encodedPayload,
+        signingInput,
+    };
+}
+/**
+ * Complete a JWT with a signature
+ *
+ * Takes the signing input and a base64url-encoded signature to create the final JWT.
+ *
+ * @param signingInput - The header.payload string that was signed
+ * @param signature - Base64url-encoded signature
+ * @returns Complete JWT string (header.payload.signature)
+ */
+function completeVCJWT(signingInput, signature) {
+    return `${signingInput}.${signature}`;
+}
+/**
+ * Parse a VC-JWT and extract the VC
+ *
+ * Does NOT verify the signature - use with a verification function.
+ *
+ * @param jwt - The JWT string
+ * @returns Parsed JWT parts
+ */
+function parseVCJWT(jwt) {
+    const parts = jwt.split('.');
+    if (parts.length !== 3) {
+        return null;
+    }
+    try {
+        // Decode header and payload
+        const headerJson = base64urlDecodeToString(parts[0]);
+        const payloadJson = base64urlDecodeToString(parts[1]);
+        const header = JSON.parse(headerJson);
+        const payload = JSON.parse(payloadJson);
+        return {
+            header,
+            payload,
+            signature: parts[2],
+            signingInput: `${parts[0]}.${parts[1]}`,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decode base64url string to string (internal helper)
+ */
+function base64urlDecodeToString(input) {
+    // Add padding if needed
+    const padded = input + '='.repeat((4 - input.length % 4) % 4);
+    const base64 = padded.replace(/-/g, '+').replace(/_/g, '/');
+    if (typeof atob !== 'undefined') {
+        return atob(base64);
+    }
+    return Buffer.from(base64, 'base64').toString('utf-8');
+}
 //# sourceMappingURL=utils.js.map

package/dist/delegation/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/delegation/utils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAaH,4CAuBC;AAlCD;;;;;;;;;;GAUG;AACH,SAAgB,gBAAgB,CAAC,GAAQ;IACvC,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAChC,IAAI,OAAO,GAAG,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;IACpD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC3D,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACxD,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3D,OAAO,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACxC,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;YAC7B,MAAM,KAAK,GAAG,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;YACzC,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,KAAK,CAAC;QAC3C,CAAC,CAAC,CAAC;QACH,OAAO,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACrC,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,6BAA6B,OAAO,GAAG,EAAE,CAAC,CAAC;AAC7D,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/delegation/utils.ts"],"names":[],"mappings":"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"}

package/dist/identity/idp-token-resolver.d.ts

@@ -4,10 +4,13 @@
  * 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 */
     tokenStorage: IIdpTokenStorage;
@@ -49,5 +52,18 @@ export declare class IdpTokenResolver {
      * @returns Access token or null if not found/expired
      */
     resolveTokenFromDid(userDid: string, provider: string, scopes: string[]): Promise<string | 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
+     */
+    resolveTokenDataFromDid(userDid: string, provider: string, scopes: string[]): Promise<IdpTokensWithMetadata | null>;
 }
 //# sourceMappingURL=idp-token-resolver.d.ts.map

package/dist/identity/idp-token-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"idp-token-resolver.d.ts","sourceRoot":"","sources":["../../src/identity/idp-token-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEzE,MAAM,WAAW,sBAAsB;IACrC,mCAAmC;IACnC,YAAY,EAAE,gBAAgB,CAAC;IAE/B,sCAAsC;IACtC,YAAY,EAAE;QACZ,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;KACjF,CAAC;IAEF,+CAA+C;IAC/C,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACpD;AAED;;;;;;;;;GASG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAEZ;gBAEU,MAAM,EAAE,sBAAsB;IAQ1C;;;;;;;;;;;;;;;;OAgBG;IACG,mBAAmB,CACvB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,GACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CA4E1B"}
+{"version":3,"file":"idp-token-resolver.d.ts","sourceRoot":"","sources":["../../src/identity/idp-token-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAEhG,MAAM,WAAW,sBAAsB;IACrC,mCAAmC;IACnC,YAAY,EAAE,gBAAgB,CAAC;IAE/B,sCAAsC;IACtC,YAAY,EAAE;QACZ,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;KACjF,CAAC;IAEF,+CAA+C;IAC/C,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACpD;AAED;;;;;;;;;GASG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAEZ;gBAEU,MAAM,EAAE,sBAAsB;IAQ1C;;;;;;;;;;;;;;;;OAgBG;IACG,mBAAmB,CACvB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,GACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAKzB;;;;;;;;;;;OAWG;IACG,uBAAuB,CAC3B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,GACf,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC;CAsFzC"}

package/dist/identity/idp-token-resolver.js

@@ -5,6 +5,9 @@
  * 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
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -46,6 +49,22 @@ class IdpTokenResolver {
      * @returns Access token or null if not found/expired
      */
     async resolveTokenFromDid(userDid, provider, scopes) {
+        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, provider, scopes) {
         // 1. Look up token from storage
         const storedToken = await this.config.tokenStorage.getToken(userDid, provider, scopes);
         if (!storedToken) {
@@ -66,18 +85,26 @@ class IdpTokenResolver {
                 hasRefreshToken: !!storedToken.refresh_token,
             });
             // 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, storedToken.refresh_token);
                 if (refreshed) {
-                    // 4. Update storage with new tokens
-                    await this.config.tokenStorage.storeToken(userDid, provider, scopes, refreshed);
+                    // 4. Update storage with new tokens, preserving usage metadata
+                    const refreshedWithMetadata = {
+                        ...refreshed,
+                        tokenUsage: storedToken.tokenUsage,
+                        tokenHeader: storedToken.tokenHeader,
+                        cookieFormat: storedToken.cookieFormat,
+                        apiHeaders: storedToken.apiHeaders,
+                    };
+                    await this.config.tokenStorage.storeToken(userDid, provider, scopes, refreshedWithMetadata);
                     this.config.logger("[IdpTokenResolver] Token refreshed successfully", {
                         userDid: userDid.substring(0, 20) + "...",
                         provider,
                         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", {
@@ -95,13 +122,14 @@ class IdpTokenResolver {
                 return null;
             }
         }
-        // 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;
     }
 }
 exports.IdpTokenResolver = IdpTokenResolver;

package/dist/identity/idp-token-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"idp-token-resolver.js","sourceRoot":"","sources":["../../src/identity/idp-token-resolver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"idp-token-resolver.js","sourceRoot":"","sources":["../../src/identity/idp-token-resolver.ts"],"names":[],"mappings":"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"}

package/dist/identity/idp-token-storage.interface.d.ts

@@ -5,9 +5,40 @@
  * 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
  */
@@ -16,25 +47,25 @@ 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): Promise<void>;
+    storeToken(userDid: string, provider: string, scopes: string[], 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>;
+    getToken(userDid: string, provider: string, scopes: string[]): 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(userDid: string, provider: string, scopes: string[]): Promise<void>;

package/dist/identity/idp-token-storage.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"idp-token-storage.interface.d.ts","sourceRoot":"","sources":["../../src/identity/idp-token-storage.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,UAAU,CACR,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,EAChB,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;OAOG;IACH,QAAQ,CACN,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,GACf,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAE7B;;;;;;OAMG;IACH,WAAW,CACT,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,GACf,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB"}
+{"version":3,"file":"idp-token-storage.interface.d.ts","sourceRoot":"","sources":["../../src/identity/idp-token-storage.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAE5C,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,SAAS,EAAE,kBAAkB;CAAG;AAE/E;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,UAAU,CACR,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,EAChB,MAAM,EAAE,SAAS,GAAG,qBAAqB,GACxC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;OAOG;IACH,QAAQ,CACN,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,GACf,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;IAEzC;;;;;;OAMG;IACH,WAAW,CACT,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,GACf,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB"}

package/dist/identity/idp-token-storage.interface.js

@@ -6,6 +6,8 @@
  * 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
  */
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/identity/idp-token-storage.interface.js.map

@@ -1 +1 @@
-{"version":3,"file":"idp-token-storage.interface.js","sourceRoot":"","sources":["../../src/identity/idp-token-storage.interface.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG"}
+{"version":3,"file":"idp-token-storage.interface.js","sourceRoot":"","sources":["../../src/identity/idp-token-storage.interface.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG"}

package/dist/identity/user-did-manager.d.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';
 /**
@@ -29,6 +35,31 @@ 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
  */
@@ -55,6 +86,26 @@ 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>;
 }
 /**
  * User DID Manager configuration
@@ -87,24 +138,47 @@ export interface UserDidManagerConfig {
 export declare class UserDidManager {
     private config;
     private sessionDidCache;
+    private sessionKeyPairCache;
     constructor(config: UserDidManagerConfig);
     /**
-     * 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
+     */
+    getKeyPairForSession(sessionId: string, oauthIdentity?: OAuthIdentity | null): Promise<UserKeyPair | 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)
      */
-    getOrCreateUserDid(sessionId: string, oauthIdentity?: OAuthIdentity | null): Promise<string>;
+    getOrCreateUserDid(sessionId: string, oauthIdentity?: OAuthIdentity | null): Promise<string | 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
+     */
+    setUserDidForSession(sessionId: string, userDid: string, oauthIdentity?: OAuthIdentity | null): Promise<void>;
     /**
      * Generate a new ephemeral user DID
      *
@@ -112,6 +186,15 @@ export declare class UserDidManager {
      * did:web can be used if configured, but requires additional setup.
      */
     private generateUserDid;
+    /**
+     * 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 generateUserDidWithKeyPair;
     /**
      * Generate did:key from Ed25519 public key bytes
      * Following spec: https://w3c-ccg.github.io/did-method-key/

package/dist/identity/user-did-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user-did-manager.d.ts","sourceRoot":"","sources":["../../src/identity/user-did-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE/C;;OAEG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjE;;OAEG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;;OAGG;IACH,UAAU,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEvE;;;OAGG;IACH,UAAU,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1F;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IAEzB;;OAEG;IACH,MAAM,EAAE,cAAc,CAAC;IAEvB;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,eAAe,CAA6B;gBAExC,MAAM,EAAE,oBAAoB;IAIxC;;;;;;;;;;;;;;;OAeG;IACG,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IA2GlG;;;;;OAKG;YACW,eAAe;IAkB7B;;;;;OAKG;IACH,OAAO,CAAC,2BAA2B;IAiBnC;;;OAGG;IACH,OAAO,CAAC,YAAY;IAwBpB;;OAEG;IACH,OAAO,CAAC,aAAa;IAerB;;OAEG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAkB3D;;OAEG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAapD;;OAEG;IACH,UAAU,IAAI,IAAI;CAGnB"}
+{"version":3,"file":"user-did-manager.d.ts","sourceRoot":"","sources":["../../src/identity/user-did-manager.ts"],"names":[],"mappings":"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"}