@cosmicdrift/kumiko-server-runtime 0.328.1 → 0.330.0

package/dist/run-prod-app.js

@@ -0,0 +1,741 @@
+/// <reference types="bun-types" preserve="true" />
+// runProdApp — production-grade Bootstrap-Wrapper für Kumiko-Apps.
+//
+// Symmetrisch zu runDevApp, aber:
+//   - DATABASE_URL / REDIS_URL / JWT_SECRET aus env (fail-fast bei Boot,
+//     keine ephemeralen Test-DBs)
+//   - Hard Schema-Drift-Gate: prüft kumiko/migrations vs. _kumiko_migrations
+//     + tableExists für jede erwartete Tabelle. KEIN Auto-CREATE TABLE im
+//     Boot — Migration ist ein CI-Step (`bun kumiko schema apply`), Boot
+//     validiert nur. Verhindert Race-Conditions bei Multi-Replica-Deploys
+//     + macht Schema-Stand reviewbar in der Pull-Request.
+//   - Idempotente Seeds: laufen nur wenn DB leer (über `isDbEmpty`-Probe
+//     pro Seed). Re-Boots nach erstem Seed sind no-op.
+//   - HTTP-Server via Bun.serve mit graceful SIGTERM/SIGINT → drain().
+//   - Auth-Routes + bundled-features auto-mix wenn `auth:` gesetzt
+//     (gleiche Logik wie runDevApp).
+//
+// App-Author schreibt:
+//   await runProdApp({ features, auth, anonymousAccess, seeds });
+//
+// Container/Coolify setzt:
+//   DATABASE_URL=postgresql://...
+//   REDIS_URL=redis://...
+//   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)
+//   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>
+import { AuthErrors, AuthHandlers, AuthQueries, } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import { seedAdminGuarded, } 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";
+import { PAT_FEATURE, patRateLimitFromFeature, } 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";
+import { UserQueries } from "@cosmicdrift/kumiko-bundled-features/user";
+import { createDefaultSseBroker, createRedisLoginRateLimiter, loadJwtSecretOrKeyring, parseTrustedProxyHopsEnv, TRUSTED_PROXY_HOPS_ENV, } from "@cosmicdrift/kumiko-framework/api";
+import { configureBlindIndexKey, configurePiiSubjectKms, resolvePlatformKeks, } from "@cosmicdrift/kumiko-framework/crypto";
+import { configureEntityFieldEncryption, createDbConnection, } from "@cosmicdrift/kumiko-framework/db";
+import { collectWriteHandlerQns, createRegistry, findTierResolverUsage, validateAppCustomScreenWriteQns, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
+import { createAllInOneEntrypoint, createApiEntrypoint, } from "@cosmicdrift/kumiko-framework/entrypoint";
+import { KumikoBootError, kmsSlotsOf, parseEnv, } from "@cosmicdrift/kumiko-framework/env";
+import { renderDryRun } from "@cosmicdrift/kumiko-framework/env/dry-run";
+import { createEsOperationsTable, createSeedMigrationContext, runPendingSeedMigrations, } from "@cosmicdrift/kumiko-framework/es-ops";
+import { assertKumikoSchemaCurrent, SchemaDriftError, } from "@cosmicdrift/kumiko-framework/migrations";
+import { createDispatcher, createEntityCache, createEventDedup, createIdempotencyGuard, } from "@cosmicdrift/kumiko-framework/pipeline";
+import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
+import { Redis } from "ioredis";
+import { applyBootSeeds } from "./boot/apply-boot-seeds.js";
+import { resolveBootCrypto } from "./boot/boot-crypto.js";
+import { jobRunLoggerCallbacks } from "./boot/job-run-logger.js";
+import { startPiiEventBackfillOnBoot } from "./boot/pii-event-backfill-on-boot.js";
+import { buildBunServeOptions, resolveDerivedMaxRequestBodySize } from "./bun-serve-options.js";
+import { buildComposeAuthOptions, composeFeatures } from "./compose-features.js";
+import { makeDispatchSystemWrite } from "./extra-routes-deps.js";
+import { assertPiiBootInvariants } from "./pii-boot-gate.js";
+import { addConfigAccessorFactory, buildBootExtraContext, buildProdSessionAuth, resolveAuthMail, wireProdPatAutoRevoke, } from "./run-prod-app-boot-context.js";
+import { buildStaticFallback } from "./run-prod-app-static-files.js";
+import { withSecurityHeaders } from "./security-headers.js";
+import { assertSessionBootInvariants } from "./session-boot-gate.js";
+import { shouldWireProdSessions } from "./session-wiring.js";
+import { stripNoRouteMatchHeader } from "./try-hono-first.js";
+export { buildBunServeOptions } from "./bun-serve-options.js";
+export { addConfigAccessorFactory, buildBootExtraContext, resolveAuthMail, } from "./run-prod-app-boot-context.js";
+export { staticCachePolicy } from "./run-prod-app-static-files.js";
+// Strict env-var read. Throws with a clear hint when missing — better
+// than discovering a Postgres-connection-refused 30s into the boot.
+// `src` defaults to process.env but is threaded from the caller's envSource
+// so the boot-path reads the SAME env-quelle that was validated above —
+// injected dummies in test-mode must not silently fall back to process.env.
+export function requireEnv(name, src = process.env, context = "runProdApp") {
+    const value = src[name];
+    if (value === undefined || value === "") {
+        const advice = context === "runProdApp"
+            ? "Set it in your container env / .env.production / Coolify secrets."
+            : "Set it in your .env / shell before running the dev server.";
+        throw new Error(`${context}: required env var "${name}" is missing or empty. ${advice}`);
+    }
+    return value;
+}
+// Optional env helper — returns undefined for missing, string for set.
+// Used for KUMIKO_INSTANCE_ID, JWT_ISSUER and other "nice to have" knobs.
+function readEnv(name, src = process.env) {
+    const value = src[name];
+    return value === undefined || value === "" ? undefined : value;
+}
+function parseRunMode(raw) {
+    if (!raw)
+        return null;
+    const v = raw.toLowerCase();
+    if (v === "1" || v === "true" || v === "human")
+        return "human";
+    if (v === "json" || v === "pulumi" || v === "k8s" || v === "boot")
+        return v;
+    // biome-ignore lint/suspicious/noConsole: boot-time warn for typo discovery
+    console.warn(`[runProdApp] KUMIKO_DRY_RUN_ENV="${raw}" unrecognized ` +
+        `(expected 1|human|json|pulumi|k8s|boot); continuing with normal boot.`);
+    return null;
+}
+function isRenderMode(mode) {
+    return mode !== null && mode !== "boot";
+}
+function defaultBootErrorReporter(err) {
+    // biome-ignore lint/suspicious/noConsole: boot-time error, no logger configured yet
+    console.error(err.format());
+    process.exit(1);
+}
+// Returned from runProdApp when KUMIKO_DRY_RUN_ENV is set AND envSource
+// was passed (= test-mode). The handle is intentionally inert — listen()
+// and stop() are no-ops; tests inspect the dry-run console output and
+// move on.
+function makeDryRunHandle() {
+    const noop = async () => {
+        /* dry-run handle: no server was constructed */
+    };
+    return {
+        // @cast-boundary dry-run-mode: no ApiEntrypoint exists because no
+        // boot ran; the handle only surfaces test/CLI inspection and the
+        // entrypoint is never reached by callers in dry-run.
+        entrypoint: undefined,
+        fetch: () => new Response("dry-run", { status: 503 }),
+        webSocketUpgradeFetch: async () => new Response("dry-run", { status: 503 }),
+        listen: noop,
+        stop: noop,
+    };
+}
+let warnedLegacyJwtSecret = false;
+function warnLegacyJwtSecretOnce() {
+    // 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) {
+    // 0. Env-Schema validation + dry-run modes. Runs FIRST so:
+    //    - operators can introspect env-requirements without a real boot
+    //      (no DB connection needed, KUMIKO_DRY_RUN_ENV=… → render + exit)
+    //    - missing/invalid env-vars produce a structured KumikoBootError
+    //      with ALL problems aggregated (not first-fail), before we waste
+    //      seconds on a Postgres connection that was never configured.
+    //
+    //    Both code paths are no-ops when no envSchema is passed — Sprint-9
+    //    migration is per-feature additive; pre-migration apps keep the
+    //    legacy `requireEnv("DATABASE_URL")` checks below.
+    //
+    //    Ordering invariant: this step runs BEFORE the Temporal polyfill,
+    //    so env-schemas MUST use only Temporal-free Zod types. Don't author
+    //    `z.iso.date()`/`Temporal.Instant` fields on env-vars — they'd crash
+    //    at parse-time before the polyfill loads. Plain strings + .regex /
+    //    .min / .email / .url cover every env-var shape we've actually
+    //    needed in 9.1's audit (37 references, 25 distinct vars).
+    const rawEnvSource = options.envSource ?? process.env;
+    const runMode = parseRunMode(rawEnvSource["KUMIKO_DRY_RUN_ENV"]);
+    if (options.envSchema) {
+        if (isRenderMode(runMode)) {
+            // biome-ignore lint/suspicious/noConsole: dry-run output IS the deliverable
+            console.log(renderDryRun(options.envSchema, runMode, {
+                ...(options.pulumiPrefix ? { pulumiPrefix: options.pulumiPrefix } : {}),
+                sources: options.envSchema.sources,
+            }));
+            // Tests inject envSource and want a return-value, not exit. Detecting
+            // "this is a test" via envSource is brittle; instead exit when running
+            // against the real process.env (the deploy-flow), return otherwise.
+            if (options.envSource === undefined) {
+                process.exit(0);
+            }
+            return makeDryRunHandle();
+        }
+        // boot-mode AND normal-boot both run env-validation. boot-mode wants
+        // a real env-check (all required vars present + schema-valid) before
+        // it asserts feature-wiring works.
+        try {
+            parseEnv(options.envSchema.schema, rawEnvSource, {
+                sources: options.envSchema.sources,
+                ...(options.pulumiPrefix ? { pulumiPrefix: options.pulumiPrefix } : {}),
+            });
+        }
+        catch (err) {
+            if (err instanceof KumikoBootError) {
+                const reporter = options.bootErrorReporter ?? defaultBootErrorReporter;
+                reporter(err);
+            }
+            throw err;
+        }
+    }
+    // Slots the schema marks `kms` are decrypted once here so every consumer
+    // below (boot probe, master-key keyring, config) sees the same resolved env.
+    const envSource = options.envSchema
+        ? await resolvePlatformKeks(rawEnvSource, {
+            slots: kmsSlotsOf(options.envSchema.schema),
+            logPrefix: "[runProdApp]",
+        })
+        : rawEnvSource;
+    // 1. Polyfill before anything else — feature code references Temporal.
+    const { ensureTemporalPolyfill } = await import("@cosmicdrift/kumiko-framework/time");
+    await ensureTemporalPolyfill();
+    // 2. Env-vars: fail-fast. Better a 0s boot crash with a clear error
+    //    than a 30s timeout chasing a Postgres connection that was never
+    //    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);
+    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).
+    const trustedProxyHops = options.trustedProxyHops ??
+        options.auth?.trustedProxyHops ??
+        parseTrustedProxyHopsEnv(readEnv(TRUSTED_PROXY_HOPS_ENV, envSource), "runProdApp");
+    const port = options.port ?? Number.parseInt(envSource["PORT"] ?? "3000", 10);
+    // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
+    console.log(`[runProdApp] booting Kumiko stack on port ${port}…`);
+    // auth.mail → expandiert in die expliziten Flow-Felder, bevor sie sowohl
+    // die Feature-Side (buildComposeAuthOptions) als auch das Routes-Fragment
+    // unten speisen. Ab hier IMMER effectiveAuth statt options.auth lesen.
+    const effectiveAuth = options.auth
+        ? resolveAuthMail(options.auth, jwtSecret, envSource)
+        : undefined;
+    // 3. Feature registry. Auth-mode auto-mixes config/user/tenant/auth-email-
+    //    password via composeFeatures — same source-of-truth as runDevApp
+    //    AND the per-app drizzle-Schema-Generator, so Migration und Runtime
+    //    sehen exakt dieselbe Liste. Built BEFORE any connection so boot-mode
+    //    can validate wiring and exit without opening a Postgres/Redis socket.
+    const composeAuthOptions = buildComposeAuthOptions(effectiveAuth);
+    const features = composeFeatures(options.features, {
+        includeBundled: !!effectiveAuth,
+        ...(composeAuthOptions && { authOptions: composeAuthOptions }),
+    });
+    validateBoot(features, { env: envSource, ...options.validateBootOptions });
+    warnIfNonUtcServerTimeZone();
+    validateAppCustomScreenWriteQns(process.cwd(), collectWriteHandlerQns(features));
+    assertPiiBootInvariants(features, {
+        kms: options.kms,
+        blindIndexKey: options.blindIndexKey,
+        allowPlaintextPii: options.allowPlaintextPii,
+        mode: "prod",
+    });
+    const sessionsFeature = features.find((f) => f.name === SESSIONS_FEATURE);
+    const registry = createRegistry(features);
+    assertSessionBootInvariants({
+        hasAuth: Boolean(effectiveAuth),
+        sessionStoreProviderMounted: registry.getExtensionUsages(EXT_SESSION_STORE).length > 0,
+        mode: "prod",
+    });
+    // C1 boot-mode exit: validators ran + registry built; no DB/Redis client
+    // is constructed at all in this branch (the eager `new Redis(...)` below
+    // would otherwise open a TCP connect just to immediately disconnect it).
+    if (runMode === "boot") {
+        // biome-ignore lint/suspicious/noConsole: boot-mode output IS the deliverable
+        console.log(`[runProdApp] boot validation OK (${features.length} features, ${registry.features.size} registry entries)`);
+        if (options.envSource === undefined) {
+            process.exit(0);
+        }
+        return makeDryRunHandle();
+    }
+    // 4. Connections — Postgres + Redis. The Redis client is shared by
+    //    idempotency, event-dedup, entity-cache, rate-limit; failing to
+    //    construct here surfaces the misconfig immediately. `new Redis(...)`
+    //    connects eagerly, so it must stay AFTER the boot-mode exit above.
+    // KMS health gate: an app configured for crypto-shredding must not boot
+    // against an unreachable key store — a silent start would answer every
+    // PII read with 503. Runs BEFORE connections so an abort leaks nothing.
+    if (options.kms) {
+        const kmsHealth = await options.kms.health();
+        if (!kmsHealth.ok) {
+            throw new Error(`[runProdApp] BOOT ABORTED — KMS health check failed (latency ${kmsHealth.latencyMs}ms)`);
+        }
+    }
+    const { db, close: closeDb } = createDbConnection(databaseUrl);
+    const redis = new Redis(redisUrl, { maxRetriesPerRequest: null });
+    // Sprint-8a Tier-Composition auto-wire: scan features for a
+    // tenantTierResolver-extension. If found AND user didn't supply own
+    // effectiveFeatures, build the resolver here (db + registry are
+    // available) before the dispatcher is constructed. App-Author sees
+    // nothing — `createTierEngineFeature(opts)` mounts + framework auto-wires.
+    let resolvedEffectiveFeatures = options.effectiveFeatures;
+    if (resolvedEffectiveFeatures === undefined) {
+        const tierResolverUsage = findTierResolverUsage(features);
+        if (tierResolverUsage) {
+            const plugin = tierResolverUsage.options;
+            resolvedEffectiveFeatures = await plugin.build({ db, registry });
+        }
+    }
+    // 5. Schema-Drift-Gate (drizzle-frei, kumiko/migrations). `kumiko schema
+    //    apply` läuft als Deploy-Step VOR dem Container-Rollout. Boot prüft nur:
+    //      (a) Alle Migrations aus kumiko/migrations/*.sql sind in
+    //          _kumiko_migrations applied (+ checksum unverändert)
+    //      (b) Alle Tabellen aus kumiko/migrations/.snapshot.json existieren
+    //    Drift = Boot-Error mit klarer Meldung (kein Auto-Heal — mehrere
+    //    Container-Replicas würden sonst race-conditionen fahren). Opt-out via
+    //    `migrations: false` für custom Schema-Setups.
+    if (options.migrations !== false) {
+        const migrationsDir = options.migrations?.dir ?? "./kumiko/migrations";
+        // biome-ignore lint/suspicious/noConsole: boot-time progress hint
+        console.log(`[runProdApp] checking schema drift (${migrationsDir})…`);
+        try {
+            await assertKumikoSchemaCurrent(db, migrationsDir);
+        }
+        catch (err) {
+            if (err instanceof SchemaDriftError) {
+                // biome-ignore lint/suspicious/noConsole: terminal error message
+                console.error(`\n[runProdApp] BOOT ABORTED — ${err.message}\n`);
+            }
+            throw err;
+        }
+    }
+    // 6. Pipeline pieces — same default config as runDevApp's setupTestStack.
+    const idempotency = createIdempotencyGuard(redis, { ttlSeconds: 60 });
+    const eventDedup = createEventDedup(redis, { ttlSeconds: 60 });
+    const entityCache = createEntityCache(redis, { ttlSeconds: 60 });
+    // 7. Lifecycle is built by createApiEntrypoint when not supplied —
+    //    we let the entrypoint own it and read it back through the handle
+    //    for SIGTERM.
+    //
+    // extraContext + anonymousAccess sind factory-union: entweder direktes
+    // Object oder Function die {db, redis, registry} bekommt und das Object
+    // returned. Factory-Form gilt als bevorzugt für Cases die zur Boot-Zeit
+    // gegen die DB resolven müssen (z.B. Subdomain-Tenant-Lookup im
+    // tenantResolver) — die Factory closure'd `db` und der Resolver kann
+    // sie zur Request-Zeit aufrufen.
+    // Build the sseBroker here (instead of letting createApiEntrypoint do it
+    // internally) so extraContext factories can close over it at boot time —
+    // e.g. an extraContext provider that publishes SSE events directly. We
+    // pass the same broker into createApiEntrypoint (sseBroker? option) so
+    // the server-internal broadcast and app-specific publishes run over
+    // exactly one broker. createDefaultSseBroker (not createSseBroker
+    // directly) is what makes that broker Redis-backed under REDIS_URL —
+    // an unconditional in-memory broker here would silently win over
+    // buildServer's own REDIS_URL default (ServerOptions.sseBroker always
+    // wins), which is exactly how fw#2630's cross-replica fanout fix shipped
+    // without ever taking effect in production.
+    const { sseBroker, ownedRedisSseBroker } = createDefaultSseBroker(envSource);
+    const deps = { db, redis, registry, sseBroker };
+    const resolvedExtraContext = typeof options.extraContext === "function"
+        ? options.extraContext(deps)
+        : (options.extraContext ?? {});
+    // Framework-Default-Provider zuerst, App-Werte (resolvedExtraContext)
+    // gewinnen immer (z.B. money-horse's eigener configResolver).
+    const bootCrypto = resolveBootCrypto(envSource, options.masterKey);
+    // App-wide cipher for `encrypted: true` entity fields — executors resolve
+    // it lazily, entities without encrypted fields never touch it.
+    configureEntityFieldEncryption(bootCrypto.entityFieldCipher);
+    // Subject-key KMS for pii-annotated fields (crypto-shredding, #724).
+    // No adapter = engine off, plaintext as before — the warning keeps the gap
+    // visible until the prod-grade PgKmsAdapter (phase E) makes a hard boot
+    // gate viable (InMemory in prod would lose every DEK on restart).
+    configurePiiSubjectKms(options.kms);
+    // Blind-Index-Key (#818) — Boot-Gate: mit aktivem KMS würden lookupable-
+    // Felder als Ciphertext gespeichert, ohne Key gäbe es keinen bidx-Arm und
+    // jeder Equality-Lookup (Login by email!) liefe ins Leere. Fail-fast statt
+    // silent-broken-auth.
+    configureBlindIndexKey(options.blindIndexKey);
+    const autoExtraContext = buildBootExtraContext({
+        db,
+        features,
+        envSource,
+        registry,
+        hasAuth: !!effectiveAuth,
+        sseBroker,
+        crypto: bootCrypto,
+        ...(options.kms && { kms: options.kms }),
+    });
+    const extraContext = {
+        ...addConfigAccessorFactory({ ...autoExtraContext, ...resolvedExtraContext }, registry),
+        ...(options.defaultLocale !== undefined && { defaultLocale: options.defaultLocale }),
+    };
+    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.
+    // 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 (#1372): sessionStore provider → resolveSessionStore.
+    const mfaFeature = features.find((f) => f.name === AUTH_MFA_FEATURE);
+    // Hoisted above buildProdSessionAuth: that call also wires MFA-enable/
+    // disable → PAT-revoke (bindRevokeAllPatTokensFromFeature), so it needs
+    // patFeature too.
+    const patFeature = features.find((f) => f.name === PAT_FEATURE);
+    const sessionAuthFragment = shouldWireProdSessions(Boolean(effectiveAuth), registry.getExtensionUsages(EXT_SESSION_STORE).length > 0)
+        ? await buildProdSessionAuth(db, registry, sessionsFeature, mfaFeature, patFeature)
+        : undefined;
+    // Password-change → PAT-revoke: independent of sessions/MFA being mounted
+    // (buildProdSessionAuth only runs when a sessionStore provider is
+    // registered), so wired unconditionally here whenever PAT itself is.
+    if (patFeature) {
+        wireProdPatAutoRevoke(db, patFeature);
+    }
+    // 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 hasTokenVerifierProviders = registry.getExtensionUsages(EXT_TOKEN_VERIFIER).length > 0;
+    let patAuthFragment;
+    if (effectiveAuth && patFeature && hasTokenVerifierProviders) {
+        const rl = patRateLimitFromFeature(patFeature);
+        patAuthFragment = {
+            tokenVerifier: (rawToken) => resolveTokenVerifier({ db, registry }, rawToken),
+            patRateLimiter: createRedisLoginRateLimiter(redis, rl.maxRequests, rl.windowMs, "pat"),
+        };
+    }
+    const baseEntrypointOptions = {
+        registry,
+        context: {
+            db,
+            redis,
+            entityCache,
+            registry,
+            ...extraContext,
+        },
+        sseBroker,
+        jwtSecret: jwtSecretOrKeyring,
+        ...(jwtIssuer && { jwtIssuer }),
+        ...(instanceId && { instanceId }),
+        dispatcherOptions: {
+            idempotency,
+            ...(resolvedEffectiveFeatures && { effectiveFeatures: resolvedEffectiveFeatures }),
+        },
+        eventDedup,
+        ...(options.observability && { observability: options.observability }),
+        ...(options.observabilityOptions && { observabilityOptions: options.observabilityOptions }),
+        ...(options.metrics && { metrics: options.metrics }),
+        ...(options.rateLimit && { rateLimit: options.rateLimit }),
+        ...(trustedProxyHops !== undefined && { trustedProxyHops }),
+        ...(options.extraRoutes && { extraRoutes: options.extraRoutes }),
+        ...(effectiveAuth && {
+            auth: {
+                membershipQuery: TenantQueries.memberships,
+                userQuery: UserQueries.findForAuth,
+                loginHandler: AuthHandlers.login,
+                loginErrorStatusMap: effectiveAuth.loginErrorStatusMap ?? {
+                    [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,
+                }),
+                ...(effectiveAuth.allowedOrigins !== undefined && {
+                    allowedOrigins: effectiveAuth.allowedOrigins,
+                }),
+                ...(effectiveAuth.unsafeSkipOriginCheck !== undefined && {
+                    unsafeSkipOriginCheck: effectiveAuth.unsafeSkipOriginCheck,
+                }),
+                ...(trustedProxyHops !== undefined && { trustedProxyHops }),
+                ...(effectiveAuth.postAuthLanding !== undefined && {
+                    postAuthLanding: effectiveAuth.postAuthLanding,
+                }),
+                ...sessionAuthFragment,
+                ...patAuthFragment,
+                ...(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: {
+                        requestHandler: AuthHandlers.requestPasswordReset,
+                        confirmHandler: AuthHandlers.resetPassword,
+                    },
+                }),
+                ...(effectiveAuth.emailVerification && {
+                    emailVerification: {
+                        requestHandler: AuthHandlers.requestEmailVerification,
+                        confirmHandler: AuthHandlers.verifyEmail,
+                    },
+                }),
+                ...(effectiveAuth.accountUnlock && {
+                    accountUnlock: {
+                        requestHandler: AuthHandlers.requestAccountUnlock,
+                        confirmHandler: AuthHandlers.confirmAccountUnlock,
+                    },
+                }),
+                ...(effectiveAuth.signup && {
+                    signup: {
+                        requestHandler: AuthHandlers.signupRequest,
+                        confirmHandler: AuthHandlers.signupConfirm,
+                    },
+                }),
+                ...(effectiveAuth.invite && {
+                    invite: {
+                        acceptHandler: AuthHandlers.inviteAccept,
+                        acceptWithLoginHandler: AuthHandlers.inviteAcceptWithLogin,
+                        signupCompleteHandler: AuthHandlers.inviteSignupComplete,
+                        infoHandler: AuthQueries.inviteInfo,
+                    },
+                }),
+            },
+        }),
+        ...(resolvedAnonymousAccess && { anonymousAccess: resolvedAnonymousAccess }),
+    };
+    // Deploy-Topologie. Default (Single-Container): createAllInOneEntrypoint
+    // fährt HTTP + BEIDE Job-Lanes (zwei Runner, jeder schedult seine eigene
+    // Lane-Crons → kein Double-Fire) + Event-Dispatcher inline. So laufen
+    // worker-Lane-Crons (run-export-jobs default runIn:"worker") UND MSPs ohne
+    // separaten Worker-Process — die Asymmetrie, an der der Daten-Export hing.
+    // runSingleInstance:false → API-only; ein dezidierter Worker MUSS dann die
+    // worker-Lane + MSPs übernehmen (api-Lane-Jobs laufen weiter lokal).
+    // Default single-instance. eventDispatcher.disabled ist die Alt-Art, MSPs
+    // diesem Prozess wegzunehmen (dezidierter Worker) — als runSingleInstance:
+    // false honorieren (api-only, kein lokaler Dispatcher), damit der explizite
+    // Flag Vorrang behält aber Bestands-Caller nicht brechen.
+    const runSingleInstance = options.runSingleInstance ?? options.eventDispatcher?.disabled !== true;
+    const hasJobs = registry.getAllJobs().size > 0;
+    const queueNamePrefix = options.jobs?.queueNamePrefix;
+    const jobLogger = jobRunLoggerCallbacks(registry, db);
+    const dispatcherTunables = options.eventDispatcher?.pollIntervalMs !== undefined
+        ? { pollIntervalMs: options.eventDispatcher.pollIntervalMs }
+        : {};
+    const entrypoint = runSingleInstance
+        ? createAllInOneEntrypoint({
+            ...baseEntrypointOptions,
+            redisUrl,
+            ...jobLogger,
+            ...(queueNamePrefix !== undefined && { queueNamePrefix }),
+            ...(options.jobs?.getActiveTenantIds !== undefined && {
+                getActiveTenantIds: options.jobs.getActiveTenantIds,
+            }),
+            ...(!options.eventDispatcher?.disabled && { eventDispatcher: dispatcherTunables }),
+        })
+        : createApiEntrypoint({
+            ...baseEntrypointOptions,
+            ...(hasJobs && {
+                jobs: {
+                    redisUrl,
+                    runLocalJobs: true,
+                    ...jobLogger,
+                    ...(queueNamePrefix !== undefined && { queueNamePrefix }),
+                    ...(options.jobs?.getActiveTenantIds !== undefined && {
+                        getActiveTenantIds: options.jobs.getActiveTenantIds,
+                    }),
+                },
+            }),
+        });
+    // The broker built above is always ours (runProdApp never accepts a
+    // caller-supplied sseBroker), so — same reasoning as buildServer's own
+    // ownedRedisSseBroker hook — closing it on shutdown is our job, not the
+    // entrypoint's. Registered after createApiEntrypoint/createAllInOneEntrypoint
+    // (which already registered the eventDispatcher/jobRunner hooks above),
+    // so it drains LIFO before those, matching the close-before-teardown
+    // order fw#2630 established for buildServer's own hook.
+    if (ownedRedisSseBroker) {
+        const broker = ownedRedisSseBroker;
+        entrypoint.lifecycle.registerShutdownHook("prodAppRedisSseBroker", async () => {
+            await broker.close();
+        });
+    }
+    // `extraRoutes` itself is already mounted — buildServer wires it inside
+    // createApiEntrypoint/createAllInOneEntrypoint, before this function ever
+    // runs. `wire` is the remaining escape-hatch for app-wired co-running
+    // components that need the system-write dispatcher but don't declare a
+    // route (kumiko-framework#3050).
+    if (options.wire) {
+        await options.wire({
+            db,
+            redis,
+            registry,
+            dispatchSystemWrite: makeDispatchSystemWrite(entrypoint.dispatcher),
+        });
+    }
+    // 9. Seeds: admin first, then config-seeds from r.config({seeds}),
+    //    then app-specific. All idempotent — runProdApp doesn't gate
+    //    "first boot" via flag, every seed-step checks its own
+    //    preconditions. Config-seeds rely on a deterministic
+    //    aggregate-id so re-boot becomes a version_conflict skip.
+    if (effectiveAuth) {
+        await seedAdminGuarded(db, effectiveAuth.admin);
+    }
+    await applyBootSeeds({
+        registry,
+        db,
+        ...(bootCrypto.configCipher && { cipher: bootCrypto.configCipher }),
+    });
+    for (const seed of options.seeds ?? []) {
+        await seed({ db });
+    }
+    // ES-Operations / Seed-Migrations (Phase 1). Läuft NACH applyBootSeeds +
+    // existing seeds-array — die deklarativen Seeds sind die "always-insert-
+    // if-missing"-Schicht; seed-migrations sind die "diff-and-update"-
+    // Schicht für Drift den existing Seeds nicht erfassen können (z.B.
+    // Membership-Roles-Change nach initialer Seed-Erstellung).
+    if (options.seedsDir !== undefined && envSource["KUMIKO_SKIP_ES_OPS"] !== "1") {
+        await createEsOperationsTable(db);
+        const seedDispatcher = createDispatcher(registry, {
+            db,
+            redis,
+            entityCache,
+            registry,
+            ...extraContext,
+        });
+        await runPendingSeedMigrations({
+            db,
+            seedsDir: options.seedsDir,
+            appliedBy: "boot",
+            registry, // → dry-run-validator catched handler-QN-typos vor dem write
+            // @wrapper-known semantic-alias
+            createContext: (dbRunner) => createSeedMigrationContext({ dispatcher: seedDispatcher, dbRunner }),
+        });
+    }
+    await entrypoint.start();
+    startPiiEventBackfillOnBoot({
+        db,
+        registry,
+        lifecycle: entrypoint.lifecycle,
+        envSource,
+    });
+    // 11. Build the fetch-handler. Static-fallback for non-/api/ paths
+    //     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 = withSecurityHeaders(options.staticDir
+        ? buildStaticFallback(entrypoint.app.fetch.bind(entrypoint.app), options.staticDir, options.hostDispatch, options.resolvePageHead
+            ? { resolvePageHead: options.resolvePageHead, dispatcher: entrypoint.dispatcher }
+            : undefined, entrypoint.dispatcher, trustedProxyHops ?? 0)
+        : // No staticDir (split-deploy / API-only container) → app.fetch's
+            // response goes straight to the client, bypassing buildStaticFallback
+            // (and with it tryHonoFirst) entirely. Must strip the router-miss
+            // marker here too, same reason as the /api/* passthrough in
+            // run-prod-app-static-files.ts (see try-hono-first.ts).
+            async (req, socketAddress) => stripNoRouteMatchHeader(await entrypoint.app.fetch(req, socketAddress)), options.securityHeaders);
+    // 11. Mark lifecycle ready — health/ready flips to 200 after this.
+    entrypoint.lifecycle.markReady();
+    // Upgrade rejections (401/403/426...) are ordinary responses and get the same headers as fetchHandler.
+    const securedUpgradeFetch = withSecurityHeaders(async (req, env) => stripNoRouteMatchHeader(await entrypoint.app.fetch(req, env)), options.securityHeaders);
+    const webSocketUpgradeFetch = async (req, env) => securedUpgradeFetch(req, env);
+    const handle = {
+        entrypoint,
+        fetch: fetchHandler,
+        webSocketUpgradeFetch,
+        listen: async (listenPort = port) => {
+            // Bun.serve is the production HTTP. Tests don't call listen()
+            // because vitest runs under Node where Bun.serve doesn't exist.
+            // Options-Shape (inkl. idleTimeout: 0 für SSE) liegt in der
+            // exportierten buildBunServeOptions-Funktion — siehe ihren
+            // Header für die Begründung.
+            if (typeof globalThis.Bun === "undefined") {
+                // Klare Fehlermeldung statt nackter ReferenceError. Trifft wenn
+                // jemand listen() unter Node/vitest aufruft ohne autoListen:false
+                // — hilft beim Debug, statt sich an "Bun is not defined" abzumühen.
+                throw new Error("[runProdApp] listen() requires Bun runtime (Bun.serve). " +
+                    "Under Node/vitest pass `autoListen: false` and call the returned `fetch()` directly.");
+            }
+            handle.server = Bun.serve(buildBunServeOptions(listenPort, fetchHandler, options.maxRequestBodySize ?? resolveDerivedMaxRequestBodySize(registry), { upgradeFetch: webSocketUpgradeFetch }));
+            // SIGTERM/SIGINT — graceful shutdown. Only registered when we
+            // actually own a Bun-server, otherwise the test process picks up
+            // signals it shouldn't respond to.
+            let shuttingDown = false;
+            const shutdown = async (signal) => {
+                // skip: shutdown already in progress, avoid double-drain
+                if (shuttingDown)
+                    return;
+                shuttingDown = true;
+                // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
+                console.log(`[runProdApp] ${signal} received — draining…`);
+                try {
+                    await handle.stop();
+                    // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
+                    console.log("[runProdApp] graceful shutdown complete.");
+                }
+                catch (e) {
+                    // biome-ignore lint/suspicious/noConsole: shutdown-time error, only path is stderr
+                    console.error("[runProdApp] error during shutdown:", e);
+                }
+                finally {
+                    process.exit(0);
+                }
+            };
+            process.on("SIGTERM", () => void shutdown("SIGTERM"));
+            process.on("SIGINT", () => void shutdown("SIGINT"));
+            // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
+            console.log(`[runProdApp] ready on http://0.0.0.0:${listenPort}`);
+        },
+        stop: async () => {
+            await entrypoint.stop();
+            handle.server?.stop();
+            await closeDb();
+            redis.disconnect();
+        },
+    };
+    // 12. Auto-listen unless explicitly suppressed (tests pass autoListen:
+    //     false because Bun.serve isn't available under vitest/node).
+    //     Production path: `await runProdApp({...})` and the server is up.
+    if (options.autoListen !== false) {
+        await handle.listen();
+    }
+    return handle;
+}