@payez/next-mvp 4.8.1 → 4.8.2

package/src/lib/roles.ts

@@ -1,177 +1,177 @@
-/**
- * Vibe Role Constants and Utilities
- *
- * Centralized role definitions for consistent authorization across the stack.
- *
- * @version 1.0
- */
-
-// =============================================================================
-// Role Constants
-// =============================================================================
-
-/**
- * Global platform roles (IDP-level)
- * These roles are managed at the IDP and grant cross-client access.
- */
-export const GlobalRoles = {
-  /** Platform super admin - full access to everything */
-  PAYEZ_ADMIN: 'payez_admin',
-
-  /** IDP client admin - manages IDP client configuration */
-  IDP_CLIENT_ADMIN: 'idp_client_admin',
-
-  /** Vibe platform admin - manages Vibe infrastructure globally */
-  VIBE_APP_ADMIN: 'vibe_app_admin',
-
-  /** Vibe client admin - manages Vibe for a specific tenant */
-  VIBE_CLIENT_ADMIN: 'vibe_client_admin',
-
-  /** Vibe agents user - AI agents operating via CLI/automation */
-  VIBE_AGENTS_USER: 'vibe_agents_user',
-} as const;
-
-/**
- * Application-level roles (per-client)
- * These roles are scoped to a specific client/tenant.
- */
-export const AppRoles = {
-  /** Standard authenticated user */
-  VIBE_APP_USER: 'vibe_app_user',
-} as const;
-
-/**
- * All Vibe roles combined
- */
-export const VibeRoles = {
-  ...GlobalRoles,
-  ...AppRoles,
-} as const;
-
-// =============================================================================
-// Role Groups
-// =============================================================================
-
-/**
- * Roles that grant admin access to the /admin section.
- * Any of these roles allows access to admin pages.
- */
-export const ADMIN_ROLES: readonly string[] = [
-  GlobalRoles.PAYEZ_ADMIN,
-  GlobalRoles.VIBE_APP_ADMIN,
-  GlobalRoles.VIBE_CLIENT_ADMIN,
-  GlobalRoles.IDP_CLIENT_ADMIN,
-] as const;
-
-/**
- * Roles that grant platform-wide admin access (not client-scoped).
- * These can access/modify any client's data.
- */
-export const PLATFORM_ADMIN_ROLES: readonly string[] = [
-  GlobalRoles.PAYEZ_ADMIN,
-  GlobalRoles.VIBE_APP_ADMIN,
-] as const;
-
-/**
- * Roles that grant client-scoped admin access.
- * These can only access their own client's data.
- */
-export const CLIENT_ADMIN_ROLES: readonly string[] = [
-  GlobalRoles.VIBE_CLIENT_ADMIN,
-  GlobalRoles.IDP_CLIENT_ADMIN,
-] as const;
-
-// =============================================================================
-// Role Checking Utilities
-// =============================================================================
-
-/**
- * Check if user has a specific role
- */
-export function hasRole(userRoles: string[] | undefined, role: string): boolean {
-  if (!userRoles || !Array.isArray(userRoles)) return false;
-  return userRoles.includes(role);
-}
-
-/**
- * Check if user has any of the specified roles
- */
-export function hasAnyRole(userRoles: string[] | undefined, roles: readonly string[]): boolean {
-  if (!userRoles || !Array.isArray(userRoles)) return false;
-  return roles.some(role => userRoles.includes(role));
-}
-
-/**
- * Check if user has all of the specified roles
- */
-export function hasAllRoles(userRoles: string[] | undefined, roles: readonly string[]): boolean {
-  if (!userRoles || !Array.isArray(userRoles)) return false;
-  return roles.every(role => userRoles.includes(role));
-}
-
-/**
- * Check if user has admin access (any admin role)
- */
-export function isAdmin(userRoles: string[] | undefined): boolean {
-  return hasAnyRole(userRoles, ADMIN_ROLES);
-}
-
-/**
- * Check if user has platform-wide admin access
- */
-export function isPlatformAdmin(userRoles: string[] | undefined): boolean {
-  return hasAnyRole(userRoles, PLATFORM_ADMIN_ROLES);
-}
-
-/**
- * Check if user is a client-scoped admin (not platform admin)
- */
-export function isClientAdmin(userRoles: string[] | undefined): boolean {
-  return hasAnyRole(userRoles, CLIENT_ADMIN_ROLES) && !isPlatformAdmin(userRoles);
-}
-
-// =============================================================================
-// Role Hierarchy
-// =============================================================================
-
-/**
- * Role hierarchy (higher index = more access)
- *
- * payez_admin (4) - IDP super admin, can do anything
- * vibe_app_admin (3) - Platform admin, manages Vibe globally
- * vibe_client_admin (2) - Client admin, manages their own tenant
- * idp_client_admin (2) - IDP client admin, manages IDP config
- * vibe_app_user (1) - Regular authenticated user
- * (anonymous) (0) - No authentication
- */
-export const ROLE_HIERARCHY: Record<string, number> = {
-  [GlobalRoles.PAYEZ_ADMIN]: 4,
-  [GlobalRoles.VIBE_APP_ADMIN]: 3,
-  [GlobalRoles.VIBE_CLIENT_ADMIN]: 2,
-  [GlobalRoles.IDP_CLIENT_ADMIN]: 2,
-  [AppRoles.VIBE_APP_USER]: 1,
-};
-
-/**
- * Get the highest role level for a user
- */
-export function getHighestRoleLevel(userRoles: string[] | undefined): number {
-  if (!userRoles || !Array.isArray(userRoles)) return 0;
-  return Math.max(0, ...userRoles.map(role => ROLE_HIERARCHY[role] || 0));
-}
-
-export default {
-  VibeRoles,
-  GlobalRoles,
-  AppRoles,
-  ADMIN_ROLES,
-  PLATFORM_ADMIN_ROLES,
-  CLIENT_ADMIN_ROLES,
-  hasRole,
-  hasAnyRole,
-  hasAllRoles,
-  isAdmin,
-  isPlatformAdmin,
-  isClientAdmin,
-  getHighestRoleLevel,
-};
+/**
+ * Vibe Role Constants and Utilities
+ *
+ * Centralized role definitions for consistent authorization across the stack.
+ *
+ * @version 1.0
+ */
+
+// =============================================================================
+// Role Constants
+// =============================================================================
+
+/**
+ * Global platform roles (IDP-level)
+ * These roles are managed at the IDP and grant cross-client access.
+ */
+export const GlobalRoles = {
+  /** Platform super admin - full access to everything */
+  PAYEZ_ADMIN: 'payez_admin',
+
+  /** IDP client admin - manages IDP client configuration */
+  IDP_CLIENT_ADMIN: 'idp_client_admin',
+
+  /** Vibe platform admin - manages Vibe infrastructure globally */
+  VIBE_APP_ADMIN: 'vibe_app_admin',
+
+  /** Vibe client admin - manages Vibe for a specific tenant */
+  VIBE_CLIENT_ADMIN: 'vibe_client_admin',
+
+  /** Vibe agents user - AI agents operating via CLI/automation */
+  VIBE_AGENTS_USER: 'vibe_agents_user',
+} as const;
+
+/**
+ * Application-level roles (per-client)
+ * These roles are scoped to a specific client/tenant.
+ */
+export const AppRoles = {
+  /** Standard authenticated user */
+  VIBE_APP_USER: 'vibe_app_user',
+} as const;
+
+/**
+ * All Vibe roles combined
+ */
+export const VibeRoles = {
+  ...GlobalRoles,
+  ...AppRoles,
+} as const;
+
+// =============================================================================
+// Role Groups
+// =============================================================================
+
+/**
+ * Roles that grant admin access to the /admin section.
+ * Any of these roles allows access to admin pages.
+ */
+export const ADMIN_ROLES: readonly string[] = [
+  GlobalRoles.PAYEZ_ADMIN,
+  GlobalRoles.VIBE_APP_ADMIN,
+  GlobalRoles.VIBE_CLIENT_ADMIN,
+  GlobalRoles.IDP_CLIENT_ADMIN,
+] as const;
+
+/**
+ * Roles that grant platform-wide admin access (not client-scoped).
+ * These can access/modify any client's data.
+ */
+export const PLATFORM_ADMIN_ROLES: readonly string[] = [
+  GlobalRoles.PAYEZ_ADMIN,
+  GlobalRoles.VIBE_APP_ADMIN,
+] as const;
+
+/**
+ * Roles that grant client-scoped admin access.
+ * These can only access their own client's data.
+ */
+export const CLIENT_ADMIN_ROLES: readonly string[] = [
+  GlobalRoles.VIBE_CLIENT_ADMIN,
+  GlobalRoles.IDP_CLIENT_ADMIN,
+] as const;
+
+// =============================================================================
+// Role Checking Utilities
+// =============================================================================
+
+/**
+ * Check if user has a specific role
+ */
+export function hasRole(userRoles: string[] | undefined, role: string): boolean {
+  if (!userRoles || !Array.isArray(userRoles)) return false;
+  return userRoles.includes(role);
+}
+
+/**
+ * Check if user has any of the specified roles
+ */
+export function hasAnyRole(userRoles: string[] | undefined, roles: readonly string[]): boolean {
+  if (!userRoles || !Array.isArray(userRoles)) return false;
+  return roles.some(role => userRoles.includes(role));
+}
+
+/**
+ * Check if user has all of the specified roles
+ */
+export function hasAllRoles(userRoles: string[] | undefined, roles: readonly string[]): boolean {
+  if (!userRoles || !Array.isArray(userRoles)) return false;
+  return roles.every(role => userRoles.includes(role));
+}
+
+/**
+ * Check if user has admin access (any admin role)
+ */
+export function isAdmin(userRoles: string[] | undefined): boolean {
+  return hasAnyRole(userRoles, ADMIN_ROLES);
+}
+
+/**
+ * Check if user has platform-wide admin access
+ */
+export function isPlatformAdmin(userRoles: string[] | undefined): boolean {
+  return hasAnyRole(userRoles, PLATFORM_ADMIN_ROLES);
+}
+
+/**
+ * Check if user is a client-scoped admin (not platform admin)
+ */
+export function isClientAdmin(userRoles: string[] | undefined): boolean {
+  return hasAnyRole(userRoles, CLIENT_ADMIN_ROLES) && !isPlatformAdmin(userRoles);
+}
+
+// =============================================================================
+// Role Hierarchy
+// =============================================================================
+
+/**
+ * Role hierarchy (higher index = more access)
+ *
+ * payez_admin (4) - IDP super admin, can do anything
+ * vibe_app_admin (3) - Platform admin, manages Vibe globally
+ * vibe_client_admin (2) - Client admin, manages their own tenant
+ * idp_client_admin (2) - IDP client admin, manages IDP config
+ * vibe_app_user (1) - Regular authenticated user
+ * (anonymous) (0) - No authentication
+ */
+export const ROLE_HIERARCHY: Record<string, number> = {
+  [GlobalRoles.PAYEZ_ADMIN]: 4,
+  [GlobalRoles.VIBE_APP_ADMIN]: 3,
+  [GlobalRoles.VIBE_CLIENT_ADMIN]: 2,
+  [GlobalRoles.IDP_CLIENT_ADMIN]: 2,
+  [AppRoles.VIBE_APP_USER]: 1,
+};
+
+/**
+ * Get the highest role level for a user
+ */
+export function getHighestRoleLevel(userRoles: string[] | undefined): number {
+  if (!userRoles || !Array.isArray(userRoles)) return 0;
+  return Math.max(0, ...userRoles.map(role => ROLE_HIERARCHY[role] || 0));
+}
+
+export default {
+  VibeRoles,
+  GlobalRoles,
+  AppRoles,
+  ADMIN_ROLES,
+  PLATFORM_ADMIN_ROLES,
+  CLIENT_ADMIN_ROLES,
+  hasRole,
+  hasAnyRole,
+  hasAllRoles,
+  isAdmin,
+  isPlatformAdmin,
+  isClientAdmin,
+  getHighestRoleLevel,
+};

