@payez/next-mvp 4.13.0 → 4.14.0

package/src/auth/better-auth-exposure.ts

@@ -0,0 +1,69 @@
+/**
+ * PAY-2592 slice 1: the exposure guard for better-auth GHSA-965c-763c-88jm (critical, CVSS 9.1; affected >=1.4.0-beta.18 <1.7.7).
+ *
+ * "OAuth state can be used as a Magic Link to sign in as another user." It needs ALL of: the Magic Link plugin enabled, an OAuth provider, and OAuth state
+ * stored with `account.storeStateStrategy: "database"` (better-auth's default when a database OR secondaryStorage exists). This package has secondaryStorage,
+ * so what keeps it unexposed is, today:
+ *   1. `account.storeStateStrategy: 'cookie'` is pinned in better-auth.ts (the advisory: cookie-backed state blocks the path), and
+ *   2. the magic-link plugin registers ONLY when a consumer passes `opts.magicLink`.
+ * Nothing in this package fixes the flaw; the fix is better-auth >= 1.7.7 (PAY-2592, spike pending). Until then a consumer that turns the plugin on is told, loudly,
+ * once per process.
+ *
+ * test/next-mvp-pay-2592-exposure-pins.test.cjs holds both conditions and this warning.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const MAGIC_LINK_ADVISORY = 'GHSA-965c-763c-88jm';
+export const MAGIC_LINK_FIX_VERSION = '1.7.7';
+
+/** The installed better-auth version, read from its own package.json (the package does not export './package.json'), or null when it cannot be found. */
+export function installedBetterAuthVersion(): string | null {
+  try {
+    let dir = dirname(require.resolve('better-auth'));
+    for (let i = 0; i < 8; i++) {
+      try {
+        const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { name?: string; version?: string };
+        if (pkg.name === 'better-auth' && typeof pkg.version === 'string') return pkg.version;
+      } catch {
+        /* no package.json at this level */
+      }
+      const up = dirname(dir);
+      if (up === dir) break;
+      dir = up;
+    }
+  } catch {
+    /* unresolvable */
+  }
+  return null;
+}
+
+/** True when `version` is strictly below `floor` (numeric major.minor.patch; a pre-release suffix is ignored). An unparseable version is NOT proven fixed, so it counts as below. */
+export function versionBelow(version: string | null, floor: string): boolean {
+  const parse = (v: string) => /^(\d+)\.(\d+)\.(\d+)/.exec(v)?.slice(1, 4).map(Number) ?? null;
+  const a = version ? parse(version) : null;
+  const b = parse(floor);
+  if (!a || !b) return true;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] < b[i];
+  }
+  return false;
+}
+
+/**
+ * Warn when the magic-link plugin is enabled on a better-auth below the fix. Returns whether it warned (so a test can assert it). `warn` and `version` are
+ * injectable for the same reason.
+ */
+export function warnIfMagicLinkBelowFix(
+  magicLinkEnabled: boolean,
+  warn: (msg: string) => void = (m) => console.warn(m),
+  version: string | null = installedBetterAuthVersion(),
+): boolean {
+  if (!magicLinkEnabled) return false;
+  if (!versionBelow(version, MAGIC_LINK_FIX_VERSION)) return false;
+  warn(
+    `[BETTER_AUTH] WARNING ${MAGIC_LINK_ADVISORY} (critical): the magic-link plugin is enabled on better-auth ${version ?? '(version unknown)'}, below the fix ${MAGIC_LINK_FIX_VERSION}. ` +
+      `This package keeps account.storeStateStrategy='cookie', which blocks the attack; do NOT change that while magic link is on, and upgrade better-auth (PAY-2592).`,
+  );
+  return true;
+}

package/src/auth/better-auth.ts

@@ -34,6 +34,11 @@ 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 { warnIfMagicLinkBelowFix } from './better-auth-exposure';
+import { noStore } from '../lib/no-store';
+
+/** PAY-2592: the magic-link advisory warning fires once per process. */
+let magicLinkAdvisoryWarned = false;
 
 /**
  * 185121: short sha256 fingerprint for secrets/tokens in log lines — enough
@@ -589,6 +594,13 @@ export function createBetterAuthInstance(
   assertAppSlugMatchesIdp(idpConfig.clientSlug);
   const appSlug = idpConfig.clientSlug || getAppSlug();
 
+  // PAY-2592 (GHSA-965c-763c-88jm): a consumer that enables the magic-link plugin on a better-auth below 1.7.7 is told, once per process. What keeps the
+  // package unexposed is account.storeStateStrategy='cookie' below plus the plugin being opt-in; see better-auth-exposure.ts.
+  if (opts.magicLink && !magicLinkAdvisoryWarned) {
+    magicLinkAdvisoryWarned = true;
+    warnIfMagicLinkBelowFix(true);
+  }
+
   // 185121 line 1: name the secret this instance PINNED, as a hash, never the
   // secret. 183047's surviving fork is HMAC-fail vs record-miss; an HMAC-fail
   // caused by a divergent secret is only diagnosable if every instance
@@ -1596,7 +1608,7 @@ export function authErrorCodeFromLocation(location: string): string | null {
  * ```
  */
 export function createAuthGetHandler(loginPath: string = '/account-auth/login') {
-  return async function GET(request: Request): Promise<Response> {
+  const get = async function GET(request: Request): Promise<Response> {
     // Card 138635: establish the request-scoped carrier for the provider's raw
     // id_token. It must wrap BOTH ba.GET (which invokes getUserInfo, the only
     // hook that sees the token) and the exchange below (which forwards it).
@@ -1711,4 +1723,6 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
     return response;
     });
   };
