@mcp-i/core 0.1.0 → 1.1.0-canary.1

package/src/__tests__/integration/mcp-transport.test.ts

@@ -0,0 +1,390 @@
+/**
+ * End-to-End MCP Transport Integration Test
+ *
+ * Exercises the MCP-I middleware through a real MCP SDK Client→Server
+ * transport (InMemoryTransport). Unlike unit tests that call handlers
+ * directly, these tests go through full JSON-RPC serialization and
+ * MCP protocol framing.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { createMCPIMiddleware } from '../../middleware/with-mcpi.js';
+import { NodeCryptoProvider } from '../utils/node-crypto-provider.js';
+import { generateDidKeyFromBase64 } from '../../utils/did-helpers.js';
+import { DelegationCredentialIssuer } from '../../delegation/vc-issuer.js';
+import { ProofVerifier } from '../../proof/verifier.js';
+import { MemoryNonceCacheProvider } from '../../providers/memory.js';
+import { ClockProvider, FetchProvider } from '../../providers/base.js';
+import {
+  createDidKeyResolver,
+  extractPublicKeyFromDidKey,
+  publicKeyToJwk,
+} from '../../delegation/did-key-resolver.js';
+import { base64urlEncodeFromBytes } from '../../utils/base64.js';
+import type {
+  DelegationCredential,
+  DIDDocument,
+  StatusList2021Credential,
+  DelegationRecord,
+  Proof,
+} from '../../types/protocol.js';
+
+// ── Test providers for ProofVerifier ──────────────────────────────
+
+class TestClockProvider extends ClockProvider {
+  now(): number { return Date.now(); }
+  isWithinSkew(timestampMs: number, skewSeconds: number): boolean {
+    return Math.abs(Date.now() - timestampMs) <= skewSeconds * 1000;
+  }
+  hasExpired(expiresAt: number): boolean { return Date.now() > expiresAt; }
+  calculateExpiry(ttlSeconds: number): number { return Date.now() + ttlSeconds * 1000; }
+  format(timestamp: number): string { return new Date(timestamp).toISOString(); }
+}
+
+class TestFetchProvider extends FetchProvider {
+  private didResolver = createDidKeyResolver();
+  async resolveDID(did: string): Promise<DIDDocument | null> {
+    return this.didResolver.resolve(did);
+  }
+  async fetchStatusList(): Promise<StatusList2021Credential | null> { return null; }
+  async fetchDelegationChain(): Promise<DelegationRecord[]> { return []; }
+  async fetch(): Promise<Response> { throw new Error('Not implemented'); }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+async function setupMcpPair(options?: { autoSession?: boolean }) {
+  const crypto = new NodeCryptoProvider();
+  const keyPair = await crypto.generateKeyPair();
+  const did = generateDidKeyFromBase64(keyPair.publicKey);
+  const kid = `${did}#keys-1`;
+
+  const mcpi = createMCPIMiddleware(
+    {
+      identity: { did, kid, privateKey: keyPair.privateKey, publicKey: keyPair.publicKey },
+      session: { sessionTtlMinutes: 60 },
+      autoSession: options?.autoSession,
+    },
+    crypto,
+  );
+
+  // ── Tool handlers (mirrors examples/node-server/server.ts) ──
+
+  const greetHandler = mcpi.wrapWithProof('greet', async (args) => ({
+    content: [{ type: 'text', text: `Hello, ${args['name'] ?? 'world'}!` }],
+  }));
+
+  const restrictedGreetHandler = mcpi.wrapWithDelegation(
+    'restricted_greet',
+    {
+      scopeId: 'greeting:restricted',
+      consentUrl: 'https://example.com/consent?scope=greeting:restricted',
+    },
+    mcpi.wrapWithProof('restricted_greet', async (args) => ({
+      content: [{ type: 'text', text: `Hello, ${args['name'] ?? 'world'}! (delegation verified)` }],
+    })),
+  );
+
+  // ── MCP Server ──
+
+  const server = new Server(
+    { name: 'mcpi-transport-test', version: '1.0.0' },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      mcpi.handshakeTool,
+      {
+        name: 'greet',
+        description: 'Returns a greeting with proof',
+        inputSchema: {
+          type: 'object' as const,
+          properties: { name: { type: 'string' } },
+        },
+      },
+      {
+        name: 'restricted_greet',
+        description: 'Protected greeting requiring delegation',
+        inputSchema: {
+          type: 'object' as const,
+          properties: {
+            name: { type: 'string' },
+            _mcpi_delegation: { type: 'object' },
+          },
+        },
+      },
+    ],
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+
+    if (name === '_mcpi_handshake') {
+      return mcpi.handleHandshake(args as Record<string, unknown>);
+    }
+    if (name === 'greet') {
+      return greetHandler(args as Record<string, unknown>);
+    }
+    if (name === 'restricted_greet') {
+      return restrictedGreetHandler(args as Record<string, unknown>);
+    }
+
+    return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+  });
+
+  // ── Client + transport ──
+
+  const client = new Client(
+    { name: 'mcpi-transport-test-client', version: '1.0.0' },
+  );
+
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  await server.connect(serverTransport);
+  await client.connect(clientTransport);
+
+  return { client, server, did, kid, keyPair, crypto };
+}
+
+async function issueDelegationVC(scopes: string[]): Promise<DelegationCredential> {
+  const crypto = new NodeCryptoProvider();
+  const keyPair = await crypto.generateKeyPair();
+  const did = generateDidKeyFromBase64(keyPair.publicKey);
+  const kid = `${did}#keys-1`;
+
+  const signingFn = async (
+    canonicalVC: string,
+    _issuerDid: string,
+    kidArg: string,
+  ): Promise<Proof> => {
+    const data = new TextEncoder().encode(canonicalVC);
+    const sigBytes = await crypto.sign(data, keyPair.privateKey);
+    const proofValue = base64urlEncodeFromBytes(sigBytes);
+    return {
+      type: 'Ed25519Signature2020',
+      created: new Date().toISOString(),
+      verificationMethod: kidArg,
+      proofPurpose: 'assertionMethod',
+      proofValue,
+    };
+  };
+
+  const issuer = new DelegationCredentialIssuer(
+    { getDid: () => did, getKeyId: () => kid, getPrivateKey: () => keyPair.privateKey },
+    signingFn,
+  );
+
+  return issuer.createAndIssueDelegation({
+    id: `test-delegation-${Date.now()}-${Math.random().toString(16).slice(2)}`,
+    issuerDid: did,
+    subjectDid: did,
+    constraints: {
+      scopes,
+      notAfter: Math.floor(Date.now() / 1000) + 3600,
+    },
+  });
+}
+
+// ── Tests ──────────────────────────────────────────────────────
+
+describe('MCP Transport Integration', () => {
+  const pairs: Array<{ client: Client; server: Server }> = [];
+
+  afterEach(async () => {
+    for (const pair of pairs) {
+      await pair.client.close();
+      await pair.server.close();
+    }
+    pairs.length = 0;
+  });
+
+  async function createPair(options?: { autoSession?: boolean }) {
+    const pair = await setupMcpPair(options);
+    pairs.push(pair);
+    return pair;
+  }
+
+  it('listTools returns handshake + app tools', async () => {
+    const { client } = await createPair();
+
+    const result = await client.listTools();
+    const toolNames = result.tools.map((t) => t.name);
+
+    expect(toolNames).toHaveLength(3);
+    expect(toolNames).toContain('_mcpi_handshake');
+    expect(toolNames).toContain('greet');
+    expect(toolNames).toContain('restricted_greet');
+  });
+
+  it('handshake establishes session via MCP transport', async () => {
+    const { client, did } = await createPair();
+
+    const result = await client.callTool({
+      name: '_mcpi_handshake',
+      arguments: {
+        nonce: `transport-test-${Date.now()}`,
+        audience: did,
+        timestamp: Math.floor(Date.now() / 1000),
+      },
+    });
+
+    expect(result.content).toHaveLength(1);
+    const first = result.content[0] as { type: string; text: string };
+    expect(first.type).toBe('text');
+
+    const parsed = JSON.parse(first.text);
+    expect(parsed.success).toBe(true);
+    expect(parsed.sessionId).toMatch(/^mcpi_/);
+    expect(parsed.serverDid).toBe(did);
+  });
+
+  it('greet returns proof in _meta after handshake', async () => {
+    const { client, did } = await createPair();
+
+    // Handshake first
+    await client.callTool({
+      name: '_mcpi_handshake',
+      arguments: {
+        nonce: `transport-test-${Date.now()}`,
+        audience: did,
+        timestamp: Math.floor(Date.now() / 1000),
+      },
+    });
+
+    // Call greet
+    const result = await client.callTool({
+      name: 'greet',
+      arguments: { name: 'MCP-I' },
+    });
+
+    // Verify tool output
+    const first = result.content[0] as { type: string; text: string };
+    expect(first.text).toBe('Hello, MCP-I!');
+
+    // Verify proof in _meta (top-level on the result)
+    expect(result._meta).toBeDefined();
+    const proof = (result._meta as Record<string, unknown>).proof as {
+      jws: string;
+      meta: Record<string, unknown>;
+    };
+    expect(proof).toBeDefined();
+    expect(proof.jws).toBeDefined();
+    expect(proof.meta.did).toMatch(/^did:key:/);
+    expect(proof.meta.sessionId).toMatch(/^mcpi_/);
+    expect(proof.meta.requestHash).toMatch(/^sha256:[a-f0-9]{64}$/);
+    expect(proof.meta.responseHash).toMatch(/^sha256:[a-f0-9]{64}$/);
+  });
+
+  it('proof from greet verifies cryptographically', async () => {
+    const { client, did, kid } = await createPair();
+
+    // Handshake
+    await client.callTool({
+      name: '_mcpi_handshake',
+      arguments: {
+        nonce: `transport-test-${Date.now()}`,
+        audience: did,
+        timestamp: Math.floor(Date.now() / 1000),
+      },
+    });
+
+    // Call greet
+    const result = await client.callTool({
+      name: 'greet',
+      arguments: { name: 'Verifier' },
+    });
+
+    const proof = (result._meta as Record<string, unknown>).proof as {
+      jws: string;
+      meta: Record<string, unknown>;
+    };
+
+    // Resolve server's public key from did:key
+    const publicKeyBytes = extractPublicKeyFromDidKey(did);
+    expect(publicKeyBytes).not.toBeNull();
+    const publicKeyJwk = publicKeyToJwk(publicKeyBytes!);
+
+    // Create verifier and verify
+    const crypto = new NodeCryptoProvider();
+    const verifier = new ProofVerifier({
+      cryptoProvider: crypto,
+      clockProvider: new TestClockProvider(),
+      nonceCacheProvider: new MemoryNonceCacheProvider(),
+      fetchProvider: new TestFetchProvider(),
+      timestampSkewSeconds: 300,
+    });
+
+    const jwkWithKid = { ...publicKeyJwk, kid };
+    const verificationResult = await verifier.verifyProof(proof as any, jwkWithKid as any);
+    expect(verificationResult.valid).toBe(true);
+  });
+
+  it('autoSession attaches proof without handshake', async () => {
+    const { client } = await createPair({ autoSession: true });
+
+    // Call greet directly — no handshake
+    const result = await client.callTool({
+      name: 'greet',
+      arguments: { name: 'Auto' },
+    });
+
+    const first = result.content[0] as { type: string; text: string };
+    expect(first.text).toBe('Hello, Auto!');
+
+    // Proof should be present via auto-session
+    expect(result._meta).toBeDefined();
+    const proof = (result._meta as Record<string, unknown>).proof as {
+      jws: string;
+      meta: Record<string, unknown>;
+    };
+    expect(proof).toBeDefined();
+    expect(proof.jws).toBeDefined();
+    expect(proof.meta.sessionId).toMatch(/^mcpi_/);
+  });
+
+  it('restricted_greet without delegation returns needs_authorization', async () => {
+    const { client } = await createPair();
+
+    const result = await client.callTool({
+      name: 'restricted_greet',
+      arguments: { name: 'Unauthorized' },
+    });
+
+    const first = result.content[0] as { type: string; text: string };
+    const parsed = JSON.parse(first.text);
+    expect(parsed.error).toBe('needs_authorization');
+    expect(parsed.authorizationUrl).toContain('consent');
+    expect(parsed.scopes).toContain('greeting:restricted');
+    expect(parsed.resumeToken).toBeDefined();
+  });
+
+  it('restricted_greet with valid delegation VC returns greeting with proof', async () => {
+    const { client, did } = await createPair({ autoSession: true });
+
+    const vc = await issueDelegationVC(['greeting:restricted']);
+
+    const result = await client.callTool({
+      name: 'restricted_greet',
+      arguments: { name: 'DIF', _mcpi_delegation: vc },
+    });
+
+    const first = result.content[0] as { type: string; text: string };
+    expect(first.text).toBe('Hello, DIF! (delegation verified)');
+
+    // Proof from inner wrapWithProof
+    expect(result._meta).toBeDefined();
+    const proof = (result._meta as Record<string, unknown>).proof as {
+      jws: string;
+      meta: Record<string, unknown>;
+    };
+    expect(proof).toBeDefined();
+    expect(proof.jws).toBeDefined();
+  });
+});

package/src/index.ts

@@ -246,6 +246,9 @@ export {
   type MCPIToolDefinition,
   type MCPIToolHandler,
   type MCPIServer,
+  withMCPI,
+  generateIdentity,
+  type WithMCPIOptions,
 } from './middleware/index.js';
 
 // Logging

package/src/middleware/index.ts

@@ -1,7 +1,10 @@
 /**
  * MCP-I Middleware
  *
- * Provides identity-aware middleware for @modelcontextprotocol/sdk Server.
+ * Primary entry point: `withMCPI(server, { crypto })` — adds identity,
+ * handshake, and auto-proofs to any McpServer instance in one call.
+ *
+ * For the low-level `Server` API or custom patterns, use `createMCPIMiddleware` directly.
  */
 
 export {
@@ -14,3 +17,9 @@ export {
   type MCPIToolHandler,
   type MCPIServer,
 } from './with-mcpi.js';
+
+export {
+  withMCPI,
+  generateIdentity,
+  type WithMCPIOptions,
+} from './with-mcpi-server.js';

package/src/middleware/with-mcpi-server.ts

@@ -0,0 +1,185 @@
+/**
+ * McpServer Adapter for MCP-I
+ *
+ * Adds MCP-I identity, session management, and proof generation to a
+ * standard McpServer instance with a single function call.
+ *
+ * Usage:
+ *   import { withMCPI } from '@mcp-i/core/middleware';
+ *   const mcpi = await withMCPI(server, { crypto: new NodeCryptoProvider() });
+ *   // All tools registered on `server` now get proofs automatically.
+ */
+
+import type { CryptoProvider } from "../providers/base.js";
+import { generateDidKeyFromBase64 } from "../utils/did-helpers.js";
+import {
+  createMCPIMiddleware,
+  type MCPIIdentityConfig,
+  type MCPIDelegationConfig,
+  type MCPIMiddleware,
+} from "./with-mcpi.js";
+import { z } from "zod";
+
+export interface WithMCPIOptions {
+  /** Platform-specific crypto implementation (required) */
+  crypto: CryptoProvider;
+  /** Identity config — auto-generated if omitted */
+  identity?: MCPIIdentityConfig;
+  /** Session configuration */
+  session?: { sessionTtlMinutes?: number };
+  /** Auto-create sessions for non-MCP-I clients (default: true) */
+  autoSession?: boolean;
+  /** Attach proofs to all tool responses (default: true) */
+  proofAllTools?: boolean;
+  /** Tools to skip proof generation for */
+  excludeTools?: string[];
+  /** Delegation verification config */
+  delegation?: MCPIDelegationConfig;
+}
+
+/**
+ * Generate a fresh Ed25519 identity for MCP-I.
+ *
+ * @param crypto - Platform-specific crypto provider
+ * @returns Identity config with DID, kid, and key material
+ */
+export async function generateIdentity(
+  crypto: CryptoProvider,
+): Promise<MCPIIdentityConfig> {
+  const keyPair = await crypto.generateKeyPair();
+  const did = generateDidKeyFromBase64(keyPair.publicKey);
+  return {
+    did,
+    kid: `${did}#keys-1`,
+    privateKey: keyPair.privateKey,
+    publicKey: keyPair.publicKey,
+  };
+}
+
+/**
+ * McpServer type — minimal interface to avoid hard dependency on the SDK.
+ * Matches the public API of @modelcontextprotocol/sdk McpServer.
+ */
+interface McpServerLike {
+  server: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    [key: string]: any;
+  };
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  registerTool(...args: any[]): void;
+}
+
+/**
+ * Add MCP-I to a McpServer instance.
+ *
+ * 1. Auto-generates Ed25519 identity (or uses provided one)
+ * 2. Registers `_mcpi_handshake` tool
+ * 3. Intercepts the `tools/call` request handler to auto-attach proofs
+ *
+ * @param server - McpServer instance
+ * @param options - Configuration
+ * @returns The MCPIMiddleware instance for advanced usage (wrapWithDelegation, etc.)
+ */
+export async function withMCPI(
+  server: McpServerLike,
+  options: WithMCPIOptions,
+): Promise<MCPIMiddleware> {
+  const identity =
+    options.identity ?? (await generateIdentity(options.crypto));
+
+  const mcpi = createMCPIMiddleware(
+    {
+      identity,
+      session: options.session,
+      delegation: options.delegation,
+      autoSession: options.autoSession ?? true,
+    },
+    options.crypto,
+  );
+
+  // Register _mcpi_handshake tool
+  server.registerTool(
+    "_mcpi_handshake",
+    {
+      description:
+        "MCP-I identity handshake — establishes a cryptographic session",
+      inputSchema: {
+        nonce: z.string().describe("Client-generated unique nonce"),
+        audience: z
+          .string()
+          .describe("Intended audience (server DID or URL)"),
+        timestamp: z.number().describe("Unix epoch seconds"),
+      },
+    },
+    async (args: unknown) => {
+      const result = await mcpi.handleHandshake(args as Record<string, unknown>);
+      return {
+        ...result,
+        content: result.content.map((c) => ({ ...c, type: "text" as const })),
+      };
+    },
+  );
+
+  // Auto-proof interception: wrap the tools/call handler
+  const proofAllTools = options.proofAllTools ?? true;
+
+  if (proofAllTools) {
+    const lowLevel = server.server;
+    const handlers: Map<string, Function> =
+      lowLevel._requestHandlers;
+    const original = handlers.get("tools/call");
+
+    if (original) {
+      handlers.set(
+        "tools/call",
+        async (request: Record<string, unknown>, extra: unknown) => {
+          const result = (await (
+            original as (
+              req: Record<string, unknown>,
+              ext: unknown,
+            ) => Promise<Record<string, unknown>>
+          )(request, extra)) as {
+            content?: Array<{
+              type: string;
+              text: string;
+              [key: string]: unknown;
+            }>;
+            isError?: boolean;
+            _meta?: Record<string, unknown>;
+            [key: string]: unknown;
+          };
+
+          const params = request.params as
+            | { name?: string; arguments?: Record<string, unknown> }
+            | undefined;
+          const toolName = params?.name;
+
+          if (
+            !toolName ||
+            toolName === "_mcpi_handshake" ||
+            result.isError
+          ) {
+            return result;
+          }
+
+          if (options.excludeTools?.includes(toolName)) {
+            return result;
+          }
+
+          // Use wrapWithProof to add proof — it handles session management
+          const addProof = mcpi.wrapWithProof(
+            toolName,
+            async () => result as {
+              content: Array<{ type: string; text: string; [key: string]: unknown }>;
+              isError?: boolean;
+              [key: string]: unknown;
+            },
+          );
+          return addProof(params?.arguments ?? {});
+        },
+      );
+    }
+  }
+
+  return mcpi;
+}

