@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

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

@@ -0,0 +1,319 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  createTestEnvelopeCipher,
+  expectErrorIncludes,
+  seedRow,
+} from "@cosmicdrift/kumiko-framework/testing";
+import { createConfigFeature } from "../../config";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { createTenantFeature } from "../../tenant";
+import { tenantMembershipsTable } from "../../tenant/membership-table";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { USER_STATUS } from "../../user";
+import { createUserFeature } from "../../user/feature";
+import { userEntity, userTable } from "../../user/schema/user";
+import { base32Decode } from "../base32";
+import { AuthMfaHandlers } from "../constants";
+import { createAuthMfaFeature } from "../feature";
+import { signMfaChallengeToken } from "../mfa-challenge-token";
+import { userMfaEntity } from "../schema/user-mfa";
+import { currentTotpCode } from "../totp";
+
+let stack: TestStack;
+
+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!!";
+
+// Handler access is `{ roles: ["all"] }`, matching how the framework route
+// dispatches with a guest identity — a literal here is enough since the
+// handler derives everything from the challenge-token payload, not from
+// event.user.
+const GUEST: SessionUser = {
+  id: "00000000-0000-0000-0000-000000000000",
+  tenantId: "00000000-0000-4000-8000-000000000001" as TenantId,
+  roles: ["all"],
+};
+
+beforeAll(async () => {
+  const encryption = createTestEnvelopeCipher();
+  configureEntityFieldEncryption(encryption);
+  const resolver = createConfigResolver({ cipher: encryption });
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createUserFeature(),
+      createTenantFeature(),
+      createAuthMfaFeature({
+        setupTokenSecret: SETUP_TOKEN_SECRET,
+        issuer: "Kumiko Test",
+        challengeTokenSecret: CHALLENGE_TOKEN_SECRET,
+      }),
+    ],
+    extraContext: { configResolver: resolver, configEncryption: encryption },
+  });
+  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();
+});
+
+async function enableMfaFor(idSeed: number): Promise<{
+  user: ReturnType<typeof createTestUser>;
+  secret: Buffer;
+  recoveryCodes: string[];
+}> {
+  const user = createTestUser({ id: idSeed, roles: ["User"] });
+  const start = await stack.http.writeOk<{
+    setupToken: string;
+    otpauthUri: string;
+    recoveryCodes: string[];
+  }>(AuthMfaHandlers.enableStart, { accountLabel: `user-${idSeed}@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,
+  );
+  // verify.write.ts re-checks tenant membership AND the user's own row
+  // (status gate) the way login.write.ts does — auth-mfa never writes a
+  // read_users row itself (enableStart/enableConfirm only touch user-mfa),
+  // so both need seeding here, not just per-test where a scenario cares.
+  await seedRow(stack.db, tenantMembershipsTable, {
+    userId: user.id,
+    tenantId: user.tenantId,
+    roles: JSON.stringify(["User"]),
+  });
+  await seedRow(stack.db, userTable, {
+    id: user.id,
+    tenantId: user.tenantId,
+    email: `user-${user.id}@example.com`,
+    passwordHash: "h",
+    displayName: `Test User ${idSeed}`,
+    locale: "de",
+    emailVerified: true,
+    roles: "[]",
+    status: USER_STATUS.Active,
+  });
+  return { user, secret, recoveryCodes: start.recoveryCodes };
+}
+
+function challengeFor(userId: string, tenantId: TenantId): string {
+  return signMfaChallengeToken({ userId, tenantId }, 10, CHALLENGE_TOKEN_SECRET).token;
+}
+
+describe("mfa verify — completes a two-step login", () => {
+  test("a valid TOTP code succeeds and returns the full session", async () => {
+    const { user, secret } = await enableMfaFor(1);
+    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);
+  });
+
+  test("a wrong TOTP code is rejected", async () => {
+    const { user } = await enableMfaFor(2);
+    const challengeToken = challengeFor(user.id, user.tenantId);
+    const err = await stack.http.writeErr(
+      AuthMfaHandlers.verify,
+      { challengeToken, code: "000000" },
+      GUEST,
+    );
+    expectErrorIncludes(err, "invalid_totp_code");
+  });
+
+  test("a valid recovery code succeeds, and the SAME code is rejected on replay", async () => {
+    const { user, recoveryCodes } = await enableMfaFor(3);
+    const code = recoveryCodes[0];
+    if (code === undefined) throw new Error("no recovery code minted");
+
+    const challengeA = challengeFor(user.id, user.tenantId);
+    const res = await stack.http.writeOk<{ session: SessionUser }>(
+      AuthMfaHandlers.verify,
+      { challengeToken: challengeA, code },
+      GUEST,
+    );
+    expect(res.session.id).toBe(user.id);
+
+    // Advisor-flagged trap: a recovery code must be single-use. Re-verify
+    // with a FRESH challenge token (a real attacker would just re-login)
+    // but the SAME recovery code — it must now be rejected because
+    // verify.write.ts persists remainingHashes on the row.
+    const challengeB = challengeFor(user.id, user.tenantId);
+    const err = await stack.http.writeErr(
+      AuthMfaHandlers.verify,
+      { challengeToken: challengeB, code },
+      GUEST,
+    );
+    expectErrorIncludes(err, "invalid_totp_code");
+  });
+
+  test("an exact-duplicate verify (same challenge token, same code) is rejected", async () => {
+    const { user, secret } = await enableMfaFor(4);
+    const challengeToken = challengeFor(user.id, user.tenantId);
+
+    await stack.http.writeOk<{ session: SessionUser }>(
+      AuthMfaHandlers.verify,
+      { challengeToken, code: currentTotpCode(secret) },
+      GUEST,
+    );
+
+    // Same challenge token, same (still time-window-valid) code — rejected
+    // by the TOTP-counter burn inside verifyMfaFactor before the challenge-
+    // token burn is even reached (that burn now happens after success).
+    const err = await stack.http.writeErr(
+      AuthMfaHandlers.verify,
+      { challengeToken, code: currentTotpCode(secret) },
+      GUEST,
+    );
+    expectErrorIncludes(err, "invalid_totp_code");
+  });
+
+  test("a TOTP code cannot be replayed across a FRESH challenge token (RFC 6238 §5.2)", async () => {
+    const { user, secret } = await enableMfaFor(105);
+    const code = currentTotpCode(secret);
+
+    const challengeA = challengeFor(user.id, user.tenantId);
+    await stack.http.writeOk<{ session: SessionUser }>(
+      AuthMfaHandlers.verify,
+      { challengeToken: challengeA, code },
+      GUEST,
+    );
+
+    // A DIFFERENT challenge token (as a real re-login would mint) but the
+    // SAME still-time-window-valid code — this is the actual attack this
+    // finding is about: a phished/shoulder-surfed code used for a parallel
+    // login, not a naive replay of the whole prior request.
+    const challengeB = challengeFor(user.id, user.tenantId);
+    const err = await stack.http.writeErr(
+      AuthMfaHandlers.verify,
+      { challengeToken: challengeB, code },
+      GUEST,
+    );
+    expectErrorIncludes(err, "invalid_totp_code");
+  });
+
+  test("a malformed challenge token is rejected without leaking account state", async () => {
+    const err = await stack.http.writeErr(
+      AuthMfaHandlers.verify,
+      { challengeToken: "not-a-real-token", code: "123456" },
+      GUEST,
+    );
+    expectErrorIncludes(err, "invalid_challenge_token");
+  });
+
+  test("a challenge token for a user without MFA enabled is rejected", async () => {
+    const challengeToken = challengeFor("verify-never-enabled-1", GUEST.tenantId);
+    const err = await stack.http.writeErr(
+      AuthMfaHandlers.verify,
+      { challengeToken, code: "123456" },
+      GUEST,
+    );
+    expectErrorIncludes(err, "invalid_challenge_token");
+  });
+});
+
+describe("mfa verify — re-checks account state the way login.write.ts does", () => {
+  test("membership revoked between login and verify → challenge rejected, no fallback to global roles", async () => {
+    const { user, secret } = await enableMfaFor(5);
+    const challengeToken = challengeFor(user.id, user.tenantId);
+
+    // Simulate the membership being pulled after the challenge token was
+    // issued but before verify runs — the exact gap login.write.ts's
+    // noMembership() guards against.
+    await asRawClient(stack.db).unsafe(
+      `DELETE FROM "${tenantMembershipsTable.tableName}" WHERE user_id = $1 AND tenant_id = $2`,
+      [user.id, user.tenantId],
+    );
+
+    const err = await stack.http.writeErr(
+      AuthMfaHandlers.verify,
+      { challengeToken, code: currentTotpCode(secret) },
+      GUEST,
+    );
+    expectErrorIncludes(err, "invalid_challenge_token");
+  });
+
+  test("account restricted between login and verify → challenge rejected", async () => {
+    const { user, secret } = await enableMfaFor(6);
+    const challengeToken = challengeFor(user.id, user.tenantId);
+
+    // enableMfaFor already seeded the user row Active — flip it to simulate
+    // a restriction landing between login and verify.
+    await asRawClient(stack.db).unsafe(
+      `UPDATE "${userTable.tableName}" SET status = $1 WHERE id = $2`,
+      [USER_STATUS.Restricted, user.id],
+    );
+
+    const err = await stack.http.writeErr(
+      AuthMfaHandlers.verify,
+      { challengeToken, code: currentTotpCode(secret) },
+      GUEST,
+    );
+    expectErrorIncludes(err, "invalid_challenge_token");
+  });
+
+  test("user row deleted between login and verify → challenge rejected (the !userRow gate)", async () => {
+    const { user, secret } = await enableMfaFor(7);
+    const challengeToken = challengeFor(user.id, user.tenantId);
+
+    // Simulate the read_users row disappearing after the challenge token
+    // was issued but before verify runs — hits verify.write.ts's
+    // `if (!userRow) return invalidChallengeToken()` gate directly, distinct
+    // from a revoked membership or a restricted-but-present user row.
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}" WHERE id = $1`, [
+      user.id,
+    ]);
+
+    const err = await stack.http.writeErr(
+      AuthMfaHandlers.verify,
+      { challengeToken, code: currentTotpCode(secret) },
+      GUEST,
+    );
+    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/base32.ts

@@ -0,0 +1,51 @@
+// RFC 4648 Base32 (no padding) — the encoding TOTP secrets and otpauth://
+// URIs use. No external dependency: the alphabet lookup is ~20 lines and every
+// authenticator app (Google/Microsoft/Authy) expects exactly this variant.
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+
+export function base32Encode(bytes: Buffer): string {
+  let bits = 0;
+  let value = 0;
+  let output = "";
+  for (const byte of bytes) {
+    value = (value << 8) | byte;
+    bits += 8;
+    while (bits >= 5) {
+      output += ALPHABET[(value >>> (bits - 5)) & 0x1f];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) {
+    output += ALPHABET[(value << (5 - bits)) & 0x1f];
+  }
+  return output;
+}
+
+// Accepts lowercase and stray whitespace (authenticator apps and users
+// copy-pasting secrets are inconsistent about casing) — normalizes case and
+// strips whitespace before decoding, but throws on a genuinely invalid
+// character so a corrupted stored secret fails loud at read time instead of
+// silently producing wrong codes.
+export function base32Decode(encoded: string): Buffer {
+  const clean = encoded.trim().toUpperCase().replace(/\s+/g, "").replace(/=+$/, "");
+  let bits = 0;
+  let value = 0;
+  const bytes: number[] = [];
+  for (const char of clean) {
+    const index = ALPHABET.indexOf(char);
+    if (index === -1) throw new Error(`base32Decode: invalid character "${char}"`);
+    value = (value << 5) | index;
+    bits += 5;
+    if (bits >= 8) {
+      bytes.push((value >>> (bits - 8)) & 0xff);
+      bits -= 8;
+    }
+  }
+  // Leftover bits must be padding zeros (a canonical-length encoding never
+  // leaves a full byte's worth, i.e. >=5 residual bits) — anything else means
+  // truncated/non-canonical input decoded to the wrong byte count.
+  if (bits >= 5 || (value & ((1 << bits) - 1)) !== 0) {
+    throw new Error("base32Decode: invalid length or non-zero padding bits");
+  }
+  return Buffer.from(bytes);
+}

package/src/auth-mfa/config.ts

@@ -0,0 +1,26 @@
+// Tenant-scoped enforcement policy: does a user need MFA to log in even if
+// they haven't opted in themselves? Default "optional" means the feature
+// is fully opt-in (existing tenants/users unaffected — no migration step).
+//
+// ponytail: "admins"/"all" HARD-BLOCK login for an unenrolled user (see
+// mfa-status-checker.ts's setupRequired branch) — there is no in-band way
+// for a blocked user to complete enrollment yet (that flow ships in PR3's
+// UI). Flipping this away from "optional" before PR3 locks out every
+// unenrolled matching user with no recovery path. Fine for a tenant that
+// enrolls its admins out-of-band first; a footgun otherwise.
+import { type ConfigKeyHandle, createTenantConfig } from "@cosmicdrift/kumiko-framework/engine";
+
+export const MFA_REQUIRED_POLICIES = ["optional", "admins", "all"] as const;
+export type MfaRequiredPolicy = (typeof MFA_REQUIRED_POLICIES)[number];
+
+export const mfaRequiredConfigHandle: ConfigKeyHandle<"select"> = {
+  name: "auth-mfa:config:required",
+  type: "select",
+};
+
+export function mfaRequiredConfigKey() {
+  return createTenantConfig("select", {
+    default: "optional" satisfies MfaRequiredPolicy,
+    options: [...MFA_REQUIRED_POLICIES],
+  });
+}

package/src/auth-mfa/constants.ts

@@ -0,0 +1,45 @@
+// @runtime client
+// Pure constants — client-marked so auth-mfa/web/ may import handler QNs
+// and the screen id without pulling the feature's server runtime barrel.
+// Qualified write-handler names — feature is registered as "auth-mfa", each
+// short `name` below gets auto-prefixed to "auth-mfa:write:<name>" by
+// r.writeHandler. Exported so cross-feature wiring (login.write.ts,
+// run-prod-app.ts) can reference them without hardcoding the string.
+export const AUTH_MFA_FEATURE = "auth-mfa" as const;
+
+export const AuthMfaHandlers = {
+  enableStart: "auth-mfa:write:enable-start",
+  enableStartPreauth: "auth-mfa:write:enable-start-preauth",
+  enableConfirm: "auth-mfa:write:enable-confirm",
+  enableConfirmPreauth: "auth-mfa:write:enable-confirm-preauth",
+  disable: "auth-mfa:write:disable",
+  regenerateRecovery: "auth-mfa:write:regenerate-recovery",
+  verify: "auth-mfa:write:verify",
+} as const;
+
+export const AuthMfaQueries = {
+  status: "auth-mfa:query:user-mfa:status",
+} as const;
+
+// Write-failure codes minted server-side into UnprocessableError (errors.ts).
+// The client reads the i18n key straight off the write result
+// (res.error.i18nKey) instead of re-deriving it from these codes.
+export const AuthMfaErrorCodes = {
+  mfaAlreadyEnabled: "mfa_already_enabled",
+  mfaNotEnabled: "mfa_not_enabled",
+  invalidSetupToken: "invalid_setup_token",
+  invalidTotpCode: "invalid_totp_code",
+  invalidRecoveryCode: "invalid_recovery_code",
+  invalidChallengeToken: "invalid_challenge_token",
+  tooManyAttempts: "too_many_attempts",
+} as const;
+
+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;
+
+// Dormant custom-screen id — see personal-access-tokens/feature.ts for the
+// same convention. App places it via r.nav in its logged-in settings area.
+export const MFA_ENABLE_SCREEN_ID = "auth-mfa-enable";

package/src/auth-mfa/db/queries.ts

@@ -0,0 +1,45 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventStoreExecutor, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
+import { userMfaEntity, userMfaTable } from "../schema/user-mfa";
+
+export type UserMfaRow = {
+  readonly id: string;
+  readonly version: number;
+  readonly userId: string;
+  readonly totpSecret: string;
+  readonly recoveryCodes: { readonly hashes: readonly string[] };
+  readonly enabledAt: string;
+  readonly lastUsedAt: string | null;
+};
+
+const executor = createEventStoreExecutor(userMfaTable, userMfaEntity, {
+  entityName: "user-mfa",
+});
+
+// `totpSecret`/`recoveryCodes` are `encrypted: true` — a raw fetchOne would
+// return ciphertext, not plaintext. fetchOne only locates the row's id (no
+// decryption needed for that); executor.detail() does the real, decrypting
+// read the same way every other entity handler does. `recoveryCodes` is
+// stored as a JSON string (schema/user-mfa.ts — both encryption layers need
+// a string value) — parsed back into `{ hashes }` here, once, for every
+// caller instead of each handler re-parsing it. A parse failure here means
+// stored data is corrupt (post-decrypt, not user input) — fail loud.
+export async function findUserMfaRow(db: TenantDb, user: SessionUser): Promise<UserMfaRow | null> {
+  const idLookup = await fetchOne<{ id: string }>(db, userMfaTable, {
+    userId: user.id,
+    tenantId: user.tenantId,
+  });
+  if (!idLookup) return null;
+  const detail = await executor.detail({ id: idLookup.id }, user, db);
+  if (!detail) return null;
+  // @cast-boundary engine-payload — executor.detail returns a decrypted,
+  // untyped Record; the userMfa entity's own field shape narrows it.
+  const row = detail as Omit<UserMfaRow, "recoveryCodes"> & { recoveryCodes: string };
+  const recoveryCodes = parseJsonOrThrow<{ hashes: readonly string[] }>(
+    row.recoveryCodes,
+    "user-mfa.recoveryCodes",
+  );
+  return { ...row, recoveryCodes };
+}

package/src/auth-mfa/errors.ts

@@ -0,0 +1,66 @@
+import {
+  UnprocessableError,
+  type WriteFailure,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { AuthMfaErrorCodes } from "./constants";
+
+export { AuthMfaErrorCodes as AuthMfaErrors } from "./constants";
+
+export function mfaAlreadyEnabled(): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrorCodes.mfaAlreadyEnabled, {
+      i18nKey: "auth.mfa.errors.mfaAlreadyEnabled",
+    }),
+  );
+}
+
+export function mfaNotEnabled(): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrorCodes.mfaNotEnabled, {
+      i18nKey: "auth.mfa.errors.mfaNotEnabled",
+    }),
+  );
+}
+
+export function invalidSetupToken(): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrorCodes.invalidSetupToken, {
+      i18nKey: "auth.mfa.errors.invalidSetupToken",
+    }),
+  );
+}
+
+export function invalidTotpCode(): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrorCodes.invalidTotpCode, {
+      i18nKey: "auth.mfa.errors.invalidTotpCode",
+    }),
+  );
+}
+
+export function invalidRecoveryCode(): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrorCodes.invalidRecoveryCode, {
+      i18nKey: "auth.mfa.errors.invalidRecoveryCode",
+    }),
+  );
+}
+
+export function invalidChallengeToken(): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrorCodes.invalidChallengeToken, {
+      i18nKey: "auth.mfa.errors.invalidChallengeToken",
+    }),
+  );
+}
+
+// retryAfterSeconds drives the login UI countdown — must stay > 0.
+export function tooManyAttempts(retryAfterSeconds: number): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(AuthMfaErrorCodes.tooManyAttempts, {
+      i18nKey: "auth.mfa.errors.tooManyAttempts",
+      details: { retryAfterSeconds },
+    }),
+  );
+}