@payez/next-mvp 4.13.1 → 4.15.0

package/src/auth/better-auth.ts

@@ -27,13 +27,13 @@ import {
   type IdpVerifiedClaims,
 } from './idp-oauth';
 import type { IDPClientConfig } from '../lib/idp-client-config';
-import { getIDPClientConfig } from '../lib/idp-client-config';
+import { getIDPClientConfig, providerSecretEnvVar } from '../lib/idp-client-config';
 import { getAppSlug, assertAppSlugMatchesIdp } from '../lib/app-slug';
 import { getRedis } from '../lib/redis';
 import { createSingleFlight, type SingleFlight } from '../lib/single-flight';
 import { SESSION_TTL } from '../lib/session-store';
 import { tokenLogId } from '../lib/token-log-id';
-import { errForLog } from '../lib/log-safe';
+import { errForLog, logSafeName } from '../lib/log-safe';
 import { warnIfMagicLinkBelowFix } from './better-auth-exposure';
 import { noStore } from '../lib/no-store';
 
@@ -277,6 +277,28 @@ export function buildIdpOAuthProviderConfig(appBaseUrl?: string): IdpOAuthProvid
   };
 }
 
+/**
+ * PAY-3139: the credentials better-auth ITSELF requires before it can build a provider's authorize URL.
+ *
+ * Read from @better-auth/core 1.5.6 (social-providers/*.mjs, createAuthorizationURL): google throws
+ * `BetterAuthError("CLIENT_ID_AND_SECRET_REQUIRED")` when clientId OR clientSecret is empty. That is a plain
+ * throw, not an APIError, so the sign-in door answered a 500 with an EMPTY body (dev-93, 14 Nov: the IdP served
+ * the public, secret-redacted client config, so google's secret arrived empty). apple, facebook and github have
+ * no such guard (facebook signs in by id_token; apple's secret is the IdP's), so only the id is required there:
+ * an empty client id cannot produce a working authorize URL for any provider.
+ *
+ * Returns the missing FIELD NAMES, never a value.
+ */
+export function missingProviderCredentials(
+  name: string,
+  oauth: { clientId?: string | null; clientSecret?: string | null }
+): Array<'clientId' | 'clientSecret'> {
+  const required: Array<'clientId' | 'clientSecret'> =
+    name === 'google' ? ['clientId', 'clientSecret'] : ['clientId'];
+  return required.filter((field) => String(oauth[field] ?? '').trim() === '');
+}
+
+
 export function buildBetterAuthProviders(
   config: IDPClientConfig
 ): Record<string, BetterAuthSocialProvider> {
@@ -285,6 +307,26 @@ export function buildBetterAuthProviders(
   for (const oauth of config.oauthProviders || []) {
     if (!oauth.enabled) continue;
     const name = oauth.provider.toLowerCase();
+
+    /**
+     * PAY-3139: an ENABLED row that lacks a credential better-auth requires is LEFT OUT, loudly. Left in, its
+     * sign-in throws inside better-auth and the door answers an empty 500 that names nothing. Left out, the
+     * same door answers better-auth's typed 404 PROVIDER_NOT_FOUND, and this line names the provider and the
+     * missing field (never a value), once per instance build.
+     */
+    const missing = missingProviderCredentials(name, oauth);
+    if (missing.length > 0) {
+      const secretHint = missing.includes('clientSecret')
+        ? ` (the secret is read env-first from ${providerSecretEnvVar(oauth.provider)}, else from the IdP's ` +
+          `secret-bearing client config, which a client that sends no valid client_secret does not receive)`
+        : '';
+      console.error(
+        `[BETTER_AUTH] PROVIDER_CREDENTIALS_MISSING provider=${logSafeName(name)} missing=${missing.join(',')}: ` +
+          `left out of the sign-in providers, so its sign-in answers PROVIDER_NOT_FOUND until the ` +
+          `${missing.join(' and ')} reach this app${secretHint}`
+      );
+      continue;
+    }
     const additionalParams = oauth.additionalParams ?? {};
     const rawPrompt = additionalParams.prompt;
     const rawAccessType = additionalParams.accessType ?? additionalParams.access_type;

package/src/components/auth/CredentialSignInForm.tsx

@@ -51,6 +51,11 @@ interface Props {
    * default would 404 a generated app's user right after a good sign-in).
    */
   enrollHref?: string;
+  /**
+   * AUTH-045: where a person is sent when the IdP says they must ENROL a factor and they have NO session (the door parked an httpOnly enrolment cookie).
+   * Distinct from enrollHref (which needs a session). NO DEFAULT: without it the form says so instead of redrawing the code box.
+   */
+  firstEnrolHref?: string;
 }
 
 const inputStyle: React.CSSProperties = {
@@ -73,7 +78,7 @@ export function resolveDestination(explicit?: string): string {
   return safeCallbackPath(authorizeResumeHref(returnUrl), safeCallbackPath(raw, '/dashboard'));
 }
 
-export function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPassword = false, enrollHref }: Props) {
+export function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPassword = false, enrollHref, firstEnrolHref }: Props) {
   const [step, setStep] = useState<'credentials' | 'code'>('credentials');
   const [email, setEmail] = useState('');
   const [password, setPassword] = useState('');
@@ -103,6 +108,18 @@ export function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showF
         else window.location.href = destination;
         return;
       }
+      if (r.kind === 'enrol_required') {
+        // AUTH-045: the code was accepted as contact proof; the door parked the enrolment-scoped token in an httpOnly cookie. Go and enrol: never redraw
+        // the code box (the 14 Nov walk looped there). A host that gave no enrolment page gets a sentence, not a silent loop.
+        if (firstEnrolHref) {
+          if (onSignedIn) onSignedIn(firstEnrolHref);
+          else window.location.href = firstEnrolHref;
+          return;
+        }
+        setError('This app has no authenticator setup page, so sign-in cannot continue. Tell the app owner.');
+        setErrorCode('sign_in_failed');
+        return;
+      }
       if (r.kind === 'two_factor') {
         setCodeRequest(r.codeRequest);
         setDevCode(r.devCode);

package/src/components/mfa/FirstEnrolPanel.tsx

@@ -0,0 +1,189 @@
+'use client';
+
+import React, { useEffect, useRef, useState } from 'react';
+import { QrCode } from './QrCode';
+
+/**
+ * AUTH-045 first-enrolment carry (PAY-2938, BAPert 100969): the panel for a person the IdP told to ENROL a factor on THIS app, who has NO session.
+ * Ported from the portal's EnrolRequired (PAY-2798 part 2). It talks ONLY to the two routes that read the httpOnly enrolment cookie:
+ *   POST /api/auth/first-enrol/enroll   (started on mount: the person already asked for this by signing in)
+ *   POST /api/auth/first-enrol/confirm  (the 6-digit code from the app) -> the recovery codes, then "sign in again"
+ *
+ * Rules: the secret and otpauth_uri live in component state only (never a URL, storage, console or a third-party QR service); a 401 is never a
+ * message box (the person is sent back to sign-in); a fixed sentence per refusal code, never the server's text; no session is minted here.
+ */
+
+export const FIRST_ENROL_ENROLL_URL = '/api/auth/first-enrol/enroll';
+export const FIRST_ENROL_CONFIRM_URL = '/api/auth/first-enrol/confirm';
+
+/** BAPert 100969 row 6: one sentence that this app has its own authenticator entry (per-client factor, by design). */
+export const PER_APP_SENTENCE = 'This app has its own authenticator entry: an authenticator you set up for another app or site does not carry over, so you add one here once.';
+export const DONE_SENTENCE = 'Your authenticator is set. Sign in with your password and the code from your app.';
+export const SIGN_IN_AGAIN_SENTENCE = 'This setup timed out or the sign-in expired. Sign in again to continue.';
+
+const REFUSAL_COPY: Record<string, string> = {
+  CODE_INVALID: 'That code did not work. Check the 6 digits in your authenticator app and try again.',
+  TOO_MANY: 'Too many attempts. Wait a few minutes and sign in again.',
+  ENROLMENT_RESTART: 'This setup timed out. Reload the page to get a new code to scan.',
+  UNAVAILABLE: 'We could not reach the sign-in service. Nothing was changed. Try again in a moment.',
+};
+const FALLBACK_COPY = 'Setup was not completed. Try again.';
+
+type Enrollment = { secret: string; otpauth_uri: string; enrollment_id: number };
+type Stage = 'starting' | 'enrolling' | 'done' | 'failed';
+
+const readJson = async (res: Response): Promise<any> => res.json().catch(() => null);
+
+export function FirstEnrolPanel({
+  fetchImpl,
+  signInHref = '/account-auth/login',
+  onSignInAgain,
+}: { fetchImpl?: typeof fetch; signInHref?: string; onSignInAgain?: (href: string) => void } = {}) {
+  const doFetch: typeof fetch = fetchImpl ?? ((...a) => fetch(...a));
+  const [stage, setStage] = useState<Stage>('starting');
+  const [enroll, setEnroll] = useState<Enrollment | null>(null);
+  const [code, setCode] = useState('');
+  const [error, setError] = useState<string | null>(null);
+  const [codes, setCodes] = useState<string[] | null>(null);
+  const [busy, setBusy] = useState(false);
+  const started = useRef(false);
+
+  const toSignIn = () => {
+    if (onSignInAgain) onSignInAgain(signInHref);
+    else window.location.href = signInHref;
+  };
+
+  async function begin() {
+    setBusy(true);
+    setError(null);
+    try {
+      const res = await doFetch(FIRST_ENROL_ENROLL_URL, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ friendly_name: 'This device' }) });
+      if (res.status === 401) return toSignIn(); // a 401 is never a message box
+      const body = await readJson(res);
+      if (res.ok && body?.data?.secret && body?.data?.otpauth_uri && Number.isInteger(body?.data?.enrollment_id)) {
+        setEnroll({ secret: body.data.secret, otpauth_uri: body.data.otpauth_uri, enrollment_id: body.data.enrollment_id });
+        setStage('enrolling');
+        return;
+      }
+      setError(REFUSAL_COPY[body?.code as string] ?? FALLBACK_COPY);
+      setStage('failed');
+    } catch {
+      setError(REFUSAL_COPY.UNAVAILABLE);
+      setStage('failed');
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  useEffect(() => {
+    if (started.current) return;
+    started.current = true;
+    void begin();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  async function confirm() {
+    if (!enroll || !/^\d{6}$/.test(code)) {
+      setError('Enter the 6-digit code from your app.');
+      return;
+    }
+    setBusy(true);
+    setError(null);
+    try {
+      const res = await doFetch(FIRST_ENROL_CONFIRM_URL, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ enrollment_id: enroll.enrollment_id, code }) });
+      if (res.status === 401) return toSignIn();
+      const body = await readJson(res);
+      if (res.ok && body?.confirmed === true) {
+        setEnroll(null);
+        setCode('');
+        setCodes(Array.isArray(body.codes) ? body.codes.filter((c: unknown) => typeof c === 'string') : null);
+        setStage('done');
+        return;
+      }
+      setCode('');
+      setError(REFUSAL_COPY[body?.code as string] ?? FALLBACK_COPY);
+    } catch {
+      setError(REFUSAL_COPY.UNAVAILABLE);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  if (stage === 'done') {
+    return (
+      <div data-testid="first-enrol-done" role="status">
+        <p>{DONE_SENTENCE}</p>
+        {codes && codes.length > 0 ? (
+          <>
+            <p>Save these recovery codes somewhere safe. Each one works once, and they are not shown again.</p>
+            <ul data-testid="first-enrol-codes">
+              {codes.map((c) => (
+                <li key={c}>
+                  <code>{c}</code>
+                </li>
+              ))}
+            </ul>
+          </>
+        ) : (
+          <p data-testid="first-enrol-no-codes">We could not show your recovery codes. You can create new ones after you sign in.</p>
+        )}
+        <p>
+          <a href={signInHref}>Sign in</a>
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div data-testid="first-enrol-panel" style={{ display: 'flex', flexDirection: 'column', gap: 12, alignItems: 'flex-start' }}>
+      <p data-testid="first-enrol-per-app">{PER_APP_SENTENCE}</p>
+      {stage === 'starting' ? <p data-testid="first-enrol-starting">Setting up…</p> : null}
+      {stage === 'enrolling' && enroll ? (
+        <>
+          <p>Open your authenticator app and scan this code. A phone camera works too.</p>
+          <QrCode value={enroll.otpauth_uri} />
+          <div>
+            <div>Can&apos;t scan? Enter this code manually:</div>
+            <code data-testid="first-enrol-secret" style={{ wordBreak: 'break-all' }}>
+              {enroll.secret}
+            </code>
+          </div>
+          <form
+            onSubmit={(e) => {
+              e.preventDefault();
+              void confirm();
+            }}
+          >
+            <label htmlFor="first-enrol-code">Enter the 6-digit code from your app:</label>
+            <br />
+            <input
+              id="first-enrol-code"
+              data-testid="first-enrol-code"
+              inputMode="numeric"
+              autoComplete="one-time-code"
+              maxLength={6}
+              value={code}
+              disabled={busy}
+              onChange={(e) => setCode(e.target.value.replace(/\D/g, '').slice(0, 6))}
+            />{' '}
+            <button type="submit" data-testid="first-enrol-confirm" disabled={busy || code.length !== 6}>
+              Confirm
+            </button>
+          </form>
+        </>
+      ) : null}
+      {error ? (
+        <p role="alert" data-testid="first-enrol-error">
+          {error}
+        </p>
+      ) : null}
+      {stage === 'failed' ? (
+        <p>
+          <a href={signInHref}>Sign in again</a>
+        </p>
+      ) : null}
+    </div>
+  );
+}
+
+export default FirstEnrolPanel;

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

@@ -24,6 +24,8 @@ export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>
 export type CredentialSignInResult =
   | { kind: 'success' }
   | { kind: 'two_factor'; codeRequest: CodeRequest; devCode: string | null; nextStep: NextStep }
+  /** AUTH-045: the code was accepted as contact proof and the IdP says this user must ENROL a factor on this client. Its own state, so it can never be drawn as the code box. */
+  | { kind: 'enrol_required' }
   | { kind: 'rate_limited'; message: string; code: ErrorCode }
   | { kind: 'error'; message: string; code: ErrorCode; offerEmailCode: boolean };
 
@@ -104,7 +106,17 @@ export async function credentialSignIn(
       const code = body?.code === 'second_factor_rate_limited' ? 'second_factor_rate_limited' : 'too_many_attempts';
       return { kind: 'rate_limited', message: tooManyAttemptsMessage(body?.retryAfter, code), code };
     }
-    if (body?.requiresTwoFactor) return { kind: 'two_factor', codeRequest: readCodeRequest(body), devCode: readDevCode(body), nextStep: readNextStep(body) };
+    if (body?.requiresTwoFactor) {
+      // AUTH-045 (BAPert 100969 rows 1-2): requiresTwoFactor alone cannot mean "go enrol" (it is also the password turn's "a code was sent"); the walk of
+      // 14 Nov showed the form redrawing the code box forever. The door's enrolmentRequired flag is the only signal for enrolment, and anything the
+      // client does not understand is a VISIBLE error, never a redraw.
+      const raw = body?.nextStep;
+      const unexpected: CredentialSignInResult = { kind: 'error', message: MSG_UNEXPECTED, code: 'sign_in_failed', offerEmailCode: false };
+      if (body?.enrolmentRequired === true) return raw === 'enroll_mfa' ? { kind: 'enrol_required' } : unexpected;
+      if (raw !== undefined && raw !== null && raw !== 'enroll_mfa' && raw !== 'mfa_verify') return unexpected;
+      if (args.code && raw === 'enroll_mfa') return unexpected; // a CODE turn told "enrol" without the flag is an older door: never a redraw
+      return { kind: 'two_factor', codeRequest: readCodeRequest(body), devCode: readDevCode(body), nextStep: readNextStep(body) };
+    }
     if (!res.ok || body?.success !== true) {
       const offerEmailCode = body?.offerEmailCode === true;
       if (isSignInFailureCode(body?.code)) return { kind: 'error', message: signInFailureMessage(body.code) as string, code: body.code, offerEmailCode };

package/src/lib/first-enrol.ts

@@ -0,0 +1,180 @@
+/**
+ * AUTH-045 first-enrolment carry (PAY-2938, BAPert 100969): the server logic of the two enrolment calls a generated app makes for a user the IdP told
+ * to ENROL a factor on this client. Ported from VibeID-Customer-Portal PAY-2798 part 2 (src/lib/auth/enrol-core.ts + enrol-required.ts at a9ab685c);
+ * the pattern is not redesigned.
+ *
+ * WHY IT EXISTS. The credential door (api-handlers/auth/credential-login) answers an enrolment-scoped token (access, NO refresh) with the enrolment
+ * answer and mints NO session, so the package's session-gated MFA routes cannot serve this user. The door parks that token in an httpOnly cookie
+ * (ENROL_COOKIE); the two routes built on this module read ONLY that cookie, and ONLY for these two operations. No other route reads it.
+ *
+ * Rules held here (each has a row in test/first-enrol-core.test.cjs): the scoped token and the full pair a confirm answers NEVER appear in a returned
+ * body; the IdP's prose is never relayed; nothing is logged; the confirm body is a whitelist; the recovery codes are fetched with the confirm's full
+ * pair SERVER-SIDE ONLY and that pair is then dropped (this module mints no session: what follows is the sign-in the person already knows).
+ *
+ * No framework imports: a test runs it with a stubbed fetch.
+ */
+
+export const ENROL_COOKIE = 'payez_enrol';
+export const ENROL_COOKIE_MAX_AGE = 600;
+export type EnrolStep = 'enroll' | 'confirm';
+export const ENROL_STEPS: readonly EnrolStep[] = ['enroll', 'confirm'];
+
+export type Fetcher = (url: string, init: RequestInit & { headers: Record<string, string> }) => Promise<Response>;
+export type CoreDeps = { fetchImpl: Fetcher; idp: string; clientKey: string };
+/** `cookie`: what the route does with the enrolment cookie. */
+export type CoreResult = { status: number; body: Record<string, unknown>; cookie: 'clear' | 'keep' };
+
+const SENTENCE_UNAVAILABLE = 'We could not reach the sign-in service. Nothing was changed. Try again in a moment.';
+
+export function enrolIdpPath(step: EnrolStep): string {
+  return step === 'enroll' ? '/api/Account/mfa/totp/enroll' : '/api/Account/mfa/totp/confirm';
+}
+
+/** The body each step may carry: enroll { friendly_name? }, confirm { enrollment_id, code }. null = nothing is sent. */
+export function enrolBodyFor(step: EnrolStep, raw: unknown): Record<string, unknown> | null {
+  const src = raw && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {};
+  if (step === 'enroll') {
+    const n = src.friendly_name;
+    return typeof n === 'string' && n.trim() !== '' && n.length <= 64 ? { friendly_name: n.trim() } : {};
+  }
+  const id = src.enrollment_id;
+  const code = src.code;
+  if (typeof id !== 'number' || !Number.isInteger(id) || id <= 0) return null;
+  if (typeof code !== 'string' || !/^\d{6}$/.test(code)) return null;
+  return { enrollment_id: id, code };
+}
+
+const unwrap = (b: unknown): Record<string, unknown> | null => {
+  if (!b || typeof b !== 'object' || Array.isArray(b)) return null;
+  const o = b as Record<string, unknown>;
+  return o.data && typeof o.data === 'object' && !Array.isArray(o.data) ? (o.data as Record<string, unknown>) : o;
+};
+const str = (v: unknown) => (typeof v === 'string' && v !== '' ? v : null);
+
+export function parseEnrol(body: unknown): { secret: string; otpauthUri: string; enrollmentId: number } | null {
+  const d = unwrap(body);
+  const secret = str(d?.secret);
+  const uri = str(d?.otpauth_uri);
+  const id = d?.enrollment_id;
+  if (!d || !secret || !uri || !uri.startsWith('otpauth://totp/') || typeof id !== 'number' || !Number.isInteger(id)) return null;
+  return { secret, otpauthUri: uri, enrollmentId: id };
+}
+
+export function parseConfirmed(body: unknown): boolean {
+  return unwrap(body)?.confirmed === true;
+}
+
+export function parseCodes(body: unknown): string[] | null {
+  const d = unwrap(body);
+  const codes = d?.codes;
+  if (!Array.isArray(codes) || codes.length === 0 || !codes.every((c) => typeof c === 'string' && c !== '')) return null;
+  return codes as string[];
+}
+
+export function codesForDisplay(codes: readonly string[]): string[] {
+  return codes.map((c) => c.trim()).filter((c) => c !== '');
+}
+
+/** What a person reads for a failed enrol / confirm call (never the server's text). 'sign-in' = 401/403: the page goes to sign-in, never a message box. */
+export function enrolRefusal(step: EnrolStep, status: number, body: unknown): { status: number; code: string; text: string } | 'sign-in' {
+  if (status === 401 || status === 403) return 'sign-in';
+  const c = (() => {
+    const b = body as { code?: unknown; error?: { code?: unknown } | string } | null;
+    if (b && typeof b.code === 'string') return b.code;
+    if (b && typeof b.error === 'object' && b.error && typeof (b.error as { code?: unknown }).code === 'string') return (b.error as { code: string }).code;
+    return null;
+  })();
+  if (status === 429) return { status: 429, code: 'TOO_MANY', text: 'Too many attempts. Wait a few minutes and try again.' };
+  if (step === 'confirm' && status >= 400 && status < 500) {
+    if (c === 'enrollment_not_found') return { status: 400, code: 'ENROLMENT_RESTART', text: 'This setup timed out. Reload the page to get a new code to scan.' };
+    return { status: 400, code: 'CODE_INVALID', text: 'That code did not work. Check the 6 digits in your authenticator app and try again.' };
+  }
+  return { status: 502, code: 'UNAVAILABLE', text: SENTENCE_UNAVAILABLE };
+}
+
+const headers = (token: string, clientKey: string): Record<string, string> => ({
+  'Content-Type': 'application/json',
+  Accept: 'application/json',
+  Authorization: `Bearer ${token}`,
+  'X-Client-Id': clientKey,
+});
+const asJson = async (res: Response) => res.json().catch(() => null);
+
+export async function runEnrolStep(deps: CoreDeps, input: { step: EnrolStep; token: string; body: unknown }): Promise<CoreResult> {
+  const body = enrolBodyFor(input.step, input.body);
+  if (body === null) return { status: 400, body: { success: false, code: 'INVALID_REQUEST' }, cookie: 'keep' };
+
+  let res: Response;
+  try {
+    res = await deps.fetchImpl(`${deps.idp}${enrolIdpPath(input.step)}`, {
+      method: 'POST',
+      headers: headers(input.token, deps.clientKey),
+      body: JSON.stringify(body),
+      cache: 'no-store',
+    });
+  } catch {
+    return { status: 502, body: { success: false, code: 'UNAVAILABLE', error: SENTENCE_UNAVAILABLE }, cookie: 'keep' };
+  }
+  const answer = await asJson(res);
+
+  if (res.status < 200 || res.status >= 300) {
+    const refusal = enrolRefusal(input.step, res.status, answer);
+    if (refusal === 'sign-in') return { status: 401, body: { success: false, code: 'SIGN_IN_AGAIN' }, cookie: 'clear' };
+    // A mistyped code must not cost a whole sign-in (the attempt limit bounds it); every other refusal ends this enrolment.
+    return { status: refusal.status, body: { success: false, code: refusal.code, error: refusal.text }, cookie: refusal.code === 'CODE_INVALID' ? 'keep' : 'clear' };
+  }
+
+  if (input.step === 'enroll') {
+    const e = parseEnrol(answer);
+    if (!e) return { status: 502, body: { success: false, code: 'UNAVAILABLE', error: 'We could not read the setup details. Nothing was changed. Reload the page.' }, cookie: 'clear' };
+    return { status: 200, body: { success: true, data: { secret: e.secret, otpauth_uri: e.otpauthUri, enrollment_id: e.enrollmentId } }, cookie: 'keep' };
+  }
+
+  // confirm: the factor is confirmed; the answer carries the FULL pair, used here ONLY to fetch the recovery codes, then dropped.
+  if (!parseConfirmed(answer)) return { status: 502, body: { success: false, code: 'UNAVAILABLE', error: 'We could not confirm that. Try the code again.' }, cookie: 'keep' };
+  const d = unwrap(answer);
+  const full = str(d?.access_token);
+  let codes: string[] | null = null;
+  if (full) {
+    try {
+      const c = await deps.fetchImpl(`${deps.idp}/api/Account/mfa/backup-codes`, { method: 'POST', headers: headers(full, deps.clientKey), body: '{}', cache: 'no-store' });
+      const list = c.ok ? parseCodes(await asJson(c)) : null;
+      codes = list ? codesForDisplay(list) : null;
+    } catch {
+      codes = null;
+    }
+  }
+  return { status: 200, body: { success: true, confirmed: true, codes }, cookie: 'clear' };
+}
+
+// ── attempt limit: per enrolment cookie (in-memory, per instance), hard-capped ──
+const WINDOW_MS = ENROL_COOKIE_MAX_AGE * 1000;
+export const LIMIT_PER_COOKIE = 5;
+const hits = new Map<string, number[]>();
+/**
+ * HARD CAP (portal PAY-2913, BAPert 90048): the map never holds more than this many keys; past it the OLDEST-TOUCHED key is evicted.
+ * KNOWN TRADE: a flood of forged cookies can push a real caller's counter out and reset its budget; bounded by this cap and by the IdP's own throttle.
+ * Not ported from the portal: the per-IP limit (it needs the trusted-proxy setting, PORTAL_TRUSTED_PROXY_HOPS, which a generated app does not have).
+ */
+export const MAX_TRACKED_KEYS = 5000;
+
+/** True when this key may attempt now; records the attempt. Keys are never the raw cookie (the route passes a digest). */
+export function attemptAllowed(key: string, limit: number, now: number = Date.now()): boolean {
+  const recent = (hits.get(key) ?? []).filter((t) => now - t < WINDOW_MS);
+  const allowed = recent.length < limit;
+  if (allowed) recent.push(now);
+  hits.delete(key); // re-insert at the end: Map order is last-touched order
+  hits.set(key, recent);
+  while (hits.size > MAX_TRACKED_KEYS) {
+    const oldest = hits.keys().next().value;
+    if (oldest === undefined) break;
+    hits.delete(oldest);
+  }
+  return allowed;
+}
+export function _resetAttempts(): void {
+  hits.clear();
+}
+export function _trackedKeys(): number {
+  return hits.size;
+}

package/src/lib/idp-client-config.ts

@@ -44,7 +44,7 @@ import 'server-only';
 import { createHash, randomUUID } from 'crypto';
 import { markNeverInResponse } from './never-in-response';
 import { clientSecretBody, warnIfProviderSecretRedacted } from './payez-client-secret';
-import { errForLog } from './log-safe';
+import { errForLog, logSafeName } from './log-safe';
 // REDIS IS IMPORTED LAZILY, AND THAT IS LOAD-BEARING.
 // A module-scope `import redis from './redis'` drags ioredis into EVERY bundle that
 // touches this file - including instrumentation.ts. Next compiles the instrumentation
@@ -225,7 +225,7 @@ function applyEnvSecrets(config: IDPClientConfig): IDPClientConfig {
             const envVar = providerSecretEnvVar(p.provider);
             const fromEnv = process.env[envVar];
             const source: SecretSource = fromEnv ? `env:${envVar}` : p.clientSecret ? 'idp-config' : 'none';
-            logSecretSource(`${p.provider} clientSecret`, source);
+            logSecretSource(`${logSafeName(p.provider)} clientSecret`, source);
             const clientSecret = fromEnv || p.clientSecret;
             markNeverInResponse(clientSecret);
             return { ...p, clientSecret };

package/src/lib/log-safe.ts

@@ -28,3 +28,12 @@ export function errForLog(err: unknown): string {
   const code = closed ? ` code=${closed}` : '';
   return `error=${name}${status}${code}`;
 }
+
+/**
+ * A provider name (or any other IdP-supplied identifier) for a log line: lower-cased, then anything outside [a-z0-9_-] becomes '?',
+ * so a name carrying a newline cannot forge a second log line (Nextpert-Scout 102543 LOW 1; the shared helper per 104626, used at
+ * every site that logs an IdP provider name: better-auth.ts, payez-client-secret.ts, idp-client-config.ts).
+ */
+export function logSafeName(name: unknown): string {
+  return String(name ?? '').toLowerCase().replace(/[^a-z0-9_-]/g, '?');
+}

package/src/lib/payez-client-secret.ts

@@ -5,6 +5,7 @@
  * what it sent before. The value is never logged and never leaves in a response (markNeverInResponse).
  */
 import { markNeverInResponse } from './never-in-response';
+import { logSafeName } from './log-safe';
 
 export const CLIENT_SECRET_ENV = 'PAYEZ_CLIENT_SECRET';
 
@@ -34,6 +35,6 @@ export function warnIfProviderSecretRedacted(
         if (process.env[envVarFor(p.provider)]) continue;
         if (warnedProviders.has(p.provider)) continue;
         warnedProviders.add(p.provider);
-        console.warn(`[IDP_CONFIG] PAYEZ_PROVIDER_SECRET_MISSING_REDACTED provider=${p.provider}`);
+        console.warn(`[IDP_CONFIG] PAYEZ_PROVIDER_SECRET_MISSING_REDACTED provider=${logSafeName(p.provider)}`);
     }
 }

package/src/lib/token-pages-switch.ts

@@ -0,0 +1,44 @@
+/**
+ * PAY-3220 (ruled Win 105653 s1, on NextPert-MB's Mac 105619): the ONE production switch for the two token-showing
+ * test-env pages (JwtInspectPage, RefreshTokenPage) and the route the refresh page drives (POST /api/test/force-expire).
+ *
+ *   PAYEZ_TOKEN_PAGES_OFF   unset or empty            -> ON  (every page works as today; the default everywhere)
+ *                           true / 1 / yes / on       -> OFF (any letter case)
+ *                           false / 0 / no / off      -> ON  (any letter case), no warning
+ *                           anything else             -> OFF, and ONE warning per process naming the variable
+ *
+ * Why an unrecognised value is OFF (the ruling's one change to the recommendation): nobody sets this variable except to
+ * turn the pages off, on Jon's word, on a production host. A mistyped attempt to turn them off must not leave
+ * token-showing pages on in production with only a log line to say so.
+ *
+ * Read from the server's process environment on every call, never captured at module scope (a module constant would be
+ * whatever the build host had). It is not NEXT_PUBLIC_, so it never reaches a client bundle, and no request input
+ * (cookie, header, query string, body, session) is consulted: only whoever can change the host's environment can turn it.
+ *
+ * Set ONLY on a production host, ONLY on Jon's word, on the day production is real. It is never in a tracked .env file.
+ * The switch is not counted as set until the production roll's served check reads both pages and force-expire back as
+ * 404 by request (BAPert-MB 105629 s3).
+ */
+export const TOKEN_PAGES_OFF_ENV = 'PAYEZ_TOKEN_PAGES_OFF';
+
+const OFF_WORDS = new Set(['true', '1', 'yes', 'on']);
+const ON_WORDS = new Set(['false', '0', 'no', 'off']);
+let warnedUnrecognised = false;
+
+export function tokenPagesOff(): boolean {
+  const raw = process.env[TOKEN_PAGES_OFF_ENV];
+  if (raw === undefined) return false;
+  const value = raw.trim().toLowerCase();
+  if (value === '') return false;
+  if (OFF_WORDS.has(value)) return true;
+  if (ON_WORDS.has(value)) return false;
+  if (!warnedUnrecognised) {
+    warnedUnrecognised = true;
+    // The variable's NAME only. The value is not a secret, but nothing about it helps the reader of this line.
+    console.warn(
+      `[test-env] ${TOKEN_PAGES_OFF_ENV} is set to a value that is not recognised (true/1/yes/on or false/0/no/off); ` +
+        'the token pages are OFF: jwt-inspect, refresh-token and POST /api/test/force-expire answer 404.',
+    );
+  }
+  return true;
+}

package/src/pages/first-enroll/page.tsx

@@ -0,0 +1,19 @@
+'use client';
+
+import React from 'react';
+import { FirstEnrolPanel } from '../../components/mfa/FirstEnrolPanel';
+
+/**
+ * AUTH-045 (PAY-2938): /account-auth/first-enroll in a generated app, the page a person is sent to when the IdP says they must enrol an authenticator
+ * on this app and they have NO session yet. The page SHELL is public (every /account-auth/* path is public by default); the two routes behind it read
+ * ONLY the httpOnly enrolment cookie the credential door parked, and answer 401 without it (the panel then sends the person to sign-in).
+ * Not the signed-in enrolment page (/account-auth/enroll), which needs a session.
+ */
+export default function FirstEnrollPage() {
+  return (
+    <main style={{ maxWidth: 480, margin: '48px auto', padding: '0 16px' }}>
+      <h1>Secure your account</h1>
+      <FirstEnrolPanel />
+    </main>
+  );
+}