@routecraft/ai 0.4.0-canary.9 → 0.4.0

package/dist/index.d.cts

@@ -369,20 +369,44 @@ declare const MCP_STDIO_MANAGERS: unique symbol;
 declare module "@routecraft/routecraft" {
     interface StoreRegistry {
         [MCP_PLUGIN_REGISTERED]: boolean;
-        [ADAPTER_MCP_CLIENT_SERVERS]: Map<string, McpClientHttpConfig$1 | McpClientStdioConfig | string>;
+        [ADAPTER_MCP_CLIENT_SERVERS]: Map<string, McpClientHttpConfig | McpClientStdioConfig | string>;
         [MCP_TOOL_REGISTRY]: McpToolRegistry;
         [MCP_STDIO_MANAGERS]: Map<string, {
             callTool(name: string, args: Record<string, unknown>): Promise<unknown>;
         }>;
     }
+    interface RoutecraftHeaders {
+        /** The MCP tool name that triggered this exchange. */
+        "routecraft.mcp.tool"?: string;
+        /** The MCP session identifier. */
+        "routecraft.mcp.session"?: string;
+        /** Authenticated subject (from AuthPrincipal). */
+        "routecraft.auth.subject"?: string;
+        /** Authentication scheme used. */
+        "routecraft.auth.scheme"?: string;
+        /** Roles assigned to the authenticated principal. */
+        "routecraft.auth.roles"?: string[];
+        /** Scopes granted to the authenticated principal. */
+        "routecraft.auth.scopes"?: string[];
+        /** Email of the authenticated principal. */
+        "routecraft.auth.email"?: string;
+        /** Display name of the authenticated principal. */
+        "routecraft.auth.name"?: string;
+        /** Token issuer (JWT `iss`). */
+        "routecraft.auth.issuer"?: string;
+        /** Intended audience (JWT `aud`). */
+        "routecraft.auth.audience"?: string[];
+    }
 }
 /**
  * HTTP client config for a remote MCP server (Streamable HTTP).
  * Used in mcpPlugin({ clients: { name: config } }).
  */
