@cosmicdrift/kumiko-bundled-features 0.159.1 → 0.161.0

package/src/auth-foundation/boot-checks.ts

@@ -13,9 +13,13 @@
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import {
   EXT_SESSION_STORE,
+  EXT_TENANT_EXISTENCE,
+  EXT_TENANT_RESOLVER,
   EXT_TOKEN_VERIFIER,
   isAuthProviderPlugin,
   isSessionStoreProvider,
+  isTenantExistenceProvider,
+  isTenantResolverProvider,
   tokenShapeKey,
 } from "./types";
 
@@ -89,3 +93,53 @@ export function validateSessionStoreMultiplicity(features: readonly FeatureDefin
     );
   }
 }
+
+// Optional single-provider (#1373). Zero registrations = OK (single-tenant /
+// header-cookie path). ≥2 or malformed = boot fail.
+export function validateTenantResolverMultiplicity(features: readonly FeatureDefinition[]): void {
+  const names: string[] = [];
+
+  for (const feature of features) {
+    for (const usage of feature.extensionUsages) {
+      if (usage.extensionName !== EXT_TENANT_RESOLVER) continue;
+      if (!isTenantResolverProvider(usage.options)) {
+        throw new Error(
+          `[auth-foundation] tenantResolver provider "${usage.entityName}" (feature "${feature.name}") ` +
+            `registered without a valid TenantResolverProvider — options must have { trust, build }.`,
+        );
+      }
+      names.push(usage.entityName);
+    }
+  }
+
+  if (names.length >= 2) {
+    throw new Error(
+      `[auth-foundation] ${names.length} tenantResolver providers registered (${names.join(", ")}) — ` +
+        `only one tenantResolver provider may be mounted at a time.`,
+    );
+  }
+}
+
+export function validateTenantExistenceMultiplicity(features: readonly FeatureDefinition[]): void {
+  const names: string[] = [];
+
+  for (const feature of features) {
+    for (const usage of feature.extensionUsages) {
+      if (usage.extensionName !== EXT_TENANT_EXISTENCE) continue;
+      if (!isTenantExistenceProvider(usage.options)) {
+        throw new Error(
+          `[auth-foundation] tenantExistence provider "${usage.entityName}" (feature "${feature.name}") ` +
+            `registered without a valid TenantExistenceProvider — options must have a { build } shape.`,
+        );
+      }
+      names.push(usage.entityName);
+    }
+  }
+
+  if (names.length >= 2) {
+    throw new Error(
+      `[auth-foundation] ${names.length} tenantExistence providers registered (${names.join(", ")}) — ` +
+        `only one tenantExistence provider may be mounted at a time.`,
+    );
+  }
+}

package/src/auth-foundation/feature.ts

@@ -1,41 +1,52 @@
 // kumiko-feature-version: 1
 //
-// auth-foundation — declares the `tokenVerifier` extension point for Bearer-
-// token verification. Provider-features (auth-provider-jwt, auth-provider-
-// pat, ...) register via `r.useExtension(EXT_TOKEN_VERIFIER, "<name>", plugin)`.
+// auth-foundation — declares auth-middleware extension points:
+//   - tokenVerifier (multi, shape-routed)
+//   - sessionStore (single, required when foundation mounts)
+//   - tenantResolver (single, optional)
+//   - tenantExistence (single, optional)
 //
-// **Scaffold only:** not wired into `api/auth-middleware.ts` yet —
-// personal-access-tokens still uses its own direct `patResolver` callback
-// (kumiko-framework#745). A future issue migrates the middleware onto this
-// extension point; #1368 only lays the groundwork (PAT-Plan-Doc Phase-1-
-// Sub-Step-1).
-//
-// **Pattern precedent:** file-foundation/mail-foundation for the extension-
-// point + plugin-registry shape. Diverges on ROUTING: those pick one active
-// provider per tenant via a config-key; auth-foundation has no tenant yet
-// at verify-time, so providers are tried in shape-match order instead (see
-// types.ts).
+// Provider-features register via `r.useExtension(EXT_*, "<name>", plugin)`.
+// Middleware / runProdApp resolve providers from the registry at boot
+// (tokenVerifier/sessionStore) or request-time (tokenVerifier shape match).
 
 import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
 import { defineFeature, type Registry } from "@cosmicdrift/kumiko-framework/engine";
