@cosmicdrift/kumiko-server-runtime 0.329.0 → 0.330.2

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

@@ -0,0 +1,471 @@
+/// <reference types="bun-types" preserve="true" />
+import { type AccountLockoutOptions, type AccountUnlockOptions, type AuthMailLocale, type AuthPaths, type EmailVerificationOptions, type InviteOptions, type PasswordResetOptions, type SignupOptions } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import { type SeedAdminOptions } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
+import { type ExtraRouteDefinition, type KumikoServeEnv, type PostAuthLandingResolver, type SseBroker } from "@cosmicdrift/kumiko-framework/api";
+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 { JobRunnerOptions } from "@cosmicdrift/kumiko-framework/jobs";
+import type { ObservabilityOptions, 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 SecurityHeadersOption } from "./security-headers.js";
+export { buildBunServeOptions } from "./bun-serve-options.js";
+export { addConfigAccessorFactory, buildBootExtraContext, resolveAuthMail, } from "./run-prod-app-boot-context.js";
+export { staticCachePolicy } from "./run-prod-app-static-files.js";
+export declare function requireEnv(name: string, src?: Record<string, string | undefined>, context?: string): string;
+/** Wrapper API for the password-reset flow.
+ *
+ *  Since the delivery migration PasswordResetOptions carries `appUrl`
+ *  (+ appName/locale) itself and the handler mails via ctx.notify — no
+ *  sendResetEmail callback anymore. Apps pass `auth.mail` (convenience,
+ *  resolveAuthMail builds the appUrl) OR an explicit block.
+ *
+ *  hmacSecret is optional here (unlike PasswordResetOptions): resolveAuthMail
+ *  backfills it, so overriding just appUrl needs no secret of its own. */
+export type PasswordResetSetup = Omit<PasswordResetOptions, "hmacSecret"> & {
+    readonly hmacSecret?: string;
+};
+/** Wrapper API for the email-verification flow, symmetric to
+ *  PasswordResetSetup (appUrl via delivery, optional hmacSecret). */
+export type EmailVerificationSetup = Omit<EmailVerificationOptions, "hmacSecret"> & {
+    readonly hmacSecret?: string;
+};
+/** Wrapper-API für Magic-Link Self-Signup. = SignupOptions (appUrl, die
+ *  Mail geht via delivery/ctx.notify wie reset/verify). Anders als reset/
+ *  verify gibt's KEIN hmacSecret — Signup-Tokens sind opaque random in
+ *  Redis, nicht HMAC-signed. */
+export type SignupSetup = SignupOptions;
+/** Wrapper-API für Tenant-Invite Magic-Link. = InviteOptions (appUrl, die
+ *  Invite-Mail geht via delivery wie reset/verify/signup). Drei accept-
+ *  Branches im framework; handler-names sind hardcoded in run-prod-app aus
+ *  AuthHandlers (analog signup). */
+export type InviteSetup = InviteOptions;
+/** Wrapper API for the account-unlock flow (#1266). = AccountUnlockOptions
+ *  (appUrl via delivery, symmetric to PasswordResetSetup). Self-service
+ *  escape hatch for accountLockout's monotonic failure counter — only
+ *  meaningful when `auth.accountLockout` is also set, but wired
+ *  independently like the other flows. */
+export type AccountUnlockSetup = AccountUnlockOptions;
+/** Wrapper API for the account-lockout brute-force guard on the login
+ *  handler. = AccountLockoutOptions (maxFailedAttempts, lockoutDurationMinutes
+ *  — no mail/appUrl fields, it doesn't mount any routes). Symmetric to
+ *  RunDevAppAuthOptions.accountLockout (kumiko-framework#1627) — before this,
+ *  `accountUnlock` existed on both wrappers with no way to ever set the
+ *  lockout it's meant to escape. */
+export type AccountLockoutSetup = AccountLockoutOptions;
+/** Auth-Mail-Convenience-Optionen — shared zwischen runProdApp + runDevApp.
+ *  Verdrahtet alle 4 Mail-Flows aus einem env-SMTP-Transport + Standard-
+ *  Templates (siehe `auth.mail` + resolveAuthMail). */
+export type AuthMailOptions = {
+    /** App-Basis-URL inkl. Schema (z.B. "https://app.example.com"). */
+    readonly baseUrl: string;
+    /** App-Name für Mail-Subject + Body. Default "Account". */
+    readonly appName?: string;
+    /** Locale für die Mail-Templates. Default "de". */
+    readonly locale?: AuthMailLocale;
+    /** "strict" blockt Login bis emailVerified; "off" mountet ohne Gate. */
+    readonly emailVerificationMode?: "strict" | "off";
+    /** Fallback-From-Adresse wenn `SMTP_FROM`-env fehlt (env gewinnt). */
+    readonly from?: string;
+    /** Einzelne Auth-Pfade überschreiben (Default DEFAULT_AUTH_PATHS). */
+    readonly paths?: Partial<AuthPaths>;
+    /** Reset/verify token secret, decoupled from JWT_SECRET rotation.
+     *  Falls back to resolveAuthMail's call-site secret when unset. */
+    readonly hmacSecret?: string;
+};
+export type RunProdAppAuthOptions = {
+    /** Initial admin user. Seeded once (idempotent — re-boots check first
+     *  whether the email is already in the users table). */
+    readonly admin: SeedAdminOptions;
+    /** Optional override of the login error → HTTP status map. */
+    readonly loginErrorStatusMap?: Readonly<Record<string, number>>;
+    /** Auth-Mail-Convenience: verdrahtet alle 4 Mail-Flows (passwordReset,
+     *  emailVerification, signup, invite) aus `auth.mail.baseUrl` + Standard-
+     *  Pfaden. Alle vier mailen via delivery (ctx.notify) — ersetzt das per-App
+     *  hand-gerollte `send*Email`-Callback-Wiring.
+     *
+     *  Null-Transport-Guard: ohne `SMTP_HOST`-env wird KEIN Mail-Flow
+     *  verdrahtet (Routes blieben sonst 500). Eine App die einen einzelnen
+     *  Flow custom braucht, setzt `passwordReset`/`signup`/… explizit —
+     *  der explizite Block gewinnt über den mail-Default.
+     *
+     *  Bewusste Entscheidung: `mail` mountet ALLE 4 Flows inkl. signup +
+     *  invite (Self-Registration on). Wer nur reset+verify will, lässt `mail`
+     *  weg und setzt die gewünschten Flows explizit — kein impliziter
+     *  Self-Signup. */
+    readonly mail?: AuthMailOptions;
+    /** Password-reset flow. When set, /api/auth/request-password-reset +
+     *  /api/auth/reset-password are mounted as public routes UND der
+     *  request/confirm-Handler im auth-email-password-Feature wird
+     *  registriert (sonst dispatchen die Routes ins Leere → 500).
+     *  Überschreibt den `mail`-Default für genau diesen Flow. */
+    readonly passwordReset?: PasswordResetSetup;
+    /** Email-verification flow. Symmetric to passwordReset. */
+    readonly emailVerification?: EmailVerificationSetup;
+    /** Self-Signup flow (Magic-Link). When set, /api/auth/signup-request +
+     *  /api/auth/signup-confirm are mounted; signup-confirm mintet JWT +
+     *  Cookies wie ein erfolgreicher login (Auto-Login direkt nach
+     *  Activation). */
+    readonly signup?: SignupSetup;
+    /** Tenant-Invite flow (Magic-Link). When set, /api/auth/invite-accept,
+     *  /api/auth/invite-accept-with-login, /api/auth/invite-signup-complete
+     *  are mounted. */
+    readonly invite?: InviteSetup;
+    /** Account-unlock flow (#1266). When set, /api/auth/request-account-unlock
+     *  + /api/auth/confirm-account-unlock are mounted. Self-service escape
+     *  hatch for accountLockout's monotonic failure-counter — confirming
+     *  clears the Redis lockout state, no entity write. */
+    readonly accountUnlock?: AccountUnlockSetup;
+    /** Brute-force guard on the login handler (maxFailedAttempts,
+     *  lockoutDurationMinutes). Mounts no routes — unlike the other flows,
+     *  it's a login-handler config knob, not a magic-link flow. Pair with
+     *  `accountUnlock` for a self-service escape hatch. */
+    readonly accountLockout?: AccountLockoutSetup;
+    /** Domain attribute for both auth cookies (see
+     *  AuthRoutesConfig.cookieDomain). Set to the registrable parent
+     *  domain when login and app live on different subdomains. */
+    readonly cookieDomain?: string;
+    /** Server-side Origin allowlist for the CSRF guard (see
+     *  AuthRoutesConfig.allowedOrigins). REQUIRED once `cookieDomain` is set —
+     *  buildServer fails closed otherwise. Apex + admin host, never tenant
+     *  subdomains. */
+    readonly allowedOrigins?: readonly string[];
+    /** Opt out of the Origin guard (see AuthRoutesConfig.unsafeSkipOriginCheck)
+     *  — accept the wide-cookie CSRF risk explicitly instead of setting
+     *  `allowedOrigins`. */
+    readonly unsafeSkipOriginCheck?: boolean;
+    /** Number of trusted reverse-proxy hops between the client and this
+     *  process for client-IP derivation (see AuthRoutesConfig.trustedProxyHops,
+     *  kumiko-framework#1539) — closes the X-Forwarded-For spoofing hole on
+     *  the auth rate-limiters. Falls back to the `KUMIKO_TRUSTED_PROXY_HOPS`
+     *  env var when unset; both unset means 0 hops, the safe socket-only
+     *  default (only the socket address counts, XFF ignored). Deprecated in
+     *  favor of the top-level `trustedProxyHops` option, which wins over
+     *  this and the env var. */
+    readonly trustedProxyHops?: number;
+    /** Server-computed post-auth redirect (see AuthRoutesConfig.postAuthLanding).
+     *  Result lands in the login/signup/invite response as `landingPath`; an
+     *  invalid path or a throwing resolver just omits the field. */
+    readonly postAuthLanding?: PostAuthLandingResolver;
+};
+/** Hook for app-specific seeding — runs after the admin (when auth is
+ *  active). Each seed is responsible for its own idempotence (seeds are
+ *  expected to check "is my row already there?" before inserting). */
+export type ProdSeedFn = (deps: {
+    db: import("@cosmicdrift/kumiko-framework/db").DbConnection;
+}) => Promise<void>;
+/** Boot-Time-Deps die `extraContext` + `anonymousAccess` Factories als
+ *  Argument bekommen. Closure dann in der returned Config (z.B. ein
+ *  TenantResolver der gegen `db` queriet, oder ein extraContext-Provider
+ *  der direkt SSE-Events publishen will). Single-source: identisch zu
+ *  setupTestStack's extraContext-Factory-Shape damit Test/Prod gleich
+ *  aussehen. */
+export type RunProdAppDeps = {
+    readonly db: import("@cosmicdrift/kumiko-framework/db").DbConnection;
+    readonly redis: Redis;
+    readonly registry: import("@cosmicdrift/kumiko-framework/engine").Registry;
+    readonly sseBroker: SseBroker;
+};
+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>);
+/** Per-host routing decision for the staticDir fallback, returned from
+ *  hostDispatch. Three modes:
+ *    - "html": serve a specific HTML file (relative to staticDir), optionally
+ *      with CSP. HTML never carries a schema — createKumikoApp fetches it
+ *      itself from the authenticated GET /api/schema, after the
+ *      clientFeature gates (auth) let it through.
+ *    - "redirect": 301/302 to the given location.
+ *    - "not-found": reject outright (e.g. unknown subdomain).
+ *
+ *  Only consulted when the path would otherwise fall through to the HTML
+ *  fallback — i.e. for "/", "/index.html", or SPA routes that neither Hono
+ *  matches nor a concrete disk file. Asset paths (/assets/*) and API paths
+ *  run independent of the host. */
+export type HostDispatchResult = {
+    readonly kind: "html";
+    readonly file: string;
+    /** @deprecated Ignored — HTML never carries the schema; createKumikoApp
+     *  fetches it from the authenticated GET /api/schema. */
+    readonly injectSchema?: boolean;
+    readonly csp?: string;
+} | {
+    readonly kind: "redirect";
+    readonly to: string;
+    readonly status?: 301 | 302;
+} | {
+    readonly kind: "not-found";
+};
+export type HostDispatchFn = (req: {
+    readonly host: string;
+    readonly path: string;
+    /** Query string incl. leading `?`, `""` if none. Redirects that
+     *  route the path to a different host (e.g. auth routes with
+     *  `?token=` from old mail links) MUST append it to `to`. */
+    readonly search: string;
+}, 
+/** `systemQuery` runs as the anonymous role (like PageHeadSystemQuery) —
+ *  hostDispatch is reachable by any public visitor, same access gate as a
+ *  real anonymous request. Lets a Multi-Tenant hostDispatch look up the
+ *  tenant for a subdomain instead of needing its own db handle. */
+deps: {
+    readonly systemQuery: PageHeadSystemQuery;
+}) => HostDispatchResult | Promise<HostDispatchResult>;
+export type { PageHeadMeta, PageHeadResolver, PageHeadSystemQuery };
+export type RunProdAppOptions = {
+    /** App-specific features. config/user/tenant/auth-email-password are
+     *  auto-mixed when `auth:` is set — don't add them yourself. */
+    readonly features: readonly FeatureDefinition[];
+    /** Opt-in boot-validator warnings — see ValidateBootOptions. */
+    readonly validateBootOptions?: ValidateBootOptions;
+    /** Listen-Port. Default 3000 (or $PORT). */
+    readonly port?: number;
+    /** Ceiling Bun.serve buffers a request body to before any app-level
+     *  body-limit middleware runs. Default is derived from `createFilesFeature`'s
+     *  configured `maxUploadSize`/field `maxSize` (see
+     *  resolveDerivedMaxRequestBodySize in bun-serve-options.ts) — override
+     *  only for a custom ceiling unrelated to that config. */
+    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[];
+    /** 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,
+     *  diff vs kumiko_es_operations-Table, läuft pending in Tx.
+     *  Plan: kumiko-platform/docs/plans/features/es-ops.md */
+    readonly seedsDir?: string;
+    /** Anonymous-access for public endpoints (same shape as runDevApp).
+     *  Akzeptiert entweder einen statischen Config-Object ODER eine
+     *  Factory `({db, redis, registry}) => Config` — die Factory wird
+     *  einmal zur Boot-Zeit aufgerufen, NACHDEM db/redis/registry konstruiert
+     *  sind. Der Caller closure'd typischerweise db/redis/registry in den
+     *  TenantResolver damit z.B. ein Subdomain → Tenant-Lookup gegen die
+     *  DB möglich ist (siehe samples/showcases/publicstatus für das
+     *  Multi-Tenant-Pattern). */
+    readonly anonymousAccess?: AnonymousAccessOption;
+    /** Static-file root for HTML / assets. Served on the catch-all route
+     *  for any path that doesn't match an /api/ handler. Use this for the
+     *  public status page HTML, embed widget JS, etc. */
+    readonly staticDir?: string;
+    /** Host-aware routing hook for multi-tenant + multi-app deployments
+     *  (e.g. publicstatus's `<sub>.publicstatus.eu` (public page) +
+     *  `admin.publicstatus.eu` (admin UI) + `publicstatus.eu` (apex/
+     *  marketing) in the SAME container).
+     *
+     *  Called when the staticDir fallback would generate an HTML response
+     *  (root or SPA route). Default behavior without hostDispatch: index.html
+     *  (single-app), no schema.
+     *
+     *  Schema safety: HTML (per-host as well as single-app) never carries an
+     *  AppSchema — createKumikoApp fetches it via GET /api/schema, which sits
+     *  behind the auth middleware and only serves non-anonymous, signed-in
+     *  users. Per-host CSP headers can additionally restrict asset paths. */
+    readonly hostDispatch?: HostDispatchFn;
+    /** Per-request head-metadata resolver (Open-Graph/title/description) for
+     *  the static-fallback HTML shell — see `PageHeadResolver`. Consulted on
+     *  the same two HTML-serving paths as `hostDispatch` (host-dispatched
+     *  HTML + the default single-app index.html), right before the response
+     *  is sent. On error, `null`, or a resolve time over 300ms, the shell
+     *  ships unchanged with status 200 — this must never turn into a 500 or
+     *  a blank page. `systemQuery` inside the resolver runs as the
+     *  anonymous role (not system) — the resolver is reachable by any
+     *  public visitor, same access gate as a real anonymous request. */
+    readonly resolvePageHead?: PageHeadResolver;
+    /** Pfad zu kumiko/migrations für den Boot-Gate. Default "./kumiko/
+     *  migrations" relativ zum process-cwd (wo die App gestartet wird —
+     *  bei Container-Deploys typischerweise der App-Workspace-Root, weil
+     *  WORKDIR im Dockerfile dorthin zeigt). Boot wirft SchemaDriftError
+     *  wenn Migrations pending sind oder erwartete Tabellen fehlen.
+     *  Setze auf `false` um den Gate komplett zu deaktivieren — nur für
+     *  Setups die ihren eigenen Schema-Check fahren (z.B. bring-your-own-
+     *  ORM). Standard-Apps lassen das default. */
+    readonly migrations?: {
+        readonly dir: string;
+    } | false;
+    /** Extra AppContext keys. Framework-Defaults werden zur Boot-Zeit
+     *  unter den Factory-Werten ergänzt, App-Werte gewinnen immer:
+     *    - `templateResolver` (createTemplateResolverApi(db)) — immer
+     *    - `secrets` (createSecretsContext) — nur wenn das `secrets`-Feature
+     *      gemountet ist (sonst kein KEK-env-Zwang für Apps ohne secrets)
+     *    - `configResolver` — im Auth-Mode (env-config-overrides)
+     *  Akzeptiert einen statischen Object ODER eine Factory
+     *  `({db, redis, registry}) => Record<string, unknown>` — gleiches
+     *  Pattern wie `anonymousAccess`. Eine App die einen dieser Keys selbst
+     *  setzt (z.B. eigener configResolver) überschreibt den Default. */
+    /** Boot default locale (BCP-47) for ctx.locale when the request carries
+     *  no locale signal. Merged into AppContext before extraContext (app wins). */
+    readonly defaultLocale?: string;
+    readonly extraContext?: ExtraContextOption;
+    /** MasterKeyProvider für die auto-verdrahtete `ctx.secrets`. Default:
+     *  `createEnvMasterKeyProvider` (KEK aus `KUMIKO_SECRETS_MASTER_KEY_V<n>`).
+     *  Override für KMS-Backends (AWS/GCP/Azure) statt env-KEK. Nur relevant
+     *  wenn das `secrets`-Feature gemountet ist. */
+    readonly masterKey?: MasterKeyProvider;
+    /** Subject-Key-Adapter für Crypto-Shredding (DSGVO Art. 17). Wenn gesetzt,
+     *  steht er Feature-Code als `ctx.kms` zur Verfügung und der Boot prüft
+     *  seine health() — die App startet nicht gegen ein unerreichbares KMS
+     *  (Silent-Start würde jeden PII-Read mit 503 beantworten). Kein Default:
+     *  ohne Adapter bleibt Crypto-Shredding aus. */
+    readonly kms?: KmsAdapter;
+    /** 32-Byte-Key (base64) für Blind-Index-HMACs auf `lookupable`-Feldern
+     *  (env: KUMIKO_BLIND_INDEX_KEY, `openssl rand -base64 32`). Bewusst
+     *  getrennt vom PLATFORM_KEK und nicht Teil des KmsAdapter-Contracts.
+     *  Pflicht sobald `kms` gesetzt ist UND ein Feature lookupable-Felder
+     *  deklariert — sonst bricht jeder Equality-Lookup auf Ciphertext
+     *  (Login by email!) und der Boot failt hart. */
+    readonly blindIndexKey?: string;
+    /** Explizites Opt-out aus dem harten PII-Boot-Gate: Features deklarieren
+     *  pii/userOwned/tenantOwned-Felder, aber es ist (noch) kein `kms`
+     *  provisioniert — die Felder liegen dann als KLARTEXT in Rows und
+     *  Events und DSGVO-Erasure via Crypto-Shredding ist unmöglich. Der Wert
+     *  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;
+    /** Deploy-Topologie. Default `true` (Single-Container): dieser Prozess
+     *  fährt HTTP + BEIDE Job-Lanes (api + worker) + den Event-Dispatcher
+     *  (MSP-Anwendung) inline — via `createAllInOneEntrypoint`. Damit laufen
+     *  worker-Lane-Crons (z.B. der Daten-Export `run-export-jobs`, default
+     *  `runIn:"worker"`) und r.multiStreamProjection ohne separaten Worker.
+     *
+     *  `false` NUR mit einem dezidierten Worker-Deployment setzen: dann fährt
+     *  dieser Prozess API-only (`createApiEntrypoint`), und worker-Lane-Jobs
+     *  + MSPs werden NICHT mehr lokal angewandt — der Worker muss sie
+     *  übernehmen, sonst bleiben Export-Jobs pending und die Read-Side leer
+     *  (2026-06-11-Incident-Klasse). */
+    readonly runSingleInstance?: boolean;
+    /** Job-Block. Wenn das Feature `r.job(...)` registriert, wird er
+     *  automatisch verdrahtet (siehe runSingleInstance). */
+    readonly jobs?: {
+        /** BullMQ-Queue-Prefix (default "kumiko"). */
+        readonly queueNamePrefix?: string;
+        /** Source of active tenant ids for `perTenant: true` jobs. Omit when the
+         *  tenant feature is mounted — the framework then resolves tenants on
+         *  its own via that feature's active-tenant-ids query. Only needed when
+         *  the app manages tenants outside that feature. */
+        readonly getActiveTenantIds?: JobRunnerOptions["getActiveTenantIds"];
+    };
+    /** Event-Dispatcher (MSP-Anwendung) im API-Process. Default AN —
+     *  runProdApp ist das Single-Container-Deployment, es gibt keinen
+     *  Worker-Process der multiStreamProjections anwenden könnte. Bis
+     *  2026-06-11 fehlte der Dispatcher hier komplett: jede MSP-basierte
+     *  Read-Projektion (z.B. custom-fields jsonb) blieb in Prod leer,
+     *  kumiko_event_consumers blieb ohne Rows. `disabled: true` nur für
+     *  Setups mit dezidiertem Worker-Process. */
+    readonly eventDispatcher?: {
+        readonly disabled?: boolean;
+        /** Poll-Intervall des Dispatcher-Loops (default siehe
+         *  createEventDispatcher). LISTEN/NOTIFY-Wiring kommt mit einem
+         *  späteren pgClient-Pass-through. */
+        readonly pollIntervalMs?: number;
+    };
+    /** Declarative HTTP-routes outside the /api/write|query|batch pipeline —
+     *  each entry declares its access tier (`entry`: "anonymous" | "user" |
+     *  "signature"), buildServer wires the matching guard + deps. Mounted
+     *  inside buildServer, right after the r.httpRoute loop, before seeds
+     *  (kumiko-framework#3050). */
+    readonly extraRoutes?: readonly ExtraRouteDefinition[];
+    /** Hook for app-wired co-running components that need the system-write
+     *  dispatcher (e.g. wiring a webhook plugin's system-scoped secrets, or
+     *  starting a co-running supervisor) — runs after buildServer, before
+     *  seeds, with NO `app` (routes are declared via `extraRoutes`, not
+     *  wired here). */
+    readonly wire?: (deps: SystemWireDeps) => void | Promise<void>;
+    /** When true (default), Bun.serve is started before runProdApp resolves —
+     *  the common case: `await runProdApp({...})` boots the server and the
+     *  process stays up listening on PORT. Set to false in tests that drive
+     *  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). */
+    readonly effectiveFeatures?: EffectiveFeaturesResolver;
+    /** Composed Zod-schema for env-validation (from `composeEnvSchema({
+     *  features, extend })` in @cosmicdrift/kumiko-framework/env). When set:
+     *  - `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;
+    /** 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. */
+    readonly pulumiPrefix?: string;
+    /** Handler for KumikoBootError. Default: print formatted error to
+     *  stderr and `process.exit(1)` so the container restarts with a
+     *  visible log line. Override in tests that drive runProdApp directly
+     *  (avoid the exit). Return type is `void` rather than `never` to keep
+     *  test-overrides honest — if a reporter returns, runProdApp falls
+     *  through to a regular `throw err` as the safety net. */
+    readonly bootErrorReporter?: (err: KumikoBootError) => void;
+    /** Override `process.env` for env-validation. Default: `process.env`.
+     *  Tests use this to feed crafted env-maps without polluting the
+     *  global. */
+    readonly envSource?: Record<string, string | undefined>;
+    /** Observability-Provider (Tracer + Meter). Default: Noop (kein Overhead,
+     *  kein `/metrics`-Endpoint). Setze `createPrometheusMeter()`-basierten
+     *  Provider + `metrics` um `/metrics` real zu exposen (publicstatus#91). */
+    readonly observability?: ObservabilityProvider;
+    /** Konfiguriert die Auto-Instrumentation des resolvierten Observability-
+     *  Providers (siehe `BaseEntrypointOptions.observabilityOptions`). */
+    readonly observabilityOptions?: ObservabilityOptions;
+    /** Aktiviert den `/metrics`-Endpoint (Open-Metrics-Format). Ohne einen
+     *  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"];
+    /** 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. */
+    readonly securityHeaders?: SecurityHeadersOption;
+    /** Number of trusted reverse-proxy hops for client-IP resolution — 1:1
+     *  durchgereicht an `buildServer`s
+     *  top-level `ServerOptions.trustedProxyHops`. Wins over the deprecated
+     *  `auth.trustedProxyHops` and `KUMIKO_TRUSTED_PROXY_HOPS`. Default 0 =
+     *  trust no proxy header, only the socket address (or "unknown") counts. */
+    readonly trustedProxyHops?: number;
+};
+export type ProdAppHandle = {
+    /** The composed entrypoint — AllInOne (runSingleInstance, default) or
+     *  Api-only (runSingleInstance:false). In KUMIKO_DRY_RUN_ENV mode WITH
+     *  `envSource` injected (test path), no boot ran and this slot is an
+     *  undefined-cast — do not access. Production dry-run hits
+     *  `process.exit(0)` before returning a handle. */
+    readonly entrypoint: ApiEntrypoint | AllInOneEntrypoint;
+    /** The fetch-handler — wired into Bun.serve in production, called
+     *  directly in tests. Composes Hono + static-fallback. Apps with
+     *  `autoListen: false` that call `Bun.serve` themselves must pass the
+     *  2nd arg from `server.requestIP(req)?.address`, extracted in their
+     *  outermost Bun fetch callback — `requestIP` only resolves for Bun's
+     *  original Request instance, never a cloned/rebuilt one. */
+    readonly fetch: (req: Request, socketAddress?: string) => Promise<Response> | Response;
+    /** Serves WebSocket-upgrade requests (r.webSocketRoute) with Bun's original
+     *  Request. Apps with `autoListen: false` that run their own `Bun.serve`
+     *  must pass it as `{ upgradeFetch }` in the 4th argument of `buildBunServeOptions` to get
+     *  WebSockets; `listen()` already wires it. */
+    readonly webSocketUpgradeFetch: (req: Request, env: KumikoServeEnv) => Promise<Response>;
+    /** Active Bun-server (only set when listen() was called — tests skip
+     *  listen() because Bun.serve isn't available under vitest/node). */
+    server?: ReturnType<typeof Bun.serve>;
+    /** Bind to PORT and start serving. Production calls this; tests don't. */
+    readonly listen: (port?: number) => Promise<void>;
+    readonly stop: () => Promise<void>;
+};
+export declare function runProdApp(options: RunProdAppOptions): Promise<ProdAppHandle>;