@kya-os/mcp-i 0.1.0 → 1.2.0

package/dist/runtime/proof.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProofGenerator = void 0;
+exports.createProofResponse = createProofResponse;
+exports.extractCanonicalData = extractCanonicalData;
+const crypto_1 = require("crypto");
+const jose_1 = require("jose");
+/**
+ * Proof generator class
+ */
+class ProofGenerator {
+    identity;
+    constructor(identity) {
+        this.identity = identity;
+    }
+    /**
+     * Generate detached proof for tool request/response
+     * Requirements: 5.1, 5.2, 5.3, 5.6
+     */
+    async generateProof(request, response, session, options = {}) {
+        // Generate canonical hashes
+        const hashes = this.generateCanonicalHashes(request, response);
+        // Create proof metadata
+        const meta = {
+            did: this.identity.did,
+            kid: this.identity.keyId,
+            ts: Math.floor(Date.now() / 1000),
+            nonce: session.nonce,
+            audience: session.audience,
+            sessionId: session.sessionId,
+            requestHash: hashes.requestHash,
+            responseHash: hashes.responseHash,
+            ...options, // Include scopeId and delegationRef if provided
+        };
+        // Generate detached JWS
+        const jws = await this.generateDetachedJWS(meta);
+        return {
+            jws,
+            meta,
+        };
+    }
+    /**
+     * Generate canonical hashes for request and response
+     * Requirement: 5.1
+     */
+    generateCanonicalHashes(request, response) {
+        // Canonicalize request (exclude transport metadata, include method and params)
+        const canonicalRequest = {
+            method: request.method,
+            ...(request.params && { params: request.params }),
+        };
+        // Canonicalize response (only the data part, exclude meta)
+        const canonicalResponse = response.data;
+        // Generate SHA-256 hashes with JCS canonicalization
+        const requestHash = this.generateSHA256Hash(canonicalRequest);
+        const responseHash = this.generateSHA256Hash(canonicalResponse);
+        return {
+            requestHash,
+            responseHash,
+        };
+    }
+    /**
+     * Generate SHA-256 hash with JCS canonicalization
+     * Requirement: 5.2
+     */
+    generateSHA256Hash(data) {
+        // JCS (JSON Canonicalization Scheme) canonicalization
+        const canonicalJson = this.canonicalizeJSON(data);
+        // Generate SHA-256 hash
+        const hash = (0, crypto_1.createHash)("sha256")
+            .update(canonicalJson, "utf8")
+            .digest("hex");
+        return `sha256:${hash}`;
+    }
+    /**
+     * JCS canonicalization implementation
+     * This is a simplified implementation - in production, use a proper JCS library
+     */
+    canonicalizeJSON(obj) {
+        if (obj === null)
+            return "null";
+        if (typeof obj === "boolean")
+            return obj.toString();
+        if (typeof obj === "number") {
+            // Handle special number cases
+            if (Number.isNaN(obj))
+                return "null";
+            if (!Number.isFinite(obj))
+                return "null";
+            return obj.toString();
+        }
+        if (typeof obj === "string")
+            return JSON.stringify(obj);
+        if (Array.isArray(obj)) {
+            const items = obj.map((item) => this.canonicalizeJSON(item));
+            return `[${items.join(",")}]`;
+        }
+        if (typeof obj === "object") {
+            // Sort keys for canonical ordering
+            const sortedKeys = Object.keys(obj).sort();
+            const pairs = sortedKeys.map((key) => {
+                const value = this.canonicalizeJSON(obj[key]);
+                return `${JSON.stringify(key)}:${value}`;
+            });
+            return `{${pairs.join(",")}}`;
+        }
+        // Fallback for other types
+        return JSON.stringify(obj);
+    }
+    /**
+     * Generate Ed25519 detached JWS (compact format)
+     * Requirement: 5.3
+     */
+    async generateDetachedJWS(meta) {
+        try {
+            // Import the private key
+            const privateKeyPem = this.formatPrivateKeyAsPEM(this.identity.privateKey);
+            const privateKey = await (0, jose_1.importPKCS8)(privateKeyPem, "EdDSA");
+            // Create JWT with proof metadata as payload
+            const jwt = await new jose_1.SignJWT(meta)
+                .setProtectedHeader({
+                alg: "EdDSA",
+                kid: this.identity.keyId,
+            })
+                .sign(privateKey);
+            // For detached JWS, we remove the payload part (middle section)
+            const [header, , signature] = jwt.split(".");
+            return `${header}..${signature}`;
+        }
+        catch (error) {
+            throw new Error(`Failed to generate detached JWS: ${error instanceof Error ? error.message : "Unknown error"}`);
+        }
+    }
+    /**
+     * Format base64 private key as PEM for JOSE library
+     */
+    formatPrivateKeyAsPEM(base64PrivateKey) {
+        // For Ed25519, we need to format as PKCS#8 PEM
+        // This is a simplified implementation - in production, use proper key formatting
+        const keyData = Buffer.from(base64PrivateKey, "base64");
+        // Ed25519 PKCS#8 header and footer
+        const header = "-----BEGIN PRIVATE KEY-----\n";
+        const footer = "\n-----END PRIVATE KEY-----";
+        // For Ed25519, we need to wrap the raw key in PKCS#8 structure
+        // This is a simplified approach - in production, use proper ASN.1 encoding
+        const pkcs8Header = Buffer.from([
+            0x30,
+            0x2e, // SEQUENCE, length 46
+            0x02,
+            0x01,
+            0x00, // INTEGER version 0
+            0x30,
+            0x05, // SEQUENCE, length 5
+            0x06,
+            0x03,
+            0x2b,
+            0x65,
+            0x70, // OID for Ed25519
+            0x04,
+            0x22, // OCTET STRING, length 34
+            0x04,
+            0x20, // OCTET STRING, length 32 (the actual key)
+        ]);
+        const fullKey = Buffer.concat([pkcs8Header, keyData.subarray(0, 32)]);
+        const base64Key = fullKey.toString("base64");
+        // Format as PEM with line breaks every 64 characters
+        const formattedKey = base64Key.match(/.{1,64}/g)?.join("\n") || base64Key;
+        return header + formattedKey + footer;
+    }
+    /**
+     * Verify a detached proof (for testing/validation)
+     */
+    async verifyProof(proof, request, response) {
+        try {
+            // Regenerate hashes
+            const expectedHashes = this.generateCanonicalHashes(request, response);
+            // Check if hashes match
+            if (proof.meta.requestHash !== expectedHashes.requestHash ||
+                proof.meta.responseHash !== expectedHashes.responseHash) {
+                return false;
+            }
+            // TODO: Verify JWS signature (requires public key)
+            // For now, just validate the structure
+            const jwsParts = proof.jws.split(".");
+            return jwsParts.length === 3 && jwsParts[1] === ""; // Detached format
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.ProofGenerator = ProofGenerator;
+/**
+ * Utility functions
+ */
+/**
+ * Create a tool response with proof
+ */
+async function createProofResponse(request, data, identity, session, options = {}) {
+    const response = { data };
+    const proofGenerator = new ProofGenerator(identity);
+    const proof = await proofGenerator.generateProof(request, response, session, options);
+    response.meta = { proof };
+    return response;
+}
+/**
+ * Extract canonical data for hashing (utility for testing)
+ */
+function extractCanonicalData(request, response) {
+    return {
+        request: {
+            method: request.method,
+            ...(request.params && { params: request.params }),
+        },
+        response: response.data,
+    };
+}

package/dist/runtime/session.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Handshake and Session Management for XMCP-I Runtime
+ *
+ * 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;
+}
+/**
+ * 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);
+    /**
+     * 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
+     */
+    private generateSessionId;
+    /**
+     * 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;
+}
+/**
+ * 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

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Handshake and Session Management for XMCP-I Runtime
+ *
+ * Handles handshake enforcement, session management, and nonce validation
+ * according to requirements 4.5-4.9 and 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
+        if (this.config.nonceCache instanceof memory_nonce_cache_1.MemoryNonceCache) {
+            console.warn("Warning: Using MemoryNonceCache - not suitable for multi-instance deployments. " +
+                "Consider using Redis, DynamoDB, or Cloudflare KV for production.");
+        }
+    }
+    /**
+     * 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);
+            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);
+            // Generate session ID
+            const sessionId = this.generateSessionId();
+            // Create session context
+            const session = {
+                sessionId,
+                audience: request.audience,
+                nonce: request.nonce,
+                timestamp: request.timestamp,
+                createdAt: now,
+                lastActivity: now,
+                ttlMinutes: this.config.sessionTtlMinutes,
+            };
+            // 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
+     */
+    generateSessionId() {
+        const timestamp = Date.now().toString(36);
+        const random = (0, crypto_1.randomBytes)(8).toString("hex");
+        return `sess_${timestamp}_${random}`;
+    }
+    /**
+     * 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);
+            }
+        }
+        // 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));
+}