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

package/template/modules/auth/files/e2e/auth-accessibility.spec.ts

@@ -0,0 +1,68 @@
+import { expect, test, type Page } from "@playwright/test";
+import { expectNoPageScroll, expectNoViolations, THEMES, VIEWPORTS } from "./axe.js";
+import { signInWithPassword } from "./auth-helpers.js";
+import { AUTH_CHOICES, USERS } from "./auth-seeded.js";
+
+// Zero axe violations on every sign-in page the app offers, in light and dark, at desktop
+// and phone sizes; the account pages are checked signed in.
+interface Screen {
+  name: string;
+  path: string;
+  signedIn?: boolean;
+  on: boolean;
+  ready: (page: Page) => Promise<void>;
+}
+
+const heading = (name: string) => (page: Page) => expect(page.getByRole("heading", { level: 1, name })).toBeVisible();
+const email = AUTH_CHOICES.emailPassword;
+
+const SCREENS: Screen[] = [
+  { name: "sign in", path: "/sign-in", on: true, ready: heading("Sign in") },
+  { name: "phone sign-in", path: "/sign-in/phone", on: AUTH_CHOICES.phoneOtp !== false, ready: heading("Sign in with your phone") },
+  { name: "sign up", path: "/sign-up", on: email && AUTH_CHOICES.registration === "open", ready: heading("Create an account") },
+  { name: "forgot password", path: "/forgot-password", on: email, ready: (p) => expect(p.getByRole("heading", { level: 1 })).toBeVisible() },
+  {
+    name: "invalid invitation",
+    path: "/accept-invitation?token=not-a-real-token",
+    on: true,
+    ready: (p) => expect(p.getByText("This invitation link is invalid")).toBeVisible(),
+  },
+  { name: "account", path: "/account", signedIn: true, on: email, ready: heading("Your account") },
+  {
+    name: "two-factor settings",
+    path: "/account/security",
+    signedIn: true,
+    on: email && AUTH_CHOICES.twoFactor,
+    ready: (p) => expect(p.getByText("Two-factor authentication is off.")).toBeVisible(),
+  },
+  {
+    name: "sessions",
+    path: "/account/sessions",
+    signedIn: true,
+    on: email,
+    ready: (p) => expect(p.getByRole("heading", { level: 1 })).toBeVisible(),
+  },
+];
+
+for (const screen of SCREENS.filter((s) => s.on)) {
+  test.describe(screen.name, () => {
+    if (screen.signedIn === true) {
+      test.beforeEach(async ({ page }) => {
+        await signInWithPassword(page, USERS.axe, "/account");
+        await expect(page.getByRole("heading", { level: 1, name: "Your account" })).toBeVisible();
+      });
+    }
+    for (const theme of THEMES) {
+      for (const [viewport, size] of Object.entries(VIEWPORTS)) {
+        test(`${screen.name} (${theme}, ${viewport}) has no accessibility violations`, async ({ page }) => {
+          await page.emulateMedia({ colorScheme: theme });
+          await page.setViewportSize(size);
+          await page.goto(screen.path);
+          await screen.ready(page);
+          await expectNoPageScroll(page);
+          await expectNoViolations(page);
+        });
+      }
+    }
+  });
+}

package/template/modules/auth/files/e2e/auth-bootstrap-admin.spec.ts

