@nanobpm/urban 0.86.1 → 0.87.1

package/src/runtime/core/modules/mcp.test.ts

@@ -327,6 +327,159 @@ test("a projected tool's input schema matches the spec's params", async () => {
   });
 });
 
+test("a $ref-bodied tool projects a self-contained body schema (no $ref, explicit type)", async () => {
+  // createInvoice's requestBody is `{ $ref: "#/components/schemas/Invoice" }` — a bare $ref with no
+  // inline `type`. An MCP client cannot resolve `#/components/...` outside the document, so the
+  // projected tool schema MUST inline the concrete Invoice shape (ADR 0067). Regression guard for the
+  // leak that shipped an opaque `#/components/...` pointer into `inputSchema.properties.body`.
+  const { router } = buildHarness();
+  const session = await connect(router);
+  const list = await rpc(router, session, "tools/list", {});
+  const tools = list.result?.tools;
+  assert.ok(Array.isArray(tools));
+  const createInvoice = tools.find((t) => Reflect.get(t, "name") === "createInvoice");
+  assert.ok(createInvoice, "createInvoice must be present in tools/list before checking its schema");
+  const schema = Reflect.get(createInvoice, "inputSchema");
+  assert.deepEqual(schema, {
+    type: "object",
+    properties: {
+      body: {
+        type: "object",
+        properties: { id: { type: "string" }, amount: { type: "integer", minimum: 1 } },
+        required: ["id", "amount"],
+        additionalProperties: false,
+      },
+    },
+    required: ["body"],
+  });
+  // Self-containment holds structurally: the serialized schema carries no `$ref` token at all.
+  assert.ok(!JSON.stringify(schema).includes("$ref"), "projected body schema must not leak a $ref");
+});
+
+test("an object body reaches the door as an object; a pre-encoded JSON-string body is parsed, not double-encoded; a malformed string body is a clear error", async () => {
+  // `createInvoice`'s requestBody is `{ $ref: "#/components/schemas/Invoice" }` — an object body
+  // whose concrete `type` is only visible after the projection resolver inlines the component. The
+  // transport must classify it as an object body FROM THE RESOLVED SCHEMA (not the raw `$ref`) so the
+  // string-parse path triggers for exactly this motivating shape, not merely an inline-`type` body.
+  let seenBody: unknown = "unset";
+  const { router } = buildHarness({
+    modules: {
+      "/app/operations/createInvoice": {
+        default: (input: { body: unknown }) => {
+          seenBody = input.body;
+          return { body: { ok: true } };
+        },
+      },
+    },
+  });
+  const session = await connect(router);
+
+  // 1. A genuine object argument reaches the door (the reused delegate) AS AN OBJECT.
+  const objCall = await rpc(router, session, "tools/call", {
+    name: "createInvoice",
+    arguments: { body: { id: "7", amount: 3 } },
+  });
+  assert.notEqual(objCall.result?.isError, true, `object body call must succeed: ${toolContentText(objCall.result)}`);
+  assert.deepEqual(seenBody, { id: "7", amount: 3 }, "an object body argument must reach the door as an object");
+
+  // 2. A PRE-ENCODED JSON-string body is accepted and parsed — NOT double-encoded into a quoted
+  //    string the door would reject with "expected object, got string".
+  seenBody = "unset";
+  const strCall = await rpc(router, session, "tools/call", {
+    name: "createInvoice",
+    arguments: { body: JSON.stringify({ id: "9", amount: 5 }) },
+  });
+  assert.notEqual(strCall.result?.isError, true, `pre-encoded string body must be accepted: ${toolContentText(strCall.result)}`);
+  assert.deepEqual(seenBody, { id: "9", amount: 5 }, "a pre-encoded JSON-string body must be parsed to an object at the door");
+
+  // 3. A malformed string body is a CLEAR tool error naming the expected shape — never a silent 4xx
+  //    from a forwarded double-encoded body, and the delegate must not run.
+  seenBody = "unset";
+  const badCall = await rpc(router, session, "tools/call", {
+    name: "createInvoice",
+    arguments: { body: "{not valid json" },
+  });
+  assert.equal(badCall.result?.isError, true, "a malformed string body must return an isError result");
+  assert.match(toolContentText(badCall.result), /object/i, "the error must name the expected object shape");
+  assert.equal(seenBody, "unset", "the door delegate must not run for a malformed string body");
+
+  // 4. A string that parses to the WRONG shape (a scalar) is likewise a clear error, not a
+  //    double-encoded forward — the object body path fails loudly on a non-object.
+  seenBody = "unset";
+  const wrongShape = await rpc(router, session, "tools/call", {
+    name: "createInvoice",
+    arguments: { body: "42" },
+  });
+  assert.equal(wrongShape.result?.isError, true, "a string parsing to a scalar must return an isError result");
+  assert.match(toolContentText(wrongShape.result), /object/i, "the error must name the expected object shape");
+  assert.equal(seenBody, "unset", "the door delegate must not run for a wrong-shape string body");
+});
+
+test("an array body reaches the door as an array; a pre-encoded JSON-string array body is parsed, not double-encoded; a wrong-shape string is a clear error", async () => {
+  // Mirror of the object-body transport test for the ARRAY branch: `structuredBodyKind` can return
+  // "array" and `normalizeBodyArg` has an `Array.isArray(parsed)` path, so a regression in array
+  // handling must be caught here. `createBatch`'s requestBody declares a `type: array` body — the
+  // transport must classify it as an array body and parse a pre-encoded JSON-string array once so it
+  // round-trips as an array rather than being double-encoded into a quoted string the door rejects.
+  const arraySpec = JSON.stringify({
+    openapi: "3.0.0",
+    paths: {
+      "/batch": {
+        post: {
+          operationId: "createBatch",
+          requestBody: {
+            required: true,
+            content: { "application/json": { schema: { type: "array", items: { type: "string" } } } },
+          },
+          responses: { "201": {} },
+        },
+      },
+    },
+  });
+  let seenBody: unknown = "unset";
+  const { router } = buildHarness({
+    spec: arraySpec,
+    modules: {
+      "/app/operations/createBatch": {
+        default: (input: { body: unknown }) => {
+          seenBody = input.body;
+          return { body: { ok: true } };
+        },
+      },
+    },
+  });
+  const session = await connect(router);
+
+  // 1. A genuine array argument reaches the door (the reused delegate) AS AN ARRAY.
+  const arrCall = await rpc(router, session, "tools/call", {
+    name: "createBatch",
+    arguments: { body: ["a", "b"] },
+  });
+  assert.notEqual(arrCall.result?.isError, true, `array body call must succeed: ${toolContentText(arrCall.result)}`);
+  assert.deepEqual(seenBody, ["a", "b"], "an array body argument must reach the door as an array");
+
+  // 2. A PRE-ENCODED JSON-string array body is accepted and parsed — NOT double-encoded into a quoted
+  //    string the door would reject with "expected array, got string".
+  seenBody = "unset";
+  const strCall = await rpc(router, session, "tools/call", {
+    name: "createBatch",
+    arguments: { body: JSON.stringify(["a", "b"]) },
+  });
+  assert.notEqual(strCall.result?.isError, true, `pre-encoded string array body must be accepted: ${toolContentText(strCall.result)}`);
+  assert.deepEqual(seenBody, ["a", "b"], "a pre-encoded JSON-string array body must be parsed to an array at the door");
+
+  // 3. A string that parses to the WRONG shape (an object) is a clear error naming the expected
+  //    array shape, not a double-encoded forward — and the delegate must not run.
+  seenBody = "unset";
+  const wrongShape = await rpc(router, session, "tools/call", {
+    name: "createBatch",
+    arguments: { body: JSON.stringify({ not: "an array" }) },
+  });
+  assert.equal(wrongShape.result?.isError, true, "a string parsing to an object must return an isError result");
+  assert.match(toolContentText(wrongShape.result), /array/i, "the error must name the expected array shape");
+  assert.equal(seenBody, "unset", "the door delegate must not run for a wrong-shape string array body");
+});
+
 test("a tool call routes through the SAME mountApi delegate as the HTTP call", async () => {
   let seenParams: Record<string, unknown> | undefined;
   const { router, imported } = buildHarness({

package/src/runtime/core/modules/mcp.ts

@@ -50,11 +50,16 @@ import {
   collectOperations,
   evaluateSecurity,
   isMutatingMethod,
+  isObjectSchema,
   type OpenApiDoc,
+  type OpenApiSchema,
   type OperationInfo,
   parseSpec,
+  resolveSchema,
+  schemaHasType,
   type SecurityDecision,
   sharedSecretSchemeName,
+  toolInputSchema,
 } from "../../../openapi/spec.ts";
 import type { AppApi, RuntimeContext } from "../context.ts";
 import { errorMessage } from "../guards.ts";
@@ -250,26 +255,10 @@ function isMutatingOperation(op: OperationInfo): boolean {
   return isMutatingMethod(op.method);
 }
 
-/** A JSON Schema (OpenAPI object subset) describing a tool's input, derived from an operation's
- *  path/query parameters and its request-body schema. Keeping the property schemas verbatim from the
- *  spec means the tool input schema and the HTTP validation share one source of truth. */
-function toolInputSchema(op: OperationInfo): Record<string, unknown> {
-  const properties: Record<string, unknown> = {};
-  const required: string[] = [];
-  for (const p of op.parameters) {
-    if (p.in === "path" || p.in === "query") {
-      properties[p.name] = p.schema ?? {};
-      if (p.required) required.push(p.name);
-    }
-  }
-  if (op.requestBodySchema) {
-    properties.body = op.requestBodySchema;
-    if (op.requestBodyRequired) required.push("body");
-  }
-  const schema: Record<string, unknown> = { type: "object", properties };
-  if (required.length > 0) schema.required = required;
-  return schema;
-}
+/** A JSON Schema (OpenAPI object subset) describing a tool's input is derived once, in
+ *  `openapi/spec.ts`'s {@link toolInputSchema}, from an operation's resolved (`$ref`-free) parameter
+ *  and request-body metadata — so the tool input schema the runtime advertises and the schema the CI
+ *  parity guard pins are the SAME derivation (one source of truth, ADR 0053/0067). */
 
 /** Substitute an operation's `{param}` path-template segments with the supplied arguments, building
  *  the request path under the shared `/app/api` base so dispatch hits the exact `mountApi` route. */
@@ -351,6 +340,10 @@ function toHttpRequest(
   args: Record<string, unknown>,
   forwardHeaders: Record<string, string | string[] | undefined>,
 ): HttpRequest {
+  // `args.body` is expected to already be the structured value the operation declares — a
+  // pre-encoded JSON-string body is normalized upstream by `normalizeBodyArg` (called in
+  // `dispatchOperationTool`) so `JSON.stringify` here serializes an object/array ONCE rather than
+  // double-encoding a quoted string the door would reject (ADR 0067).
   const bodyText = op.requestBodySchema !== undefined && args.body !== undefined
     ? JSON.stringify(args.body)
     : "";
@@ -369,6 +362,76 @@ function toHttpRequest(
   };
 }
 
+/** The operation's effective request-body schema for classifying a tool-call `body`: P0's resolved,
+ *  `$ref`-free schema ({@link OperationInfo.requestBodySchemaResolved}, produced by
+ *  `collectOperations`). As defence in depth, if that metadata is somehow still a bare `$ref` (it
+ *  should never be after resolution), re-resolve it via {@link resolveSchema} against `doc` so the
+ *  classification below never keys off an opaque `#/components/...` pointer. */
+function effectiveRequestBodySchema(
+  op: OperationInfo,
+  doc: OpenApiDoc | undefined,
+): OpenApiSchema | undefined {
+  const schema = op.requestBodySchemaResolved ?? op.requestBodySchema;
+  if (schema?.$ref) return doc ? resolveSchema(doc, schema) : undefined;
+  return schema;
+}
+
+/** Whether the operation declares a STRUCTURED (object/array) request body — the shapes the app door
+ *  expects as a JSON object/array rather than a bare scalar. Classified from the RESOLVED schema so a
+ *  `$ref`-bodied op (e.g. `previewDeliveryGraph`, whose object `type` is only visible after P0's
+ *  resolution) is recognized, not merely an inline-`type` object body. */
+function structuredBodyKind(schema: OpenApiSchema | undefined): "object" | "array" | undefined {
+  if (!schema) return undefined;
+  if (isObjectSchema(schema)) return "object";
+  if (schemaHasType(schema, "array")) return "array";
+  return undefined;
+}
+
+/** Normalize a tool-call `body` argument for FAITHFUL transport (ADR 0067). A client that saw an
+ *  opaque input schema — or that coerces non-primitive args — may send `body` as a pre-encoded JSON
+ *  *string* instead of the object/array the operation declares. Left as-is, `toHttpRequest`'s
+ *  `JSON.stringify` would DOUBLE-encode it into a quoted string and the door would reject it with
+ *  "expected object, got string". So when the op declares an object/array body and `body` arrives as
+ *  a string, parse it once so it round-trips as the structured value. A genuine object/array argument
+ *  passes through untouched (still serialized by the transport). A string that does not parse to the
+ *  declared shape is a CLEAR tool error naming the expected shape — never a silently double-encoded
+ *  (and 4xx-rejected) request. */
+function normalizeBodyArg(
+  op: OperationInfo,
+  args: Record<string, unknown>,
+  doc: OpenApiDoc | undefined,
+): { ok: true; args: Record<string, unknown> } | { ok: false; error: string } {
+  const body = args.body;
+  const kind = structuredBodyKind(effectiveRequestBodySchema(op, doc));
+  if (body === undefined || kind === undefined || typeof body !== "string") {
+    return { ok: true, args };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return {
+      ok: false,
+      error:
+        `validation failed: the "body" argument was sent as a string but this operation expects a JSON ${kind}; the string is not valid JSON`,
+    };
+  }
+  const parsedKind = Array.isArray(parsed)
+    ? "array"
+    : parsed !== null && typeof parsed === "object"
+      ? "object"
+      : undefined;
+  if (parsedKind !== kind) {
+    const got = parsedKind ?? (parsed === null ? "null" : typeof parsed);
+    return {
+      ok: false,
+      error:
+        `validation failed: the "body" argument was sent as a string but this operation expects a JSON ${kind}; it parsed to a ${got}`,
+    };
+  }
+  return { ok: true, args: { ...args, body: parsed } };
+}
+
 /** Wrap a value as an MCP tool text result. A JSON payload is stringified; `isError` flags a
  *  non-2xx dispatch so the client sees the failure (carrying the delegate's own error body). */
 function textResult(value: unknown, isError = false): {
@@ -853,10 +916,16 @@ export function mountMcp(ctx: RuntimeContext, app: AppApi, apiRoutes: Route[]):
         true,
       );
     }
+    // Faithful body transport (ADR 0067): a client may send an object/array `body` pre-encoded as a
+    // JSON string. Normalize it to the structured value from the operation's RESOLVED body schema so
+    // it is not double-encoded by `toHttpRequest`; a string that cannot parse to the declared shape
+    // is a clear tool error rather than a silent 4xx from a double-encoded body.
+    const normalized = normalizeBodyArg(op, args, (await loadSpecDoc()).doc);
+    if (!normalized.ok) return textResult({ error: normalized.error }, true);
     // Forward the MCP connection's headers so the reused router enforces the operation's own
     // OpenAPI `security` (a mutating — or secured read — app op is guarded exactly as its HTTP
     // route). A `401`/`403`/`500` from that enforcement flows back as an error tool result.
-    const res = await apiRouter(toHttpRequest(op, args, headers));
+    const res = await apiRouter(toHttpRequest(op, normalized.args, headers));
     const status = res.status ?? 200;
     return textResult(res.body ?? "", status >= 400);
   };