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

package/dist/session/index.d.ts

@@ -1,5 +0,0 @@
-/**
- * Session module — platform-agnostic session management reference implementation.
- */
-export { SessionManager, createHandshakeRequest, validateHandshakeFormat, type SessionConfig, type HandshakeResult, } from "./manager";
-//# sourceMappingURL=index.d.ts.map

package/dist/session/index.js

@@ -1,11 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateHandshakeFormat = exports.createHandshakeRequest = exports.SessionManager = void 0;
-/**
- * Session module — platform-agnostic session management reference implementation.
- */
-var manager_1 = require("./manager");
-Object.defineProperty(exports, "SessionManager", { enumerable: true, get: function () { return manager_1.SessionManager; } });
-Object.defineProperty(exports, "createHandshakeRequest", { enumerable: true, get: function () { return manager_1.createHandshakeRequest; } });
-Object.defineProperty(exports, "validateHandshakeFormat", { enumerable: true, get: function () { return manager_1.validateHandshakeFormat; } });
-//# sourceMappingURL=index.js.map

package/dist/session/manager.d.ts

@@ -1,113 +0,0 @@
-/**
- * Session Management — Platform-agnostic Protocol Reference
- *
- * Handles handshake enforcement, session management, and nonce validation
- * according to MCP-I requirements 4.5–4.9 and 19.1–19.2.
- *
- * Platform adapters inject a CryptoProvider for all random byte generation.
- * The static generateNonce() uses globalThis.crypto (available Node 20+ and
- * Cloudflare Workers) to remain synchronous without platform-specific imports.
- */
-import { HandshakeRequest, SessionContext, NonceCache } from "@kya-os/contracts/handshake";
-import { CryptoProvider } from "../providers/base";
-/**
- * Session management configuration
- */
-export interface SessionConfig {
-    /** Clock-skew tolerance in seconds. Default: 120. */
-    timestampSkewSeconds?: number;
-    /** Idle session TTL in minutes. Default: 30. */
-    sessionTtlMinutes?: number;
-    /** Optional absolute session lifetime in minutes. */
-    absoluteSessionLifetime?: number;
-    /** Nonce cache implementation. Default: MemoryNonceCacheProvider. */
-    nonceCache?: NonceCache;
-    /** Optional server DID to include in session context. */
-    serverDid?: string;
-}
-/**
- * Handshake validation result
- */
-export interface HandshakeResult {
-    success: boolean;
-    session?: SessionContext;
-    error?: {
-        code: string;
-        message: string;
-        remediation?: string;
-    };
-}
-/**
- * Platform-agnostic session manager.
- * Requires a CryptoProvider for session ID and client ID generation.
- */
-export declare class SessionManager {
-    private config;
-    private cryptoProvider;
-    private sessions;
-    constructor(cryptoProvider: CryptoProvider, config?: SessionConfig);
-    /**
-     * Set server DID for session creation (called after identity is loaded).
-     */
-    setServerDid(serverDid: string): void;
-    /**
-     * Validate handshake and create or retrieve session.
-     * Requirements: 4.5, 4.6, 4.7, 4.8, 4.9
-     */
-    validateHandshake(request: HandshakeRequest): Promise<HandshakeResult>;
-    /**
-     * Get session by ID and update last activity.
-     */
-    getSession(sessionId: string): Promise<SessionContext | null>;
-    /**
-     * Generate a unique session ID (mcpi_{uuid} format).
-     * Uses injected CryptoProvider for platform-agnostic random bytes.
-     */
-    private generateSessionId;
-    /**
-     * Generate a deterministic client identifier.
-     */
-    private generateClientId;
-    /**
-     * Normalize string fields from handshake metadata.
-     */
-    private normalizeClientInfoString;
-    /**
-     * Build MCP client metadata for the session.
-     */
-    private buildClientInfo;
-    /**
-     * Generate a cryptographically secure nonce.
-     * Uses globalThis.crypto (sync Web Crypto — available in Node 20+ and Workers).
-     */
-    static generateNonce(): string;
-    /**
-     * Cleanup expired sessions and nonces.
-     */
-    cleanup(): Promise<void>;
-    /**
-     * Get session statistics.
-     */
-    getStats(): {
-        activeSessions: number;
-        config: {
-            timestampSkewSeconds: number;
-            sessionTtlMinutes: number;
-            absoluteSessionLifetime?: number;
-            cacheType: string;
-        };
-    };
-    /**
-     * Clear all sessions (useful for testing).
-     */
-    clearSessions(): void;
-}
-/**
- * Create a handshake request with a secure nonce.
- */
-export declare function createHandshakeRequest(audience: string): HandshakeRequest;
-/**
- * Validate handshake request format.
- */
-export declare function validateHandshakeFormat(request: unknown): request is HandshakeRequest;
-//# sourceMappingURL=manager.d.ts.map

