@nanobpm/nano-workforce 0.171.10 → 0.171.11

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.171.11](https://github.com/nanobpm/nano-workforce/compare/v0.171.10...v0.171.11) (2026-09-01)
+
+### Bug Fixes
+
+* **mcp:** declare x-nano-secret-env on hookSecret so urban_debug_* mutations authorize remotely ([#700](https://github.com/nanobpm/nano-workforce/issues/700)) ([bd46ac6](https://github.com/nanobpm/nano-workforce/commit/bd46ac6e235fc9a13cab27351108cea9570f387b)), closes [#698](https://github.com/nanobpm/nano-workforce/issues/698) [#698](https://github.com/nanobpm/nano-workforce/issues/698) [#698](https://github.com/nanobpm/nano-workforce/issues/698) [pre-#698](https://github.com/nanobpm/pre-/issues/698)
+
 ## [0.171.10](https://github.com/nanobpm/nano-workforce/compare/v0.171.9...v0.171.10) (2026-09-01)
 
 ### Bug Fixes

package/docs/mcp-runbook.md

@@ -133,6 +133,41 @@ header on **both reads and mutations** — read endpoints like `GET /app/api/age
 `/app/mcp` follows the same `network.bind` manifest setting as the rest of the app's
 HTTP surface.
 
+### Framework mutation guard — `urban_debug_*` mutations need `x-hook-secret` too
+
+The framework-owned **mutating** `urban_debug_*` tools (`set_variables`, `retry_job`,
+`resolve_incident`, `cancel_instance`) are gated by the Urban runtime's *own* mutation
+guard (`authorizeMutation`), which is separate from nwf's app-operation guard above. It
+authorizes a mutation one of two ways:
+
+1. **Loopback bypass** — `URBAN_MCP_ALLOW_MUTATIONS=true` **and** `mcp.allowRemote` off.
+   This is the credential-free, local-only path; it is disabled the moment the surface is
+   remote-exposed (`allowRemote` on), by design — the guard never drops for a non-loopback
+   caller.
+2. **Shared-secret scheme** — an apiKey *header* security scheme that declares an
+   `x-nano-secret-env` extension naming the env var holding the secret. nwf declares this
+   on **`hookSecret`** (`x-nano-secret-env: NANO_PR_WEBHOOK_SECRET`), so a mutating
+   `urban_debug_*` call carrying `x-hook-secret: <NANO_PR_WEBHOOK_SECRET>` is authorized on
+   a remote-exposed instance.
+
+This is the **same secret and same header** as nwf's app-operation guard (both key on
+`NANO_PR_WEBHOOK_SECRET` via `x-hook-secret`), so reads and mutations — app-operation and
+framework — share one credential. The MCP server entry's `headers` already carries it (§1);
+nothing extra is needed for `urban_debug_*` mutations once the secret is set.
+
+**Fail-closed caveat.** When `NANO_PR_WEBHOOK_SECRET` is **unset** there is no credential to
+present, so on a remote-exposed instance (`allowRemote` on) framework mutations remain
+**closed** — this is correct fail-closed behavior, not a regression. Because the scheme is now
+*declared* (it names the env var) but the secret is absent, the runtime surfaces the attempt as a
+`500` *security-misconfigured* ("secret env `NANO_PR_WEBHOOK_SECRET` is not set") rather than a
+plain refusal — either way no mutation occurs. An operator who needs remote mutation repair (e.g.
+patching a wedged instance's variable + retrying a `JOB_NO_RETRIES` job) must set
+`NANO_PR_WEBHOOK_SECRET`; then a `urban_debug_*` mutation carrying `x-hook-secret: <secret>`
+succeeds, while a missing or wrong header `401`s. The loopback bypass
+(`URBAN_MCP_ALLOW_MUTATIONS=true` with `allowRemote` off) remains the credential-free
+local-only alternative. Only `hookSecret` may carry `x-nano-secret-env` — the runtime
+throws on more than one shared-secret scheme.
+
 **Operator-only doors stay operator-only.** The staged delivery-graph lifecycle —
 `stageDeliveryGraph`, `dispatchDeliveryGraph`, `dismissProposal` — is `x-mcp`-excluded
 from the projected tool surface (ADR 0067 §2): the human clicking **Dispatch** in the

package/e2e/mcp-surface.e2e.ts

@@ -184,12 +184,18 @@ describe("MCP surface e2e — the runtime-served /app/mcp handshake, per tool (S
   });
 
   test("mutating framework tools are gated without the shared secret (set-variables)", async () => {
+    // This harness boots WITHOUT `NANO_PR_WEBHOOK_SECRET`. Since #698 declares the `hookSecret`
+    // shared-secret scheme (`x-nano-secret-env`), a remote-exposed mutation now fails CLOSED
+    // DETERMINISTICALLY as a misconfiguration ("secret env … is not set") — the credential the guard
+    // requires cannot exist until the operator sets the env var. Pin exactly that new shape (NOT the
+    // pre-#698 no-scheme "shared secret"/"allowMutations" refusal), so the test actually proves #698's
+    // `x-nano-secret-env` declaration took effect rather than accepting the old behavior.
     const res = await h.callTool("urban_debug_set_variables", { processInstanceKey: "1", variables: {} });
     assert.ok(res.isError, "urban_debug_set_variables must refuse a credential-free mutation");
     assert.match(
       res.text,
-      /shared secret|allowMutations/i,
-      `the refusal must name the guard: ${res.text}`,
+      /secret env .* is not set|misconfigured/i,
+      `the refusal must be the #698 misconfiguration shape: ${res.text}`,
     );
   });
 
