@cosmicdrift/kumiko-dev-server 0.328.1 → 0.330.0

package/src/run-dev-app.ts

@@ -1,694 +0,0 @@
-// High-level dev-server wrapper for sample apps and showcases. In auth mode it
-// mixes in the standard features (config/user/tenant/auth-email-password),
-// wires AuthRoutesConfig plus the login error map and calls seedAdminGuarded()
-// in onAfterSetup, cutting a sample bootstrap from ~50 lines to 5-10.
-//
-// Auto-mix passiert NUR im auth-mode. Ohne `auth`-Block bleibt der
-// Server im Auto-Mint-JWT-Modus (Dev-Default) und mischt nichts dazu —
-// Showcases die nur eine Domain demonstrieren wollen ohne Login-Flow
-// haben so nicht plötzlich vier zusätzliche Features in der Registry.
-//
-// Wer maximale Kontrolle braucht (z.B. abweichende Auth-Wiring,
-// alternativer Membership-Query, eigener LoginRateLimiter): geht direkt
-// auf `createKumikoServer` aus @cosmicdrift/kumiko-dev-server.
-
-import {
-  AuthErrors,
-  AuthHandlers,
-  AuthQueries,
-} from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
-import {
-  type SeedAdminOptions,
-  seedAdminGuarded,
-} from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
-import {
-  EXT_SESSION_STORE,
-  resolveSessionStore,
-  resolveTokenVerifier,
-  type SessionStore,
-} from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
-import {
-  AUTH_MFA_FEATURE,
-  AuthMfaHandlers,
-  bindMfaRevokeAllOtherSessionsFromFeature,
-  bindRevokeAllPatTokensFromFeature,
-} from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
-import {
-  buildEnvConfigOverrides,
-  createConfigResolver,
-} from "@cosmicdrift/kumiko-bundled-features/config";
-import {
-  bindPatAutoRevokeOnPasswordChangeFromFeature,
-  PAT_FEATURE,
-  patRateLimitFromFeature,
-  revokeAllPatTokensForUser,
-} from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
-import {
-  bindAutoRevokeFromFeature,
-  SESSIONS_FEATURE,
-} from "@cosmicdrift/kumiko-bundled-features/sessions";
-import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
-import type {
-  PostAuthLandingResolver,
-  SessionMetadata,
-  TokenVerifier,
-} from "@cosmicdrift/kumiko-framework/api";
-import {
-  createInMemoryLoginRateLimiter,
-  parseTrustedProxyHopsEnv,
-  TRUSTED_PROXY_HOPS_ENV,
-} from "@cosmicdrift/kumiko-framework/api";
-import {
-  configureBlindIndexKey,
-  configurePiiSubjectKms,
-  type KmsAdapter,
-} from "@cosmicdrift/kumiko-framework/crypto";
-import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
-import {
-  collectWriteHandlerQns,
-  createRegistry,
-  type EffectiveFeaturesResolver,
-  type FeatureDefinition,
-  FILE_STORAGE_PROVIDER_BOOT_SENTINEL,
-  FILE_STORAGE_PROVIDER_ENV,
-  findTierResolverUsage,
-  type Registry,
-  type SessionUser,
-  type TenantId,
-  type TierResolverPlugin,
-  type ValidateBootOptions,
-  validateAppCustomScreenWriteQns,
-  validateBoot,
-} from "@cosmicdrift/kumiko-framework/engine";
-import type { EnvelopeCipher, MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
-import type { TestStack } from "@cosmicdrift/kumiko-framework/stack";
-import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
-import type { PageHeadResolver } from "@cosmicdrift/kumiko-headless/apex";
-import { applyBootSeeds } from "@cosmicdrift/kumiko-server-runtime/boot/apply-boot-seeds";
-import { resolveBootCrypto } from "@cosmicdrift/kumiko-server-runtime/boot/boot-crypto";
-import {
-  buildComposeAuthOptions,
-  composeFeatures,
-} from "@cosmicdrift/kumiko-server-runtime/compose-features";
-import { assertPiiBootInvariants } from "@cosmicdrift/kumiko-server-runtime/pii-boot-gate";
-import { assertSessionBootInvariants } from "@cosmicdrift/kumiko-server-runtime/session-boot-gate";
-import { watchAndRegenerate } from "./codegen";
-import {
-  type CreateKumikoServerOptions,
-  createKumikoServer,
-  type KumikoServerHandle,
-} from "./create-kumiko-server";
-import { renderWelcomeBanner } from "./welcome-banner";
-
-// Re-export der shared Auth-Setup-Types damit Apps nur einen Import-Pfad
-// brauchen. PasswordResetSetup / EmailVerificationSetup leben in
-// @cosmicdrift/kumiko-server-runtime (single source of truth) — hier nur
-// durchgereicht.
-export type {
-  AccountLockoutSetup,
-  AccountUnlockSetup,
-  AuthMailOptions,
-  EmailVerificationSetup,
-  InviteSetup,
-  PasswordResetSetup,
-  SignupSetup,
-} from "@cosmicdrift/kumiko-server-runtime/run-prod-app";
-
-import type {
-  AccountLockoutSetup,
-  AccountUnlockSetup,
-  AuthMailOptions,
-  EmailVerificationSetup,
-  InviteSetup,
-  PasswordResetSetup,
-  SignupSetup,
-} from "@cosmicdrift/kumiko-server-runtime/run-prod-app";
-import {
-  addConfigAccessorFactory,
-  buildBootExtraContext,
-  requireEnv,
-  resolveAuthMail,
-} from "@cosmicdrift/kumiko-server-runtime/run-prod-app";
-
-export type RunDevAppAuthOptions = {
-  /** Admin user to seed at boot. Idempotent — re-runs in persistent-DB
-   *  mode reuse the existing user. */
-  readonly admin: SeedAdminOptions;
-  /** Optional override of the login error → HTTP status map. Default
-   *  maps invalidCredentials → 401, noMembership → 403. */
-  readonly loginErrorStatusMap?: Readonly<Record<string, number>>;
-  /** Auth-Mail-Convenience — symmetrisch zu RunProdAppAuthOptions.mail.
-   *  Verdrahtet alle 4 Mail-Flows aus env-SMTP + Standard-Templates;
-   *  hmacSecret = `JWT_SECRET`-env (Dev-Fallback wenn ungesetzt). Ohne
-   *  `SMTP_HOST`-env bleiben die Flows unverdrahtet (Null-Transport-Guard).
-   *  Explizite Flow-Setups gewinnen über den mail-Default. */
-  readonly mail?: AuthMailOptions;
-  /** Password-reset flow. Wenn gesetzt werden /api/auth/request-password-
-   *  reset + /api/auth/reset-password als Public-Routes gemounted UND
-   *  der request/confirm-Handler im auth-email-password-Feature wird
-   *  registriert. Symmetrisch zu RunProdAppAuthOptions.passwordReset. */
-  readonly passwordReset?: PasswordResetSetup;
-  /** Email-verification flow. Symmetric to passwordReset. */
-  readonly emailVerification?: EmailVerificationSetup;
-  /** Self-signup flow (magic link). Symmetric to RunProdAppAuthOptions. */
-  readonly signup?: SignupSetup;
-  /** Tenant-invite flow (magic link). Symmetric. */
-  readonly invite?: InviteSetup;
-  /** Account-unlock flow (#1266). Symmetric to RunProdAppAuthOptions. */
-  readonly accountUnlock?: AccountUnlockSetup;
-  /** Brute-force guard on the login handler (maxFailedAttempts,
-   *  lockoutDurationMinutes). Mounts no routes. Symmetric to
-   *  RunProdAppAuthOptions.accountLockout (kumiko-framework#1627). */
-  readonly accountLockout?: AccountLockoutSetup;
-  /** Domain attribute for both auth cookies (see
-   *  AuthRoutesConfig.cookieDomain). Symmetric to RunProdAppAuthOptions. */
-  readonly cookieDomain?: string;
-  /** Server-side Origin allowlist for the CSRF guard (see
-   *  AuthRoutesConfig.allowedOrigins). Symmetric to RunProdAppAuthOptions —
-   *  required once `cookieDomain` is set. */
-  readonly allowedOrigins?: readonly string[];
-  /** Opt out of the Origin guard. Symmetric to RunProdAppAuthOptions. */
-  readonly unsafeSkipOriginCheck?: boolean;
-  /** Number of trusted reverse-proxy hops for client-IP derivation (see
-   *  AuthRoutesConfig.trustedProxyHops, kumiko-framework#1539). Symmetric to
-   *  RunProdAppAuthOptions — dev usually runs unproxied, so this is normally
-   *  left unset (default 0). */
-  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 (demo data, fixtures). Runs after the
- *  admin (when auth is active) in declared order. */
-export type SeedFn = (stack: TestStack) => Promise<void>;
-
-export type RunDevAppOptions = {
-  /** App-spezifische Features. Im auth-mode werden config/user/tenant/
-   *  auth-email-password automatisch dazu gemischt — KEIN doppeltes
-   *  manuelles Hinzufügen nötig. */
-  readonly features: readonly FeatureDefinition[];
-  /** Opt-in boot-validator warnings — see ValidateBootOptions. */
-  readonly validateBootOptions?: ValidateBootOptions;
-  /** Browser entry module, bundled to /client.js. Mutually exclusive with
-   *  `clientEntries`. */
-  readonly clientEntry?: string;
-  /** Multi-entry mode: one bundle (`/client-<name>.js`) and one HTML template
-   *  per entry; `hostDispatch` picks the entry per request. kumiko-build reads
-   *  the same list from package.json `kumiko.clientEntries`. Mutually exclusive
-   *  with `clientEntry`. */
-  readonly clientEntries?: CreateKumikoServerOptions["clientEntries"];
-  /** Multi-entry mode: per-request routing. Required with `clientEntries`,
-   *  otherwise the server cannot tell which HTML to serve. */
-  readonly hostDispatch?: CreateKumikoServerOptions["hostDispatch"];
-  /** Per-request head-metadata resolver — same option, same signature as
-   *  `runProdApp`'s `resolvePageHead`, so `bun dev` and every e2e that boots
-   *  through `runDevApp` show the same resolved head prod does. See
-   *  `CreateKumikoServerOptions.resolvePageHead` for the full contract. */
-  readonly resolvePageHead?: PageHeadResolver;
-  /** CSS-Entry. Default: package-export `@cosmicdrift/kumiko-renderer-web/styles.css`
-   *  wenn ein client-Entry gesetzt ist. `false` deaktiviert die CSS-Pipeline. */
-  readonly stylesheet?: string | false;
-  /** Tailwind `--watch` process on/off, see `CreateKumikoServerOptions.stylesheetWatch`. */
-  readonly stylesheetWatch?: boolean;
-  /** Eigenes HTML-Template; sonst minimal-Default (#root + client.js).
-   *  Im Multi-Entry-Mode ist es das Fallback-Template, wenn ein einzelner
-   *  Entry kein eigenes htmlPath setzt. */
-  readonly htmlPath?: string;
-  /** Listen-Port. Default 4173 (oder $PORT). */
-  readonly port?: number;
-  /** Extra-Verzeichnisse für den File-Watcher (Trigger Hot-Reload). */
-  readonly watchDirs?: readonly string[];
-  /** SIGINT/SIGTERM-Handler installieren (Default true; in Tests auf
-   *  false damit repeated boots keine Listener akkumulieren). */
-  readonly installSignalHandlers?: boolean;
-  /** Auth mode: standard features mixed in, auth routes wired, seedAdminGuarded
-   *  runs in onAfterSetup. Without `auth` the server stays in auto-mint JWT mode. */
-  readonly auth?: RunDevAppAuthOptions;
-  /** Eigene Seed-Funktionen, laufen nach dem Admin (wenn auth) in
-   *  Array-Reihenfolge. */
-  readonly seeds?: readonly SeedFn[];
-  /** Extra-AppContext-Keys. `templateResolver` (immer) + `secrets` (wenn das
-   *  secrets-Feature gemountet ist) + `configResolver` (auth-mode) werden
-   *  automatisch ergänzt — App-Werte gewinnen. Symmetrisch zu runProdApp. */
-  /** 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?: CreateKumikoServerOptions["extraContext"];
-  /** MasterKeyProvider für die auto-verdrahtete `ctx.secrets`. Default:
-   *  `createEnvMasterKeyProvider`. Override für KMS-Backends. Nur relevant
-   *  wenn das secrets-Feature gemountet ist. Symmetrisch zu runProdApp. */
-  readonly masterKey?: MasterKeyProvider;
-  /** Subject-Key-KMS für pii-annotierte Felder (Crypto-Shredding) — dev-
-   *  Pendant zu runProdApp({ kms }). Ephemere DB: InMemoryKmsAdapter reicht.
-   *  Persistente Dev-DB: createPgKmsAdapter gegen dieselbe DB, sonst sind
-   *  alte Rows nach dem Restart unlesbar (DEKs weg). Ohne Adapter: Klartext
-   *  + Boot-Warnung. */
-  readonly kms?: KmsAdapter;
-  /** 32-Byte-Key (base64) für Blind-Index-HMACs — Pflicht sobald `kms`
-   *  gesetzt ist und lookupable-Felder gemountet sind (sonst Boot-Abbruch,
-   *  symmetrisch zu runProdApp). */
-  readonly blindIndexKey?: string;
-  /** Env-Quelle für die ENV→config-app-override-Brücke (Keys mit `env:`
-   *  bekommen ihren env-Wert als app-override-Default — symmetrisch zu
-   *  runProdApp). Default `process.env`. Injizierbar als Test-Seam, damit
-   *  Tests eigene env-Werte reichen statt `process.env` global zu mutieren. */
-  readonly envSource?: Record<string, string | undefined>;
-  /** Anonymous-Access für Public-Endpoints — Requests ohne JWT laufen
-   *  als Pseudo-User mit Rolle `anonymous` durch, wenn der Handler die
-   *  Rolle in `access.roles` führt. */
-  readonly anonymousAccess?: CreateKumikoServerOptions["anonymousAccess"];
-  /** File-Storage-Provider — aktiviert die Upload-Routes (/api/files) +
-   *  `ctx.files`. Demos: `{ storageProvider: createInMemoryFileProvider() }`. */
-  readonly files?: CreateKumikoServerOptions["files"];
-  /** App-eigene HTTP-Routes (z.B. /feed.xml, /sitemap.xml) — wird ans
-   *  Hono-app gehängt, läuft VOR dem static-asset-Pfad. Symmetrisch zur
-   *  gleichnamigen Option in runProdApp. */
-  readonly extraRoutes?: CreateKumikoServerOptions["extraRoutes"];
-  /** Hook for app-wired co-running components — symmetric to
-   *  runProdApp.wire (kumiko-framework#3050). */
-  readonly wire?: CreateKumikoServerOptions["wire"];
-  /** Feature-toggle resolver — durchgereicht an createKumikoServer →
-   *  setupTestStack. Sprint-8 Tier-Composition: per-Tenant unterschied-
-   *  liche features aktiv via globalFeatureToggleRuntime. Pattern in
-   *  bin/server.ts: createLateBoundHolder + post-boot runtime.initialize
-   *  in einem seed-fn, weil die runtime stack.db braucht und die seed-
-   *  Funktionen nach setupTestStack laufen. */
-  readonly effectiveFeatures?: CreateKumikoServerOptions["effectiveFeatures"];
-  /** Print a first-run banner after the server starts (URL, admin login,
-   *  hot-reload hint, docs link). Default: off — apps that already log
-   *  their own startup shouldn't get double-printed. The scaffold template
-   *  (create-kumiko-app) flips this on so the first `bun dev` ends on
-   *  something the user can click. Pass an object to override the
-   *  features-dir hint or the docs URL. */
-  readonly welcomeBanner?: boolean | { readonly featuresDir?: string; readonly docsUrl?: string };
-  /** Forwarded to createKumikoServer → setupTestStack's top-level
-   *  `trustedProxyHops` — symmetric to
-   *  RunProdAppOptions.trustedProxyHops. Wins over the deprecated
-   *  `auth.trustedProxyHops`, which wins over the `KUMIKO_TRUSTED_PROXY_HOPS`
-   *  env var. Dev usually runs unproxied, so this is normally left unset
-   *  (default 0). */
-  readonly trustedProxyHops?: number;
-};
-
-export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServerHandle> {
-  // Auto-mix Standard-Features im auth-mode via composeFeatures (single
-  // source of truth — auch runProdApp und der per-app drizzle-Schema-
-  // Generator nutzen denselben Helper, damit Migration und Runtime nie
-  // auseinanderdriften können).
-  const envSource = options.envSource ?? process.env;
-  // auth.mail → normalisiert in die expliziten Flow-Felder (symmetrisch zu
-  // runProdApp). hmacSecret = JWT_SECRET-env (fail-fast, symmetrisch zu
-  // runProdApp). Ab hier IMMER effectiveAuth statt options.auth.
-  const effectiveAuth = options.auth
-    ? resolveAuthMail(options.auth, requireEnv("JWT_SECRET", envSource, "runDevApp"), envSource)
-    : undefined;
-  const composeAuthOptions = buildComposeAuthOptions(effectiveAuth);
-  const features = composeFeatures(options.features, {
-    includeBundled: !!effectiveAuth,
-    ...(composeAuthOptions && { authOptions: composeAuthOptions }),
-  });
-
-  // An explicitly wired file provider (options.files) satisfies the
-  // FILE_STORAGE_PROVIDER boot gate — set it before validateBoot runs. Only
-  // if WE set it (532/2): deleting it after use instead of leaving a
-  // permanent process.env mutation, so a second runDevApp call in the same
-  // process (no files this time) doesn't fall through the gate falsely.
-  const setFileStorageProviderEnv =
-    options.files !== undefined && process.env[FILE_STORAGE_PROVIDER_ENV] === undefined;
-  if (setFileStorageProviderEnv) {
-    process.env[FILE_STORAGE_PROVIDER_ENV] = FILE_STORAGE_PROVIDER_BOOT_SENTINEL;
-  }
-
-  // Boot-Validation als allererstes — vor fs-Watcher und Server. Dieselbe
-  // Fehlerklasse (unqualifizierte nav-/handler-QNs, screen-access etc.),
-  // die früher nur runProdApp fing und sonst erst den Prod-Pod im
-  // CrashLoopBackOff sterben ließ (#359). Wirft synchron, bevor ein
-  // Socket oder Watcher (codegen-Write) aufgeht.
-  try {
-    validateBoot(features, options.validateBootOptions);
-  } finally {
-    if (setFileStorageProviderEnv) delete process.env[FILE_STORAGE_PROVIDER_ENV];
-  }
-  warnIfNonUtcServerTimeZone();
-  validateAppCustomScreenWriteQns(process.cwd(), collectWriteHandlerQns(features));
-
-  // Codegen + File-Watcher — schreibt `<appRoot>/.kumiko/types.generated.d.ts`
-  // + `define.ts` aus den r.defineEvent-Aufrufen der App, einmal beim
-  // Boot UND danach bei jeder relevanten Änderung unter `<appRoot>/src/`.
-  // Idempotent (writeIfChanged) — der TS-Sprachserver kriegt nur einen
-  // Reload-Tick wenn sich tatsächlich was geändert hat.
-  //
-  // App-Root ist process.cwd() (bun-dev läuft vom App-Workspace). Der
-  // Watcher läuft solange der Dev-Server lebt; close() bei Shutdown
-  // wird über das createKumikoServer-Handle implizit erledigt (Bun's
-  // process-exit räumt fs.watch-handles auf).
-  // Sammelt alle Write-Handler-QNs für den Codegen — damit
-  // `types.generated.d.ts` eine `WriteHandlerQn`-Union exportieren
-  // kann, die dispatcher.write-Aufrufe client-seitig typisiert.
-  const handlerQns = collectWriteHandlerQns(features);
-  watchAndRegenerate({ appRoot: process.cwd(), handlerQns: [...handlerQns] });
-
-  // Sprint-8a Tier-Composition auto-wire: scan features for a
-  // tenantTierResolver-extension. If found AND user didn't supply own
-  // effectiveFeatures, we wire a late-bound wrapper here and fill it
-  // in onAfterSetup (where stack.db + stack.registry are available).
-  // App-Author sees nothing — `createTierEngineFeature(opts)` mounts +
-  // framework auto-wires.
-  const tierResolverUsage = options.effectiveFeatures ? undefined : findTierResolverUsage(features);
-  const tierResolverHolder: { resolver: EffectiveFeaturesResolver | undefined } = {
-    resolver: undefined,
-  };
-  const finalEffectiveFeatures: EffectiveFeaturesResolver | undefined =
-    options.effectiveFeatures ??
-    (tierResolverUsage
-      ? Object.assign(
-          (tenantId: TenantId) => {
-            // Defensive: Server starts AFTER onAfterSetup completes, so the
-            // resolver is filled before any request comes in. Throwing here
-            // means a programming error (boot order) rather than silent
-            // "all-features-on" misbehavior.
-            if (!tierResolverHolder.resolver) {
-              throw new Error(
-                "tier-resolver: extension found but resolver not yet built — boot order issue?",
-              );
-            }
-            return tierResolverHolder.resolver(tenantId);
-          },
-          {
-            // Late-bind: der echte trialGate hängt erst nach plugin.build() am
-            // holder.resolver. Delegieren (nicht kopieren), weil dieses
-            // Wrapper-Closure vor build() konstruiert wird. Kein Trial → false.
-            trialGate: (tenantId: TenantId, featureName: string): Promise<boolean> =>
-              tierResolverHolder.resolver?.trialGate?.(tenantId, featureName) ??
-              Promise.resolve(false),
-          },
-        )
-      : undefined);
-
-  // configResolver-default fürs config-feature — im auth-mode immer
-  // hinzufügen, im no-auth-mode dem Caller überlassen. Factory-form
-  // wird gewrap't damit der spread auf das aufgerufene Result greift,
-  // nicht auf die function selbst (no-op). Die ENV→config-Brücke (Keys mit
-  // `env:` → app-override-Default) läuft symmetrisch zu runProdApp; die
-  // throwaway-Registry hier extrahiert nur die config-Keys, weil der
-  // configResolver vor dem Server-Boot konstruiert wird (stack.registry
-  // gibt's erst onAfterSetup) — createKumikoServer baut intern seine eigene.
-  const bootCrypto = resolveBootCrypto(envSource, options.masterKey);
-  // App-wide cipher for `encrypted: true` entity fields (symmetrisch zu
-  // runProdApp) — executors resolve it lazily.
-  configureEntityFieldEncryption(bootCrypto.entityFieldCipher);
-  // Subject-KMS + Blind-Index (symmetrisch zu runProdApp). Dev warnt bei
-  // Klartext-PII statt zu failen; kms+lookupable ohne blindIndexKey bricht
-  // auch hier (Lookups wären in jedem Modus kaputt).
-  configurePiiSubjectKms(options.kms);
-  configureBlindIndexKey(options.blindIndexKey);
-  assertPiiBootInvariants(features, {
-    kms: options.kms,
-    blindIndexKey: options.blindIndexKey,
-    mode: "dev",
-  });
-  // Throwaway registry, built once and reused below — mirrors runProdApp's
-  // `createRegistry(features)` right after validateBoot (#2027). Symmetric
-  // sessionStoreProviderMounted check to runProdApp's (registry.getExtension-
-  // Usages, not a raw features.some(...) scan) so dev and prod never ask the
-  // same question two different ways again.
-  const registry = effectiveAuth ? createRegistry(features) : undefined;
-  const sessionStoreProviderMounted =
-    registry !== undefined && registry.getExtensionUsages(EXT_SESSION_STORE).length > 0;
-  assertSessionBootInvariants({
-    hasAuth: Boolean(effectiveAuth),
-    sessionStoreProviderMounted,
-    mode: "dev",
-  });
-  const cfgExtra = registry
-    ? mergeConfigResolverDefault(options.extraContext, registry, envSource, bootCrypto.configCipher)
-    : options.extraContext;
-  // Auto-wire templateResolver (immer) + secrets (feature-gated), symmetrisch zu
-  // runProdApp. Anders als prod existiert die db hier erst im Factory-deps
-  // (createKumikoServer baut den Stack), darum als Factory: buildBootExtraContext
-  // mit hasAuth:false (configResolver kommt schon aus cfgExtra), App-Werte
-  // (cfgExtra) gewinnen über die Boot-Defaults.
-  const extraContext: CreateKumikoServerOptions["extraContext"] = (deps) => {
-    const boot = buildBootExtraContext({
-      db: deps.db,
-      features,
-      envSource,
-      registry: deps.registry,
-      hasAuth: false,
-      sseBroker: deps.sseBroker,
-      crypto: bootCrypto,
-    });
-    const base = typeof cfgExtra === "function" ? cfgExtra(deps) : (cfgExtra ?? {});
-    return {
-      ...boot,
-      ...(options.defaultLocale !== undefined && { defaultLocale: options.defaultLocale }),
-      ...base,
-    };
-  };
-
-  // Sessions: late-bound holder — resolveSessionStore needs concrete db+
-  // registry (only after setupTestStack). Wired when sessions feature is
-  // mounted (#1372); no auth.sessions opt-in anymore.
-  let sessionStore: SessionStore | undefined;
-  const requireSessionStore = (): SessionStore => {
-    if (!sessionStore) {
-      throw new Error("[runDevApp] sessionStore accessed before onAfterSetup");
-    }
-    return sessionStore;
-  };
-  // Token-verifier opt-in: same late-bound holder pattern — resolveTokenVerifier
-  // needs the real db+registry (only concrete after setupTestStack). Wired
-  // whenever a provider feature (personal-access-tokens today) is mounted.
-  let tokenVerifier: TokenVerifier | undefined;
-  const patFeature = features.find((f) => f.name === PAT_FEATURE);
-  const mfaFeature = features.find((f) => f.name === AUTH_MFA_FEATURE);
-  const patAuthFragment = patFeature
-    ? {
-        tokenVerifier: (rawToken: string) => {
-          if (!tokenVerifier) {
-            throw new Error("[runDevApp] token-verifier accessed before onAfterSetup");
-          }
-          return tokenVerifier(rawToken);
-        },
-        patRateLimiter: (() => {
-          const rl = patRateLimitFromFeature(patFeature);
-          return createInMemoryLoginRateLimiter(rl.maxRequests, rl.windowMs);
-        })(),
-      }
-    : {};
-
-  // Parity with runProdApp (#1372 review): gate on sessionStore provider, not
-  // the sessions feature name — a custom provider must also wire auth
-  // callbacks. sessionStoreProviderMounted computed above via the registry
-  // (same check as runProdApp, #2027) — not recomputed here.
-  const sessionAuthFragment =
-    effectiveAuth && sessionStoreProviderMounted
-      ? {
-          sessionCreator: (user: SessionUser, meta: SessionMetadata) =>
-            requireSessionStore().creator(user, meta),
-          sessionRevoker: (sid: string) => requireSessionStore().revoker(sid),
-          sessionChecker: (sid: string, userId: string) =>
-            requireSessionStore().checker(sid, userId),
-        }
-      : {};
-
-  const trustedProxyHops =
-    options.trustedProxyHops ??
-    effectiveAuth?.trustedProxyHops ??
-    parseTrustedProxyHopsEnv(envSource[TRUSTED_PROXY_HOPS_ENV], "runDevApp");
-
-  const handle = await createKumikoServer({
-    features,
-    ...(options.clientEntry !== undefined && { clientEntry: options.clientEntry }),
-    ...(options.clientEntries !== undefined && { clientEntries: options.clientEntries }),
-    ...(options.hostDispatch !== undefined && { hostDispatch: options.hostDispatch }),
-    ...(options.resolvePageHead !== undefined && { resolvePageHead: options.resolvePageHead }),
-    ...(options.stylesheet !== undefined && { stylesheet: options.stylesheet }),
-    ...(options.stylesheetWatch !== undefined && { stylesheetWatch: options.stylesheetWatch }),
-    ...(options.htmlPath !== undefined && { htmlPath: options.htmlPath }),
-    ...(options.port !== undefined && { port: options.port }),
-    ...(options.watchDirs !== undefined && { watchDirs: options.watchDirs }),
-    ...(options.installSignalHandlers !== undefined && {
-      installSignalHandlers: options.installSignalHandlers,
-    }),
-    ...(extraContext !== undefined && { extraContext }),
-    ...(options.anonymousAccess !== undefined && { anonymousAccess: options.anonymousAccess }),
-    ...(options.files !== undefined && { files: options.files }),
-    ...(options.extraRoutes !== undefined && { extraRoutes: options.extraRoutes }),
-    ...(options.wire !== undefined && { wire: options.wire }),
-    ...(trustedProxyHops !== undefined && { trustedProxyHops }),
-    ...(finalEffectiveFeatures !== undefined && {
-      effectiveFeatures: finalEffectiveFeatures,
-    }),
-    ...(effectiveAuth && {
-      auth: {
-        membershipQuery: TenantQueries.memberships,
-        loginHandler: AuthHandlers.login,
-        loginErrorStatusMap: effectiveAuth.loginErrorStatusMap ?? {
-          [AuthErrors.invalidCredentials]: 401,
-          [AuthErrors.noMembership]: 403,
-        },
-        ...(effectiveAuth.cookieDomain !== undefined && {
-          cookieDomain: effectiveAuth.cookieDomain,
-        }),
-        ...(effectiveAuth.allowedOrigins !== undefined && {
-          allowedOrigins: effectiveAuth.allowedOrigins,
-        }),
-        ...(effectiveAuth.unsafeSkipOriginCheck !== undefined && {
-          unsafeSkipOriginCheck: effectiveAuth.unsafeSkipOriginCheck,
-        }),
-        ...(effectiveAuth.trustedProxyHops !== undefined && {
-          trustedProxyHops: effectiveAuth.trustedProxyHops,
-        }),
-        ...(effectiveAuth.postAuthLanding !== undefined && {
-          postAuthLanding: effectiveAuth.postAuthLanding,
-        }),
-        ...sessionAuthFragment,
-        ...patAuthFragment,
-        ...(mfaFeature && {
-          mfaVerifyHandler: AuthMfaHandlers.verify,
-          mfaPreauthEnableStartHandler: AuthMfaHandlers.enableStartPreauth,
-          mfaPreauthConfirmHandler: AuthMfaHandlers.enableConfirmPreauth,
-        }),
-        ...(effectiveAuth.passwordReset && {
-          passwordReset: {
-            requestHandler: AuthHandlers.requestPasswordReset,
-            confirmHandler: AuthHandlers.resetPassword,
-          },
-        }),
-        ...(effectiveAuth.emailVerification && {
-          emailVerification: {
-            requestHandler: AuthHandlers.requestEmailVerification,
-            confirmHandler: AuthHandlers.verifyEmail,
-          },
-        }),
-        ...(effectiveAuth.accountUnlock && {
-          accountUnlock: {
-            requestHandler: AuthHandlers.requestAccountUnlock,
-            confirmHandler: AuthHandlers.confirmAccountUnlock,
-          },
-        }),
-        ...(effectiveAuth.signup && {
-          signup: {
-            requestHandler: AuthHandlers.signupRequest,
-            confirmHandler: AuthHandlers.signupConfirm,
-          },
-        }),
-        ...(effectiveAuth.invite && {
-          invite: {
-            acceptHandler: AuthHandlers.inviteAccept,
-            acceptWithLoginHandler: AuthHandlers.inviteAcceptWithLogin,
-            signupCompleteHandler: AuthHandlers.inviteSignupComplete,
-            infoHandler: AuthQueries.inviteInfo,
-          },
-        }),
-      },
-    }),
-    onAfterSetup: async (stack) => {
-      // Sprint-8a: build tier-resolver BEFORE any seeds so seeds can rely
-      // on the resolver being live (e.g. seed that writes a SystemAdmin's
-      // tier-assignment can immediately read tier-cuts).
-      if (tierResolverUsage) {
-        const plugin = tierResolverUsage.options as TierResolverPlugin;
-        tierResolverHolder.resolver = await plugin.build({
-          db: stack.db,
-          registry: stack.registry,
-        });
-      }
-      if (effectiveAuth && stack.registry.getExtensionUsages(EXT_SESSION_STORE).length > 0) {
-        // Secure-by-default (#1372): resolve sessionStore provider; bind
-        // password-change mass-revoke + MFA revokeAllOthers.
-        const store = await resolveSessionStore({
-          db: stack.db,
-          registry: stack.registry,
-        });
-        const sessionsFeature = features.find((f) => f.name === SESSIONS_FEATURE);
-        if (sessionsFeature) {
-          bindAutoRevokeFromFeature(sessionsFeature)?.(store.massRevoker);
-        }
-        if (mfaFeature) {
-          bindMfaRevokeAllOtherSessionsFromFeature(mfaFeature)?.(store.revokeAllOthers);
-        }
-        if (mfaFeature && patFeature) {
-          bindRevokeAllPatTokensFromFeature(mfaFeature)?.((userId) =>
-            revokeAllPatTokensForUser(stack.db, userId),
-          );
-        }
-        sessionStore = store;
-      }
-      if (patFeature) {
-        tokenVerifier = (rawToken) =>
-          resolveTokenVerifier({ db: stack.db, registry: stack.registry }, rawToken);
-        // Password-change → PAT-revoke: independent of sessions/MFA being
-        // mounted, so wired unconditionally here whenever PAT itself is.
-        bindPatAutoRevokeOnPasswordChangeFromFeature(patFeature)?.((userId) =>
-          revokeAllPatTokensForUser(stack.db, userId),
-        );
-      }
-      if (effectiveAuth) {
-        await seedAdminGuarded(stack.db, effectiveAuth.admin);
-      }
-      // Apply r.config({ seeds }) declared by any registered feature.
-      // Runs before user-supplied seed callbacks so those can read /
-      // override the deploy-defaults. The helper indirection is what
-      // config-seed-boot.integration.ts pins — keep it as a single call.
-      await applyBootSeeds({
-        registry: stack.registry,
-        db: stack.db,
-        ...(bootCrypto.configCipher && { cipher: bootCrypto.configCipher }),
-      });
-      for (const seed of options.seeds ?? []) {
-        await seed(stack);
-      }
-    },
-  });
-
-  if (options.welcomeBanner) {
-    const overrides = typeof options.welcomeBanner === "object" ? options.welcomeBanner : {};
-    const port = handle.server?.port ?? options.port ?? 3000;
-    const banner = renderWelcomeBanner({
-      url: `http://localhost:${port}`,
-      ...(effectiveAuth?.admin && {
-        admin: {
-          email: effectiveAuth.admin.email,
-          password: effectiveAuth.admin.password,
-        },
-      }),
-      ...(overrides.featuresDir !== undefined && { featuresDir: overrides.featuresDir }),
-      ...(overrides.docsUrl !== undefined && { docsUrl: overrides.docsUrl }),
-    });
-    // biome-ignore lint/suspicious/noConsole: boot-time UX print, opt-in via welcomeBanner.
-    console.log(`\n${banner}\n`);
-  }
-
-  return handle;
-}
-
-// Exported for the wiring-contract test (config-resolver-default.integration):
-// pins that the dev configResolver-default carries the ENV→app-override bridge
-// and that a caller-supplied configResolver still overrides it. Not re-exported
-// from the package barrel (index.ts lists only runDevApp).
-export function mergeConfigResolverDefault(
-  ctx: CreateKumikoServerOptions["extraContext"],
-  registry: Registry,
-  envSource: Record<string, string | undefined>,
-  cipher?: EnvelopeCipher,
-): CreateKumikoServerOptions["extraContext"] {
-  const defaults = {
-    configResolver: createConfigResolver({
-      appOverrides: buildEnvConfigOverrides(registry, envSource),
-      ...(cipher && { cipher }),
-    }),
-  };
-  // ctx.config wird per-Request aus _configAccessorFactory geminted (siehe
-  // addConfigAccessorFactory) — sonst bleibt ctx.config undefined und Handler
-  // die es lesen (createFileProviderForTenant) werfen. Aus dem EFFEKTIVEN
-  // Resolver (Caller-Override gewinnt) gebaut, symmetrisch zu runProdApp.
-  if (ctx === undefined) return addConfigAccessorFactory(defaults, registry);
-  if (typeof ctx === "function") {
-    return (deps) => addConfigAccessorFactory({ ...defaults, ...ctx(deps) }, registry);
-  }
-  return addConfigAccessorFactory({ ...defaults, ...ctx }, registry);
-}