tina4-nodejs 3.13.41 → 3.13.42

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.42)
 
 > 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.42",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",

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";