@cosmicdrift/kumiko-server-runtime 0.374.0 → 0.377.0

package/dist/boot/env-gate.d.ts

@@ -0,0 +1,23 @@
+import { type ComposedEnvSchema, KumikoBootError } from "@cosmicdrift/kumiko-framework/env";
+import { type DryRunEnvMode } from "@cosmicdrift/kumiko-framework/env/dry-run";
+import type { MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
+import type { BootOptionFields } from "../boot-options/resolve-boot-options.ts";
+export type RunMode = DryRunEnvMode;
+export declare function parseRunMode(raw: string | undefined, processName?: string): RunMode | null;
+export type EnvGateOptions = BootOptionFields & {
+    readonly envSchema: ComposedEnvSchema | undefined;
+    readonly envSource?: Record<string, string | undefined>;
+    readonly masterKey?: MasterKeyProvider;
+    readonly pulumiPrefix?: string;
+    readonly bootErrorReporter?: (err: KumikoBootError) => void;
+};
+export type EnvGateResult = {
+    readonly kind: "stopped";
+} | {
+    readonly kind: "ready";
+    readonly runMode: RunMode | null;
+    readonly decryptedEnvSource: Record<string, string | undefined>;
+};
+/** Env schema parse, dry-run output and KEK-slot decryption, in front of any boot work.
+ *  `stopped` means a dry-run mode produced its output and the caller returns an inert handle. */
+export declare function runEnvGate(options: EnvGateOptions, processName: string): Promise<EnvGateResult>;

package/dist/boot/env-gate.js

@@ -0,0 +1,136 @@
+import { SECRETS_MASTER_KEK_ENV_KEYS } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { resolvePlatformKeks } from "@cosmicdrift/kumiko-framework/crypto";
+import { inspectEnv, KumikoBootError, kmsSlotsOf, parseEnv, withOptionalEnvKeys, } from "@cosmicdrift/kumiko-framework/env";
+import { DRY_RUN_ENV_VAR, parseDryRunEnvMode, renderDryRun, renderEnvInspection, } from "@cosmicdrift/kumiko-framework/env/dry-run";
+import { withBootOptionEnvBlocks } from "../boot-options/option-env-schema.js";
+// `boot` is the smoke-test path: validators run, no DB/Redis connect, exit
+// after the registry build. Render modes (human|json|pulumi|k8s|1) inspect the
+// env schema and exit before any feature wiring.
+export function parseRunMode(raw, processName = "runProdApp") {
+    const mode = parseDryRunEnvMode(raw);
+    if (mode !== undefined)
+        return mode;
+    if (raw) {
+        // biome-ignore lint/suspicious/noConsole: boot-time warn for typo discovery
+        console.warn(`[${processName}] ${DRY_RUN_ENV_VAR}="${raw}" unrecognized ` +
+            `(expected 1|human|json|pulumi|k8s|boot); continuing with normal boot.`);
+    }
+    return null;
+}
+function isRenderMode(mode) {
+    return mode !== null && mode !== "boot";
+}
+function defaultBootErrorReporter(err) {
+    // biome-ignore lint/suspicious/noConsole: boot-time error, no logger configured yet
+    console.error(err.format());
+    process.exit(1);
+}
+// The boot dry run lists these even when the app schema leaves them out
+// (JWT_SECRET usually comes from auth-email-password).
+const RUNTIME_REQUIRED_ENV_KEYS = ["DATABASE_URL", "REDIS_URL", "JWT_SECRET"];
+function inspectUndeclaredRuntimeEnv(declaredShape, env) {
+    return RUNTIME_REQUIRED_ENV_KEYS.filter((name) => !(name in declaredShape)).map((name) => ({
+        name,
+        klass: "required",
+        source: "server-runtime",
+        status: env[name] ? "set" : "missing",
+    }));
+}
+function requireEnvSchema(envSchema, processName) {
+    if (envSchema === undefined) {
+        throw new KumikoBootError([
+            {
+                name: "envSchema",
+                kind: "missing",
+                message: `${processName} needs envSchema. Pass composeEnvSchema({ core: frameworkCoreEnvSchema, features, extend }): composeEnvSchema from @cosmicdrift/kumiko-framework/env, frameworkCoreEnvSchema from @cosmicdrift/kumiko-dev-server/env-schema, features the same list as ${processName}'s.`,
+            },
+        ]);
+    }
+    return envSchema;
+}
+/** Env schema parse, dry-run output and KEK-slot decryption, in front of any boot work.
+ *  `stopped` means a dry-run mode produced its output and the caller returns an inert handle. */
+export async function runEnvGate(options, processName) {
+    const rawEnvSource = options.envSource ?? process.env;
+    const runMode = parseRunMode(rawEnvSource[DRY_RUN_ENV_VAR], processName);
+    const composedEnvSchema = withBootOptionEnvBlocks(requireEnvSchema(options.envSchema, processName), options);
+    const effectiveEnvSchema = options.masterKey
+        ? withOptionalEnvKeys(composedEnvSchema.schema, SECRETS_MASTER_KEK_ENV_KEYS)
+        : composedEnvSchema.schema;
+    const reportBootError = (err) => {
+        const reporter = options.bootErrorReporter ?? defaultBootErrorReporter;
+        reporter(err);
+    };
+    const validateEnv = (source) => {
+        try {
+            parseEnv(effectiveEnvSchema, source, {
+                sources: composedEnvSchema.sources,
+                ...(options.pulumiPrefix ? { pulumiPrefix: options.pulumiPrefix } : {}),
+            });
+        }
+        catch (err) {
+            if (err instanceof KumikoBootError)
+                reportBootError(err);
+            throw err;
+        }
+    };
+    if (isRenderMode(runMode)) {
+        // biome-ignore lint/suspicious/noConsole: dry-run output IS the deliverable
+        console.log(renderDryRun(composedEnvSchema, runMode, {
+            ...(options.pulumiPrefix ? { pulumiPrefix: options.pulumiPrefix } : {}),
+            sources: composedEnvSchema.sources,
+        }));
+        // Tests inject envSource and want a return value, not an exit.
+        if (options.envSource === undefined) {
+            process.exit(0);
+        }
+        return { kind: "stopped" };
+    }
+    if (runMode === "boot") {
+        const inspection = [
+            ...inspectEnv(effectiveEnvSchema, rawEnvSource, { sources: composedEnvSchema.sources }),
+            ...inspectUndeclaredRuntimeEnv(effectiveEnvSchema.shape, rawEnvSource),
+        ];
+        // biome-ignore lint/suspicious/noConsole: boot-mode output IS the deliverable
+        console.log(renderEnvInspection(inspection));
+        if (inspection.some((row) => row.status === "invalid")) {
+            // Missing rows go into the same report: the run fails anyway, so the
+            // operator sees every variable to fix in one pass.
+            reportBootError(new KumikoBootError(inspection.flatMap((row) => row.status === "invalid" || row.status === "missing"
+                ? [
+                    {
+                        name: row.name,
+                        kind: row.status,
+                        message: row.message ?? (row.status === "missing" ? "missing" : "invalid value"),
+                        source: row.source,
+                    },
+                ]
+                : [])));
+            return { kind: "stopped" };
+        }
+        // A build pipeline has no deploy secrets: the inventory is the result,
+        // and the wiring check needs every value, so it stops here.
+        if (inspection.some((row) => row.status === "missing")) {
+            if (options.envSource === undefined) {
+                process.exit(0);
+            }
+            return { kind: "stopped" };
+        }
+    }
+    // boot-mode with a complete env AND normal boot run the full validation,
+    // including object-level refinements the per-field check skips.
+    validateEnv(rawEnvSource);
+    // Slots the schema marks `kms` are decrypted once here so every consumer
+    // below sees the same resolved env.
+    const kmsSlots = kmsSlotsOf(composedEnvSchema.schema);
+    const decryptedEnvSource = await resolvePlatformKeks(rawEnvSource, {
+        slots: kmsSlots,
+        logPrefix: `[${processName}]`,
+    });
+    // The first parse relaxes ciphertext-only slots, so their decrypted
+    // plaintext never met the slot's own validators (.regex/.min/.refine).
+    if (kmsSlots.some((slot) => rawEnvSource[slot] === undefined && decryptedEnvSource[slot] !== undefined)) {
+        validateEnv(decryptedEnvSource);
+    }
+    return { kind: "ready", runMode, decryptedEnvSource };
+}

package/dist/boot/worker-boot-core.d.ts

@@ -4,6 +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 { FeatureTogglesWiring } from "../boot-options/feature-toggles-option.ts";
 import type { RunWorkerAppOptions } from "../run-worker-app.ts";
 export type WorkerBootCoreOptions = Omit<RunWorkerAppOptions, "wireComponents">;
 export type WorkerBootProfile = {
@@ -14,6 +15,8 @@ export type WorkerBootProfile = {
     /** One-shot process: its job queue is not drained after exit, so ctx.notify
      *  sends queued channels inline. */
     readonly deliverQueuedInline?: boolean;
+    /** Set by runWorkerApp when `featureToggles` mounted the feature; bound once the database exists. */
+    readonly featureToggles?: FeatureTogglesWiring;
 };
 export type BootedWorkerProcess = {
     readonly kind: "booted";

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

@@ -128,8 +128,16 @@ export async function bootWorkerProcess(options, envSource, profile) {
         await cacheSync.close();
         throw err;
     }
-    const resolvedEffectiveFeatures = options.effectiveFeatures ??
-        (await buildTierEffectiveFeatures(features, db, registry, cacheSync));
+    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;
+    }
     if (options.migrations !== false) {
         try {
             await assertWorkerSchemaCurrent(db, options.migrations?.dir, processName);

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

@@ -1,5 +1,10 @@
 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 | {
+    readonly role: DemoAccountRole;
+    readonly label?: Readonly<Record<string, string>>;
+};
 /** What `GET /demo-mode` tells the client to show. Every field is optional. */
 export type DemoModeNotice = {
     /** Banner text per locale, e.g. `{ de: "…", en: "…" }`. */
@@ -11,7 +16,7 @@ export type DemoModeNotice = {
     /** 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[];
+    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
@@ -39,6 +44,7 @@ export type DemoModePayload = {
         readonly links?: DemoModeNotice["links"];
         readonly accounts: readonly {
             readonly role: DemoAccountRole;
+            readonly label?: Readonly<Record<string, string>>;
             readonly email: string;
             readonly password: string;
         }[];

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

@@ -13,11 +13,14 @@ const ACCOUNT_ENV_KEYS = {
 };
 export function buildDemoModePayload(demoMode, envSource) {
     const accounts = demoMode.readOnly
-        ? (demoMode.notice?.accounts ?? []).flatMap((role) => {
+        ? (demoMode.notice?.accounts ?? []).flatMap((entry) => {
+            const { role, label } = typeof entry === "string" ? { role: entry, label: undefined } : entry;
             const keys = ACCOUNT_ENV_KEYS[role];
             const email = envSource[keys.email];
             const password = envSource[keys.password];
-            return email && password ? [{ role, email, password }] : [];
+            return email && password
+                ? [{ role, ...(label !== undefined && { label }), email, password }]
+                : [];
         })
         : [];
     return {

package/dist/boot-options/feature-toggles-option.d.ts

@@ -0,0 +1,19 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { EffectiveFeaturesResolver, FeatureDefinition, Registry } from "@cosmicdrift/kumiko-framework/engine";
+import type { CacheSyncBus } from "@cosmicdrift/kumiko-framework/redis";
+export type FeatureTogglesBinding = {
+    /** Resolver for the dispatcher: the global toggles, narrowing the tier resolver when one exists. */
+    readonly resolver: EffectiveFeaturesResolver;
+};
+export type FeatureTogglesWiring = {
+    readonly feature: FeatureDefinition;
+    /** Loads the toggle snapshot; call once the database, the registry and the cache bus exist. */
+    readonly bind: (deps: {
+        readonly db: DbConnection;
+        readonly registry: Registry;
+        readonly cacheSync: CacheSyncBus;
+        readonly tierResolver: EffectiveFeaturesResolver | undefined;
+    }) => Promise<FeatureTogglesBinding>;
+};
+/** `featureToggles: true` mounts `feature-toggles` and layers its operator switches over the tier resolver. */
+export declare function resolveFeatureTogglesOption(): FeatureTogglesWiring;

package/dist/boot-options/feature-toggles-option.js

@@ -0,0 +1,25 @@
+import { composeTierResolverWithGlobalToggles, createFeatureToggleRuntime, createFeatureTogglesFeature, } from "@cosmicdrift/kumiko-bundled-features/feature-toggles";
+/** `featureToggles: true` mounts `feature-toggles` and layers its operator switches over the tier resolver. */
+export function resolveFeatureTogglesOption() {
+    let runtime;
+    const feature = createFeatureTogglesFeature({
+        getRuntime: () => {
+            if (runtime === undefined) {
+                throw new Error("feature-toggles: the toggle runtime is not bound yet (boot order).");
+            }
+            return runtime;
+        },
+    });
+    return {
+        feature,
+        bind: async ({ db, registry, cacheSync, tierResolver }) => {
+            runtime = await createFeatureToggleRuntime(db, registry, undefined, cacheSync);
+            const toggles = runtime;
+            return {
+                resolver: tierResolver
+                    ? composeTierResolverWithGlobalToggles(tierResolver, toggles, registry)
+                    : () => toggles.effectiveFeatures(),
+            };
+        },
+    };
+}

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

@@ -9,15 +9,24 @@ export type FileStorageProviderName = "s3-env" | "inmemory";
  *  - `"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.
+ *  `providers` mounts further providers so tenants can switch to them. A
+ *  `{ name, envPrefix }` entry adds a named S3 provider reading `<envPrefix>BUCKET`
+ *  etc.; its credentials are required at boot unless `lazy` is set.
  *
  *  @example
  *  runProdApp({ ..., fileStorage: { provider: "auto" } })
  */
+export type NamedS3FileProvider = {
+    readonly name: string;
+    readonly envPrefix: string;
+    readonly lazy?: boolean;
+};
 export type FileStorageBootOption = {
     readonly provider: FileStorageProviderName | "auto";
-    readonly providers?: readonly FileStorageProviderName[];
+    readonly providers?: readonly (FileStorageProviderName | NamedS3FileProvider)[];
 };
+export declare function isNamedS3FileProvider(provider: FileStorageProviderName | NamedS3FileProvider): provider is NamedS3FileProvider;
+export declare function s3KeysOf(envPrefix: string): readonly string[];
 export declare const FILE_FOUNDATION_FEATURE = "file-foundation";
 export declare function resolveFileStorageOption(fileStorage: FileStorageBootOption, deps: {
     readonly envSource: Record<string, string | undefined>;

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

@@ -1,14 +1,36 @@
 import { createFileProviderInMemoryFeature } from "@cosmicdrift/kumiko-bundled-features/file-provider-inmemory";
-import { createFileProviderS3Feature } from "@cosmicdrift/kumiko-bundled-features/file-provider-s3";
+import { createFileProviderS3Feature, createFileProviderS3NamedEnvFeature, } from "@cosmicdrift/kumiko-bundled-features/file-provider-s3";
 import { FILE_STORAGE_PROVIDER_ENV, } from "@cosmicdrift/kumiko-framework/engine";
+export function isNamedS3FileProvider(provider) {
+    return typeof provider === "object";
+}
+export function s3KeysOf(envPrefix) {
+    return S3_KEY_SUFFIXES.map((suffix) => `${envPrefix}${suffix}`);
+}
 export const FILE_FOUNDATION_FEATURE = "file-foundation";
-const S3_REQUIRED_ENV_KEYS = ["S3_BUCKET", "S3_REGION", "S3_ACCESS_KEY", "S3_SECRET_KEY"];
+const S3_KEY_SUFFIXES = ["BUCKET", "REGION", "ACCESS_KEY", "SECRET_KEY"];
+const S3_REQUIRED_ENV_KEYS = s3KeysOf("S3_");
 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 missingEnvKeys(envSource, keys) {
+    return keys.filter((key) => !envSource[key]);
+}
+// Plugin names the bundled providers register: a named provider reusing one would
+// shadow it (or collide at registry build) for every tenant that selects it.
+const RESERVED_PROVIDER_NAMES = new Set(["s3-env", "s3", "inmemory"]);
+function assertNamedProviderNames(named) {
+    const seen = new Set();
+    for (const { name } of named) {
+        if (RESERVED_PROVIDER_NAMES.has(name)) {
+            throw new Error(`[runProdApp] fileStorage provider name "${name}" is reserved for a bundled provider — pick another name.`);
+        }
+        if (seen.has(name)) {
+            throw new Error(`[runProdApp] fileStorage provider "${name}" is listed twice.`);
+        }
+        seen.add(name);
+    }
 }
 function buildProviderFeature(provider) {
     return provider === "s3-env"
@@ -16,7 +38,7 @@ function buildProviderFeature(provider) {
         : createFileProviderInMemoryFeature();
 }
 export function resolveFileStorageOption(fileStorage, deps) {
-    const missingS3 = missingS3EnvKeys(deps.envSource);
+    const missingS3 = missingEnvKeys(deps.envSource, S3_REQUIRED_ENV_KEYS);
     let provider;
     if (fileStorage.provider === "auto") {
         if (missingS3.length === 0) {
@@ -38,10 +60,27 @@ export function resolveFileStorageOption(fileStorage, deps) {
     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);
+    const additional = fileStorage.providers ?? [];
+    const wanted = new Set([
+        provider,
+        ...additional.filter((entry) => !isNamedS3FileProvider(entry)),
+    ]);
+    const named = additional.filter(isNamedS3FileProvider);
+    assertNamedProviderNames(named);
+    for (const entry of named) {
+        const missing = entry.lazy ? [] : missingEnvKeys(deps.envSource, s3KeysOf(entry.envPrefix));
+        if (missing.length > 0) {
+            throw new Error(`[runProdApp] fileStorage provider "${entry.name}" is missing: ${missing.join(", ")}.`);
+        }
+    }
+    const features = [
+        ...[...wanted]
+            .filter((name) => !deps.mountedFeatureNames.has(PROVIDER_FEATURE_NAMES[name]))
+            .map(buildProviderFeature),
+        ...named
+            .filter((entry) => !deps.mountedFeatureNames.has(`file-provider-s3-env-${entry.name}`))
+            .map((entry) => createFileProviderS3NamedEnvFeature({ name: entry.name, envPrefix: entry.envPrefix })),
+    ];
     return {
         provider,
         features,

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

@@ -1,5 +1,5 @@
 import { type EmailChannelOptions, type EmailTransport, type TenantTransportResolver } from "@cosmicdrift/kumiko-bundled-features/channel-email";
-import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+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` /
@@ -10,17 +10,22 @@ import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
  *  @example
  *  runProdApp({ ..., mail: { transport: "smtp-env", from: "Acme <noreply@acme.example>" } })
  */
+export type MailRecipientScope = "membership" | "any";
 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 with that id (any tenant). */
+    /** Which users the default resolver reaches from a tenant other than the system tenant.
+     *  `"membership"` (default): members of the notifying tenant and SystemAdmins.
+     *  `"any"`: every user, whatever tenant notifies. Ignored with a custom `resolveEmail`. */
+    readonly recipientScope?: MailRecipientScope;
+    /** Maps a user id to the stored email. Default: see `recipientScope`. */
     readonly resolveEmail?: EmailChannelOptions["resolveEmail"];
     /** Per-tenant transport, see `createChannelEmailFeature`. */
     readonly tenantTransport?: TenantTransportResolver;
 };
 export declare const CHANNEL_EMAIL_FEATURE = "channel-email";
-export declare function resolveStoredUserEmail(userId: string, ctx: Parameters<EmailChannelOptions["resolveEmail"]>[1]): Promise<string | null>;
+export declare function resolveStoredUserEmail(userId: string, ctx: Parameters<EmailChannelOptions["resolveEmail"]>[1], recipientScope?: MailRecipientScope): Promise<string | null>;
 export declare function resolveMailOption(mail: MailBootOption, deps: {
     readonly envSource: Record<string, string | undefined>;
     readonly isProduction: boolean;

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

@@ -1,14 +1,28 @@
 import { createChannelEmailFeature, createInMemoryTransport, createSmtpTransportFromEnv, } from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import { tenantMembershipsTable } from "@cosmicdrift/kumiko-bundled-features/tenant";
 import { userTable } from "@cosmicdrift/kumiko-bundled-features/user";
-import { selectMany } from "@cosmicdrift/kumiko-framework/db";
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 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.
-export async function resolveStoredUserEmail(userId, ctx) {
-    const rows = await selectMany(ctx.db, userTable, {
-        id: userId,
+// User rows live on SYSTEM_TENANT_ID; the tenant-scoped db still reads them.
+// SystemAdmin comes from the recipient's stored global roles, never from the session.
+export async function resolveStoredUserEmail(userId, ctx, recipientScope = "membership") {
+    const user = await fetchOne(ctx.db, userTable, { id: userId });
+    if (!user)
+        return null;
+    if (recipientScope === "any" || ctx.tenantId === SYSTEM_TENANT_ID)
+        return user.email;
+    const membership = await fetchOne(ctx.db, tenantMembershipsTable, {
+        tenantId: ctx.tenantId,
+        userId,
     });
-    return rows[0]?.email ?? null;
+    if (membership || parseRoles(user.roles).includes(ROLES.SystemAdmin))
+        return user.email;
+    return null;
 }
 function buildSmtpEnvTransport(envSource, fallbackFrom) {
     if (Boolean(envSource["SMTP_USER"]) !== Boolean(envSource["SMTP_PASS"])) {
@@ -36,7 +50,8 @@ export function resolveMailOption(mail, deps) {
     }
     const feature = createChannelEmailFeature({
         transport,
-        resolveEmail: mail.resolveEmail ?? resolveStoredUserEmail,
+        resolveEmail: mail.resolveEmail ??
+            ((userId, ctx) => resolveStoredUserEmail(userId, ctx, mail.recipientScope)),
         ...(mail.tenantTransport && { tenantTransport: mail.tenantTransport }),
     });
     return { feature, transport };

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

@@ -1,21 +1,24 @@
 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 { createS3EnvSchema, 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 { isNamedS3FileProvider, s3KeysOf } from "./file-storage-option.js";
 import { isSeedFnList } from "./resolve-boot-options.js";
+const SMTP_HOST_REQUIRED_DESCRIPTION = 'SMTP host; required with mail transport "smtp-env".';
 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) {
+function requiredField(field, description) {
     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 text = description ?? field.description;
+    const described = text ? inner.describe(text) : inner;
     const meta = readKumikoMeta(field);
     return Object.keys(meta).length > 0 ? described.meta({ kumiko: meta }) : described;
 }
@@ -47,12 +50,8 @@ function seedEnvBlock(seeds) {
         return undefined;
     return { source: "runProdApp.seeds", shape: pickShape(demoAdminEnvSchema.shape, keys), required };
 }
-function collectOptionEnvBlocks(options) {
+function fileStorageEnvBlocks(fileStorage) {
     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" ||
@@ -65,6 +64,28 @@ function collectOptionEnvBlocks(options) {
             required: fileStorage.provider === "s3-env" ? S3_REQUIRED_KEYS : [],
         });
     }
+    for (const provider of fileStorage?.providers ?? []) {
+        if (!isNamedS3FileProvider(provider))
+            continue;
+        blocks.push({
+            source: `runProdApp.fileStorage.${provider.name}`,
+            shape: createS3EnvSchema({ prefix: provider.envPrefix }).shape,
+            required: provider.lazy ? [] : s3KeysOf(provider.envPrefix),
+        });
+    }
+    return blocks;
+}
+function collectOptionEnvBlocks(options) {
+    const blocks = [];
+    if (options.mail?.transport === "smtp-env") {
+        blocks.push({
+            source: "runProdApp.mail",
+            shape: smtpEnvSchema.shape,
+            required: ["SMTP_HOST"],
+            descriptions: { SMTP_HOST: SMTP_HOST_REQUIRED_DESCRIPTION },
+        });
+    }
+    blocks.push(...fileStorageEnvBlocks(options.fileStorage));
     // 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") {
@@ -100,7 +121,7 @@ export function withBootOptionEnvBlocks(composed, options) {
         for (const [key, field] of Object.entries(block.shape)) {
             const existing = additions[key] ?? declared[key];
             if (required.has(key)) {
-                additions[key] = requiredField(existing ?? field);
+                additions[key] = requiredField(existing ?? field, block.descriptions?.[key]);
                 sources[key] ??= block.source;
             }
             else if (existing === undefined) {

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

@@ -3,6 +3,7 @@ import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import type { ProdSeedFn } from "../run-prod-app.ts";
 import { type BillingBootOption } from "./billing-option.ts";
 import { type DemoModeOption } from "./demo-mode.ts";
+import { type FeatureTogglesWiring } from "./feature-toggles-option.ts";
 import { type FileStorageBootOption } from "./file-storage-option.ts";
 import { type KmsMode, type ResolvedKmsMode } from "./kms-mode.ts";
 import { type MailBootOption } from "./mail-option.ts";
@@ -13,12 +14,16 @@ export type BootOptionFields = {
     readonly kmsMode?: KmsMode;
     readonly fileStorage?: FileStorageBootOption;
     readonly billing?: BillingBootOption;
+    readonly featureToggles?: boolean;
     readonly demoMode?: DemoModeOption;
     readonly seeds?: readonly ProdSeedFn[] | ProdSeedsConfig;
     readonly kms?: ResolvedKmsMode["kms"];
     readonly blindIndexKey?: string;
     readonly allowPlaintextPii?: string;
     readonly runSingleInstance?: boolean;
+    /** 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 auth?: {
         readonly admin?: unknown;
         readonly mail?: {
@@ -34,11 +39,14 @@ export type BootOptionWiring = {
     readonly kms: ResolvedKmsMode;
     readonly shortcutSeeds: readonly DbSeedFn[];
     readonly customSeeds: readonly ProdSeedFn[];
+    /** Set when `featureToggles` mounted the feature; bind it once the database exists. */
+    readonly featureToggles?: FeatureTogglesWiring;
     /** True when `mail` mounted a transport; the auth mail flows then wire without `SMTP_HOST`. */
     readonly mailConfigured: boolean;
     readonly wrapFetch: <TArg>(handler: (req: Request, arg?: TArg) => Promise<Response>) => (req: Request, arg?: TArg) => Promise<Response>;
 };
-export declare function isSeedFnList(seeds: readonly ProdSeedFn[] | ProdSeedsConfig): seeds is readonly ProdSeedFn[];
+export declare function isSeedFnList<Fn, Config extends object>(seeds: readonly Fn[] | Config): seeds is readonly Fn[];
+export declare function rejectRemovedEffectiveFeatures(options: object): void;
 /** Runs after the env is validated and KEK slots are decrypted, before any
  *  connection: every misconfiguration of the new options fails here. */
 export declare function resolveBootOptionWiring(options: BootOptionFields, envSource: Record<string, string | undefined>): Promise<BootOptionWiring>;