@@ -264,3 +270,71 @@ describe("MCP surface e2e — the runtime-served /app/mcp handshake, per tool (S
     assert.deepEqual(json?.proposals, [], "no live staged proposals may remain");
   });
 });
+
+// Framework mutation-guard authorization (issue #698).
+// --------------------------------------------------------------------------
+// The framework-owned mutating `urban_debug_*` tools (set_variables/retry_job/resolve_incident/
+// cancel_instance) are gated by @nanobpm/urban's OWN mutation guard (`authorizeMutation`), distinct
+// from nwf's app-operation guard. On a REMOTE-exposed instance (the harness always boots with
+// `URBAN_MCP_ALLOW_REMOTE: "true"`) the loopback bypass is off, so the ONLY door left is the
+// shared-secret apiKey scheme — which the guard recognizes only when an apiKey *header* scheme
+// declares `x-nano-secret-env`. nwf now declares `x-nano-secret-env: NANO_PR_WEBHOOK_SECRET` on the
+// `hookSecret` scheme (this issue), so a mutating call carrying `x-hook-secret: <secret>` is
+// authorized past the guard, while a missing/wrong header stays 401. This pins that contract.
+const HOOK_SECRET = "issue-698-shared-secret";
+
+describe("MCP surface e2e — framework mutation guard authorizes with the shared secret (#698)", () => {
+  let h: McpHarness;
+
+  before(async () => {
+    // Remote-exposed (harness default) + a shared secret set: the exact condition of #698, where the
+    // loopback bypass is off and the shared-secret scheme is the only authorization door.
+    h = await bootMcpHarness({ env: { NANO_PR_WEBHOOK_SECRET: HOOK_SECRET } });
+  });
+
+  after(async () => {
+    await h?.stop();
+  });
+
+  test("a mutating urban_debug_* call is refused WITHOUT the shared-secret header", async () => {
+    const res = await h.callTool("urban_debug_set_variables", { processInstanceKey: "1", variables: {} });
+    assert.ok(res.isError, "a credential-free mutation must be refused on a remote-exposed instance");
+    assert.match(
+      res.text,
+      /unauthorized|401/i,
+      `a missing shared-secret header must 401: ${res.text}`,
+    );
+  });
+
+  test("a mutating urban_debug_* call is refused WITH A WRONG shared-secret header", async () => {
+    const res = await h.callTool(
+      "urban_debug_set_variables",
+      { processInstanceKey: "1", variables: {} },
+      { "x-hook-secret": "not-the-secret" },
+    );
+    assert.ok(res.isError, "a wrong-secret mutation must still be refused");
+    assert.match(
+      res.text,
+      /unauthorized|401/i,
+      `a wrong shared-secret header must 401: ${res.text}`,
+    );
+  });
+
+  test("a mutating urban_debug_* call carrying the correct x-hook-secret is authorized past the guard", async () => {
+    const res = await h.callTool(
+      "urban_debug_set_variables",
+      { processInstanceKey: "1", variables: {} },
+      { "x-hook-secret": HOOK_SECRET },
+    );
+    // The correct credential clears the shared-secret guard. The call may still fail downstream (the
+    // hermetic engine has no instance `1`), but it must NO LONGER be the shared-secret refusal NOR a
+    // generic authorization failure (401/unauthorized) — excluding those is the falsifiable proof the
+    // `x-nano-secret-env` declaration made the scheme authorizable (rather than the credential silently
+    // still being rejected).
+    assert.doesNotMatch(
+      res.text,
+      /shared secret|allowMutations|NO_SHARED_SECRET|unauthorized|401/i,
+      `the authorized call must clear the shared-secret guard, got: ${res.text}`,
+    );
+  });
+});

