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

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,

package/src/providers/index.ts

@@ -13,3 +13,5 @@ export {
   MemoryNonceCacheProvider,
   MemoryIdentityProvider,
 } from './memory.js';
+
+export { NodeCryptoProvider } from './node-crypto.js';

package/src/providers/node-crypto.ts

@@ -0,0 +1,107 @@
+/**
+ * Node.js CryptoProvider
+ *
+ * Ed25519 crypto backed by Node.js built-in `node:crypto`.
+ * Use this on any Node.js 20+ server.
+ *
+ * @example
+ * ```typescript
+ * import { NodeCryptoProvider } from '@mcp-i/core/providers';
+ * import { withMCPI } from '@mcp-i/core/middleware';
+ *
+ * await withMCPI(server, { crypto: new NodeCryptoProvider() });
+ * ```
+ */
+
+import {
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+  sign,
+  verify,
+  randomBytes,
+} from "node:crypto";
+import { CryptoProvider } from "./base.js";
+
+/** PKCS8 DER header for Ed25519 private keys (16 bytes) */
+const ED25519_PKCS8_PREFIX = Buffer.from(
+  "302e020100300506032b657004220420",
+  "hex",
+);
+
+/** SPKI DER header for Ed25519 public keys (12 bytes) */
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+export class NodeCryptoProvider extends CryptoProvider {
+  async sign(
+    data: Uint8Array,
+    privateKeyBase64: string,
+  ): Promise<Uint8Array> {
+    const privateKey = Buffer.from(privateKeyBase64, "base64");
+
+    // Handle both raw 32-byte and full 64-byte Ed25519 keys
+    const keyBytes =
+      privateKey.length === 64 ? privateKey.subarray(0, 32) : privateKey;
+
+    const keyObject = createPrivateKey({
+      key: Buffer.concat([ED25519_PKCS8_PREFIX, keyBytes]),
+      format: "der",
+      type: "pkcs8",
+    });
+
+    return new Uint8Array(sign(null, Buffer.from(data), keyObject));
+  }
+
+  async verify(
+    data: Uint8Array,
+    signature: Uint8Array,
+    publicKeyBase64: string,
+  ): Promise<boolean> {
+    try {
+      const keyObject = createPublicKey({
+        key: Buffer.concat([
+          ED25519_SPKI_PREFIX,
+          Buffer.from(publicKeyBase64, "base64"),
+        ]),
+        format: "der",
+        type: "spki",
+      });
+
+      return verify(
+        null,
+        Buffer.from(data),
+        keyObject,
+        Buffer.from(signature),
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  async generateKeyPair(): Promise<{
+    privateKey: string;
+    publicKey: string;
+  }> {
+    const { publicKey, privateKey } = generateKeyPairSync("ed25519", {
+      publicKeyEncoding: { type: "spki", format: "der" },
+      privateKeyEncoding: { type: "pkcs8", format: "der" },
+    });
+
+    return {
+      privateKey: (privateKey as Buffer).subarray(16, 48).toString("base64"),
+      publicKey: (publicKey as Buffer).subarray(12, 44).toString("base64"),
+    };
+  }
+
+  async hash(data: Uint8Array): Promise<string> {
+    const hex = createHash("sha256")
+      .update(Buffer.from(data))
+      .digest("hex");
+    return `sha256:${hex}`;
+  }
+
+  async randomBytes(length: number): Promise<Uint8Array> {
+    return new Uint8Array(randomBytes(length));
+  }
+}