@kya-os/mcp-i 0.1.0-alpha.3.9 → 1.2.0

package/dist/runtime/mcpi-runtime.d.ts

@@ -0,0 +1,164 @@
+/**
+ * XMCP-I Runtime - Identity-Aware MCP Runtime
+ *
+ * Composes upstream XMCP core with identity plugin layer
+ * according to runtime support specification and requirements.
+ */
+import { SessionContext, HandshakeRequest } from "@kya-os/contracts/handshake";
+import { ToolRequest, ToolResponse } from "./proof";
+import { WellKnownConfig } from "./well-known";
+import { DemoManager } from "./demo";
+/**
+ * Runtime environment check
+ */
+export interface RuntimeEnvironment {
+    isNode: boolean;
+    isWorker: boolean;
+    isVercelEdge: boolean;
+    isAWSLambda: boolean;
+    nodeVersion?: string;
+    supportsESM: boolean;
+}
+/**
+ * XMCP-I Runtime configuration
+ */
+export interface MCPIRuntimeConfig {
+    identity?: {
+        environment?: "development" | "production";
+        devIdentityPath?: string;
+        privacyMode?: boolean;
+    };
+    session?: {
+        timestampSkewSeconds?: number;
+        sessionTtlMinutes?: number;
+        absoluteSessionLifetime?: number;
+    };
+    audit?: {
+        enabled?: boolean;
+        logFunction?: (record: string) => void;
+        includePayloads?: boolean;
+    };
+    wellKnown?: WellKnownConfig;
+    runtime?: {
+        showVerifyLink?: boolean;
+        identityBadge?: boolean;
+    };
+    demo?: {
+        identityBadge?: boolean;
+    };
+}
+/**
+ * XMCP-I Runtime class
+ */
+export declare class MCPIRuntime {
+    private identityManager;
+    private sessionManager;
+    private auditLogger;
+    private wellKnownManager?;
+    private debugManager?;
+    private demoManager?;
+    private config;
+    private cachedIdentity?;
+    constructor(config?: MCPIRuntimeConfig);
+    /**
+     * Initialize the runtime (async setup)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Validate handshake and create session
+     */
+    validateHandshake(request: HandshakeRequest): Promise<SessionContext | null>;
+    /**
+     * Process tool call with identity-aware proof generation
+     */
+    processToolCall(request: ToolRequest, session: SessionContext, toolHandler: (request: ToolRequest) => Promise<any>, options?: {
+        scopeId?: string;
+        delegationRef?: string;
+    }): Promise<ToolResponse>;
+    /**
+     * Get well-known endpoint handler
+     */
+    getWellKnownHandler(): import("./well-known").WellKnownHandler;
+    /**
+     * Get debug endpoint handler (development only)
+     */
+    getDebugHandler(logRoot?: string): (_request: any) => Promise<Response>;
+    /**
+     * Get demo manager
+     */
+    getDemoManager(): DemoManager | undefined;
+    /**
+     * Get runtime statistics
+     */
+    getStats(): {
+        identity: {
+            did: string | undefined;
+            keyId: string | undefined;
+            environment: "production" | "development";
+        };
+        session: {
+            activeSessions: number;
+            config: {
+                timestampSkewSeconds: number;
+                sessionTtlMinutes: number;
+                absoluteSessionLifetime?: number;
+                cacheType: string;
+            };
+        };
+        audit: {
+            enabled: boolean;
+            sessionsLogged: number;
+            includePayloads: boolean;
+        };
+        runtime: {
+            initialized: boolean;
+            wellKnownEnabled: boolean;
+        };
+    };
+    /**
+     * Cleanup resources
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Check runtime environment compatibility
+     */
+    private checkRuntimeEnvironment;
+    /**
+     * Detect runtime environment
+     */
+    private detectRuntimeEnvironment;
+    /**
+     * Describe runtime environment for logging
+     */
+    private describeEnvironment;
+}
+/**
+ * Create and initialize XMCP-I runtime
+ */
+export declare function createMCPIRuntime(config?: MCPIRuntimeConfig): Promise<MCPIRuntime>;
+/**
+ * Runtime factory for different environments
+ */
+export declare const RuntimeFactory: {
+    /**
+     * Create runtime for development
+     */
+    forDevelopment(overrides?: Partial<MCPIRuntimeConfig>): Promise<MCPIRuntime>;
+    /**
+     * Create runtime for production
+     */
+    forProduction(overrides?: Partial<MCPIRuntimeConfig>): Promise<MCPIRuntime>;
+    /**
+     * Create runtime for testing
+     */
+    forTesting(overrides?: Partial<MCPIRuntimeConfig>): Promise<MCPIRuntime>;
+};
+/**
+ * Error codes
+ */
+export declare const RUNTIME_ERRORS: {
+    readonly ERUNTIME: "XMCP_I_ERUNTIME";
+    readonly ENOIDENTITY: "XMCP_I_ENOIDENTITY";
+    readonly EHANDSHAKE: "XMCP_I_EHANDSHAKE";
+    readonly ESESSION: "XMCP_I_ESESSION";
+};