package/dist/session/manager.js

@@ -1,273 +0,0 @@
-"use strict";
-/**
- * Session Management — Platform-agnostic Protocol Reference
- *
- * Handles handshake enforcement, session management, and nonce validation
- * according to MCP-I requirements 4.5–4.9 and 19.1–19.2.
- *
- * Platform adapters inject a CryptoProvider for all random byte generation.
- * The static generateNonce() uses globalThis.crypto (available Node 20+ and
- * Cloudflare Workers) to remain synchronous without platform-specific imports.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SessionManager = void 0;
-exports.createHandshakeRequest = createHandshakeRequest;
-exports.validateHandshakeFormat = validateHandshakeFormat;
-const memory_1 = require("../providers/memory");
-const logging_1 = require("../logging");
-/**
- * Platform-agnostic session manager.
- * Requires a CryptoProvider for session ID and client ID generation.
- */
-class SessionManager {
-    config;
-    cryptoProvider;
-    sessions = new Map();
-    constructor(cryptoProvider, config = {}) {
-        this.cryptoProvider = cryptoProvider;
-        this.config = {
-            timestampSkewSeconds: config.timestampSkewSeconds ?? 120,
-            sessionTtlMinutes: config.sessionTtlMinutes ?? 30,
-            nonceCache: config.nonceCache ?? new memory_1.MemoryNonceCacheProvider(),
-            ...(config.absoluteSessionLifetime !== undefined && {
-                absoluteSessionLifetime: config.absoluteSessionLifetime,
-            }),
-            ...(config.serverDid !== undefined && { serverDid: config.serverDid }),
-        };
-        if (this.config.nonceCache instanceof memory_1.MemoryNonceCacheProvider) {
-            logging_1.logger.warn("[SessionManager] Using MemoryNonceCacheProvider — not suitable for " +
-                "multi-instance deployments. Use Redis, DynamoDB, or Cloudflare KV " +
-                "for production.");
-        }
-    }
-    /**
-     * Set server DID for session creation (called after identity is loaded).
-     */
-    setServerDid(serverDid) {
-        this.config.serverDid = serverDid;
-    }
-    /**
-     * Validate handshake and create or retrieve session.
-     * Requirements: 4.5, 4.6, 4.7, 4.8, 4.9
-     */
-    async validateHandshake(request) {
-        try {
-            const now = Math.floor(Date.now() / 1000);
-            const timeDiff = Math.abs(now - request.timestamp);
-            if (timeDiff > this.config.timestampSkewSeconds) {
-                return {
-                    success: false,
-                    error: {
-                        code: "XMCP_I_EHANDSHAKE",
-                        message: `Timestamp outside acceptable range (±${this.config.timestampSkewSeconds}s)`,
-                        remediation: `Check NTP sync on client and server. Current server time: ${now}, received: ${request.timestamp}, diff: ${timeDiff}s. Adjust timestampSkewSeconds if needed.`,
-                    },
-                };
-            }
-            const nonceExists = await this.config.nonceCache.has(request.nonce, request.agentDid);
-            if (nonceExists) {
-                return {
-                    success: false,
-                    error: {
-                        code: "XMCP_I_EHANDSHAKE",
-                        message: "Nonce already used (replay attack prevention)",
-                        remediation: "Generate a new unique nonce for each request",
-                    },
-                };
-            }
-            const nonceTtlSeconds = this.config.sessionTtlMinutes * 60 + 60;
-            await this.config.nonceCache.add(request.nonce, nonceTtlSeconds, request.agentDid);
-            const sessionId = await this.generateSessionId();
-            const clientInfo = await this.buildClientInfo(request);
-            const session = {
-                sessionId,
-                audience: request.audience,
-                nonce: request.nonce,
-                timestamp: request.timestamp,
-                createdAt: now,
-                lastActivity: now,
-                ttlMinutes: this.config.sessionTtlMinutes,
-                identityState: "anonymous",
-                agentDid: request.agentDid,
-                ...(this.config.serverDid && { serverDid: this.config.serverDid }),
-                ...(clientInfo && { clientInfo }),
-            };
-            this.sessions.set(sessionId, session);
-            return { success: true, session };
-        }
-        catch (error) {
-            return {
-                success: false,
-                error: {
-                    code: "XMCP_I_EHANDSHAKE",
-                    message: `Handshake validation failed: ${error instanceof Error ? error.message : "Unknown error"}`,
-                },
-            };
-        }
-    }
-    /**
-     * Get session by ID and update last activity.
-     */
-    async getSession(sessionId) {
-        const session = this.sessions.get(sessionId);
-        if (!session)
-            return null;
-        const now = Math.floor(Date.now() / 1000);
-        const idleTimeSeconds = now - session.lastActivity;
-        const maxIdleSeconds = session.ttlMinutes * 60;
-        if (idleTimeSeconds > maxIdleSeconds) {
-            this.sessions.delete(sessionId);
-            return null;
-        }
-        if (this.config.absoluteSessionLifetime !== undefined) {
-            const sessionAgeSeconds = now - session.createdAt;
-            const maxAgeSeconds = this.config.absoluteSessionLifetime * 60;
-            if (sessionAgeSeconds > maxAgeSeconds) {
-                this.sessions.delete(sessionId);
-                return null;
-            }
-        }
-        session.lastActivity = now;
-        this.sessions.set(sessionId, session);
-        return session;
-    }
-    /**
-     * Generate a unique session ID (mcpi_{uuid} format).
-     * Uses injected CryptoProvider for platform-agnostic random bytes.
-     */
-    async generateSessionId() {
-        const bytes = await this.cryptoProvider.randomBytes(16);
-        // Apply UUID v4 version and variant bits
-        bytes[6] = (bytes[6] & 0x0f) | 0x40;
-        bytes[8] = (bytes[8] & 0x3f) | 0x80;
-        const hex = Array.from(bytes)
-            .map((b) => b.toString(16).padStart(2, "0"))
-            .join("");
-        const uuid = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
-        return `mcpi_${uuid}`;
-    }
-    /**
-     * Generate a deterministic client identifier.
-     */
-    async generateClientId() {
-        const bytes = await this.cryptoProvider.randomBytes(6);
-        const hex = Array.from(bytes)
-            .map((b) => b.toString(16).padStart(2, "0"))
-            .join("");
-        return `client_${hex}`;
-    }
-    /**
-     * Normalize string fields from handshake metadata.
-     */
-    normalizeClientInfoString(value) {
-        if (typeof value !== "string")
-            return undefined;
-        const trimmed = value.trim();
-        return trimmed.length > 0 ? trimmed : undefined;
-    }
-    /**
-     * Build MCP client metadata for the session.
-     */
-    async buildClientInfo(request) {
-        const hasMetadata = !!request.clientInfo ||
-            typeof request.clientProtocolVersion === "string" ||
-            request.clientCapabilities !== undefined;
-        if (!hasMetadata)
-            return undefined;
-        const source = request.clientInfo;
-        return {
-            name: this.normalizeClientInfoString(source?.name) ?? "unknown",
-            title: this.normalizeClientInfoString(source?.title),
-            version: this.normalizeClientInfoString(source?.version),
-            platform: this.normalizeClientInfoString(source?.platform),
-            vendor: this.normalizeClientInfoString(source?.vendor),
-            persistentId: this.normalizeClientInfoString(source?.persistentId),
-            clientId: this.normalizeClientInfoString(source?.clientId) ??
-                (await this.generateClientId()),
-            protocolVersion: this.normalizeClientInfoString(request.clientProtocolVersion),
-            capabilities: request.clientCapabilities,
-        };
-    }
-    /**
-     * Generate a cryptographically secure nonce.
-     * Uses globalThis.crypto (sync Web Crypto — available in Node 20+ and Workers).
-     */
-    static generateNonce() {
-        const buffer = new Uint8Array(16);
-        globalThis.crypto.getRandomValues(buffer);
-        let binaryStr = "";
-        for (let i = 0; i < buffer.length; i++) {
-            binaryStr += String.fromCharCode(buffer[i]);
-        }
-        return btoa(binaryStr)
-            .replace(/\+/g, "-")
-            .replace(/\//g, "_")
-            .replace(/=/g, "");
-    }
-    /**
-     * Cleanup expired sessions and nonces.
-     */
-    async cleanup() {
-        const now = Math.floor(Date.now() / 1000);
-        for (const [sessionId, session] of this.sessions.entries()) {
-            const idleTimeSeconds = now - session.lastActivity;
-            const maxIdleSeconds = session.ttlMinutes * 60;
-            let expired = idleTimeSeconds > maxIdleSeconds;
-            if (!expired && this.config.absoluteSessionLifetime !== undefined) {
-                const sessionAgeSeconds = now - session.createdAt;
-                const maxAgeSeconds = this.config.absoluteSessionLifetime * 60;
-                expired = sessionAgeSeconds > maxAgeSeconds;
-            }
-            if (expired) {
-                this.sessions.delete(sessionId);
-            }
-        }
-        await this.config.nonceCache.cleanup();
-    }
-    /**
-     * Get session statistics.
-     */
-    getStats() {
-        return {
-            activeSessions: this.sessions.size,
-            config: {
-                timestampSkewSeconds: this.config.timestampSkewSeconds,
-                sessionTtlMinutes: this.config.sessionTtlMinutes,
-                absoluteSessionLifetime: this.config.absoluteSessionLifetime,
-                cacheType: this.config.nonceCache.constructor.name,
-            },
-        };
-    }
-    /**
-     * Clear all sessions (useful for testing).
-     */
-    clearSessions() {
-        this.sessions.clear();
-    }
-}
-exports.SessionManager = SessionManager;
-/**
- * Create a handshake request with a secure nonce.
- */
-function createHandshakeRequest(audience) {
-    return {
-        nonce: SessionManager.generateNonce(),
-        audience,
-        timestamp: Math.floor(Date.now() / 1000),
-    };
-}
-/**
- * Validate handshake request format.
- */
-function validateHandshakeFormat(request) {
-    return (typeof request === "object" &&
-        request !== null &&
-        typeof request.nonce === "string" &&
-        request.nonce.length > 0 &&
-        typeof request.audience === "string" &&
-        request.audience.length > 0 &&
-        typeof request.timestamp === "number" &&
-        request.timestamp > 0 &&
-        Number.isInteger(request.timestamp));
-}
-//# sourceMappingURL=manager.js.map

package/dist/types/oauth-required-error.d.ts

@@ -1,46 +0,0 @@
-/**
- * OAuth Required Error
- *
- * Error thrown when a tool requires an IDP token (OAuth) but none is available.
- * This triggers the OAuth flow to obtain the necessary token.
- *
- * @package @kya-os/mcp-i-core
- */
-export interface OAuthRequiredErrorOptions {
-    /** Name of the tool requiring OAuth */
-    toolName: string;
-    /** Required OAuth scopes */
-    requiredScopes: string[];
-    /** OAuth provider name (e.g., "github", "google") */
-    provider: string;
-    /** OAuth authorization URL */
-    oauthUrl: string;
-    /** Optional resume token for continuing after OAuth */
-    resumeToken?: string;
-    /** Optional user DID */
-    userDid?: string;
-    /** Optional session ID */
-    sessionId?: string;
-    /**
-     * Auth type from tool protection config (e.g., "password", "oauth")
-     * Used to determine correct consent flow when catching the error
-     */
-    authType?: string;
-}
-/**
- * Error thrown when a tool requires OAuth but IDP token is not available
- *
- * This error should trigger the OAuth flow to obtain the necessary IDP token.
- */
-export declare class OAuthRequiredError extends Error {
-    readonly toolName: string;
-    readonly requiredScopes: string[];
-    readonly provider: string;
-    readonly oauthUrl: string;
-    readonly resumeToken?: string;
-    readonly userDid?: string;
-    readonly sessionId?: string;
-    readonly authType?: string;
-    constructor(options: OAuthRequiredErrorOptions);
-}
-//# sourceMappingURL=oauth-required-error.d.ts.map

package/dist/types/oauth-required-error.js

@@ -1,42 +0,0 @@
-"use strict";
-/**
- * OAuth Required Error
- *
- * Error thrown when a tool requires an IDP token (OAuth) but none is available.
- * This triggers the OAuth flow to obtain the necessary token.
- *
- * @package @kya-os/mcp-i-core
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.OAuthRequiredError = void 0;
-/**
- * Error thrown when a tool requires OAuth but IDP token is not available
- *
- * This error should trigger the OAuth flow to obtain the necessary IDP token.
- */
-class OAuthRequiredError extends Error {
-    toolName;
-    requiredScopes;
-    provider;
-    oauthUrl;
-    resumeToken;
-    userDid;
-    sessionId;
-    authType;
-    constructor(options) {
-        const { toolName, requiredScopes, provider, oauthUrl } = options;
-        super(`OAuth required for tool "${toolName}" with provider "${provider}". ` +
-            `Required scopes: ${requiredScopes.join(", ")}`);
-        this.name = "OAuthRequiredError";
-        this.toolName = toolName;
-        this.requiredScopes = requiredScopes;
-        this.provider = provider;
-        this.oauthUrl = oauthUrl;
-        this.resumeToken = options.resumeToken;
-        this.userDid = options.userDid;
-        this.sessionId = options.sessionId;
-        this.authType = options.authType;
-    }
-}
-exports.OAuthRequiredError = OAuthRequiredError;
-//# sourceMappingURL=oauth-required-error.js.map

package/dist/types/tool-protection.d.ts

@@ -1,144 +0,0 @@
-/**
- * Tool Protection Types
- *
- * Implementation-specific type definitions for tool protection services.
- * Core spec types are imported from @kya-os/contracts/tool-protection.
- *
- * @package @kya-os/mcp-i-core
- * @version 1.0.0
- */
-import type { ToolProtection, ToolProtectionMap } from "@kya-os/contracts/tool-protection";
-export type { ToolProtection };
-/**
- * Complete tool protection configuration for a project
- * @deprecated Use ToolProtectionMap from @kya-os/contracts/tool-protection
- */
-export interface ToolProtectionConfig {
-    /**
-     * Map of tool names to their protection settings
-     */
-    toolProtections: ToolProtectionMap;
-}
-/**
- * Configuration for the ToolProtectionService
- */
-export interface ToolProtectionServiceConfig {
-    /**
-     * AgentShield API base URL
-     * @example "https://kya.vouched.id"
-     */
-    apiUrl: string;
-    /**
-     * AgentShield API key for authentication
-     * @example "sk_..."
-     */
-    apiKey: string;
-    /**
-     * Project ID (optional, used for backward compatibility)
-     * The service now fetches config by agent DID instead
-     * @deprecated Use agent DID from runtime identity
-     * @example "mcp-i-ieu0ro"
-     */
-    projectId?: string;
-    /**
-     * Cache TTL in milliseconds
-     * @default 300000 (5 minutes)
-     */
-    cacheTtl?: number;
-    /**
-     * Local/default configuration (LOWEST priority after defaults)
-     *
-     * This config serves as a base that gets OVERRIDDEN by remote config.
-     * Use this for development defaults or project-specific base settings.
-     *
-     * Precedence order (highest to lowest):
-     * 1. Remote config (AgentShield API) - WINS
-     * 2. Local config (this field)
-     * 3. Framework defaults
-     *
-     * @optional
-     */
-    localConfig?: ToolProtectionConfig;
-    /**
-     * Offline fallback configuration (ONLY used when API is unavailable)
-     *
-     * Unlike localConfig, this is NOT merged with remote config.
-     * It's only used as a complete replacement when the API cannot be reached.
-     *
-     * Fallback order when API fails:
-     * 1. Stale cache (if allowStaleCache=true and within maxStaleCacheAge)
-     * 2. This offlineFallbackConfig
-     * 3. failSafeBehavior (deny-all or allow-all)
-     *
-     * @optional
-     */
-    offlineFallbackConfig?: ToolProtectionConfig;
-    /**
-     * Fail-safe behavior when API is unavailable and no offline fallback is provided
-     * - 'deny-all': Block all tools by default (secure, recommended for production)
-     * - 'allow-all': Allow all tools (insecure, not recommended for production)
-     * @default 'deny-all'
-     */
-    failSafeBehavior?: "deny-all" | "allow-all";
-    /**
-     * Maximum age (in milliseconds) for stale cache to be used during outages
-     * Stale cache is used when API fails and no fallback is provided
-     * @default 86400000 (24 hours)
-     */
-    maxStaleCacheAge?: number;
-    /**
-     * Allow using stale cache during outages
-     * @default true
-     */
-    allowStaleCache?: boolean;
-    /**
-     * Enable debug logging
-     * @default false
-     */
-    debug?: boolean;
-}
-/**
- * API response from /api/v1/bouncer/projects/{projectId}/tool-protections
- */
-export interface ToolProtectionApiResponse {
-    success: boolean;
-    data: {
-        toolProtections: Record<string, ToolProtection>;
-    };
-    metadata: {
-        timestamp: string;
-        cachedUntil: string;
-    };
-}
-/**
- * Error thrown when a tool requires delegation but none is provided
- *
- * Note: Resume token generation is handled by MCPIRuntimeBase.generateResumeToken().
- * The runtime should generate the token and pass it to this constructor.
- */
-export declare class DelegationRequiredError extends Error {
-    toolName: string;
-    requiredScopes: string[];
-    consentUrl?: string | undefined;
-    resumeToken?: string;
-    interceptedCall?: InterceptedToolCall;
-    constructor(toolName: string, requiredScopes: string[], consentUrl?: string | undefined, interceptedCall?: InterceptedToolCall, resumeToken?: string);
-}
-/**
- * Context for an intercepted tool call that needs authorization
- */
-export interface InterceptedToolCall {
-    toolName: string;
-    args: any;
-    sessionId: string;
-    timestamp: number;
-    expiresAt: number;
-}
-/**
- * Error thrown when the tool protection service fails
- */
-export declare class ToolProtectionServiceError extends Error {
-    cause?: Error | undefined;
-    constructor(message: string, cause?: Error | undefined);
-}
-//# sourceMappingURL=tool-protection.d.ts.map

package/dist/types/tool-protection.js

@@ -1,48 +0,0 @@
-"use strict";
-/**
- * Tool Protection Types
- *
- * Implementation-specific type definitions for tool protection services.
- * Core spec types are imported from @kya-os/contracts/tool-protection.
- *
- * @package @kya-os/mcp-i-core
- * @version 1.0.0
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolProtectionServiceError = exports.DelegationRequiredError = void 0;
-/**
- * Error thrown when a tool requires delegation but none is provided
- *
- * Note: Resume token generation is handled by MCPIRuntimeBase.generateResumeToken().
- * The runtime should generate the token and pass it to this constructor.
- */
-class DelegationRequiredError extends Error {
-    toolName;
-    requiredScopes;
-    consentUrl;
-    resumeToken;
-    interceptedCall;
-    constructor(toolName, requiredScopes, consentUrl, interceptedCall, resumeToken) {
-        super(`Delegation required for tool "${toolName}"`);
-        this.toolName = toolName;
-        this.requiredScopes = requiredScopes;
-        this.consentUrl = consentUrl;
-        this.name = "DelegationRequiredError";
-        this.interceptedCall = interceptedCall;
-        this.resumeToken = resumeToken;
-    }
-}
-exports.DelegationRequiredError = DelegationRequiredError;
-/**
- * Error thrown when the tool protection service fails
- */
-class ToolProtectionServiceError extends Error {
-    cause;
-    constructor(message, cause) {
-        super(message);
-        this.cause = cause;
-        this.name = "ToolProtectionServiceError";
-    }
-}
-exports.ToolProtectionServiceError = ToolProtectionServiceError;
-//# sourceMappingURL=tool-protection.js.map