@awsmbiz/create-inbis-app 0.0.0-stage → 0.1.0

package/template/modules/auth/files/src/auth.ts

@@ -0,0 +1,68 @@
+import { createInbisAuth, type InbisAuthConfig } from "@awsmbiz/inbis-auth";
+import { mountAuth, requireAuth, sessionMiddleware, type AuthEnv, type AuthResolver } from "@awsmbiz/inbis-auth/hono";
+import type { ApiEnv } from "@awsmbiz/inbis-api";
+import { requireBinding, requireSecret } from "@awsmbiz/inbis-cloudflare";
+import { authEmailTemplates } from "@awsmbiz/inbis-notifications";
+import type { Hono } from "hono";
+import { auditSinkFor } from "./audit-sink.js";
+import type { AppNotifications } from "./notifications.js";
+
+/** What the auth wiring needs; `src/index.ts` builds it from `env`, tests inject fakes. */
+export interface AuthDeps extends AppNotifications {
+  authConfig: InbisAuthConfig;
+  /** Outbound fetch for the breached-password check; defaults to the global `fetch`. */
+  fetch?: typeof fetch;
+}
+
+/**
+ * One `@awsmbiz/inbis-auth` instance per request, from the app's bindings and secrets
+ * (ADR-1). Auth events go to the app's audit trail when it has one (src/audit-sink.ts);
+ * without one, auth keeps its own interim history.
+ */
+export function authResolver(deps: AuthDeps): AuthResolver<ApiEnv<Env>> {
+  return (c) => {
+    const audit = auditSinkFor(c.env, { logger: c.var.logger });
+    return createInbisAuth({
+      config: deps.authConfig,
+      env: { authSecret: requireSecret(c.env, "AUTH_SECRET"), turnstileSecretKey: requireSecret(c.env, "TURNSTILE_SECRET_KEY") },
+      db: requireBinding(c.env, "AUTH_DB"),
+      email: deps.email,
+      emailTemplates: authEmailTemplates,
+      sms: deps.sms,
+      logger: c.var.logger,
+      requestId: c.var.requestId,
+      ...(audit === undefined ? {} : { audit }),
+      ...(deps.fetch === undefined ? {} : { fetch: deps.fetch }),
+    });
+  };
+}
+
+/**
+ * Mounts sign-in on the app: the session on every `/api/*` request, the auth routes
+ * under `/api/auth` (sign-in, sign-up, phone codes, 2FA, invitations, sessions),
+ * `GET /api/me` (the signed-in user), and the local email/SMS outboxes.
+ */
+export function mountAppAuth(app: Hono<ApiEnv<Env>>, deps: AuthDeps | undefined): AuthResolver<ApiEnv<Env>> {
+  if (deps === undefined) throw new Error("createApp needs deps.auth (see src/index.ts).");
+  const authFor = authResolver(deps);
+  app.use("/api/*", sessionMiddleware(authFor));
+  mountAuth(app, deps.authConfig, authFor);
+  const signedIn = app as unknown as Hono<ApiEnv<Env> & AuthEnv>;
+  signedIn.get("/api/me", requireAuth(), (c) => c.json({ user: c.var.user, session: c.var.session }));
+
+  // Local development only (log transports on a local host): newest message first.
+  const { outbox, smsOutbox } = deps;
+  if (outbox !== undefined) {
+    app.get("/api/dev/outbox", (c) => {
+      c.header("cache-control", "no-store");
+      return c.json({ emails: [...outbox.recent()].reverse() });
+    });
+  }
+  if (smsOutbox !== undefined) {
+    app.get("/api/dev/sms-outbox", (c) => {
+      c.header("cache-control", "no-store");
+      return c.json({ messages: [...smsOutbox.recent()].reverse() });
+    });
+  }
+  return authFor;
+}

package/template/modules/auth/files/src/local-test-mode.ts

