@fitzzero/quickdraw-core 5.1.1 → 5.1.3

package/dist/server/mcp/index.js

@@ -3,34 +3,51 @@ import {
 } from "../../chunk-XNLWBZIG.js";
 import {
   NEVER_ABORTED,
+  callerGrantsOf,
+  checkKind,
+  inputKeys,
   lazyMembers,
+  narrowKinds,
   parseInput,
-  toQuickdrawError
-} from "../../chunk-2PWMUVC7.js";
+  pointerToken,
+  referenced,
+  runtimeOf,
+  toQuickdrawError,
+  withCallerGrants
+} from "../../chunk-OCZJ4EYV.js";
 import {
   describeError
-} from "../../chunk-DD4SKCNO.js";
+} from "../../chunk-RZXJTDH5.js";
 import {
+  originAllowlist
+} from "../../chunk-NO4M6PO5.js";
+import {
+  isForbiddenCredential,
   isJsonRequest,
+  isPrincipal,
+  isRefusal,
   readJsonInput,
   toPrincipal,
   unreadable
-} from "../../chunk-REX5YPHX.js";
-import "../../chunk-H23KEFBA.js";
+} from "../../chunk-PHCURHC7.js";
+import "../../chunk-DUBU3BB3.js";
+import "../../chunk-AK23XSWD.js";
+import {
+  consoleLogger
+} from "../../chunk-DKE6QO26.js";
 import {
   hasJsonSchema,
   isStandardSchema
 } from "../../chunk-47AEXVDM.js";
-import "../../chunk-Z2LZ7IZ7.js";
-import {
-  consoleLogger
-} from "../../chunk-YSWH776Y.js";
+import "../../chunk-SN3OZVEQ.js";
+import "../../chunk-7Y5ROPXL.js";
 import {
   INTERNAL_MESSAGE,
   QuickdrawError,
   httpStatus,
   toWire
-} from "../../chunk-4YO5H5ON.js";
+} from "../../chunk-Q4OGQM5I.js";
+import "../../chunk-QSU47XEX.js";
 
 // src/server/mcp/tools.ts
 var JSON_SCHEMA_TARGET = "draft-07";
