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

package/dist/utils/did-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"did-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/did-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMvD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE;IACnC,QAAQ,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD,GAAG,MAAM,CAMT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIlD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAQD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,UAAU,GAAG,MAAM,CAW1E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAMxE"}
+{"version":3,"file":"did-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/did-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMvD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE;IACnC,QAAQ,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD,GAAG,MAAM,CAMT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIlD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAQD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,UAAU,GAAG,MAAM,CAW1E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAMxE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMlD"}

package/dist/utils/did-helpers.js

@@ -190,4 +190,22 @@ export function generateDidKeyFromBase64(publicKeyBase64) {
     const publicKeyBytes = Uint8Array.from(atob(publicKeyBase64), (c) => c.charCodeAt(0));
     return generateDidKeyFromBytes(publicKeyBytes);
 }
+/**
+ * Get the spec-compliant fragment identifier for a did:key DID.
+ *
+ * Per the did:key spec (W3C CCG), the fragment equals the multibase-encoded
+ * public key value (the DID-specific-id). For example:
+ *   did:key:z6MkABC... → z6MkABC...
+ *
+ * @see https://w3c-ccg.github.io/did-key-spec/#document-creation-algorithm
+ * @param did - A did:key DID string
+ * @returns The fragment identifier (multibase value), or 'keys-1' as fallback for non-did:key
+ */
+export function didKeyFragment(did) {
+    if (did.startsWith('did:key:')) {
+        return did.slice('did:key:'.length);
+    }
+    // Fallback for non-did:key methods
+    return 'keys-1';
+}
 //# sourceMappingURL=did-helpers.js.map

package/dist/utils/did-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"did-helpers.js","sourceRoot":"","sources":["../../src/utils/did-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IACzC,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;AACpB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,IAAY;IACpD,OAAO,YAAY,CAAC,IAAI,CAAC,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,YAAY,CAAC,MAE5B;IACC,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;IACxE,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,8CAA8C;IAC9C,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC;AACxC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,cAAc,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,yBAAyB,GAAG,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;AAE/D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,uBAAuB,CAAC,cAA0B;IAChE,yCAAyC;IACzC,MAAM,aAAa,GAAG,IAAI,UAAU,CAClC,yBAAyB,CAAC,MAAM,GAAG,cAAc,CAAC,MAAM,CACzD,CAAC;IACF,aAAa,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;IAC7C,aAAa,CAAC,GAAG,CAAC,cAAc,EAAE,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAEpE,iDAAiD;IACjD,MAAM,aAAa,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;IAClD,OAAO,YAAY,aAAa,EAAE,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,wBAAwB,CAAC,eAAuB;IAC9D,yBAAyB;IACzB,MAAM,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAClE,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAChB,CAAC;IACF,OAAO,uBAAuB,CAAC,cAAc,CAAC,CAAC;AACjD,CAAC"}
+{"version":3,"file":"did-helpers.js","sourceRoot":"","sources":["../../src/utils/did-helpers.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mcp-i/core",
-  "version": "1.1.0-canary.2",
-  "description": "MCP-I protocol reference implementation — delegation, proof, and session for Model Context Protocol Identity",
+  "version": "1.1.0",
+  "description": "Core library for MCP-I — delegation, proof, and session primitives for Model Context Protocol Identity",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -62,7 +62,6 @@
     "example:inspector": "npx @modelcontextprotocol/inspector npx tsx examples/node-server/server.ts --stdio"
   },
   "dependencies": {
-    "@mcp-i/core": "^1.1.0-canary.1",
     "jose": "^5.6.3",
     "json-canonicalize": "^2.0.0"
   },
@@ -76,6 +75,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@kya-os/consent": "^0.1.37",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@types/express": "^5.0.6",
     "@types/node": "^20.14.9",

package/src/__tests__/errors.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect } from "vitest";
+import {
+  MCPI_ERROR_CODES,
+  createMCPIError,
+} from "../errors.js";
+
+describe("MCPI_ERROR_CODES", () => {
+  it("should define all canonical error codes", () => {
+    const codes = Object.values(MCPI_ERROR_CODES);
+    expect(codes).toContain("invalid_proof");
+    expect(codes).toContain("invalid_jws");
+    expect(codes).toContain("nonce_replay");
+    expect(codes).toContain("timestamp_skew");
+    expect(codes).toContain("did_not_found");
+    expect(codes).toContain("invalid_public_key");
+    expect(codes).toContain("handshake_failed");
+    expect(codes).toContain("session_expired");
+    expect(codes).toContain("invalid_request");
+    expect(codes).toContain("needs_authorization");
+    expect(codes).toContain("insufficient_scope");
+    expect(codes).toContain("delegation_expired");
+    expect(codes).toContain("delegation_not_yet_valid");
+    expect(codes).toContain("delegation_revoked");
+    expect(codes).toContain("delegation_invalid");
+    expect(codes).toContain("budget_exceeded");
+    expect(codes).toContain("rate_limit_exceeded");
+    expect(codes).toContain("invalid_token");
+    expect(codes).toContain("token_expired");
+    expect(codes).toContain("mirror_pending");
+    expect(codes).toContain("claim_failed");
+    expect(codes).toContain("configuration_error");
+    expect(codes).toContain("runtime_error");
+  });
+
+  it("should have key === value for every code", () => {
+    for (const [key, value] of Object.entries(MCPI_ERROR_CODES)) {
+      expect(key).toBe(value);
+    }
+  });
+});
+
+describe("createMCPIError", () => {
+  it("should create an error response with code and message", () => {
+    const error = createMCPIError("handshake_failed", "Nonce already used");
+    expect(error.code).toBe("handshake_failed");
+    expect(error.message).toBe("Nonce already used");
+    expect(error.details).toBeUndefined();
+  });
+
+  it("should include details when provided", () => {
+    const error = createMCPIError("delegation_revoked", "Credential revoked", {
+      credentialId: "urn:uuid:123",
+    });
+    expect(error.details).toEqual({ credentialId: "urn:uuid:123" });
+  });
+});