@@ -0,0 +1,49 @@
+/**
+ * Local test mode (`LOCAL_TEST_MODE=true`, set by the Playwright suite): the Worker
+ * answers the two outside services auth calls itself, Cloudflare Turnstile's
+ * siteverify and the Pwned Passwords range API, as the real services answer for
+ * Cloudflare's Turnstile testing secrets and a password that is not breached, and
+ * auth rate limits are raised (src/auth-config.ts). So e2e runs never depend on, or
+ * send requests to, third parties. Honoured only when the app runs on a local host;
+ * a deployed Worker always calls the real services. The browser still loads the
+ * real Turnstile widget.
+ */
+
+export const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+/** Whether the app runs on this machine (`AUTH_BASE_URL` is a local host). */
+export function isLocal(vars: Pick<Env, "AUTH_BASE_URL">): boolean {
+  return LOCAL_HOSTS.has(new URL(vars.AUTH_BASE_URL).hostname);
+}
+
+export function localTestMode(vars: Pick<Env, "AUTH_BASE_URL" | "LOCAL_TEST_MODE">): boolean {
+  return vars.LOCAL_TEST_MODE === "true" && isLocal(vars);
+}
+
+const SITEVERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+const PWNED_RANGE_PREFIX = "https://api.pwnedpasswords.com/range/";
+
+/** Cloudflare's Turnstile testing secrets and what siteverify answers for each. */
+const TESTING_SECRETS: Record<string, { success: boolean; "error-codes": string[] }> = {
+  "1x0000000000000000000000000000000AA": { success: true, "error-codes": [] },
+  "2x0000000000000000000000000000000AA": { success: false, "error-codes": ["invalid-input-response"] },
+  "3x0000000000000000000000000000000AA": { success: false, "error-codes": ["timeout-or-duplicate"] },
+};
+
+function siteverify(init: RequestInit | undefined): Response {
+  const body = JSON.parse(typeof init?.body === "string" ? init.body : "{}") as { secret?: string; response?: string };
+  if ((body.response ?? "") === "") return Response.json({ success: false, "error-codes": ["missing-input-response"] });
+  const answer = TESTING_SECRETS[body.secret ?? ""] ?? { success: false, "error-codes": ["invalid-input-secret"] };
+  return Response.json({ ...answer, ...(answer.success ? { hostname: "localhost" } : {}) });
+}
+
+/** `base`, except that siteverify and the Pwned Passwords range API are answered locally. */
+export function stubbedFetch(base: typeof fetch): typeof fetch {
+  return (input, init) => {
+    const url = input instanceof Request ? input.url : String(input);
+    if (url === SITEVERIFY_URL) return Promise.resolve(siteverify(init));
+    // An empty range: no breached password has this hash prefix.
+    if (url.startsWith(PWNED_RANGE_PREFIX)) return Promise.resolve(new Response("", { status: 200 }));
+    return base(input, init);
+  };
+}

package/template/modules/auth/files/src/notifications.ts

