@cosmicdrift/kumiko-server-runtime 0.368.0 → 0.370.0

package/dist/run-prod-app.js

@@ -16,7 +16,7 @@
 //     (gleiche Logik wie runDevApp).
 //
 // App-Author schreibt:
-//   await runProdApp({ features, auth, anonymousAccess, seeds });
+//   await runProdApp({ features, envSchema, auth, anonymousAccess, seeds });
 //
 // Container/Coolify setzt:
 //   DATABASE_URL=postgresql://...
@@ -42,20 +42,19 @@
 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 { createUnsubscribeRoutes, } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { AUTH_MFA_FEATURE, AuthMfaHandlers, bindMfaTokenSecretsFromFeature, } from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
 import { PAT_FEATURE, patRateLimitFromFeature, } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
 import { SECRETS_MASTER_KEK_ENV_KEYS } from "@cosmicdrift/kumiko-bundled-features/secrets";
 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, publicOriginOf, TRUSTED_PROXY_HOPS_ENV, withFileProviderResolver, } from "@cosmicdrift/kumiko-framework/api";
+import { createDefaultSseBroker, createRedisLoginRateLimiter, loadJwtSecretOrKeyring, parseTrustedProxyHopsEnv, TRUSTED_PROXY_HOPS_ENV, withFileProviderResolver, } from "@cosmicdrift/kumiko-framework/api";
 import { configureBlindIndexKey, configurePiiSubjectKms, resolvePlatformKeks, } from "@cosmicdrift/kumiko-framework/crypto";
 import { configureEntityFieldEncryption, createDbConnection, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/db";
 import { collectWriteHandlerQns, createRegistry, findTierResolverUsage, requireTierResolverPlugin, validateAppCustomScreenWriteQns, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
 import { createAllInOneEntrypoint, createApiEntrypoint, } from "@cosmicdrift/kumiko-framework/entrypoint";
-import { KumikoBootError, kmsSlotsOf, parseEnv, withOptionalEnvKeys, } from "@cosmicdrift/kumiko-framework/env";
-import { renderDryRun } from "@cosmicdrift/kumiko-framework/env/dry-run";
+import { inspectEnv, KumikoBootError, kmsSlotsOf, parseEnv, withOptionalEnvKeys, } from "@cosmicdrift/kumiko-framework/env";
+import { DRY_RUN_ENV_VAR, parseDryRunEnvMode, renderDryRun, renderEnvInspection, } from "@cosmicdrift/kumiko-framework/env/dry-run";
 import { createEsOperationsTable, createSeedMigrationContext, runPendingSeedMigrations, } from "@cosmicdrift/kumiko-framework/es-ops";
 import { assertSeedModeNotInProduction } from "@cosmicdrift/kumiko-framework/event-store";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
@@ -71,21 +70,39 @@ 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 { waitForDatabase, waitUntilDatabaseReachable } from "./boot/wait-for-database.js";
+import { withBootOptionEnvBlocks } from "./boot-options/option-env-schema.js";
+import { installShutdownSignals } from "./boot-options/process-signals.js";
+import { resolveBootOptionWiring } from "./boot-options/resolve-boot-options.js";
+import { assertStackBootRequirements } from "./boot-options/stack-boot-requirements.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 { APP_BASE_URL_ENV, resolveAuthPublicOrigin } from "./resolve-auth-public-origin.js";
+import { resolveRateLimit } from "./rate-limit-defaults.js";
+import { resolveAuthPublicOrigin } from "./resolve-auth-public-origin.js";
+import { resolveUnsubscribeWiring } from "./resolve-unsubscribe-wiring.js";
 import { addConfigAccessorFactory, buildBootExtraContext, buildProdSessionAuth, loggerFromExtraContext, resolveAuthMail, wireProdPatAutoRevoke, } from "./run-prod-app-boot-context.js";
-import { buildStaticFallback } from "./run-prod-app-static-files.js";
+import { buildStaticFallback, resolveCspScriptHashes } from "./run-prod-app-static-files.js";
 import { withSecurityHeaders } from "./security-headers.js";
 import { makeSeedCreateFileRef, withSeedErrorContext, } from "./seed-dispatcher.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 { resolveUnsubscribeWiring, } from "./resolve-unsubscribe-wiring.js";
 export { addConfigAccessorFactory, buildBootExtraContext, loggerFromExtraContext, resolveAuthMail, } from "./run-prod-app-boot-context.js";
 export { staticCachePolicy } from "./run-prod-app-static-files.js";
+// runProdApp reads these itself, so the boot dry run lists them even when
+// the app schema leaves them out (JWT_SECRET usually comes from auth-email-password).
+const RUNTIME_REQUIRED_ENV_KEYS = ["DATABASE_URL", "REDIS_URL", "JWT_SECRET"];
+function inspectUndeclaredRuntimeEnv(declaredShape, env) {
+    return RUNTIME_REQUIRED_ENV_KEYS.filter((name) => !(name in declaredShape)).map((name) => ({
+        name,
+        klass: "required",
+        source: "server-runtime",
+        status: env[name] ? "set" : "missing",
+    }));
+}
 // 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
@@ -108,16 +125,14 @@ function readEnv(name, src = process.env) {
     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.`);
+    const mode = parseDryRunEnvMode(raw);
+    if (mode !== undefined)
+        return mode;
+    if (raw) {
+        // biome-ignore lint/suspicious/noConsole: boot-time warn for typo discovery
+        console.warn(`[runProdApp] ${DRY_RUN_ENV_VAR}="${raw}" unrecognized ` +
+            `(expected 1|human|json|pulumi|k8s|boot); continuing with normal boot.`);
+    }
     return null;
 }
 function isRenderMode(mode) {
@@ -161,6 +176,19 @@ function warnLegacyJwtSecretOnce() {
         "that is no longer present in any in-flight token (see resolveAuthMail / " +
         "loadJwtSecretOrKeyring).");
 }
+// JS callers and apps built against older typings can still omit it.
+function requireEnvSchema(envSchema) {
+    if (envSchema === undefined) {
+        throw new KumikoBootError([
+            {
+                name: "envSchema",
+                kind: "missing",
+                message: "runProdApp needs envSchema. Pass composeEnvSchema({ core: frameworkCoreEnvSchema, features, extend }): composeEnvSchema from @cosmicdrift/kumiko-framework/env, frameworkCoreEnvSchema from @cosmicdrift/kumiko-dev-server/env-schema, features the same list as runProdApp's.",
+            },
+        ]);
+    }
+    return envSchema;
+}
 export async function runProdApp(options) {
     assertSeedModeNotInProduction();
     // 0. Env-Schema validation + dry-run modes. Runs FIRST so:
@@ -170,9 +198,9 @@ export async function runProdApp(options) {
     //      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.
+    //    The dry-run exits sit before every other env read (KEK decrypt,
+    //    JWT secret, MFA token secrets), so a build pipeline without deploy
+    //    secrets can run them.
     //
     //    Ordering invariant: this step runs BEFORE the Temporal polyfill,
     //    so env-schemas MUST use only Temporal-free Zod types. Don't author
@@ -181,63 +209,96 @@ export async function runProdApp(options) {
     //    .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"]);
-    const composedEnvSchema = options.envSchema;
+    const runMode = parseRunMode(rawEnvSource[DRY_RUN_ENV_VAR]);
+    const composedEnvSchema = withBootOptionEnvBlocks(requireEnvSchema(options.envSchema), options);
+    const effectiveEnvSchema = options.masterKey
+        ? withOptionalEnvKeys(composedEnvSchema.schema, SECRETS_MASTER_KEK_ENV_KEYS)
+        : composedEnvSchema.schema;
+    const reportBootError = (err) => {
+        const reporter = options.bootErrorReporter ?? defaultBootErrorReporter;
+        reporter(err);
+    };
     const validateEnv = (source) => {
-        // skip: app declares no env schema, nothing to validate
-        if (!composedEnvSchema)
-            return;
         try {
-            const schema = options.masterKey
-                ? withOptionalEnvKeys(composedEnvSchema.schema, SECRETS_MASTER_KEK_ENV_KEYS)
-                : composedEnvSchema.schema;
-            parseEnv(schema, source, {
+            parseEnv(effectiveEnvSchema, source, {
                 sources: composedEnvSchema.sources,
                 ...(options.pulumiPrefix ? { pulumiPrefix: options.pulumiPrefix } : {}),
             });
         }
         catch (err) {
-            if (err instanceof KumikoBootError) {
-                const reporter = options.bootErrorReporter ?? defaultBootErrorReporter;
-                reporter(err);
-            }
+            if (err instanceof KumikoBootError)
+                reportBootError(err);
             throw err;
         }
     };
-    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 (isRenderMode(runMode)) {
+        // biome-ignore lint/suspicious/noConsole: dry-run output IS the deliverable
+        console.log(renderDryRun(composedEnvSchema, runMode, {
+            ...(options.pulumiPrefix ? { pulumiPrefix: options.pulumiPrefix } : {}),
+            sources: composedEnvSchema.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();
+    }
+    if (runMode === "boot") {
+        const inspection = [
+            ...inspectEnv(effectiveEnvSchema, rawEnvSource, { sources: composedEnvSchema.sources }),
+            ...inspectUndeclaredRuntimeEnv(effectiveEnvSchema.shape, rawEnvSource),
+        ];
+        // biome-ignore lint/suspicious/noConsole: boot-mode output IS the deliverable
+        console.log(renderEnvInspection(inspection));
+        if (inspection.some((row) => row.status === "invalid")) {
+            // Missing rows go into the same report: the run fails anyway, so the
+            // operator sees every variable to fix in one pass.
+            reportBootError(new KumikoBootError(inspection.flatMap((row) => row.status === "invalid" || row.status === "missing"
+                ? [
+                    {
+                        name: row.name,
+                        kind: row.status,
+                        message: row.message ?? (row.status === "missing" ? "missing" : "invalid value"),
+                        source: row.source,
+                    },
+                ]
+                : [])));
+            return makeDryRunHandle();
+        }
+        // A build pipeline has no deploy secrets: the inventory is the result,
+        // and the wiring check below needs every value, so it stops here.
+        if (inspection.some((row) => row.status === "missing")) {
             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.
-        validateEnv(rawEnvSource);
     }
+    // boot-mode with a complete env AND normal boot run the full validation,
+    // including object-level refinements the per-field check skips.
+    validateEnv(rawEnvSource);
     // 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;
+    const decryptedEnvSource = await resolvePlatformKeks(rawEnvSource, {
+        slots: kmsSlotsOf(composedEnvSchema.schema),
+        logPrefix: "[runProdApp]",
+    });
     // The first parse relaxes ciphertext-only slots, so their decrypted
     // plaintext never met the slot's own validators (.regex/.min/.refine).
-    if (options.envSchema &&
-        kmsSlotsOf(options.envSchema.schema).some((slot) => rawEnvSource[slot] === undefined && envSource[slot] !== undefined)) {
-        validateEnv(envSource);
+    if (kmsSlotsOf(composedEnvSchema.schema).some((slot) => rawEnvSource[slot] === undefined && decryptedEnvSource[slot] !== undefined)) {
+        validateEnv(decryptedEnvSource);
     }
+    // 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 = Object.keys(bootOptionWiring.envDefaults).length > 0
+        ? { ...bootOptionWiring.envDefaults, ...decryptedEnvSource }
+        : decryptedEnvSource;
+    const bootKms = bootOptionWiring.kms;
     // 1. Polyfill before anything else — feature code references Temporal.
     const { ensureTemporalPolyfill } = await import("@cosmicdrift/kumiko-framework/time");
     await ensureTemporalPolyfill();
@@ -274,8 +335,9 @@ export async function runProdApp(options) {
         // rate limiters collapse into one shared bucket behind a reverse proxy.
         // biome-ignore lint/suspicious/noConsole: boot-time warn, no logger configured this early
         console.warn(`[runProdApp] 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.");
+            "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);
     // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
     console.log(`[runProdApp] booting Kumiko stack on port ${port}…`);
@@ -283,7 +345,9 @@ export async function runProdApp(options) {
     // 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)
+        ? resolveAuthMail(options.auth, jwtSecret, envSource, {
+            mailConfigured: bootOptionWiring.mailConfigured,
+        })
         : undefined;
     const authPublicOrigin = effectiveAuth
         ? resolveAuthPublicOrigin(effectiveAuth, envSource, (message) => {
@@ -291,34 +355,20 @@ export async function runProdApp(options) {
             console.warn(message);
         })
         : undefined;
-    const unsubscribeBaseUrl = options.unsubscribe
-        ? publicOriginOf(effectiveAuth?.publicOrigin ??
-            effectiveAuth?.mail?.baseUrl ??
-            envSource[APP_BASE_URL_ENV] ??
-            "")
-        : undefined;
-    if (options.unsubscribe && unsubscribeBaseUrl === undefined) {
-        createFallbackLogger("runProdApp").warn(`unsubscribe is enabled but no valid public app URL is known (auth.publicOrigin, auth.mail.baseUrl or ${APP_BASE_URL_ENV}), so mails get no unsubscribe link.`);
-    }
-    const unsubscribeLinks = options.unsubscribe && unsubscribeBaseUrl !== undefined
-        ? {
-            secret: options.unsubscribe.secret,
-            baseUrl: unsubscribeBaseUrl,
-            ...(options.unsubscribe.tenantOrigin !== undefined && {
-                tenantOrigin: options.unsubscribe.tenantOrigin,
-            }),
-        }
-        : undefined;
-    const unsubscribeRoutes = options.unsubscribe
-        ? createUnsubscribeRoutes({ secret: options.unsubscribe.secret })
-        : [];
+    const { unsubscribeLinks, unsubscribeRoutes } = resolveUnsubscribeWiring({
+        unsubscribe: options.unsubscribe,
+        publicOrigin: effectiveAuth?.publicOrigin,
+        mailBaseUrl: effectiveAuth?.mail?.baseUrl,
+        envSource,
+        warn: (message) => createFallbackLogger("runProdApp").warn(message),
+    });
     // 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, {
+    const features = composeFeatures([...options.features, ...bootOptionWiring.features], {
         includeBundled: !!effectiveAuth,
         ...(composeAuthOptions && { authOptions: composeAuthOptions }),
     });
@@ -331,9 +381,9 @@ export async function runProdApp(options) {
     warnIfNonUtcServerTimeZone();
     validateAppCustomScreenWriteQns(process.cwd(), collectWriteHandlerQns(features));
     assertPiiBootInvariants(features, {
-        kms: options.kms,
-        blindIndexKey: options.blindIndexKey,
-        allowPlaintextPii: options.allowPlaintextPii,
+        kms: bootKms.kms,
+        blindIndexKey: bootKms.blindIndexKey,
+        allowPlaintextPii: bootKms.allowPlaintextPii,
         mode: "prod",
     });
     const sessionsFeature = features.find((f) => f.name === SESSIONS_FEATURE);
@@ -349,6 +399,7 @@ export async function runProdApp(options) {
     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)`);
+        await bootKms.close();
         if (options.envSource === undefined) {
             process.exit(0);
         }
@@ -361,8 +412,8 @@ export async function runProdApp(options) {
     // 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 kms = options.kms;
+    if (bootKms.kms) {
+        const kms = bootKms.kms;
         const kmsHealth = await waitUntilDatabaseReachable(() => kms.health(), {
             processName: "runProdApp",
         });
@@ -464,12 +515,12 @@ export async function runProdApp(options) {
     // No adapter only gets this far when assertPiiBootInvariants above let it
     // through: no PII carriers, or an explicit allowPlaintextPii opt-out. The
     // engine then stays off and those fields are stored in plaintext.
-    configurePiiSubjectKms(options.kms);
+    configurePiiSubjectKms(bootKms.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);
+    configureBlindIndexKey(bootKms.blindIndexKey);
     const bootLogger = loggerFromExtraContext(resolvedExtraContext);
     const autoExtraContext = buildBootExtraContext({
         db,
@@ -480,7 +531,7 @@ export async function runProdApp(options) {
         sseBroker,
         redis,
         crypto: bootCrypto,
-        ...(options.kms && { kms: options.kms }),
+        ...(bootKms.kms && { kms: bootKms.kms }),
         ...(bootLogger && { log: bootLogger }),
         ...(unsubscribeLinks && { unsubscribeLinks }),
     });
@@ -506,6 +557,8 @@ export async function runProdApp(options) {
     // über die auth-routes.
     // Secure-by-default (#1372): sessionStore provider → resolveSessionStore.
     const mfaFeature = features.find((f) => f.name === AUTH_MFA_FEATURE);
+    if (mfaFeature)
+        bindMfaTokenSecretsFromFeature(mfaFeature)?.(jwtSecret, envSource);
     if (mfaFeature && registry.getWriteHandler(AuthHandlers.switchTenantMfaGate) === undefined) {
         throw new Error(`[runProdApp] auth-mfa is mounted but ${AuthHandlers.switchTenantMfaGate} is not registered: ` +
             "createAuthEmailPasswordFeature registers it only when mfaStatusChecker is set, and without it " +
@@ -562,11 +615,15 @@ export async function runProdApp(options) {
         ...(options.observability && { observability: options.observability }),
         ...(options.observabilityOptions && { observabilityOptions: options.observabilityOptions }),
         ...(options.metrics && { metrics: options.metrics }),
-        ...(options.rateLimit && { rateLimit: options.rateLimit }),
+        ...(resolvedRateLimit && { rateLimit: resolvedRateLimit }),
         ...(trustedProxyHops !== undefined && { trustedProxyHops }),
         ...(options.errorDocs && { errorDocs: options.errorDocs }),
-        ...((options.extraRoutes || options.unsubscribe) && {
-            extraRoutes: [...(options.extraRoutes ?? []), ...unsubscribeRoutes],
+        ...((options.extraRoutes || options.unsubscribe || bootOptionWiring.extraRoutes.length > 0) && {
+            extraRoutes: [
+                ...(options.extraRoutes ?? []),
+                ...unsubscribeRoutes,
+                ...bootOptionWiring.extraRoutes,
+            ],
         }),
         ...(effectiveAuth && {
             auth: {
@@ -731,12 +788,16 @@ export async function runProdApp(options) {
     if (effectiveAuth?.admin) {
         await seedAdminGuarded(db, effectiveAuth.admin);
     }
+    for (const seed of bootOptionWiring.shortcutSeeds) {
+        await seed(db);
+    }
     await applyBootSeeds({
         registry,
         db,
         ...(bootCrypto.configCipher && { cipher: bootCrypto.configCipher }),
     });
-    const hasSeeds = (options.seeds?.length ?? 0) > 0 || options.seedsDir !== undefined;
+    const customSeeds = bootOptionWiring.customSeeds;
+    const hasSeeds = customSeeds.length > 0 || options.seedsDir !== undefined;
     const seedContext = hasSeeds
         ? withFileProviderResolver(registry, { db, redis, entityCache, registry, ...extraContext }, cacheSync)
         : undefined;
@@ -748,7 +809,7 @@ export async function runProdApp(options) {
         : undefined;
     if (seedDispatcher && seedContext) {
         const createFileRef = makeSeedCreateFileRef({ db, registry, context: seedContext });
-        for (const seed of options.seeds ?? []) {
+        for (const seed of customSeeds) {
             await seed({ db, registry, dispatcher: seedDispatcher, createFileRef });
         }
     }
@@ -780,7 +841,8 @@ export async function runProdApp(options) {
     //     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
+    const cspScriptHashes = await resolveCspScriptHashes(options.staticDir, options.securityHeaders);
+    const fetchHandler = withSecurityHeaders(bootOptionWiring.wrapFetch(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)
@@ -789,12 +851,13 @@ export async function runProdApp(options) {
             // (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);
+            async (req, socketAddress) => stripNoRouteMatchHeader(await entrypoint.app.fetch(req, socketAddress))), options.securityHeaders, cspScriptHashes);
     // 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 securedUpgradeFetch = withSecurityHeaders(async (req, env) => stripNoRouteMatchHeader(await entrypoint.app.fetch(req, env)), options.securityHeaders, cspScriptHashes);
     const webSocketUpgradeFetch = async (req, env) => securedUpgradeFetch(req, env);
+    let uninstallShutdownSignals;
     const handle = {
         entrypoint,
         fetch: fetchHandler,
@@ -816,29 +879,15 @@ export async function runProdApp(options) {
             // 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"));
+            if (options.signals !== false) {
+                uninstallShutdownSignals?.();
+                uninstallShutdownSignals = installShutdownSignals({
+                    stop: () => handle.stop(),
+                    ...(options.signals?.drainTimeoutMs !== undefined && {
+                        drainTimeoutMs: options.signals.drainTimeoutMs,
+                    }),
+                });
+            }
             // 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}`);
         },
@@ -849,6 +898,9 @@ export async function runProdApp(options) {
             await closeDb();
             await closeOutsideTransactionDb();
             redis.disconnect();
+            await bootKms.close();
+            uninstallShutdownSignals?.();
+            uninstallShutdownSignals = undefined;
         },
     };
     // 12. Auto-listen unless explicitly suppressed (tests pass autoListen:

package/dist/run-worker-app.d.ts

@@ -7,8 +7,8 @@ import type { JobRunnerOptions } from "@cosmicdrift/kumiko-framework/jobs";
 import { type ObservabilityOptions, type ObservabilityProvider } from "@cosmicdrift/kumiko-framework/observability";
 import type { MasterKeyProvider, SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import type { Redis } from "ioredis";
-import { type WorkerMetricsOptions, type WorkerMetricsServer } from "./boot/worker-metrics-server.js";
-import { type SystemWireDeps } from "./extra-routes-deps.js";
+import { type WorkerMetricsOptions, type WorkerMetricsServer } from "./boot/worker-metrics-server.ts";
+import { type SystemWireDeps } from "./extra-routes-deps.ts";
 export type WorkerContextOption = Record<string, unknown> | ((deps: WorkerDeps) => Record<string, unknown>);
 export type WorkerDeps = {
     readonly db: DbConnection;

package/dist/security-headers.d.ts

@@ -11,10 +11,21 @@ export type SecurityHeadersOption = false | {
     /** `Referrer-Policy` value, or `false` to omit.
      *  Default: `strict-origin-when-cross-origin`. */
     readonly referrerPolicy?: string | false;
-    /** `Content-Security-Policy` default for ALL responses. No built-in
-     *  default — a wrong CSP breaks app assets, so it stays opt-in.
+    /** `Content-Security-Policy` for ALL responses.
+     *  - omitted: the built-in default (see `DEFAULT_CSP_DIRECTIVES`) with the
+     *    inline-script hashes from `dist/csp-hashes.json`.
+     *  - `false`: no CSP header.
+     *  - string: replaces the default entirely (no hashes are added).
+     *  - `{ extend }`: adds sources to the default directives, or new directives.
      *  A per-host CSP from `hostDispatch` wins over this value. */
-    readonly csp?: string;
+    readonly csp?: CspOption;
 };
-export declare function resolveSecurityHeaders(option: SecurityHeadersOption | undefined): ReadonlyArray<readonly [string, string]>;
-export declare function withSecurityHeaders<TServeArg = string>(handler: (req: Request, serveArg?: TServeArg) => Response | Promise<Response>, option: SecurityHeadersOption | undefined): (req: Request, serveArg?: TServeArg) => Response | Promise<Response>;
+export type CspExtension = Readonly<Record<string, readonly string[]>>;
+export type CspOption = false | string | {
+    readonly extend: CspExtension;
+};
+export declare const DEFAULT_CSP_DIRECTIVES: Readonly<Record<string, readonly string[]>>;
+export declare function isScriptHash(value: unknown): value is string;
+export declare function buildDefaultCsp(scriptHashes: readonly string[], extend?: CspExtension): string;
+export declare function resolveSecurityHeaders(option: SecurityHeadersOption | undefined, scriptHashes?: readonly string[]): ReadonlyArray<readonly [string, string]>;
+export declare function withSecurityHeaders<TServeArg = string>(handler: (req: Request, serveArg?: TServeArg) => Response | Promise<Response>, option: SecurityHeadersOption | undefined, scriptHashes?: readonly string[]): (req: Request, serveArg?: TServeArg) => Response | Promise<Response>;

package/dist/security-headers.js

@@ -1,7 +1,57 @@
 const DEFAULT_HSTS = "max-age=31536000; includeSubDomains";
 const DEFAULT_FRAME_OPTIONS = "DENY";
 const DEFAULT_REFERRER_POLICY = "strict-origin-when-cross-origin";
-export function resolveSecurityHeaders(option) {
+export const DEFAULT_CSP_DIRECTIVES = {
+    "default-src": ["'self'"],
+    "script-src": ["'self'"],
+    "style-src": ["'self'", "'unsafe-inline'"],
+    "img-src": ["'self'", "data:", "blob:"],
+    "connect-src": ["'self'"],
+    "frame-ancestors": ["'none'"],
+    "base-uri": ["'self'"],
+    "form-action": ["'self'"],
+    "object-src": ["'none'"],
+};
+const SCRIPT_HASH_PATTERN = /^sha256-[A-Za-z0-9+/]{43}=$/;
+const DIRECTIVE_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+// Separators that would let an extension value end its own
+// directive, start a new one or break out of the header line.
+const FORBIDDEN_SOURCE_CHARS = /[;,\s]/;
+export function isScriptHash(value) {
+    return typeof value === "string" && SCRIPT_HASH_PATTERN.test(value);
+}
+function assertValidExtension(extend) {
+    for (const [directive, sources] of Object.entries(extend)) {
+        if (!DIRECTIVE_NAME_PATTERN.test(directive)) {
+            throw new Error(`[security-headers] csp.extend: invalid directive name "${directive}".`);
+        }
+        for (const source of sources) {
+            if (source.length === 0 || FORBIDDEN_SOURCE_CHARS.test(source)) {
+                throw new Error(`[security-headers] csp.extend["${directive}"]: source "${source}" must be a single token without whitespace, ";" or ",".`);
+            }
+        }
+    }
+}
+export function buildDefaultCsp(scriptHashes, extend = {}) {
+    assertValidExtension(extend);
+    const directives = new Map(Object.entries(DEFAULT_CSP_DIRECTIVES).map(([name, sources]) => [name, [...sources]]));
+    directives.get("script-src")?.push(...scriptHashes.map((hash) => `'${hash}'`));
+    for (const [name, sources] of Object.entries(extend)) {
+        const existing = directives.get(name) ?? [];
+        // 'none' is only valid as the sole source, so extending it replaces it.
+        const base = existing.length === 1 && existing[0] === "'none'" ? [] : existing;
+        directives.set(name, [...new Set([...base, ...sources])]);
+    }
+    return [...directives].map(([name, sources]) => [name, ...sources].join(" ")).join("; ");
+}
+function resolveCsp(option, scriptHashes) {
+    if (option === false)
+        return null;
+    if (typeof option === "string")
+        return option.length > 0 ? option : null;
+    return buildDefaultCsp(scriptHashes, option?.extend);
+}
+export function resolveSecurityHeaders(option, scriptHashes = []) {
     if (option === false)
         return [];
     const opt = option ?? {};
@@ -17,14 +67,15 @@ export function resolveSecurityHeaders(option) {
     const referrerPolicy = opt.referrerPolicy ?? DEFAULT_REFERRER_POLICY;
     if (referrerPolicy !== false)
         headers.push(["referrer-policy", referrerPolicy]);
-    if (opt.csp)
-        headers.push(["content-security-policy", opt.csp]);
+    const csp = resolveCsp(opt.csp, scriptHashes);
+    if (csp !== null)
+        headers.push(["content-security-policy", csp]);
     return headers;
 }
 // Sets each header only when absent so per-response values (e.g. the
 // per-host CSP from hostDispatch) always win over the runtime default.
-export function withSecurityHeaders(handler, option) {
-    const defaults = resolveSecurityHeaders(option);
+export function withSecurityHeaders(handler, option, scriptHashes = []) {
+    const defaults = resolveSecurityHeaders(option, scriptHashes);
     if (defaults.length === 0)
         return handler;
     return async (req, serveArg) => {