@nanobpm/urban 0.85.0 → 0.86.0

package/dist/openapi/spec.d.ts

@@ -128,6 +128,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;
 }
 /** Parse an OpenAPI document from text. Accepts both YAML (the sanctioned authoring format for
@@ -143,6 +148,73 @@ export declare function resolveSchema(doc: OpenApiDoc, schema: OpenApiSchema | u
  *  (path, method) order. Operations without an operationId are skipped here; the runtime mount logs
  *  them at `warn` and skips them too — this keeps the pure collector total. */
 export declare function collectOperations(doc: OpenApiDoc): OperationInfo[];
+/**
+ * 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 declare function isMcpExcluded(ext: unknown): boolean;
+/** 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 declare function isMutatingMethod(method: HttpMethodLower): boolean;
+/** 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 declare function collectMcpToolProjection(doc: OpenApiDoc): McpToolProjection[];
+/**
+ * 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 declare function diffMcpToolProjection(snapshot: McpToolProjection[], current: McpToolProjection[]): string[];
+/**
+ * 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 declare function sharedSecretSchemeNames(doc: OpenApiDoc): string[];
+/**
+ * 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 declare function sharedSecretSchemeName(doc: OpenApiDoc): string | undefined;
 /**
  * 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>`

package/dist/openapi/spec.js

@@ -172,12 +172,142 @@ export function collectOperations(doc) {
                 responseSchemas: collectResponseSchemas(responses),
                 security,
                 eject: opRaw["x-urban-eject"] === true,
+                mcpExcluded: isMcpExcluded(opRaw["x-mcp"]),
                 summary: typeof opRaw.summary === "string" ? opRaw.summary : undefined,
             });
         }
     }
     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) {
+    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 = ["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) {
+    return !READ_ONLY_METHODS.includes(method);
+}
+/**
+ * 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) {
+    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, current) {
+    const drift = [];
+    const byId = (list) => 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) {
+    const schemes = doc.components?.securitySchemes ?? {};
+    const names = [];
+    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) {
+    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>`

package/dist/runtime/core/modules/mcp.d.ts

@@ -25,19 +25,37 @@ interface McpConfig {
     readonly enabled: boolean;
     /** Whether non-loopback callers are allowed. Defaults OFF (loopback-only). */
     readonly allowRemote: boolean;
+    /** Explicit runtime opt-in that authorizes the framework MUTATING debug tools WITHOUT a
+     *  shared-secret credential (ADR 0067 Slice 3). Defaults OFF: mutations then require the app's
+     *  shared secret. An operator sets this to open mutations on a trusted, credential-less setup
+     *  (e.g. a purely local debugging box). It is honoured LOOPBACK-ONLY: when `allowRemote` is also
+     *  enabled the credential-free bypass is ignored and remote mutations still require the shared
+     *  secret, so opening the surface to non-loopback callers can never silently expose unguarded
+     *  mutating tools. */
+    readonly allowMutations: boolean;
 }
 /**
- * Resolve the MCP access policy from the manifest (`mcp: { enabled?, allowRemote? }`, read
- * reflectively until the app schema folds the field in — mirroring how `readApiBinding` reads
- * `api`) and the environment (`URBAN_MCP_ENABLED`, `URBAN_MCP_ALLOW_REMOTE`). The env flags win so
- * an operator can force the surface off (or open it to a non-loopback bind) without editing the
- * manifest. Enabled defaults ON and access defaults to loopback-only ("defaults ON for loopback").
+ * Resolve the MCP access policy from the manifest
+ * (`mcp: { enabled?, allowRemote?, allowMutations? }`, read reflectively until the app schema folds
+ * the field in — mirroring how `readApiBinding` reads `api`) and the environment
+ * (`URBAN_MCP_ENABLED`, `URBAN_MCP_ALLOW_REMOTE`, `URBAN_MCP_ALLOW_MUTATIONS`). The env flags win so
+ * an operator can force the surface off (or open it to a non-loopback bind, or enable mutating
+ * tools) without editing the manifest. Enabled defaults ON and access defaults to loopback-only
+ * ("defaults ON for loopback"); `allowMutations` defaults OFF (mutating tools stay closed).
  */
 export declare function readMcpConfig(manifest: unknown, env: (name: string) => string | undefined): McpConfig;
 /** Whether the request targets a loopback host — the best-effort loopback signal available at the
  *  host seam (which carries no peer address). A missing Host header is treated as loopback (a direct
  *  local client that sent none). */
 export declare function isLoopbackRequest(req: HttpRequest): boolean;
+/** Read a header value from the SDK's per-request `requestInfo.headers` map (lower-cased keys,
+ *  values `string | string[] | undefined`). A repeated header (`string[]`, as Node's raw adapter
+ *  surfaces it) is comma-joined to MATCH `Headers.get()` semantics — the same read `mountApi` and
+ *  the reconstructed `toHttpRequest` use for OpenAPI route enforcement — so the shared-secret guard
+ *  cannot diverge from route enforcement on a repeated credential header. Returns `undefined` when
+ *  absent. Used to read the shared-secret credential the client presents on the MCP connection for a
+ *  mutating tool call. */
+export declare function readHeader(headers: Record<string, string | string[] | undefined>, name: string): string | undefined;
 /** The `required` keys a tool's `inputSchema` declares but the call omitted. Presence is decided
  *  solely by {@link isBlankArg} — the single source of truth also used for path args — so a value is
  *  "provided" unless it is absent (`undefined`/`null`) or a blank/whitespace-only string. A required