@@ -0,0 +1,94 @@
+import { AUTH_SMS_TEMPLATES, requiredAuthSmsTemplates, type InbisAuthConfig } from "@awsmbiz/inbis-auth";
+import { requireBinding } from "@awsmbiz/inbis-cloudflare";
+import type { EmailSender, SmsSender } from "@awsmbiz/inbis-core";
+import {
+  communicationServiceBinding,
+  createCommunicationServiceEmailSender,
+  createCommunicationServiceSmsSender,
+  createLogEmailSender,
+  createLogSmsSender,
+  type LoggedEmail,
+  type LoggedSms,
+} from "@awsmbiz/inbis-notifications";
+import { isLocal } from "./local-test-mode.js";
+
+/** How auth emails and SMS leave the Worker, plus the local outboxes when it is safe to expose them. */
+export interface AppNotifications {
+  email: EmailSender;
+  sms: SmsSender;
+  /** Recent emails for `GET /api/dev/outbox`: the log transport on a local host only. */
+  outbox?: { recent(): readonly LoggedEmail[] };
+  /** Recent SMS for `GET /api/dev/sms-outbox`: the log transport on a local host only. */
+  smsOutbox?: { recent(): readonly LoggedSms[] };
+}
+
+/** The Worker variables and bindings the notification wiring reads. */
+export type NotificationsEnv = Pick<
+  Env,
+  | "EMAIL_TRANSPORT"
+  | "SMS_TRANSPORT"
+  | "AUTH_BASE_URL"
+  | "APP_ID"
+  | "COMMUNICATION_SERVICE"
+  | "SMS_HEADER"
+  | "SMS_OTP_TEMPLATE_ID"
+  | "SMS_INVITATION_TEMPLATE_ID"
+>;
+
+/**
+ * The text of each auth SMS exactly as registered with the SMS provider (through the
+ * communication service), with `{variable}` placeholders. Change a text only together
+ * with its registration, or the provider rejects every message.
+ */
+export const SMS_TEXTS = {
+  [AUTH_SMS_TEMPLATES.phoneOtp]: "{code} is your {appName} sign-in code. It expires in {minutes} minutes.",
+  [AUTH_SMS_TEMPLATES.invitation]: "{inviter} invited you to {appName}. Sign in with this phone number to join: {url}",
+} as const;
+
+/**
+ * Picks the email and SMS adapters from `EMAIL_TRANSPORT` / `SMS_TRANSPORT`:
+ * - `log` (local development): prints every message and keeps an outbox, exposed
+ *   only when the app runs on a local host (it holds live links and sign-in codes);
+ * - `communication-service`: the shared communication service through the
+ *   `COMMUNICATION_SERVICE` service binding, as app `APP_ID`; SMS also need the
+ *   sender header and the template IDs of the texts above.
+ *
+ * Throws at startup when a transport is unknown or its settings are missing.
+ */
+export function appNotifications(env: NotificationsEnv, authConfig: InbisAuthConfig): AppNotifications {
+  const local = isLocal(env);
+  const binding = () => communicationServiceBinding(requireBinding(env, "COMMUNICATION_SERVICE"));
+  const result: Partial<AppNotifications> = {};
+
+  if (env.EMAIL_TRANSPORT === "communication-service") {
+    result.email = createCommunicationServiceEmailSender({ binding: binding(), appId: env.APP_ID });
+  } else if (env.EMAIL_TRANSPORT === "log") {
+    const log = createLogEmailSender();
+    result.email = log;
+    if (local) result.outbox = log;
+  } else {
+    throw new Error('EMAIL_TRANSPORT must be "log" or "communication-service".');
+  }
+
+  if (env.SMS_TRANSPORT === "communication-service") {
+    const { phoneOtp, invitation } = AUTH_SMS_TEMPLATES;
+    result.sms = createCommunicationServiceSmsSender({
+      binding: binding(),
+      appId: env.APP_ID,
+      smsHeader: env.SMS_HEADER,
+      templates: {
+        [phoneOtp]: { templateId: env.SMS_OTP_TEMPLATE_ID, text: SMS_TEXTS[phoneOtp] },
+        [invitation]: { templateId: env.SMS_INVITATION_TEMPLATE_ID, text: SMS_TEXTS[invitation] },
+      },
+      requiredTemplates: requiredAuthSmsTemplates(authConfig),
+    });
+  } else if (env.SMS_TRANSPORT === "log") {
+    const log = createLogSmsSender();
+    result.sms = log;
+    if (local) result.smsOutbox = log;
+  } else {
+    throw new Error('SMS_TRANSPORT must be "log" or "communication-service".');
+  }
+
+  return result as AppNotifications;
+}

package/template/modules/auth/files/test/auth-fixtures.ts

