@nanobpm/urban 0.84.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/api.d.ts

@@ -13,6 +13,10 @@ export interface ApiBinding {
      *  for free — the UI reads the SAME OpenAPI document the runtime routes + validates from. */
     docs?: boolean | string;
 }
+/** The canonical, non-configurable mount prefix for an app's OpenAPI operations. Operations always
+ *  live under `/app/api` so page actions, links, and any `callRoute` can name an operation path as a
+ *  stable framework constant (`/app/api/<op path>`) — there is no per-app `base` knob to drift. */
+export declare const API_BASE = "/app/api";
 /**
  * Derive the ABSOLUTE spec + operations-server URLs the Swagger UI page should use, from the docs
  * page's own address (`pageHref`), the mount-root-relative docs path (`docsBase`, e.g.
@@ -97,6 +101,7 @@ export declare class NotImplemented extends Error {
 export declare function defineOperation<Req extends OperationContract = DefaultContract, Res = unknown>(_id: string, handler: OperationHandler<Req, Res>): OperationHandler<Req, Res>;
 /** Resolve an operation delegate from a loaded module: `default` (when a function) else `handler`. */
 export declare function resolveOperationHandler(mod: Record<string, unknown>): OperationHandler | undefined;
+export declare function readApiBinding(manifest: unknown): ApiBinding | undefined;
 /** The Swagger UI route for an app's `api` binding, or `undefined` when there is no api surface
  *  or docs are disabled. Lets other surfaces (e.g. the pages shell's "API docs" badge) link to
  *  the docs without re-deriving the path. */

package/dist/runtime/core/modules/api.js

@@ -19,7 +19,7 @@ import { collectOperations, isSafeOperationId, operationsWithoutId, operationsWi
 /** The canonical, non-configurable mount prefix for an app's OpenAPI operations. Operations always
  *  live under `/app/api` so page actions, links, and any `callRoute` can name an operation path as a
  *  stable framework constant (`/app/api/<op path>`) — there is no per-app `base` knob to drift. */
-const API_BASE = "/app/api";
+export const API_BASE = "/app/api";
 /** Pinned Swagger UI dist served from a CDN, so the docs UI adds zero bundle/runtime deps to an
  *  Urban app (matching the deps-free spirit of the rest of the surface — validators are standalone,
  *  ADR 0058 Consequences). Pinned (not `latest`) for reproducibility. */
@@ -147,7 +147,7 @@ export function resolveOperationHandler(mod) {
         return mod.handler;
     return undefined;
 }
-function readApiBinding(manifest) {
+export function readApiBinding(manifest) {
     const raw = manifest && typeof manifest === "object" ? Reflect.get(manifest, "api") : undefined;
     if (!raw || typeof raw !== "object")
         return undefined;

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

@@ -0,0 +1,75 @@
+import type { AppApi, RuntimeContext } from "../context.ts";
+import type { HttpRequest } from "../host.ts";
+import { type Route } from "../router.ts";
+export interface McpHandle {
+    readonly name: string;
+    routes: Route[];
+    /** Whether the surface actually answers vs. 404s (config-enabled). The route is always mounted
+     *  for a stable address, so callers deriving an "active surfaces" list must gate on this. */
+    readonly enabled: boolean;
+    describe(): Record<string, unknown>;
+}
+/** Mint a fresh MCP session id, host-agnostically. Prefers the Web Crypto `randomUUID` (a global,
+ *  not `node:crypto`) where present, with a time+random fallback so a host without `crypto` never
+ *  throws — mirroring how core treats Web Crypto as optional (see `mintRootRequestKey`). */
+export declare function newSessionId(): string;
+/** Bound the live-session map to `max` by evicting least-recently-used entries (the `Map`'s leading
+ *  keys, given `touchSession` re-inserts on use), closing each victim best-effort so its transport /
+ *  server releases. This is the categorical fix for the unbounded-growth vector: no client can pin
+ *  more than `max` server/transport pairs, whatever its `initialize` cadence. Exported for a direct
+ *  unit test of the LRU eviction contract. */
+export declare function evictExcessSessions<S>(sessions: Map<string, S>, max: number, close: (session: S) => Promise<void>): Promise<void>;
+/** The resolved MCP access policy for this app. */
+interface McpConfig {
+    /** Whether the MCP surface answers at all. Defaults ON. */
+    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?, 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
+ *  non-string input (e.g. a numeric/boolean/object arg) that is present is therefore accepted, not
+ *  wrongly reported missing. Derived from the schema's own `required` array so declaring a field
+ *  required is enough to have missing (or whitespace-only) calls rejected rather than silently
+ *  substituted with an empty string. */
+export declare function missingRequiredArgs(inputSchema: Record<string, unknown>, args: Record<string, unknown>): string[];
+/**
+ * Mount the runtime-served MCP surface at `/app/mcp` (ADR 0067). Returns a single `*`-method route
+ * (mounted unconditionally, like `/app/agent`); the handler bridges the host request/response seam
+ * to the SDK's Web-Standard Streamable-HTTP transport, maintaining one MCP session per
+ * `mcp-session-id`. The tool projection reuses the SAME OpenAPI enumeration and dispatch path as
+ * `mountApi`, so a tool call is equivalent to the corresponding HTTP call.
+ */
+export declare function mountMcp(ctx: RuntimeContext, app: AppApi, apiRoutes: Route[]): McpHandle;
+export {};