@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/auth-mfa.md

@@ -0,0 +1,323 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/auth-mfa. Do not edit. -->
+
+# auth-mfa
+
+createAuthMfaFeature — TOTP/2FA enrollment, login challenge, and recovery codes wired into auth-email-password.
+
+## README
+
+# Sample: Auth MFA (TOTP/2FA)
+
+**I want users to be able to enable TOTP-based 2FA, and login to become a two-step challenge once they have.**
+
+## What this sample shows
+
+The production wiring shape: mount `createAuthMfaFeature()` next to `createAuthEmailPasswordFeature()`, thread its status-checker into the login handler, and give `auth: { mfaVerifyHandler: ... }` to `buildServer`. From there the framework handles the rest — a password-only login for an MFA-enrolled user returns a challenge token instead of a JWT, and `POST /auth/mfa/verify` completes it with a TOTP or recovery code.
+
+## The wiring in 4 sentences
+
+1. `createAuthMfaFeature({ setupTokenSecret, challengeTokenSecret, issuer })` builds the feature; `mfaStatusCheckerFromFeature(mfaFeature)` reads its login-status callback back off.
+2. That callback goes into `createAuthEmailPasswordFeature({ mfaStatusChecker: ... })` — `login.write.ts` calls it after the password check to decide whether to mint a JWT or a challenge.
+3. `buildServer({ auth: { mfaVerifyHandler: AuthMfaHandlers.verify } })` mounts `POST /auth/mfa/verify`, a framework route (not a dispatcher write-handler) with its own rate limiter, since it runs before a JWT exists.
+4. If `sessions` is mounted too, `bindMfaRevokeAllOtherSessionsFromFeature(mfaFeature)?.(sessionCallbacks.sessionRevokeAllOthers)` wires "enable/disable/regenerate signs out every other session."
+
+## What to copy into your app
+
+```ts illustration
+const mfaFeature = createAuthMfaFeature({
+  setupTokenSecret: config.mfaSetupSecret,
+  challengeTokenSecret: config.mfaChallengeSecret,
+  issuer: "Your App",
+});
+const sessionCallbacks = createSessionCallbacks({ db });
+bindMfaRevokeAllOtherSessionsFromFeature(mfaFeature)?.(
+  sessionCallbacks.sessionRevokeAllOthers,
+);
+
+const server = buildServer({
+  registry: buildRegistry([
+    createAuthEmailPasswordFeature({
+      mfaStatusChecker: mfaStatusCheckerFromFeature(mfaFeature),
+    }),
+    createSessionsFeature({
+      autoRevokeOnPasswordChange: sessionCallbacks.sessionMassRevoker,
+    }),
+    mfaFeature,
+    // ... other features
+  ]),
+  context: { db, /* ... */ },
+  jwtSecret: process.env.JWT_SECRET,
+  auth: {
+    membershipQuery: "tenant:query:memberships",
+    loginHandler: "auth-email-password:[REDACTED:API key param]",
+    mfaVerifyHandler: AuthMfaHandlers.verify,
+    sessionCreator: sessionCallbacks.sessionCreator,
+    sessionRevoker: sessionCallbacks.sessionRevoker,
+    sessionChecker: sessionCallbacks.sessionChecker,
+  },
+});
+```
+
+Apps built via `runDevApp`/`runProdApp` (the dev-server bootstrap used by `create-kumiko-app`) get all of this automatically — just add `createAuthMfaFeature(...)` to `APP_FEATURES`. `composeFeatures` threads the status-checker and the bootstrap wires the session-revoke bind and the verify route for you. This sample shows the raw contract those helpers implement.
+
+## Design rules
+
+1. **Enrollment is stateless until confirmed.** `enable-start` returns a signed setup token (QR + secret + 8 recovery codes) — nothing is persisted until `enable-confirm` proves the user scanned it with a valid TOTP code.
+2. **The TOTP secret is envelope-encrypted at rest**, same `MasterKeyProvider` as `secrets`/`config` — no separate crypto story to maintain.
+3. **`/auth/mfa/verify` is a framework route, not a dispatcher handler.** It runs before a JWT exists, so it gets its own IP-keyed rate limiter (`mfaVerifyRateLimit`), independent of the login rate limiter.
+4. **Recovery codes are single-use.** Each of the 8 generated codes completes exactly one login challenge, then it's burned.
+5. **MFA state changes revoke every OTHER live session** (stolen-session defense) — never the session that made the change.
+6. **Enforcement is opt-in.** Without a tenant enabling `auth-mfa:config:required`, users choose for themselves whether to enroll.
+
+## Tests
+
+- **Baseline:** a user without MFA enrolled still gets a JWT straight from `/auth/login`.
+- **End-to-end:** enroll via `enable-start`/`enable-confirm`, log in (gets a challenge, no JWT), complete via `/auth/mfa/verify` (gets a JWT) — copies the `buildServer({ auth: ... })` block from the sample comment verbatim.
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Auth MFA Sample — Integration Test
+//
+// Drives the wiring from the sample's comment snippet end-to-end against
+// real HTTP + DB. If a reader copies the buildServer({...}) block verbatim,
+// the resulting app behaves like this test asserts: login is two-step once
+// MFA is enabled, and a valid TOTP code completes it.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  AuthHandlers,
+  createAuthEmailPasswordFeature,
+  hashPassword,
+} from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import {
+  configValuesTable,
+  createConfigFeature,
+} from "@cosmicdrift/kumiko-bundled-features/config";
+import {
+  createTenantFeature,
+  tenantEntity,
+  tenantMembershipsTable,
+} from "@cosmicdrift/kumiko-bundled-features/tenant";
+import { seedTenantMembership } from "@cosmicdrift/kumiko-bundled-features/tenant/seeding";
+import {
+  createUserFeature,
+  UserHandlers,
+  userEntity,
+  userTable,
+} from "@cosmicdrift/kumiko-bundled-features/user";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
+import {
+  AuthMfaHandlers,
+  base32Decode,
+  createAuthMfaFeature,
+  currentTotpCode,
+  mfaStatusCheckerFromFeature,
+  userMfaEntity,
+} from "../feature";
+
+const TENANT: TenantId = testTenantId(1);
+const SETUP_TOKEN_SECRET = "test-mfa-setup-secret-at-least-32-bytes-long!!";
+const CHALLENGE_TOKEN_SECRET = "test-mfa-challenge-secret-at-least-32-bytes!!";
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  configureEntityFieldEncryption(createTestEnvelopeCipher());
+
+  const mfaFeature = createAuthMfaFeature({
+    setupTokenSecret: SETUP_TOKEN_SECRET,
+    challengeTokenSecret: CHALLENGE_TOKEN_SECRET,
+    issuer: "Kumiko Sample",
+  });
+
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createUserFeature(),
+      createTenantFeature(),
+      createAuthEmailPasswordFeature({
+        mfaStatusChecker: mfaStatusCheckerFromFeature(mfaFeature),
+      }),
+      mfaFeature,
+    ],
+    authConfig: {
+      membershipQuery: "tenant:query:memberships",
+      loginHandler: AuthHandlers.login,
+      mfaVerifyHandler: AuthMfaHandlers.verify,
+    },
+  });
+
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, userMfaEntity);
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafePushTables(stack.db, { configValuesTable, tenantMembershipsTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+  configureEntityFieldEncryption(undefined);
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+});
+
+describe("auth-mfa sample wiring", () => {
+  test("login without MFA enrolled returns a JWT directly", async () => {
+    const hash = await hashPassword("super-long-password");
+    const created = await stack.http.writeOk<{ id: string }>(
+      UserHandlers.create,
+      { email: "plain@example.com", passwordHash: hash, displayName: "Plain" },
+      TestUsers.systemAdmin,
+    );
+    await seedTenantMembership(stack.db, { userId: created.id, tenantId: TENANT, roles: ["User"] });
+
+    const res = await stack.http.raw("POST", "/api/auth/login", {
+      email: "plain@example.com",
+      password: "super-long-password",
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { token?: string; mfaRequired?: boolean };
+    expect(body.token).toBeTypeOf("string");
+    expect(body.mfaRequired).toBeUndefined();
+  });
+
+  test("login with MFA enrolled challenges, then verify mints the JWT", async () => {
+    const hash = await hashPassword("super-long-password");
+    const created = await stack.http.writeOk<{ id: string }>(
+      UserHandlers.create,
+      { email: "mfa@example.com", passwordHash: hash, displayName: "Mfa" },
+      TestUsers.systemAdmin,
+    );
+    await seedTenantMembership(stack.db, { userId: created.id, tenantId: TENANT, roles: ["User"] });
+    const user = { ...TestUsers.user, id: created.id, tenantId: TENANT };
+
+    const start = await stack.http.writeOk<{ setupToken: string; otpauthUri: string }>(
+      AuthMfaHandlers.enableStart,
+      { accountLabel: "mfa@example.com" },
+      user,
+    );
+    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) },
+      user,
+    );
+
+    const loginRes = await stack.http.raw("POST", "/api/auth/login", {
+      email: "mfa@example.com",
+      password: "super-long-password",
+    });
+    expect(loginRes.status).toBe(200);
+    const challenge = (await loginRes.json()) as {
+      token?: string;
+      mfaRequired?: boolean;
+      challengeToken?: string;
+    };
+    expect(challenge.token).toBeUndefined();
+    expect(challenge.mfaRequired).toBe(true);
+    expect(challenge.challengeToken).toBeTypeOf("string");
+
+    const verifyRes = await stack.http.raw("POST", "/api/auth/mfa/verify", {
+      challengeToken: challenge.challengeToken,
+      code: currentTotpCode(secret),
+    });
+    expect(verifyRes.status).toBe(200);
+    const { token } = (await verifyRes.json()) as { token: string };
+    expect(token).toBeTypeOf("string");
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Auth MFA (TOTP/2FA) Sample
+//
+// Shows the production-wiring shape: mount `createAuthMfaFeature()` next to
+// `createAuthEmailPasswordFeature()`, thread its status-checker into the
+// login handler, and (if `sessions` is mounted) bind its revoke-all-other-
+// sessions callback. From there the framework handles the rest — login
+// returns a challenge instead of a JWT when MFA is enabled, POST
+// /auth/mfa/verify completes it, and every OTHER live session gets signed
+// out whenever the account's MFA state changes (enable/disable/regenerate).
+//
+// What to copy into your own app:
+//
+//   const mfaFeature = createAuthMfaFeature({
+//     setupTokenSecret: config.mfaSetupSecret,
+//     challengeTokenSecret: config.mfaChallengeSecret,
+//     issuer: "Your App",
+//   });
+//   const sessionCallbacks = createSessionCallbacks({ db });
+//   bindMfaRevokeAllOtherSessionsFromFeature(mfaFeature)?.(
+//     sessionCallbacks.sessionRevokeAllOthers,
+//   );
+//
+//   const server = buildServer({
+//     registry: buildRegistry([
+//       createAuthEmailPasswordFeature({
+//         mfaStatusChecker: mfaStatusCheckerFromFeature(mfaFeature),
+//       }),
+//       createSessionsFeature({
+//         autoRevokeOnPasswordChange: sessionCallbacks.sessionMassRevoker,
+//       }),
+//       mfaFeature,
+//       // ... other features
+//     ]),
+//     context: { db, ... },
+//     jwtSecret: config.jwtSecret,
+//     auth: {
+//       membershipQuery: "tenant:query:memberships",
+//       loginHandler: "auth-email-password:[REDACTED:API key param]",
+//       mfaVerifyHandler: AuthMfaHandlers.verify,
+//       sessionCreator: sessionCallbacks.sessionCreator,
+//       sessionRevoker: sessionCallbacks.sessionRevoker,
+//       sessionChecker: sessionCallbacks.sessionChecker,
+//     },
+//   });
+//
+// Apps built via runDevApp/runProdApp (the dev-server bootstrap) get all of
+// this for free just by adding `createAuthMfaFeature(...)` to APP_FEATURES —
+// composeFeatures threads the status-checker and the bootstrap wraps the
+// session-revoke bind and the /auth/mfa/verify route automatically. This
+// sample shows the raw wiring contract those helpers implement.
+//
+// Design rules the sample demonstrates:
+//
+//  1. Login becomes two-step once MFA is enabled. `POST /auth/login` returns
+//     `{ mfaRequired: true, challengeToken }` instead of a JWT; the client
+//     completes with `POST /auth/mfa/verify`.
+//  2. Enrollment is stateless until confirmed. `enable-start` returns a
+//     signed setup token (QR + recovery codes) — nothing is persisted until
+//     `enable-confirm` proves the user scanned it with a valid TOTP code.
+//  3. Recovery codes are single-use. Each of the 8 generated codes can
+//     complete exactly one login challenge, then it's burned.
+//  4. Every MFA state change signs out every OTHER live session (stolen-
+//     session defense) — but never the session that made the change.
+export {
+  AuthMfaHandlers,
+  base32Decode,
+  bindMfaRevokeAllOtherSessionsFromFeature,
+  createAuthMfaFeature,
+  mfaStatusCheckerFromFeature,
+  userMfaEntity,
+} from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
+export { currentTotpCode } from "@cosmicdrift/kumiko-bundled-features/auth-mfa/testing";
+```