@cosmicdrift/kumiko-server-runtime 0.387.0 → 0.388.0

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/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.js

@@ -133,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))

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;
+        }
+    }
+}

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

@@ -0,0 +1,14 @@
+import type { EffectiveFeaturesResolver } from "@cosmicdrift/kumiko-framework/engine";
+import { type AllInOneEntrypoint, type ApiEntrypoint, type ApiEntrypointOptions } from "@cosmicdrift/kumiko-framework/entrypoint";
+import type { RunProdAppOptions } from "./run-prod-app.ts";
+import { type ProdAuthWiring } from "./run-prod-app-auth.ts";
+import type { ProdBootConfig, ProdComposedFeatures } from "./run-prod-app-config.ts";
+import type { ProdConnections } from "./run-prod-app-connections.ts";
+import type { ProdRequestContext } from "./run-prod-app-request-context.ts";
+export type ProdEntrypoint = ApiEntrypoint | AllInOneEntrypoint;
+export declare function buildProdEntrypointOptions(options: RunProdAppOptions, config: ProdBootConfig, composed: ProdComposedFeatures, connections: ProdConnections, requestContext: ProdRequestContext, authWiring: ProdAuthWiring, effectiveFeatures: EffectiveFeaturesResolver | undefined): ApiEntrypointOptions;
+export type ProdEntrypointOptions = ReturnType<typeof buildProdEntrypointOptions>;
+export declare function createProdEntrypoint(options: RunProdAppOptions, config: ProdBootConfig, composed: ProdComposedFeatures, connections: ProdConnections, entrypointOptions: ProdEntrypointOptions): ProdEntrypoint;
+export declare function registerProdShutdownHooks(entrypoint: ProdEntrypoint, cacheSync: ProdConnections["cacheSync"], ownedRedisSseBroker: ProdRequestContext["ownedRedisSseBroker"]): void;
+export declare function runProdWireHook(options: RunProdAppOptions, composed: ProdComposedFeatures, connections: ProdConnections, entrypoint: ProdEntrypoint): Promise<void>;
+export declare function startProdBackgroundWork(entrypoint: ProdEntrypoint, config: ProdBootConfig, composed: ProdComposedFeatures, connections: ProdConnections): Promise<void>;

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

