@nanobpm/urban 0.85.0 → 0.86.0

package/src/openapi/mcp-parity.fixture.yaml

@@ -0,0 +1,49 @@
+# Parity-guard fixture (ADR 0067 Slice 3) — NOT an app spec.
+#
+# This is the input to the spec↔tool parity guard (`scripts/gen-mcp-tools.ts`).
+# It exercises every branch of the MCP tool projection with a stable, minimal
+# document so `check:mcp` fails loudly the moment the walker's projection changes
+# without a matching, reviewed regeneration of `mcp-tools.snapshot.json`:
+#
+#   - a READ operation (GET)            → projected, non-mutating
+#   - a MUTATING operation (POST)       → projected, mutating (guarded at runtime)
+#   - an `x-mcp`-EXCLUDED operation      → present in the doc but withheld from the
+#                                          agent-facing tool surface (the security-
+#                                          relevant opt-out, `x-mcp: false`)
+#
+# Edit this fixture ONLY together with a reviewed `npm run gen:mcp-tools`.
+openapi: 3.1.0
+info:
+  title: mcp-parity-fixture
+  version: 0.0.0
+components:
+  securitySchemes:
+    appSecret:
+      type: apiKey
+      in: header
+      name: X-Nano-Key
+      x-nano-secret-env: NANO_WEBHOOK_KEY
+paths:
+  /widgets:
+    get:
+      operationId: listWidgets
+      summary: List widgets (read — projected, unguarded on loopback).
+      responses:
+        "200":
+          description: ok
+    post:
+      operationId: createWidget
+      summary: Create a widget (mutating — projected, guarded).
+      security:
+        - appSecret: []
+      responses:
+        "201":
+          description: created
+  /internal/reindex:
+    post:
+      operationId: reindexWidgets
+      summary: Operator-only reindex (withheld from the MCP tool surface).
+      x-mcp: false
+      responses:
+        "202":
+          description: accepted

package/src/openapi/mcp-tools.snapshot.json

@@ -0,0 +1,20 @@
+[
+  {
+    "operationId": "reindexWidgets",
+    "method": "post",
+    "mutating": true,
+    "excluded": true
+  },
+  {
+    "operationId": "listWidgets",
+    "method": "get",
+    "mutating": false,
+    "excluded": false
+  },
+  {
+    "operationId": "createWidget",
+    "method": "post",
+    "mutating": true,
+    "excluded": false
+  }
+]

package/src/openapi/spec.test.ts

