@mcp-i/core 0.1.0

package/src/session/__tests__/session-manager.test.ts

@@ -0,0 +1,342 @@
+/**
+ * Session Manager Tests — @mcp-i/core
+ *
+ * Verifies platform-agnostic SessionManager behaviour:
+ * - Nonce format identical to existing implementation
+ * - TTL / expiry behaviour unchanged
+ * - getSession returns correct session by ID
+ * - validateHandshake behaviour unchanged
+ *
+ * NodeCryptoProvider is injected (test environment is Node.js).
+ */
+
+import { describe, it, expect, beforeEach } from "vitest";
+import { SessionManager, createHandshakeRequest, validateHandshakeFormat } from "../manager.js";
+import type { SessionConfig } from "../manager.js";
+import type { HandshakeRequest } from "../../types/protocol.js";
+
+// NodeCryptoProvider for test environment (Node.js)
+import { NodeCryptoProvider } from "../../__tests__/utils/node-crypto-provider.js";
+
+const cryptoProvider = new NodeCryptoProvider();
+
+function makeSessionManager(config: SessionConfig = {}): SessionManager {
+  return new SessionManager(cryptoProvider, config);
+}
+
+function makeRequest(overrides: Partial<HandshakeRequest> = {}): HandshakeRequest {
+  return {
+    nonce: SessionManager.generateNonce(),
+    audience: "example.com",
+    timestamp: Math.floor(Date.now() / 1000),
+    agentDid: "did:key:zAgent",
+    ...overrides,
+  };
+}
+
+describe("SessionManager", () => {
+  let manager: SessionManager;
+
+  beforeEach(() => {
+    manager = makeSessionManager();
+  });
+
+  describe("Nonce format", () => {
+    it("should generate nonce as base64url string", () => {
+      const nonce = SessionManager.generateNonce();
+      expect(typeof nonce).toBe("string");
+      expect(nonce.length).toBeGreaterThan(0);
+      // base64url uses A-Z a-z 0-9 - _ (no padding)
+      expect(nonce).toMatch(/^[A-Za-z0-9_-]+$/);
+    });
+
+    it("should generate unique nonces", () => {
+      const nonces = new Set(Array.from({ length: 20 }, () => SessionManager.generateNonce()));
+      expect(nonces.size).toBe(20);
+    });
+
+    it("should generate nonces of consistent entropy (16-byte = ~22 base64url chars)", () => {
+      const nonce = SessionManager.generateNonce();
+      // 16 bytes base64url → ceil(16 * 4/3) = 22 chars (no padding)
+      expect(nonce.length).toBeGreaterThanOrEqual(20);
+      expect(nonce.length).toBeLessThanOrEqual(24);
+    });
+  });
+
+  describe("Handshake validation", () => {
+    it("should create a valid session on correct handshake", async () => {
+      const request = makeRequest();
+      const result = await manager.validateHandshake(request);
+
+      expect(result.success).toBe(true);
+      expect(result.session).toBeDefined();
+      expect(result.session?.audience).toBe(request.audience);
+      expect(result.session?.nonce).toBe(request.nonce);
+      expect(result.session?.identityState).toBe("anonymous");
+    });
+
+    it("should return session ID with mcpi_ prefix", async () => {
+      const request = makeRequest();
+      const result = await manager.validateHandshake(request);
+
+      expect(result.session?.sessionId).toMatch(/^mcpi_/);
+    });
+
+    it("should reject request with stale timestamp", async () => {
+      const staleTs = Math.floor(Date.now() / 1000) - 200; // 200s ago, skew is 120s
+      const request = makeRequest({ timestamp: staleTs });
+      const result = await manager.validateHandshake(request);
+
+      expect(result.success).toBe(false);
+      expect(result.error?.code).toBe("XMCP_I_EHANDSHAKE");
+    });
+
+    it("should accept request within timestamp skew", async () => {
+      const slightlyOldTs = Math.floor(Date.now() / 1000) - 60; // 60s ago, within 120s default
+      const request = makeRequest({ timestamp: slightlyOldTs });
+      const result = await manager.validateHandshake(request);
+
+      expect(result.success).toBe(true);
+    });
+
+    it("should reject replayed nonce", async () => {
+      const request = makeRequest();
+      await manager.validateHandshake(request);
+
+      // Same request again (same nonce)
+      const second = await manager.validateHandshake(request);
+      expect(second.success).toBe(false);
+      expect(second.error?.code).toBe("XMCP_I_EHANDSHAKE");
+    });
+
+    it("should accept different nonces in succession", async () => {
+      const r1 = makeRequest();
+      const r2 = makeRequest(); // fresh nonce
+
+      const res1 = await manager.validateHandshake(r1);
+      const res2 = await manager.validateHandshake(r2);
+
+      expect(res1.success).toBe(true);
+      expect(res2.success).toBe(true);
+    });
+  });
+
+  describe("Session lookup — getSession", () => {
+    it("should return session by ID after handshake", async () => {
+      const request = makeRequest();
+      const { session } = await manager.validateHandshake(request);
+      expect(session).toBeDefined();
+
+      const found = await manager.getSession(session!.sessionId);
+      expect(found).toBeDefined();
+      expect(found?.sessionId).toBe(session!.sessionId);
+    });
+
+    it("should return null for unknown session ID", async () => {
+      const found = await manager.getSession("mcpi_does-not-exist");
+      expect(found).toBeNull();
+    });
+
+    it("should update lastActivity on each getSession call", async () => {
+      const request = makeRequest();
+      const { session } = await manager.validateHandshake(request);
+
+      const before = session!.lastActivity;
+      // Artificially advance lastActivity to simulate time passing
+      await new Promise((r) => setTimeout(r, 10));
+      const found = await manager.getSession(session!.sessionId);
+
+      // lastActivity should be updated (>= before)
+      expect(found!.lastActivity).toBeGreaterThanOrEqual(before);
+    });
+  });
+
+  describe("Session expiry — TTL behaviour", () => {
+    it("should expire idle sessions after TTL", async () => {
+      // Use 1-minute TTL but manually manipulate lastActivity
+      const sm = makeSessionManager({ sessionTtlMinutes: 1 });
+      const request = makeRequest();
+      const { session } = await sm.validateHandshake(request);
+      expect(session).toBeDefined();
+
+      // Backdate lastActivity beyond TTL (simulate 70s of idle)
+      session!.lastActivity = Math.floor(Date.now() / 1000) - 70;
+      // Directly set in sessions map via cleanup
+      await sm.cleanup();
+
+      const found = await sm.getSession(session!.sessionId);
+      expect(found).toBeNull();
+    });
+
+    it("should not expire active sessions within TTL", async () => {
+      const sm = makeSessionManager({ sessionTtlMinutes: 30 });
+      const request = makeRequest();
+      const { session } = await sm.validateHandshake(request);
+      expect(session).toBeDefined();
+
+      const found = await sm.getSession(session!.sessionId);
+      expect(found).not.toBeNull();
+    });
+
+    it("should expire sessions beyond absolute lifetime", async () => {
+      const sm = makeSessionManager({ absoluteSessionLifetime: 1 });
+      const request = makeRequest();
+      const { session } = await sm.validateHandshake(request);
+      expect(session).toBeDefined();
+
+      // Backdate createdAt beyond 1-minute absolute lifetime
+      session!.createdAt = Math.floor(Date.now() / 1000) - 65;
+      await sm.cleanup();
+
+      const found = await sm.getSession(session!.sessionId);
+      expect(found).toBeNull();
+    });
+  });
+
+  describe("Custom timestamp skew", () => {
+    it("should use custom timestampSkewSeconds when provided", async () => {
+      const sm = makeSessionManager({ timestampSkewSeconds: 30 });
+
+      // 40s stale — should fail with 30s skew
+      const staleRequest = makeRequest({
+        timestamp: Math.floor(Date.now() / 1000) - 40,
+      });
+      const result = await sm.validateHandshake(staleRequest);
+
+      expect(result.success).toBe(false);
+    });
+
+    it("should accept request within custom skew", async () => {
+      const sm = makeSessionManager({ timestampSkewSeconds: 60 });
+
+      // 50s stale — should pass with 60s skew
+      const request = makeRequest({
+        timestamp: Math.floor(Date.now() / 1000) - 50,
+      });
+      const result = await sm.validateHandshake(request);
+
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe("getStats", () => {
+    it("should report zero active sessions initially", () => {
+      const stats = manager.getStats();
+      expect(stats.activeSessions).toBe(0);
+    });
+
+    it("should report correct count after handshakes", async () => {
+      await manager.validateHandshake(makeRequest());
+      await manager.validateHandshake(makeRequest());
+
+      const stats = manager.getStats();
+      expect(stats.activeSessions).toBe(2);
+    });
+  });
+
+  describe("clearSessions", () => {
+    it("should clear all sessions", async () => {
+      await manager.validateHandshake(makeRequest());
+      manager.clearSessions();
+
+      const stats = manager.getStats();
+      expect(stats.activeSessions).toBe(0);
+    });
+  });
+
+  describe("setServerDid", () => {
+    it("should include serverDid in session when set", async () => {
+      manager.setServerDid("did:web:example.com:server");
+      const request = makeRequest({ audience: "did:web:example.com:server" });
+      const { session } = await manager.validateHandshake(request);
+
+      expect(session?.serverDid).toBe("did:web:example.com:server");
+    });
+  });
+
+  describe("Audience validation", () => {
+    it("should reject handshake when audience doesn't match serverDid", async () => {
+      const sm = makeSessionManager({ serverDid: "did:web:example.com:server" });
+      const request = makeRequest({ audience: "did:web:other.com:server" });
+      const result = await sm.validateHandshake(request);
+
+      expect(result.success).toBe(false);
+      expect(result.error?.code).toBe("MCPI_AUDIENCE_MISMATCH");
+      expect(result.error?.message).toContain("Audience mismatch");
+    });
+
+    it("should accept handshake when audience matches serverDid", async () => {
+      const sm = makeSessionManager({ serverDid: "did:web:example.com:server" });
+      const request = makeRequest({ audience: "did:web:example.com:server" });
+      const result = await sm.validateHandshake(request);
+
+      expect(result.success).toBe(true);
+      expect(result.session?.audience).toBe("did:web:example.com:server");
+    });
+
+    it("should accept handshake when serverDid is not configured (backward compat)", async () => {
+      const sm = makeSessionManager(); // No serverDid configured
+      const request = makeRequest({ audience: "any-audience" });
+      const result = await sm.validateHandshake(request);
+
+      expect(result.success).toBe(true);
+    });
+  });
+});
+
+describe("createHandshakeRequest", () => {
+  it("should create a valid handshake request for an audience", () => {
+    const req = createHandshakeRequest("example.com");
+
+    expect(req.audience).toBe("example.com");
+    expect(typeof req.nonce).toBe("string");
+    expect(req.nonce.length).toBeGreaterThan(0);
+    expect(typeof req.timestamp).toBe("number");
+    expect(req.timestamp).toBeGreaterThan(0);
+  });
+
+  it("should generate unique nonces across calls", () => {
+    const nonces = new Set(
+      Array.from({ length: 20 }, () => createHandshakeRequest("test.com").nonce)
+    );
+    expect(nonces.size).toBe(20);
+  });
+
+  it("should use current timestamp", () => {
+    const before = Math.floor(Date.now() / 1000);
+    const req = createHandshakeRequest("test.com");
+    const after = Math.floor(Date.now() / 1000);
+
+    expect(req.timestamp).toBeGreaterThanOrEqual(before);
+    expect(req.timestamp).toBeLessThanOrEqual(after);
+  });
+});
+
+describe("validateHandshakeFormat", () => {
+  it("should return true for a valid request", () => {
+    const req = createHandshakeRequest("example.com");
+    expect(validateHandshakeFormat(req)).toBe(true);
+  });
+
+  it("should return false for missing nonce", () => {
+    expect(validateHandshakeFormat({ audience: "x", timestamp: 1 })).toBe(false);
+  });
+
+  it("should return false for empty nonce", () => {
+    expect(validateHandshakeFormat({ nonce: "", audience: "x", timestamp: 1 })).toBe(false);
+  });
+
+  it("should return false for missing audience", () => {
+    expect(validateHandshakeFormat({ nonce: "abc", timestamp: 1 })).toBe(false);
+  });
+
+  it("should return false for non-integer timestamp", () => {
+    expect(validateHandshakeFormat({ nonce: "abc", audience: "x", timestamp: 1.5 })).toBe(false);
+  });
+
+  it("should return false for non-object", () => {
+    expect(validateHandshakeFormat(null)).toBe(false);
+    expect(validateHandshakeFormat("string")).toBe(false);
+    expect(validateHandshakeFormat(42)).toBe(false);
+  });
+});

package/src/session/index.ts

@@ -0,0 +1,7 @@
+export {
+  SessionManager,
+  createHandshakeRequest,
+  validateHandshakeFormat,
+  type SessionConfig,
+  type HandshakeResult,
+} from './manager.js';

package/src/session/manager.ts

@@ -0,0 +1,332 @@
+/**
+ * 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 type {
+  HandshakeRequest,
+  SessionContext,
+  NonceCache,
+} from '../types/protocol.js';
+import type { CryptoProvider } from '../providers/base.js';
+import { MemoryNonceCacheProvider } from '../providers/memory.js';
+import { logger } from '../logging/index.js';
+
+export interface SessionConfig {
+  timestampSkewSeconds?: number;
+  sessionTtlMinutes?: number;
+  absoluteSessionLifetime?: number;
+  nonceCache?: NonceCache;
+  serverDid?: string;
+}
+
+export interface HandshakeResult {
+  success: boolean;
+  session?: SessionContext;
+  error?: {
+    code: string;
+    message: string;
+    remediation?: string;
+  };
+}
+
+export class SessionManager {
+  private config: Required<Omit<SessionConfig, 'absoluteSessionLifetime' | 'serverDid'>> & {
+    absoluteSessionLifetime?: number;
+    serverDid?: string;
+  };
+  private cryptoProvider: CryptoProvider;
+  private sessions = new Map<string, SessionContext>();
+
+  constructor(cryptoProvider: CryptoProvider, config: SessionConfig = {}) {
+    this.cryptoProvider = cryptoProvider;
+    this.config = {
+      timestampSkewSeconds: config.timestampSkewSeconds ?? 120,
+      sessionTtlMinutes: config.sessionTtlMinutes ?? 30,
+      nonceCache: config.nonceCache ?? new MemoryNonceCacheProvider(),
+      ...(config.absoluteSessionLifetime !== undefined && {
+        absoluteSessionLifetime: config.absoluteSessionLifetime,
+      }),
+      ...(config.serverDid !== undefined && { serverDid: config.serverDid }),
+    };
+
+    if (this.config.nonceCache instanceof MemoryNonceCacheProvider) {
+      logger.warn(
+        '[SessionManager] Using MemoryNonceCacheProvider — not suitable for ' +
+          'multi-instance deployments. Use Redis, DynamoDB, or Cloudflare KV ' +
+          'for production.'
+      );
+    }
+  }
+
+  setServerDid(serverDid: string): void {
+    this.config.serverDid = serverDid;
+  }
+
+  /**
+   * Validate an MCP-I handshake request and create a session.
+   *
+   * Performs the following checks:
+   * - Timestamp within acceptable skew window
+   * - Audience matches server DID (if configured)
+   * - Nonce not previously used (replay protection)
+   *
+   * @param request - The handshake request containing nonce, audience, timestamp, and optional agentDid
+   * @returns Result object with success flag, session on success, or error details on failure
+   */
+  async validateHandshake(request: HandshakeRequest): Promise<HandshakeResult> {
+    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.`,
+          },
+        };
+      }
+
+      // Validate audience matches this server's DID (SPEC.md §4 MUST)
+      if (this.config.serverDid && request.audience !== this.config.serverDid) {
+        return {
+          success: false,
+          error: {
+            code: 'MCPI_AUDIENCE_MISMATCH',
+            message: `Audience mismatch: expected ${this.config.serverDid}, got ${request.audience}`,
+          },
+        };
+      }
+
+      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: SessionContext = {
+        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'}`,
+        },
+      };
+    }
+  }
+
+  /**
+   * Retrieve a session by ID, checking for expiration.
+   *
+   * Updates lastActivity timestamp on successful retrieval (sliding window expiry).
+   * Returns null if session doesn't exist, has exceeded idle TTL, or has exceeded
+   * absolute lifetime (if configured).
+   *
+   * @param sessionId - The session ID (e.g., "mcpi_...")
+   * @returns Session context if valid, null if expired or not found
+   */
+  async getSession(sessionId: string): Promise<SessionContext | null> {
+    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;
+  }
+
+  private async generateSessionId(): Promise<string> {
+    const bytes = await this.cryptoProvider.randomBytes(16);
+    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}`;
+  }
+
+  private async generateClientId(): Promise<string> {
+    const bytes = await this.cryptoProvider.randomBytes(6);
+    const hex = Array.from(bytes)
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('');
+    return `client_${hex}`;
+  }
+
+  private normalizeClientInfoString(value: unknown): string | undefined {
+    if (typeof value !== 'string') return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  }
+
+  private async buildClientInfo(
+    request: HandshakeRequest
+  ): Promise<SessionContext['clientInfo'] | undefined> {
+    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,
+    };
+  }
+
+  static generateNonce(): string {
+    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, '');
+  }
+
+  async cleanup(): Promise<void> {
+    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();
+  }
+
+  getStats(): {
+    activeSessions: number;
+    config: {
+      timestampSkewSeconds: number;
+      sessionTtlMinutes: number;
+      absoluteSessionLifetime?: number;
+      cacheType: string;
+    };
+  } {
+    return {
+      activeSessions: this.sessions.size,
+      config: {
+        timestampSkewSeconds: this.config.timestampSkewSeconds,
+        sessionTtlMinutes: this.config.sessionTtlMinutes,
+        absoluteSessionLifetime: this.config.absoluteSessionLifetime,
+        cacheType: this.config.nonceCache.constructor.name,
+      },
+    };
+  }
+
+  clearSessions(): void {
+    this.sessions.clear();
+  }
+}
+
+export function createHandshakeRequest(audience: string): HandshakeRequest {
+  return {
+    nonce: SessionManager.generateNonce(),
+    audience,
+    timestamp: Math.floor(Date.now() / 1000),
+  };
+}
+
+export function validateHandshakeFormat(request: unknown): request is HandshakeRequest {
+  return (
+    typeof request === 'object' &&
+    request !== null &&
+    typeof (request as Record<string, unknown>)['nonce'] === 'string' &&
+    ((request as Record<string, unknown>)['nonce'] as string).length > 0 &&
+    typeof (request as Record<string, unknown>)['audience'] === 'string' &&
+    ((request as Record<string, unknown>)['audience'] as string).length > 0 &&
+    typeof (request as Record<string, unknown>)['timestamp'] === 'number' &&
+    ((request as Record<string, unknown>)['timestamp'] as number) > 0 &&
+    Number.isInteger((request as Record<string, unknown>)['timestamp'])
+  );
+}