create-nevela 0.3.0 → 0.4.1

package/template/web/lib/auth-client.ts

@@ -0,0 +1,279 @@
+/**
+ * The browser's side of signing in, with the method names Flare's screens call.
+ *
+ * In Flare these are Better Auth's client. Here each one is a request to this app's
+ * `/api/auth/…` route, which passes it to Laravel and keeps the token in an httpOnly
+ * cookie. So the screens are Flare's, unchanged, and the accounts, passwords, codes and
+ * passkeys are Laravel's.
+ *
+ * Every method resolves to `{ data, error }` and never throws.
+ */
+
+export interface AuthError {
+  message: string;
+  code?: string;
+  status: number;
+}
+
+export type AuthResult<T = Record<string, unknown>> = { data: T; error: null } | { data: null; error: AuthError };
+
+async function call<T = Record<string, unknown>>(method: string, path: string, body?: unknown): Promise<AuthResult<T>> {
+  try {
+    const response = await fetch(`/api/auth/${path}`, {
+      method,
+      credentials: "same-origin",
+      headers: body === undefined ? { Accept: "application/json" } : { Accept: "application/json", "Content-Type": "application/json" },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const text = await response.text();
+    const parsed = (text ? JSON.parse(text) : {}) as Record<string, unknown>;
+    if (!response.ok) {
+      return { data: null, error: { message: String(parsed.error ?? "Something went wrong. Try again."), code: parsed.code as string | undefined, status: response.status } };
+    }
+    return { data: parsed as T, error: null };
+  } catch {
+    return { data: null, error: { message: "Can't reach the server. Check your connection and try again.", status: 0 } };
+  }
+}
+
+const post = <T = Record<string, unknown>>(path: string, body: unknown = {}) => call<T>("POST", path, body);
+
+/**
+ * Laravel may answer a sign-in with "now the second step" instead of signing in. The
+ * pending sign-in is already in an httpOnly cookie; this sends the browser to the page
+ * that asks for the code, and never resolves, so the caller doesn't carry on as if signed in.
+ */
+async function orSecondStep<T extends AuthResult<{ twoFactorRedirect?: boolean }>>(pending: Promise<T>): Promise<T> {
+  const result = await pending;
+  if (!result.data?.twoFactorRedirect) return result;
+  const next = new URLSearchParams(window.location.search).get("next");
+  window.location.href = `/two-factor${next ? `?next=${encodeURIComponent(next)}` : ""}`;
+  return new Promise<T>(() => {});
+}
+const unsupported = async (what: string): Promise<AuthResult<never>> => ({ data: null, error: { message: `${what} isn't available in this app.`, code: "NOT_ENABLED", status: 404 } });
+
+/* --- Passkeys: the browser's WebAuthn calls, with their binary fields as base64url text. --- */
+
+const toBytes = (text: string): ArrayBuffer => {
+  const base64 = text.replace(/-/g, "+").replace(/_/g, "/");
+  const binary = atob(base64 + "=".repeat((4 - (base64.length % 4)) % 4));
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes.buffer;
+};
+
+const toText = (buffer: ArrayBuffer | null | undefined): string => {
+  if (!buffer) return "";
+  let binary = "";
+  for (const byte of new Uint8Array(buffer)) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+
+type Descriptor = { id: string; type: string; transports?: string[] };
+type CreationOptions = { challenge: string; user: { id: string; name: string; displayName: string }; excludeCredentials?: Descriptor[] } & Record<string, unknown>;
+type RequestOptions = { challenge: string; allowCredentials?: Descriptor[] } & Record<string, unknown>;
+
+const descriptors = (list: Descriptor[] | undefined) => (list ?? []).map((item) => ({ ...item, id: toBytes(item.id) })) as PublicKeyCredentialDescriptor[];
+
+const passkeyError = (cause: unknown, fallback: string): AuthError => {
+  const name = cause instanceof DOMException ? cause.name : "";
+  if (name === "NotAllowedError" || name === "AbortError") return { message: "The passkey prompt was closed before it finished.", code: "PASSKEY_CANCELLED", status: 0 };
+  if (name === "InvalidStateError") return { message: "This device already has a passkey for your account.", code: "PASSKEY_EXISTS", status: 0 };
+  if (name === "SecurityError") return { message: "Passkeys need this site to be on https, or on localhost.", code: "PASSKEY_UNAVAILABLE", status: 0 };
+  return { message: fallback, code: "PASSKEY_FAILED", status: 0 };
+};
+
+/** One autofill request may be waiting at a time; a button press takes over from it. */
+let autofill: AbortController | null = null;
+
+async function signInWithPasskey({ autoFill = false }: { autoFill?: boolean } = {}): Promise<AuthResult> {
+  if (typeof PublicKeyCredential === "undefined") return { data: null, error: { message: "This browser doesn't support passkeys.", code: "PASSKEY_UNAVAILABLE", status: 0 } };
+  autofill?.abort();
+  autofill = autoFill ? new AbortController() : null;
+
+  const start = await post<{ challenge: string; options: RequestOptions }>("passkey/options");
+  if (start.error) return start;
+  let credential: PublicKeyCredential | null;
+  try {
+    credential = (await navigator.credentials.get({
+      publicKey: { ...start.data.options, challenge: toBytes(start.data.options.challenge), allowCredentials: descriptors(start.data.options.allowCredentials) } as PublicKeyCredentialRequestOptions,
+      ...(autoFill ? { mediation: "conditional" as CredentialMediationRequirement, signal: autofill!.signal } : {}),
+    })) as PublicKeyCredential | null;
+  } catch (cause) {
+    return { data: null, error: passkeyError(cause, "That passkey didn't work. Try again or use your email.") };
+  }
+  if (!credential) return { data: null, error: passkeyError(null, "No passkey was chosen.") };
+
+  const answer = credential.response as AuthenticatorAssertionResponse;
+  return post("passkey", {
+    challenge: start.data.challenge,
+    response: {
+      id: credential.id,
+      clientDataJSON: toText(answer.clientDataJSON),
+      authenticatorData: toText(answer.authenticatorData),
+      signature: toText(answer.signature),
+      userHandle: toText(answer.userHandle),
+    },
+  });
+}
+
+async function addPasskey({ name }: { name?: string } = {}): Promise<AuthResult> {
+  if (typeof PublicKeyCredential === "undefined") return { data: null, error: { message: "This browser doesn't support passkeys.", code: "PASSKEY_UNAVAILABLE", status: 0 } };
+  const start = await post<{ challenge: string; options: CreationOptions }>("passkeys/options");
+  if (start.error) return start;
+  const options = start.data.options;
+  let credential: PublicKeyCredential | null;
+  try {
+    credential = (await navigator.credentials.create({
+      publicKey: {
+        ...options,
+        challenge: toBytes(options.challenge),
+        user: { ...options.user, id: toBytes(options.user.id) },
+        excludeCredentials: descriptors(options.excludeCredentials),
+      } as PublicKeyCredentialCreationOptions,
+    })) as PublicKeyCredential | null;
+  } catch (cause) {
+    return { data: null, error: passkeyError(cause, "That passkey couldn't be added. Try again.") };
+  }
+  if (!credential) return { data: null, error: passkeyError(null, "No passkey was created.") };
+
+  const answer = credential.response as AuthenticatorAttestationResponse;
+  return post("passkeys", {
+    challenge: start.data.challenge,
+    name,
+    response: {
+      id: credential.id,
+      clientDataJSON: toText(answer.clientDataJSON),
+      attestationObject: toText(answer.attestationObject),
+      transports: answer.getTransports?.() ?? [],
+    },
+  });
+}
+
+/* --- Sessions (devices) --- */
+
+interface DeviceRow {
+  id: string;
+  userAgent: string | null;
+  ipAddress: string | null;
+  createdAt: string | null;
+  lastUsedAt: string | null;
+  current: boolean;
+}
+
+export interface SessionUser {
+  id: string;
+  name: string | null;
+  email: string;
+  role: string | null;
+  emailVerified: boolean;
+  twoFactorEnabled: boolean;
+  avatar: string | null;
+  image: string | null;
+}
+
+export const authClient = {
+  signIn: {
+    /** With a second step set up, the browser is sent to /two-factor instead. */
+    email: ({ email, password }: { email: string; password: string }) => orSecondStep(post<{ twoFactorRedirect?: boolean }>("token", { email, password })),
+    magicLink: ({ email, callbackURL }: { email: string; callbackURL?: string; errorCallbackURL?: string }) => post("magic-link", { email, next: callbackURL }),
+    emailOtp: ({ email, otp }: { email: string; otp: string }) => orSecondStep(post<{ twoFactorRedirect?: boolean }>("email-code/verify", { email, code: otp })),
+    passkey: signInWithPasskey,
+    social: (_options: { provider: string; callbackURL?: string; errorCallbackURL?: string }) => unsupported("Signing in with that provider"),
+  },
+  signUp: {
+    email: ({ name, email, password }: { name: string; email: string; password: string; callbackURL?: string }) =>
+      post<{ verify?: boolean; user?: SessionUser }>("register", { name, email, password }),
+  },
+  signOut: () => call("DELETE", "token"),
+
+  emailOtp: {
+    sendVerificationOtp: ({ email, type }: { email: string; type: "sign-in" | "email-verification" | "forget-password" }) =>
+      type === "sign-in" ? post("email-code", { email }) : post("email/send", { email }),
+    verifyEmail: ({ email, otp }: { email: string; otp: string }) => orSecondStep(post<{ twoFactorRedirect?: boolean }>("email/verify", { email, code: otp })),
+  },
+  sendVerificationEmail: ({ email, callbackURL }: { email: string; callbackURL?: string }) => post("email/send", { email, next: callbackURL }),
+
+  requestPasswordReset: ({ email }: { email: string; redirectTo?: string }) => post("password/forgot", { email }),
+  resetPassword: ({ newPassword, token }: { newPassword: string; token: string }) => post("password/reset", { newPassword, token }),
+  changePassword: (input: { currentPassword: string; newPassword: string; revokeOtherSessions?: boolean }) => post("password", input),
+
+  /** `avatar` is the key of a picture uploaded with uploadAvatar(), or null to remove it. */
+  updateUser: (input: { name?: string; avatar?: string | null }) => call<{ user: SessionUser }>("PATCH", "me", input),
+
+  async getSession(): Promise<AuthResult<{ user: SessionUser; session: { token: string | null } }>> {
+    const result = await call<{ user: SessionUser; session: { id: string | null } }>("GET", "me");
+    if (result.error) return result;
+    return { data: { user: result.data.user, session: { token: result.data.session?.id ?? null } }, error: null };
+  },
+
+  /** The devices signed in to this account. `token` identifies a row; it is not the token itself. */
+  async listSessions() {
+    const result = await call<{ data: DeviceRow[] }>("GET", "sessions");
+    if (result.error) return result;
+    return {
+      data: result.data.data.map((row) => ({ id: row.id, token: row.id, userAgent: row.userAgent, ipAddress: row.ipAddress, updatedAt: row.lastUsedAt ?? row.createdAt ?? undefined, current: row.current })),
+      error: null,
+    };
+  },
+  revokeSession: ({ token }: { token: string }) => call("DELETE", `sessions/${encodeURIComponent(token)}`),
+  revokeOtherSessions: () => call("DELETE", "sessions"),
+
+  twoFactor: {
+    /** `method: "totp"` starts an authenticator app's setup; `"otp"` switches on emailed codes. */
+    enable: ({ password, method }: { password?: string; method?: "totp" | "otp" }) =>
+      post<{ totpURI?: string; backupCodes: string[] }>("two-factor/enable", { password, method: method === "otp" ? "email" : "totp" }),
+    disable: ({ password }: { password?: string }) => post("two-factor/disable", { password }),
+    generateBackupCodes: ({ password }: { password?: string }) => post<{ backupCodes: string[] }>("two-factor/backup-codes", { password }),
+    /**
+     * A code from the authenticator app. While a sign-in is waiting for its second step it
+     * completes that; otherwise it confirms the app that is being set up.
+     */
+    async verifyTotp({ code }: { code: string; trustDevice?: boolean }) {
+      const waiting = await call<{ pending: boolean }>("GET", "two-factor/pending");
+      return waiting.data?.pending ? post("two-factor/verify", { method: "totp", code }) : post("two-factor/confirm", { code });
+    },
+    sendOtp: () => post("two-factor/send"),
+    verifyOtp: ({ code }: { code: string; trustDevice?: boolean }) => post("two-factor/verify", { method: "email", code }),
+    verifyBackupCode: ({ code }: { code: string; trustDevice?: boolean }) => post("two-factor/verify", { method: "backup", code }),
+  },
+
+  passkey: {
+    async listUserPasskeys() {
+      const result = await call<{ data: { id: string; name: string | null; createdAt: string | null }[] }>("GET", "passkeys");
+      return result.error ? result : { data: result.data.data, error: null };
+    },
+    addPasskey,
+    deletePasskey: ({ id }: { id: string }) => call("DELETE", `passkeys/${encodeURIComponent(id)}`),
+  },
+
+  // Signing in with Google, GitHub and the like isn't part of Nevela yet.
+  listAccounts: async (): Promise<AuthResult<{ id: string; providerId: string; accountId: string }[]>> => ({ data: [], error: null }),
+  linkSocial: (_options: { provider: string; callbackURL?: string }) => unsupported("Connecting that provider"),
+  unlinkAccount: (_options: { providerId?: string; accountId?: string }) => unsupported("Disconnecting that provider"),
+};
+
+/**
+ * Upload a profile picture. It is the request body, so the browser can report progress,
+ * and Laravel optimises it like any image field: a 400×400 square with a small thumbnail.
+ */
+export function uploadAvatar(file: File, onProgress?: (fraction: number) => void): Promise<AuthResult<{ user: SessionUser }>> {
+  return new Promise((resolve) => {
+    const request = new XMLHttpRequest();
+    request.upload.onprogress = (event) => onProgress?.(event.total ? event.loaded / event.total : 0);
+    request.onload = () => {
+      let answer: Record<string, unknown> = {};
+      try {
+        answer = JSON.parse(request.responseText) as Record<string, unknown>;
+      } catch {
+        // Not JSON: the status says what happened.
+      }
+      if (request.status >= 200 && request.status < 300) return resolve({ data: answer as { user: SessionUser }, error: null });
+      resolve({ data: null, error: { message: String(answer.error ?? `The upload failed (${request.status}).`), code: answer.code as string | undefined, status: request.status } });
+    };
+    request.onerror = () => resolve({ data: null, error: { message: "The upload failed. Check your connection and try again.", status: 0 } });
+    request.open("PUT", `/api/auth/avatar?name=${encodeURIComponent(file.name)}`);
+    request.setRequestHeader("Content-Type", file.type || "application/octet-stream");
+    request.send(file);
+  });
+}

package/template/web/lib/auth-config.ts

@@ -0,0 +1,43 @@
+/**
+ * How people sign in to this app.
+ *
+ * Written by `php nevela generate` from the "auth" section of config/nevela.php in the
+ * Laravel app. Change a setting there, then generate again: Laravel refuses a method
+ * that is switched off, and this file keeps the screens from offering it.
+ *
+ * Email and password sign-in is always available.
+ */
+export type SocialProvider = "google" | "github" | "apple" | "microsoft";
+
+// nevela:generated:start hash=584f50322414
+export const authConfig = {
+  /** People can create their own account at /sign-up. */
+  registration: false,
+  /** 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,
+  },
+  /** Refuse password sign-in until the email address is verified. */
+  requireEmailVerification: false,
+  /** Check new passwords against Have I Been Pwned's breach list. */
+  checkBreachedPasswords: true,
+  /** Signing in with Google, GitHub and the like isn't part of Nevela yet. */
+  social: [] as SocialProvider[],
+};
+// nevela:generated:end
+
+/** Whether any second factor can be set up. */
+export const twoFactorAvailable = authConfig.twoFactor.authenticator || authConfig.twoFactor.email;
+
+/** The social providers that are switched on and configured. None yet. */
+export function enabledSocialProviders(): SocialProvider[] {
+  return authConfig.social;
+}

package/template/web/lib/laravel.ts

@@ -1,4 +1,4 @@
-import { cookies } from "next/headers";
+import { cookies, headers } from "next/headers";
 
 /**
  * The one place the web app talks to Laravel.
@@ -16,6 +16,30 @@ export async function sessionToken(): Promise<string | undefined> {
   return (await cookies()).get(TOKEN_COOKIE)?.value;
 }
 
+/**
+ * What Laravel can't see for itself, because this server makes the call and not the
+ * browser: where the dashboard is being served from (for the links in emails, and for
+ * passkeys, which are tied to that address), and the person's own browser and address
+ * (for the list of devices signed in to an account).
+ */
+export async function callerHeaders(): Promise<Record<string, string>> {
+  const incoming = await headers();
+  const sent: Record<string, string> = {};
+  const host = incoming.get("x-forwarded-host") ?? incoming.get("host");
+  if (host) {
+    const local = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/.test(host);
+    sent["X-Nevela-Origin"] = `${incoming.get("x-forwarded-proto")?.split(",")[0] ?? (local ? "http" : "https")}://${host}`;
+  }
+  const agent = incoming.get("user-agent");
+  if (agent) sent["X-Nevela-User-Agent"] = agent.slice(0, 500);
+  const address = (incoming.get("x-forwarded-for") ?? "").split(",")[0]?.trim() || incoming.get("x-real-ip");
+  if (address) sent["X-Nevela-Ip"] = address.replace(/^::ffff:/, "");
+  // Proves to Laravel that this is the dashboard speaking for a browser, and not someone
+  // calling the API with made-up headers. The same value is in the Laravel app's .env.
+  if (process.env.NEVELA_PROXY_SECRET) sent["X-Nevela-Proxy-Secret"] = process.env.NEVELA_PROXY_SECRET;
+  return sent;
+}
+
 export interface LaravelRequest {
   method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
   body?: unknown;
@@ -37,6 +61,7 @@ export async function laravel(path: string, { method = "GET", body, token }: Lar
     method,
     headers: {
       Accept: "application/json",
+      ...(await callerHeaders()),
       ...(body === undefined ? {} : { "Content-Type": "application/json" }),
       ...(bearer ? { Authorization: `Bearer ${bearer}` } : {}),
     },

package/template/web/lib/password-rules.ts

@@ -0,0 +1,167 @@
+/**
+ * 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. Kept as one run of words, not as quoted strings: a list of the world's worst
+ * passwords is not a leaked one, but a secret scanner reading quoted strings can't tell.
+ */
+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
+  `
+    .split(/\s+/)
+    .filter(Boolean),
+);
+
+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;
+  }
+}

package/template/web/lib/second-step.ts

@@ -0,0 +1,35 @@
+import { cookies } from "next/headers";
+
+/**
+ * A sign-in that is waiting for its second step.
+ *
+ * After a right password (or an emailed link or code) on an account with two-factor on,
+ * Laravel hands back a challenge instead of a token. It is kept here, in an httpOnly
+ * cookie, until the code arrives: the browser only ever sends the code, never the
+ * challenge. Laravel forgets the challenge after the same ten minutes.
+ */
+export const PENDING_COOKIE = "nevela_2fa";
+export const PENDING_MAX_AGE = 60 * 10;
+
+/** The ways this sign-in can be finished, as Laravel names them. */
+export type SecondStepMethod = "totp" | "email" | "backup";
+
+export interface PendingSecondStep {
+  challenge: string;
+  methods: SecondStepMethod[];
+}
+
+export const encodePending = (pending: PendingSecondStep) => JSON.stringify({ c: pending.challenge, m: pending.methods });
+
+export async function pendingSecondStep(): Promise<PendingSecondStep | null> {
+  const raw = (await cookies()).get(PENDING_COOKIE)?.value;
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw) as { c?: unknown; m?: unknown };
+    if (typeof parsed.c !== "string" || !parsed.c) return null;
+    const methods = Array.isArray(parsed.m) ? parsed.m.filter((m): m is SecondStepMethod => m === "totp" || m === "email" || m === "backup") : [];
+    return { challenge: parsed.c, methods };
+  } catch {
+    return null;
+  }
+}

package/template/web/lib/session.ts

@@ -7,10 +7,16 @@ export interface SessionUser {
   name: string | null;
   email: string;
   role: string | null;
+  emailVerified: boolean;
+  twoFactorEnabled: boolean;
+  /** The key of the profile picture (an optimised upload), or null. Show it with fileUrl(). */
+  avatar: string | null;
 }
 
 export interface Session {
   user: SessionUser;
+  /** Which of the account's devices this is: its id in the list of devices. */
+  session: { id: string | null };
 }
 
 /**
@@ -22,7 +28,8 @@ export const getSession = cache(async (): Promise<Session | null> => {
   if (!(await sessionToken())) return null;
   const response = await laravel("auth/me");
   if (!response.ok) return null;
-  return { user: (response.body as { user: SessionUser }).user };
+  const body = response.body as { user: SessionUser; session?: { id: string | null } };
+  return { user: body.user, session: body.session ?? { id: null } };
 });
 
 /** The current session; redirects to /sign-in (returning to `returnTo` afterwards) when signed out. */
@@ -36,7 +43,8 @@ export async function requireSession(returnTo?: string) {
 
 /** Only allow same-site relative redirect targets, to avoid open redirects via `?next=`. */
 export function safeRedirectPath(value: unknown, fallback = "/dashboard"): string {
-  return typeof value === "string" && value.startsWith("/") && !value.startsWith("//") && !value.startsWith("/\\")
-    ? value
-    : fallback;
+  // One leading slash, and no backslash or control character anywhere. Browsers drop tabs
+  // and newlines from an address, which would turn "/<tab>/evil.example" into "//evil.example".
+  // eslint-disable-next-line no-control-regex -- control characters are exactly what is refused
+  return typeof value === "string" && /^\/(?!\/)[^\\\u0000-\u001f\u007f]*$/.test(value) ? value : fallback;
 }

package/template/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nevela-web",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "private": true,
   "type": "module",
   "scripts": {
@@ -29,7 +29,8 @@
     "react-dom": "19.3.0",
     "sonner": "^2.0.8",
     "tailwind-merge": "^3.7.0",
-    "tw-animate-css": "^1.4.0"
+    "tw-animate-css": "^1.4.0",
+    "uqr": "0.1.3"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.3",