@@ -72,20 +89,72 @@ function toolInputOf(label, schema, fail, instead = `leave ${label} out with exc
       `the input schema of ${label} cannot be written as JSON Schema (${json.message}): change that schema, or ${instead}`
     );
   }
-  if (json.type === "object") {
-    return { schema: json, mode: "object" };
+  const described = referenced(json, json);
+  if (described?.type === "object") {
+    return { schema: inlined(json, described), mode: "object" };
   }
-  const { $schema: dialect, ...input } = json;
+  const { $schema: dialect, definitions, $defs, ...input } = json;
   return {
     schema: {
       ...dialect === void 0 ? {} : { $schema: dialect },
       type: "object",
-      properties: { input },
-      ...acceptsUndefined(schema) ? {} : { required: ["input"] }
+      properties: { input: rerooted(input) },
+      ...acceptsUndefined(schema) ? {} : { required: ["input"] },
+      ...definitions === void 0 ? {} : { definitions: rerooted(definitions) },
+      ...$defs === void 0 ? {} : { $defs: rerooted($defs) }
     },
     mode: "wrapped"
   };
 }
+var WRAPPED_INPUT = "#/properties/input";
+function rerooted(value) {
+  if (Array.isArray(value)) {
+    return value.map(rerooted);
+  }
+  if (!isRecord(value)) {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => {
+      const intoRoot = key === "$ref" && typeof item === "string" && (item === "#" || item.startsWith("#/") && !/^#\/(?:definitions|\$defs)\//u.test(item));
+      return [key, intoRoot ? `${WRAPPED_INPUT}${item.slice(1)}` : rerooted(item)];
+    })
+  );
+}
+function refersTo(value, ref) {
+  if (Array.isArray(value)) {
+    return value.some((item) => refersTo(item, ref));
+  }
+  if (!isRecord(value)) {
+    return false;
+  }
+  return value.$ref === ref || Object.values(value).some((item) => refersTo(item, ref));
+}
+function inlined(json, target) {
+  if (target === json) {
+    return json;
+  }
+  const ref = String(json.$ref);
+  const { $schema: dialect } = json;
+  const schema = {
+    ...dialect === void 0 ? {} : { $schema: dialect },
+    ...target
+  };
+  for (const keyword of ["definitions", "$defs"]) {
+    const defs = json[keyword];
+    if (!isRecord(defs)) {
+      continue;
+    }
+    const others = Object.fromEntries(
+      Object.entries(defs).filter(([name]) => `#/${keyword}/${pointerToken(name)}` !== ref)
+    );
+    const kept = refersTo({ ...schema, [keyword]: others }, ref) ? defs : others;
+    if (Object.keys(kept).length > 0) {
+      schema[keyword] = kept;
+    }
+  }
+  return schema;
+}
 function inputOf(mode, args) {
   if (mode === "object") {
     return args ?? {};
@@ -139,35 +208,19 @@ function describeMethod(service, method, kind, text) {
 function propertiesOf(schema) {
   return isRecord(schema) && isRecord(schema.properties) ? Object.keys(schema.properties) : [];
 }
-function branchProperties(schema, found = /* @__PURE__ */ new Set()) {
-  if (!isRecord(schema)) {
-    return found;
-  }
-  for (const keyword of ["anyOf", "oneOf", "allOf"]) {
-    const branches = schema[keyword];
-    for (const branch of Array.isArray(branches) ? branches : []) {
-      for (const key of propertiesOf(branch)) {
-        found.add(key);
-      }
-      branchProperties(branch, found);
-    }
-  }
-  return found;
-}
-function boundArguments(label, input, bind, fail) {
-  if (input.mode === "object") {
-    const properties = propertiesOf(input.schema);
-    return bind.filter((key) => properties.includes(key));
+function boundArguments(label, input, schema, bind, fail) {
+  if (bind.length === 0) {
+    return [];
   }
-  const wrapped = input.schema.properties?.input;
-  const unbindable = branchProperties(wrapped, new Set(propertiesOf(wrapped)));
-  const misplaced = bind.find((key) => unbindable.has(key));
+  const bindable = input.mode === "object" ? propertiesOf(input.schema) : [];
+  const keys = inputKeys(schema) ?? [];
+  const misplaced = bind.find((key) => keys.includes(key) && !bindable.includes(key));
   if (misplaced !== void 0) {
     fail(
-      `bind.${misplaced} names a property of the input of ${label}, which is not an object: bind fills properties of object inputs only; leave ${label} out with exclude, or make its input an object`
+      `bind.${misplaced} names a property of the input of ${label}, which is not an object: bind fills properties of object inputs only (an object schema, or one with .meta({ id }); not a union, an intersection, or a schema made from an object, as .optional() or .refine() make); leave ${label} out with exclude, or make its input an object`
     );
   }
-  return [];
+  return bind.filter((key) => bindable.includes(key));
 }
 function withoutArguments(schema, bound) {
   const kept = (key) => !bound.includes(key);
@@ -194,7 +247,7 @@ function planMethodTools(services, options, fail, bind = []) {
       }
       const label = `${service.name}.${method}`;
       const input = toolInputOf(label, def.input, fail);
-      const bound = boundArguments(label, input, bind, fail);
+      const bound = boundArguments(label, input, def.input, bind, fail);
       const tool = {
         name: toolName(service.name, method),
         description: describeMethod(service.name, method, def.kind, def.describe),
@@ -228,6 +281,46 @@ function describeTools(services, options = {}) {
   return planned.map((entry2) => entry2.tool);
 }
 
+// src/server/mcp/lanes.ts
+import { createHash } from "crypto";
+import { isIPv6 } from "net";
+function groupsOf(address) {
+  const written = new URL(`http://[${address}]/`).hostname.slice(1, -1);
+  const [head = "", tail = ""] = written.split("::");
+  const parse2 = (part) => part === "" ? [] : part.split(":").map((group) => Number.parseInt(group, 16));
+  const before = parse2(head);
+  const after = parse2(tail);
+  return [...before, ...new Array(8 - before.length - after.length).fill(0), ...after];
+}
+function addressLane(ip) {
+  const address = ip.split("%", 1)[0] ?? ip;
+  if (!isIPv6(address)) {
+    return ip;
+  }
+  const [a = 0, b = 0, c = 0, d = 0, e = 0, f = 0, g = 0, h = 0] = groupsOf(address);
+  if (a === 0 && b === 0 && c === 0 && d === 0 && e === 0 && f === 65535) {
+    return [g >> 8, g & 255, h >> 8, h & 255].join(".");
+  }
+  return `${[a, b, c, d & 65280].map((group) => group.toString(16)).join(":")}::/56`;
+}
+function addressOf(request) {
+  const { ip } = request.req;
+  return typeof ip === "string" && ip !== "" ? ip : request.req.socket?.remoteAddress ?? "unknown";
+}
+function laneOf(request, principal) {
+  if (request.transport === "stdio") {
+    return `mcp:${request.sessionId}`;
+  }
+  if (principal === null) {
+    return `mcp:http:address:${addressLane(addressOf(request))}`;
+  }
+  if (request.token === null) {
+    return `mcp:http:user:${principal.userId}`;
+  }
+  const hash = createHash("sha256").update(request.token).digest("base64url").slice(0, 22);
+  return `mcp:http:token:${hash}`;
+}
+
 // src/server/mcp/session.ts
 var CATEGORY = "quickdraw.mcp";
 async function principalOf(settings, request) {
@@ -237,7 +330,8 @@ async function principalOf(settings, request) {
   try {
     return toPrincipal(await settings.principal(request));
   } catch (error) {
-    settings.logger.error("MCP authentication failed", {
+    const refused = isRefusal(error) || isForbiddenCredential(error);
+    settings.logger[refused ? "debug" : "error"]("MCP authentication failed", {
       category: CATEGORY,
       transport: request.transport,
       error: describeError(error)
@@ -258,10 +352,22 @@ async function contextOf(settings, request, principal) {
   }
   return fields;
 }
-async function openSession(settings, request) {
-  const principal = await principalOf(settings, request);
+function givenPrincipal(principal) {
+  if (principal === null || principal === void 0) {
+    return null;
+  }
+  if (!isPrincipal(principal)) {
+    throw new TypeError(
+      "An MCP call's principal must be a principal with a non-empty string userId, or null"
+    );
+  }
+  return principal;
+}
+async function openSession(settings, options) {
+  const { request } = options;
+  const principal = Object.hasOwn(options, "principal") ? await withCallerGrants(givenPrincipal(options.principal), callerGrantsOf(settings.dispatcher)) : await principalOf(settings, request);
   const mcp = await contextOf(settings, request, principal);
-  return { principal, mcp, connectionId: `mcp:${request.sessionId}` };
+  return { principal, mcp, connectionId: laneOf(request, principal) };
 }
 function failure(settings, error, tool) {
   const converted = toQuickdrawError(error);
@@ -342,7 +448,26 @@ function accessOf(owner, access, fail) {
   }
   return access;
 }
-function checkCustomTool(value, index, fail) {
+function appKindsOf(services) {
+  let kinds;
+  for (const service of services) {
+    const own = runtimeOf(service)?.kinds;
+    if (own !== void 0) {
+      kinds = kinds === void 0 ? own : kinds.filter((kind) => own.includes(kind));
+    }
+  }
+  return kinds;
+}
+function kindsOf(owner, value, access, appKinds, fail) {
+  if (value.kinds !== void 0 && access === "public") {
+    fail(
+      `${owner}: a "public" tool takes no kinds of its own, since a caller of a refused kind could call it signed out; give it access "authenticated"`
+    );
+  }
+  const above = appKinds === void 0 ? void 0 : { kinds: appKinds, by: "initQuickdraw" };
+  return narrowKinds(value.kinds, above, (message) => fail(`${owner}: ${message}`));
+}
+function checkCustomTool(value, index, appKinds, fail) {
   if (!isRecord2(value)) {
     fail(`customTools[${index}] must be { name, description, inputSchema, handler }`);
   }
@@ -361,6 +486,7 @@ function checkCustomTool(value, index, fail) {
     fail(`${owner}: annotations must be an object of hints`);
   }
   const access = accessOf(owner, value.access, fail);
+  const kinds = kindsOf(owner, value, access, appKinds, fail);
   const input = argumentsOf(owner, inputSchema, fail);
   const tool = {
     name,
@@ -371,19 +497,26 @@ function checkCustomTool(value, index, fail) {
   return {
     tool: Object.freeze(tool),
     access,
+    kinds,
     mode: input.mode,
     schema: isStandardSchema(inputSchema) ? inputSchema : void 0,
     handler
   };
 }
-function checkCustomTools(value, fail) {
+function checkCustomTools(value, fail, services = []) {
   if (value === void 0) {
     return [];
   }
   if (!Array.isArray(value)) {
     fail("customTools must be an array of { name, description, inputSchema, handler }");
   }
-  return value.map((tool, index) => checkCustomTool(tool, index, fail));
+  const appKinds = appKindsOf(services);
+  if (appKinds?.length === 0 && value.length > 0) {
+    fail(
+      "customTools: the served services' apps admit no kind in common (initQuickdraw({ kinds })), so no principal could call a custom tool: serve custom tools beside the services of one app, or of apps that admit a kind in common"
+    );
+  }
+  return value.map((tool, index) => checkCustomTool(tool, index, appKinds, fail));
 }
 async function runCustomTool(settings, custom, args, session, options) {
   const { name } = custom.tool;
@@ -392,6 +525,7 @@ async function runCustomTool(settings, custom, args, session, options) {
     if (custom.access === "authenticated" && session.principal === null) {
       throw new QuickdrawError("UNAUTHENTICATED", "Authentication required");
     }
+    checkKind(custom.kinds, session.principal, `The tool "${name}"`);
     const input = inputOf(custom.mode, args);
     const parsed = custom.schema === void 0 ? input : await parseInput(custom.schema, input, `the tool "${name}"`);
     const data = await custom.handler({
@@ -475,7 +609,7 @@ function resolveRegistry(options) {
   const binders = checkBinders(options.bind, fail);
   const methodTools = planMethodTools(options.services, options, fail, [...binders.keys()]);
   checkBound(binders, methodTools, fail);
-  const customTools = checkCustomTools(options.customTools, fail);
+  const customTools = checkCustomTools(options.customTools, fail, options.services);
   const entries = [
     ...methodTools.map((tool) => ({ kind: "method", ...tool })),
     ...customTools.map((tool) => ({ kind: "custom", ...tool }))
@@ -500,7 +634,7 @@ function resolveRegistry(options) {
 async function inSession(settings, name, options, run) {
   let session;
   try {
-    session = await openSession(settings, options.request);
+    session = await openSession(settings, options);
   } catch (error) {
     return settle(settings, options, failure(settings, error, name));
   }
@@ -545,6 +679,16 @@ async function bindInput(settings, tool, input, session, request) {
   return { ...given, ...Object.fromEntries(filled) };
 }
 async function dispatchMethod(settings, tool, input, session, options) {
+  const stray = settings.binders.size === 0 || !isRecord3(input) || Array.isArray(input) ? void 0 : [...settings.binders.keys()].find(
+    (key) => !tool.bound.includes(key) && Object.hasOwn(input, key)
+  );
+  if (stray !== void 0) {
+    const error = new QuickdrawError(
+      "FORBIDDEN",
+      `"${stray}" is bound to the caller; ${tool.service}.${tool.method} does not take it from the agent`
+    );
+    return settle(settings, options, failure(settings, error, tool.tool.name));
+  }
   let bound = input;
   if (tool.bound.length > 0) {
     try {
@@ -894,8 +1038,81 @@ async function bootstrapMcpServer(serverModule) {
   }
 }
 
-// src/server/mcp/http.ts
+// src/server/mcp/httpRequest.ts
 import { randomUUID as randomUUID2 } from "crypto";
+function requestOf(req) {
+  const header = req.headers.authorization;
+  const token = typeof header === "string" && header.startsWith("Bearer ") ? header.slice(7) : "";
+  return {
+    transport: "http",
+    sessionId: randomUUID2(),
+    token: token.trim() === "" ? null : token.trim(),
+    headers: req.headers,
+    req
+  };
+}
+function hostOf(value) {
+  if (/\s/u.test(value)) {
+    return void 0;
+  }
+  const host = !value.startsWith("[") && value.split(":").length > 2 ? `[${value}]` : value;
+  let url;
+  try {
+    url = new URL(`http://${host}`);
+  } catch {
+    return void 0;
+  }
+  const extra = url.username + url.password + url.search + url.hash;
+  if (url.hostname === "" || extra !== "" || url.pathname !== "/") {
+    return void 0;
+  }
+  const written = !host.endsWith("]") && /:\d+$/u.test(host);
+  return { hostname: url.hostname, port: written ? url.port || "80" : void 0 };
+}
+function checkHosts(hosts) {
+  if (hosts === void 0) {
+    return void 0;
+  }
+  const parsed = Array.isArray(hosts) ? hosts.map((host) => typeof host === "string" ? hostOf(host) : void 0) : [];
+  if (parsed.length === 0 || parsed.includes(void 0)) {
+    throw new TypeError(
+      'createMcpHttpRouter: allowedHosts must list host names, such as "localhost" or "mcp.example.com:8443"'
+    );
+  }
+  return Object.freeze(parsed);
+}
+function hostAllowed(hosts, header) {
+  const host = header === void 0 ? void 0 : hostOf(header);
+  if (host === void 0) {
+    return false;
+  }
+  const portMatches = (port) => host.port === void 0 ? port === "80" || port === "443" : port === host.port;
+  return hosts.some(
+    (entry2) => entry2.hostname === host.hostname && (entry2.port === void 0 || portMatches(entry2.port))
+  );
+}
+function requestGate(allowedOrigins, allowedHosts) {
+  const origins = originAllowlist(
+    allowedOrigins ?? [],
+    "createMcpHttpRouter",
+    true
+  );
+  const hosts = checkHosts(allowedHosts);
+  return Object.freeze({
+    refusal(req) {
+      const { origin, host } = req.headers;
+      if (origin !== void 0 && origins.allowed(origin) === null) {
+        return "The MCP routes refuse requests from web pages unless allowedOrigins lists their origin";
+      }
+      if (hosts !== void 0 && !hostAllowed(hosts, host)) {
+        return "The MCP routes do not answer for this host";
+      }
+      return void 0;
+    }
+  });
+}
+
+// src/server/mcp/http.ts
 var DEFAULT_MAX_BODY_BYTES = 1048576;
 var CATEGORY3 = "quickdraw.mcp";
 var NOT_JSON = "Send the call as a JSON body with Content-Type: application/json";
@@ -922,6 +1139,8 @@ function send(res, status, body) {
   res.statusCode = status;
   res.setHeader("content-type", "application/json; charset=utf-8");
   res.setHeader("content-length", bytes);
+  res.setHeader("cache-control", "no-store");
+  res.setHeader("x-content-type-options", "nosniff");
   res.end(body);
   return bytes;
 }
@@ -962,17 +1181,6 @@ function targetOf(body) {
   }
   return void 0;
 }
-function requestOf(req) {
-  const header = req.headers.authorization;
-  const token = typeof header === "string" && header.startsWith("Bearer ") ? header.slice(7) : "";
-  return {
-    transport: "http",
-    sessionId: randomUUID2(),
-    token: token.trim() === "" ? null : token.trim(),
-    headers: req.headers,
-    req
-  };
-}
 async function invoke(settings, req, res) {
   const controller = new AbortController();
   res.once("close", () => {
@@ -1022,7 +1230,8 @@ function resolveSettings(options) {
     registry: options.registry,
     prefix: normalizePath(options.path ?? "/mcp"),
     maxBodyBytes,
-    logger: options.logger ?? consoleLogger
+    logger: options.logger ?? consoleLogger,
+    gate: requestGate(options.allowedOrigins, options.allowedHosts)
   };
 }
 function createMcpHttpRouter(options) {
@@ -1037,6 +1246,16 @@ function createMcpHttpRouter(options) {
       }
       return;
     }
+    const refusal = settings.gate.refusal(req);
+    if (refusal !== void 0) {
+      settings.logger.debug("An MCP HTTP request was refused", {
+        category: CATEGORY3,
+        origin: req.headers.origin,
+        host: req.headers.host
+      });
+      sendResult(settings, res, failure2(new QuickdrawError("FORBIDDEN", refusal)));
+      return;
+    }
     if (route === "tools") {
       send(res, 200, JSON.stringify({ tools: settings.registry.tools }));
       return;