-interface McpClientHttpConfig$1 {
+interface McpClientHttpConfig {
     transport?: "streamable-http";
     url: string;
+    /** Auth credentials sent on every request to this server. */
+    auth?: McpClientAuthOptions;
 }
 /**
  * Stdio client config for a local MCP server subprocess.
@@ -401,7 +425,155 @@ interface McpClientStdioConfig {
     cwd?: string;
 }
 /** Union of client configs accepted by mcpPlugin({ clients }). */
-type McpClientServerConfig = McpClientHttpConfig$1 | McpClientStdioConfig;
+type McpClientServerConfig = McpClientHttpConfig | McpClientStdioConfig;
+/**
+ * Header keys set on exchanges created by the MCP server.
+ * Use these with `exchange.headers[McpHeadersKeys.AUTH_SUBJECT]` for type-safe access.
+ *
+ * @example
+ * ```ts
+ * import { McpHeadersKeys } from '@routecraft/ai'
+ *
+ * .process((ex) => {
+ *   const user = ex.headers[McpHeadersKeys.AUTH_SUBJECT]
+ *   const tool = ex.headers[McpHeadersKeys.TOOL]
+ * })
+ * ```
+ */
+declare enum McpHeadersKeys {
+    /** The MCP tool name that triggered this exchange. */
+    TOOL = "routecraft.mcp.tool",
+    /** The MCP session identifier. */
+    SESSION = "routecraft.mcp.session",
+    /** Authenticated subject (from AuthPrincipal). */
+    AUTH_SUBJECT = "routecraft.auth.subject",
+    /** Authentication scheme used. */
+    AUTH_SCHEME = "routecraft.auth.scheme",
+    /** Roles assigned to the authenticated principal. */
+    AUTH_ROLES = "routecraft.auth.roles",
+    /** Scopes granted to the authenticated principal. */
+    AUTH_SCOPES = "routecraft.auth.scopes",
+    /** Email of the authenticated principal. */
+    AUTH_EMAIL = "routecraft.auth.email",
+    /** Display name of the authenticated principal. */
+    AUTH_NAME = "routecraft.auth.name",
+    /** Token issuer (JWT `iss`). */
+    AUTH_ISSUER = "routecraft.auth.issuer",
+    /** Intended audience (JWT `aud`). */
+    AUTH_AUDIENCE = "routecraft.auth.audience"
+}
+/**
+ * Authenticated user principal resolved from an incoming request.
+ * Returned by the auth validator to populate exchange headers for logging,
+ * filtering, and access control inside routes.
+ *
+ * `subject` and `scheme` are always required; everything else is
+ * scheme-dependent and may be absent.
+ *
+ * @experimental
+ */
+interface AuthPrincipal {
+    /** Unique user/client identifier (JWT `sub`, username, API key ID, etc.). */
+    subject: string;
+    /** Authentication scheme that produced this principal. */
+    scheme: "bearer" | "basic" | "api-key" | (string & {});
+    /** Role names granted to this principal. */
+    roles?: string[];
+    /** OAuth 2.0 / JWT scopes. */
+    scopes?: string[];
+    /** Email address, if known. */
+    email?: string;
+    /** Display name, if known. */
+    name?: string;
+    /** Token issuer (JWT `iss`). */
+    issuer?: string;
+    /** Intended audiences (JWT `aud`). */
+    audience?: string[];
+    /** Expiry as Unix epoch seconds (JWT `exp`, session expiry). */
+    expiresAt?: number;
+    /** Arbitrary extra claims. For JWTs this holds the full decoded payload. */
+    claims?: Record<string, unknown>;
+}
+/**
+ * Authentication options for the MCP HTTP server.
+ * Only applies when `transport` is `"http"`. Ignored for stdio.
+ *
+ * The validator receives the raw bearer token from the `Authorization` header
+ * on every request and must return an {@link AuthPrincipal} on success or
+ * `null` / `false` to reject with 401. Use the built-in `jwt()` helper for
+ * HMAC-signed JWTs or supply a custom function for other schemes.
+ *
+ * @example
+ * ```ts
+ * // Built-in JWT helper (HMAC / HS256)
+ * import { jwt } from "@routecraft/ai";
+ * auth: jwt({ secret: process.env.JWT_SECRET! })
+ *
+ * // Custom validator
+ * auth: {
+ *   validator: async (token) => {
+ *     const user = await lookupApiKey(token);
+ *     if (!user) return null;
+ *     return { subject: user.id, scheme: "api-key", roles: user.roles };
+ *   }
+ * }
+ * ```
+ *
+ * @experimental
+ */
+interface McpHttpAuthOptions {
+    /**
+     * Validator function called with the raw bearer token on every request.
+     *
+     * Return an {@link AuthPrincipal} to allow access; return `null` or `false`
+     * to reject with 401. May be async.
+     *
+     * If the function throws, the server responds with 500.
+     * Validators should catch expected failures (e.g. JWT expiry) and return `null`.
+     */
+    validator: McpAuthValidator;
+}
+/**
+ * A function that validates a bearer token and resolves the authenticated principal.
+ * Called on every incoming HTTP request.
+ * May be synchronous or asynchronous.
+ *
+ * Return an {@link AuthPrincipal} to allow access, or `null` / `false` to reject with 401.
+ * If the function throws, the server responds with 500.
+ *
+ * @experimental
+ */
+type McpAuthValidator = (token: string) => AuthPrincipal | null | false | Promise<AuthPrincipal | null | false>;
+/**
+ * A function that provides a bearer token for outbound requests.
+ * Called on every request; may be synchronous or asynchronous.
+ * Useful for dynamic tokens (JWT refresh, rotating API keys, etc.).
+ *
+ * @experimental
+ */
+type McpClientTokenProvider = () => string | Promise<string>;
+/**
+ * Auth config for an outbound MCP HTTP client connection.
+ * Passed as request headers on every connection to the remote server.
+ *
+ * @experimental
+ */
+interface McpClientAuthOptions {
+    /**
+     * Bearer token(s) or provider for the `Authorization` header.
+     * Builds `Authorization: Bearer <token>`.
+     *
+     * - `string` -- single static token.
+     * - `string[]` -- array of tokens; one is selected per request (round-robin).
+     * - `() => string | Promise<string>` -- called per request for dynamic tokens.
+     */
+    token?: string | string[] | McpClientTokenProvider;
+    /**
+     * Additional headers to include on every request to the remote server.
+     * If `Authorization` is set here, it overrides `token`.
+     */
+    headers?: Record<string, string>;
+}
 /**
  * Options for the MCP plugin (mcpPlugin).
  * One plugin per adapter: this is the single options type for the MCP plugin.
@@ -417,6 +589,17 @@ interface McpPluginOptions {
     port?: number;
     /** Host to bind to. Default: "localhost" (only used with transport: "http") */
     host?: string;
+    /**
+     * Authentication for the HTTP transport. When set, every request to `/mcp` must
+     * include a valid `Authorization: Bearer <token>` header. Ignored for stdio.
+     *
+     * @example
+     * ```ts
+     * import { jwt } from "@routecraft/ai";
+     * auth: jwt({ secret: process.env.JWT_SECRET! })
+     * ```
+     */
+    auth?: McpHttpAuthOptions;
     /**
      * Filter which tools to expose. Default: all mcp() routes.
      * Can be an array of endpoint names or a filter function.
@@ -428,7 +611,7 @@ interface McpPluginOptions {
      * Stdio clients are managed as subprocesses with auto-restart.
      * HTTP clients are used for ephemeral tool calls.
      */
-    clients?: Record<string, McpClientHttpConfig$1 | McpClientStdioConfig>;
+    clients?: Record<string, McpClientHttpConfig | McpClientStdioConfig>;
     /**
      * Max auto-restart attempts for stdio clients before giving up.
      * Applies to all stdio clients. Default: 5.
@@ -485,6 +668,13 @@ interface McpClientOptions {
      * Default: body as object -> use as args; otherwise { input: body }.
      */
     args?: McpArgsExtractor$1;
+    /**
+     * Auth credentials for the outbound HTTP connection.
+     * When using `serverId`, auth flows automatically from `mcpPlugin({ clients })`
+     * so this field is rarely needed. Use it to override registered auth or to
+     * supply credentials when using inline `url`.
+     */
+    auth?: McpClientAuthOptions;
 }
 /**
  * Represents a tool exposed via MCP
@@ -534,14 +724,6 @@ type McpMessage<S extends StandardSchemaV1 | undefined> = S extends StandardSche
  * Extracts MCP tool arguments from an exchange. Default implementation uses exchange.body.
  */
 type McpArgsExtractor = (exchange: Exchange<unknown>) => Record<string, unknown>;
