@payez/next-mvp 4.8.0 → 4.8.2

package/src/lib/code-step-copy.ts

@@ -1,83 +1,83 @@
-/**
- * PAY-1576 - the 2FA "enter your code" step, described ONCE.
- *
- * WHY THIS FILE EXISTS. Two cards render the same step for the same door
- * (POST /api/auth/admin-login, the package's routes/auth/credential-login, answers `requiresTwoFactor` with `sentVia` /
- * `codeRequested` / `emailSent`):
- *   - SignInCard.tsx      (fixed in 267479 to name every lane the box accepts)
- *   - AdminLoginCard.tsx  (NOT fixed: it said "from your authenticator app" for every user and
- *                          discarded the door's answer, so an email-code user was sent to a
- *                          factor they do not have; live allowed2FAMethods=[emailcode,totp])
- * 267479 reached only one of the twins. A comment cannot stop that recurring; a shared helper can,
- * because there is then only one place the sentence is built and a static gate
- * (testing/qa/code-step-copy-gate.js) fails if either card builds its own.
- *
- * THE COPY RULES (carried over verbatim from 267479 / 267561, not re-decided here):
- *   - Name BOTH lanes and RANK NEITHER: the screen does not know which factor the user holds.
- *   - The non-authenticator clause is gated on the door's answer, so we never mention a code nobody
- *     asked for.
- *   - `codeRequested` means "a code was requested", NOT "a code arrived" (twofa/email/send returns
- *     200 even when the SMTP send threw), so the copy says "the code we emailed you" and never
- *     "check your inbox" / "it has arrived".
- */
-
-export type CodeSentVia = 'sms' | 'email' | null;
-
-export interface CodeRequest {
-  /** The door asked for a code to be sent (`codeRequested`, or the older alias `emailSent`). */
-  codeRequested: boolean;
-  /** Which lane the door actually fired, or null when nothing was sent (a TOTP holder). */
-  sentVia: CodeSentVia;
-  /**
-   * PAY-2314 (4.7.1): present and false ONLY when the door said which factors it accepts (acceptedFactors) and TOTP is not
-   * among them. Absent means "the door did not say" (an older door) and keeps the historic authenticator sentence.
-   */
-  acceptsAuthenticator?: false;
-}
-
-/** Nothing sent, nothing to say beyond the authenticator. What a card starts with. */
-export const NO_CODE_REQUEST: CodeRequest = { codeRequested: false, sentVia: null };
-
-/**
- * Read the door's answer. Total: any shape (null, a string, an array, junk fields) yields a
- * CodeRequest and never throws, so a malformed body degrades to the authenticator-only sentence
- * rather than to a crash or to a claim the door never made.
- */
-export function readCodeRequest(body: unknown): CodeRequest {
-  const b = body && typeof body === 'object' ? (body as Record<string, unknown>) : {};
-  const sentVia: CodeSentVia = b.sentVia === 'sms' || b.sentVia === 'email' ? b.sentVia : null;
-  const accepted = Array.isArray(b.acceptedFactors) ? (b.acceptedFactors as unknown[]) : null;
-  const base: CodeRequest = { codeRequested: b.codeRequested === true || b.emailSent === true, sentVia };
-  return accepted !== null && !accepted.includes('totp') ? { ...base, acceptsAuthenticator: false } : base;
-}
-
-/** The lane clause that follows the authenticator, or '' when the door sent nothing. */
-function laneClause(r: CodeRequest): string {
-  if (!r.codeRequested) return '';
-  if (r.sentVia === 'sms') return ', or the code we texted you';
-  if (r.sentVia === 'email') return ', or the code we emailed you';
-  return ', or the code we sent you';
-}
-
-/**
- * The sentence, split around the email so a card can render the address however it likes
- * (SignInCard wraps it in <strong>; AdminLoginCard passes a plain-string subtitle).
- * `before + email + after` is the whole sentence.
- */
-export function codeStepParts(r: CodeRequest): { before: string; after: string } {
-  if (r.acceptsAuthenticator === false) {
-    // PAY-2314: the door told us TOTP is not an accepted factor for this user - never send them to an authenticator they do not have.
-    const how = r.sentVia === 'sms' ? 'texted' : r.sentVia === 'email' ? 'emailed' : 'sent';
-    return { before: 'Enter your 6-digit code to finish signing in as ', after: ` — the code we ${how} you.` };
-  }
-  return {
-    before: 'Enter your 6-digit code to finish signing in as ',
-    after: ` — from your authenticator app${laneClause(r)}.`,
-  };
-}
-
-/** The sentence as one plain string, for a card whose subtitle prop is a string. */
-export function codeStepInstruction(email: string, r: CodeRequest): string {
-  const { before, after } = codeStepParts(r);
-  return `${before}${email}${after}`;
-}
+/**
+ * PAY-1576 - the 2FA "enter your code" step, described ONCE.
+ *
+ * WHY THIS FILE EXISTS. Two cards render the same step for the same door
+ * (POST /api/auth/admin-login, the package's routes/auth/credential-login, answers `requiresTwoFactor` with `sentVia` /
+ * `codeRequested` / `emailSent`):
+ *   - SignInCard.tsx      (fixed in 267479 to name every lane the box accepts)
+ *   - AdminLoginCard.tsx  (NOT fixed: it said "from your authenticator app" for every user and
+ *                          discarded the door's answer, so an email-code user was sent to a
+ *                          factor they do not have; live allowed2FAMethods=[emailcode,totp])
+ * 267479 reached only one of the twins. A comment cannot stop that recurring; a shared helper can,
+ * because there is then only one place the sentence is built and a static gate
+ * (testing/qa/code-step-copy-gate.js) fails if either card builds its own.
+ *
+ * THE COPY RULES (carried over verbatim from 267479 / 267561, not re-decided here):
+ *   - Name BOTH lanes and RANK NEITHER: the screen does not know which factor the user holds.
+ *   - The non-authenticator clause is gated on the door's answer, so we never mention a code nobody
+ *     asked for.
+ *   - `codeRequested` means "a code was requested", NOT "a code arrived" (twofa/email/send returns
+ *     200 even when the SMTP send threw), so the copy says "the code we emailed you" and never
+ *     "check your inbox" / "it has arrived".
+ */
+
+export type CodeSentVia = 'sms' | 'email' | null;
+
+export interface CodeRequest {
+  /** The door asked for a code to be sent (`codeRequested`, or the older alias `emailSent`). */
+  codeRequested: boolean;
+  /** Which lane the door actually fired, or null when nothing was sent (a TOTP holder). */
+  sentVia: CodeSentVia;
+  /**
+   * PAY-2314 (4.7.1): present and false ONLY when the door said which factors it accepts (acceptedFactors) and TOTP is not
+   * among them. Absent means "the door did not say" (an older door) and keeps the historic authenticator sentence.
+   */
+  acceptsAuthenticator?: false;
+}
+
+/** Nothing sent, nothing to say beyond the authenticator. What a card starts with. */
+export const NO_CODE_REQUEST: CodeRequest = { codeRequested: false, sentVia: null };
+
+/**
+ * Read the door's answer. Total: any shape (null, a string, an array, junk fields) yields a
+ * CodeRequest and never throws, so a malformed body degrades to the authenticator-only sentence
+ * rather than to a crash or to a claim the door never made.
+ */
+export function readCodeRequest(body: unknown): CodeRequest {
+  const b = body && typeof body === 'object' ? (body as Record<string, unknown>) : {};
+  const sentVia: CodeSentVia = b.sentVia === 'sms' || b.sentVia === 'email' ? b.sentVia : null;
+  const accepted = Array.isArray(b.acceptedFactors) ? (b.acceptedFactors as unknown[]) : null;
+  const base: CodeRequest = { codeRequested: b.codeRequested === true || b.emailSent === true, sentVia };
+  return accepted !== null && !accepted.includes('totp') ? { ...base, acceptsAuthenticator: false } : base;
+}
+
+/** The lane clause that follows the authenticator, or '' when the door sent nothing. */
+function laneClause(r: CodeRequest): string {
+  if (!r.codeRequested) return '';
+  if (r.sentVia === 'sms') return ', or the code we texted you';
+  if (r.sentVia === 'email') return ', or the code we emailed you';
+  return ', or the code we sent you';
+}
+
+/**
+ * The sentence, split around the email so a card can render the address however it likes
+ * (SignInCard wraps it in <strong>; AdminLoginCard passes a plain-string subtitle).
+ * `before + email + after` is the whole sentence.
+ */
+export function codeStepParts(r: CodeRequest): { before: string; after: string } {
+  if (r.acceptsAuthenticator === false) {
+    // PAY-2314: the door told us TOTP is not an accepted factor for this user - never send them to an authenticator they do not have.
+    const how = r.sentVia === 'sms' ? 'texted' : r.sentVia === 'email' ? 'emailed' : 'sent';
+    return { before: 'Enter your 6-digit code to finish signing in as ', after: ` — the code we ${how} you.` };
+  }
+  return {
+    before: 'Enter your 6-digit code to finish signing in as ',
+    after: ` — from your authenticator app${laneClause(r)}.`,
+  };
+}
+
+/** The sentence as one plain string, for a card whose subtitle prop is a string. */
+export function codeStepInstruction(email: string, r: CodeRequest): string {
+  const { before, after } = codeStepParts(r);
+  return `${before}${email}${after}`;
+}

