@nanobpm/urban 0.85.0 → 0.86.1

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/host.d.ts

@@ -260,12 +260,58 @@ export interface ElementInstanceSummary {
 }
 /**
  * The kind of wait an element instance is parked in, as a
- * `/v2/element-instances/wait-states/search` result reports it. Unlike a user-task search,
- * this surfaces *every* park — a `JOB` (a service task awaiting a worker), a `MESSAGE`
- * (an event awaiting correlation), a `TIMER`, a `SIGNAL`, a `CONDITION`, as well as a
- * `USER_TASK` — so a consumer can read "what is this instance blocked on" beyond user tasks.
+ * `/v2/element-instances/wait-states/search` result reports it. This is the *canonical*
+ * six-type contract (Zeebe's, as of 2026): a `JOB` (a service task awaiting a worker), a
+ * `MESSAGE` (an event awaiting correlation), a `TIMER`, a `SIGNAL`, a `CONDITION`, as well
+ * as a `USER_TASK`.
+ *
+ * **Not every deployed engine implements the whole union.** It is forward-looking on
+ * purpose (the response mapper and {@link normalizeWaitStateType} tolerate all six so a
+ * newer engine's rows map cleanly), but the *currently deployed* nanobpmn gateway's
+ * read-model floor is narrower — see {@link DEPLOYED_WAIT_STATE_TYPES}. A
+ * {@link ElementInstanceWaitStateFilter} whose `waitStateType` falls outside that floor is
+ * rejected (the gateway answers HTTP 422); {@link assertDeployedWaitStateType} enforces the
+ * same floor client-side so the divergence surfaces as a clear error offline, in tests, and
+ * against a live engine alike. Ref: Magikcraft/nano-bpm#1042.
  */
 export type WaitStateType = "JOB" | "MESSAGE" | "USER_TASK" | "TIMER" | "SIGNAL" | "CONDITION";
