@fitzzero/quickdraw-core 5.1.1 → 5.1.3

package/dist/server/mcp/index.d.ts

@@ -1,14 +1,15 @@
-import { A as AnyService, d as Caller } from '../../caller-CXTFswBO.js';
+import { A as AnyService, d as Caller } from '../../caller-BTwGl7vm.js';
 import { IncomingHttpHeaders, IncomingMessage } from 'node:http';
-import { ap as MethodName, d as StandardSchemaV1, c as InferOutput } from '../../infer-Teo1xpsd.js';
+import { ap as MethodName, d as StandardSchemaV1, c as InferOutput } from '../../infer-Br62cnyW.js';
 import { Q as QuickdrawError, a as ErrorCode } from '../../errors-S-bxEIBC.js';
-import { P as PrincipalOfServices, C as ContractOfServices, D as Dispatcher, H as HttpRouter } from '../../http-Djj2Inuu.js';
-import { a as McpContext, b as McpContextOf, M as MaybePromise } from '../../types-Cu0vmx7c.js';
-import { L as Logger } from '../../logger-BY28acW-.js';
-import { A as AuthenticateResult } from '../../auth-BhWqdyb-.js';
+import { P as PrincipalOfServices, M as McpContextOfServices, C as ContractOfServices, D as Dispatcher, H as HttpRouter } from '../../http-YzLAar3w.js';
+import { M as MaybePromise, P as Principal } from '../../types-CLRCQGnO.js';
+import { L as Logger } from '../../logger-Yz93KzdV.js';
+import { A as AuthenticateResult } from '../../auth-DtdYjrZ9.js';
 import { Readable, Writable } from 'node:stream';
-import '../../envelope-Cp3YcVxC.js';
-import '../../metrics-BdBu5o8G.js';
+import { A as AllowedOrigin } from '../../origins-kvpxnVcW.js';
+import '../../envelope-BMBaxppV.js';
+import '../../metrics-CTVpw0gu.js';
 import 'socket.io';
 
 /** The JSON Schema of a tool's arguments. MCP requires an object schema. */
@@ -55,7 +56,12 @@ interface McpStdioRequest {
     /** The session's id. Every call of the server carries the same one. */
     readonly sessionId: string;
 }
