tina4-nodejs 3.13.41 → 3.13.43

package/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.41)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.43)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
@@ -300,6 +300,15 @@ Auto-generates OpenAPI 3.0.3 docs.
 - `TINA4_SWAGGER_UI_CDN` - base URL for the Swagger UI assets (`swagger-ui.css` + `swagger-ui-bundle.js`). Defaults to the public CDN (`https://unpkg.com/swagger-ui-dist@5`); point it at a self-hosted mirror for air-gapped deployments.
 - Info block: `TINA4_SWAGGER_TITLE`, `TINA4_SWAGGER_VERSION`, `TINA4_SWAGGER_DESCRIPTION`, `TINA4_SWAGGER_CONTACT_EMAIL`, `TINA4_SWAGGER_CONTACT_TEAM`, `TINA4_SWAGGER_CONTACT_URL`, `TINA4_SWAGGER_LICENSE`.
 
+**Configurability (v3.13.42):**
+- `TINA4_SWAGGER_OPENAPI` - OpenAPI version (default `3.0.3`); `3.1`/`3.1.0` emits `3.1.0`.
+- `TINA4_SWAGGER_BEARER_FORMAT` - `bearerFormat` on the built-in `bearerAuth` scheme (default `JWT`; use `opaque` for `sk_live_` keys).
+- `TINA4_SWAGGER_API_KEY_NAME` / `TINA4_SWAGGER_API_KEY_IN` - when the name is set, emit an `apiKeyAuth` scheme; `_IN` is `header` (default) / `query` / `cookie`.
+- `TINA4_SWAGGER_DEFAULT_SCHEME` - scheme a secured route uses when its `meta` declares no `security` (default `bearerAuth`).
+- `TINA4_SWAGGER_INCLUDE` / `TINA4_SWAGGER_EXCLUDE` - comma-separated path-prefix allow-list / deny-list (`/swagger` + `/__dev` always excluded).
+
+**Per-route security + reusable schemas (v3.13.42).** A route's `meta` may carry `security` (a scheme name, a `{name: [scopes]}` map, a list of maps for OR, or the string `"public"` to force `security: []`), a sibling `scopes` array, and `requestSchema` / `responseSchemas` referencing schemas registered with `addSchema(name, schema)`. Register arbitrary schemes (including `oauth2` with scopes) via `addSecurityScheme(name, definition)`; `resetRegistry()` clears both. All three are exported from `@tina4/swagger`. Scopes are kept spec-valid: only `oauth2`/`openIdConnect` carry them, `http`/`apiKey` get `[]`.
+
 ### @tina4/frond (`packages/frond/`)
 Built-in zero-dependency Twig-compatible template engine (the only template engine; there is no `twig` npm dependency).
 

package/package.json

@@ -3,7 +3,7 @@
 
 
 
-  "version": "3.13.41",
+  "version": "3.13.43",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",

package/packages/core/src/queue.ts

@@ -81,9 +81,17 @@ export interface ProcessOptions {
   maxJobs?: number;
   maxRetries?: number;
   batchSize?: number;
+  /**
+   * Override the queue's topic for this drain (parity with Python's
+   * process(handler, topic=...)). When set, process() retargets the queue so
+   * pop() reads the requested topic instead of the construction-time one.
+   */
+  topic?: string;
 }
 
 export interface ConsumeOptions {
+  /** Topic to consume (defaults to the constructor topic). */
+  topic?: string;
   batchSize?: number;
   pollInterval?: number;
   iterations?: number;
@@ -95,6 +103,18 @@ export interface QueueBackendInterface {
   pop(queue: string): QueueJob | null;
   size(queue: string): number;
   clear(queue: string): void;
+  // Optional full lifecycle. Reservation-based backends (MongoDB) implement
+  // these so complete()/fail() ack the ACTIVE store — without complete(), a
+  // reserved Mongo job is re-delivered after the visibility window. Backends
+  // that auto-ack on pop (RabbitMQ no-ack) or delegate to the broker (Kafka
+  // offsets) omit them, and the Queue keeps its prior behaviour for them.
+  complete?(queue: string, id: string): void;
+  fail?(queue: string, id: string, error: string, maxRetries: number, retryBackoff: number): void;
+  retry?(queue: string, id: string, delaySeconds?: number): void;
+  deadLetters?(queue: string, maxRetries?: number): QueueJob[];
+  failed?(queue: string, maxRetries?: number): QueueJob[];
+  retryFailed?(queue: string, maxRetries?: number): number;
+  purge?(queue: string, status?: string): number;
 }
 
 // ── Queue ────────────────────────────────────────────────────
@@ -152,6 +172,22 @@ export class Queue {
     }
   }
 
