@nanobpm/nano-workforce 0.66.0 → 0.67.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.67.0](https://github.com/nanobpm/nano-workforce/compare/v0.66.0...v0.67.0) (2026-08-14)
+
+
+### Features
+
+* **agentic:** local-first visibility — on by default, security opt-in (hub) ([#218](https://github.com/nanobpm/nano-workforce/issues/218)) ([ffef1d9](https://github.com/nanobpm/nano-workforce/commit/ffef1d9819679cb6995ad2d2825bce5c6cabccb5)), closes [jwulf/c8ctl-plugin-nano#38](https://github.com/jwulf/c8ctl-plugin-nano/issues/38)
+
 # [0.66.0](https://github.com/nanobpm/nano-workforce/compare/v0.65.0...v0.66.0) (2026-08-14)
 
 

package/app/agentic/channel.test.ts

@@ -5,10 +5,11 @@
 // 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 { createLogger } from "@nanobpm/urban/runtime";
 import { WebSocket } from "ws";
 import { assert, assertEquals } from "#test-assert";
 import { noopLog } from "../../test/log.ts";
-import { type AgenticChannelHandle, mountAgenticChannel } from "./channel.ts";
+import { type AgenticChannelHandle, LOCAL_AGENTIC_TOKEN, mountAgenticChannel } from "./channel.ts";
 import { type AgenticContext, AgenticFamilyRegistry } from "./registry.ts";
 
 const SECRET = "test-agentic-secret";
@@ -242,3 +243,119 @@ test("a missing secret is refused (never mount an open channel)", async (t) => {
   assert(threw, "mountAgenticChannel must reject an empty secret");
   assertEquals(port > 0, true);
 });
+
+test("LOCAL mode (secure:false): the well-known token upgrades with NO credential", async (t) => {
+  const { server, port } = await startHttp();
+  // Local-first default-on: no secret, no credential — a `nano work` worker appears live with the
+  // well-known localhost token alone (security opt-in).
+  const channel = await mountAgenticChannel({
+    server,
+    secret: "",
+    secure: false,
+    data: undefined,
+    log: noopLog(),
+  });
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const ws = await connect(port, `?token=${LOCAL_AGENTIC_TOKEN}`);
+  assertEquals(ws.readyState, WebSocket.OPEN);
+  assertEquals(channel.hub.connectionCount, 1);
+  assertEquals(channel.inspect().mode, "local");
+  ws.close();
+});
+
+test("LOCAL mode still rejects a wrong token (4401)", async (t) => {
+  const { server, port } = await startHttp();
+  const channel = await mountAgenticChannel({
+    server,
+    secret: "",
+    secure: false,
+    data: undefined,
+    log: noopLog(),
+  });
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const closedCode = await rejectionCode(port, "?token=not-the-local-token");
+  assertEquals(closedCode, 4401);
+  assertEquals(channel.hub.connectionCount, 0);
+});
+
+/** A capturing `Logger`: records every `(level, msg)` pair the sink receives. */
+function capturingLog(): { log: ReturnType<typeof noopLog>; records: Array<{ level: string; msg: string }> } {
+  const records: Array<{ level: string; msg: string }> = [];
+  const log = createLogger((level: string, msg: string) => {
+    records.push({ level, msg });
+  });
+  return { log, records };
+}
+
+test("LOCAL mode warns when the server is bound to a non-loopback interface", async (t) => {
+  const server = createServer((_req, res) => res.end());
+  await new Promise<void>((resolve) => server.listen(0, "0.0.0.0", resolve));
+  const { log, records } = capturingLog();
+  const channel = await mountAgenticChannel({
+    server,
+    secret: "",
+    secure: false,
+    data: undefined,
+    log,
+  });
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const warned = records.some((r) => r.level === "warn" && r.msg.includes("not bound to loopback"));
+  assert(warned, "LOCAL mode on a non-loopback bind must warn that the well-known token is exposed");
+});
+
+test("LOCAL mode warns when the server bind address is unverifiable (not listening)", async (t) => {
+  const { server } = await startHttp();
+  // Simulate a server whose bind cannot be verified (e.g. mounted before `listen` resolves):
+  // `address()` returns null, so the LOCAL exposure check cannot confirm a loopback-only bind.
+  const realAddress = server.address.bind(server);
+  server.address = () => null;
+  const { log, records } = capturingLog();
+  const channel = await mountAgenticChannel({
+    server,
+    secret: "",
+    secure: false,
+    data: undefined,
+    log,
+  });
+  t.after(async () => {
+    server.address = realAddress;
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const warned = records.some(
+    (r) => r.level === "warn" && r.msg.includes("bind address could not be verified"),
+  );
+  assert(warned, "LOCAL mode on an unbound server must warn that the well-known token is unverifiable");
+});
+
+test("LOCAL mode does NOT warn when the server is bound to loopback", async (t) => {
+  const { server } = await startHttp();
+  const { log, records } = capturingLog();
+  const channel = await mountAgenticChannel({
+    server,
+    secret: "",
+    secure: false,
+    data: undefined,
+    log,
+  });
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  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");
+});

package/app/agentic/channel.ts

@@ -14,6 +14,7 @@
 // Invariants (ADR 0056): app-tier only, never the engine; the Camunda-8 job protocol (worker⇄engine)
 // is untouched; advisory semantics preserved (a family never gates a BPMN sequence flow).
 import type { Server } from "node:http";
+import type { AddressInfo } from "node:net";
 import {
   AgenticHub,
   sharedSecretAuthenticator,
@@ -26,11 +27,47 @@ import { AgenticFamilyRegistry } from "./registry.ts";
 /** The path the agentic channel is served on, on the app's own port. */
 export const AGENTIC_PATH = "/agentic";
 
+/**
+ * The well-known identity token used in LOCAL mode (security opt-in). Nano is local-first: on a
+ * developer's own machine the visibility channel is on by default with no credential friction, so
+ * the hub and the `nano work` worker agree on this constant, well-known localhost token. It is NOT
+ * a secret — it only gates same-machine dev traffic. In secure mode (`secure: true` + a real
+ * `NANO_AGENTIC_SECRET`) this constant is never used and a real ADR 0028 verifier applies. Keep in
+ * lock-step with the worker constant in jwulf/c8ctl-plugin-nano (`c8ctl-plugin.js` LOCAL_AGENTIC_TOKEN).
+ */
+export const LOCAL_AGENTIC_TOKEN = "nano-local";
+
+/**
+ * True if `addr` (from {@link Server.address}) is a loopback / same-machine bind — the safety
+ * assumption LOCAL mode relies on. A string address is a UNIX domain socket / named pipe (same-host
+ * only) and is treated as safe; a TCP bind is loopback only for `127.0.0.0/8` or `::1`. A wildcard
+ * bind (`0.0.0.0` / `::`) or any specific public interface is NOT loopback, so the well-known
+ * {@link LOCAL_AGENTIC_TOKEN} would be reachable off-box. `null` (an unbound / not-yet-listening
+ * server) is NOT treated as safe — the bind is unverifiable, so callers must handle it explicitly
+ * rather than silently skipping the exposure check.
+ */
+function isLoopbackBind(addr: string | AddressInfo | null): boolean {
+  if (addr === null) return false;
+  if (typeof addr === "string") return true;
+  const host = addr.address;
+  return host === "::1" || host === "::ffff:127.0.0.1" || host.startsWith("127.");
+}
+
 export interface MountAgenticChannelOptions {
   /** The app's own `node:http` server (share its port; `app.httpServer` narrowed to `Server`). */
   readonly server: Server;
-  /** The shared-secret ADR 0028 identity token every valid peer must present as `?token=…`. */
+  /** The shared-secret ADR 0028 identity token every valid peer must present as `?token=…`. In LOCAL
+   * mode (`secure: false`) this may be empty — the hub substitutes {@link LOCAL_AGENTIC_TOKEN}. */
   readonly secret: string;
+  /**
+   * Security mode. Nano is local-first, so this defaults to `true` (strict) at the library level to
+   * keep the fail-closed contract for any caller that doesn't opt in — but `main.ts` passes
+   * `secure: false` whenever no `NANO_AGENTIC_SECRET` is configured, mounting an on-by-default LOCAL
+   * channel: a well-known localhost token ({@link LOCAL_AGENTIC_TOKEN}) and NO required capability
+   * credential. Set `secure: true` (with a real secret) to require an ADR 0028 identity token AND a
+   * capability credential on every upgrade.
+   */
+  readonly secure?: boolean;
   /** The app's SQLite data layer, threaded to family modules (may be absent when data isn't mounted). */
   readonly data: DataLayer | undefined;
   /** A structured logger for lifecycle lines. */
@@ -67,21 +104,56 @@ async function discoverRegistry(log: Logger): Promise<AgenticFamilyRegistry> {
 export async function mountAgenticChannel(
   opts: MountAgenticChannelOptions,
 ): Promise<AgenticChannelHandle> {
-  const { server, secret, data, log } = opts;
-  if (!secret) throw new Error("mountAgenticChannel requires a non-empty identity secret");
+  const { server, data, log } = opts;
+  // Local-first: `secure` defaults to true at the library level (fail-closed for callers that don't
+  // opt in), but `main.ts` passes `secure: false` for the on-by-default LOCAL channel. In LOCAL mode
+  // an empty secret is fine — we substitute the well-known localhost token and drop the credential
+  // requirement so a `nano work` worker appears live with zero configuration.
+  const secure = opts.secure ?? true;
+  const secret = opts.secret || (secure ? "" : LOCAL_AGENTIC_TOKEN);
+  if (secure && !secret) {
+    throw new Error("mountAgenticChannel (secure mode) requires a non-empty identity secret");
+  }
 
   const transport = new WebSocketChannelTransport({ server, path: AGENTIC_PATH });
   const hub = new AgenticHub({
     transport,
-    // 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.
-    authenticator: sharedSecretAuthenticator({ secret, requireCredential: true }),
+    // 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 }),
     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.
+  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.",
+        { 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.",
+        { mode: "local", bind: typeof addr === "object" ? addr.address : String(addr) },
+      );
+    }
+  }
+
   // If discovery or any family mount throws, the transport + hub are already live: tear down whatever
   // mounted (in reverse) and close the hub before rethrowing, so a failed boot never strands upgrade
   // handlers or half-open connections.
@@ -97,6 +169,7 @@ export async function mountAgenticChannel(
 
   log.info("agentic channel mounted", {
     path: AGENTIC_PATH,
+    mode: secure ? "secure" : "local",
     families: registry.names(),
   });
 
@@ -108,6 +181,7 @@ export async function mountAgenticChannel(
     inspect() {
       return {
         path: AGENTIC_PATH,
+        mode: secure ? "secure" : "local",
         families: registry.names(),
         connections: hub.connectionCount,
         address: hub.address,

package/main.ts

@@ -46,24 +46,40 @@ const app = await runFromEnv({ engine, host, port: PORT, handleSignals: false })
 // Agentic visibility channel (ADR 0056, epic #142). Ride the app's OWN HTTP server so the channel
 // shares the app port (no sidecar). This is the ONLY main.ts wiring for the whole epic — sibling
 // slices (H1/H3/H4) extend it by dropping a family module under `app/agentic/families/`, never here.
-// Mount only when a shared identity secret is configured, so the app never exposes an
-// unauthenticated upgrade; `app.httpServer` is a `node:http` Server once started (undefined on hosts
-// that don't surface one, e.g. Deno).
+//
+// Local-first (security opt-in): Nano is designed for local use, so the channel is ON BY DEFAULT.
+//   - No secret configured  -> LOCAL mode: well-known localhost token, no credential required, so a
+//     `nano work` worker appears live with zero configuration.
+//   - `NANO_AGENTIC_SECRET` (or `NANO_PR_WEBHOOK_SECRET`) set -> SECURE mode: ADR 0028 identity token
+//     + capability credential required on every upgrade.
+//   - `NANO_AGENTIC=off` (or 0/false/no) -> disabled entirely.
+// `app.httpServer` is a `node:http` Server once started (undefined on hosts that don't surface one,
+// e.g. Deno).
 let agentic: AgenticChannelHandle | undefined;
 const agenticSecret = envVar("NANO_AGENTIC_SECRET") ?? envVar("NANO_PR_WEBHOOK_SECRET");
+const agenticDisabled = /^(0|off|false|no)$/i.test(envVar("NANO_AGENTIC") ?? "");
 const httpServer = app.httpServer;
 if (httpServer instanceof Server) {
-  if (agenticSecret) {
+  if (agenticDisabled) {
+    app.log.info("agentic channel disabled (NANO_AGENTIC=off)");
+  } else {
+    const secure = Boolean(agenticSecret);
     agentic = await mountAgenticChannel({
       server: httpServer,
-      secret: agenticSecret,
+      secret: agenticSecret ?? "",
+      secure,
       data: app.data,
       log: app.log,
     });
-  } else {
-    app.log.warn("agentic channel not mounted: set NANO_AGENTIC_SECRET (or NANO_PR_WEBHOOK_SECRET)");
+    if (!secure) {
+      app.log.info(
+        "agentic channel mounted in LOCAL mode (on by default, token-only — a well-known localhost " +
+          "token, no capability credential). Set NANO_AGENTIC_SECRET for secure mode, or " +
+          "NANO_AGENTIC=off to disable.",
+      );
+    }
   }
-} else if (agenticSecret) {
+} else if (!agenticDisabled) {
   app.log.warn("agentic channel not mounted: app.httpServer is not a node:http Server on this host");
 }
 

package/package.json

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