@cosmicdrift/kumiko-dev-server 0.387.0 → 0.389.0

package/dist/run-dev-app.js

@@ -11,222 +11,103 @@
 // For maximum control, such as custom auth wiring, a different membership
 // query, or a custom LoginRateLimiter, use `createKumikoServer` directly from
 // @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, bindMfaTokenSecretsFromFeature, 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, requireTierResolverPlugin, validateAppCustomScreenWriteQns, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
-import { parseEnv } from "@cosmicdrift/kumiko-framework/env";
-import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
-import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
-import { assertStackBootRequirements, isSeedFnList, rejectRemovedEffectiveFeatures, resolveBootOptionWiring, withBootOptionEnvBlocks, } from "@cosmicdrift/kumiko-server-runtime";
-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 { createKumikoServer, logInfo, } from "./create-kumiko-server.js";
-import { captureEphemeralDevPiiKms, resolveDevPiiKms, } from "./resolve-dev-pii-kms.js";
+import { createConfigResolver } from "@cosmicdrift/kumiko-bundled-features/config";
+import { parseTrustedProxyHopsEnv, TRUSTED_PROXY_HOPS_ENV, } from "@cosmicdrift/kumiko-framework/api";
+import { findTierResolverUsage, } from "@cosmicdrift/kumiko-framework/engine";
+import { createKumikoServer, } from "./create-kumiko-server.js";
+import { createDevLateBindings, createLateBoundEffectiveFeatures, runDevAfterSetup, wireDevAuth, } from "./run-dev-app-auth.js";
+import { configureDevBootCrypto, resolveDevAuthRegistry, resolveDevBootConfig, validateDevBoot, } from "./run-dev-app-config.js";
+import { buildDevServerOptions } from "./run-dev-app-server-options.js";
 import { renderWelcomeBanner } from "./welcome-banner.js";
