@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/auth-mfa/web/mfa-setup-preauth-screen.tsx

@@ -0,0 +1,267 @@
+// @runtime client
+// Pre-auth twin of MfaEnableScreen: a user blocked at login by MFA
+// enforcement and not yet enrolled lands here straight out of the login
+// flow — there is no session yet. Identity comes entirely from the
+// preauthSetupToken login()'s mfa-setup-required result carries (see
+// auth-client.ts's LoginResult). Calls startMfaSetupPreauth/confirmMfa-
+// SetupPreauth directly via fetch (mfa-client.ts) — no useSession(), no
+// useDispatcher(), both assume a real session that doesn't exist here.
+//
+// Session contract: a successful confirm mints cookie+JWT server-side, but
+// THIS component does not refresh the session itself (unlike MfaVerify-
+// Screen, which calls session.refresh() internally). onSuccess fires right
+// after confirm — the caller (e.g. auth-gate's LoginRoute, which already
+// has useSession() in scope) must call refresh() there, otherwise the app
+// stays "unauthenticated" until the next reload.
+
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+// qrcode's package.json#browser remap avoids Node-only deps (yargs/pngjs)
+// for bundlers that honor it — Metro doesn't, hence the explicit subpath.
+import QRCode from "qrcode/lib/browser";
+import { type FormEvent, type ReactNode, useState } from "react";
+// kumiko-lint-ignore cross-feature-import client-only component, the feature's server barrel has no web/ re-export
+import { AuthCard } from "../../auth-email-password/web";
+import { confirmMfaSetupPreauth, startMfaSetupPreauth } from "./mfa-client";
+
+type SetupState = {
+  readonly setupToken: string;
+  readonly secretParam: string;
+  readonly recoveryCodes: readonly string[];
+  readonly qrSvg: string;
+};
+
+// otpauth:// URIs put the secret in the query string — extract it for the
+// manual-entry fallback (authenticator apps without a camera / desktop use).
+function extractSecret(otpauthUri: string): string {
+  const query = otpauthUri.split("?")[1] ?? "";
+  return new URLSearchParams(query).get("secret") ?? "";
+}
+
+function reasonToKey(reason: string): string {
+  switch (reason) {
+    case "invalid_totp_code":
+      return "auth.mfa.errors.invalidCode";
+    case "mfa_already_enabled":
+      return "auth.mfa.errors.mfaAlreadyEnabled";
+    case "invalid_setup_token":
+      return "auth.mfa.errors.invalidSetupToken";
+    case "invalid_challenge_token":
+      return "auth.mfa.errors.challengeExpired";
+    case "too_many_attempts":
+      return "auth.mfa.errors.tooManyAttempts";
+    case "rate_limited":
+      return "auth.errors.rateLimited";
+    default:
+      return "auth.mfa.errors.setupFailed";
+  }
+}
+
+export type MfaSetupPreauthScreenProps = {
+  readonly preauthSetupToken: string;
+  /** Account label for the otpauth:// URI (typically the email typed at
+   *  login) — without a session there's no session.user.email to derive it from. */
+  readonly accountLabel: string;
+  readonly title?: string;
+  readonly subtitle?: ReactNode;
+  /** Fired once confirm succeeds — the caller owns session refresh, see the
+   *  file-level comment above. */
+  readonly onSuccess?: () => void;
+  readonly onCancel?: () => void;
+};
+
+export function MfaSetupPreauthScreen({
+  preauthSetupToken,
+  accountLabel,
+  title,
+  subtitle,
+  onSuccess,
+  onCancel,
+}: MfaSetupPreauthScreenProps): ReactNode {
+  const t = useTranslation();
+  const { Button, Banner, Field, Form, Input, Section } = usePrimitives();
+
+  const [setup, setSetup] = useState<SetupState | null>(null);
+  const [acknowledged, setAcknowledged] = useState(false);
+  const [code, setCode] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [retryAfterSeconds, setRetryAfterSeconds] = useState<number | null>(null);
+
+  const startSetup = async (): Promise<void> => {
+    setBusy(true);
+    setError(null);
+    setRetryAfterSeconds(null);
+    try {
+      const res = await startMfaSetupPreauth(preauthSetupToken, accountLabel);
+      if (res.kind !== "success") {
+        setError(res.error.reason);
+        setRetryAfterSeconds(res.error.retryAfterSeconds ?? null);
+        return;
+      }
+      // errorCorrectionLevel "H" (~30% redundancy) — more resilient to
+      // camera/lighting issues than the default, no downside for a code
+      // this short-lived.
+      const qrSvg = await QRCode.toString(res.data.otpauthUri, {
+        type: "svg",
+        errorCorrectionLevel: "H",
+      });
+      setSetup({
+        setupToken: res.data.setupToken,
+        secretParam: extractSecret(res.data.otpauthUri),
+        recoveryCodes: res.data.recoveryCodes,
+        qrSvg,
+      });
+      setAcknowledged(false);
+      setCode("");
+    } catch {
+      setError("setup_failed");
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const confirmSetup = async (): Promise<void> => {
+    if (!setup) return;
+    setBusy(true);
+    setError(null);
+    setRetryAfterSeconds(null);
+    try {
+      const res = await confirmMfaSetupPreauth(setup.setupToken, code);
+      if (res.kind !== "success") {
+        setError(res.error.reason);
+        setRetryAfterSeconds(res.error.retryAfterSeconds ?? null);
+        // An expired or already-burned setupToken can never succeed again —
+        // drop back to the intro so the "start setup" button reappears,
+        // otherwise the user is stuck on this screen with no way forward
+        // short of a full reload (which loses the preauthSetupToken).
+        if (
+          res.error.reason === "invalid_setup_token" ||
+          res.error.reason === "invalid_challenge_token"
+        ) {
+          setSetup(null);
+          setAcknowledged(false);
+          setCode("");
+        }
+        return;
+      }
+      onSuccess?.();
+    } catch {
+      setError("setup_failed");
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const onSubmit = (e?: FormEvent): void => {
+    e?.preventDefault();
+    void confirmSetup();
+  };
+
+  return (
+    <AuthCard
+      title={title ?? t("auth.mfa.setup.title")}
+      subtitle={subtitle ?? t("auth.mfa.setup.subtitle")}
+    >
+      <div className="p-6 pt-0 flex flex-col gap-4">
+        {error !== null ? (
+          <Banner variant="error">
+            {error === "too_many_attempts" && retryAfterSeconds !== null
+              ? t("auth.mfa.errors.tooManyAttemptsWithSeconds", { seconds: retryAfterSeconds })
+              : t(reasonToKey(error))}
+          </Banner>
+        ) : null}
+
+        {!setup && (
+          <Section
+            testId="mfa-setup-preauth-intro"
+            actions={
+              <Button
+                variant="primary"
+                onClick={() => void startSetup()}
+                loading={busy}
+                disabled={busy}
+              >
+                {t("auth.mfa.setup.start")}
+              </Button>
+            }
+          >
+            <span className="text-sm text-muted-foreground">{t("auth.mfa.setup.intro")}</span>
+          </Section>
+        )}
+
+        {setup && (
+          <Form onSubmit={onSubmit}>
+            <Section
+              testId="mfa-setup-preauth-setup"
+              actions={
+                <Button
+                  type="submit"
+                  variant="primary"
+                  loading={busy}
+                  disabled={busy || !acknowledged || code.length !== 6}
+                >
+                  {t("auth.mfa.setup.confirm")}
+                </Button>
+              }
+            >
+              <div className="flex flex-col items-center gap-2 text-center">
+                <span className="text-sm font-semibold">{t("auth.mfa.enable.scanTitle")}</span>
+                {/* qrcode's own SVG string output, not user input — safe to inline */}
+                <div
+                  className="h-40 w-40"
+                  // biome-ignore lint/security/noDangerouslySetInnerHtml: qrcode-generated SVG, no user input
+                  dangerouslySetInnerHTML={{ __html: setup.qrSvg }}
+                />
+                <span className="text-xs text-muted-foreground">
+                  {t("auth.mfa.enable.manualEntry")}
+                </span>
+                <code className="inline-block break-all rounded bg-muted px-3 py-2 font-mono text-sm">
+                  {setup.secretParam}
+                </code>
+              </div>
+
+              <div className="flex flex-col gap-2">
+                <span className="text-sm font-semibold">{t("auth.mfa.enable.recoveryTitle")}</span>
+                <span className="text-xs text-muted-foreground">
+                  {t("auth.mfa.enable.recoveryHint")}
+                </span>
+                <code className="block whitespace-pre-wrap break-all rounded bg-muted px-3 py-2 font-mono text-sm">
+                  {setup.recoveryCodes.join("\n")}
+                </code>
+                <Field id="mfa-setup-preauth-ack" label={t("auth.mfa.enable.acknowledge")}>
+                  <Input
+                    kind="boolean"
+                    id="mfa-setup-preauth-ack"
+                    name="mfa-setup-preauth-ack"
+                    value={acknowledged}
+                    onChange={setAcknowledged}
+                  />
+                </Field>
+              </div>
+
+              <Field id="mfa-setup-preauth-code" label={t("auth.mfa.enable.code")} required>
+                <Input
+                  kind="text"
+                  id="mfa-setup-preauth-code"
+                  name="mfa-setup-preauth-code"
+                  value={code}
+                  onChange={setCode}
+                  disabled={busy || !acknowledged}
+                  autoComplete="one-time-code"
+                />
+              </Field>
+            </Section>
+          </Form>
+        )}
+
+        {onCancel ? (
+          <div className="flex justify-center">
+            <Button type="button" variant="secondary" onClick={onCancel} disabled={busy}>
+              {t("auth.mfa.verify.backToLogin")}
+            </Button>
+          </div>
+        ) : null}
+      </div>
+    </AuthCard>
+  );
+}

package/src/auth-mfa/web/mfa-verify-screen.tsx

@@ -0,0 +1,117 @@
+// @runtime client
+// Login-Challenge-Step, gerendert wenn LoginScreen's onMfaChallenge feuert
+// (/auth/login antwortete mfaRequired). Stilistisch wie login-screen.tsx:
+// useState + direkter fetch-Call, kein Dispatcher — es existiert noch kein
+// JWT. Nach Erfolg ruft es session.refresh() statt eines Hard-Reloads, weil
+// der Aufrufer (typisch ein Wizard-State im App-Root) sofort neu rendern
+// will, sobald status:"authenticated" ankommt.
+
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type FormEvent, type ReactNode, useState } from "react";
+// kumiko-lint-ignore cross-feature-import client-only barrel, the feature's server barrel has no web/ re-export
+import { AuthCard, useSession } from "../../auth-email-password/web";
+import { verifyMfaChallenge } from "./mfa-client";
+
+export type MfaVerifyScreenProps = {
+  readonly challengeToken: string;
+  readonly title?: string;
+  readonly subtitle?: ReactNode;
+  readonly submitLabel?: string;
+  /** Called after the server confirms the code and the session state has
+   *  refreshed. Optional — apps that swap this screen back out purely on
+   *  session.status changing to "authenticated" don't need it. */
+  readonly onSuccess?: () => void;
+  // Some failures (challenge_expired, too_many_attempts) have no retry path —
+  // the challengeToken is dead. Without this, the host has no way back to
+  // login short of a full page reload. Optional: apps that always mount
+  // this screen fresh per challenge can omit it.
+  readonly onCancel?: () => void;
+};
+
+function reasonToKey(reason: string): string {
+  switch (reason) {
+    case "invalid_totp_code":
+    case "invalid_recovery_code":
+    case "invalid_code":
+      return "auth.mfa.errors.invalidCode";
+    case "challenge_expired":
+    case "invalid_challenge_token":
+      return "auth.mfa.errors.challengeExpired";
+    case "too_many_attempts":
+      return "auth.mfa.errors.tooManyAttempts";
+    case "rate_limited":
+      return "auth.errors.rateLimited";
+    default:
+      return "auth.mfa.errors.verifyFailed";
+  }
+}
+
+export function MfaVerifyScreen({
+  challengeToken,
+  title,
+  subtitle,
+  submitLabel,
+  onSuccess,
+  onCancel,
+}: MfaVerifyScreenProps): ReactNode {
+  const t = useTranslation();
+  const { Form, Field, Input, Button, Banner } = usePrimitives();
+  const session = useSession();
+  const [code, setCode] = useState("");
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const doSubmit = async (): Promise<void> => {
+    setSubmitting(true);
+    setError(null);
+    const res = await verifyMfaChallenge(challengeToken, code);
+    if (res.kind === "success") {
+      await session.refresh();
+      setSubmitting(false);
+      onSuccess?.();
+      return;
+    }
+    setSubmitting(false);
+    setError(res.error.reason);
+  };
+
+  const onSubmit = (e?: FormEvent): void => {
+    e?.preventDefault();
+    void doSubmit();
+  };
+
+  return (
+    <AuthCard
+      title={title ?? t("auth.mfa.verify.title")}
+      subtitle={subtitle ?? t("auth.mfa.verify.subtitle")}
+    >
+      <div className="p-6 pt-0 flex flex-col gap-4">
+        <Form onSubmit={onSubmit}>
+          <Field id="mfa-verify-code" label={t("auth.mfa.verify.code")} required>
+            <Input
+              kind="text"
+              id="mfa-verify-code"
+              name="mfa-verify-code"
+              value={code}
+              onChange={setCode}
+              disabled={submitting}
+              required
+              autoComplete="one-time-code"
+            />
+          </Field>
+          {error !== null ? <Banner variant="error">{t(reasonToKey(error))}</Banner> : null}
+          <Button type="submit" loading={submitting} disabled={submitting}>
+            {submitting
+              ? t("auth.mfa.verify.submitting")
+              : (submitLabel ?? t("auth.mfa.verify.submit"))}
+          </Button>
+          {onCancel ? (
+            <Button type="button" variant="secondary" onClick={onCancel} disabled={submitting}>
+              {t("auth.mfa.verify.backToLogin")}
+            </Button>
+          ) : null}
+        </Form>
+      </div>
+    </AuthCard>
+  );
+}

package/src/auth-mfa/web/qrcode-browser.d.ts

@@ -0,0 +1,12 @@
+// @types/qrcode only declares the main "qrcode" entry, not the browser-only
+// subpath (see mfa-enable-screen.tsx's import — the main entry pulls in
+// Node-only deps like yargs/pngjs via qrcode's own package.json#browser
+// remap, which Metro doesn't honor). Same runtime shape, just re-typed.
+// `export *` never re-exports a default — `import QRCode from "..."`
+// resolving here relies on the consuming app's esModuleInterop/
+// allowSyntheticDefaultImports (which synthesizes a default from the
+// namespace). Copy this file into apps that need it, but note that
+// requirement — without it, the default import comes back undefined.
+declare module "qrcode/lib/browser" {
+  export * from "qrcode";
+}

package/src/auth-mfa-user-data/__tests__/hooks.integration.test.ts

@@ -0,0 +1,134 @@
+// userMfaExportHook/userMfaDeleteHook — GDPR export must never surface the
+// TOTP secret or recovery codes, and forget must actually remove the row
+// (not just leave it dangling for a future projection rebuild to resurrect).
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
+import { base32Decode } from "../../auth-mfa/base32";
+import { AuthMfaHandlers } from "../../auth-mfa/constants";
+import { createAuthMfaFeature } from "../../auth-mfa/feature";
+import { userMfaEntity } from "../../auth-mfa/schema/user-mfa";
+import { currentTotpCode } from "../../auth-mfa/totp";
+import { createConfigFeature } from "../../config";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { createTenantFeature } from "../../tenant";
+import { createUserFeature } from "../../user/feature";
+import { userEntity } from "../../user/schema/user";
+import { userMfaDeleteHook, userMfaExportHook } from "../hooks";
+
+let stack: TestStack;
+
+const SETUP_TOKEN_SECRET = "test-setup-token-secret-do-not-use-in-prod";
+
+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: "test-mfa-challenge-secret-at-least-32-bytes!!",
+      }),
+    ],
+    extraContext: { configResolver: resolver, configEncryption: encryption },
+  });
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, userMfaEntity);
+  await unsafePushTables(stack.db, { configValuesTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+async function enrollUser(userId: string) {
+  const user = createTestUser({ id: userId, roles: ["User"] });
+  const start = await stack.http.writeOk<{ setupToken: string; otpauthUri: string }>(
+    AuthMfaHandlers.enableStart,
+    { accountLabel: `${userId}@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,
+  );
+  return user;
+}
+
+describe("userMfaExportHook / userMfaDeleteHook", () => {
+  test("export confirms enrollment without leaking the TOTP secret or recovery codes", async () => {
+    const user = await enrollUser("export-1");
+
+    const snippet = await userMfaExportHook({
+      db: stack.db,
+      registry: stack.registry,
+      tenantId: user.tenantId,
+      userId: user.id,
+    });
+
+    expect(snippet).not.toBeNull();
+    expect(snippet?.rows).toHaveLength(1);
+    const row = snippet?.rows[0] as Record<string, unknown>;
+    expect(row["enrolled"]).toBe(true);
+    expect(JSON.stringify(row)).not.toContain("totpSecret");
+    expect(JSON.stringify(row)).not.toContain("recoveryCodes");
+  });
+
+  test("export returns null for a user who never enrolled", async () => {
+    const user = createTestUser({ id: "never-enrolled", roles: ["User"] });
+    const snippet = await userMfaExportHook({
+      db: stack.db,
+      registry: stack.registry,
+      tenantId: user.tenantId,
+      userId: user.id,
+    });
+    expect(snippet).toBeNull();
+  });
+
+  test("delete hard-removes the row via forget (rebuild-safe)", async () => {
+    const user = await enrollUser("delete-1");
+
+    const before = await userMfaExportHook({
+      db: stack.db,
+      registry: stack.registry,
+      tenantId: user.tenantId,
+      userId: user.id,
+    });
+    expect(before).not.toBeNull();
+
+    await userMfaDeleteHook(
+      {
+        db: stack.db,
+        registry: stack.registry,
+        tenantId: user.tenantId,
+        userId: user.id,
+      },
+      "delete",
+    );
+
+    const after = await userMfaExportHook({
+      db: stack.db,
+      registry: stack.registry,
+      tenantId: user.tenantId,
+      userId: user.id,
+    });
+    expect(after).toBeNull();
+  });
+});

package/src/auth-mfa-user-data/hooks.ts

@@ -0,0 +1,53 @@
+// EXT_USER_DATA hooks for userMfa (GDPR Art. 15/17/20). Both totpSecret and
+// recoveryCodes are marked userOwned in the schema for exactly this: on
+// forget, the row must actually disappear — a leftover TOTP secret or
+// recovery-code hash under an anonymized user is still a live credential
+// nobody can rotate. Mirrors folders-user-data/hooks.ts's executor-based
+// delete (rebuild-safe: forget replays via the event, a raw DELETE would be
+// resurrected by a projection rebuild).
+
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createSystemUser,
+  type UserDataDeleteHook,
+  type UserDataExportHook,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { userMfaEntity, userMfaTable } from "../auth-mfa";
+
+const executor = createEventStoreExecutor(userMfaTable, userMfaEntity, {
+  entityName: "user-mfa",
+});
+
+// Never includes totpSecret/recoveryCodes — secret-derived credential
+// material, not portable personal data (same reasoning as api-token's
+// tokenHash exclusion in user-data-rights-defaults). Just confirms
+// enrollment + when, which is what a data subject actually needs to see.
+export const userMfaExportHook: UserDataExportHook = async (ctx) => {
+  const rows = await selectMany<{ id: string; enabledAt: unknown }>(ctx.db, userMfaTable, {
+    userId: ctx.userId,
+    tenantId: ctx.tenantId,
+  });
+  if (rows.length === 0) return null;
+  return {
+    entity: "user-mfa",
+    rows: rows.map((r) => ({ enrolled: true, enabledAt: String(r.enabledAt ?? "") })),
+  };
+};
+
+// Always a real hard-delete regardless of the incoming strategy — a 2FA
+// secret can't be anonymized, and userOwned already means this row belongs
+// to exactly one user (never shared tenant data).
+export const userMfaDeleteHook: UserDataDeleteHook = async (ctx) => {
+  const rows = await selectMany<{ id: string }>(ctx.db, userMfaTable, {
+    userId: ctx.userId,
+    tenantId: ctx.tenantId,
+  });
+  // skip: nothing enrolled for this user — no row to erase
+  if (rows.length === 0) return;
+  const systemUser = createSystemUser(ctx.tenantId);
+  const tdb = createTenantDb(ctx.db, ctx.tenantId, "system");
+  for (const row of rows) {
+    await executor.forget({ id: row.id }, systemUser, tdb);
+  }
+};

package/src/auth-mfa-user-data/index.ts

@@ -0,0 +1,21 @@
+// Provides the EXT_USER_DATA export/delete hooks for the `user-mfa` entity as
+// a standalone feature — mount it alongside `auth-mfa` + `user-data-rights`
+// when an app needs 2FA enrollment in its GDPR export/forget pipeline. Kept
+// separate from `auth-mfa` (which only requires "user"/"config") so auth-mfa
+// consumers without the user-data-rights stack don't pull a hard dependency.
+// Mirrors folders-user-data.
+
+import { defineFeature, EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
+import { userMfaDeleteHook, userMfaExportHook } from "./hooks";
+
+export const authMfaUserDataFeature = defineFeature("auth-mfa-user-data", (r) => {
+  r.describe(
+    "GDPR (Art. 20 export / Art. 17 erasure) coverage for the `auth-mfa` feature's `user-mfa` entity. Mounts the EXT_USER_DATA export + delete hooks so 2FA enrollment status is included in the user-data export bundle and a user's TOTP secret + recovery codes are hard-deleted (via executor.forget, rebuild-safe) on a data-subject erasure request. Kept separate from `auth-mfa` so consumers without the user-data-rights pipeline don't pull a hard dependency — requires `user-data-rights`, optionalRequires `auth-mfa`.",
+  );
+  r.requires("user-data-rights");
+  r.optionalRequires("auth-mfa");
+  r.useExtension(EXT_USER_DATA, "user-mfa", {
+    export: userMfaExportHook,
+    delete: userMfaDeleteHook,
+  });
+});