@@ -0,0 +1,135 @@
+import { createCapturingEmailSender, createCapturingSmsSender } from "@awsmbiz/inbis-core/testing";
+import { createExecutionContext, waitOnExecutionContext } from "cloudflare:test";
+import { env } from "cloudflare:workers";
+import { createApp } from "../src/app.js";
+import { AUTH_CHOICES, type AuthChoices } from "../src/auth-choices.js";
+import { appAuthConfig } from "../src/auth-config.js";
+import { migrate as migrateAll } from "./migrate.js";
+import { secretOf, totpCode } from "./totp.js";
+import { fakeSiteverify, TURNSTILE_TEST } from "./turnstile-fake.js";
+
+/** Origin the tests call the Worker on; `AUTH_BASE_URL` in vitest.config.ts. */
+export const ORIGIN = "https://app.example.test";
+
+const TEST_RATE_LIMIT = { default: { window: 60, max: 5000 }, signIn: { window: 60, max: 5000 }, twoFactor: { window: 60, max: 5000 } };
+
+/** Every migration (platform sources first, as `pnpm db:migrate`), and a fake Turnstile siteverify. */
+export async function migrate(): Promise<void> {
+  fakeSiteverify();
+  await migrateAll();
+}
+
+/**
+ * The app Worker built as `src/index.ts` builds it, with `choices` instead of the app's
+ * own (src/auth-choices.ts), and capturing email/SMS senders, so tests read the links
+ * and codes the user would receive.
+ */
+export function testApp(choices: AuthChoices = AUTH_CHOICES) {
+  const email = createCapturingEmailSender();
+  const sms = createCapturingSmsSender();
+  const config = appAuthConfig(env, choices);
+  const app = createApp({
+    auth: {
+      // Raised rate limits: every test signs in from the same (absent) client address.
+      authConfig: { ...config, security: { ...config.security, rateLimit: TEST_RATE_LIMIT } },
+      email,
+      sms,
+      // A Pwned Passwords range API that knows no breached password: tests never reach the network.
+      fetch: () => Promise.resolve(new Response("", { status: 200 })),
+    },
+  });
+
+  async function call(path: string, init: RequestInit = {}): Promise<Response> {
+    const ctx = createExecutionContext();
+    const response = await app.fetch(new Request(`${ORIGIN}${path}`, init), env, ctx);
+    await waitOnExecutionContext(ctx);
+    return response;
+  }
+
+  return { call, email, sms };
+}
+
+export type TestApp = ReturnType<typeof testApp>;
+
+/** Every method on, and the given registration mode. */
+export function choicesWith(registration: AuthChoices["registration"], phoneOtp: AuthChoices["phoneOtp"] = false): AuthChoices {
+  return { emailPassword: true, phoneOtp, twoFactor: true, registration };
+}
+
+/** A JSON POST as the browser sends it from the app's own origin, with the Turnstile widget's token. */
+export function json(body: unknown, headers: Record<string, string> = {}): RequestInit {
+  return {
+    method: "POST",
+    headers: { "content-type": "application/json", origin: ORIGIN, "x-captcha-response": TURNSTILE_TEST.token, ...headers },
+    body: JSON.stringify(body),
+  };
+}
+
+/** The `name=value` pairs of every Set-Cookie header, as a Cookie request header. */
+export function cookieHeader(response: Response): string {
+  return response.headers
+    .getSetCookie()
+    .map((cookie) => cookie.split(";")[0])
+    .join("; ");
+}
+
+/** The links in an email's text part. */
+export function linksIn(email: { text: string } | undefined): string[] {
+  return email?.text.match(/https?:\/\/\S+/g) ?? [];
+}
+
+export interface TestUser {
+  name: string;
+  email: string;
+  password: string;
+}
+
+/** A user with a fresh email address (D1 state persists across the tests of a file). */
+export function newUser(name = "Ada Lovelace"): TestUser {
+  return { name, email: `user-${crypto.randomUUID()}@example.test`, password: "correct horse battery" };
+}
+
+/** Creates a verified user through public sign-up (registration "open") and the emailed link, as a user would. */
+export async function seedUser(user: TestUser): Promise<void> {
+  const open = testApp(choicesWith("open"));
+  const response = await open.call("/api/auth/sign-up/email", json(user));
+  if (response.status !== 200) throw new Error(`Seeding failed: ${response.status} ${await response.text()}`);
+  const [link] = linksIn(open.email.lastTo(user.email));
+  if (link === undefined) throw new Error("Sign-up sent no verification email.");
+  const url = new URL(link);
+  const verified = await open.call(`${url.pathname}${url.search}`);
+  if (verified.status >= 400) throw new Error(`Verifying the seeded user failed: ${verified.status}`);
+}
+
+/** Signs in with email and password; returns the session cookie. */
+export async function signIn(app: TestApp, user: TestUser): Promise<string> {
+  const response = await app.call("/api/auth/sign-in/email", json({ email: user.email, password: user.password }));
+  if (response.status !== 200) throw new Error(`Sign-in failed: ${response.status} ${await response.text()}`);
+  return cookieHeader(response);
+}
+
+/**
+ * A verified user made an administrator directly in the auth database (test setup only;
+ * a real app gets its first administrator from `inbis-auth bootstrap-admin`), with an
+ * enrolled authenticator, because administrators need 2FA. Returns the 2FA-verified
+ * session cookie.
+ */
+export async function seedAdmin(user: TestUser = newUser("Grace Admin")): Promise<string> {
+  await seedUser(user);
+  await env.AUTH_DB.prepare("UPDATE user SET role = 'admin' WHERE email = ?").bind(user.email).run();
+  const app = testApp(choicesWith("invite-only"));
+  const cookie = await signIn(app, user);
+  const enabled = await app.call("/api/auth/two-factor/enable", json({ password: user.password }, { cookie }));
+  if (enabled.status !== 200) throw new Error(`Admin 2FA enrolment failed: ${enabled.status}`);
+  const secret = secretOf((await enabled.json<{ totpURI: string }>()).totpURI);
+  const verified = await app.call("/api/auth/two-factor/verify-totp", json({ code: await totpCode(secret) }, { cookie }));
+  if (verified.status !== 200) throw new Error(`Admin 2FA verification failed: ${verified.status}`);
+  // Enrolment replaces the session; the last session cookie set is the new, verified one.
+  const session = verified.headers
+    .getSetCookie()
+    .map((c) => c.split(";")[0] ?? "")
+    .filter((pair) => pair.includes("session_token="))
+    .at(-1);
+  if (session === undefined) throw new Error("Admin 2FA enrolment set no session cookie.");
+  return session;
+}

