@nanobpm/urban 0.34.0 → 0.35.0

package/dist/openapi/spec.d.ts

@@ -50,6 +50,26 @@ export interface OpenApiResponse {
     description?: string;
     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?: {
@@ -59,7 +79,10 @@ export interface OpenApiDoc {
     paths?: Record<string, Record<string, unknown>>;
     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. */
 export declare const HTTP_METHODS: readonly ["get", "put", "post", "delete", "patch", "options", "head"];
@@ -76,6 +99,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;
 }
@@ -109,6 +135,34 @@ export declare function isSafeOperationId(id: string): boolean;
  *  path segment. collectOperations skips these (they never mount or drive an import); the runtime
  *  surfaces them at `warn`. */
 export declare function operationsWithUnsafeId(doc: OpenApiDoc): string[];
+/** 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;
+}
+/**
+ * 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 declare function evaluateSecurity(doc: OpenApiDoc, op: OperationInfo, getHeader: (name: string) => string | undefined, getQuery: (name: string) => string | undefined, getSecret: (envVar: string) => string | undefined): SecurityDecision;
+/** "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 declare function undeclaredSecuritySchemes(doc: OpenApiDoc): string[];
 /** Turn an OpenAPI path template ("/invoices/{id}") into a matcher under `base` ("/app/api"):
  *  a RegExp that captures each `{param}` positionally, plus the ordered path-parameter names. The
  *  runtime matches concrete request paths, so a templated segment becomes a single-segment capture. */

package/dist/openapi/spec.js

@@ -126,6 +126,12 @@ export function collectOperations(doc) {
             const requestBody = isRecord(opRaw.requestBody) ? opRaw.requestBody : undefined;
             const requestBodySchema = firstJsonSchema(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,
@@ -134,6 +140,7 @@ export function collectOperations(doc) {
                 requestBodySchema,
                 requestBodyRequired: requestBody?.required === true,
                 responseSchema: firstSuccessSchema(responses),
+                security,
                 eject: opRaw["x-urban-eject"] === true,
                 summary: typeof opRaw.summary === "string" ? opRaw.summary : undefined,
             });
@@ -205,6 +212,145 @@ export function operationsWithUnsafeId(doc) {
     }
     return out;
 }
+const MALFORMED_SECURITY_REQUIREMENT = "__nano_malformed_security_requirement__";
+function malformedSecurityRequirement() {
+    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) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        return [malformedSecurityRequirement()];
+    const out = [];
+    for (const entry of raw) {
+        if (!isRecord(entry)) {
+            out.push(malformedSecurityRequirement());
+            continue;
+        }
+        const req = {};
+        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;
+}
+const SECURITY_OK = { 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, b) {
+    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, op, getHeader, getQuery, getSecret) {
+    if (op.security.length === 0)
+        return SECURITY_OK;
+    const schemes = doc.components?.securitySchemes ?? {};
+    let misconfig;
+    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) {
+    const declared = new Set(Object.keys(doc.components?.securitySchemes ?? {}));
+    const out = [];
+    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) {
     // 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/dist/runtime/core/modules/api.js

@@ -14,7 +14,7 @@
 import { errorMessage } from "../guards.js";
 import { html, json, normalizeRoutePath } from "../router.js";
 import { resolveAppPath } from "./datasource.js";
-import { collectOperations, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, resolveSchema, toRouteMatcher, undeclaredPathParams, validateValue, } from "../../../openapi/spec.js";
+import { collectOperations, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, resolveSchema, toRouteMatcher, undeclaredPathParams, undeclaredSecuritySchemes, evaluateSecurity, validateValue, } from "../../../openapi/spec.js";
 /** The canonical, non-configurable mount prefix for an app's OpenAPI operations. Operations always
  *  live under `/app/api` so page actions, links, and any `callRoute` can name an operation path as a
  *  stable framework constant (`/app/api/<op path>`) — there is no per-app `base` knob to drift. */
@@ -229,6 +229,10 @@ export function mountApi(ctx, app) {
                 if (unsafe.length > 0) {
                     ctx.host.log("warn", "OpenAPI operationIds that are not a safe path segment are skipped (ADR 0058)", { unsafe });
                 }
+                const undeclaredSchemes = undeclaredSecuritySchemes(d);
+                if (undeclaredSchemes.length > 0) {
+                    ctx.host.log("warn", "OpenAPI operations require a security scheme not declared in components.securitySchemes — those requests are rejected with 500 (ADR 0059)", { undeclared: undeclaredSchemes });
+                }
                 const mounted = collectOperations(d).map((op) => {
                     const { pattern, paramNames } = toRouteMatcher(base, op.path);
                     return { op, pattern, paramNames };
@@ -270,6 +274,19 @@ export function mountApi(ctx, app) {
         }
         const { op } = match;
         const ejected = surfaceEject || op.eject;
+        // Enforce the operation's security requirements (ADR 0059) before touching the body or the
+        // delegate: an unauthorized request should do no work and reveal nothing. Enforced even for
+        // ejected ops (eject changes body handling, not who may call the operation).
+        const authz = evaluateSecurity(d, op, (name) => req.headers.get(name) ?? undefined, (name) => req.query.get(name) ?? undefined, (envVar) => ctx.host.env(envVar));
+        if (!authz.ok) {
+            if (authz.status === 500) {
+                ctx.host.log("error", "OpenAPI operation security is misconfigured (ADR 0059)", {
+                    operationId: op.operationId,
+                    reason: authz.error,
+                });
+            }
+            return json({ error: authz.error ?? "unauthorized" }, authz.status ?? 401);
+        }
         // Path params from the capture groups; query as a single-or-array map.
         const captures = match.pattern.exec(req.path) ?? [];
         const params = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.34.0",
+  "version": "0.35.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",

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);
+});

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,
       });
@@ -291,6 +328,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

@@ -7,12 +7,16 @@ import { makeRouter } from "../router.ts";
 import { DataLayer } from "./datasource.ts";
 import { mountApi, resolveOperationHandler, apiDocsPath, 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,12 +86,13 @@ function build(
   api: Record<string, unknown> | undefined,
   modules: Record<string, Record<string, unknown>>,
   specText = spec,
+  env: (v: string) => string | undefined = () => undefined,
 ): Built {
   const imported: string[] = [];
   const logs: Array<{ level: string; msg: string }> = [];
   const host: HostContext = {
     runtime: "node",
-    env: () => undefined,
+    env,
     readTextFile: async () => specText,
     listDir: async () => [],
     exists: async () => false,
@@ -521,3 +526,74 @@ 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)));
+});

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