+  // PAY-2994: every Better Auth GET answer (session, OAuth callbacks, redirects) is per-user and may set cookies; never cached.
+  return noStore(get);
 }

package/src/auth/route-config.ts

@@ -92,6 +92,15 @@ const defaultUnauthenticatedRoutes: UnauthenticatedRouteConfig[] = [
     allowDuringCircuitBreakerOpen: true,
     requiresRateLimit: false
   },
+  {
+    // PAY-2804: the exact path. '/api/health/*' matches startsWith('/api/health/'), which the bare
+    // '/api/health' (the ALB check) does not, so without this entry it sat behind sign-in.
+    pattern: '/api/health',
+    description: 'Health check endpoint (ALB target; anonymous, state only)',
+    allowDuringCircuitBreakerOpen: true,
+    // An ALB check comes from few IPs: a rate limit here would answer 429 and get tasks pulled (NightHawk 89179).
+    requiresRateLimit: false
+  },
   {
     pattern: '/api/health/*',
     description: 'Health check endpoints',

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/no-store.ts

@@ -0,0 +1,30 @@
+/**
+ * Cache-Control: no-store for GET routes whose answer carries a person's, a tenant's or a session's data (PAY-2994).
+ *
+ * WHY: the portal's BFF no-store ratchet (testing/qa/bff-no-store-ratchet.js) found 8 GET routes re-exported from this package that sent no
+ * Cache-Control. Their answers carry per-user data and some carry tokens, so a browser or an intermediate cache must never keep them.
+ *
+ * `noStore(handler)` wraps a route handler and sets `Cache-Control: no-store` on EVERY response it returns (errors and redirects too: nothing
+ * a session route says is worth caching). It REPLACES an existing Cache-Control, never merges, so a looser value cannot survive. A Response
+ * whose headers are immutable (a fetch() result, Response.redirect()) is rebuilt with the same status, body and headers (Set-Cookie kept).
+ */
+export const NO_STORE_VALUE = 'no-store';
+
+export function withNoStoreHeader(res: Response): Response {
+  // Not a Response (no headers object): hand it back untouched. A Next route always returns a Response, so this only keeps a hand-made
+  // test double from being turned into an empty Response.
+  if (!res || typeof res !== 'object' || !(res as { headers?: unknown }).headers) return res;
+  try {
+    res.headers.set('Cache-Control', NO_STORE_VALUE);
+    return res;
+  } catch {
+    // Immutable headers (TypeError). Rebuild: same status, statusText, body and every header; Headers copies Set-Cookie entries intact.
+    const headers = new Headers(res.headers);
+    headers.set('Cache-Control', NO_STORE_VALUE);
+    return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+  }
+}
+
+export function noStore<A extends unknown[], R extends Response>(handler: (...args: A) => R | Promise<R>): (...args: A) => Promise<Response> {
+  return async (...args: A) => withNoStoreHeader(await handler(...args));
+}

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>
+  );
+}

package/src/routes/auth/session.ts

@@ -13,6 +13,7 @@
  * @since auth-ready-v2
  */
 
+import { noStore } from '../../lib/no-store';
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession as getBetterAuthSession } from '../../server/auth';
 import { getSession as getRedisSession, updateSession } from '../../lib/session-store';
@@ -27,7 +28,7 @@ import { tokenLogId } from '../../lib/token-log-id';
  * - Token expiry status
  * - Session validity
  */
-export async function GET(req: NextRequest) {
+async function getHandler(req: NextRequest) {
   try {
     const authSession = await getBetterAuthSession(req);
 
@@ -121,6 +122,9 @@ export async function GET(req: NextRequest) {
   }
 }
 
+/** PAY-2994: session state is per-user and some answers carry tokens; never cached (noStore). */
+export const GET = noStore(getHandler);
+
 /**
  * The fields this route USED to accept from the request body and must never accept
  * again. Cards 308833 (critical) / 312092 (remediation spec) / 318272 / 311425.