@kya-os/mcp-i 1.7.13 → 1.10.0

package/dist/runtime/request-context.d.ts

@@ -8,10 +8,21 @@
  * was set during handshake processing.
  */
 import type { SessionContext } from '@kya-os/contracts/handshake';
+import type { Ed25519PrivateJWK } from '@kya-os/mcp-i-core';
 export interface RequestContext {
     session?: SessionContext;
     requestId?: string;
     startTime?: number;
+    /** Delegation VC credential ID (set after delegation verification succeeds) */
+    delegationRef?: string;
+    /** Reference chain string — format: vc_id_1>del_id_1>... */
+    delegationChain?: string;
+    /** Scopes granted by the active delegation */
+    delegationScopes?: string[];
+    /** Agent Ed25519 private key JWK for delegation proof signing */
+    delegationPrivateKeyJwk?: Ed25519PrivateJWK;
+    /** Key ID used in delegation proof JWT header */
+    delegationAgentKid?: string;
 }
 /**
  * Run a function with request context
@@ -35,3 +46,33 @@ export declare function getCurrentAgentDid(): string | undefined;
  * NOTE: This only works if called within a runWithContext block
  */
 export declare function setSession(session: SessionContext): void;
+/**
+ * Update delegation context fields in the current request context.
+ * Called after delegation is verified for a protected tool call.
+ *
+ * NOTE: This only works if called within a runWithContext block
+ */
+export declare function setDelegationContext(fields: {
+    delegationRef: string;
+    delegationChain: string;
+    delegationScopes: string[];
+    delegationPrivateKeyJwk?: Ed25519PrivateJWK;
+    delegationAgentKid?: string;
+}): void;
+/**
+ * Convenience helper that wires delegation metadata from a verified delegation
+ * result and agent identity into AsyncLocalStorage in a single call.
+ *
+ * Avoids duplicating the base64-to-base64url JWK conversion and the
+ * setDelegationContext call across mcpi-runtime.ts and utils/tools.ts.
+ */
+export declare function setDelegationContextFromIdentity(params: {
+    delegationId: string;
+    delegationChain: string;
+    delegationScopes: string[];
+    identity: {
+        privateKey: string;
+        publicKey: string;
+        kid: string;
+    } | null | undefined;
+}): void;

package/dist/runtime/request-context.js

@@ -14,6 +14,8 @@ exports.getContext = getContext;
 exports.getCurrentSession = getCurrentSession;
 exports.getCurrentAgentDid = getCurrentAgentDid;
 exports.setSession = setSession;
+exports.setDelegationContext = setDelegationContext;
+exports.setDelegationContextFromIdentity = setDelegationContextFromIdentity;
 const async_hooks_1 = require("async_hooks");
 const asyncLocalStorage = new async_hooks_1.AsyncLocalStorage();
 /**
@@ -54,3 +56,49 @@ function setSession(session) {
         console.warn('[RequestContext] Attempted to set session outside of request context');
     }
 }
+/**
+ * Update delegation context fields in the current request context.
+ * Called after delegation is verified for a protected tool call.
+ *
+ * NOTE: This only works if called within a runWithContext block
+ */
+function setDelegationContext(fields) {
+    const context = getContext();
+    if (!context) {
+        console.warn('[RequestContext] setDelegationContext called outside of runWithContext — delegation headers will not be injected');
+        return;
+    }
+    context.delegationRef = fields.delegationRef;
+    context.delegationChain = fields.delegationChain;
+    context.delegationScopes = fields.delegationScopes;
+    if (fields.delegationPrivateKeyJwk !== undefined) {
+        context.delegationPrivateKeyJwk = fields.delegationPrivateKeyJwk;
+    }
+    if (fields.delegationAgentKid !== undefined) {
+        context.delegationAgentKid = fields.delegationAgentKid;
+    }
+}
+/**
+ * Convenience helper that wires delegation metadata from a verified delegation
+ * result and agent identity into AsyncLocalStorage in a single call.
+ *
+ * Avoids duplicating the base64-to-base64url JWK conversion and the
+ * setDelegationContext call across mcpi-runtime.ts and utils/tools.ts.
+ */
+function setDelegationContextFromIdentity(params) {
+    setDelegationContext({
+        delegationRef: params.delegationId,
+        delegationChain: params.delegationChain,
+        delegationScopes: params.delegationScopes,
+        delegationPrivateKeyJwk: params.identity?.privateKey
+            ? {
+                kty: "OKP",
+                crv: "Ed25519",
+                d: Buffer.from(params.identity.privateKey, "base64").toString("base64url"),
+                x: Buffer.from(params.identity.publicKey, "base64").toString("base64url"),
+                kid: params.identity.kid,
+            }
+            : undefined,
+        delegationAgentKid: params.identity?.kid,
+    });
+}