package/e2e/support/mcp-harness.ts

@@ -125,8 +125,9 @@ export interface McpHarness {
   readonly sessionId: string;
   /** `tools/list` — the projected tool catalogue (app operations + framework debug tools). */
   listTools(): Promise<McpTool[]>;
-  /** `tools/call` — invoke a tool by name with its argument object. */
-  callTool(name: string, args?: Record<string, unknown>): Promise<McpToolResult>;
+  /** `tools/call` — invoke a tool by name with its argument object. Optional `extraHeaders` are
+   *  overlaid on the POST (e.g. an `x-hook-secret` shared-secret credential for a gated mutation). */
+  callTool(name: string, args?: Record<string, unknown>, extraHeaders?: Record<string, string>): Promise<McpToolResult>;
   /** A raw JSON-RPC request against `/app/mcp` (escape hatch for a bespoke case). `params` omitted →
    *  no `params` field; a `notifications/*` method is sent as a notification (no `id`, no response). */
   rpc(method: string, params?: unknown): Promise<McpRpcResult>;
@@ -175,13 +176,22 @@ export async function bootMcpHarness(opts: BootMcpHarnessOptions = {}): Promise<
   }
 
   let idCounter = 0;
-  const rpc = async (method: string, params?: unknown, sessionId?: string): Promise<McpRpcResult> => {
+  const rpc = async (
+    method: string,
+    params?: unknown,
+    sessionId?: string,
+    extraHeaders?: Record<string, string>,
+  ): Promise<McpRpcResult> => {
     const headers: Record<string, string> = {
       "content-type": "application/json",
       // The Streamable-HTTP transport inspects Accept; a real client offers both even when the
       // server answers JSON (the runtime sets `enableJsonResponse`).
       accept: "application/json, text/event-stream",
     };
+    // Apply caller-supplied overlay headers FIRST so the session header stays authoritative — a
+    // caller passing auth headers (e.g. `x-hook-secret`) must not be able to clobber `mcp-session-id`
+    // and break the MCP handshake for this request.
+    if (extraHeaders) Object.assign(headers, extraHeaders);
     if (sessionId) headers[SESSION_HEADER] = sessionId;
     const isNotification = method.startsWith("notifications/");
     const message: Record<string, unknown> = { jsonrpc: "2.0", method };
@@ -252,8 +262,8 @@ export async function bootMcpHarness(opts: BootMcpHarnessOptions = {}): Promise<
       }
       return body.result.tools;
     },
