@cosmicdrift/kumiko-bundled-features 0.160.0 → 0.162.0

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__/enable-confirm-preauth.integration.test.ts

@@ -0,0 +1,253 @@
+// #1456: completes both the enrollment #1465 started AND the login that
+// mfa-setup-required blocked. Real HTTP through setupTestStack, exercising
+// the full chain: login → preauthSetupToken → preauth-enable-start →
+// preauth-confirm → the minted JWT actually authenticates a follow-up
+// request. That end-to-end seam is the thing a mocked test would fake.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
+import {
+  AuthErrors as AuthEmailPasswordErrors,
+  AuthHandlers as AuthEmailPasswordHandlers,
+  createAuthEmailPasswordFeature,
+} from "../../auth-email-password";
+import { ConfigHandlers, createConfigFeature } from "../../config";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { hashPassword } from "../../shared";
+import { createTenantFeature } from "../../tenant";
+import { tenantMembershipsTable } from "../../tenant/membership-table";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { seedTenantMembership } from "../../tenant/testing";
+import { UserHandlers } from "../../user";
+import { createUserFeature } from "../../user/feature";
+import { userEntity, userTable } from "../../user/schema/user";
+import { base32Decode } from "../base32";
+import { mfaRequiredConfigHandle } from "../config";
+import { AuthMfaHandlers } from "../constants";
+import { createAuthMfaFeature, mfaStatusCheckerFromFeature } from "../feature";
+import { userMfaEntity } from "../schema/user-mfa";
+import { currentTotpCode } from "../totp";
+
+let stack: TestStack;
+
+const CHALLENGE_TOKEN_SECRET = "integration-test-challenge-token-secret-not-real-0001";
+const SETUP_TOKEN_SECRET = "integration-test-setup-token-secret-not-real-0002";
+const TENANT_ID: TenantId = testTenantId(420);
+
+beforeAll(async () => {
+  const encryption = createTestEnvelopeCipher(randomBytes(32).toString("base64"));
+  configureEntityFieldEncryption(encryption);
+  const resolver = createConfigResolver({ cipher: encryption });
+  const authMfaFeature = createAuthMfaFeature({
+    setupTokenSecret: SETUP_TOKEN_SECRET,
+    issuer: "Kumiko Test",
+    challengeTokenSecret: CHALLENGE_TOKEN_SECRET,
+  });
+
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createUserFeature(),
+      createTenantFeature(),
+      authMfaFeature,
+      createAuthEmailPasswordFeature({
+        mfaStatusChecker: mfaStatusCheckerFromFeature(authMfaFeature),
+      }),
+    ],
+    extraContext: { configResolver: resolver, configEncryption: encryption },
+    authConfig: {
+      membershipQuery: "tenant:query:memberships",
+      loginHandler: AuthEmailPasswordHandlers.login,
+      loginErrorStatusMap: {
+        [AuthEmailPasswordErrors.invalidCredentials]: 401,
+        [AuthEmailPasswordErrors.noMembership]: 403,
+      },
+      mfaPreauthEnableStartHandler: AuthMfaHandlers.enableStartPreauth,
+      mfaPreauthConfirmHandler: AuthMfaHandlers.enableConfirmPreauth,
+    },
+  });
+
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafeCreateEntityTable(stack.db, userMfaEntity);
+  await unsafePushTables(stack.db, { configValuesTable, tenantMembershipsTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+});
+
+async function loginBlockedByEnforcement(
+  email = "unenrolled@example.com",
+): Promise<{ preauthSetupToken: string; userId: string }> {
+  const password = "correct-horse-battery-2026";
+  const hash = await hashPassword(password);
+  const created = await stack.http.writeOk<{ id: string }>(
+    UserHandlers.create,
+    { email, passwordHash: hash, displayName: "Unenrolled" },
+    createTestUser({ id: 421, tenantId: TENANT_ID, roles: ["SystemAdmin"] }),
+  );
+  await seedTenantMembership(stack.db, {
+    userId: created.id,
+    tenantId: TENANT_ID,
+    roles: ["User"],
+  });
+  await stack.http.writeOk(
+    ConfigHandlers.set,
+    { key: mfaRequiredConfigHandle.name, value: "all" },
+    createTestUser({ id: 422, tenantId: TENANT_ID, roles: ["Admin"] }),
+  );
+
+  const loginRes = await stack.http.raw("POST", "/api/auth/login", { email, password });
+  const loginBody = await loginRes.json();
+  return { preauthSetupToken: loginBody.preauthSetupToken as string, userId: created.id };
+}
+
+async function startEnrollment(
+  preauthSetupToken: string,
+  accountLabel: string,
+): Promise<{ setupToken: string; secret: Buffer }> {
+  const startRes = await stack.http.raw("POST", "/api/auth/mfa/preauth-enable-start", {
+    preauthSetupToken,
+    accountLabel,
+  });
+  const startBody = await startRes.json();
+  const secretParam = new URLSearchParams(startBody.otpauthUri.split("?")[1]).get("secret") ?? "";
+  return { setupToken: startBody.setupToken as string, secret: base32Decode(secretParam) };
+}
+
+describe("POST /auth/mfa/preauth-confirm", () => {
+  test("completes enrollment + login: full chain, minted JWT authenticates a follow-up request", async () => {
+    const email = "chain@example.com";
+    const { preauthSetupToken } = await loginBlockedByEnforcement(email);
+    const { setupToken, secret } = await startEnrollment(preauthSetupToken, email);
+
+    const res = await stack.http.raw("POST", "/api/auth/mfa/preauth-confirm", {
+      setupToken,
+      code: currentTotpCode(secret),
+    });
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(true);
+    expect(typeof body.token).toBe("string");
+    expect(body.user.tenantId).toBe(TENANT_ID);
+
+    // The proof that matters: the minted JWT actually authenticates.
+    const meRes = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "user:query:user:me", payload: {} },
+      { Authorization: `Bearer ${body.token}` },
+    );
+    expect(meRes.status).toBe(200);
+  });
+
+  test("wrong TOTP code → invalid_totp_code, no enrollment persisted", async () => {
+    const email = "wrongcode@example.com";
+    const { preauthSetupToken } = await loginBlockedByEnforcement(email);
+    const { setupToken } = await startEnrollment(preauthSetupToken, email);
+
+    const res = await stack.http.raw("POST", "/api/auth/mfa/preauth-confirm", {
+      setupToken,
+      code: "000000",
+    });
+
+    expect(res.status).not.toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+    expect(body.error.details.reason).toBe("invalid_totp_code");
+    expect(body.token).toBeUndefined();
+  });
+
+  test("replaying the same setupToken after a successful confirm → invalid_setup_token (burned), not a second enrollment", async () => {
+    const email = "race@example.com";
+    const { preauthSetupToken } = await loginBlockedByEnforcement(email);
+    const { setupToken, secret } = await startEnrollment(preauthSetupToken, email);
+    const code = currentTotpCode(secret);
+
+    const first = await stack.http.raw("POST", "/api/auth/mfa/preauth-confirm", {
+      setupToken,
+      code,
+    });
+    expect(first.status).toBe(200);
+
+    // Same setupToken again — this integration stack wires real Redis, so
+    // the single-use burn from the first call rejects the replay before it
+    // ever reaches the already-enrolled DB check.
+    const second = await stack.http.raw("POST", "/api/auth/mfa/preauth-confirm", {
+      setupToken,
+      code,
+    });
+    expect(second.status).not.toBe(200);
+    const secondBody = await second.json();
+    expect(secondBody.error.details.reason).toBe("invalid_setup_token");
+  });
+
+  test("a session-issued setupToken (no tenantId) is rejected, not silently accepted", async () => {
+    const email = "sessionissued@example.com";
+    const password = "correct-horse-battery-2026";
+    const hash = await hashPassword(password);
+    const created = await stack.http.writeOk<{ id: string }>(
+      UserHandlers.create,
+      { email, passwordHash: hash, displayName: "Session Issued" },
+      createTestUser({ id: 423, tenantId: TENANT_ID, roles: ["SystemAdmin"] }),
+    );
+    await seedTenantMembership(stack.db, {
+      userId: created.id,
+      tenantId: TENANT_ID,
+      roles: ["User"],
+    });
+    const sessionUser = createTestUser({ id: created.id, tenantId: TENANT_ID, roles: ["User"] });
+
+    // The session-authed enable-start signs a setupToken with the SAME
+    // secret + format, but never carries tenantId (see mfa-setup-token.ts).
+    // A malicious or confused client resubmitting it to the pre-auth
+    // endpoint must not be able to piggyback on tenantId inference.
+    const start = await stack.http.writeOk<{ setupToken: string }>(
+      AuthMfaHandlers.enableStart,
+      { accountLabel: email },
+      sessionUser,
+    );
+
+    const res = await stack.http.raw("POST", "/api/auth/mfa/preauth-confirm", {
+      setupToken: start.setupToken,
+      code: "123456",
+    });
+
+    expect(res.status).not.toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+    expect(body.error.details.reason).toBe("invalid_setup_token");
+  });
+
+  test("expired/garbage setupToken → invalid_setup_token, no session minted", async () => {
+    const res = await stack.http.raw("POST", "/api/auth/mfa/preauth-confirm", {
+      setupToken: "not-a-real-token",
+      code: "123456",
+    });
+
+    expect(res.status).not.toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+    expect(body.token).toBeUndefined();
+  });
+});

