@flaredev/cli 0.2.0 → 0.4.0

package/templates/app/lib/auth-config.ts

@@ -1,33 +1,38 @@
-/**
- * How people sign in to this app. `flare create` wrote the choices you made; change
- * them here any time. Every method's tables already exist, so switching one on or off
- * needs no migration, and a method that's off is refused by the API, not just hidden.
- *
- * Email and password sign-in is always available.
- */
-export const authConfig = {
-  /** A sign-in link by email. */
-  magicLink: true,
-  /** A 6-digit sign-in code by email. */
-  emailOtp: true,
-  /** Face ID, Touch ID, Windows Hello or a security key. */
-  passkeys: true,
-  twoFactor: {
-    /** Codes from an authenticator app (TOTP), with backup codes. */
-    authenticator: true,
-    /** Codes by email as the second step. */
-    email: true,
-  },
-  /**
-   * Social sign-in. Each provider also needs its credentials (see .dev.vars.example);
-   * without them its button stays hidden.
-   */
-  social: [] as SocialProvider[],
-  /** Refuse password sign-in until the email address is verified. */
-  requireEmailVerification: false,
-};
-
-export type SocialProvider = "google" | "github" | "apple" | "microsoft";
-
-/** Whether any second factor can be set up. */
-export const twoFactorAvailable = authConfig.twoFactor.authenticator || authConfig.twoFactor.email;
+/**
+ * How people sign in to this app. `flare create` wrote the choices you made; change
+ * them here any time. Every method's tables already exist, so switching one on or off
+ * needs no migration, and a method that's off is refused by the API, not just hidden.
+ *
+ * Email and password sign-in is always available.
+ */
+export const authConfig = {
+  /** A sign-in link by email. */
+  magicLink: true,
+  /** A 6-digit sign-in code by email. */
+  emailOtp: true,
+  /** Face ID, Touch ID, Windows Hello or a security key. */
+  passkeys: true,
+  twoFactor: {
+    /** Codes from an authenticator app (TOTP), with backup codes. */
+    authenticator: true,
+    /** Codes by email as the second step. */
+    email: true,
+  },
+  /**
+   * Social sign-in. Each provider also needs its credentials (see .dev.vars.example);
+   * without them its button stays hidden.
+   */
+  social: [] as SocialProvider[],
+  /** Refuse password sign-in until the email address is verified. */
+  requireEmailVerification: false,
+  /**
+   * Check new passwords against Have I Been Pwned's breach list. Only the first five
+   * characters of the password's hash are sent, and an outage lets the password through.
+   */
+  checkBreachedPasswords: true,
+};
+
+export type SocialProvider = "google" | "github" | "apple" | "microsoft";
+
+/** Whether any second factor can be set up. */
+export const twoFactorAvailable = authConfig.twoFactor.authenticator || authConfig.twoFactor.email;

package/templates/app/lib/auth.ts

@@ -11,6 +11,7 @@ import { twoFactor } from "better-auth/plugins/two-factor";
 import { hashPassword, verifyPassword } from "@flaredev/core";
 import { getDb, schema } from "@/db";
 import { authConfig, type SocialProvider } from "./auth-config";
+import { checkPassword, isBreachedPassword, PASSWORD_MAX_LENGTH } from "./password-rules";
 import { sendEmailCode, sendMagicLink, sendPasswordReset, sendTwoFactorCode, sendVerificationEmail } from "./auth-emails";
 
 const vars = env as unknown as Record<string, string | undefined>;
@@ -51,6 +52,38 @@ function disabledPath(path: string): boolean {
   return false;
 }
 
