@nanobpm/urban 0.34.0 → 0.36.0

package/package.json

@@ -1,76 +1,76 @@
 {
-  "name": "@nanobpm/urban",
-  "version": "0.34.0",
-  "description": "Urban: build and run code-first apps on Nano \u2014 runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
-  "license": "Apache-2.0",
-  "type": "module",
-  "keywords": [
-    "nanobpm",
-    "urban",
-    "cli",
-    "runtime",
-    "codegen",
-    "derivation",
-    "nano-app",
-    "rad"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/nanobpm/nano-ide.git",
-    "directory": "packages/urban"
-  },
-  "engines": {
-    "node": ">=22.6"
-  },
-  "bin": {
-    "urban": "src/bin.mjs"
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./runtime": {
-      "types": "./dist/runtime/index.d.ts",
-      "default": "./dist/runtime/index.js"
-    },
-    "./toolkit": {
-      "types": "./dist/toolkit/index.d.ts",
-      "default": "./dist/toolkit/index.js"
-    },
-    "./worker": {
-      "types": "./dist/worker.d.ts",
-      "default": "./dist/worker.js"
-    },
-    "./source": "./src/index.ts"
-  },
-  "files": [
-    "dist",
-    "src",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "prepack": "npm run build",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "node --test --experimental-strip-types \"src/**/*.test.ts\"",
-    "test:deno": "deno test -A --no-check src/"
-  },
-  "dependencies": {
-    "@nanobpm/nano-app-schema": "^0.4.0",
-    "@nanobpm/nano-sdk": "^1.2.3",
-    "@nanobpm/workflow": "^0.8.0",
-    "bpmn-auto-layout": "^2.0.0-alpha.2",
-    "create-urban-app": "^0.9.0",
-    "yaml": "^2.9.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.20.1",
-    "typescript": "^5.9.3"
-  }
+	"name": "@nanobpm/urban",
+	"version": "0.36.0",
+	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
+	"license": "Apache-2.0",
+	"type": "module",
+	"keywords": [
+		"nanobpm",
+		"urban",
+		"cli",
+		"runtime",
+		"codegen",
+		"derivation",
+		"nano-app",
+		"rad"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/nanobpm/nano-ide.git",
+		"directory": "packages/urban"
+	},
+	"engines": {
+		"node": ">=22.6"
+	},
+	"bin": {
+		"urban": "src/bin.mjs"
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./runtime": {
+			"types": "./dist/runtime/index.d.ts",
+			"default": "./dist/runtime/index.js"
+		},
+		"./toolkit": {
+			"types": "./dist/toolkit/index.d.ts",
+			"default": "./dist/toolkit/index.js"
+		},
+		"./worker": {
+			"types": "./dist/worker.d.ts",
+			"default": "./dist/worker.js"
+		},
+		"./source": "./src/index.ts"
+	},
+	"files": [
+		"dist",
+		"src",
+		"README.md"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"prepack": "npm run build",
+		"typecheck": "tsc --noEmit -p tsconfig.json",
+		"test": "node --test --experimental-strip-types \"src/**/*.test.ts\"",
+		"test:deno": "deno test -A --no-check src/"
+	},
+	"dependencies": {
+		"@nanobpm/nano-app-schema": "^0.4.0",
+		"@nanobpm/nano-sdk": "^1.2.3",
+		"@nanobpm/workflow": "^0.8.0",
+		"bpmn-auto-layout": "^2.0.0-alpha.2",
+		"create-urban-app": "^0.9.0",
+		"yaml": "^2.9.0"
+	},
+	"devDependencies": {
+		"@types/node": "^22.20.1",
+		"typescript": "^5.9.3"
+	}
 }

package/src/cli.test.ts