-/** What one request to the MCP HTTP routes stands for. Each request is a session of its own. */
+/**
+ * What one request to the MCP HTTP routes stands for. Each request is a
+ * session of its own, and its queries share its caller's concurrency lane:
+ * its bearer token's, its user's without a token, or its address's when
+ * anonymous.
+ */
 interface McpHttpRequest {
     readonly transport: "http";
     readonly sessionId: string;
@@ -66,8 +72,7 @@ interface McpHttpRequest {
 }
 /** The session or request a tool call arrives on, as the registry's `principal` and `context` see it. */
 type McpRequest = McpStdioRequest | McpHttpRequest;
-/** The type of `ctx.mcp` for the services of `S`: their app's `QuickdrawTypes["mcp"]`. */
-type McpContextOfServices<S extends readonly AnyService[]> = [S[number]] extends [never] ? McpContext : McpContextOf<NonNullable<S[number]["~types"]>>;
+
 /** How a tool call ended: what the tool returned, or why it failed. */
 type McpCallResult = {
     readonly ok: true;
@@ -93,6 +98,18 @@ interface McpToolResult {
 interface McpCallOptions {
     /** The session or request the call arrived on. */
     readonly request: McpRequest;
+    /**
+     * Who the call acts for, when the app signed the caller in itself (its own
+     * MCP transport over `callMethod`, an in-process assistant): the
+     * registry's `principal` hook is not asked. `null` calls anonymously, and
+     * so does `undefined`: the hook is asked only when the key is absent. The
+     * `context` hook, bound arguments and the call's concurrency lane see this
+     * principal. One that carries no `serviceAccess` gets the grants the
+     * server's `auth.loadServiceAccess` loads, at each call, as `qd.caller`
+     * gives them; one that carries grants (`{}` included) keeps them. An
+     * in-process option: the HTTP routes never read it from a request.
+     */
+    readonly principal?: Principal | null;
     /** Cancels the call. Only queries stop early; a mutation runs to its end. */
     readonly signal?: AbortSignal;
     /**
@@ -119,8 +136,9 @@ interface McpToolCall<S extends readonly AnyService[] = readonly AnyService[], A
      */
     readonly arguments: Args;
     /**
-     * Who the call acts for, from the registry's `principal`. `null` only for
-     * an anonymous caller of a tool with `access: "public"`.
+     * Who the call acts for, from the registry's `principal` hook or the
+     * call's own `principal` option. `null` only for an anonymous caller of a
+     * tool with `access: "public"`.
      */
     readonly principal: PrincipalOfServices<S> | null;
     /** The fields the registry's `context` produced for the call, if any. */
@@ -176,6 +194,14 @@ interface McpCustomTool<S extends readonly AnyService[] = readonly AnyService[],
      * `"public"` lets anonymous callers in, with `principal: null`.
      */
     readonly access?: McpToolAccess;
+    /**
+     * The kinds of principal (`principal.kind`) that may call the tool, within
+     * the ones the app's `initQuickdraw({ kinds })` admits, which it admits by
+     * default: a caller of another kind gets `FORBIDDEN` before the arguments
+     * are read or the handler runs. A `"public"` tool takes none of its own (a
+     * caller of a refused kind could call it signed out).
+     */
+    readonly kinds?: readonly NonNullable<PrincipalOfServices<S>["kind"]>[];
     /**
      * The tool's arguments. A Standard Schema that can describe itself as JSON
      * Schema (Zod 4.2 or later) validates them before the handler runs; a JSON
@@ -219,7 +245,15 @@ interface McpRegistryOptions<S extends readonly AnyService[], Tools extends read
      * anonymous caller, who may call `"public"` methods and `"public"` custom
      * tools only. A stdio server usually reads a token from its environment;
      * an HTTP request carries one as a bearer token. Throwing fails the call
-     * with `UNAUTHENTICATED`. Without it every call is anonymous.
+     * with `UNAUTHENTICATED`: throw `QuickdrawError("UNAUTHENTICATED")` (or
+     * `FORBIDDEN`) to refuse a token, which is logged at debug, and never put
+     * the token in a message; anything else thrown is logged as an error.
+     * Without it every call is anonymous. An HTTP request's queries share the
+     * lane of its bearer token: a hook that authenticates by anything else (a
+     * cookie, an API key header) must refuse a request whose bearer token it
+     * does not verify, or a caller makes a lane per made-up token. A call
+     * whose options give `principal` (an app that signed the caller in
+     * itself) is not asked about.
      */
     readonly principal?: (request: McpRequest) => MaybePromise<AuthenticateResult<PrincipalOfServices<S>>>;
     /**
@@ -237,10 +271,15 @@ interface McpRegistryOptions<S extends readonly AnyService[], Tools extends read
      * before the method runs when the caller is anonymous (`UNAUTHENTICATED`),
      * or when the binder returns `undefined` or `null` or the caller sent the
      * argument with another value (`FORBIDDEN`); a binder that throws fails it
-     * with `INTERNAL`, or with the code of a `QuickdrawError`. Custom tools are
-     * never bound. Binding is not access control: the same principal reaches
-     * the method over a socket or HTTP with nothing bound, so the method's
-     * access must still confine it.
+     * with `INTERNAL`, or with the code of a `QuickdrawError`. A call of any
+     * other method's tool that sends a bound argument is refused (`FORBIDDEN`).
+     * An input that is a `$ref` to an object counts as that object, and a
+     * bound key anywhere else in an input (in a union's or an intersection's
+     * branch, or an input that is no object) fails when the registry is built.
+     * Only top-level arguments are bound. Custom tools are never bound.
+     * Binding is not access control: the same principal reaches the method
+     * over a socket or HTTP with nothing bound, so the method's access must
+     * still confine it.
      */
     readonly bind?: Readonly<Record<string, McpBinder<S>>>;
     /** The app's own tools, listed after the generated ones. */
@@ -264,16 +303,18 @@ interface McpRegistry {
     has(name: string): boolean;
     /**
      * Calls the tool `name` with the client's `args` in the session of
-     * `options.request`. Resolves with the tool's value or its failure (an
-     * unknown name is `NOT_FOUND`), after `options.respond` was given it.
-     * Never rejects.
+     * `options.request`, as `options.principal` when it is given. Resolves
+     * with the tool's value or its failure (an unknown name is `NOT_FOUND`),
+     * after `options.respond` was given it. Never rejects.
      */
     call(name: string, args: unknown, options: McpCallOptions): Promise<McpCallResult>;
     /**
      * Calls a method's tool by its service and method name with the method's
      * `input` as it is, without the tool's argument mapping: the shape 4.1's
-     * HTTP route took. Bound arguments are filled as for `call`. A method that
-     * is not a tool is `NOT_FOUND`.
+     * HTTP route took. Bound arguments are filled as for `call`, and
+     * `options.principal` says who calls as for `call`: an app's own MCP
+     * transport over it passes the caller it signed in. A method that is not
+     * a tool is `NOT_FOUND`.
      */
     callMethod(service: string, method: string, input: unknown, options: McpCallOptions): Promise<McpCallResult>;
 }
@@ -282,9 +323,14 @@ interface McpRegistry {
  * `customTools`, served by `dispatcher`. Throws at once when a method's
  * input schema cannot describe itself as JSON Schema (use Zod 4.2 or later
  * for it, or `exclude` the method), when two tools share a name, when the
- * dispatcher does not serve one of the services, or when an argument of
- * `bind` is in no tool's object input or is in an input that is not an
- * object.
+ * dispatcher does not serve one of the services, when an argument of
+ * `bind` is in no tool's object input or may be anywhere in an input where
+ * it cannot be filled (an input that is not an object schema, or a branch
+ * of a union or an intersection, behind a `$ref` too), or when custom tools
+ * are served beside the services of apps that admit no kind in common.
+ * Every call runs in its caller's concurrency lane: a stdio session, or on
+ * HTTP its bearer token, its user without a token, or its address when
+ * anonymous.
  *
  * @example
  * const registry = createMcpRegistry({
@@ -381,6 +427,22 @@ interface McpHttpRouterOptions {
     readonly maxBodyBytes?: number;
     /** Default: the console. */
     readonly logger?: Logger;
+    /**
+     * The web pages that may call the routes, by origin: exact origins
+     * (`"https://app.example.com"`) or patterns anchored with `^` and `$`, as
+     * `socketAuth` takes them. A request whose `Origin` is not listed gets 403;
+     * a request without one (an MCP client, a script) is not a page's and
+     * passes. Default: none, so no page may call them.
+     */
+    readonly allowedOrigins?: readonly AllowedOrigin[];
+    /**
+     * The `Host` names the routes answer for (`"localhost"`, `"127.0.0.1"`,
+     * `"mcp.example.com:8443"`; an entry without a port matches any port): a
+     * request for another gets 403. Set it for a server on a developer's
+     * machine or a LAN, where a page could reach it through DNS rebinding.
+     * Default: any host.
+     */
+    readonly allowedHosts?: readonly string[];
 }
 /** What `invoke` answers: 4.1's `{ success, data }`, or a failure's message, code and data. */
 type McpHttpReply = {
@@ -406,4 +468,4 @@ type McpHttpReply = {
  */
 declare function createMcpHttpRouter(options: McpHttpRouterOptions): HttpRouter;
 
-export { type DescribeToolsOptions, MCP_PROTOCOL_VERSION, type McpBindCall, type McpBinder, type McpCallOptions, type McpCallResult, type McpContextOfServices, type McpCustomTool, type McpHttpReply, type McpHttpRequest, type McpHttpRouterOptions, type McpInputSchema, type McpMethodRef, type McpRegistry, type McpRegistryOptions, type McpRequest, type McpStdioRequest, type McpStdioServer, type McpStdioServerOptions, type McpTextContent, type McpTool, type McpToolAccess, type McpToolAnnotations, type McpToolArguments, type McpToolCall, type McpToolInputSchema, type McpToolResult, bootstrapMcpServer, createMcpHttpRouter, createMcpRegistry, createMcpStdioServer, describeTools, toToolResult };
+export { type DescribeToolsOptions, MCP_PROTOCOL_VERSION, type McpBindCall, type McpBinder, type McpCallOptions, type McpCallResult, McpContextOfServices, type McpCustomTool, type McpHttpReply, type McpHttpRequest, type McpHttpRouterOptions, type McpInputSchema, type McpMethodRef, type McpRegistry, type McpRegistryOptions, type McpRequest, type McpStdioRequest, type McpStdioServer, type McpStdioServerOptions, type McpTextContent, type McpTool, type McpToolAccess, type McpToolAnnotations, type McpToolArguments, type McpToolCall, type McpToolInputSchema, type McpToolResult, bootstrapMcpServer, createMcpHttpRouter, createMcpRegistry, createMcpStdioServer, describeTools, toToolResult };