@payez/next-mvp 4.13.1 → 4.14.0

package/dist/pages/first-enroll/page.js

@@ -0,0 +1,15 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = FirstEnrollPage;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const FirstEnrolPanel_1 = require("../../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.
+ */
+function FirstEnrollPage() {
+    return ((0, jsx_runtime_1.jsxs)("main", { style: { maxWidth: 480, margin: '48px auto', padding: '0 16px' }, children: [(0, jsx_runtime_1.jsx)("h1", { children: "Secure your account" }), (0, jsx_runtime_1.jsx)(FirstEnrolPanel_1.FirstEnrolPanel, {})] }));
+}

package/dist/routes/mfa/first-enrol-confirm.d.ts

@@ -0,0 +1,10 @@
+/**
+ * AUTH-045 first-enrolment: confirm the first authenticator code, clear the enrolment cookie, return the recovery codes. Mints no session.
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/first-enrol/confirm/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/first-enrol-confirm';
+ * ```
+ */
+export { POST_CONFIRM as POST } from '../../api-handlers/mfa/first-enrol';

package/dist/routes/mfa/first-enrol-confirm.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+/**
+ * AUTH-045 first-enrolment: confirm the first authenticator code, clear the enrolment cookie, return the recovery codes. Mints no session.
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/first-enrol/confirm/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/first-enrol-confirm';
+ * ```
+ */
+var first_enrol_1 = require("../../api-handlers/mfa/first-enrol");
+Object.defineProperty(exports, "POST", { enumerable: true, get: function () { return first_enrol_1.POST_CONFIRM; } });

package/dist/routes/mfa/first-enrol-enroll.d.ts

@@ -0,0 +1,10 @@
+/**
+ * AUTH-045 first-enrolment: begin TOTP enrolment for a user the IdP told to enrol (uses ONLY the httpOnly enrolment cookie the credential door parked).
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/first-enrol/enroll/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/first-enrol-enroll';
+ * ```
+ */
+export { POST_ENROLL as POST } from '../../api-handlers/mfa/first-enrol';

package/dist/routes/mfa/first-enrol-enroll.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+/**
+ * AUTH-045 first-enrolment: begin TOTP enrolment for a user the IdP told to enrol (uses ONLY the httpOnly enrolment cookie the credential door parked).
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/first-enrol/enroll/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/first-enrol-enroll';
+ * ```
+ */
+var first_enrol_1 = require("../../api-handlers/mfa/first-enrol");
+Object.defineProperty(exports, "POST", { enumerable: true, get: function () { return first_enrol_1.POST_ENROLL; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.13.1",
+  "version": "4.14.0",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -990,6 +990,16 @@
       "require": "./dist/routes/mfa/totp-confirm.js",
       "default": "./dist/routes/mfa/totp-confirm.js"
     },
+    "./routes/mfa/first-enrol-enroll": {
+      "types": "./dist/routes/mfa/first-enrol-enroll.d.ts",
+      "require": "./dist/routes/mfa/first-enrol-enroll.js",
+      "default": "./dist/routes/mfa/first-enrol-enroll.js"
+    },
+    "./routes/mfa/first-enrol-confirm": {
+      "types": "./dist/routes/mfa/first-enrol-confirm.d.ts",
+      "require": "./dist/routes/mfa/first-enrol-confirm.js",
+      "default": "./dist/routes/mfa/first-enrol-confirm.js"
+    },
     "./routes/mfa/totp-verify": {
       "types": "./dist/routes/mfa/totp-verify.d.ts",
       "require": "./dist/routes/mfa/totp-verify.js",
@@ -1100,6 +1110,11 @@
       "require": "./dist/components/mfa/TotpEnrollPanel.js",
       "default": "./dist/components/mfa/TotpEnrollPanel.js"
     },
+    "./dist/pages/first-enroll": {
+      "types": "./dist/pages/first-enroll/page.d.ts",
+      "require": "./dist/pages/first-enroll/page.js",
+      "default": "./dist/pages/first-enroll/page.js"
+    },
     "./dist/pages/enroll": {
       "types": "./dist/pages/enroll/page.d.ts",
       "require": "./dist/pages/enroll/page.js",

package/src/api-handlers/auth/credential-login.ts

@@ -49,6 +49,8 @@ import { DEVICE_ID_HEADER, isValidDeviceId } from '../../lib/device-id';
 import { classifyTwofaRejection, type TwofaLaneResult } from '../../lib/twofa-rejection';
 import { bearerFetch } from '../../lib/bearer-fetch';
 import { errForLog } from '../../lib/log-safe';
+// AUTH-045: the httpOnly cookie that carries the enrolment-scoped token from the code turn to the two enrolment routes (ONE name, defined in lib/first-enrol).
+import { ENROL_COOKIE, ENROL_COOKIE_MAX_AGE } from '../../lib/first-enrol';
 
 // `export const runtime = 'nodejs'` must be written LITERALLY in the app's route file (Next ignores a re-exported segment config).
 
@@ -348,6 +350,53 @@ export async function POST(req: NextRequest) {
     const vresult = verifyData?.data?.result ?? verifyData?.data ?? verifyData;
     const vAccess: string | undefined = vresult?.access_token;
     const vRefresh: string | undefined = vresult?.refresh_token;
+    // PAY-3083 (AUTH-045): ACCESS WITHOUT REFRESH AT THE CODE TURN IS NOT A FAILURE - IT IS ENROLMENT.
+    //
+    // The IdP withholds the refresh token for a user who has no usable second factor on THIS client.
+    // TOTP enrolment is PER CLIENT (DotNetPert 99446 sec A, client 90717 / user 1175): the password turn
+    // answered Require2FA=true, IssueRefreshToken=false, step=enroll_mfa, and this verify turn then
+    // accepted the emailed code as CONTACT PROOF and issued an ENROLMENT-SCOPED access token, again with
+    // no refresh token. That is exactly what PAY-2798 requires of the IdP - the IdP is RIGHT.
+    //
+    // This branch used to read "access, no refresh" as an incomplete response and answer 502, so the
+    // developer who had just proved their contact was told the server was broken and could never reach
+    // the enrolment page: the 502 the field saw as
+    //   '[ADMIN-LOGIN] verify response missing token { hasAccess: true, hasRefresh: false }'.
+    //
+    // Send them to ENROLMENT instead, in the ONE contract the door and the form already share for it
+    // (PAY-2630): requiresTwoFactor + nextStep 'enroll_mfa'. No session is minted - an enrolment-scoped
+    // token is not a signed-in session - and the token value is NEVER logged nor echoed (BAPert 99521 #2).
+    //
+    // Guard kept: no access token AT ALL (a refresh-only or empty body) is still a broken success and
+    // still 502 below - this widening is only for a genuine access-with-no-refresh answer.
+    if (vAccess && !vRefresh) {
+      const step = vresult?.next_step === 'enroll_mfa' || vresult?.next_step === 'mfa_verify' ? vresult.next_step : 'enroll_mfa';
+      const enrolling = step === 'enroll_mfa';
+      const answer = NextResponse.json(
+        {
+          success: false,
+          requiresTwoFactor: true,
+          acceptedFactors: acceptedFactorsFor('email'),
+          sentVia: null,
+          codeRequested: false,
+          emailSent: false,
+          nextStep: step,
+          // AUTH-045 (walk 14 Nov 2026): requiresTwoFactor alone is also the password turn's "a code was sent", so the form re-drew the code box
+          // and looped. This flag is the ONLY signal that means "go enrol"; it is set on this answer and nowhere else.
+          ...(enrolling ? { enrolmentRequired: true } : {}),
+        },
+        { status: 200 },
+      );
+      if (enrolling) {
+        // No session exists for an enrolment-scoped token, and the enrolment page's actions need one, so the token rides in this httpOnly
+        // cookie to the enrolment routes (the portal's PAY-2798 part 2 pattern): never in a body, a URL or a log; strict; 600 s.
+        answer.cookies.set(ENROL_COOKIE, vAccess, { httpOnly: true, secure: process.env.NODE_ENV === 'production', sameSite: 'strict', path: '/', maxAge: ENROL_COOKIE_MAX_AGE });
+        // The provisional bearer is spent: the enrolment token replaces it.
+        answer.cookies.set('adm2fa', '', { path: '/', maxAge: 0 });
+        answer.cookies.set('adm2fa_lane', '', { path: '/', maxAge: 0 });
+      }
+      return answer;
+    }
     if (!vAccess || !vRefresh) {
       console.error('[ADMIN-LOGIN] verify response missing tokens', { hasAccess: !!vAccess, hasRefresh: !!vRefresh });
       return NextResponse.json({ success: false, error: 'Authentication service returned an incomplete response' }, { status: 502 });

package/src/api-handlers/mfa/first-enrol.ts

@@ -0,0 +1,55 @@
+import { createHash } from 'node:crypto';
+import { NextRequest, NextResponse } from 'next/server';
+import { getIDPClientConfig } from '../../lib/idp-client-config';
+import { resolveClientKey } from '../../lib/client-key';
+import { NO_STORE, refuseNonJson } from '../../lib/mfa-json-guard';
+import { ENROL_COOKIE, LIMIT_PER_COOKIE, attemptAllowed, runEnrolStep, type EnrolStep } from '../../lib/first-enrol';
+
+/**
+ * AUTH-045 first-enrolment carry (PAY-2938, BAPert 100969 rows 3-5): the TWO routes a user the IdP told to enrol uses, built on lib/first-enrol.
+ *
+ * WHO MAY CALL: the browser that holds the httpOnly enrolment cookie the credential door parked (ENROL_COOKIE). This is the ONLY module besides the
+ * door that reads that cookie, and it serves ONLY these two operations; every other package route stays session-gated and answers 401 to a caller
+ * holding nothing but this cookie (a gate row holds that). No cookie -> 401 SIGN_IN_AGAIN and no IdP call.
+ *
+ * What follows a confirm (BAPert 100969 row 5): the cookie is cleared and the answer carries the recovery codes; NO session is minted here and no new
+ * way to mint one is added. The person signs in again with their password and the authenticator, through the same credential door as before.
+ *
+ * The token never leaves the server: not in a body, a URL, a log or a Referer. The IdP's prose is never relayed.
+ */
+const digest = (s: string) => createHash('sha256').update(s).digest('hex');
+
+const cookieOpts = (maxAge: number) => ({ httpOnly: true, secure: process.env.NODE_ENV === 'production', sameSite: 'strict' as const, path: '/', maxAge });
+
+function reply(status: number, body: Record<string, unknown>, clear: boolean): NextResponse {
+  const res = NextResponse.json(body, { status, headers: NO_STORE });
+  if (clear) res.cookies.set(ENROL_COOKIE, '', cookieOpts(0));
+  return res;
+}
+
+export function enrolStepPOST(step: EnrolStep) {
+  return async function POST(req: NextRequest): Promise<NextResponse> {
+    const refused = refuseNonJson(req);
+    if (refused) return refused;
+    const token = req.cookies.get(ENROL_COOKIE)?.value;
+    if (!token) return reply(401, { success: false, code: 'SIGN_IN_AGAIN' }, false);
+    if (!attemptAllowed(`${step}|ck|${digest(token)}`, LIMIT_PER_COOKIE)) return reply(429, { success: false, code: 'TOO_MANY', error: 'Too many attempts. Wait a few minutes and try again.' }, true);
+
+    const idp = process.env.IDP_URL;
+    let clientKey = '';
+    try {
+      const config = await getIDPClientConfig();
+      clientKey = resolveClientKey(config, 'first-enrol').key ?? '';
+    } catch {
+      return reply(503, { success: false, code: 'IDP_CONFIG_UNAVAILABLE' }, false);
+    }
+    if (!idp || !clientKey) return reply(503, { success: false, code: 'IDP_CONFIG_UNAVAILABLE' }, false);
+
+    const body = await req.json().catch(() => null);
+    const r = await runEnrolStep({ fetchImpl: (u, i) => fetch(u, i), idp, clientKey }, { step, token, body });
+    return reply(r.status, r.body, r.cookie === 'clear');
+  };
+}
+
+export const POST_ENROLL = enrolStepPOST('enroll');
+export const POST_CONFIRM = enrolStepPOST('confirm');

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