@@ -5,6 +5,7 @@ import {
   evaluateSecurity,
   isObjectSchema,
   isSafeOperationId,
+  isMutatingMethod,
   type OpenApiDoc,
   type OpenApiSchema,
   operationsWithoutId,
@@ -13,6 +14,8 @@ import {
   resolveSchema,
   responseSchemaForStatus,
   sharedRequestBodySchemas,
+  sharedSecretSchemeName,
+  sharedSecretSchemeNames,
   toRouteMatcher,
   undeclaredPathParams,
   undeclaredSecuritySchemes,
@@ -436,6 +439,18 @@ test("isSafeOperationId rejects path separators and traversal; collectOperations
   assert.deepEqual(operationsWithUnsafeId(evil), ["GET /x (../../etc/passwd)"]);
 });
 
+test("isMutatingMethod: the HTTP safe verbs (get/head/options) are read-only, everything else mutates", () => {
+  // OPTIONS is a CORS/preflight metadata probe — a safe, non-mutating verb (RFC 9110 §9.2.1). It must
+  // NOT be flagged mutating, or an `options` operation is wrongly marked destructive in tools/list and
+  // captured as a "mutating" fact by the spec↔tool parity snapshot.
+  for (const safe of ["get", "head", "options"] as const) {
+    assert.equal(isMutatingMethod(safe), false, `${safe} must be treated as read-only`);
+  }
+  for (const mutating of ["put", "post", "delete", "patch"] as const) {
+    assert.equal(isMutatingMethod(mutating), true, `${mutating} must be treated as mutating`);
+  }
+});
+
 test("object validation uses own-property checks (prototype keys don't satisfy required or bypass additionalProperties)", () => {
   // A prototype key must NOT satisfy `required` (own-property semantics).
   const req = { type: "object", properties: { toString: { type: "string" } }, required: ["toString"] };
@@ -633,6 +648,83 @@ test("evaluateSecurity: alternative requirements are OR (any one satisfied autho
   assert.equal(evaluateSecurity(doc, op, noHeader, noQuery, env).status, 401);
 });
 
+test("sharedSecretSchemeName: exactly one apiKey header scheme with x-nano-secret-env is the guard", () => {
+  assert.equal(sharedSecretSchemeName(secured), "webhookKey");
+  assert.deepEqual(sharedSecretSchemeNames(secured), ["webhookKey"]);
+});
+
+test("sharedSecretSchemeName: no candidate scheme → undefined (mutations stay closed)", () => {
+  const doc: OpenApiDoc = {
+    openapi: "3.0.0",
+    components: { securitySchemes: { oauth: { type: "oauth2" } } },
+    paths: {},
+  };
+  assert.equal(sharedSecretSchemeName(doc), undefined);
+  assert.deepEqual(sharedSecretSchemeNames(doc), []);
+});
+
+test("sharedSecretSchemeName: MULTIPLE candidate schemes are an explicit misconfiguration, not a silent first-wins", () => {
+  // Two apiKey header schemes both carry x-nano-secret-env: which one guards mutations would
+  // otherwise depend on object iteration (authoring) order — surface it loudly instead.
+  const doc: OpenApiDoc = {
+    openapi: "3.0.0",
+    components: {
+      securitySchemes: {
+        primary: { type: "apiKey", in: "header", name: "X-A", "x-nano-secret-env": "A_KEY" },
+        secondary: { type: "apiKey", in: "header", name: "X-B", "x-nano-secret-env": "B_KEY" },
+      },
+    },
+    paths: {},
+  };
+  // The full candidate list is exposed (source of truth) …
+  assert.deepEqual(sharedSecretSchemeNames(doc), ["primary", "secondary"]);
+  // … and the selector refuses to pick one silently.
+  assert.throws(
+    () => sharedSecretSchemeName(doc),
+    /multiple shared-secret schemes.*primary, secondary/s,
+  );
+});
+
+test("sharedSecretSchemeNames: a declared-but-EMPTY x-nano-secret-env is still a candidate (→ 500 downstream, not a silent 401)", () => {
+  // An empty `x-nano-secret-env` is a misconfiguration, not "no scheme": a truthiness test would
+  // drop it so the guard reports a misleading "no shared-secret scheme" (401). A structural presence
+  // check keeps it selected so `evaluateSecurity` surfaces it as a 500, mirroring how it treats an
+  // empty env-var pointer.
+  const doc: OpenApiDoc = {
+    openapi: "3.0.0",
+    components: {
+      securitySchemes: {
+        webhookKey: { type: "apiKey", in: "header", name: "X-Key", "x-nano-secret-env": "" },
+      },
+    },
+    paths: {},
+  };
+  assert.deepEqual(sharedSecretSchemeNames(doc), ["webhookKey"]);
+  assert.equal(sharedSecretSchemeName(doc), "webhookKey");
+});
+
+test("sharedSecretSchemeNames: a malformed (null) scheme entry is skipped, not a bare TypeError", () => {
+  // A mistakenly empty scheme (`webhookKey:` with no body) parses as `null` in YAML. Dereferencing
+  // it (`scheme.type`) would throw a bare TypeError; a non-object scheme is not a valid apiKey
+  // shared-secret candidate, so it is skipped and the real candidate is still selected. Built via
+  // JSON.parse so the runtime-invalid `null` scheme reaches the function (types forbid it).
+  const doc: OpenApiDoc = parseSpec(
+    JSON.stringify({
+      openapi: "3.0.0",
+      components: {
+        securitySchemes: {
+          brokenEmpty: null,
+          webhookKey: { type: "apiKey", in: "header", name: "X-Key", "x-nano-secret-env": "KEY" },
+        },
+      },
+      paths: {},
+    }),
+  );
+  assert.deepEqual(sharedSecretSchemeNames(doc), ["webhookKey"]);
+  assert.equal(sharedSecretSchemeName(doc), "webhookKey");
+});
+
+
 test("responseSchemaForStatus: a documented-but-bodyless status suppresses the default fallback", () => {
   const ops = collectOperations({
     openapi: "3.1.0",

package/src/openapi/spec.ts

@@ -187,6 +187,11 @@ export interface OperationInfo {
    *  else the document-level default, else `[]`). An empty list means the operation is open. */
   security: OpenApiSecurityRequirement[];
   eject: boolean;
+  /** Whether the operation opts OUT of MCP tool projection via the `x-mcp` extension (ADR 0067).
+   *  Defaults to `false` — an operation IS exposed as a tool unless it explicitly excludes itself.
+   *  Security-relevant: this is the single authoring switch that keeps an operator-only door (e.g.
+   *  a human-gated dispatch) out of the agent-facing tool surface. See {@link isMcpExcluded}. */
+  mcpExcluded: boolean;
   summary?: string;
 }
 
@@ -307,6 +312,7 @@ export function collectOperations(doc: OpenApiDoc): OperationInfo[] {
         responseSchemas: collectResponseSchemas(responses),
         security,
         eject: opRaw["x-urban-eject"] === true,
+        mcpExcluded: isMcpExcluded(opRaw["x-mcp"]),
         summary: typeof opRaw.summary === "string" ? opRaw.summary : undefined,
       });
     }
@@ -314,6 +320,161 @@ export function collectOperations(doc: OpenApiDoc): OperationInfo[] {
   return out;
 }
 
+/**
+ * Read the `x-mcp` operation extension (ADR 0067 — MCP tool projection). An operation is EXPOSED as
+ * an MCP tool by default; it is excluded only when it says so explicitly, so a spec author opts a
+ * door OUT rather than every operation having to opt in. Recognised exclusion forms:
+ *   - `x-mcp: false`            — a terse boolean opt-out;
+ *   - `x-mcp: { exclude: true }` — the object form (room for future keys, e.g. per-tool metadata).
+ * Any other value (including `x-mcp: true` / `{ exclude: false }` / absent) leaves the operation
+ * exposed — fail-open to the documented default. This is a SECURITY-RELEVANT authoring rule: it is
+ * the one switch that keeps an operator-only operation out of the agent-facing tool surface, so it
+ * is enforced from the same single walker the runtime and the parity guard both read (no second
+ * source of truth to drift, ADR 0053).
+ */
+export function isMcpExcluded(ext: unknown): boolean {
+  if (ext === false) return true;
+  return isRecord(ext) && ext.exclude === true;
+}
+
+/** The HTTP methods MCP treats as read-only (safe, non-mutating). These are exactly the HTTP "safe"
+ *  verbs (RFC 9110 §9.2.1) that {@link HTTP_METHODS} can express: GET/HEAD, plus OPTIONS (a
+ *  CORS/preflight metadata probe that never mutates). Every other method an operation can declare is
+ *  a mutation whose tool is guarded (ADR 0067 Slice 3). */
+const READ_ONLY_METHODS: readonly HttpMethodLower[] = ["get", "head", "options"];
+
+/** Whether an operation's HTTP method mutates state — anything other than a safe read verb. Drives
+ *  the MCP read/mutate split: read tools are unguarded on loopback, mutating tools are gated. */
+export function isMutatingMethod(method: HttpMethodLower): boolean {
+  return !READ_ONLY_METHODS.includes(method);
+}
+
+/** One operation's MCP-tool projection facts: its id, HTTP method, whether it mutates, and whether
+ *  `x-mcp` excludes it from projection. This is the shared unit the runtime MCP surface AND the CI
+ *  spec↔tool parity guard both read — a single derivation of "which operations become tools", never
+ *  a second walker (ADR 0053). */
+export interface McpToolProjection {
+  operationId: string;
+  method: HttpMethodLower;
+  mutating: boolean;
+  excluded: boolean;
+}
+
+/**
+ * Project every operationId-bearing operation to its MCP-tool facts, in the stable
+ * `collectOperations` (path, method) order. Excluded operations are RETAINED here (flagged
+ * `excluded: true`) rather than dropped, so the parity guard can positively assert that an
+ * `x-mcp`-excluded door is present-but-withheld — the runtime drops them when it builds the live
+ * tool list. Derived entirely from {@link collectOperations}, so it can never diverge from what
+ * `mountApi` routes.
+ */
+export function collectMcpToolProjection(doc: OpenApiDoc): McpToolProjection[] {
+  return collectOperations(doc).map((op) => ({
+    operationId: op.operationId,
+    method: op.method,
+    mutating: isMutatingMethod(op.method),
+    excluded: op.mcpExcluded,
+  }));
+}
+
+/**
+ * Compare a previously-captured MCP-tool projection (the committed snapshot) against the projection
+ * freshly computed from the spec, returning a human-readable line for every skew — an operation the
+ * spec now projects that the snapshot lacks, one the snapshot still lists that the spec no longer
+ * projects, or one whose method / mutating / excluded facts changed. An empty array means the spec
+ * and the projected tool list are in parity. This is the pure core of the `check:mcp` CI drift gate
+ * (ADR 0067) — the same "generated derived artifact + fail-on-drift" pattern the repo already uses
+ * for `check:runtime` — and is unit-tested by feeding it an injected skew.
+ */
+export function diffMcpToolProjection(
+  snapshot: McpToolProjection[],
+  current: McpToolProjection[],
+): string[] {
+  const drift: string[] = [];
+  const byId = (list: McpToolProjection[]): Map<string, McpToolProjection> =>
+    new Map(list.map((p) => [p.operationId, p]));
+  const snapshotById = byId(snapshot);
+  const currentById = byId(current);
+  for (const [id, cur] of currentById) {
+    const snap = snapshotById.get(id);
+    if (!snap) {
+      drift.push(`+ ${id}: spec projects a tool the snapshot is missing (regenerate the snapshot)`);
+      continue;
+    }
+    if (snap.method !== cur.method || snap.mutating !== cur.mutating || snap.excluded !== cur.excluded) {
+      drift.push(
+        `~ ${id}: projection changed — snapshot {method:${snap.method}, mutating:${snap.mutating}, ` +
+          `excluded:${snap.excluded}} vs spec {method:${cur.method}, mutating:${cur.mutating}, ` +
+          `excluded:${cur.excluded}}`,
+      );
+    }
+  }
+  for (const id of snapshotById.keys()) {
+    if (!currentById.has(id)) {
+      drift.push(`- ${id}: snapshot lists a tool the spec no longer projects (regenerate the snapshot)`);
+    }
+  }
+  return drift;
+}
+
+/**
+ * Every app shared-secret security scheme (ADR 0067/0059): the `apiKey` schemes in
+ * `components.securitySchemes` presented in a request HEADER and pointing at an env var via
+ * `x-nano-secret-env` (declared, even if empty — an empty pointer is a misconfiguration surfaced as
+ * 500 downstream, not "no scheme"), in document (authoring) order. Single source of truth for both the guard
+ * selector (`sharedSecretSchemeName`) and its ambiguity check — a mutating MCP tool REUSES the
+ * app's existing shared secret (the same one a `webhook` trigger or a guarded operation already
+ * uses) instead of minting an MCP-specific synonym.
+ */
+export function sharedSecretSchemeNames(doc: OpenApiDoc): string[] {
+  const schemes = doc.components?.securitySchemes ?? {};
+  const names: string[] = [];
+  for (const [name, scheme] of Object.entries(schemes)) {
+    // A malformed scheme value (e.g. `webhookKey:` with no body parses as `null` in YAML, or a
+    // primitive) is not a valid apiKey shared-secret candidate — skip it rather than dereference it
+    // and throw a bare TypeError. This mirrors `evaluateSecurity`, which never treats a non-object
+    // scheme as a valid credential (a referenced null/primitive scheme surfaces there as a 500), so
+    // there is no silent security hole: mutations fail closed and a genuine misconfig is caught at
+    // request time by the enforcement path.
+    if (!isRecord(scheme)) continue;
+    // Structural presence check (`typeof … === "string"`), NOT truthiness: a declared-but-EMPTY
+    // `x-nano-secret-env` is a misconfiguration, not "no scheme". Selecting it here lets
+    // `evaluateSecurity` surface it as a 500 (missing env-var pointer) — the same way it treats an
+    // empty pointer — instead of silently dropping the scheme so the guard reports a misleading 401.
+    if (
+      scheme.type === "apiKey" &&
+      (scheme.in ?? "header") === "header" &&
+      typeof scheme["x-nano-secret-env"] === "string"
+    ) {
+      names.push(name);
+    }
+  }
+  return names;
+}
+
+/**
+ * The name of the app's single shared-secret security scheme (ADR 0067/0059) — the credential the
+ * framework MUTATING MCP tools require. `undefined` when the app declares no such scheme, in which
+ * case the mutating tools stay closed unless an explicit runtime opt-in is set.
+ *
+ * THROWS when the spec declares MORE THAN ONE candidate: which scheme becomes "the" MCP mutation
+ * guard would otherwise depend on `securitySchemes` object iteration (authoring) order, silently
+ * guarding with an unintended secret (or rejecting a different, valid shared-secret header). That is
+ * an incoherent spec, surfaced loudly — the caller maps it to a 500 misconfiguration — rather than
+ * resolved by an invisible "first wins" rule. Derived from `sharedSecretSchemeNames` (no drift).
+ */
+export function sharedSecretSchemeName(doc: OpenApiDoc): string | undefined {
+  const names = sharedSecretSchemeNames(doc);
+  if (names.length > 1) {
+    throw new Error(
+      `OpenAPI spec declares multiple shared-secret schemes (apiKey header with x-nano-secret-env): ` +
+        `${names.join(", ")}. Exactly one may serve as the MCP mutation guard — remove the extras so ` +
+        "the guard scheme is unambiguous.",
+    );
+  }
+  return names[0];
+}
+
 /**
  * Throw if the document declares the same `operationId` on more than one operation. An operationId
  * must be unique across the whole OpenAPI document (it names the delegate module `<dir>/<operationId>`