+  /**
+   * Point this queue at ``topic`` in place.
+   *
+   * produce()/consume()/process() call this so a topic argument actually
+   * changes which topic is read or written. Without it the argument was
+   * accepted but ignored on the read path — pop() always used the
+   * construction-time topic, so consume("other") silently drained the wrong
+   * queue. The lite + external backends are topic-per-call (every push/pop/size
+   * takes the queue name), so changing this.topic retargets all of them; the
+   * job lifecycle (complete()/fail()/retry()) routes by the job's own .topic, so
+   * it is unaffected. Mirrors Python's Queue._retarget().
+   */
+  private retarget(topic: string): void {
+    this.topic = topic;
+  }
+
   // ── Unified API (topic-aware) ────────────────────────────────
 
   /**
@@ -197,6 +233,12 @@ export class Queue {
     handler: (job: QueueJob | QueueJob[]) => Promise<void> | void,
     options?: ProcessOptions,
   ): void {
+    // Honour an explicit topic: retarget so pop() drains the requested topic
+    // (parity with Python's process(handler, topic=...)). Without this the
+    // argument was accepted but ignored on the read path.
+    if (options?.topic !== undefined) {
+      this.retarget(options.topic);
+    }
     const queue = this.topic;
     const opts = options;
 
@@ -275,6 +317,9 @@ export class Queue {
    * auto-retry lifecycle; dead-lettered jobs are returned by deadLetters().
    */
   failed(): QueueJob[] {
+    if (this.externalBackend?.failed) {
+      return this.externalBackend.failed(this.topic, this._maxRetries);
+    }
     return this.liteBackend.failed(this.topic, this._maxRetries);
   }
 