package/dist/runtime/mcpi-runtime.js

@@ -0,0 +1,352 @@
+"use strict";
+/**
+ * XMCP-I Runtime - Identity-Aware MCP Runtime
+ *
+ * Composes upstream XMCP core with identity plugin layer
+ * according to runtime support specification and requirements.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNTIME_ERRORS = exports.RuntimeFactory = exports.MCPIRuntime = void 0;
+exports.createMCPIRuntime = createMCPIRuntime;
+const identity_1 = require("./identity");
+const session_1 = require("./session");
+const proof_1 = require("./proof");
+const audit_1 = require("./audit");
+const well_known_1 = require("./well-known");
+const debug_1 = require("./debug");
+const demo_1 = require("./demo");
+/**
+ * XMCP-I Runtime class
+ */
+class MCPIRuntime {
+    identityManager;
+    sessionManager;
+    auditLogger;
+    wellKnownManager;
+    debugManager;
+    demoManager;
+    config;
+    cachedIdentity;
+    constructor(config = {}) {
+        this.config = config;
+        // Initialize identity manager
+        this.identityManager = new identity_1.IdentityManager({
+            environment: config.identity?.environment || "development",
+            ...config.identity,
+        });
+        // Initialize session manager
+        this.sessionManager = new session_1.SessionManager(config.session);
+        // Initialize audit logger
+        this.auditLogger = new audit_1.AuditLogger(config.audit);
+    }
+    /**
+     * Initialize the runtime (async setup)
+     */
+    async initialize() {
+        // Perform runtime environment checks
+        this.checkRuntimeEnvironment();
+        // Ensure identity is loaded
+        this.cachedIdentity = await this.identityManager.ensureIdentity();
+        // Initialize well-known manager if configured
+        if (this.config.wellKnown) {
+            this.wellKnownManager = new well_known_1.WellKnownManager(this.cachedIdentity, this.config.wellKnown);
+        }
+        // Initialize debug manager in development
+        if (this.config.identity?.environment === "development") {
+            this.debugManager = (0, debug_1.createDebugEndpoint)(this.cachedIdentity, this.config.identity.environment);
+        }
+        // Initialize demo manager
+        this.demoManager = (0, demo_1.createDemoManager)(this.cachedIdentity, {
+            identityBadge: this.config.demo?.identityBadge || false,
+            environment: this.config.identity?.environment || "development",
+        });
+        console.log(`✅ XMCP-I Runtime initialized`);
+        console.log(`   DID: ${this.cachedIdentity.did}`);
+        console.log(`   Key ID: ${this.cachedIdentity.keyId}`);
+        // Show verify link in development (default true)
+        const showVerifyLink = this.config.runtime?.showVerifyLink !== false;
+        demo_1.DemoConsole.printVerifyLink(showVerifyLink, this.config.identity?.environment || "development");
+        // Show demo warning if any demo features are enabled
+        if (this.demoManager?.isIdentityBadgeEnabled()) {
+            demo_1.DemoConsole.printDemoWarning();
+        }
+    }
+    /**
+     * Validate handshake and create session
+     */
+    async validateHandshake(request) {
+        const result = await this.sessionManager.validateHandshake(request);
+        if (!result.success) {
+            console.error(`Handshake validation failed: ${result.error?.message}`);
+            if (result.error?.remediation) {
+                console.error(`Remediation: ${result.error.remediation}`);
+            }
+            return null;
+        }
+        return result.session;
+    }
+    /**
+     * Process tool call with identity-aware proof generation
+     */
+    async processToolCall(request, session, toolHandler, options = {}) {
+        if (!this.cachedIdentity) {
+            throw new Error("Runtime not initialized - call initialize() first");
+        }
+        try {
+            // Execute the tool
+            let data = await toolHandler(request);
+            // Add identity badge if enabled
+            if (this.demoManager?.isIdentityBadgeEnabled()) {
+                data = this.demoManager.addIdentityBadgeToResponse(data);
+            }
+            // Create response with proof
+            const response = await (0, proof_1.createProofResponse)(request, data, this.cachedIdentity, session, options);
+            // Update debug state with latest proof
+            if (this.debugManager && response.meta?.proof) {
+                this.debugManager.updateDebugState(response.meta.proof, session);
+            }
+            // Log audit record (first call per session)
+            const auditContext = {
+                identity: this.cachedIdentity,
+                session,
+                requestHash: response.meta.proof.meta.requestHash,
+                responseHash: response.meta.proof.meta.responseHash,
+                verified: "yes",
+                scopeId: options.scopeId,
+            };
+            await this.auditLogger.logAuditRecord(auditContext);
+            return response;
+        }
+        catch (error) {
+            // Log failed audit record
+            const auditContext = {
+                identity: this.cachedIdentity,
+                session,
+                requestHash: "sha256:error",
+                responseHash: "sha256:error",
+                verified: "no",
+                scopeId: options.scopeId,
+            };
+            await this.auditLogger.logAuditRecord(auditContext);
+            throw error;
+        }
+    }
+    /**
+     * Get well-known endpoint handler
+     */
+    getWellKnownHandler() {
+        if (!this.cachedIdentity) {
+            throw new Error("Runtime not initialized - call initialize() first");
+        }
+        if (!this.wellKnownManager) {
+            throw new Error("Well-known endpoints not configured");
+        }
+        return (0, well_known_1.createWellKnownHandler)(this.cachedIdentity, this.config.wellKnown);
+    }
+    /**
+     * Get debug endpoint handler (development only)
+     */
+    getDebugHandler(logRoot) {
+        if (!this.cachedIdentity) {
+            throw new Error("Runtime not initialized - call initialize() first");
+        }
+        if (!this.debugManager) {
+            throw new Error("Debug endpoint not available (not in development mode)");
+        }
+        // Update debug manager with log root if provided
+        if (logRoot) {
+            // Store log root for receipt verification
+            this.debugManager.logRoot = logRoot;
+        }
+        return this.debugManager.createDebugHandler();
+    }
+    /**
+     * Get demo manager
+     */
+    getDemoManager() {
+        return this.demoManager;
+    }
+    /**
+     * Get runtime statistics
+     */
+    getStats() {
+        return {
+            identity: {
+                did: this.cachedIdentity?.did,
+                keyId: this.cachedIdentity?.keyId,
+                environment: this.config.identity?.environment || "development",
+            },
+            session: this.sessionManager.getStats(),
+            audit: this.auditLogger.getStats(),
+            runtime: {
+                initialized: !!this.cachedIdentity,
+                wellKnownEnabled: !!this.wellKnownManager,
+            },
+        };
+    }
+    /**
+     * Cleanup resources
+     */
+    async cleanup() {
+        await this.sessionManager.cleanup();
+        this.auditLogger.clearSessionLog();
+    }
+    /**
+     * Check runtime environment compatibility
+     */
+    checkRuntimeEnvironment() {
+        const env = this.detectRuntimeEnvironment();
+        // Check Node.js version
+        if (env.isNode && env.nodeVersion) {
+            const [major, minor] = env.nodeVersion.split(".").map(Number);
+            if (major < 18 || (major === 18 && minor < 18)) {
+                const error = new Error(`Unsupported Node.js version ${env.nodeVersion}. MCP-I requires Node.js ≥18.18.0`);
+                error.code = "XMCP_I_ERUNTIME";
+                throw error;
+            }
+        }
+        // Check ESM support
+        if (!env.supportsESM) {
+            const error = new Error("MCP-I requires ESM support. CommonJS-only environments are not supported.");
+            error.code = "XMCP_I_ERUNTIME";
+            throw error;
+        }
+        console.log(`✅ Runtime environment check passed`);
+        console.log(`   Environment: ${this.describeEnvironment(env)}`);
+        console.log(`   ESM Support: ${env.supportsESM}`);
+        if (env.nodeVersion) {
+            console.log(`   Node.js: ${env.nodeVersion}`);
+        }
+    }
+    /**
+     * Detect runtime environment
+     */
+    detectRuntimeEnvironment() {
+        const isNode = typeof process !== "undefined" && process.versions?.node;
+        const isWorker = typeof globalThis !== "undefined" && "WorkerGlobalScope" in globalThis;
+        const isVercelEdge = typeof globalThis !== "undefined" && "EdgeRuntime" in globalThis;
+        const isAWSLambda = typeof process !== "undefined" && !!process.env.AWS_LAMBDA_FUNCTION_NAME;
+        // Check ESM support
+        // The package is CommonJS but can be imported via ESM (import from .mjs files)
+        // ESM is supported in modern Node.js and edge runtimes
+        const supportsESM = !!(isNode || isWorker || isVercelEdge || isAWSLambda);
+        return {
+            isNode: !!isNode,
+            isWorker: !!isWorker,
+            isVercelEdge: !!isVercelEdge,
+            isAWSLambda: !!isAWSLambda,
+            nodeVersion: isNode ? process.versions.node : undefined,
+            supportsESM,
+        };
+    }
+    /**
+     * Describe runtime environment for logging
+     */
+    describeEnvironment(env) {
+        if (env.isVercelEdge)
+            return "Vercel Edge Runtime";
+        if (env.isAWSLambda)
+            return "AWS Lambda";
+        if (env.isWorker)
+            return "Web Worker";
+        if (env.isNode)
+            return `Node.js ${env.nodeVersion}`;
+        return "Unknown";
+    }
+}
+exports.MCPIRuntime = MCPIRuntime;
+/**
+ * Create and initialize XMCP-I runtime
+ */
+async function createMCPIRuntime(config = {}) {
+    const runtime = new MCPIRuntime(config);
+    await runtime.initialize();
+    return runtime;
+}
+/**
+ * Runtime factory for different environments
+ */
+exports.RuntimeFactory = {
+    /**
+     * Create runtime for development
+     */
+    async forDevelopment(overrides = {}) {
+        const config = {
+            identity: {
+                environment: "development",
+                privacyMode: false, // Single public DID default
+                devIdentityPath: ".mcpi/identity.json",
+                ...overrides.identity,
+            },
+            wellKnown: {
+                environment: "development",
+                baseUrl: "http://localhost:3000",
+                ...overrides.wellKnown,
+            },
+            runtime: {
+                showVerifyLink: true, // Default true in dev
+                ...overrides.runtime,
+            },
+            demo: {
+                identityBadge: false, // Default false, opt-in
+                ...overrides.demo,
+            },
+            session: overrides.session,
+            audit: overrides.audit,
+        };
+        return createMCPIRuntime(config);
+    },
+    /**
+     * Create runtime for production
+     */
+    async forProduction(overrides = {}) {
+        const config = {
+            identity: {
+                environment: "production",
+                privacyMode: false, // Single public DID default
+            },
+            wellKnown: {
+                environment: "production",
+            },
+            runtime: {
+                showVerifyLink: false,
+            },
+            demo: {
+                identityBadge: false, // Disabled in production
+            },
+            ...overrides,
+        };
+        return createMCPIRuntime(config);
+    },
+    /**
+     * Create runtime for testing
+     */
+    async forTesting(overrides = {}) {
+        const config = {
+            identity: {
+                environment: "development",
+                devIdentityPath: ".test-mcp-i/identity.json",
+            },
+            audit: {
+                enabled: false, // Disable audit logging in tests
+            },
+            runtime: {
+                showVerifyLink: false,
+            },
+            demo: {
+                identityBadge: false,
+            },
+            ...overrides,
+        };
+        return createMCPIRuntime(config);
+    },
+};
+/**
+ * Error codes
+ */
+exports.RUNTIME_ERRORS = {
+    ERUNTIME: "XMCP_I_ERUNTIME",
+    ENOIDENTITY: "XMCP_I_ENOIDENTITY",
+    EHANDSHAKE: "XMCP_I_EHANDSHAKE",
+    ESESSION: "XMCP_I_ESESSION",
+};

