@cosmicdrift/kumiko-server-runtime 0.158.2 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "0.158.2",
+  "version": "1.0.0",
   "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.158.2",
-    "@cosmicdrift/kumiko-framework": "0.158.2",
+    "@cosmicdrift/kumiko-bundled-features": "1.0.0",
+    "@cosmicdrift/kumiko-framework": "1.0.0",
     "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,
@@ -790,7 +803,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 +820,7 @@ describe("runProdApp — auth allowedOrigins forwarding", () => {
           admin: ADMIN,
           cookieDomain: "example.eu",
           allowedOrigins: ["https://app.example.eu"],
+          sessions: false,
         },
       });
       expect(handle).toBeDefined();
@@ -819,6 +833,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 +988,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__/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,

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";
@@ -56,7 +65,9 @@ import {
   createRedisLoginRateLimiter,
   createSseBroker,
   type LoginRateLimiter,
+  loadJwtSecretOrKeyring,
   type SseBroker,
+  type TokenVerifier,
 } from "@cosmicdrift/kumiko-framework/api";
 import {
   configureBlindIndexKey,
@@ -128,6 +139,7 @@ import {
 } 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,
@@ -244,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). */
@@ -271,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). */
@@ -308,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. */
@@ -660,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);
@@ -695,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
@@ -832,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),
@@ -857,20 +892,24 @@ 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>;
+        tokenVerifier: TokenVerifier;
         patRateLimiter: LoginRateLimiter;
       }
     | undefined;
-  if (effectiveAuth && patFeature) {
+  if (effectiveAuth && patFeature && hasTokenVerifierProviders) {
     const rl = patRateLimitFromFeature(patFeature);
     patAuthFragment = {
-      patResolver: createPatResolver({ db, scopes: patScopesFromFeature(patFeature) }),
+      tokenVerifier: (rawToken) => resolveTokenVerifier({ db, registry }, rawToken),
       patRateLimiter: createRedisLoginRateLimiter(redis, rl.maxRequests, rl.windowMs, "pat"),
     };
   }
@@ -895,7 +934,7 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
       ...extraContext,
     },
     sseBroker,
-    jwtSecret,
+    jwtSecret: jwtSecretOrKeyring,
     ...(jwtIssuer && { jwtIssuer }),
     ...(instanceId && { instanceId }),
     dispatcherOptions: {
@@ -955,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,

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).
  */