package/src/middleware/with-mcpi.ts

@@ -1,13 +1,18 @@
 /**
- * MCP-I Middleware for @modelcontextprotocol/sdk Server
+ * MCP-I Middleware — Core Implementation
  *
- * Adds identity, session management, and proof generation to a standard
- * MCP SDK Server.
+ * Adds identity, session management, and proof generation to MCP servers.
  *
- * Usage:
- *   const { handshakeTool, registerToolWithProof } = createMCPIMiddleware(config, crypto);
- *   server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: [handshakeTool, ...] }));
- *   registerToolWithProof(server, myToolDef, myHandler);
+ * For most use cases, prefer the high-level `withMCPI()` adapter from
+ * `./with-mcpi-server.ts` which auto-registers the handshake tool and
+ * auto-attaches proofs to all tool responses:
+ *
+ *   import { withMCPI } from '@mcp-i/core';
+ *   await withMCPI(server, { crypto: new NodeCryptoProvider() });
+ *
+ * `createMCPIMiddleware()` in this file is the lower-level API used
+ * internally by `withMCPI()` and for advanced use cases like the
+ * low-level `Server` API or custom request handler patterns.
  */
 
 import {
@@ -115,9 +120,11 @@ export interface MCPIToolDefinition {
   };
 }
 
-export interface MCPIToolHandler {
+export interface MCPIToolHandler<
+  T extends Record<string, unknown> = Record<string, unknown>,
+> {
   (
-    args: Record<string, unknown>,
+    args: T,
     sessionId?: string,
   ): Promise<{
     content: Array<{ type: string; text: string; [key: string]: unknown }>;
@@ -138,6 +145,9 @@ export interface MCPIServer {
 }
 
 export interface MCPIMiddleware {
+  /** The identity config used by this middleware instance */
+  identity: MCPIIdentityConfig;
+
   /** The SessionManager instance for manual session operations */
   sessionManager: SessionManager;
 
@@ -163,7 +173,10 @@ export interface MCPIMiddleware {
    * Wrap a tool handler to automatically generate proofs.
    * Returns a new handler that appends proof metadata to the response.
    */
-  wrapWithProof(toolName: string, handler: MCPIToolHandler): MCPIToolHandler;
+  wrapWithProof<T extends Record<string, unknown> = Record<string, unknown>>(
+    toolName: string,
+    handler: MCPIToolHandler<T>,
+  ): MCPIToolHandler;
 
   /**
    * Wrap a tool handler to require a valid W3C Delegation Credential.
@@ -253,6 +266,14 @@ function validateScopeAttenuation(
 /**
  * Create MCP-I middleware for a standard MCP SDK Server.
  *
+ * For most use cases, prefer {@link withMCPI} from `./with-mcpi-server.ts`
+ * which wraps this function and auto-registers handshake + auto-attaches proofs.
+ *
+ * Use `createMCPIMiddleware` directly when:
+ * - You use the low-level `Server` API (not `McpServer`)
+ * - You need custom request handler patterns
+ * - You want per-tool control over proof/delegation wrapping
+ *
  * @param config - Agent identity and session configuration
  * @param cryptoProvider - Platform-specific crypto implementation
  * @returns Middleware components for session management and proof generation
@@ -394,12 +415,12 @@ export function createMCPIMiddleware(
     return undefined;
   }
 
-  function wrapWithProof(
+  function wrapWithProof<T extends Record<string, unknown> = Record<string, unknown>>(
     toolName: string,
-    handler: MCPIToolHandler,
+    handler: MCPIToolHandler<T>,
   ): MCPIToolHandler {
     return async (args: Record<string, unknown>, sessionId?: string) => {
-      const result = await handler(args, sessionId);
+      const result = await handler(args as T, sessionId);
 
       if (result.isError) {
         return result;
@@ -756,6 +777,7 @@ export function createMCPIMiddleware(
   }
 
   return {
+    identity: config.identity,
     sessionManager,
     proofGenerator,
     handshakeTool,