@cosmicdrift/kumiko-server-runtime 0.319.0 → 0.321.0

package/src/__tests__/run-prod-app.integration.test.ts

@@ -25,6 +25,7 @@ import {
   ExtraRouteRejection,
   isRedisSseBroker,
   NO_ROUTE_MATCH_HEADER_NAME,
+  requestContext,
   type SseEvent,
   signatureRoute,
 } from "@cosmicdrift/kumiko-framework/api";
@@ -92,6 +93,17 @@ const widgetFeature = defineFeature("prod-probe", (r) => {
     rateLimit: { per: "ip", limit: 60, windowSeconds: 60 },
     handler: async () => ({ pong: true }),
   });
+  // Echoes the resolved client IP — the only way to prove a real Bun.serve
+  // socket address reaches requestContext.ip end-to-end (fw#3260 addendum:
+  // every other test in this file drives fetchHandler directly, which never
+  // exercises server.requestIP()).
+  r.queryHandler({
+    name: "ip-probe",
+    schema: z.object({}),
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip", limit: 60, windowSeconds: 60 },
+    handler: async () => ({ ip: requestContext.get()?.ip }),
+  });
   r.queryHandler({
     name: "kms-probe",
     schema: z.object({}),
@@ -347,6 +359,27 @@ describe("runProdApp", () => {
     expect(body).toContain('<probe ok="true" />');
   });
 
+  test("handle.fetch threads the socket address into deps.clientIp, ignoring a spoofed X-Forwarded-For at the default trustedProxyHops (0)", async () => {
+    const handle = await boot(undefined, {
+      extraRoutes: [
+        {
+          method: "GET",
+          path: "/client-ip-probe",
+          entry: "anonymous",
+          handler: (c, deps) => c.body(deps.clientIp, 200),
+        },
+      ],
+    });
+    const req = () =>
+      new Request("http://test/client-ip-probe", { headers: { "x-forwarded-for": "1.2.3.4" } });
+
+    const withSocket = await handle.fetch(req(), "198.51.100.7");
+    expect(await withSocket.text()).toBe("198.51.100.7");
+
+    const withoutSocket = await handle.fetch(req());
+    expect(await withoutSocket.text()).toBe("unknown");
+  });
+
   test("extraRoutes: entry:signature dispatchSystemWrite schreibt als SystemAdmin des Ziel-Tenants, registry verfügbar", async () => {
     // Wiring for provider webhook routes (billing-foundation
     // createSubscriptionWebhookRoute): the route authenticates via
@@ -691,9 +724,10 @@ describe("runProdApp", () => {
   });
 
   test("hostDispatch: per-host html-Datei + Schema-Gating", async () => {
-    // Multi-App-Deployment: zwei HTML-Dateien für unterschiedliche
-    // Hosts. Schema wird NUR für admin-Host injected — Public-Host
-    // bekommt das pure HTML ohne __KUMIKO_SCHEMA__ Tag (Sicherheit).
+    // Multi-app deployment: two HTML files for different hosts. Neither
+    // ever carries __KUMIKO_SCHEMA__ (kumiko-framework#3314) —
+    // createKumikoApp fetches the schema itself from GET /api/schema
+    // after the auth gates let it through, regardless of host.
     const tmpStaticDir = await createTempStaticDir({
       "index.html": "<html><body>PUBLIC</body><script src=/client.js></script></html>",
       "admin.html": "<html><body>ADMIN</body><script src=/client.js></script></html>",
@@ -703,13 +737,12 @@ describe("runProdApp", () => {
       staticDir: tmpStaticDir,
       hostDispatch: ({ host }) => {
         if (host.startsWith("admin.")) {
-          return { kind: "html", file: "admin.html", injectSchema: true };
+          return { kind: "html", file: "admin.html" };
         }
-        return { kind: "html", file: "index.html", injectSchema: false };
+        return { kind: "html", file: "index.html" };
       },
     });
 
-    // Public host: index.html, KEIN schema-Tag.
     const pubRes = await handle.fetch(
       new Request("http://demo.example.test/", { headers: { host: "demo.example.test" } }),
     );
@@ -718,57 +751,107 @@ describe("runProdApp", () => {
     expect(pubBody).toContain("PUBLIC");
     expect(pubBody).not.toContain("__KUMIKO_SCHEMA__");
 
-    // Admin host: admin.html MIT schema-Tag.
     const adminRes = await handle.fetch(
       new Request("http://admin.example.test/", { headers: { host: "admin.example.test" } }),
     );
     expect(adminRes.status).toBe(200);
     const adminBody = await adminRes.text();
     expect(adminBody).toContain("ADMIN");
-    expect(adminBody).toContain("__KUMIKO_SCHEMA__");
-
-    // #2062: this boot()'s widgetFeature never wires extraContext.searchAdapter,
-    // so run-prod-app's `searchAdapterMissing = !(extraContext).searchAdapter`
-    // must actually flip true and flow into the injected schema — proving
-    // the cast-boundary read isn't silently always-false.
-    const schemaMatch = adminBody.match(/window\.__KUMIKO_SCHEMA__=(\{.*?\});<\/script>/s);
-    expect(schemaMatch).not.toBeNull();
-    const injectedSchema = JSON.parse(schemaMatch?.[1] ?? "{}");
-    // Guards against a regex miss silently degrading to `?? "{}"` — an empty
-    // features array would make `.every(...)` below vacuously true too.
-    expect(injectedSchema.features.length).toBeGreaterThan(0);
-    const allFeaturesMissingAdapter = injectedSchema.features.every(
-      (f: { searchAdapterMissing?: boolean }) => f.searchAdapterMissing === true,
-    );
-    expect(allFeaturesMissingAdapter).toBe(true);
+    expect(adminBody).not.toContain("__KUMIKO_SCHEMA__");
   });
 
-  test("extraContext.searchAdapter wired → injected schema omits searchAdapterMissing (#2062)", async () => {
+  test("staticDir without hostDispatch: HTML never carries the schema; GET /api/schema needs a signed-in user (kumiko-framework#3314)", async () => {
+    // A real POST /api/auth/login round-trip needs the tenant/user bundled
+    // features' own projection tables (e.g. read_tenants), which this
+    // suite's boot() doesn't migrate (migrations: false, only the app's own
+    // entity tables are auto-created — see unsafeEnsureEntityTable above).
+    // Signing a token straight through the entrypoint's JwtHelper exercises
+    // the exact same cookie transport auth-middleware reads, without
+    // pulling in that migration surface just for this schema-fetch test.
     const tmpStaticDir = await createTempStaticDir({
-      "index.html": "<html><body>ADMIN</body><script src=/client.js></script></html>",
+      "index.html": "<html><body>SHELL</body><script src=/client.js></script></html>",
+    });
+
+    const handle = await boot(undefined, { staticDir: tmpStaticDir });
+
+    const rootRes = await handle.fetch(new Request("http://test/"));
+    expect(rootRes.status).toBe(200);
+    expect(await rootRes.text()).not.toContain("__KUMIKO_SCHEMA__");
+
+    const spaRes = await handle.fetch(new Request("http://test/some/spa/route"));
+    expect(spaRes.status).toBe(200);
+    expect(await spaRes.text()).not.toContain("__KUMIKO_SCHEMA__");
+
+    const anonSchemaRes = await handle.fetch(new Request("http://test/api/schema"));
+    expect(anonSchemaRes.status).toBe(401);
+
+    const token = await handle.entrypoint.jwt.sign({
+      id: "schema-fetch-user",
+      tenantId: TENANT_ID as import("@cosmicdrift/kumiko-framework/engine").TenantId,
+      roles: ["User"],
     });
+    const schemaRes = await handle.fetch(
+      new Request("http://test/api/schema", { headers: { Cookie: `kumiko_auth=${token}` } }),
+    );
+    expect(schemaRes.status).toBe(200);
+    const schema = (await schemaRes.json()) as { features: readonly unknown[] };
+    expect(schema.features.length).toBeGreaterThan(0);
+  });
 
+  test("anonymousAccess wired → GET /api/schema still 401s for the synthesised anonymous user", async () => {
+    const handle = await boot(undefined, {
+      anonymousAccess: {
+        defaultTenantId: TENANT_ID as import("@cosmicdrift/kumiko-framework/engine").TenantId,
+      },
+    });
+
+    const res = await handle.entrypoint.app.fetch(new Request("http://test/api/schema"));
+    expect(res.status).toBe(401);
+  });
+
+  test("extraContext.searchAdapter absent → GET /api/schema marks every feature searchAdapterMissing (#2062)", async () => {
+    const handle = await boot();
+    const token = await handle.entrypoint.jwt.sign({
+      id: "schema-probe-user",
+      tenantId: TENANT_ID as import("@cosmicdrift/kumiko-framework/engine").TenantId,
+      roles: ["User"],
+    });
+
+    const res = await handle.entrypoint.app.fetch(
+      new Request("http://test/api/schema", { headers: { Authorization: `Bearer ${token}` } }),
+    );
+    expect(res.status).toBe(200);
+    const schema = (await res.json()) as {
+      features: ReadonlyArray<{ searchAdapterMissing?: boolean }>;
+    };
+    // Guards against a vacuous pass — an empty features array would make
+    // `.every(...)` below vacuously true too.
+    expect(schema.features.length).toBeGreaterThan(0);
+    expect(schema.features.every((f) => f.searchAdapterMissing === true)).toBe(true);
+  });
+
+  test("extraContext.searchAdapter wired → GET /api/schema omits searchAdapterMissing (#2062)", async () => {
     const handle = await boot(undefined, {
-      staticDir: tmpStaticDir,
       // Presence-only probe — run-prod-app's cast-boundary read only checks
       // truthiness, so a minimal stand-in is enough without pulling in the
       // real SearchAdapter shape.
       extraContext: { searchAdapter: { configure: async () => {}, search: async () => [] } },
-      hostDispatch: () => ({ kind: "html", file: "index.html", injectSchema: true }),
+    });
+    const token = await handle.entrypoint.jwt.sign({
+      id: "schema-probe-user",
+      tenantId: TENANT_ID as import("@cosmicdrift/kumiko-framework/engine").TenantId,
+      roles: ["User"],
     });
 
-    const res = await handle.fetch(new Request("http://demo.example.test/"));
-    const body = await res.text();
-    const schemaMatch = body.match(/window\.__KUMIKO_SCHEMA__=(\{.*?\});<\/script>/s);
-    expect(schemaMatch).not.toBeNull();
-    const injectedSchema = JSON.parse(schemaMatch?.[1] ?? "{}");
-    // Guards against a regex miss silently degrading to `?? "{}"` — an empty
-    // features array would make `.some(...)` below vacuously false too.
-    expect(injectedSchema.features.length).toBeGreaterThan(0);
-    const anyFeatureMissingAdapter = injectedSchema.features.some(
-      (f: { searchAdapterMissing?: boolean }) => f.searchAdapterMissing === true,
+    const res = await handle.entrypoint.app.fetch(
+      new Request("http://test/api/schema", { headers: { Authorization: `Bearer ${token}` } }),
     );
-    expect(anyFeatureMissingAdapter).toBe(false);
+    expect(res.status).toBe(200);
+    const schema = (await res.json()) as {
+      features: ReadonlyArray<{ searchAdapterMissing?: boolean }>;
+    };
+    expect(schema.features.length).toBeGreaterThan(0);
+    expect(schema.features.some((f) => f.searchAdapterMissing === true)).toBe(false);
   });
 
   test("hostDispatch: redirect-Modus", async () => {
@@ -983,6 +1066,37 @@ describe("runProdApp", () => {
   });
 });
 
+describe("runProdApp — real Bun.serve socket resolves the client IP (fw#3260 addendum)", () => {
+  // Every other test in this file drives handle.fetch()/entrypoint.app.fetch()
+  // directly, which never goes through Bun.serve's real TCP socket — so none
+  // of them can catch a regression where the socket address gets lost before
+  // reaching requestContext.ip (see client-ip.ts: falls back to "unknown"
+  // rather than throwing, so a wiring bug here stays silent otherwise).
+  test("a real loopback connection resolves to the actual socket address, not 'unknown'", async () => {
+    const handle = await boot(undefined, {
+      autoListen: true,
+      anonymousAccess: { defaultTenantId: TENANT_ID },
+    });
+    const port = handle.server?.port;
+    if (port === undefined) throw new Error("expected handle.server to be listening");
+
+    const res = await fetch(`http://127.0.0.1:${port}/api/query`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ type: "prod-probe:query:ip-probe", payload: {} }),
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { data?: { ip?: string } };
+    // Exact loopback notation (bare "127.0.0.1" vs. the IPv4-mapped IPv6
+    // form "::ffff:127.0.0.1") depends on the platform's dual-stack
+    // listener behavior, not on the code under test — matching the
+    // family instead of a fixed literal keeps the assertion about what
+    // this test actually proves: a real socket address reached
+    // requestContext.ip instead of the "unknown" fallback.
+    expect(body.data?.ip).toMatch(/^(::ffff:)?127\.0\.0\.1$/);
+  });
+});
+
 describe("runProdApp: lokaler Event-Dispatcher (MSP-Anwendung im Single-Container)", () => {
   // Regression für den 2026-06-11-Incident: runProdApp baute den
   // Event-Dispatcher nie ({disabled:true} im API-Entrypoint) — jede
@@ -1238,6 +1352,13 @@ describe("runProdApp job-lane wiring (runSingleInstance)", () => {
     const handle = await boot(undefined, {
       rateLimit: { global: { limit: 1, windowSeconds: 60 } },
       anonymousAccess: { defaultTenantId: TENANT_ID },
+      // handle.entrypoint.app.fetch has no real socket, and the client-ip
+      // resolver ignores X-Forwarded-For without a trusted hop — without
+      // this, every call below (and every other untrusted-XFF call this
+      // suite makes) resolves to the same shared "unknown" bucket, so the
+      // probeIp uniqueness below is silently defeated by whichever test
+      // happens to run first.
+      trustedProxyHops: 1,
     });
 
     // Unique per test run: the L1 limiter's Redis bucket is keyed only on

package/src/bun-serve-options.ts

@@ -1,3 +1,31 @@
+import { DEFAULT_MAX_REQUEST_BYTES } from "@cosmicdrift/kumiko-framework/api";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine/types";
+import {
+  readFilesRouteOptions,
+  resolveMaxUploadBodyBytes,
+} from "@cosmicdrift/kumiko-framework/files";
+
+// Fallback for callers that skip resolveDerivedMaxRequestBodySize below —
+// Bun's own default is 128 MiB, buffered per request before any app-level
+// body-limit middleware runs.
+export const DEFAULT_MAX_REQUEST_BODY_SIZE_BYTES = 32 * 1024 * 1024;
+
+// Keeps Bun's cap above the files route's own derived bodyLimit, so that
+// route's JSON 413 fires before Bun's bare rejection would.
+const BUN_BODY_LIMIT_SAFETY_MARGIN_BYTES = 8 * 1024;
+
+// Derives Bun's request-body ceiling from the same registry-configured
+// maxUploadSize/field maxSize the upload route itself enforces.
+export function resolveDerivedMaxRequestBodySize(registry: Registry): number {
+  const filesRouteOptions = readFilesRouteOptions(registry);
+  return (
+    Math.max(
+      DEFAULT_MAX_REQUEST_BYTES,
+      resolveMaxUploadBodyBytes({ registry, maxUploadSize: filesRouteOptions.maxUploadSize }),
+    ) + BUN_BODY_LIMIT_SAFETY_MARGIN_BYTES
+  );
+}
+
 /**
  * Bun.serve-Options für Production.
  *
@@ -12,11 +40,21 @@
  */
 export function buildBunServeOptions(
   port: number,
-  fetchHandler: (req: Request) => Response | Promise<Response>,
+  fetchHandler: (req: Request, socketAddress?: string) => Response | Promise<Response>,
+  maxRequestBodySize: number = DEFAULT_MAX_REQUEST_BODY_SIZE_BYTES,
 ): {
   readonly port: number;
-  readonly fetch: (req: Request) => Response | Promise<Response>;
+  readonly fetch: (req: Request, server: Bun.Server<unknown>) => Response | Promise<Response>;
   readonly idleTimeout: number;
+  readonly maxRequestBodySize: number;
 } {
-  return { port, fetch: fetchHandler, idleTimeout: 0 };
+  // `server.requestIP(req)` only resolves for the exact Request instance
+  // Bun created — extracted here, once, before any downstream req.clone()
+  // (tryHonoFirst et al.) can invalidate it.
+  return {
+    port,
+    fetch: (req, server) => fetchHandler(req, server.requestIP(req)?.address),
+    idleTimeout: 0,
+    maxRequestBodySize,
+  };
 }

package/src/changes.json

@@ -1,4 +1,43 @@
 [
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "runProdApp's KUMIKO_TRUSTED_PROXY_HOPS parsing now shares framework's parseTrustedProxyHopsEnv",
+    "detail": "The inline digits-only + non-negative-integer validation moved out of\n`run-prod-app.ts` into `parseTrustedProxyHopsEnv`\n(`@cosmicdrift/kumiko-framework/api`); same validation and error message\nas before, no behavioral change.",
+    "migration": "No action needed."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "ProdAppHandle.fetch's type now declares its optional socket-address parameter",
+    "detail": "`fetch: (req: Request, socketAddress?: string) => Promise<Response> |\nResponse`. The doc comment now explains that an app with `autoListen:\nfalse` running its own `Bun.serve` must pass\n`server.requestIP(req)?.address`, extracted at the outermost Bun fetch\ncallback — `requestIP()` only resolves for Bun's original Request\ninstance, not a cloned/rebuilt one. `RunProdAppAuthOptions\n.trustedProxyHops`'s doc comment also dropped the stale \"pre-#1539\nspoofable default\" wording; 0 hops is the safe socket-only default.",
+    "migration": "No action needed for the default `autoListen: true` boot. Apps with\n`autoListen: false` can now type-check passing the socket address to\n`handle.fetch`; passing nothing keeps the previous (unresolved) behavior."
+  },
+  {
+    "version": "0.320.0",
+    "type": "breaking",
+    "title": "runProdApp threads the Bun socket address and a trustedProxyHops option through to the client-IP resolver",
+    "detail": "`buildBunServeOptions` now extracts the client socket address once via\n`server.requestIP(req)` at the outermost Bun.serve fetch callback (a\ncloned/rebuilt Request loses that ability) and threads it through\n`tryHonoFirst`/`withSecurityHeaders`/`buildStaticFallback` as Hono's\n`env`. `RunProdAppOptions` gained a top-level `trustedProxyHops` (falls\nback to the deprecated `auth.trustedProxyHops`, then\n`KUMIKO_TRUSTED_PROXY_HOPS`), forwarded into `buildServer` and the\nstatic-fallback's own client-IP resolver.",
+    "migration": "Same as the framework entry — set `trustedProxyHops` on `runProdApp` when\ndeployed behind a reverse-proxy/ingress."
+  },
+  {
+    "version": "0.320.0",
+    "type": "breaking",
+    "title": "Static fallback no longer injects __KUMIKO_SCHEMA__ into HTML",
+    "migration": "`HostDispatchResult.injectSchema` is deprecated and ignored — HTML never\ncarries the schema anymore, in prod or dev. `createKumikoApp` now fetches\nthe schema itself from the authenticated `GET /api/schema` after its\nclientFeature gates (e.g. an auth gate) let rendering through, so a\nsigned-in admin app keeps working without changes. Anything that read\n`window.__KUMIKO_SCHEMA__` directly (custom clients, e2e fixtures) must\nswitch to fetching `/api/schema` instead. An anonymously reachable page\nthat used to render schema-based screens needs `createPublicSurface`,\nwhich never carries a schema. The `@cosmicdrift/kumiko-server-runtime/inject-schema`\nsubpath export is removed."
+  },
+  {
+    "version": "0.320.0",
+    "type": "improvement",
+    "title": "requireEnv is now part of the public package export",
+    "detail": "`packages/server-runtime/src/index.ts` now re-exports `requireEnv`\nalongside `runProdApp`, so `import { requireEnv } from\n\"@cosmicdrift/kumiko-server-runtime\"` resolves without reaching into the\ninternal `run-prod-app.ts` module."
+  },
+  {
+    "version": "0.320.0",
+    "type": "improvement",
+    "title": "resolveAuthMail builds locale-aware appUrls and adds a dedicated auth.mail.hmacSecret",
+    "detail": "resolveAuthMail (shared by runProdApp and runDevApp) now builds the passwordReset/emailVerification/signup/invite appUrl from a locale-aware AuthPath, so a function-valued auth.mail.paths entry produces a locale-aware appUrl for every flow, symmetric to the appUrl-as-function support each flow's options already had.\nAuthMailOptions also gains an optional hmacSecret: when set, passwordReset/emailVerification tokens sign with it instead of the hmacSecret resolveAuthMail is called with (JWT_SECRET), so JWT_SECRET can rotate without invalidating in-flight reset/verify tokens. hmacSecret is now optional on the passwordReset/emailVerification wrapper options too — an app overriding just appUrl no longer has to also thread its own secret; resolveAuthMail backfills the resolved secret onto that explicit block. An explicitly supplied hmacSecret still wins."
+  },
   {
     "version": "0.298.0",
     "type": "breaking",

package/src/compose-features.ts

@@ -110,8 +110,8 @@ export function composeFeatures(
 }
 
 /** Shape of any run{Prod,Dev}App auth block that can carry a
- *  passwordReset/emailVerification config. The wrapper API
- *  (PasswordResetSetup) extends the feature API (PasswordResetOptions), so
+ *  passwordReset/emailVerification config, once resolveAuthMail has resolved
+ *  the wrapper's optional hmacSecret into the feature API's required one —
  *  a structural-typed lookup on the auth-only subset is enough. Lets
  *  buildComposeAuthOptions be called with both RunProd- and
  *  RunDev-AuthOptions without building the helper twice. */

package/src/index.ts

@@ -17,7 +17,7 @@ export type {
   RunProdAppOptions,
   SignupSetup,
 } from "./run-prod-app";
-export { runProdApp } from "./run-prod-app";
+export { requireEnv, runProdApp } from "./run-prod-app";
 export type {
   RunWorkerAppOptions,
   WorkerAppHandle,

package/src/run-prod-app-boot-context.ts

@@ -2,7 +2,12 @@ import {
   AUDIT_FEATURE,
   createEscapeHatchAuditSink,
 } from "@cosmicdrift/kumiko-bundled-features/audit";
-import { makeAuthPaths } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import {
+  type AuthPath,
+  type EmailVerificationOptions,
+  makeAuthPaths,
+  type PasswordResetOptions,
+} from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
 import { resolveSessionStore } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import {
   bindMfaRevokeAllOtherSessionsFromFeature,
@@ -182,18 +187,53 @@ type AuthMailNormalizable = {
   readonly invite?: InviteSetup;
 };
 
+function buildAuthPathAppUrl(
+  baseUrl: string,
+  path: AuthPath,
+): string | ((locale: string) => string) {
+  return typeof path === "function"
+    ? (locale: string) => `${baseUrl}${path(locale)}`
+    : `${baseUrl}${path}`;
+}
+
 // accountUnlock (#1266) deliberately does NOT join this convenience block —
 // unlike reset/verify/signup/invite it's only meaningful paired with
 // `accountLockout` (kumiko-framework#1627), and apps set both explicitly
 // alongside each other (same shape as `passwordReset`), so `mail` alone
 // can't silently expose a new public endpoint an app didn't ask for.
 
+function backfillTokenSecrets<T extends AuthMailNormalizable>(auth: T, tokenSecret: string) {
+  return {
+    ...auth,
+    ...(auth.passwordReset && {
+      passwordReset: {
+        ...auth.passwordReset,
+        hmacSecret: auth.passwordReset.hmacSecret ?? tokenSecret,
+      },
+    }),
+    ...(auth.emailVerification && {
+      emailVerification: {
+        ...auth.emailVerification,
+        hmacSecret: auth.emailVerification.hmacSecret ?? tokenSecret,
+      },
+    }),
+  };
+}
+
 export function resolveAuthMail<T extends AuthMailNormalizable>(
   auth: T,
   hmacSecret: string,
   envSource: Record<string, string | undefined>,
-): T {
-  if (!auth.mail) return auth;
+): T & {
+  readonly passwordReset?: PasswordResetOptions;
+  readonly emailVerification?: EmailVerificationOptions;
+} {
+  // Runs before the mail/SMTP guards below so an app-supplied block without
+  // hmacSecret is backfilled even without a `mail` block; an explicit secret still wins.
+  const tokenSecret = auth.mail?.hmacSecret ?? hmacSecret;
+  const withResolvedSecrets = backfillTokenSecrets(auth, tokenSecret);
+
+  if (!auth.mail) return withResolvedSecrets;
   // SMTP-presence gate: ohne SMTP_HOST-env wird KEIN Flow verdrahtet (Routes
   // blieben sonst 500). Der eigentliche Mail-Versand läuft über delivery
   // (channel-email), nicht über diesen Transport — er ist nur der Detektor
@@ -201,7 +241,7 @@ export function resolveAuthMail<T extends AuthMailNormalizable>(
   if (
     !createSmtpTransportFromEnv(envSource, { fallbackFrom: auth.mail.from ?? "noreply@localhost" })
   ) {
-    return auth;
+    return withResolvedSecrets;
   }
   const paths = makeAuthPaths(auth.mail.paths);
   // appName/locale fließen in alle vier Flow-Options (alle mailen via delivery).
@@ -210,26 +250,26 @@ export function resolveAuthMail<T extends AuthMailNormalizable>(
     ...(auth.mail.locale !== undefined && { locale: auth.mail.locale }),
   };
   return {
-    ...auth,
-    passwordReset: auth.passwordReset ?? {
-      hmacSecret,
-      appUrl: `${auth.mail.baseUrl}${paths.resetPassword}`,
+    ...withResolvedSecrets,
+    passwordReset: withResolvedSecrets.passwordReset ?? {
+      hmacSecret: tokenSecret,
+      appUrl: buildAuthPathAppUrl(auth.mail.baseUrl, paths.resetPassword),
       ...mailPresentation,
     },
-    emailVerification: auth.emailVerification ?? {
-      hmacSecret,
-      appUrl: `${auth.mail.baseUrl}${paths.verifyEmail}`,
+    emailVerification: withResolvedSecrets.emailVerification ?? {
+      hmacSecret: tokenSecret,
+      appUrl: buildAuthPathAppUrl(auth.mail.baseUrl, paths.verifyEmail),
       ...(auth.mail.emailVerificationMode !== undefined && {
         mode: auth.mail.emailVerificationMode,
       }),
       ...mailPresentation,
     },
-    signup: auth.signup ?? {
-      appUrl: `${auth.mail.baseUrl}${paths.signupComplete}`,
+    signup: withResolvedSecrets.signup ?? {
+      appUrl: buildAuthPathAppUrl(auth.mail.baseUrl, paths.signupComplete),
       ...mailPresentation,
     },
-    invite: auth.invite ?? {
-      appUrl: `${auth.mail.baseUrl}${paths.inviteAccept}`,
+    invite: withResolvedSecrets.invite ?? {
+      appUrl: buildAuthPathAppUrl(auth.mail.baseUrl, paths.inviteAccept),
       ...mailPresentation,
     },
   };