-import { validateSessionStoreMultiplicity, validateTokenVerifierMultiplicity } from "./boot-checks";
+import {
+  validateSessionStoreMultiplicity,
+  validateTenantExistenceMultiplicity,
+  validateTenantResolverMultiplicity,
+  validateTokenVerifierMultiplicity,
+} from "./boot-checks";
 import {
   type AuthProviderBuildDeps,
   EXT_SESSION_STORE,
+  EXT_TENANT_EXISTENCE,
+  EXT_TENANT_RESOLVER,
   EXT_TOKEN_VERIFIER,
   isAuthProviderPlugin,
   isSessionStoreProvider,
+  isTenantExistenceProvider,
+  isTenantResolverProvider,
   type SessionStore,
+  type TenantExistsFn,
+  type TenantResolverFn,
+  type TenantResolverTrust,
   tokenShapeMatches,
 } from "./types";
 
-export { EXT_SESSION_STORE, EXT_TOKEN_VERIFIER } from "./types";
+export {
+  EXT_SESSION_STORE,
+  EXT_TENANT_EXISTENCE,
+  EXT_TENANT_RESOLVER,
+  EXT_TOKEN_VERIFIER,
+} from "./types";
 
 const FEATURE_NAME = "auth-foundation";
 
 export const authFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
   r.describe(
-    "Declares the `tokenVerifier` (Bearer-token auth) and `sessionStore` extension points. Provider-features register a static `shape` plus a `build()` for tokenVerifier — mount together with at least one auth-provider-* feature (e.g. personal-access-tokens) and call `resolveTokenVerifier(deps, rawToken)` to find the matching one; sessions self-registers as the single sessionStore provider.",
+    "Declares auth-middleware extension points: `tokenVerifier` (Bearer), `sessionStore` (revocable JWT sid), optional `tenantResolver` + `tenantExistence` for anonymous multi-tenant. Provider-features register via r.useExtension; mount auth-foundation with the matching provider features.",
   );
   r.uiHints({
     displayLabel: "Auth Provider Foundation",
@@ -49,19 +60,28 @@ export const authFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
       // resolveTokenVerifier looks it up at request-time.
     },
   });
-
-  // Owns EXT_TOKEN_VERIFIER, so its own mount is the trigger — same
-  // convention as tenant-lifecycle/user-data-rights' self-bootCheck.
   r.bootCheck(({ features }) => validateTokenVerifierMultiplicity(features));
 
   r.extendsRegistrar(EXT_SESSION_STORE, {
     onRegister: () => {
-      // No side-effects at register-time — registry stores the usage,
-      // resolveSessionStore looks it up at request-time.
+      // No side-effects at register-time — resolveSessionStore at boot/request.
     },
   });
-
   r.bootCheck(({ features }) => validateSessionStoreMultiplicity(features));