package/src/lib/credential-sign-in-client.ts

@@ -1,101 +1,101 @@
-/**
- * PAY-2302 cut 1b: the BROWSER side of the package's credential sign-in, as plain functions so it is testable without a DOM.
- *
- * It talks to the routes the app mounts from this package:
- *   POST /api/auth/admin-login             routes/auth/credential-login             { email, password, code? }
- *   POST /api/auth/admin-login/email-code  routes/auth/credential-login-email-code  (no body: the browser names no address and no client)
- *
- * The result is a closed union so the form cannot invent a state the door never answered. The logic mirrors the portal's
- * AdminLoginCard.submitLogin (VibeID-Customer-Portal 3d654917) and keeps its rules:
- *   - 429 is relayed as the door's own sentence; the form never states a window the door did not send.
- *   - `requiresTwoFactor` moves to the code step and keeps the door's answer (sentVia / codeRequested) so the step names the
- *     lane that was actually fired (PAY-1576).
- *   - anything else not `success: true` is an error carrying the door's message, and `offerEmailCode` only when the door set it
- *     literally true (PAY-2284).
- */
-import { NO_CODE_REQUEST, readCodeRequest, type CodeRequest } from './code-step-copy';
-
-export const CREDENTIAL_LOGIN_URL = '/api/auth/admin-login';
-export const CREDENTIAL_EMAIL_CODE_URL = '/api/auth/admin-login/email-code';
-
-export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
-
-export type CredentialSignInResult =
-  | { kind: 'success' }
-  | { kind: 'two_factor'; codeRequest: CodeRequest }
-  | { kind: 'rate_limited'; message: string }
-  | { kind: 'error'; message: string; offerEmailCode: boolean };
-
-export const MSG_RATE_LIMITED = 'Too many attempts. Please try again later.';
-export const MSG_CANNOT_SIGN_IN = 'Could not sign in. Check your details and try again.';
-export const MSG_UNEXPECTED = 'Something went wrong signing you in. Please try again.';
-
-const EMAIL_SHAPE = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
-
-export function isEmailShaped(v: string): boolean {
-  return EMAIL_SHAPE.test(v);
-}
-
-/** Field-level checks before anything is sent. Returns the errors, or null when the input may be submitted. */
-export function validateCredentials(email: string, password: string): { email?: string; password?: string } | null {
-  const errors: { email?: string; password?: string } = {};
-  const trimmed = email.trim();
-  if (!trimmed) errors.email = 'Enter your email address.';
-  else if (!isEmailShaped(trimmed)) errors.email = 'Enter a valid email address.';
-  if (!password) errors.password = 'Enter your password.';
-  return errors.email || errors.password ? errors : null;
-}
-
-function asString(v: unknown): string | undefined {
-  return typeof v === 'string' && v ? v : undefined;
-}
-
-/** One call to the credential door. `code` is the 2FA code on the second turn; email and password are resubmitted with it. */
-export async function credentialSignIn(
-  args: { email: string; password: string; code?: string },
-  fetchImpl: FetchLike = (input, init) => fetch(input, init),
-): Promise<CredentialSignInResult> {
-  try {
-    const res = await fetchImpl(CREDENTIAL_LOGIN_URL, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ email: args.email, password: args.password, code: args.code }),
-    });
-    const body: any = await res.json().catch(() => null);
-
-    if (res.status === 429) return { kind: 'rate_limited', message: asString(body?.error) ?? MSG_RATE_LIMITED };
-    if (body?.requiresTwoFactor) return { kind: 'two_factor', codeRequest: readCodeRequest(body) };
-    if (!res.ok || body?.success !== true) {
-      return { kind: 'error', message: asString(body?.error) ?? MSG_CANNOT_SIGN_IN, offerEmailCode: body?.offerEmailCode === true };
-    }
-    return { kind: 'success' };
-  } catch {
-    return { kind: 'error', message: MSG_UNEXPECTED, offerEmailCode: false };
-  }
-}
-
-export type EmailCodeResult =
-  | { kind: 'requested'; codeRequest: CodeRequest; devCode: string | null }
-  | { kind: 'error'; message: string };
-
-export const MSG_EMAIL_CODE_FAILED = 'We could not ask for an email code just now. Try again shortly.';
-
-/** "Email me a code instead": asks the door to email a code. `requested` means asked, never arrived. */
-export async function requestEmailCode(fetchImpl: FetchLike = (input, init) => fetch(input, init)): Promise<EmailCodeResult> {
-  try {
-    const res = await fetchImpl(CREDENTIAL_EMAIL_CODE_URL, { method: 'POST', credentials: 'include' });
-    const body: any = await res.json().catch(() => null);
-    if (res.ok && body?.success === true) {
-      return {
-        kind: 'requested',
-        codeRequest: readCodeRequest(body),
-        devCode: typeof body?.devVerificationCode === 'string' && body.devVerificationCode ? body.devVerificationCode : null,
-      };
-    }
-    return { kind: 'error', message: asString(body?.error) ?? MSG_EMAIL_CODE_FAILED };
-  } catch {
-    return { kind: 'error', message: MSG_EMAIL_CODE_FAILED };
-  }
-}
-
-export { NO_CODE_REQUEST };
+/**
+ * PAY-2302 cut 1b: the BROWSER side of the package's credential sign-in, as plain functions so it is testable without a DOM.
+ *
+ * It talks to the routes the app mounts from this package:
+ *   POST /api/auth/admin-login             routes/auth/credential-login             { email, password, code? }
+ *   POST /api/auth/admin-login/email-code  routes/auth/credential-login-email-code  (no body: the browser names no address and no client)
+ *
+ * The result is a closed union so the form cannot invent a state the door never answered. The logic mirrors the portal's
+ * AdminLoginCard.submitLogin (VibeID-Customer-Portal 3d654917) and keeps its rules:
+ *   - 429 is relayed as the door's own sentence; the form never states a window the door did not send.
+ *   - `requiresTwoFactor` moves to the code step and keeps the door's answer (sentVia / codeRequested) so the step names the
+ *     lane that was actually fired (PAY-1576).
+ *   - anything else not `success: true` is an error carrying the door's message, and `offerEmailCode` only when the door set it
+ *     literally true (PAY-2284).
+ */
+import { NO_CODE_REQUEST, readCodeRequest, type CodeRequest } from './code-step-copy';
+
+export const CREDENTIAL_LOGIN_URL = '/api/auth/admin-login';
+export const CREDENTIAL_EMAIL_CODE_URL = '/api/auth/admin-login/email-code';
+
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export type CredentialSignInResult =
+  | { kind: 'success' }
+  | { kind: 'two_factor'; codeRequest: CodeRequest }
+  | { kind: 'rate_limited'; message: string }
+  | { kind: 'error'; message: string; offerEmailCode: boolean };
+
+export const MSG_RATE_LIMITED = 'Too many attempts. Please try again later.';
+export const MSG_CANNOT_SIGN_IN = 'Could not sign in. Check your details and try again.';
+export const MSG_UNEXPECTED = 'Something went wrong signing you in. Please try again.';
+
+const EMAIL_SHAPE = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
+
+export function isEmailShaped(v: string): boolean {
+  return EMAIL_SHAPE.test(v);
+}
+
+/** Field-level checks before anything is sent. Returns the errors, or null when the input may be submitted. */
+export function validateCredentials(email: string, password: string): { email?: string; password?: string } | null {
+  const errors: { email?: string; password?: string } = {};
+  const trimmed = email.trim();
+  if (!trimmed) errors.email = 'Enter your email address.';
+  else if (!isEmailShaped(trimmed)) errors.email = 'Enter a valid email address.';
+  if (!password) errors.password = 'Enter your password.';
+  return errors.email || errors.password ? errors : null;
+}
+
+function asString(v: unknown): string | undefined {
+  return typeof v === 'string' && v ? v : undefined;
+}
+
+/** One call to the credential door. `code` is the 2FA code on the second turn; email and password are resubmitted with it. */
+export async function credentialSignIn(
+  args: { email: string; password: string; code?: string },
+  fetchImpl: FetchLike = (input, init) => fetch(input, init),
+): Promise<CredentialSignInResult> {
+  try {
+    const res = await fetchImpl(CREDENTIAL_LOGIN_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email: args.email, password: args.password, code: args.code }),
+    });
+    const body: any = await res.json().catch(() => null);
+
+    if (res.status === 429) return { kind: 'rate_limited', message: asString(body?.error) ?? MSG_RATE_LIMITED };
+    if (body?.requiresTwoFactor) return { kind: 'two_factor', codeRequest: readCodeRequest(body) };
+    if (!res.ok || body?.success !== true) {
+      return { kind: 'error', message: asString(body?.error) ?? MSG_CANNOT_SIGN_IN, offerEmailCode: body?.offerEmailCode === true };
+    }
+    return { kind: 'success' };
+  } catch {
+    return { kind: 'error', message: MSG_UNEXPECTED, offerEmailCode: false };
+  }
+}
+
+export type EmailCodeResult =
+  | { kind: 'requested'; codeRequest: CodeRequest; devCode: string | null }
+  | { kind: 'error'; message: string };
+
+export const MSG_EMAIL_CODE_FAILED = 'We could not ask for an email code just now. Try again shortly.';
+
+/** "Email me a code instead": asks the door to email a code. `requested` means asked, never arrived. */
+export async function requestEmailCode(fetchImpl: FetchLike = (input, init) => fetch(input, init)): Promise<EmailCodeResult> {
+  try {
+    const res = await fetchImpl(CREDENTIAL_EMAIL_CODE_URL, { method: 'POST', credentials: 'include' });
+    const body: any = await res.json().catch(() => null);
+    if (res.ok && body?.success === true) {
+      return {
+        kind: 'requested',
+        codeRequest: readCodeRequest(body),
+        devCode: typeof body?.devVerificationCode === 'string' && body.devVerificationCode ? body.devVerificationCode : null,
+      };
+    }
+    return { kind: 'error', message: asString(body?.error) ?? MSG_EMAIL_CODE_FAILED };
+  } catch {
+    return { kind: 'error', message: MSG_EMAIL_CODE_FAILED };
+  }
+}
+
+export { NO_CODE_REQUEST };

