@cosmicdrift/kumiko-server-runtime 0.368.0 → 0.370.0

package/dist/boot/boot-crypto.js

@@ -14,17 +14,7 @@ export function envHasMasterKek(env) {
     return Object.entries(env).some(([k, v]) => MASTER_KEK_VAR.test(k) && !!v);
 }
 export function resolveBootCrypto(envSource, masterKeyOverride) {
-    const masterKeyProvider = masterKeyOverride ??
-        (envHasMasterKek(envSource)
-            ? createEnvMasterKeyProvider({
-                // CURRENT_VERSION default "1" spiegelt secretsEnvSchema — ohne
-                // ihn wirft der raw-env-Provider, obwohl V1 gesetzt ist.
-                env: {
-                    ...envSource,
-                    KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: envSource["KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION"] ?? "1",
-                },
-            })
-            : undefined);
+    const masterKeyProvider = masterKeyOverride ?? envMasterKeyProviderIfConfigured(envSource);
     const dekCache = createDekCache();
     const configCipher = masterKeyProvider
         ? createEnvelopeCipher(masterKeyProvider, { dekCache })
@@ -37,3 +27,19 @@ export function resolveBootCrypto(envSource, masterKeyOverride) {
         dekCache,
     };
 }
+function envMasterKeyProviderIfConfigured(envSource) {
+    if (!envHasMasterKek(envSource))
+        return undefined;
+    const provider = createEnvMasterKeyProvider({
+        // CURRENT_VERSION default "1" spiegelt secretsEnvSchema — ohne
+        // ihn wirft der raw-env-Provider, obwohl V1 gesetzt ist.
+        env: {
+            ...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/worker-boot-core.d.ts

@@ -4,7 +4,7 @@ import { type FeatureDefinition, type Registry } from "@cosmicdrift/kumiko-frame
 import { type WorkerEntrypoint } from "@cosmicdrift/kumiko-framework/entrypoint";
 import type { EnvelopeCipher, SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import { Redis } from "ioredis";
-import type { RunWorkerAppOptions } from "../run-worker-app.js";
+import type { RunWorkerAppOptions } from "../run-worker-app.ts";
 export type WorkerBootCoreOptions = Omit<RunWorkerAppOptions, "wireComponents">;
 export type WorkerBootProfile = {
     /** Log prefix and requireEnv context, e.g. "runWorkerApp". */

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

@@ -0,0 +1,34 @@
+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.
+ *
+ *  @example
+ *  runProdApp({ ..., billing: {
+ *    stripe: { priceToTier: { [env.STRIPE_PRICE_PRO]: "pro" } },
+ *    defaultTier: "free",
+ *  } })
+ */
+export type BillingBootOption = {
+    readonly stripe: {
+        readonly priceToTier: Readonly<Record<string, string>>;
+        /** Default `SUBSCRIPTION_WEBHOOK_PATH`; must contain `:providerName`. */
+        readonly webhookPath?: string;
+        readonly oneOffPriceIds?: SubscriptionStripeOptions["oneOffPriceIds"];
+        readonly paymentInvoiceCreation?: boolean;
+    };
+    /** 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. */
+    readonly onTierSyncError?: "log" | "fail-webhook";
+};
+export declare function resolveBillingOption(billing: BillingBootOption, envSource: Record<string, string | undefined>): {
+    readonly feature: FeatureDefinition;
+    readonly route: ExtraRouteDefinition;
+};

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

@@ -0,0 +1,35 @@
+import { createSubscriptionTierSync, SUBSCRIPTION_WEBHOOK_PATH, } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { createSubscriptionStripeFeature, } from "@cosmicdrift/kumiko-bundled-features/subscription-stripe";
+const PROVIDER_NAME_PARAM = ":providerName";
+export function resolveBillingOption(billing, envSource) {
+    const webhookPath = billing.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 tierNames = new Set([
+        billing.defaultTier,
+        ...Object.values(billing.stripe.priceToTier),
+        ...(billing.tierNames ?? []),
+    ]);
+    const tierSync = createSubscriptionTierSync({
+        isTierName: (value) => tierNames.has(value),
+        defaultTier: billing.defaultTier,
+        onSyncError: billing.onTierSyncError ?? "fail-webhook",
+    });
+    return { feature, route: tierSync.createWebhookRoute({ path: webhookPath }) };
+}

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

@@ -0,0 +1,51 @@
+import type { ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
+export type DemoAccountRole = "admin" | "sysadmin";
+/** What `GET /demo-mode` tells the client to show. Every field is optional. */
+export type DemoModeNotice = {
+    /** Banner text per locale, e.g. `{ de: "…", en: "…" }`. */
+    readonly text?: Readonly<Record<string, string>>;
+    readonly links?: readonly {
+        readonly label: Readonly<Record<string, string>>;
+        readonly href: string;
+    }[];
+    /** Demo logins to publish, read from `DEMO_ADMIN_*` / `DEMO_SYSADMIN_*`.
+     *  Published only while `readOnly` is true. Default: none — the route is
+     *  anonymous, so listing an account hands its password to every visitor. */
+    readonly accounts?: readonly DemoAccountRole[];
+};
+/** Live-demo switch. `readOnly: true` answers every mutating request
+ *  (POST/PUT/PATCH/DELETE) 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.
+ *
+ *  @example
+ *  runProdApp({ ..., demoMode: {
+ *    readOnly: env.DEMO_READ_ONLY === "true",
+ *    notice: { text: { en: "Read-only demo" }, accounts: ["admin"] },
+ *  } })
+ */
+export type DemoModeOption = {
+    readonly readOnly: boolean;
+    readonly notice?: DemoModeNotice;
+    /** Mutating paths that stay open besides the default allowlist. */
+    readonly allowedWritePaths?: readonly string[];
+};
+export declare const DEMO_MODE_PATH = "/demo-mode";
+export declare const DEMO_READ_ONLY_ERROR_CODE = "demo_read_only";
+export type DemoModePayload = {
+    readonly readOnly: boolean;
+    readonly notice: {
+        readonly text?: Readonly<Record<string, string>>;
+        readonly links?: DemoModeNotice["links"];
+        readonly accounts: readonly {
+            readonly role: DemoAccountRole;
+            readonly email: string;
+            readonly password: string;
+        }[];
+    };
+};
+export declare function buildDemoModePayload(demoMode: DemoModeOption, envSource: Record<string, string | undefined>): DemoModePayload;
+export declare function buildDemoModeRoute(demoMode: DemoModeOption, envSource: Record<string, string | undefined>): ExtraRouteDefinition;
+/** Wraps the app fetch handler; the second argument (socket address) is
+ *  passed through so client-IP rate limits keep working behind the gate. */
+export declare function withDemoReadOnlyFetch<TArg>(fetchHandler: (req: Request, arg?: TArg) => Promise<Response>, demoMode: DemoModeOption): (req: Request, arg?: TArg) => Promise<Response>;

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

@@ -0,0 +1,64 @@
+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"]);
+const DEFAULT_ALLOWED_WRITE_PATHS = [
+    "/api/query",
+    "/api/auth/login",
+    "/api/auth/logout",
+    "/api/auth/mfa/verify",
+];
+const ACCOUNT_ENV_KEYS = {
+    admin: { email: "DEMO_ADMIN_EMAIL", password: "DEMO_ADMIN_PASSWORD" },
+    sysadmin: { email: "DEMO_SYSADMIN_EMAIL", password: "DEMO_SYSADMIN_PASSWORD" },
+};
+export function buildDemoModePayload(demoMode, envSource) {
+    const accounts = demoMode.readOnly
+        ? (demoMode.notice?.accounts ?? []).flatMap((role) => {
+            const keys = ACCOUNT_ENV_KEYS[role];
+            const email = envSource[keys.email];
+            const password = envSource[keys.password];
+            return email && password ? [{ role, email, password }] : [];
+        })
+        : [];
+    return {
+        readOnly: demoMode.readOnly,
+        notice: {
+            ...(demoMode.notice?.text && { text: demoMode.notice.text }),
+            ...(demoMode.notice?.links && { links: demoMode.notice.links }),
+            accounts,
+        },
+    };
+}
+export function buildDemoModeRoute(demoMode, envSource) {
+    const payload = buildDemoModePayload(demoMode, envSource);
+    return {
+        method: "GET",
+        path: DEMO_MODE_PATH,
+        entry: "anonymous",
+        handler: (c) => c.json(payload),
+    };
+}
+/** Wraps the app fetch handler; the second argument (socket address) is
+ *  passed through so client-IP rate limits keep working behind the gate. */
+export function withDemoReadOnlyFetch(fetchHandler, demoMode) {
+    // skip: no read-only gate requested, keep the handler untouched
+    if (!demoMode.readOnly)
+        return fetchHandler;
+    const allowed = new Set([
+        ...DEFAULT_ALLOWED_WRITE_PATHS,
+        ...(demoMode.allowedWritePaths ?? []),
+    ]);
+    return async (req, arg) => {
+        if (MUTATING_METHODS.has(req.method) && !allowed.has(new URL(req.url).pathname)) {
+            return Response.json({
+                isSuccess: false,
+                error: {
+                    code: DEMO_READ_ONLY_ERROR_CODE,
+                    message: "This live demo is read-only.",
+                    i18nKey: "errors.demoReadOnly",
+                },
+            }, { status: 403 });
+        }
+        return fetchHandler(req, arg);
+    };
+}

package/dist/boot-options/file-storage-option.d.ts

@@ -0,0 +1,30 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+export type FileStorageProviderName = "s3-env" | "inmemory";
+/** Mounts the file provider feature(s) for `file-foundation` and makes the
+ *  chosen one the default (`FILE_STORAGE_PROVIDER`, an explicit env value wins).
+ *  - `"s3-env"`: one bucket from `S3_BUCKET` / `S3_REGION` / `S3_ACCESS_KEY` /
+ *    `S3_SECRET_KEY` (optional `S3_ENDPOINT`, `S3_FORCE_PATH_STYLE`); missing
+ *    values abort the boot.
+ *  - `"inmemory"`: bytes live in process memory; refused with `NODE_ENV=production`.
+ *  - `"auto"`: `"s3-env"` when the S3 env is complete; otherwise a boot error
+ *    with `NODE_ENV=production` and `"inmemory"` elsewhere.
+ *
+ *  `providers` mounts further providers so tenants can switch to them.
+ *
+ *  @example
+ *  runProdApp({ ..., fileStorage: { provider: "auto" } })
+ */
+export type FileStorageBootOption = {
+    readonly provider: FileStorageProviderName | "auto";
+    readonly providers?: readonly FileStorageProviderName[];
+};
+export declare const FILE_FOUNDATION_FEATURE = "file-foundation";
+export declare function resolveFileStorageOption(fileStorage: FileStorageBootOption, deps: {
+    readonly envSource: Record<string, string | undefined>;
+    readonly isProduction: boolean;
+    readonly mountedFeatureNames: ReadonlySet<string>;
+}): {
+    readonly provider: FileStorageProviderName;
+    readonly features: readonly FeatureDefinition[];
+    readonly envDefaults: Readonly<Record<string, string>>;
+};

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

@@ -0,0 +1,52 @@
+import { createFileProviderInMemoryFeature } from "@cosmicdrift/kumiko-bundled-features/file-provider-inmemory";
+import { createFileProviderS3Feature } from "@cosmicdrift/kumiko-bundled-features/file-provider-s3";
+import { FILE_STORAGE_PROVIDER_ENV, } from "@cosmicdrift/kumiko-framework/engine";
+export const FILE_FOUNDATION_FEATURE = "file-foundation";
+const S3_REQUIRED_ENV_KEYS = ["S3_BUCKET", "S3_REGION", "S3_ACCESS_KEY", "S3_SECRET_KEY"];
+const PROVIDER_FEATURE_NAMES = {
+    "s3-env": "file-provider-s3-env",
+    inmemory: "file-provider-inmemory",
+};
+function missingS3EnvKeys(envSource) {
+    return S3_REQUIRED_ENV_KEYS.filter((key) => !envSource[key]);
+}
+function buildProviderFeature(provider) {
+    return provider === "s3-env"
+        ? createFileProviderS3Feature({ fromEnv: true })
+        : createFileProviderInMemoryFeature();
+}
+export function resolveFileStorageOption(fileStorage, deps) {
+    const missingS3 = missingS3EnvKeys(deps.envSource);
+    let provider;
+    if (fileStorage.provider === "auto") {
+        if (missingS3.length === 0) {
+            provider = "s3-env";
+        }
+        else if (deps.isProduction) {
+            throw new Error(`[runProdApp] fileStorage "auto" with NODE_ENV=production needs S3, missing: ${missingS3.join(", ")}.`);
+        }
+        else {
+            provider = "inmemory";
+        }
+    }
+    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 wanted = new Set([provider, ...(fileStorage.providers ?? [])]);
+    const features = [...wanted]
+        .filter((name) => !deps.mountedFeatureNames.has(PROVIDER_FEATURE_NAMES[name]))
+        .map(buildProviderFeature);
+    return {
+        provider,
+        features,
+        envDefaults: deps.envSource[FILE_STORAGE_PROVIDER_ENV]
+            ? {}
+            : { [FILE_STORAGE_PROVIDER_ENV]: provider },
+    };
+}

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

@@ -0,0 +1,27 @@
+import { type KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+/** Short form over the low-level `kms` / `blindIndexKey` / `allowPlaintextPii`
+ *  fields:
+ *  - `"required"`: wires the subject-key KMS from `PLATFORM_KEK`,
+ *    `SUBJECT_KEYS_DATABASE_URL` and `KUMIKO_BLIND_INDEX_KEY` (ciphertext
+ *    slots resolved via the Key Manager); an empty trio aborts the boot.
+ *  - `"optional"`: wires it when the trio is complete. An empty trio leaves the
+ *    app without KMS and the PII boot gate decides: PII carriers abort.
+ *  - `{ plaintextReason }`: no KMS, PII stays plaintext; the reason is logged
+ *    for the audit trail. Use only for demo apps.
+ *
+ *  A partial trio throws in every mode. */
+export type KmsMode = "required" | "optional" | {
+    readonly plaintextReason: string;
+};
+export type ResolvedKmsMode = {
+    readonly kms?: KmsAdapter;
+    readonly blindIndexKey?: string;
+    readonly allowPlaintextPii?: string;
+    readonly close: () => Promise<void>;
+};
+export type LowLevelKmsFields = {
+    readonly kms?: KmsAdapter;
+    readonly blindIndexKey?: string;
+    readonly allowPlaintextPii?: string;
+};
+export declare function resolveKmsMode(kmsMode: KmsMode | undefined, lowLevel: LowLevelKmsFields, envSource: Record<string, string | undefined>): Promise<ResolvedKmsMode>;

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

@@ -0,0 +1,40 @@
+import { resolveKmsWiringAsync } from "@cosmicdrift/kumiko-framework/crypto";
+const KMS_CIPHERTEXT_SLOTS = ["PLATFORM_KEK", "PLATFORM_KEK_PREVIOUS", "KUMIKO_BLIND_INDEX_KEY"];
+export async function resolveKmsMode(kmsMode, lowLevel, envSource) {
+    const noop = () => Promise.resolve();
+    if (kmsMode === undefined) {
+        return {
+            ...(lowLevel.kms && { kms: lowLevel.kms }),
+            ...(lowLevel.blindIndexKey !== undefined && { blindIndexKey: lowLevel.blindIndexKey }),
+            ...(lowLevel.allowPlaintextPii !== undefined && {
+                allowPlaintextPii: lowLevel.allowPlaintextPii,
+            }),
+            close: noop,
+        };
+    }
+    if (lowLevel.kms !== undefined ||
+        lowLevel.blindIndexKey !== undefined ||
+        lowLevel.allowPlaintextPii !== undefined) {
+        throw new Error("[runProdApp] kmsMode cannot be combined with kms / blindIndexKey / allowPlaintextPii — pick the short form or the low-level fields.");
+    }
+    if (typeof kmsMode === "object") {
+        if (kmsMode.plaintextReason.trim() === "") {
+            throw new Error("[runProdApp] kmsMode.plaintextReason must name a reason.");
+        }
+        return { allowPlaintextPii: kmsMode.plaintextReason, close: noop };
+    }
+    const wiring = await resolveKmsWiringAsync(envSource, {
+        slots: KMS_CIPHERTEXT_SLOTS,
+        logPrefix: "[runProdApp]",
+    });
+    if ("kms" in wiring) {
+        return { kms: wiring.kms, blindIndexKey: wiring.blindIndexKey, close: wiring.close };
+    }
+    if (kmsMode === "required") {
+        throw new Error('[runProdApp] kmsMode "required": PLATFORM_KEK / SUBJECT_KEYS_DATABASE_URL / KUMIKO_BLIND_INDEX_KEY are not set. ' +
+            'Provision the KMS or use kmsMode: { plaintextReason: "…" }.');
+    }
+    // The wiring's own plaintext fallback reason is deliberately dropped: only an
+    // explicit plaintextReason may switch off the PII boot gate.
+    return { close: noop };
+}

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

@@ -0,0 +1,30 @@
+import { type EmailChannelOptions, type EmailTransport, type TenantTransportResolver } from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+/** Mounts `channel-email` with an app-wide transport and wires the auth mail
+ *  flows (`auth.mail`) to it.
+ *  - `"smtp-env"`: SMTP from `SMTP_HOST` / `SMTP_PORT` / `SMTP_SECURE` /
+ *    `SMTP_USER` / `SMTP_PASS` / `SMTP_FROM`; a missing `SMTP_HOST` aborts the boot.
+ *  - `"inmemory"`: keeps mails in memory; refused when `NODE_ENV=production`.
+ *  - an `EmailTransport` object: used as is.
+ *
+ *  @example
+ *  runProdApp({ ..., mail: { transport: "smtp-env", from: "Acme <noreply@acme.example>" } })
+ */
+export type MailBootOption = {
+    readonly transport: "smtp-env" | "inmemory" | EmailTransport;
+    /** Sender when `SMTP_FROM` is unset (`"smtp-env"` only). Default `auth.mail.from`, then `noreply@localhost`. */
+    readonly from?: string;
+    /** Maps a user id to the stored email. Default: the `user` row of that tenant. */
+    readonly resolveEmail?: EmailChannelOptions["resolveEmail"];
+    /** Per-tenant transport, see `createChannelEmailFeature`. */
+    readonly tenantTransport?: TenantTransportResolver;
+};
+export declare const CHANNEL_EMAIL_FEATURE = "channel-email";
+export declare function resolveMailOption(mail: MailBootOption, deps: {
+    readonly envSource: Record<string, string | undefined>;
+    readonly isProduction: boolean;
+    readonly authMailFrom: string | undefined;
+}): {
+    readonly feature: FeatureDefinition;
+    readonly transport: EmailTransport;
+};

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

@@ -0,0 +1,44 @@
+import { createChannelEmailFeature, createInMemoryTransport, createSmtpTransportFromEnv, } from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import { userTable } from "@cosmicdrift/kumiko-bundled-features/user";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
+export const CHANNEL_EMAIL_FEATURE = "channel-email";
+// channel-email decrypts the returned value itself, so the raw stored column
+// (ciphertext under an active KMS) is the right thing to hand back.
+async function resolveStoredUserEmail(userId, ctx) {
+    const rows = await selectMany(ctx.db, userTable, {
+        id: userId,
+        tenantId: ctx.tenantId,
+    });
+    return rows[0]?.email ?? null;
+}
+function buildSmtpEnvTransport(envSource, fallbackFrom) {
+    if (Boolean(envSource["SMTP_USER"]) !== Boolean(envSource["SMTP_PASS"])) {
+        throw new Error('[runProdApp] mail.transport "smtp-env": SMTP_USER and SMTP_PASS must be set together.');
+    }
+    const transport = createSmtpTransportFromEnv(envSource, { fallbackFrom });
+    if (!transport) {
+        throw new Error('[runProdApp] mail.transport "smtp-env" needs SMTP_HOST.');
+    }
+    return transport;
+}
+export function resolveMailOption(mail, deps) {
+    let transport;
+    if (mail.transport === "smtp-env") {
+        transport = buildSmtpEnvTransport(deps.envSource, mail.from ?? deps.authMailFrom ?? "noreply@localhost");
+    }
+    else if (mail.transport === "inmemory") {
+        if (deps.isProduction) {
+            throw new Error('[runProdApp] mail.transport "inmemory" drops every mail — not allowed with NODE_ENV=production.');
+        }
+        transport = createInMemoryTransport();
+    }
+    else {
+        transport = mail.transport;
+    }
+    const feature = createChannelEmailFeature({
+        transport,
+        resolveEmail: mail.resolveEmail ?? resolveStoredUserEmail,
+        ...(mail.tenantTransport && { tenantTransport: mail.tenantTransport }),
+    });
+    return { feature, transport };
+}

package/dist/boot-options/option-env-schema.d.ts

@@ -0,0 +1,7 @@
+import { type ComposedEnvSchema } from "@cosmicdrift/kumiko-framework/env";
+import { type BootOptionFields } from "./resolve-boot-options.ts";
+/** Adds the env blocks the boot options read to the app's composed schema, so
+ *  the dry run and the env validation cover them without the app composing
+ *  them itself. A key the app already declares keeps the app's field unless
+ *  the option needs it set; then the stricter, required field wins. */
+export declare function withBootOptionEnvBlocks(composed: ComposedEnvSchema, options: BootOptionFields): ComposedEnvSchema;

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

@@ -0,0 +1,113 @@
+import { smtpEnvSchema } from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import { kmsEnvSchema } from "@cosmicdrift/kumiko-bundled-features/crypto-shredding/env";
+import { s3EnvSchema } from "@cosmicdrift/kumiko-bundled-features/file-provider-s3";
+import { demoAdminEnvSchema } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
+import { subscriptionStripeEnvSchema } from "@cosmicdrift/kumiko-bundled-features/subscription-stripe";
+import { readKumikoMeta } from "@cosmicdrift/kumiko-framework/env";
+import * as z from "zod";
+import { isSeedFnList } from "./resolve-boot-options.js";
+const S3_REQUIRED_KEYS = ["S3_BUCKET", "S3_REGION", "S3_ACCESS_KEY", "S3_SECRET_KEY"];
+// `.unwrap()` drops what sits on the optional wrapper: the description and the
+// kumiko meta (pulumi secret, kms), both of which the dry run reports.
+function requiredField(field) {
+    if (!(field instanceof z.ZodOptional))
+        return field;
+    const inner = field.unwrap();
+    if (!(inner instanceof z.ZodType))
+        return field;
+    const described = field.description ? inner.describe(field.description) : inner;
+    const meta = readKumikoMeta(field);
+    return Object.keys(meta).length > 0 ? described.meta({ kumiko: meta }) : described;
+}
+function pickShape(shape, keys) {
+    const picked = {};
+    for (const key of keys) {
+        const field = shape[key];
+        if (field)
+            picked[key] = field;
+    }
+    return picked;
+}
+function seedEnvBlock(seeds) {
+    const keys = [];
+    const required = [];
+    if (seeds.demoTenant && seeds.demoTenant.id === undefined) {
+        keys.push("DEMO_TENANT_ID");
+        required.push("DEMO_TENANT_ID");
+    }
+    if (seeds.demoAdminFromEnv) {
+        keys.push("DEMO_ADMIN_EMAIL", "DEMO_ADMIN_PASSWORD");
+        required.push("DEMO_ADMIN_EMAIL", "DEMO_ADMIN_PASSWORD");
+    }
+    if (seeds.sysadminFromEnv) {
+        keys.push("DEMO_SYSADMIN_EMAIL", "DEMO_SYSADMIN_PASSWORD");
+        required.push("DEMO_SYSADMIN_EMAIL", "DEMO_SYSADMIN_PASSWORD");
+    }
+    if (keys.length === 0)
+        return undefined;
+    return { source: "runProdApp.seeds", shape: pickShape(demoAdminEnvSchema.shape, keys), required };
+}
+function collectOptionEnvBlocks(options) {
+    const blocks = [];
+    if (options.mail?.transport === "smtp-env") {
+        blocks.push({ source: "runProdApp.mail", shape: smtpEnvSchema.shape, required: ["SMTP_HOST"] });
+    }
+    const { fileStorage } = options;
+    if (fileStorage &&
+        (fileStorage.provider === "s3-env" ||
+            fileStorage.provider === "auto" ||
+            fileStorage.providers?.includes("s3-env"))) {
+        // auto may fall back to in-memory outside production, so its keys stay
+        // optional here; resolveFileStorageOption rejects a partial set.
+        blocks.push({
+            source: "runProdApp.fileStorage",
+            shape: s3EnvSchema.shape,
+            required: fileStorage.provider === "s3-env" ? S3_REQUIRED_KEYS : [],
+        });
+    }
+    // The trio stays optional even under "required": each KMS slot may arrive
+    // as its *_CIPHERTEXT twin instead, which resolveKmsMode checks after decryption.
+    if (options.kmsMode === "required" || options.kmsMode === "optional") {
+        blocks.push({ source: "runProdApp.kmsMode", shape: kmsEnvSchema.shape, required: [] });
+    }
+    if (options.billing) {
+        blocks.push({
+            source: "runProdApp.billing",
+            shape: subscriptionStripeEnvSchema.shape,
+            required: [],
+        });
+    }
+    if (options.seeds && !isSeedFnList(options.seeds)) {
+        const block = seedEnvBlock(options.seeds);
+        if (block)
+            blocks.push(block);
+    }
+    return blocks;
+}
+/** Adds the env blocks the boot options read to the app's composed schema, so
+ *  the dry run and the env validation cover them without the app composing
+ *  them itself. A key the app already declares keeps the app's field unless
+ *  the option needs it set; then the stricter, required field wins. */
+export function withBootOptionEnvBlocks(composed, options) {
+    const blocks = collectOptionEnvBlocks(options);
+    if (blocks.length === 0)
+        return composed;
+    const declared = composed.schema.shape;
+    const additions = {};
+    const sources = { ...composed.sources };
+    for (const block of blocks) {
+        const required = new Set(block.required);
+        for (const [key, field] of Object.entries(block.shape)) {
+            const existing = additions[key] ?? declared[key];
+            if (required.has(key)) {
+                additions[key] = requiredField(existing ?? field);
+                sources[key] ??= block.source;
+            }
+            else if (existing === undefined) {
+                additions[key] = field;
+                sources[key] = block.source;
+            }
+        }
+    }
+    return { schema: composed.schema.safeExtend(additions), sources };
+}

package/dist/boot-options/process-signals.d.ts

@@ -0,0 +1,23 @@
+export type ShutdownSignal = "SIGTERM" | "SIGINT";
+/** `false` keeps the process signals untouched (the app installs its own
+ *  handlers). The object form tunes the drain budget. */
+export type SignalsOption = false | {
+    readonly drainTimeoutMs?: number;
+};
+export declare const DEFAULT_DRAIN_TIMEOUT_MS = 25000;
+export type SignalProcess = {
+    on(signal: ShutdownSignal, listener: () => void): unknown;
+    off(signal: ShutdownSignal, listener: () => void): unknown;
+};
+export type ShutdownSignalDeps = {
+    readonly stop: () => Promise<void>;
+    readonly drainTimeoutMs?: number;
+    readonly signalProcess?: SignalProcess;
+    readonly exit?: (code: number) => void;
+    readonly log?: (message: string) => void;
+    readonly logError?: (message: string, error: unknown) => void;
+};
+/** Registers SIGTERM/SIGINT: the first signal drains via `stop()` and exits
+ *  0, a drain that fails or outlives the timeout exits 1. Returns the
+ *  uninstall function so `stop()` can drop the listeners again. */
+export declare function installShutdownSignals(deps: ShutdownSignalDeps): () => void;