+
+  r.extendsRegistrar(EXT_TENANT_RESOLVER, {
+    onRegister: () => {
+      // Optional — zero providers is fine (single-tenant / header-cookie).
+    },
+  });
+  r.bootCheck(({ features }) => validateTenantResolverMultiplicity(features));
+
+  r.extendsRegistrar(EXT_TENANT_EXISTENCE, {
+    onRegister: () => {
+      // Optional — zero providers skips the existence check.
+    },
+  });
+  r.bootCheck(({ features }) => validateTenantExistenceMultiplicity(features));
 });
 
 /**
@@ -101,3 +121,37 @@ export async function resolveSessionStore(
   }
   return usage.options.build(deps);
 }
+
+export type ResolvedTenantResolver = {
+  readonly resolve: TenantResolverFn;
+  readonly trust: TenantResolverTrust;
+};
+
+/** Optional tenantResolver — null when no provider registered. */
+export async function resolveTenantResolver(
+  deps: AuthProviderBuildDeps & { readonly registry: Registry },
+): Promise<ResolvedTenantResolver | null> {
+  const usage = deps.registry.getExtensionUsages(EXT_TENANT_RESOLVER)[0];
+  if (!usage) return null;
+  if (!isTenantResolverProvider(usage.options)) {
+    throw new Error(
+      "[auth-foundation] tenantResolver provider registered without a valid TenantResolverProvider",
+    );
+  }
+  const resolve = await usage.options.build(deps);
+  return { resolve, trust: usage.options.trust };
+}
+
+/** Optional tenantExistence — null when no provider registered. */
+export async function resolveTenantExistence(
+  deps: AuthProviderBuildDeps & { readonly registry: Registry },
+): Promise<TenantExistsFn | null> {
+  const usage = deps.registry.getExtensionUsages(EXT_TENANT_EXISTENCE)[0];
+  if (!usage) return null;
+  if (!isTenantExistenceProvider(usage.options)) {
+    throw new Error(
+      "[auth-foundation] tenantExistence provider registered without a valid TenantExistenceProvider",
+    );
+  }
+  return usage.options.build(deps);
+}

package/src/auth-foundation/index.ts

@@ -2,21 +2,35 @@
 
 export {
   authFoundationFeature,
+  type ResolvedTenantResolver,
   resolveSessionStore,
+  resolveTenantExistence,
+  resolveTenantResolver,
   resolveTokenVerifier,
 } from "./feature";
