@kya-os/mcp-i
Version:
The TypeScript MCP framework with identity features built-in
108 lines (107 loc) • 2.81 kB
TypeScript
/**
* 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;
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
*/
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;
}
/**
* 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;