@nanobpm/urban 0.34.0 → 0.36.0

package/src/openapi/spec.ts

@@ -84,11 +84,38 @@ export interface OpenApiResponse {
   content?: Record<string, OpenApiMediaType>;
 }
 
+/**
+ * A security scheme (OpenAPI Components Object → `securitySchemes`). The supported profile is the
+ * `apiKey` type carried in a request header (ADR 0059): a webhook/operation is guarded by a shared
+ * secret. The expected value is never inlined — it is read from an environment variable named by
+ * the `x-nano-secret-env` extension (ADR 0025/0027: secrets stay env pointers).
+ */
+export interface OpenApiSecurityScheme {
+  type?: string;
+  /** For `apiKey`: where the key travels. `header` and `query` are enforced in this slice. */
+  in?: "header" | "query" | "cookie";
+  /** For `apiKey`: the header (or query) name carrying the key, e.g. `X-Webhook-Key`. */
+  name?: string;
+  /** Env var holding the expected secret value. Required to enforce an `apiKey` scheme. */
+  "x-nano-secret-env"?: string;
+  description?: string;
+}
+
+/** A security requirement: scheme name → scopes (scopes are unused for `apiKey`, always `[]`). An
+ *  operation is authorized when ANY one requirement object is fully satisfied (OR across the list,
+ *  AND within an object). An empty list (`security: []`) means the operation is explicitly open. */
+export type OpenApiSecurityRequirement = Record<string, string[]>;
+
 export interface OpenApiDoc {
   openapi?: string;
   info?: { title?: string; version?: string };
   paths?: Record<string, Record<string, unknown>>;
-  components?: { schemas?: Record<string, OpenApiSchema> };
+  components?: {
+    schemas?: Record<string, OpenApiSchema>;
+    securitySchemes?: Record<string, OpenApiSecurityScheme>;
+  };
+  /** Document-level default security, applied to any operation that declares none. */
+  security?: OpenApiSecurityRequirement[];
 }
 
 /** The HTTP methods we mount, lowercase as they appear as path-item keys. */
@@ -107,6 +134,9 @@ export interface OperationInfo {
   requestBodyRequired: boolean;
   /** Schema of the first 2xx (else default) JSON response, when declared. */
   responseSchema?: OpenApiSchema;
+  /** Effective security requirements (op-level if declared — including an explicit empty list —
+   *  else the document-level default, else `[]`). An empty list means the operation is open. */
+  security: OpenApiSecurityRequirement[];
   eject: boolean;
   summary?: string;
 }
@@ -212,6 +242,12 @@ export function collectOperations(doc: OpenApiDoc): OperationInfo[] {
         isRecord(requestBody?.content) ? requestBody.content : undefined,
       );
       const responses = isRecord(opRaw.responses) ? opRaw.responses : {};
