@nanobpm/nano-workforce 0.68.0 → 0.69.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.69.0](https://github.com/nanobpm/nano-workforce/compare/v0.68.0...v0.69.0) (2026-08-15)
+
+
+### Features
+
+* **agentic:** enable nwf for a remote fleet — loopback-guard the LOCAL token + document network posture ([#224](https://github.com/nanobpm/nano-workforce/issues/224)) ([#228](https://github.com/nanobpm/nano-workforce/issues/228)) ([73f6170](https://github.com/nanobpm/nano-workforce/commit/73f6170ff4c0df0ad6c4eb2a2e6e9b3df5d1e343)), closes [nano-ide#235](https://github.com/nano-ide/issues/235) [nano-ide#235](https://github.com/nano-ide/issues/235)
+
 # [0.68.0](https://github.com/nanobpm/nano-workforce/compare/v0.67.0...v0.68.0) (2026-08-14)
 
 

package/README.md

@@ -263,6 +263,70 @@ active epic already targets the same custom base. See
 | `NANO_PR_MAX_CI_FIX_ROUNDS` | `3` | max `senior:fix-ci` attempts to green a `blocked` PR before escalating; `0` disables (escalate immediately), clamped 0–20 |
 | `NANO_PR_REVIEW_WAIT_TIMEOUT` | `PT20M` | ISO-8601 duration the loop waits for a fresh review before escalating a stalled review (timer arm of the `wait-review` gateway) |
 | `NANO_PR_REVIEW_NUDGE_MINUTES` | `5` | cooldown between the poller's automatic reviewer re-request nudges for one waiting PR (clamped 1–1440) |
+| `NANO_PR_PUBLIC_BASE_URL` | `http://localhost:3000` | externally-reachable base URL for the capability hooks (`/app/api/hooks/*`). Must resolve from **wherever the agent runs** — set it to the app's LAN address (or console-proxy URL) for a remote fleet. Falls back to `NANO_PR_BASE_URL`, then `http://localhost:3000`. See [Fleet networking](#fleet-networking-remote-workers) |
+| `NANO_AGENTIC_SECRET` | — | enables **secure mode** for the agentic visibility channel (`/agentic`): requires an ADR 0028 identity token + capability credential from every peer. Required to attach agentic visibility from **off-box** workers; unset = on-by-default **LOCAL mode** (well-known token, loopback peers only). Also accepts `NANO_PR_WEBHOOK_SECRET` |
+
+### Fleet networking (remote workers)
+
+`nano-workforce` can drive a **distributed worker fleet** — `senior:*` agents running on other LAN
+machines. Two app surfaces must be reachable from those off-box workers:
+
+- The **capability hooks** — `/app/api/hooks/abandon` and `/app/api/hooks/blackboard`. Every
+  side-effecting agent is handed an unguessable per-run capability URL in its prompt and `curl`s it
+  before each irreversible action (an unknown token is a `404`). A remote worker can only reach these
+  if (a) the app's HTTP server is bound so off-box hosts can connect, and (b) the base URL baked into
+  that prompt resolves from the worker's host — hence **`NANO_PR_PUBLIC_BASE_URL` must be the app's
+  LAN address, not `localhost`**.
+- The **agentic visibility channel** — `/agentic` (WebSocket). In on-by-default **LOCAL mode** it is
+  gated only by a *well-known, non-secret* localhost token, so it is enforced **loopback-only**: an
+  off-box peer is refused — as is a **reverse-proxied** peer (a connection carrying an
+  `X-Forwarded-For`/`Forwarded`/`X-Real-IP` header is refused even over loopback, so forwarding
+  `/agentic` through the console proxy cannot smuggle the well-known token off-box). To give remote
+  workers visibility, run the channel in **secure mode** by setting `NANO_AGENTIC_SECRET`. (Fleet
+  coordination itself does not depend on this channel — it is visibility only.)
+
+#### Bind the HTTP server
+
+The capability hooks are only reachable off-box if the app's HTTP server binds to a routable
+interface. The declarative, per-app control is an **app-manifest** setting (loopback by default,
+opt-in to all interfaces):
+
+```jsonc
+// nano.app.json
+{ "network": { "bind": "all" } }   // 0.0.0.0 / :: — expose to the LAN for a remote fleet
+```
+
+> **Status:** this manifest key is delivered by the Urban runtime in
+> [`nanobpm/nano-ide#235`](https://github.com/nanobpm/nano-ide/issues/235) (add the field to the app
+> schema + plumb the bind host to the node adapter). Until that lands, the runtime binds to all
+> interfaces by default (Node's `listen(port)` default), so a fleet already reaches the hooks — but
+> once the parallel *loopback-by-default* change ships, set `"network": { "bind": "all" }` here to
+> keep nwf reachable. This repo is ready for that flip; nwf already enforces the LOCAL-token
+> loopback-only guard so binding wide never exposes the well-known agentic token off-box.
+
+#### Choose a path: direct LAN bind vs console proxy
+
+nwf composes with two deployment topologies — pick one and point the fleet at it:
+
+| Path | When | Fleet uses |
+|---|---|---|
+| **Direct LAN bind** | nwf run standalone for a fleet | Bind the server wide (above) and set `NANO_PR_PUBLIC_BASE_URL=http://<app-lan-host>:3000`. Workers `curl` the hooks directly on the app's LAN address. |
+| **Console reverse-proxy** | nwf embedded behind the nano console at `/console/app-view/Workforce` | Leave the app bound to loopback and set `NANO_PR_PUBLIC_BASE_URL` to the console's public origin + the app-view prefix, so `/app/api/hooks/*` resolves through the proxy. Workers reach the hooks via the console. |
+
+Either way the capability URL in each agent's prompt (`${NANO_PR_PUBLIC_BASE_URL}/app/api/hooks/…`)
+must resolve from the worker's host. **Verify** from a fleet host before relying on it:
+
+```sh
+# From a remote LAN worker, against the base URL seeded into agent prompts.
+# A live run returns { "prKey": "...", "status": "...", "abandoned": false }; -f exits non-zero on 404.
+curl -fsS "${NANO_PR_PUBLIC_BASE_URL}/app/api/hooks/abandon?token=<per-run-token>"
+```
+
+If the `curl` cannot reach the host, off-box agents will (correctly, per the abort contract) treat the
+run as abandoned and stop — the exact failure behind
+[`jwulf/c8ctl-plugin-nano#76`](https://github.com/jwulf/c8ctl-plugin-nano/issues/76). Fix it by
+binding wide + setting a routable `NANO_PR_PUBLIC_BASE_URL`, or by fronting nwf with the console proxy.
+
 
 ### Purge
 

package/app/agentic/channel.test.ts

@@ -5,11 +5,19 @@
 // hub is visible via `inspect()`, families mount/tear-down through the seam, and shutdown is clean.
 import { type AddressInfo, createServer, type Server } from "node:http";
 import { test } from "node:test";
+import { AUTH_UNAUTHORIZED } from "@nanobpm/agentic/channel";
 import { createLogger } from "@nanobpm/urban/runtime";
 import { WebSocket } from "ws";
 import { assert, assertEquals } from "#test-assert";
 import { noopLog } from "../../test/log.ts";
-import { type AgenticChannelHandle, LOCAL_AGENTIC_TOKEN, mountAgenticChannel } from "./channel.ts";
+import {
+  type AgenticChannelHandle,
+  isForwardedConnection,
+  isLoopbackRemote,
+  LOCAL_AGENTIC_TOKEN,
+  loopbackOnly,
+  mountAgenticChannel,
+} from "./channel.ts";
 import { type AgenticContext, AgenticFamilyRegistry } from "./registry.ts";
 
 const SECRET = "test-agentic-secret";
@@ -359,3 +367,79 @@ test("LOCAL mode does NOT warn when the server is bound to loopback", async (t)
   const warned = records.some((r) => r.level === "warn" && r.msg.includes("not bound to loopback"));
   assert(!warned, "a loopback-bound LOCAL channel is the expected safe case and must not warn");
 });
+
+// --- Loopback-only enforcement of the LOCAL well-known token (issue #224 / nano-ide#235) ---
+//
+// The LOCAL token is not a secret, so once the app binds to all interfaces (network.bind: "all") it
+// must never be honoured off-box. `isLoopbackRemote` vets the peer's origin; `loopbackOnly` wraps an
+// authenticator to refuse a non-loopback peer with 4401 while delegating loopback peers to the base.
+
+test("isLoopbackRemote accepts same-host peers and rejects everything else", () => {
+  for (const ok of ["127.0.0.1", "127.0.0.5", "::1", "::ffff:127.0.0.1", "::ffff:127.1.2.3"]) {
+    assert(isLoopbackRemote(ok), `${ok} should be loopback`);
+  }
+  for (const no of [undefined, "", "10.0.0.4", "192.168.1.20", "::ffff:10.0.0.4", "2001:db8::1", "0.0.0.0"]) {
+    assert(!isLoopbackRemote(no), `${String(no)} should NOT be loopback`);
+  }
+});
+
+test("loopbackOnly refuses a non-loopback peer with 4401 and never calls the base authenticator", () => {
+  let baseCalls = 0;
+  const base = () => {
+    baseCalls++;
+    return { ok: true as const, grant: { identity: "peer" } };
+  };
+  const guarded = loopbackOnly(base);
+
+  const remote = guarded({ token: LOCAL_AGENTIC_TOKEN, remote: "10.0.0.4" });
+  assert(!("then" in remote), "authenticator result is synchronous here");
+  assertEquals((remote as { ok: boolean; code?: number }).ok, false);
+  assertEquals((remote as { code?: number }).code, AUTH_UNAUTHORIZED);
+  assertEquals(baseCalls, 0);
+});
+
+test("loopbackOnly delegates a loopback peer to the base authenticator", () => {
+  let baseCalls = 0;
+  const base = () => {
+    baseCalls++;
+    return { ok: true as const, grant: { identity: "peer" } };
+  };
+  const guarded = loopbackOnly(base);
+
+  const local = guarded({ token: LOCAL_AGENTIC_TOKEN, remote: "127.0.0.1" });
+  assertEquals((local as { ok: boolean }).ok, true);
+  assertEquals(baseCalls, 1);
+});
+
+// A reverse proxy that connects to the app over loopback makes an off-box client appear same-host to
+// `req.remote`. `isForwardedConnection` detects the relay from proxy-forwarding headers, so
+// `loopbackOnly` fails closed on a proxied peer even when `req.remote` itself is loopback.
+
+test("isForwardedConnection detects proxy-forwarding headers and ignores absent/empty ones", () => {
+  assert(isForwardedConnection({ "x-forwarded-for": "10.0.0.4" }), "x-forwarded-for marks a relay");
+  assert(isForwardedConnection({ forwarded: "for=10.0.0.4" }), "forwarded marks a relay");
+  assert(isForwardedConnection({ "x-real-ip": "10.0.0.4" }), "x-real-ip marks a relay");
+
+  assert(!isForwardedConnection(undefined), "no headers is a direct connection");
+  assert(!isForwardedConnection({}), "empty headers is a direct connection");
+  assert(!isForwardedConnection({ "x-forwarded-for": "   " }), "whitespace value is treated as absent");
+  assert(!isForwardedConnection({ "content-type": "application/json" }), "unrelated headers are ignored");
+});
+
+test("loopbackOnly refuses a reverse-proxied peer (loopback remote + forwarding header) with 4401", () => {
+  let baseCalls = 0;
+  const base = () => {
+    baseCalls++;
+    return { ok: true as const, grant: { identity: "peer" } };
+  };
+  const guarded = loopbackOnly(base);
+
+  const proxied = guarded({
+    token: LOCAL_AGENTIC_TOKEN,
+    remote: "127.0.0.1",
+    headers: { "x-forwarded-for": "203.0.113.7" },
+  });
+  assertEquals((proxied as { ok: boolean; code?: number }).ok, false);
+  assertEquals((proxied as { code?: number }).code, AUTH_UNAUTHORIZED);
+  assertEquals(baseCalls, 0);
+});

package/app/agentic/channel.ts

@@ -17,6 +17,8 @@ import type { Server } from "node:http";
 import type { AddressInfo } from "node:net";
 import {
   AgenticHub,
+  AUTH_UNAUTHORIZED,
+  type Authenticator,
   sharedSecretAuthenticator,
   WebSocketChannelTransport,
 } from "@nanobpm/agentic/channel";
@@ -53,6 +55,83 @@ function isLoopbackBind(addr: string | AddressInfo | null): boolean {
   return host === "::1" || host === "::ffff:127.0.0.1" || host.startsWith("127.");
 }
 
+/**
+ * True if a peer's remote address (`req.remote`, i.e. `socket.remoteAddress`) is a same-host /
+ * loopback peer. This is the per-connection counterpart to {@link isLoopbackBind}: while that vets
+ * the *server's* bind, this vets the *client's* origin, so LOCAL mode can be honoured off a
+ * wildcard/all-interfaces bind (`network.bind: "all"`, issue #224) yet still refuse the well-known
+ * {@link LOCAL_AGENTIC_TOKEN} to anything but a same-machine peer. Loopback is `127.0.0.0/8`, `::1`,
+ * or the IPv6-mapped IPv4 forms Node reports on a dual-stack listener (`::ffff:127.x`). An
+ * absent/unparseable remote is NOT provably same-host, so it is treated as non-loopback
+ * (fail-closed), matching the `isLoopbackBind(null) === false` posture.
+ */
+export function isLoopbackRemote(remote: string | undefined): boolean {
+  if (!remote) return false;
+  return (
+    remote === "::1" ||
+    remote === "::ffff:127.0.0.1" ||
+    remote.startsWith("127.") ||
+    remote.startsWith("::ffff:127.")
+  );
+}
+
+/**
+ * Proxy-forwarding request headers. Their presence means the connection was relayed through a
+ * reverse proxy, so `req.remote` is the *proxy's* address (typically loopback for an embedded/console
+ * proxy) rather than the true client — a loopback `remote` no longer proves a same-host peer. A
+ * genuine same-machine loopback peer connects directly and never carries one of these.
+ */
+const FORWARDING_HEADERS: readonly string[] = ["x-forwarded-for", "forwarded", "x-real-ip"];
+
+/**
+ * True if the handshake carries a proxy-forwarding header — i.e. the connection reached us through a
+ * reverse proxy, so `req.remote` is the proxy, not the originating client. Used to fail LOCAL mode
+ * closed: a relayed connection can present a loopback `remote` (the proxy) while the real client is
+ * off-box, so the well-known token must never be honoured for it (see {@link loopbackOnly}). Headers
+ * are lower-cased by the transport ({@link HandshakeRequest.headers}); an empty/whitespace value is
+ * treated as absent.
+ */
+export function isForwardedConnection(headers: Readonly<Record<string, string>> | undefined): boolean {
+  if (!headers) return false;
+  return FORWARDING_HEADERS.some((h) => {
+    const value = headers[h];
+    return typeof value === "string" && value.trim() !== "";
+  });
+}
+
+/**
+ * Wrap `base` so a peer is admitted ONLY from a direct, same-host loopback connection. LOCAL mode
+ * gates purely on the well-known {@link LOCAL_AGENTIC_TOKEN}, which is not a secret — so once the app
+ * is exposed on the LAN (`network.bind: "all"`, issue #224) that token must never be honoured
+ * off-box. This enforces the invariant per-connection (any other peer is closed `4401`), independent
+ * of the server's bind, closing the interplay the bind-to-all setting exposes (nano-ide#235).
+ *
+ * Two ways a peer can fail to be a same-host loopback client, both refused:
+ *  - a non-loopback `req.remote` (a direct off-box connection); or
+ *  - a proxy-forwarding header ({@link isForwardedConnection}) — the connection was relayed, so a
+ *    loopback `req.remote` is the *proxy*, not the client. Refusing any forwarded connection keeps
+ *    the guard robust even if `/agentic` is inadvertently reverse-proxied over loopback (the
+ *    embedded/console-proxy topology), where the off-box client would otherwise appear same-host.
+ *
+ * Note this guards ONLY the agentic visibility channel: the capability HTTP hooks
+ * (`/app/api/hooks/*`) carry their own unguessable per-request tokens and stay reachable off-box
+ * (including through the console proxy), which is what a remote fleet needs. To attach agentic
+ * visibility from off-box — directly or via a proxy — run the channel in SECURE mode instead.
+ */
+export function loopbackOnly(base: Authenticator): Authenticator {
+  return (req) => {
+    if (isForwardedConnection(req.headers) || !isLoopbackRemote(req.remote)) {
+      return {
+        ok: false,
+        code: AUTH_UNAUTHORIZED,
+        reason:
+          "LOCAL-mode agentic channel is loopback-only and refuses reverse-proxied peers; use secure mode (NANO_AGENTIC_SECRET) for off-box or proxied peers",
+      };
+    }
+    return base(req);
+  };
+}
+
 export interface MountAgenticChannelOptions {
   /** The app's own `node:http` server (share its port; `app.httpServer` narrowed to `Server`). */
   readonly server: Server;
@@ -116,39 +195,44 @@ export async function mountAgenticChannel(
   }
 
   const transport = new WebSocketChannelTransport({ server, path: AGENTIC_PATH });
+  // LOCAL mode gates only on the well-known localhost token, so it must be honoured only for a
+  // same-machine peer: wrap the authenticator to refuse any non-loopback remote (see loopbackOnly).
+  // Secure mode presents a real ADR 0028 identity token + capability credential, so it is safe from
+  // any origin and needs no such guard.
+  const baseAuthenticator = sharedSecretAuthenticator({ secret, requireCredential: secure });
   const hub = new AgenticHub({
     transport,
     // Secure mode: a valid identity token PLUS a required capability credential upgrades; either
     // missing/invalid is rejected (4401 / 4403). Swap in a real ADR 0028 verifier later by passing an
-    // Authenticator. LOCAL mode: token-only (the well-known localhost token), no credential required.
-    authenticator: sharedSecretAuthenticator({ secret, requireCredential: secure }),
+    // Authenticator. LOCAL mode: token-only (the well-known localhost token), loopback peers only.
+    authenticator: secure ? baseAuthenticator : loopbackOnly(baseAuthenticator),
     onError: (err, connectionId) =>
       log.warn("agentic hub error", { connectionId, err: String(err) }),
   });
   // Share the app's port: the transport rode the existing server, so it is already listening.
   await transport.ready();
 
-  // LOCAL mode gates only on the well-known localhost token, so it is safe ONLY while the server is
-  // bound to loopback. The channel rides the app's server and does not own its bind address, so it
-  // cannot enforce this — but if the server is exposed on a wildcard/public interface, the token is
-  // reachable off-box; warn loudly so an operator either binds to loopback or switches to secure mode.
-  // A `null` address (server not listening yet) is unverifiable — warn rather than silently skipping
-  // the exposure check, since the bind could later resolve to a public interface.
+  // LOCAL mode is now enforced loopback-only per connection (see loopbackOnly), so the well-known
+  // token can never be honoured off-box even on a wildcard/all-interfaces bind. A non-loopback bind
+  // is still worth surfacing though: it means off-box agentic peers are REFUSED, so a remote worker
+  // fleet gets no visibility until the channel runs in secure mode. Warn so the operator makes the
+  // deliberate choice. A `null` address (server not listening yet) is unverifiable — warn too.
   if (!secure) {
     const addr = server.address();
     if (addr === null) {
       log.warn(
         "agentic channel is in LOCAL mode but the server bind address could not be verified " +
-          "(the server is not listening yet) — the well-known LOCAL_AGENTIC_TOKEN cannot be " +
-          "confirmed loopback-only. Mount the channel after the server is listening, set " +
-          "NANO_AGENTIC_SECRET for secure mode, or bind the server to 127.0.0.1.",
+          "(the server is not listening yet) — the loopback-only enforcement for the well-known " +
+          "LOCAL_AGENTIC_TOKEN cannot be confirmed. Mount the channel after the server is listening, " +
+          "set NANO_AGENTIC_SECRET for secure mode, or bind the server to 127.0.0.1.",
         { mode: "local", bind: null },
       );
     } else if (!isLoopbackBind(addr)) {
       log.warn(
-        "agentic channel is in LOCAL mode but the server is not bound to loopback — the well-known " +
-          "LOCAL_AGENTIC_TOKEN is reachable from other hosts. Set NANO_AGENTIC_SECRET for secure " +
-          "mode, or bind the server to 127.0.0.1.",
+        "agentic channel is in LOCAL mode but the server is not bound to loopback — off-box peers " +
+          "are refused the channel (the well-known LOCAL_AGENTIC_TOKEN is enforced loopback-only), " +
+          "so a remote worker fleet cannot attach visibility. Set NANO_AGENTIC_SECRET for secure " +
+          "mode to serve remote peers, or bind the server to 127.0.0.1.",
         { mode: "local", bind: typeof addr === "object" ? addr.address : String(addr) },
       );
     }

package/package.json

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