package/template/modules/auth/files/test/auth.test.ts

@@ -0,0 +1,210 @@
+import { validateAuthConfig } from "@awsmbiz/inbis-auth";
+import { env, exports } from "cloudflare:workers";
+import { beforeEach, describe, expect, it } from "vitest";
+import { AUTH_CHOICES } from "../src/auth-choices.js";
+import { appAuthConfig } from "../src/auth-config.js";
+import { appNotifications } from "../src/notifications.js";
+import {
+  choicesWith,
+  cookieHeader,
+  json,
+  linksIn,
+  migrate,
+  newUser,
+  ORIGIN,
+  seedAdmin,
+  seedUser,
+  signIn,
+  testApp,
+} from "./auth-fixtures.js";
+import { secretOf, totpCode } from "./totp.js";
+
+// Sign-in wired into the app, over HTTP. The app's own choices (src/auth-choices.ts) are
+// checked first; the journeys then run with explicit choices, so every registration mode
+// and method is covered whatever this app chose. @awsmbiz/inbis-auth's own tests cover
+// each rule in detail; these prove the wiring.
+
+beforeEach(async () => {
+  await migrate();
+});
+
+describe("the app's auth config", () => {
+  it("is valid and is what the public config reports", async () => {
+    expect(() => validateAuthConfig(appAuthConfig(env))).not.toThrow();
+
+    const response = await exports.default.fetch(new Request(`${ORIGIN}/api/auth/public-config`));
+    const config = await response.json<{
+      registration: { mode: string };
+      methods: { emailPassword?: object; phoneOtp?: object };
+      twoFactor?: object;
+    }>();
+    expect(response.status).toBe(200);
+    expect(config.registration.mode).toBe(AUTH_CHOICES.registration);
+    expect(config.methods.emailPassword !== undefined).toBe(AUTH_CHOICES.emailPassword);
+    expect(config.methods.phoneOtp !== undefined).toBe(AUTH_CHOICES.phoneOtp !== false);
+    expect(config.twoFactor !== undefined).toBe(AUTH_CHOICES.twoFactor);
+  });
+
+  it("GET /api/me needs a session", async () => {
+    const response = await exports.default.fetch(new Request(`${ORIGIN}/api/me`));
+    expect(response.status).toBe(401);
+  });
+});
+
+describe("email and password", () => {
+  it("a verified user signs in, the app knows who it is, and signs out", async () => {
+    const user = newUser();
+    await seedUser(user);
+    const app = testApp(choicesWith("invite-only"));
+
+    const cookie = await signIn(app, user);
+    const me = await app.call("/api/me", { headers: { cookie } });
+    expect(await me.json()).toMatchObject({ user: { email: user.email, name: user.name, role: "user" } });
+
+    const out = await app.call("/api/auth/sign-out", json({}, { cookie }));
+    expect(out.status).toBe(200);
+    expect((await app.call("/api/me", { headers: { cookie } })).status).toBe(401);
+  });
+
+  it("a wrong password is refused", async () => {
+    const user = newUser();
+    await seedUser(user);
+    const response = await testApp().call("/api/auth/sign-in/email", json({ email: user.email, password: "not the password" }));
+    expect(response.status).toBe(401);
+  });
+
+  it("self sign-up works only when registration is open", async () => {
+    const closed = await testApp(choicesWith("invite-only")).call("/api/auth/sign-up/email", json(newUser()));
+    expect(closed.status).toBeGreaterThanOrEqual(400);
+    const open = await testApp(choicesWith("open")).call("/api/auth/sign-up/email", json(newUser()));
+    expect(open.status).toBe(200);
+  });
+});
+
+describe("invitations", () => {
+  it("invite-only: an administrator invites by email; the invitee accepts from the link and signs in", async () => {
+    const admin = await seedAdmin();
+    const app = testApp(choicesWith("invite-only"));
+    const invitee = newUser("Ivy Invitee");
+
+    const created = await app.call("/api/auth/admin/create-invitation", json({ email: invitee.email }, { cookie: admin }));
+    expect(created.status).toBe(200);
+    const [link] = linksIn(app.email.lastTo(invitee.email));
+    const url = new URL(link ?? "");
+    expect(`${url.origin}${url.pathname}`).toBe(`${ORIGIN}/accept-invitation`);
+
+    const token = url.searchParams.get("token") ?? "";
+    const accepted = await app.call("/api/auth/invitation/accept", json({ token, name: invitee.name, password: invitee.password }));
+    expect(accepted.status).toBe(200);
+    await signIn(app, invitee);
+  });
+
+  it.each(["admin-only", "closed"] as const)("%s: invitations are refused", async (mode) => {
+    const admin = await seedAdmin();
+    const app = testApp(choicesWith(mode));
+
+    const created = await app.call("/api/auth/admin/create-invitation", json({ email: newUser().email }, { cookie: admin }));
+    expect(created.status).toBe(403);
+    expect(await created.text()).toContain("REGISTRATION_NOT_ALLOWED");
+    expect(app.email.messages).toEqual([]);
+  });
+
+  it("admin-only: an administrator creates the account directly", async () => {
+    const admin = await seedAdmin();
+    const app = testApp(choicesWith("admin-only"));
+    const user = newUser();
+
+    const created = await app.call(
+      "/api/auth/admin/create-user",
+      json({ name: user.name, email: user.email, password: user.password, data: { emailVerified: true } }, { cookie: admin }),
+    );
+    expect(created.status).toBe(200);
+    await signIn(app, user);
+  });
+});
+
+describe("phone sign-in", () => {
+  const phone = { allowedCountries: ["+44"], blockedCountries: ["+4479"] };
+
+  it("an invited number signs in with the SMS code", async () => {
+    const admin = await seedAdmin();
+    const app = testApp(choicesWith("invite-only", phone));
+    const number = "+447700900321";
+
+    const invited = await app.call("/api/auth/admin/create-invitation", json({ phoneNumber: number }, { cookie: admin }));
+    expect(invited.status).toBe(200);
+    expect(app.sms.lastTo(number)?.text).toContain("invited you");
+
+    expect((await app.call("/api/auth/phone-number/send-otp", json({ phoneNumber: number }))).status).toBe(200);
+    const code = app.sms.lastTo(number)?.template?.variables["code"] ?? "";
+    const verified = await app.call("/api/auth/phone-number/verify", json({ phoneNumber: number, code }));
+    expect(verified.status).toBe(200);
+    const me = await app.call("/api/me", { headers: { cookie: cookieHeader(verified) } });
+    expect(await me.json()).toMatchObject({ user: { phoneNumber: number, emailIsPlaceholder: true } });
+  });
+
+  it.each([
+    ["outside the allowed countries", "+15550100123"],
+    ["in a blocked range", "+447900900321"],
+  ])("sends no code to a number %s", async (_, number) => {
+    const app = testApp(choicesWith("open", phone));
+    const response = await app.call("/api/auth/phone-number/send-otp", json({ phoneNumber: number }));
+    expect(response.status).toBeGreaterThanOrEqual(400);
+    expect(app.sms.messages).toEqual([]);
+  });
+});
+
+describe("two-factor authentication", () => {
+  it("a user enrols an authenticator; the next sign-in needs its code", async () => {
+    const user = newUser();
+    await seedUser(user);
+    const app = testApp(choicesWith("invite-only"));
+    const cookie = await signIn(app, user);
+
+    const enabled = await app.call("/api/auth/two-factor/enable", json({ password: user.password }, { cookie }));
+    expect(enabled.status).toBe(200);
+    const secret = secretOf((await enabled.json<{ totpURI: string }>()).totpURI);
+    expect((await app.call("/api/auth/two-factor/verify-totp", json({ code: await totpCode(secret) }, { cookie }))).status).toBe(200);
+
+    const challenged = await app.call("/api/auth/sign-in/email", json({ email: user.email, password: user.password }));
+    expect(await challenged.json()).toMatchObject({ twoFactorRedirect: true });
+    const pending = cookieHeader(challenged);
+    expect((await app.call("/api/me", { headers: { cookie: pending } })).status).toBe(401);
+
+    const verified = await app.call("/api/auth/two-factor/verify-totp", json({ code: await totpCode(secret) }, { cookie: pending }));
+    expect(verified.status).toBe(200);
+    expect((await app.call("/api/me", { headers: { cookie: cookieHeader(verified) } })).status).toBe(200);
+  });
+});
+
+describe("email and SMS delivery", () => {
+  const base = {
+    AUTH_BASE_URL: "http://localhost:8787",
+    APP_ID: "",
+    SMS_HEADER: "",
+    SMS_OTP_TEMPLATE_ID: "",
+    SMS_INVITATION_TEMPLATE_ID: "",
+  };
+  const config = appAuthConfig(env);
+
+  it("logs locally and keeps an outbox only on a local host", () => {
+    const local = appNotifications({ ...base, EMAIL_TRANSPORT: "log", SMS_TRANSPORT: "log" }, config);
+    expect(local.outbox).toBeDefined();
+    expect(local.smsOutbox).toBeDefined();
+    const deployed = appNotifications({ ...base, AUTH_BASE_URL: "https://app.example.test", EMAIL_TRANSPORT: "log", SMS_TRANSPORT: "log" }, config);
+    expect(deployed.outbox).toBeUndefined();
+    expect(deployed.smsOutbox).toBeUndefined();
+  });
+
+  it("fails at startup without the communication service binding or with an unknown transport", () => {
+    expect(() => appNotifications({ ...base, APP_ID: "app", EMAIL_TRANSPORT: "communication-service", SMS_TRANSPORT: "log" }, config)).toThrow(
+      /misconfigured/,
+    );
+    expect(() => appNotifications({ ...base, EMAIL_TRANSPORT: "smtp", SMS_TRANSPORT: "log" }, config)).toThrow(/EMAIL_TRANSPORT/);
+  });
+
+  it("the dev outbox route answers on a local host only", async () => {
+    const response = await exports.default.fetch(new Request(`${ORIGIN}/api/dev/outbox`));
+    expect(response.status).toBe(404);
+  });
+});

