@kya-os/mcp-i-core 1.4.18 → 1.6.0

package/dist/runtime/ext-apps-constants.d.ts

@@ -0,0 +1,14 @@
+/**
+ * MCP Apps Extension Constants
+ *
+ * Shared constants for the MCP Apps consent UI integration.
+ * Kept separate from the runtime class so consumers can import
+ * without pulling in the full MCPIRuntimeBase dependency.
+ */
+/**
+ * URI for the shared consent UI resource.
+ * All consent-requiring tools reference this single resource;
+ * tool-specific data is passed via structuredContent.
+ */
+export declare const CONSENT_UI_RESOURCE_URI = "ui://mcpi-consent/authorize";
+//# sourceMappingURL=ext-apps-constants.d.ts.map

package/dist/runtime/ext-apps-constants.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * MCP Apps Extension Constants
+ *
+ * Shared constants for the MCP Apps consent UI integration.
+ * Kept separate from the runtime class so consumers can import
+ * without pulling in the full MCPIRuntimeBase dependency.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONSENT_UI_RESOURCE_URI = void 0;
+/**
+ * URI for the shared consent UI resource.
+ * All consent-requiring tools reference this single resource;
+ * tool-specific data is passed via structuredContent.
+ */
+exports.CONSENT_UI_RESOURCE_URI = "ui://mcpi-consent/authorize";
+//# sourceMappingURL=ext-apps-constants.js.map

package/dist/services/batch-delegation.service.d.ts

@@ -48,6 +48,6 @@ export declare class BatchDelegationService {
      * @param agentDid - Agent DID for fetching tool protections
      * @returns Array of tool names requiring the specified provider
      */
-    getToolsForProvider(provider: string, projectId: string, agentDid: string): Promise<string[]>;
+    getToolsForProvider(_provider: string, _projectId: string, _agentDid: string): Promise<string[]>;
 }
 //# sourceMappingURL=batch-delegation.service.d.ts.map

package/dist/services/batch-delegation.service.js

@@ -84,10 +84,10 @@ class BatchDelegationService {
      * @param agentDid - Agent DID for fetching tool protections
      * @returns Array of tool names requiring the specified provider
      */
-    async getToolsForProvider(provider, projectId, agentDid) {
-        // This would require fetching all tool protections
-        // For now, return empty array (can be enhanced later)
-        // TODO: Implement if needed for Phase 4 batch delegation UI
+    async getToolsForProvider(_provider, _projectId, _agentDid) {
+        // Stub implementation: Returns empty array.
+        // Full implementation would fetch all tool protections and filter by provider.
+        // TODO(feature): Implement when batch delegation UI requires provider-based tool grouping.
         return [];
     }
 }

package/dist/services/proof-verifier.js

@@ -23,7 +23,7 @@ class ProofVerifier {
         this.clock = config.clockProvider;
         this.nonceCache = config.nonceCacheProvider;
         this.fetch = config.fetchProvider;
-        this.timestampSkewSeconds = config.timestampSkewSeconds ?? 120; // Default 2 minutes
+        this.timestampSkewSeconds = config.timestampSkewSeconds ?? 300; // Default 5 minutes
         this.nonceTtlSeconds = config.nonceTtlSeconds ?? 300; // Default 5 minutes
     }
     /**

package/dist/session/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 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

@@ -0,0 +1,11 @@
+"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

@@ -0,0 +1,113 @@
+/**
+ * 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

@@ -0,0 +1,273 @@
+"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/docs/API_REFERENCE.md

@@ -0,0 +1,76 @@
+# API Reference
+
+Full API reference for `@kya-os/mcp-i-core` package.
+
+> **Note:** This reference is being updated. For complete API signatures, see the TypeScript type definitions in `src/index.ts` which exports all public interfaces.
+
+## Installation
+
+```bash
+npm install @kya-os/mcp-i-core
+# or
+pnpm add @kya-os/mcp-i-core
+```
+
+## Core Exports
+
+### Runtime
+
+- **MCPIRuntimeBase** - Provider-based runtime class for MCP-I operations
+
+### Delegation (W3C VC-based)
+
+- **DelegationCredentialIssuer** - Issues W3C Verifiable Credentials for delegations
+- **DelegationCredentialVerifier** - Verifies delegation credentials with DID resolution
+- **StatusList2021Manager** - Manages StatusList2021 credentials for revocation
+- **DelegationGraphManager** - Manages delegation relationships and chains
+- **CascadingRevocationManager** - Handles cascading revocation through delegation chains
+
+### Services
+
+- **ToolProtectionService** - Manages tool-level delegation requirements
+- **PolicyService** - Evaluates access policies
+- **CryptoService** - Cryptographic operations (JWS, signatures)
+- **ProofVerifier** - Verifies detached proofs
+- **OAuthService** - OAuth 2.0 with PKCE support
+- **AccessControlApiService** - AgentShield API integration
+
+### Providers (Abstract)
+
+- **CryptoProvider** - Cryptographic operations interface
+- **IdentityProvider** - Agent identity management
+- **ClockProvider** - Time operations
+- **FetchProvider** - Network operations
+- **StorageProvider** - Key-value storage
+- **NonceCacheProvider** - Replay attack prevention
+
+### Memory Providers (Testing)
+
+- **MemoryStorageProvider** - In-memory storage
+- **MemoryNonceCacheProvider** - In-memory nonce cache
+- **MemoryIdentityProvider** - In-memory identity storage
+- **MemoryStatusListStorage** - In-memory status list storage
+- **MemoryDelegationGraphStorage** - In-memory delegation graph
+
+### Utilities
+
+- **SchemaVerifier** - JSON Schema draft-07 compliance verification
+- **BitstringManager** - StatusList2021 bitstring operations
+- **UserDidManager** - User DID generation and management
+- **createDidKeyResolver** - did:key resolution utilities
+
+### Error Types
+
+- **DelegationRequiredError** - Thrown when delegation is required
+- **OAuthRequiredError** - Thrown when OAuth authorization is needed
+- **ProofVerificationError** - Proof verification failures
+
+## Usage Examples
+
+See the main [README.md](../README.md) for usage examples and the [TypeScript definitions](../src/index.ts) for complete type signatures.
+
+## Related Documentation
+
+- [W3C VC Delegation Guide](./W3C_VC_DELEGATION_GUIDE.md)
+- [StatusList2021 Guide](./STATUSLIST2021_GUIDE.md)
+- [Compliance Matrix](./COMPLIANCE_MATRIX.md)