@cosmicdrift/kumiko-server-runtime 0.387.0 → 0.389.0

package/dist/boot/boot-crypto.js

@@ -15,6 +15,9 @@ export function envHasMasterKek(env) {
 }
 export function resolveBootCrypto(envSource, masterKeyOverride) {
     const masterKeyProvider = masterKeyOverride ?? envMasterKeyProviderIfConfigured(envSource);
+    // Providers defer their keyring check under KUMIKO_DRY_RUN_ENV; an app-supplied
+    // provider must still be rejected at boot, not at the first key access.
+    masterKeyProvider?.currentVersion();
     const dekCache = createDekCache();
     const configCipher = masterKeyProvider
         ? createEnvelopeCipher(masterKeyProvider, { dekCache })
@@ -37,8 +40,5 @@ function envMasterKeyProviderIfConfigured(envSource) {
             KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: envSource["KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION"] ?? "1",
         },
     });
-    // The provider defers its keyring check under KUMIKO_DRY_RUN_ENV; the boot
-    // must still reject a malformed keyring there.
-    provider.currentVersion();
     return provider;
 }

package/dist/boot/shared-boot-steps.d.ts

@@ -0,0 +1,46 @@
+import { type SeedAdminOptions } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
+import type { AuthRoutesConfig } from "@cosmicdrift/kumiko-framework/api";
+import type { KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import { type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { type BundledListsOptions, type EffectiveFeaturesResolver, type FeatureDefinition, type Registry, type ValidateBootOptions } from "@cosmicdrift/kumiko-framework/engine";
+import type { CacheSyncBus } from "@cosmicdrift/kumiko-framework/redis";
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
+import type { FeatureTogglesWiring } from "../boot-options/feature-toggles-option.ts";
+import type { DbSeedFn } from "../boot-options/seed-shortcuts.ts";
+import { type AuthOptionsCarrier } from "../compose-features.ts";
+import type { RunProdAppAuthOptions } from "../run-prod-app.ts";
+import { type DatabaseWaitClock } from "./wait-for-database.ts";
+/** Returns `envSource` itself (it may be `process.env`) when there is nothing to layer under it. */
+export declare function withEnvDefaults(envDefaults: Readonly<Record<string, string | undefined>>, envSource: Record<string, string | undefined>): Record<string, string | undefined>;
+export declare function composeAppFeatures(appFeatures: readonly FeatureDefinition[], bootFeatures: readonly FeatureDefinition[], effectiveAuth: AuthOptionsCarrier | undefined, bundledLists?: BundledListsOptions): readonly FeatureDefinition[];
+export declare function validateComposedFeatures(features: readonly FeatureDefinition[], bootOptions: ValidateBootOptions): void;
+export declare function assertMfaSwitchTenantGate(registry: Registry, processName: string): void;
+export declare function buildEffectiveFeaturesResolver(deps: {
+    readonly features: readonly FeatureDefinition[];
+    readonly featureToggles: FeatureTogglesWiring | undefined;
+    readonly db: DbConnection;
+    readonly registry: Registry;
+    readonly cacheSync: CacheSyncBus;
+}): Promise<EffectiveFeaturesResolver | undefined>;
+export declare function applyStandardBootSeeds(deps: {
+    readonly db: DbConnection;
+    readonly registry: Registry;
+    readonly admin: SeedAdminOptions | undefined;
+    readonly shortcutSeeds: readonly DbSeedFn[];
+    readonly cipher: EnvelopeCipher | undefined;
+    readonly processName: string;
+    readonly databaseWait?: DatabaseWaitClock;
+}): Promise<void>;
+type SharedAuthFlowFields = Pick<RunProdAppAuthOptions, "passwordReset" | "emailVerification" | "accountUnlock" | "signup" | "invite">;
+type AuthFlowRoutes = Pick<AuthRoutesConfig, "passwordReset" | "emailVerification" | "accountUnlock" | "signup" | "invite">;
+export type SharedAuthRouteSource = SharedAuthFlowFields & Pick<RunProdAppAuthOptions, "loginErrorStatusMap" | "cookieDomain" | "retiredCookieDomains" | "allowedOrigins" | "unsafeSkipOriginCheck" | "postAuthLanding">;
+export type SharedAuthRoutes = AuthFlowRoutes & Pick<AuthRoutesConfig, "membershipQuery" | "loginHandler" | "loginErrorStatusMap" | "cookieDomain" | "retiredCookieDomains" | "allowedOrigins" | "unsafeSkipOriginCheck" | "postAuthLanding" | "mfaVerifyHandler" | "switchTenantMfaGateHandler" | "mfaPreauthEnableStartHandler" | "mfaPreauthConfirmHandler">;
+export declare function buildSharedAuthRoutes(effectiveAuth: SharedAuthRouteSource, hasMfa: boolean): SharedAuthRoutes;
+export declare function waitForKmsHealthy(kms: KmsAdapter, processName: string, deadline: number, clock?: DatabaseWaitClock): Promise<void>;
+export declare function openDatabasePools(databaseUrl: string, envSource: Record<string, string | undefined>): {
+    readonly db: DbConnection;
+    readonly closeDb: () => Promise<void>;
+    readonly outsideTransactionDb: DbConnection;
+    readonly closeOutsideTransactionDb: () => Promise<void>;
+};
+export {};

package/dist/boot/shared-boot-steps.js

@@ -0,0 +1,160 @@
+// Boot steps that runProdApp, the dev server and the worker processes run
+// identically. Each step keeps the caller in charge of ordering, logging sinks
+// and cleanup policy: those differ between the processes.
+import { AuthErrors, AuthHandlers, AuthQueries, } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import { seedAdminGuarded, } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
+import { AuthMfaHandlers } from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
+import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import { createDbConnection, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, serverTimeoutOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/db";
+import { collectWriteHandlerQns, findTierResolverUsage, requireTierResolverPlugin, validateAppCustomScreenWriteQns, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
+import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
+import { buildComposeAuthOptions, composeFeatures, } from "../compose-features.js";
+import { applyBootSeeds } from "./apply-boot-seeds.js";
+import { waitUntilDatabaseReachable } from "./wait-for-database.js";
+/** Returns `envSource` itself (it may be `process.env`) when there is nothing to layer under it. */
+export function withEnvDefaults(envDefaults, envSource) {
+    return Object.keys(envDefaults).length > 0 ? { ...envDefaults, ...envSource } : envSource;
+}
+export function composeAppFeatures(appFeatures, bootFeatures, effectiveAuth, bundledLists) {
+    const composeAuthOptions = buildComposeAuthOptions(effectiveAuth);
+    return composeFeatures([...appFeatures, ...bootFeatures], {
+        includeBundled: !!effectiveAuth,
+        ...(composeAuthOptions && { authOptions: composeAuthOptions }),
+        ...(bundledLists && { bundledLists }),
+    });
+}
+export function validateComposedFeatures(features, bootOptions) {
+    validateBoot(features, bootOptions);
+    warnIfNonUtcServerTimeZone();
+    validateAppCustomScreenWriteQns(process.cwd(), collectWriteHandlerQns(features));
+}
+export function assertMfaSwitchTenantGate(registry, processName) {
+    if (registry.getWriteHandler(AuthHandlers.switchTenantMfaGate) === undefined) {
+        throw new Error(`[${processName}] 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");
+    }
+}
+export async function buildEffectiveFeaturesResolver(deps) {
+    const { features, featureToggles, db, registry, cacheSync } = deps;
+    const tierResolverUsage = findTierResolverUsage(features);
+    const tierResolver = tierResolverUsage
+        ? await requireTierResolverPlugin(tierResolverUsage).build({ db, registry, cacheSync })
+        : undefined;
+    if (!featureToggles)
+        return tierResolver;
+    const bound = await featureToggles.bind({ db, registry, cacheSync, tierResolver });
+    return bound.resolver;
+}
+export async function applyStandardBootSeeds(deps) {
+    const { db, registry, admin, shortcutSeeds, cipher, processName, databaseWait } = deps;
+    // Seeds are idempotent, so a transient connection error re-runs the whole sequence; any other
+    // error stays fatal. Later boot steps build on the seeds, so this cannot continue in the background.
+    await waitUntilDatabaseReachable(async () => {
+        if (admin) {
+            await seedAdminGuarded(db, admin);
+        }
+        for (const seed of shortcutSeeds) {
+            await seed(db);
+        }
+        // The helper indirection is what config-seed-boot.integration.ts pins — keep it as a single call.
+        await applyBootSeeds({
+            registry,
+            db,
+            ...(cipher && { cipher }),
+        });
+    }, { ...databaseWait, processName, target: "database (boot seeds)" });
+}
+const MFA_ROUTE_HANDLERS = {
+    mfaVerifyHandler: AuthMfaHandlers.verify,
+    switchTenantMfaGateHandler: AuthHandlers.switchTenantMfaGate,
+    mfaPreauthEnableStartHandler: AuthMfaHandlers.enableStartPreauth,
+    mfaPreauthConfirmHandler: AuthMfaHandlers.enableConfirmPreauth,
+};
+function buildAuthFlowRoutes(effectiveAuth) {
+    return {
+        ...(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,
+            },
+        }),
+    };
+}
+export function buildSharedAuthRoutes(effectiveAuth, hasMfa) {
+    return {
+        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.postAuthLanding !== undefined && {
+            postAuthLanding: effectiveAuth.postAuthLanding,
+        }),
+        ...(hasMfa && MFA_ROUTE_HANDLERS),
+        ...buildAuthFlowRoutes(effectiveAuth),
+    };
+}
+export async function waitForKmsHealthy(kms, processName, deadline, clock) {
+    const kmsHealth = await waitUntilDatabaseReachable(() => kms.health(), {
+        ...clock,
+        processName,
+        target: "KMS",
+        deadline,
+    });
+    if (!kmsHealth.ok) {
+        throw new Error(`[${processName}] BOOT ABORTED — KMS health check failed (latency ${kmsHealth.latencyMs}ms)`);
+    }
+}
+export function openDatabasePools(databaseUrl, envSource) {
+    const { db, close: closeDb } = createDbConnection({
+        url: databaseUrl,
+        ...dbConnectionOptionsFromEnv(envSource),
+        ...serverTimeoutOptionsFromEnv(envSource),
+    });
+    const { db: outsideTransactionDb, close: closeOutsideTransactionDb } = createDbConnection({
+        url: databaseUrl,
+        ...outsideTransactionPoolOptionsFromEnv(envSource),
+        ...serverTimeoutOptionsFromEnv(envSource),
+    });
+    return { db, closeDb, outsideTransactionDb, closeOutsideTransactionDb };
+}

package/dist/boot/wait-for-database.d.ts

@@ -5,9 +5,14 @@ export declare const WAIT_FOR_DATABASE_MAX_BACKOFF_MS = 15000;
 export declare const WAIT_FOR_DATABASE_DEADLINE_MS = 90000;
 export type WaitForDatabaseOptions = {
     readonly processName: string;
+    /** Names the dependency in the retry log line; default "database". */
+    readonly target?: string;
     readonly log?: (line: string) => void;
     readonly sleep?: (ms: number) => Promise<void>;
     readonly now?: () => number;
+    readonly deadline?: number;
 };
+/** Injectable clock and sink; tests drive the backoff without real waiting. */
+export type DatabaseWaitClock = Pick<WaitForDatabaseOptions, "log" | "sleep" | "now">;
 export declare function waitForDatabase(db: DbConnection, options: WaitForDatabaseOptions): Promise<void>;
 export declare function waitUntilDatabaseReachable<T>(ping: () => Promise<T>, options: WaitForDatabaseOptions): Promise<T>;

package/dist/boot/wait-for-database.js

@@ -7,9 +7,10 @@ const TRANSIENT_CODES = new Set([
     "ETIMEDOUT",
     "ENOTFOUND",
     "EAI_AGAIN",
-    "CONNECTION_CLOSED",
-    "CONNECT_TIMEOUT",
-    "CONNECTION_DESTROYED",
+    "ERR_POSTGRES_CONNECTION_CLOSED",
+    "ERR_POSTGRES_CONNECTION_REFUSED",
+    "ERR_POSTGRES_CONNECTION_TIMEOUT",
+    "ERR_POSTGRES_CONNECTION_FAILED",
 ]);
 const CONNECTION_EXCEPTION_CLASS = "08";
 export function isTransientConnectionError(error) {
@@ -37,8 +38,8 @@ export async function waitForDatabase(db, options) {
     await waitUntilDatabaseReachable(() => tableExists(db, "pg_catalog.pg_class"), options);
 }
 export async function waitUntilDatabaseReachable(ping, options) {
-    const { processName, log = logToConsole, sleep = sleepReal, now = Date.now } = options;
-    const deadline = now() + WAIT_FOR_DATABASE_DEADLINE_MS;
+    const { processName, target = "database", log = logToConsole, sleep = sleepReal, now = Date.now, } = options;
+    const deadline = options.deadline ?? now() + WAIT_FOR_DATABASE_DEADLINE_MS;
     let backoffMs = WAIT_FOR_DATABASE_INITIAL_BACKOFF_MS;
     for (let attempt = 1;; attempt++) {
         try {
@@ -52,7 +53,7 @@ export async function waitUntilDatabaseReachable(ping, options) {
                 throw error;
             const waitMs = Math.min(backoffMs, remainingMs);
             const code = extractPgError(error)?.code ?? "unknown";
-            log(`[${processName}] database not reachable (code ${code}, attempt ${attempt}), retrying in ${waitMs}ms…`);
+            log(`[${processName}] ${target} not reachable (code ${code}, attempt ${attempt}), retrying in ${waitMs}ms…`);
             await sleep(waitMs);
             backoffMs = Math.min(backoffMs * 2, WAIT_FOR_DATABASE_MAX_BACKOFF_MS);
         }

package/dist/boot/worker-boot-core.js

@@ -5,8 +5,8 @@
 // share every step that decides ciphers, blind indexes and config encryption.
 import { loadJwtSecretOrKeyring } from "@cosmicdrift/kumiko-framework/api";
 import { configureBlindIndexKey, configurePiiSubjectKms, resolvePlatformKeks, } from "@cosmicdrift/kumiko-framework/crypto";
-import { configureEntityFieldEncryption, createDbConnection, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, serverTimeoutOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/db";
-import { createRegistry, findTierResolverUsage, requireTierResolverPlugin, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
+import { configureEntityFieldEncryption, } from "@cosmicdrift/kumiko-framework/db";
+import { createRegistry, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
 import { createWorkerEntrypoint, } from "@cosmicdrift/kumiko-framework/entrypoint";
 import { assertKumikoSchemaCurrent, SchemaDriftError, } from "@cosmicdrift/kumiko-framework/migrations";
 import { createEntityCache, createEventDedup, createIdempotencyGuard, } from "@cosmicdrift/kumiko-framework/pipeline";
@@ -16,11 +16,13 @@ import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { Redis } from "ioredis";
 import { composeFeatures } from "../compose-features.js";
 import { assertPiiBootInvariants } from "../pii-boot-gate.js";
-import { requireEnv } from "../run-prod-app.js";
+import { readEnv, requireEnv } from "../require-env.js";
 import { addConfigAccessorFactory, buildBootExtraContext, loggerFromExtraContext, } from "../run-prod-app-boot-context.js";
 import { resolveBootCrypto } from "./boot-crypto.js";
 import { jobRunLoggerCallbacks } from "./job-run-logger.js";
-import { waitForDatabase, waitUntilDatabaseReachable } from "./wait-for-database.js";
+import { INSTANCE_ID_ENV } from "./record-app-started-on-boot.js";
+import { buildEffectiveFeaturesResolver, openDatabasePools, waitForKmsHealthy, } from "./shared-boot-steps.js";
+import { WAIT_FOR_DATABASE_DEADLINE_MS, waitForDatabase } from "./wait-for-database.js";
 import { assertWorkerMetricsOptions } from "./worker-metrics-server.js";
 function isSecretsContext(value) {
     if (typeof value !== "object" || value === null)
@@ -36,12 +38,6 @@ export async function resolveWorkerEnvSource(options, processName) {
         })
         : rawEnvSource;
 }
-async function buildTierEffectiveFeatures(features, db, registry, cacheSync) {
-    const tierResolverUsage = findTierResolverUsage(features);
-    if (!tierResolverUsage)
-        return undefined;
-    return requireTierResolverPlugin(tierResolverUsage).build({ db, registry, cacheSync });
-}
 async function assertWorkerSchemaCurrent(db, migrationsDir, processName) {
     const dir = migrationsDir ?? "./kumiko/migrations";
     // biome-ignore lint/suspicious/noConsole: boot-time progress hint
@@ -71,6 +67,7 @@ export async function bootWorkerProcess(options, envSource, profile) {
     const features = composeFeatures(options.features, {
         includeBundled,
         ...(profile.authOptions && { authOptions: profile.authOptions }),
+        ...(options.bundledLists && { bundledLists: options.bundledLists }),
     });
     const bootCrypto = resolveBootCrypto(envSource, options.masterKey);
     validateBoot(features, {
@@ -96,32 +93,22 @@ export async function bootWorkerProcess(options, envSource, profile) {
         return { kind: "dry-run", envSource };
     }
     // Before the connections, so an abort leaks nothing.
+    const databaseWaitDeadline = (options.databaseWait?.now ?? Date.now)() + WAIT_FOR_DATABASE_DEADLINE_MS;
     if (options.kms) {
-        const kms = options.kms;
-        const kmsHealth = await waitUntilDatabaseReachable(() => kms.health(), {
-            processName: processName,
-        });
-        if (!kmsHealth.ok) {
-            throw new Error(`[${processName}] BOOT ABORTED — KMS health check failed (latency ${kmsHealth.latencyMs}ms)`);
-        }
+        await waitForKmsHealthy(options.kms, processName, databaseWaitDeadline, options.databaseWait);
     }
-    const { db, close: closeDb } = createDbConnection({
-        url: databaseUrl,
-        ...dbConnectionOptionsFromEnv(envSource),
-        ...serverTimeoutOptionsFromEnv(envSource),
-    });
-    const { db: outsideTransactionDb, close: closeOutsideTransactionDb } = createDbConnection({
-        url: databaseUrl,
-        ...outsideTransactionPoolOptionsFromEnv(envSource),
-        ...serverTimeoutOptionsFromEnv(envSource),
-    });
+    const { db, closeDb, outsideTransactionDb, closeOutsideTransactionDb } = openDatabasePools(databaseUrl, envSource);
     const redis = new Redis(redisUrl, { maxRetriesPerRequest: null });
     const cacheSync = createRedisCacheSyncBus({
         redisUrl,
         clientOptions: redisClientOptionsFromEnv(envSource),
     });
     try {
-        await waitForDatabase(db, { processName });
+        await waitForDatabase(db, {
+            ...options.databaseWait,
+            processName,
+            deadline: databaseWaitDeadline,
+        });
     }
     catch (err) {
         await closeDb();
@@ -130,16 +117,13 @@ export async function bootWorkerProcess(options, envSource, profile) {
         await cacheSync.close();
         throw err;
     }
-    let resolvedEffectiveFeatures = await buildTierEffectiveFeatures(features, db, registry, cacheSync);
-    if (profile.featureToggles) {
-        const bound = await profile.featureToggles.bind({
-            db,
-            registry,
-            cacheSync,
-            tierResolver: resolvedEffectiveFeatures,
-        });
-        resolvedEffectiveFeatures = bound.resolver;
-    }
+    const resolvedEffectiveFeatures = await buildEffectiveFeaturesResolver({
+        features,
+        featureToggles: profile.featureToggles,
+        db,
+        registry,
+        cacheSync,
+    });
     if (options.migrations !== false) {
         try {
             await assertWorkerSchemaCurrent(db, options.migrations?.dir, processName);
@@ -172,6 +156,7 @@ export async function bootWorkerProcess(options, envSource, profile) {
         registry,
         hasAuth: includeBundled,
         redis,
+        ...(options.appOverrides && { appOverrides: options.appOverrides }),
         crypto: bootCrypto,
         ...(options.kms && { kms: options.kms }),
         ...(profile.deliverQueuedInline === true && { deliverQueuedInline: true }),
@@ -200,6 +185,7 @@ export async function bootWorkerProcess(options, envSource, profile) {
             getActiveTenantIds: options.jobs.getActiveTenantIds,
         }),
         ...(options.eventDispatcher && { eventDispatcher: options.eventDispatcher }),
+        instanceId: readEnv(INSTANCE_ID_ENV, envSource),
     });
     entrypoint.lifecycle.registerShutdownHook("workerCacheSync", async () => {
         await cacheSync.close();

package/dist/boot-options/billing-option.d.ts

@@ -1,37 +1,46 @@
 import { type TierSyncResult } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { type SubscriptionDodoOptions } from "@cosmicdrift/kumiko-bundled-features/subscription-dodo";
 import { type SubscriptionStripeOptions } from "@cosmicdrift/kumiko-bundled-features/subscription-stripe";
 import type { ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-/** Mounts `subscription-stripe` plus the webhook route that writes the
- *  subscription and syncs the tenant's tier (`tier-engine`). Needs
- *  `billing-foundation`, `tier-engine`, `config` and `secrets` in `features`.
- *  `STRIPE_API_KEY` / `STRIPE_WEBHOOK_SECRET` from the env are only the
- *  bridge fallback; the keys normally live in the secrets store.
+/** Mounts `subscription-stripe` and/or `subscription-dodo` plus one webhook
+ *  route that writes the subscription and syncs the tenant's tier
+ *  (`tier-engine`). Needs `billing-foundation`, `tier-engine`, `config` and
+ *  `secrets` in `features`. The env keys (`STRIPE_API_KEY` /
+ *  `STRIPE_WEBHOOK_SECRET`, `DODO_PAYMENTS_API_KEY` /
+ *  `DODO_PAYMENTS_WEBHOOK_KEY`) are only the bridge fallback; the keys
+ *  normally live in the secrets store.
  *
  *  @example
  *  runProdApp({ ..., billing: {
  *    stripe: { priceToTier: { [env.STRIPE_PRICE_PRO]: "pro" } },
+ *    dodo: { priceToTier: { [env.DODO_PRODUCT_PRO]: "pro" } },
  *    defaultTier: "free",
  *  } })
  */
 export type BillingBootOption = {
-    readonly stripe: {
+    /** At least one of `stripe` and `dodo` is required. */
+    readonly stripe?: {
         readonly priceToTier: Readonly<Record<string, string>>;
-        /** Default `SUBSCRIPTION_WEBHOOK_PATH`; must contain `:providerName`. */
+        /** Default `SUBSCRIPTION_WEBHOOK_PATH`; must contain `:providerName`. Applies to every provider. */
         readonly webhookPath?: string;
         readonly oneOffPriceIds?: SubscriptionStripeOptions["oneOffPriceIds"];
         readonly paymentInvoiceCreation?: boolean;
     };
+    readonly dodo?: {
+        readonly priceToTier: Readonly<Record<string, string>>;
+        readonly oneOffPriceIds?: SubscriptionDodoOptions["oneOffPriceIds"];
+    };
     /** Tier a tenant falls back to without an active subscription. */
     readonly defaultTier: string;
     /** Valid tier names beyond `defaultTier` and the `priceToTier` targets. */
     readonly tierNames?: readonly string[];
-    /** Default `"fail-webhook"`: Stripe retries, so a failed tier sync gets another attempt. */
+    /** Default `"fail-webhook"`: the provider retries, so a failed tier sync gets another attempt. */
     readonly onTierSyncError?: "log" | "fail-webhook";
     /** Runs after every webhook whose tier sync succeeded, also when the tier stayed the same (`changed: false`). */
     readonly afterSync?: (result: TierSyncResult<string>) => Promise<void>;
 };
 export declare function resolveBillingOption(billing: BillingBootOption, envSource: Record<string, string | undefined>): {
-    readonly feature: FeatureDefinition;
+    readonly features: readonly FeatureDefinition[];
     readonly route: ExtraRouteDefinition;
 };

package/dist/boot-options/billing-option.js

@@ -1,29 +1,55 @@
 import { createSubscriptionTierSync, SUBSCRIPTION_WEBHOOK_PATH, } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { createSubscriptionDodoFeature, } from "@cosmicdrift/kumiko-bundled-features/subscription-dodo";
 import { createSubscriptionStripeFeature, } from "@cosmicdrift/kumiko-bundled-features/subscription-stripe";
 const PROVIDER_NAME_PARAM = ":providerName";
+function warnOnEmptyPriceMap(provider, priceToTier) {
+    if (Object.keys(priceToTier).length === 0) {
+        // biome-ignore lint/suspicious/noConsole: boot-time warn, no logger configured this early
+        console.warn(`[runProdApp] billing.${provider}.priceToTier is empty: every subscription webhook is ignored until a price maps to a tier.`);
+    }
+}
+function bridgeCredentials(envSource, apiKeyName, webhookSecretName) {
+    const apiKey = envSource[apiKeyName];
+    const webhookSecret = envSource[webhookSecretName];
+    return { ...(apiKey && { apiKey }), ...(webhookSecret && { webhookSecret }) };
+}
+function providerFeatures({ stripe, dodo }, envSource) {
+    const features = [];
+    if (stripe) {
+        warnOnEmptyPriceMap("stripe", stripe.priceToTier);
+        features.push(createSubscriptionStripeFeature({
+            priceToTier: stripe.priceToTier,
+            ...(stripe.oneOffPriceIds && { oneOffPriceIds: stripe.oneOffPriceIds }),
+            ...(stripe.paymentInvoiceCreation !== undefined && {
+                paymentInvoiceCreation: stripe.paymentInvoiceCreation,
+            }),
+            ...bridgeCredentials(envSource, "STRIPE_API_KEY", "STRIPE_WEBHOOK_SECRET"),
+        }));
+    }
+    if (dodo) {
+        warnOnEmptyPriceMap("dodo", dodo.priceToTier);
+        features.push(createSubscriptionDodoFeature({
+            priceToTier: dodo.priceToTier,
+            ...(dodo.oneOffPriceIds && { oneOffPriceIds: dodo.oneOffPriceIds }),
+            ...bridgeCredentials(envSource, "DODO_PAYMENTS_API_KEY", "DODO_PAYMENTS_WEBHOOK_KEY"),
+        }));
+    }
+    return features;
+}
 export function resolveBillingOption(billing, envSource) {
-    const webhookPath = billing.stripe.webhookPath ?? SUBSCRIPTION_WEBHOOK_PATH;
+    const { stripe, dodo } = billing;
+    if (!stripe && !dodo) {
+        throw new Error("[runProdApp] billing needs at least one provider: set billing.stripe or billing.dodo.");
+    }
+    const webhookPath = stripe?.webhookPath ?? SUBSCRIPTION_WEBHOOK_PATH;
     if (!webhookPath.includes(PROVIDER_NAME_PARAM)) {
         throw new Error(`[runProdApp] billing.stripe.webhookPath "${webhookPath}" must contain ${PROVIDER_NAME_PARAM}.`);
     }
-    if (Object.keys(billing.stripe.priceToTier).length === 0) {
-        // biome-ignore lint/suspicious/noConsole: boot-time warn, no logger configured this early
-        console.warn("[runProdApp] billing.stripe.priceToTier is empty: every subscription webhook is ignored until a price maps to a tier.");
-    }
-    const apiKey = envSource["STRIPE_API_KEY"];
-    const webhookSecret = envSource["STRIPE_WEBHOOK_SECRET"];
-    const feature = createSubscriptionStripeFeature({
-        priceToTier: billing.stripe.priceToTier,
-        ...(billing.stripe.oneOffPriceIds && { oneOffPriceIds: billing.stripe.oneOffPriceIds }),
-        ...(billing.stripe.paymentInvoiceCreation !== undefined && {
-            paymentInvoiceCreation: billing.stripe.paymentInvoiceCreation,
-        }),
-        ...(apiKey && { apiKey }),
-        ...(webhookSecret && { webhookSecret }),
-    });
+    const features = providerFeatures(billing, envSource);
     const tierNames = new Set([
         billing.defaultTier,
-        ...Object.values(billing.stripe.priceToTier),
+        ...Object.values(stripe?.priceToTier ?? {}),
+        ...Object.values(dodo?.priceToTier ?? {}),
         ...(billing.tierNames ?? []),
     ]);
     const tierSync = createSubscriptionTierSync({
@@ -32,5 +58,5 @@ export function resolveBillingOption(billing, envSource) {
         onSyncError: billing.onTierSyncError ?? "fail-webhook",
         ...(billing.afterSync && { afterSync: billing.afterSync }),
     });
-    return { feature, route: tierSync.createWebhookRoute({ path: webhookPath }) };
+    return { features, route: tierSync.createWebhookRoute({ path: webhookPath }) };
 }

package/dist/boot-options/demo-mode.d.ts

@@ -1,4 +1,4 @@
-import type { ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
+import { type ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
 export type DemoAccountRole = "admin" | "sysadmin";
 /** A role alone, or a role with the label the banner shows next to the login. */
 export type DemoAccountEntry = DemoAccountRole | {
@@ -19,7 +19,7 @@ export type DemoModeNotice = {
     readonly accounts?: readonly DemoAccountEntry[];
 };
 /** Live-demo switch. `readOnly: true` answers every mutating request
- *  (POST/PUT/PATCH/DELETE) outside `/api/query` and the login/logout/MFA
+ *  (POST/PUT/PATCH/DELETE) and every WebSocket upgrade outside `/api/query` and the login/logout/MFA
  *  routes with 403 `demo_read_only`. `GET /demo-mode` (anonymous) returns
  *  `{ readOnly, notice }` for the client banner.
  *
@@ -32,7 +32,7 @@ export type DemoModeNotice = {
 export type DemoModeOption = {
     readonly readOnly: boolean;
     readonly notice?: DemoModeNotice;
-    /** Mutating paths that stay open besides the default allowlist. */
+    /** Mutating paths (and WebSocket route paths) that stay open besides the default allowlist. */
     readonly allowedWritePaths?: readonly string[];
 };
 export declare const DEMO_MODE_PATH = "/demo-mode";

package/dist/boot-options/demo-mode.js

@@ -1,3 +1,4 @@
+import { isWebSocketUpgradeRequest, } from "@cosmicdrift/kumiko-framework/api";
 export const DEMO_MODE_PATH = "/demo-mode";
 export const DEMO_READ_ONLY_ERROR_CODE = "demo_read_only";
 const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
@@ -52,7 +53,9 @@ export function withDemoReadOnlyFetch(fetchHandler, demoMode) {
         ...(demoMode.allowedWritePaths ?? []),
     ]);
     return async (req, arg) => {
-        if (MUTATING_METHODS.has(req.method) && !allowed.has(new URL(req.url).pathname)) {
+        // A socket carries writes after the upgrade (route `write` dep), outside this method gate.
+        const mutates = MUTATING_METHODS.has(req.method) || isWebSocketUpgradeRequest(req);
+        if (mutates && !allowed.has(new URL(req.url).pathname)) {
             return Response.json({
                 isSuccess: false,
                 error: {

package/dist/boot-options/file-storage-option.js

@@ -54,17 +54,17 @@ export function resolveFileStorageOption(fileStorage, deps) {
     else {
         provider = fileStorage.provider;
     }
-    if (provider === "s3-env" && missingS3.length > 0) {
-        throw new Error(`[runProdApp] fileStorage "s3-env" is missing: ${missingS3.join(", ")}.`);
-    }
-    if (provider === "inmemory" && deps.isProduction) {
-        throw new Error('[runProdApp] fileStorage "inmemory" loses every file on restart — not allowed with NODE_ENV=production.');
-    }
     const additional = fileStorage.providers ?? [];
     const wanted = new Set([
         provider,
         ...additional.filter((entry) => !isNamedS3FileProvider(entry)),
     ]);
+    if (wanted.has("s3-env") && missingS3.length > 0) {
+        throw new Error(`[runProdApp] fileStorage "s3-env" is missing: ${missingS3.join(", ")}.`);
+    }
+    if (wanted.has("inmemory") && deps.isProduction) {
+        throw new Error('[runProdApp] fileStorage "inmemory" loses every file on restart — not allowed with NODE_ENV=production.');
+    }
     const named = additional.filter(isNamedS3FileProvider);
     assertNamedProviderNames(named);
     for (const entry of named) {

package/dist/boot-options/option-env-schema.js

@@ -31,10 +31,17 @@ function pickShape(shape, keys) {
     }
     return picked;
 }
+function sysadminTenantNeedsEnvId(seeds) {
+    const { sysadminFromEnv } = seeds;
+    return (typeof sysadminFromEnv === "object" &&
+        sysadminFromEnv.tenant !== undefined &&
+        sysadminFromEnv.tenant.id === undefined);
+}
 function seedEnvBlock(seeds) {
     const keys = [];
     const required = [];
-    if (seeds.demoTenant && seeds.demoTenant.id === undefined) {
+    const demoTenantNeedsEnvId = seeds.demoTenant !== undefined && seeds.demoTenant.id === undefined;
+    if (demoTenantNeedsEnvId || sysadminTenantNeedsEnvId(seeds)) {
         keys.push("DEMO_TENANT_ID");
         required.push("DEMO_TENANT_ID");
     }
@@ -61,7 +68,9 @@ function fileStorageEnvBlocks(fileStorage) {
         blocks.push({
             source: "runProdApp.fileStorage",
             shape: s3EnvSchema.shape,
-            required: fileStorage.provider === "s3-env" ? S3_REQUIRED_KEYS : [],
+            required: fileStorage.provider === "s3-env" || fileStorage.providers?.includes("s3-env")
+                ? S3_REQUIRED_KEYS
+                : [],
         });
     }
     for (const provider of fileStorage?.providers ?? []) {

package/dist/boot-options/resolve-boot-options.d.ts

@@ -24,6 +24,7 @@ export type BootOptionFields = {
     /** With `runSingleInstance: false`: the worker process mounts the same mail / fileStorage
      *  features (its own boot options or by hand), which silences the boot warning. */
     readonly workerMountsFeatures?: boolean;
+    readonly appOverrides?: object;
     readonly auth?: {
         readonly admin?: unknown;
         readonly mail?: {