@cosmicdrift/kumiko-server-runtime 0.386.0 → 0.388.0

package/dist/fatal-error-handlers.js

@@ -16,6 +16,7 @@ export function installFatalErrorHandlers(options) {
     const exit = options.exit ?? ((code) => process.exit(code));
     const hardExitMs = options.hardExitMs ?? DEFAULT_HARD_EXIT_MS;
     let handling = false;
+    let stopRunning = false;
     const handle = (source) => (reason) => {
         // skip: a second fault during shutdown is already covered by the running stop and hard-exit timer
         if (handling)
@@ -28,11 +29,13 @@ export function installFatalErrorHandlers(options) {
         });
         const hardExitTimer = setTimeout(() => exit(1), hardExitMs);
         hardExitTimer.unref();
+        stopRunning = true;
         void stop()
             .catch((stopError) => {
             logger.error("shutdown after fatal error failed", describeFatal(stopError));
         })
             .finally(() => {
+            stopRunning = false;
             clearTimeout(hardExitTimer);
             exit(1);
         });
@@ -42,6 +45,10 @@ export function installFatalErrorHandlers(options) {
     process.on("uncaughtException", onUncaughtException);
     process.on("unhandledRejection", onUnhandledRejection);
     return () => {
+        // stop() uninstalls first; during a fatal shutdown the listeners must stay so a second fault cannot hit the default crash path mid-flush
+        // skip: fatal shutdown in progress, see above.
+        if (stopRunning)
+            return;
         process.off("uncaughtException", onUncaughtException);
         process.off("unhandledRejection", onUnhandledRejection);
     };

package/dist/index.js

@@ -1,7 +1,7 @@
-// Public API für den Kumiko-Production-Server-Boot. Symmetrisch zu
-// runDevApp (kumiko-dev-server), aber ohne Dev-/Scaffold-/Codegen-
-// Tooling (ts-morph) als Dependency — Prod-Apps ziehen so kein
-// Dev-Tooling mehr in ihre node_modules.
+// Public API for Kumiko's production-server boot. Symmetric with
+// runDevApp (kumiko-dev-server), but without Dev/Scaffold/Codegen
+// tooling (ts-morph) as a dependency, so production apps do not pull
+// development tooling into their node_modules.
 export { resolveBillingOption } from "./boot-options/billing-option.js";
 export { buildDemoModeRoute, withDemoReadOnlyFetch, } from "./boot-options/demo-mode.js";
 export { resolveFeatureTogglesOption, } from "./boot-options/feature-toggles-option.js";

package/dist/pii-boot-gate.js

@@ -13,7 +13,7 @@ export function assertPiiBootInvariants(features, opts) {
     const piiEntities = features.flatMap((feature) => Object.entries(feature.entities ?? {})
         .filter(([, entity]) => collectPiiSubjectFields(entity).length > 0)
         .map(([name]) => name));
-    // fw#2776: a declared event stance is worth as much as an entity annotation —
+    // A declared event stance is worth as much as an entity annotation —
     // encryptEventPayloadPii no-ops without a KMS, so a catalogued event writes
     // plaintext PII into kumiko_events with nothing to crypto-shred later.
     const piiEvents = features.flatMap((feature) => Object.values(feature.events ?? {})

package/dist/require-env.d.ts

@@ -0,0 +1,2 @@
+export declare function requireEnv(name: string, src?: Record<string, string | undefined>, context?: string): string;
+export declare function readEnv(name: string, src?: Record<string, string | undefined>): string | undefined;

package/dist/require-env.js

@@ -0,0 +1,21 @@
+// 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.
+export function readEnv(name, src = process.env) {
+    const value = src[name];
+    return value === undefined || value === "" ? undefined : value;
+}

package/dist/resolve-tailwind-cli.js

@@ -1,11 +1,9 @@
-// Resolved den lokal installierten @tailwindcss/cli-Bin auf seinen
-// absoluten Dateipfad. Wir vermeiden `bunx`, weil das auch bei lokal
-// installiertem Package noch das Registry-Manifest fragt und ohne Netz
-// mit `FailedToOpenSocket` stirbt.
+// Resolves the locally installed @tailwindcss/cli binary to its absolute path.
+// We avoid `bunx` because it still requests the registry manifest for a locally
+// installed package and fails with `FailedToOpenSocket` when offline.
 //
-// Ausgelagert aus create-kumiko-server.ts, damit unter vitest/Node
-// testbar (Bun-Branch + Resolve-Fail-Branch) ohne den Server zu
-// booten.
+// Kept separate from create-kumiko-server.ts so the Bun and resolution-failure
+// branches can be tested under Vitest/Node without booting the server.
 import { dirname, resolve } from "node:path";
 export function resolveTailwindCli(deps) {
     if (deps.bun === undefined)

package/dist/run-bootstrap.d.ts

@@ -1,5 +1,5 @@
 import { type BootstrapPlan, type BootstrapReport } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
-import { type RunProdAppAuthOptions } from "./run-prod-app.ts";
+import type { RunProdAppAuthOptions } from "./run-prod-app.ts";
 import type { RunWorkerAppOptions } from "./run-worker-app.ts";
 export type RunBootstrapOptions = Omit<RunWorkerAppOptions, "wireComponents" | "includeBundled" | "jobs" | "eventDispatcher" | "metrics"> & BootstrapPlan & {
     /** The same auth block the app passes to runProdApp (`admin` is ignored).

package/dist/run-bootstrap.js

@@ -12,7 +12,7 @@
 import { bootstrapTenants, } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
 import { bootWorkerProcess, resolveWorkerEnvSource } from "./boot/worker-boot-core.js";
 import { buildComposeAuthOptions } from "./compose-features.js";
-import { requireEnv } from "./run-prod-app.js";
+import { requireEnv } from "./require-env.js";
 import { resolveAuthMail } from "./run-prod-app-boot-context.js";
 const PROCESS_NAME = "runBootstrap";
 function maskEmailForLog(email) {

package/dist/run-prod-app-auth.d.ts

@@ -0,0 +1,17 @@
+import { type AuthRoutesConfig, type LoginRateLimiter, type TokenVerifier } from "@cosmicdrift/kumiko-framework/api";
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { buildProdSessionAuth } from "./run-prod-app-boot-context.ts";
+import type { ProdBootConfig, ProdComposedFeatures } from "./run-prod-app-config.ts";
+import type { ProdConnections } from "./run-prod-app-connections.ts";
+type PatAuthFragment = {
+    readonly tokenVerifier: TokenVerifier;
+    readonly patRateLimiter: LoginRateLimiter;
+};
+export type ProdAuthWiring = {
+    readonly mfaFeature: FeatureDefinition | undefined;
+    readonly sessionAuthFragment: Awaited<ReturnType<typeof buildProdSessionAuth>> | undefined;
+    readonly patAuthFragment: PatAuthFragment | undefined;
+};
+export declare function wireProdAuth(config: ProdBootConfig, composed: ProdComposedFeatures, connections: ProdConnections): Promise<ProdAuthWiring>;
+export declare function buildProdAuthRoutes(effectiveAuth: NonNullable<ProdComposedFeatures["effectiveAuth"]>, config: ProdBootConfig, composed: ProdComposedFeatures, connections: ProdConnections, authWiring: ProdAuthWiring): AuthRoutesConfig;
+export {};

package/dist/run-prod-app-auth.js

@@ -0,0 +1,83 @@
+import { EXT_SESSION_STORE, EXT_TOKEN_VERIFIER, resolveTokenVerifier, } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { AUTH_MFA_FEATURE, bindMfaTokenSecretsFromFeature, } from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
+import { PAT_FEATURE, patRateLimitFromFeature, } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
+import { UserQueries } from "@cosmicdrift/kumiko-bundled-features/user";
+import { createRedisLoginRateLimiter, } from "@cosmicdrift/kumiko-framework/api";
+import { assertMfaSwitchTenantGate, buildSharedAuthRoutes } from "./boot/shared-boot-steps.js";
+import { buildProdSessionAuth, wireProdPatAutoRevoke } from "./run-prod-app-boot-context.js";
+import { shouldWireProdSessions } from "./session-wiring.js";
+// Sessions are wired directly because db has already been created; unlike
+// runDevApp, no late binding is needed. Once a sessionChecker is wired, JWTs
+// without sid are rejected, so production sessions cannot be bypassed.
+// sessionMassRevoker (the fourth callback from createSessionCallbacks) is not
+// part of AuthRoutesConfig; bindAutoRevokeFromFeature hands it to the sessions
+// feature so password change and reset revoke all sessions. Secure by default: the sessionStore provider
+// goes through resolveSessionStore.
+export async function wireProdAuth(config, composed, connections) {
+    const { features, registry, effectiveAuth, sessionsFeature } = composed;
+    const { db, redis } = connections;
+    const mfaFeature = features.find((f) => f.name === AUTH_MFA_FEATURE);
+    if (mfaFeature) {
+        bindMfaTokenSecretsFromFeature(mfaFeature)?.(config.jwtSecret, config.envSource);
+        assertMfaSwitchTenantGate(registry, "runProdApp");
+    }
+    // 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"),
+        };
+    }
+    return { mfaFeature, sessionAuthFragment, patAuthFragment };
+}
+function buildMfaRateLimits(redis) {
+    return {
+        mfaVerifyRateLimit: createRedisLoginRateLimiter(redis, undefined, undefined, "mfa-verify"),
+        mfaPreauthEnableStartRateLimit: createRedisLoginRateLimiter(redis, undefined, undefined, "mfa-preauth-start"),
+        mfaPreauthConfirmRateLimit: createRedisLoginRateLimiter(redis, undefined, undefined, "mfa-preauth-confirm"),
+    };
+}
+export function buildProdAuthRoutes(effectiveAuth, config, composed, connections, authWiring) {
+    const { redis } = connections;
+    const { authPublicOrigin } = composed;
+    const { trustedProxyHops } = config;
+    return {
+        ...buildSharedAuthRoutes(effectiveAuth, Boolean(authWiring.mfaFeature)),
+        userQuery: UserQueries.findForAuth,
+        // 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. Redis is required infra
+        // here already (REDIS_URL), so this is free.
+        loginRateLimit: createRedisLoginRateLimiter(redis),
+        ...(effectiveAuth.secureCookies !== undefined && {
+            secureCookies: effectiveAuth.secureCookies,
+        }),
+        ...(authPublicOrigin !== undefined && { publicOrigin: authPublicOrigin }),
+        ...(trustedProxyHops !== undefined && { trustedProxyHops }),
+        ...authWiring.sessionAuthFragment,
+        ...authWiring.patAuthFragment,
+        ...(authWiring.mfaFeature && buildMfaRateLimits(redis)),
+    };
+}

package/dist/run-prod-app-boot-context.d.ts

@@ -39,8 +39,8 @@ type BootExtraContextOptions = {
     readonly appOverrides?: ConfigOverridesInput;
 };
 export declare function buildBootExtraContext(opts: BootExtraContextOptions): Record<string, unknown>;
-/** Die Auth-Felder die resolveAuthMail liest/normalisiert — beide
- *  App-Auth-Typen (prod + dev) erfüllen das strukturell. */
+/** The auth fields read and normalized by resolveAuthMail; both
+ *  app auth types (prod + dev) satisfy this structurally. */
 type AuthMailNormalizable = {
     readonly mail?: AuthMailOptions;
     readonly passwordReset?: PasswordResetSetup;

package/dist/run-prod-app-boot-context.js

@@ -17,14 +17,14 @@ import { resolveBootCrypto } from "./boot/boot-crypto.js";
 // Boot-time context helpers for runProdApp: ctx-extra-context wiring
 // (templateResolver/delivery/secrets/config-resolver), auth-mail convenience
 // normalization, and prod session-auth wiring. Split out of run-prod-app.ts
-// (#1005, Welle 2) — mechanical relocation, these are self-contained pure
+// — mechanical relocation, these are self-contained pure
 // functions, no closure over runProdApp's local boot state.
 // Shared with runDevApp (mergeConfigResolverDefault) for dev/prod parity.
 export function addConfigAccessorFactory(resolved, registry) {
     if (!resolved.configResolver)
         return resolved;
     // Both keys, always overriding an app-supplied value: the factory must derive from the
-    // effective resolver (fw#3313); the underscore alias stays until the next major.
+    // effective resolver; the underscore alias stays until the next major.
     const configAccessorFactory = createConfigAccessorFactory(registry, resolved.configResolver);
     return {
         ...resolved,
@@ -32,20 +32,19 @@ export function addConfigAccessorFactory(resolved, registry) {
         _configAccessorFactory: configAccessorFactory,
     };
 }
-// Framework-Default-Provider für den AppContext — gleicher Mechanismus wie
-// der tenantTierResolver-Autowire (findTierResolverUsage): deklarierter
-// Bedarf (Feature gemountet) → Default aus db/env, App überschreibt nur die
-// Ausnahme. templateResolver ist unbedingt (createTemplateResolverApi wirft nie, baut
-// nur einen db-gebundenen Accessor). secrets wird nur auto-verdrahtet wenn
-// das secrets-Feature gemountet ist UND ein KEK tatsächlich verfügbar ist
-// (masterKey-Override ODER env-KEK present) — sonst skip, damit der eager
-// KEK-Detection + Provider/Cipher-Aufbau leben in boot/boot-crypto.ts
-// (envHasMasterKek, resolveBootCrypto) — gemeinsam mit runDevApp.
-// Prod-Misconfig (secrets gemountet, kein KEK) fängt schon secretsEnvSchema
-// beim Boot; fehlt der env-Schema-Pfad, wirft requireSecretsContext beim
-// ersten ctx.secrets-Zugriff mit Wiring-Hinweis. configResolver nur im
-// Auth-Mode. Exportiert + pure für Unit-Tests; der merge mit App-Werten
-// passiert beim Caller (App gewinnt).
+// Framework-default providers for AppContext, using the same mechanism as
+// tenantTierResolver auto-wiring (findTierResolverUsage): a mounted feature declares
+// the need, the default comes from db/env, and the app can override the exception.
+// templateResolver is always wired (createTemplateResolverApi never throws; it only
+// creates a db-bound accessor). secrets is auto-wired only when the secrets feature is
+// mounted AND a KEK is available (masterKey override OR env KEK present); otherwise it
+// is skipped so eager KEK detection and provider/cipher construction remain in
+// boot/boot-crypto.ts (envHasMasterKek, resolveBootCrypto), shared with runDevApp.
+// A production misconfiguration (secrets mounted without a KEK) is caught by
+// secretsEnvSchema during boot; without the env-schema path, requireSecretsContext
+// throws with a wiring hint on the first ctx.secrets access. configResolver is only
+// wired in auth mode. Exported and pure for unit tests; the caller merges it with
+// app values (the app wins).
 // Prod/dev parity for ctx.notify: without this `_notifyFactory` is only wired
 // in tests (createDeliveryTestContext), so ctx.notify is undefined at runtime
 // and every notification silently skips. sseBroker optional (email/push don't
@@ -134,9 +133,13 @@ function createBootConfigResolver(registry, envSource, crypto, appOverrides) {
 // layouts), so apps without auth still get a resolver for it; the ctx entry
 // stays auth-only.
 function resolveDeliveryConfigResolver(opts, hasDeliveryFeature, crypto) {
-    return opts.hasAuth || hasDeliveryFeature
-        ? createBootConfigResolver(opts.registry, opts.envSource, crypto, opts.appOverrides)
-        : undefined;
+    if (opts.hasAuth || hasDeliveryFeature) {
+        return createBootConfigResolver(opts.registry, opts.envSource, crypto, opts.appOverrides);
+    }
+    if (opts.appOverrides) {
+        throw new Error("[runProdApp] appOverrides needs `auth` or a delivery feature: without one no config resolver is built and the overrides would be ignored.");
+    }
+    return undefined;
 }
 function bootDeliveryContext(opts, parts) {
     if (!opts.features.some((f) => f.name === DELIVERY_FEATURE))
@@ -219,17 +222,17 @@ export function resolveAuthMail(auth, hmacSecret, envSource, mailWiring = {}) {
     const withResolvedSecrets = backfillTokenSecrets(auth, tokenSecret);
     if (!auth.mail)
         return withResolvedSecrets;
-    // SMTP-presence gate: ohne SMTP_HOST-env wird KEIN Flow verdrahtet (Routes
-    // blieben sonst 500). Der eigentliche Mail-Versand läuft über delivery
-    // (channel-email), nicht über diesen Transport — er ist nur der Detektor
-    // "ist Mail konfiguriert?".
+    // SMTP-presence gate: without SMTP_HOST in the environment, no flow is wired
+    // (the routes would otherwise return 500). Mail delivery itself runs through
+    // delivery (channel-email), not this transport; it only detects whether mail is
+    // configured.
     // An app transport from runProdApp's `mail` option replaces the probe.
     if (mailWiring.mailConfigured !== true &&
         !createSmtpTransportFromEnv(envSource, { fallbackFrom: auth.mail.from ?? "noreply@localhost" })) {
         return withResolvedSecrets;
     }
     const paths = makeAuthPaths(auth.mail.paths);
-    // appName/locale fließen in alle vier Flow-Options (alle mailen via delivery).
+    // appName/locale flow into all four flow options because they all send through delivery.
     const mailPresentation = {
         ...(auth.mail.appName !== undefined && { appName: auth.mail.appName }),
         ...(auth.mail.locale !== undefined && { locale: auth.mail.locale }),
@@ -266,7 +269,7 @@ export function resolveAuthMail(auth, hmacSecret, envSource, mailWiring = {}) {
     };
 }
 export async function buildProdSessionAuth(db, registry, sessionsFeature, mfaFeature, patFeature) {
-    // Resolve the sessions feature sessionStore provider (#1372).
+    // Resolve the sessions feature sessionStore provider.
     const store = await resolveSessionStore({ db, registry });
     if (sessionsFeature) {
         bindAutoRevokeFromFeature(sessionsFeature)?.(store.massRevoker);

package/dist/run-prod-app-config.d.ts

@@ -0,0 +1,36 @@
+import { loadJwtSecretOrKeyring } from "@cosmicdrift/kumiko-framework/api";
+import { type FeatureDefinition, type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { type Logger } from "@cosmicdrift/kumiko-framework/logging";
+import { resolveBootCrypto } from "./boot/boot-crypto.ts";
+import { type BootOptionWiring } from "./boot-options/resolve-boot-options.ts";
+import { resolveRateLimit } from "./rate-limit-defaults.ts";
+import { resolveUnsubscribeWiring } from "./resolve-unsubscribe-wiring.ts";
+import type { RunProdAppOptions } from "./run-prod-app.ts";
+import { resolveAuthMail } from "./run-prod-app-boot-context.ts";
+export type BootAbortCleanup = () => void | Promise<void>;
+export type RegisterBootAbortCleanup = (cleanup: BootAbortCleanup) => void;
+export declare function runWithBootAbortCleanups<T>(boot: (register: RegisterBootAbortCleanup) => Promise<T>): Promise<T>;
+export type ProdBootConfig = {
+    readonly bootOptionWiring: BootOptionWiring;
+    readonly envSource: Record<string, string | undefined>;
+    readonly bootKms: BootOptionWiring["kms"];
+    readonly databaseUrl: string;
+    readonly redisUrl: string;
+    readonly jwtSecret: string;
+    readonly jwtSecretOrKeyring: ReturnType<typeof loadJwtSecretOrKeyring>;
+    readonly jwtIssuer: string | undefined;
+    readonly instanceId: string | undefined;
+    readonly trustedProxyHops: number | undefined;
+    readonly resolvedRateLimit: ReturnType<typeof resolveRateLimit>;
+    readonly port: number;
+};
+export type ProdComposedFeatures = ReturnType<typeof resolveUnsubscribeWiring> & {
+    readonly effectiveAuth: ReturnType<typeof resolveAuthMail<NonNullable<RunProdAppOptions["auth"]>>> | undefined;
+    readonly authPublicOrigin: string | undefined;
+    readonly features: readonly FeatureDefinition[];
+    readonly bootCrypto: ReturnType<typeof resolveBootCrypto>;
+    readonly sessionsFeature: FeatureDefinition | undefined;
+    readonly registry: Registry;
+};
+export declare function resolveProdBootConfig(options: RunProdAppOptions, decryptedEnvSource: Record<string, string | undefined>, log: Logger, registerAbortCleanup: RegisterBootAbortCleanup): Promise<ProdBootConfig>;
+export declare function composeProdFeatures(options: RunProdAppOptions, config: ProdBootConfig, log: Logger): ProdComposedFeatures;

package/dist/run-prod-app-config.js

@@ -0,0 +1,169 @@
+import { EXT_SESSION_STORE } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { SESSIONS_FEATURE } from "@cosmicdrift/kumiko-bundled-features/sessions";
+import { loadJwtSecretOrKeyring, TRUSTED_PROXY_HOPS_ENV } from "@cosmicdrift/kumiko-framework/api";
+import { createRegistry, } from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { resolveBootCrypto } from "./boot/boot-crypto.js";
+import { composeAppFeatures, validateComposedFeatures, withEnvDefaults, } from "./boot/shared-boot-steps.js";
+import { resolveBootOptionWiring, } from "./boot-options/resolve-boot-options.js";
+import { assertStackBootRequirements } from "./boot-options/stack-boot-requirements.js";
+import { assertPiiBootInvariants } from "./pii-boot-gate.js";
+import { resolveRateLimit } from "./rate-limit-defaults.js";
+import { readEnv, requireEnv } from "./require-env.js";
+import { resolveAuthPublicOrigin } from "./resolve-auth-public-origin.js";
+import { resolveUnsubscribeWiring } from "./resolve-unsubscribe-wiring.js";
+import { resolveAuthMail } from "./run-prod-app-boot-context.js";
+import { assertSessionBootInvariants } from "./session-boot-gate.js";
+import { resolveTrustedProxyHops } from "./trusted-proxy-hops.js";
+export async function runWithBootAbortCleanups(boot) {
+    const abortCleanups = [];
+    try {
+        return await boot((cleanup) => abortCleanups.push(cleanup));
+    }
+    catch (error) {
+        // Pools and clients opened before the failing step would otherwise keep the process alive.
+        for (const cleanup of abortCleanups.reverse()) {
+            await Promise.resolve()
+                .then(cleanup)
+                .catch(() => undefined);
+        }
+        throw error;
+    }
+}
+let warnedLegacyJwtSecret = false;
+function warnLegacyJwtSecretOnce() {
+    // skip: already warned once this process — avoid log spam on every boot path.
+    if (warnedLegacyJwtSecret)
+        return;
+    warnedLegacyJwtSecret = true;
+    createFallbackLogger("runProdApp").warn("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 resolveProdBootConfig(options, decryptedEnvSource, log, registerAbortCleanup) {
+    // Stacks whose boot options are missing and the declarative boot options
+    // (mail, kmsMode, fileStorage, billing, demoMode, seed shortcuts) fail here, before any connection. Their defaults sit under
+    // the env so an explicitly set variable wins.
+    assertStackBootRequirements(options);
+    const bootOptionWiring = await resolveBootOptionWiring(options, decryptedEnvSource);
+    const envSource = withEnvDefaults(bootOptionWiring.envDefaults, decryptedEnvSource);
+    const bootKms = bootOptionWiring.kms;
+    registerAbortCleanup(() => bootKms.close());
+    // Polyfill before anything else — feature code references Temporal.
+    const { ensureTemporalPolyfill } = await import("@cosmicdrift/kumiko-framework/time");
+    await ensureTemporalPolyfill();
+    // 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);
+    // 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 = resolveTrustedProxyHops({
+        option: options.trustedProxyHops,
+        authOption: options.auth?.trustedProxyHops,
+        envValue: readEnv(TRUSTED_PROXY_HOPS_ENV, envSource),
+        nodeEnv: process.env["NODE_ENV"],
+    });
+    if (trustedProxyHops === undefined) {
+        // With 0 hops every request appears to come from the proxy pod, so all IP-keyed
+        // rate limiters collapse into one shared bucket behind a reverse proxy.
+        log.warn(`trustedProxyHops / ${TRUSTED_PROXY_HOPS_ENV} is not set; client IP falls back to the socket address. ` +
+            "Behind a reverse proxy all clients share one rate-limit bucket, so the default L1/L2 limits throttle the whole site at once.");
+    }
+    const resolvedRateLimit = resolveRateLimit(options.rateLimit);
+    const port = options.port ?? Number.parseInt(envSource["PORT"] ?? "3000", 10);
+    log.info(`booting Kumiko stack on port ${port}`);
+    return {
+        bootOptionWiring,
+        envSource,
+        bootKms,
+        databaseUrl,
+        redisUrl,
+        jwtSecret,
+        jwtSecretOrKeyring,
+        jwtIssuer,
+        instanceId,
+        trustedProxyHops,
+        resolvedRateLimit,
+        port,
+    };
+}
+export function composeProdFeatures(options, config, log) {
+    const { bootOptionWiring, envSource, bootKms, jwtSecret } = config;
+    // auth.mail is expanded into the explicit flow fields before feeding both
+    // the feature side (buildComposeAuthOptions) and the routes fragment below.
+    // From here on, always read effectiveAuth instead of options.auth.
+    const effectiveAuth = options.auth
+        ? resolveAuthMail(options.auth, jwtSecret, envSource, {
+            mailConfigured: bootOptionWiring.mailConfigured,
+        })
+        : undefined;
+    const authPublicOrigin = effectiveAuth
+        ? resolveAuthPublicOrigin(effectiveAuth, envSource, (message) => {
+            log.warn(message);
+        })
+        : undefined;
+    const { unsubscribeLinks, unsubscribeRoutes } = resolveUnsubscribeWiring({
+        unsubscribe: options.unsubscribe,
+        publicOrigin: effectiveAuth?.publicOrigin,
+        mailBaseUrl: effectiveAuth?.mail?.baseUrl,
+        envSource,
+        warn: (message) => createFallbackLogger("runProdApp").warn(message),
+    });
+    // Feature registry. Auth mode automatically mixes config/user/tenant/
+    // auth-email-password via composeFeatures, using the same feature list as
+    // runDevApp and the per-app schema generator. Build it before any connection
+    // so boot mode can validate wiring without opening Postgres or Redis sockets.
+    const features = composeAppFeatures(options.features, bootOptionWiring.features, effectiveAuth);
+    const bootCrypto = resolveBootCrypto(envSource, options.masterKey);
+    validateComposedFeatures(features, {
+        env: envSource,
+        ...(bootCrypto.entityFieldCipher && { entityFieldCipher: bootCrypto.entityFieldCipher }),
+        ...options.validateBootOptions,
+    });
+    assertPiiBootInvariants(features, {
+        kms: bootKms.kms,
+        blindIndexKey: bootKms.blindIndexKey,
+        allowPlaintextPii: bootKms.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",
+    });
+    return {
+        effectiveAuth,
+        authPublicOrigin,
+        unsubscribeLinks,
+        unsubscribeRoutes,
+        features,
+        bootCrypto,
+        sessionsFeature,
+        registry,
+    };
+}

package/dist/run-prod-app-connections.d.ts

@@ -0,0 +1,16 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
+import { createRedisCacheSyncBus } from "@cosmicdrift/kumiko-framework/redis";
+import { Redis } from "ioredis";
+import type { RunProdAppOptions } from "./run-prod-app.ts";
+import type { ProdBootConfig, RegisterBootAbortCleanup } from "./run-prod-app-config.ts";
+export type ProdConnections = {
+    readonly db: DbConnection;
+    readonly closeDb: () => Promise<void>;
+    readonly outsideTransactionDb: DbConnection;
+    readonly closeOutsideTransactionDb: () => Promise<void>;
+    readonly redis: Redis;
+    readonly cacheSync: ReturnType<typeof createRedisCacheSyncBus>;
+};
+export declare function connectProdDependencies(config: ProdBootConfig, log: Logger, registerAbortCleanup: RegisterBootAbortCleanup): Promise<ProdConnections>;
+export declare function assertProdSchemaCurrent(db: DbConnection, migrations: RunProdAppOptions["migrations"], log: Logger): Promise<void>;

package/dist/run-prod-app-connections.js

@@ -0,0 +1,55 @@
+import { assertKumikoSchemaCurrent, SchemaDriftError, } from "@cosmicdrift/kumiko-framework/migrations";
+import { createRedisCacheSyncBus, logRedisConnectionState, redisClientOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/redis";
+import { Redis } from "ioredis";
+import { openDatabasePools, waitForKmsHealthy } from "./boot/shared-boot-steps.js";
+import { WAIT_FOR_DATABASE_DEADLINE_MS, waitForDatabase } from "./boot/wait-for-database.js";
+// 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 this must stay AFTER the
+// boot-mode exit.
+export async function connectProdDependencies(config, log, registerAbortCleanup) {
+    const { bootKms, databaseUrl, redisUrl, envSource } = config;
+    // 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.
+    const databaseWaitDeadline = Date.now() + WAIT_FOR_DATABASE_DEADLINE_MS;
+    if (bootKms.kms) {
+        await waitForKmsHealthy(bootKms.kms, "runProdApp", databaseWaitDeadline);
+    }
+    const pools = openDatabasePools(databaseUrl, envSource);
+    const redis = new Redis(redisUrl, { maxRetriesPerRequest: null });
+    registerAbortCleanup(pools.closeDb);
+    registerAbortCleanup(pools.closeOutsideTransactionDb);
+    registerAbortCleanup(() => redis.disconnect());
+    logRedisConnectionState(redis, log);
+    await waitForDatabase(pools.db, { processName: "runProdApp", deadline: databaseWaitDeadline });
+    // One bus per process: the tier resolver, the dispatcher and the file-provider
+    // resolver all subscribe to it (invalidation across the API pods).
+    const cacheSync = createRedisCacheSyncBus({
+        redisUrl,
+        clientOptions: redisClientOptionsFromEnv(envSource),
+    });
+    return { ...pools, redis, cacheSync };
+}
+// Schema-drift gate (without drizzle, using kumiko/migrations). `kumiko
+// schema apply` runs as a deploy step before container rollout. Boot only
+// verifies that every kumiko/migrations/*.sql file is applied in
+// _kumiko_migrations with an unchanged checksum and that every table in
+// kumiko/migrations/.snapshot.json exists. Drift aborts boot rather than being auto-healed, avoiding
+// races between container replicas. `migrations: false` opts out for custom
+// schema setups.
+export async function assertProdSchemaCurrent(db, migrations, log) {
+    if (migrations !== false) {
+        const migrationsDir = migrations?.dir ?? "./kumiko/migrations";
+        log.info(`checking schema drift (${migrationsDir})`);
+        try {
+            await assertKumikoSchemaCurrent(db, migrationsDir);
+        }
+        catch (err) {
+            if (err instanceof SchemaDriftError) {
+                log.error(`BOOT ABORTED — ${err.message}`);
+            }
+            throw err;
+        }
+    }
+}