-/**
- * HTTP client config for a remote MCP server (Streamable HTTP).
- * Used in mcpPlugin({ clients: { name: config } }).
- */
-interface McpClientHttpConfig {
-    transport?: "streamable-http";
-    url: string;
-}
 
 /**
  * Brand symbol for MCP adapter type checking.
@@ -598,6 +780,109 @@ declare function mcp(shorthand: RegisteredMcpShorthand, options?: {
     args?: McpArgsExtractor$1;
 }): Destination<unknown, unknown>;
 
+/**
+ * Supported HMAC algorithms for JWT signature verification.
+ * Maps JWT `alg` header values to Node.js `crypto.createHmac` digest names.
+ */
+declare const HMAC_ALGORITHMS: {
+    readonly HS256: "sha256";
+    readonly HS384: "sha384";
+    readonly HS512: "sha512";
+};
+/**
+ * Supported RSA algorithms for JWT signature verification.
+ * Maps JWT `alg` header values to Node.js `crypto.createVerify` algorithm names.
+ */
+declare const RSA_ALGORITHMS: {
+    readonly RS256: "RSA-SHA256";
+    readonly RS384: "RSA-SHA384";
+    readonly RS512: "RSA-SHA512";
+};
+type HmacAlgorithm = keyof typeof HMAC_ALGORITHMS;
+type RsaAlgorithm = keyof typeof RSA_ALGORITHMS;
+/**
+ * HMAC (symmetric) JWT options.
+ * Uses a shared secret to sign and verify tokens.
+ *
+ * @experimental
+ */
+interface JwtHmacOptions {
+    /** Shared secret used to verify HMAC signatures. */
+    secret: string;
+    /**
+     * HMAC algorithm to accept. Default: `"HS256"`.
+     * The helper rejects tokens whose `alg` header does not match.
+     */
+    algorithm?: HmacAlgorithm;
+    /**
+     * Clock skew tolerance in seconds for `exp` and `nbf` checks.
+     * Default: `0` (no tolerance).
+     */
+    clockToleranceSec?: number;
+}
+/**
+ * RSA (asymmetric) JWT options.
+ * Uses a public key to verify signatures. Only the public key is needed
+ * since the server only verifies, never signs.
+ *
+ * @experimental
+ */
+interface JwtRsaOptions {
+    /** PEM-encoded public key or certificate used to verify RSA signatures. */
+    publicKey: string;
+    /**
+     * RSA algorithm to accept. Default: `"RS256"`.
+     * The helper rejects tokens whose `alg` header does not match.
+     */
+    algorithm?: RsaAlgorithm;
+    /**
+     * Clock skew tolerance in seconds for `exp` and `nbf` checks.
+     * Default: `0` (no tolerance).
+     */
+    clockToleranceSec?: number;
+}
+/**
+ * Options for the built-in JWT auth helper.
+ * Supports HMAC (symmetric) and RSA (asymmetric) signing.
+ *
+ * Discriminated by key: pass `secret` for HMAC, `publicKey` for RSA.
+ *
+ * @experimental
+ */
+type JwtAuthOptions = JwtHmacOptions | JwtRsaOptions;
+/**
+ * Built-in JWT authentication helper for MCP HTTP servers.
+ * Verifies HMAC or RSA signed JWTs using only `node:crypto` (no external
+ * dependencies).
+ *
+ * Returns an {@link McpHttpAuthOptions} that can be passed directly to
+ * `mcpPlugin({ auth: jwt({ ... }) })`.
+ *
+ * On success the validator returns an {@link AuthPrincipal} populated from
+ * standard JWT claims (`sub`, `iss`, `aud`, `exp`, `scope`, etc.) with the
+ * full decoded payload available in `claims`.
+ *
+ * @example
+ * ```ts
+ * import { mcpPlugin, jwt } from "@routecraft/ai";
+ *
+ * // HMAC (symmetric) - shared secret
+ * mcpPlugin({
+ *   transport: "http",
+ *   auth: jwt({ secret: process.env.JWT_SECRET! }),
+ * });
+ *
+ * // RSA (asymmetric) - public key only
+ * mcpPlugin({
+ *   transport: "http",
+ *   auth: jwt({ algorithm: "RS256", publicKey: process.env.JWT_PUBLIC_KEY! }),
+ * });
+ * ```
+ *
+ * @experimental
+ */
+declare function jwt(options: JwtAuthOptions): McpHttpAuthOptions;
+
 /**
  * MCP plugin: one plugin per adapter. Starts the MCP server during plugin apply (before routes start) so startup failures fail context build. Exposes mcp() routes to external MCP clients.
  * Optional clients: register named remote MCP servers so routes can use .to(mcp("name:tool")) without passing url.
@@ -625,6 +910,8 @@ declare class McpServer {
     private transport;
     /** Node HTTP server when transport is http; used to listen on port and close on stop. */
     private httpServer;