-import { addConfigAccessorFactory, buildBootExtraContext, loggerFromExtraContext, requireEnv, resolveAuthMail, resolveUnsubscribeWiring, } from "@cosmicdrift/kumiko-server-runtime/run-prod-app";
+import { addConfigAccessorFactory, buildBootExtraContext, buildConfigOverrides, loggerFromExtraContext, } from "@cosmicdrift/kumiko-server-runtime/run-prod-app";
 export async function runDevApp(options) {
-    // Automatically mixes standard features in auth mode through composeFeatures.
-    // runProdApp and the per-app Drizzle schema generator use the same helper,
-    // keeping migrations and runtime feature composition aligned.
-    const rawEnvSource = options.envSource ?? process.env;
-    const seedsConfig = options.seeds !== undefined && !isSeedFnList(options.seeds) ? options.seeds : undefined;
-    const stackSeeds = options.seeds === undefined
-        ? []
-        : isSeedFnList(options.seeds)
-            ? options.seeds
-            : (options.seeds.run ?? []);
-    if (options.envSchema) {
-        // Free dev seeds take the test stack; the env blocks only read the declarative part.
-        const { seeds: _devSeeds, kms: devKms, ...bootFields } = options;
-        const composed = withBootOptionEnvBlocks(options.envSchema, {
-            ...bootFields,
-            ...(devKms && { kms: devKms }),
-            ...(seedsConfig && { seeds: { ...seedsConfig, run: [] } }),
-            features: options.features,
-        });
-        parseEnv(composed.schema, rawEnvSource, { sources: composed.sources });
+    const bootFailure = { release: undefined };
+    try {
+        return await bootDevApp(options, bootFailure);
     }
-    rejectRemovedEffectiveFeatures(options);
-    const wiring = await resolveBootOptionWiring({
-        features: options.features,
-        ...(options.mail && { mail: options.mail }),
-        ...(options.fileStorage && { fileStorage: options.fileStorage }),
-        ...(options.kmsMode !== undefined && { kmsMode: options.kmsMode }),
-        ...(options.billing && { billing: options.billing }),
-        ...(options.featureToggles && { featureToggles: true }),
-        ...(options.demoMode && { demoMode: options.demoMode }),
-        ...(seedsConfig && { seeds: { ...seedsConfig, run: [] } }),
-        ...(options.kms && { kms: options.kms }),
-        ...(options.blindIndexKey !== undefined && { blindIndexKey: options.blindIndexKey }),
-        ...(options.auth && { auth: options.auth }),
-    }, rawEnvSource);
-    const envSource = Object.keys(wiring.envDefaults).length > 0
-        ? { ...wiring.envDefaults, ...rawEnvSource }
-        : rawEnvSource;
-    assertStackBootRequirements({
-        features: options.features,
-        ...(options.featureToggles && { featureToggles: true }),
-    }, ["featureToggles"]);
-    // Normalizes auth.mail into the explicit flow fields, symmetrically with
-    // runProdApp. hmacSecret is read from the JWT_SECRET environment value and
-    // fails fast when unavailable. From this point on, use effectiveAuth rather
-    // than options.auth.
-    const effectiveAuth = options.auth
-        ? resolveAuthMail(options.auth, requireEnv("JWT_SECRET", envSource, "runDevApp"), envSource, {
-            mailConfigured: wiring.mailConfigured,
-        })
-        : undefined;
-    const composeAuthOptions = buildComposeAuthOptions(effectiveAuth);
-    const { unsubscribeLinks, unsubscribeRoutes } = resolveUnsubscribeWiring({
-        unsubscribe: options.unsubscribe,
-        publicOrigin: undefined,
-        mailBaseUrl: effectiveAuth?.mail?.baseUrl,
-        envSource,
-        warn: (message) => createFallbackLogger("runDevApp").warn(message),
-    });
-    const extraRoutes = unsubscribeRoutes.length === 0 && wiring.extraRoutes.length === 0
-        ? options.extraRoutes
-        : [...(options.extraRoutes ?? []), ...unsubscribeRoutes, ...wiring.extraRoutes];
-    const features = composeFeatures([...options.features, ...wiring.features], {
-        includeBundled: !!effectiveAuth,
-        ...(composeAuthOptions && { authOptions: composeAuthOptions }),
-    });
-    // An explicitly wired file provider (options.files) satisfies the
-    // FILE_STORAGE_PROVIDER boot gate. Passed via the validateBoot env option
-    // instead of mutating process.env, so nothing leaks into later runDevApp
-    // calls in the same process.
-    const baseBootEnv = {
-        ...wiring.envDefaults,
-        ...(options.validateBootOptions?.env ?? process.env),
-    };
-    const hasBootEnvDefaults = Object.keys(wiring.envDefaults).length > 0;
-    const bootOptions = options.files !== undefined && baseBootEnv[FILE_STORAGE_PROVIDER_ENV] === undefined
-        ? {
-            ...options.validateBootOptions,
-            env: { ...baseBootEnv, [FILE_STORAGE_PROVIDER_ENV]: FILE_STORAGE_PROVIDER_BOOT_SENTINEL },
-        }
-        : hasBootEnvDefaults
-            ? { ...options.validateBootOptions, env: baseBootEnv }
-            : options.validateBootOptions;
-    // Run boot validation before creating the server. This catches the same
-    // errors runProdApp catches (unqualified navigation or handler QNs,
-    // screen-access violations), which would otherwise only show up as a prod pod
-    // in CrashLoopBackOff. It throws
-    // synchronously before a socket is opened.
-    // Resolve this before validateBoot: an app-supplied masterKey provider must
-    // satisfy the encrypted-field gate exactly as it does in runProdApp.
-    const bootCrypto = resolveBootCrypto(envSource, options.masterKey);
-    validateBoot(features, {
-        ...(bootCrypto.entityFieldCipher && { entityFieldCipher: bootCrypto.entityFieldCipher }),
-        ...bootOptions,
+    catch (error) {
+        // Anything that throws after the KMS wiring is open (boot gates, server creation) must close it.
+        await bootFailure.release?.().catch(() => { });
+        throw error;
+    }
+}
+async function bootDevApp(options, bootFailure) {
+    const config = await resolveDevBootConfig(options, bootFailure);
+    const bootCrypto = validateDevBoot(options, config);
+    const lateBindings = createDevLateBindings();
+    const tierResolverUsage = findTierResolverUsage(config.features);
+    const effectiveFeatures = createLateBoundEffectiveFeatures(lateBindings, Boolean(tierResolverUsage || config.wiring.featureToggles));
+    const { releasePiiKms } = configureDevBootCrypto(options, config, bootCrypto, lateBindings.resets, bootFailure);
+    const { registry, sessionStoreProviderMounted } = resolveDevAuthRegistry(config);
+    const extraContext = buildDevExtraContext(options, config, registry, bootCrypto);
+    const auth = wireDevAuth(config, registry, sessionStoreProviderMounted, lateBindings);
+    const trustedProxyHops = options.trustedProxyHops ??
+        config.effectiveAuth?.trustedProxyHops ??
+        parseTrustedProxyHopsEnv(config.envSource[TRUSTED_PROXY_HOPS_ENV], "runDevApp");
+    const handle = await createKumikoServer({
+        ...buildDevServerOptions({
+            options,
+            config,
+            auth,
+            extraContext,
+            trustedProxyHops,
+            effectiveFeatures,
+        }),
+        onAfterSetup: (stack) => runDevAfterSetup(stack, { config, bootCrypto, auth, lateBindings }),
     });
-    warnIfNonUtcServerTimeZone();
-    validateAppCustomScreenWriteQns(process.cwd(), collectWriteHandlerQns(features));
-    // Tier-Composition auto-wire: scan features for a
-    // tenantTierResolver-extension and wire a late-bound wrapper here; it is
-    // filled in onAfterSetup (where stack.db + stack.registry are available).
-    // The global operator toggles layer over the same wrapper.
-    // App-Author sees nothing — `createTierEngineFeature(opts)` mounts +
-    // framework auto-wires.
-    const tierResolverUsage = findTierResolverUsage(features);
-    const tierResolverHolder = {
-        resolver: undefined,
-    };
-    const finalEffectiveFeatures = tierResolverUsage || wiring.featureToggles
-        ? 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?");
+    bootFailure.release = undefined;
+    if (options.welcomeBanner) {
+        const banner = renderDevWelcomeBanner(options, config, handle);
+        // biome-ignore lint/suspicious/noConsole: boot-time UX print, opt-in via welcomeBanner.
+        console.log(`\n${banner}\n`);
+    }
+    return {
+        ...handle,
+        stop: async () => {
+            try {
+                await handle.stop();
             }
-            return tierResolverHolder.resolver(tenantId);
-        }, {
-            // The real trialGate lands on holder.resolver only after plugin.build(). Delegate rather than
-            // copy it because this wrapper closure is created before build().
-            // Return false when no trial gate is available.
-            trialGate: (tenantId, featureName) => tierResolverHolder.resolver?.trialGate?.(tenantId, featureName) ??
-                Promise.resolve(false),
-        })
-        : undefined;
-    // Provide the configResolver default for the config feature in auth mode;
-    // in no-auth mode, leave that choice to the caller. Wrap the factory so the
-    // spread applies to its result; spreading the function itself is a no-op. The
-    // ENV-to-config bridge supplies app-override defaults from `env:` keys.
-    // The temporary registry extracts only config keys because the resolver is
-    // built before server boot, and stack.registry only exists from onAfterSetup;
-    // createKumikoServer builds its own registry internally.
-    // The app-wide cipher for `encrypted: true` entity fields is resolved lazily
-    // by executors, symmetrically with runProdApp.
-    configureEntityFieldEncryption(bootCrypto.entityFieldCipher);
-    // Configure Subject-KMS and blind-index handling, symmetrically with
-    // runProdApp. Dev warns instead of failing for plaintext PII, but kms with
-    // lookupable fields still requires blindIndexKey because lookups would fail
-    // in every mode.
-    const piiKms = options.kmsMode !== undefined
-        ? {
-            kms: wiring.kms.kms,
-            blindIndexKey: wiring.kms.blindIndexKey,
-            generatedBlindIndexKey: false,
-            mode: wiring.kms.kms ? "app-kms" : "plaintext",
-        }
-        : resolveDevPiiKms(options);
-    configurePiiSubjectKms(piiKms.kms);
-    configureBlindIndexKey(piiKms.blindIndexKey);
-    const releaseEphemeralPiiKms = captureEphemeralDevPiiKms(piiKms);
-    // The auth features bind database-backed revokers onto their (possibly shared) instances;
-    // stop() swaps them for inert ones so a later stack in the same process never reaches this
-    // app's closed connection.
-    const resetLateBindings = [];
-    const releasePiiKms = async () => {
-        for (const reset of resetLateBindings)
-            reset();
-        releaseEphemeralPiiKms();
-        await wiring.kms.close();
+            finally {
+                await releasePiiKms();
+            }
+        },
     };
-    assertPiiBootInvariants(features, {
-        kms: piiKms.kms,
-        blindIndexKey: piiKms.blindIndexKey,
-        mode: "dev",
-    });
-    if (piiKms.mode === "ephemeral-default") {
-        logInfo("[runDevApp] PII encrypted with in-memory KMS (ephemeral DB); pass kms: false to opt out");
-    }
-    // Throwaway registry, built once and reused below — mirrors runProdApp's
-    // `createRegistry(features)` right after validateBoot. 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",
+}
+function renderDevWelcomeBanner(options, config, handle) {
+    const { effectiveAuth } = config;
+    const overrides = typeof options.welcomeBanner === "object" ? options.welcomeBanner : {};
+    const port = handle.server?.port ?? options.port ?? 3000;
+    return 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 }),
     });
