@tulipes/cli 0.1.1 → 0.2.0-rc.1

package/templates/app/modules/hello/controllers/greetings.controllers.ts

@@ -0,0 +1,43 @@
+import type { Request, RequestHandler, Response } from "express";
+import { requireModels, requireQueues, type Ctx } from "@tulipes/core/boot";
+import { HttpError } from "@tulipes/core/http";
+
+export class GreetingsController {
+  readonly #ctx: Ctx;
+
+  constructor(ctx: Ctx) {
+    this.#ctx = ctx;
+  }
+
+  list(): RequestHandler {
+    return async (req: Request, res: Response) => {
+      // ?page and ?per_page, already clamped by config.pagination — so
+      // every list endpoint in every module paginates the same way.
+      const { per_page, skip } = req.page;
+      const Greeting = requireModels(this.#ctx).get("Greeting");
+
+      const [greetings, total_items] = await Promise.all([
+        Greeting.find().select("name message times_used -_id")
+          .skip(skip).limit(per_page).lean(),
+        Greeting.countDocuments(),
+      ]);
+
+      // Passing total_items is what marks this a page: respond fills in
+      // page, per_page and total_pages from the request and the count.
+      res.respond({ data: greetings, meta: { total_items } });
+    };
+  }
+
+  use(): RequestHandler {
+    return async (req: Request, res: Response) => {
+      const name = String(req.params.name);
+      const greeting = await requireModels(this.#ctx).get("Greeting").findOne({ name }).lean();
+      if (!greeting) throw new HttpError(404, "noSuchGreeting", { vars: { name } });
+
+      // Slow or retryable work belongs in a job, not in the request. Run
+      // `pnpm worker` in another terminal to see it processed.
+      await requireQueues(this.#ctx).add("hello.count-greeting", "count", { name });
+      res.respond({ status: 202, data: { name, queued: true } });
+    };
+  }
+}

package/templates/app/modules/hello/controllers/hello.controllers.ts

@@ -0,0 +1,50 @@
+import type { Request, RequestHandler, Response } from "express";
+import type { Ctx } from "@tulipes/core/boot";
+
+import { buildGreeting } from "../helpers/greeting.ts";
+
+/**
+ * Controllers hold the work so routes stay a table of contents. The
+ * framework does not scan this folder — routes import the class directly,
+ * which keeps the wiring explicit.
+ *
+ * Taking ctx in the constructor is what makes it testable: construct one
+ * with a stub context and call the method.
+ */
+export class HelloController {
+  readonly #ctx: Ctx;
+
+  constructor(ctx: Ctx) {
+    this.#ctx = ctx;
+  }
+
+  greet(): RequestHandler {
+    return (req: Request, res: Response): void => {
+      const name = String(req.query.name ?? "world");
+      // Every response goes through res.respond, which wraps the payload
+      // in the app's envelope: { success, data, errors, meta }.
+      res.respond({
+        data: {
+          message: buildGreeting(String(this.#ctx.config.hello?.greeting), name),
+          app: this.#ctx.config.app?.name,
+        },
+      });
+    };
+  }
+
+  secret(): RequestHandler {
+    return (req: Request, res: Response): void => {
+      // req.t is bound to this module's namespace by rai(), so the key
+      // resolves in modules/hello/i18n/<locale>.json. Try ?lang=fr.
+      res.respond({ data: { secret: req.t("secret"), locale: req.locale } });
+    };
+  }
+
+  byName(): RequestHandler {
+    return (req: Request, res: Response): void => {
+      res.respond({
+        data: { message: `${this.#ctx.config.hello?.greeting}, ${req.params.name}!` },
+      });
+    };
+  }
+}

package/templates/app/modules/hello/helpers/greeting.ts

@@ -0,0 +1,8 @@
+/**
+ * Pure logic: no Express, no database, no framework. Trivial to unit
+ * test, and the framework never scans this folder — helpers are plain
+ * imports. Anything two modules need moves up to lib/.
+ */
+export function buildGreeting(greeting: string, name: string): string {
+  return `${greeting}, ${name}!`;
+}

package/templates/app/modules/hello/i18n/en.json

@@ -0,0 +1,8 @@
+{
+  "secret": "Only roles granted hello:read see this",
+  "noSuchGreeting": "No greeting named \"{{name}}\"",
+  "list": {
+    "count_one": "{{count}} greeting",
+    "count_other": "{{count}} greetings"
+  }
+}

package/templates/app/modules/hello/i18n/fr.json

@@ -0,0 +1,8 @@
+{
+  "secret": "Seuls les rôles disposant de hello:read voient ceci",
+  "noSuchGreeting": "Aucune salutation nommée « {{name}} »",
+  "list": {
+    "count_one": "{{count}} salutation",
+    "count_other": "{{count}} salutations"
+  }
+}

package/templates/app/modules/hello/models/greeting.model.ts

@@ -0,0 +1,24 @@
+import { Schema } from "mongoose";
+import type { ModelDef } from "@tulipes/mongoose";
+
+// Cross-module import by package name, never a relative path out
+// of the module — the dependency is declared in package.json.
+import { baseSchemaOptions } from "@app/core";
+
+/**
+ * A model file is a DECLARATION, never a registration: the framework
+ * compiles the schema on its own connection and puts it in the model
+ * store. Never call mongoose.model() yourself.
+ *
+ * Read it anywhere the context reaches: models!.get("Greeting").
+ */
+const greetingSchema = new Schema(
+  {
+    name: { type: String, required: true, unique: true, lowercase: true, trim: true },
+    message: { type: String, required: true },
+    times_used: { type: Number, default: 0, min: 0 },
+  },
+  baseSchemaOptions,
+);
+
+export default { name: "Greeting", schema: greetingSchema } satisfies ModelDef;

package/templates/app/modules/hello/module.acl.ts

@@ -0,0 +1,16 @@
+import type { AclBuilder } from "@tulipes/core/acl";
+
+/**
+ * Roles are global and defined once by the sys core module; a feature
+ * module only attaches grants, and always on resources namespaced by
+ * its own name ("hello:*"). Granting the same role+resource from two
+ * modules crashes the boot.
+ */
+export default function helloAcl(acl: AclBuilder): void {
+  // Public: the greeting endpoints are granted to guest, which is
+  // how an endpoint is made public — there is no "skip auth" flag.
+  acl.allow("guest", "hello:greet", "hello:greet-name", "hello:demo-missing");
+
+  // Signed in: the secret needs a real role.
+  acl.allow("user", "hello:read", "hello:list-greetings", "hello:use-greeting");
+}

package/templates/app/modules/hello/module.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "@tulipes/core/config";
+import { z } from "zod/v4";
+
+/**
+ * Whatever this declares is stored at `config.hello`, edited through the
+ * console, typed by `pnpm sync`, and read live by every other module — a
+ * change lands without a restart.
+ */
+export default defineConfig({
+  schema: z.object({
+    greeting: z.string().min(1).default("Hello")
+      .describe("Word this module greets callers with"),
+  }),
+});

package/templates/app/modules/hello/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@app/hello",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "tulipes": {
+    "tier": "app",
+    "priority": 100,
+    "dependsOn": [
+      "auth",
+      "core"
+    ]
+  },
+  "dependencies": {
+    "@app/auth": "workspace:*",
+    "@app/core": "workspace:*",
+    "@tulipes/bullmq": "workspace:*",
+    "@tulipes/core": "workspace:*",
+    "@tulipes/mongoose": "workspace:*",
+    "@tulipes/socket.io": "workspace:*",
+    "express": "^5",
+    "mongoose": "^8"
+  }
+}

package/templates/app/modules/hello/queues/hello.queues.ts

@@ -0,0 +1,38 @@
+import type { Ctx } from "@tulipes/core/boot";
+import type { JobSchemas, QueueRegistry } from "@tulipes/bullmq";
+import { z } from "zod/v4";
+
+import { moduleLogger } from "@app/core";
+
+/**
+ * The job data each queue accepts. This export is the declaration: it
+ * defines the queue, validates every `queues.add()` payload, and
+ * `pnpm sync` types `job.data` here and the payload at the producer from
+ * it — a wrong queue name or shape no longer compiles.
+ */
+export const jobs = {
+  "hello.count-greeting": z.object({ name: z.string().min(1) }),
+} satisfies JobSchemas;
+
+/**
+ * ONE file describes both sides. The backend process registers the queue
+ * so routes can produce into it; `pnpm worker` turns the processor
+ * into a live consumer. Never duplicate the definition.
+ *
+ * Queue names use "." — BullMQ reserves ":" as its redis separator.
+ */
+export default function helloQueues(ctx: Ctx, queues: QueueRegistry): void {
+  const { models } = ctx;
+  // The same logger the backend uses. In the worker process it writes
+  // to app-worker.log, so the two processes never share a file.
+  const log = moduleLogger(ctx.Environment, "hello", ctx.mode);
+
+  queues.process("hello.count-greeting", async (job) => {
+    // Jobs retry, so processors must be idempotent-safe. Pass ids in
+    // job.data and re-read state here rather than shipping documents.
+    const { name } = job.data;
+    await models!.get("Greeting").updateOne({ name }, { $inc: { times_used: 1 } });
+    log.info({ name }, "counted greeting");
+    return { counted: name };
+  });
+}

package/templates/app/modules/hello/routes/greetings.routes.ts

@@ -0,0 +1,25 @@
+import { Router } from "express";
+import type { BackendCtx } from "@tulipes/core/boot";
+
+import { GreetingsController } from "../controllers/greetings.controllers.ts";
+
+export default function greetingsRoutes(ctx: BackendCtx): Router {
+  const { rai } = ctx;
+  const router = Router();
+  const greetings = new GreetingsController(ctx);
+
+  router.get("/greetings", rai({
+      id: "hello:list-greetings",
+      name: "List greetings",
+      description: "Reads the seeded rows, clamped by the shared bounds",
+    }), greetings.list());
+
+  router.post("/greetings/:name/use", rai({
+      id: "hello:use-greeting",
+      status: 202,
+      name: "Use a greeting",
+      description: "Queues a job that counts the use",
+    }), greetings.use());
+
+  return router;
+}

package/templates/app/modules/hello/routes/hello.routes.ts

@@ -0,0 +1,44 @@
+import { Router } from "express";
+import type { BackendCtx } from "@tulipes/core/boot";
+import { HttpError } from "@tulipes/core/http";
+
+import { HelloController } from "../controllers/hello.controllers.ts";
+
+/**
+ * A routes file is a plain function of the context. It returns a Router,
+ * which core mounts under `config.api.prefix`, and declares a RAI on every
+ * endpoint: the id is the permission, and a route without one refuses the
+ * boot. Build the router from the context; read models, settings and the
+ * environment inside handlers, where they are live.
+ */
+export default function helloRoutes(ctx: BackendCtx): Router {
+  const { rai } = ctx;
+  const router = Router();
+  const hello = new HelloController(ctx);
+
+  router.get("/hello", rai({
+      id: "hello:greet",
+      name: "Greet",
+      description: "Public greeting, granted to guest",
+    }), hello.greet());
+
+  router.get("/hello/secret", rai({
+      id: "hello:read",
+      name: "Read the secret",
+      description: "Requires a role granted hello:read",
+    }), hello.secret());
+
+  router.get("/hello/:name", rai({
+      id: "hello:greet-name",
+      name: "Greet by name",
+    }), hello.byName());
+
+  router.get("/hello/demo/missing", rai({
+      id: "hello:demo-missing",
+      name: "HttpError demo",
+    }), async () => {
+      throw new HttpError(404, "nothing here", { details: { hint: "demo endpoint" } });
+    });
+
+  return router;
+}

package/templates/app/modules/hello/sockets/hello.sockets.ts

@@ -0,0 +1,21 @@
+import type { Ctx } from "@tulipes/core/boot";
+import type { SocketRegistry } from "@tulipes/socket.io";
+
+/**
+ * Backend mode only. A namespace is claimed by exactly one module; emit
+ * from anywhere with `ctx.sockets!.of("/hello")`.
+ *
+ * Try it: wscat -c ws://localhost:3000/hello
+ */
+export default function helloSockets({ config }: Ctx, sockets: SocketRegistry): void {
+  sockets.namespace("/hello", (nsp) => {
+    nsp.on("connection", (socket) => {
+      socket.emit("greeting", {
+        message: config.hello?.greeting,
+        online: nsp.sockets.size,
+      });
+
+      socket.on("ping", (ack: (reply: string) => void) => ack("pong"));
+    });
+  });
+}

package/templates/app/modules/hello/tests/hello.test.ts

@@ -0,0 +1,19 @@
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { z } from "zod/v4";
+import { afterAll, beforeAll, expect, test, vi } from "vitest";
+import { boot } from "@tulipes/core/boot";
+import { useTestApp } from "@tulipes/testing";
+
+import { testEnv, testSettings } from "../../../tests/support.ts";
+
+const rootDir = fileURLToPath(new URL("../../../", import.meta.url));
+const app = useTestApp({ rootDir, env: testEnv(), settings: testSettings() }, { beforeAll, afterAll });
+
+
+test("hello responds through the declared public endpoint", async () => {
+  const response = await fetch(app.base + "/api/v1/hello");
+
+  expect(response.status).toBe(200);
+  expect(await response.json()).toMatchObject({ success: true, errors: [] });
+});

package/templates/app/modules/security/bootstrap/rate-limit.bootstrap.ts

@@ -0,0 +1,8 @@
+import type { BootstrapCleanup, RuntimeCtx } from "@tulipes/core/boot";
+
+import { closeRateLimits } from "../helpers/rate-limit.ts";
+
+/** The rate limiters open their Redis client on first use; this returns the close. */
+export default function rateLimits(ctx: RuntimeCtx): BootstrapCleanup {
+  return () => closeRateLimits(ctx);
+}

package/templates/app/modules/security/helpers/hardening.ts

@@ -0,0 +1,65 @@
+import type { CorsOptions } from "cors";
+import type { HelmetOptions } from "helmet";
+
+/** The settings the hardening middleware is built from — `ctx.config.security`. */
+export interface HardeningSettings {
+  hstsMaxAge: number;
+  corsOrigins: string;
+  corsCredentials: boolean;
+}
+
+/**
+ * Helmet tuned for an API rather than a web page. Defaults assume a site
+ * that serves HTML and its own assets; this one serves JSON and nothing
+ * else, so the policy can be far stricter.
+ */
+export function helmetOptions(settings: Pick<HardeningSettings, "hstsMaxAge">): HelmetOptions {
+  const maxAge = settings.hstsMaxAge;
+
+  return {
+    // An API serves no active content: deny every resource type outright,
+    // which defuses any HTML-ish response a bug might produce.
+    contentSecurityPolicy: {
+      useDefaults: false,
+      directives: { "default-src": ["'none'"], "frame-ancestors": ["'none'"] },
+    },
+    // Browsers only honour HSTS over HTTPS, so it is inert in local dev —
+    // but a max-age of 0 lets a deployment switch it off deliberately.
+    hsts: maxAge > 0 ? { maxAge, includeSubDomains: true } : false,
+    // Helmet defaults to SAMEORIGIN; an API is never framed at all.
+    frameguard: { action: "deny" },
+    // Irrelevant without a browsing context, and it costs a header.
+    originAgentCluster: false,
+    crossOriginEmbedderPolicy: false,
+  };
+}
+
+/**
+ * CORS controls which browser origins can read responses. An empty list
+ * grants no cross-origin access; it does not reject incoming HTTP requests.
+ * Authentication and any future cookie/CSRF checks remain separate controls.
+ */
+export function corsOptions(settings: Pick<HardeningSettings, "corsOrigins" | "corsCredentials">): CorsOptions {
+  const raw = settings.corsOrigins.trim();
+  // This controls Access-Control-Allow-Credentials, not token extraction.
+  // Explicit Bearer headers do not require cookie authentication to be enabled.
+  const credentials = settings.corsCredentials;
+
+  if (raw === "*") {
+    // "*" and credentials are mutually exclusive per the CORS spec — the
+    // browser rejects the response, so the schema refuses the combination
+    // rather than storing a policy that silently fails in production.
+    if (credentials) {
+      throw new Error('corsOrigins "*" cannot be combined with corsCredentials — list the origins explicitly');
+    }
+
+    return { origin: true, credentials: false };
+  }
+
+  const origins = raw
+    .split(",")
+    .map((origin) => origin.trim())
+    .filter(Boolean);
+
+  return { origin: origins, credentials };
+}

package/templates/app/modules/security/helpers/proxy.ts

@@ -0,0 +1,16 @@
+import { isIP } from "node:net";
+
+/** Explicit proxy peers only: no blanket trust, hop counts or named subnet aliases. */
+export function trustedProxies(raw: string): false | string[] {
+  if (!raw.trim()) return false;
+  const entries = raw.split(",").map(entry => entry.trim());
+  for (const entry of entries) {
+    const [address = "", bits, ...extra] = entry.split("/");
+    const family = isIP(address);
+    if (!family || address.includes("%") || extra.length ||
+      (bits !== undefined && (!/^[1-9][0-9]{0,2}$/.test(bits) || Number(bits) > (family === 4 ? 32 : 128)))) {
+      throw new Error("TRUST_PROXY_CIDRS must be empty or a comma-separated list of IP addresses/CIDRs with nonzero prefix lengths");
+    }
+  }
+  return [...new Set(entries)];
+}

package/templates/app/modules/security/helpers/rate-limit.ts

@@ -0,0 +1,150 @@
+import { createHash } from "node:crypto";
+import { isIP } from "node:net";
+import { Router, type RequestHandler } from "express";
+import { Redis } from "ioredis";
+import ipaddr from "ipaddr.js";
+import { HttpError } from "@tulipes/core/http";
+import type { Ctx } from "@tulipes/core/boot";
+
+// One atomic, expiring counter per client and policy, shared by every backend.
+// Rejected requests neither increase the counter nor extend its expiration.
+const consume = `
+local count = tonumber(redis.call('GET', KEYS[1]) or '0')
+local ttl = redis.call('PTTL', KEYS[1])
+if ttl <= 0 then
+  redis.call('SET', KEYS[1], 1, 'PX', ARGV[2])
+  return {1, tonumber(ARGV[2])}
+end
+if count >= tonumber(ARGV[1]) then return {0, ttl} end
+redis.call('INCR', KEYS[1])
+return {1, ttl}
+`;
+
+export interface RateLimitOptions {
+  redisUrl: string;
+  namespace: string;
+  windowMs: number;
+  authLimit: number;
+  sessionLimit: number;
+  configLimit: number;
+}
+
+/** The `rateLimits` setting, as `ctx.config.security.rateLimits`. */
+export interface RateLimitSettings {
+  namespace: string;
+  windowMs: number;
+  auth: number;
+  session: number;
+  config: number;
+}
+
+type RateLimits = ReturnType<typeof createRateLimits>;
+
+/**
+ * One limiter set per boot, built from the live settings on first use and
+ * rebuilt by module.config's onChange when they change. The routes file
+ * mounts a handler that always delegates to the current set, so a rebuild
+ * never re-mounts anything; the previous set's client is closed once the
+ * new one exists.
+ */
+const instances = new WeakMap<Ctx, { limits: RateLimits; settings: RateLimitSettings }>();
+
+export function configuredRateLimits(ctx: Ctx): RateLimits {
+  const current = instances.get(ctx);
+  if (current) return current.limits;
+  return rebuildRateLimits(ctx, settingsOf(ctx)).limits;
+}
+
+/** @internal module.config onChange and the first request. */
+export function rebuildRateLimits(ctx: Ctx, settings: RateLimitSettings): { limits: RateLimits; settings: RateLimitSettings } {
+  const previous = instances.get(ctx);
+  if (previous && JSON.stringify(previous.settings) === JSON.stringify(settings)) return previous;
+  const next = {
+    settings: { ...settings },
+    limits: createRateLimits({
+      redisUrl: String(ctx.Environment.get("REDIS_URL")),
+      namespace: settings.namespace + ":" + ctx.Environment.appEnv,
+      windowMs: settings.windowMs,
+      authLimit: settings.auth,
+      sessionLimit: settings.session,
+      configLimit: settings.config,
+    }),
+  };
+  instances.set(ctx, next);
+  previous?.limits.close();
+  return next;
+}
+
+function settingsOf(ctx: Ctx): RateLimitSettings {
+  const settings = (ctx.config.security as { rateLimits?: RateLimitSettings } | undefined)?.rateLimits;
+  if (!settings) throw new Error("security settings are not loaded — the rate limiter is built after boot phase 6");
+  return settings;
+}
+
+export function createRateLimits(options: RateLimitOptions) {
+  for (const [name, value] of Object.entries({ windowMs: options.windowMs,
+    auth: options.authLimit, session: options.sessionLimit, config: options.configLimit })) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > 2_147_483_647) {
+      throw new Error("rateLimits." + name + " must be a positive integer no greater than 2147483647");
+    }
+  }
+  if (!/^[a-zA-Z0-9:_-]{1,128}$/.test(options.namespace)) {
+    throw new Error("rateLimits.namespace must use letters, digits, colon, underscore or hyphen (max 128 including app environment)");
+  }
+  const redis = new Redis(options.redisUrl, {
+    lazyConnect: true, enableOfflineQueue: false, maxRetriesPerRequest: 0,
+    connectTimeout: 1000, commandTimeout: 1000,
+  });
+  // Never log connection URLs or driver errors; HTTP failures use a stable code.
+  redis.on("error", () => {});
+  // Driver handshakes can involve several timed commands. Bound the initial
+  // wait separately; reconnection may continue while requests fail closed.
+  const ready = new Promise<void>(resolve => {
+    const timer = setTimeout(resolve, 1000);
+    timer.unref();
+    void redis.connect().catch(() => {}).finally(() => { clearTimeout(timer); resolve(); });
+  });
+  const limit = (policy: string, maximum: number): RequestHandler => async (req, res, next) => {
+    // Use only Express's resolved address. Invalid trusted-proxy input shares one
+    // bucket, so arbitrary header strings cannot mint arbitrary client identities.
+    let identity = "unknown";
+    if (req.ip && isIP(req.ip)) {
+      const address = ipaddr.process(req.ip);
+      const bytes = address.toByteArray();
+      if (address.kind() === "ipv6") bytes.fill(0, 7); // Aggregate IPv6 /56.
+      identity = ipaddr.fromByteArray(bytes).toString();
+    }
+    const key = "tulipes:rate:" + options.namespace + ":" + policy + ":"
+      + createHash("sha256").update(identity).digest("hex");
+    let result: unknown;
+    try {
+      await ready;
+      if (redis.status !== "ready") throw new Error("unavailable");
+      result = await redis.eval(consume, 1, key, maximum, options.windowMs);
+      if (!Array.isArray(result) || result.length !== 2 || ![0, 1].includes(result[0])
+        || !Number.isSafeInteger(result[1]) || result[1] < 1) throw new Error("invalid counter");
+    } catch {
+      throw new HttpError(503, "rateLimitUnavailable", { code: "RATE_LIMIT_UNAVAILABLE",
+        defaultMessage: "Request limits are unavailable; try again later" });
+    }
+    if (Array.isArray(result) && result[0] === 0) {
+      res.setHeader("Retry-After", Math.max(1, Math.ceil(Number(result[1]) / 1000)));
+      throw new HttpError(429, "tooManyRequests", { code: "TOO_MANY_REQUESTS",
+        defaultMessage: "Too many requests; try again later" });
+    }
+    next();
+  };
+  const auth = Router();
+  // The broad quota bounds all auth requests, including refresh, reads and misses.
+  auth.use(limit("sessions", options.sessionLimit));
+  auth.post(["/login", "/register", "/password"], limit("credentials", options.authLimit));
+  return { auth, config: limit("config", options.configLimit), close: () => {
+    redis.disconnect();
+  } };
+}
+
+/** Security owns its connections, including partially initialized boot cleanup. */
+export function closeRateLimits(ctx: Ctx): void {
+  instances.get(ctx)?.limits.close();
+  instances.delete(ctx);
+}

package/templates/app/modules/security/module.config.ts

@@ -0,0 +1,59 @@
+import { defineConfig } from "@tulipes/core/config";
+import { z } from "zod/v4";
+
+import { corsOptions } from "./helpers/hardening.ts";
+import { rebuildRateLimits } from "./helpers/rate-limit.ts";
+import { trustedProxies } from "./helpers/proxy.ts";
+
+/**
+ * Everything the request pipeline is configured with. None of it is a
+ * secret and none of it is needed before the settings store answers, so
+ * none of it is an environment variable: an operator changes it through
+ * the console and every replica rebuilds its middleware from `onChange`.
+ * The schema refuses a value the middleware could not be built from, so a
+ * bad write never lands in the store.
+ */
+export default defineConfig({
+  schema: z.object({
+    passwordRounds: z.number().int().min(4).max(31).default(12)
+      .describe("bcrypt cost factor for new password hashes; existing hashes are upgraded on login"),
+    bodyLimit: z.string().regex(/^\d+(\.\d+)?\s*(b|kb|mb|gb)?$/i).default("1mb")
+      .describe("Largest JSON request body express parses, e.g. \"1mb\"; nginx client_max_body_size must be at least this"),
+    trustProxyCidrs: z.string().default("")
+      .refine((raw) => { try { trustedProxies(raw); return true; } catch { return false; } },
+        "Empty, or a comma-separated list of IP addresses/CIDRs with nonzero prefix lengths")
+      .describe("Comma-separated trusted proxy addresses or CIDRs; empty ignores forwarded headers. Configure only actual proxy peers"),
+    corsOrigins: z.string().default("")
+      .describe("Comma-separated browser origins allowed to read API responses; \"*\" allows any, empty allows none (same-origin only)"),
+    corsCredentials: z.boolean().default(false)
+      .describe("Emit Access-Control-Allow-Credentials for browser credential mode; does not enable cookie authentication or CSRF protection (cannot be combined with corsOrigins \"*\")"),
+    hstsMaxAge: z.number().int().min(0).default(15_552_000)
+      .describe("Strict-Transport-Security max-age in seconds; 0 disables the header (browsers only honour it over HTTPS)"),
+    rateLimits: z.object({
+      namespace: z.string().regex(/^[a-zA-Z0-9:_-]{1,100}$/).default("tulipes")
+        .describe("Stable identifier shared by replicas; use a different value for unrelated apps on the same Redis database"),
+      windowMs: z.number().int().min(1).max(2_147_483_647).default(60_000)
+        .describe("Fixed request window in milliseconds"),
+      auth: z.number().int().min(1).max(2_147_483_647).default(20)
+        .describe("Combined login, register and password POST attempts per client per window"),
+      session: z.number().int().min(1).max(2_147_483_647).default(120)
+        .describe("All auth requests per client per window, including refresh and credential attempts"),
+      config: z.number().int().min(1).max(2_147_483_647).default(60)
+        .describe("All console (config and settings) requests per client per window"),
+    }).default({ namespace: "tulipes", windowMs: 60_000, auth: 20, session: 120, config: 60 })
+      .describe("Shared request quotas, counted in Redis so replicas agree"),
+  }).refine((values) => { try { corsOptions(values); return true; } catch { return false; } }, {
+    path: ["corsCredentials"],
+    message: "corsOrigins \"*\" cannot be combined with corsCredentials — list the origins explicitly",
+  }),
+
+  /**
+   * Helmet, CORS and the body parser read the live values on every
+   * request; the rate limiter holds a Redis client and the proxy policy is
+   * an app setting, so those two are rebuilt here.
+   */
+  onChange(next, ctx) {
+    ctx.app?.set("trust proxy", trustedProxies(next.trustProxyCidrs));
+    rebuildRateLimits(ctx, next.rateLimits);
+  },
+});