@cosmicdrift/kumiko-dev-server 0.100.0 → 0.102.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.100.0",
+  "version": "0.102.0",
   "description": "Development server bootstrap for Kumiko apps. Bundles the client, mints dev-JWTs, injects the resolved AppSchema, and seeds an admin. Not for production.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -50,8 +50,8 @@
     "kumiko-schema-check": "./bin/kumiko-schema-check.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.100.0",
-    "@cosmicdrift/kumiko-framework": "0.100.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.102.0",
+    "@cosmicdrift/kumiko-framework": "0.102.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/__tests__/boot-extra-context.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, test } from "bun:test";
+import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { createRegistry, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import type { MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
+import { buildBootExtraContext } from "../run-prod-app";
+
+// Pins runProdApp's framework-default-provider autowire (buildBootExtraContext):
+// textContent unconditional, secrets feature-gated, KEK-env trap avoided, and
+// the money-horse regression (no secrets feature → no forced KEK → no throw).
+
+// db is never touched at construction time — createTextContentApi /
+// createSecretsContext only store the handle and query lazily. A bare stub
+// keeps this a fast unit test (no Postgres) instead of a full boot.
+const fakeDb = {} as unknown as DbConnection;
+const registry = createRegistry([]);
+const KEK = Buffer.alloc(32, 7).toString("base64");
+
+const otherFeature = defineFeature("widgets", () => {});
+
+describe("buildBootExtraContext — framework-default provider autowire", () => {
+  test("textContent is wired unconditionally (no secrets feature, no auth)", () => {
+    const ctx = buildBootExtraContext({
+      db: fakeDb,
+      features: [otherFeature],
+      envSource: {},
+      registry,
+      hasAuth: false,
+    });
+    expect(typeof (ctx["textContent"] as { getBlock?: unknown }).getBlock).toBe("function");
+    expect(ctx["secrets"]).toBeUndefined();
+    expect(ctx["configResolver"]).toBeUndefined();
+  });
+
+  test("secrets feature mounted + valid KEK env → ctx.secrets wired", () => {
+    const ctx = buildBootExtraContext({
+      db: fakeDb,
+      features: [createSecretsFeature()],
+      envSource: {
+        KUMIKO_SECRETS_MASTER_KEY_V1: KEK,
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+      },
+      registry,
+      hasAuth: false,
+    });
+    const secrets = ctx["secrets"] as {
+      get?: unknown;
+      set?: unknown;
+      has?: unknown;
+      delete?: unknown;
+    };
+    expect(typeof secrets.get).toBe("function");
+    expect(typeof secrets.set).toBe("function");
+  });
+
+  test("secrets feature mounted, only V1 set (no CURRENT_VERSION) → wired (default '1')", () => {
+    const ctx = buildBootExtraContext({
+      db: fakeDb,
+      features: [createSecretsFeature()],
+      envSource: { KUMIKO_SECRETS_MASTER_KEY_V1: KEK },
+      registry,
+      hasAuth: false,
+    });
+    expect(ctx["secrets"]).toBeDefined();
+  });
+
+  test("secrets feature mounted but NO KEK + no override → skipped, no throw (dev DEV_KEY path)", () => {
+    // dev wires its own DEV_KEY secrets explicitly; the auto-wire must not
+    // eagerly construct an env-provider and crash the boot when no env KEK
+    // exists. ctx.secrets stays unset so the app's explicit wiring wins.
+    let ctx: Record<string, unknown> | undefined;
+    expect(() => {
+      ctx = buildBootExtraContext({
+        db: fakeDb,
+        features: [createSecretsFeature()],
+        envSource: {},
+        registry,
+        hasAuth: false,
+      });
+    }).not.toThrow();
+    expect(ctx?.["secrets"]).toBeUndefined();
+  });
+
+  test("no secrets feature → no KEK ever read, boots green (money-horse regression)", () => {
+    const ctx = buildBootExtraContext({
+      db: fakeDb,
+      features: [otherFeature],
+      envSource: {}, // no KEK — must NOT matter when secrets isn't mounted
+      registry,
+      hasAuth: false,
+    });
+    expect(ctx["secrets"]).toBeUndefined();
+  });
+
+  test("masterKey override is used verbatim — no env-provider built", () => {
+    const override: MasterKeyProvider = {
+      wrapDek: async () => ({ encryptedDek: Buffer.alloc(0), kekVersion: 1 }),
+      unwrapDek: async () => Buffer.alloc(0),
+      currentVersion: () => 1,
+      isAvailable: async () => true,
+    };
+    // envSource is empty: if the override weren't honoured, createEnvMasterKeyProvider
+    // would throw "no KEK". It doesn't → the override path is taken.
+    const ctx = buildBootExtraContext({
+      db: fakeDb,
+      features: [createSecretsFeature()],
+      envSource: {},
+      registry,
+      hasAuth: false,
+      masterKey: override,
+    });
+    expect(ctx["secrets"]).toBeDefined();
+  });
+});

package/src/__tests__/resolve-auth-mail.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+import { type RunProdAppAuthOptions, resolveAuthMail } from "../run-prod-app";
+
+// Pins the auth.mail convenience (resolveAuthMail): one mail block expands
+// into the four explicit flow setups built from DEFAULT_AUTH_PATHS, the
+// null-transport guard (no SMTP_HOST → flows stay unwired), and explicit
+// per-flow setups winning over the mail default.
+
+const admin: RunProdAppAuthOptions["admin"] = {
+  email: "admin@example.com",
+  password: "pw-long-enough",
+  displayName: "Admin",
+  memberships: [],
+};
+
+const withMail: RunProdAppAuthOptions = {
+  admin,
+  mail: { baseUrl: "https://app.example.com", appName: "Test" },
+};
+
+describe("resolveAuthMail", () => {
+  test("no mail block → auth returned unchanged", () => {
+    const noMail: RunProdAppAuthOptions = { admin };
+    const out = resolveAuthMail(noMail, "secret", { SMTP_HOST: "localhost" });
+    expect(out.passwordReset).toBeUndefined();
+    expect(out.signup).toBeUndefined();
+  });
+
+  test("mail + SMTP_HOST → all four flows wired from DEFAULT_AUTH_PATHS", () => {
+    const out = resolveAuthMail(withMail, "secret", { SMTP_HOST: "localhost" });
+    expect(out.passwordReset?.appResetUrl).toBe("https://app.example.com/reset-password");
+    expect(out.emailVerification?.appVerifyUrl).toBe("https://app.example.com/verify-email");
+    expect(out.signup?.appActivationUrl).toBe("https://app.example.com/signup/complete");
+    expect(out.invite?.appAcceptUrl).toBe("https://app.example.com/invite/accept");
+    expect(typeof out.passwordReset?.sendResetEmail).toBe("function");
+  });
+
+  test("mail but NO SMTP_HOST → null-transport guard, flows stay unwired", () => {
+    const out = resolveAuthMail(withMail, "secret", {});
+    expect(out.passwordReset).toBeUndefined();
+    expect(out.signup).toBeUndefined();
+  });
+
+  test("explicit per-flow setup wins over the mail default", () => {
+    const explicit: RunProdAppAuthOptions = {
+      ...withMail,
+      passwordReset: {
+        hmacSecret: "h",
+        appResetUrl: "https://custom.example.com/pw",
+        sendResetEmail: async () => {},
+      },
+    };
+    const out = resolveAuthMail(explicit, "secret", { SMTP_HOST: "localhost" });
+    expect(out.passwordReset?.appResetUrl).toBe("https://custom.example.com/pw");
+    // other flows still come from the mail default
+    expect(out.signup?.appActivationUrl).toBe("https://app.example.com/signup/complete");
+  });
+
+  test("paths override only affects the named path", () => {
+    const pathsOverride: RunProdAppAuthOptions = {
+      admin,
+      mail: { baseUrl: "https://app.example.com", paths: { resetPassword: "/pw" } },
+    };
+    const out = resolveAuthMail(pathsOverride, "secret", { SMTP_HOST: "localhost" });
+    expect(out.passwordReset?.appResetUrl).toBe("https://app.example.com/pw");
+    expect(out.emailVerification?.appVerifyUrl).toBe("https://app.example.com/verify-email");
+  });
+});

package/src/__tests__/session-wiring.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "bun:test";
+import { resolveProdSessionsConfig, shouldWireProdSessions } from "../session-wiring";
+
+describe("shouldWireProdSessions — secure-by-default with opt-out (KF-1)", () => {
+  it("wires sessions when the feature is mounted, even without an explicit config", () => {
+    // The publicstatus bug: sessions feature mounted + auth set, but no auth.sessions —
+    // previously left stateless (no revocation). Now it wires automatically.
+    expect(shouldWireProdSessions(true, true, undefined)).toBe(true);
+  });
+
+  it("wires sessions when a config object is given", () => {
+    expect(shouldWireProdSessions(true, true, { expiresInMs: 1000 })).toBe(true);
+  });
+
+  it("does not wire when sessions: false (explicit opt-out)", () => {
+    expect(shouldWireProdSessions(true, true, false)).toBe(false);
+  });
+
+  it("does not wire when the sessions feature is not mounted", () => {
+    expect(shouldWireProdSessions(true, false, undefined)).toBe(false);
+  });
+
+  it("does not wire when the app has no auth at all", () => {
+    expect(shouldWireProdSessions(false, true, undefined)).toBe(false);
+  });
+});
+
+describe("resolveProdSessionsConfig", () => {
+  it("passes a config object through", () => {
+    expect(resolveProdSessionsConfig({ expiresInMs: 5000 })).toEqual({ expiresInMs: 5000 });
+  });
+
+  it("collapses false / undefined to defaults", () => {
+    expect(resolveProdSessionsConfig(undefined)).toEqual({});
+    expect(resolveProdSessionsConfig(false)).toEqual({});
+  });
+});

package/src/run-dev-app.ts

@@ -41,6 +41,7 @@ import {
   validateAppCustomScreenWriteQns,
   validateBoot,
 } from "@cosmicdrift/kumiko-framework/engine";
+import type { MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
 import type { TestStack } from "@cosmicdrift/kumiko-framework/stack";
 import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import { applyBootSeeds } from "./boot/apply-boot-seeds";
@@ -58,6 +59,7 @@ import { renderWelcomeBanner } from "./welcome-banner";
 // brauchen. PasswordResetSetup / EmailVerificationSetup leben in
 // run-prod-app.ts (single source of truth) — hier nur durchgereicht.
 export type {
+  AuthMailOptions,
   EmailVerificationSetup,
   InviteSetup,
   PasswordResetSetup,
@@ -65,12 +67,13 @@ export type {
 } from "./run-prod-app";
 
 import type {
+  AuthMailOptions,
   EmailVerificationSetup,
   InviteSetup,
   PasswordResetSetup,
   SignupSetup,
 } from "./run-prod-app";
-import { addConfigAccessorFactory } from "./run-prod-app";
+import { addConfigAccessorFactory, buildBootExtraContext, resolveAuthMail } from "./run-prod-app";
 
 export type RunDevAppAuthOptions = {
   /** Admin user to seed at boot. Idempotent — re-runs in persistent-DB
@@ -90,6 +93,12 @@ export type RunDevAppAuthOptions = {
   readonly sessions?: {
     readonly expiresInMs?: number;
   };
+  /** Auth-Mail-Convenience — symmetrisch zu RunProdAppAuthOptions.mail.
+   *  Verdrahtet alle 4 Mail-Flows aus env-SMTP + Standard-Templates;
+   *  hmacSecret = `JWT_SECRET`-env (Dev-Fallback wenn ungesetzt). Ohne
+   *  `SMTP_HOST`-env bleiben die Flows unverdrahtet (Null-Transport-Guard).
+   *  Explizite Flow-Setups gewinnen über den mail-Default. */
+  readonly mail?: AuthMailOptions;
   /** Password-reset flow. Wenn gesetzt werden /api/auth/request-password-
    *  reset + /api/auth/reset-password als Public-Routes gemounted UND
    *  der request/confirm-Handler im auth-email-password-Feature wird
@@ -154,9 +163,14 @@ export type RunDevAppOptions = {
   /** Eigene Seed-Funktionen, laufen nach dem Admin (wenn auth) in
    *  Array-Reihenfolge. */
   readonly seeds?: readonly SeedFn[];
-  /** Extra-AppContext-Keys. Im auth-mode wird `configResolver` automatisch
-   *  hinzugefügt — kein Override durch den Caller nötig. */
+  /** Extra-AppContext-Keys. `textContent` (immer) + `secrets` (wenn das
+   *  secrets-Feature gemountet ist) + `configResolver` (auth-mode) werden
+   *  automatisch ergänzt — App-Werte gewinnen. Symmetrisch zu runProdApp. */
   readonly extraContext?: CreateKumikoServerOptions["extraContext"];
+  /** MasterKeyProvider für die auto-verdrahtete `ctx.secrets`. Default:
+   *  `createEnvMasterKeyProvider`. Override für KMS-Backends. Nur relevant
+   *  wenn das secrets-Feature gemountet ist. Symmetrisch zu runProdApp. */
+  readonly masterKey?: MasterKeyProvider;
   /** Env-Quelle für die ENV→config-app-override-Brücke (Keys mit `env:`
    *  bekommen ihren env-Wert als app-override-Default — symmetrisch zu
    *  runProdApp). Default `process.env`. Injizierbar als Test-Seam, damit
@@ -194,9 +208,21 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
   // source of truth — auch runProdApp und der per-app drizzle-Schema-
   // Generator nutzen denselben Helper, damit Migration und Runtime nie
   // auseinanderdriften können).
-  const composeAuthOptions = buildComposeAuthOptions(options.auth);
+  const envSource = options.envSource ?? process.env;
+  // auth.mail → normalisiert in die expliziten Flow-Felder (symmetrisch zu
+  // runProdApp). hmacSecret = JWT_SECRET-env mit Dev-Fallback (der Dev-Server
+  // mintet JWTs selbst; der Reset-Token-HMAC teilt denselben Key wie in den
+  // Apps). Ab hier IMMER effectiveAuth statt options.auth.
+  const effectiveAuth = options.auth
+    ? resolveAuthMail(
+        options.auth,
+        envSource["JWT_SECRET"] ?? "kumiko-dev-auth-mail-hmac-fallback-secret",
+        envSource,
+      )
+    : undefined;
+  const composeAuthOptions = buildComposeAuthOptions(effectiveAuth);
   const features = composeFeatures(options.features, {
-    includeBundled: !!options.auth,
+    includeBundled: !!effectiveAuth,
     ...(composeAuthOptions && { authOptions: composeAuthOptions }),
   });
 
@@ -277,13 +303,26 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
   // throwaway-Registry hier extrahiert nur die config-Keys, weil der
   // configResolver vor dem Server-Boot konstruiert wird (stack.registry
   // gibt's erst onAfterSetup) — createKumikoServer baut intern seine eigene.
-  const extraContext = options.auth
-    ? mergeConfigResolverDefault(
-        options.extraContext,
-        createRegistry(features),
-        options.envSource ?? process.env,
-      )
+  const cfgExtra = effectiveAuth
+    ? mergeConfigResolverDefault(options.extraContext, createRegistry(features), envSource)
     : options.extraContext;
+  // Auto-wire textContent (immer) + secrets (feature-gated), symmetrisch zu
+  // runProdApp. Anders als prod existiert die db hier erst im Factory-deps
+  // (createKumikoServer baut den Stack), darum als Factory: buildBootExtraContext
+  // mit hasAuth:false (configResolver kommt schon aus cfgExtra), App-Werte
+  // (cfgExtra) gewinnen über die Boot-Defaults.
+  const extraContext: CreateKumikoServerOptions["extraContext"] = (deps) => {
+    const boot = buildBootExtraContext({
+      db: deps.db,
+      features,
+      envSource,
+      registry: deps.registry,
+      hasAuth: false,
+      ...(options.masterKey && { masterKey: options.masterKey }),
+    });
+    const base = typeof cfgExtra === "function" ? cfgExtra(deps) : (cfgExtra ?? {});
+    return { ...boot, ...base };
+  };
 
   // Sessions opt-in: Holder lebt im closure, `createSessionCallbacks`
   // kennt erst nach setupTestStack die echte db-connection. Inline
@@ -300,7 +339,7 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
     return sessionCallbacks;
   };
   const sessionAuthFragment =
-    options.auth?.sessions !== undefined
+    effectiveAuth?.sessions !== undefined
       ? {
           sessionCreator: (user: SessionUser, meta: SessionMetadata) =>
             requireSessions().sessionCreator(user, meta),
@@ -334,55 +373,55 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
     ...(finalEffectiveFeatures !== undefined && {
       effectiveFeatures: finalEffectiveFeatures,
     }),
-    ...(options.auth && {
+    ...(effectiveAuth && {
       auth: {
         membershipQuery: TenantQueries.memberships,
         loginHandler: AuthHandlers.login,
-        loginErrorStatusMap: options.auth.loginErrorStatusMap ?? {
+        loginErrorStatusMap: effectiveAuth.loginErrorStatusMap ?? {
           [AuthErrors.invalidCredentials]: 401,
           [AuthErrors.noMembership]: 403,
         },
-        ...(options.auth.cookieDomain !== undefined && {
-          cookieDomain: options.auth.cookieDomain,
+        ...(effectiveAuth.cookieDomain !== undefined && {
+          cookieDomain: effectiveAuth.cookieDomain,
         }),
-        ...(options.auth.allowedOrigins !== undefined && {
-          allowedOrigins: options.auth.allowedOrigins,
+        ...(effectiveAuth.allowedOrigins !== undefined && {
+          allowedOrigins: effectiveAuth.allowedOrigins,
         }),
-        ...(options.auth.unsafeSkipOriginCheck !== undefined && {
-          unsafeSkipOriginCheck: options.auth.unsafeSkipOriginCheck,
+        ...(effectiveAuth.unsafeSkipOriginCheck !== undefined && {
+          unsafeSkipOriginCheck: effectiveAuth.unsafeSkipOriginCheck,
         }),
         ...sessionAuthFragment,
-        ...(options.auth.passwordReset && {
+        ...(effectiveAuth.passwordReset && {
           passwordReset: {
             requestHandler: AuthHandlers.requestPasswordReset,
             confirmHandler: AuthHandlers.resetPassword,
-            sendResetEmail: options.auth.passwordReset.sendResetEmail,
-            appResetUrl: options.auth.passwordReset.appResetUrl,
+            sendResetEmail: effectiveAuth.passwordReset.sendResetEmail,
+            appResetUrl: effectiveAuth.passwordReset.appResetUrl,
           },
         }),
-        ...(options.auth.emailVerification && {
+        ...(effectiveAuth.emailVerification && {
           emailVerification: {
             requestHandler: AuthHandlers.requestEmailVerification,
             confirmHandler: AuthHandlers.verifyEmail,
-            sendVerificationEmail: options.auth.emailVerification.sendVerificationEmail,
-            appVerifyUrl: options.auth.emailVerification.appVerifyUrl,
+            sendVerificationEmail: effectiveAuth.emailVerification.sendVerificationEmail,
+            appVerifyUrl: effectiveAuth.emailVerification.appVerifyUrl,
           },
         }),
-        ...(options.auth.signup && {
+        ...(effectiveAuth.signup && {
           signup: {
             requestHandler: AuthHandlers.signupRequest,
             confirmHandler: AuthHandlers.signupConfirm,
-            sendActivationEmail: options.auth.signup.sendActivationEmail,
-            appActivationUrl: options.auth.signup.appActivationUrl,
+            sendActivationEmail: effectiveAuth.signup.sendActivationEmail,
+            appActivationUrl: effectiveAuth.signup.appActivationUrl,
           },
         }),
-        ...(options.auth.invite && {
+        ...(effectiveAuth.invite && {
           invite: {
             acceptHandler: AuthHandlers.inviteAccept,
             acceptWithLoginHandler: AuthHandlers.inviteAcceptWithLogin,
             signupCompleteHandler: AuthHandlers.inviteSignupComplete,
-            sendInviteEmail: options.auth.invite.sendInviteEmail,
-            appAcceptUrl: options.auth.invite.appAcceptUrl,
+            sendInviteEmail: effectiveAuth.invite.sendInviteEmail,
+            appAcceptUrl: effectiveAuth.invite.appAcceptUrl,
           },
         }),
       },
@@ -398,15 +437,15 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
           registry: stack.registry,
         });
       }
-      if (options.auth?.sessions !== undefined) {
-        const expiresInMs = options.auth.sessions.expiresInMs;
+      if (effectiveAuth?.sessions !== undefined) {
+        const expiresInMs = effectiveAuth.sessions.expiresInMs;
         sessionCallbacks = createSessionCallbacks({
           db: stack.db,
           ...(expiresInMs !== undefined && { expiresInMs }),
         });
       }
-      if (options.auth) {
-        await seedAdmin(stack.db, options.auth.admin);
+      if (effectiveAuth) {
+        await seedAdmin(stack.db, effectiveAuth.admin);
       }
       // Apply r.config({ seeds }) declared by any registered feature.
       // Runs before user-supplied seed callbacks so those can read /
@@ -424,10 +463,10 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
     const port = handle.server?.port ?? options.port ?? 3000;
     const banner = renderWelcomeBanner({
       url: `http://localhost:${port}`,
-      ...(options.auth?.admin && {
+      ...(effectiveAuth?.admin && {
         admin: {
-          email: options.auth.admin.email,
-          password: options.auth.admin.password,
+          email: effectiveAuth.admin.email,
+          password: effectiveAuth.admin.password,
         },
       }),
       ...(overrides.featuresDir !== undefined && { featuresDir: overrides.featuresDir }),

package/src/run-prod-app.ts

@@ -27,8 +27,13 @@
 import {
   AuthErrors,
   AuthHandlers,
+  type AuthMailerConfig,
+  type AuthMailLocale,
+  type AuthPaths,
+  createAuthMailerConfig,
   type EmailVerificationOptions,
   type InviteOptions,
+  makeAuthPaths,
   type PasswordResetOptions,
   type SignupOptions,
 } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
@@ -36,13 +41,22 @@ import {
   type SeedAdminOptions,
   seedAdmin,
 } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
+import { createSmtpTransportFromEnv } from "@cosmicdrift/kumiko-bundled-features/channel-email";
 import {
   buildEnvConfigOverrides,
   createConfigAccessorFactory,
   createConfigResolver,
 } from "@cosmicdrift/kumiko-bundled-features/config";
-import { createSessionCallbacks } from "@cosmicdrift/kumiko-bundled-features/sessions";
+import {
+  createSecretsContext,
+  SECRETS_FEATURE_NAME,
+} from "@cosmicdrift/kumiko-bundled-features/secrets";
+import {
+  createSessionCallbacks,
+  SESSIONS_FEATURE,
+} from "@cosmicdrift/kumiko-bundled-features/sessions";
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import { createTextContentApi } from "@cosmicdrift/kumiko-bundled-features/text-content";
 import { UserQueries } from "@cosmicdrift/kumiko-bundled-features/user";
 import {
   type CachePolicy,
@@ -52,7 +66,11 @@ import {
   createSseBroker,
   type SseBroker,
 } from "@cosmicdrift/kumiko-framework/api";
-import { createDbConnection, type DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createDbConnection,
+  type DbConnection,
+  type DbRunner,
+} from "@cosmicdrift/kumiko-framework/db";
 import {
   buildAppSchema,
   type ConfigResolver,
@@ -94,6 +112,10 @@ import {
   createEventDedup,
   createIdempotencyGuard,
 } from "@cosmicdrift/kumiko-framework/pipeline";
+import {
+  createEnvMasterKeyProvider,
+  type MasterKeyProvider,
+} from "@cosmicdrift/kumiko-framework/secrets";
 import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import Redis from "ioredis";
 import { applyBootSeeds } from "./boot/apply-boot-seeds";
@@ -101,6 +123,12 @@ import { ASSETS_DIR } from "./build-prod-bundle";
 import { buildComposeAuthOptions, composeFeatures } from "./compose-features";
 import { type ExtraRoutesSystemDeps, makeDispatchSystemWrite } from "./extra-routes-deps";
 import { injectSchema } from "./inject-schema";
+import {
+  type ProdSessionsConfig,
+  type ProdSessionsOption,
+  resolveProdSessionsConfig,
+  shouldWireProdSessions,
+} from "./session-wiring";
 import { tryHonoFirst } from "./try-hono-first";
 
 /**
@@ -258,6 +286,24 @@ export type InviteSetup = InviteOptions & {
   readonly appAcceptUrl: string;
 };
 
+/** Auth-Mail-Convenience-Optionen — shared zwischen runProdApp + runDevApp.
+ *  Verdrahtet alle 4 Mail-Flows aus einem env-SMTP-Transport + Standard-
+ *  Templates (siehe `auth.mail` + resolveAuthMail). */
+export type AuthMailOptions = {
+  /** App-Basis-URL inkl. Schema (z.B. "https://app.example.com"). */
+  readonly baseUrl: string;
+  /** App-Name für Mail-Subject + Body. Default "Account". */
+  readonly appName?: string;
+  /** Locale für die Mail-Templates. Default "de". */
+  readonly locale?: AuthMailLocale;
+  /** "strict" blockt Login bis emailVerified; "off" mountet ohne Gate. */
+  readonly emailVerificationMode?: "strict" | "off";
+  /** Fallback-From-Adresse wenn `SMTP_FROM`-env fehlt (env gewinnt). */
+  readonly from?: string;
+  /** Einzelne Auth-Pfade überschreiben (Default DEFAULT_AUTH_PATHS). */
+  readonly paths?: Partial<AuthPaths>;
+};
+
 export type RunProdAppAuthOptions = {
   /** Initial admin user. Seeded once (idempotent — re-boots check first
    *  whether the email is already in the users table). */
@@ -271,13 +317,27 @@ export type RunProdAppAuthOptions = {
    *
    *  Standardverhalten ohne diese Option: stateless JWTs ohne sid
    *  (legacy-Verhalten, Karten­haus existing-Apps unangefasst). */
-  readonly sessions?: {
-    readonly expiresInMs?: number;
-  };
+  readonly sessions?: ProdSessionsOption;
+  /** Auth-Mail-Convenience: verdrahtet alle 4 Mail-Flows (passwordReset,
+   *  emailVerification, signup, invite) aus einem SMTP-Transport-aus-env +
+   *  Standard-Templates. Ersetzt das per-App hand-gerollte
+   *  `createSmtpTransportFromEnv` + `createAuthMailerConfig`-Wrapper-Trio.
+   *
+   *  Null-Transport-Guard: ohne `SMTP_HOST`-env wird KEIN Mail-Flow
+   *  verdrahtet (Routes blieben sonst 500). Eine App die einen einzelnen
+   *  Flow custom braucht, setzt `passwordReset`/`signup`/… explizit —
+   *  der explizite Block gewinnt über den mail-Default.
+   *
+   *  Bewusste Entscheidung: `mail` mountet ALLE 4 Flows inkl. signup +
+   *  invite (Self-Registration on). Wer nur reset+verify will, lässt `mail`
+   *  weg und setzt die gewünschten Flows explizit — kein impliziter
+   *  Self-Signup. */
+  readonly mail?: AuthMailOptions;
   /** Password-reset flow. When set, /api/auth/request-password-reset +
    *  /api/auth/reset-password are mounted as public routes UND der
    *  request/confirm-Handler im auth-email-password-Feature wird
-   *  registriert (sonst dispatchen die Routes ins Leere → 500). */
+   *  registriert (sonst dispatchen die Routes ins Leere → 500).
+   *  Überschreibt den `mail`-Default für genau diesen Flow. */
   readonly passwordReset?: PasswordResetSetup;
   /** Email-verification flow. Symmetric to passwordReset. */
   readonly emailVerification?: EmailVerificationSetup;
@@ -421,13 +481,22 @@ export type RunProdAppOptions = {
    *  Setups die ihren eigenen Schema-Check fahren (z.B. bring-your-own-
    *  ORM). Standard-Apps lassen das default. */
   readonly migrations?: { readonly dir: string } | false;
-  /** Extra AppContext keys. configResolver is auto-set in auth-mode.
-   *  Akzeptiert entweder einen statischen Object ODER eine Factory
+  /** Extra AppContext keys. Framework-Defaults werden zur Boot-Zeit
+   *  unter den Factory-Werten ergänzt, App-Werte gewinnen immer:
+   *    - `textContent` (createTextContentApi(db)) — immer
+   *    - `secrets` (createSecretsContext) — nur wenn das `secrets`-Feature
+   *      gemountet ist (sonst kein KEK-env-Zwang für Apps ohne secrets)
+   *    - `configResolver` — im Auth-Mode (env-config-overrides)
+   *  Akzeptiert einen statischen Object ODER eine Factory
    *  `({db, redis, registry}) => Record<string, unknown>` — gleiches
-   *  Pattern wie `anonymousAccess`. Im Auth-Mode wird `configResolver`
-   *  weiterhin automatisch ergänzt; Factory-Result + auto-resolver
-   *  werden gemerged (Factory-Werte überschreiben). */
+   *  Pattern wie `anonymousAccess`. Eine App die einen dieser Keys selbst
+   *  setzt (z.B. eigener configResolver) überschreibt den Default. */
   readonly extraContext?: ExtraContextOption;
+  /** MasterKeyProvider für die auto-verdrahtete `ctx.secrets`. Default:
+   *  `createEnvMasterKeyProvider` (KEK aus `KUMIKO_SECRETS_MASTER_KEY_V<n>`).
+   *  Override für KMS-Backends (AWS/GCP/Azure) statt env-KEK. Nur relevant
+   *  wenn das `secrets`-Feature gemountet ist. */
+  readonly masterKey?: MasterKeyProvider;
   /** Deploy-Topologie. Default `true` (Single-Container): dieser Prozess
    *  fährt HTTP + BEIDE Job-Lanes (api + worker) + den Event-Dispatcher
    *  (MSP-Anwendung) inline — via `createAllInOneEntrypoint`. Damit laufen
@@ -547,6 +616,109 @@ export function addConfigAccessorFactory<T extends { readonly configResolver?: C
   };
 }
 
+// Framework-Default-Provider für den AppContext — gleicher Mechanismus wie
+// der tenantTierResolver-Autowire (findTierResolverUsage): deklarierter
+// Bedarf (Feature gemountet) → Default aus db/env, App überschreibt nur die
+// Ausnahme. textContent ist unbedingt (createTextContentApi wirft nie, baut
+// nur einen db-gebundenen Accessor). secrets wird nur auto-verdrahtet wenn
+// das secrets-Feature gemountet ist UND ein KEK tatsächlich verfügbar ist
+// (masterKey-Override ODER env-KEK present) — sonst skip, damit der eager
+// createEnvMasterKeyProvider nicht wirft. Das deckt zwei Fälle: (a) App ohne
+// secrets → kein KEK-Zwang; (b) dev mit App-eigenem DEV-KEK in extraContext
+// (kein env-KEK) → kein Boot-Crash, die App-explizite secrets-Wiring gewinnt.
+// Prod-Misconfig (secrets gemountet, kein KEK) fängt schon secretsEnvSchema
+// beim Boot; fehlt der env-Schema-Pfad, wirft requireSecretsContext beim
+// ersten ctx.secrets-Zugriff mit Wiring-Hinweis. configResolver nur im
+// Auth-Mode. Exportiert + pure für Unit-Tests; der merge mit App-Werten
+// passiert beim Caller (App gewinnt).
+const MASTER_KEK_VAR = /^KUMIKO_SECRETS_MASTER_KEY_V\d+$/;
+function envHasMasterKek(env: Record<string, string | undefined>): boolean {
+  return Object.entries(env).some(([k, v]) => MASTER_KEK_VAR.test(k) && !!v);
+}
+
+export function buildBootExtraContext(opts: {
+  readonly db: DbConnection;
+  readonly features: readonly FeatureDefinition[];
+  readonly envSource: Record<string, string | undefined>;
+  readonly registry: Registry;
+  readonly hasAuth: boolean;
+  readonly masterKey?: MasterKeyProvider;
+}): Record<string, unknown> {
+  const hasSecretsFeature = opts.features.some((f) => f.name === SECRETS_FEATURE_NAME);
+  const wireSecrets =
+    hasSecretsFeature && (opts.masterKey !== undefined || envHasMasterKek(opts.envSource));
+  return {
+    textContent: createTextContentApi(opts.db),
+    ...(wireSecrets && {
+      secrets: createSecretsContext({
+        db: opts.db,
+        masterKeyProvider:
+          opts.masterKey ??
+          createEnvMasterKeyProvider({
+            // CURRENT_VERSION default "1" spiegelt secretsEnvSchema — ohne
+            // ihn wirft der raw-env-Provider, obwohl V1 gesetzt ist.
+            env: {
+              ...opts.envSource,
+              KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION:
+                opts.envSource["KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION"] ?? "1",
+            },
+          }),
+      }),
+    }),
+    ...(opts.hasAuth && {
+      configResolver: createConfigResolver({
+        appOverrides: buildEnvConfigOverrides(opts.registry, opts.envSource),
+      }),
+    }),
+  };
+}
+
+// auth.mail-Convenience → normalisiert in die expliziten passwordReset/
+// emailVerification/signup/invite-Felder, BEVOR buildComposeAuthOptions
+// (Feature-Side: hmacSecret/mode) und das auth-routes-Fragment sie lesen —
+// so speist EIN mail-Block beide Pfade. App-explizite Flows gewinnen über
+// den Default. Null-Transport-Guard: ohne SMTP_HOST-env bleibt alles
+// unverdrahtet (sonst lieferten die reset/verify-Routes 500).
+/** Die Auth-Felder die resolveAuthMail liest/normalisiert — beide
+ *  App-Auth-Typen (prod + dev) erfüllen das strukturell. */
+type AuthMailNormalizable = {
+  readonly mail?: AuthMailOptions;
+  readonly passwordReset?: PasswordResetSetup;
+  readonly emailVerification?: EmailVerificationSetup;
+  readonly signup?: SignupSetup;
+  readonly invite?: InviteSetup;
+};
+
+export function resolveAuthMail<T extends AuthMailNormalizable>(
+  auth: T,
+  hmacSecret: string,
+  envSource: Record<string, string | undefined>,
+): T {
+  if (!auth.mail) return auth;
+  const mailSender = createSmtpTransportFromEnv(envSource, {
+    fallbackFrom: auth.mail.from ?? "noreply@localhost",
+  });
+  if (!mailSender) return auth;
+  const mc: AuthMailerConfig = createAuthMailerConfig({
+    mailSender,
+    hmacSecret,
+    baseUrl: auth.mail.baseUrl,
+    paths: makeAuthPaths(auth.mail.paths),
+    ...(auth.mail.appName !== undefined && { appName: auth.mail.appName }),
+    ...(auth.mail.locale !== undefined && { locale: auth.mail.locale }),
+    ...(auth.mail.emailVerificationMode !== undefined && {
+      emailVerificationMode: auth.mail.emailVerificationMode,
+    }),
+  });
+  return {
+    ...auth,
+    passwordReset: auth.passwordReset ?? mc.passwordReset,
+    emailVerification: auth.emailVerification ?? mc.emailVerification,
+    signup: auth.signup ?? mc.signup,
+    invite: auth.invite ?? mc.invite,
+  };
+}
+
 export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHandle> {
   // 0. Env-Schema validation + dry-run modes. Runs FIRST so:
   //    - operators can introspect env-requirements without a real boot
@@ -618,14 +790,21 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
   console.log(`[runProdApp] booting Kumiko stack on port ${port}…`);
 
+  // auth.mail → expandiert in die expliziten Flow-Felder, bevor sie sowohl
+  // die Feature-Side (buildComposeAuthOptions) als auch das Routes-Fragment
+  // unten speisen. Ab hier IMMER effectiveAuth statt options.auth lesen.
+  const effectiveAuth = options.auth
+    ? resolveAuthMail(options.auth, jwtSecret, envSource)
+    : undefined;
+
   // 3. Feature registry. Auth-mode auto-mixes config/user/tenant/auth-email-
   //    password via composeFeatures — same source-of-truth as runDevApp
   //    AND the per-app drizzle-Schema-Generator, so Migration und Runtime
   //    sehen exakt dieselbe Liste. Built BEFORE any connection so boot-mode
   //    can validate wiring and exit without opening a Postgres/Redis socket.
-  const composeAuthOptions = buildComposeAuthOptions(options.auth);
+  const composeAuthOptions = buildComposeAuthOptions(effectiveAuth);
   const features = composeFeatures(options.features, {
-    includeBundled: !!options.auth,
+    includeBundled: !!effectiveAuth,
     ...(composeAuthOptions && { authOptions: composeAuthOptions }),
   });
 
@@ -719,15 +898,19 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
     typeof options.extraContext === "function"
       ? options.extraContext(deps)
       : (options.extraContext ?? {});
+
+  // Framework-Default-Provider zuerst, App-Werte (resolvedExtraContext)
+  // gewinnen immer (z.B. money-horse's eigener configResolver).
+  const autoExtraContext = buildBootExtraContext({
+    db,
+    features,
+    envSource,
+    registry,
+    hasAuth: !!effectiveAuth,
+    ...(options.masterKey && { masterKey: options.masterKey }),
+  });
   const extraContext = addConfigAccessorFactory(
-    options.auth
-      ? {
-          configResolver: createConfigResolver({
-            appOverrides: buildEnvConfigOverrides(registry, envSource),
-          }),
-          ...resolvedExtraContext,
-        }
-      : resolvedExtraContext,
+    { ...autoExtraContext, ...resolvedExtraContext },
     registry,
   );
   const resolvedAnonymousAccess =
@@ -743,8 +926,16 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   // AuthRoutesConfig-Surface — der wird vom sessions-Feature selbst über
   // die `autoRevokeOnPasswordChange`-Option konsumiert, nicht über die
   // auth-routes.
-  const sessionAuthFragment = options.auth?.sessions
-    ? buildProdSessionAuth(db, options.auth.sessions)
+  // Secure-by-default: if the sessions feature is mounted, server-side revocation +
+  // sessionStrictMode are wired automatically; `auth.sessions` only overrides the config,
+  // and `auth.sessions: false` is the explicit opt-out (back to stateless JWTs).
+  const sessionsFeatureMounted = features.some((f) => f.name === SESSIONS_FEATURE);
+  const sessionAuthFragment = shouldWireProdSessions(
+    Boolean(effectiveAuth),
+    sessionsFeatureMounted,
+    effectiveAuth?.sessions,
+  )
+    ? buildProdSessionAuth(db, resolveProdSessionsConfig(effectiveAuth?.sessions))
     : undefined;
 
   const baseEntrypointOptions = {
@@ -765,56 +956,56 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
       ...(resolvedEffectiveFeatures && { effectiveFeatures: resolvedEffectiveFeatures }),
     },
     eventDedup,
-    ...(options.auth && {
+    ...(effectiveAuth && {
       auth: {
         membershipQuery: TenantQueries.memberships,
         userQuery: UserQueries.findForAuth,
         loginHandler: AuthHandlers.login,
-        loginErrorStatusMap: options.auth.loginErrorStatusMap ?? {
+        loginErrorStatusMap: effectiveAuth.loginErrorStatusMap ?? {
           [AuthErrors.invalidCredentials]: 401,
           [AuthErrors.noMembership]: 403,
         },
-        ...(options.auth.cookieDomain !== undefined && {
-          cookieDomain: options.auth.cookieDomain,
+        ...(effectiveAuth.cookieDomain !== undefined && {
+          cookieDomain: effectiveAuth.cookieDomain,
         }),
-        ...(options.auth.allowedOrigins !== undefined && {
-          allowedOrigins: options.auth.allowedOrigins,
+        ...(effectiveAuth.allowedOrigins !== undefined && {
+          allowedOrigins: effectiveAuth.allowedOrigins,
         }),
-        ...(options.auth.unsafeSkipOriginCheck !== undefined && {
-          unsafeSkipOriginCheck: options.auth.unsafeSkipOriginCheck,
+        ...(effectiveAuth.unsafeSkipOriginCheck !== undefined && {
+          unsafeSkipOriginCheck: effectiveAuth.unsafeSkipOriginCheck,
         }),
         ...sessionAuthFragment,
-        ...(options.auth.passwordReset && {
+        ...(effectiveAuth.passwordReset && {
           passwordReset: {
             requestHandler: AuthHandlers.requestPasswordReset,
             confirmHandler: AuthHandlers.resetPassword,
-            sendResetEmail: options.auth.passwordReset.sendResetEmail,
-            appResetUrl: options.auth.passwordReset.appResetUrl,
+            sendResetEmail: effectiveAuth.passwordReset.sendResetEmail,
+            appResetUrl: effectiveAuth.passwordReset.appResetUrl,
           },
         }),
-        ...(options.auth.emailVerification && {
+        ...(effectiveAuth.emailVerification && {
           emailVerification: {
             requestHandler: AuthHandlers.requestEmailVerification,
             confirmHandler: AuthHandlers.verifyEmail,
-            sendVerificationEmail: options.auth.emailVerification.sendVerificationEmail,
-            appVerifyUrl: options.auth.emailVerification.appVerifyUrl,
+            sendVerificationEmail: effectiveAuth.emailVerification.sendVerificationEmail,
+            appVerifyUrl: effectiveAuth.emailVerification.appVerifyUrl,
           },
         }),
-        ...(options.auth.signup && {
+        ...(effectiveAuth.signup && {
           signup: {
             requestHandler: AuthHandlers.signupRequest,
             confirmHandler: AuthHandlers.signupConfirm,
-            sendActivationEmail: options.auth.signup.sendActivationEmail,
-            appActivationUrl: options.auth.signup.appActivationUrl,
+            sendActivationEmail: effectiveAuth.signup.sendActivationEmail,
+            appActivationUrl: effectiveAuth.signup.appActivationUrl,
           },
         }),
-        ...(options.auth.invite && {
+        ...(effectiveAuth.invite && {
           invite: {
             acceptHandler: AuthHandlers.inviteAccept,
             acceptWithLoginHandler: AuthHandlers.inviteAcceptWithLogin,
             signupCompleteHandler: AuthHandlers.inviteSignupComplete,
-            sendInviteEmail: options.auth.invite.sendInviteEmail,
-            appAcceptUrl: options.auth.invite.appAcceptUrl,
+            sendInviteEmail: effectiveAuth.invite.sendInviteEmail,
+            appAcceptUrl: effectiveAuth.invite.appAcceptUrl,
           },
         }),
       },
@@ -880,8 +1071,8 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   //    "first boot" via flag, every seed-step checks its own
   //    preconditions. Config-seeds rely on a deterministic
   //    aggregate-id so re-boot becomes a version_conflict skip.
-  if (options.auth) {
-    await seedAdmin(db, options.auth.admin);
+  if (effectiveAuth) {
+    await seedAdmin(db, effectiveAuth.admin);
   }
   await applyBootSeeds({ registry, db });
   for (const seed of options.seeds ?? []) {
@@ -1270,7 +1461,7 @@ export function staticCachePolicy(pathname: string): CachePolicy {
 
 function buildProdSessionAuth(
   db: import("@cosmicdrift/kumiko-framework/db").DbConnection,
-  opts: NonNullable<RunProdAppAuthOptions["sessions"]>,
+  opts: ProdSessionsConfig,
 ): {
   readonly sessionCreator: ReturnType<typeof createSessionCallbacks>["sessionCreator"];
   readonly sessionRevoker: ReturnType<typeof createSessionCallbacks>["sessionRevoker"];

package/src/session-wiring.ts

@@ -0,0 +1,29 @@
+/**
+ * runProdApp session-wiring decision (extracted pure so it is testable without a
+ * full prod boot).
+ *
+ * Secure-by-default: mounting the `sessions` feature turns server-side session
+ * revocation + sessionStrictMode ON automatically — there is no separate opt-in. The
+ * `auth.sessions` option only overrides the config, and `auth.sessions: false` is the
+ * explicit opt-out (back to stateless JWTs).
+ */
+
+export type ProdSessionsConfig = { readonly expiresInMs?: number };
+
+/** Config object to override defaults, or `false` to disable session wiring entirely. */
+export type ProdSessionsOption = ProdSessionsConfig | false;
+
+export function shouldWireProdSessions(
+  hasAuth: boolean,
+  sessionsFeatureMounted: boolean,
+  sessionsOption: ProdSessionsOption | undefined,
+): boolean {
+  return hasAuth && sessionsFeatureMounted && sessionsOption !== false;
+}
+
+/** The config passed to buildProdSessionAuth — `false`/absent collapse to defaults. */
+export function resolveProdSessionsConfig(
+  sessionsOption: ProdSessionsOption | undefined,
+): ProdSessionsConfig {
+  return sessionsOption || {};
+}