@payez/next-mvp 4.8.0 → 4.8.2

package/src/lib/nextauth-secret.ts

@@ -1,168 +1,168 @@
-/**
- * resolveNextAuthSecret - COMPATIBILITY SHIM (restored 2026-09-30, PAY-2005 / N7).
- *
- * ---------------------------------------------------------------------------
- * WHY THIS FILE EXISTS, AND WHY IT IS A SHIM RATHER THAN A FEATURE
- * ---------------------------------------------------------------------------
- * The NextAuth-era broker secret resolver was DELETED in
- *     4d3d29e6  "feat!: Better Auth 4.0.0 — NextAuth fully removed"
- * and it is intentionally NOT coming back as first-class API: this package is
- * Better Auth now, and new apps must not resolve a NextAuth secret at all.
- *
- * It is restored here ONLY because ONE consumer is still mid-migration and cannot
- * take the 4.4.x bump without it:
- *
- *   CONSUMER THAT NEEDS THIS: the customer portal
- *   (`payez_idp_admin_web` / VibeID-Customer-Portal). It is pinned at
- *   @payez/next-mvp 4.0.46 and still runs BOTH next-auth@4.24 and better-auth; its
- *   `src/lib/server-session.ts` and `src/lib/session-token.ts` (and 5 route files)
- *   import `resolveNextAuthSecret` from here. Without this export, bumping the
- *   portal to 4.4.x breaks its build. BAPert ruled (68003) to ship this scoped
- *   shim rather than force the portal's full NextAuth->BetterAuth migration
- *   tonight. That migration is tracked as its own card; WHEN IT LANDS, DELETE
- *   THIS FILE.
- *
- * DO NOT add new consumers. If you are starting an app, use Better Auth's own
- * secret handling; you do not need this.
- *
- * ---------------------------------------------------------------------------
- * BEHAVIOUR (faithful to the 4.0.46 implementation, with one deliberate change)
- * ---------------------------------------------------------------------------
- * Priority: (1) process.env.NEXTAUTH_SECRET if set; (2) fetch from the IDP via a
- * signed client assertion; (3) cache in-memory 5 min and stamp NEXTAUTH_SECRET.
- *
- * DELIBERATE CHANGE, 4.0.46 -> here: 4.0.46 validated the fetched secret with
- * `validateNextAuthSecret`, which this package's 4.4.x no longer exports (it was
- * renamed to `validateAuthSecret` with an IDENTICAL body). The shim calls
- * `validateAuthSecret` - same predicate, current name - so there is no second
- * copy of the rule. The validation semantics are unchanged.
- *
- * SERVER-ONLY: the IDP handshake and NEXTAUTH_SECRET are server concerns.
- */
-import 'server-only';
-import { randomUUID } from 'node:crypto';
-import { validateAuthSecret } from './secret-validation';
-
-let cachedSecret: string | null = null;
-let lastFetchedAt = 0;
-
-const CACHE_TTL_MS = 5 * 60 * 1000;
-
-interface SigningResponse {
-  data?: { client_assertion?: string; clientAssertion?: string; ClientAssertion?: string };
-  client_assertion?: string;
-  clientAssertion?: string;
-  ClientAssertion?: string;
-}
-
-interface SecretResponse {
-  data?: { secret?: string; configuration?: unknown };
-  secret?: string;
-  configuration?: unknown;
-}
-
-/**
- * Resolve the NextAuth secret (server-only).
- *
- * Priority:
- * 1) Use process.env.NEXTAUTH_SECRET if present (allows overrides/production)
- * 2) Fetch from the IDP broker endpoint - the IDP handles all Key Vault/signing
- * 3) Cache result in-memory and set process.env.NEXTAUTH_SECRET for later calls
- */
-export async function resolveNextAuthSecret(): Promise<string> {
-  // Check if already in environment
-  if (process.env.NEXTAUTH_SECRET && process.env.NEXTAUTH_SECRET.trim() !== '') {
-    return process.env.NEXTAUTH_SECRET;
-  }
-
-  // Check if cached and fresh (within 5 minutes)
-  if (cachedSecret && Date.now() - lastFetchedAt < CACHE_TTL_MS) {
-    return cachedSecret;
-  }
-
-  // Broker mode: fetch from the IDP (the IDP handles all Key Vault/signing)
-  const base = process.env.IDP_URL;
-  if (!base) throw new Error('IDP_URL environment variable is required');
-
-  const clientIdStr = process.env.CLIENT_ID;
-  if (!clientIdStr || clientIdStr.trim() === '') {
-    throw new Error('CLIENT_ID is required (e.g., "ideal_resume_website")');
-  }
-
-  // Step 1: ask the IDP to sign a client assertion (the IDP holds the keys, not us)
-  const signingUrl = `${base.replace(/\/$/, '')}/api/ExternalAuth/sign-client-assertion`;
-  const signingResp = await fetch(signingUrl, {
-    method: 'POST',
-    headers: {
-      Accept: 'application/json',
-      'Content-Type': 'application/json',
-      'X-Client-Id': clientIdStr,
-      'X-Correlation-Id': randomUUID().replace(/-/g, ''),
-    },
-    body: JSON.stringify({
-      issuer: clientIdStr,
-      subject: clientIdStr,
-      audience: 'urn:payez:externalauth:nextauthsecret',
-      expires_in: 60,
-    }),
-    cache: 'no-store',
-  });
-
-  if (!signingResp.ok) {
-    const txt = await signingResp.text().catch(() => 'Unknown error');
-    throw new Error(`Failed to sign client assertion: ${signingResp.status} ${signingResp.statusText} - ${txt}`);
-  }
-
-  const signingBody = (await signingResp.json().catch(() => ({}))) as SigningResponse;
-  const clientAssertion =
-    signingBody?.data?.client_assertion ??
-    signingBody?.data?.clientAssertion ??
-    signingBody?.client_assertion ??
-    signingBody?.clientAssertion ??
-    signingBody?.data?.ClientAssertion ??
-    signingBody?.ClientAssertion;
-
-  if (!clientAssertion || typeof clientAssertion !== 'string') {
-    throw new Error('IDP did not return a valid signed client assertion');
-  }
-
-  // Step 2: use the signed assertion to fetch the NextAuth secret
-  const proxyUrl = `${base.replace(/\/$/, '')}/api/ExternalAuth/next-auth/secret`;
-  const proxyResp = await fetch(proxyUrl, {
-    method: 'POST',
-    headers: {
-      Accept: 'application/json',
-      'Content-Type': 'application/json',
-      'X-Client-Id': clientIdStr,
-      'X-Correlation-Id': randomUUID().replace(/-/g, ''),
-    },
-    body: JSON.stringify({ client_assertion: clientAssertion }),
-    cache: 'no-store',
-  });
-
-  if (!proxyResp.ok) {
-    const txt = await proxyResp.text().catch(() => 'Unknown error');
-    throw new Error(`Proxy error: ${proxyResp.status} ${proxyResp.statusText} - ${txt}`);
-  }
-
-  const proxyBody = (await proxyResp.json().catch(() => ({}))) as SecretResponse;
-  const secret = proxyBody?.data?.secret ?? proxyBody?.secret;
-  // `configuration` is available from the IDP but deliberately not logged.
-
-  if (!secret || typeof secret !== 'string') {
-    throw new Error('Proxy did not return a valid NextAuth secret');
-  }
-
-  // Same predicate as 4.0.46's validateNextAuthSecret, under its current name.
-  const validation = validateAuthSecret(secret);
-  if (!validation.valid) {
-    throw new Error(`Fetched NextAuth secret failed validation: ${validation.reason}`);
-  }
-
-  cachedSecret = secret;
-  lastFetchedAt = Date.now();
-  process.env.NEXTAUTH_SECRET = secret;
-
-  console.log('[NEXTAUTH-SECRET] Resolved from IDP (length:', secret.length + ')');
-  return secret;
-}
+/**
+ * resolveNextAuthSecret - COMPATIBILITY SHIM (restored 2026-09-30, PAY-2005 / N7).
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS, AND WHY IT IS A SHIM RATHER THAN A FEATURE
+ * ---------------------------------------------------------------------------
+ * The NextAuth-era broker secret resolver was DELETED in
+ *     4d3d29e6  "feat!: Better Auth 4.0.0 — NextAuth fully removed"
+ * and it is intentionally NOT coming back as first-class API: this package is
+ * Better Auth now, and new apps must not resolve a NextAuth secret at all.
+ *
+ * It is restored here ONLY because ONE consumer is still mid-migration and cannot
+ * take the 4.4.x bump without it:
+ *
+ *   CONSUMER THAT NEEDS THIS: the customer portal
+ *   (`payez_idp_admin_web` / VibeID-Customer-Portal). It is pinned at
+ *   @payez/next-mvp 4.0.46 and still runs BOTH next-auth@4.24 and better-auth; its
+ *   `src/lib/server-session.ts` and `src/lib/session-token.ts` (and 5 route files)
+ *   import `resolveNextAuthSecret` from here. Without this export, bumping the
+ *   portal to 4.4.x breaks its build. BAPert ruled (68003) to ship this scoped
+ *   shim rather than force the portal's full NextAuth->BetterAuth migration
+ *   tonight. That migration is tracked as its own card; WHEN IT LANDS, DELETE
+ *   THIS FILE.
+ *
+ * DO NOT add new consumers. If you are starting an app, use Better Auth's own
+ * secret handling; you do not need this.
+ *
+ * ---------------------------------------------------------------------------
+ * BEHAVIOUR (faithful to the 4.0.46 implementation, with one deliberate change)
+ * ---------------------------------------------------------------------------
+ * Priority: (1) process.env.NEXTAUTH_SECRET if set; (2) fetch from the IDP via a
+ * signed client assertion; (3) cache in-memory 5 min and stamp NEXTAUTH_SECRET.
+ *
+ * DELIBERATE CHANGE, 4.0.46 -> here: 4.0.46 validated the fetched secret with
+ * `validateNextAuthSecret`, which this package's 4.4.x no longer exports (it was
+ * renamed to `validateAuthSecret` with an IDENTICAL body). The shim calls
+ * `validateAuthSecret` - same predicate, current name - so there is no second
+ * copy of the rule. The validation semantics are unchanged.
+ *
+ * SERVER-ONLY: the IDP handshake and NEXTAUTH_SECRET are server concerns.
+ */
+import 'server-only';
+import { randomUUID } from 'node:crypto';
+import { validateAuthSecret } from './secret-validation';
+
+let cachedSecret: string | null = null;
+let lastFetchedAt = 0;
+
+const CACHE_TTL_MS = 5 * 60 * 1000;
+
+interface SigningResponse {
+  data?: { client_assertion?: string; clientAssertion?: string; ClientAssertion?: string };
+  client_assertion?: string;
+  clientAssertion?: string;
+  ClientAssertion?: string;
+}
+
+interface SecretResponse {
+  data?: { secret?: string; configuration?: unknown };
+  secret?: string;
+  configuration?: unknown;
+}
+
+/**
+ * Resolve the NextAuth secret (server-only).
+ *
+ * Priority:
+ * 1) Use process.env.NEXTAUTH_SECRET if present (allows overrides/production)
+ * 2) Fetch from the IDP broker endpoint - the IDP handles all Key Vault/signing
+ * 3) Cache result in-memory and set process.env.NEXTAUTH_SECRET for later calls
+ */
+export async function resolveNextAuthSecret(): Promise<string> {
+  // Check if already in environment
+  if (process.env.NEXTAUTH_SECRET && process.env.NEXTAUTH_SECRET.trim() !== '') {
+    return process.env.NEXTAUTH_SECRET;
+  }
+
+  // Check if cached and fresh (within 5 minutes)
+  if (cachedSecret && Date.now() - lastFetchedAt < CACHE_TTL_MS) {
+    return cachedSecret;
+  }
+
+  // Broker mode: fetch from the IDP (the IDP handles all Key Vault/signing)
+  const base = process.env.IDP_URL;
+  if (!base) throw new Error('IDP_URL environment variable is required');
+
+  const clientIdStr = process.env.CLIENT_ID;
+  if (!clientIdStr || clientIdStr.trim() === '') {
+    throw new Error('CLIENT_ID is required (e.g., "ideal_resume_website")');
+  }
+
+  // Step 1: ask the IDP to sign a client assertion (the IDP holds the keys, not us)
+  const signingUrl = `${base.replace(/\/$/, '')}/api/ExternalAuth/sign-client-assertion`;
+  const signingResp = await fetch(signingUrl, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      'X-Client-Id': clientIdStr,
+      'X-Correlation-Id': randomUUID().replace(/-/g, ''),
+    },
+    body: JSON.stringify({
+      issuer: clientIdStr,
+      subject: clientIdStr,
+      audience: 'urn:payez:externalauth:nextauthsecret',
+      expires_in: 60,
+    }),
+    cache: 'no-store',
+  });
+
+  if (!signingResp.ok) {
+    const txt = await signingResp.text().catch(() => 'Unknown error');
+    throw new Error(`Failed to sign client assertion: ${signingResp.status} ${signingResp.statusText} - ${txt}`);
+  }
+
+  const signingBody = (await signingResp.json().catch(() => ({}))) as SigningResponse;
+  const clientAssertion =
+    signingBody?.data?.client_assertion ??
+    signingBody?.data?.clientAssertion ??
+    signingBody?.client_assertion ??
+    signingBody?.clientAssertion ??
+    signingBody?.data?.ClientAssertion ??
+    signingBody?.ClientAssertion;
+
+  if (!clientAssertion || typeof clientAssertion !== 'string') {
+    throw new Error('IDP did not return a valid signed client assertion');
+  }
+
+  // Step 2: use the signed assertion to fetch the NextAuth secret
+  const proxyUrl = `${base.replace(/\/$/, '')}/api/ExternalAuth/next-auth/secret`;
+  const proxyResp = await fetch(proxyUrl, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      'X-Client-Id': clientIdStr,
+      'X-Correlation-Id': randomUUID().replace(/-/g, ''),
+    },
+    body: JSON.stringify({ client_assertion: clientAssertion }),
+    cache: 'no-store',
+  });
+
+  if (!proxyResp.ok) {
+    const txt = await proxyResp.text().catch(() => 'Unknown error');
+    throw new Error(`Proxy error: ${proxyResp.status} ${proxyResp.statusText} - ${txt}`);
+  }
+
+  const proxyBody = (await proxyResp.json().catch(() => ({}))) as SecretResponse;
+  const secret = proxyBody?.data?.secret ?? proxyBody?.secret;
+  // `configuration` is available from the IDP but deliberately not logged.
+
+  if (!secret || typeof secret !== 'string') {
+    throw new Error('Proxy did not return a valid NextAuth secret');
+  }
+
+  // Same predicate as 4.0.46's validateNextAuthSecret, under its current name.
+  const validation = validateAuthSecret(secret);
+  if (!validation.valid) {
+    throw new Error(`Fetched NextAuth secret failed validation: ${validation.reason}`);
+  }
+
+  cachedSecret = secret;
+  lastFetchedAt = Date.now();
+  process.env.NEXTAUTH_SECRET = secret;
+
+  console.log('[NEXTAUTH-SECRET] Resolved from IDP (length:', secret.length + ')');
+  return secret;
+}