package/dist/runtime/session.d.ts

@@ -1,108 +1,17 @@
 /**
- * Handshake and Session Management for XMCP-I Runtime
+ * Session Management for XMCP-I Runtime — Node.js adapter
  *
- * Handles handshake enforcement, session management, and nonce validation
- * according to requirements 4.5-4.9 and 19.1-19.2.
- */
-import { HandshakeRequest, SessionContext, NonceCache } from "@kya-os/contracts/handshake";
-/**
- * Session management configuration
- */
-export interface SessionConfig {
-    timestampSkewSeconds?: number;
-    sessionTtlMinutes?: number;
-    absoluteSessionLifetime?: number;
-    nonceCache?: NonceCache;
-    serverDid?: string;
-}
-/**
- * Handshake validation result
- */
-export interface HandshakeResult {
-    success: boolean;
-    session?: SessionContext;
-    error?: {
-        code: string;
-        message: string;
-        remediation?: string;
-    };
-}
-/**
- * Session manager class
- */
-export declare class SessionManager {
-    private config;
-    private sessions;
-    constructor(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
-     * Uses mcpi_{uuid} format for MCP protocol compliance and traceability
-     */
-    private generateSessionId;
-    /**
-     * Generate a deterministic client identifier when the client
-     * does not provide one during the handshake.
-     */
-    private generateClientId;
-    /**
-     * Normalize string fields from handshake metadata
-     */
-    private normalizeClientInfoString;
-    /**
-     * Build MCP client metadata for the session when provided during handshake
-     */
-    private buildClientInfo;
-    /**
-     * Generate a cryptographically secure nonce
-     */
-    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;
+ * Re-exports SessionManager from @kya-os/mcp-i-core and wires in
+ * NodeCryptoProvider as the default. All existing call sites remain
+ * compatible: `new SessionManager()` and `new SessionManager(config)` work.
+ *
+ * Requirements: 4.5-4.9, 19.1-19.2
+ */
+import { SessionManager as CoreSessionManager, createHandshakeRequest, validateHandshakeFormat, type SessionConfig, type HandshakeResult } from "@kya-os/mcp-i-core";
+import { CryptoProvider } from "@kya-os/mcp-i-core";
+export type { SessionConfig, HandshakeResult };
+export { createHandshakeRequest, validateHandshakeFormat };
+export declare class SessionManager extends CoreSessionManager {
+    constructor(configOrCrypto?: SessionConfig | CryptoProvider, config?: SessionConfig);
 }
-/**
- * Default session manager instance
- */
 export declare const defaultSessionManager: SessionManager;
-/**
- * Utility functions
- */
-/**
- * Create a handshake request
- */
-export declare function createHandshakeRequest(audience: string): HandshakeRequest;
-/**
- * Validate handshake request format
- */
-export declare function validateHandshakeFormat(request: any): request is HandshakeRequest;

package/dist/runtime/session.js

@@ -1,278 +1,42 @@
 "use strict";
 /**
- * Handshake and Session Management for XMCP-I Runtime
+ * Session Management for XMCP-I Runtime — Node.js adapter
  *
- * Handles handshake enforcement, session management, and nonce validation
- * according to requirements 4.5-4.9 and 19.1-19.2.
+ * Re-exports SessionManager from @kya-os/mcp-i-core and wires in
+ * NodeCryptoProvider as the default. All existing call sites remain
+ * compatible: `new SessionManager()` and `new SessionManager(config)` work.
+ *
+ * Requirements: 4.5-4.9, 19.1-19.2
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultSessionManager = exports.SessionManager = void 0;
-exports.createHandshakeRequest = createHandshakeRequest;
-exports.validateHandshakeFormat = validateHandshakeFormat;
-const crypto_1 = require("crypto");
-const memory_nonce_cache_1 = require("../cache/memory-nonce-cache");
-/**
- * Session manager class
- */
-class SessionManager {
-    config;
-    sessions = new Map();
-    constructor(config = {}) {
-        this.config = {
-            timestampSkewSeconds: parseInt(process.env.XMCP_I_TS_SKEW_SEC || "120"),
-            sessionTtlMinutes: parseInt(process.env.XMCP_I_SESSION_TTL_MIN || "30"),
-            // absoluteSessionLifetime: undefined, // Disabled by default (omit to use undefined)
-            nonceCache: new memory_nonce_cache_1.MemoryNonceCache(),
-            ...config,
-        };
-        // Warn about multi-instance deployments with memory cache (only in production or if explicitly enabled)
-        if (this.config.nonceCache instanceof memory_nonce_cache_1.MemoryNonceCache &&
-            (process.env.NODE_ENV === "production" ||
-                process.env.MCPI_WARN_MEMORY_CACHE === "true")) {
-            console.warn("Warning: Using MemoryNonceCache - not suitable for multi-instance deployments. " +
-                "Consider using 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 {
-            // Validate timestamp (±120s clock skew by default)
-            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 XMCP_I_TS_SKEW_SEC if needed.`,
-                    },
-                };
-            }
-            // Validate nonce (must be unique within session window)
-            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",
-                    },
-                };
-            }
-            // Add nonce to cache with TTL >= session TTL
-            const nonceTtlSeconds = this.config.sessionTtlMinutes * 60 + 60; // Session TTL + 1 minute buffer
-            await this.config.nonceCache.add(request.nonce, nonceTtlSeconds, request.agentDid);
-            // Generate session ID
-            const sessionId = this.generateSessionId();
-            const clientInfo = this.buildClientInfo(request);
-            // Create session context
-            // Phase 5: Sessions start anonymous until OAuth completes
-            const session = {
-                sessionId,
-                audience: request.audience,
-                nonce: request.nonce,
-                timestamp: request.timestamp,
-                createdAt: now,
-                lastActivity: now,
-                ttlMinutes: this.config.sessionTtlMinutes,
-                identityState: "anonymous", // Phase 5: Anonymous until OAuth
-                agentDid: request.agentDid, // Pass through agent DID for delegation verification
-                ...(this.config.serverDid && { serverDid: this.config.serverDid }), // Include server DID if provided
-                ...(clientInfo && { clientInfo }),
-            };
-            // Store session
-            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);
-        // Check if session has expired (idle timeout)
-        const idleTimeSeconds = now - session.lastActivity;
-        const maxIdleSeconds = session.ttlMinutes * 60;
-        if (idleTimeSeconds > maxIdleSeconds) {
-            this.sessions.delete(sessionId);
-            return null;
-        }
-        // Check absolute session lifetime if configured
-        if (this.config.absoluteSessionLifetime) {
-            const sessionAgeSeconds = now - session.createdAt;
-            const maxAgeSeconds = this.config.absoluteSessionLifetime * 60;
-            if (sessionAgeSeconds > maxAgeSeconds) {
-                this.sessions.delete(sessionId);
-                return null;
-            }
-        }
-        // Update last activity
-        session.lastActivity = now;
-        this.sessions.set(sessionId, session);
-        return session;
-    }
-    /**
-     * Generate a unique session ID
-     * Uses mcpi_{uuid} format for MCP protocol compliance and traceability
-     */
-    generateSessionId() {
-        // Generate UUID v4 using crypto random bytes
-        const bytes = (0, crypto_1.randomBytes)(16);
-        // Set version (4) and variant (RFC4122)
-        bytes[6] = (bytes[6] & 0x0f) | 0x40;
-        bytes[8] = (bytes[8] & 0x3f) | 0x80;
-        const hex = bytes.toString("hex");
-        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 when the client
-     * does not provide one during the handshake.
-     */
-    generateClientId() {
-        return `client_${(0, crypto_1.randomBytes)(6).toString("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 when provided during handshake
-     */
-    buildClientInfo(request) {
-        const hasMetadata = !!request.clientInfo ||
-            typeof request.clientProtocolVersion === "string" ||
-            request.clientCapabilities !== undefined;
-        if (!hasMetadata) {
-            return undefined;
+exports.defaultSessionManager = exports.SessionManager = exports.validateHandshakeFormat = exports.createHandshakeRequest = void 0;
+const mcp_i_core_1 = require("@kya-os/mcp-i-core");
+Object.defineProperty(exports, "createHandshakeRequest", { enumerable: true, get: function () { return mcp_i_core_1.createHandshakeRequest; } });
+Object.defineProperty(exports, "validateHandshakeFormat", { enumerable: true, get: function () { return mcp_i_core_1.validateHandshakeFormat; } });
+const mcp_i_core_2 = require("@kya-os/mcp-i-core");
+const node_providers_1 = require("../providers/node-providers");
+function resolveNodeConfig(config) {
+    const skewEnv = process.env["XMCP_I_TS_SKEW_SEC"];
+    const ttlEnv = process.env["XMCP_I_SESSION_TTL_MIN"];
+    const parsedSkew = skewEnv ? parseInt(skewEnv, 10) : undefined;
+    const parsedTtl = ttlEnv ? parseInt(ttlEnv, 10) : undefined;
+    return {
+        ...config,
+        timestampSkewSeconds: config.timestampSkewSeconds ??
+            (parsedSkew !== undefined && !isNaN(parsedSkew) ? parsedSkew : undefined),
+        sessionTtlMinutes: config.sessionTtlMinutes ??
+            (parsedTtl !== undefined && !isNaN(parsedTtl) ? parsedTtl : undefined),
+    };
+}
+class SessionManager extends mcp_i_core_1.SessionManager {
+    constructor(configOrCrypto, config) {
+        if (configOrCrypto instanceof mcp_i_core_2.CryptoProvider) {
+            super(configOrCrypto, resolveNodeConfig(config ?? {}));
         }
-        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) ??
-                this.generateClientId(),
-            protocolVersion: this.normalizeClientInfoString(request.clientProtocolVersion),
-            capabilities: request.clientCapabilities,
-        };
-    }
-    /**
-     * Generate a cryptographically secure nonce
-     */
-    static generateNonce() {
-        return (0, crypto_1.randomBytes)(16).toString("base64url"); // 128-bit nonce
-    }
-    /**
-     * Cleanup expired sessions and nonces
-     */
-    async cleanup() {
-        const now = Math.floor(Date.now() / 1000);
-        // Clean up expired sessions
-        for (const [sessionId, session] of this.sessions.entries()) {
-            const idleTimeSeconds = now - session.lastActivity;
-            const maxIdleSeconds = session.ttlMinutes * 60;
-            let expired = idleTimeSeconds > maxIdleSeconds;
-            // Check absolute lifetime
-            if (!expired && this.config.absoluteSessionLifetime) {
-                const sessionAgeSeconds = now - session.createdAt;
-                const maxAgeSeconds = this.config.absoluteSessionLifetime * 60;
-                expired = sessionAgeSeconds > maxAgeSeconds;
-            }
-            if (expired) {
-                this.sessions.delete(sessionId);
-            }
+        else {
+            super(new node_providers_1.NodeCryptoProvider(), resolveNodeConfig(configOrCrypto ?? {}));
         }
-        // Clean up expired nonces
-        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;
-/**
- * Default session manager instance
- */
 exports.defaultSessionManager = new SessionManager();
-/**
- * Utility functions
- */
-/**
- * Create a handshake request
- */
-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));
-}