+export { resolveAnonymousAccessFromRegistry } from "./resolve-anonymous-access";
 export {
   type AuthProviderBuildDeps,
   type AuthProviderPlugin,
   type AuthVerifier,
   EXT_SESSION_STORE,
+  EXT_TENANT_EXISTENCE,
+  EXT_TENANT_RESOLVER,
   EXT_TOKEN_VERIFIER,
   isAuthProviderPlugin,
   isSessionStoreProvider,
+  isTenantExistenceProvider,
+  isTenantResolverProvider,
+  isTenantResolverTrust,
   isValidTokenShape,
   type SessionMassRevoker,
   type SessionStore,
   type SessionStoreProvider,
+  type TenantExistenceProvider,
+  type TenantExistsFn,
+  type TenantResolverFn,
+  type TenantResolverProvider,
+  type TenantResolverTrust,
   type TokenShape,
   tokenShapeKey,
   tokenShapeMatches,

package/src/auth-foundation/resolve-anonymous-access.ts

@@ -0,0 +1,54 @@
+/**
+ * Merge app-facing AnonymousAccessConfig with auth-foundation tenant providers.
+ * Providers win over any leftover callback fields (hard cutover #1374).
+ * Test stacks may still pass Resolved callbacks when no provider is mounted.
+ */
+import type {
+  AnonymousAccessConfig,
+  AnonymousAccessResolved,
+  TenantExists,
+  TenantResolver,
+} from "@cosmicdrift/kumiko-framework/api";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { resolveTenantExistence, resolveTenantResolver } from "./feature";
+import type { AuthProviderBuildDeps } from "./types";
+
+export async function resolveAnonymousAccessFromRegistry(
+  base: AnonymousAccessResolved | AnonymousAccessConfig | undefined,
+  deps: AuthProviderBuildDeps & { readonly registry: Registry },
+): Promise<AnonymousAccessResolved | undefined> {
+  const [tenantResolver, tenantExists] = await Promise.all([
+    resolveTenantResolver(deps),
+    resolveTenantExistence(deps),
+  ]);
+
+  if (!base && !tenantResolver && !tenantExists) return undefined;
+
+  // Fail-closed (#1374 security): inline tenantResolver without trust is the
+  // old ambiguous config — providers always carry trust; test stacks must too.
+  if (
+    !tenantResolver &&
+    base &&
+    "tenantResolver" in base &&
+    base.tenantResolver !== undefined &&
+    base.resolverTrust === undefined
+  ) {
+    throw new Error(
+      "[auth-foundation] anonymousAccess.tenantResolver is set without resolverTrust — " +
+        'declare "authoritative" or "fallback-only" (or mount an EXT_TENANT_RESOLVER provider).',
+    );
+  }
+
+  // Providers win (#1374). When none are mounted, keep any test-injected
+  // Resolved callbacks so framework middleware suites stay self-contained.
+  return {
+    ...(base ?? {}),
+    ...(tenantResolver
+      ? {
+          tenantResolver: tenantResolver.resolve as TenantResolver,
+          resolverTrust: tenantResolver.trust,
+        }
+      : {}),
+    ...(tenantExists ? { tenantExists: tenantExists as TenantExists } : {}),
+  };
+}

package/src/auth-foundation/types.ts

@@ -86,11 +86,18 @@ export const EXT_SESSION_STORE = "sessionStore";
 /** Mass-revoke every live session for a user. Used by password-change and "sign out everywhere". */
 export type SessionMassRevoker = (userId: string) => Promise<number>;
 
+/** Keep current sid (if any); revoke every other live session. Used by auth-mfa. */
+export type SessionRevokeAllOthers = (
+  userId: string,
+  currentSid: string | undefined,
+) => Promise<number>;
+
 export type SessionStore = {
   readonly creator: SessionCreator;
   readonly revoker: SessionRevoker;
   readonly checker: SessionChecker;
   readonly massRevoker: SessionMassRevoker;
+  readonly revokeAllOthers: SessionRevokeAllOthers;
 };
 
 export type SessionStoreProvider = {
@@ -105,3 +112,59 @@ export function isSessionStoreProvider(o: unknown): o is SessionStoreProvider {
     typeof (o as { build: unknown }).build === "function"
   );
 }
+
+// Tenant-resolution extension points (#1373). Both are single-provider and
+// optional — zero registered means today's single-tenant / header-cookie
+// path (no subdomain resolver, no existence check). ≥2 fails boot.
+
+export const EXT_TENANT_RESOLVER = "tenantResolver";
+export const EXT_TENANT_EXISTENCE = "tenantExistence";
+
+/** Trust mode for a registered tenantResolver — mirrors AnonymousAccessConfig.resolverTrust. */
+export type TenantResolverTrust = "authoritative" | "fallback-only";
+
+/**
+ * Resolves the tenant for an unauthenticated request. Return null when no
+ * tenant can be determined — middleware rejects with 400. Throw only on
+ * infrastructure failures.
+ */
+export type TenantResolverFn = (
+  // Hono Context — typed loosely so auth-foundation stays free of a hono dep.
+  // Callers cast at the boundary (same shape as framework TenantResolver).
+  c: unknown,
+) => Promise<string | null> | string | null;
+
+export type TenantExistsFn = (tenantId: string) => Promise<boolean> | boolean;
+
+export type TenantResolverProvider = {
+  readonly trust: TenantResolverTrust;
+  readonly build: (deps: AuthProviderBuildDeps) => Promise<TenantResolverFn> | TenantResolverFn;
+};
+
+export type TenantExistenceProvider = {
+  readonly build: (deps: AuthProviderBuildDeps) => Promise<TenantExistsFn> | TenantExistsFn;
+};
+
+export function isTenantResolverTrust(v: unknown): v is TenantResolverTrust {
+  return v === "authoritative" || v === "fallback-only";
+}
+
+export function isTenantResolverProvider(o: unknown): o is TenantResolverProvider {
+  return (
+    typeof o === "object" &&
+    o !== null &&
+    "build" in o &&
+    typeof (o as { build: unknown }).build === "function" &&
+    "trust" in o &&
+    isTenantResolverTrust((o as { trust: unknown }).trust)
+  );
+}
+
+export function isTenantExistenceProvider(o: unknown): o is TenantExistenceProvider {
+  return (
+    typeof o === "object" &&
+    o !== null &&
+    "build" in o &&
+    typeof (o as { build: unknown }).build === "function"
+  );
+}

package/src/auth-mfa/__tests__/mfa-preauth-setup-token.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import { Temporal } from "temporal-polyfill";
+import { signMfaPreauthSetupToken, verifyMfaPreauthSetupToken } from "../mfa-preauth-setup-token";
+
+const SECRET = "test-mfa-preauth-setup-secret-at-least-32-bytes!!";
+const USER_ID = "11111111-1111-4111-8111-111111111111";
+const TENANT_ID = "22222222-2222-4222-8222-222222222222";
+
+describe("mfa-preauth-setup-token", () => {
+  test("round-trip: sign → verify → payload", () => {
+    const { token } = signMfaPreauthSetupToken(
+      { userId: USER_ID, tenantId: TENANT_ID },
+      10,
+      SECRET,
+    );
+    const result = verifyMfaPreauthSetupToken(token, SECRET);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.payload).toEqual({ userId: USER_ID, tenantId: TENANT_ID });
+    }
+  });
+
+  test("cross-domain replay from a challenge-shaped signature is rejected", () => {
+    const { token } = signMfaPreauthSetupToken(
+      { userId: USER_ID, tenantId: TENANT_ID },
+      10,
+      SECRET,
+    );
+    const [bodyB64] = token.split(".");
+    const forged = `${bodyB64}.${Buffer.from("not-the-real-signature-bytes").toString("base64url")}`;
+    expect(verifyMfaPreauthSetupToken(forged, SECRET)).toEqual({
+      ok: false,
+      reason: "bad_signature",
+    });
+  });
+
+  test("tampered signature → bad_signature", () => {
+    const { token } = signMfaPreauthSetupToken(
+      { userId: USER_ID, tenantId: TENANT_ID },
+      10,
+      SECRET,
+    );
+    const tampered = `${token.slice(0, -3)}XXX`;
+    expect(verifyMfaPreauthSetupToken(tampered, SECRET)).toEqual({
+      ok: false,
+      reason: "bad_signature",
+    });
+  });
+
+  test("different secret → bad_signature", () => {
+    const { token } = signMfaPreauthSetupToken(
+      { userId: USER_ID, tenantId: TENANT_ID },
+      10,
+      SECRET,
+    );
+    expect(verifyMfaPreauthSetupToken(token, "other-secret-not-the-same-one!!!!")).toEqual({
+      ok: false,
+      reason: "bad_signature",
+    });
+  });
+
+  test("expired → expired", () => {
+    const t0 = Temporal.Instant.fromEpochMilliseconds(1_700_000_000_000);
+    const laterThanTtl = t0.add({ minutes: 11 });
+    const { token } = signMfaPreauthSetupToken(
+      { userId: USER_ID, tenantId: TENANT_ID },
+      10,
+      SECRET,
+      t0,
+    );
+    expect(verifyMfaPreauthSetupToken(token, SECRET, laterThanTtl)).toEqual({
+      ok: false,
+      reason: "expired",
+    });
+  });
+
+  test("malformed: wrong part count", () => {
+    expect(verifyMfaPreauthSetupToken("not-a-token", SECRET)).toEqual({
+      ok: false,
+      reason: "malformed",
+    });
+    expect(verifyMfaPreauthSetupToken("a.b.c", SECRET)).toEqual({
+      ok: false,
+      reason: "malformed",
+    });
+  });
+});

