@nanobpm/urban 0.1.0 → 0.2.0

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

@@ -0,0 +1,42 @@
+// Security regression tests for the hosted surfaces: manifest-provided values
+// (surface paths, chat agent) must not be able to inject markup/script.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mountSurfaces } from "./surfaces.ts";
+import type { HttpRequest, HttpResponse } from "../host.ts";
+
+function ctxWith(surfaces: Record<string, unknown>) {
+  return {
+    manifest: { id: "app", surfaces } as unknown,
+    host: { log: () => {} },
+  } as unknown as Parameters<typeof mountSurfaces>[0];
+}
+
+const fakeApp = { engine: { async searchUserTasks() { return []; } } } as unknown as Parameters<
+  typeof mountSurfaces
+>[1];
+
+async function render(route: { handler: (req: HttpRequest) => HttpResponse | Promise<HttpResponse> }): Promise<string> {
+  const res = await route.handler({ method: "GET", url: "/", query: new URLSearchParams(), text: async () => "" } as unknown as HttpRequest);
+  return String(res.body);
+}
+
+test("chat agent is HTML-escaped in the mount page", async () => {
+  const s = mountSurfaces(ctxWith({ chat: { enabled: true, agent: "<img src=x onerror=alert(1)>" } }), fakeApp);
+  const chatRoute = s.routes.find((r) => r.source === "surface:chat" && r.method === "GET")!;
+  const body = await render(chatRoute);
+  assert.ok(!body.includes("<img src=x"), "raw markup must not appear");
+  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 () => {
+  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");
+});

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

@@ -0,0 +1,103 @@
+// 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.
+
+import type { AppApi, RuntimeContext } from "../context.ts";
+import { html, json, normalizeRoutePath, type Route } from "../router.ts";
+
+/** Escape HTML-significant characters before embedding a value in markup. */
+function escapeHtml(s: string): string {
+  return s.replace(/[&<>"']/g, (c) =>
+    ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]!,
+  );
+}
+
+export interface SurfacesHandle {
+  readonly name: string;
+  routes: Route[];
+  describe(): Record<string, unknown>;
+}
+
+function inboxPage(basePath: string): string {
+  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>
+<h1>Task inbox</h1><ul id="tasks"><li>loading…</li></ul>
+<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);}
+});
+</script>`;
+}
+
+/** Mount the enabled surfaces and return their routes. */
+export function mountSurfaces(ctx: RuntimeContext, app: AppApi): SurfacesHandle {
+  const routes: Route[] = [];
+  const surfaces = ctx.manifest.surfaces ?? {};
+  const enabled: string[] = [];
+
+  const inbox = surfaces.taskInbox;
+  if (inbox?.enabled) {
+    const base = normalizeRoutePath(inbox.path, "/tasks");
+    enabled.push(`taskInbox@${base}`);
+    routes.push({
+      method: "GET",
+      path: base,
+      source: "surface:taskInbox",
+      handler: () => html(inboxPage(base)),
+    });
+    routes.push({
+      method: "GET",
+      path: `${base}/api/tasks`,
+      source: "surface:taskInbox",
+      handler: async (req) => {
+        const pik = req.query.get("processInstanceKey") ?? undefined;
+        const tasks = await app.engine.searchUserTasks(pik ? { processInstanceKey: pik } : undefined);
+        return json(tasks);
+      },
+    });
+    routes.push({
+      method: "POST",
+      path: `${base}/api/complete`,
+      source: "surface:taskInbox",
+      handler: async (req) => {
+        let body: { userTaskKey?: string; variables?: Record<string, unknown> };
+        try {
+          body = JSON.parse((await req.text()) || "{}");
+        } catch {
+          return json({ error: "invalid JSON body" }, 400);
+        }
+        if (!body.userTaskKey) return json({ error: "userTaskKey required" }, 400);
+        await app.engine.completeUserTask(body.userTaskKey, body.variables);
+        return json({ ok: true });
+      },
+    });
+  }
+
+  const chat = surfaces.chat;
+  if (chat?.enabled) {
+    const base = normalizeRoutePath(chat.path, "/chat");
+    enabled.push(`chat@${base}`);
+    routes.push({
+      method: "GET",
+      path: base,
+      source: "surface:chat",
+      handler: () =>
+        html(`<!doctype html><meta charset="utf-8"><title>Chat</title>
+<body style="font:14px system-ui;margin:2rem"><h1>Chat</h1>
+<p>Chat surface mount point (agent: <code>${escapeHtml(chat.agent ?? "?")}</code>). LLM wiring pending.</p>`),
+    });
+  }
+
+  ctx.host.log("info", "surfaces mounted", { enabled });
+  return { name: "surfaces", routes, describe: () => ({ enabled }) };
+}

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

@@ -0,0 +1,143 @@
+// triggers — the inbound I/O edge (ADR 0025). Turns each `webhook` trigger in the manifest
+// into an HTTP route that verifies the request, maps the payload, and publishes the declared
+// message to the engine for correlation. HMAC verification uses Web Crypto (global in both
+// Node 18+ and Deno), so this stays runtime-agnostic.
+
+import type { AppApi, RuntimeContext } from "../context.ts";
+import type { HttpRequest } from "../host.ts";
+import { json, normalizeRoutePath, type Route } from "../router.ts";
+import type { TriggerDecl } from "../manifest.ts";
+
+export interface TriggersHandle {
+  readonly name: string;
+  routes: Route[];
+  describe(): Record<string, unknown>;
+}
+
+/** Evaluate a tiny correlation expression: `= body.a.b`, or a literal string. */
+export function evalCorrelation(
+  expr: string | undefined,
+  scope: { body: unknown; headers: Record<string, string>; query: Record<string, string> },
+): string | undefined {
+  if (!expr) return undefined;
+  const trimmed = expr.trim();
+  if (!trimmed.startsWith("=")) return trimmed; // literal
+  const pathExpr = trimmed.slice(1).trim(); // e.g. "body.taskId"
+  let cur: unknown = scope;
+  for (const seg of pathExpr.split(".")) {
+    if (cur && typeof cur === "object" && seg in (cur as Record<string, unknown>)) {
+      cur = (cur as Record<string, unknown>)[seg];
+    } else {
+      return undefined;
+    }
+  }
+  return cur == null ? undefined : String(cur);
+}
+
+async function verifyHmac(secret: string, body: string, signature: string): Promise<boolean> {
+  const enc = new TextEncoder();
+  const key = await globalThis.crypto.subtle.importKey(
+    "raw",
+    enc.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await globalThis.crypto.subtle.sign("HMAC", key, enc.encode(body));
+  const hex = [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
+  const provided = signature.replace(/^sha256=/, "").trim().toLowerCase();
+  // Constant-time-ish compare.
+  if (provided.length !== hex.length) return false;
+  let diff = 0;
+  for (let i = 0; i < hex.length; i++) diff |= hex.charCodeAt(i) ^ provided.charCodeAt(i);
+  return diff === 0;
+}
+
+/** Env var holding the secret for an `hmac:<connection>` auth ref. */
+function secretEnvName(connection: string): string {
+  return `URBAN_TRIGGER_SECRET_${connection.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`;
+}
+
+function headerRecord(req: HttpRequest): Record<string, string> {
+  const out: Record<string, string> = {};
+  req.headers.forEach((v, k) => (out[k.toLowerCase()] = v));
+  return out;
+}
+
+/** Mount webhook triggers and return their routes. */
+export function mountTriggers(ctx: RuntimeContext, app: AppApi): TriggersHandle {
+  const routes: Route[] = [];
+  const mounted: string[] = [];
+  const seenDeliveries = new Set<string>();
+
+  for (const trig of (ctx.manifest.triggers ?? []) as TriggerDecl[]) {
+    if (trig.type !== "webhook") {
+      ctx.host.log("warn", `trigger "${trig.id}": type "${trig.type}" not implemented, skipped`);
+      continue;
+    }
+    const path = normalizeRoutePath(trig.path, `/hooks/${trig.id}`);
+    mounted.push(`${trig.id}@${path}`);
+
+    routes.push({
+      method: "POST",
+      path,
+      source: `trigger:${trig.id}`,
+      handler: async (req) => {
+        const raw = await req.text();
+        const headers = headerRecord(req);
+
+        // Auth (hmac:<connection>).
+        if (trig.auth?.startsWith("hmac:")) {
+          const conn = trig.auth.slice("hmac:".length);
+          const secret = app.env(secretEnvName(conn));
+          if (!secret) {
+            app.log("error", `trigger "${trig.id}": missing secret ${secretEnvName(conn)}`);
+            return json({ error: "server not configured for hmac" }, 500);
+          }
+          const sig = headers["x-signature"] ?? headers["x-hub-signature-256"] ?? "";
+          if (!sig || !(await verifyHmac(secret, raw, sig))) {
+            return json({ error: "invalid signature" }, 401);
+          }
+        }
+
+        // Idempotency by delivery id (bounded set).
+        const delivery = headers["x-delivery-id"] ?? headers["x-github-delivery"];
+        if (delivery) {
+          if (seenDeliveries.has(delivery)) return json({ ok: true, deduped: true });
+          seenDeliveries.add(delivery);
+          if (seenDeliveries.size > 10_000) {
+            seenDeliveries.delete(seenDeliveries.values().next().value as string);
+          }
+        }
+
+        let body: unknown = {};
+        try {
+          body = raw ? JSON.parse(raw) : {};
+        } catch {
+          return json({ error: "body must be JSON" }, 400);
+        }
+
+        const message = trig.action?.message;
+        if (!message) {
+          app.log("warn", `trigger "${trig.id}": no action.message; nothing published`);
+          return json({ ok: true, published: false });
+        }
+        const correlationKey = evalCorrelation(trig.action?.correlationKey, {
+          body,
+          headers,
+          query: Object.fromEntries(req.query),
+        });
+        await app.engine.publishMessage({
+          name: message,
+          correlationKey,
+          variables: (body && typeof body === "object" ? (body as Record<string, unknown>) : {}),
+        });
+        app.log("info", `trigger "${trig.id}" published`, { message, correlationKey });
+        return json({ ok: true, published: true, message, correlationKey });
+      },
+    });
+  }
+
+  ctx.host.log("info", "triggers mounted", { mounted });
+  return { name: "triggers", routes, describe: () => ({ mounted }) };
+}

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

@@ -0,0 +1,22 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolveHandler } from "./workers.ts";
+import { evalCorrelation } from "./triggers.ts";
+
+test("resolveHandler prefers handlers[jobType], then segment, then default", () => {
+  const fn = () => {};
+  assert.equal(resolveHandler({ handlers: { "a.b": fn } }, "a.b"), fn);
+  assert.equal(resolveHandler({ "a.b": fn }, "a.b"), fn);
+  assert.equal(resolveHandler({ handlers: { b: fn } }, "a.b"), fn); // last segment
+  assert.equal(resolveHandler({ default: fn }, "a.b"), fn);
+  assert.equal(resolveHandler({}, "a.b"), undefined);
+});
+
+test("evalCorrelation resolves = body.path, literals, and misses", () => {
+  const scope = { body: { taskId: "T1", nested: { k: 7 } }, headers: {}, query: {} };
+  assert.equal(evalCorrelation("= body.taskId", scope), "T1");
+  assert.equal(evalCorrelation("=body.nested.k", scope), "7");
+  assert.equal(evalCorrelation("literal", scope), "literal");
+  assert.equal(evalCorrelation("= body.missing", scope), undefined);
+  assert.equal(evalCorrelation(undefined, scope), undefined);
+});

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

@@ -0,0 +1,96 @@
+// workers — load each declared worker's handler module and register it as a push worker
+// on the engine. Handlers are resolved by a small, documented contract and are injected
+// with the app's runtime API (datasource + engine + host utils).
+
+import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
+import type { EngineJob, JobHandler, WorkerSubscription } from "../host.ts";
+import { workerJobType, type WorkerDecl } from "../manifest.ts";
+
+/** A handler as authored by an app: the job plus the injected app API. */
+export type AppJobHandler = (
+  job: EngineJob,
+  app: AppApi,
+) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+
+/**
+ * Resolve a handler for `jobType` from a loaded module, in priority order:
+ *   1. `handlers[jobType]`            (a map keyed by job type — the multi-type module case)
+ *   2. a named export matching jobType (or its last dotted segment)
+ *   3. `default` (when it is a function)
+ */
+export function resolveHandler(
+  mod: Record<string, unknown>,
+  jobType: string,
+): AppJobHandler | undefined {
+  const map = mod.handlers as Record<string, unknown> | undefined;
+  if (map && typeof map[jobType] === "function") return map[jobType] as AppJobHandler;
+  const seg = jobType.includes(".") ? jobType.slice(jobType.lastIndexOf(".") + 1) : jobType;
+  if (typeof mod[jobType] === "function") return mod[jobType] as AppJobHandler;
+  if (map && typeof map[seg] === "function") return map[seg] as AppJobHandler;
+  if (typeof mod[seg] === "function") return mod[seg] as AppJobHandler;
+  if (typeof mod.default === "function") return mod.default as AppJobHandler;
+  return undefined;
+}
+
+export interface WorkersHandle extends Mounted {
+  readonly jobTypes: string[];
+}
+
+/** Load handler modules and register a push worker per declared worker. */
+export async function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<WorkersHandle> {
+  const decls = ctx.manifest.workers ?? [];
+  const subs: WorkerSubscription[] = [];
+  const jobTypes: string[] = [];
+
+  // Cache module loads so a multi-type handler module is imported once.
+  const moduleCache = new Map<string, Record<string, unknown>>();
+  const joinRoot = (p: string): string =>
+    p.startsWith("/") ? p : `${ctx.root.replace(/\/+$/, "")}/${p.replace(/^\/+/, "")}`;
+  const loadModule = async (path: string): Promise<Record<string, unknown>> => {
+    const key = joinRoot(path);
+    const cached = moduleCache.get(key);
+    if (cached) return cached;
+    const mod = await ctx.host.importModule(key);
+    moduleCache.set(key, mod);
+    return mod;
+  };
+
+  for (const decl of decls as WorkerDecl[]) {
+    const jobType = workerJobType(decl);
+    if (!jobType) continue;
+    if (!decl.handler) {
+      // llm-backed workers (schema `oneOf` handler|llm) are validated but not yet
+      // executed by the runtime. Skip with a clear warning rather than crashing.
+      ctx.host.log("warn", "skipping worker: llm-backed workers are not yet implemented", {
+        jobType,
+        llm: decl.llm,
+      });
+      continue;
+    }
+    const mod = await loadModule(decl.handler);
+    const handler = resolveHandler(mod, jobType);
+    if (!handler) {
+      throw new Error(
+        `worker "${jobType}": ${decl.handler} exports no handler for it ` +
+          `(expected handlers["${jobType}"], a named export, or a default function)`,
+      );
+    }
+    const wrapped: JobHandler = (job) => handler(job, app);
+    const sub = await ctx.engine.registerWorker(jobType, wrapped, {
+      workerName: `${ctx.manifest.id}:${jobType}`,
+    });
+    subs.push(sub);
+    jobTypes.push(jobType);
+    ctx.host.log("info", "worker registered", { jobType, handler: decl.handler });
+  }
+
+  return {
+    name: "workers",
+    jobTypes,
+    async stop() {
+      // Graceful unsubscribe on exit (defensive against the Falcon dead-subscriber stall).
+      await Promise.allSettled(subs.map((s) => s.unsubscribe()));
+    },
+    describe: () => ({ jobTypes }),
+  };
+}

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

@@ -0,0 +1,31 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readdir, readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+// Architectural guard (ADR 0052): core/ is runtime-agnostic. It must not import `node:*`
+// modules or reference the `Deno` global. The only runtime-coupled code lives in adapters/.
+
+const coreDir = dirname(fileURLToPath(import.meta.url));
+
+async function tsFiles(dir: string): Promise<string[]> {
+  const out: string[] = [];
+  for (const e of await readdir(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) out.push(...(await tsFiles(p)));
+    else if (e.name.endsWith(".ts") && !e.name.endsWith(".test.ts")) out.push(p);
+  }
+  return out;
+}
+
+test("core/ has zero runtime-specific imports", async () => {
+  const offenders: string[] = [];
+  for (const file of await tsFiles(coreDir)) {
+    const src = await readFile(file, "utf8");
+    if (/from\s+["']node:/.test(src)) offenders.push(`${file}: imports node:*`);
+    // `Deno` as an identifier (not inside a comment word like "Deno adapter")
+    if (/\bDeno\s*\./.test(src)) offenders.push(`${file}: references Deno.*`);
+  }
+  assert.deepEqual(offenders, [], `core purity violations:\n${offenders.join("\n")}`);
+});

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

@@ -0,0 +1,16 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { normalizeRoutePath } from "./router.ts";
+
+test("normalizeRoutePath ensures a leading slash and trims trailing slashes", () => {
+  assert.equal(normalizeRoutePath("hooks/x", "/fallback"), "/hooks/x");
+  assert.equal(normalizeRoutePath("/hooks/x", "/fallback"), "/hooks/x");
+  assert.equal(normalizeRoutePath("/tasks/", "/tasks"), "/tasks");
+  assert.equal(normalizeRoutePath("  /chat  ", "/chat"), "/chat");
+});
+
+test("normalizeRoutePath falls back when value is missing or collapses to root", () => {
+  assert.equal(normalizeRoutePath(undefined, "/tasks"), "/tasks");
+  assert.equal(normalizeRoutePath("/", "/tasks"), "/tasks");
+  assert.equal(normalizeRoutePath("", "/tasks"), "/tasks");
+});

package/src/runtime/core/router.ts

@@ -0,0 +1,55 @@
+// A minimal path router shared by the surfaces and triggers modules so the runtime serves
+// a single HTTP port. Matching is exact path or, for a route registered with `prefix`,
+// a path-prefix match. First match wins.
+
+import type { HttpHandler, HttpRequest, HttpResponse } from "./host.ts";
+
+export interface Route {
+  method: string;
+  path: string;
+  /** When true, match any path that starts with `path`. */
+  prefix?: boolean;
+  handler: HttpHandler;
+  /** For diagnostics / inspect(). */
+  source?: string;
+}
+
+export function json(body: unknown, status = 200): HttpResponse {
+  return { status, headers: { "content-type": "application/json" }, body: JSON.stringify(body) };
+}
+
+export function html(body: string, status = 200): HttpResponse {
+  return { status, headers: { "content-type": "text/html; charset=utf-8" }, body };
+}
+
+export function text(body: string, status = 200): HttpResponse {
+  return { status, headers: { "content-type": "text/plain; charset=utf-8" }, body };
+}
+
+/**
+ * Normalize a manifest-supplied route path: ensure a leading "/", drop trailing
+ * slashes. Incoming request paths always start with "/", so a manifest path
+ * lacking one (e.g. "hooks/x") would otherwise never match. Falls back to
+ * `fallback` when the value is missing or collapses to empty ("/").
+ */
+export function normalizeRoutePath(value: string | undefined, fallback: string): string {
+  const raw = (value ?? fallback).trim();
+  const withLead = raw.startsWith("/") ? raw : `/${raw}`;
+  const noTrail = withLead.replace(/\/+$/, "");
+  return noTrail || fallback;
+}
+
+function matches(route: Route, req: HttpRequest): boolean {
+  if (route.method !== "*" && route.method.toUpperCase() !== req.method.toUpperCase()) return false;
+  return route.prefix ? req.path.startsWith(route.path) : req.path === route.path;
+}
+
+/** Build a single HttpHandler that dispatches across the given routes. */
+export function makeRouter(routes: Route[]): HttpHandler {
+  return async (req: HttpRequest): Promise<HttpResponse> => {
+    for (const route of routes) {
+      if (matches(route, req)) return route.handler(req);
+    }
+    return text("not found", 404);
+  };
+}