@nanobpm/nano-workforce 0.150.1 → 0.150.3

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.150.3](https://github.com/nanobpm/nano-workforce/compare/v0.150.2...v0.150.3) (2026-08-28)
+
+### Bug Fixes
+
+* **compileDeliveryGraph:** key reviewUrl to the request origin ([#577](https://github.com/nanobpm/nano-workforce/issues/577)) ([#581](https://github.com/nanobpm/nano-workforce/issues/581)) ([8c04c95](https://github.com/nanobpm/nano-workforce/commit/8c04c95b9d3617b3d71d28e54a7f24cae54c6e2c))
+
+## [0.150.2](https://github.com/nanobpm/nano-workforce/compare/v0.150.1...v0.150.2) (2026-08-28)
+
+### Bug Fixes
+
+* honour X-Forwarded-Prefix in resolveApiBase so the operator guide baseUrl resolves behind the app-view proxy ([#580](https://github.com/nanobpm/nano-workforce/issues/580)) ([21fdeca](https://github.com/nanobpm/nano-workforce/commit/21fdecac2d7c383cca066fa47950d9b6d28f41fc)), closes [#578](https://github.com/nanobpm/nano-workforce/issues/578)
+
 ## [0.150.1](https://github.com/nanobpm/nano-workforce/compare/v0.150.0...v0.150.1) (2026-08-28)
 
 ### Bug Fixes

package/app/deliveryGraphProposals.test.ts

@@ -25,6 +25,7 @@ import {
   stageProposal,
   sweepExpiredProposals,
 } from "./deliveryGraphProposals.ts";
+import { publicBaseUrl } from "./blackboard.ts";
 
 const APP_ROOT = resolve(import.meta.dirname, "..");
 
@@ -87,6 +88,12 @@ test("proposalReviewUrl: a navigational deep-link to the cockpit page — NOT a
   assert(!/\/actions\//.test(url), "reviewUrl points at a page, never an API action");
 });
 
+test("proposalReviewUrl: with no base falls back to publicBaseUrl() — the text-ingress (no request) path (#577)", () => {
+  // The staging text-ingress path has no HTTP request to derive an origin from, so the default base
+  // must stay the deployment-wide NANO_WORKFORCE_BASE_URL via publicBaseUrl().
+  assertEquals(proposalReviewUrl("abc123"), `${publicBaseUrl()}/app/pages/delivery-graphs#proposal-abc123`);
+});
+
 test("buildProposalRow: stamps status staged, boolean→0/1, and TTL from createdAt", () => {
   const r = row({ sideEffecting: true, createdAt: "2024-01-01T00:00:00.000Z" });
   assertEquals(r.status, "staged");

package/app/resolveApiBase.test.ts

@@ -1,9 +1,10 @@
 // Tests for app/resolveApiBase.ts — the single canonical control-API base reconstruction shared by
-// getAgentInstructions and getAgentSkill. Covers proxy-header handling, scheme restriction,
+// getAgentInstructions and getAgentSkill, plus the human-facing resolvePublicOrigin (#577). Covers
+// proxy-header handling, scheme restriction, host sanitisation, x-forwarded-prefix sanitisation,
 // host-absent fallback, and mount-suffix stripping for both mount depths.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
-import { resolveApiBase } from "./resolveApiBase.ts";
+import { resolveApiBase, resolvePublicOrigin } from "./resolveApiBase.ts";
 
 function req(headers: Record<string, string>, path: string) {
   return { path, headers: new Headers(headers) };
@@ -41,3 +42,136 @@ test("tolerates a leading slash on the mount suffix", () => {
 test("strips multiple trailing slashes after the mount suffix", () => {
   assertEquals(resolveApiBase(req({ host: "h" }, "/app/api/agent/skill///"), "agent/skill"), "http://h/app/api");
 });
+
+// ── resolveApiBase: x-forwarded-prefix sanitisation (#580) via the shared sanitiseForwardedPrefix ──
+test("prepends a validated x-forwarded-prefix to the reconstructed base", () => {
+  const r = req(
+    { host: "nano.ngrok-free.dev", "x-forwarded-prefix": "/console/app-view/Workforce" },
+    "/app/api/agent",
+  );
+  assertEquals(resolveApiBase(r, "agent"), "http://nano.ngrok-free.dev/console/app-view/Workforce/app/api");
+});
+
+test("normalises a trailing slash on x-forwarded-prefix", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "/console/app-view/Workforce/" }, "/app/api/agent");
+  assertEquals(resolveApiBase(r, "agent"), "http://h/console/app-view/Workforce/app/api");
+});
+
+test("ignores a x-forwarded-prefix carrying a scheme", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "https://evil.test" }, "/app/api/agent");
+  assertEquals(resolveApiBase(r, "agent"), "http://h/app/api");
+});
+
+test("ignores a x-forwarded-prefix carrying an authority", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "//evil.test" }, "/app/api/agent");
+  assertEquals(resolveApiBase(r, "agent"), "http://h/app/api");
+});
+
+test("ignores a x-forwarded-prefix with .. traversal", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "/a/../.." }, "/app/api/agent");
+  assertEquals(resolveApiBase(r, "agent"), "http://h/app/api");
+});
+
+test("ignores a x-forwarded-prefix with percent-encoded .. traversal", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "/a/%2e%2e/%2e%2e" }, "/app/api/agent");
+  assertEquals(resolveApiBase(r, "agent"), "http://h/app/api");
+});
+
+test("ignores a x-forwarded-prefix with a percent-encoded authority", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "/%2F%2Fevil.test" }, "/app/api/agent");
+  assertEquals(resolveApiBase(r, "agent"), "http://h/app/api");
+});
+
+test("ignores a relative (non-absolute) x-forwarded-prefix", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "console/app-view/Workforce" }, "/app/api/agent");
+  assertEquals(resolveApiBase(r, "agent"), "http://h/app/api");
+});
+
+test("prefix composes with x-forwarded-proto and x-forwarded-host", () => {
+  const r = req(
+    {
+      host: "internal",
+      "x-forwarded-host": "nano.ngrok-free.dev",
+      "x-forwarded-proto": "https",
+      "x-forwarded-prefix": "/console/app-view/Workforce",
+    },
+    "/app/api/agent/skill",
+  );
+  assertEquals(resolveApiBase(r, "agent/skill"), "https://nano.ngrok-free.dev/console/app-view/Workforce/app/api");
+});
+
+// ── resolvePublicOrigin: the human-facing ORIGIN (+ proxy prefix), no /app/api suffix (#577) ──
+// Shares sanitiseForwardedPrefix with resolveApiBase, so the prefix policy (absolute-only, reject
+// scheme/authority/traversal entirely, percent-aware) is identical on both surfaces — no drift.
+test("resolvePublicOrigin: bare origin from the host header", () => {
+  assertEquals(resolvePublicOrigin(req({ host: "wf.example.com" }, "/app/api/actions/compile-delivery-graph")), "http://wf.example.com");
+});
+
+test("resolvePublicOrigin: honours x-forwarded-proto and x-forwarded-host", () => {
+  const r = req({ host: "internal", "x-forwarded-host": "example.test", "x-forwarded-proto": "https" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "https://example.test");
+});
+
+test("resolvePublicOrigin: restricts x-forwarded-proto to http/https", () => {
+  const r = req({ host: "wf.example.com", "x-forwarded-proto": "javascript" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "http://wf.example.com");
+});
+
+test("resolvePublicOrigin: appends the reverse-proxy x-forwarded-prefix", () => {
+  const r = req(
+    { "x-forwarded-host": "nano.ngrok-free.dev", "x-forwarded-proto": "https", "x-forwarded-prefix": "/console/app-view/Workforce" },
+    "/app/api/actions/compile-delivery-graph",
+  );
+  assertEquals(resolvePublicOrigin(r), "https://nano.ngrok-free.dev/console/app-view/Workforce");
+});
+
+test("resolvePublicOrigin: normalises a trailing slash on x-forwarded-prefix", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "/console/app-view/Workforce/" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "http://h/console/app-view/Workforce");
+});
+
+test("resolvePublicOrigin: treats a slash-only x-forwarded-prefix as empty (no double slash)", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "///" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "http://h");
+});
+
+test("resolvePublicOrigin: rejects a path-traversal x-forwarded-prefix entirely", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "/console/../../etc" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "http://h");
+});
+
+test("resolvePublicOrigin: rejects a scheme/authority x-forwarded-prefix", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "https://evil.example/hijack" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "http://h");
+});
+
+test("resolvePublicOrigin: rejects a relative (non-absolute) x-forwarded-prefix", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "@evil.example" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "http://h");
+});
+
+test("resolvePublicOrigin: falls back to a localhost origin when the Host header is absent", () => {
+  assertEquals(resolvePublicOrigin(req({}, "/app/api/actions/compile-delivery-graph")), "http://localhost:3000");
+});
+
+// ── host sanitisation: the untrusted x-forwarded-host/host authority is reflected into the URL ──
+test("rejects a userinfo-injecting host (falls back to localhost)", () => {
+  const r = req({ "x-forwarded-host": "evil.com@real.example" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "http://localhost:3000");
+  assertEquals(resolveApiBase(req({ "x-forwarded-host": "evil.com@real.example" }, "/app/api/agent"), "agent"), "http://localhost:3000/app/api");
+});
+
+test("rejects a path-injecting host (falls back to localhost)", () => {
+  const r = req({ "x-forwarded-host": "real.example/extra-path" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "http://localhost:3000");
+});
+
+test("accepts a host:port authority", () => {
+  const r = req({ "x-forwarded-host": "wf.example.com:8443", "x-forwarded-proto": "https" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "https://wf.example.com:8443");
+});
+
+test("accepts a bracketed IPv6 host authority", () => {
+  const r = req({ "x-forwarded-host": "[2001:db8::1]:3000" }, "/app/api/actions/compile-delivery-graph");
+  assertEquals(resolvePublicOrigin(r), "http://[2001:db8::1]:3000");
+});

package/app/resolveApiBase.ts

@@ -4,8 +4,9 @@
 // to the request base (getAgentInstructions, getAgentSkill, …) — per AGENTS.md "Derivation over
 // duplication: no drift surfaces", proxy-header handling and base-path stripping must not fork.
 //
-// Honour reverse-proxy forwarding headers; fall back to a localhost default when the Host header is
-// absent (e.g. a raw unit-test request).
+// Honour reverse-proxy forwarding headers — proto, host, and the external path prefix
+// (X-Forwarded-Prefix, e.g. the console app-view proxy's "/console/app-view/{project}") — and fall
+// back to a localhost default when the Host header is absent (e.g. a raw unit-test request).
 
 /**
  * Recover the control-API base from a request, stripping the operation's own mount suffix.
@@ -16,13 +17,72 @@
  *                    "/app/api" when the path is nothing but the suffix.
  */
 export function resolveApiBase(req: { path: string; headers: Headers }, mountSuffix: string): string {
-  const rawProto = (req.headers.get("x-forwarded-proto") ?? "http").split(",")[0].trim().toLowerCase();
-  // x-forwarded-proto is user-controlled behind some proxies; only trust http/https.
-  const proto = rawProto === "http" || rawProto === "https" ? rawProto : "http";
-  const host = (req.headers.get("x-forwarded-host") ?? req.headers.get("host") ?? "").split(",")[0].trim();
+  const { proto, host } = requestProtoHost(req);
+  const prefix = sanitiseForwardedPrefix(req.headers.get("x-forwarded-prefix"));
   // The op is mounted at "<base>/<mountSuffix>"; strip the trailing segments to recover the base path.
   const suffix = mountSuffix.replace(/^\/+/, "").replace(/\/+$/, "");
   const stripRe = new RegExp(`/${suffix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/*$`);
   const basePath = req.path.replace(stripRe, "") || "/app/api";
-  return host ? `${proto}://${host}${basePath}` : `http://localhost:3000${basePath}`;
+  return host ? `${proto}://${host}${prefix}${basePath}` : `http://localhost:3000${prefix}${basePath}`;
+}
+
+/** The public ORIGIN (+ proxy prefix) this request arrived on — the base for a navigational link
+ * handed back to the caller (e.g. a cockpit deep-link), WITHOUT the `/app/api` mount suffix that
+ * {@link resolveApiBase} keeps. Where `resolveApiBase` reconstructs the control-API base an *agent*
+ * calls back on, this reconstructs the human-facing origin: proto + host (same proxy-header trust as
+ * `resolveApiBase`) plus any reverse-proxy path prefix advertised via `x-forwarded-prefix`, so a
+ * link built as `${resolvePublicOrigin(req)}/app/pages/…` opens on the exact origin the operator is
+ * driving this app from (e.g. a tunnel), not a static deployment-wide base. Falls back to a
+ * localhost origin when the Host header is absent (a raw unit-test request). */
+export function resolvePublicOrigin(req: { path: string; headers: Headers }): string {
+  const { proto, host } = requestProtoHost(req);
+  const prefix = sanitiseForwardedPrefix(req.headers.get("x-forwarded-prefix"));
+  return host ? `${proto}://${host}${prefix}` : `http://localhost:3000${prefix}`;
+}
+
+/** Sanitise the untrusted, proxy/user-controlled `x-forwarded-prefix` into a safe leading-slash,
+ * no-trailing-slash path segment (or ""). The ONE canonical prefix sanitiser shared by
+ * {@link resolveApiBase} and {@link resolvePublicOrigin} (AGENTS.md "derivation over duplication") —
+ * the prefix is the reverse-proxy path the public URL was mounted under (e.g.
+ * "/console/app-view/Workforce") and is reflected into a caller-facing URL, so it must not smuggle a
+ * scheme, an authority ("//host"), or a "."/".." traversal segment into the URL. Accept only an
+ * absolute path of URL-safe path characters, then drop trailing slashes so it composes cleanly with
+ * the base path; anything else falls back to an empty prefix. Percent-encoding can smuggle those
+ * forms past a literal check ("%2e%2e" decodes to "..", "%2f%2f" to an authority-introducing "//"),
+ * so normalise the common encoded spellings of "." and "/" (case-insensitively) before rejecting
+ * dot-segments and "//"; the still-encoded raw value is what we reflect once it validates. Because
+ * the return is always either "" or a leading-"/" path, it can never alter the `${proto}://${host}`
+ * authority. */
+function sanitiseForwardedPrefix(raw: string | null): string {
+  const rawPrefix = (raw ?? "").split(",")[0].trim();
+  const decodedPrefix = rawPrefix.replace(/%2e/gi, ".").replace(/%2f/gi, "/");
+  return /^\/(?!\/)[A-Za-z0-9._~\-/%]*$/.test(rawPrefix) &&
+    !decodedPrefix.includes("//") &&
+    !/(^|\/)\.\.?(\/|$)/.test(decodedPrefix)
+    ? rawPrefix.replace(/\/+$/, "")
+    : "";
+}
+
+/** The trusted (proto, host) pair for a request — the ONE place proxy-header handling lives so
+ * `resolveApiBase` and `resolvePublicOrigin` can't drift (AGENTS.md "derivation over duplication").
+ * Only `http`/`https` are trusted from the user-controlled `x-forwarded-proto`; the host prefers
+ * `x-forwarded-host` over `host`. `host` is "" when neither header is present or the advertised host
+ * is not a valid authority (see {@link sanitiseHost}). */
+function requestProtoHost(req: { headers: Headers }): { proto: string; host: string } {
+  const rawProto = (req.headers.get("x-forwarded-proto") ?? "http").split(",")[0].trim().toLowerCase();
+  const proto = rawProto === "http" || rawProto === "https" ? rawProto : "http";
+  const rawHost = (req.headers.get("x-forwarded-host") ?? req.headers.get("host") ?? "").split(",")[0].trim();
+  return { proto, host: sanitiseHost(rawHost) };
+}
+
+/** Sanitise the untrusted, proxy/user-controlled host (`x-forwarded-host`/`host`) into a bare
+ * authority — a registered name or IPv4 with an optional `:port`, or a bracketed IPv6 literal with
+ * an optional `:port` — or "" when it carries anything else. The host is reflected verbatim into the
+ * `${proto}://${host}` authority of a caller-facing URL, so a hostile value like
+ * `evil.com@real.example` (userinfo injection) or `real.example/extra-path` (path injection) must be
+ * rejected outright rather than smuggled through. */
+function sanitiseHost(host: string): string {
+  if (!host) return "";
+  const valid = /^(?:[A-Za-z0-9.-]+|\[[0-9A-Fa-f:.]+\])(?::\d+)?$/.test(host);
+  return valid ? host : "";
 }

package/operations/compileDeliveryGraph.test.ts

@@ -30,8 +30,9 @@ async function withApp(fn: (app: AppApi, data: DataLayer) => Promise<void>): Pro
   }
 }
 
-async function call(app: AppApi, body: unknown) {
-  return (await handler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
+async function call(app: AppApi, body: unknown, headers: Record<string, string> = {}) {
+  const req = { path: "/app/api/actions/compile-delivery-graph", headers: new Headers(headers) };
+  return (await handler({ req: req as any, params: {}, query: {}, body } as any, app)) as any;
 }
 
 const GOOD = {
@@ -79,6 +80,33 @@ test("compile-delivery-graph: the response exposes NO dispatch handle — no run
   });
 });
 
+// ── #577: reviewUrl is a caller-facing link → keyed to the request origin, not the static base ──
+test("compile-delivery-graph: reviewUrl is on the request's forwarded origin, not NANO_WORKFORCE_BASE_URL", async () => {
+  await withApp(async (app) => {
+    const res = await call(app, GOOD, { "x-forwarded-proto": "https", "x-forwarded-host": "example.test" });
+    assertEquals(res.status, 200);
+    assertEquals(
+      res.body.reviewUrl,
+      `https://example.test/app/pages/delivery-graphs#proposal-${res.body.digest}`,
+    );
+  });
+});
+
+test("compile-delivery-graph: reviewUrl honours the reverse-proxy x-forwarded-prefix", async () => {
+  await withApp(async (app) => {
+    const res = await call(app, GOOD, {
+      "x-forwarded-proto": "https",
+      "x-forwarded-host": "nano.ngrok-free.dev",
+      "x-forwarded-prefix": "/console/app-view/Workforce",
+    });
+    assertEquals(res.status, 200);
+    assertEquals(
+      res.body.reviewUrl,
+      `https://nano.ngrok-free.dev/console/app-view/Workforce/app/pages/delivery-graphs#proposal-${res.body.digest}`,
+    );
+  });
+});
+
 test("compile-delivery-graph: re-compiling the same graph is idempotent — one staged proposal, TTL anchored to the first stage", async () => {
   await withApp(async (app, data) => {
     const first = await call(app, GOOD);

package/operations/compileDeliveryGraph.ts

@@ -21,12 +21,13 @@ import {
   stageProposal,
 } from "../app/deliveryGraphProposals.ts";
 import { deliveryGraphDigest } from "../app/deliveryRunner.ts";
+import { resolvePublicOrigin } from "../app/resolveApiBase.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 const STAGED_MESSAGE =
   "The graph compiled and is staged for operator review. Ask the operator to preview and approve — or request modifications — in the cockpit. Dispatch is an operator action; there is no start endpoint.";
 
-export default defineOperation("compileDeliveryGraph", async ({ body }, app) => {
+export default defineOperation("compileDeliveryGraph", async ({ body, req }, app) => {
   // The runtime validates the body's SHAPE against `DeliveryGraph` before we run; the compiler adds
   // the SEMANTIC checks (acyclicity, edge integrity, fact resolution). A directly-invoked delegate
   // could still pass `undefined` — the compiler reads its input as `unknown` and maps that to a clean
@@ -75,7 +76,10 @@ export default defineOperation("compileDeliveryGraph", async ({ body }, app) =>
       message: STAGED_MESSAGE,
       digest,
       preview,
-      reviewUrl: proposalReviewUrl(digest),
+      // Navigational, human-facing link → keyed to the ORIGIN this request arrived on (tunnel,
+      // proxy prefix, …), not the static deployment-wide NANO_WORKFORCE_BASE_URL, so the operator
+      // driving this instance can actually open it (#577).
+      reviewUrl: proposalReviewUrl(digest, resolvePublicOrigin(req)),
     },
   };
 });

package/operations/getAgentInstructions.test.ts

@@ -86,6 +86,30 @@ test("examples are keyed to the request's control-API base and leave no placehol
   assert(!md.includes("__ENGINE__"), "no unsubstituted __ENGINE__ placeholder");
 });
 
+test("x-forwarded-prefix is prepended to the baseUrl and rendered examples", async () => {
+  const proxied = input(
+    {
+      host: "internal",
+      "x-forwarded-host": "nano.ngrok-free.dev",
+      "x-forwarded-proto": "https",
+      "x-forwarded-prefix": "/console/app-view/Workforce",
+    },
+  );
+  const body = (await handler(proxied, app)) as any;
+  assertEquals(body.body.baseUrl, "https://nano.ngrok-free.dev/console/app-view/Workforce/app/api");
+  const md = body.body.instructions as string;
+  assert(
+    md.includes("https://nano.ngrok-free.dev/console/app-view/Workforce/app/api/version"),
+    "prefixed base URL substituted into examples",
+  );
+});
+
+test("a hostile x-forwarded-prefix is ignored rather than reflected into the baseUrl", async () => {
+  const hostile = input({ host: "wf.example.com", "x-forwarded-prefix": "https://evil.test" });
+  const body = (await handler(hostile, app)) as any;
+  assertEquals(body.body.baseUrl, "http://wf.example.com/app/api", "hostile prefix falls back to today's behaviour");
+});
+
 test("x-forwarded-proto is restricted to http/https", async () => {
   const spoofed = input({ host: "wf.example.com", "x-forwarded-proto": "javascript" });
   const body = (await handler(spoofed, app)) as any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.150.1",
+  "version": "0.150.3",
   "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",