@kya-os/mcp 1.2.0

package/dist/middleware/with-mcpi.d.ts

@@ -0,0 +1,202 @@
+/**
+ * MCP-I Middleware — Core Implementation
+ *
+ * Adds identity, session management, and proof generation to MCP servers.
+ *
+ * For most use cases, prefer the high-level `withMCPI()` adapter from
+ * `./with-mcpi-server.ts` which (by default) auto-registers the handshake
+ * tool and auto-attaches proofs to all tool responses:
+ *
+ *   import { withMCPI } from '@kya-os/mcp';
+ *   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 { type CryptoProvider, FetchProvider } from "../providers/base.js";
+import { SessionManager, type SessionConfig } from "../session/manager.js";
+import { ProofGenerator } from "../proof/generator.js";
+import { type DIDResolver, type StatusListResolver } from "../delegation/vc-verifier.js";
+import { type DelegationCredential } from "../types/protocol.js";
+export interface MCPIIdentityConfig {
+    did: string;
+    kid: string;
+    privateKey: string;
+    publicKey: string;
+    agentName?: string;
+}
+export declare const MCPI_ACTIONS: readonly ["handshake", "identity", "reputation"];
+export interface MCPIDelegationConfig {
+    /**
+     * Optional custom DID resolver. If it returns null, middleware falls back to
+     * built-in did:key resolution and fetch-backed did:web resolution.
+     */
+    didResolver?: DIDResolver;
+    /**
+     * Optional fetch provider used for did:web resolution.
+     * If omitted, middleware falls back to the runtime global fetch when available.
+     */
+    fetchProvider?: FetchProvider;
+    /**
+     * Resolver for StatusList2021 checks. Credentials with credentialStatus are
+     * rejected when no resolver is configured.
+     */
+    statusListResolver?: StatusListResolver;
+    /**
+     * Resolve ancestor credentials for a delegated chain. The returned array may
+     * contain only ancestors (root -> parent) or the full chain (root -> leaf).
+     */
+    resolveDelegationChain?: (leafCredential: DelegationCredential) => Promise<DelegationCredential[]>;
+    /**
+     * When true, re-delegations (credentials with a `parentId`) MUST include
+     * an `audience` constraint binding them to the verifying server's DID.
+     *
+     * This prevents confused-deputy attacks where a delegated credential is
+     * forwarded to an unintended server. Without audience binding, any server
+     * that receives the credential will accept it.
+     *
+     * Recommended for production. See: Alan Karp's transitive access analysis
+     * and MCP-I §11.6 (Confused Deputy Attacks).
+     *
+     * Default is false for backward compatibility.
+     */
+    requireAudienceOnRedelegation?: boolean;
+    /**
+     * Compatibility mode for legacy integrations that cannot yet provide
+     * full delegation-chain and status-list resolvers.
+     *
+     * WARNING: Enabling this weakens verification guarantees:
+     * - Parent-linked delegations are accepted without chain resolution
+     * - credentialStatus is accepted without StatusList checks
+     *
+     * Default is false (strict security behavior).
+     */
+    allowLegacyUnsafeDelegation?: boolean;
+}
+export interface MCPIConfig {
+    /** Agent identity (DID + key material) */
+    identity: MCPIIdentityConfig;
+    /** Session configuration overrides */
+    session?: Omit<SessionConfig, "nonceCache">;
+    /** Delegation verification overrides */
+    delegation?: MCPIDelegationConfig;
+    /**
+     * When true, automatically creates a session on the first tool call
+     * if no session exists. Useful for demos and development where
+     * MCP clients don't support the `_mcpi` handshake flow.
+     * In production, MCP-I-aware runtimes should execute handshake before tool calls.
+     */
+    autoSession?: boolean;
+}
+export interface MCPIToolDefinition {
+    name: string;
+    description?: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
+        [key: string]: unknown;
+    };
+}
+export interface MCPIToolHandler<T extends Record<string, unknown> = Record<string, unknown>> {
+    (args: T, sessionId?: string): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+            [key: string]: unknown;
+        }>;
+        isError?: boolean;
+        [key: string]: unknown;
+    }>;
+}
+/**
+ * Server interface — minimal subset of @modelcontextprotocol/sdk Server.
+ * This avoids a hard dependency on the SDK at the type level.
+ */
+export interface MCPIServer {
+    setRequestHandler(schema: unknown, handler: (...args: unknown[]) => unknown): void;
+}
+export interface MCPIMiddleware {
+    /** The identity config used by this middleware instance */
+    identity: MCPIIdentityConfig;
+    /** The SessionManager instance for manual session operations */
+    sessionManager: SessionManager;
+    /** The ProofGenerator instance for manual proof operations */
+    proofGenerator: ProofGenerator;
+    /**
+     * Unified tool definition for `_mcpi`.
+     * Include this in your ListToolsRequest handler's tool list.
+     */
+    mcpiTool: MCPIToolDefinition;
+    /**
+     * @deprecated Use `mcpiTool` (`_mcpi` with `action: "handshake"`).
+     * Tool definition for `_mcpi_handshake`.
+     * Include this in your ListToolsRequest handler's tool list.
+     */
+    handshakeTool: MCPIToolDefinition;
+    /**
+     * Handle a unified `_mcpi` action. Use this in your CallToolRequest handler
+     * when `request.params.name === '_mcpi'`.
+     */
+    handleMCPI(args: Record<string, unknown>): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        isError?: boolean;
+    }>;
+    /**
+     * @deprecated Use `handleMCPI` with `action: "handshake"`.
+     * Handle a handshake call. Use this in your CallToolRequest handler
+     * when `request.params.name === '_mcpi_handshake'`.
+     */
+    handleHandshake(args: Record<string, unknown>): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        isError?: boolean;
+    }>;
+    /**
+     * Wrap a tool handler to automatically generate proofs.
+     * Returns a new handler that appends proof metadata to the response.
+     */
+    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.
+     *
+     * Caller must pass the VC as `_mcpi_delegation` in the tool args.
+     * - If absent: returns a `needs_authorization` response with the consentUrl.
+     * - If present but invalid: returns a structured error with reason.
+     * - If valid with correct scope: strips `_mcpi_delegation` and calls the handler.
+     */
+    wrapWithDelegation(toolName: string, config: {
+        scopeId: string;
+        consentUrl: string;
+    }, handler: MCPIToolHandler): MCPIToolHandler;
+}
+/**
+ * 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 (by default) 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
+ *
+ * @remarks
+ * **Single-process only**: This middleware stores session state in memory using closure
+ * variables (`activeSessionId`, `sessionNonces`). It is NOT suitable for multi-instance
+ * deployments behind a load balancer. For distributed deployments, implement a custom
+ * `SessionStore` backed by Redis, DynamoDB, or similar and pass it via `config.session`.
+ */
+export declare function createMCPIMiddleware(config: MCPIConfig, cryptoProvider: CryptoProvider): MCPIMiddleware;
+//# sourceMappingURL=with-mcpi.d.ts.map

package/dist/middleware/with-mcpi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-mcpi.d.ts","sourceRoot":"","sources":["../../src/middleware/with-mcpi.ts"],"names":[],"mappings":"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"}