package/src/lib/onboarding-proxy.ts

@@ -1,57 +1,57 @@
-/**
- * PAY-2121: shared anonymous IDP proxy for the /api/onboarding/* handlers.
- *
- * The onboarding flow is TOKEN-DRIVEN: the invitee has no account or session
- * yet, and the onboard_token IS the credential. So these calls must NOT go
- * through idpFetchJSON (which injects a Bearer from a Redis session) - there is
- * no session. They are plain server-to-server POSTs to the IdP, exactly as the
- * VibeID portal's hand-built /api/onboarding/* routes do (card 182611).
- *
- * WHY A SERVER ROUTE AT ALL, AND NOT A BROWSER CALL: the IdP URL is not exposed
- * to the browser, and the route is the one place that owns that. The token is
- * forwarded, never the IdP's host.
- */
-import { NextRequest, NextResponse } from 'next/server';
-import { ENV_CONFIG } from '../config/env';
-import { assertAbsoluteIdpUrl } from './idp-url-guard';
-
-/** A typed refusal in the kit's error envelope - used for a missing field, BEFORE any IdP call. */
-export function onboardingBadRequest(code: string, message: string) {
-  return NextResponse.json({ success: false, message, error: { code } }, { status: 400 });
-}
-
-/**
- * POST a JSON body to `{IDP_URL}{idpPath}` with no credentials, and relay the
- * IdP's status and body verbatim (the page acts on what the IdP actually
- * returns, not on a shape this layer guesses). Never relays the IdP error TEXT
- * for a non-2xx is NOT done here: the onboarding endpoints answer structured
- * envelopes the page reads; the page owns the copy.
- */
-export async function onboardingProxy(req: NextRequest, idpPath: string): Promise<NextResponse> {
-  const idpBase = ENV_CONFIG.IDP_URL;
-  if (!idpBase) {
-    return NextResponse.json({ success: false, message: 'IDP_URL is not configured', error: { code: 'NO_IDP_URL' } }, { status: 500 });
-  }
-  const url = `${idpBase}${idpPath}`;
-  assertAbsoluteIdpUrl(url);
-  let bodyText = '{}';
-  try {
-    const raw = await req.text();
-    if (raw && raw.trim().length > 0) bodyText = raw;
-  } catch { /* empty body is fine */ }
-
-  const headers: Record<string, string> = { 'Content-Type': 'application/json', Accept: 'application/json' };
-  const xfwd = req.headers.get('x-forwarded-for') || req.headers.get('x-real-ip');
-  if (xfwd) headers['X-Forwarded-For'] = xfwd;
-  const ua = req.headers.get('user-agent');
-  if (ua) headers['User-Agent'] = ua;
-
-  let res: Response;
-  try {
-    res = await fetch(url, { method: 'POST', headers, body: bodyText, cache: 'no-store' });
-  } catch {
-    return NextResponse.json({ success: false, message: 'The identity service is unreachable.', error: { code: 'UPSTREAM_UNREACHABLE' } }, { status: 502 });
-  }
-  const json = await res.json().catch(() => null);
-  return NextResponse.json(json ?? { success: res.ok }, { status: res.status });
-}
+/**
+ * PAY-2121: shared anonymous IDP proxy for the /api/onboarding/* handlers.
+ *
+ * The onboarding flow is TOKEN-DRIVEN: the invitee has no account or session
+ * yet, and the onboard_token IS the credential. So these calls must NOT go
+ * through idpFetchJSON (which injects a Bearer from a Redis session) - there is
+ * no session. They are plain server-to-server POSTs to the IdP, exactly as the
+ * VibeID portal's hand-built /api/onboarding/* routes do (card 182611).
+ *
+ * WHY A SERVER ROUTE AT ALL, AND NOT A BROWSER CALL: the IdP URL is not exposed
+ * to the browser, and the route is the one place that owns that. The token is
+ * forwarded, never the IdP's host.
+ */
+import { NextRequest, NextResponse } from 'next/server';
+import { ENV_CONFIG } from '../config/env';
+import { assertAbsoluteIdpUrl } from './idp-url-guard';
+
+/** A typed refusal in the kit's error envelope - used for a missing field, BEFORE any IdP call. */
+export function onboardingBadRequest(code: string, message: string) {
+  return NextResponse.json({ success: false, message, error: { code } }, { status: 400 });
+}
+
+/**
+ * POST a JSON body to `{IDP_URL}{idpPath}` with no credentials, and relay the
+ * IdP's status and body verbatim (the page acts on what the IdP actually
+ * returns, not on a shape this layer guesses). Never relays the IdP error TEXT
+ * for a non-2xx is NOT done here: the onboarding endpoints answer structured
+ * envelopes the page reads; the page owns the copy.
+ */
+export async function onboardingProxy(req: NextRequest, idpPath: string): Promise<NextResponse> {
+  const idpBase = ENV_CONFIG.IDP_URL;
+  if (!idpBase) {
+    return NextResponse.json({ success: false, message: 'IDP_URL is not configured', error: { code: 'NO_IDP_URL' } }, { status: 500 });
+  }
+  const url = `${idpBase}${idpPath}`;
+  assertAbsoluteIdpUrl(url);
+  let bodyText = '{}';
+  try {
+    const raw = await req.text();
+    if (raw && raw.trim().length > 0) bodyText = raw;
+  } catch { /* empty body is fine */ }
+
+  const headers: Record<string, string> = { 'Content-Type': 'application/json', Accept: 'application/json' };
+  const xfwd = req.headers.get('x-forwarded-for') || req.headers.get('x-real-ip');
+  if (xfwd) headers['X-Forwarded-For'] = xfwd;
+  const ua = req.headers.get('user-agent');
+  if (ua) headers['User-Agent'] = ua;
+
+  let res: Response;
+  try {
+    res = await fetch(url, { method: 'POST', headers, body: bodyText, cache: 'no-store' });
+  } catch {
+    return NextResponse.json({ success: false, message: 'The identity service is unreachable.', error: { code: 'UPSTREAM_UNREACHABLE' } }, { status: 502 });
+  }
+  const json = await res.json().catch(() => null);
+  return NextResponse.json(json ?? { success: res.ok }, { status: res.status });
+}