package/src/auth-mfa/__tests__/verify.integration.test.ts

@@ -292,4 +292,28 @@ describe("mfa verify — re-checks account state the way login.write.ts does", (
     );
     expectErrorIncludes(err, "invalid_challenge_token");
   });
+
+  test("user row homed in a DIFFERENT tenant than the challenge → verify succeeds (#1235)", async () => {
+    const { user, secret } = await enableMfaFor(8);
+
+    // Re-home the read_users row into another tenant — the #1235 layout:
+    // the user entity is tenant-agnostic (systemStream), so its row's
+    // tenant_id need not match the tenant being logged into. The old
+    // tenant-scoped UserQueries.detail lookup returned null here and every
+    // verify died with invalid_challenge_token; the unscoped findForAuth
+    // must resolve the row regardless.
+    await asRawClient(stack.db).unsafe(
+      `UPDATE "${userTable.tableName}" SET tenant_id = $1 WHERE id = $2`,
+      ["00000000-0000-4000-8000-0000000000fe", user.id],
+    );
+
+    const challengeToken = challengeFor(user.id, user.tenantId);
+    const res = await stack.http.writeOk<{ session: SessionUser }>(
+      AuthMfaHandlers.verify,
+      { challengeToken, code: currentTotpCode(secret) },
+      GUEST,
+    );
+    expect(res.session.id).toBe(user.id);
+    expect(res.session.tenantId).toBe(user.tenantId);
+  });
 });

