@cosmicdrift/kumiko-framework 0.161.0 → 0.163.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.161.0",
+  "version": "0.163.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -182,7 +182,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.161.0",
+    "@cosmicdrift/kumiko-types": "0.163.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.18",
@@ -198,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.161.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.163.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/schema-cli.integration.test.ts

@@ -177,6 +177,27 @@ describe("runSchemaCli — validate (static CI gate, no DB)", () => {
     const code = await runSchemaCli(["validate"], appCwd, cap.out);
     expect(code).toBe(0);
     expect(cap.log.join("\n")).toContain("migrations match");
+    expect(cap.log.join("\n")).toContain("committed SQL matches .snapshot.json");
+  });
+
+  // Reproduces the kumiko-studio 0016 incident: a migration file gets
+  // hand-edited (or copy-pasted from another file) after `generate` wrote
+  // it — the snapshot still matches ENTITY_METAS (layer 1 stays green), but
+  // the .sql content no longer produces what the snapshot claims.
+  test("migration file edited after generate to not match its snapshot entry → drift, exit 1", async () => {
+    writeSchemaFile(appCwd, "read_widgets");
+    await runSchemaCli(["generate", "init"], appCwd, captureOut().out);
+    writeFileSync(
+      join(appCwd, "kumiko/migrations/0001_init.sql"),
+      `-- oops: hand-edited to the wrong table name after the snapshot was written
+CREATE TABLE IF NOT EXISTS "read_widgets_v2" ("id" uuid PRIMARY KEY);
+`,
+    );
+    const cap = captureOut();
+    const code = await runSchemaCli(["validate"], appCwd, cap.out);
+    expect(code).toBe(1);
+    expect(cap.err.join("\n")).toContain("migration-content drift");
+    expect(cap.err.join("\n")).toContain("read_widgets");
   });
 
   test("no FEATURES export → validateBoot skipped (drift still checked)", async () => {

package/src/api/__tests__/auth-routes-mfa-preauth-confirm.test.ts

@@ -0,0 +1,205 @@
+// auth-routes /auth/mfa/preauth-confirm — framework-level route mechanics
+// only: body validation, dispatch-and-mint-on-success, its OWN rate limiter
+// (mfaPreauthConfirmRateLimit, distinct from mfaVerifyRateLimit/
+// loginRateLimit), and error-status mapping. Uses a stub Dispatcher with a
+// fake handler — the REAL setupToken verification / TOTP check / brute-
+// force cap lives in auth-mfa's own handler and is covered there, not here.
+
+import { describe, expect, test } from "bun:test";
+import type { Hono } from "hono";
+import { Hono as HonoCtor } from "hono";
+import { InternalError, UnprocessableError } from "../../errors";
+import type { BatchResult, Dispatcher, WriteResult } from "../../pipeline/dispatcher";
+import { TestUsers } from "../../stack";
+import { getSetCookies } from "../../testing/http-cookies";
+import { PUBLIC_API_PATHS } from "../api-constants";
+import { AUTH_COOKIE_NAME, authMiddleware, CSRF_COOKIE_NAME } from "../auth-middleware";
+import {
+  type AuthRoutesConfig,
+  createAuthRoutes,
+  createInMemoryLoginRateLimiter,
+} from "../auth-routes";
+import { createJwtHelper } from "../jwt";
+
+const JWT_SECRET = "test-jwt-secret-for-mfa-preauth-confirm-route-tests-only-not-a-real-secret";
+const PREAUTH_CONFIRM_QN = "auth-mfa:write:enable-confirm-preauth";
+
+function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
+  const base: Dispatcher = {
+    async write(): Promise<WriteResult> {
+      const ok: WriteResult = {
+        isSuccess: true,
+        data: { kind: "mfa-preauth-confirm-success", session: TestUsers.user },
+      };
+      return ok;
+    },
+    async query(): Promise<unknown> {
+      return [];
+    },
+    async *stream(): AsyncGenerator<unknown> {},
+    async command(): Promise<void> {},
+    async batch(): Promise<BatchResult> {
+      const ok: BatchResult = { isSuccess: true, results: [] };
+      return ok;
+    },
+    async resolveAuthClaims(): Promise<Record<string, unknown>> {
+      return {};
+    },
+  };
+  return { ...base, ...overrides };
+}
+
+async function buildApp(
+  overrides: Partial<AuthRoutesConfig> = {},
+  dispatcher: Dispatcher = createStubDispatcher(),
+): Promise<{ app: Hono }> {
+  const jwt = createJwtHelper(JWT_SECRET);
+  const config: AuthRoutesConfig = {
+    membershipQuery: "tenant:query:memberships",
+    mfaPreauthConfirmHandler: PREAUTH_CONFIRM_QN,
+    mfaPreauthConfirmRateLimit: null,
+    ...overrides,
+  };
+  const app = new HonoCtor();
+  const jwtGuard = authMiddleware(jwt);
+  app.use("/api/*", async (c, next) => {
+    if (PUBLIC_API_PATHS.has(c.req.path)) return next();
+    return jwtGuard(c, next);
+  });
+  app.route("/api", createAuthRoutes(dispatcher, jwt, config));
+  return { app };
+}
+
+function preauthConfirmRequest(body: unknown): Request {
+  return new Request("http://localhost/api/auth/mfa/preauth-confirm", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+describe("POST /auth/mfa/preauth-confirm", () => {
+  test("is public — reachable without a JWT", async () => {
+    expect(PUBLIC_API_PATHS.has("/api/auth/mfa/preauth-confirm")).toBe(true);
+  });
+
+  test("not mounted when mfaPreauthConfirmHandler is unset", async () => {
+    const { app } = await buildApp({ mfaPreauthConfirmHandler: undefined });
+    const res = await app.request(preauthConfirmRequest({ setupToken: "t", code: "123456" }));
+    expect(res.status).toBe(404);
+  });
+
+  test("400 on a malformed body, before dispatch or rate-limit", async () => {
+    let dispatched = false;
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        dispatched = true;
+        return {
+          isSuccess: true,
+          data: { kind: "mfa-preauth-confirm-success", session: TestUsers.user },
+        };
+      },
+    });
+    const { app } = await buildApp({}, dispatcher);
+    const res = await app.request(preauthConfirmRequest({ setupToken: "t" }));
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { isSuccess: boolean; error: string };
+    expect(body.error).toBe("invalid_body");
+    expect(dispatched).toBe(false);
+  });
+
+  test("on success: dispatches to mfaPreauthConfirmHandler, mints a JWT + cookies", async () => {
+    let receivedBody: unknown;
+    const dispatcher = createStubDispatcher({
+      async write(qn, payload): Promise<WriteResult> {
+        expect(qn).toBe(PREAUTH_CONFIRM_QN);
+        receivedBody = payload;
+        return {
+          isSuccess: true,
+          data: { kind: "mfa-preauth-confirm-success", session: TestUsers.user },
+        };
+      },
+    });
+    const { app } = await buildApp({}, dispatcher);
+    const res = await app.request(
+      preauthConfirmRequest({ setupToken: "secret-carrying-setup-token", code: "123456" }),
+    );
+    expect(res.status).toBe(200);
+    expect(receivedBody).toEqual({
+      setupToken: "secret-carrying-setup-token",
+      code: "123456",
+    });
+
+    const body = (await res.json()) as { isSuccess: boolean; token: string };
+    expect(body.isSuccess).toBe(true);
+    expect(typeof body.token).toBe("string");
+    expect(body.token.length).toBeGreaterThan(20);
+
+    const cookies = getSetCookies(res);
+    expect(cookies.get(AUTH_COOKIE_NAME)).toBeDefined();
+    expect(cookies.get(CSRF_COOKIE_NAME)).toBeDefined();
+  });
+
+  test("a handler failure maps through mfaPreauthConfirmErrorStatusMap", async () => {
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        return {
+          isSuccess: false,
+          error: new UnprocessableError("invalid_totp_code", {
+            details: { reason: "invalid_totp_code" },
+          }),
+        };
+      },
+    });
+    const { app } = await buildApp(
+      { mfaPreauthConfirmErrorStatusMap: { invalid_totp_code: 422 } },
+      dispatcher,
+    );
+    const res = await app.request(preauthConfirmRequest({ setupToken: "t", code: "000000" }));
+    expect(res.status).toBe(422);
+    const body = (await res.json()) as { isSuccess: boolean };
+    expect(body.isSuccess).toBe(false);
+  });
+
+  test("an unmapped handler failure falls back to the error's own httpStatus", async () => {
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        return { isSuccess: false, error: new InternalError({ message: "boom" }) };
+      },
+    });
+    const { app } = await buildApp({}, dispatcher);
+    const res = await app.request(preauthConfirmRequest({ setupToken: "t", code: "000000" }));
+    expect(res.status).toBe(500);
+  });
+
+  test("mfaPreauthConfirmRateLimit is independent from mfaVerifyRateLimit — 429 after its own cap", async () => {
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        return {
+          isSuccess: false,
+          error: new UnprocessableError("invalid_totp_code"),
+        };
+      },
+    });
+    const { app } = await buildApp(
+      { mfaPreauthConfirmRateLimit: createInMemoryLoginRateLimiter(2, 60_000) },
+      dispatcher,
+    );
+    const attempt = () => app.request(preauthConfirmRequest({ setupToken: "t", code: "000000" }));
+    expect((await attempt()).status).toBe(422);
+    expect((await attempt()).status).toBe(422);
+    const third = await attempt();
+    expect(third.status).toBe(429);
+    const body = (await third.json()) as { isSuccess: boolean; error: string };
+    expect(body.error).toBe("rate_limited");
+  });
+
+  test("a successful confirm resets the rate-limit counter for that IP", async () => {
+    const { app } = await buildApp({
+      mfaPreauthConfirmRateLimit: createInMemoryLoginRateLimiter(1, 60_000),
+    });
+    const attempt = () => app.request(preauthConfirmRequest({ setupToken: "t", code: "000000" }));
+    expect((await attempt()).status).toBe(200);
+    expect((await attempt()).status).toBe(200);
+  });
+});

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