package/src/lib/password-rules.ts

@@ -1,50 +1,50 @@
-/**
- * PAY-1591: the one sentence that states the password rules on the recovery set-password step.
- *
- * Built ONLY from the policy the IdP reported (usePasswordValidation.policy). A rule that is off is not stated, and with
- * no policy at all we state no number: telling a user "at least 8 characters" when the client is configured for 12 is
- * the same defect as saying nothing, one step later.
- */
-export interface PasswordPolicyLike {
-  min_length?: number;
-  require_uppercase?: boolean;
-  require_lowercase?: boolean;
-  require_digit?: boolean;
-  require_special?: boolean;
-}
-
-export function passwordRulesText(policy: PasswordPolicyLike | undefined | null): string {
-  if (!policy || typeof policy.min_length !== 'number') {
-    return "Use a password that meets this site's rules. We'll show what is missing as you type.";
-  }
-  const parts = [`at least ${policy.min_length} characters`];
-  if (policy.require_uppercase) parts.push('an upper-case letter');
-  if (policy.require_lowercase) parts.push('a lower-case letter');
-  if (policy.require_digit) parts.push('a number');
-  if (policy.require_special) parts.push('a symbol');
-  const [first, ...rest] = parts;
-  return rest.length ? `Your password needs ${first}, with ${rest.join(', ')}.` : `Your password needs ${first}.`;
-}
-
-/**
- * PAY-1591: the IdP's reset refusal names WHICH rules failed as codes (error.details.rules). This is the closed set the
- * portal accepts and the one plain sentence for each. Anything outside it is dropped, never displayed or forwarded.
- */
-export const PASSWORD_RULE_SENTENCES: Readonly<Record<string, string>> = {
-  min_length: 'Use a longer password.',
-  uppercase: 'Add an upper-case letter.',
-  lowercase: 'Add a lower-case letter.',
-  digit: 'Add a number.',
-  special: 'Add a symbol.',
-  unique_chars: 'Use more different characters.',
-  recent_password: "Choose a password you haven't used recently.",
-};
-
-export function knownPasswordRules(rules: unknown): string[] {
-  if (!Array.isArray(rules)) return [];
-  return rules.filter((r): r is string => typeof r === 'string' && Object.prototype.hasOwnProperty.call(PASSWORD_RULE_SENTENCES, r));
-}
-
-export function passwordRuleSentences(rules: string[]): string {
-  return rules.map((r) => PASSWORD_RULE_SENTENCES[r]).join(' ');
-}
+/**
+ * PAY-1591: the one sentence that states the password rules on the recovery set-password step.
+ *
+ * Built ONLY from the policy the IdP reported (usePasswordValidation.policy). A rule that is off is not stated, and with
+ * no policy at all we state no number: telling a user "at least 8 characters" when the client is configured for 12 is
+ * the same defect as saying nothing, one step later.
+ */
+export interface PasswordPolicyLike {
+  min_length?: number;
+  require_uppercase?: boolean;
+  require_lowercase?: boolean;
+  require_digit?: boolean;
+  require_special?: boolean;
+}
+
+export function passwordRulesText(policy: PasswordPolicyLike | undefined | null): string {
+  if (!policy || typeof policy.min_length !== 'number') {
+    return "Use a password that meets this site's rules. We'll show what is missing as you type.";
+  }
+  const parts = [`at least ${policy.min_length} characters`];
+  if (policy.require_uppercase) parts.push('an upper-case letter');
+  if (policy.require_lowercase) parts.push('a lower-case letter');
+  if (policy.require_digit) parts.push('a number');
+  if (policy.require_special) parts.push('a symbol');
+  const [first, ...rest] = parts;
+  return rest.length ? `Your password needs ${first}, with ${rest.join(', ')}.` : `Your password needs ${first}.`;
+}
+
+/**
+ * PAY-1591: the IdP's reset refusal names WHICH rules failed as codes (error.details.rules). This is the closed set the
+ * portal accepts and the one plain sentence for each. Anything outside it is dropped, never displayed or forwarded.
+ */
+export const PASSWORD_RULE_SENTENCES: Readonly<Record<string, string>> = {
+  min_length: 'Use a longer password.',
+  uppercase: 'Add an upper-case letter.',
+  lowercase: 'Add a lower-case letter.',
+  digit: 'Add a number.',
+  special: 'Add a symbol.',
+  unique_chars: 'Use more different characters.',
+  recent_password: "Choose a password you haven't used recently.",
+};
+
+export function knownPasswordRules(rules: unknown): string[] {
+  if (!Array.isArray(rules)) return [];
+  return rules.filter((r): r is string => typeof r === 'string' && Object.prototype.hasOwnProperty.call(PASSWORD_RULE_SENTENCES, r));
+}
+
+export function passwordRuleSentences(rules: string[]): string {
+  return rules.map((r) => PASSWORD_RULE_SENTENCES[r]).join(' ');
+}