+}
+// Provide the configResolver default for the config feature in auth mode;
+// in no-auth mode, leave that choice to the caller. Wrap the factory so the
+// spread applies to its result; spreading the function itself is a no-op. The
+// ENV-to-config bridge supplies app-override defaults from `env:` keys.
+// The temporary registry extracts only config keys because the resolver is
+// built before server boot, and stack.registry only exists from onAfterSetup;
+// createKumikoServer builds its own registry internally.
+// Automatically wire templateResolver and feature-gated secrets, symmetrically
+// with runProdApp. Unlike prod, the database is available here only in the
+// factory dependencies because createKumikoServer builds the stack. Therefore
+// use a factory: buildBootExtraContext runs with hasAuth:false because
+// configResolver already comes from cfgExtra, and cfgExtra values override
+// the boot defaults.
+function buildDevExtraContext(options, config, registry, bootCrypto) {
+    const { features, envSource, unsubscribeLinks } = config;
     const cfgExtra = registry
-        ? mergeConfigResolverDefault(options.extraContext, registry, envSource, bootCrypto.configCipher)
+        ? mergeConfigResolverDefault(options.extraContext, registry, envSource, bootCrypto.configCipher, options.appOverrides)
         : options.extraContext;
-    // Automatically wire templateResolver and feature-gated secrets, symmetrically
-    // with runProdApp. Unlike prod, the database is available here only in the
-    // factory dependencies because createKumikoServer builds the stack. Therefore
-    // use a factory: buildBootExtraContext runs with hasAuth:false because
-    // configResolver already comes from cfgExtra, and cfgExtra values override
-    // the boot defaults.
-    const extraContext = (deps) => {
+    return (deps) => {
         const base = typeof cfgExtra === "function" ? cfgExtra(deps) : (cfgExtra ?? {});
         const bootLogger = loggerFromExtraContext(base);
         const boot = buildBootExtraContext({
@@ -247,269 +128,15 @@ export async function runDevApp(options) {
             ...base,
         };
     };
-    // Sessions: late-bound holder — resolveSessionStore needs concrete db+
-    // registry (only after setupTestStack). Wired when sessions feature is
-    // mounted; 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);
-    // Same master secret as runProdApp. Without JWT_SECRET the feature keeps
-    // its explicit secrets, or its handlers report the missing binding.
-    const devMasterSecret = envSource["JWT_SECRET"];
-    if (mfaFeature && devMasterSecret) {
-        bindMfaTokenSecretsFromFeature(mfaFeature)?.(devMasterSecret, envSource);
-    }
-    if (effectiveAuth &&
-        mfaFeature &&
-        registry?.getWriteHandler(AuthHandlers.switchTenantMfaGate) === undefined) {
-        throw new Error(`[runDevApp] auth-mfa is mounted but ${AuthHandlers.switchTenantMfaGate} is not registered: ` +
-            "createAuthEmailPasswordFeature registers it only when mfaStatusChecker is set, and without it " +
-            "POST /auth/switch-tenant would mint sessions without the second factor");
-    }
-    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: 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) — 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.errorDocs && { errorDocs: options.errorDocs }),
-        ...(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 }),
-        ...(extraRoutes !== undefined && { extraRoutes }),
-        ...(options.wire !== undefined && { wire: options.wire }),
-        ...(trustedProxyHops !== undefined && { trustedProxyHops }),
-        ...(options.demoMode && { wrapFetch: wiring.wrapFetch }),
-        ...(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.retiredCookieDomains !== undefined && {
-                    retiredCookieDomains: effectiveAuth.retiredCookieDomains,
-                }),
-                ...(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,
-                    switchTenantMfaGateHandler: AuthHandlers.switchTenantMfaGate,
-                    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) => {
-            // 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) {
-                tierResolverHolder.resolver = await requireTierResolverPlugin(tierResolverUsage).build({
-                    db: stack.db,
-                    registry: stack.registry,
-                    cacheSync: stack.cacheSync,
-                });
-            }
-            if (wiring.featureToggles) {
-                const bound = await wiring.featureToggles.bind({
-                    db: stack.db,
-                    registry: stack.registry,
-                    cacheSync: stack.cacheSync,
-                    tierResolver: tierResolverHolder.resolver,
-                });
-                tierResolverHolder.resolver = bound.resolver;
-            }
-            if (effectiveAuth && stack.registry.getExtensionUsages(EXT_SESSION_STORE).length > 0) {
-                // Secure-by-default: 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) {
-                    bindReleasable(bindAutoRevokeFromFeature(sessionsFeature), store.massRevoker, INERT_REVOKER, resetLateBindings);
-                }
-                if (mfaFeature) {
-                    bindReleasable(bindMfaRevokeAllOtherSessionsFromFeature(mfaFeature), store.revokeAllOthers, INERT_REVOKER, resetLateBindings);
-                }
-                if (mfaFeature && patFeature) {
-                    bindReleasable(bindRevokeAllPatTokensFromFeature(mfaFeature), (userId) => revokeAllPatTokensForUser(stack.db, userId), INERT_REVOKER, resetLateBindings);
-                }
-                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.
-                bindReleasable(bindPatAutoRevokeOnPasswordChangeFromFeature(patFeature), (userId) => revokeAllPatTokensForUser(stack.db, userId), INERT_REVOKER, resetLateBindings);
-            }
-            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.
-            for (const seed of wiring.shortcutSeeds) {
-                await seed(stack.db);
-            }
-            await applyBootSeeds({
-                registry: stack.registry,
-                db: stack.db,
-                ...(bootCrypto.configCipher && { cipher: bootCrypto.configCipher }),
-            });
-            for (const seed of stackSeeds) {
-                await seed(stack);
-            }
-        },
-    }).catch(async (error) => {
-        await releasePiiKms().catch(() => { });
-        throw error;
-    });
-    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,
-        stop: async () => {
-            try {
-                await handle.stop();
-            }
-            finally {
-                await releasePiiKms();
-            }
-        },
-    };
-}
-const INERT_REVOKER = async () => 0;
-// Binds a late-bound revoker and records how to swap it for an inert one when the app stops.
-function bindReleasable(bind, revoker, inert, resets) {
-    if (bind) {
-        bind(revoker);
-        resets.push(() => bind(inert));
-    }
 }
 // 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) {
+export function mergeConfigResolverDefault(ctx, registry, envSource, cipher, appOverrides) {
     const defaults = {
         configResolver: createConfigResolver({
-            appOverrides: buildEnvConfigOverrides(registry, envSource),
+            appOverrides: buildConfigOverrides(registry, envSource, appOverrides),
             ...(cipher && { cipher }),
         }),
     };

package/dist/scaffold-app.d.ts

@@ -27,7 +27,8 @@ export type ScaffoldAppOptions = {
      *  (the CLI's ctx.cwd) MUST pass it so the scaffold lands where the
      *  command's output claims it does. */
     readonly cwd?: string;
-    /** npm-version-pin for @cosmicdrift/* deps. Default "*" for latest. */
+    /** Exact version pin for @cosmicdrift/* deps. Default: the running framework version
+     *  (resolveFrameworkVersion); scaffoldApp throws when that cannot be resolved. */
     readonly frameworkVersion?: string;
     /** Bundled-features to mount in run-config.ts. Default: secrets + auth-foundation + sessions
      *  (the historical foundation). create-kumiko-app passes the picker output