@cosmicdrift/kumiko-server-runtime 0.369.0 → 0.371.0

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

@@ -8,8 +8,8 @@ import { type ConfigResolver, type FeatureDefinition, type Registry } from "@cos
 import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
 import type { MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
 import type { Redis } from "ioredis";
-import { type BootCrypto } from "./boot/boot-crypto.js";
-import type { AuthMailOptions, EmailVerificationSetup, InviteSetup, PasswordResetSetup, SignupSetup } from "./run-prod-app.js";
+import { type BootCrypto } from "./boot/boot-crypto.ts";
+import type { AuthMailOptions, EmailVerificationSetup, InviteSetup, PasswordResetSetup, SignupSetup } from "./run-prod-app.ts";
 export declare function addConfigAccessorFactory<T extends {
     readonly configResolver?: ConfigResolver;
 }>(resolved: T, registry: Registry): T;
@@ -43,7 +43,9 @@ type AuthMailNormalizable = {
     readonly signup?: SignupSetup;
     readonly invite?: InviteSetup;
 };
-export declare function resolveAuthMail<T extends AuthMailNormalizable>(auth: T, hmacSecret: string, envSource: Record<string, string | undefined>): T & {
+export declare function resolveAuthMail<T extends AuthMailNormalizable>(auth: T, hmacSecret: string, envSource: Record<string, string | undefined>, mailWiring?: {
+    readonly mailConfigured?: boolean;
+}): T & {
     readonly passwordReset?: PasswordResetOptions;
     readonly emailVerification?: EmailVerificationOptions;
 };

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

@@ -185,7 +185,7 @@ function backfillTokenSecrets(auth, tokenSecret) {
         }),
     };
 }