+/**
+ * The `waitStateType` values the *currently deployed* nanobpmn gateway's wait-state read
+ * model actually implements — the **deployed floor**, a strict subset of the canonical
+ * {@link WaitStateType} union. The gateway's read model is a snapshot of the Zeebe contract
+ * taken 2026-06-09 (the same day Zeebe extended it with `USER_TASK`, then `TIMER`/`SIGNAL`/
+ * `CONDITION`), so it recognizes only `JOB | MESSAGE` and rejects any other filter value
+ * with HTTP 422.
+ *
+ * This constant is the **single source of truth** for that floor: the SDK-backed and
+ * WASM-backed {@link EngineClient} adapters both gate through {@link assertDeployedWaitStateType},
+ * and the WASM emulation synthesizes only these park kinds — so a test cannot pass against
+ * the emulation while a real gateway would 422 (No Drift Surfaces). Widen it (adding a leg
+ * backed by the real gateway) only once the engine actually serves the richer type — the
+ * tracking gap is Magikcraft/nano-bpm#1042.
+ */
+export declare const DEPLOYED_WAIT_STATE_TYPES: readonly WaitStateType[];
+/**
+ * Thrown when a wait-state search is asked to filter on a {@link WaitStateType} the deployed
+ * gateway's read model does not implement (outside {@link DEPLOYED_WAIT_STATE_TYPES}). It
+ * fails fast client-side with a clear, offline-detectable error rather than letting the call
+ * reach the gateway and surface as an opaque HTTP 422 "did not match any variant of untagged
+ * enum WaitStateTypeFilterProperty". Ref: Magikcraft/nano-bpm#1042.
+ */
+export declare class UnsupportedWaitStateTypeError extends Error {
+    readonly waitStateType: string;
+    readonly supported: readonly WaitStateType[];
+    constructor(waitStateType: string);
+}
+/**
+ * Assert a wait-state filter's `waitStateType` is within the deployed floor
+ * ({@link DEPLOYED_WAIT_STATE_TYPES}), throwing {@link UnsupportedWaitStateTypeError}
+ * otherwise. An absent selector is always allowed (the search is unfiltered by type). Both
+ * {@link EngineClient} adapters call this before issuing a wait-state search, so the floor is
+ * enforced identically whether the query runs against a live gateway or the in-process
+ * emulation. No-ops for an in-floor type.
+ */
+export declare function assertDeployedWaitStateType(waitStateType?: WaitStateType): void;
 /**
  * A single parked (waiting) element instance as
  * {@link EngineClient.searchElementInstanceWaitStates} reports it. Every variant carries the
@@ -312,6 +358,10 @@ export interface ElementInstanceFilter {
  * Selectors for an element-instance *wait-state* search: which process instance, element,
  * and/or kind of wait to match. Used by {@link EngineClient.searchElementInstanceWaitStates}.
  * There is deliberately no lifecycle-`state` selector — a wait state is always an active park.
+ *
+ * A `waitStateType` selector must fall within the deployed floor
+ * ({@link DEPLOYED_WAIT_STATE_TYPES}); a value outside it is rejected with
+ * {@link UnsupportedWaitStateTypeError} (the live gateway answers HTTP 422).
  */
 export interface ElementInstanceWaitStateFilter {
     processInstanceKey?: string;
@@ -476,11 +526,19 @@ export interface EngineClient {
     searchElementInstances(filter?: ElementInstanceFilter): Promise<ElementInstanceSummary[]>;
     /**
      * Search the *wait states* of element instances
-     * (`POST /v2/element-instances/wait-states/search`) — every park, not only user tasks. A
-     * `JOB` park (a service task awaiting a worker), a `MESSAGE` park (an event awaiting
-     * correlation), a `TIMER`/`SIGNAL`/`CONDITION`, plus `USER_TASK`. A zero-wait read; each
-     * result is discriminated by `waitStateType` (see {@link ElementInstanceWaitState}), so a
-     * consumer can read the job/message parks a {@link searchUserTasks} cannot surface.
+     * (`POST /v2/element-instances/wait-states/search`) — the parks the deployed engine's
+     * read model serves. A zero-wait read; each result is discriminated by `waitStateType`
+     * (see {@link ElementInstanceWaitState}), so a consumer can read the job/message parks a
+     * {@link searchUserTasks} cannot surface.
+     *
+     * **Deployed floor.** The currently deployed nanobpmn gateway implements only
+     * `JOB | MESSAGE` ({@link DEPLOYED_WAIT_STATE_TYPES}) — a `USER_TASK` park is read via
+     * {@link searchUserTasks}, not here. A `waitStateType` filter outside the floor is rejected
+     * with {@link UnsupportedWaitStateTypeError} (the live gateway answers HTTP 422); an
+     * unfiltered search returns only in-floor parks. The `waitStateType` union is
+     * forward-looking (richer engines may serve more), but this adapter contract pins the
+     * floor so a query cannot pass in emulation while a real engine rejects it. Ref:
+     * Magikcraft/nano-bpm#1042.
      */
     searchElementInstanceWaitStates(filter?: ElementInstanceWaitStateFilter): Promise<ElementInstanceWaitState[]>;
     /**

package/dist/runtime/core/host.js

@@ -42,6 +42,54 @@ export function presentFormIdentifier(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed : undefined;
 }
+/**
+ * The `waitStateType` values the *currently deployed* nanobpmn gateway's wait-state read
+ * model actually implements — the **deployed floor**, a strict subset of the canonical
+ * {@link WaitStateType} union. The gateway's read model is a snapshot of the Zeebe contract
+ * taken 2026-06-09 (the same day Zeebe extended it with `USER_TASK`, then `TIMER`/`SIGNAL`/
+ * `CONDITION`), so it recognizes only `JOB | MESSAGE` and rejects any other filter value
+ * with HTTP 422.
+ *
+ * This constant is the **single source of truth** for that floor: the SDK-backed and
+ * WASM-backed {@link EngineClient} adapters both gate through {@link assertDeployedWaitStateType},
+ * and the WASM emulation synthesizes only these park kinds — so a test cannot pass against
+ * the emulation while a real gateway would 422 (No Drift Surfaces). Widen it (adding a leg
+ * backed by the real gateway) only once the engine actually serves the richer type — the
+ * tracking gap is Magikcraft/nano-bpm#1042.
+ */
+export const DEPLOYED_WAIT_STATE_TYPES = ["JOB", "MESSAGE"];
+/**
+ * Thrown when a wait-state search is asked to filter on a {@link WaitStateType} the deployed
+ * gateway's read model does not implement (outside {@link DEPLOYED_WAIT_STATE_TYPES}). It
+ * fails fast client-side with a clear, offline-detectable error rather than letting the call
+ * reach the gateway and surface as an opaque HTTP 422 "did not match any variant of untagged
+ * enum WaitStateTypeFilterProperty". Ref: Magikcraft/nano-bpm#1042.
+ */
+export class UnsupportedWaitStateTypeError extends Error {
+    waitStateType;
+    supported;
+    constructor(waitStateType) {
+        super(`unsupported waitStateType "${waitStateType}": the deployed nanobpmn gateway's ` +
+            `wait-state read model implements only ${DEPLOYED_WAIT_STATE_TYPES.join(" | ")} and ` +
+            `rejects any other value with HTTP 422. Ref: Magikcraft/nano-bpm#1042.`);
+        this.name = "UnsupportedWaitStateTypeError";
+        this.waitStateType = waitStateType;
+        this.supported = DEPLOYED_WAIT_STATE_TYPES;
+    }
+}
+/**
+ * Assert a wait-state filter's `waitStateType` is within the deployed floor
+ * ({@link DEPLOYED_WAIT_STATE_TYPES}), throwing {@link UnsupportedWaitStateTypeError}
+ * otherwise. An absent selector is always allowed (the search is unfiltered by type). Both
+ * {@link EngineClient} adapters call this before issuing a wait-state search, so the floor is
+ * enforced identically whether the query runs against a live gateway or the in-process
+ * emulation. No-ops for an in-floor type.
+ */
+export function assertDeployedWaitStateType(waitStateType) {
+    if (waitStateType !== undefined && !DEPLOYED_WAIT_STATE_TYPES.includes(waitStateType)) {
+        throw new UnsupportedWaitStateTypeError(waitStateType);
+    }
+}
 /**
  * The names of every method on {@link EngineClient} — the single *runtime* source of
  * truth for the interface's surface. It is compile-time-pinned to `keyof EngineClient`

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