package/src/auth-mfa/__tests__/enable-start-preauth.integration.test.ts

@@ -0,0 +1,214 @@
+// #1465: a user blocked at login by MFA enforcement (mfa-setup-required,
+// see #1455) can generate a TOTP secret + QR without a session, using the
+// preauthSetupToken login.write.ts issued. Real HTTP through
+// setupTestStack, exercising the full chain: login → preauthSetupToken →
+// POST /auth/mfa/preauth-enable-start → a setupToken that #1456's
+// (not-yet-built) confirm step will consume via verifyMfaSetupToken.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
+import {
+  AuthErrors as AuthEmailPasswordErrors,
+  AuthHandlers as AuthEmailPasswordHandlers,
+  createAuthEmailPasswordFeature,
+} from "../../auth-email-password";
+import { ConfigHandlers, createConfigFeature } from "../../config";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { hashPassword } from "../../shared";
+import { createTenantFeature } from "../../tenant";
+import { tenantMembershipsTable } from "../../tenant/membership-table";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { seedTenantMembership } from "../../tenant/testing";
+import { UserHandlers } from "../../user";
+import { createUserFeature } from "../../user/feature";
+import { userEntity, userTable } from "../../user/schema/user";
+import { base32Decode } from "../base32";
+import { mfaRequiredConfigHandle } from "../config";
+import { AuthMfaHandlers } from "../constants";
+import { createAuthMfaFeature, mfaStatusCheckerFromFeature } from "../feature";
+import { signMfaPreauthSetupToken } from "../mfa-preauth-setup-token";
+import { verifyMfaSetupToken } from "../mfa-setup-token";
+import { userMfaEntity } from "../schema/user-mfa";
+import { currentTotpCode } from "../totp";
+
+let stack: TestStack;
+
+const CHALLENGE_TOKEN_SECRET = "test-mfa-challenge-secret-at-least-32-bytes!!";
+const SETUP_TOKEN_SECRET = "test-mfa-setup-token-secret-at-least-32-bytes!!";
+const TENANT_ID: TenantId = testTenantId(410);
+
+beforeAll(async () => {
+  const encryption = createTestEnvelopeCipher(randomBytes(32).toString("base64"));
+  configureEntityFieldEncryption(encryption);
+  const resolver = createConfigResolver({ cipher: encryption });
+  const authMfaFeature = createAuthMfaFeature({
+    setupTokenSecret: SETUP_TOKEN_SECRET,
+    issuer: "Kumiko Test",
+    challengeTokenSecret: CHALLENGE_TOKEN_SECRET,
+  });
+
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createUserFeature(),
+      createTenantFeature(),
+      authMfaFeature,
+      createAuthEmailPasswordFeature({
+        mfaStatusChecker: mfaStatusCheckerFromFeature(authMfaFeature),
+      }),
+    ],
+    extraContext: { configResolver: resolver, configEncryption: encryption },
+    authConfig: {
+      membershipQuery: "tenant:query:memberships",
+      loginHandler: AuthEmailPasswordHandlers.login,
+      loginErrorStatusMap: {
+        [AuthEmailPasswordErrors.invalidCredentials]: 401,
+        [AuthEmailPasswordErrors.noMembership]: 403,
+      },
+      mfaPreauthEnableStartHandler: AuthMfaHandlers.enableStartPreauth,
+    },
+  });
+
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafeCreateEntityTable(stack.db, userMfaEntity);
+  await unsafePushTables(stack.db, { configValuesTable, tenantMembershipsTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+});
+
+async function loginBlockedByEnforcement(): Promise<{
+  preauthSetupToken: string;
+  userId: string;
+}> {
+  const password = "correct-horse-battery-2026";
+  const hash = await hashPassword(password);
+  const created = await stack.http.writeOk<{ id: string }>(
+    UserHandlers.create,
+    { email: "unenrolled@example.com", passwordHash: hash, displayName: "Unenrolled" },
+    createTestUser({ id: 411, tenantId: TENANT_ID, roles: ["SystemAdmin"] }),
+  );
+  await seedTenantMembership(stack.db, {
+    userId: created.id,
+    tenantId: TENANT_ID,
+    roles: ["User"],
+  });
+  await stack.http.writeOk(
+    ConfigHandlers.set,
+    { key: mfaRequiredConfigHandle.name, value: "all" },
+    createTestUser({ id: 412, tenantId: TENANT_ID, roles: ["Admin"] }),
+  );
+
+  const loginRes = await stack.http.raw("POST", "/api/auth/login", {
+    email: "unenrolled@example.com",
+    password,
+  });
+  const loginBody = await loginRes.json();
+  return { preauthSetupToken: loginBody.preauthSetupToken as string, userId: created.id };
+}
+
+describe("POST /auth/mfa/preauth-enable-start", () => {
+  test("generates a TOTP secret + QR from a valid preauthSetupToken, no session minted", async () => {
+    const { preauthSetupToken } = await loginBlockedByEnforcement();
+
+    const res = await stack.http.raw("POST", "/api/auth/mfa/preauth-enable-start", {
+      preauthSetupToken,
+      accountLabel: "unenrolled@example.com",
+    });
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(true);
+    expect(body.token).toBeUndefined();
+    expect(typeof body.setupToken).toBe("string");
+    expect(typeof body.otpauthUri).toBe("string");
+    expect(body.otpauthUri).toContain("otpauth://totp/");
+    expect(Array.isArray(body.recoveryCodes)).toBe(true);
+    expect(body.recoveryCodes).toHaveLength(8);
+
+    // The returned setupToken must compose with the EXISTING enable-confirm
+    // verification path (verifyMfaSetupToken) — proves #1465 and #1456
+    // actually chain together, not just that each returns *a* string.
+    const verified = verifyMfaSetupToken(body.setupToken, SETUP_TOKEN_SECRET);
+    expect(verified.ok).toBe(true);
+    if (verified.ok) {
+      expect(typeof verified.payload.totpSecretBase32).toBe("string");
+      expect(verified.payload.recoveryCodeHashes).toHaveLength(8);
+    }
+  });
+
+  test("expired/garbage preauthSetupToken → invalid_challenge_token, no secret leaked", async () => {
+    const res = await stack.http.raw("POST", "/api/auth/mfa/preauth-enable-start", {
+      preauthSetupToken: "not-a-real-token",
+      accountLabel: "unenrolled@example.com",
+    });
+
+    expect(res.status).not.toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+    expect(body.setupToken).toBeUndefined();
+  });
+
+  test("already-enrolled user gets mfa_already_enabled, not a fresh secret", async () => {
+    const { userId } = await loginBlockedByEnforcement();
+    const sessionUser = createTestUser({ id: userId, tenantId: TENANT_ID, roles: ["User"] });
+
+    // Really enrolls — via the existing session-authed enable-start/confirm
+    // pair, not a synthetic DB insert — so this test breaks if enrollment
+    // detection ever drifts from what a real enroll actually persists.
+    const start = await stack.http.writeOk<{ setupToken: string; otpauthUri: string }>(
+      AuthMfaHandlers.enableStart,
+      { accountLabel: "unenrolled@example.com" },
+      sessionUser,
+    );
+    const secretParam = new URLSearchParams(start.otpauthUri.split("?")[1]).get("secret") ?? "";
+    const secret = base32Decode(secretParam);
+    await stack.http.writeOk(
+      AuthMfaHandlers.enableConfirm,
+      { setupToken: start.setupToken, code: currentTotpCode(secret) },
+      sessionUser,
+    );
+
+    // A fresh preauthSetupToken for the SAME already-enrolled user — the
+    // login flow itself would no longer issue one (mfaStatusChecker sees
+    // the row and returns `required: true`, not `setupRequired`), so this
+    // mints one directly to isolate the handler's own already-enrolled
+    // check from that unrelated login-side branch.
+    const { token: freshPreauthToken } = signMfaPreauthSetupToken(
+      { userId, tenantId: TENANT_ID },
+      10,
+      CHALLENGE_TOKEN_SECRET,
+    );
+
+    const res = await stack.http.raw("POST", "/api/auth/mfa/preauth-enable-start", {
+      preauthSetupToken: freshPreauthToken,
+      accountLabel: "unenrolled@example.com",
+    });
+
+    expect(res.status).not.toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+    expect(body.error.details.reason).toBe("mfa_already_enabled");
+    expect(body.setupToken).toBeUndefined();
+  });
+});

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",
+    });
+  });
+});