package/src/__tests__/integration/full-flow.test.ts

@@ -74,7 +74,7 @@ describe("MCP-I Full Protocol Flow", () => {
     const agent = await identityProvider.getIdentity();
 
     expect(agent.did).toMatch(/^did:key:z/);
-    expect(agent.kid).toMatch(/#keys-1$/);
+    expect(agent.kid).toMatch(/#z[\w]+$/);
 
     // ── Step 2: Establish session via handshake ──────────────────
     const serverDid = "did:web:test-server.example.com";

package/src/__tests__/integration/mcp-enhance-server.test.ts

@@ -2,7 +2,7 @@
  * withMCPI() Integration Tests
  *
  * Tests the dream API: `withMCPI(server, { crypto })` auto-registers
- * the handshake tool and auto-attaches proofs to all tool responses.
+ * the `_mcpi` protocol tool and auto-attaches proofs to all tool responses.
  */
 
 import { describe, it, expect, afterEach } from 'vitest';
@@ -20,6 +20,7 @@ async function createTestPair(options?: {
   excludeTools?: string[];
   autoSession?: boolean;
   registerToolsBeforeWithMCPI?: boolean;
+  handshakeExposure?: 'tool' | 'none';
 }) {
   const crypto = new NodeCryptoProvider();
   const server = new McpServer(
@@ -46,6 +47,7 @@ async function createTestPair(options?: {
     autoSession: options?.autoSession ?? true,
     proofAllTools: options?.proofAllTools,
     excludeTools: options?.excludeTools,
+    handshakeExposure: options?.handshakeExposure,
   });
 
   // Register tools AFTER withMCPI to test late registration
@@ -103,13 +105,23 @@ describe('withMCPI()', () => {
     return pair;
   }
 
-  it('auto-registers _mcpi_handshake tool', async () => {
+  it('auto-registers _mcpi tool', async () => {
     const { client } = await create();
 
     const result = await client.listTools();
     const toolNames = result.tools.map((t) => t.name);
 
-    expect(toolNames).toContain('_mcpi_handshake');
+    expect(toolNames).toContain('_mcpi');
+  });
+
+  it('handshakeExposure: none does not auto-register _mcpi', async () => {
+    const { client } = await create({ handshakeExposure: 'none' });
+
+    const result = await client.listTools();
+    const toolNames = result.tools.map((t) => t.name);
+
+    expect(toolNames).not.toContain('_mcpi');
+    expect(toolNames).toContain('greet');
   });
 
   it('auto-proofs all registered tools', async () => {
@@ -204,8 +216,9 @@ describe('withMCPI()', () => {
     const { client, mcpi } = await create({ autoSession: false });
 
     const result = await client.callTool({
-      name: '_mcpi_handshake',
+      name: '_mcpi',
       arguments: {
+        action: 'handshake',
         nonce: `test-${Date.now()}`,
         audience: mcpi.identity.did,
         timestamp: Math.floor(Date.now() / 1000),
@@ -219,6 +232,36 @@ describe('withMCPI()', () => {
     expect(parsed.serverDid).toBe(mcpi.identity.did);
   });
 
+  it('manual handshake API works when handshake tool is not exposed', async () => {
+    const { client, mcpi } = await create({
+      autoSession: false,
+      handshakeExposure: 'none',
+    });
+
+    await mcpi.handleHandshake({
+      nonce: `manual-${Date.now()}`,
+      audience: mcpi.identity.did,
+      timestamp: Math.floor(Date.now() / 1000),
+    });
+
+    const result = await client.callTool({
+      name: 'greet',
+      arguments: { name: 'Manual Handshake' },
+    });
+
+    const first = result.content[0] as { type: string; text: string };
+    expect(first.text).toBe('Hello, Manual Handshake!');
+
+    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('multiple tools share the same auto-session', async () => {
     const { client } = await create();
 
@@ -292,7 +335,7 @@ describe('generateIdentity()', () => {
     const identity = await generateIdentity(crypto);
 
     expect(identity.did).toMatch(/^did:key:z6Mk/);
-    expect(identity.kid).toBe(`${identity.did}#keys-1`);
+    expect(identity.kid).toBe(`${identity.did}#${identity.did.replace('did:key:', '')}`);
     expect(identity.privateKey).toBeDefined();
     expect(identity.publicKey).toBeDefined();
     // Keys should be base64 strings

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

@@ -25,7 +25,7 @@ async function setupMcpServerPair(options?: { autoSession?: boolean }) {
   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 mcpi = createMCPIMiddleware(
     {
@@ -43,18 +43,19 @@ async function setupMcpServerPair(options?: { autoSession?: boolean }) {
     { instructions: 'Test server for McpServer + MCP-I integration' },
   );
 
-  // Register _mcpi_handshake tool (same pattern as Context7 integration)
+  // Register unified _mcpi tool (same pattern as Context7 integration)
   server.registerTool(
-    '_mcpi_handshake',
+    '_mcpi',
     {
-      description: 'MCP-I identity handshake',
+      description: 'MCP-I protocol',
       inputSchema: {
-        nonce: z.string(),
-        audience: z.string(),
-        timestamp: z.number(),
+        action: z.enum(['handshake', 'identity', 'reputation']),
+        nonce: z.string().optional(),
+        audience: z.string().optional(),
+        timestamp: z.number().optional(),
       },
     },
-    async (args) => mcpi.handleHandshake(args as Record<string, unknown>),
+    async (args) => mcpi.handleMCPI(args as Record<string, unknown>),
   );
 
   // Wrap a test tool with proof (simulates Context7's resolve-library-id)
@@ -135,13 +136,13 @@ describe('McpServer (High-Level API) + MCP-I Integration', () => {
     return pair;
   }
 
-  it('listTools returns handshake + registered tools', async () => {
+  it('listTools returns _mcpi + registered tools', async () => {
     const { client } = await createPair();
 
     const result = await client.listTools();
     const toolNames = result.tools.map((t) => t.name);
 
-    expect(toolNames).toContain('_mcpi_handshake');
+    expect(toolNames).toContain('_mcpi');
     expect(toolNames).toContain('search');
     expect(toolNames).toContain('fetch-docs');
   });
@@ -150,8 +151,9 @@ describe('McpServer (High-Level API) + MCP-I Integration', () => {
     const { client, did } = await createPair();
 
     const result = await client.callTool({
-      name: '_mcpi_handshake',
+      name: '_mcpi',
       arguments: {
+        action: 'handshake',
         nonce: `mcpserver-test-${Date.now()}`,
         audience: did,
         timestamp: Math.floor(Date.now() / 1000),
@@ -173,8 +175,9 @@ describe('McpServer (High-Level API) + MCP-I Integration', () => {
 
     // Handshake first
     await client.callTool({
-      name: '_mcpi_handshake',
+      name: '_mcpi',
       arguments: {
+        action: 'handshake',
         nonce: `mcpserver-test-${Date.now()}`,
         audience: did,
         timestamp: Math.floor(Date.now() / 1000),
@@ -337,13 +340,13 @@ describe('McpServer + withMCPI() (Dream API)', () => {
     return { client, server, mcpi };
   }
 
-  it('listTools returns handshake + registered tools (withMCPI)', async () => {
+  it('listTools returns _mcpi + registered tools (withMCPI)', async () => {
     const { client } = await createWithMCPIPair();
 
     const result = await client.listTools();
     const toolNames = result.tools.map((t) => t.name);
 
-    expect(toolNames).toContain('_mcpi_handshake');
+    expect(toolNames).toContain('_mcpi');
     expect(toolNames).toContain('search');
     expect(toolNames).toContain('fetch-docs');
   });
@@ -373,8 +376,9 @@ describe('McpServer + withMCPI() (Dream API)', () => {
     const { client, mcpi } = await createWithMCPIPair({ autoSession: false });
 
     const result = await client.callTool({
-      name: '_mcpi_handshake',
+      name: '_mcpi',
       arguments: {
+        action: 'handshake',
         nonce: `withmcpi-test-${Date.now()}`,
         audience: mcpi.identity.did,
         timestamp: Math.floor(Date.now() / 1000),

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

@@ -64,7 +64,7 @@ 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 kid = `${did}#${did.replace('did:key:', '')}`;
 
   const mcpi = createMCPIMiddleware(
     {
@@ -101,7 +101,7 @@ async function setupMcpPair(options?: { autoSession?: boolean }) {
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
-      mcpi.handshakeTool,
+      mcpi.mcpiTool,
       {
         name: 'greet',
         description: 'Returns a greeting with proof',
@@ -127,8 +127,8 @@ async function setupMcpPair(options?: { autoSession?: boolean }) {
   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 === '_mcpi') {
+      return mcpi.handleMCPI(args as Record<string, unknown>);
     }
     if (name === 'greet') {
       return greetHandler(args as Record<string, unknown>);
@@ -157,7 +157,7 @@ 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 kid = `${did}#${did.replace('did:key:', '')}`;
 
   const signingFn = async (
     canonicalVC: string,
@@ -211,14 +211,14 @@ describe('MCP Transport Integration', () => {
     return pair;
   }
 
-  it('listTools returns handshake + app tools', async () => {
+  it('listTools returns _mcpi + 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('_mcpi');
     expect(toolNames).toContain('greet');
     expect(toolNames).toContain('restricted_greet');
   });
@@ -227,8 +227,9 @@ describe('MCP Transport Integration', () => {
     const { client, did } = await createPair();
 
     const result = await client.callTool({
-      name: '_mcpi_handshake',
+      name: '_mcpi',
       arguments: {
+        action: 'handshake',
         nonce: `transport-test-${Date.now()}`,
         audience: did,
         timestamp: Math.floor(Date.now() / 1000),
@@ -250,8 +251,9 @@ describe('MCP Transport Integration', () => {
 
     // Handshake first
     await client.callTool({
-      name: '_mcpi_handshake',
+      name: '_mcpi',
       arguments: {
+        action: 'handshake',
         nonce: `transport-test-${Date.now()}`,
         audience: did,
         timestamp: Math.floor(Date.now() / 1000),
@@ -287,8 +289,9 @@ describe('MCP Transport Integration', () => {
 
     // Handshake
     await client.callTool({
-      name: '_mcpi_handshake',
+      name: '_mcpi',
       arguments: {
+        action: 'handshake',
         nonce: `transport-test-${Date.now()}`,
         audience: did,
         timestamp: Math.floor(Date.now() / 1000),

package/src/__tests__/providers/base.test.ts

@@ -155,7 +155,7 @@ describe('Base Provider Classes', () => {
     it('should have proper type structure', () => {
       const validIdentity = {
         did: 'did:key:z123',
-        kid: 'did:key:z123#keys-1',
+        kid: 'did:key:z123#z123',
         privateKey: 'private-key',
         publicKey: 'public-key',
         createdAt: new Date().toISOString(),

package/src/__tests__/providers/memory.test.ts

@@ -222,7 +222,7 @@ describe('MemoryIdentityProvider', () => {
 
       expect(identity).toBeDefined();
       expect(identity.did).toMatch(/^did:key:z/);
-      expect(identity.kid).toBe(`${identity.did}#keys-1`);
+      expect(identity.kid).toBe(`${identity.did}#${identity.did.replace('did:key:', '')}`);
       expect(identity.privateKey).toMatch(/^[A-Za-z0-9+/=]+$/); // Valid base64 string
       expect(identity.publicKey).toMatch(/^[A-Za-z0-9+/=]+$/); // Valid base64 string
       expect(identity.type).toBe('development');
@@ -246,7 +246,7 @@ describe('MemoryIdentityProvider', () => {
     it('should save and return the saved identity', async () => {
       const customIdentity = {
         did: 'did:key:zcustom',
-        kid: 'did:key:zcustom#keys-1',
+        kid: 'did:key:zcustom#zcustom',
         privateKey: 'custom-private',
         publicKey: 'custom-public',
         createdAt: new Date().toISOString(),

package/src/__tests__/utils/mock-providers.ts

@@ -251,7 +251,7 @@ export class MockIdentityProvider extends IdentityProvider {
     if (!this.identity) {
       this.identity = {
         did: 'did:key:zmock123',
-        kid: 'did:key:zmock123#keys-1',
+        kid: 'did:key:zmock123#zmock123',
         privateKey: 'mock-private-key',
         publicKey: 'mock-public-key',
         createdAt: new Date().toISOString(),
@@ -271,7 +271,7 @@ export class MockIdentityProvider extends IdentityProvider {
     this.rotateCount++;
     this.identity = {
       did: `did:key:zmock456-${this.rotateCount}`,
-      kid: `did:key:zmock456-${this.rotateCount}#keys-1`,
+      kid: `did:key:zmock456-${this.rotateCount}#zmock456-${this.rotateCount}`,
       privateKey: `mock-private-key-rotated-${this.rotateCount}`,
       publicKey: `mock-public-key-rotated-${this.rotateCount}`,
       createdAt: new Date().toISOString(),

package/src/auth/__tests__/handshake.test.ts

@@ -0,0 +1,190 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  verifyOrHints,
+  MemoryResumeTokenStore,
+  type AuthHandshakeConfig,
+} from '../handshake.js';
+
+// Mock global fetch
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+function createConfig(overrides?: {
+  minReputationScore?: number;
+  unknownAgentPolicy?: 'deny' | 'require-consent' | 'allow';
+  reputationApiUrl?: string;
+}): AuthHandshakeConfig {
+  return {
+    delegationVerifier: {
+      verify: vi.fn().mockResolvedValue({ valid: false, reason: 'No delegation' }),
+    },
+    resumeTokenStore: new MemoryResumeTokenStore(),
+    reputationService: {
+      apiUrl: overrides?.reputationApiUrl ?? 'https://reputation.example.com',
+    },
+    authorization: {
+      authorizationUrl: 'https://example.com/consent',
+      minReputationScore: overrides?.minReputationScore ?? 30,
+      unknownAgentPolicy: overrides?.unknownAgentPolicy,
+    },
+  };
+}
+
+function mockReputationResponse(score: number, status = 200) {
+  mockFetch.mockResolvedValueOnce({
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: status === 200 ? 'OK' : 'Error',
+    json: async () => ({ score }),
+  });
+}
+
+function mockReputationNotFound() {
+  mockFetch.mockResolvedValueOnce({
+    ok: false,
+    status: 404,
+    statusText: 'Not Found',
+  });
+}
+
+function mockReputationNetworkError() {
+  mockFetch.mockRejectedValueOnce(new Error('ECONNREFUSED'));
+}
+
+describe('verifyOrHints — unknownAgentPolicy', () => {
+  const agentDid = 'did:key:z6MkTest';
+  const scopes = ['read:data'];
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('known agents (reputation service returns a score)', () => {
+    it('should reject known agent with score below threshold', async () => {
+      const config = createConfig({ minReputationScore: 30 });
+      mockReputationResponse(10);
+
+      const result = await verifyOrHints(agentDid, scopes, config);
+
+      expect(result.authorized).toBe(false);
+      expect(result.reason).toBe('Low reputation score');
+      expect(result.reputation?.score).toBe(10);
+    });
+
+    it('should allow known agent with score above threshold to proceed to delegation', async () => {
+      const config = createConfig({ minReputationScore: 30 });
+      mockReputationResponse(80);
+
+      const result = await verifyOrHints(agentDid, scopes, config);
+
+      // Not authorized (no delegation), but passed reputation gate
+      expect(result.authorized).toBe(false);
+      expect(result.reason).toBe('No delegation');
+      expect(result.reputation?.score).toBe(80);
+    });
+  });
+
+  describe('unknown agents (404 from reputation service)', () => {
+    it('should deny unknown agent when policy is "deny"', async () => {
+      const config = createConfig({ unknownAgentPolicy: 'deny' });
+      mockReputationNotFound();
+
+      const result = await verifyOrHints(agentDid, scopes, config);
+
+      expect(result.authorized).toBe(false);
+      expect(result.reason).toBe('Unknown agent — policy: deny');
+      expect(result.reputation?.score).toBeNull();
+    });
+
+    it('should require consent for unknown agent when policy is "require-consent"', async () => {
+      const config = createConfig({ unknownAgentPolicy: 'require-consent' });
+      mockReputationNotFound();
+
+      const result = await verifyOrHints(agentDid, scopes, config);
+
+      expect(result.authorized).toBe(false);
+      expect(result.reason).toBe('Unknown agent — policy: require-consent');
+      expect(result.authError).toBeDefined();
+      expect(result.reputation?.score).toBeNull();
+    });
+
+    it('should default to "require-consent" when no policy is set', async () => {
+      const config = createConfig(); // no unknownAgentPolicy
+      mockReputationNotFound();
+
+      const result = await verifyOrHints(agentDid, scopes, config);
+
+      expect(result.authorized).toBe(false);
+      expect(result.reason).toBe('Unknown agent — policy: require-consent');
+    });
+
+    it('should allow unknown agent when policy is "allow"', async () => {
+      const config = createConfig({ unknownAgentPolicy: 'allow' });
+      mockReputationNotFound();
+
+      const result = await verifyOrHints(agentDid, scopes, config);
+
+      // Not authorized (no delegation), but passed reputation gate
+      expect(result.authorized).toBe(false);
+      expect(result.reason).toBe('No delegation');
+      expect(result.reputation?.score).toBeNull();
+    });
+  });
+
+  describe('reputation service unreachable (network error)', () => {
+    it('should treat network errors as unknown agent', async () => {
+      const config = createConfig({ unknownAgentPolicy: 'deny' });
+      mockReputationNetworkError();
+
+      const result = await verifyOrHints(agentDid, scopes, config);
+
+      expect(result.authorized).toBe(false);
+      expect(result.reason).toBe('Unknown agent — policy: deny');
+      expect(result.reputation?.score).toBeNull();
+      expect(result.reputation?.riskLevel).toBe('unknown');
+    });
+
+    it('should route to consent on network error with default policy', async () => {
+      const config = createConfig(); // default = require-consent
+      mockReputationNetworkError();
+
+      const result = await verifyOrHints(agentDid, scopes, config);
+
+      expect(result.authorized).toBe(false);
+      expect(result.reason).toBe('Unknown agent — policy: require-consent');
+      expect(result.authError).toBeDefined();
+    });
+
+    it('should allow through on network error when policy is "allow"', async () => {
+      const config = createConfig({ unknownAgentPolicy: 'allow' });
+      mockReputationNetworkError();
+
+      const result = await verifyOrHints(agentDid, scopes, config);
+
+      // Passes reputation gate, fails on delegation
+      expect(result.authorized).toBe(false);
+      expect(result.reason).toBe('No delegation');
+    });
+  });
+
+  describe('no reputation service configured', () => {
+    it('should skip reputation check entirely when no service configured', async () => {
+      const config: AuthHandshakeConfig = {
+        delegationVerifier: {
+          verify: vi.fn().mockResolvedValue({ valid: false, reason: 'No delegation' }),
+        },
+        resumeTokenStore: new MemoryResumeTokenStore(),
+        // No reputationService
+        authorization: {
+          authorizationUrl: 'https://example.com/consent',
+          minReputationScore: 30,
+        },
+      };
+
+      const result = await verifyOrHints(agentDid, scopes, config);
+
+      expect(result.reputation).toBeUndefined();
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+  });
+});