package/src/lib/rate-limit-service.ts

@@ -1,9 +1,9 @@
-import redis from '../lib/redis';
-import { logger } from '../config/logger';
-
-export interface RateLimitRule { endpoint: string; period: string; limit: number; }
-export interface RateLimitResult { isAllowed: boolean; requestCount: number; limit: number; retryAfterSeconds?: number; failedAttempts?: number; }
-
-export function createPayEzRateLimitResponse(retryAfterSeconds: number, remainingAttempts: number = 0) {
-  return { success: false, message: 'Too many failed attempts', user_info: null, errors: [ { code: 'RateLimitExceeded', message: 'Too many failed authentication attempts', resolution: `Please try again in ${retryAfterSeconds} seconds`, remainingAttempts } ] };
-}
+import redis from '../lib/redis';
+import { logger } from '../config/logger';
+
+export interface RateLimitRule { endpoint: string; period: string; limit: number; }
+export interface RateLimitResult { isAllowed: boolean; requestCount: number; limit: number; retryAfterSeconds?: number; failedAttempts?: number; }
+
+export function createPayEzRateLimitResponse(retryAfterSeconds: number, remainingAttempts: number = 0) {
+  return { success: false, message: 'Too many failed attempts', user_info: null, errors: [ { code: 'RateLimitExceeded', message: 'Too many failed authentication attempts', resolution: `Please try again in ${retryAfterSeconds} seconds`, remainingAttempts } ] };
+}