package/dist/runtime/proof.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Detached Proof Generation for XMCP-I Runtime
+ *
+ * Handles JCS canonicalization, SHA-256 digest generation, and Ed25519 detached JWS signing
+ * according to requirements 5.1, 5.2, 5.3, 5.6.
+ */
+import { DetachedProof } from "@kya-os/contracts/proof";
+import { SessionContext } from "@kya-os/contracts/handshake";
+import { AgentIdentity } from "./identity";
+/**
+ * Tool request structure for proof generation
+ */
+export interface ToolRequest {
+    method: string;
+    params?: any;
+}
+/**
+ * Tool response structure for proof generation
+ */
+export interface ToolResponse {
+    data: any;
+    meta?: {
+        proof?: DetachedProof;
+        [key: string]: any;
+    };
+}
+/**
+ * Proof generation options
+ */
+export interface ProofOptions {
+    scopeId?: string;
+    delegationRef?: string;
+}
+/**
+ * Proof generator class
+ */
+export declare class ProofGenerator {
+    private identity;
+    constructor(identity: AgentIdentity);
+    /**
+     * Generate detached 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
+     */
+    private generateSHA256Hash;
+    /**
+     * JCS canonicalization implementation
+     * This is a simplified implementation - in production, use a proper JCS library
+     */
+    private canonicalizeJSON;
+    /**
+     * Generate Ed25519 detached JWS (compact format)
+     * Requirement: 5.3
+     */
+    private generateDetachedJWS;
+    /**
+     * Format base64 private key as PEM for JOSE library
+     */
+    private formatPrivateKeyAsPEM;
+    /**
+     * Verify a detached proof (for testing/validation)
+     */
+    verifyProof(proof: DetachedProof, request: ToolRequest, response: ToolResponse): Promise<boolean>;
+}
+/**
+ * Utility functions
+ */
+/**
+ * Create a tool response with proof
+ */
+export declare function createProofResponse(request: ToolRequest, data: any, identity: AgentIdentity, session: SessionContext, options?: ProofOptions): Promise<ToolResponse>;
+/**
+ * Extract canonical data for hashing (utility for testing)
+ */
+export declare function extractCanonicalData(request: ToolRequest, response: ToolResponse): {
+    request: any;
+    response: any;
+};