@@ -0,0 +1,186 @@
+// auth-routes /auth/mfa/preauth-enable-start — framework-level route
+// mechanics only: body validation, dispatch-without-minting-a-session, and
+// error-status mapping. Uses a stub Dispatcher with a fake handler — the
+// REAL preauthSetupToken verification / secret generation lives in
+// auth-mfa's own handler and is covered there, not here.
+
+import { describe, expect, test } from "bun:test";
+import type { Hono } from "hono";
+import { Hono as HonoCtor } from "hono";
+import { InternalError, UnprocessableError } from "../../errors";
+import type { BatchResult, Dispatcher, WriteResult } from "../../pipeline/dispatcher";
+import { PUBLIC_API_PATHS } from "../api-constants";
+import { authMiddleware } from "../auth-middleware";
+import { type AuthRoutesConfig, createAuthRoutes } from "../auth-routes";
+import { createJwtHelper } from "../jwt";
+
+const JWT_SECRET = "test-jwt-secret-at-least-32-bytes-long!!";
+const PREAUTH_ENABLE_START_QN = "auth-mfa:write:enable-start-preauth";
+
+function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
+  const base: Dispatcher = {
+    async write(): Promise<WriteResult> {
+      const ok: WriteResult = {
+        isSuccess: true,
+        data: {
+          setupToken: "stub-setup-token",
+          otpauthUri: "otpauth://totp/stub",
+          recoveryCodes: ["AAAA-BBBB"],
+        },
+      };
+      return ok;
+    },
+    async query(): Promise<unknown> {
+      return [];
+    },
+    async *stream(): AsyncGenerator<unknown> {},
+    async command(): Promise<void> {},
+    async batch(): Promise<BatchResult> {
+      const ok: BatchResult = { isSuccess: true, results: [] };
+      return ok;
+    },
+    async resolveAuthClaims(): Promise<Record<string, unknown>> {
+      return {};
+    },
+  };
+  return { ...base, ...overrides };
+}
+
+async function buildApp(
+  overrides: Partial<AuthRoutesConfig> = {},
+  dispatcher: Dispatcher = createStubDispatcher(),
+): Promise<{ app: Hono }> {
+  const jwt = createJwtHelper(JWT_SECRET);
+  const config: AuthRoutesConfig = {
+    membershipQuery: "tenant:query:memberships",
+    mfaPreauthEnableStartHandler: PREAUTH_ENABLE_START_QN,
+    ...overrides,
+  };
+  const app = new HonoCtor();
+  const jwtGuard = authMiddleware(jwt);
+  app.use("/api/*", async (c, next) => {
+    if (PUBLIC_API_PATHS.has(c.req.path)) return next();
+    return jwtGuard(c, next);
+  });
+  app.route("/api", createAuthRoutes(dispatcher, jwt, config));
+  return { app };
+}
+
+function preauthStartRequest(body: unknown): Request {
+  return new Request("http://localhost/api/auth/mfa/preauth-enable-start", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+describe("POST /auth/mfa/preauth-enable-start", () => {
+  test("is public — reachable without a JWT", async () => {
+    expect(PUBLIC_API_PATHS.has("/api/auth/mfa/preauth-enable-start")).toBe(true);
+  });
+
+  test("not mounted when mfaPreauthEnableStartHandler is unset", async () => {
+    const { app } = await buildApp({ mfaPreauthEnableStartHandler: undefined });
+    const res = await app.request(
+      preauthStartRequest({ preauthSetupToken: "t", accountLabel: "a@b.c" }),
+    );
+    expect(res.status).toBe(404);
+  });
+
+  test("400 on a malformed body, before dispatch", async () => {
+    let dispatched = false;
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        dispatched = true;
+        return {
+          isSuccess: true,
+          data: { setupToken: "x", otpauthUri: "otpauth://totp/x", recoveryCodes: [] },
+        };
+      },
+    });
+    const { app } = await buildApp({}, dispatcher);
+    const res = await app.request(preauthStartRequest({ preauthSetupToken: "t" }));
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { isSuccess: boolean; error: string };
+    expect(body.error).toBe("invalid_body");
+    expect(dispatched).toBe(false);
+  });
+
+  test("on success: dispatches to the handler, returns setupToken/otpauthUri/recoveryCodes, mints NO session", async () => {
+    let receivedBody: unknown;
+    const dispatcher = createStubDispatcher({
+      async write(qn, payload): Promise<WriteResult> {
+        expect(qn).toBe(PREAUTH_ENABLE_START_QN);
+        receivedBody = payload;
+        return {
+          isSuccess: true,
+          data: {
+            setupToken: "secret-carrying-setup-token",
+            otpauthUri: "otpauth://totp/Kumiko:a%40b.c",
+            recoveryCodes: ["AAAA-BBBB", "CCCC-DDDD"],
+          },
+        };
+      },
+    });
+    const { app } = await buildApp({}, dispatcher);
+    const res = await app.request(
+      preauthStartRequest({ preauthSetupToken: "opaque-preauth-token", accountLabel: "a@b.c" }),
+    );
+    expect(res.status).toBe(200);
+    expect(receivedBody).toEqual({
+      preauthSetupToken: "opaque-preauth-token",
+      accountLabel: "a@b.c",
+    });
+
+    const body = (await res.json()) as {
+      isSuccess: boolean;
+      setupToken: string;
+      otpauthUri: string;
+      recoveryCodes: string[];
+      token?: string;
+    };
+    expect(body.isSuccess).toBe(true);
+    expect(body.setupToken).toBe("secret-carrying-setup-token");
+    expect(body.otpauthUri).toBe("otpauth://totp/Kumiko:a%40b.c");
+    expect(body.recoveryCodes).toEqual(["AAAA-BBBB", "CCCC-DDDD"]);
+    // No JWT minted — unlike /auth/login and /auth/mfa/verify, this route
+    // never establishes a session.
+    expect(body.token).toBeUndefined();
+  });
+
+  test("a handler failure maps through mfaPreauthEnableStartErrorStatusMap", async () => {
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        return {
+          isSuccess: false,
+          error: new UnprocessableError("invalid_challenge_token", {
+            details: { reason: "invalid_challenge_token" },
+          }),
+        };
+      },
+    });
+    const { app } = await buildApp(
+      { mfaPreauthEnableStartErrorStatusMap: { invalid_challenge_token: 422 } },
+      dispatcher,
+    );
+    const res = await app.request(
+      preauthStartRequest({ preauthSetupToken: "t", accountLabel: "a@b.c" }),
+    );
+    expect(res.status).toBe(422);
+    const body = (await res.json()) as { isSuccess: boolean };
+    expect(body.isSuccess).toBe(false);
+  });
+
+  test("an unmapped handler failure falls back to the error's own httpStatus", async () => {
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        return { isSuccess: false, error: new InternalError({ message: "boom" }) };
+      },
+    });
+    const { app } = await buildApp({}, dispatcher);
+    const res = await app.request(
+      preauthStartRequest({ preauthSetupToken: "t", accountLabel: "a@b.c" }),
+    );
+    expect(res.status).toBe(500);
+  });
+});