package/template/modules/auth/files/test/totp.ts

@@ -0,0 +1,49 @@
+/**
+ * An independent RFC 6238 TOTP generator (SHA-1, 6 digits, 30 s), playing the
+ * part of the user's authenticator app in tests. Runs on Web Crypto, so it
+ * works in workerd (Vitest) and in Node (Playwright).
+ */
+
+const BASE32 = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+
+function base32Decode(input: string): Uint8Array<ArrayBuffer> {
+  const clean = input.replace(/=+$/, "").toUpperCase();
+  const bytes: number[] = [];
+  let bits = 0;
+  let value = 0;
+  for (const char of clean) {
+    const index = BASE32.indexOf(char);
+    if (index === -1) throw new Error(`Not base32: ${char}`);
+    value = (value << 5) | index;
+    bits += 5;
+    if (bits >= 8) {
+      bytes.push((value >>> (bits - 8)) & 0xff);
+      bits -= 8;
+    }
+  }
+  return new Uint8Array(bytes);
+}
+
+/** The base32 secret of an `otpauth://totp/...` URI (what the QR code encodes). */
+export function secretOf(totpURI: string): string {
+  const secret = new URL(totpURI).searchParams.get("secret");
+  if (secret === null) throw new Error(`No secret in ${totpURI}`);
+  return secret;
+}
+
+/** The 6-digit code an authenticator app shows for `secret` at `time`. */
+export async function totpCode(secret: string, time: number = Date.now()): Promise<string> {
+  const key = await crypto.subtle.importKey("raw", base32Decode(secret), { name: "HMAC", hash: "SHA-1" }, false, [
+    "sign",
+  ]);
+  const counter = new DataView(new ArrayBuffer(8));
+  counter.setBigUint64(0, BigInt(Math.floor(time / 30_000)), false);
+  const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, counter.buffer));
+  const offset = (mac[mac.length - 1] ?? 0) & 0x0f;
+  const binary =
+    (((mac[offset] ?? 0) & 0x7f) << 24) |
+    ((mac[offset + 1] ?? 0) << 16) |
+    ((mac[offset + 2] ?? 0) << 8) |
+    (mac[offset + 3] ?? 0);
+  return String(binary % 1_000_000).padStart(6, "0");
+}