package/src/lib/demo-mode.ts

@@ -1,18 +1,18 @@
-/**
- * Demo mode utilities
- * When DEMO_MODE=true, auth package is installed but not enforced
- */
-
-export function isDemoMode(): boolean {
-  return process.env.DEMO_MODE === 'true' || process.env.NEXT_PUBLIC_DEMO_MODE === 'true';
-}
-
-export function isAuthConfigured(): boolean {
-  if (isDemoMode()) return false;
-  return !!(
-    process.env.BETTER_AUTH_SECRET ||
-    process.env.NEXTAUTH_SECRET ||
-  // was NEXT_CLIENT_ID - a third name for CLIENT_ID, read only here. Collapsed 2026-08-26.
-    (process.env.CLIENT_ID && process.env.NEXT_CLIENT_PRIVATE_KEY_PEM)
-  );
-}
+/**
+ * Demo mode utilities
+ * When DEMO_MODE=true, auth package is installed but not enforced
+ */
+
+export function isDemoMode(): boolean {
+  return process.env.DEMO_MODE === 'true' || process.env.NEXT_PUBLIC_DEMO_MODE === 'true';
+}
+
+export function isAuthConfigured(): boolean {
+  if (isDemoMode()) return false;
+  return !!(
+    process.env.BETTER_AUTH_SECRET ||
+    process.env.NEXTAUTH_SECRET ||
+  // was NEXT_CLIENT_ID - a third name for CLIENT_ID, read only here. Collapsed 2026-08-26.
+    (process.env.CLIENT_ID && process.env.NEXT_CLIENT_PRIVATE_KEY_PEM)
+  );
+}

