@kya-os/mcp-i-core 1.8.0 → 1.8.2

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

@@ -1,136 +0,0 @@
-"use strict";
-/**
- * IDP Token Resolver
- *
- * 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 });
-exports.IdpTokenResolver = void 0;
-/**
- * Service for resolving User DID to IDP access token
- *
- * MH-7 Requirement: resolveTokenFromDid(userDid: string): Promise<string>
- *
- * This service implements the core MH-7 functionality:
- * - Resolves User DID to IDP access token
- * - Handles token expiration and automatic refresh
- * - Supports multiple IDP providers
- */
-class IdpTokenResolver {
-    config;
-    constructor(config) {
-        this.config = {
-            tokenStorage: config.tokenStorage,
-            oauthService: config.oauthService,
-            logger: config.logger || (() => { }),
-        };
-    }
-    /**
-     * Resolve User DID to IDP access token
-     *
-     * MH-7 Requirement: resolveTokenFromDid(userDid: string): Promise<string>
-     *
-     * Flow:
-     * 1. Look up token from storage
-     * 2. Check expiration
-     * 3. Auto-refresh if expired and refresh_token available
-     * 4. Update storage after refresh
-     * 5. Return access_token or null
-     *
-     * @param userDid - User DID to resolve
-     * @param provider - OAuth provider name (e.g., "github", "google")
-     * @param scopes - Required scopes for token
-     * @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) {
-            this.config.logger("[IdpTokenResolver] Token not found", {
-                userDid: userDid.substring(0, 20) + "...",
-                provider,
-                scopes,
-            });
-            return null;
-        }
-        // 2. Check expiration
-        const now = Date.now();
-        if (storedToken.expires_at < now) {
-            this.config.logger("[IdpTokenResolver] Token expired, attempting refresh", {
-                userDid: userDid.substring(0, 20) + "...",
-                provider,
-                expiresAt: new Date(storedToken.expires_at).toISOString(),
-                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, 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 token data
-                    return refreshedWithMetadata;
-                }
-                else {
-                    this.config.logger("[IdpTokenResolver] Token refresh failed", {
-                        userDid: userDid.substring(0, 20) + "...",
-                        provider,
-                    });
-                    return null;
-                }
-            }
-            else {
-                this.config.logger("[IdpTokenResolver] Token expired and no refresh token", {
-                    userDid: userDid.substring(0, 20) + "...",
-                    provider,
-                });
-                return null;
-            }
-        }
-        // 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;
-    }
-}
-exports.IdpTokenResolver = IdpTokenResolver;
-//# sourceMappingURL=idp-token-resolver.js.map

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

@@ -1,80 +0,0 @@
-/**
- * IDP Token Storage Interface
- *
- * Platform-agnostic interface for storing and retrieving IDP tokens.
- * 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>;
-    /**
-     * User ID extracted from credential provider response
-     *
-     * For credential providers, this is the userId extracted via responseFields.userId.
-     * This is passed to tool handlers via ToolExecutionContext.userId.
-     */
-    userId?: string;
-}
-/**
- * Extended IdpTokens with usage metadata (CRED-003)
- */
-export interface IdpTokensWithMetadata extends IdpTokens, TokenUsageMetadata {
-}
-/**
- * Interface for IDP token storage
- */
-export interface IIdpTokenStorage {
-    /**
-     * Store IDP tokens
-     *
-     * @param userDid - User DID to associate tokens with
-     * @param provider - OAuth provider name or credential provider
-     * @param scopes - Scopes granted for these tokens
-     * @param tokens - IDP tokens to store (may include usage metadata for credentials)
-     */
-    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 or credential provider
-     * @param scopes - Scopes to retrieve tokens for
-     * @returns IDP tokens with optional usage metadata or null if not found
-     */
-    getToken(userDid: string, provider: string, scopes: string[]): Promise<IdpTokensWithMetadata | null>;
-    /**
-     * Delete IDP tokens
-     *
-     * @param userDid - User DID
-     * @param provider - OAuth provider name or credential provider
-     * @param scopes - Scopes
-     */
-    deleteToken(userDid: string, provider: string, scopes: string[]): Promise<void>;
-}
-//# sourceMappingURL=idp-token-storage.interface.d.ts.map

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

@@ -1,14 +0,0 @@
-"use strict";
-/**
- * IDP Token Storage Interface
- *
- * Platform-agnostic interface for storing and retrieving IDP tokens.
- * 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 });
-//# sourceMappingURL=idp-token-storage.interface.js.map

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

@@ -1,228 +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 declare class UserDidManager {
-    private config;
-    private sessionDidCache;
-    private sessionKeyPairCache;
-    constructor(config: UserDidManagerConfig);
-    /**
-     * 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.
-     * 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)
-     */
-    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
-     *
-     * Uses did:key format by default for simplicity.
-     * 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/
-     *
-     * Format: did:key:z<multibase-base58btc(<multicodec-ed25519-pub><publicKey>)>
-     */
-    private generateDidKeyFromPublicKey;
-    /**
-     * Base58 encode (Bitcoin alphabet)
-     * Simple implementation for did:key generation
-     */
-    private base58Encode;
-    /**
-     * Convert base64 or base64url string to Uint8Array
-     * Handles both standard base64 (+/) and base64url (-_) formats
-     */
-    private base64ToBytes;
-    /**
-     * Get user DID for a session without creating one
-     */
-    getUserDid(sessionId: string): Promise<string | null>;
-    /**
-     * Clear user DID for a session
-     */
-    clearUserDid(sessionId: string): Promise<void>;
-    /**
-     * Clear all cached user DIDs (useful for testing)
-     */
-    clearCache(): void;
-}
-//# sourceMappingURL=user-did-manager.d.ts.map