@@ -0,0 +1,147 @@
+import { createAllInOneEntrypoint, createApiEntrypoint, } from "@cosmicdrift/kumiko-framework/entrypoint";
+import { createMetricsForFactory } from "@cosmicdrift/kumiko-framework/observability";
+import { jobRunLoggerCallbacks } from "./boot/job-run-logger.js";
+import { startPiiEventBackfillOnBoot } from "./boot/pii-event-backfill-on-boot.js";
+import { recordAppStartedOnBoot } from "./boot/record-app-started-on-boot.js";
+import { makeDispatchSystemQuery, makeDispatchSystemWrite } from "./extra-routes-deps.js";
+import { buildProdAuthRoutes } from "./run-prod-app-auth.js";
+function collectProdExtraRoutes(options, config, composed) {
+    const bootExtraRoutes = config.bootOptionWiring.extraRoutes;
+    if (!options.extraRoutes && !options.unsubscribe && bootExtraRoutes.length === 0) {
+        return undefined;
+    }
+    return [...(options.extraRoutes ?? []), ...composed.unsubscribeRoutes, ...bootExtraRoutes];
+}
+export function buildProdEntrypointOptions(options, config, composed, connections, requestContext, authWiring, effectiveFeatures) {
+    const { registry, effectiveAuth } = composed;
+    const { db, redis, outsideTransactionDb, cacheSync } = connections;
+    const { jwtIssuer, instanceId, trustedProxyHops, resolvedRateLimit } = config;
+    const extraRoutes = collectProdExtraRoutes(options, config, composed);
+    return {
+        registry,
+        context: {
+            db,
+            redis,
+            entityCache: requestContext.entityCache,
+            registry,
+            ...requestContext.extraContext,
+        },
+        sseBroker: requestContext.sseBroker,
+        jwtSecret: config.jwtSecretOrKeyring,
+        ...(jwtIssuer && { jwtIssuer }),
+        ...(instanceId && { instanceId }),
+        dispatcherOptions: {
+            idempotency: requestContext.idempotency,
+            cacheSync,
+            outsideTransactionDb,
+            ...(effectiveFeatures && { effectiveFeatures }),
+        },
+        eventDedup: requestContext.eventDedup,
+        ...(options.observability && { observability: options.observability }),
+        ...(options.metrics && { metrics: options.metrics }),
+        ...(resolvedRateLimit && { rateLimit: resolvedRateLimit }),
+        ...(trustedProxyHops !== undefined && { trustedProxyHops }),
+        ...(options.errorDocs && { errorDocs: options.errorDocs }),
+        ...(extraRoutes && { extraRoutes }),
+        ...(effectiveAuth && {
+            auth: buildProdAuthRoutes(effectiveAuth, config, composed, connections, authWiring),
+        }),
+        ...(requestContext.resolvedAnonymousAccess && {
+            anonymousAccess: requestContext.resolvedAnonymousAccess,
+        }),
+    };
+}
+function prodJobOptions(options, composed, connections) {
+    const queueNamePrefix = options.jobs?.queueNamePrefix;
+    return {
+        ...jobRunLoggerCallbacks(composed.registry, connections.db),
+        ...(queueNamePrefix !== undefined && { queueNamePrefix }),
+        ...(options.jobs?.getActiveTenantIds !== undefined && {
+            getActiveTenantIds: options.jobs.getActiveTenantIds,
+        }),
+    };
+}
+// Deployment topology. By default, createAllInOneEntrypoint runs HTTP, both
+// job lanes (two runners, each scheduling only its own lane's crons, so
+// nothing fires twice) and the event dispatcher inline. That way worker-lane
+// crons (run-export-jobs defaults to runIn:"worker") and MSPs run without a
+// separate worker process, the gap the data export used to stall on.
+// runSingleInstance:false means API-only: a dedicated worker must then take
+// over the worker lane and MSPs, while API-lane jobs keep running locally.
+// The legacy eventDispatcher.disabled maps to runSingleInstance:false so
+// existing callers keep working; the explicit flag takes precedence.
+export function createProdEntrypoint(options, config, composed, connections, entrypointOptions) {
+    const runSingleInstance = options.runSingleInstance ?? options.eventDispatcher?.disabled !== true;
+    const hasJobs = composed.registry.getAllJobs().size > 0;
+    const jobOptions = prodJobOptions(options, composed, connections);
+    const dispatcherTunables = options.eventDispatcher?.pollIntervalMs !== undefined
+        ? { pollIntervalMs: options.eventDispatcher.pollIntervalMs }
+        : {};
+    return runSingleInstance
+        ? createAllInOneEntrypoint({
+            ...entrypointOptions,
+            redisUrl: config.redisUrl,
+            ...jobOptions,
+            ...(!options.eventDispatcher?.disabled && { eventDispatcher: dispatcherTunables }),
+        })
+        : createApiEntrypoint({
+            ...entrypointOptions,
+            ...(hasJobs && {
+                jobs: {
+                    redisUrl: config.redisUrl,
+                    runLocalJobs: true,
+                    ...jobOptions,
+                },
+            }),
+        });
+}
+// 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 established for buildServer's own hook.
+export function registerProdShutdownHooks(entrypoint, cacheSync, ownedRedisSseBroker) {
+    entrypoint.lifecycle.registerShutdownHook("prodAppCacheSync", async () => {
+        await cacheSync.close();
+    });
+    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.
+export async function runProdWireHook(options, composed, connections, entrypoint) {
+    const { wire } = options;
+    if (wire) {
+        const { bootCrypto } = composed;
+        await wire({
+            db: connections.db,
+            redis: connections.redis,
+            registry: composed.registry,
+            ...(bootCrypto.masterKeyProvider && { masterKeyProvider: bootCrypto.masterKeyProvider }),
+            ...(bootCrypto.configCipher && { configEncryption: bootCrypto.configCipher }),
+            metricsFor: createMetricsForFactory(entrypoint.observability.meter),
+            dispatchSystemWrite: makeDispatchSystemWrite(entrypoint.dispatcher),
+            dispatchSystemQuery: makeDispatchSystemQuery(entrypoint.dispatcher),
+        });
+    }
+}
+export async function startProdBackgroundWork(entrypoint, config, composed, connections) {
+    const { envSource } = config;
+    await entrypoint.start();
+    await recordAppStartedOnBoot({ db: connections.db, envSource });
+    startPiiEventBackfillOnBoot({
+        db: connections.db,
+        registry: composed.registry,
+        lifecycle: entrypoint.lifecycle,
+        envSource,
+    });
+}

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

@@ -0,0 +1,20 @@
+import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
+import type { ProdAppHandle, RunProdAppOptions } from "./run-prod-app.ts";
+import type { ProdBootConfig, ProdComposedFeatures } from "./run-prod-app-config.ts";
+import type { ProdConnections } from "./run-prod-app-connections.ts";
+import type { ProdEntrypoint } from "./run-prod-app-entrypoint.ts";
+export type ProdFetchHandler = {
+    readonly fetchHandler: ProdAppHandle["fetch"];
+    readonly cspScriptHashes: readonly string[];
+};
+export declare function buildProdFetchHandler(options: RunProdAppOptions, config: ProdBootConfig, entrypoint: ProdEntrypoint): Promise<ProdFetchHandler>;
+export type ProdAppHandleInput = {
+    readonly options: RunProdAppOptions;
+    readonly config: ProdBootConfig;
+    readonly composed: ProdComposedFeatures;
+    readonly connections: ProdConnections;
+    readonly entrypoint: ProdEntrypoint;
+    readonly fetch: ProdFetchHandler;
+    readonly log: Logger;
+};
+export declare function createProdAppHandle(input: ProdAppHandleInput): ProdAppHandle;