+      // Effective security: an operation's own `security` (even an explicit `[]`, which opts out of
+      // a document-level default) wins; otherwise inherit the document-level default; otherwise open.
+      const rawSecurity = Object.prototype.hasOwnProperty.call(opRaw, "security")
+        ? opRaw.security
+        : doc.security;
+      const security = normalizeSecurity(rawSecurity);
       out.push({
         operationId,
         method,
@@ -220,6 +256,7 @@ export function collectOperations(doc: OpenApiDoc): OperationInfo[] {
         requestBodySchema,
         requestBodyRequired: requestBody?.required === true,
         responseSchema: firstSuccessSchema(responses),
+        security,
         eject: opRaw["x-urban-eject"] === true,
         summary: typeof opRaw.summary === "string" ? opRaw.summary : undefined,
       });
@@ -228,6 +265,30 @@ export function collectOperations(doc: OpenApiDoc): OperationInfo[] {
   return out;
 }
 
+/**
+ * Throw if the document declares the same `operationId` on more than one operation. An operationId
+ * must be unique across the whole OpenAPI document (it names the delegate module `<dir>/<operationId>`
+ * AND the generated controller registry key), so a duplicate would silently overwrite an earlier
+ * entry in the emitted object literal — dispatching the wrong delegate while still type-checking — and
+ * make the scaffolder plan the same stub twice. Called by the gen/scaffold path so `urban gen`
+ * fails loudly on an incoherent spec instead of shipping a mis-dispatching registry.
+ */
+export function assertUniqueOperationIds(doc: OpenApiDoc): void {
+  const seen = new Set<string>();
+  const duplicates = new Set<string>();
+  for (const op of collectOperations(doc)) {
+    if (seen.has(op.operationId)) duplicates.add(op.operationId);
+    seen.add(op.operationId);
+  }
+  if (duplicates.size > 0) {
+    const list = [...duplicates].sort().join(", ");
+    throw new Error(
+      `OpenAPI spec declares duplicate operationId(s): ${list}. Each operationId must be unique — ` +
+        "it names the delegate module and the generated controller registry key.",
+    );
+  }
+}
+
 /** "method path" pointers for every operation that declares no `operationId`. Such operations are
  *  unroutable (no delegate to bind), so the runtime mount logs them at `warn` and skips them. */
 export function operationsWithoutId(doc: OpenApiDoc): string[] {
@@ -291,6 +352,163 @@ export function operationsWithUnsafeId(doc: OpenApiDoc): string[] {
   return out;
 }
 
+const MALFORMED_SECURITY_REQUIREMENT = "__nano_malformed_security_requirement__";
+
+function malformedSecurityRequirement(): OpenApiSecurityRequirement {
+  return { [MALFORMED_SECURITY_REQUIREMENT]: [] };
+}
+
+/** Normalize a raw `security` value into a clean requirement list. Missing → `[]` (open).
+ *  Present-but-malformed values become an impossible marker requirement so enforcement fails closed
+ *  as a 500 misconfiguration instead of silently opening a guarded operation. */
+function normalizeSecurity(raw: unknown): OpenApiSecurityRequirement[] {
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw)) return [malformedSecurityRequirement()];
+  const out: OpenApiSecurityRequirement[] = [];
+  for (const entry of raw) {
+    if (!isRecord(entry)) {
+      out.push(malformedSecurityRequirement());
+      continue;
+    }
+    const req: OpenApiSecurityRequirement = {};
+    let malformed = false;
+    for (const [name, scopes] of Object.entries(entry)) {
+      if (!Array.isArray(scopes) || scopes.some((s) => typeof s !== "string")) {
+        malformed = true;
+        break;
+      }
+      req[name] = scopes;
+    }
+    out.push(malformed ? malformedSecurityRequirement() : req);
+  }
+  return out;
+}
+
+/** The outcome of enforcing an operation's security: `ok` when authorized, otherwise the HTTP
+ *  status to return — `401` (the request presented no/invalid credential) or `500` (the app is
+ *  misconfigured: an operation references an unknown scheme, an unsupported scheme type, or a
+ *  scheme whose secret env var is unset). */
+export interface SecurityDecision {
+  ok: boolean;
+  status?: 401 | 500;
+  error?: string;
+}
+
+const SECURITY_OK: SecurityDecision = { ok: true };
+const TEXT_ENCODER = new TextEncoder();
+
+/** Constant-time string comparison — avoids leaking how many leading characters of a secret matched
+ *  via response timing. Unequal lengths short-circuit (an acceptable length oracle for API keys). */
+function timingSafeEqual(a: string, b: string): boolean {
+  const ab = TEXT_ENCODER.encode(a);
+  const bb = TEXT_ENCODER.encode(b);
+  if (ab.length !== bb.length) return false;
+  let diff = 0;
+  for (let i = 0; i < ab.length; i++) diff |= ab[i] ^ bb[i];
+  return diff === 0;
+}
+
+/**
+ * Enforce an operation's effective security requirements (ADR 0059). Pure: the caller supplies the
+ * request's header/query readers and an env reader, so all policy lives here (and is unit-tested)
+ * while the impure lookups stay in the runtime.
+ *
+ * Semantics follow OpenAPI: authorized when ANY one requirement object is satisfied (OR), and a
+ * requirement object is satisfied only when ALL its schemes are (AND). An empty requirement list
+ * means the operation is open. Only `apiKey` schemes (in `header` or `query`) are enforced; the
+ * expected value comes from the scheme's `x-nano-secret-env` env var.
+ *
+ * A referenced scheme that is unknown, not `apiKey`, or missing its secret env var is a server
+ * misconfiguration → `500` (fail closed), reported in preference to a `401` so operators see the
+ * real cause. A well-formed scheme with a wrong/absent presented credential → `401`.
+ */
+export function evaluateSecurity(
+  doc: OpenApiDoc,
+  op: OperationInfo,
+  getHeader: (name: string) => string | undefined,
+  getQuery: (name: string) => string | undefined,
+  getSecret: (envVar: string) => string | undefined,
+): SecurityDecision {
+  if (op.security.length === 0) return SECURITY_OK;
+  const schemes = doc.components?.securitySchemes ?? {};
+  let misconfig: string | undefined;
+
+  for (const requirement of op.security) {
+    const names = Object.keys(requirement);
+    if (names.length === 0) return SECURITY_OK; // an empty object is a "no auth" alternative
+    let satisfied = true;
+    for (const name of names) {
+      if (name === MALFORMED_SECURITY_REQUIREMENT) {
+        misconfig ??= "malformed security requirement";
+        satisfied = false;
+        break;
+      }
+      const scheme = schemes[name];
+      if (!scheme) {
+        misconfig ??= `security scheme "${name}" is not declared in components.securitySchemes`;
+        satisfied = false;
+        break;
+      }
+      if (scheme.type !== "apiKey") {
+        misconfig ??= `security scheme "${name}" has unsupported type "${scheme.type ?? "(none)"}" (only apiKey is enforced)`;
+        satisfied = false;
+        break;
+      }
+      const where = scheme.in ?? "header";
+      if (where !== "header" && where !== "query") {
+        misconfig ??= `security scheme "${name}" apiKey location "${where}" is unsupported (use header or query)`;
+        satisfied = false;
+        break;
+      }
+      if (!scheme.name) {
+        misconfig ??= `security scheme "${name}" is missing its apiKey \`name\``;
+        satisfied = false;
+        break;
+      }
+      const envVar = scheme["x-nano-secret-env"];
+      if (!envVar) {
+        misconfig ??= `security scheme "${name}" is missing \`x-nano-secret-env\` (the env var holding the expected key)`;
+        satisfied = false;
+        break;
+      }
+      const expected = getSecret(envVar);
+      if (expected === undefined || expected === "") {
+        misconfig ??= `security scheme "${name}" secret env ${envVar} is not set`;
+        satisfied = false;
+        break;
+      }
+      const presented = where === "header" ? getHeader(scheme.name) : getQuery(scheme.name);
+      if (presented === undefined || !timingSafeEqual(presented, expected)) {
+        satisfied = false; // a wrong/absent credential → 401 (not a misconfig)
+        break;
+      }
+    }
+    if (satisfied) return SECURITY_OK;
+  }
+
+  return misconfig
+    ? { ok: false, status: 500, error: `security misconfigured: ${misconfig}` }
+    : { ok: false, status: 401, error: "unauthorized" };
+}
+
+/** "scheme (op)" pointers for every operation security requirement that names a scheme absent from
+ *  components.securitySchemes — an app-drift the runtime rejects at request time (500) and the
+ *  `--check` gate can surface ahead of time. */
+export function undeclaredSecuritySchemes(doc: OpenApiDoc): string[] {
+  const declared = new Set(Object.keys(doc.components?.securitySchemes ?? {}));
+  const out: string[] = [];
+  for (const op of collectOperations(doc)) {
+    for (const requirement of op.security) {
+      for (const name of Object.keys(requirement)) {
+        if (name !== MALFORMED_SECURITY_REQUIREMENT && !declared.has(name)) {
+          out.push(`${name} (${op.method.toUpperCase()} ${op.path})`);
+        }
+      }
+    }
+  }
+  return out;
+}
+
 function normalizeParameters(raw: unknown[]): OpenApiParameter[] {
   // OpenAPI: parameters are uniquely identified by (name, in). A path-level parameter can be
   // overridden by an operation-level one with the same (name, in) — never duplicated. Callers pass

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

@@ -5,14 +5,18 @@ import type { AppManifest } from "../manifest.ts";
 import type { EngineClient, HostContext, HttpRequest } from "../host.ts";
 import { makeRouter } from "../router.ts";
 import { DataLayer } from "./datasource.ts";
-import { mountApi, resolveOperationHandler, apiDocsPath, type ApiHandle, type OperationHandler } from "./api.ts";
+import { mountApi, resolveOperationHandler, apiDocsPath, NotImplemented, type ApiHandle, type OperationHandler } from "./api.ts";
 
-function req(method: string, path: string, opts: { query?: string; body?: string } = {}): HttpRequest {
+function req(
+  method: string,
+  path: string,
+  opts: { query?: string; body?: string; headers?: Record<string, string> } = {},
+): HttpRequest {
   return {
     method,
     path,
     query: new URLSearchParams(opts.query ?? ""),
-    headers: new Headers(),
+    headers: new Headers(opts.headers ?? {}),
     text: () => Promise.resolve(opts.body ?? ""),
   };
 }
@@ -82,15 +86,18 @@ function build(
   api: Record<string, unknown> | undefined,
   modules: Record<string, Record<string, unknown>>,
   specText = spec,
+  env: (v: string) => string | undefined = () => undefined,
+  existsPaths: string[] = [],
 ): Built {
   const imported: string[] = [];
   const logs: Array<{ level: string; msg: string }> = [];
+  const existsSet = new Set(existsPaths);
   const host: HostContext = {
     runtime: "node",
-    env: () => undefined,
+    env,
     readTextFile: async () => specText,
     listDir: async () => [],
-    exists: async () => false,
+    exists: async (p: string) => existsSet.has(p),
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },
@@ -521,3 +528,174 @@ test("apiDocsPath resolves the UI route (and honours disable / override)", () =>
   assert.equal(apiDocsPath({ api: { spec: "openapi.json", docs: false } }), undefined);
   assert.equal(apiDocsPath({}), undefined);
 });
+
+// ── Security enforcement (ADR 0059: apiKey-guarded webhook operations) ────────────────────────
+
+const securedSpec = JSON.stringify({
+  openapi: "3.0.0",
+  components: {
+    securitySchemes: {
+      webhookKey: { type: "apiKey", in: "header", name: "X-Webhook-Key", "x-nano-secret-env": "NANO_WEBHOOK_KEY" },
+    },
+  },
+  paths: {
+    "/hooks/submit": {
+      post: {
+        operationId: "submitHook",
+        security: [{ webhookKey: [] }],
+        responses: { "204": {} },
+      },
+    },
+  },
+});
+
+test("secured operation: correct apiKey header reaches the delegate (200)", async () => {
+  const seen: unknown[] = [];
+  const handler: OperationHandler = (input) => {
+    seen.push(input);
+    return { status: 200, body: { ok: true } };
+  };
+  const { router, imported } = build(
+    { spec: "openapi.json", dir: "operations" },
+    { "/app/operations/submitHook": { default: handler } },
+    securedSpec,
+    (v) => (v === "NANO_WEBHOOK_KEY" ? "s3cret" : undefined),
+  );
+  const res = await router(
+    req("POST", "/app/api/hooks/submit", { body: "{}", headers: { "X-Webhook-Key": "s3cret" } }),
+  );
+  assert.equal(res.status, 200);
+  assert.equal(seen.length, 1);
+  assert.deepEqual(imported, ["/app/operations/submitHook"]);
+});
+
+test("secured operation: missing/wrong apiKey is rejected 401 without loading the delegate", async () => {
+  const { router, imported } = build(
+    { spec: "openapi.json", dir: "operations" },
+    { "/app/operations/submitHook": { default: () => ({ status: 200 }) } },
+    securedSpec,
+    (v) => (v === "NANO_WEBHOOK_KEY" ? "s3cret" : undefined),
+  );
+  const missing = await router(req("POST", "/app/api/hooks/submit", { body: "{}" }));
+  assert.equal(missing.status, 401);
+  const wrong = await router(
+    req("POST", "/app/api/hooks/submit", { body: "{}", headers: { "X-Webhook-Key": "nope" } }),
+  );
+  assert.equal(wrong.status, 401);
+  // The delegate must never run for an unauthorized request.
+  assert.deepEqual(imported, []);
+});
+
+test("secured operation: an unset secret env fails closed with 500 (misconfiguration)", async () => {
+  const { router, logs } = build(
+    { spec: "openapi.json", dir: "operations" },
+    { "/app/operations/submitHook": { default: () => ({ status: 200 }) } },
+    securedSpec,
+    () => undefined, // NANO_WEBHOOK_KEY not set
+  );
+  const res = await router(
+    req("POST", "/app/api/hooks/submit", { body: "{}", headers: { "X-Webhook-Key": "anything" } }),
+  );
+  assert.equal(res.status, 500);
+  assert.ok(logs.some((l) => l.level === "error" && /security is misconfigured/.test(l.msg)));
+});
+
+// ── Generated controller registry (ADR 0059) ────────────────────────────────────────────────────
+// When `nano-generated/controller.ts` is present, dispatch resolves delegates from its exported
+// `operations` map (deterministic, drift-checked) instead of per-op path imports.
+
+test("controller present: dispatch uses the registry, not a per-op import", async () => {
+  const seen: unknown[] = [];
+  const handler: OperationHandler = (input) => {
+    seen.push(input.params);
+    return { status: 200, body: { ok: true } };
+  };
+  const { router, imported } = build(
+    { spec: "openapi.json" },
+    {
+      "/app/nano-generated/controller": { operations: { getInvoice: handler } },
+    },
+    spec,
+    () => undefined,
+    ["/app/nano-generated/controller.ts"],
+  );
+  const res = await router(req("GET", "/app/api/invoices/7"));
+  assert.equal(res.status, 200);
+  assert.deepEqual(seen, [{ id: "7" }]);
+  // Only the controller barrel is imported — never a per-operation delegate path.
+  assert.deepEqual(imported, ["/app/nano-generated/controller"]);
+});
+
+test("controller present: request validation still runs before the registry delegate", async () => {
+  const handler: OperationHandler = () => ({ status: 201, body: { id: "i", amount: 1 } });
+  const { router } = build(
+    { spec: "openapi.json" },
+    { "/app/nano-generated/controller": { operations: { createInvoice: handler } } },
+    spec,
+    () => undefined,
+    ["/app/nano-generated/controller.ts"],
+  );
+  // amount:0 violates minimum:1 → a 400 from validation, before the delegate.
+  const res = await router(req("POST", "/app/api/invoices", { body: JSON.stringify({ id: "i", amount: 0 }) }));
+  assert.equal(res.status, 400);
+  assert.match(JSON.parse(res.body!).error, /request validation failed/);
+});
+
+test("controller present but missing a delegate key → 500 with a run-`urban gen` hint", async () => {
+  const { router, logs } = build(
+    { spec: "openapi.json" },
+    { "/app/nano-generated/controller": { operations: {} } }, // stale: getInvoice not registered
+    spec,
+    () => undefined,
+    ["/app/nano-generated/controller.ts"],
+  );
+  const res = await router(req("GET", "/app/api/invoices/7"));
+  assert.equal(res.status, 500);
+  assert.match(JSON.parse(res.body!).error, /is not registered/);
+  assert.ok(logs.some((l) => l.level === "error" && /not registered in the generated controller/.test(l.msg)));
+});
+
+test("a NotImplemented throw from a delegate maps to HTTP 501", async () => {
+  const stub: OperationHandler = () => {
+    throw new NotImplemented("getInvoice");
+  };
+  const { router } = build(
+    { spec: "openapi.json" },
+    { "/app/nano-generated/controller": { operations: { getInvoice: stub } } },
+    spec,
+    () => undefined,
+    ["/app/nano-generated/controller.ts"],
+  );
+  const res = await router(req("GET", "/app/api/invoices/7"));
+  assert.equal(res.status, 501);
+  const bodyJson = JSON.parse(res.body!);
+  assert.equal(bodyJson.operationId, "getInvoice");
+  assert.match(bodyJson.error, /not implemented/);
+});
+
+test("no controller present → back-compat per-op import path still works", async () => {
+  const { router, imported } = build(
+    { spec: "openapi.json" },
+    { "/app/operations/getInvoice": { default: () => ({ body: { ok: true } }) } },
+    // no exists paths → controller absent
+  );
+  const res = await router(req("GET", "/app/api/invoices/9"));
+  assert.equal(res.status, 200);
+  assert.deepEqual(imported, ["/app/operations/getInvoice"]);
+});
+
+test("compiled app: controller.js present (no .ts) → still uses the registry", async () => {
+  // A published / `urban run` build ships controller.js with TS sources absent. Probing only .ts
+  // would wrongly report the registry missing and fall back to per-op imports; probe all extensions.
+  const handler: OperationHandler = () => ({ status: 200, body: { ok: true } });
+  const { router, imported } = build(
+    { spec: "openapi.json" },
+    { "/app/nano-generated/controller": { operations: { getInvoice: handler } } },
+    spec,
+    () => undefined,
+    ["/app/nano-generated/controller.js"], // only the compiled artifact exists on disk
+  );
+  const res = await router(req("GET", "/app/api/invoices/7"));
+  assert.equal(res.status, 200);
+  assert.deepEqual(imported, ["/app/nano-generated/controller"]);
+});