@kya-os/mcp-i-core 1.7.0 → 1.8.1

package/dist/identity/user-did-manager.js

@@ -1,356 +0,0 @@
-"use strict";
-/**
- * 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)
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.UserDidManager = void 0;
-const did_helpers_1 = require("../utils/did-helpers");
-/**
- * User DID Manager
- *
- * Generates and manages user DIDs for MCP-I sessions.
- * Supports both ephemeral (did:key) and persistent (did:web) formats.
- */
-class UserDidManager {
-    config;
-    sessionDidCache = new Map();
-    sessionKeyPairCache = new Map();
-    constructor(config) {
-        this.config = config;
-    }
-    /**
-     * 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, oauthIdentity) {
-        // 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.
-     * 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)
-     */
-    async getOrCreateUserDid(sessionId, oauthIdentity) {
-        // Check cache first
-        if (this.sessionDidCache.has(sessionId)) {
-            return this.sessionDidCache.get(sessionId);
-        }
-        // PRIORITY 1: If OAuth identity provided, check for persistent user DID mapping
-        if (oauthIdentity &&
-            oauthIdentity.provider &&
-            oauthIdentity.subject &&
-            this.config.storage?.getByOAuth) {
-            try {
-                const persistentUserDid = await this.config.storage.getByOAuth(oauthIdentity.provider, oauthIdentity.subject);
-                if (persistentUserDid) {
-                    console.error("[UserDidManager] Found persistent user DID from OAuth mapping:", {
-                        provider: oauthIdentity.provider,
-                        userDid: persistentUserDid.substring(0, 20) + "...",
-                    });
-                    // Cache it for this session
-                    this.sessionDidCache.set(sessionId, persistentUserDid);
-                    // Also store in session storage for faster future lookups
-                    if (this.config.storage) {
-                        try {
-                            await this.config.storage.set(sessionId, persistentUserDid, 1800); // 30 minutes TTL
-                        }
-                        catch (error) {
-                            // Log but continue - DID is cached and will be returned
-                            console.warn("[UserDidManager] Failed to cache persistent DID in session storage:", error);
-                        }
-                    }
-                    return persistentUserDid;
-                }
-            }
-            catch (error) {
-                // Log but continue - will check session storage or generate new DID
-                console.warn("[UserDidManager] OAuth lookup failed, falling back to session storage:", error);
-            }
-        }
-        // PRIORITY 2: Check session storage if available
-        if (this.config.storage) {
-            try {
-                const storedDid = await this.config.storage.get(sessionId);
-                if (storedDid) {
-                    this.sessionDidCache.set(sessionId, storedDid);
-                    // If OAuth identity provided but no persistent mapping found, create one now
-                    if (oauthIdentity &&
-                        oauthIdentity.provider &&
-                        oauthIdentity.subject &&
-                        this.config.storage.setByOAuth) {
-                        try {
-                            await this.config.storage.setByOAuth(oauthIdentity.provider, oauthIdentity.subject, storedDid, 90 * 24 * 60 * 60 // 90 days TTL for persistent mapping
-                            );
-                            console.error("[UserDidManager] Created persistent OAuth mapping for existing user DID:", {
-                                provider: oauthIdentity.provider,
-                                userDid: storedDid.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 storedDid;
-                }
-            }
-            catch (error) {
-                // Log but continue - session will be anonymous
-                console.warn("[UserDidManager] Storage.get failed:", error);
-            }
-        }
-        // PHASE 5: No ephemeral DID generation - session stays anonymous
-        // User DID will be resolved via AgentShield after OAuth completes
-        return 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
-     */
-    async setUserDidForSession(sessionId, userDid, oauthIdentity) {
-        // Cache in memory
-        this.sessionDidCache.set(sessionId, userDid);
-        // Store in session storage if available
-        if (this.config.storage) {
-            try {
-                await this.config.storage.set(sessionId, userDid, 1800); // 30 minutes TTL
-            }
-            catch (error) {
-                console.warn("[UserDidManager] Failed to store user DID in session storage:", error);
-            }
-        }
-        // Create OAuth mapping if provided
-        if (oauthIdentity?.provider &&
-            oauthIdentity?.subject &&
-            this.config.storage?.setByOAuth) {
-            try {
-                await this.config.storage.setByOAuth(oauthIdentity.provider, oauthIdentity.subject, userDid, 90 * 24 * 60 * 60 // 90 days TTL for persistent mapping
-                );
-                console.error("[UserDidManager] Created OAuth → DID mapping:", {
-                    provider: oauthIdentity.provider,
-                    userDid: userDid.substring(0, 20) + "...",
-                });
-            }
-            catch (error) {
-                console.warn("[UserDidManager] Failed to create OAuth mapping:", error);
-            }
-        }
-    }
-    /**
-     * 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.
-     */
-    async generateUserDid() {
-        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
-     */
-    async generateUserDidWithKeyPair() {
-        if (this.config.useDidWeb && this.config.didWebBaseUrl) {
-            // did:web generation requires a web server to host the DID document.
-            // Currently falls back to did:key which is self-resolving.
-            // TODO(feature): Implement did:web generation when required for production use cases.
-            // This would involve generating the DID document and coordinating with
-            // the hosting infrastructure to serve it at the well-known URL.
-            console.warn("[UserDidManager] did:web not yet implemented, using did:key");
-        }
-        // 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
-        const did = this.generateDidKeyFromPublicKey(publicKeyBytes);
-        // Key ID uses spec-compliant fragment (multibase value for did:key)
-        const keyId = `${did}#${(0, did_helpers_1.didKeyFragment)(did)}`;
-        return {
-            did,
-            publicKey: keyPair.publicKey,
-            privateKey: keyPair.privateKey,
-            keyId,
-        };
-    }
-    /**
-     * 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>)>
-     */
-    generateDidKeyFromPublicKey(publicKeyBytes) {
-        // Ed25519 multicodec prefix (0xed 0x01)
-        const multicodecPrefix = new Uint8Array([0xed, 0x01]);
-        // Combine prefix + public key
-        const multicodecKey = new Uint8Array(multicodecPrefix.length + publicKeyBytes.length);
-        multicodecKey.set(multicodecPrefix);
-        multicodecKey.set(publicKeyBytes, multicodecPrefix.length);
-        // Base58 encode (using a simple implementation)
-        // Note: For production, consider using base-x library
-        const base58Encoded = this.base58Encode(multicodecKey);
-        // Add multibase prefix 'z' for base58-btc
-        return `did:key:z${base58Encoded}`;
-    }
-    /**
-     * Base58 encode (Bitcoin alphabet)
-     * Simple implementation for did:key generation
-     */
-    base58Encode(bytes) {
-        const alphabet = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
-        let num = BigInt(0);
-        // Convert bytes to big integer
-        for (let i = 0; i < bytes.length; i++) {
-            num = num * BigInt(256) + BigInt(bytes[i]);
-        }
-        // Convert to base58
-        let result = "";
-        while (num > 0) {
-            result = alphabet[Number(num % BigInt(58))] + result;
-            num = num / BigInt(58);
-        }
-        // Add leading zeros
-        for (let i = 0; i < bytes.length && bytes[i] === 0; i++) {
-            result = "1" + result;
-        }
-        return result;
-    }
-    /**
-     * Convert base64 or base64url string to Uint8Array
-     * Handles both standard base64 (+/) and base64url (-_) formats
-     */
-    base64ToBytes(base64) {
-        // Convert base64url to standard base64 if needed
-        // Base64url uses - instead of + and _ instead of /
-        let standardBase64 = base64.replace(/-/g, "+").replace(/_/g, "/");
-        // Add padding if needed (base64url often omits padding)
-        const paddingNeeded = (4 - (standardBase64.length % 4)) % 4;
-        standardBase64 += "=".repeat(paddingNeeded);
-        if (typeof Buffer !== "undefined") {
-            // Node.js environment
-            return new Uint8Array(Buffer.from(standardBase64, "base64"));
-        }
-        else {
-            // Browser/Workers environment
-            const binaryString = atob(standardBase64);
-            const bytes = new Uint8Array(binaryString.length);
-            for (let i = 0; i < binaryString.length; i++) {
-                bytes[i] = binaryString.charCodeAt(i);
-            }
-            return bytes;
-        }
-    }
-    /**
-     * Get user DID for a session without creating one
-     */
-    async getUserDid(sessionId) {
-        // Check cache
-        if (this.sessionDidCache.has(sessionId)) {
-            return this.sessionDidCache.get(sessionId);
-        }
-        // Check storage
-        if (this.config.storage) {
-            const storedDid = await this.config.storage.get(sessionId);
-            if (storedDid) {
-                this.sessionDidCache.set(sessionId, storedDid);
-                return storedDid;
-            }
-        }
-        return null;
-    }
-    /**
-     * Clear user DID for a session
-     */
-    async clearUserDid(sessionId) {
-        this.sessionDidCache.delete(sessionId);
-        if (this.config.storage) {
-            try {
-                await this.config.storage.delete(sessionId);
-            }
-            catch (error) {
-                // Log but continue - cache is already cleared
-                console.warn("[UserDidManager] Storage.delete failed, continuing:", error);
-            }
-        }
-    }
-    /**
-     * Clear all cached user DIDs (useful for testing)
-     */
-    clearCache() {
-        this.sessionDidCache.clear();
-    }
-}
-exports.UserDidManager = UserDidManager;
-//# sourceMappingURL=user-did-manager.js.map

package/dist/logging/index.d.ts

@@ -1,5 +0,0 @@
-/**
- * Logging module exports
- */
-export { logger, createDefaultConsoleLogger, type Logger, type Level, } from "./logger";
-//# sourceMappingURL=index.d.ts.map

package/dist/logging/index.js

@@ -1,10 +0,0 @@
-"use strict";
-/**
- * Logging module exports
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createDefaultConsoleLogger = exports.logger = void 0;
-var logger_1 = require("./logger");
-Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return logger_1.logger; } });
-Object.defineProperty(exports, "createDefaultConsoleLogger", { enumerable: true, get: function () { return logger_1.createDefaultConsoleLogger; } });
-//# sourceMappingURL=index.js.map

package/dist/logging/logger.d.ts

@@ -1,33 +0,0 @@
-/**
- * Transport-aware Logger for MCP-I
- *
- * Provides a lightweight, dependency-free logging interface that:
- * - Maps log levels correctly for Cloudflare Workers (so wrangler tail shows correct severities)
- * - Routes all logs to stderr for stdio transport (so stdout remains protocol-only)
- * - Supports runtime configuration of log level and transport mode
- */
-export type Level = "debug" | "info" | "warn" | "error";
-export interface Logger {
-    configure: (opts?: {
-        level?: Level;
-        transport?: string;
-        forceStderr?: boolean;
-    }) => void;
-    debug: (...args: any[]) => void;
-    info: (...args: any[]) => void;
-    warn: (...args: any[]) => void;
-    error: (...args: any[]) => void;
-}
-/**
- * Create a default console logger with transport-aware behavior
- *
- * - Cloudflare Workers: Maps levels to console.debug/info/warn/error
- * - stdio transport: Routes all levels to console.error (stderr) to keep stdout protocol-only
- */
-export declare function createDefaultConsoleLogger(): Logger;
-/**
- * Default singleton logger instance
- * Configure via logger.configure() before use
- */
-export declare const logger: Logger;
-//# sourceMappingURL=logger.d.ts.map

package/dist/logging/logger.js

@@ -1,104 +0,0 @@
-"use strict";
-/**
- * Transport-aware Logger for MCP-I
- *
- * Provides a lightweight, dependency-free logging interface that:
- * - Maps log levels correctly for Cloudflare Workers (so wrangler tail shows correct severities)
- * - Routes all logs to stderr for stdio transport (so stdout remains protocol-only)
- * - Supports runtime configuration of log level and transport mode
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.logger = void 0;
-exports.createDefaultConsoleLogger = createDefaultConsoleLogger;
-const SEVERITY = {
-    debug: 10,
-    info: 20,
-    warn: 30,
-    error: 40,
-};
-/**
- * Create a default console logger with transport-aware behavior
- *
- * - Cloudflare Workers: Maps levels to console.debug/info/warn/error
- * - stdio transport: Routes all levels to console.error (stderr) to keep stdout protocol-only
- */
-function createDefaultConsoleLogger() {
-    let level = "info";
-    let forceStderr = false;
-    function shouldLog(l) {
-        return SEVERITY[l] >= SEVERITY[level];
-    }
-    function write(l, ...args) {
-        if (!shouldLog(l))
-            return;
-        if (forceStderr) {
-            // stdio transport: all logs go to stderr (console.error)
-            // This ensures stdout remains protocol-only
-            console.error(...args);
-            return;
-        }
-        // Cloudflare Workers: map to appropriate console method
-        switch (l) {
-            case "debug":
-                if (typeof console.debug === "function") {
-                    console.debug(...args);
-                }
-                else {
-                    console.log(...args);
-                }
-                break;
-            case "info":
-                if (typeof console.info === "function") {
-                    console.info(...args);
-                }
-                else {
-                    console.log(...args);
-                }
-                break;
-            case "warn":
-                if (typeof console.warn === "function") {
-                    console.warn(...args);
-                }
-                else {
-                    console.error(...args);
-                }
-                break;
-            case "error":
-                console.error(...args);
-                break;
-        }
-    }
-    return {
-        configure(opts = {}) {
-            if (opts.level)
-                level = opts.level;
-            // Handle transport-based stderr routing
-            // - stdio transport: force all logs to stderr (stdout is protocol-only)
-            // - sse/http transports: use normal console routing
-            // - explicit forceStderr overrides transport-based behavior
-            if (opts.forceStderr === true) {
-                forceStderr = true;
-            }
-            else if (opts.forceStderr === false) {
-                forceStderr = false;
-            }
-            else if (opts.transport === "stdio") {
-                forceStderr = true;
-            }
-            else if (opts.transport === "sse" || opts.transport === "http") {
-                // Reset to normal console routing for non-stdio transports
-                forceStderr = false;
-            }
-        },
-        debug: (...a) => write("debug", ...a),
-        info: (...a) => write("info", ...a),
-        warn: (...a) => write("warn", ...a),
-        error: (...a) => write("error", ...a),
-    };
-}
-/**
- * Default singleton logger instance
- * Configure via logger.configure() before use
- */
-exports.logger = createDefaultConsoleLogger();
-//# sourceMappingURL=logger.js.map

package/dist/proof/generator.d.ts

@@ -1,109 +0,0 @@
-/**
- * Proof Generation — Platform-agnostic Protocol Reference
- *
- * Handles JCS canonicalization, SHA-256 digest generation, and Ed25519 JWS
- * signing (compact format) according to MCP-I requirements 5.1, 5.2, 5.3, 5.6.
- *
- * This module is the authoritative proof implementation. All platform adapters
- * (Node.js, Cloudflare Workers) inject a CryptoProvider and delegate here.
- */
-import { DetachedProof } from "@kya-os/contracts/proof";
-import { SessionContext } from "@kya-os/contracts/handshake";
-import { CryptoProvider } from "../providers/base";
-/**
- * Minimal agent identity required by ProofGenerator.
- * Structurally compatible with both AgentIdentity definitions
- * in mcp-i-core (providers/base) and packages/mcp-i (runtime/identity).
- */
-export interface ProofAgentIdentity {
-    did: string;
-    kid: string;
-    privateKey: string;
-    publicKey: string;
-}
-/**
- * Tool request structure for proof generation
- */
-export interface ToolRequest {
-    method: string;
-    params?: unknown;
-}
-/**
- * Tool response structure for proof generation
- */
-export interface ToolResponse {
-    data: unknown;
-    meta?: {
-        proof?: DetachedProof;
-        [key: string]: unknown;
-    };
-}
-/**
- * Proof generation options
- */
-export interface ProofOptions {
-    scopeId?: string;
-    delegationRef?: string;
-    clientDid?: string;
-}
-/**
- * Platform-agnostic proof generator.
- * Requires a CryptoProvider for all cryptographic operations.
- */
-export declare class ProofGenerator {
-    private identity;
-    private cryptoProvider;
-    constructor(identity: ProofAgentIdentity, cryptoProvider: CryptoProvider);
-    /**
-     * Generate proof for tool request/response.
-     * Requirements: 5.1, 5.2, 5.3, 5.6
-     */
-    generateProof(request: ToolRequest, response: ToolResponse, session: SessionContext, options?: ProofOptions): Promise<DetachedProof>;
-    /**
-     * Generate canonical hashes for request and response.
-     * Requirement: 5.1
-     */
-    private generateCanonicalHashes;
-    /**
-     * Generate SHA-256 hash with JCS canonicalization.
-     * Requirement: 5.2
-     *
-     * Delegates to CryptoProvider.hash() which must return "sha256:<hex>".
-     */
-    private generateSHA256Hash;
-    /**
-     * JCS canonicalization implementation (RFC 8785)
-     */
-    private canonicalizeJSON;
-    /**
-     * Generate Ed25519 JWS in compact format (header.payload.signature).
-     * Requirement: 5.3
-     *
-     * Uses standard JWT claims (aud, sub, iss) in addition to custom claims.
-     */
-    private generateJWS;
-    /**
-     * Format base64 private key as PKCS#8 PEM for JOSE library.
-     */
-    private formatPrivateKeyAsPEM;
-    /**
-     * Verify a proof (for testing/validation).
-     */
-    verifyProof(proof: DetachedProof, request: ToolRequest, response: ToolResponse): Promise<boolean>;
-    /**
-     * Convert base64 public key to Ed25519 JWK format.
-     */
-    private base64PublicKeyToJWK;
-}
-/**
- * Create a tool response with proof.
- */
-export declare function createProofResponse(request: ToolRequest, data: unknown, identity: ProofAgentIdentity, session: SessionContext, cryptoProvider: CryptoProvider, options?: ProofOptions): Promise<ToolResponse>;
-/**
- * Extract canonical data for hashing (utility for testing).
- */
-export declare function extractCanonicalData(request: ToolRequest, response: ToolResponse): {
-    request: unknown;
-    response: unknown;
-};
-//# sourceMappingURL=generator.d.ts.map