tina4-nodejs 3.13.94 → 3.13.95

package/packages/core/src/middleware.ts

@@ -1,7 +1,10 @@
 import type { Tina4Request, Tina4Response, Middleware } from "./types.js";
+import { HTTP_OK, HTTP_FORBIDDEN } from "./constants.js";
 import { validToken, getPayload } from "./auth.js";
 import { Log } from "./logger.js";
 import { isTruthy } from "./dotenv.js";
+import { defaultRouter, type Router } from "./router.js";
+import { resolveClientIp } from "./trustedProxy.js";
 
 /**
  * Whether to emit a per-request log line (v3.13.14). TINA4_LOG_REQUESTS is
@@ -65,24 +68,86 @@ export class MiddlewareChain {
 }
 
 // ── Class-based middleware runner ────────────────────────────────
+//
+// Class-based middleware follows the beforeX / afterX naming convention:
+// statics named before* run before the route handler (MiddlewareRunner.runBefore),
+// statics named after* run once it is done (runAfter). Each hook receives
+// (req, res); what it RETURNS is interpreted by the one table in
+// interpretHookResult below.
+
+/**
+ * True when a middleware spec is a CLASS (the beforeX/afterX convention)
+ * rather than a plain `(req, res, next)` middleware function.
+ *
+ * A class's `prototype` property is non-writable by the language spec
+ * (ClassDefinitionEvaluation); an ordinary function's is writable, and an
+ * arrow function, async function or bound function has no `prototype` at all.
+ * That is a language-level distinction rather than a name or source-string
+ * sniff, so a class named `cors` and a function named `Cors` both classify
+ * correctly.
+ */
+export function isMiddlewareClass(spec: unknown): boolean {
+  if (typeof spec !== "function") return false;
+  const proto = Object.getOwnPropertyDescriptor(spec, "prototype");
+  return proto !== undefined && proto.writable === false;
+}
+
+/**
+ * The Tina4 response object — callable, and carrying the raw ServerResponse.
+ * Structural, so a rebound response is recognised too.
+ */
+function isResponse(value: unknown): value is Tina4Response {
+  return typeof value === "function"
+    && typeof (value as Tina4Response).raw?.end === "function";
+}
 
 /**
- * Runs class-based middleware that follows the beforeX / afterX naming convention.
+ * ONE return-value table, for EVERY beforeX/afterX hook, at EVERY scope
+ * (global and per-route):
  *
- * Static methods whose names start with "before" are executed by runBefore
- * (prior to the route handler). Static methods starting with "after" are
- * executed by runAfter (after the handler).
+ *   a Response object   SHORT-CIRCUIT. That object IS the response, at ANY
+ *                       status. This is the PRIMARY rule and the only return
+ *                       that can express a 302 redirect.
+ *   the [req, res] pair rebind both, continue (length >= 2, mirroring Python's
+ *                       `isinstance(result, tuple) and len(result) >= 2`)
+ *   false               SHORT-CIRCUIT. Send the response AS SET; a still
+ *                       default and still unwritten response becomes a 403,
+ *                       because a bare `return false` is a deny.
+ *   undefined / null    continue
  *
- * Each static method receives (req, res) and returns [req, res].
- * If a "before" method returns a response whose status code is >= 400
- * the chain short-circuits and runBefore returns shouldContinue = false.
+ * Returns [req, res, stop].
  */
