@nanobpm/urban 0.47.0 → 0.49.0

package/src/runtime/core/modules/surfaces.test.ts

@@ -29,6 +29,7 @@ function ctxWith(surfaces: Record<string, unknown>): Parameters<typeof mountSurf
     cancelInstance: async () => {},
     publishMessage: async () => {},
     searchUserTasks: async () => [],
+    getForm: async () => null,
     completeUserTask: async () => {},
     searchProcessInstances: async () => [],
     registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
@@ -43,6 +44,7 @@ const fakeEngine: EngineClient = {
   cancelInstance: async () => {},
   publishMessage: async () => {},
   searchUserTasks: async () => [],
+  getForm: async () => null,
   completeUserTask: async () => {},
   searchProcessInstances: async () => [],
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
@@ -76,13 +78,204 @@ test("chat agent is HTML-escaped in the mount page", async () => {
   assert.ok(body.includes("&lt;img src=x onerror=alert(1)&gt;"), "agent is escaped");
 });
 
-test("task-inbox path is injected as a quoted JS literal (no script breakout)", async () => {
+test("task-inbox client derives its API base from location (reverse-proxy safe, no path embedding)", async () => {
+  // The client must NOT embed the manifest-supplied route base as an absolute
+  // literal: a hardcoded "/tasks" escapes the Nano console's path-prefixed
+  // reverse proxy (/console/app-view/<name>/tasks) — every fetch to
+  // "/tasks/api/…" 404s upstream. Deriving the base from location.pathname keeps
+  // the API calls document-relative (correct at the origin root AND under the
+  // proxy) and, as a bonus, removes the manifest→<script> injection surface
+  // entirely: nothing manifest-supplied is embedded in the page at all.
   const evil = "/tasks'});alert(1);//x";
   const s = mountSurfaces(ctxWith({ taskInbox: { enabled: true, path: evil } }), fakeApp);
   const page = s.routes.find((r) => r.source === "surface:taskInbox" && r.method === "GET" && !r.path.endsWith("/api/tasks"))!;
   const body = await render(page);
-  // The path is embedded via JSON.stringify, so the raw breakout sequence must
-  // not appear unescaped inside the <script>.
-  assert.ok(!body.includes("'});alert(1);//'"), "no raw single-quoted breakout");
-  assert.ok(body.includes(JSON.stringify(evil)), "path embedded as a JSON string literal");
+  // The manifest path (evil or otherwise) is never emitted into the page.
+  assert.ok(!body.includes("alert(1)"), "manifest path is not embedded — nothing to inject");
+  assert.ok(!body.includes(JSON.stringify(evil)), "manifest path is not embedded as a JS literal");
+  // The base is derived from where the page was actually served, so it inherits
+  // any reverse-proxy path prefix instead of a root-absolute mount path.
+  assert.ok(body.includes("location.pathname"), "client derives its API base from location.pathname");
+  assert.ok(!/const\s+BASE\s*=\s*["'/]/.test(body), "client does not embed an absolute route base");
 });
+
+/** Build an app handle backed by a specific engine (the flow tests drive the routes). */
+function appWith(engine: EngineClient): Parameters<typeof mountSurfaces>[1] {
+  return {
+    manifest: { schemaVersion: 1, id: "app", name: "App" },
+    data: new DataLayer(new Map(), undefined, {}),
+    engine,
+    env: () => undefined,
+    log: createLogger(() => {}),
+  };
+}
+
+/** Invoke a route handler with an optional query string and POST body. */
+async function call(
+  route: { handler: (req: HttpRequest) => HttpResponse | Promise<HttpResponse> },
+  opts: { method?: string; query?: string; body?: string } = {},
+): Promise<HttpResponse> {
+  return route.handler({
+    method: opts.method ?? "GET",
+    path: "/",
+    query: new URLSearchParams(opts.query ?? ""),
+    headers: new Headers(),
+    text: async () => opts.body ?? "",
+  });
+}
+
+function inboxRoutes(engine: EngineClient) {
+  const s = mountSurfaces(ctxWith({ taskInbox: { enabled: true, path: "/tasks" } }), appWith(engine));
+  const at = (suffix: string, method = "GET") =>
+    s.routes.find(
+      (r) => r.source === "surface:taskInbox" && r.method === method && r.path.endsWith(suffix),
+    )!;
+  return {
+    page: s.routes.find((r) => r.source === "surface:taskInbox" && r.method === "GET" && r.path === "/tasks")!,
+    tasks: at("/api/tasks"),
+    form: at("/api/form"),
+    complete: at("/api/complete", "POST"),
+  };
+}
+
+test("inbox page renders the client-side form fetch + renderer", async () => {
+  const { page } = inboxRoutes(fakeEngine);
+  const rendered = String((await call(page)).body);
+  assert.ok(rendered.includes("/api/form"), "page fetches the linked form");
+  assert.ok(rendered.includes("function renderForm"), "page has a form renderer");
+  assert.ok(rendered.includes("function buildField"), "page builds fields from the schema");
+  assert.ok(rendered.includes("/api/complete"), "page posts completion");
+  // Drift guard: the client script is a stringified <script> body, so it is invisible to
+  // the type checker. UserTaskSummary carries `formKey`/`externalFormReference` but no
+  // `formId`, so the client must never branch on a task-supplied `formId` (that phantom
+  // field would silently be `undefined`). Lock the drift closed.
+  assert.ok(!rendered.includes("formId"), "client script must not reference formId — UserTaskSummary carries none");
+  // Prototype-pollution guard: submit builds `variables` from engine-supplied component
+  // keys (a schema could key a field '__proto__'/'constructor'). It must use a null-
+  // prototype bag so an untrusted key lands as an own property, never mutating a prototype.
+  assert.ok(rendered.includes("Object.create(null)"), "client builds the variables bag with a null prototype");
+  assert.ok(!/const\s+variables\s*=\s*\{\}/.test(rendered), "client must not collect untrusted keys into a plain {} object");
+});
+
+test("/api/tasks surfaces the resolved form linkage", async () => {
+  let seenFilter: unknown;
+  const engine: EngineClient = {
+    ...fakeEngine,
+    searchUserTasks: async (filter) => {
+      seenFilter = filter;
+      return [
+        { userTaskKey: "1", elementId: "approve", formKey: "form-123" },
+        { userTaskKey: "2", elementId: "review" },
+      ];
+    },
+  };
+  const { tasks } = inboxRoutes(engine);
+  const res = await call(tasks, { query: "processInstanceKey=pi-9" });
+  assert.deepEqual(seenFilter, { processInstanceKey: "pi-9" });
+  const parsed = JSON.parse(String(res.body));
+  assert.equal(parsed[0].formKey, "form-123");
+  assert.equal(parsed[1].formKey, undefined);
+});
+
+test("/api/form resolves a linked form's schema", async () => {
+  let seen: unknown;
+  const schema = { type: "default", schemaVersion: 18, components: [{ type: "textfield", key: "name", label: "Name" }] };
+  const engine: EngineClient = {
+    ...fakeEngine,
+    getForm: async (input) => {
+      seen = input;
+      return { formKey: "form-123", schema };
+    },
+  };
+  const { form } = inboxRoutes(engine);
+  const res = await call(form, { query: "formKey=form-123" });
+  assert.deepEqual(seen, { formKey: "form-123", formId: undefined });
+  assert.equal(res.status, 200);
+  assert.deepEqual(JSON.parse(String(res.body)).schema, schema);
+});
+
+test("/api/form requires an identifier", async () => {
+  const { form } = inboxRoutes(fakeEngine);
+  const res = await call(form);
+  assert.equal(res.status, 400);
+});
+
+test("/api/form passes an empty formKey through so getForm can fall back to formId", async () => {
+  // A `?formKey=&formId=…` request must not be rejected at the boundary (only *both*
+  // identifiers absent is a 400) nor stripped here — resolving an empty key to its formId
+  // fallback is getForm's single responsibility (see nanosdk getForm empty/whitespace test).
+  let seen: unknown;
+  const engine: EngineClient = {
+    ...fakeEngine,
+    getForm: async (input) => {
+      seen = input;
+      return { formKey: "form-9", schema: { type: "default", components: [] } };
+    },
+  };
+  const { form } = inboxRoutes(engine);
+  const res = await call(form, { query: "formKey=&formId=form-9" });
+  assert.equal(res.status, 200);
+  assert.deepEqual(seen, { formKey: "", formId: "form-9" });
+});
+
+test("/api/form 400s a whitespace-only identifier instead of a spurious 204", async () => {
+  // A `?formKey=   ` (or `formId=   `) request provides no usable identifier. The route's
+  // presence gate must follow getForm's canonical rule (whitespace = absent) and 400,
+  // rather than letting the blank key slip past a raw truthiness check to getForm (→ null
+  // → 204). Guards the route↔getForm presence drift on the taskInbox form path — Red when
+  // the gate checks raw `!formKey && !formId`, since "   " is truthy.
+  const { form } = inboxRoutes(fakeEngine);
+  assert.equal((await call(form, { query: "formKey=%20%20%20" })).status, 400);
+  assert.equal((await call(form, { query: "formId=%20%20" })).status, 400);
+});
+
+test("/api/form returns 204 for a task with no resolvable form (no-form fallback)", async () => {
+  const engine: EngineClient = { ...fakeEngine, getForm: async () => null };
+  const { form } = inboxRoutes(engine);
+  const res = await call(form, { query: "formKey=missing" });
+  assert.equal(res.status, 204);
+  // The body must be empty: a "null" payload (json(null, 204)) makes the client's
+  // fetch helper throw on parse and surface "Failed to load form" instead of the
+  // no-form fallback. Guard the wire shape here and the client short-circuit below.
+  assert.equal(res.body, "");
+});
+
+test("inbox client fetch helper short-circuits 204 so the no-form fallback renders", async () => {
+  const { page } = inboxRoutes(fakeEngine);
+  const rendered = String((await call(page)).body);
+  // The api() helper must not call r.json() on a 204 (empty body → throw). It has
+  // to resolve to null so openForm() falls through to renderNoForm(t).
+  assert.ok(rendered.includes("r.status===204"), "api() short-circuits a 204 response");
+  assert.ok(rendered.includes("function renderNoForm"), "page has a no-form renderer");
+});
+
+test("number field reader guards against a non-numeric (tampered) value", async () => {
+  // A number field submits `Number(raw)`; a non-numeric value (only reachable via tampering
+  // — the browser blanks invalid type=number input) yields NaN, which JSON.stringify
+  // serializes as null, silently changing the submission. The inline reader must guard it
+  // with Number.isFinite so a bad value is treated as absent rather than submitted as NaN.
+  const { page } = inboxRoutes(fakeEngine);
+  const rendered = String((await call(page)).body);
+  assert.ok(rendered.includes("Number.isFinite"), "number field guards NaN via Number.isFinite");
+});
+
+test("/api/complete completes the task with the submitted variables", async () => {
+  const calls: { key: string; variables?: Record<string, unknown> }[] = [];
+  const engine: EngineClient = {
+    ...fakeEngine,
+    completeUserTask: async (key, variables) => {
+      calls.push({ key, variables });
+    },
+  };
+  const { complete } = inboxRoutes(engine);
+  const res = await call(complete, { method: "POST", body: JSON.stringify({ userTaskKey: "7", variables: { name: "Ada", agree: true } }) });
+  assert.equal(res.status, 200);
+  assert.deepEqual(calls, [{ key: "7", variables: { name: "Ada", agree: true } }]);
+});
+
+test("/api/complete rejects a body with no userTaskKey", async () => {
+  const { complete } = inboxRoutes(fakeEngine);
+  const res = await call(complete, { method: "POST", body: JSON.stringify({ variables: {} }) });
+  assert.equal(res.status, 400);
+});
+

package/src/runtime/core/modules/surfaces.ts

@@ -1,10 +1,15 @@
 // surfaces — the hosted human surfaces (ADR 0026). Implements the `taskInbox` surface: a
-// small JSON+HTML task list backed by the engine's user-task search, that renders the
-// linked `.form` and posts completion back. The `chat` surface is stubbed as a mount point
-// (LLM wiring is a separate concern). Surfaces contribute routes to the shared server.
+// small JSON+HTML task list backed by the engine's user-task search. Each open task links to
+// its deployed `.form` via the engine-resolved `formKey`; the list fetches that form's form-js
+// schema (`GET base/api/form`), renders its fields client-side with a minimal built-in
+// renderer, and posts the entered field values as the completion `variables` (`POST
+// base/api/complete`). A task with no linked form keeps the bare key-list + raw-complete
+// behavior. The `chat` surface is stubbed as a mount point (LLM wiring is a separate concern).
+// Surfaces contribute routes to the shared server.
 
 import type { AppApi, RuntimeContext } from "../context.ts";
-import { html, json, normalizeRoutePath, type Route } from "../router.ts";
+import { presentFormIdentifier } from "../host.ts";
+import { html, json, noContent, normalizeRoutePath, type Route } from "../router.ts";
 import { mountActions } from "./actions.ts";
 import { mountApi } from "./api.ts";
 import { mountPages } from "./pages.ts";
@@ -22,23 +27,169 @@ export interface SurfacesHandle {
   describe(): Record<string, unknown>;
 }
 
-function inboxPage(basePath: string): string {
+function inboxPage(): string {
+  // Reverse-proxy safe: the client derives its API base from location.pathname
+  // (where THIS page was actually served) rather than an embedded absolute
+  // route base. A hardcoded "/tasks" would escape the Nano console's
+  // path-prefixed proxy (/console/app-view/<name>/tasks) — the API fetches must
+  // inherit that prefix. Deriving from location also removes the manifest→
+  // <script> injection surface entirely: nothing manifest-supplied is embedded.
+  // All task/form values are rendered via textContent / setAttribute — never
+  // innerHTML — so nothing the engine returns can inject markup.
   return `<!doctype html><meta charset="utf-8"><title>Task inbox</title>
 <style>body{font:14px system-ui,sans-serif;margin:2rem;max-width:52rem}
-li{margin:.4rem 0}code{background:#f4f4f4;padding:.1rem .3rem;border-radius:3px}</style>
+ul{list-style:none;padding:0}li{margin:.4rem 0;display:flex;align-items:center;gap:.5rem}
+code{background:#f4f4f4;padding:.1rem .3rem;border-radius:3px}
+button{font:inherit;padding:.2rem .6rem;cursor:pointer}
+form label{display:block;margin:.6rem 0 .2rem;font-weight:600}
+form .field input,form .field textarea,form .field select{font:inherit;padding:.3rem;width:100%;box-sizing:border-box;max-width:24rem}
+form .field input[type=checkbox],form .field input[type=radio]{width:auto}
+#form{margin-top:1.5rem;border-top:1px solid #ddd;padding-top:1rem}
+.muted{color:#666}</style>
 <h1>Task inbox</h1><ul id="tasks"><li>loading…</li></ul>
+<div id="form"></div>
 <script>
-fetch(${JSON.stringify(basePath)}+'/api/tasks').then(r=>r.json()).then(ts=>{
-  const ul=document.getElementById('tasks');
-  ul.replaceChildren();
-  if(!ts.length){const li=document.createElement('li');li.textContent='No open tasks.';ul.appendChild(li);return;}
-  for(const t of ts){const li=document.createElement('li');
-    const code=document.createElement('code');
-    code.textContent=t.elementId||t.userTaskKey;
-    li.appendChild(code);
-    li.appendChild(document.createTextNode(' — key '+t.userTaskKey));
-    ul.appendChild(li);}
-});
+const BASE=location.pathname.replace(/\/+$/,'');
+const tasksEl=document.getElementById('tasks');
+const formEl=document.getElementById('form');
+
+function api(path,opts){return fetch(BASE+path,opts).then(r=>{if(!r.ok)return r.text().then(t=>{throw new Error(t||r.status)});if(r.status===204)return null;return r.json();});}
+
+function loadTasks(){
+  formEl.replaceChildren();
+  tasksEl.replaceChildren(el('li',{},'loading…'));
+  return api('/api/tasks').then(ts=>{
+    tasksEl.replaceChildren();
+    if(!ts.length){tasksEl.appendChild(el('li',{},'No open tasks.'));return;}
+    for(const t of ts){
+      const li=document.createElement('li');
+      const code=el('code',{},t.elementId||t.userTaskKey);
+      li.appendChild(code);
+      li.appendChild(document.createTextNode(' — key '+t.userTaskKey));
+      if(t.formKey){
+        li.appendChild(btn('Open',()=>openForm(t)));
+      }else{
+        li.appendChild(btn('Complete',()=>complete(t.userTaskKey,{})));
+      }
+      tasksEl.appendChild(li);
+    }
+  }).catch(err=>tasksEl.replaceChildren(el('li',{class:'muted'},'Failed to load tasks: '+err.message)));
+}
+
+function openForm(t){
+  formEl.replaceChildren(el('p',{class:'muted'},'loading form…'));
+  const q='formKey='+encodeURIComponent(t.formKey);
+  api('/api/form?'+q).then(f=>{
+    formEl.replaceChildren();
+    if(!f||!f.schema){renderNoForm(t);return;}
+    renderForm(t,f.schema);
+  }).catch(err=>{formEl.replaceChildren(el('p',{class:'muted'},'Failed to load form: '+err.message));});
+}
+
+function renderNoForm(t){
+  formEl.appendChild(el('p',{class:'muted'},'This task has no renderable form.'));
+  const bar=el('div',{});
+  bar.appendChild(btn('Complete',()=>complete(t.userTaskKey,{})));
+  bar.appendChild(btn('Cancel',loadTasks));
+  formEl.appendChild(bar);
+}
+
+function renderForm(t,schema){
+  const form=document.createElement('form');
+  form.appendChild(el('h2',{},'Task '+(t.elementId||t.userTaskKey)));
+  const components=Array.isArray(schema.components)?schema.components:[];
+  const inputs=[];
+  for(const c of components){
+    const built=buildField(c);
+    if(!built)continue;
+    form.appendChild(built.field);
+    if(built.read)inputs.push(built.read);
+  }
+  const submit=btn('Submit',null);submit.type='submit';
+  const bar=el('div',{});bar.appendChild(submit);bar.appendChild(btn('Cancel',loadTasks));
+  form.appendChild(bar);
+  form.addEventListener('submit',e=>{
+    e.preventDefault();
+    // Null-prototype: field keys come from the engine-supplied form schema. A component
+    // keyed '__proto__'/'constructor' must land as a plain own property (and round-trip
+    // through JSON), never mutate a prototype — no prototype pollution in the page runtime.
+    const variables=Object.create(null);
+    for(const read of inputs){const kv=read();if(kv)variables[kv.key]=kv.value;}
+    submit.disabled=true;
+    complete(t.userTaskKey,variables).catch(()=>{submit.disabled=false;});
+  });
+  formEl.appendChild(form);
+}
+
+function buildField(c){
+  const type=c&&c.type;
+  // Static (keyless) components: show text as a paragraph, ignore layout-only ones.
+  if(type==='text'){return {field:el('p',{class:'muted'},typeof c.text==='string'?c.text:'')};}
+  const key=c&&c.key;
+  if(!key)return null;
+  const wrap=el('div',{class:'field'});
+  const label=typeof c.label==='string'&&c.label?c.label:key;
+  if(type==='checkbox'){
+    const input=document.createElement('input');input.type='checkbox';
+    const lab=el('label',{});lab.appendChild(input);lab.appendChild(document.createTextNode(' '+label));
+    wrap.appendChild(lab);
+    return {field:wrap,read:()=>({key,value:input.checked})};
+  }
+  const labelEl=el('label',{},label);
+  wrap.appendChild(labelEl);
+  let input;
+  if(type==='textarea'){input=document.createElement('textarea');}
+  else if(type==='select'){
+    input=document.createElement('select');
+    input.appendChild(el('option',{value:''},'—'));
+    for(const o of (Array.isArray(c.values)?c.values:[])){
+      input.appendChild(el('option',{value:String(o.value)},String(o.label!=null?o.label:o.value)));
+    }
+  }
+  else if(type==='radio'){
+    const name='r'+Math.random().toString(36).slice(2);
+    const group=el('div',{});
+    for(const o of (Array.isArray(c.values)?c.values:[])){
+      const rlab=el('label',{});
+      const r=document.createElement('input');r.type='radio';r.name=name;r.value=String(o.value);
+      rlab.appendChild(r);rlab.appendChild(document.createTextNode(' '+String(o.label!=null?o.label:o.value)));
+      group.appendChild(rlab);
+    }
+    wrap.appendChild(group);
+    return {field:wrap,read:()=>{const sel=group.querySelector('input:checked');return sel?{key,value:sel.value}:null;}};
+  }
+  else{
+    input=document.createElement('input');
+    input.type=(type==='number')?'number':(type==='datetime'?'datetime-local':'text');
+  }
+  // Associate the label with the input (for/id) so screen readers announce it on focus.
+  const fieldId='f'+Math.random().toString(36).slice(2);
+  input.id=fieldId;labelEl.setAttribute('for',fieldId);
+  wrap.appendChild(input);
+  const isNumber=type==='number';
+  return {field:wrap,read:()=>{
+    const raw=input.value;
+    if(raw===''||raw==null)return null;
+    if(isNumber){
+      const n=Number(raw);
+      // A non-numeric value in a number field is only reachable via tampering (the browser
+      // blanks invalid type=number input). Treat it as absent rather than silently submitting
+      // NaN, which JSON.stringify serializes as null — quietly changing the submitted value.
+      return Number.isFinite(n)?{key,value:n}:null;
+    }
+    return {key,value:raw};
+  }};
+}
+
+function complete(userTaskKey,variables){
+  return api('/api/complete',{method:'POST',headers:{'content-type':'application/json'},
+    body:JSON.stringify({userTaskKey,variables})}).then(loadTasks);
+}
+
+function el(tag,attrs,text){const e=document.createElement(tag);for(const k in attrs)e.setAttribute(k,attrs[k]);if(text!=null)e.textContent=text;return e;}
+function btn(label,onClick){const b=document.createElement('button');b.type='button';b.textContent=label;if(onClick)b.addEventListener('click',onClick);return b;}
+
+loadTasks();
 </script>`;
 }
 
@@ -56,7 +207,7 @@ export function mountSurfaces(ctx: RuntimeContext, app: AppApi): SurfacesHandle
       method: "GET",
       path: base,
       source: "surface:taskInbox",
-      handler: () => html(inboxPage(base)),
+      handler: () => html(inboxPage()),
     });
     routes.push({
       method: "GET",
@@ -68,6 +219,28 @@ export function mountSurfaces(ctx: RuntimeContext, app: AppApi): SurfacesHandle
         return json(tasks);
       },
     });
+    routes.push({
+      method: "GET",
+      path: `${base}/api/form`,
+      source: "surface:taskInbox",
+      handler: async (req) => {
+        const formKey = req.query.get("formKey") ?? undefined;
+        const formId = req.query.get("formId") ?? undefined;
+        // Reject only when *neither* identifier is present. Presence follows getForm's
+        // canonical rule (`presentFormIdentifier`: empty/whitespace = absent) so a
+        // whitespace-only `?formKey=   ` request 400s here instead of slipping past a raw
+        // truthiness check and returning a spurious 204. The raw values are still passed
+        // through unchanged — resolving a blank key to its `formId` fallback is getForm's
+        // single responsibility.
+        if (!presentFormIdentifier(formKey) && !presentFormIdentifier(formId))
+          return json({ error: "formKey or formId required" }, 400);
+        const form = await app.engine.getForm({ formKey, formId });
+        // A task whose form can't be resolved returns 204: the client renders the
+        // no-form fallback rather than erroring.
+        if (!form) return noContent();
+        return json(form);
+      },
+    });
     routes.push({
       method: "POST",
       path: `${base}/api/complete`,

package/src/runtime/core/modules/triggers.test.ts

@@ -30,6 +30,7 @@ class MiniEngine implements EngineClient {
     this.calls.push({ kind: "message", target: input.name, correlationKey: input.correlationKey, variables: input.variables });
   }
   async searchUserTasks(): Promise<[]> { return []; }
+  async getForm(): Promise<null> { return null; }
   async completeUserTask(): Promise<void> {}
   async searchProcessInstances(): Promise<[]> { return []; }
   async registerWorker(jobType: string): Promise<{ jobType: string; unsubscribe(): Promise<void> }> {

package/src/runtime/core/modules/workers.test.ts

@@ -15,6 +15,7 @@ class MiniEngine implements EngineClient {
   async cancelInstance(): Promise<void> {}
   async publishMessage(): Promise<void> {}
   async searchUserTasks(): Promise<[]> { return []; }
+  async getForm(): Promise<null> { return null; }
   async completeUserTask(): Promise<void> {}
   async searchProcessInstances(): Promise<[]> { return []; }
   async close(): Promise<void> {}

package/src/runtime/core/router.test.ts

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { normalizeRoutePath } from "./router.ts";
+import { noContent, normalizeRoutePath } from "./router.ts";
 
 test("normalizeRoutePath ensures a leading slash and trims trailing slashes", () => {
   assert.equal(normalizeRoutePath("hooks/x", "/fallback"), "/hooks/x");
@@ -20,3 +20,12 @@ test("normalizeRoutePath falls back when value is missing or collapses to root",
   assert.equal(normalizeRoutePath("/", "/tasks"), "/tasks");
   assert.equal(normalizeRoutePath("", "/tasks"), "/tasks");
 });
+
+test("noContent emits a 204 with an empty body and no content-type", () => {
+  const res = noContent();
+  assert.equal(res.status, 204);
+  // 204 must carry no body: a "null" (or any) payload violates the semantics and
+  // makes a body-parsing client throw. Guard against a json(null, 204) regression.
+  assert.equal(res.body, "");
+  assert.equal(res.headers?.["content-type"], undefined);
+});

package/src/runtime/core/router.ts

@@ -26,6 +26,16 @@ export function text(body: string, status = 200): HttpResponse {
   return { status, headers: { "content-type": "text/plain; charset=utf-8" }, body };
 }
 
+/**
+ * A `204 No Content` response: an empty body and no `content-type`. Use this
+ * instead of `json(null, 204)` — the latter emits a `"null"` body that both
+ * violates the no-body semantics of 204 and makes a client that parses the
+ * body throw. Any client that short-circuits 204 receives no payload here.
+ */
+export function noContent(): HttpResponse {
+  return { status: 204, headers: {}, body: "" };
+}
+
 /**
  * Normalize a manifest-supplied route path: collapse leading slashes to exactly
  * one, drop trailing slashes. Incoming request paths always start with "/", so a

package/src/runtime/core/runtime.test.ts

@@ -41,6 +41,9 @@ class FakeEngine implements EngineClient {
   async searchUserTasks() {
     return this.userTasks;
   }
+  async getForm() {
+    return null;
+  }
   async completeUserTask(key: string, variables?: Record<string, unknown>) {
     this.completedTasks.push({ key, variables });
   }
@@ -70,7 +73,7 @@ function expectArray(value: unknown): unknown[] {
   return value;
 }
 
-async function makeFixture(): Promise<string> {
+async function makeFixture(extraManifest?: Record<string, unknown>): Promise<string> {
   const dir = await mkdtemp(join(tmpdir(), "urban-rt-"));
   await mkdir(join(dir, "processes"));
   await mkdir(join(dir, "decisions"));
@@ -103,6 +106,7 @@ async function makeFixture(): Promise<string> {
     workers: [{ taskType: "wf.claim", handler: "workers/handlers.ts" }],
     triggers: [{ id: "hook", type: "webhook", path: "/hooks/task", action: { message: "wf.requested", correlationKey: "= body.taskId" } }],
     surfaces: { taskInbox: { enabled: true, path: "/tasks" } },
+    ...extraManifest,
   };
   await writeFile(join(dir, "nano.app.json"), JSON.stringify(manifest, null, 2));
   return dir;
@@ -569,6 +573,68 @@ test("treats NANOBPMN_APP_HANDSHAKE other than \"1\" as opt-out", async () => {
   }
 });
 
+// Read the interface a started app's HTTP server actually bound to (issue #235).
+function appBoundAddress(app: { httpServer: object | undefined }): string {
+  const native = app.httpServer;
+  assert.ok(native instanceof http.Server, "app exposes a node http.Server");
+  const addr = native.address();
+  assert.ok(addr && typeof addr === "object", "server has a bound AddressInfo");
+  return addr.address;
+}
+
+test("defaults to a loopback bind when the manifest omits network (issue #235)", async () => {
+  const dir = await makeFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+  await app.start();
+  try {
+    assert.equal(appBoundAddress(app), "127.0.0.1");
+  } finally {
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('manifest network.bind:"all" binds every interface (issue #235)', async () => {
+  const dir = await makeFixture({ network: { bind: "all" } });
+  const logs: Array<{ level: string; msg: string }> = [];
+  const host = createNodeHost({ cwd: dir, log: (level, msg) => logs.push({ level, msg }) });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+  await app.start();
+  try {
+    assert.equal(appBoundAddress(app), "0.0.0.0");
+    // exposing the app off-box must never be silent
+    assert.ok(
+      logs.some((l) => l.level === "warn" && l.msg.includes("all interfaces")),
+      "a warning is logged when binding to all interfaces",
+    );
+  } finally {
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("URBAN_BIND=all overrides a loopback manifest (issue #235)", async () => {
+  const dir = await makeFixture({ network: { bind: "loopback" } });
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const prev = process.env.URBAN_BIND;
+  process.env.URBAN_BIND = "all";
+  let app: Awaited<ReturnType<typeof createUrbanApp>> | undefined;
+  try {
+    app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+    await app.start();
+    assert.equal(appBoundAddress(app), "0.0.0.0");
+  } finally {
+    if (prev === undefined) delete process.env.URBAN_BIND;
+    else process.env.URBAN_BIND = prev;
+    await app?.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 // A minimal deterministic scheduler seam: records armed timers so a test can assert the
 // injected scheduler — not the live one — drives createUrbanApp's background loops.
 function countingScheduler(): SchedulerDeps & { armed: () => number } {