@nanobpm/nano-workforce 0.150.1 → 0.150.2

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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/resolveApiBase.test.ts

@@ -41,3 +41,59 @@ 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");
 });
+
+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");
+});

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.
@@ -20,9 +21,29 @@ export function resolveApiBase(req: { path: string; headers: Headers }, mountSuf
   // 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();
+  // The external path prefix stripped by a reverse proxy (e.g. the console app-view proxy mounts us
+  // under "/console/app-view/{project}"). X-Forwarded-Prefix is the de-facto standard header for it.
+  // It is untrusted, proxy-supplied input that ends up in a URL handed to an agent, so validate it as
+  // strictly as x-forwarded-proto above: accept only an absolute path of URL-safe path characters —
+  // rejecting anything with a scheme, an authority ("//host"), or a "."/".." traversal segment — then
+  // drop trailing slashes so it composes cleanly with the base path. Anything else falls back to an
+  // empty prefix, i.e. today's behaviour.
+  //
+  // Percent-encoding can smuggle those forms past a literal check: "%2e%2e" decodes to "..", and
+  // "%2f%2f" decodes 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.
+  const rawPrefix = (req.headers.get("x-forwarded-prefix") ?? "").split(",")[0].trim();
+  const decodedPrefix = rawPrefix.replace(/%2e/gi, ".").replace(/%2f/gi, "/");
+  const prefix =
+    /^\/(?!\/)[A-Za-z0-9._~\-/%]*$/.test(rawPrefix) &&
+    !decodedPrefix.includes("//") &&
+    !/(^|\/)\.\.?(\/|$)/.test(decodedPrefix)
+      ? rawPrefix.replace(/\/+$/, "")
+      : "";
   // 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}`;
 }

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.2",
   "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",