package/src/lib/device-id.ts

@@ -1,67 +1,67 @@
-/**
- * Per-browser device identity — card 240566 (QAPert flag 2 on the 9c7a815 review).
- *
- * BEFORE: /api/auth/admin-login forwarded ONE hardcoded device-id cookie —
- * `payez-PayEz-6c8201c35c1b44c9b2e823b36b95a718` — for every caller on the
- * PUBLIC /sign-in password path. To the IDP's rate limiter and device
- * fingerprinting, every portal user was literally the same device. Two
- * consequences, both measured-by-inspection rather than hypothetical:
- *   1. SHARED-FATE LOCKOUT — one attacker's failed attempts consume the
- *      throttle budget for every legitimate user at once.
- *   2. Per-device risk signals are meaningless: "new device" and "trusted
- *      device" cannot distinguish anybody from anybody.
- *
- * The id is a routing/telemetry key, NOT a credential — the IDP must never
- * grant anything on the strength of it, and nothing here assumes otherwise.
- * It is client-supplied and therefore client-forgeable; that is inherent to
- * device-id throttling and is why it supplements, never replaces, the
- * identifier- and IP-scoped limits on the IDP side.
- *
- * Shape is fixed by what the IDP already accepts from
- * createLoginHandler: `payez-PayEz-<32 lowercase hex>`.
- */
-
-export const DEVICE_ID_HEADER = 'X-Device-Id';
-export const DEVICE_ID_PATTERN = /^payez-PayEz-[0-9a-f]{32}$/;
-const STORAGE_KEY = 'payez.device-id';
-
-/** True for a well-formed device id. Used on BOTH sides of the wire. */
-export function isValidDeviceId(value: string | null | undefined): value is string {
-  return typeof value === 'string' && DEVICE_ID_PATTERN.test(value);
-}
-
-function mint(): string {
-  const bytes = new Uint8Array(16);
-  crypto.getRandomValues(bytes);
-  const hex = Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
-  return `payez-PayEz-${hex}`;
-}
-
-/**
- * The stable per-browser device id, minted once and persisted.
- *
- * Browser-only. Persistence is best-effort: private windows, disabled site
- * data and storage-quota failures all throw on access, so every read and
- * write is guarded. A browser that cannot persist still gets a VALID id for
- * this call — it simply looks like a new device each time, which is the
- * honest answer for a client that refuses to be remembered, and is still
- * strictly better than every user sharing one identity.
- */
-export function getDeviceId(): string {
-  if (typeof window === 'undefined') return mint();
-
-  try {
-    const existing = window.localStorage.getItem(STORAGE_KEY);
-    if (isValidDeviceId(existing)) return existing;
-  } catch {
-    return mint();
-  }
-
-  const minted = mint();
-  try {
-    window.localStorage.setItem(STORAGE_KEY, minted);
-  } catch {
-    /* not persistable — the minted id is still returned and used for this call */
-  }
-  return minted;
-}
+/**
+ * Per-browser device identity — card 240566 (QAPert flag 2 on the 9c7a815 review).
+ *
+ * BEFORE: /api/auth/admin-login forwarded ONE hardcoded device-id cookie —
+ * `payez-PayEz-6c8201c35c1b44c9b2e823b36b95a718` — for every caller on the
+ * PUBLIC /sign-in password path. To the IDP's rate limiter and device
+ * fingerprinting, every portal user was literally the same device. Two
+ * consequences, both measured-by-inspection rather than hypothetical:
+ *   1. SHARED-FATE LOCKOUT — one attacker's failed attempts consume the
+ *      throttle budget for every legitimate user at once.
+ *   2. Per-device risk signals are meaningless: "new device" and "trusted
+ *      device" cannot distinguish anybody from anybody.
+ *
+ * The id is a routing/telemetry key, NOT a credential — the IDP must never
+ * grant anything on the strength of it, and nothing here assumes otherwise.
+ * It is client-supplied and therefore client-forgeable; that is inherent to
+ * device-id throttling and is why it supplements, never replaces, the
+ * identifier- and IP-scoped limits on the IDP side.
+ *
+ * Shape is fixed by what the IDP already accepts from
+ * createLoginHandler: `payez-PayEz-<32 lowercase hex>`.
+ */
+
+export const DEVICE_ID_HEADER = 'X-Device-Id';
+export const DEVICE_ID_PATTERN = /^payez-PayEz-[0-9a-f]{32}$/;
+const STORAGE_KEY = 'payez.device-id';
+
+/** True for a well-formed device id. Used on BOTH sides of the wire. */
+export function isValidDeviceId(value: string | null | undefined): value is string {
+  return typeof value === 'string' && DEVICE_ID_PATTERN.test(value);
+}
+
+function mint(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  const hex = Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+  return `payez-PayEz-${hex}`;
+}
+
+/**
+ * The stable per-browser device id, minted once and persisted.
+ *
+ * Browser-only. Persistence is best-effort: private windows, disabled site
+ * data and storage-quota failures all throw on access, so every read and
+ * write is guarded. A browser that cannot persist still gets a VALID id for
+ * this call — it simply looks like a new device each time, which is the
+ * honest answer for a client that refuses to be remembered, and is still
+ * strictly better than every user sharing one identity.
+ */
+export function getDeviceId(): string {
+  if (typeof window === 'undefined') return mint();
+
+  try {
+    const existing = window.localStorage.getItem(STORAGE_KEY);
+    if (isValidDeviceId(existing)) return existing;
+  } catch {
+    return mint();
+  }
+
+  const minted = mint();
+  try {
+    window.localStorage.setItem(STORAGE_KEY, minted);
+  } catch {
+    /* not persistable — the minted id is still returned and used for this call */
+  }
+  return minted;
+}