@@ -14,7 +14,6 @@ test("urban data exits 0 with a parseable envelope on an unreadable request", as
     root: ".",
     manifest: "nano.app.json",
     check: false,
-    write: false,
     deno: false,
     models: true,
     stdout: false,

package/src/cli.ts

@@ -25,7 +25,7 @@ import { denoGlobal, processGlobal } from "./runtime/adapters/globals.ts";
 import { errorMessage, isRecord } from "./runtime/core/guards.ts";
 import { scaffold, slugify } from "create-urban-app";
 import type { DataRequest } from "./runtime/index.ts";
-import { addConnector, createNodeGenIO, previewModels, runGen, scaffoldWorkers } from "./toolkit/index.ts";
+import { addConnector, createNodeGenIO, previewModels, generate, runGen } from "./toolkit/index.ts";
 import { pathToFileURL } from "node:url";
 import { readFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
@@ -50,7 +50,6 @@ interface Flags {
   manifest: string;
   port?: number;
   check: boolean;
-  write: boolean;
   deno: boolean;
   models: boolean;
   stdout: boolean;
@@ -62,7 +61,7 @@ interface Flags {
 }
 
 function parse(argv: string[]): Flags {
-  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, write: false, deno: false, models: true, stdout: false, install: true, help: false, version: false, _: [] };
+  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, deno: false, models: true, stdout: false, install: true, help: false, version: false, _: [] };
   const need = (i: number, flag: string): string => {
     const v = argv[i];
     if (v === undefined || v.startsWith("-")) throw new Error(`flag ${flag} requires a value`);
@@ -73,7 +72,6 @@ function parse(argv: string[]): Flags {
     if (a === "-h" || a === "--help") f.help = true;
     else if (a === "-v" || a === "--version") f.version = true;
     else if (a === "--check") f.check = true;
-    else if (a === "--write") f.write = true;
     else if (a === "--deno") f.deno = true;
     else if (a === "--no-models") f.models = false;
     else if (a === "--models") f.models = true;
@@ -108,11 +106,12 @@ Usage:
   urban new <name> [--root <path>] [--deno] [--style model|code]    scaffold a new Urban app
                                     (--code-first is shorthand for --style code)
   urban check                       validate the manifest
-  urban gen [--check] [--no-models] derive artifacts (migrations, worker-io, + code-first models)
+  urban gen [--check] [--no-models] derive artifacts + scaffold write-once handler stubs
+                                    (--check: verify up-to-date without writing; a missing stub or
+                                    drifted artifact fails — run \`urban gen\`)
                                     (--no-models: skip writing derived .bpmn; type-contracts only)
   urban derive [--check|--stdout]   derive code-first models only (workflows/*.ts → processes/*.bpmn)
                                     (--stdout: print {models,incomplete} JSON without writing)
-  urban stubs [--write]             scaffold write-once handler stubs from the model
   urban add <pkg> [--no-install]    install a connector pack + wire it into nano.app.json
   urban run                         materialize + serve the app
   urban dev                         run + watch sources, hot-reload on change
@@ -148,23 +147,43 @@ async function cmdCheck(f: Flags): Promise<number> {
 
 async function cmdGen(f: Flags): Promise<number> {
   const io = createNodeGenIO();
-  const res = await runGen({ root: f.root, io, manifestFile: f.manifest, check: f.check, emitModels: f.models });
+  const res = await generate({ root: f.root, io, manifestFile: f.manifest, check: f.check, emitModels: f.models });
   if (res.incomplete) {
     console.error(`✖ ${res.modelErrors.length} workflow(s) failed to derive:`);
     for (const e of res.modelErrors) console.error(`  • ${e.path}: ${e.message}`);
     return 1;
   }
   if (f.check) {
-    if (res.drift.length === 0) {
-      console.log(`✔ generated artifacts are up to date (${res.artifacts.length} checked)`);
+    if (res.drift.length === 0 && res.missingStubs.length === 0) {
+      console.log(`✔ generated artifacts + handler stubs are up to date (${res.artifacts.length} checked)`);
       return 0;
     }
-    console.error(`✖ ${res.drift.length} generated artifact(s) are out of date — run \`urban gen\`:`);
-    for (const p of res.drift) console.error(`  • ${p}`);
+    if (res.drift.length > 0) {
+      console.error(`✖ ${res.drift.length} generated artifact(s) are out of date — run \`urban gen\`:`);
+      for (const p of res.drift) console.error(`  • ${p}`);
+    }
+    if (res.missingStubs.length > 0) {
+      console.error(`✖ ${res.missingStubs.length} handler stub(s) missing — run \`urban gen\`:`);
+      for (const p of res.missingStubs) console.error(`  • ${p}`);
+    }
     return 1;
   }
   console.log(`✔ generated ${res.artifacts.length} artifact(s):`);
   for (const a of res.artifacts) console.log(`  • ${a.path}`);
+
+  // Write-once handler stubs scaffolded as part of generation (workers from the model, operation
+  // delegates from the OpenAPI spec). Existing, human-owned stubs are kept verbatim.
+  const created = [
+    ...res.workerStubs.filter((o) => o.status === "created").map((o) => o.handlerPath),
+    ...res.operationStubs.filter((o) => o.status === "created").map((o) => o.handlerPath),
+  ];
+  if (created.length > 0) {
+    console.log(`✔ scaffolded ${created.length} handler stub(s):`);
+    for (const p of created) console.log(`  + ${p}`);
+  }
+  if (res.manifestPatched) {
+    console.log(`✔ wired ${res.wiredWorkers.length} worker(s) into ${f.manifest}`);
+  }
   return 0;
 }
 
@@ -217,38 +236,6 @@ async function cmdDerive(f: Flags): Promise<number> {
   return 0;
 }
 
-async function cmdStubs(f: Flags): Promise<number> {
-  const io = createNodeGenIO();
-  const run = await scaffoldWorkers({ root: f.root, io, manifestFile: f.manifest, write: f.write });
-
-  const created = run.outcomes.filter((o) => o.status === "created");
-  const would = run.outcomes.filter((o) => o.status === "would-create");
-  const kept = run.outcomes.filter((o) => o.status === "kept");
-  const typing = (o: { typedIn: boolean; typedOut: boolean }) =>
-    o.typedIn || o.typedOut ? ` (typed${o.typedIn ? " in" : ""}${o.typedOut ? " out" : ""})` : "";
-
-  if (run.write) {
-    console.log(`✔ scaffolded ${created.length} worker stub(s):`);
-    for (const o of created) console.log(`  + ${o.handlerPath}${typing(o)}`);
-    if (run.manifestPatched) {
-      console.log(`✔ wired ${run.wired.length} worker(s) into ${f.manifest}`);
-    }
-  } else {
-    if (would.length === 0) {
-      console.log(`✔ no new worker stubs to scaffold`);
-    } else {
-      console.log(`Would scaffold ${would.length} worker stub(s) — run with --write to apply:`);
-      for (const o of would) console.log(`  + ${o.handlerPath}${typing(o)}`);
-    }
-  }
-  for (const o of kept) console.log(`  = ${o.handlerPath} (kept — already exists)`);
-  if (run.skipped.length > 0) {
-    console.log(`  skipped ${run.skipped.length}: ` +
-      run.skipped.map((s) => `${s.taskType} (${s.reason})`).join(", "));
-  }
-  return 0;
-}
-
 async function cmdRun(f: Flags, mount?: Record<string, boolean>): Promise<number> {
   const app = await runFromEnv({
     root: f.root,
@@ -430,8 +417,6 @@ export async function main(argv: string[]): Promise<number> {
       return cmdGen(f);
     case "derive":
       return cmdDerive(f);
-    case "stubs":
-      return cmdStubs(f);
     case "add":
       return cmdAdd(f);
     case "data":

package/src/openapi/spec.test.ts

@@ -2,6 +2,7 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import {
   collectOperations,
+  evaluateSecurity,
   isObjectSchema,
   isSafeOperationId,
   type OpenApiDoc,
@@ -12,6 +13,7 @@ import {
   resolveSchema,
   toRouteMatcher,
   undeclaredPathParams,
+  undeclaredSecuritySchemes,
   validateValue,
 } from "./spec.ts";
 
@@ -346,3 +348,172 @@ test("validateValue handles null: typeless object rejects it; nullable/type-null
   // A truly empty schema allows anything, including null.
   assert.equal(validateValue(doc, {}, null).length, 0);
 });
+
+// ── Security (ADR 0059: one HTTP surface, apiKey-guarded webhook operations) ──────────────────
+
+const secured: OpenApiDoc = {
+  openapi: "3.0.0",
+  components: {
+    securitySchemes: {
+      webhookKey: {
+        type: "apiKey",
+        in: "header",
+        name: "X-Webhook-Key",
+        "x-nano-secret-env": "NANO_WEBHOOK_KEY",
+      },
+      queryKey: {
+        type: "apiKey",
+        in: "query",
+        name: "key",
+        "x-nano-secret-env": "NANO_QUERY_KEY",
+      },
+    },
+  },
+  security: [{ webhookKey: [] }], // document-level default
+  paths: {
+    "/hooks/submit": {
+      post: { operationId: "submitHook", responses: { "204": {} } }, // inherits the default
+    },
+    "/hooks/open": {
+      post: { operationId: "openHook", security: [], responses: { "204": {} } }, // opts out
+    },
+    "/hooks/query": {
+      post: {
+        operationId: "queryHook",
+        security: [{ queryKey: [] }],
+        responses: { "204": {} },
+      },
+    },
+  },
+};
+
+const noHeader = (): undefined => undefined;
+const noQuery = (): undefined => undefined;
+const secret = (vars: Record<string, string>) => (v: string): string | undefined => vars[v];
+
+test("collectOperations resolves effective security (op-level wins, explicit [] opts out, doc default inherited)", () => {
+  const ops = collectOperations(secured);
+  const byId = Object.fromEntries(ops.map((o) => [o.operationId, o]));
+  assert.deepEqual(byId.submitHook.security, [{ webhookKey: [] }]); // inherited default
+  assert.deepEqual(byId.openHook.security, []); // explicit opt-out
+  assert.deepEqual(byId.queryHook.security, [{ queryKey: [] }]); // own requirement
+});
+
+test("evaluateSecurity: an open operation (no requirement) is always authorized", () => {
+  const open = collectOperations(secured).find((o) => o.operationId === "openHook")!;
+  assert.deepEqual(
+    evaluateSecurity(secured, open, noHeader, noQuery, secret({})),
+    { ok: true },
+  );
+});
+
+test("evaluateSecurity: a valid apiKey header authorizes; wrong/absent → 401", () => {
+  const op = collectOperations(secured).find((o) => o.operationId === "submitHook")!;
+  const env = secret({ NANO_WEBHOOK_KEY: "s3cret" });
+  // Correct key.
+  assert.equal(
+    evaluateSecurity(secured, op, (n) => (n === "X-Webhook-Key" ? "s3cret" : undefined), noQuery, env).ok,
+    true,
+  );
+  // Wrong key → 401.
+  assert.deepEqual(
+    evaluateSecurity(secured, op, () => "nope", noQuery, env),
+    { ok: false, status: 401, error: "unauthorized" },
+  );
+  // Missing key → 401.
+  assert.deepEqual(evaluateSecurity(secured, op, noHeader, noQuery, env), {
+    ok: false,
+    status: 401,
+    error: "unauthorized",
+  });
+});
+
+test("evaluateSecurity: an apiKey in query is read from the query, not the header", () => {
+  const op = collectOperations(secured).find((o) => o.operationId === "queryHook")!;
+  const env = secret({ NANO_QUERY_KEY: "qk" });
+  assert.equal(
+    evaluateSecurity(secured, op, noHeader, (n) => (n === "key" ? "qk" : undefined), env).ok,
+    true,
+  );
+  assert.equal(evaluateSecurity(secured, op, noHeader, () => "bad", env).status, 401);
+});
+
+test("evaluateSecurity: an unset secret env is a 500 misconfiguration (fail closed, not 401)", () => {
+  const op = collectOperations(secured).find((o) => o.operationId === "submitHook")!;
+  const decision = evaluateSecurity(secured, op, () => "anything", noQuery, secret({}));
+  assert.equal(decision.ok, false);
+  assert.equal(decision.status, 500);
+  assert.match(decision.error ?? "", /NANO_WEBHOOK_KEY is not set/);
+});
+
+test("evaluateSecurity: a requirement naming an undeclared scheme is a 500 misconfiguration", () => {
+  const doc: OpenApiDoc = {
+    openapi: "3.0.0",
+    components: { securitySchemes: {} },
+    paths: {
+      "/x": { post: { operationId: "x", security: [{ ghost: [] }], responses: { "204": {} } } },
+    },
+  };
+  const op = collectOperations(doc)[0];
+  const decision = evaluateSecurity(doc, op, () => "k", noQuery, secret({}));
+  assert.equal(decision.status, 500);
+  assert.match(decision.error ?? "", /not declared/);
+  assert.deepEqual(undeclaredSecuritySchemes(doc), ["ghost (POST /x)"]);
+});
+
+
+test("evaluateSecurity: malformed security entries fail closed as a 500 misconfiguration", () => {
+  const doc: OpenApiDoc = {
+    openapi: "3.0.0",
+    components: {
+      securitySchemes: { webhookKey: { type: "apiKey", in: "header", name: "X-Key", "x-nano-secret-env": "KEY" } },
+    },
+    paths: {
+      "/x": { post: { operationId: "x", security: ["webhookKey"], responses: { "204": {} } } },
+    },
+  };
+  const op = collectOperations(doc)[0];
+  const decision = evaluateSecurity(doc, op, () => "secret", noQuery, secret({ KEY: "secret" }));
+  assert.equal(decision.status, 500);
+  assert.match(decision.error ?? "", /malformed security requirement/);
+});
+
+test("evaluateSecurity: an unsupported scheme type is a 500 misconfiguration", () => {
+  const doc: OpenApiDoc = {
+    openapi: "3.0.0",
+    components: { securitySchemes: { oauth: { type: "oauth2" } } },
+    paths: {
+      "/x": { post: { operationId: "x", security: [{ oauth: [] }], responses: { "204": {} } } },
+    },
+  };
+  const op = collectOperations(doc)[0];
+  const decision = evaluateSecurity(doc, op, () => "k", noQuery, secret({}));
+  assert.equal(decision.status, 500);
+  assert.match(decision.error ?? "", /unsupported type "oauth2"/);
+});
+
+test("evaluateSecurity: alternative requirements are OR (any one satisfied authorizes)", () => {
+  const doc: OpenApiDoc = {
+    openapi: "3.0.0",
+    components: {
+      securitySchemes: {
+        a: { type: "apiKey", in: "header", name: "A", "x-nano-secret-env": "A_KEY" },
+        b: { type: "apiKey", in: "header", name: "B", "x-nano-secret-env": "B_KEY" },
+      },
+    },
+    paths: {
+      "/x": {
+        post: { operationId: "x", security: [{ a: [] }, { b: [] }], responses: { "204": {} } },
+      },
+    },
+  };
+  const op = collectOperations(doc)[0];
+  const env = secret({ A_KEY: "aa", B_KEY: "bb" });
+  // Only B presented → still authorized (OR).
+  assert.equal(
+    evaluateSecurity(doc, op, (n) => (n === "B" ? "bb" : undefined), noQuery, env).ok,
+    true,
+  );
+  // Neither presented → 401.
+  assert.equal(evaluateSecurity(doc, op, noHeader, noQuery, env).status, 401);
+});