+/** Where a new password arrives, and what it's called in the body. */
+const NEW_PASSWORD_FIELDS: Record<string, string> = {
+  "/sign-up/email": "password",
+  "/reset-password": "newPassword",
+  "/change-password": "newPassword",
+};
+
+/**
+ * The same password rules the sign-up and reset forms show as you type
+ * (lib/password-rules.ts), enforced here so the API agrees with the screens.
+ * Checked on the way in, before the password is hashed or stored.
+ */
+async function guardPassword(path: string, body: Record<string, unknown> | undefined) {
+  const field = NEW_PASSWORD_FIELDS[path];
+  if (!field) return;
+  const password = body?.[field];
+  if (typeof password !== "string") return;
+
+  if (password.length > PASSWORD_MAX_LENGTH) {
+    throw new APIError("BAD_REQUEST", { message: `Passwords can be at most ${PASSWORD_MAX_LENGTH} characters.` });
+  }
+  const check = checkPassword(password, [body?.email as string | undefined, body?.name as string | undefined]);
+  if (!check.valid) throw new APIError("BAD_REQUEST", { message: check.advice ?? "That password is too short." });
+
+  // A password in a public breach list is already guessed, however strong it looks.
+  if (authConfig.checkBreachedPasswords && (await isBreachedPassword(password))) {
+    throw new APIError("BAD_REQUEST", {
+      message: "That password has appeared in a data breach, so it isn't safe to use here. Pick a different one.",
+    });
+  }
+}
+
 export const auth = betterAuth({
   appName: "__APP_NAME__",
   secret: env.BETTER_AUTH_SECRET,
@@ -90,6 +123,7 @@ export const auth = betterAuth({
   hooks: {
     before: createAuthMiddleware(async (ctx) => {
       if (disabledPath(ctx.path)) throw new APIError("NOT_FOUND", { message: "This sign-in method isn't enabled." });
+      await guardPassword(ctx.path, ctx.body as Record<string, unknown> | undefined);
     }),
   },
   plugins: [

package/templates/app/lib/cache.ts

@@ -1,83 +1,83 @@
-import { revalidateTag, unstable_cache } from "next/cache";
-import type { ChangeEvent } from "@flaredev/core/server";
-
-/**
- * Caching for data you read far more often than you write.
- *
- * Only the **data cache** (Workers KV) is configured in `vite.config.ts`. It is
- * what `cached()` below, `fetch()` and `"use cache"` write to. Shared by every
- * colo and every isolate, so a value computed once is reused until it expires or
- * its tag is revalidated.
- *
- * vinext's page-level CDN cache (the Workers Cache `cdn` adapter) is off until a
- * vinext fix lands: in the current beta, pages that redirect break behind it.
- *
- * Nothing here caches per-user data: everything keyed by session belongs
- * outside the cache, since these entries are shared between visitors.
- */
-
-/** How long cached values stay fresh, in seconds. Pick the one that matches how stale you can stand. */
-export const TTL = {
-  /** Changes often, cheap to recompute: counts, dashboards. */
-  short: 60,
-  /** The usual case: lists and detail views behind a resource tag. */
-  medium: 5 * 60,
-  /** Rarely changes: settings, published content, reference tables. */
-  long: 60 * 60,
-} as const;
-
-/** Tag for everything derived from a resource, e.g. `resource/Deal`. */
-export const resourceTag = (resource: string) => `resource/${resource}`;
-
-/** Tag for one record, e.g. `resource/Deal/0f9…`. */
-export const recordTag = (resource: string, id: string) => `resource/${resource}/${id}`;
-
-/**
- * The KV data cache silently ignores tags containing `:`, `\` or control
- * characters — the entry is stored untagged, so no revalidation ever reaches
- * it. Refuse them here instead, where the mistake is still visible.
- */
-function checkTag(tag: string): string {
-  if (!tag || tag.length > 256 || /[\x00-\x1f\\:]/.test(tag)) {
-    throw new Error(`Cache tag "${tag}" can't be used: tags must be 1–256 characters without ":", "\\" or control characters.`);
-  }
-  return tag;
-}
-
-/**
- * Cache the result of an async function in the data cache.
- *
- * `keyParts` identify the value (include every argument the result depends on);
- * `tags` say what invalidates it. Cached functions must not read cookies,
- * headers, or anything else request-specific — the value is shared.
- *
- * ```ts
- * const openDeals = cached(
- *   () => getDb().select({ total: count() }).from(deals).where(eq(deals.stage, "open")),
- *   ["deals", "open-count"],
- *   { tags: [resourceTag("Deal")] },
- * );
- * ```
- */
-export function cached<Args extends unknown[], Value>(
-  fn: (...args: Args) => Promise<Value>,
-  keyParts: string[],
-  options: { tags?: string[]; revalidate?: number } = {},
-) {
-  return unstable_cache(fn, keyParts, {
-    revalidate: options.revalidate ?? TTL.medium,
-    tags: (options.tags ?? []).map(checkTag),
-  });
-}
-
-/**
- * Drop everything cached for a resource (and for the record that changed).
- * `lib/admin.ts` and `lib/api.ts` pass this to the store, so writes through the
- * admin or the REST API invalidate without anyone remembering to call it.
- */
-export function revalidateResource({ resource, action, id }: ChangeEvent) {
-  // { expire: 0 }: drop the entry now rather than serving it stale while it refreshes.
-  // A record someone just edited should never come back with its old values.
-  revalidateTag(resourceTag(resource), { expire: 0 });
-  if (action !== "create") revalidateTag(recordTag(resource, id), { expire: 0 });
-}
+import { revalidateTag, unstable_cache } from "next/cache";
+import type { ChangeEvent } from "@flaredev/core/server";
+
+/**
+ * Caching for data you read far more often than you write.
+ *
+ * Only the **data cache** (Workers KV) is configured in `vite.config.ts`. It is
+ * what `cached()` below, `fetch()` and `"use cache"` write to. Shared by every
+ * colo and every isolate, so a value computed once is reused until it expires or
+ * its tag is revalidated.
+ *
+ * vinext's page-level CDN cache (the Workers Cache `cdn` adapter) is off until a
+ * vinext fix lands: in the current beta, pages that redirect break behind it.
+ *
+ * Nothing here caches per-user data: everything keyed by session belongs
+ * outside the cache, since these entries are shared between visitors.
+ */
+
+/** How long cached values stay fresh, in seconds. Pick the one that matches how stale you can stand. */
+export const TTL = {
+  /** Changes often, cheap to recompute: counts, dashboards. */
+  short: 60,
+  /** The usual case: lists and detail views behind a resource tag. */
+  medium: 5 * 60,
+  /** Rarely changes: settings, published content, reference tables. */
+  long: 60 * 60,
+} as const;
+
+/** Tag for everything derived from a resource, e.g. `resource/Deal`. */
+export const resourceTag = (resource: string) => `resource/${resource}`;
+
+/** Tag for one record, e.g. `resource/Deal/0f9…`. */
+export const recordTag = (resource: string, id: string) => `resource/${resource}/${id}`;
+
+/**
+ * The KV data cache silently ignores tags containing `:`, `\` or control
+ * characters — the entry is stored untagged, so no revalidation ever reaches
+ * it. Refuse them here instead, where the mistake is still visible.
+ */
+function checkTag(tag: string): string {
+  if (!tag || tag.length > 256 || /[\x00-\x1f\\:]/.test(tag)) {
+    throw new Error(`Cache tag "${tag}" can't be used: tags must be 1–256 characters without ":", "\\" or control characters.`);
+  }
+  return tag;
+}
+
+/**
+ * Cache the result of an async function in the data cache.
+ *
+ * `keyParts` identify the value (include every argument the result depends on);
+ * `tags` say what invalidates it. Cached functions must not read cookies,
+ * headers, or anything else request-specific — the value is shared.
+ *
+ * ```ts
+ * const openDeals = cached(
+ *   () => getDb().select({ total: count() }).from(deals).where(eq(deals.stage, "open")),
+ *   ["deals", "open-count"],
+ *   { tags: [resourceTag("Deal")] },
+ * );
+ * ```
+ */
+export function cached<Args extends unknown[], Value>(
+  fn: (...args: Args) => Promise<Value>,
+  keyParts: string[],
+  options: { tags?: string[]; revalidate?: number } = {},
+) {
+  return unstable_cache(fn, keyParts, {
+    revalidate: options.revalidate ?? TTL.medium,
+    tags: (options.tags ?? []).map(checkTag),
+  });
+}
+
+/**
+ * Drop everything cached for a resource (and for the record that changed).
+ * `lib/dashboard.ts` and `lib/api.ts` pass this to the store, so writes through the
+ * admin or the REST API invalidate without anyone remembering to call it.
+ */
+export function revalidateResource({ resource, action, id }: ChangeEvent) {
+  // { expire: 0 }: drop the entry now rather than serving it stale while it refreshes.
+  // A record someone just edited should never come back with its old values.
+  revalidateTag(resourceTag(resource), { expire: 0 });
+  if (action !== "create") revalidateTag(recordTag(resource, id), { expire: 0 });
+}

package/templates/app/lib/csv.ts

@@ -0,0 +1,24 @@
+/**
+ * CSV, the way spreadsheets expect it (RFC 4180): fields holding a comma, a quote or a
+ * line break are quoted, and quotes inside them are doubled.
+ *
+ * Shared by the table's "export selected" (in the browser) and the export action (on
+ * the server), so both produce the same file.
+ */
+
+export interface CsvColumn {
+  key: string;
+  label: string;
+}
+
+export function csvCell(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  const text = Array.isArray(value) ? value.join("; ") : value instanceof Date ? value.toISOString() : String(value);
+  return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+
+export function toCsv(rows: Record<string, unknown>[], columns: CsvColumn[]): string {
+  const header = columns.map((column) => csvCell(column.label)).join(",");
+  const body = rows.map((row) => columns.map((column) => csvCell(row[column.key])).join(","));
+  return [header, ...body].join("\r\n");
+}

package/templates/app/lib/dashboard-nav.ts

@@ -0,0 +1,15 @@
+// Extra dashboard sidebar links (maintained by flare generators such as `flare gen security`).
+// Add your own links outside the generated block.
+// generated:start
+export interface DashboardLink {
+  label: string;
+  href: string;
+  /** A resource icon name, e.g. "shield" (see components/dashboard/resource-icon.tsx). */
+  icon: string;
+}
+
+export const generatedDashboardLinks: DashboardLink[] = [];
+// generated:end
+
+/** Links shown under "Platform" in the dashboard sidebar. */
+export const dashboardLinks: DashboardLink[] = [...generatedDashboardLinks, { label: "API reference", href: "/api/reference", icon: "book" }];

package/templates/app/lib/dashboard.ts

@@ -0,0 +1,165 @@
+import { headers } from "next/headers";
+import { notFound, redirect } from "next/navigation";
+import { allowedActions, can, type Policy, type PolicyAction, type Resource } from "@flaredev/core";
+import { and, count, gte, lt } from "drizzle-orm";
+import type { SQLiteTable } from "drizzle-orm/sqlite-core";
+import { createResourceStore, type ResourceStore } from "@flaredev/core/server";
+import { getDb } from "@/db";
+import { policies } from "@/policies";
+import { resourceTables } from "@/resources/server";
+import { currentUser } from "./api";
+import { auth } from "./auth";
+import { cached, resourceTag, revalidateResource, TTL } from "./cache";
+
+/**
+ * Roles that always reach the dashboard, whatever the policies say. Other roles get in when a
+ * policy grants them read access to at least one resource.
+ * Register roles with `flare role:add`, assign with `flare user:role`.
+ */
+export const ADMIN_ROLES = ["admin", "staff"];
+
+export function policyFor(resourceName: string): Policy | undefined {
+  return (policies as Record<string, Policy | undefined>)[resourceName];
+}
+
+export async function dashboardSession() {
+  const session = await auth.api.getSession({ headers: await headers() });
+  if (!session) return { session: null, role: null, allowed: false } as const;
+  const role = (session.user as { role?: string | null }).role ?? null;
+  const readable = allResources().some((resource) => can(policyFor(resource.name), role, "read"));
+  return { session, role, allowed: (role !== null && ADMIN_ROLES.includes(role)) || readable } as const;
+}
+
+/** For admin pages: redirects signed-out visitors to sign-in and users without access to the home page. */
+export async function requireDashboard(returnTo = "/dashboard") {
+  const { session, role, allowed } = await dashboardSession();
+  if (!session) redirect(`/sign-in?next=${encodeURIComponent(returnTo)}`);
+  if (!allowed) redirect("/?error=forbidden");
+  return { session, role };
+}
+
+/**
+ * For resource pages: also requires the policy to allow `action` on this resource.
+ * Sends the user somewhere they can actually go — the list when they may read it,
+ * the dashboard when they may not.
+ */
+export async function requireAccess(resource: Resource, action: PolicyAction) {
+  const { session, role } = await requireDashboard(resourcePath(resource));
+  const policy = policyFor(resource.name);
+  if (!can(policy, role, action)) {
+    redirect(action !== "read" && can(policy, role, "read") ? resourcePath(resource) : "/dashboard?error=forbidden");
+  }
+  return { session, role };
+}
+
+/** What the current user may do with a resource, for hiding actions they can't use. */
+export async function adminPermissions(resourceName: string) {
+  const { role } = await dashboardSession();
+  return allowedActions(policyFor(resourceName), role);
+}
+
+const stores = new Map<string, ResourceStore>();
+
+/** CRUD store for a resource by name (404 for unknown names). */
+export function dashboardStore(name: string): ResourceStore {
+  const entry = (resourceTables as unknown as Record<string, { resource: Resource; table: SQLiteTable } | undefined>)[name];
+  if (!entry) notFound();
+  let store = stores.get(name);
+  if (!store) {
+    store = createResourceStore({ resource: entry.resource, table: entry.table, getDb, onChange: revalidateResource, currentUser });
+    stores.set(name, store);
+  }
+  return store;
+}
+
+/**
+ * How many records a resource has. Cached in the data cache under the resource's tag,
+ * so the dashboard does not count every table on every visit, and a write through the
+ * admin or the API drops the count on its way out.
+ */
+export function recordCount(name: string): Promise<number> {
+  const counted = cached(
+    async (resourceName: string) => {
+      // Counted straight off the table, not through the store: a list stops counting at
+      // 10,000 so that paging stays quick, and a stat wants the real number.
+      const entry = (resourceTables as unknown as Record<string, { table: SQLiteTable } | undefined>)[resourceName];
+      if (!entry) return 0;
+      const [row] = await getDb().select({ total: count() }).from(entry.table);
+      return row?.total ?? 0;
+    },
+    ["flare", "record-count"],
+    { tags: [resourceTag(name)], revalidate: TTL.short },
+  );
+  return counted(name);
+}
+
+/**
+ * How many records hold each value of a field, in one grouped query rather than one
+ * count per option. Used by the stats above a resource's table.
+ */
+export function valueCounts(name: string, field: string): Promise<Record<string, number>> {
+  const counted = cached(
+    async (resourceName: string, key: string) => {
+      const entry = (resourceTables as unknown as Record<string, { table: SQLiteTable } | undefined>)[resourceName];
+      const column = entry ? (entry.table as unknown as Record<string, unknown>)[key] : undefined;
+      if (!entry || !column) return {};
+      const rows = (await getDb()
+        .select({ value: column as never, total: count() })
+        .from(entry.table)
+        .groupBy(column as never)) as { value: unknown; total: number }[];
+      return Object.fromEntries(rows.map((row) => [String(row.value ?? ""), row.total]));
+    },
+    ["flare", "value-counts"],
+    { tags: [resourceTag(name)], revalidate: TTL.short },
+  );
+  return counted(name, field);
+}
+
+/**
+ * How many records a resource gained in the last `days` days, and in the `days` before
+ * that, so a stat can show which way it's going. Cached like the totals.
+ */
+export function recentCounts(name: string, days = 7): Promise<{ current: number; previous: number }> {
+  const counts = cached(
+    async (resourceName: string, windowDays: number) => {
+      const entry = (resourceTables as unknown as Record<string, { table: SQLiteTable } | undefined>)[resourceName];
+      const createdAt = entry ? (entry.table as unknown as Record<string, unknown>).createdAt : undefined;
+      // A resource whose table has no createdAt (a custom one) simply has no trend.
+      if (!entry || !createdAt) return { current: 0, previous: 0 };
+      const window = windowDays * 86_400_000;
+      const since = new Date(Date.now() - window);
+      const before = new Date(Date.now() - window * 2);
+      const column = createdAt as never;
+      const [current] = await getDb().select({ total: count() }).from(entry.table).where(gte(column, since));
+      const [previous] = await getDb()
+        .select({ total: count() })
+        .from(entry.table)
+        .where(and(gte(column, before), lt(column, since)));
+      return { current: current?.total ?? 0, previous: previous?.total ?? 0 };
+    },
+    ["flare", "recent-count"],
+    { tags: [resourceTag(name)], revalidate: TTL.short },
+  );
+  return counts(name, days);
+}
+
+/** Percentage change between two periods, or undefined when there's nothing to compare. */
+export function trend(current: number, previous: number): number | undefined {
+  if (previous === 0) return current === 0 ? undefined : 100;
+  return ((current - previous) / previous) * 100;
+}
+
+/** Every resource descriptor (unfiltered): navigation uses `visibleResources()` instead. */
+export function allResources(): Resource[] {
+  return Object.values(resourceTables as unknown as Record<string, { resource: Resource }>).map((entry) => entry.resource);
+}
+
+/** Resources the current user may read, for the sidebar and dashboard. */
+export async function visibleResources(): Promise<Resource[]> {
+  const { role } = await dashboardSession();
+  return allResources().filter((resource) => can(policyFor(resource.name), role, "read"));
+}
+
+export function resourcePath(resource: Resource, ...parts: string[]) {
+  return ["/dashboard", resource.slug, ...parts].join("/");
+}

package/templates/app/lib/password-rules.ts

@@ -0,0 +1,159 @@
+/**
+ * What makes a password acceptable here, in one place: the sign-up, reset and change
+ * forms show these rules as you type, and the server checks the same ones before it
+ * accepts a password (lib/auth.ts).
+ *
+ * Only the length is required. The rest are advice, shown as a strength reading — length
+ * beats punctuation, and a form that refuses "correct horse battery staple" while
+ * accepting "P@ssw0rd" has its rules the wrong way round.
+ */
+
+export const PASSWORD_MIN_LENGTH = 8;
+/** Better Auth's own ceiling; long passphrases are the point, so it's generous. */
+export const PASSWORD_MAX_LENGTH = 128;
+
+/** Passwords guessed first in every credential-stuffing list, and the words they're built from. */
+const COMMON = new Set([
+  "password", "passw0rd", "p@ssword", "p@ssw0rd", "letmein", "welcome", "monkey", "dragon", "football", "baseball",
+  "iloveyou", "sunshine", "princess", "admin", "administrator", "login", "master", "hello", "freedom", "whatever",
+  "qwerty", "qwertyuiop", "asdfgh", "zxcvbn", "111111", "123123", "123456", "1234567", "12345678", "123456789",
+  "1234567890", "abc123", "trustno1", "superman", "batman", "starwars", "pokemon", "chocolate", "internet", "computer",
+  "samsung", "google", "facebook", "flare", "changeme", "secret", "test", "temp", "default", "guest",
+]);
+
+const KEYBOARD_RUNS = ["qwertyuiop", "asdfghjkl", "zxcvbnm", "1234567890", "abcdefghijklmnopqrstuvwxyz"];
+
+export type RuleId = "length" | "variety" | "notCommon" | "notPersonal";
+
+export interface PasswordRule {
+  id: RuleId;
+  label: string;
+  met: boolean;
+  /** A password can't be used until every required rule is met. */
+  required: boolean;
+}
+
+export interface PasswordCheck {
+  rules: PasswordRule[];
+  /** 0 (hopeless) to 4 (strong), the way zxcvbn scores. */
+  score: 0 | 1 | 2 | 3 | 4;
+  label: "Too short" | "Weak" | "Fair" | "Good" | "Strong";
+  /** The one thing most worth fixing, or null when there's nothing to say. */
+  advice: string | null;
+  /** Every required rule is met. */
+  valid: boolean;
+}
+
+/** Strip the digits and punctuation people add to the end: "Password123!" is "password". */
+const stem = (value: string) =>
+  value
+    .toLowerCase()
+    .replace(/[^a-z]/g, "")
+    .replace(/(.)\1{2,}/g, "$1");
+
+const looksCommon = (password: string): boolean => {
+  const lower = password.toLowerCase();
+  if (COMMON.has(lower) || COMMON.has(stem(lower))) return true;
+  // A common word with anything tacked on either end is still that word.
+  for (const word of COMMON) {
+    if (word.length >= 5 && lower.includes(word)) return true;
+  }
+  return KEYBOARD_RUNS.some((run) => {
+    for (let i = 0; i + 5 <= run.length; i++) {
+      const slice = run.slice(i, i + 5);
+      if (lower.includes(slice) || lower.includes([...slice].reverse().join(""))) return true;
+    }
+    return false;
+  });
+};
+
+/** Characters that carry information: repeats and runs count once. */
+function effectiveLength(password: string): number {
+  let length = 0;
+  let previous = "";
+  let run = 0;
+  for (const character of password) {
+    if (character === previous) {
+      run++;
+      length += run > 1 ? 0.25 : 0.5;
+    } else {
+      run = 0;
+      length += 1;
+    }
+    previous = character;
+  }
+  return length;
+}
+
+const classes = (password: string) =>
+  [/[a-z]/, /[A-Z]/, /\d/, /[^\w\s]/, /\s/].filter((pattern) => pattern.test(password)).length;
+
+/**
+ * Check a password, for the form as you type and for the server on submit.
+ * `avoid` is the things it shouldn't contain — the person's name and email.
+ */
+export function checkPassword(password: string, avoid: (string | null | undefined)[] = []): PasswordCheck {
+  const personal = avoid
+    .filter((value): value is string => Boolean(value && value.length > 2))
+    .flatMap((value) => [value.toLowerCase(), ...value.toLowerCase().split(/[@.\s]+/)])
+    .filter((part) => part.length > 2);
+  const lower = password.toLowerCase();
+
+  const rules: PasswordRule[] = [
+    { id: "length", label: `At least ${PASSWORD_MIN_LENGTH} characters`, met: password.length >= PASSWORD_MIN_LENGTH, required: true },
+    { id: "variety", label: "Letters and something else: a number, a symbol or a space", met: classes(password) >= 2, required: false },
+    { id: "notCommon", label: "Not a password everyone tries first", met: password.length > 0 && !looksCommon(password), required: false },
+    { id: "notPersonal", label: "Nothing from your name or email", met: !personal.some((part) => lower.includes(part)), required: false },
+  ];
+
+  const valid = rules.every((rule) => !rule.required || rule.met) && password.length <= PASSWORD_MAX_LENGTH;
+  const failed = rules.find((rule) => !rule.met);
+
+  let score: PasswordCheck["score"] = 0;
+  if (password.length >= PASSWORD_MIN_LENGTH) {
+    const length = effectiveLength(password);
+    const variety = classes(password);
+    const guessable = !rules.find((rule) => rule.id === "notCommon")!.met || !rules.find((rule) => rule.id === "notPersonal")!.met;
+    const raw = length >= 20 ? 4 : length >= 16 ? 3.5 : length >= 12 ? 3 : length >= 10 ? 2 : 1;
+    const adjusted = raw + (variety >= 3 ? 0.5 : 0) - (guessable ? 2 : 0);
+    score = Math.max(1, Math.min(4, Math.round(adjusted))) as PasswordCheck["score"];
+  }
+
+  const label = password.length < PASSWORD_MIN_LENGTH ? "Too short" : (["Weak", "Weak", "Fair", "Good", "Strong"] as const)[score];
+
+  let advice: string | null = null;
+  if (password.length === 0) advice = null;
+  else if (password.length < PASSWORD_MIN_LENGTH) advice = `${PASSWORD_MIN_LENGTH - password.length} more to go.`;
+  else if (password.length > PASSWORD_MAX_LENGTH) advice = `That's over ${PASSWORD_MAX_LENGTH} characters.`;
+  else if (failed?.id === "notCommon") advice = "That's close to a password attackers try first. A few unrelated words work better.";
+  else if (failed?.id === "notPersonal") advice = "Anyone who knows your email can guess this. Try something unrelated to you.";
+  else if (score < 3) advice = "Longer is stronger: three or four unrelated words beat a short password with symbols.";
+
+  return { rules, score, label, advice, valid };
+}
+
+/**
+ * Has this password appeared in a breach? Asks Have I Been Pwned with the k-anonymity
+ * range API: only the first five characters of the hash leave the Worker, and the
+ * password itself never does.
+ *
+ * Fails open — an outage shouldn't stop people signing up.
+ */
+export async function isBreachedPassword(password: string, fetchImpl: typeof fetch = fetch): Promise<boolean> {
+  try {
+    const bytes = new Uint8Array(await crypto.subtle.digest("SHA-1", new TextEncoder().encode(password)));
+    const hash = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("").toUpperCase();
+    const response = await fetchImpl(`https://api.pwnedpasswords.com/range/${hash.slice(0, 5)}`, {
+      headers: { "Add-Padding": "true" },
+      signal: AbortSignal.timeout(2500),
+    });
+    if (!response.ok) return false;
+    const suffix = hash.slice(5);
+    return (await response.text()).split("\n").some((line) => {
+      const [candidate, count] = line.trim().split(":");
+      return candidate === suffix && Number(count) > 0;
+    });
+  } catch {
+    return false;
+  }
+}