package/src/auth-mfa/constants.ts

@@ -34,6 +34,7 @@ export const AuthMfaErrorCodes = {
 
 export const MFA_SETUP_TOKEN_TTL_MINUTES = 10;
 export const MFA_CHALLENGE_TOKEN_TTL_MINUTES = 10;
+export const MFA_PREAUTH_SETUP_TOKEN_TTL_MINUTES = 10;
 export const MFA_VERIFY_MAX_ATTEMPTS = 5;
 export const MFA_VERIFY_LOCKOUT_MINUTES = 5;
 

package/src/auth-mfa/handlers/verify.write.ts

@@ -129,7 +129,7 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
       // the SAME tenant the challenge token already committed to (no
       // "pick a tenant" step here — that already happened at login time).
       const systemUser = createSystemUser(tenantId, ["SystemAdmin"]);
-      const userRow = (await ctx.queryAs(systemUser, UserQueries.detail, {
+      const userRow = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {
         id: userId,
       })) as { roles?: string | null; status?: string } | null; // @cast-boundary engine-payload
 

package/src/auth-mfa/mfa-preauth-setup-token.ts

@@ -0,0 +1,86 @@
+// HMAC-signed token minted by login.write.ts when enforcement policy blocks
+// an unenrolled user (mfa-setup-required) — proves the password check
+// already succeeded, so a later pre-auth enable-start variant (#1231) can
+// let the user enroll without a full session. No secret material (unlike
+// mfa-setup-token.ts) — just enough to look the user back up.
+//
+// Same domain-separated HMAC shape as mfa-challenge-token.ts, distinct
+// signing string so this can never be replayed as a login challenge or
+// vice versa. Reuses challengeTokenSecret rather than adding a third
+// feature secret: both tokens assert the identical trust boundary
+// ("password already verified, short-lived follow-up allowed").
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { Temporal } from "temporal-polyfill";
+
+export type MfaPreauthSetupPayload = {
+  readonly userId: string;
+  readonly tenantId: TenantId;
+};
+
+type EncodedBody = MfaPreauthSetupPayload & { readonly expiresAtMs: number };
+
+function sign(input: string, secret: string): string {
+  return createHmac("sha256", secret).update(input).digest("base64url");
+}
+
+export function signMfaPreauthSetupToken(
+  payload: MfaPreauthSetupPayload,
+  ttlMinutes: number,
+  secret: string,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): { token: string; expiresAt: Temporal.Instant } {
+  const expiresAt = now.add({ minutes: ttlMinutes });
+  const body: EncodedBody = { ...payload, expiresAtMs: expiresAt.epochMilliseconds };
+  const bodyB64 = Buffer.from(JSON.stringify(body)).toString("base64url");
+  const signature = sign(`mfa-preauth-setup:${bodyB64}`, secret);
+  return { token: `${bodyB64}.${signature}`, expiresAt };
+}
+
+export type VerifyMfaPreauthSetupResult =
+  | { readonly ok: true; readonly payload: MfaPreauthSetupPayload; readonly expiresAtMs: number }
+  | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
+
+function isEncodedBody(value: unknown): value is EncodedBody {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v["userId"] === "string" &&
+    typeof v["tenantId"] === "string" &&
+    typeof v["expiresAtMs"] === "number"
+  );
+}
+
+export function verifyMfaPreauthSetupToken(
+  token: string,
+  secret: string,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): VerifyMfaPreauthSetupResult {
+  const parts = token.split(".");
+  if (parts.length !== 2) return { ok: false, reason: "malformed" };
+  const [bodyB64, providedSig] = parts;
+  if (!bodyB64 || !providedSig) return { ok: false, reason: "malformed" };
+
+  const expected = sign(`mfa-preauth-setup:${bodyB64}`, secret);
+  const expectedBuf = Buffer.from(expected, "base64url");
+  const providedBuf = Buffer.from(providedSig, "base64url");
+  if (expectedBuf.length !== providedBuf.length) return { ok: false, reason: "bad_signature" };
+  if (!timingSafeEqual(expectedBuf, providedBuf)) return { ok: false, reason: "bad_signature" };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(Buffer.from(bodyB64, "base64url").toString("utf8"));
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+  if (!isEncodedBody(parsed)) return { ok: false, reason: "malformed" };
+
+  if (
+    Temporal.Instant.compare(now, Temporal.Instant.fromEpochMilliseconds(parsed.expiresAtMs)) > 0
+  ) {
+    return { ok: false, reason: "expired" };
+  }
+
+  const { expiresAtMs, ...payload } = parsed;
+  return { ok: true, payload, expiresAtMs };
+}

package/src/auth-mfa/mfa-status-checker.ts

@@ -6,9 +6,10 @@ import {
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { type MfaRequiredPolicy, mfaRequiredConfigHandle, mfaRequiredConfigKey } from "./config";
-import { MFA_CHALLENGE_TOKEN_TTL_MINUTES } from "./constants";
+import { MFA_CHALLENGE_TOKEN_TTL_MINUTES, MFA_PREAUTH_SETUP_TOKEN_TTL_MINUTES } from "./constants";
 import { findUserMfaRow } from "./db/queries";
 import { signMfaChallengeToken } from "./mfa-challenge-token";
+import { signMfaPreauthSetupToken } from "./mfa-preauth-setup-token";
 
 export type MfaStatusCheckResult =
   | { readonly required: false }
@@ -17,7 +18,7 @@ export type MfaStatusCheckResult =
   // yet. Distinct from `required: true` (which means "enrolled, prove it
   // now") — see config.ts's ponytail note on why this hard-blocks login
   // with no in-band recovery until PR3's enrollment-during-login UI ships.
-  | { readonly setupRequired: true };
+  | { readonly setupRequired: true; readonly preauthSetupToken: string };
 
 // Consumed by auth-email-password's login.write.ts via `mfaStatusChecker`
 // (a generic callback type declared THERE, not here — auth-email-password
@@ -67,9 +68,17 @@ export function createMfaStatusChecker(opts: {
       scopedDb,
     )) ?? "optional") as MfaRequiredPolicy | "optional";
     if (policy === "optional") return { required: false };
-    if (policy === "all") return { setupRequired: true };
+    const buildSetupToken = (): string =>
+      signMfaPreauthSetupToken(
+        { userId, tenantId },
+        MFA_PREAUTH_SETUP_TOKEN_TTL_MINUTES,
+        opts.challengeTokenSecret,
+      ).token;
+    if (policy === "all") return { setupRequired: true, preauthSetupToken: buildSetupToken() };
     // policy === "admins"
     const isAdmin = roles.some((role) => access.admin.includes(role));
-    return isAdmin ? { setupRequired: true } : { required: false };
+    return isAdmin
+      ? { setupRequired: true, preauthSetupToken: buildSetupToken() }
+      : { required: false };
   };
 }

package/src/config/__tests__/app-overrides.test.ts

@@ -115,4 +115,15 @@ describe("validateAppOverrides", () => {
       }),
     ).toThrow(/computed resolver.*app-overrides would silently bypass/i);
   });
+
+  test("throws on type mismatch — text key, number value", () => {
+    const reg = registryStub({
+      "a:config:s": createTenantConfig("text"),
+    });
+    expect(() =>
+      validateAppOverrides(reg, {
+        "a:config:s": 42,
+      }),
+    ).toThrow(/expected string, got number/i);
+  });
 });