package/src/lib/safe-error-response.ts

@@ -1,149 +1,149 @@
-/**
- * PAY-1438: what a USER-FACING handler may put in an error response.
- *
- * Several of these routes are reachable before authentication (session check, viability probe,
- * logout, auth status, refresh-viability), so whatever lands in the body reaches an anonymous caller.
- *
- * Class A - an EXCEPTION: its text (ioredis `connect ECONNREFUSED host:port`, undici `fetch failed`,
- * JSON parse errors quoting payload bytes) stays server-side. The response carries a fixed message,
- * a code and a correlationId; the log line carries the exception and the same id.
- *
- * Class B - an IDP ERROR ENVELOPE ({ success, message, error: { code, message, details, support } }):
- * never passed through whole. Only the display contract is projected: code, message, resolution,
- * request_id - each only when it is a string. `details` (free-form, may carry validation internals
- * or exception data) is dropped, except for the password-policy messages change-password's UI reads.
- */
-
-import { knownPasswordRules } from './password-rules';
-
-export interface IdpErrorProjection {
-  code?: string;
-  message?: string;
-  resolution?: string;
-  request_id?: string;
-}
-
-const str = (v: unknown): string | undefined => (typeof v === 'string' ? v : undefined);
-
-/** Log an exception with a fresh correlationId and return the id for the response body. */
-export function logExceptionWithCorrelation(tag: string, err: unknown): string {
-  const correlationId = globalThis.crypto.randomUUID();
-  console.error(tag, { correlationId, error: err });
-  return correlationId;
-}
-
-/** Whitelisted projection of an IDP error envelope: code / message / resolution / request_id only. */
-export function projectIdpError(json: unknown): IdpErrorProjection {
-  if (!json || typeof json !== 'object') return {};
-  const top = json as Record<string, unknown>;
-  const err = top.error && typeof top.error === 'object' ? (top.error as Record<string, unknown>) : {};
-  const support = err.support && typeof err.support === 'object' ? (err.support as Record<string, unknown>) : {};
-  const out: IdpErrorProjection = {};
-  const code = str(err.code) ?? str(top.code) ?? str(top.error_code);
-  const message = str(err.message) ?? str(top.message);
-  const resolution = str(err.resolution) ?? str(top.resolution);
-  const requestId = str(support.request_id) ?? str(top.request_id);
-  if (code !== undefined) out.code = code;
-  if (message !== undefined) out.message = message;
-  if (resolution !== undefined) out.resolution = resolution;
-  if (requestId !== undefined) out.request_id = requestId;
-  return out;
-}
-
-/**
- * change-password's `details`: the security pages show `details.value[0].message` (else
- * `details.message`) as the password-policy error (QAPert census on PAY-1438). Keep exactly those
- * strings; drop everything else.
- */
-export function projectPasswordPolicyDetails(details: unknown): { message?: string; value?: Array<{ message: string }> } | undefined {
-  if (!details || typeof details !== 'object') return undefined;
-  const d = details as Record<string, unknown>;
-  const out: { message?: string; value?: Array<{ message: string }> } = {};
-  if (Array.isArray(d.value)) {
-    const value = d.value
-      .map((v) => (v && typeof v === 'object' ? str((v as Record<string, unknown>).message) : undefined))
-      .filter((m): m is string => m !== undefined)
-      .map((message) => ({ message }));
-    if (value.length) out.value = value;
-  }
-  const message = str(d.message);
-  if (message !== undefined) out.message = message;
-  return out.value || out.message !== undefined ? out : undefined;
-}
-
-/**
- * For proxies that used to pass the IDP response through WHOLE on every status (account recovery,
- * reset-password, passkey sign-in - all anonymous): on a non-OK status, return the same envelope
- * SHAPE callers already read (`message`, `error.code`, `error.message`) built only from the
- * whitelisted projection. The success path keeps its passthrough.
- */
-export function idpErrorEnvelope(json: unknown, fallbackMessage = 'Request failed'): {
-  success: false;
-  message: string;
-  error: { code?: string; message: string; resolution?: string };
-  request_id?: string;
-} {
-  const p = projectIdpError(json);
-  const message = p.message ?? fallbackMessage;
-  const error: { code?: string; message: string; resolution?: string } = { message };
-  if (p.code !== undefined) error.code = p.code;
-  if (p.resolution !== undefined) error.resolution = p.resolution;
-  const out: { success: false; message: string; error: typeof error; request_id?: string } = { success: false, message, error };
-  if (p.request_id !== undefined) out.request_id = p.request_id;
-  return out;
-}
-
-/**
- * True only when the IdP EXPLICITLY says the recovery token itself is unusable: details.code token_expired / token_used, or an
- * ASP.NET Identity `InvalidToken` error in details.value (what the served IdP sends when ResetPasswordAsync refuses a used or
- * expired token, AccountController.ResetPassword line ~699 at b5c56e6c0). Only this boolean crosses the anonymous route, never the
- * Identity error text. Anything else is NOT a dead-link signal (rigpert 60822): an older IdP sends a weak-password refusal with
- * no code at all, and calling that 'link expired' loops the user.
- */
-export function projectResetTokenInvalid(json: unknown): boolean {
-  if (!json || typeof json !== 'object') return false;
-  const top = json as Record<string, unknown>;
-  const err = top.error && typeof top.error === 'object' ? (top.error as Record<string, unknown>) : {};
-  const details = (err.details && typeof err.details === 'object' ? err.details : top.details && typeof top.details === 'object' ? top.details : null) as Record<string, unknown> | null;
-  if (!details) return false;
-  if (details.code === 'token_expired' || details.code === 'token_used') return true;
-  return Array.isArray(details.value) && details.value.some((v) => !!v && typeof v === 'object' && (v as Record<string, unknown>).code === 'InvalidToken');
-}
-
-/**
- * PAY-1591: the IdP refuses a reset password with error.details = { code: 'password_policy', rules: [codes], requirements:
- * [English] }. This route is anonymous, so only the CODES cross, and only the known ones: never `requirements`, never an
- * unknown string. Returns undefined when this is NOT a password-policy refusal, and [] when it is one but names no rule we know
- * (the caller must be able to tell a refused password from a dead recovery session).
- */
-export function projectPasswordPolicyRules(json: unknown): string[] | undefined {
-  if (!json || typeof json !== 'object') return undefined;
-  const top = json as Record<string, unknown>;
-  const err = top.error && typeof top.error === 'object' ? (top.error as Record<string, unknown>) : {};
-  const details = (err.details && typeof err.details === 'object' ? err.details : top.details && typeof top.details === 'object' ? top.details : null) as Record<string, unknown> | null;
-  if (!details || details.code !== 'password_policy') return undefined;
-  return knownPasswordRules(details.rules);
-}
-
-/**
- * PAY-2103 (AUTH-009 breached-password check): the IdP refuses a password found in a breach corpus with
- * the typed code `password_breached` in its 400 validation envelope (error.code, or error.details.code,
- * or a value[] entry while it settles). The reset-password route is ANONYMOUS, so only a BOOLEAN crosses
- * (`password_breached: true`), never the code text: the page maps the boolean to its own sentence. Reads
- * only the code, never IdP text.
- */
-export function projectPasswordBreached(json: unknown): boolean {
-  if (!json || typeof json !== 'object') return false;
-  const top = json as Record<string, unknown>;
-  const err = top.error && typeof top.error === 'object' ? (top.error as Record<string, unknown>) : {};
-  const direct = str(err.code) ?? str(top.code) ?? str(top.error_code);
-  if (direct?.toLowerCase() === 'password_breached') return true;
-  const details = (err.details && typeof err.details === 'object' ? err.details : top.details && typeof top.details === 'object' ? top.details : null) as Record<string, unknown> | null;
-  if (str(details?.code)?.toLowerCase() === 'password_breached') return true;
-  // THE SHAPE THE IdP ACTUALLY SENDS (DotNetPert-Scout, PAY-2103 PR 850caa07a): error.details =
-  // { field:'new_password', code:'password_policy', rules:['password_breached'], requirements:[...] }.
-  // The breach is a member of rules[], not a code - the house envelope carries every password rule
-  // that way. Reading only a code would MISS the real refusal.
-  if (Array.isArray(details?.rules) && (details!.rules as unknown[]).some((r) => typeof r === 'string' && r.toLowerCase() === 'password_breached')) return true;
-  return Array.isArray(details?.value) && (details!.value as unknown[]).some((v) => !!v && typeof v === 'object' && str((v as Record<string, unknown>).code)?.toLowerCase() === 'password_breached');
-}
+/**
+ * PAY-1438: what a USER-FACING handler may put in an error response.
+ *
+ * Several of these routes are reachable before authentication (session check, viability probe,
+ * logout, auth status, refresh-viability), so whatever lands in the body reaches an anonymous caller.
+ *
+ * Class A - an EXCEPTION: its text (ioredis `connect ECONNREFUSED host:port`, undici `fetch failed`,
+ * JSON parse errors quoting payload bytes) stays server-side. The response carries a fixed message,
+ * a code and a correlationId; the log line carries the exception and the same id.
+ *
+ * Class B - an IDP ERROR ENVELOPE ({ success, message, error: { code, message, details, support } }):
+ * never passed through whole. Only the display contract is projected: code, message, resolution,
+ * request_id - each only when it is a string. `details` (free-form, may carry validation internals
+ * or exception data) is dropped, except for the password-policy messages change-password's UI reads.
+ */
+
+import { knownPasswordRules } from './password-rules';
+
+export interface IdpErrorProjection {
+  code?: string;
+  message?: string;
+  resolution?: string;
+  request_id?: string;
+}
+
+const str = (v: unknown): string | undefined => (typeof v === 'string' ? v : undefined);
+
+/** Log an exception with a fresh correlationId and return the id for the response body. */
+export function logExceptionWithCorrelation(tag: string, err: unknown): string {
+  const correlationId = globalThis.crypto.randomUUID();
+  console.error(tag, { correlationId, error: err });
+  return correlationId;
+}
+
+/** Whitelisted projection of an IDP error envelope: code / message / resolution / request_id only. */
+export function projectIdpError(json: unknown): IdpErrorProjection {
+  if (!json || typeof json !== 'object') return {};
+  const top = json as Record<string, unknown>;
+  const err = top.error && typeof top.error === 'object' ? (top.error as Record<string, unknown>) : {};
+  const support = err.support && typeof err.support === 'object' ? (err.support as Record<string, unknown>) : {};
+  const out: IdpErrorProjection = {};
+  const code = str(err.code) ?? str(top.code) ?? str(top.error_code);
+  const message = str(err.message) ?? str(top.message);
+  const resolution = str(err.resolution) ?? str(top.resolution);
+  const requestId = str(support.request_id) ?? str(top.request_id);
+  if (code !== undefined) out.code = code;
+  if (message !== undefined) out.message = message;
+  if (resolution !== undefined) out.resolution = resolution;
+  if (requestId !== undefined) out.request_id = requestId;
+  return out;
+}
+
+/**
+ * change-password's `details`: the security pages show `details.value[0].message` (else
+ * `details.message`) as the password-policy error (QAPert census on PAY-1438). Keep exactly those
+ * strings; drop everything else.
+ */
+export function projectPasswordPolicyDetails(details: unknown): { message?: string; value?: Array<{ message: string }> } | undefined {
+  if (!details || typeof details !== 'object') return undefined;
+  const d = details as Record<string, unknown>;
+  const out: { message?: string; value?: Array<{ message: string }> } = {};
+  if (Array.isArray(d.value)) {
+    const value = d.value
+      .map((v) => (v && typeof v === 'object' ? str((v as Record<string, unknown>).message) : undefined))
+      .filter((m): m is string => m !== undefined)
+      .map((message) => ({ message }));
+    if (value.length) out.value = value;
+  }
+  const message = str(d.message);
+  if (message !== undefined) out.message = message;
+  return out.value || out.message !== undefined ? out : undefined;
+}
+
+/**
+ * For proxies that used to pass the IDP response through WHOLE on every status (account recovery,
+ * reset-password, passkey sign-in - all anonymous): on a non-OK status, return the same envelope
+ * SHAPE callers already read (`message`, `error.code`, `error.message`) built only from the
+ * whitelisted projection. The success path keeps its passthrough.
+ */
+export function idpErrorEnvelope(json: unknown, fallbackMessage = 'Request failed'): {
+  success: false;
+  message: string;
+  error: { code?: string; message: string; resolution?: string };
+  request_id?: string;
+} {
+  const p = projectIdpError(json);
+  const message = p.message ?? fallbackMessage;
+  const error: { code?: string; message: string; resolution?: string } = { message };
+  if (p.code !== undefined) error.code = p.code;
+  if (p.resolution !== undefined) error.resolution = p.resolution;
+  const out: { success: false; message: string; error: typeof error; request_id?: string } = { success: false, message, error };
+  if (p.request_id !== undefined) out.request_id = p.request_id;
+  return out;
+}
+
+/**
+ * True only when the IdP EXPLICITLY says the recovery token itself is unusable: details.code token_expired / token_used, or an
+ * ASP.NET Identity `InvalidToken` error in details.value (what the served IdP sends when ResetPasswordAsync refuses a used or
+ * expired token, AccountController.ResetPassword line ~699 at b5c56e6c0). Only this boolean crosses the anonymous route, never the
+ * Identity error text. Anything else is NOT a dead-link signal (rigpert 60822): an older IdP sends a weak-password refusal with
+ * no code at all, and calling that 'link expired' loops the user.
+ */
+export function projectResetTokenInvalid(json: unknown): boolean {
+  if (!json || typeof json !== 'object') return false;
+  const top = json as Record<string, unknown>;
+  const err = top.error && typeof top.error === 'object' ? (top.error as Record<string, unknown>) : {};
+  const details = (err.details && typeof err.details === 'object' ? err.details : top.details && typeof top.details === 'object' ? top.details : null) as Record<string, unknown> | null;
+  if (!details) return false;
+  if (details.code === 'token_expired' || details.code === 'token_used') return true;
+  return Array.isArray(details.value) && details.value.some((v) => !!v && typeof v === 'object' && (v as Record<string, unknown>).code === 'InvalidToken');
+}
+
+/**
+ * PAY-1591: the IdP refuses a reset password with error.details = { code: 'password_policy', rules: [codes], requirements:
+ * [English] }. This route is anonymous, so only the CODES cross, and only the known ones: never `requirements`, never an
+ * unknown string. Returns undefined when this is NOT a password-policy refusal, and [] when it is one but names no rule we know
+ * (the caller must be able to tell a refused password from a dead recovery session).
+ */
+export function projectPasswordPolicyRules(json: unknown): string[] | undefined {
+  if (!json || typeof json !== 'object') return undefined;
+  const top = json as Record<string, unknown>;
+  const err = top.error && typeof top.error === 'object' ? (top.error as Record<string, unknown>) : {};
+  const details = (err.details && typeof err.details === 'object' ? err.details : top.details && typeof top.details === 'object' ? top.details : null) as Record<string, unknown> | null;
+  if (!details || details.code !== 'password_policy') return undefined;
+  return knownPasswordRules(details.rules);
+}
+
+/**
+ * PAY-2103 (AUTH-009 breached-password check): the IdP refuses a password found in a breach corpus with
+ * the typed code `password_breached` in its 400 validation envelope (error.code, or error.details.code,
+ * or a value[] entry while it settles). The reset-password route is ANONYMOUS, so only a BOOLEAN crosses
+ * (`password_breached: true`), never the code text: the page maps the boolean to its own sentence. Reads
+ * only the code, never IdP text.
+ */
+export function projectPasswordBreached(json: unknown): boolean {
+  if (!json || typeof json !== 'object') return false;
+  const top = json as Record<string, unknown>;
+  const err = top.error && typeof top.error === 'object' ? (top.error as Record<string, unknown>) : {};
+  const direct = str(err.code) ?? str(top.code) ?? str(top.error_code);
+  if (direct?.toLowerCase() === 'password_breached') return true;
+  const details = (err.details && typeof err.details === 'object' ? err.details : top.details && typeof top.details === 'object' ? top.details : null) as Record<string, unknown> | null;
+  if (str(details?.code)?.toLowerCase() === 'password_breached') return true;
+  // THE SHAPE THE IdP ACTUALLY SENDS (DotNetPert-Scout, PAY-2103 PR 850caa07a): error.details =
+  // { field:'new_password', code:'password_policy', rules:['password_breached'], requirements:[...] }.
+  // The breach is a member of rules[], not a code - the house envelope carries every password rule
+  // that way. Reading only a code would MISS the real refusal.
+  if (Array.isArray(details?.rules) && (details!.rules as unknown[]).some((r) => typeof r === 'string' && r.toLowerCase() === 'password_breached')) return true;
+  return Array.isArray(details?.value) && (details!.value as unknown[]).some((v) => !!v && typeof v === 'object' && str((v as Record<string, unknown>).code)?.toLowerCase() === 'password_breached');
+}