+    /** Active HTTP sessions keyed by session ID (each session has its own server+transport pair). */
+    private httpSessions;
     private running;
     private toolsListLogged;
     constructor(context: CraftContext, options?: McpPluginOptions);
@@ -638,8 +925,10 @@ declare class McpServer {
     private startStdio;
     /**
      * Start HTTP transport (streamable-http).
-     * The SDK transport does not create or listen on a port; we create a Node HTTP server
-     * and call transport.handleRequest(req, res) for each request to /mcp.
+     * Creates a Node HTTP server that manages per-session MCP server+transport pairs.
+     * Each client session (identified by the `mcp-session-id` header) gets its own
+     * Server and StreamableHTTPServerTransport so that reconnecting clients can
+     * establish fresh sessions without restarting the process.
      */
     private startHttp;
     /**
@@ -647,10 +936,19 @@ declare class McpServer {
      */
     getHttpPort(): number | undefined;
     /**
-     * Set up request handlers (shared by both transports).
-     * Uses SDK request schemas so setRequestHandler receives a proper schema (method literal).
+     * Validate the Authorization header using the configured validator.
+     * Returns the authenticated principal on success, or `null` to reject with 401.
+     */
+    private validateAuth;
+    /**
+     * Set up request handlers on this.server (used by stdio transport).
      */
     private setupRequestHandlers;
+    /**
+     * Set up request handlers on the given server instance.
+     * Uses SDK request schemas so setRequestHandler receives a proper schema (method literal).
+     */
+    private setupRequestHandlersOn;
     /**
      * Stop the MCP server
      */
@@ -857,4 +1155,4 @@ declare function embeddingPlugin(options?: EmbeddingPluginOptions): CraftPlugin;
  */
 declare function disposeEmbeddingPipelineCache(): Promise<void>;
 
-export { ADAPTER_LLM_OPTIONS, ADAPTER_LLM_PROVIDERS, ADAPTER_MCP_CLIENT_SERVERS, AgentDestinationAdapter, type AgentModelId, type AgentOptions, type AgentPromptSource, type AgentResult, BRAND, BRAND_MCP_ADAPTER, EmbeddingDestinationAdapter, type EmbeddingModelConfig, type EmbeddingModelConfigHuggingFace, type EmbeddingModelConfigOllama, type EmbeddingModelConfigOpenAI, type EmbeddingModelId, type EmbeddingOptions, type EmbeddingPluginOptions, type EmbeddingPluginProviders, type EmbeddingProviderType, type EmbeddingResult, type LlmAnthropicProviderOptions, LlmDestinationAdapter, type LlmGeminiProviderOptions, type LlmModelConfig, type LlmModelConfigAnthropic, type LlmModelConfigGemini, type LlmModelConfigOllama, type LlmModelConfigOpenAI, type LlmModelConfigOpenRouter, type LlmModelId, type LlmOllamaProviderOptions, type LlmOpenAIProviderOptions, type LlmOpenRouterProviderOptions, type LlmOptions, type LlmPluginOptions, type LlmPluginProviders, type LlmPromptSource, type LlmProviderRegistry, type LlmProviderType, type LlmResult, type LlmUsage, MCP_PLUGIN_REGISTERED, MCP_STDIO_MANAGERS, MCP_TOOL_REGISTRY, type McpArgsExtractor, type McpClientHttpConfig, type McpClientOptions, type McpClientServerConfig, type McpClientStdioConfig, type McpMessage, type McpOptions, type McpPluginOptions, McpServer, type McpServerOptions, type McpServerRegistry, type McpTool, McpToolRegistry, type McpToolRegistryEntry, type McpToolResult, type RegisteredLlmModelId, type RegisteredMcpServer, type RegisteredMcpShorthand, agent, defaultArgs, disposeEmbeddingPipelineCache, embedding, embeddingPlugin, isMcpAdapter, llm, llmPlugin, mcp, mcpPlugin, validateLlmPluginOptions, validateWithSchema };
+export { ADAPTER_LLM_OPTIONS, ADAPTER_LLM_PROVIDERS, ADAPTER_MCP_CLIENT_SERVERS, AgentDestinationAdapter, type AgentModelId, type AgentOptions, type AgentPromptSource, type AgentResult, type AuthPrincipal, BRAND, BRAND_MCP_ADAPTER, EmbeddingDestinationAdapter, type EmbeddingModelConfig, type EmbeddingModelConfigHuggingFace, type EmbeddingModelConfigOllama, type EmbeddingModelConfigOpenAI, type EmbeddingModelId, type EmbeddingOptions, type EmbeddingPluginOptions, type EmbeddingPluginProviders, type EmbeddingProviderType, type EmbeddingResult, type JwtAuthOptions, type JwtHmacOptions, type JwtRsaOptions, type LlmAnthropicProviderOptions, LlmDestinationAdapter, type LlmGeminiProviderOptions, type LlmModelConfig, type LlmModelConfigAnthropic, type LlmModelConfigGemini, type LlmModelConfigOllama, type LlmModelConfigOpenAI, type LlmModelConfigOpenRouter, type LlmModelId, type LlmOllamaProviderOptions, type LlmOpenAIProviderOptions, type LlmOpenRouterProviderOptions, type LlmOptions, type LlmPluginOptions, type LlmPluginProviders, type LlmPromptSource, type LlmProviderRegistry, type LlmProviderType, type LlmResult, type LlmUsage, MCP_PLUGIN_REGISTERED, MCP_STDIO_MANAGERS, MCP_TOOL_REGISTRY, type McpArgsExtractor, type McpAuthValidator, type McpClientAuthOptions, type McpClientHttpConfig, type McpClientOptions, type McpClientServerConfig, type McpClientStdioConfig, type McpClientTokenProvider, McpHeadersKeys, type McpHttpAuthOptions, type McpMessage, type McpOptions, type McpPluginOptions, McpServer, type McpServerOptions, type McpServerRegistry, type McpTool, McpToolRegistry, type McpToolRegistryEntry, type McpToolResult, type RegisteredLlmModelId, type RegisteredMcpServer, type RegisteredMcpShorthand, agent, defaultArgs, disposeEmbeddingPipelineCache, embedding, embeddingPlugin, isMcpAdapter, jwt, llm, llmPlugin, mcp, mcpPlugin, validateLlmPluginOptions, validateWithSchema };