@mcp-i/core 1.1.0-canary.2 → 1.1.0

package/src/errors.ts

@@ -0,0 +1,65 @@
+/**
+ * MCP-I Canonical Error Codes
+ *
+ * Single source of truth for all wire-format error codes.
+ * Aligned with the error catalog at modelcontextprotocol-identity.io.
+ *
+ * Naming convention: snake_case, no protocol prefix.
+ * Follows OAuth 2.0 / Stripe conventions for readability and portability.
+ */
+
+export const MCPI_ERROR_CODES = {
+  // Proof errors
+  invalid_proof: "invalid_proof",
+  invalid_jws: "invalid_jws",
+  nonce_replay: "nonce_replay",
+  timestamp_skew: "timestamp_skew",
+
+  // Identity / DID errors
+  did_not_found: "did_not_found",
+  invalid_public_key: "invalid_public_key",
+
+  // Session / Handshake errors
+  handshake_failed: "handshake_failed",
+  session_expired: "session_expired",
+  invalid_request: "invalid_request",
+
+  // Delegation errors
+  needs_authorization: "needs_authorization",
+  insufficient_scope: "insufficient_scope",
+  delegation_expired: "delegation_expired",
+  delegation_not_yet_valid: "delegation_not_yet_valid",
+  delegation_revoked: "delegation_revoked",
+  delegation_invalid: "delegation_invalid",
+  budget_exceeded: "budget_exceeded",
+  rate_limit_exceeded: "rate_limit_exceeded",
+
+  // Token errors
+  invalid_token: "invalid_token",
+  token_expired: "token_expired",
+
+  // Registry errors
+  mirror_pending: "mirror_pending",
+  claim_failed: "claim_failed",
+
+  // System errors
+  configuration_error: "configuration_error",
+  runtime_error: "runtime_error",
+} as const;
+
+export type MCPIErrorCode =
+  (typeof MCPI_ERROR_CODES)[keyof typeof MCPI_ERROR_CODES];
+
+export interface MCPIErrorResponse {
+  code: MCPIErrorCode;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export function createMCPIError(
+  code: MCPIErrorCode,
+  message: string,
+  details?: Record<string, unknown>,
+): MCPIErrorResponse {
+  return details ? { code, message, details } : { code, message };
+}

package/src/index.ts

@@ -15,6 +15,14 @@
  * This ensures callers can always handle failures without try/catch on validation paths.
  */
 
+// Error contract
+export {
+  MCPI_ERROR_CODES,
+  createMCPIError,
+  type MCPIErrorCode,
+  type MCPIErrorResponse,
+} from './errors.js';
+
 // Protocol types
 export type {
   DelegationConstraints,
@@ -171,6 +179,7 @@ export {
   extractAgentSlug,
   generateDidKeyFromBytes,
   generateDidKeyFromBase64,
+  didKeyFragment,
 } from './utils/did-helpers.js';
 
 // Auth module
@@ -182,6 +191,7 @@ export {
   type VerifyOrHintsResult,
   type AgentReputation,
   type ResumeTokenStore,
+  type UnknownAgentPolicy,
   type DelegationVerifier,
   type VerifyDelegationResult,
 } from './auth/index.js';

package/src/middleware/__tests__/mcpi-transport.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi } from "vitest";
+import { createMCPITransport, type Transport, type JSONRPCMessage } from "../mcpi-transport.js";
+import type { MCPIMiddleware, MCPIToolHandler } from "../with-mcpi.js";
+
+function createMockTransport(): Transport & { sentMessages: JSONRPCMessage[] } {
+  const sent: JSONRPCMessage[] = [];
+  return {
+    sentMessages: sent,
+    start: vi.fn().mockResolvedValue(undefined),
+    send: vi.fn(async (msg: JSONRPCMessage) => { sent.push(msg); }),
+    close: vi.fn().mockResolvedValue(undefined),
+    onmessage: undefined,
+    onclose: undefined,
+    onerror: undefined,
+  };
+}
+
+function createMockMCPI(proofResult?: Record<string, unknown>): MCPIMiddleware {
+  return {
+    wrapWithProof: (_toolName: string, handler: MCPIToolHandler) => {
+      return async (args: Record<string, unknown>) => {
+        const result = await handler(args);
+        if (proofResult) {
+          result._meta = { proof: proofResult };
+        }
+        return result;
+      };
+    },
+  } as unknown as MCPIMiddleware;
+}
+
+describe("createMCPITransport", () => {
+  it("should pass through non-tools/call messages unmodified", async () => {
+    const inner = createMockTransport();
+    const mcpi = createMockMCPI();
+    const wrapper = createMCPITransport(inner, mcpi);
+
+    await wrapper.send({ jsonrpc: "2.0", method: "resources/list", id: 1 });
+
+    expect(inner.sentMessages).toHaveLength(1);
+    expect(inner.sentMessages[0]).toEqual({ jsonrpc: "2.0", method: "resources/list", id: 1 });
+  });
+
+  it("should skip proof injection for excluded tools", async () => {
+    const inner = createMockTransport();
+    const mcpi = createMockMCPI({ jws: "test" });
+    const wrapper = createMCPITransport(inner, mcpi, ["_mcpi"]);
+
+    await wrapper.start();
+
+    // Simulate incoming _mcpi request
+    inner.onmessage!({
+      jsonrpc: "2.0",
+      method: "tools/call",
+      id: 42,
+      params: { name: "_mcpi", arguments: { action: "handshake" } },
+    });
+
+    // Simulate response
+    await wrapper.send({
+      jsonrpc: "2.0",
+      id: 42,
+      result: { content: [{ type: "text", text: "ok" }] },
+    });
+
+    // Should pass through without proof
+    const sent = inner.sentMessages[0] as { result?: { _meta?: unknown } };
+    expect(sent.result?._meta).toBeUndefined();
+  });
+
+  it("should inject proof for non-excluded tool calls", async () => {
+    const inner = createMockTransport();
+    const proof = { jws: "test.jws.sig", meta: { did: "did:key:z6Mk..." } };
+    const mcpi = createMockMCPI(proof);
+    const wrapper = createMCPITransport(inner, mcpi);
+
+    await wrapper.start();
+
+    // Simulate incoming greet request
+    inner.onmessage!({
+      jsonrpc: "2.0",
+      method: "tools/call",
+      id: 1,
+      params: { name: "greet", arguments: { name: "test" } },
+    });
+
+    // Simulate response
+    await wrapper.send({
+      jsonrpc: "2.0",
+      id: 1,
+      result: { content: [{ type: "text", text: "Hello!" }] },
+    });
+
+    const sent = inner.sentMessages[0] as { result?: { _meta?: { proof?: unknown } } };
+    expect(sent.result?._meta?.proof).toEqual(proof);
+  });
+
+  it("should not inject proof for error responses", async () => {
+    const inner = createMockTransport();
+    const mcpi = createMockMCPI({ jws: "test" });
+    const wrapper = createMCPITransport(inner, mcpi);
+
+    await wrapper.start();
+
+    inner.onmessage!({
+      jsonrpc: "2.0",
+      method: "tools/call",
+      id: 1,
+      params: { name: "greet", arguments: {} },
+    });
+
+    await wrapper.send({
+      jsonrpc: "2.0",
+      id: 1,
+      result: { content: [{ type: "text", text: "error" }], isError: true },
+    });
+
+    const sent = inner.sentMessages[0] as { result?: { _meta?: unknown } };
+    expect(sent.result?._meta).toBeUndefined();
+  });
+
+  it("should proxy onmessage/onclose/onerror to inner transport", () => {
+    const inner = createMockTransport();
+    const mcpi = createMockMCPI();
+    const wrapper = createMCPITransport(inner, mcpi);
+
+    const handler = () => {};
+    wrapper.onmessage = handler;
+    expect(inner.onmessage).toBe(handler);
+    expect(wrapper.onmessage).toBe(handler);
+
+    const closeHandler = () => {};
+    wrapper.onclose = closeHandler;
+    expect(inner.onclose).toBe(closeHandler);
+
+    const errorHandler = () => {};
+    wrapper.onerror = errorHandler;
+    expect(inner.onerror).toBe(errorHandler);
+  });
+
+  it("should delegate start and close to inner transport", async () => {
+    const inner = createMockTransport();
+    const mcpi = createMockMCPI();
+    const wrapper = createMCPITransport(inner, mcpi);
+
+    // close delegates directly
+    await wrapper.close();
+    expect(inner.close).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,117 @@
+import { describe, it, expect, vi } from "vitest";
+import { generateIdentity, withMCPI } from "../with-mcpi-server.js";
+import { NodeCryptoProvider } from "../../__tests__/utils/node-crypto-provider.js";
+
+const crypto = new NodeCryptoProvider();
+
+describe("generateIdentity", () => {
+  it("should return did, kid, privateKey, and publicKey", async () => {
+    const identity = await generateIdentity(crypto);
+
+    expect(identity.did).toMatch(/^did:key:z6Mk/);
+    expect(identity.kid).toMatch(/^did:key:z6Mk.+#z6Mk/);
+    expect(identity.privateKey).toBeDefined();
+    expect(identity.publicKey).toBeDefined();
+  });
+
+  it("should use spec-compliant did:key fragment (not #keys-1)", async () => {
+    const identity = await generateIdentity(crypto);
+    const fragment = identity.kid.split("#")[1];
+
+    expect(fragment).not.toBe("keys-1");
+    expect(fragment).toMatch(/^z6Mk/);
+    expect(identity.kid).toBe(`${identity.did}#${identity.did.replace("did:key:", "")}`);
+  });
+
+  it("should generate unique identities each call", async () => {
+    const a = await generateIdentity(crypto);
+    const b = await generateIdentity(crypto);
+
+    expect(a.did).not.toBe(b.did);
+    expect(a.privateKey).not.toBe(b.privateKey);
+  });
+});
+
+describe("withMCPI", () => {
+  it("should register _mcpi tool on server by default", async () => {
+    const registerTool = vi.fn();
+    const server = {
+      connect: vi.fn().mockResolvedValue(undefined),
+      registerTool,
+    };
+
+    await withMCPI(server, { crypto });
+
+    expect(registerTool).toHaveBeenCalledWith(
+      "_mcpi",
+      expect.objectContaining({ description: expect.any(String) }),
+      expect.any(Function),
+    );
+  });
+
+  it("should not register tool when handshakeExposure is 'none'", async () => {
+    const registerTool = vi.fn();
+    const server = {
+      connect: vi.fn().mockResolvedValue(undefined),
+      registerTool,
+    };
+
+    await withMCPI(server, { crypto, handshakeExposure: "none" });
+
+    expect(registerTool).not.toHaveBeenCalled();
+  });
+
+  it("should patch server.connect to wrap transport", async () => {
+    const originalConnect = vi.fn().mockResolvedValue(undefined);
+    const server = {
+      connect: originalConnect,
+      registerTool: vi.fn(),
+    };
+
+    await withMCPI(server, { crypto });
+
+    // server.connect should now be patched
+    expect(server.connect).not.toBe(originalConnect);
+
+    // Call the patched connect
+    const mockTransport = {
+      start: vi.fn().mockResolvedValue(undefined),
+      send: vi.fn().mockResolvedValue(undefined),
+      close: vi.fn().mockResolvedValue(undefined),
+    };
+    await server.connect(mockTransport);
+
+    // Original connect should have been called with wrapped transport
+    expect(originalConnect).toHaveBeenCalledTimes(1);
+    // The argument should be the wrapped transport (not the original)
+    const wrappedTransport = originalConnect.mock.calls[0][0];
+    expect(wrappedTransport).not.toBe(mockTransport);
+  });
+
+  it("should not patch connect when proofAllTools is false", async () => {
+    const originalConnect = vi.fn().mockResolvedValue(undefined);
+    const server = {
+      connect: originalConnect,
+      registerTool: vi.fn(),
+    };
+
+    await withMCPI(server, { crypto, proofAllTools: false });
+
+    // connect should NOT be patched
+    expect(server.connect).toBe(originalConnect);
+  });
+
+  it("should return MCPIMiddleware instance", async () => {
+    const server = {
+      connect: vi.fn().mockResolvedValue(undefined),
+      registerTool: vi.fn(),
+    };
+
+    const mcpi = await withMCPI(server, { crypto });
+
+    expect(mcpi).toBeDefined();
+    expect(mcpi.wrapWithProof).toBeInstanceOf(Function);
+    expect(mcpi.wrapWithDelegation).toBeInstanceOf(Function);
+    expect(mcpi.handleMCPI).toBeInstanceOf(Function);
+  });
+});

package/src/middleware/__tests__/with-mcpi.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, vi } from 'vitest';
 import {
   createMCPIMiddleware,
   type MCPIDelegationConfig,
@@ -24,7 +24,7 @@ async function createTestMiddleware(options?: {
   const crypto = new NodeCryptoProvider();
   const keyPair = await crypto.generateKeyPair();
   const did = generateDidKeyFromBase64(keyPair.publicKey);
-  const kid = `${did}#keys-1`;
+  const kid = `${did}#${did.replace('did:key:', '')}`;
 
   const middleware = createMCPIMiddleware(
     {
@@ -36,14 +36,14 @@ async function createTestMiddleware(options?: {
     crypto,
   );
 
-  return { middleware, did };
+  return { middleware, did, crypto };
 }
 
 async function createDelegationIssuer(options?: { did?: string; kid?: string }) {
   const crypto = new NodeCryptoProvider();
   const keyPair = await crypto.generateKeyPair();
   const did = options?.did ?? generateDidKeyFromBase64(keyPair.publicKey);
-  const kid = options?.kid ?? `${did}#keys-1`;
+  const kid = options?.kid ?? `${did}#${did.replace('did:key:', '')}`;
 
   const signingFn = async (
     canonicalVC: string,
@@ -126,7 +126,95 @@ describe('createMCPIMiddleware', () => {
       expect(result.isError).toBe(true);
       const parsed = JSON.parse(result.content[0].text);
       expect(parsed.success).toBe(false);
-      expect(parsed.error.code).toBe('MCPI_INVALID_HANDSHAKE');
+      expect(parsed.error.code).toBe('handshake_failed');
+    });
+  });
+
+  describe('_mcpi unified tool', () => {
+    it('should expose mcpiTool with name "_mcpi"', async () => {
+      const { middleware: mcpi } = await createTestMiddleware();
+      expect(mcpi.mcpiTool.name).toBe('_mcpi');
+      expect(mcpi.mcpiTool.inputSchema.properties?.action).toBeDefined();
+      expect(
+        (mcpi.mcpiTool.inputSchema.properties?.action as { enum?: string[] })?.enum,
+      ).toContain('handshake');
+      expect(
+        (mcpi.mcpiTool.inputSchema.properties?.action as { enum?: string[] })?.enum,
+      ).toContain('identity');
+      expect(mcpi.mcpiTool.inputSchema.required).toEqual(['action']);
+    });
+
+    it('should still expose handshakeTool as deprecated alias', async () => {
+      const { middleware: mcpi } = await createTestMiddleware();
+      expect(mcpi.handshakeTool).toBeDefined();
+      expect(mcpi.handshakeTool.name).toBe('_mcpi_handshake');
+    });
+
+    it('should dispatch action: "handshake" to handleHandshake', async () => {
+      const { middleware: mcpi, did } = await createTestMiddleware();
+      const result = await mcpi.handleMCPI({
+        action: 'handshake',
+        nonce: 'test-nonce',
+        audience: did,
+        timestamp: Math.floor(Date.now() / 1000),
+      });
+
+      expect(result.isError).toBeUndefined();
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.success).toBe(true);
+      expect(parsed.sessionId).toMatch(/^mcpi_/);
+    });
+
+    it('should dispatch action: "identity" and return server metadata', async () => {
+      const { middleware: mcpi, did } = await createTestMiddleware();
+      const result = await mcpi.handleMCPI({ action: 'identity' });
+
+      expect(result.isError).toBeUndefined();
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.did).toBe(did);
+      expect(parsed.kid).toMatch(/#z[\w]+$/);
+      expect(parsed.capabilities).toContain('handshake');
+      expect(parsed.capabilities).toContain('signing');
+      expect(parsed.capabilities).toContain('verification');
+    });
+
+    it('should return error for unknown action', async () => {
+      const { middleware: mcpi } = await createTestMiddleware();
+      const result = await mcpi.handleMCPI({ action: 'does_not_exist' });
+
+      expect(result.isError).toBe(true);
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.error.code).toBe('invalid_request');
+    });
+
+    it('should return error when action is missing', async () => {
+      const { middleware: mcpi } = await createTestMiddleware();
+      const result = await mcpi.handleMCPI({});
+
+      expect(result.isError).toBe(true);
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.error.code).toBe('invalid_request');
+    });
+
+    it('should return "not implemented" for action: "reputation"', async () => {
+      const { middleware: mcpi } = await createTestMiddleware();
+      const result = await mcpi.handleMCPI({ action: 'reputation' });
+
+      expect(result.isError).toBe(true);
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.error.code).toBe('runtime_error');
+    });
+
+    it('should still support handleHandshake() directly (backward compat)', async () => {
+      const { middleware: mcpi, did } = await createTestMiddleware();
+      const result = await mcpi.handleHandshake({
+        nonce: 'legacy-nonce',
+        audience: did,
+        timestamp: Math.floor(Date.now() / 1000),
+      });
+
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.success).toBe(true);
     });
   });
 
@@ -195,6 +283,36 @@ describe('createMCPIMiddleware', () => {
       expect(result.content[0].text).toBe('Hello!');
       expect(result._meta).toBeUndefined();
     });
+
+    it('should surface proofError in _meta when proof generation fails', async () => {
+      const { middleware: mcpi, did, crypto } = await createTestMiddleware();
+
+      // Handshake first
+      const hs = await mcpi.handleHandshake({
+        nonce: 'test-nonce-proof-fail',
+        audience: did,
+        timestamp: Math.floor(Date.now() / 1000),
+      });
+      const sessionId = JSON.parse(hs.content[0].text).sessionId;
+
+      // Make crypto.hash throw to break proof generation after handshake succeeds
+      vi.spyOn(crypto, 'hash').mockRejectedValue(new Error('HSM unavailable'));
+
+      const handler = mcpi.wrapWithProof('greet', async () => ({
+        content: [{ type: 'text', text: 'Hello!' }],
+      }));
+
+      const result = await handler({}, sessionId);
+
+      // Tool result still returned
+      expect(result.content[0].text).toBe('Hello!');
+      expect(result.isError).toBeUndefined();
+
+      // But _meta signals the proof failure
+      expect(result._meta).toBeDefined();
+      expect(result._meta!.proofError).toBeDefined();
+      expect(result._meta!.proof).toBeUndefined();
+    });
   });
 
   describe('wrapWithDelegation', () => {
@@ -232,7 +350,7 @@ describe('createMCPIMiddleware', () => {
 
       expect(result.isError).toBe(true);
       const parsed = JSON.parse(result.content[0].text);
-      expect(parsed.error).toBe('delegation_scope_missing');
+      expect(parsed.error).toBe('insufficient_scope');
     });
 
     it('should accept and call handler when VC has correct scope and valid signature', async () => {

package/src/middleware/index.ts

@@ -23,3 +23,9 @@ export {
   generateIdentity,
   type WithMCPIOptions,
 } from './with-mcpi-server.js';
+
+export {
+  createMCPITransport,
+  type Transport,
+  type JSONRPCMessage,
+} from './mcpi-transport.js';