+function interpretHookResult(
+  result: unknown,
+  req: Tina4Request,
+  res: Tina4Response,
+): [Tina4Request, Tina4Response, boolean] {
+  if (Array.isArray(result)) {
+    return result.length >= 2
+      ? [result[0] as Tina4Request, result[1] as Tina4Response, false]
+      : [req, res, false];
+  }
+  if (isResponse(result)) return [req, result, true];
+  if (result === false) {
+    if (!res.raw.writableEnded && res.raw.statusCode === HTTP_OK) {
+      res.raw.statusCode = HTTP_FORBIDDEN;
+    }
+    return [req, res, true];
+  }
+  return [req, res, false];
+}
+
 /**
  * Produce the deterministic clean 500 for a throwing class-based middleware
- * (M2). Mirrors Python's _middleware_500: LOG via Log.error (class + method +
- * error type + message — never silent) then return a 500 with the exact JSON
- * body shape shared across all four frameworks. The worker never crashes and
- * no unhandled exception leaks.
+ * (M2): LOG via Log.error (class + method + error type + message — never
+ * silent) then return a 500 with the exact JSON body shape shared across all
+ * four frameworks. The worker never crashes and no unhandled exception leaks.
+ *
+ * The counterpart is Python's `Middleware.middleware_500`
+ * (tina4_python/core/middleware.py), called from its own run_before/run_after.
+ * This used to cite `_middleware_500`, which is not a symbol in tina4-python at
+ * all — that name belonged to its dispatcher, back when its orchestrator had no
+ * exception handling to mirror.
  */
 function middleware500(
   res: Tina4Response,
@@ -126,6 +191,33 @@ export class MiddlewareRunner {
   }
 
   /** Return the list of globally registered middleware classes. */
+  /**
+   * Global middleware that runs BEFORE route matching.
+   *
+   * A middleware opts in with `static preMatch = true`. Everything else stays
+   * where it has always run - after matching - so this is additive and no
+   * existing middleware changes behaviour.
+   *
+   * The two groups need opposite things. CORS must run before matching so its
+   * headers survive a short-circuited 401/403; a browser shown a 401 without
+   * them reports a CORS error and the real status never reaches the developer.
+   * CSRF must run AFTER, because it reads the matched route's metadata to
+   * honour a route marked noAuth - PHP shipped exactly that bypass as dead
+   * code once, because the metadata was not assigned yet.
+   *
+   * NOT named `beforeMatch` - hook discovery treats every `before*` static as
+   * a middleware hook and would call the flag itself with (req, res).
+   */
+  static partitionByMatchPhase(all: any[]): { pre: any[]; post: any[] } {
+    const pre: any[] = [];
+    const post: any[] = [];
+    for (const m of all) {
+      if (m && m.preMatch === true) pre.push(m);
+      else post.push(m);
+    }
+    return { pre, post };
+  }
+
   static getGlobal(): any[] {
     return [...MiddlewareRunner.globalMiddleware];
   }
@@ -136,19 +228,59 @@ export class MiddlewareRunner {
   }
 
   /**
-   * Discover the before-prefixed / after-prefixed method names on a
-   * middleware class in DEFINITION order (M1).
-   * `Object.getOwnPropertyNames` returns a class's own
-   * static method names in source-declaration order — we deliberately do NOT
-   * sort() them, so within a class the hooks run in the order they were
-   * written (parity with Python walking __dict__, PHP get_class_methods, Ruby
+   * Discover the before-prefixed / after-prefixed hook names on a middleware
+   * class, INHERITED HOOKS INCLUDED, base class first (M1).
+   *
+   * `Object.getOwnPropertyNames` returns a class's OWN statics only, in
+   * source-declaration order. On its own that silently DROPPED every hook a
+   * subclass inherited: for `class Sub extends Base` with `static beforeBase`
+   * on the base, discovery returned only ["beforeSub"] even though
+   * `Sub.beforeBase` is a live function — so a shared base middleware simply
+   * never ran, with no error. Python returns ['before_base','before_sub'] and
+   * Ruby [:before_base,:before_sub]; Node was the only one of the four that
+   * lost hooks.
+   *
+   * So walk the prototype chain (the STATIC side: Sub -> Base -> ...) and emit
+   * base-class hooks BEFORE the subclass's own, de-duping an override to its
+   * first (base) position. That is exactly Python's `_discover_methods`
+   * walking `reversed(__mro__)` over each `__dict__`, and Ruby's
+   * `discover_methods` walking `ancestors.reverse_each`.
+   *
+   * Within one class the order is still source-declaration order — we
+   * deliberately do NOT sort(), so hooks run in the order they were written
+   * (parity with Python walking __dict__, PHP get_class_methods, Ruby
    * instance_methods(false)). Cross-class order is the natural iteration of
    * the registered classes = REGISTRATION order.
+   *
+   * The chain walk stops at Function.prototype / Object.prototype, so the
+   * built-in members are never scanned. A plain object registered as
+   * middleware still works: its own keys are level 0.
    */
   private static methodNames(cls: any, prefix: string): string[] {
-    return Object.getOwnPropertyNames(cls).filter(
-      (name) => typeof cls[name] === "function" && name.startsWith(prefix),
-    );
+    const levels: string[][] = [];
+    for (
+      let level: any = cls;
+      level && level !== Function.prototype && level !== Object.prototype;
+      level = Object.getPrototypeOf(level)
+    ) {
+      levels.push(
+        Object.getOwnPropertyNames(level).filter(
+          (name) => name.startsWith(prefix) && typeof cls[name] === "function",
+        ),
+      );
+    }
+
+    const seen = new Set<string>();
+    const names: string[] = [];
+    // Reverse the levels: base class first, then each derived class.
+    for (let i = levels.length - 1; i >= 0; i--) {
+      for (const name of levels[i]) {
+        if (seen.has(name)) continue;
+        seen.add(name);
+        names.push(name);
+      }
+    }
+    return names;
   }
 
   /**
@@ -172,6 +304,10 @@ export class MiddlewareRunner {
    * a synchronous hook that returns an array is harmless (the array resolves
    * immediately), so existing sync hooks keep working unchanged.
    *
+   * RETURN VALUE — see `interpretHookResult` for the one table every hook at
+   * every scope obeys. A returned Response object is the PRIMARY
+   * short-circuit; `false` is a deny.
+   *
    * Returns [req, res, shouldContinue].
    */
   static async runBefore(
@@ -182,16 +318,22 @@ export class MiddlewareRunner {
     for (const cls of classes) {
       for (const method of MiddlewareRunner.methodNames(cls, "before")) {
         try {
-          const result = await cls[method](req, res);
-          if (Array.isArray(result)) {
-            [req, res] = result as [Tina4Request, Tina4Response];
-          }
+          const [nextReq, nextRes, stop] =
+            interpretHookResult(await cls[method](req, res), req, res);
+          req = nextReq;
+          res = nextRes;
+          if (stop) return [req, res, false];
         } catch (error) {
           // Throw → logged clean 500, skip the handler (deterministic).
           res = middleware500(res, cls, method, error);
           return [req, res, false];
         }
-        // Short-circuit if the middleware set an error status
+        // LEGACY COMPAT PATH — retained, but NOT the main mechanism. A hook
+        // that returns nothing and merely leaves an error status (or an ended
+        // response) still short-circuits, so middleware written before the
+        // return-value contract keeps working. It cannot express a 3xx
+        // redirect, which is exactly why a returned Response is the primary
+        // rule above.
         if (res.raw.statusCode >= 400 || res.raw.writableEnded) {
           return [req, res, false];
         }
@@ -218,6 +360,12 @@ export class MiddlewareRunner {
    * ASYNC — each hook is awaited (e.g. the responseCache after-hook awaiting
    * `backend.set`). Awaiting a synchronous hook is harmless, so existing sync
    * after-hooks keep working unchanged.
+   *
+   * RETURN VALUE — the SAME table as runBefore (`interpretHookResult`): the
+   * contract is one table for every hook at every scope. There is nothing left
+   * to skip after the handler, so a short-circuit here ends the after chain.
+   * A THROW is different and unchanged: it is logged, becomes a clean 500, and
+   * the remaining after hooks still run.
    */
   static async runAfter(
     classes: any[],
@@ -227,10 +375,11 @@ export class MiddlewareRunner {
     for (const cls of classes) {
       for (const method of MiddlewareRunner.methodNames(cls, "after")) {
         try {
-          const result = await cls[method](req, res);
-          if (Array.isArray(result)) {
-            [req, res] = result as [Tina4Request, Tina4Response];
-          }
+          const [nextReq, nextRes, stop] =
+            interpretHookResult(await cls[method](req, res), req, res);
+          req = nextReq;
+          res = nextRes;
+          if (stop) return [req, res];
         } catch (error) {
           // Throw → logged clean 500, but remaining after* STILL run.
           res = middleware500(res, cls, method, error);
@@ -246,7 +395,7 @@ export class MiddlewareRunner {
 
 /** Configuration for the CORS middleware */
 export interface CorsConfig {
-  /** Allowed origins. Default: "*" (or TINA4_CORS_ORIGINS env, comma-separated) */
+  /** Allowed origins. Default: NONE (deny) — or TINA4_CORS_ORIGINS env, comma-separated. "*" allows any. */
   origins?: string | string[];
   /** Allowed methods. Default: standard REST methods (or TINA4_CORS_METHODS env) */
   methods?: string | string[];
@@ -254,71 +403,218 @@ export interface CorsConfig {
   headers?: string | string[];
   /** Access-Control-Max-Age in seconds. Default: 86400 (or TINA4_CORS_MAX_AGE env) */
   maxAge?: number;
+  /** Send Access-Control-Allow-Credentials. Default: false (or TINA4_CORS_CREDENTIALS env). Never sent with a wildcard origin. */
+  credentials?: boolean;
+}
+
+/** Warn-once ledger so a scripted probe cannot flood the log. */
+const corsWarned = new Set<string>();
+
+/** Reset the CORS warn-once ledger. Test seam. */
+export function resetCorsWarnings(): void {
+  corsWarned.clear();
+}
+
+function corsWarnOnce(key: string, message: string): void {
+  if (corsWarned.has(key)) return;
+  corsWarned.add(key);
+  Log.warning(message);
+}
+
+/**
+ * The resolved CORS policy — ONE implementation of the rules.
+ *
+ * Both the function middleware `cors()` and the class middleware
+ * `CorsMiddleware` build one of these and apply what it returns. They used to
+ * be two independent implementations that had already drifted: `cors()` never
+ * read TINA4_CORS_CREDENTIALS at all, so the DEFAULT always-on pipeline
+ * silently ignored a documented env var (measured 2026-07-31). One feature,
+ * one code path.
+ *
+ * DENY BY DEFAULT (ADR-0018). With no origins configured, NO
+ * Access-Control-Allow-Origin is emitted and the browser's own CORS check
+ * blocks the cross-origin request. "*" still works, it just has to be asked for.
+ *
+ * CREDENTIALS AND THE WILDCARD ARE MUTUALLY EXCLUSIVE. The Fetch Standard's
+ * CORS check treats "*" as a literal (not a wildcard) once the request's
+ * credentials mode is "include", so ACAO: * with
+ * Access-Control-Allow-Credentials: true is rejected by every browser.
+ *
+ * VARY: ORIGIN whenever the ACAO value is COMPUTED from the request's Origin,
+ * i.e. whenever an allow-list is configured — on a MISS as well as a match.
+ * RFC 9110 s12.5.5: a Vary field name list tells cache recipients they "MUST
+ * NOT use this response to satisfy a later request unless the later request
+ * has the same values for the listed header fields as the original request".
+ * The miss case matters most: without it a shared cache can store the no-ACAO
+ * response for origin B and serve it to origin A. A constant "*" genuinely
+ * does not vary and gets no Vary, which would only fragment a CDN's cache.
+ *
+ * Access-Control-Allow-Methods / -Allow-Headers are static configured lists
+ * here, never derived from the request's Access-Control-Request-* headers, so
+ * those field names do NOT belong in Vary.
+ */
+export class CorsPolicy {
+  readonly allowedOrigins: string[];
+  readonly allowedMethods: string;
+  readonly allowedHeaders: string;
+  readonly maxAge: number;
+  readonly credentials: boolean;
+
+  constructor(config?: CorsConfig) {
+    // Default is EMPTY, not "*" — deny by default (ADR-0018).
+    const originsRaw = config?.origins ?? process.env.TINA4_CORS_ORIGINS ?? "";
+    const list = Array.isArray(originsRaw) ? originsRaw : originsRaw.split(",");
+    this.allowedOrigins = list.map((o) => o.trim()).filter((o) => o !== "");
+
+    const methodsRaw = config?.methods
+      ?? process.env.TINA4_CORS_METHODS
+      ?? "GET, POST, PUT, DELETE, PATCH, OPTIONS";
+    this.allowedMethods = Array.isArray(methodsRaw) ? methodsRaw.join(", ") : methodsRaw;
+
+    const headersRaw = config?.headers
+      ?? process.env.TINA4_CORS_HEADERS
+      ?? "Content-Type,Authorization,X-Request-ID";
+    this.allowedHeaders = Array.isArray(headersRaw) ? headersRaw.join(", ") : headersRaw;
+
+    this.maxAge = config?.maxAge
+      ?? (process.env.TINA4_CORS_MAX_AGE ? parseInt(process.env.TINA4_CORS_MAX_AGE, 10) : 86400);
+
+    this.credentials = config?.credentials
+      ?? ["true", "1", "yes"].includes((process.env.TINA4_CORS_CREDENTIALS ?? "false").toLowerCase());
+  }
+
+  /** Whether an operator has actually declared a CORS policy. */
+  isConfigured(): boolean {
+    return this.allowedOrigins.length > 0;
+  }
+
+  /** The origin to send in Access-Control-Allow-Origin, or undefined for none. */
+  resolveOrigin(requestOrigin: string): string | undefined {
+    if (this.allowedOrigins.length === 0) return undefined;
+    if (this.allowedOrigins.includes("*")) return "*";
+    if (requestOrigin && this.allowedOrigins.includes(requestOrigin)) return requestOrigin;
+    return undefined;
+  }
+
+  /**
+   * The CORS headers for a request origin. `isPreflight` adds Max-Age, which
+   * the Fetch Standard only defines for a preflight response.
+   */
+  headersFor(requestOrigin: string, isPreflight: boolean): Record<string, string> {
+    if (this.allowedOrigins.length === 0) {
+      if (requestOrigin) {
+        corsWarnOnce("unconfigured",
+          `CORS: refused cross-origin request from ${requestOrigin} — no policy is configured. `
+          + "Set TINA4_CORS_ORIGINS to the origins you want to allow, e.g. "
+          + "TINA4_CORS_ORIGINS=https://app.example.com (or '*' to allow any origin).");
+      }
+      return {};
+    }
+
+    const out: Record<string, string> = {};
+    if (!this.allowedOrigins.includes("*")) {
+      out["Vary"] = "Origin";
+    }
+
+    const origin = this.resolveOrigin(requestOrigin);
+    if (origin === undefined) {
+      if (requestOrigin) {
+        corsWarnOnce(`denied:${requestOrigin}`,
+          `CORS: origin ${requestOrigin} is not in TINA4_CORS_ORIGINS `
+          + `(${this.allowedOrigins.join(",")}) — the browser will block this response.`);
+      }
+      return out;
+    }
+
+    out["Access-Control-Allow-Origin"] = origin;
+    out["Access-Control-Allow-Methods"] = this.allowedMethods;
+    out["Access-Control-Allow-Headers"] = this.allowedHeaders;
+    if (isPreflight) out["Access-Control-Max-Age"] = String(this.maxAge);
+
+    if (this.credentials) {
+      if (origin === "*") {
+        corsWarnOnce("wildcard-credentials",
+          "CORS: TINA4_CORS_CREDENTIALS is true but TINA4_CORS_ORIGINS is '*'. The Fetch Standard "
+          + "forbids Access-Control-Allow-Origin: * with credentials, so credentials are NOT being "
+          + "sent. Credentialed CORS requires an explicit origin list, e.g. "
+          + "TINA4_CORS_ORIGINS=https://app.example.com.");
+      } else {
+        out["Access-Control-Allow-Credentials"] = "true";
+      }
+    }
+    return out;
+  }
+}
+
+/** Fold a Vary field name into whatever Vary the response already carries. */
+function applyCorsHeaders(res: Tina4Response, headers: Record<string, string>): void {
+  for (const [name, value] of Object.entries(headers)) {
+    if (name === "Vary") {
+      const current = String((res as { raw?: { getHeader?(n: string): unknown } }).raw?.getHeader?.("Vary") ?? "");
+      const parts = current.split(",").map((p) => p.trim()).filter((p) => p !== "");
+      if (!parts.some((p) => p.toLowerCase() === value.toLowerCase())) parts.push(value);
+      res.header(name, parts.join(", "));
+      continue;
+    }
+    res.header(name, value);
+  }
+}
+
+/**
+ * Is this a REAL CORS preflight (as opposed to a bare protocol-introspection
+ * OPTIONS)? A preflight carries an Origin — browsers always send one. A bare
+ * OPTIONS does not, and belongs to the RFC 9110 s9.3.7 handler in dispatch.
+ */
+function isCorsPreflight(method: string | undefined, requestOrigin: string): boolean {
+  return method === "OPTIONS" && requestOrigin !== "";
+}
+
+/** The Allow header for a path, from the LIVE router. */
+function allowHeaderForUrl(url: string | undefined): string {
+  const pathname = new URL(url ?? "/", "http://localhost").pathname;
+  // startServer builds its own Router and publishes it on globalThis;
+  // defaultRouter is the module-level instance used by the standalone
+  // get()/post() helpers. A file-routed app registers nothing in the latter,
+  // so reading it alone returned an empty method set and stamped Allow: "".
+  const liveRouter = (globalThis as { __tina4_router?: Router }).__tina4_router ?? defaultRouter;
+  return liveRouter.methodsAllowedForPath(pathname).join(", ");
 }
 
 /**
  * Built-in CORS middleware (function form).
- * Reads configuration from env vars if not provided:
+ *
+ * A thin adapter over CorsPolicy — see that class for the rules and the
+ * standards behind them. Reads configuration from env vars when not provided:
  *   TINA4_CORS_ORIGINS — comma-separated list of allowed origins, or "*"
  *   TINA4_CORS_METHODS — comma-separated list of allowed methods
  *   TINA4_CORS_HEADERS — comma-separated list of allowed headers
  *   TINA4_CORS_MAX_AGE — preflight cache duration in seconds
+ *   TINA4_CORS_CREDENTIALS — send Access-Control-Allow-Credentials
  *
- * Preflight (OPTIONS) returns 204 with appropriate headers.
- * Supports wildcard ("*") and specific origin matching.
+ * A real preflight is answered 204. The status is the same whether the origin
+ * was allowed or denied — the browser does the blocking.
  */
 export function cors(config?: CorsConfig): Middleware {
-  const originsRaw = config?.origins
-    ?? process.env.TINA4_CORS_ORIGINS
-    ?? "*";
-  const allowedOrigins = Array.isArray(originsRaw)
-    ? originsRaw
-    : originsRaw.split(",").map((o) => o.trim());
-
-  const methodsRaw = config?.methods
-    ?? process.env.TINA4_CORS_METHODS
-    ?? "GET, POST, PUT, DELETE, PATCH, OPTIONS";
-  const allowedMethods = Array.isArray(methodsRaw)
-    ? methodsRaw.join(", ")
-    : methodsRaw;
-
-  const headersRaw = config?.headers
-    ?? process.env.TINA4_CORS_HEADERS
-    ?? "Content-Type,Authorization,X-Request-ID";
-  const allowedHeaders = Array.isArray(headersRaw)
-    ? headersRaw.join(", ")
-    : headersRaw;
-
-  const maxAge = config?.maxAge
-    ?? (process.env.TINA4_CORS_MAX_AGE ? parseInt(process.env.TINA4_CORS_MAX_AGE, 10) : 86400);
+  const policy = new CorsPolicy(config);
 
   return (req, res, next) => {
     const requestOrigin = req.headers.origin ?? "";
-
-    // Determine the correct origin header value
-    let originHeader: string;
-    if (allowedOrigins.includes("*")) {
-      originHeader = "*";
-    } else if (allowedOrigins.includes(requestOrigin)) {
-      originHeader = requestOrigin;
-      // When responding with a specific origin, add Vary: Origin
-      res.header("Vary", "Origin");
-    } else {
-      // Origin not allowed — still call next() but don't set CORS headers
-      if (req.method === "OPTIONS") {
-        res(null, 204);
-        return;
-      }
-      next();
-      return;
-    }
-
-    res.header("Access-Control-Allow-Origin", originHeader);
-    res.header("Access-Control-Allow-Methods", allowedMethods);
-    res.header("Access-Control-Allow-Headers", allowedHeaders);
-
-    if (req.method === "OPTIONS") {
-      res.header("Access-Control-Max-Age", String(maxAge));
+    const preflight = isCorsPreflight(req.method, requestOrigin);
+
+    applyCorsHeaders(res as Tina4Response, policy.headersFor(requestOrigin, preflight));
+
+    if (preflight) {
+      // Carry the resource's REAL method set as Allow (RFC 9110 s9.3.7): a
+      // preflight IS an OPTIONS response, so it answers the same question a
+      // bare OPTIONS does, on top of the CORS policy headers. This is
+      // CONFORMANCE, not a deviation — Django's View.options() and Express's
+      // router already emit Allow; the add-on CORS libraries lose it only
+      // because they short-circuit ahead of the framework. See ADR-0013.
+      //
+      // Allow and Access-Control-Allow-Methods are NOT interchangeable: Allow
+      // is what the resource supports, ACAM is what the CORS policy permits
+      // cross-origin. A policy allowing DELETE on a GET-only route still 405s.
+      res.header("Allow", allowHeaderForUrl(req.url));
       res(null, 204);
       return;
     }
@@ -329,53 +625,21 @@ export function cors(config?: CorsConfig): Middleware {
 
 /**
  * Class-based CORS middleware using the before/after convention.
- * Wraps the same CORS logic as the `cors()` function middleware.
+ *
+ * The same CorsPolicy as `cors()` — one implementation, one set of semantics.
  *
  * Usage:
  *   Router.use(CorsMiddleware);
  */
 export class CorsMiddleware {
   static beforeCors(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response] {
-    const originsRaw = process.env.TINA4_CORS_ORIGINS ?? "*";
-    const allowedOrigins = originsRaw.split(",").map((o) => o.trim());
-
-    const allowedMethods = process.env.TINA4_CORS_METHODS
-      ?? "GET, POST, PUT, DELETE, PATCH, OPTIONS";
-
-    const allowedHeaders = process.env.TINA4_CORS_HEADERS
-      ?? "Content-Type,Authorization,X-Request-ID";
-
-    const credentials = process.env.TINA4_CORS_CREDENTIALS ?? "false";
-
-    const maxAge = process.env.TINA4_CORS_MAX_AGE
-      ? parseInt(process.env.TINA4_CORS_MAX_AGE, 10)
-      : 86400;
-
     const requestOrigin = req.headers.origin ?? "";
+    const preflight = isCorsPreflight(req.method, requestOrigin);
 
-    let originHeader: string | undefined;
-    if (allowedOrigins.includes("*")) {
-      originHeader = "*";
-    } else if (allowedOrigins.includes(requestOrigin)) {
-      originHeader = requestOrigin;
-      res.header("Vary", "Origin");
-    }
-
-    if (originHeader) {
-      res.header("Access-Control-Allow-Origin", originHeader);
-      res.header("Access-Control-Allow-Methods", allowedMethods);
-      res.header("Access-Control-Allow-Headers", allowedHeaders);
-
-      // Add credentials header when enabled and origin is not wildcard
-      if (credentials === "true" && originHeader !== "*") {
-        res.header("Access-Control-Allow-Credentials", "true");
-      }
+    applyCorsHeaders(res, new CorsPolicy().headersFor(requestOrigin, preflight));
 
-      if (req.method === "OPTIONS") {
-        res.header("Access-Control-Max-Age", String(maxAge));
-        res(null, 204);
-      }
-    } else if (req.method === "OPTIONS") {
+    if (preflight) {
+      res.header("Allow", allowHeaderForUrl(req.url));
       res(null, 204);
     }
 
@@ -384,6 +648,10 @@ export class CorsMiddleware {
 
   /**
    * Check if a request is an OPTIONS preflight.
+   *
+   * NOTE: returns true for ANY OPTIONS, with no Origin check, so the name
+   * overstates what it tests. The real short-circuit uses isCorsPreflight().
+   * Kept because existing tests pin this meaning.
    */
   static isPreflight(method: string): boolean {
     return method?.toUpperCase() === "OPTIONS";
@@ -436,10 +704,9 @@ export class RateLimiterMiddleware {
     const now = Date.now();
     const cutoff = now - windowMs;
 
-    const forwarded = req.headers["x-forwarded-for"];
-    const ip = (typeof forwarded === "string" ? forwarded.split(",")[0].trim() : undefined)
-      ?? req.socket?.remoteAddress
-      ?? "unknown";
+    // Client key. X-Forwarded-For is honoured ONLY when the socket peer is a
+    // declared trusted proxy (TINA4_TRUSTED_PROXIES). ADR-0019.
+    const ip = resolveClientIp(req.headers, req.socket?.remoteAddress ?? "") || "unknown";
 
     let entry = RateLimiterMiddleware.store.get(ip);
     if (!entry) {