@cosmicdrift/kumiko-server-runtime 1.0.0 → 2.0.0

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

@@ -263,6 +263,31 @@ 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('KUMIKO_DRY_RUN_ENV="not-a-real-mode"') && 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 —
@@ -803,7 +828,12 @@ 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", sessions: false },
+        features: [
+          authFoundationFeature,
+          createPersonalAccessTokensFeature({ scopes: {} }),
+          createSessionsFeature(),
+        ],
+        auth: { admin: ADMIN, cookieDomain: "example.eu" },
         allowPlaintextPii: "test: origin-guard focus, not crypto",
       }),
     ).rejects.toThrow(/allowedOrigins is empty/);
@@ -811,16 +841,20 @@ describe("runProdApp — auth allowedOrigins forwarding", () => {
 
   test("cookieDomain + allowedOrigins clears the guard — allowlist reaches buildServer", async () => {
     // Without the forwarding fix this would ALSO throw /allowedOrigins is empty/.
-    // It may still fail later on the minimal harness (no auth tables migrated),
-    // but never on the origin guard — that is the forwarding proof.
+    // auth tables are migrated for this file (migrateTestDb() above); this test
+    // isolates only that a later boot failure is never the origin-guard message.
     let bootError: unknown;
     try {
       const handle = await boot(undefined, {
+        features: [
+          authFoundationFeature,
+          createPersonalAccessTokensFeature({ scopes: {} }),
+          createSessionsFeature(),
+        ],
         auth: {
           admin: ADMIN,
           cookieDomain: "example.eu",
           allowedOrigins: ["https://app.example.eu"],
-          sessions: false,
         },
       });
       expect(handle).toBeDefined();
@@ -841,7 +875,7 @@ describe("runProdApp — session boot gate (#1262/#1275)", () => {
     memberships: [],
   };
 
-  test("auth mounted, sessions feature missing, no opt-out → aborts boot", async () => {
+  test("auth mounted, sessions feature missing → aborts boot", async () => {
     await expect(
       boot(undefined, {
         auth: {
@@ -851,7 +885,7 @@ describe("runProdApp — session boot gate (#1262/#1275)", () => {
         },
         allowPlaintextPii: "test: session-gate focus, not crypto",
       }),
-    ).rejects.toThrow(/BOOT ABORTED.*sessions.*stateless/s);
+    ).rejects.toThrow(/BOOT ABORTED.*sessionStore/);
   });
 
   test("auth mounted, sessions feature mounted → boots cleanly (the happy path the gate guards)", async () => {

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

@@ -1,54 +1,22 @@
 import { describe, expect, test } from "bun:test";
 import { assertSessionBootInvariants } from "../session-boot-gate";
 
-describe("assertSessionBootInvariants", () => {
-  test("no auth mounted → nothing to gate", () => {
+describe("assertSessionBootInvariants (#1372)", () => {
+  test("no auth → no throw", () => {
     expect(() =>
-      assertSessionBootInvariants({
-        hasAuth: false,
-        sessionsFeatureMounted: false,
-        sessionsOption: undefined,
-      }),
+      assertSessionBootInvariants({ hasAuth: false, sessionStoreProviderMounted: false }),
     ).not.toThrow();
   });
 
-  test("auth mounted, sessions feature missing, no opt-out → aborts boot", () => {
+  test("auth + sessionStore → no throw", () => {
     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,
-      }),
+      assertSessionBootInvariants({ hasAuth: true, sessionStoreProviderMounted: true }),
     ).not.toThrow();
   });
 
-  test("auth mounted, sessions feature wired AND an expiresInMs override → boots", () => {
+  test("auth without sessionStore → throws", () => {
     expect(() =>
-      assertSessionBootInvariants({
-        hasAuth: true,
-        sessionsFeatureMounted: true,
-        sessionsOption: { expiresInMs: 60_000 },
-      }),
-    ).not.toThrow();
+      assertSessionBootInvariants({ hasAuth: true, sessionStoreProviderMounted: false }),
+    ).toThrow(/BOOT ABORTED/);
   });
 });

package/src/__tests__/session-wiring.test.ts

@@ -1,51 +1,16 @@
 import { describe, expect, it } from "bun:test";
-import {
-  createSessionsFeature,
-  SESSIONS_FEATURE,
-} from "@cosmicdrift/kumiko-bundled-features/sessions";
-import { resolveProdSessionsConfig, shouldWireProdSessions } from "../session-wiring";
+import { shouldWireProdSessions } from "../session-wiring";
 
-describe("shouldWireProdSessions — secure-by-default with opt-out (KF-1)", () => {
-  it("wires sessions when the feature is mounted, even without an explicit config", () => {
-    // The publicstatus bug: sessions feature mounted + auth set, but no auth.sessions —
-    // previously left stateless (no revocation). Now it wires automatically.
-    expect(shouldWireProdSessions(true, true, undefined)).toBe(true);
+describe("shouldWireProdSessions — secure-by-default (#1372)", () => {
+  it("wires when auth + sessionStore provider mounted", () => {
+    expect(shouldWireProdSessions(true, true)).toBe(true);
   });
 
-  it("wires sessions when a config object is given", () => {
-    expect(shouldWireProdSessions(true, true, { expiresInMs: 1000 })).toBe(true);
+  it("does not wire without auth", () => {
+    expect(shouldWireProdSessions(false, true)).toBe(false);
   });
 
-  it("does not wire when sessions: false (explicit opt-out)", () => {
-    expect(shouldWireProdSessions(true, true, false)).toBe(false);
-  });
-
-  it("does not wire when the sessions feature is not mounted", () => {
-    expect(shouldWireProdSessions(true, false, undefined)).toBe(false);
-  });
-
-  it("does not wire when the app has no auth at all", () => {
-    expect(shouldWireProdSessions(false, true, undefined)).toBe(false);
-  });
-});
-
-describe("SESSIONS_FEATURE constant matches the real feature name", () => {
-  it("createSessionsFeature()'s name equals SESSIONS_FEATURE", () => {
-    // shouldWireProdSessions's own arm only tests the pure boolean helper —
-    // the actual run-prod-app.ts integration seam
-    // (`features.some((f) => f.name === SESSIONS_FEATURE)`) drifts silently
-    // if the feature is ever renamed without updating this constant.
-    expect(createSessionsFeature().name).toBe(SESSIONS_FEATURE);
-  });
-});
-
-describe("resolveProdSessionsConfig", () => {
-  it("passes a config object through", () => {
-    expect(resolveProdSessionsConfig({ expiresInMs: 5000 })).toEqual({ expiresInMs: 5000 });
-  });
-
-  it("collapses false / undefined to defaults", () => {
-    expect(resolveProdSessionsConfig(undefined)).toEqual({});
-    expect(resolveProdSessionsConfig(false)).toEqual({});
+  it("does not wire without sessionStore provider", () => {
+    expect(shouldWireProdSessions(true, false)).toBe(false);
   });
 });

package/src/compose-features.ts

@@ -1,21 +1,24 @@
-// composeFeatures — single source of truth für die Feature-Liste die
-// Boot UND Schema-Generator sehen.
+// composeFeatures — single source of truth for the feature list that
+// boot AND the schema generator see.
 //
-// Sowohl runDevApp als auch runProdApp mischen im auth-mode dieselben
-// vier Bundled-Features dazu (config + user + tenant + auth-email-pw).
-// Damit der drizzle-Schema-Generator pro App genau dieselbe Feature-
-// Liste sieht wie die Runtime, leben die Komposition hier — beide
-// Bootstrap-Wrapper UND der per-app drizzle/generate.ts rufen sie auf.
+// Both runDevApp and runProdApp mix in the same bundled features in
+// auth-mode (config + user + tenant + auth-email-password, plus
+// auth-self-registration when authOptions.signup is set). So the
+// drizzle schema generator sees the exact same feature list per app as
+// the runtime, the composition lives here — both bootstrap wrappers AND
+// each app's drizzle/generate.ts call it.
 //
-// Reihenfolge: Infrastruktur-Features (config/user/tenant) zuerst, dann
-// auth-email-password, dann die App-Features. Spätere Features dürfen
-// auf Frühere referenzieren (z.B. authClaims-Hooks an user/tenant).
+// Order: infrastructure features (config/user/tenant) first, then
+// auth-email-password (+ auth-self-registration when authOptions.signup
+// is set), then the app features. Later features may reference earlier
+// ones (e.g. authClaims hooks on user/tenant).
 
 import {
   type AccountUnlockOptions,
   type AuthEmailPasswordOptions,
   type AuthMailLocale,
   createAuthEmailPasswordFeature,
+  createAuthSelfRegistrationToggleFeature,
   type EmailVerificationOptions,
   type InviteOptions,
   type PasswordResetOptions,
@@ -32,7 +35,8 @@ import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 
 export type ComposeFeaturesOptions = {
   /** When true, prepends config + user + tenant + auth-email-password
-   *  before the app features. Mirror of "auth-mode" in run{Dev,Prod}App. */
+   *  (+ auth-self-registration when authOptions.signup is set) before the
+   *  app features. Mirror of "auth-mode" in run{Dev,Prod}App. */
   readonly includeBundled: boolean;
   /** Optional auth-feature-options durchgereicht an
    *  createAuthEmailPasswordFeature. Wenn passwordReset / emailVerification
@@ -75,6 +79,14 @@ export function composeFeatures(
     createUserFeature(),
     createTenantFeature(),
     createAuthEmailPasswordFeature(authOptions ?? {}),
+    // signup-request/signup-confirm are registered whenever authOptions.signup
+    // is set (see above), but the handler itself no-ops unless the companion
+    // toggle feature is mounted (ctx.hasFeature(AUTH_SELF_REGISTRATION_FEATURE))
+    // — without this, apps using the includeBundled convenience path get
+    // self-signup silently broken (always-200 anti-enumeration contract masks
+    // it as success). Mount it alongside signup, default ON, matching the
+    // "on unless an operator flips it off at runtime" contract.
+    ...(authOptions?.signup !== undefined ? [createAuthSelfRegistrationToggleFeature()] : []),
   ];
   const bundledNames = new Set(bundled.map((f) => f.name));
   const filteredApp: FeatureDefinition[] = [];

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

@@ -1,4 +1,5 @@
 import { makeAuthPaths } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import { resolveSessionStore } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { bindMfaRevokeAllOtherSessionsFromFeature } from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
 import { createSmtpTransportFromEnv } from "@cosmicdrift/kumiko-bundled-features/channel-email";
 import {
@@ -15,10 +16,7 @@ import {
   createSecretsContext,
   SECRETS_FEATURE_NAME,
 } from "@cosmicdrift/kumiko-bundled-features/secrets";
-import {
-  bindAutoRevokeFromFeature,
-  createSessionCallbacks,
-} from "@cosmicdrift/kumiko-bundled-features/sessions";
+import { bindAutoRevokeFromFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
 import { createTextContentApi } from "@cosmicdrift/kumiko-bundled-features/text-content";
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
@@ -38,7 +36,6 @@ import type {
   PasswordResetSetup,
   SignupSetup,
 } from "./run-prod-app";
-import type { ProdSessionsConfig } from "./session-wiring";
 
 // Boot-time context helpers for runProdApp: ctx-extra-context wiring
 // (textContent/delivery/secrets/config-resolver), auth-mail convenience
@@ -214,33 +211,27 @@ export function resolveAuthMail<T extends AuthMailNormalizable>(
   };
 }
 
-export function buildProdSessionAuth(
+export async function buildProdSessionAuth(
   db: DbConnection,
-  opts: ProdSessionsConfig,
+  registry: Registry,
   sessionsFeature: FeatureDefinition | undefined,
   mfaFeature: FeatureDefinition | undefined,
-): {
-  readonly sessionCreator: ReturnType<typeof createSessionCallbacks>["sessionCreator"];
-  readonly sessionRevoker: ReturnType<typeof createSessionCallbacks>["sessionRevoker"];
-  readonly sessionChecker: ReturnType<typeof createSessionCallbacks>["sessionChecker"];
-} {
-  const cbs = createSessionCallbacks({
-    db,
-    ...(opts.expiresInMs !== undefined && { expiresInMs: opts.expiresInMs }),
-  });
-  // Secure-by-default: password-change/-reset mass-revokes the user's live
-  // sessions without the app opting in via autoRevokeOnPasswordChange.
+): Promise<{
+  readonly sessionCreator: Awaited<ReturnType<typeof resolveSessionStore>>["creator"];
+  readonly sessionRevoker: Awaited<ReturnType<typeof resolveSessionStore>>["revoker"];
+  readonly sessionChecker: Awaited<ReturnType<typeof resolveSessionStore>>["checker"];
+}> {
+  // Resolve the sessions feature sessionStore provider (#1372).
+  const store = await resolveSessionStore({ db, registry });
   if (sessionsFeature) {
-    bindAutoRevokeFromFeature(sessionsFeature)?.(cbs.sessionMassRevoker);
+    bindAutoRevokeFromFeature(sessionsFeature)?.(store.massRevoker);
   }
-  // MFA enable/disable/regenerate mass-revokes every OTHER live session
-  // (stolen-session defense) — only wired when auth-mfa is mounted.
   if (mfaFeature) {
-    bindMfaRevokeAllOtherSessionsFromFeature(mfaFeature)?.(cbs.sessionRevokeAllOthers);
+    bindMfaRevokeAllOtherSessionsFromFeature(mfaFeature)?.(store.revokeAllOthers);
   }
   return {
-    sessionCreator: cbs.sessionCreator,
-    sessionRevoker: cbs.sessionRevoker,
-    sessionChecker: cbs.sessionChecker,
+    sessionCreator: store.creator,
+    sessionRevoker: store.revoker,
+    sessionChecker: store.checker,
   };
 }

package/src/run-prod-app-static-files.ts

@@ -43,7 +43,14 @@ export async function readStaticFile(
     const [bytes, fileStat] = await Promise.all([readFile(filePath), stat(filePath)]);
     return { bytes, mime: mimeTypeFor(filePath), mtimeMs: fileStat.mtimeMs };
   } catch (err) {
-    if ((err as { code?: string }).code === "ENOENT") return undefined;
+    const code = (err as { code?: string }).code;
+    // ENOENT: no such path. EISDIR: readFile() on a directory (e.g. GET
+    // /assets where "assets" is a subfolder copied verbatim from public/).
+    // ENOTDIR: a path segment that isn't a directory is used as one (e.g.
+    // GET /index.html/x — "index.html" is a file, not a directory) — all
+    // three mean "not a servable file", so fall through to the SPA
+    // fallback instead of a 500.
+    if (code === "ENOENT" || code === "EISDIR" || code === "ENOTDIR") return undefined;
     throw err;
   }
 }

package/src/run-prod-app.ts

@@ -27,6 +27,15 @@
 //   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)
+//   Adopting rotation for the first time (no JWT_SECRET_V<n> set yet): the
+//   plain JWT_SECRET above stays set and is carried into the keyring as a
+//   verify-only legacy key (loadJwtSecretOrKeyring), so sessions signed
+//   before the cutover keep verifying — no mass-logout at adoption. This
+//   legacy key never expires on its own (boot logs a warning while it's
+//   present) — once max token TTL has elapsed since cutover, unset
+//   JWT_SECRET to retire it. Check first whether an app relies on the
+//   auth.mail convenience default for passwordReset/emailVerification
+//   hmacSecret (falls back to this same JWT_SECRET) before unsetting it.
 //   PORT=3000
 //   KUMIKO_INSTANCE_ID=<stable per replica>
 
@@ -46,7 +55,9 @@ import {
   seedAdmin,
 } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
 import {
+  EXT_SESSION_STORE,
   EXT_TOKEN_VERIFIER,
+  resolveAnonymousAccessFromRegistry,
   resolveTokenVerifier,
 } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { AUTH_MFA_FEATURE, AuthMfaHandlers } from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
@@ -140,11 +151,7 @@ import {
 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,
-  shouldWireProdSessions,
-} from "./session-wiring";
+import { shouldWireProdSessions } from "./session-wiring";
 
 export { buildBunServeOptions } from "./bun-serve-options";
 export {
@@ -287,14 +294,6 @@ export type RunProdAppAuthOptions = {
   readonly admin: SeedAdminOptions;
   /** Optional override of the login error → HTTP status map. */
   readonly loginErrorStatusMap?: Readonly<Record<string, number>>;
-  /** 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 (sidless JWTs werden dann abgelehnt).
-   *
-   *  Standardverhalten ohne diese Option: stateless JWTs ohne sid
-   *  (legacy-Verhalten, Karten­haus existing-Apps unangefasst). */
-  readonly sessions?: ProdSessionsOption;
   /** Auth-Mail-Convenience: verdrahtet alle 4 Mail-Flows (passwordReset,
    *  emailVerification, signup, invite) aus `auth.mail.baseUrl` + Standard-
    *  Pfaden. Alle vier mailen via delivery (ctx.notify) — ersetzt das per-App
@@ -345,6 +344,13 @@ export type RunProdAppAuthOptions = {
    *  — accept the wide-cookie CSRF risk explicitly instead of setting
    *  `allowedOrigins`. */
   readonly unsafeSkipOriginCheck?: boolean;
+  /** Number of trusted reverse-proxy hops between the client and this
+   *  process for client-IP derivation (see AuthRoutesConfig.trustedProxyHops,
+   *  kumiko-framework#1539) — closes the X-Forwarded-For spoofing hole on
+   *  the auth rate-limiters. Falls back to the `KUMIKO_TRUSTED_PROXY_HOPS`
+   *  env var when unset; both unset means the pre-#1539 spoofable default
+   *  (0 hops). Set this to your real ingress hop count (typically 1). */
+  readonly trustedProxyHops?: number;
 };
 
 /** Hook for app-specific seeding — runs after the admin (when auth is
@@ -368,10 +374,8 @@ export type RunProdAppDeps = {
 };
 
 export type AnonymousAccessOption =
-  | import("@cosmicdrift/kumiko-framework/api").ServerOptions["anonymousAccess"]
-  | ((
-      deps: RunProdAppDeps,
-    ) => import("@cosmicdrift/kumiko-framework/api").ServerOptions["anonymousAccess"]);
+  | import("@cosmicdrift/kumiko-framework/api").AnonymousAccessConfig
+  | ((deps: RunProdAppDeps) => import("@cosmicdrift/kumiko-framework/api").AnonymousAccessConfig);
 
 export type ExtraContextOption =
   | Record<string, unknown>
@@ -621,6 +625,22 @@ export type ProdAppHandle = {
   readonly stop: () => Promise<void>;
 };
 
+let warnedLegacyJwtSecret = false;
+function warnLegacyJwtSecretOnce(): void {
+  // skip: already warned once this process — avoid log spam on every boot path.
+  if (warnedLegacyJwtSecret) return;
+  warnedLegacyJwtSecret = true;
+  // biome-ignore lint/suspicious/noConsole: boot-time ops hint, no logger configured this early
+  console.warn(
+    "[runProdApp] JWT keyring carries a legacy (pre-rotation) verify-only key — " +
+      "it never expires on its own. JWT_SECRET remains a required env (hmacSecret " +
+      "fallback + boot requireEnv). To stop verifying with the pre-rotation secret: " +
+      "set auth.mail.hmacSecret explicitly, then rotate JWT_SECRET to a fresh value " +
+      "that is no longer present in any in-flight token (see resolveAuthMail / " +
+      "loadJwtSecretOrKeyring).",
+  );
+}
+
 export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHandle> {
   // 0. Env-Schema validation + dry-run modes. Runs FIRST so:
   //    - operators can introspect env-requirements without a real boot
@@ -691,8 +711,36 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   // rotation of the session-JWT signing key — see loadJwtSecretOrKeyring.
   const jwtSecret = requireEnv("JWT_SECRET", envSource);
   const jwtSecretOrKeyring = loadJwtSecretOrKeyring(envSource);
+  if (typeof jwtSecretOrKeyring === "object" && Object.hasOwn(jwtSecretOrKeyring.keys, "legacy")) {
+    // Once per process — JWT_SECRET stays a required env (requireEnv above +
+    // resolveAuthMail hmacSecret fallback). Retiring the *legacy verify key*
+    // means setting auth.mail.hmacSecret explicitly and rotating JWT_SECRET
+    // to a fresh value that is no longer in any in-flight token; unsetting
+    // JWT_SECRET entirely hard-crashes boot.
+    warnLegacyJwtSecretOnce();
+  }
   const jwtIssuer = readEnv("JWT_ISSUER", envSource);
   const instanceId = readEnv("KUMIKO_INSTANCE_ID", envSource);
+  // kumiko-framework#1539 — options.auth.trustedProxyHops wins; falls back
+  // to the env var so ops can close the XFF-spoofing hole per-deployment
+  // without a code change (mirrors instanceId's env-first pattern above).
+  // Fail loud on a garbage env value rather than silently coercing to NaN:
+  // clientIpOf treats NaN like "always short chain" and returns "unknown"
+  // for every request, which collapses mfa-verify/preauth-confirm's
+  // pure-IP-keyed rate limiter into one shared bucket for the whole
+  // deployment — a self-inflicted DoS, worse than staying on the default.
+  const trustedProxyHopsFromEnv = readEnv("KUMIKO_TRUSTED_PROXY_HOPS", envSource);
+  const trustedProxyHops = ((): number | undefined => {
+    if (options.auth?.trustedProxyHops !== undefined) return options.auth.trustedProxyHops;
+    if (trustedProxyHopsFromEnv === undefined) return undefined;
+    const parsed = Number.parseInt(trustedProxyHopsFromEnv, 10);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+      throw new Error(
+        `runProdApp: KUMIKO_TRUSTED_PROXY_HOPS must be a non-negative integer, got "${trustedProxyHopsFromEnv}".`,
+      );
+    }
+    return parsed;
+  })();
   const port = options.port ?? Number.parseInt(envSource["PORT"] ?? "3000", 10);
 
   // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
@@ -726,12 +774,11 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
     mode: "prod",
   });
   const sessionsFeature = features.find((f) => f.name === SESSIONS_FEATURE);
+  const registry = createRegistry(features);
   assertSessionBootInvariants({
     hasAuth: Boolean(effectiveAuth),
-    sessionsFeatureMounted: sessionsFeature !== undefined,
-    sessionsOption: effectiveAuth?.sessions,
+    sessionStoreProviderMounted: registry.getExtensionUsages(EXT_SESSION_STORE).length > 0,
   });
-  const registry = createRegistry(features);
 
   // C1 boot-mode exit: validators ran + registry built; no DB/Redis client
   // is constructed at all in this branch (the eager `new Redis(...)` below
@@ -861,10 +908,15 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
     { ...autoExtraContext, ...resolvedExtraContext },
     registry,
   );
-  const resolvedAnonymousAccess =
+  const baseAnonymousAccess =
     typeof options.anonymousAccess === "function"
       ? options.anonymousAccess(deps)
       : options.anonymousAccess;
+  // #1374: tenantResolver / tenantExists come from auth-foundation providers.
+  const resolvedAnonymousAccess = await resolveAnonymousAccessFromRegistry(baseAnonymousAccess, {
+    db,
+    registry,
+  });
 
   // Sessions opt-in: db ist hier schon konkret (createDbConnection oben),
   // also direkt verdrahten — kein late-bound nötig wie bei runDevApp.
@@ -874,22 +926,13 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   // 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 +
-  // 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).
+  // Secure-by-default (#1372): sessionStore provider → resolveSessionStore.
   const mfaFeature = features.find((f) => f.name === AUTH_MFA_FEATURE);
   const sessionAuthFragment = shouldWireProdSessions(
     Boolean(effectiveAuth),
-    sessionsFeature !== undefined,
-    effectiveAuth?.sessions,
+    registry.getExtensionUsages(EXT_SESSION_STORE).length > 0,
   )
-    ? buildProdSessionAuth(
-        db,
-        resolveProdSessionsConfig(effectiveAuth?.sessions),
-        sessionsFeature,
-        mfaFeature,
-      )
+    ? await buildProdSessionAuth(db, registry, sessionsFeature, mfaFeature)
     : undefined;
 
   // Token-verifier opt-in: any provider feature (personal-access-tokens, a
@@ -970,17 +1013,32 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
         ...(effectiveAuth.unsafeSkipOriginCheck !== undefined && {
           unsafeSkipOriginCheck: effectiveAuth.unsafeSkipOriginCheck,
         }),
+        ...(trustedProxyHops !== undefined && { trustedProxyHops }),
         ...sessionAuthFragment,
         ...patAuthFragment,
         ...tenantLifecycleAuthFragment,
         ...(mfaFeature && {
           mfaVerifyHandler: AuthMfaHandlers.verify,
+          mfaPreauthEnableStartHandler: AuthMfaHandlers.enableStartPreauth,
+          mfaPreauthConfirmHandler: AuthMfaHandlers.enableConfirmPreauth,
           mfaVerifyRateLimit: createRedisLoginRateLimiter(
             redis,
             undefined,
             undefined,
             "mfa-verify",
           ),
+          mfaPreauthEnableStartRateLimit: createRedisLoginRateLimiter(
+            redis,
+            undefined,
+            undefined,
+            "mfa-preauth-start",
+          ),
+          mfaPreauthConfirmRateLimit: createRedisLoginRateLimiter(
+            redis,
+            undefined,
+            undefined,
+            "mfa-preauth-confirm",
+          ),
         }),
         ...(effectiveAuth.passwordReset && {
           passwordReset: {

package/src/session-boot-gate.ts

@@ -1,29 +1,20 @@
-import type { ProdSessionsOption } from "./session-wiring";
-
 export type SessionBootGateOptions = {
   readonly hasAuth: boolean;
-  readonly sessionsFeatureMounted: boolean;
-  readonly sessionsOption: ProdSessionsOption | undefined;
+  readonly sessionStoreProviderMounted: boolean;
 };
 
-// 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.
+// Catch a forgotten sessions mount at boot instead of silently degrading
+// into stateless JWTs (#1372). Mount createSessionsFeature() for revocable
+// sessions; there is no auth.sessions opt-out anymore.
 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;
+  // skip: sessionStore provider is wired (sessions feature).
+  if (opts.sessionStoreProviderMounted) 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.",
+    "[runProdApp] BOOT ABORTED — auth is mounted but no sessionStore provider is registered. " +
+      "JWTs would be stateless (no server-side revocation). Mount createSessionsFeature() " +
+      "(@cosmicdrift/kumiko-bundled-features/sessions) alongside auth-foundation.",
   );
 }