package/src/api/api-constants.ts

@@ -14,6 +14,8 @@ export const Routes = {
   auth: "/auth",
   authLogin: "/auth/login",
   authMfaVerify: "/auth/mfa/verify",
+  authMfaPreauthEnableStart: "/auth/mfa/preauth-enable-start",
+  authMfaPreauthConfirm: "/auth/mfa/preauth-confirm",
   authLogout: "/auth/logout",
   authTenants: "/auth/tenants",
   authSwitchTenant: "/auth/switch-tenant",
@@ -41,6 +43,8 @@ export const Routes = {
 export const PUBLIC_API_PATHS: ReadonlySet<string> = new Set([
   `/api${Routes.authLogin}`,
   `/api${Routes.authMfaVerify}`,
+  `/api${Routes.authMfaPreauthEnableStart}`,
+  `/api${Routes.authMfaPreauthConfirm}`,
   `/api${Routes.authRequestPasswordReset}`,
   `/api${Routes.authResetPassword}`,
   `/api${Routes.authRequestEmailVerification}`,

package/src/api/auth-routes.ts

@@ -106,6 +106,26 @@ const MfaVerifyBody = z.object({
   code: z.string().min(6).max(9),
 });
 
+// Body schema for POST /auth/mfa/preauth-enable-start. preauthSetupToken is
+// opaque to the framework — minted by login.write.ts's mfaStatusChecker
+// (auth-mfa) when enforcement policy blocks an unenrolled user, verified
+// entirely by the mfaPreauthEnableStartHandler. accountLabel is
+// client-supplied (the email the user just typed at login) for the
+// otpauth:// URI, mirroring auth-mfa's own enable-start.write.ts.
+const MfaPreauthEnableStartBody = z.object({
+  preauthSetupToken: z.string().min(1),
+  accountLabel: z.string().min(1).max(200),
+});
+
+// Body schema for POST /auth/mfa/preauth-confirm. setupToken is opaque to
+// the framework — minted by the mfaPreauthEnableStartHandler, verified
+// entirely by the mfaPreauthConfirmHandler. code is TOTP-only (no recovery
+// codes at enrollment time), mirroring auth-mfa's own enable-confirm.write.ts.
+const MfaPreauthConfirmBody = z.object({
+  setupToken: z.string().min(1),
+  code: z.string().length(6),
+});
+
 const ResetPasswordBody = z.object({
   token: z.string().min(1),
   newPassword: z.string().min(8).max(200),
@@ -248,6 +268,42 @@ export type AuthRoutesConfig = {
   // and per-account guessing protection are different threats, neither
   // substitutes for the other.
   mfaVerifyRateLimit?: LoginRateLimiter | null;
+  // Optional: qualified write handler generating a TOTP secret + QR for a
+  // user blocked at login by MFA enforcement but not yet enrolled (see
+  // mfaStatusChecker's setupRequired branch, auth-mfa). When set, POST
+  // /auth/mfa/preauth-enable-start dispatches { preauthSetupToken,
+  // accountLabel } to this handler with a guest identity — no session is
+  // minted, the response is just { setupToken, otpauthUri, recoveryCodes }
+  // (same shape as auth-mfa's own enable-start.write.ts). No dedicated
+  // rate-limiter here (unlike mfaVerifyRateLimit): the route already
+  // inherits the generic L2 authEndpointRateLimit on /api/auth/*, and this
+  // handler checks no TOTP code, so there's no per-account guessing
+  // surface to cap — that cap belongs on the later confirm handler.
+  mfaPreauthEnableStartHandler?: string;
+  // Maps mfaPreauthEnableStartHandler error codes to HTTP status codes,
+  // same pattern as mfaVerifyErrorStatusMap.
+  mfaPreauthEnableStartErrorStatusMap?: Readonly<Record<string, number>>;
+  // Optional: qualified write handler completing the enrollment started by
+  // mfaPreauthEnableStartHandler — takes the secret-carrying setupToken
+  // from that step plus a TOTP code. When set, POST /auth/mfa/preauth-
+  // confirm dispatches { setupToken, code } to this handler with a guest
+  // identity. On success the handler must return { kind: "mfa-preauth-
+  // confirm-success", session: SessionUser } and the route mints a JWT
+  // exactly like /auth/mfa/verify — this call both finishes enrollment AND
+  // completes the login that was blocked by mfa-setup-required. Unlike
+  // mfaPreauthEnableStartHandler, THIS is the per-account TOTP-guessing
+  // surface the enable-start doc comment refers to — the handler owns its
+  // own brute-force cap (mirroring mfaVerifyHandler's), and this route adds
+  // its own IP-scoped rate limiter for the same reason mfaVerifyRateLimit
+  // exists separately from loginRateLimit.
+  mfaPreauthConfirmHandler?: string;
+  // Maps mfaPreauthConfirmHandler error codes to HTTP status codes, same
+  // pattern as mfaVerifyErrorStatusMap.
+  mfaPreauthConfirmErrorStatusMap?: Readonly<Record<string, number>>;
+  // Rate-limit for POST /auth/mfa/preauth-confirm, keyed by client IP. Same
+  // reasoning as mfaVerifyRateLimit — defaults to in-memory 10/5min, pass
+  // `null` to disable.
+  mfaPreauthConfirmRateLimit?: LoginRateLimiter | null;
   // Session-lifecycle callbacks. When both are wired the JWT carries a `jti`
   // (sid) and the server can revoke individual sessions (logout, compromise,
   // password-change). When unwired the framework issues plain stateless JWTs.
@@ -709,6 +765,126 @@ export function createAuthRoutes(
     });
   }
 
+  // POST /auth/mfa/preauth-enable-start — lets a user blocked at login by
+  // MFA enforcement (mfa-setup-required) generate a TOTP secret + QR
+  // without a session, using the preauthSetupToken login.write.ts issued.
+  // No JWT is minted here (unlike /auth/login and /auth/mfa/verify) — the
+  // handler's response carries a secret-bearing setupToken that a later
+  // pre-auth confirm step (the same shape auth-mfa's own enable-confirm
+  // consumes) verifies. No dedicated rate-limiter: see
+  // AuthRoutesConfig.mfaPreauthEnableStartHandler's doc comment for why
+  // the generic L2 /api/auth/* limiter is enough here.
+  if (config.mfaPreauthEnableStartHandler) {
+    const mfaPreauthEnableStartQn = config.mfaPreauthEnableStartHandler;
+    const statusMap = config.mfaPreauthEnableStartErrorStatusMap ?? {};
+
+    api.post(Routes.authMfaPreauthEnableStart, async (c) => {
+      const raw = await c.req.json().catch(() => null);
+      const parsed = MfaPreauthEnableStartBody.safeParse(raw);
+      if (!parsed.success) {
+        return c.json({ isSuccess: false, error: "invalid_body" }, 400);
+      }
+      const body = parsed.data;
+
+      const result = await dispatcher.write(mfaPreauthEnableStartQn, body, GUEST_USER);
+
+      if (!result.isSuccess) {
+        // @cast-boundary error-details — KumikoError.details shape is per-error
+        const reason =
+          (result.error.details as { reason?: string } | undefined)?.reason ?? result.error.code;
+        // @cast-boundary engine-payload — statusMap value union narrows to the http-status union
+        const status = (statusMap[reason] ?? result.error.httpStatus) as
+          | 400
+          | 401
+          | 403
+          | 422
+          | 429
+          | 500;
+        return c.json({ isSuccess: false, error: result.error }, status);
+      }
+
+      // @cast-boundary engine-payload — generic dispatcher.write result for
+      // the preauth-enable-start handler
+      const data = result.data as {
+        setupToken: string;
+        otpauthUri: string;
+        recoveryCodes: readonly string[];
+      };
+
+      return c.json({ isSuccess: true, ...data });
+    });
+  }
+
+  // POST /auth/mfa/preauth-confirm — completes both the enrollment started
+  // by preauth-enable-start AND the login mfa-setup-required blocked.
+  // Mirrors /auth/mfa/verify structurally (public, GUEST_USER dispatch,
+  // mintSessionAndRespond on success) with its OWN rate limiter
+  // (mfaPreauthConfirmRateLimit) — same reasoning as mfaVerifyRateLimit.
+  // Per-account brute-force protection (capping wrong-code guesses against
+  // one still-valid setupToken) is owned by the handler itself — see
+  // AuthRoutesConfig.mfaPreauthConfirmHandler's doc comment.
+  if (config.mfaPreauthConfirmHandler) {
+    const mfaPreauthConfirmQn = config.mfaPreauthConfirmHandler;
+    const statusMap = config.mfaPreauthConfirmErrorStatusMap ?? {};
+    const rateLimiter =
+      config.mfaPreauthConfirmRateLimit === null
+        ? null
+        : (config.mfaPreauthConfirmRateLimit ?? createInMemoryLoginRateLimiter());
+
+    api.post(Routes.authMfaPreauthConfirm, async (c) => {
+      const raw = await c.req.json().catch(() => null);
+      const parsed = MfaPreauthConfirmBody.safeParse(raw);
+      if (!parsed.success) {
+        return c.json({ isSuccess: false, error: "invalid_body" }, 400);
+      }
+      const body = parsed.data;
+
+      const clientIp =
+        c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ??
+        c.req.header("x-real-ip") ??
+        "unknown";
+
+      if (rateLimiter) {
+        const allowed = await rateLimiter.check(clientIp);
+        if (!allowed) {
+          return c.json({ isSuccess: false, error: "rate_limited" }, 429);
+        }
+      }
+
+      const result = await dispatcher.write(mfaPreauthConfirmQn, body, GUEST_USER);
+
+      if (!result.isSuccess) {
+        // @cast-boundary error-details — KumikoError.details shape is per-error
+        const reason =
+          (result.error.details as { reason?: string } | undefined)?.reason ?? result.error.code;
+        // @cast-boundary engine-payload — statusMap value union narrows to the http-status union
+        const status = (statusMap[reason] ?? result.error.httpStatus) as
+          | 400
+          | 401
+          | 403
+          | 422
+          | 429
+          | 500;
+        return c.json({ isSuccess: false, error: result.error }, status);
+      }
+
+      // @cast-boundary engine-payload — generic dispatcher.write result for mfa-preauth-confirm handler
+      const data = result.data as { kind: "mfa-preauth-confirm-success"; session: SessionUser };
+
+      const token = await mintSessionAndRespond(c, data.session);
+
+      if (rateLimiter) {
+        await rateLimiter.reset(clientIp);
+      }
+
+      return c.json({
+        isSuccess: true,
+        token,
+        user: { id: data.session.id, tenantId: data.session.tenantId, roles: data.session.roles },
+      });
+    });
+  }
+
   // POST /auth/request-password-reset + /auth/reset-password — public.
   // Silent-success on request (no enumeration), typed failure on confirm.
   // Rate-limit covered via config.rateLimit.auth (Sprint G.5 L2, /auth/*).

package/src/db/__tests__/replay-migration-sql.test.ts

@@ -0,0 +1,207 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { EntityTableMeta } from "../entity-table-meta";
+import { snapshotFromMetas } from "../migrate-generator";
+import { diffReplayAgainstSnapshot, replayMigrationsDir } from "../replay-migration-sql";
+
+function tmpMigrationsDir(): string {
+  return mkdtempSync(join(tmpdir(), "replay-migration-sql-"));
+}
+
+function write(dir: string, filename: string, sql: string): void {
+  writeFileSync(join(dir, filename), sql);
+}
+
+function meta(tableName: string, columns: EntityTableMeta["columns"]): EntityTableMeta {
+  return { tableName, source: "managed", indexes: [], columns };
+}
+
+describe("replayMigrationsDir", () => {
+  test("reconstructs table+column shape from CREATE TABLE", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_init.sql",
+        `CREATE TABLE IF NOT EXISTS "read_accounts" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "tenant_id" uuid NOT NULL,
+  "stripe_customer_id" text
+);
+CREATE INDEX IF NOT EXISTS "read_accounts_tenant_id_idx" ON "read_accounts" ("tenant_id");`,
+      );
+      const replayed = replayMigrationsDir(dir);
+      expect([...replayed.keys()]).toEqual(["read_accounts"]);
+      expect([...(replayed.get("read_accounts")?.columns ?? [])].sort()).toEqual([
+        "id",
+        "stripe_customer_id",
+        "tenant_id",
+      ]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("ADD COLUMN extends an already-created table across files", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(dir, "0001_init.sql", `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY);`);
+      write(dir, "0002_add-col.sql", `ALTER TABLE "read_a" ADD COLUMN "title" text;`);
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("read_a")?.columns ?? [])].sort()).toEqual(["id", "title"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  // Hand-edited migrations legitimately add "IF NOT EXISTS"/"IF EXISTS" to
+  // ADD/DROP COLUMN (the generator itself never emits it, but app authors
+  // are explicitly allowed to hand-edit before committing — see the header
+  // comment every generated migration carries).
+  test("ADD COLUMN IF NOT EXISTS (hand-edited) still extends the table", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(dir, "0001_init.sql", `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY);`);
+      write(dir, "0002_add-col.sql", `ALTER TABLE "read_a" ADD COLUMN IF NOT EXISTS "title" text;`);
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("read_a")?.columns ?? [])].sort()).toEqual(["id", "title"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("DROP COLUMN IF EXISTS (hand-edited) still removes the column", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_init.sql",
+        `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY, "title" text);`,
+      );
+      write(dir, "0002_drop-col.sql", `ALTER TABLE "read_a" DROP COLUMN IF EXISTS "title";`);
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("read_a")?.columns ?? [])]).toEqual(["id"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("commented-out destructive DROP TABLE is not replayed", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(dir, "0001_init.sql", `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY);`);
+      write(
+        dir,
+        "0002_drop.sql",
+        `-- DESTRUCTIVE: DROP TABLE IF EXISTS "read_a";  -- uncomment + ensure backup`,
+      );
+      const replayed = replayMigrationsDir(dir);
+      expect([...replayed.keys()]).toEqual(["read_a"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("diffReplayAgainstSnapshot", () => {
+  test("clean: replayed schema matches snapshot exactly", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_init.sql",
+        `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY, "title" text);`,
+      );
+      const snapshot = snapshotFromMetas([
+        meta("read_a", [
+          { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
+          { name: "title", pgType: "text", notNull: false },
+        ]),
+      ]);
+      const mismatches = diffReplayAgainstSnapshot(replayMigrationsDir(dir), snapshot);
+      expect(mismatches).toEqual([]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  // Reproduces the kumiko-studio 0016 incident: the snapshot correctly
+  // records store_api_tokens, but the migration file that's supposed to
+  // create it is an accidental copy of an earlier file (creates read_accounts
+  // again instead) — CI must fail loud instead of shipping a table that only
+  // ever exists on paper.
+  test("misgenerated migration: snapshot expects a table no file actually creates", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_account-entity.sql",
+        `CREATE TABLE IF NOT EXISTS "read_accounts" ("id" uuid PRIMARY KEY, "stripe_customer_id" text);`,
+      );
+      write(
+        dir,
+        "0002_add-personal-access-tokens.sql",
+        // bug: this should create store_api_tokens, but it's a copy of 0001
+        `CREATE TABLE IF NOT EXISTS "read_accounts" ("id" uuid PRIMARY KEY, "stripe_customer_id" text);`,
+      );
+      const snapshot = snapshotFromMetas([
+        meta("read_accounts", [
+          { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
+          { name: "stripe_customer_id", pgType: "text", notNull: false },
+        ]),
+        meta("store_api_tokens", [
+          { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
+          { name: "token_hash", pgType: "text", notNull: true },
+        ]),
+      ]);
+      const mismatches = diffReplayAgainstSnapshot(replayMigrationsDir(dir), snapshot);
+      expect(mismatches).toEqual([
+        {
+          tableName: "store_api_tokens",
+          kind: "missing-table",
+          detail: 'snapshot expects "store_api_tokens" but no migration file creates it',
+        },
+      ]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("column drift: migration creates a table with the wrong columns", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(dir, "0001_init.sql", `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY);`);
+      const snapshot = snapshotFromMetas([
+        meta("read_a", [
+          { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
+          { name: "title", pgType: "text", notNull: false },
+        ]),
+      ]);
+      const mismatches = diffReplayAgainstSnapshot(replayMigrationsDir(dir), snapshot);
+      expect(mismatches).toEqual([
+        { tableName: "read_a", kind: "column-drift", detail: "missing columns: title" },
+      ]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("unexpected table: migrations create a table the snapshot doesn't know about", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(dir, "0001_init.sql", `CREATE TABLE IF NOT EXISTS "orphan" ("id" uuid PRIMARY KEY);`);
+      const mismatches = diffReplayAgainstSnapshot(replayMigrationsDir(dir), snapshotFromMetas([]));
+      expect(mismatches).toEqual([
+        {
+          tableName: "orphan",
+          kind: "unexpected-table",
+          detail: 'migrations create "orphan" but .snapshot.json has no entry for it',
+        },
+      ]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/db/index.ts

@@ -119,6 +119,13 @@ export {
 } from "./rebuild-marker";
 export { seedReferenceData } from "./reference-data";
 export { renderTableDdl, renderTablesDdl } from "./render-ddl";
+export {
+  diffReplayAgainstSnapshot,
+  type ReplayedSchema,
+  type ReplayedTable,
+  type ReplayMismatch,
+  replayMigrationsDir,
+} from "./replay-migration-sql";
 export { tableExists } from "./schema-inspection";
 export {
   buildBaseColumns,

package/src/db/replay-migration-sql.ts

@@ -0,0 +1,152 @@
+// Build-time, DB-free replay: reads the checked-in `kumiko/migrations/*.sql`
+// files in sequence order and reconstructs the table/column shape they
+// actually produce — then that gets diffed against `.snapshot.json`.
+//
+// Catches the class of bug where a migration file's *content* silently
+// drifts from what its filename/snapshot-entry claims (e.g. a copy-paste
+// from an earlier migration): `kumiko schema validate`'s other checks only
+// compare ENTITY_METAS ↔ snapshot, never the committed SQL bytes against
+// either. Reuses `loadMigrationsFromDir`'s statement-splitting so the replay
+// sees exactly what the real runner would execute.
+
+import type { Snapshot } from "./migrate-generator";
+import { loadMigrationsFromDir } from "./migrate-runner";
+
+export type ReplayedTable = {
+  readonly columns: ReadonlySet<string>;
+};
+
+export type ReplayedSchema = ReadonlyMap<string, ReplayedTable>;
+
+// Splits a parenthesized column-list body on top-level commas — depth-aware
+// so commas inside `numeric(10,2)` or `DEFAULT gen_random_uuid()` don't
+// fracture a column definition.
+function splitTopLevel(body: string): readonly string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of body) {
+    if (ch === "(") depth++;
+    if (ch === ")") depth--;
+    if (ch === "," && depth === 0) {
+      parts.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim().length > 0) parts.push(current);
+  return parts;
+}
+
+function parseColumnNames(body: string): Set<string> {
+  const columns = new Set<string>();
+  for (const part of splitTopLevel(body)) {
+    const trimmed = part.trim();
+    if (/^CONSTRAINT\b/i.test(trimmed)) continue; // composite-PK line, not a column
+    const match = trimmed.match(/^"([^"]+)"/);
+    if (match?.[1] !== undefined) columns.add(match[1]);
+  }
+  return columns;
+}
+
+function applyStatement(schema: Map<string, { columns: Set<string> }>, statement: string): void {
+  const create = statement.match(
+    /^CREATE TABLE\s+(?:IF NOT EXISTS\s+)?"([^"]+)"\s*\(([\s\S]*)\);?\s*$/i,
+  );
+  const createTableName = create?.[1];
+  const createBody = create?.[2];
+
+  const addColumn = statement.match(
+    /^ALTER TABLE\s+"([^"]+)"\s+ADD COLUMN\s+(?:IF NOT EXISTS\s+)?"([^"]+)"/i,
+  );
+  const addColumnTable = addColumn?.[1];
+  const addColumnName = addColumn?.[2];
+
+  const dropTable = statement.match(/^DROP TABLE\s+(?:IF EXISTS\s+)?"([^"]+)"/i);
+  const dropTableName = dropTable?.[1];
+
+  const dropColumn = statement.match(
+    /^ALTER TABLE\s+"([^"]+)"\s+DROP COLUMN\s+(?:IF EXISTS\s+)?"([^"]+)"/i,
+  );
+  const dropColumnTable = dropColumn?.[1];
+  const dropColumnName = dropColumn?.[2];
+
+  if (createTableName !== undefined && createBody !== undefined) {
+    schema.set(createTableName, { columns: parseColumnNames(createBody) });
+  } else if (addColumnTable !== undefined && addColumnName !== undefined) {
+    const table = schema.get(addColumnTable);
+    if (table) table.columns.add(addColumnName);
+    else schema.set(addColumnTable, { columns: new Set([addColumnName]) });
+  } else if (dropTableName !== undefined) {
+    schema.delete(dropTableName);
+  } else if (dropColumnTable !== undefined && dropColumnName !== undefined) {
+    schema.get(dropColumnTable)?.columns.delete(dropColumnName);
+  }
+  // else: CREATE INDEX, ALTER COLUMN (TYPE/DEFAULT/NOT NULL) and everything
+  // else don't change the table/column shape this replay tracks.
+}
+
+// Reads `<migrationsDir>/*.sql` in sequence order and replays every
+// CREATE/ALTER/DROP TABLE statement to reconstruct the resulting schema.
+export function replayMigrationsDir(migrationsDir: string): ReplayedSchema {
+  const schema = new Map<string, { columns: Set<string> }>();
+  for (const migration of loadMigrationsFromDir(migrationsDir)) {
+    for (const statement of migration.statements) applyStatement(schema, statement);
+  }
+  return schema;
+}
+
+export type ReplayMismatch = {
+  readonly tableName: string;
+  readonly kind: "missing-table" | "unexpected-table" | "column-drift";
+  readonly detail: string;
+};
+
+// Compares what the migration files actually produce (`replayed`) against
+// what `.snapshot.json` claims (`snapshot`) — the check that would have
+// caught kumiko-studio's 0016 misgeneration (snapshot correct, SQL wrong).
+export function diffReplayAgainstSnapshot(
+  replayed: ReplayedSchema,
+  snapshot: Snapshot,
+): readonly ReplayMismatch[] {
+  const mismatches: ReplayMismatch[] = [];
+  const snapshotTableNames = new Set(snapshot.tables.map((t) => t.tableName));
+
+  for (const meta of snapshot.tables) {
+    const table = replayed.get(meta.tableName);
+    if (!table) {
+      mismatches.push({
+        tableName: meta.tableName,
+        kind: "missing-table",
+        detail: `snapshot expects "${meta.tableName}" but no migration file creates it`,
+      });
+      continue;
+    }
+    const expected = new Set(meta.columns.map((c) => c.name));
+    const missing = [...expected].filter((c) => !table.columns.has(c));
+    const extra = [...table.columns].filter((c) => !expected.has(c));
+    if (missing.length > 0 || extra.length > 0) {
+      const parts: string[] = [];
+      if (missing.length > 0) parts.push(`missing columns: ${missing.join(", ")}`);
+      if (extra.length > 0) parts.push(`unexpected columns: ${extra.join(", ")}`);
+      mismatches.push({
+        tableName: meta.tableName,
+        kind: "column-drift",
+        detail: parts.join("; "),
+      });
+    }
+  }
+
+  for (const tableName of replayed.keys()) {
+    if (!snapshotTableNames.has(tableName)) {
+      mismatches.push({
+        tableName,
+        kind: "unexpected-table",
+        detail: `migrations create "${tableName}" but .snapshot.json has no entry for it`,
+      });
+    }
+  }
+
+  return mismatches;
+}

package/src/schema-cli.ts

@@ -14,6 +14,7 @@ import {
   baselineMigrations,
   createDbConnection,
   type DbConnection,
+  diffReplayAgainstSnapshot,
   fetchAppliedMigrations,
   generateMigration,
   loadMigrationsFromDir,
@@ -21,6 +22,7 @@ import {
   readRebuildMarker,
   rebuildTablesFromDiff,
   type renderTablesDdl,
+  replayMigrationsDir,
   runMigrationsFromDir,
   tableExists,
   writeRebuildMarker,
@@ -198,11 +200,18 @@ export async function runSchemaCli(
 
     case "validate": {
       // Static, DB-free boot-blocking checks for CI — catches "this won't boot"
-      // before deploy. Two layers, no database:
+      // before deploy. Three layers, no database:
       //   1. schema drift: would `generate` write a migration? (= an entity was
       //      added/changed but never generated → missing table → prod 500)
       //   2. boot validity: validateBoot over the composed FEATURES (QN/screen/
       //      nav/role refs). Runs only if kumiko/schema.ts exports FEATURES.
+      //   3. migration-content drift: replay every committed *.sql file and
+      //      diff the result against .snapshot.json — catches a migration
+      //      file whose SQL body doesn't match what its own snapshot entry
+      //      claims (e.g. an accidental copy-paste from an earlier file).
+      //      Layer 1 alone misses this: it only compares ENTITY_METAS to the
+      //      snapshot, never the snapshot to the SQL that's supposed to have
+      //      produced it.
       // The DB-level gate (assertKumikoSchemaCurrent) stays at boot/deploy.
       if (!existsSync(schemaFile)) {
         out.err(`  ${schemaFile} fehlt.`);
@@ -262,6 +271,28 @@ export async function runSchemaCli(
         );
       }
 
+      // 3. Migration-content drift — replay the committed *.sql files and
+      // diff the reconstructed schema against .snapshot.json.
+      const committedSnapshot = existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
+      if (existsSync(migrationsDir) && committedSnapshot !== null) {
+        const replayed = replayMigrationsDir(migrationsDir);
+        const mismatches = diffReplayAgainstSnapshot(replayed, committedSnapshot);
+        if (mismatches.length === 0) {
+          out.log("  ✓ migrations: committed SQL matches .snapshot.json");
+        } else {
+          ok = false;
+          out.err(
+            "  ✗ migration-content drift: committed *.sql files don't produce .snapshot.json.",
+          );
+          for (const m of mismatches) {
+            out.err(`    ${m.tableName} (${m.kind}): ${m.detail}`);
+          }
+          out.err(
+            "    Fix: a migration file's body doesn't match what it (or the snapshot) claims — hand-fix the file, or ship a corrective migration if it's already applied in prod.",
+          );
+        }
+      }
+
       return ok ? 0 : 1;
     }