@@ -288,6 +333,10 @@ export class Queue {
   retry(jobId?: string, delaySeconds?: number): boolean {
     if (jobId) {
       // Retry a specific job by ID
+      if (this.externalBackend?.retry) {
+        this.externalBackend.retry(this.topic, jobId, delaySeconds);
+        return true;
+      }
       return this.liteBackend.retry(this.topic, jobId, delaySeconds);
     }
     // Retry all dead-letter jobs
@@ -295,8 +344,12 @@ export class Queue {
     if (deadJobs.length === 0) return false;
     let retried = false;
     for (const job of deadJobs) {
-      const ok = this.liteBackend.retry(this.topic, job.id, delaySeconds);
-      if (ok) retried = true;
+      if (this.externalBackend?.retry) {
+        this.externalBackend.retry(this.topic, job.id, delaySeconds);
+        retried = true;
+      } else if (this.liteBackend.retry(this.topic, job.id, delaySeconds)) {
+        retried = true;
+      }
     }
     return retried;
   }
@@ -305,6 +358,9 @@ export class Queue {
    * Get dead letter jobs — failed jobs that exceeded max retries.
    */
   deadLetters(maxRetries?: number): QueueJob[] {
+    if (this.externalBackend?.deadLetters) {
+      return this.externalBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
+    }
     return this.liteBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
   }
 
@@ -312,6 +368,9 @@ export class Queue {
    * Delete messages by status (e.g. "completed", "failed", "dead").
    */
   purge(status: string, maxRetries?: number): number {
+    if (this.externalBackend?.purge) {
+      return this.externalBackend.purge(this.topic, status);
+    }
     return this.liteBackend.purge(this.topic, status, maxRetries ?? this._maxRetries);
   }
 
@@ -319,17 +378,27 @@ export class Queue {
    * Re-queue failed jobs that haven't exceeded max retries back to pending.
    */
   retryFailed(maxRetries?: number): number {
+    if (this.externalBackend?.retryFailed) {
+      return this.externalBackend.retryFailed(this.topic, maxRetries ?? this._maxRetries);
+    }
     return this.liteBackend.retryFailed(this.topic, maxRetries ?? this._maxRetries);
   }
 
   /**
    * Produce a message onto a topic. Convenience wrapper around push().
+   *
+   * Retargets to the requested topic (restoring the prior one afterwards) so it
+   * shares the same retarget path consume()/process() use — keeping produce and
+   * consume symmetric on the same topic argument.
    */
   produce(topic: string, payload: unknown, priority: number = 0, delay: number = 0): string {
-    if (this.externalBackend) {
-      return this.externalBackend.push(topic, payload, delay);
+    const previous = this.topic;
+    this.retarget(topic);
+    try {
+      return this.push(payload, delay, priority);
+    } finally {
+      this.retarget(previous);
     }
-    return this.liteBackend.push(topic, payload, delay, priority);
   }
 
   /**
@@ -368,7 +437,9 @@ export class Queue {
 
     if (topicOrOptions !== null && typeof topicOrOptions === "object") {
       const opts = topicOrOptions as ConsumeOptions;
-      q = this.topic;
+      // Honour opts.topic (parity with the string-arg form) — previously the
+      // options-object form ignored it and always drained the constructor topic.
+      q = opts.topic ?? this.topic;
       resolvedId = opts.id;
       resolvedPollInterval = opts.pollInterval ?? 1000;
       resolvedIterations = opts.iterations ?? 0;
@@ -381,6 +452,12 @@ export class Queue {
       resolvedBatchSize = batchSize;
     }
 
+    // Honour the topic argument: point the queue (and the backend pop()/
+    // popById() route through) at it. Previously the resolved topic was
+    // computed but never used — pop()/popById() read this.topic, so
+    // consume("other") silently drained the construction-time topic.
+    this.retarget(q);
+
     if (resolvedId !== undefined) {
       const raw = this.popById(resolvedId);
       if (raw) yield createJob(raw as any, this);
@@ -453,6 +530,10 @@ export class Queue {
    * after retryBackoff seconds) or dead-letter (attempts >= maxRetries).
    */
   _failJob(queue: string, job: QueueJob, error: string, maxRetries: number): void {
+    if (this.externalBackend?.fail) {
+      this.externalBackend.fail(queue, job.id, error, maxRetries, this._retryBackoff);
+      return;
+    }
     this.liteBackend.failJob(queue, job, error, maxRetries, this._retryBackoff);
   }
 
@@ -460,15 +541,26 @@ export class Queue {
    * Re-queue a job back to the main queue directory with incremented attempts.
    */
   _retryJob(queue: string, job: QueueJob, delaySeconds?: number): void {
+    if (this.externalBackend?.retry) {
+      this.externalBackend.retry(queue, job.id, delaySeconds);
+      return;
+    }
     this.liteBackend.retryJob(queue, job, delaySeconds);
   }
 
   /**
-   * Acknowledge a completed job — drop its reservation record so the visibility
-   * reclaim never re-delivers it. No-op for external backends (they ack their
-   * own way; lite-backend reservations are file records).
+   * Acknowledge a completed job — drop its reservation so the visibility reclaim
+   * never re-delivers it. Routes to the active backend: a reservation-based
+   * external backend (MongoDB) acks there (without this its reserved doc would
+   * be re-delivered after the visibility window); RabbitMQ (no-ack on get) and
+   * Kafka (offset-based) expose no complete(), so the lite path is used and is a
+   * harmless no-op for them since they already acked/own redelivery.
    */
   _completeJob(queue: string, job: QueueJob): void {
+    if (this.externalBackend?.complete) {
+      this.externalBackend.complete(queue, job.id);
+      return;
+    }
     this.liteBackend.completeJob(queue, job);
   }
 }

package/packages/core/src/queueBackends/mongoBackend.ts

@@ -229,12 +229,20 @@ export class MongoBackend implements QueueBackend {
             if (result && result.value) {
               // findOneAndUpdate returns { value: doc } in older drivers
               const doc = result.value;
+              // Carry the framework topic on the job so complete()/fail()
+              // route the ack/requeue back to THIS topic's docs (the Mongo
+              // internal queue field is dropped from the returned shape).
+              doc.topic = queueName;
               delete doc._id;
               delete doc.queue;
               process.stdout.write(JSON.stringify(doc));
             } else if (result && result._id) {
               // Some driver versions return the doc directly
               const doc = { ...result };
+              // Carry the framework topic on the job so complete()/fail()
+              // route the ack/requeue back to THIS topic's docs (the Mongo
+              // internal queue field is dropped from the returned shape).
+              doc.topic = queueName;
               delete doc._id;
               delete doc.queue;
               process.stdout.write(JSON.stringify(doc));
@@ -253,6 +261,95 @@ export class MongoBackend implements QueueBackend {
             await col.deleteMany({ queue: queueName });
             process.stdout.write("__CLEARED__");
           }
+          else if (operation === "complete") {
+            // Ack a finished job so the reclaim never re-delivers it. data = job id.
+            // (The pop reserved this doc; without this it stays reserved and is
+            // re-delivered after the visibility window — the redelivery bug.)
+            await col.updateOne(
+              { queue: queueName, id: data },
+              { $set: { status: "completed", completedAt: new Date().toISOString(), reservedAt: null } },
+            );
+            process.stdout.write("__OK__");
+          }
+          else if (operation === "fail") {
+            // Requeue while retries remain (reset availableAt -> visible again),
+            // else dead-letter. Atomic decision in Mongo. data = JSON
+            // { id, error, maxRetries, retryBackoff }.
+            const info = JSON.parse(data);
+            const now = new Date().toISOString();
+            const doc = await col.findOne({ queue: queueName, id: info.id });
+            if (doc) {
+              const attempts = (doc.attempts || 0) + 1;
+              if (attempts >= info.maxRetries) {
+                await col.insertOne({
+                  ...doc, _id: undefined, attempts,
+                  status: "dead", queue: queueName + ".dead_letter", error: info.error,
+                });
+                await col.deleteOne({ _id: doc._id, queue: queueName });
+              } else {
+                const avail = info.retryBackoff > 0
+                  ? new Date(Date.now() + info.retryBackoff * 1000).toISOString()
+                  : now;
+                await col.updateOne(
+                  { _id: doc._id, queue: queueName },
+                  { $set: { status: "pending", availableAt: avail, reservedAt: null, error: info.error },
+                    $inc: { attempts: 1 } },
+                );
+              }
+            }
+            process.stdout.write("__OK__");
+          }
+          else if (operation === "retry") {
+            // Explicit manual re-queue (always re-enqueues). data = JSON
+            // { id, delaySeconds }.
+            const info = JSON.parse(data);
+            const avail = info.delaySeconds > 0
+              ? new Date(Date.now() + info.delaySeconds * 1000).toISOString()
+              : new Date().toISOString();
+            await col.updateOne(
+              { queue: queueName, id: info.id },
+              { $set: { status: "pending", availableAt: avail, reservedAt: null }, $inc: { attempts: 1 } },
+            );
+            process.stdout.write("__OK__");
+          }
+          else if (operation === "deadLetters") {
+            const docs = await col.find({ queue: queueName + ".dead_letter" }).toArray();
+            const out = docs.map((d) => { delete d._id; delete d.queue; return d; });
+            process.stdout.write(JSON.stringify(out));
+          }
+          else if (operation === "failed") {
+            const docs = await col
+              .find({ queue: queueName, status: "failed", attempts: { $lt: maxRetries } })
+              .toArray();
+            const out = docs.map((d) => { delete d._id; delete d.queue; return d; });
+            process.stdout.write(JSON.stringify(out));
+          }
+          else if (operation === "retryFailed") {
+            // Revive dead-lettered jobs under the (possibly raised) limit back to
+            // the main queue as pending. data = the max-retries limit.
+            const mr = data ? Number(data) : maxRetries;
+            const now = new Date().toISOString();
+            let revived = 0;
+            while (true) {
+              const doc = await col.findOneAndUpdate(
+                { queue: queueName + ".dead_letter", attempts: { $lt: mr } },
+                { $set: { status: "pending", availableAt: now, reservedAt: null, queue: queueName, error: null } },
+                { returnDocument: "after" },
+              );
+              const updated = doc && doc.value ? doc.value : (doc && doc._id ? doc : null);
+              if (!updated) break;
+              revived++;
+            }
+            process.stdout.write(String(revived));
+          }
+          else if (operation === "purge") {
+            // Delete docs by status (default: all for the topic). data = JSON { status }.
+            const info = data ? JSON.parse(data) : {};
+            const filter = { queue: queueName };
+            if (info.status) filter.status = info.status;
+            const res = await col.deleteMany(filter);
+            process.stdout.write(String(res.deletedCount || 0));
+          }
         } catch (err) {
           process.stderr.write(err.message || String(err));
           process.exit(1);
@@ -328,4 +425,50 @@ export class MongoBackend implements QueueBackend {
   clear(queue: string): void {
     this.execSync("clear", queue);
   }
+
+  /**
+   * Acknowledge a completed job — drop its reservation so the reclaim never
+   * re-delivers it. Without this a Mongo-popped job stayed reserved and was
+   * re-delivered after the visibility window (the redelivery bug).
+   */
+  complete(queue: string, id: string): void {
+    this.execSync("complete", queue, id);
+  }
+
+  /**
+   * Record a failed attempt: requeue (reset availableAt, ++attempts) while
+   * retries remain, else dead-letter. Mirrors the file/lite backend.
+   */
+  fail(queue: string, id: string, error: string, maxRetries: number, retryBackoff: number = 0): void {
+    this.execSync("fail", queue, JSON.stringify({ id, error, maxRetries, retryBackoff }));
+  }
+
+  /** Explicit manual re-queue (always re-enqueues regardless of the retry limit). */
+  retry(queue: string, id: string, delaySeconds: number = 0): void {
+    this.execSync("retry", queue, JSON.stringify({ id, delaySeconds }));
+  }
+
+  /** Jobs that exceeded max retries (the `<queue>.dead_letter` collection topic). */
+  deadLetters(queue: string, maxRetries?: number): QueueJob[] {
+    const out = this.execSync("deadLetters", queue, String(maxRetries ?? this.maxRetries));
+    try { return JSON.parse(out) as QueueJob[]; } catch { return []; }
+  }
+
+  /** Jobs that failed but are still eligible for retry (status=failed, attempts < max). */
+  failed(queue: string, maxRetries?: number): QueueJob[] {
+    const out = this.execSync("failed", queue, String(maxRetries ?? this.maxRetries));
+    try { return JSON.parse(out) as QueueJob[]; } catch { return []; }
+  }
+
+  /** Revive dead-lettered jobs under the (possibly raised) limit. Returns count revived. */
+  retryFailed(queue: string, maxRetries?: number): number {
+    const out = this.execSync("retryFailed", queue, String(maxRetries ?? this.maxRetries));
+    return parseInt(out, 10) || 0;
+  }
+
+  /** Remove jobs by status (default: every doc for the topic). Returns count removed. */
+  purge(queue: string, status?: string): number {
+    const out = this.execSync("purge", queue, JSON.stringify({ status: status ?? "" }));
+    return parseInt(out, 10) || 0;
+  }
 }

package/packages/core/src/types.ts

@@ -138,6 +138,28 @@ export interface RouteMeta {
   example?: unknown;
   /** Marks the operation deprecated in the spec. */
   deprecated?: boolean;
+  /**
+   * Per-route security requirement (v3.13.42). Overrides the default scheme.
+   * Accepted forms (normalized by the generator into a security-requirement list):
+   *   "bearerAuth"                          -> [{ bearerAuth: [] }]
+   *   "public" | "none" | []                -> [] (explicitly no auth)
+   *   { apiKeyAuth: [] }                    -> [{ apiKeyAuth: [] }]   (AND within one map)
+   *   [{ oauth2: ["read"] }, { bearerAuth: [] }]  -> verbatim (OR across maps)
+   */
+  security?: string | string[] | Record<string, string[]> | Array<Record<string, string[]>>;
+  /** Scopes for a single named scheme passed as `security: "oauth2"` + `scopes: [...]`. */
+  scopes?: string[];
+  /**
+   * Reference a registered component schema as the request body (v3.13.42):
+   *   requestSchema: "CreateUser"  OR  { name: "CreateUser", contentType: "application/json" }
+   * Emits `$ref: #/components/schemas/CreateUser` and lands the schema in components.schemas.
+   */
+  requestSchema?: string | { name: string; contentType?: string };
+  /**
+   * Reference registered component schemas as response bodies, keyed by status (v3.13.42):
+   *   responseSchemas: { 200: "User", 201: { name: "User", isList: true } }
+   */
+  responseSchemas?: Record<string, string | { name: string; isList?: boolean }>;
 }
 
 export interface Tina4Config {

package/packages/swagger/src/generator.ts

@@ -20,6 +20,120 @@ interface OpenAPISpec {
 
 const WRITE_METHODS = new Set(["post", "put", "patch", "delete"]);
 
+// ── Configuration registries (v3.13.42) ───────────────────────────
+// Process-wide registries for security schemes and reusable component schemas
+// declared programmatically (addSecurityScheme / addSchema). Kept module-level so
+// app bootstrap can register before any generate() call; resetRegistry() clears
+// them (tests). Parity with Python's Swagger.add_security_scheme/add_schema/reset_registry.
+const registeredSchemes: Record<string, Record<string, unknown>> = {};
+const registeredSchemas: Record<string, Record<string, unknown>> = {};
+
+/**
+ * Register a named OpenAPI security scheme (e.g. an oauth2 scheme with scopes,
+ * or a custom apiKey). Call at app bootstrap, before generate(). A registered
+ * scheme may override the built-in bearerAuth.
+ */
+export function addSecurityScheme(name: string, definition: Record<string, unknown>): void {
+  registeredSchemes[name] = definition;
+}
+
+/**
+ * Register a reusable component schema, referenceable via meta.requestSchema /
+ * meta.responseSchemas or a raw $ref.
+ */
+export function addSchema(name: string, schema: Record<string, unknown>): void {
+  registeredSchemas[name] = schema;
+}
+
+/** Clear the security-scheme and schema registries (test helper). */
+export function resetRegistry(): void {
+  for (const k of Object.keys(registeredSchemes)) delete registeredSchemes[k];
+  for (const k of Object.keys(registeredSchemas)) delete registeredSchemas[k];
+}
+
+/** Resolve TINA4_SWAGGER_OPENAPI to a concrete version. Default 3.0.3; "3.1"/"3.1.0" -> "3.1.0". */
+function resolveOpenApiVersion(): string {
+  const v = (process.env.TINA4_SWAGGER_OPENAPI ?? "").trim();
+  if (!v) return "3.0.3";
+  if (v === "3.1" || v === "3.1.0") return "3.1.0";
+  if (v === "3.0" || v === "3.0.3") return "3.0.3";
+  return v; // honour an explicit full version verbatim
+}
+
+/** Comma-separated env value -> clean list. */
+function csv(val: string | undefined): string[] {
+  return (val ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+/** Resolve components.securitySchemes from defaults + env + registry. */
+function resolveSecuritySchemes(): Record<string, Record<string, unknown>> {
+  const bearerFormat = process.env.TINA4_SWAGGER_BEARER_FORMAT ?? "JWT";
+  const schemes: Record<string, Record<string, unknown>> = {
+    bearerAuth: { type: "http", scheme: "bearer", bearerFormat },
+  };
+  const apiKeyName = (process.env.TINA4_SWAGGER_API_KEY_NAME ?? "").trim();
+  if (apiKeyName.length > 0) {
+    const rawIn = process.env.TINA4_SWAGGER_API_KEY_IN ?? "header";
+    const apiKeyIn = ["header", "query", "cookie"].includes(rawIn) ? rawIn : "header";
+    schemes.apiKeyAuth = { type: "apiKey", name: apiKeyName, in: apiKeyIn };
+  }
+  // Registered schemes win (let an app override bearerAuth or add oauth2).
+  for (const [name, def] of Object.entries(registeredSchemes)) {
+    schemes[name] = def;
+  }
+  return schemes;
+}
+
+/**
+ * Normalize a meta.security value (+ optional scopes) into an OpenAPI
+ * security-requirement list. Mirrors Python's _normalize_security.
+ */
+function normalizeSecurity(
+  value: NonNullable<unknown> | undefined,
+  scopes: string[] | undefined
+): Array<Record<string, string[]>> {
+  if ((value === "public" || value === "none" || value === undefined || value === null) && (!scopes || scopes.length === 0)) {
+    return [];
+  }
+  if (typeof value === "string") {
+    return [{ [value]: [...(scopes ?? [])] }];
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return [];
+    return value.map((req) => normalizeRequirementMap(req as Record<string, string[]>));
+  }
+  if (value !== null && typeof value === "object") {
+    return [normalizeRequirementMap(value as Record<string, string[]>)];
+  }
+  return [];
+}
+
+function normalizeRequirementMap(req: Record<string, string[]>): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const [k, v] of Object.entries(req)) out[k] = [...(v ?? [])];
+  return out;
+}
+
+/**
+ * Keep a security-requirement list spec-valid: scopes are allowed only on
+ * oauth2/openIdConnect schemes; everything else gets an empty array (OpenAPI
+ * requires it). Mirrors Python's _sanitize_security.
+ */
+function sanitizeSecurity(
+  reqs: Array<Record<string, string[]>>,
+  schemes: Record<string, Record<string, unknown>>
+): Array<Record<string, string[]>> {
+  const scopeOk = new Set(["oauth2", "openIdConnect"]);
+  return reqs.map((req) => {
+    const clean: Record<string, string[]> = {};
+    for (const [name, scopes] of Object.entries(req)) {
+      const stype = (schemes[name] as Record<string, unknown> | undefined)?.type;
+      clean[name] = scopeOk.has(stype as string) ? [...scopes] : [];
+    }
+    return clean;
+  });
+}
+
 export function generate(
   routes: RouteDefinition[],
   models: ModelDefinition[] = []
@@ -49,21 +163,31 @@ export function generate(
     info.license = url ? { name, url } : { name };
   }
 
+  const schemes = resolveSecuritySchemes();
   const spec: OpenAPISpec = {
-    openapi: "3.0.3",
+    openapi: resolveOpenApiVersion(),
     info,
     servers: resolveServers(),
     paths: {},
     components: {
       schemas: {},
-      // bearerAuth was never defined before — secured routes were documented
-      // identically to public ones (audit P1). Define it once and reference it.
-      securitySchemes: {
-        bearerAuth: { type: "http", scheme: "bearer", bearerFormat: "JWT" },
-      },
+      // Configurable security schemes (v3.13.42): bearerFormat via env, optional
+      // apiKey scheme, plus any programmatically-registered schemes (which may
+      // override bearerAuth — e.g. an oauth2 scheme with scopes).
+      securitySchemes: schemes,
     },
   };
 
+  // Default scheme secured routes use when no explicit meta.security is set.
+  const defaultScheme = process.env.TINA4_SWAGGER_DEFAULT_SCHEME ?? "bearerAuth";
+
+  // Path filters (comma-separated raw-path prefixes).
+  const includePrefixes = csv(process.env.TINA4_SWAGGER_INCLUDE);
+  const excludePrefixes = csv(process.env.TINA4_SWAGGER_EXCLUDE);
+
+  // Reusable custom schemas referenced by routes via meta.requestSchema/responseSchemas.
+  const refSchemas = new Set<string>();
+
   // Generate schemas from models
   for (const model of models) {
     const schema = modelToSchema(model);
@@ -75,6 +199,7 @@ export function generate(
 
   // Generate paths from routes
   for (const route of routes) {
+    if (!isIncludedPath(route.pattern, includePrefixes, excludePrefixes)) continue;
     const openApiPath = patternToOpenAPI(route.pattern);
     const method = route.method.toLowerCase();
 
@@ -123,8 +248,20 @@ export function generate(
       }
     }
 
-    // Add request body for POST/PUT
-    if (method === "post" || method === "put") {
+    // Request body — a registered custom schema $ref (meta.requestSchema) wins,
+    // else the inferred-from-model body (POST/PUT to a resource), else an
+    // example-only body.
+    const reqSchemaRef = parseRequestSchema(route.meta?.requestSchema);
+    if (reqSchemaRef && (method === "post" || method === "put" || method === "patch")) {
+      refSchemas.add(reqSchemaRef.name);
+      const media: Record<string, unknown> = {
+        schema: { $ref: `#/components/schemas/${reqSchemaRef.name}` },
+      };
+      if (route.meta?.example !== undefined) media.example = route.meta.example;
+      operation.requestBody = {
+        content: { [reqSchemaRef.contentType]: media },
+      };
+    } else if (method === "post" || method === "put") {
       const modelName = inferModelFromPath(route.pattern);
       if (modelName && models.some((m) => m.tableName === modelName)) {
         const media: Record<string, unknown> = {
@@ -151,11 +288,35 @@ export function generate(
       }
     }
 
-    // Security — a secured route emits operation.security + 401. Mirrors the
-    // router's enforcement (writes secure by default unless noAuth; GET secure
-    // only when marked). Before, no route ever got a security requirement.
-    if (routeRequiresAuth(route, method)) {
-      operation.security = [{ bearerAuth: [] }];
+    // Registered response schemas ($ref) — explicit and authoritative, keyed by status.
+    const respSchemas = parseResponseSchemas(route.meta?.responseSchemas);
+    if (respSchemas.length > 0) {
+      const responses = operation.responses as Record<string, unknown>;
+      for (const { status, name, isList } of respSchemas) {
+        refSchemas.add(name);
+        const sref = `#/components/schemas/${name}`;
+        const schema = isList ? { type: "array", items: { $ref: sref } } : { $ref: sref };
+        responses[status] = {
+          description: status.startsWith("2") ? "Successful response" : "Response",
+          content: { "application/json": { schema } },
+        };
+      }
+    }
+
+    // Security (v3.13.42) — explicit meta.security wins (empty list = explicitly
+    // public); otherwise a secured route gets the default scheme. Scopes are kept
+    // valid (only oauth2/openIdConnect carry them).
+    const hasExplicitSecurity =
+      route.meta?.security !== undefined || (route.meta?.scopes !== undefined && route.meta.scopes.length > 0);
+    if (hasExplicitSecurity) {
+      const normalized = normalizeSecurity(route.meta?.security, route.meta?.scopes);
+      operation.security = normalized.length > 0 ? sanitizeSecurity(normalized, schemes) : [];
+      if (normalized.length > 0) {
+        const responses = operation.responses as Record<string, unknown>;
+        if (!responses["401"]) responses["401"] = { description: "Unauthorized" };
+      }
+    } else if (routeRequiresAuth(route, method)) {
+      operation.security = sanitizeSecurity([{ [defaultScheme]: [] }], schemes);
       const responses = operation.responses as Record<string, unknown>;
       if (!responses["401"]) responses["401"] = { description: "Unauthorized" };
     }
@@ -163,6 +324,16 @@ export function generate(
     spec.paths[openApiPath][method] = operation;
   }
 
+  // Registered component schemas referenced via meta.requestSchema/responseSchemas.
+  if (refSchemas.size > 0) {
+    const schemas = spec.components!.schemas!;
+    for (const name of refSchemas) {
+      if (name in registeredSchemas && !(name in schemas)) {
+        schemas[name] = registeredSchemas[name];
+      }
+    }
+  }
+
   if (usedTags.length > 0) {
     spec.tags = usedTags.map((name) => ({ name }));
   }
@@ -176,6 +347,45 @@ function routeRequiresAuth(route: RouteDefinition, method: string): boolean {
   return route.secure === true;
 }
 
+/**
+ * Path-filter a raw route pattern. Framework internals (/swagger, /__dev) are
+ * ALWAYS excluded; then TINA4_SWAGGER_INCLUDE (allow-list) / _EXCLUDE apply.
+ * Mirrors Python's _included.
+ */
+function isIncludedPath(rawPath: string, include: string[], exclude: string[]): boolean {
+  for (const internal of ["/swagger", "/__dev"]) {
+    if (rawPath === internal || rawPath.startsWith(internal + "/")) return false;
+  }
+  if (include.length > 0 && !include.some((p) => rawPath === p || rawPath.startsWith(p))) {
+    return false;
+  }
+  if (exclude.some((p) => rawPath === p || rawPath.startsWith(p))) return false;
+  return true;
+}
+
+function parseRequestSchema(
+  spec: string | { name: string; contentType?: string } | undefined
+): { name: string; contentType: string } | null {
+  if (spec === undefined) return null;
+  if (typeof spec === "string") return { name: spec, contentType: "application/json" };
+  return { name: spec.name, contentType: spec.contentType ?? "application/json" };
+}
+
+function parseResponseSchemas(
+  spec: Record<string, string | { name: string; isList?: boolean }> | undefined
+): Array<{ status: string; name: string; isList: boolean }> {
+  if (!spec) return [];
+  const out: Array<{ status: string; name: string; isList: boolean }> = [];
+  for (const [status, value] of Object.entries(spec)) {
+    if (typeof value === "string") {
+      out.push({ status, name: value, isList: false });
+    } else {
+      out.push({ status, name: value.name, isList: value.isList === true });
+    }
+  }
+  return out;
+}
+
 function resolveServers(): { url: string }[] {
   const raw = (process.env.TINA4_SWAGGER_SERVERS ?? "").trim();
   const urls = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);

package/packages/swagger/src/index.ts

@@ -1,2 +1,2 @@
-export { generate } from "./generator.js";
+export { generate, addSecurityScheme, addSchema, resetRegistry } from "./generator.js";
 export { createSwaggerRoutes, swaggerEnabled } from "./ui.js";