@cosmicdrift/kumiko-server-runtime 0.157.2 → 0.159.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "0.157.2",
+  "version": "0.159.1",
   "description": "Production server-boot runtime for Kumiko apps: connections, schema-drift-gate, seeds, lifecycle, graceful shutdown. Symmetric to kumiko-dev-server's runDevApp, without dev/scaffold/codegen tooling.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -72,8 +72,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.157.2",
-    "@cosmicdrift/kumiko-framework": "0.157.2",
+    "@cosmicdrift/kumiko-bundled-features": "0.159.1",
+    "@cosmicdrift/kumiko-framework": "0.159.1",
     "temporal-polyfill": "^0.3.2"
   },
   "publishConfig": {

package/src/__tests__/run-prod-app.integration.test.ts

@@ -13,6 +13,13 @@ import { afterEach, beforeAll, describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { createPersonalAccessTokensFeature } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
+import {
+  createSessionsFeature,
+  userSessionEntity,
+} from "@cosmicdrift/kumiko-bundled-features/sessions";
+import { userEntity } from "@cosmicdrift/kumiko-bundled-features/user";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import { InMemoryKmsAdapter, type KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
 import { createDbConnection } from "@cosmicdrift/kumiko-framework/db";
@@ -26,6 +33,10 @@ import {
   createArchivedStreamsTable,
   createEventsTable,
 } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createNoopProvider,
+  createPrometheusMeter,
+} from "@cosmicdrift/kumiko-framework/observability";
 import {
   createEventConsumerStateTable,
   createProjectionStateTable,
@@ -196,6 +207,8 @@ async function migrateTestDb(): Promise<void> {
     await createProjectionStateTable(db);
     await createEventConsumerStateTable(db);
     await unsafeEnsureEntityTable(db, widgetEntity, "widget");
+    await unsafeEnsureEntityTable(db, userEntity, "user");
+    await unsafeEnsureEntityTable(db, userSessionEntity, "user-session");
     await asRawClient(db).unsafe(
       `CREATE TABLE IF NOT EXISTS prod_probe_pings (
          id BIGSERIAL PRIMARY KEY,
@@ -250,6 +263,26 @@ describe("runProdApp", () => {
     expect(res.status).toBe(200);
   });
 
+  test("unrecognized KUMIKO_DRY_RUN_ENV value warns and falls through to a normal boot", async () => {
+    const originalWarn = console.warn;
+    const warnings: string[] = [];
+    console.warn = (...args: unknown[]) => {
+      warnings.push(args.map(String).join(" "));
+    };
+    const original = process.env["KUMIKO_DRY_RUN_ENV"];
+    process.env["KUMIKO_DRY_RUN_ENV"] = "not-a-real-mode";
+    try {
+      const handle = await boot();
+      const res = await handle.entrypoint.app.fetch(new Request("http://test/health"));
+      expect(res.status).toBe(200);
+    } finally {
+      console.warn = originalWarn;
+      if (original === undefined) delete process.env["KUMIKO_DRY_RUN_ENV"];
+      else process.env["KUMIKO_DRY_RUN_ENV"] = original;
+    }
+    expect(warnings.some((line) => line.includes("unrecognized"))).toBe(true);
+  });
+
   test("second boot against the same DB is idempotent — no crash, no duplicate tables", async () => {
     await boot();
     // First boot left tables in place. Restart on the same DB —
@@ -790,7 +823,7 @@ describe("runProdApp — auth allowedOrigins forwarding", () => {
   test("cookieDomain without allowedOrigins fails closed — guard is wired through runProdApp", async () => {
     await expect(
       boot(undefined, {
-        auth: { admin: ADMIN, cookieDomain: "example.eu" },
+        auth: { admin: ADMIN, cookieDomain: "example.eu", sessions: false },
         allowPlaintextPii: "test: origin-guard focus, not crypto",
       }),
     ).rejects.toThrow(/allowedOrigins is empty/);
@@ -807,6 +840,7 @@ describe("runProdApp — auth allowedOrigins forwarding", () => {
           admin: ADMIN,
           cookieDomain: "example.eu",
           allowedOrigins: ["https://app.example.eu"],
+          sessions: false,
         },
       });
       expect(handle).toBeDefined();
@@ -819,6 +853,48 @@ describe("runProdApp — auth allowedOrigins forwarding", () => {
   });
 });
 
+describe("runProdApp — session boot gate (#1262/#1275)", () => {
+  const ADMIN = {
+    email: "session-gate@example.eu",
+    password: "test-pw-strong-1234",
+    displayName: "Admin",
+    memberships: [],
+  };
+
+  test("auth mounted, sessions feature missing, no opt-out → aborts boot", async () => {
+    await expect(
+      boot(undefined, {
+        auth: {
+          admin: ADMIN,
+          cookieDomain: "example.eu",
+          allowedOrigins: ["https://app.example.eu"],
+        },
+        allowPlaintextPii: "test: session-gate focus, not crypto",
+      }),
+    ).rejects.toThrow(/BOOT ABORTED.*sessions.*stateless/s);
+  });
+
+  test("auth mounted, sessions feature mounted → boots cleanly (the happy path the gate guards)", async () => {
+    const handle = await boot(undefined, {
+      // "user" is auto-mounted via includeBundled whenever auth.admin is set.
+      // sessions requires auth-foundation, which needs a tokenVerifier
+      // provider — PAT.
+      features: [
+        authFoundationFeature,
+        createPersonalAccessTokensFeature({ scopes: {} }),
+        createSessionsFeature(),
+      ],
+      auth: {
+        admin: ADMIN,
+        cookieDomain: "example.eu",
+        allowedOrigins: ["https://app.example.eu"],
+      },
+      allowPlaintextPii: "test: session-gate focus, not crypto",
+    });
+    expect(handle).toBeDefined();
+  });
+});
+
 describe("runProdApp job-lane wiring (runSingleInstance)", () => {
   // Red-then-green for the export bug: on createApiEntrypoint (old default) the
   // worker-lane cron was never registered. createAllInOneEntrypoint (new
@@ -932,3 +1008,36 @@ describe("hard PII boot gate (#818 step 2)", () => {
     expect(handle).toBeDefined();
   });
 });
+
+// Regression for fw#1352: runProdApp wires the metrics route through two
+// independently forwarded options (observability, metrics). Wrong nesting
+// or a renamed key in ApiEntrypointOptions would silently no-op instead of
+// erroring the boot, and /metrics would stay 404 or empty.
+describe("runProdApp — /metrics endpoint (fw#1352)", () => {
+  test("observability (PrometheusMeter) + metrics.token wired → GET /metrics mit Bearer liefert OpenMetrics-Body", async () => {
+    const meter = createPrometheusMeter();
+    meter.registerMetric({ name: "kumiko_probe_total", type: "counter" });
+    meter.counter("kumiko_probe_total").inc(2);
+
+    const handle = await boot(undefined, {
+      observability: { ...createNoopProvider(), meter },
+      metrics: { token: "t" },
+    });
+
+    const res = await handle.entrypoint.app.fetch(
+      new Request("http://test/metrics", { headers: { Authorization: "Bearer t" } }),
+    );
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toMatch(/openmetrics-text/);
+    const body = await res.text();
+    expect(body).toContain("kumiko_probe_total 2");
+    expect(body).toMatch(/# EOF\n$/);
+  });
+
+  test("ohne observability und ohne metrics-Option → /metrics ist keine Route (404)", async () => {
+    const handle = await boot();
+
+    const res = await handle.entrypoint.app.fetch(new Request("http://test/metrics"));
+    expect(res.status).toBe(404);
+  });
+});

package/src/__tests__/security-headers.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "bun:test";
+import { resolveSecurityHeaders, withSecurityHeaders } from "../security-headers";
+
+const okHandler = (_req: Request) => new Response("ok");
+const req = new Request("http://localhost/");
+
+describe("resolveSecurityHeaders", () => {
+  it("returns the four defaults without csp when unconfigured", () => {
+    const headers = new Map(resolveSecurityHeaders(undefined));
+    expect(headers.get("strict-transport-security")).toBe("max-age=31536000; includeSubDomains");
+    expect(headers.get("x-frame-options")).toBe("DENY");
+    expect(headers.get("x-content-type-options")).toBe("nosniff");
+    expect(headers.get("referrer-policy")).toBe("strict-origin-when-cross-origin");
+    expect(headers.has("content-security-policy")).toBe(false);
+  });
+
+  it("returns nothing when disabled", () => {
+    expect(resolveSecurityHeaders(false)).toEqual([]);
+  });
+
+  it("applies per-header overrides and opt-outs", () => {
+    const headers = new Map(
+      resolveSecurityHeaders({
+        hsts: "max-age=60",
+        frameOptions: false,
+        referrerPolicy: "no-referrer",
+        csp: "default-src 'self'",
+      }),
+    );
+    expect(headers.get("strict-transport-security")).toBe("max-age=60");
+    expect(headers.has("x-frame-options")).toBe(false);
+    expect(headers.get("x-content-type-options")).toBe("nosniff");
+    expect(headers.get("referrer-policy")).toBe("no-referrer");
+    expect(headers.get("content-security-policy")).toBe("default-src 'self'");
+  });
+});
+
+describe("withSecurityHeaders", () => {
+  it("sets defaults on every response", async () => {
+    const res = await withSecurityHeaders(okHandler, undefined)(req);
+    expect(res.headers.get("strict-transport-security")).toBe(
+      "max-age=31536000; includeSubDomains",
+    );
+    expect(res.headers.get("x-frame-options")).toBe("DENY");
+    expect(res.headers.get("x-content-type-options")).toBe("nosniff");
+    expect(res.headers.get("referrer-policy")).toBe("strict-origin-when-cross-origin");
+    expect(await res.text()).toBe("ok");
+  });
+
+  it("returns the handler unwrapped when disabled", () => {
+    expect(withSecurityHeaders(okHandler, false)).toBe(okHandler);
+  });
+
+  it("never overrides a header the response already set", async () => {
+    const handler = (_req: Request) =>
+      new Response("ok", {
+        headers: {
+          "content-security-policy": "default-src 'none'",
+          "x-frame-options": "SAMEORIGIN",
+        },
+      });
+    const res = await withSecurityHeaders(handler, { csp: "default-src 'self'" })(req);
+    expect(res.headers.get("content-security-policy")).toBe("default-src 'none'");
+    expect(res.headers.get("x-frame-options")).toBe("SAMEORIGIN");
+    expect(res.headers.get("x-content-type-options")).toBe("nosniff");
+  });
+
+  it("re-wraps responses with immutable headers", async () => {
+    const immutable = new Response("ok", { status: 201, statusText: "Created" });
+    Object.defineProperty(immutable, "headers", {
+      value: new Proxy(immutable.headers, {
+        get(target, prop) {
+          if (prop === "set") {
+            return () => {
+              throw new TypeError("immutable");
+            };
+          }
+          const value = Reflect.get(target, prop);
+          return typeof value === "function" ? value.bind(target) : value;
+        },
+      }),
+    });
+    const res = await withSecurityHeaders(() => immutable, undefined)(req);
+    expect(res.status).toBe(201);
+    expect(res.headers.get("x-content-type-options")).toBe("nosniff");
+    expect(await res.text()).toBe("ok");
+  });
+});

package/src/__tests__/session-boot-gate.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import { assertSessionBootInvariants } from "../session-boot-gate";
+
+describe("assertSessionBootInvariants", () => {
+  test("no auth mounted → nothing to gate", () => {
+    expect(() =>
+      assertSessionBootInvariants({
+        hasAuth: false,
+        sessionsFeatureMounted: false,
+        sessionsOption: undefined,
+      }),
+    ).not.toThrow();
+  });
+
+  test("auth mounted, sessions feature missing, no opt-out → aborts boot", () => {
+    expect(() =>
+      assertSessionBootInvariants({
+        hasAuth: true,
+        sessionsFeatureMounted: false,
+        sessionsOption: undefined,
+      }),
+    ).toThrow(/BOOT ABORTED.*sessions.*stateless/s);
+  });
+
+  test("auth mounted, sessions feature missing, explicit sessions:false → boots", () => {
+    expect(() =>
+      assertSessionBootInvariants({
+        hasAuth: true,
+        sessionsFeatureMounted: false,
+        sessionsOption: false,
+      }),
+    ).not.toThrow();
+  });
+
+  test("auth mounted, sessions feature wired → boots", () => {
+    expect(() =>
+      assertSessionBootInvariants({
+        hasAuth: true,
+        sessionsFeatureMounted: true,
+        sessionsOption: undefined,
+      }),
+    ).not.toThrow();
+  });
+
+  test("auth mounted, sessions feature wired AND an expiresInMs override → boots", () => {
+    expect(() =>
+      assertSessionBootInvariants({
+        hasAuth: true,
+        sessionsFeatureMounted: true,
+        sessionsOption: { expiresInMs: 60_000 },
+      }),
+    ).not.toThrow();
+  });
+});

package/src/boot/boot-crypto.ts

@@ -5,7 +5,6 @@
 // buildBootExtraContext + applyBootSeeds so resolver, set-handler and
 // seeds share the same cipher instance (and DEK cache).
 
-import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import {
   createDekCache,
   createEnvelopeCipher,
@@ -27,12 +26,10 @@ export function envHasMasterKek(env: Record<string, string | undefined>): boolea
 export type BootCrypto = {
   readonly masterKeyProvider?: MasterKeyProvider;
   // Cipher for encrypted config keys. Present exactly when a master key is
-  // available. Decrypts legacy CONFIG_ENCRYPTION_KEY values as fallback
-  // until the config re-encrypt job migrated them.
+  // available.
   readonly configCipher?: EnvelopeCipher;
-  // Cipher for `encrypted: true` entity fields — same master key, but the
-  // legacy fallback reads the pre-envelope ENCRYPTION_KEY format. Identical
-  // to configCipher when no ENCRYPTION_KEY is set.
+  // Cipher for `encrypted: true` entity fields — same master key and
+  // instance as configCipher (kept as a separate field for API stability).
   readonly entityFieldCipher?: EnvelopeCipher;
   readonly dekCache: DekCache;
 };
@@ -56,22 +53,10 @@ export function resolveBootCrypto(
       : undefined);
 
   const dekCache = createDekCache();
-  const legacyConfigKey = envSource["CONFIG_ENCRYPTION_KEY"];
   const configCipher = masterKeyProvider
-    ? createEnvelopeCipher(masterKeyProvider, {
-        dekCache,
-        ...(legacyConfigKey ? { legacy: createEncryptionProvider(legacyConfigKey) } : {}),
-      })
+    ? createEnvelopeCipher(masterKeyProvider, { dekCache })
     : undefined;
-
-  const legacyEntityKey = envSource["ENCRYPTION_KEY"];
-  const entityFieldCipher =
-    masterKeyProvider && legacyEntityKey
-      ? createEnvelopeCipher(masterKeyProvider, {
-          dekCache,
-          legacy: createEncryptionProvider(legacyEntityKey),
-        })
-      : configCipher;
+  const entityFieldCipher = configCipher;
 
   return {
     ...(masterKeyProvider && { masterKeyProvider }),

package/src/compose-features.ts

@@ -12,6 +12,7 @@
 // auf Frühere referenzieren (z.B. authClaims-Hooks an user/tenant).
 
 import {
+  type AccountUnlockOptions,
   type AuthEmailPasswordOptions,
   type AuthMailLocale,
   createAuthEmailPasswordFeature,
@@ -102,6 +103,7 @@ export type AuthOptionsCarrier = {
   readonly emailVerification?: EmailVerificationOptions;
   readonly signup?: SignupOptions;
   readonly invite?: InviteOptions;
+  readonly accountUnlock?: AccountUnlockOptions;
 };
 
 /** Baut den authOptions-Block für composeFeatures aus einem
@@ -158,7 +160,17 @@ export function buildComposeAuthOptions(
   if (auth.invite) {
     opts.invite = pickMailFields(auth.invite);
   }
-  return opts.passwordReset || opts.emailVerification || opts.signup || opts.invite
+  if (auth.accountUnlock) {
+    opts.accountUnlock = {
+      hmacSecret: auth.accountUnlock.hmacSecret,
+      ...pickMailFields(auth.accountUnlock),
+    };
+  }
+  return opts.passwordReset ||
+    opts.emailVerification ||
+    opts.signup ||
+    opts.invite ||
+    opts.accountUnlock
     ? opts
     : undefined;
 }

package/src/index.ts

@@ -4,6 +4,7 @@
 // Dev-Tooling mehr in ihre node_modules.
 export { type ComposeFeaturesOptions, composeFeatures } from "./compose-features";
 export type {
+  AccountUnlockSetup,
   EmailVerificationSetup,
   InviteSetup,
   PasswordResetSetup,
@@ -14,3 +15,4 @@ export type {
   SignupSetup,
 } from "./run-prod-app";
 export { runProdApp } from "./run-prod-app";
+export type { SecurityHeadersOption } from "./security-headers";

package/src/run-prod-app-boot-context.ts

@@ -160,6 +160,13 @@ type AuthMailNormalizable = {
   readonly invite?: InviteSetup;
 };
 
+// accountUnlock (#1266) deliberately does NOT join this convenience block —
+// unlike reset/verify/signup/invite it's only meaningful paired with
+// `accountLockout`, which itself isn't wired through RunProdAppAuthOptions
+// today. Apps that mount `accountLockout` set `auth.accountUnlock` alongside
+// it explicitly (same shape as `passwordReset`), so `mail` alone can't
+// silently expose a new public endpoint an app didn't ask for.
+
 export function resolveAuthMail<T extends AuthMailNormalizable>(
   auth: T,
   hmacSecret: string,
@@ -216,7 +223,6 @@ export function buildProdSessionAuth(
   readonly sessionCreator: ReturnType<typeof createSessionCallbacks>["sessionCreator"];
   readonly sessionRevoker: ReturnType<typeof createSessionCallbacks>["sessionRevoker"];
   readonly sessionChecker: ReturnType<typeof createSessionCallbacks>["sessionChecker"];
-  readonly sessionStrictMode: true;
 } {
   const cbs = createSessionCallbacks({
     db,
@@ -236,6 +242,5 @@ export function buildProdSessionAuth(
     sessionCreator: cbs.sessionCreator,
     sessionRevoker: cbs.sessionRevoker,
     sessionChecker: cbs.sessionChecker,
-    sessionStrictMode: true,
   };
 }

package/src/run-prod-app.ts

@@ -20,11 +20,18 @@
 // Container/Coolify setzt:
 //   DATABASE_URL=postgresql://...
 //   REDIS_URL=redis://...
-//   JWT_SECRET=<random-32+>
+//   JWT_SECRET=<random-32+>  (always required — also signs the password-
+//     reset/email-verification HMAC tokens, a separate non-rotating family)
+//     — additionally, for zero-downtime rotation of the session-JWT
+//     signing key specifically:
+//   JWT_SECRET_V1=<random-32+>  (repeat _V2, _V3, ... per rotation)
+//   JWT_SECRET_CURRENT_VERSION=1  (which V<n> signs new tokens; the others
+//     still verify in-flight tokens until they expire)
 //   PORT=3000
 //   KUMIKO_INSTANCE_ID=<stable per replica>
 
 import {
+  type AccountUnlockOptions,
   AuthErrors,
   AuthHandlers,
   type AuthMailLocale,
@@ -38,12 +45,14 @@ import {
   type SeedAdminOptions,
   seedAdmin,
 } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
+import {
+  EXT_TOKEN_VERIFIER,
+  resolveTokenVerifier,
+} from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { AUTH_MFA_FEATURE, AuthMfaHandlers } from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
 import {
-  createPatResolver,
   PAT_FEATURE,
   patRateLimitFromFeature,
-  patScopesFromFeature,
 } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
 import { SESSIONS_FEATURE } from "@cosmicdrift/kumiko-bundled-features/sessions";
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
@@ -53,9 +62,12 @@ import {
 } from "@cosmicdrift/kumiko-bundled-features/tenant-lifecycle";
 import { UserQueries } from "@cosmicdrift/kumiko-bundled-features/user";
 import {
-  createInMemoryLoginRateLimiter,
+  createRedisLoginRateLimiter,
   createSseBroker,
+  type LoginRateLimiter,
+  loadJwtSecretOrKeyring,
   type SseBroker,
+  type TokenVerifier,
 } from "@cosmicdrift/kumiko-framework/api";
 import {
   configureBlindIndexKey,
@@ -126,6 +138,8 @@ import {
   resolveAuthMail,
 } from "./run-prod-app-boot-context";
 import { buildStaticFallback } from "./run-prod-app-static-files";
+import { type SecurityHeadersOption, withSecurityHeaders } from "./security-headers";
+import { assertSessionBootInvariants } from "./session-boot-gate";
 import {
   type ProdSessionsOption,
   resolveProdSessionsConfig,
@@ -242,6 +256,13 @@ export type SignupSetup = SignupOptions;
  *  AuthHandlers (analog signup). */
 export type InviteSetup = InviteOptions;
 
+/** Wrapper API for the account-unlock flow (#1266). = AccountUnlockOptions
+ *  (appUrl via delivery, symmetric to PasswordResetSetup). Self-service
+ *  escape hatch for accountLockout's monotonic failure counter — only
+ *  meaningful when `auth.accountLockout` is also set, but wired
+ *  independently like the other flows. */
+export type AccountUnlockSetup = AccountUnlockOptions;
+
 /** Auth-Mail-Convenience-Optionen — shared zwischen runProdApp + runDevApp.
  *  Verdrahtet alle 4 Mail-Flows aus einem env-SMTP-Transport + Standard-
  *  Templates (siehe `auth.mail` + resolveAuthMail). */
@@ -269,7 +290,7 @@ export type RunProdAppAuthOptions = {
   /** Opt-in: revocable server-side sessions. Caller MUSS
    *  `createSessionsFeature()` zu `features` adden — runProdApp wired
    *  hier nur die Auth-Callbacks (creator/revoker/checker) gegen die
-   *  echte db-connection, plus sessionStrictMode=true.
+   *  echte db-connection (sidless JWTs werden dann abgelehnt).
    *
    *  Standardverhalten ohne diese Option: stateless JWTs ohne sid
    *  (legacy-Verhalten, Karten­haus existing-Apps unangefasst). */
@@ -306,6 +327,11 @@ export type RunProdAppAuthOptions = {
    *  /api/auth/invite-accept-with-login, /api/auth/invite-signup-complete
    *  are mounted. */
   readonly invite?: InviteSetup;
+  /** Account-unlock flow (#1266). When set, /api/auth/request-account-unlock
+   *  + /api/auth/confirm-account-unlock are mounted. Self-service escape
+   *  hatch for accountLockout's monotonic failure-counter — confirming
+   *  clears the Redis lockout state, no entity write. */
+  readonly accountUnlock?: AccountUnlockSetup;
   /** Domain attribute for both auth cookies (see
    *  AuthRoutesConfig.cookieDomain). Set to the registrable parent
    *  domain when login and app live on different subdomains. */
@@ -569,6 +595,12 @@ export type RunProdAppOptions = {
    *  dieses Feld wird kein L1/L2 verdrahtet (L3 Handler-`rateLimit:`
    *  funktioniert unabhängig davon bereits). */
   readonly rateLimit?: import("@cosmicdrift/kumiko-framework/api").ServerOptions["rateLimit"];
+  /** Default security headers on every response (HSTS, X-Frame-Options,
+   *  X-Content-Type-Options, Referrer-Policy; CSP opt-in). Headers already
+   *  set by a response (e.g. hostDispatch's per-host CSP) are never
+   *  overridden. `false` disables the whole block; per-header overrides
+   *  via the object form — see SecurityHeadersOption. */
+  readonly securityHeaders?: SecurityHeadersOption;
 };
 
 export type ProdAppHandle = {
@@ -652,7 +684,13 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   //    configured.
   const databaseUrl = requireEnv("DATABASE_URL", envSource);
   const redisUrl = requireEnv("REDIS_URL", envSource);
+  // JWT_SECRET stays mandatory (also the resolveAuthMail hmacSecret
+  // fallback below — a separate, non-rotating HMAC token family, not the
+  // session JWT). jwtSecretOrKeyring is the OPTIONAL upgrade: set
+  // JWT_SECRET_V<n> + JWT_SECRET_CURRENT_VERSION for zero-downtime
+  // rotation of the session-JWT signing key — see loadJwtSecretOrKeyring.
   const jwtSecret = requireEnv("JWT_SECRET", envSource);
+  const jwtSecretOrKeyring = loadJwtSecretOrKeyring(envSource);
   const jwtIssuer = readEnv("JWT_ISSUER", envSource);
   const instanceId = readEnv("KUMIKO_INSTANCE_ID", envSource);
   const port = options.port ?? Number.parseInt(envSource["PORT"] ?? "3000", 10);
@@ -687,6 +725,12 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
     allowPlaintextPii: options.allowPlaintextPii,
     mode: "prod",
   });
+  const sessionsFeature = features.find((f) => f.name === SESSIONS_FEATURE);
+  assertSessionBootInvariants({
+    hasAuth: Boolean(effectiveAuth),
+    sessionsFeatureMounted: sessionsFeature !== undefined,
+    sessionsOption: effectiveAuth?.sessions,
+  });
   const registry = createRegistry(features);
 
   // C1 boot-mode exit: validators ran + registry built; no DB/Redis client
@@ -824,17 +868,16 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
 
   // Sessions opt-in: db ist hier schon konkret (createDbConnection oben),
   // also direkt verdrahten — kein late-bound nötig wie bei runDevApp.
-  // sessionStrictMode=true: Prod-Sessions sollen nicht stillschweigend
-  // von einem JWT-ohne-sid umgangen werden können. sessionMassRevoker
+  // Ein JWT ohne sid wird abgelehnt, sobald ein sessionChecker verdrahtet ist —
+  // Prod-Sessions können nicht stillschweigend umgangen werden. sessionMassRevoker
   // (4. callback aus createSessionCallbacks) ist nicht Teil der
   // AuthRoutesConfig-Surface — der geht via bindAutoRevokeFromFeature ans
   // sessions-Feature (Password-Change/-Reset revoked alle Sessions), nicht
   // über die auth-routes.
   // Secure-by-default: if the sessions feature is mounted, server-side revocation +
-  // sessionStrictMode + auto-revoke-on-password-change are wired automatically;
+  // auto-revoke-on-password-change are wired automatically;
   // `auth.sessions` only overrides the config, and `auth.sessions: false` is the
   // explicit opt-out (back to stateless JWTs).
-  const sessionsFeature = features.find((f) => f.name === SESSIONS_FEATURE);
   const mfaFeature = features.find((f) => f.name === AUTH_MFA_FEATURE);
   const sessionAuthFragment = shouldWireProdSessions(
     Boolean(effectiveAuth),
@@ -849,21 +892,25 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
       )
     : undefined;
 
-  // PAT opt-in: if the personal-access-tokens feature is mounted, wire its
-  // resolver (bearer PATs → SessionUser, before jwt.verify). Scopes come from
-  // the feature's exports — the same declaration its handlers use.
+  // Token-verifier opt-in: any provider feature (personal-access-tokens, a
+  // future auth-provider-jwt, ...) self-registers via
+  // r.useExtension(EXT_TOKEN_VERIFIER, ...) — wire one generic resolver
+  // whenever at least one is mounted, resolved by shape at request-time.
+  // PAT keeps its own per-token rate limiter (patRateLimiter), unrelated to
+  // verification.
   const patFeature = features.find((f) => f.name === PAT_FEATURE);
+  const hasTokenVerifierProviders = registry.getExtensionUsages(EXT_TOKEN_VERIFIER).length > 0;
   let patAuthFragment:
     | {
-        patResolver: ReturnType<typeof createPatResolver>;
-        patRateLimiter: ReturnType<typeof createInMemoryLoginRateLimiter>;
+        tokenVerifier: TokenVerifier;
+        patRateLimiter: LoginRateLimiter;
       }
     | undefined;
-  if (effectiveAuth && patFeature) {
+  if (effectiveAuth && patFeature && hasTokenVerifierProviders) {
     const rl = patRateLimitFromFeature(patFeature);
     patAuthFragment = {
-      patResolver: createPatResolver({ db, scopes: patScopesFromFeature(patFeature) }),
-      patRateLimiter: createInMemoryLoginRateLimiter(rl.maxRequests, rl.windowMs),
+      tokenVerifier: (rawToken) => resolveTokenVerifier({ db, registry }, rawToken),
+      patRateLimiter: createRedisLoginRateLimiter(redis, rl.maxRequests, rl.windowMs, "pat"),
     };
   }
 
@@ -887,7 +934,7 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
       ...extraContext,
     },
     sseBroker,
-    jwtSecret,
+    jwtSecret: jwtSecretOrKeyring,
     ...(jwtIssuer && { jwtIssuer }),
     ...(instanceId && { instanceId }),
     dispatcherOptions: {
@@ -908,6 +955,12 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
           [AuthErrors.invalidCredentials]: 401,
           [AuthErrors.noMembership]: 403,
         },
+        // Redis-backed, not the in-memory default createAuthRoutes falls
+        // back to — an in-process limiter only rate-limits within a single
+        // replica, so a multi-instance prod deployment would silently give
+        // each replica its own bucket (#1262/#1274). Redis is required infra
+        // here already (REDIS_URL), so this is free.
+        loginRateLimit: createRedisLoginRateLimiter(redis),
         ...(effectiveAuth.cookieDomain !== undefined && {
           cookieDomain: effectiveAuth.cookieDomain,
         }),
@@ -920,7 +973,15 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
         ...sessionAuthFragment,
         ...patAuthFragment,
         ...tenantLifecycleAuthFragment,
-        ...(mfaFeature && { mfaVerifyHandler: AuthMfaHandlers.verify }),
+        ...(mfaFeature && {
+          mfaVerifyHandler: AuthMfaHandlers.verify,
+          mfaVerifyRateLimit: createRedisLoginRateLimiter(
+            redis,
+            undefined,
+            undefined,
+            "mfa-verify",
+          ),
+        }),
         ...(effectiveAuth.passwordReset && {
           passwordReset: {
             requestHandler: AuthHandlers.requestPasswordReset,
@@ -933,6 +994,12 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
             confirmHandler: AuthHandlers.verifyEmail,
           },
         }),
+        ...(effectiveAuth.accountUnlock && {
+          accountUnlock: {
+            requestHandler: AuthHandlers.requestAccountUnlock,
+            confirmHandler: AuthHandlers.confirmAccountUnlock,
+          },
+        }),
         ...(effectiveAuth.signup && {
           signup: {
             requestHandler: AuthHandlers.signupRequest,
@@ -1066,14 +1133,17 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   //     wired via a wrapper so Hono owns /api/* + extraRoutes and disk
   //     owns the rest. Tests use this directly; listen() wraps it in
   //     Bun.serve.
-  const fetchHandler = options.staticDir
-    ? buildStaticFallback(
-        entrypoint.app.fetch.bind(entrypoint.app),
-        options.staticDir,
-        appSchemaJson,
-        options.hostDispatch,
-      )
-    : entrypoint.app.fetch.bind(entrypoint.app);
+  const fetchHandler = withSecurityHeaders(
+    options.staticDir
+      ? buildStaticFallback(
+          entrypoint.app.fetch.bind(entrypoint.app),
+          options.staticDir,
+          appSchemaJson,
+          options.hostDispatch,
+        )
+      : entrypoint.app.fetch.bind(entrypoint.app),
+    options.securityHeaders,
+  );
 
   // 11. Mark lifecycle ready — health/ready flips to 200 after this.
   entrypoint.lifecycle.markReady();

package/src/security-headers.ts

@@ -0,0 +1,67 @@
+export type SecurityHeadersOption =
+  | false
+  | {
+      /** `Strict-Transport-Security` value, or `false` to omit.
+       *  Default: `max-age=31536000; includeSubDomains`. */
+      readonly hsts?: string | false;
+      /** `X-Frame-Options` value, or `false` to omit. Default: `DENY`.
+       *  Apps that must be embeddable (iframe widgets) set `false` and
+       *  scope framing via a `csp` frame-ancestors directive instead. */
+      readonly frameOptions?: string | false;
+      /** `false` omits `X-Content-Type-Options: nosniff`. */
+      readonly contentTypeOptions?: false;
+      /** `Referrer-Policy` value, or `false` to omit.
+       *  Default: `strict-origin-when-cross-origin`. */
+      readonly referrerPolicy?: string | false;
+      /** `Content-Security-Policy` default for ALL responses. No built-in
+       *  default — a wrong CSP breaks app assets, so it stays opt-in.
+       *  A per-host CSP from `hostDispatch` wins over this value. */
+      readonly csp?: string;
+    };
+
+const DEFAULT_HSTS = "max-age=31536000; includeSubDomains";
+const DEFAULT_FRAME_OPTIONS = "DENY";
+const DEFAULT_REFERRER_POLICY = "strict-origin-when-cross-origin";
+
+export function resolveSecurityHeaders(
+  option: SecurityHeadersOption | undefined,
+): ReadonlyArray<readonly [string, string]> {
+  if (option === false) return [];
+  const opt = option ?? {};
+  const headers: Array<readonly [string, string]> = [];
+  const hsts = opt.hsts ?? DEFAULT_HSTS;
+  if (hsts !== false) headers.push(["strict-transport-security", hsts]);
+  const frameOptions = opt.frameOptions ?? DEFAULT_FRAME_OPTIONS;
+  if (frameOptions !== false) headers.push(["x-frame-options", frameOptions]);
+  if (opt.contentTypeOptions !== false) headers.push(["x-content-type-options", "nosniff"]);
+  const referrerPolicy = opt.referrerPolicy ?? DEFAULT_REFERRER_POLICY;
+  if (referrerPolicy !== false) headers.push(["referrer-policy", referrerPolicy]);
+  if (opt.csp) headers.push(["content-security-policy", opt.csp]);
+  return headers;
+}
+
+// Sets each header only when absent so per-response values (e.g. the
+// per-host CSP from hostDispatch) always win over the runtime default.
+export function withSecurityHeaders(
+  handler: (req: Request) => Response | Promise<Response>,
+  option: SecurityHeadersOption | undefined,
+): (req: Request) => Response | Promise<Response> {
+  const defaults = resolveSecurityHeaders(option);
+  if (defaults.length === 0) return handler;
+  return async (req: Request): Promise<Response> => {
+    const res = await handler(req);
+    try {
+      for (const [name, value] of defaults) {
+        if (!res.headers.has(name)) res.headers.set(name, value);
+      }
+      return res;
+    } catch {
+      // Immutable-headers Response (e.g. proxied fetch) — re-wrap.
+      const headers = new Headers(res.headers);
+      for (const [name, value] of defaults) {
+        if (!headers.has(name)) headers.set(name, value);
+      }
+      return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+    }
+  };
+}

package/src/session-boot-gate.ts

@@ -0,0 +1,29 @@
+import type { ProdSessionsOption } from "./session-wiring";
+
+export type SessionBootGateOptions = {
+  readonly hasAuth: boolean;
+  readonly sessionsFeatureMounted: boolean;
+  readonly sessionsOption: ProdSessionsOption | undefined;
+};
+
+// Mirrors pii-boot-gate.ts: catch a forgotten wiring at boot instead of
+// letting it degrade silently into stateless JWTs (no server-side
+// revocation, valid for the full 24h token TTL). `auth.sessions: false` is
+// already the sanctioned opt-out (see session-wiring.ts) — reusing it here
+// instead of inventing a second acknowledgment param.
+export function assertSessionBootInvariants(opts: SessionBootGateOptions): void {
+  // skip: no auth mounted — nothing to gate.
+  if (!opts.hasAuth) return;
+  // skip: explicit opt-out, operator acknowledged stateless JWTs.
+  if (opts.sessionsOption === false) return;
+  // skip: sessions feature is wired.
+  if (opts.sessionsFeatureMounted) return;
+
+  throw new Error(
+    "[runProdApp] BOOT ABORTED — auth is mounted but the `sessions` feature is not. " +
+      "JWTs would be stateless (no server-side revocation, valid until the 24h expiry) " +
+      "with no warning. Mount createSessionsFeature() " +
+      "(@cosmicdrift/kumiko-bundled-features/sessions) for revocable sessions, or pass " +
+      "{ auth: { sessions: false } } to acknowledge stateless JWTs are intentional.",
+  );
+}

package/src/session-wiring.ts

@@ -3,7 +3,7 @@
  * full prod boot).
  *
  * Secure-by-default: mounting the `sessions` feature turns server-side session
- * revocation + sessionStrictMode ON automatically — there is no separate opt-in. The
+ * revocation ON automatically — there is no separate opt-in. The
  * `auth.sessions` option only overrides the config, and `auth.sessions: false` is the
  * explicit opt-out (back to stateless JWTs).
  */