@@ -29,6 +29,8 @@ import {
   resolveSchema,
   toRouteMatcher,
   undeclaredPathParams,
+  undeclaredSecuritySchemes,
+  evaluateSecurity,
   validateValue,
   type ValidationIssue,
 } from "../../../openapi/spec.ts";
@@ -336,6 +338,14 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
               { unsafe },
             );
           }
+          const undeclaredSchemes = undeclaredSecuritySchemes(d);
+          if (undeclaredSchemes.length > 0) {
+            ctx.host.log(
+              "warn",
+              "OpenAPI operations require a security scheme not declared in components.securitySchemes — those requests are rejected with 500 (ADR 0059)",
+              { undeclared: undeclaredSchemes },
+            );
+          }
           const mounted = collectOperations(d).map((op) => {
             const { pattern, paramNames } = toRouteMatcher(base, op.path);
             return { op, pattern, paramNames };
@@ -384,6 +394,26 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
     const { op } = match;
     const ejected = surfaceEject || op.eject;
 
+    // Enforce the operation's security requirements (ADR 0059) before touching the body or the
+    // delegate: an unauthorized request should do no work and reveal nothing. Enforced even for
+    // ejected ops (eject changes body handling, not who may call the operation).
+    const authz = evaluateSecurity(
+      d,
+      op,
+      (name) => req.headers.get(name) ?? undefined,
+      (name) => req.query.get(name) ?? undefined,
+      (envVar) => ctx.host.env(envVar),
+    );
+    if (!authz.ok) {
+      if (authz.status === 500) {
+        ctx.host.log("error", "OpenAPI operation security is misconfigured (ADR 0059)", {
+          operationId: op.operationId,
+          reason: authz.error,
+        });
+      }
+      return json({ error: authz.error ?? "unauthorized" }, authz.status ?? 401);
+    }
+
     // Path params from the capture groups; query as a single-or-array map.
     const captures = match.pattern.exec(req.path) ?? [];
     const params: Record<string, string> = {};