package/template/modules/auth/files/test/turnstile-fake.ts

@@ -0,0 +1,42 @@
+import { vi } from "vitest";
+
+// Cloudflare Turnstile's documented testing keys
+// (https://developers.cloudflare.com/turnstile/troubleshooting/testing/).
+// Better Auth's captcha plugin calls siteverify with the global `fetch`; the
+// fixtures replace it with this stand-in, so tests never reach the network.
+export const TURNSTILE_TEST = {
+  /** Site key whose widget always passes (`TURNSTILE_SITE_KEY` in wrangler.jsonc). */
+  siteKey: "1x00000000000000000000AA",
+  /** Secret key that accepts any token (`TURNSTILE_SECRET_KEY` in vitest.config.ts). */
+  passSecret: "1x0000000000000000000000000000000AA",
+  /** The token the testing site key hands out. */
+  token: "XXXX.DUMMY.TOKEN.XXXX",
+} as const;
+
+const SITEVERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+
+interface SiteverifyCall {
+  secret: string;
+  response: string;
+  remoteip?: string;
+}
+
+let calls: SiteverifyCall[] = [];
+
+/** The siteverify requests since {@link fakeSiteverify}. */
+export function siteverifyCalls(): readonly SiteverifyCall[] {
+  return calls;
+}
+
+/** Replaces the global `fetch` with a siteverify stand-in that passes only the testing pass secret. */
+export function fakeSiteverify(): void {
+  calls = [];
+  vi.stubGlobal("fetch", (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = input instanceof Request ? input.url : String(input);
+    if (url !== SITEVERIFY_URL) return Promise.reject(new Error(`Unexpected network call in a test: ${url}`));
+    const body = JSON.parse(typeof init?.body === "string" ? init.body : "{}") as SiteverifyCall;
+    calls.push(body);
+    const success = body.response !== "" && body.secret === TURNSTILE_TEST.passSecret;
+    return Promise.resolve(Response.json({ success, "error-codes": success ? [] : ["invalid-input-response"] }));
+  });
+}