@@ -0,0 +1,58 @@
+import { spawnSync } from "node:child_process";
+import { expect, test } from "@playwright/test";
+import { totpCode } from "../test/totp.js";
+import { emailedLink, signInWithPassword } from "./auth-helpers.js";
+import { adminsCanSignIn, BOOTSTRAP_STATE, BOOTSTRAP_URL } from "./auth-seeded.js";
+
+// The first administrator of a fresh installation, against its own server
+// (playwright.config.ts, a second webServer with no users at all). The operator runs the
+// real CLI against that server's local D1, as `pnpm auth:bootstrap-admin` would.
+const FIRST = { email: "first.admin@example.test", name: "Ada First", password: "the very first admin pass" };
+
+test.use({ baseURL: BOOTSTRAP_URL });
+test.skip(!adminsCanSignIn, "administrators need email + password and 2FA (src/auth-choices.ts)");
+
+function bootstrapAdmin(...args: string[]) {
+  const result = spawnSync("pnpm", ["exec", "inbis-auth", "bootstrap-admin", ...args, "--local", "--persist-to", BOOTSTRAP_STATE], {
+    encoding: "utf8",
+    env: { ...process.env, FORCE_COLOR: "0" },
+  });
+  return { code: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+test("bootstrap-admin issues a one-time link; the first administrator joins and sets up 2FA; a second run is refused", async ({ page }) => {
+  const issued = bootstrapAdmin("--email", FIRST.email, "--url", BOOTSTRAP_URL, "--send-email");
+  expect(issued.code, issued.stdout + issued.stderr).toBe(0);
+  const link = /https?:\/\/\S+/.exec(issued.stdout)?.[0] ?? "";
+  expect(link.startsWith(`${BOOTSTRAP_URL}/accept-invitation?token=`)).toBe(true);
+  // --send-email: the app emailed the same link.
+  expect(await emailedLink(page.request, FIRST.email, "")).toBe(link);
+
+  await page.goto(link);
+  await expect(page.getByRole("heading", { name: "Accept your invitation" })).toBeVisible();
+  await page.getByLabel("Name").fill(FIRST.name);
+  await page.getByLabel("Password", { exact: true }).fill(FIRST.password);
+  await page.getByLabel("Confirm password").fill(FIRST.password);
+  await page.getByRole("button", { name: "Create account" }).click();
+  await expect(page.getByText("Your account is ready")).toBeVisible();
+
+  // Administrators need 2FA: they set it up from the account page.
+  await signInWithPassword(page, FIRST, "/account/security");
+  await page.getByRole("button", { name: "Set up authenticator app" }).click();
+  await page.getByLabel("Current password").fill(FIRST.password);
+  await page.getByRole("button", { name: "Continue" }).click();
+  const secret = (await page.getByTestId("totp-secret").textContent()) ?? "";
+  await page.getByLabel("6-digit code").fill(await totpCode(secret));
+  await page.getByRole("button", { name: "Verify and turn on" }).click();
+  await page.getByRole("button", { name: "I have saved my backup codes" }).click();
+  await expect(page.getByText("Two-factor authentication is on.")).toBeVisible();
+
+  const me = (await (await page.request.get("/api/me")).json()) as { user: { role: string } };
+  expect(me.user.role).toBe("admin");
+
+  // An administrator exists now: the CLI refuses and issues nothing.
+  const again = bootstrapAdmin("--email", "second.admin@example.test", "--url", BOOTSTRAP_URL);
+  expect(again.code).toBe(1);
+  expect(again.stderr).toContain("an administrator already exists");
+  expect(again.stdout).not.toContain("token=");
+});

package/template/modules/auth/files/e2e/auth-helpers.ts

@@ -0,0 +1,74 @@
+import { expect, type APIRequestContext, type Page, type PlaywrightWorkerArgs } from "@playwright/test";
+import { totpCode } from "../test/totp.js";
+import { ADMIN_TOTP_SECRET, TURNSTILE_TEST_TOKEN, USERS } from "./auth-seeded.js";
+
+/** Signs in on the sign-in screen with email and password. */
+export async function signInWithPassword(page: Page, user: { email: string; password: string }, next?: string) {
+  await page.goto(next === undefined ? "/sign-in" : `/sign-in?next=${encodeURIComponent(next)}`);
+  await page.getByLabel("Email").fill(user.email);
+  await page.getByLabel("Password").fill(user.password);
+  await page.getByRole("button", { name: "Sign in" }).click();
+}
+
+interface OutboxEmail {
+  to: string;
+  subject: string;
+  links: string[];
+}
+
+/** The first link of the newest email to `to` whose subject contains `subject` (local outbox). */
+export async function emailedLink(request: APIRequestContext, to: string, subject: string): Promise<string> {
+  let link: string | undefined;
+  await expect
+    .poll(async () => {
+      const { emails } = (await (await request.get("/api/dev/outbox")).json()) as { emails: OutboxEmail[] };
+      link = emails.find((email) => email.to === to && email.subject.includes(subject))?.links[0];
+      return link !== undefined;
+    })
+    .toBe(true);
+  return link ?? "";
+}
+
+interface OutboxSms {
+  to: string;
+  text: string;
+  templateId: string;
+}
+
+/** How many sign-in codes went to `to` so far (local SMS outbox). */
+export async function codesSent(request: APIRequestContext, to: string): Promise<number> {
+  const { messages } = (await (await request.get("/api/dev/sms-outbox")).json()) as { messages: OutboxSms[] };
+  return messages.filter((sms) => sms.to === to && sms.templateId === "auth.phone-otp").length;
+}
+
+/** The newest sign-in code to `to`, once more than `before` have been sent. */
+export async function newestCode(request: APIRequestContext, to: string, before: number): Promise<string> {
+  let code = "";
+  await expect
+    .poll(async () => {
+      const { messages } = (await (await request.get("/api/dev/sms-outbox")).json()) as { messages: OutboxSms[] };
+      const codes = messages.filter((sms) => sms.to === to && sms.templateId === "auth.phone-otp");
+      code = codes.length > before ? (/^(\d{6}) /.exec(codes[0]?.text ?? "")?.[1] ?? "") : "";
+      return code !== "";
+    })
+    .toBe(true);
+  return code;
+}
+
+/**
+ * An API client signed in as the seeded administrator, in its own cookie jar: password,
+ * then the authenticator code (administrators need a 2FA-verified session).
+ */
+export async function adminApi(playwright: PlaywrightWorkerArgs["playwright"], baseURL: string | undefined): Promise<APIRequestContext> {
+  const admin = await playwright.request.newContext({
+    baseURL: baseURL ?? "",
+    // Sign-in needs a Turnstile token: the one the testing site key hands out, sent like the widget would.
+    extraHTTPHeaders: { origin: baseURL ?? "", "x-captcha-response": TURNSTILE_TEST_TOKEN },
+  });
+  const signIn = await admin.post("/api/auth/sign-in/email", { data: { email: USERS.admin.email, password: USERS.admin.password } });
+  expect(signIn.status()).toBe(200);
+  expect(await signIn.json()).toMatchObject({ twoFactorRedirect: true });
+  const verified = await admin.post("/api/auth/two-factor/verify-totp", { data: { code: await totpCode(ADMIN_TOTP_SECRET) } });
+  expect(verified.status()).toBe(200);
+  return admin;
+}

package/template/modules/auth/files/e2e/auth-invitations.spec.ts

@@ -0,0 +1,51 @@
+import { expect, test } from "@playwright/test";
+import { adminApi, emailedLink, signInWithPassword } from "./auth-helpers.js";
+import { adminsCanSignIn, AUTH_CHOICES, invitationsAllowed } from "./auth-seeded.js";
+
+// Invitations: the seeded administrator invites through the API; the invitee has only the
+// browser and the emailed link. Registration "admin-only" and "closed" refuse invitations.
+const INVITEE = { email: "invitee@example.test", name: "Ivy Invitee", password: "an invited pass phrase" };
+
+test.skip(!adminsCanSignIn, "administrators need email + password and 2FA (src/auth-choices.ts)");
+
+test("an invitee accepts an emailed invitation, then signs in; the link works once", async ({ page, playwright, baseURL }) => {
+  test.skip(!invitationsAllowed, `registration "${AUTH_CHOICES.registration}" refuses invitations`);
+  const admin = await adminApi(playwright, baseURL);
+  const created = await admin.post("/api/auth/admin/create-invitation", { data: { email: INVITEE.email } });
+  expect(created.status()).toBe(200);
+  const link = await emailedLink(admin, INVITEE.email, "invited you");
+  await admin.dispose();
+
+  await page.goto(link);
+  await expect(page).toHaveURL(/\/accept-invitation\?token=/);
+  await expect(page.getByRole("heading", { name: "Accept your invitation" })).toBeVisible();
+  await expect(page.getByText(`account for ${INVITEE.email}`)).toBeVisible();
+  await page.getByLabel("Name").fill(INVITEE.name);
+  await page.getByLabel("Password", { exact: true }).fill(INVITEE.password);
+  await page.getByLabel("Confirm password").fill(INVITEE.password);
+  await page.getByRole("button", { name: "Create account" }).click();
+  await expect(page.getByText("Your account is ready")).toBeVisible();
+
+  await signInWithPassword(page, INVITEE, "/account");
+  await expect(page.getByText(`Signed in as ${INVITEE.name} (${INVITEE.email}).`)).toBeVisible();
+
+  // The same link again: refused, no form.
+  await page.goto(link);
+  await expect(page.getByText("This invitation link is invalid, has expired or was already used")).toBeVisible();
+  await expect(page.getByLabel("Name")).toHaveCount(0);
+});
+
+test("the registration mode refuses invitations", async ({ playwright, baseURL }) => {
+  test.skip(invitationsAllowed, `registration "${AUTH_CHOICES.registration}" allows invitations`);
+  const admin = await adminApi(playwright, baseURL);
+  const created = await admin.post("/api/auth/admin/create-invitation", { data: { email: INVITEE.email } });
+  expect(created.status()).toBe(403);
+  expect(await created.text()).toContain("REGISTRATION_NOT_ALLOWED");
+  await admin.dispose();
+});
+
+test("an invalid invitation link shows no form", async ({ page }) => {
+  await page.goto("/accept-invitation?token=not-a-real-token");
+  await expect(page.getByText("This invitation link is invalid, has expired or was already used")).toBeVisible();
+  await expect(page.getByRole("button", { name: "Create account" })).toHaveCount(0);
+});

package/template/modules/auth/files/e2e/auth-phone.spec.ts

@@ -0,0 +1,41 @@
+import { expect, test } from "@playwright/test";
+import { codesSent, newestCode } from "./auth-helpers.js";
+import { AUTH_CHOICES, PHONE_USER, refusedNumber } from "./auth-seeded.js";
+
+// Phone sign-in by SMS code. The seeded user's number is one the app's country rules
+// accept; codes are read from the local SMS outbox (GET /api/dev/sms-outbox).
+
+test.skip(AUTH_CHOICES.phoneOtp === false, "phone sign-in is off (src/auth-choices.ts)");
+
+test("a user signs in with a code sent to their phone", async ({ page }) => {
+  const number = PHONE_USER.phone ?? "";
+  test.skip(number === "", "no test number passes the app's country rules");
+
+  await page.goto("/sign-in/phone");
+  await expect(page.getByRole("heading", { name: "Sign in with your phone" })).toBeVisible();
+  await page.getByLabel("Phone number").fill(number);
+  const before = await codesSent(page.request, number);
+  await page.getByRole("button", { name: "Send code" }).click();
+
+  // A wrong code is refused with a clear message, then the right one signs in.
+  await page.getByLabel("6-digit code").fill("000000");
+  await page.getByRole("button", { name: "Verify" }).click();
+  await expect(page.getByRole("alert")).toContainText("That code is not right");
+  await page.getByLabel("6-digit code").fill(await newestCode(page.request, number, before));
+  await page.getByRole("button", { name: "Verify" }).click();
+
+  await expect(page).toHaveURL(/\/$/);
+  await page.goto("/account");
+  await expect(page.getByText(`Signed in as ${PHONE_USER.name}`)).toBeVisible();
+});
+
+test("a number from a country the app does not serve gets no code", async ({ page }) => {
+  const number = refusedNumber();
+  test.skip(number === undefined, "the app's country rules refuse no number");
+
+  await page.goto("/sign-in/phone");
+  await page.getByLabel("Phone number").fill(number ?? "");
+  await page.getByRole("button", { name: "Send code" }).click();
+  await expect(page.getByRole("alert")).toContainText("Phone numbers from this country cannot be used here.");
+  expect(await codesSent(page.request, number ?? "")).toBe(0);
+});

package/template/modules/auth/files/e2e/auth-seeded.ts

@@ -0,0 +1,97 @@
+// What playwright.config.ts seeds into the local D1 for the auth specs, and what the specs
+// derive from the app's sign-in choices (src/auth-choices.ts). Local values only, never
+// real secrets.
+import { AUTH_CHOICES, type AuthChoices } from "../src/auth-choices.js";
+
+export { AUTH_CHOICES };
+
+/** The Worker's AUTH_SECRET in e2e runs (passed with --var). */
+export const E2E_AUTH_SECRET = "e2e-only-secret-0123456789abcdefghijkl";
+
+/** Cloudflare's Turnstile testing secret, which accepts any token. */
+export const TURNSTILE_TEST_SECRET = "1x0000000000000000000000000000000AA";
+
+/** The token Turnstile's testing site key hands out (sent like the widget would). */
+export const TURNSTILE_TEST_TOKEN = "XXXX.DUMMY.TOKEN.XXXX";
+
+/** The seeded administrators' authenticator (base32, as in an otpauth:// URI). */
+export const ADMIN_TOTP_SECRET = "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP";
+
+const PASSWORD = "correct horse battery";
+
+/** Seeded users, each for one spec so specs never disturb each other. */
+export const USERS = {
+  /** Signs in and out (auth-sign-in.spec.ts). */
+  member: { name: "Ada Lovelace", email: "ada@example.test", password: PASSWORD },
+  /** Turns 2FA on (auth-two-factor.spec.ts). */
+  totp: { name: "Grace Hopper", email: "totp@example.test", password: PASSWORD },
+  /** Pages checked with axe while signed in (auth-accessibility.spec.ts). */
+  axe: { name: "Alan Turing", email: "axe@example.test", password: PASSWORD },
+  /** An administrator with 2FA, who sends invitations (auth-invitations.spec.ts). */
+  admin: { name: "Grace Admin", email: "admin@example.test", password: PASSWORD },
+} as const;
+
+const SAMPLE_NUMBERS = ["+447700900123", "+15550100123", "+61491570123", "+33612345678", "+819012345678"];
+
+/** An E.164 test number starting with `prefix`: 11 digits in all. */
+const numberFor = (prefix: string) => `${prefix}${"0".repeat(Math.max(0, 11 - prefix.length))}1`;
+
+/**
+ * A number the app's phone country rules accept (an allowed prefix, not a blocked one),
+ * for the seeded phone user, or `undefined` when phone sign-in is off.
+ */
+export function acceptedNumber(choices: AuthChoices = AUTH_CHOICES): string | undefined {
+  const phone = choices.phoneOtp;
+  if (phone === false) return undefined;
+  const blocked = (n: string) => phone.blockedCountries.some((prefix) => n.startsWith(prefix));
+  const candidates = phone.allowedCountries === undefined ? SAMPLE_NUMBERS : phone.allowedCountries.map(numberFor);
+  return candidates.find((n) => !blocked(n));
+}
+
+/** A number the app's phone country rules refuse, or `undefined` when they refuse none. */
+export function refusedNumber(choices: AuthChoices = AUTH_CHOICES): string | undefined {
+  const phone = choices.phoneOtp;
+  if (phone === false) return undefined;
+  const first = phone.blockedCountries[0];
+  if (first !== undefined) return numberFor(first);
+  const allowed = phone.allowedCountries;
+  return allowed === undefined ? undefined : SAMPLE_NUMBERS.find((n) => !allowed.some((prefix) => n.startsWith(prefix)));
+}
+
+/** A seeded user with a verified phone number, who signs in by SMS code (auth-phone.spec.ts). */
+export const PHONE_USER = { name: "Pat Phone", email: "phone@example.test", password: PASSWORD, phone: acceptedNumber() };
+
+/** The `wrangler dev` flags of an e2e server at `baseURL`: test secrets, and local test mode on. */
+export function authDevVars(baseURL: string): string {
+  return [
+    `--var AUTH_SECRET:${E2E_AUTH_SECRET}`,
+    `--var TURNSTILE_SECRET_KEY:${TURNSTILE_TEST_SECRET}`,
+    `--var AUTH_BASE_URL:${baseURL}`,
+    "--var LOCAL_TEST_MODE:true",
+  ].join(" ");
+}
+
+/** The shell commands that seed the users above into the e2e database at `state`. */
+export function authSeedCommands(state: string): string[] {
+  const seed = (user: { name: string; email: string; password: string }, extra = "") =>
+    `node scripts/seed-user.mjs --persist-to ${state} --email ${user.email} --name '${user.name}' --password '${user.password}'${extra}`;
+  const admin2fa = ` --role admin --totp-secret ${ADMIN_TOTP_SECRET} --auth-secret ${E2E_AUTH_SECRET}`;
+  return [
+    seed(USERS.member),
+    seed(USERS.totp),
+    seed(USERS.axe),
+    seed(USERS.admin, admin2fa),
+    ...(PHONE_USER.phone === undefined ? [] : [seed(PHONE_USER, ` --phone ${PHONE_USER.phone}`)]),
+  ];
+}
+
+/** The e2e server with a fresh installation (no users), for bootstrap-admin: the port after the main one. */
+export const BOOTSTRAP_PORT = Number(process.env["E2E_PORT"] ?? 8790) + 1;
+export const BOOTSTRAP_URL = `http://localhost:${BOOTSTRAP_PORT}`;
+export const BOOTSTRAP_STATE = ".wrangler/e2e-bootstrap";
+
+/** Whether this app's registration mode lets administrators invite (`open`, `invite-only`). */
+export const invitationsAllowed = AUTH_CHOICES.registration === "open" || AUTH_CHOICES.registration === "invite-only";
+
+/** Whether an administrator can sign in (email + password with 2FA). */
+export const adminsCanSignIn = AUTH_CHOICES.emailPassword && AUTH_CHOICES.twoFactor;

package/template/modules/auth/files/e2e/auth-sign-in.spec.ts

@@ -0,0 +1,57 @@
+import { expect, test } from "@playwright/test";
+import { signInWithPassword } from "./auth-helpers.js";
+import { AUTH_CHOICES, USERS } from "./auth-seeded.js";
+
+// Email + password sign-in, the account page and signing out, as a visitor does it.
+const USER = USERS.member;
+
+test.skip(!AUTH_CHOICES.emailPassword, "email + password sign-in is off (src/auth-choices.ts)");
+
+test("a visitor signs in from the header, reaches the account page, and signs out", async ({ page }) => {
+  await page.goto("/");
+  await page.getByRole("link", { name: "Sign in" }).click();
+  await expect(page.getByRole("heading", { name: "Sign in" })).toBeVisible();
+  await expect(page.getByText("Sign in to React Hono App")).toBeVisible();
+
+  await page.getByLabel("Email").fill(USER.email);
+  await page.getByLabel("Password").fill(USER.password);
+  await page.getByRole("button", { name: "Sign in" }).click();
+
+  // Back where they came from, with their name in the header.
+  await expect(page).toHaveURL(/\/$/);
+  await page.getByRole("link", { name: `Account: ${USER.name}` }).click();
+  await expect(page.getByRole("heading", { level: 1, name: "Your account" })).toBeVisible();
+  await expect(page.getByText(`Signed in as ${USER.name} (${USER.email}).`)).toBeVisible();
+
+  // The session cookie is HttpOnly, so page scripts cannot read it; it survives a reload.
+  const session = (await page.context().cookies()).find((c) => c.name.endsWith("session_token"));
+  expect(session?.httpOnly).toBe(true);
+  await page.reload();
+  await expect(page.getByRole("heading", { level: 1, name: "Your account" })).toBeVisible();
+
+  await page.getByRole("button", { name: "Sign out" }).click();
+  await expect(page).toHaveURL(/\/sign-in$/);
+  await page.goto("/account");
+  await expect(page).toHaveURL(/\/sign-in\?next=%2Faccount$/);
+});
+
+test("the account page sends a signed-out visitor to sign in and back", async ({ page }) => {
+  await page.goto("/account");
+  await expect(page).toHaveURL(/\/sign-in\?next=%2Faccount$/);
+  await page.getByLabel("Email").fill(USER.email);
+  await page.getByLabel("Password").fill(USER.password);
+  await page.getByRole("button", { name: "Sign in" }).click();
+  await expect(page.getByRole("heading", { level: 1, name: "Your account" })).toBeVisible();
+});
+
+test("a wrong password shows an error and does not sign in", async ({ page }) => {
+  await signInWithPassword(page, { email: USER.email, password: "not the right password" });
+  await expect(page.getByRole("alert")).toContainText("The email or password is incorrect.");
+  await expect(page).toHaveURL(/\/sign-in$/);
+});
+
+test("the sign-in screen offers sign-up exactly when registration is open", async ({ page }) => {
+  await page.goto("/sign-in");
+  await expect(page.getByRole("heading", { name: "Sign in" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Create an account" })).toHaveCount(AUTH_CHOICES.registration === "open" ? 1 : 0);
+});

package/template/modules/auth/files/e2e/auth-two-factor.spec.ts

@@ -0,0 +1,44 @@
+import { expect, test } from "@playwright/test";
+import { totpCode } from "../test/totp.js";
+import { signInWithPassword } from "./auth-helpers.js";
+import { AUTH_CHOICES, USERS } from "./auth-seeded.js";
+
+// Two-factor authentication: one user's lifecycle, in order (each test starts where the
+// last one left off): enrol an authenticator, then sign in with its code.
+const USER = USERS.totp;
+let secret = "";
+
+test.describe.configure({ mode: "serial" });
+test.skip(!AUTH_CHOICES.twoFactor, "two-factor authentication is off (src/auth-choices.ts)");
+
+test("a user enrols an authenticator app from the account page", async ({ page }) => {
+  await signInWithPassword(page, USER, "/account");
+  await page.getByRole("link", { name: "Two-factor authentication" }).click();
+  await expect(page.getByRole("heading", { name: "Two-factor authentication" })).toBeVisible();
+  await expect(page.getByText("Two-factor authentication is off.")).toBeVisible();
+
+  await page.getByRole("button", { name: "Set up authenticator app" }).click();
+  await page.getByLabel("Current password").fill(USER.password);
+  await page.getByRole("button", { name: "Continue" }).click();
+  await expect(page.getByRole("img", { name: "QR code for your authenticator app" })).toBeVisible();
+  secret = (await page.getByTestId("totp-secret").textContent()) ?? "";
+  expect(secret).toMatch(/^[A-Z2-7]+$/);
+
+  await page.getByLabel("6-digit code").fill(await totpCode(secret));
+  await page.getByRole("button", { name: "Verify and turn on" }).click();
+  await expect(page.getByRole("heading", { name: "Save your backup codes" })).toBeVisible();
+  await page.getByRole("button", { name: "I have saved my backup codes" }).click();
+  await expect(page.getByText("Two-factor authentication is on.")).toBeVisible();
+});
+
+test("sign-in then asks for the authenticator code", async ({ page }) => {
+  await signInWithPassword(page, USER, "/account");
+  await expect(page.getByRole("heading", { name: "Two-factor authentication" })).toBeVisible();
+  await page.getByLabel("6-digit code").fill("000000");
+  await page.getByRole("button", { name: "Verify" }).click();
+  await expect(page.getByRole("alert")).toContainText("That code is not valid.");
+
+  await page.getByLabel("6-digit code").fill(await totpCode(secret));
+  await page.getByRole("button", { name: "Verify" }).click();
+  await expect(page.getByRole("heading", { level: 1, name: "Your account" })).toBeVisible();
+});

package/template/modules/auth/files/scripts/seed-user.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// Seeds (or re-seeds) one verified email + password user into the LOCAL D1 database,
+// for trying sign-in by hand and for the Playwright suite:
+//
+//   pnpm db:migrate && pnpm db:seed [--email a@b.test] [--password '...'] [--name 'Ada'] [--role admin]
+//     [--phone +15550100123] [--totp-secret BASE32 --auth-secret <AUTH_SECRET>] [--persist-to <dir>]
+//
+// The password is hashed with Better Auth's own hasher, so the account is exactly what a
+// sign-up would have created. Local only: it never touches a remote database. The first
+// administrator of a real installation comes from `pnpm auth:bootstrap-admin`.
+import { execFileSync } from "node:child_process";
+import { stdout } from "node:process";
+import { parseArgs } from "node:util";
+import { createId } from "@awsmbiz/inbis-core";
+import { hashPassword, symmetricEncrypt } from "better-auth/crypto";
+
+const { values } = parseArgs({
+  options: {
+    email: { type: "string", default: "ada@example.test" },
+    password: { type: "string", default: "correct horse battery" },
+    name: { type: "string", default: "Ada Lovelace" },
+    "persist-to": { type: "string" },
+    // The coarse platform role: "user" (default) or "admin".
+    role: { type: "string", default: "user" },
+    // A verified phone number (E.164), so the user can also sign in by SMS code.
+    phone: { type: "string" },
+    // An enrolled authenticator with this base32 TOTP secret (2FA on). Needs --auth-secret.
+    "totp-secret": { type: "string" },
+    // The Worker's AUTH_SECRET, which encrypts the stored TOTP secret.
+    "auth-secret": { type: "string" },
+  },
+});
+if (values.role !== "user" && values.role !== "admin") throw new Error('--role must be "user" or "admin".');
+if (values["totp-secret"] !== undefined && values["auth-secret"] === undefined) {
+  throw new Error("--totp-secret needs --auth-secret (the Worker's AUTH_SECRET).");
+}
+
+const quote = (value) => `'${String(value).replaceAll("'", "''")}'`;
+const userId = createId();
+const now = Date.now();
+const hash = await hashPassword(values.password);
+const totp = values["totp-secret"];
+const phone = values.phone === undefined ? "NULL" : quote(values.phone);
+
+const sql = [
+  // Cascades to the user's accounts, sessions and authenticator.
+  `DELETE FROM user WHERE email = ${quote(values.email)};`,
+  `INSERT INTO user (id, name, email, email_verified, role, phone_number, phone_number_verified, two_factor_enabled, created_at, updated_at) VALUES (${quote(userId)}, ${quote(values.name)}, ${quote(values.email)}, 1, ${quote(values.role)}, ${phone}, ${values.phone === undefined ? 0 : 1}, ${totp === undefined ? 0 : 1}, ${now}, ${now});`,
+  `INSERT INTO account (id, account_id, provider_id, user_id, password, created_at, updated_at) VALUES (${quote(createId())}, ${quote(userId)}, 'credential', ${quote(userId)}, ${quote(hash)}, ${now}, ${now});`,
+];
+if (totp !== undefined) {
+  // Better Auth stores imported secrets as `base32:<secret>`, encrypted with the auth secret.
+  const key = values["auth-secret"];
+  const secret = await symmetricEncrypt({ key, data: `base32:${totp}` });
+  const backupCodes = await symmetricEncrypt({ key, data: JSON.stringify([]) });
+  sql.push(
+    `INSERT INTO two_factor (id, secret, backup_codes, user_id, verified) VALUES (${quote(createId())}, ${quote(secret)}, ${quote(backupCodes)}, ${quote(userId)}, 1);`,
+  );
+}
+
+const args = ["d1", "execute", "AUTH_DB", "--local", "--command", sql.join("\n")];
+if (values["persist-to"] !== undefined) args.push("--persist-to", values["persist-to"]);
+execFileSync("wrangler", args, { stdio: ["ignore", "ignore", "inherit"] });
+stdout.write(`Seeded ${values.email} (local D1).\n`);

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

@@ -0,0 +1,33 @@
+import type { RegistrationMode } from "@awsmbiz/inbis-auth";
+
+/**
+ * The sign-in choices made when this app was created (create-inbis-app). They are
+ * yours to change: src/auth-config.ts turns them into the auth config, and the
+ * tests read them to know which journeys apply.
+ */
+export interface AuthChoices {
+  /** Email + password sign-in (and password reset, email verification). */
+  emailPassword: boolean;
+  /**
+   * Sign-in with an SMS code, or `false`. Countries are calling-code prefixes
+   * (`"+44"`, `"+1876"`): absent `allowedCountries` means every country;
+   * `blockedCountries` wins over it. There is no platform default.
+   */
+  phoneOtp: false | { allowedCountries?: readonly string[]; blockedCountries: readonly string[] };
+  /** Two-factor authentication with an authenticator app (password sign-ins). Administrators need it. */
+  twoFactor: boolean;
+  /**
+   * Who may create an account: `open` (anyone signs up), `invite-only`
+   * (administrators create accounts or invite), `admin-only` (administrators
+   * create accounts; invitations are refused), `closed` (no new accounts but
+   * the first administrator).
+   */
+  registration: RegistrationMode;
+}
+
+export const AUTH_CHOICES: AuthChoices = {
+  emailPassword: true,
+  phoneOtp: false,
+  twoFactor: true,
+  registration: "invite-only",
+};

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

@@ -0,0 +1,55 @@
+import { defineAuthConfig, type InbisAuthConfig } from "@awsmbiz/inbis-auth";
+import { AUTH_CHOICES, type AuthChoices } from "./auth-choices.js";
+import { localTestMode } from "./local-test-mode.js";
+
+/** The Worker variables the auth config reads (they differ per environment). */
+export type AuthConfigVars = Pick<Env, "AUTH_BASE_URL" | "TRUSTED_ORIGINS" | "TURNSTILE_SITE_KEY" | "EMAIL_FROM" | "LOCAL_TEST_MODE">;
+
+/**
+ * Raised auth rate limits for the Playwright suite only (`LOCAL_TEST_MODE`, local hosts).
+ * Better Auth's count for a route starts over only after a whole window with no request,
+ * so over a suite run every page load adds up; deployed Workers keep the defaults.
+ */
+const LOCAL_TEST_RATE_LIMIT = {
+  default: { window: 60, max: 5000 },
+  signIn: { window: 60, max: 500 },
+  passwordReset: { window: 60, max: 100 },
+  otp: { window: 60, max: 100 },
+  twoFactor: { window: 60, max: 500 },
+};
+const LOCAL_TEST_PHONE_LIMITS = {
+  perNumberLimit: { window: 3600, max: 50 },
+  perIpLimit: { window: 3600, max: 200 },
+};
+
+/**
+ * The app's auth config (`@awsmbiz/inbis-auth`): the sign-in choices from
+ * src/auth-choices.ts, plus what varies per environment from Worker variables.
+ * Everything else is the platform's defaults; see the package README for every option.
+ */
+export function appAuthConfig(vars: AuthConfigVars, choices: AuthChoices = AUTH_CHOICES): InbisAuthConfig {
+  const testing = localTestMode(vars);
+  const phoneOtp = choices.phoneOtp;
+  return defineAuthConfig({
+    app: {
+      name: "React Hono App",
+      baseURL: vars.AUTH_BASE_URL,
+      trustedOrigins: vars.TRUSTED_ORIGINS.split(",")
+        .map((origin) => origin.trim())
+        .filter((origin) => origin !== ""),
+    },
+    registration: { mode: choices.registration },
+    methods: {
+      emailPassword: choices.emailPassword ? {} : false,
+      phoneOtp: phoneOtp === false ? false : { ...phoneOtp, ...(testing ? LOCAL_TEST_PHONE_LIMITS : {}) },
+    },
+    twoFactor: choices.twoFactor ? {} : false,
+    // Verification, password reset and email invitations (sent through src/notifications.ts).
+    ...(choices.emailPassword ? { emails: { from: vars.EMAIL_FROM } } : {}),
+    security: {
+      // Turnstile before sign-in, sign-up, password reset and phone code requests.
+      captcha: { provider: "cloudflare-turnstile", siteKey: vars.TURNSTILE_SITE_KEY },
+      ...(testing ? { rateLimit: LOCAL_TEST_RATE_LIMIT } : {}),
+    },
+  });
+}