-export function resolveAuthMail(auth, hmacSecret, envSource) {
+export function resolveAuthMail(auth, hmacSecret, envSource, mailWiring = {}) {
     // Runs before the mail/SMTP guards below so an app-supplied block without
     // hmacSecret is backfilled even without a `mail` block; an explicit secret still wins.
     const tokenSecret = auth.mail?.hmacSecret ?? hmacSecret;
@@ -196,7 +196,9 @@ export function resolveAuthMail(auth, hmacSecret, envSource) {
     // 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?".
-    if (!createSmtpTransportFromEnv(envSource, { fallbackFrom: auth.mail.from ?? "noreply@localhost" })) {
+    // 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);

package/dist/run-prod-app-static-files.d.ts

@@ -1,11 +1,15 @@
 import { type CachePolicy } from "@cosmicdrift/kumiko-framework/api";
-import { type QueryDispatcher } from "./request-bound-system-query.js";
-import type { HostDispatchFn, PageHeadResolver } from "./run-prod-app.js";
+import { type QueryDispatcher } from "./request-bound-system-query.ts";
+import type { HostDispatchFn, PageHeadResolver } from "./run-prod-app.ts";
+import type { SecurityHeadersOption } from "./security-headers.ts";
 export declare function readStaticFile(filePath: string): Promise<{
     readonly bytes: Uint8Array;
     readonly mime: string;
     readonly mtimeMs: number;
 } | undefined>;
+/** Hashes for the default CSP. Only an app that keeps the default CSP and serves a
+ *  staticDir needs them; a missing or broken file leaves inline scripts blocked, so boot says so. */
+export declare function resolveCspScriptHashes(staticDir: string | undefined, securityHeaders: SecurityHeadersOption | undefined): Promise<readonly string[]>;
 export declare function serveDiskFile(req: Request, pathname: string, file: {
     readonly bytes: Uint8Array;
     readonly mime: string;

package/dist/run-prod-app-static-files.js

@@ -1,9 +1,10 @@
-import { resolve, sep } from "node:path";
+import { join, resolve, sep } from "node:path";
 import { cachedResponse, computeStrongEtag, computeWeakEtag, createClientIpResolver, } from "@cosmicdrift/kumiko-framework/api";
 import { resolveAndInjectPageHead } from "@cosmicdrift/kumiko-headless/apex";
 import { errorCodeOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { ASSETS_DIR } from "./build-prod-bundle.js";
 import { BUNDLED_ASSETS_DIST_DIR } from "./bundled-assets.js";
+import { CSP_HASHES_FILE, parseCspHashes } from "./csp-hashes.js";
 import { buildRequestBoundSystemQuery, } from "./request-bound-system-query.js";
 import { stripNoRouteMatchHeader, tryHonoFirst } from "./try-hono-first.js";
 // Static-asset + SPA-fallback serving for runProdApp's HTTP handler. Split
@@ -48,6 +49,26 @@ export async function readStaticFile(filePath) {
         throw err;
     }
 }
+/** Hashes for the default CSP. Only an app that keeps the default CSP and serves a
+ *  staticDir needs them; a missing or broken file leaves inline scripts blocked, so boot says so. */
+export async function resolveCspScriptHashes(staticDir, securityHeaders) {
+    if (staticDir === undefined || securityHeaders === false)
+        return [];
+    const csp = securityHeaders?.csp;
+    if (csp === false || typeof csp === "string")
+        return [];
+    const file = await readStaticFile(join(staticDir, CSP_HASHES_FILE));
+    const result = file ? parseCspHashes(new TextDecoder().decode(file.bytes)) : undefined;
+    if (result?.kind === "found")
+        return result.scriptSrc;
+    const problem = result === undefined
+        ? `${CSP_HASHES_FILE} not found in ${staticDir} (written by kumiko build)`
+        : `${CSP_HASHES_FILE} is invalid: ${result.kind === "invalid" ? result.problem : ""}`;
+    // biome-ignore lint/suspicious/noConsole: boot-time warn, no logger configured this early
+    console.warn(`[runProdApp] ${problem}; the default CSP carries no inline-script hashes, so inline scripts in the served HTML are blocked. ` +
+        "Rebuild with kumiko build, or set securityHeaders.csp.");
+    return [];
+}
 // Bundled assets are server-side inputs (readBundledAsset), never public URLs.
 // Compared on the resolved path, not the URL prefix: "//kumiko-bundled-assets/x"
 // or a case variant on a case-insensitive disk would slip past a prefix check.

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

@@ -6,21 +6,32 @@ import { type KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
 import { type EffectiveFeaturesResolver, type FeatureDefinition, type ValidateBootOptions } from "@cosmicdrift/kumiko-framework/engine";
 import { type AllInOneEntrypoint, type ApiEntrypoint } from "@cosmicdrift/kumiko-framework/entrypoint";
 import { type ComposedEnvSchema, KumikoBootError } from "@cosmicdrift/kumiko-framework/env";
+import { type DryRunEnvMode } from "@cosmicdrift/kumiko-framework/env/dry-run";
 import type { ErrorDocsConfig } from "@cosmicdrift/kumiko-framework/errors";
 import type { JobRunnerOptions } from "@cosmicdrift/kumiko-framework/jobs";
 import { type ObservabilityOptions, type ObservabilityProvider } from "@cosmicdrift/kumiko-framework/observability";
 import type { MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
 import type { PageHeadMeta, PageHeadResolver, PageHeadSystemQuery } from "@cosmicdrift/kumiko-headless/apex";
 import { Redis } from "ioredis";
-import { type SystemWireDeps } from "./extra-routes-deps.js";
-import { type UnsubscribeOption } from "./resolve-unsubscribe-wiring.js";
-import { type SecurityHeadersOption } from "./security-headers.js";
-import { type SeedCreateFileRef } from "./seed-dispatcher.js";
-export { buildBunServeOptions } from "./bun-serve-options.js";
-export { resolveUnsubscribeWiring, type UnsubscribeOption, } 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";
+import type { BillingBootOption } from "./boot-options/billing-option.ts";
+import type { DemoModeOption } from "./boot-options/demo-mode.ts";
+import type { FileStorageBootOption } from "./boot-options/file-storage-option.ts";
+import type { KmsMode } from "./boot-options/kms-mode.ts";
+import type { MailBootOption } from "./boot-options/mail-option.ts";
+import { type SignalsOption } from "./boot-options/process-signals.ts";
+import type { ProdSeedsConfig } from "./boot-options/seed-shortcuts.ts";
+import { type SystemWireDeps } from "./extra-routes-deps.ts";
+import { type RateLimitOption } from "./rate-limit-defaults.ts";
+import { type UnsubscribeOption } from "./resolve-unsubscribe-wiring.ts";
+import { type SecurityHeadersOption } from "./security-headers.ts";
+import { type SeedCreateFileRef } from "./seed-dispatcher.ts";
+export { buildBunServeOptions } from "./bun-serve-options.ts";
+export { resolveUnsubscribeWiring, type UnsubscribeOption, } from "./resolve-unsubscribe-wiring.ts";
+export { addConfigAccessorFactory, buildBootExtraContext, loggerFromExtraContext, resolveAuthMail, } from "./run-prod-app-boot-context.ts";
+export { staticCachePolicy } from "./run-prod-app-static-files.ts";
 export declare function requireEnv(name: string, src?: Record<string, string | undefined>, context?: string): string;
+type RunMode = DryRunEnvMode;
+export declare function parseRunMode(raw: string | undefined): RunMode | null;
 /** Wrapper API for the password-reset flow.
  *
  *  Since the delivery migration PasswordResetOptions carries `appUrl`
@@ -193,6 +204,8 @@ export type RunProdAppDeps = {
     readonly redis: Redis;
     readonly registry: import("@cosmicdrift/kumiko-framework/engine").Registry;
     readonly sseBroker: SseBroker;
+    /** The env the boot runs on: process env or `envSource`, with the boot-option defaults (e.g. `fileStorage`) underneath. */
+    readonly env: Readonly<Record<string, string | undefined>>;
 };
 export type AnonymousAccessOption = import("@cosmicdrift/kumiko-framework/api").AnonymousAccessConfig | ((deps: RunProdAppDeps) => import("@cosmicdrift/kumiko-framework/api").AnonymousAccessConfig);
 export type ExtraContextOption = Record<string, unknown> | ((deps: RunProdAppDeps) => Record<string, unknown>);
@@ -258,8 +271,13 @@ export type RunProdAppOptions = {
     readonly maxRequestBodySize?: number;
     /** Auth-mode: standard features + routes wired, admin seeded. */
     readonly auth?: RunProdAppAuthOptions;
-    /** Custom seed functions, run after the admin seed (when auth-mode). */
-    readonly seeds?: readonly ProdSeedFn[];
+    /** Custom seed functions, run after the admin seed (when auth-mode). The
+     *  object form adds the declarative demo-tenant / demo-admin / sysadmin
+     *  seeds from the env and takes the functions under `run`; see
+     *  `ProdSeedsConfig`.
+     *  @example
+     *  seeds: { demoTenant: { key: "demo", name: "Demo" }, sysadminFromEnv: true, run: [seedDemoData] } */
+    readonly seeds?: readonly ProdSeedFn[] | ProdSeedsConfig;
     /** Pfad zum seeds-Directory für ES-Operations / Seed-Migrations
      *  (file-basiert wie drizzle-migrate). Wenn gesetzt + KUMIKO_SKIP_ES_OPS
      *  != "1": runProdApp scannt das Verzeichnis nach `<id>.ts` Files,
@@ -354,6 +372,39 @@ export type RunProdAppOptions = {
      *  ist eine Begründung für den Audit-Trail (z.B. "kms rollout pending,
      *  infra#188"). Ohne Flag und ohne `kms` bricht der Boot ab. */
     readonly allowPlaintextPii?: string;
+    /** Short form over `kms` / `blindIndexKey` / `allowPlaintextPii` that wires
+     *  the subject-key KMS from the env; not combinable with them. Unset keeps
+     *  today's behavior: no KMS unless `kms` is passed, and the PII boot gate
+     *  aborts when PII fields exist without one. See `KmsMode`.
+     *  @example
+     *  kmsMode: "required" */
+    readonly kmsMode?: KmsMode;
+    /** App-wide mail transport: mounts `channel-email` and wires the `auth.mail`
+     *  flows without an `SMTP_HOST` probe. See `MailBootOption`.
+     *  @example
+     *  mail: { transport: "smtp-env", from: "Acme <noreply@acme.example>" } */
+    readonly mail?: MailBootOption;
+    /** File provider for `file-foundation` plus the `FILE_STORAGE_PROVIDER`
+     *  default. See `FileStorageBootOption`.
+     *  @example
+     *  fileStorage: { provider: "auto" } */
+    readonly fileStorage?: FileStorageBootOption;
+    /** Stripe billing: `subscription-stripe` plus the tier-syncing webhook
+     *  route. Needs `billing-foundation` and `tier-engine`. See `BillingBootOption`.
+     *  @example
+     *  billing: { stripe: { priceToTier: { [env.STRIPE_PRICE_PRO]: "pro" } }, defaultTier: "free" } */
+    readonly billing?: BillingBootOption;
+    /** Live-demo mode: read-only gate in the fetch chain plus the anonymous
+     *  `GET /demo-mode` route. See `DemoModeOption`.
+     *  @example
+     *  demoMode: { readOnly: env.DEMO_READ_ONLY === "true", notice: { text: { en: "Read-only demo" } } } */
+    readonly demoMode?: DemoModeOption;
+    /** SIGTERM/SIGINT handling of `listen()`: drains via `stop()` (default
+     *  timeout 25 s), exits 0, or 1 when the drain fails or times out. `false`
+     *  leaves the signals to the app.
+     *  @example
+     *  signals: { drainTimeoutMs: 10_000 } */
+    readonly signals?: SignalsOption;
     /** Deploy topology. Default `true` (single container): this process runs
      *  HTTP, both job lanes (api + worker) and the event dispatcher (MSP apply)
      *  inline via `createAllInOneEntrypoint`. Worker-lane crons (e.g. the data
@@ -423,23 +474,22 @@ export type RunProdAppOptions = {
      *  the fetch-handler directly (Bun.serve isn't available under vitest +
      *  node), then call handle.listen() manually if needed. */
     readonly autoListen?: boolean;
-    /** Feature-toggle resolver — durchgereicht an createApiEntrypoint's
-     *  dispatcherOptions. Sprint-8 Tier-Composition: per-Tenant unterschied-
-     *  liche features aktiv via globalFeatureToggleRuntime. Pattern:
-     *  createLateBoundHolder + post-boot runtime.initialize in einem
-     *  seed-fn (db ist erst nach migrations + features ready). */
+    /** Per-tenant feature resolver, passed to the dispatcher.
+     *  @deprecated Removed in the next release. `createTierEngineFeature({ tierMap })`
+     *  (or `composeSaasStack`) builds the resolver at boot, and prod-only features
+     *  come from the `mail`, `fileStorage` and `billing` options. */
     readonly effectiveFeatures?: EffectiveFeaturesResolver;
     /** Composed Zod-schema for env-validation (from `composeEnvSchema({
-     *  features, extend })` in @cosmicdrift/kumiko-framework/env). When set:
+     *  core, features, extend })` in @cosmicdrift/kumiko-framework/env):
      *  - `process.env` is parsed against it BEFORE any boot work; missing
      *    or invalid vars throw a `KumikoBootError` listing ALL problems
      *    at once (not first-fail).
      *  - `KUMIKO_DRY_RUN_ENV=human|json|pulumi|k8s` introspects the schema
      *    and prints the env-var inventory, then exits without booting.
-     *
-     *  9.1 is additive: features that still read `process.env` directly
-     *  keep working. Migration to the schema is Sprint-9.2-9.5. */
-    readonly envSchema?: ComposedEnvSchema;
+     *  - `KUMIKO_DRY_RUN_ENV=boot` prints a per-variable table. With required
+     *    values missing it exits 0 without validating the feature wiring; an
+     *    invalid value exits 1; a complete env runs the boot validators. */
+    readonly envSchema: ComposedEnvSchema;
     /** Prefix for `pulumi config set <prefix><CamelCase(VAR)>` in dry-run
      *  output and boot-error suggestions. Without this, suggestions use
      *  bare `camelCase(VAR)` and ops has to guess the app prefix. */
@@ -466,16 +516,18 @@ export type RunProdAppOptions = {
      *  PrometheusMeter-basierten `observability`-Provider antwortet `/metrics`
      *  mit 503 + Misconfiguration-Hinweis statt echter Metriken. */
     readonly metrics?: import("@cosmicdrift/kumiko-framework/api").ServerOptions["metrics"];
-    /** L1 (Login-Lockout) + L2 (globaler IP-Limit) Rate-Limit-Middleware —
-     *  1:1 durchgereicht an `buildServer`s `ServerOptions.rateLimit`. Ohne
-     *  dieses Feld wird kein L1/L2 verdrahtet (L3 Handler-`rateLimit:`
-     *  funktioniert unabhängig davon bereits). */
-    readonly rateLimit?: import("@cosmicdrift/kumiko-framework/api").ServerOptions["rateLimit"];
+    /** L1 (global per-IP limit) + L2 (auth endpoints) rate-limit middleware, passed
+     *  to `buildServer`'s `ServerOptions.rateLimit`. Without a value L1 allows 600/60 s
+     *  and L2 30/60 s; a partial value overrides only the fields it names, `false`
+     *  (whole option or one layer) switches it off. Behind a reverse proxy the
+     *  client-IP key needs `trustedProxyHops`, otherwise all clients share one bucket. */
+    readonly rateLimit?: RateLimitOption;
     /** Default security headers on every response (HSTS, X-Frame-Options,
-     *  X-Content-Type-Options, Referrer-Policy; CSP opt-in). Headers already
-     *  set by a response (e.g. hostDispatch's per-host CSP) are never
-     *  overridden. `false` disables the whole block; per-header overrides
-     *  via the object form — see SecurityHeadersOption. */
+     *  X-Content-Type-Options, Referrer-Policy, Content-Security-Policy with
+     *  the build's inline-script hashes). Headers already set by a response
+     *  (e.g. hostDispatch's per-host CSP) are never overridden. `false`
+     *  disables the whole block; per-header overrides via the object form —
+     *  see SecurityHeadersOption. */
     readonly securityHeaders?: SecurityHeadersOption;
     /** Number of trusted reverse-proxy hops for client-IP resolution — 1:1
      *  durchgereicht an `buildServer`s