@kya-os/mcp-i

/** * 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"; import { DelegationVerifierConfig } from "./delegation-verifier"; import { NeedsAuthorizationError } from "@kya-os/contracts/runtime"; import { ToolProtectionMap, ToolProtectionResolver } from "./tool-protection"; /** * Runtime environment check */ export interface RuntimeEnvironment { isNode: boolean; isWorker: boolean; isVercelEdge: boolean; isAWSLambda: boolean; nodeVersion?: string; supportsESM: boolean; } /** * XMCP-I Runtime configuration * @deprecated Use NodeRuntimeConfig from @kya-os/mcp-i/config instead. * This interface is maintained for backward compatibility only. */ 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; includeProofHashes?: boolean; }; proofing?: { /** Enable proof generation and submission */ enabled?: boolean; /** Proof batch queue configuration */ batchQueue?: { /** Proof submission destinations (AgentShield, KTA, etc.) */ destinations?: Array<{ /** Destination type */ type: "agentshield" | "kta"; /** API base URL */ apiUrl: string; /** API key for authentication */ apiKey?: string; }>; /** Maximum batch size before auto-flush (default: 10) */ maxBatchSize?: number; /** Flush interval in milliseconds (default: 5000) */ flushIntervalMs?: number; /** Maximum retries per batch (default: 3) */ maxRetries?: number; /** Enable debug logging */ debug?: boolean; }; }; wellKnown?: WellKnownConfig; delegation?: { /** Enable delegation checks (default: false for backward compatibility) */ enabled?: boolean; /** Delegation verifier configuration */ verifier?: DelegationVerifierConfig; /** Authorization handshake configuration */ authorization?: { /** Authorization URL base for consent flow */ authorizationUrl?: string; /** KTA API configuration for reputation checks */ kta?: { apiUrl: string; apiKey?: string; }; /** Minimum reputation score to bypass authorization (0-100) */ minReputationScore?: number; /** Resume token TTL in milliseconds */ resumeTokenTtl?: number; /** Require authorization for unknown agents */ requireAuthForUnknown?: boolean; }; /** Tool protection configuration (NEW - Phase 1.5) */ toolProtections?: ToolProtectionMap; /** Local tool protection file path (default: tool-protections.json) */ toolProtectionsFile?: string | false; /** AgentShield API configuration for fetching tool protections */ agentShield?: { apiUrl: string; apiKey?: string; }; }; runtime?: { showVerifyLink?: boolean; identityBadge?: boolean; }; demo?: { identityBadge?: boolean; }; } /** * XMCP-I Runtime class */ /** * @deprecated Use MCPINodeRuntimeWrapper instead. * This class is maintained for backward compatibility only. */ export declare class MCPIRuntime { private identityManager; private sessionManager; private auditLogger; private wellKnownManager?; private debugManager?; private demoManager?; private delegationVerifier?; private resumeTokenStore; private toolProtectionResolver?; 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 * * NEW (Phase 1): Includes delegation verification interceptor */ processToolCall(request: ToolRequest, session: SessionContext, toolHandler: (request: ToolRequest) => Promise<any>, options?: { scopeId?: string; delegationRef?: string; requiresDelegation?: boolean; requiredScopes?: string[]; agentDid?: string; }): Promise<ToolResponse | NeedsAuthorizationError>; /** * 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 tool protection resolver (NEW - Phase 1.5) */ getToolProtectionResolver(): ToolProtectionResolver | undefined; /** * Get runtime statistics */ getStats(): { identity: { did: string | undefined; kid: string | undefined; environment: "development" | "production"; }; session: { activeSessions: number; config: { timestampSkewSeconds: number; sessionTtlMinutes: number; absoluteSessionLifetime?: number; cacheType: string; }; }; audit: { enabled: boolean; sessionsLogged: number; includePayloads: boolean; totalRecordsLogged: number; currentLogSize: number; lastRotationTime: number; }; 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"; };