-    async callTool(name, args = {}): Promise<McpToolResult> {
-      const res = await rpc("tools/call", { name, arguments: args }, sessionId);
+    async callTool(name, args = {}, extraHeaders): Promise<McpToolResult> {
+      const res = await rpc("tools/call", { name, arguments: args }, sessionId, extraHeaders);
       const body = res.body as
         | { result?: { isError?: boolean; content?: Array<{ type: string; text?: string }> }; error?: { message?: string } }
         | undefined;

package/openapi.yaml

@@ -24,9 +24,16 @@ components:
       type: apiKey
       in: header
       name: x-hook-secret
-      description: Optional shared secret. Enforced by the delegate (NOT the runtime) only when
-        NANO_PR_WEBHOOK_SECRET is set; unset means the endpoint is open. Declared here for
-        documentation.
+      x-nano-secret-env: NANO_PR_WEBHOOK_SECRET
+      description: Shared secret. Enforced by the delegate (NOT the runtime) on this app's own
+        operations only when NANO_PR_WEBHOOK_SECRET is set; unset means those endpoints are open.
+        The `x-nano-secret-env` extension additionally makes this the app's canonical shared-secret
+        scheme for the Urban runtime's framework mutation guard (`authorizeMutation`), so the
+        framework-owned mutating `urban_debug_*` MCP tools (set_variables, retry_job,
+        resolve_incident, cancel_instance) are authorizable on a remote-exposed instance by
+        presenting the `x-hook-secret` header set to NANO_PR_WEBHOOK_SECRET. One shared secret, one
+        header, for both app-operation reads/mutations and framework mutations. Must remain the sole
+        apiKey scheme carrying `x-nano-secret-env` — the runtime throws on ambiguity.
   schemas:
     ErrorBody:
       type: object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.171.10",
+  "version": "0.171.11",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/overview.page.json

@@ -84,7 +84,7 @@
           "title": "Point your agent at Nano Workforce",
           "description": "Copy this prompt and paste it into your coding agent (Copilot, Claude, etc.). It connects the agent to this instance's MCP server \u2014 the workforce's operations become native tools (including the live operator guide as `getAgentInstructions`, or its addressable companion `getAgentGuide(section?)` \u2014 preferred over the ~43KB blob to avoid tool-result overrun), so it can drive and debug your workforce; agents with no MCP client fall back to fetching the operator skill. Note: `/app/mcp` is served on the same HTTP surface as the rest of the app \u2014 reachable on loopback by default, and from a remote instance (merlin, an ngrok tunnel) only when the app is bound wide (`network.bind`) or fronted by a reverse proxy, per the MCP runbook.",
           "copyLabel": "Copy prompt",
-          "copyText": "Add this running Nano Workforce instance as an MCP server, then help me drive and debug my workforce \u2014 a durable orchestration app that drives pull requests to review convergence against an automated reviewer, merges them, and can take a whole issue and plan \u2192 implement \u2192 converge it across a fleet of coding agents.\n\nRegister ONE MCP server entry per instance (streamable-HTTP transport, URL {{appBase}}app/mcp). Naming the instance makes targeting the wrong one structurally impossible \u2014 its tools are namespaced under that name:\n\n    copilot mcp add --transport http workforce-local {{appBase}}app/mcp\n\nGive each instance its own entry (e.g. `workforce-merlin` for a LAN/remote node). In config form (~/.copilot/mcp-config.json or repo-scoped .mcp.json):\n\n    {\n      \"mcpServers\": {\n        \"workforce-local\": {\n          \"type\": \"http\",\n          \"url\": \"{{appBase}}app/mcp\",\n          \"tools\": [\"*\"]\n        }\n      }\n    }\n\nIf this instance is secured with a shared secret (NANO_PR_WEBHOOK_SECRET), pass it on the MCP connection \u2014 reads AND mutations both require it:\n\n    copilot mcp add --transport http workforce-local {{appBase}}app/mcp \\\n      --header \"x-hook-secret: $NANO_PR_WEBHOOK_SECRET\"\n\nIn config form, add a `headers` entry alongside `url` on that server (per the MCP runbook) \u2014 the config path has no header flag, so omitting this yields 401s:\n\n    \"headers\": { \"x-hook-secret\": \"$NANO_PR_WEBHOOK_SECRET\" }\n\nA Basic-Auth-fronted instance (behind a reverse proxy) additionally needs `Authorization: Basic \u2026` on the connection.\n\nMCP servers register at host startup \u2014 add the entry, THEN start a new session so its tools load. The `workforce-*` tools then appear (the full set of operations projected from this instance's OpenAPI contract, including the live operator guide itself as the `getAgentInstructions` read tool \u2014 or its addressable companion `getAgentGuide(section?)`, which the MCP runbook recommends over the ~43KB blob to avoid tool-result overrun \u2014 plus the `urban_debug_*` family for inspecting a wedged instance's process instances, wait states, and incidents).\n\nThe instance's operations are now native tools. Ask, naming the instance: \"Using workforce-local, show what's in flight and any open escalations.\" It should call the status tool, not curl. Operator-only doors (the delivery-graph stage/dispatch/dismiss lifecycle \u2014 the human click IS the approval) are deliberately not tools.\n\nNo MCP client? The curl path is unchanged \u2014 fetch and follow the live guide (the response is JSON with a `skill` markdown field), adding `-H \"x-hook-secret: <secret>\"` if this instance is secured:\n\n    curl -sS {{appBase}}app/api/agent/skill\n\nThat skill bootstraps you to this instance's live operator guide at {{appBase}}app/api/agent (the same guide MCP exposes as `getAgentInstructions`, or section-addressably as `getAgentGuide`). If you find a bug or a stuck process, the guide explains how to raise an issue or a PR against nanobpm/nano-workforce."
+          "copyText": "Add this running Nano Workforce instance as an MCP server, then help me drive and debug my workforce \u2014 a durable orchestration app that drives pull requests to review convergence against an automated reviewer, merges them, and can take a whole issue and plan \u2192 implement \u2192 converge it across a fleet of coding agents.\n\nRegister ONE MCP server entry per instance (streamable-HTTP transport, URL {{appBase}}app/mcp). Naming the instance makes targeting the wrong one structurally impossible \u2014 its tools are namespaced under that name:\n\n    copilot mcp add --transport http workforce-local {{appBase}}app/mcp\n\nGive each instance its own entry (e.g. `workforce-merlin` for a LAN/remote node). In config form (~/.copilot/mcp-config.json or repo-scoped .mcp.json):\n\n    {\n      \"mcpServers\": {\n        \"workforce-local\": {\n          \"type\": \"http\",\n          \"url\": \"{{appBase}}app/mcp\",\n          \"tools\": [\"*\"]\n        }\n      }\n    }\n\nIf this instance is secured with a shared secret (NANO_PR_WEBHOOK_SECRET), pass it on the MCP connection \u2014 reads AND mutations both require it (including the framework-owned mutating urban_debug_* tools \u2014 set_variables, retry_job, resolve_incident, cancel_instance \u2014 which authorize against this same x-hook-secret on a remote-exposed instance):\n\n    copilot mcp add --transport http workforce-local {{appBase}}app/mcp \\\n      --header \"x-hook-secret: $NANO_PR_WEBHOOK_SECRET\"\n\nIn config form, add a `headers` entry alongside `url` on that server (per the MCP runbook) \u2014 the config path has no header flag, so omitting this yields 401s:\n\n    \"headers\": { \"x-hook-secret\": \"$NANO_PR_WEBHOOK_SECRET\" }\n\nA Basic-Auth-fronted instance (behind a reverse proxy) additionally needs `Authorization: Basic \u2026` on the connection.\n\nMCP servers register at host startup \u2014 add the entry, THEN start a new session so its tools load. The `workforce-*` tools then appear (the full set of operations projected from this instance's OpenAPI contract, including the live operator guide itself as the `getAgentInstructions` read tool \u2014 or its addressable companion `getAgentGuide(section?)`, which the MCP runbook recommends over the ~43KB blob to avoid tool-result overrun \u2014 plus the `urban_debug_*` family for inspecting a wedged instance's process instances, wait states, and incidents).\n\nThe instance's operations are now native tools. Ask, naming the instance: \"Using workforce-local, show what's in flight and any open escalations.\" It should call the status tool, not curl. Operator-only doors (the delivery-graph stage/dispatch/dismiss lifecycle \u2014 the human click IS the approval) are deliberately not tools.\n\nNo MCP client? The curl path is unchanged \u2014 fetch and follow the live guide (the response is JSON with a `skill` markdown field), adding `-H \"x-hook-secret: <secret>\"` if this instance is secured:\n\n    curl -sS {{appBase}}app/api/agent/skill\n\nThat skill bootstraps you to this instance's live operator guide at {{appBase}}app/api/agent (the same guide MCP exposes as `getAgentInstructions`, or section-addressably as `getAgentGuide`). If you find a bug or a stuck process, the guide explains how to raise an issue or a PR against nanobpm/nano-workforce."
         }
       }
     },