@cosmicdrift/kumiko-dev-server 0.328.1 → 0.330.0

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

@@ -0,0 +1,174 @@
+import { type SeedAdminOptions } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
+import type { PostAuthLandingResolver } from "@cosmicdrift/kumiko-framework/api";
+import { type KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import { type FeatureDefinition, type Registry, type ValidateBootOptions } from "@cosmicdrift/kumiko-framework/engine";
+import type { EnvelopeCipher, MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
+import type { TestStack } from "@cosmicdrift/kumiko-framework/stack";
+import type { PageHeadResolver } from "@cosmicdrift/kumiko-headless/apex";
+import { type CreateKumikoServerOptions, type KumikoServerHandle } from "./create-kumiko-server.js";
+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";
+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 declare function runDevApp(options: RunDevAppOptions): Promise<KumikoServerHandle>;
+export declare function mergeConfigResolverDefault(ctx: CreateKumikoServerOptions["extraContext"], registry: Registry, envSource: Record<string, string | undefined>, cipher?: EnvelopeCipher): CreateKumikoServerOptions["extraContext"];

package/dist/run-dev-app.js

@@ -0,0 +1,403 @@
+// 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 { seedAdminGuarded, } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
+import { EXT_SESSION_STORE, resolveSessionStore, resolveTokenVerifier, } 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 { createInMemoryLoginRateLimiter, parseTrustedProxyHopsEnv, TRUSTED_PROXY_HOPS_ENV, } from "@cosmicdrift/kumiko-framework/api";
+import { configureBlindIndexKey, configurePiiSubjectKms, } from "@cosmicdrift/kumiko-framework/crypto";
+import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
+import { collectWriteHandlerQns, createRegistry, FILE_STORAGE_PROVIDER_BOOT_SENTINEL, FILE_STORAGE_PROVIDER_ENV, findTierResolverUsage, validateAppCustomScreenWriteQns, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
+import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
+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/index.js";
+import { createKumikoServer, } from "./create-kumiko-server.js";
+import { renderWelcomeBanner } from "./welcome-banner.js";
+import { addConfigAccessorFactory, buildBootExtraContext, requireEnv, resolveAuthMail, } from "@cosmicdrift/kumiko-server-runtime/run-prod-app";
+export async function runDevApp(options) {
+    // 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: undefined,
+    };
+    const finalEffectiveFeatures = options.effectiveFeatures ??
+        (tierResolverUsage
+            ? Object.assign((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, featureName) => 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 = (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;
+    const requireSessionStore = () => {
+        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;
+    const patFeature = features.find((f) => f.name === PAT_FEATURE);
+    const mfaFeature = features.find((f) => f.name === AUTH_MFA_FEATURE);
+    const patAuthFragment = patFeature
+        ? {
+            tokenVerifier: (rawToken) => {
+                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, meta) => requireSessionStore().creator(user, meta),
+            sessionRevoker: (sid) => requireSessionStore().revoker(sid),
+            sessionChecker: (sid, userId) => 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;
+                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, registry, envSource, cipher) {
+    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);
+}

package/dist/scaffold-app-feature.d.ts

@@ -0,0 +1,16 @@
+export type ScaffoldAppFeatureOptions = {
+    /** kebab-case feature name (e.g. "product-catalog"). */
+    readonly name: string;
+    /** App workspace root. Defaults to cwd. */
+    readonly appRoot?: string;
+};
+export type ScaffoldAppFeatureResult = {
+    readonly featureName: string;
+    readonly featureDir: string;
+    readonly files: readonly string[];
+    /** Whether src/run-config.ts was auto-mounted. False if run-config
+     *  is missing — caller gets the scaffolded files but must hand-mount. */
+    readonly autoMounted: boolean;
+};
+export declare function scaffoldAppFeature(options: ScaffoldAppFeatureOptions): ScaffoldAppFeatureResult;
+export declare function runConfigPathForApp(appRoot: string): string;