@payez/next-mvp 4.13.1 → 4.14.0

package/CHANGELOG.md

@@ -1,6 +1,15 @@
 # Changelog — @payez/next-mvp
 
-## Unreleased
+## 4.14.0 (to be published under dist-tag `next` only, after 4.13.1; `latest` stays 4.8.9 until Jon says otherwise)
+
+A minor: additive exports, plus one behaviour change in the generated-app credential sign-in (listed first). Built from GitHub `keelsecurity/keelauth-next` main `33c188e0`; this release commit changes only this file and the version. Consumers keep their own pins.
+
+- **CHANGE (PAY-3083 / PAY-2938, AUTH-045): a first sign-in on an app with no authenticator now reaches enrolment instead of failing.** When the second-factor step answers with an access token and no refresh token, `api-handlers/auth/credential-login` no longer answers 502. It answers 200 in both cases below, never mints a session, and never echoes or logs the token. **(1) The IdP says `next_step: 'enroll_mfa'` (the enrolment-scoped answer after a verified email code, and the default when the IdP names no step):** the answer is `{ success: false, requiresTwoFactor: true, nextStep: 'enroll_mfa', enrolmentRequired: true }`, parks the token in an httpOnly cookie `payez_enrol` (SameSite=Strict, path `/`, 600 s) that only the two new routes below read; it expires the `adm2fa` and `adm2fa_lane` cookies. **(2) The IdP says `next_step: 'mfa_verify'`:** the answer passes that step through as `nextStep: 'mfa_verify'` with NO `enrolmentRequired` flag, NO `payez_enrol` cookie, and the `adm2fa` and `adm2fa_lane` cookies are left in place (the sign-in form continues at the code step). A refresh-only or empty success is still a 502. TOTP enrolment is per client (per app), by design.
+- **ADDITIVE: new exports** `./routes/mfa/first-enrol-enroll` and `./routes/mfa/first-enrol-confirm` (POST routes that read ONLY the `payez_enrol` cookie, accept JSON only, answer 401 `SIGN_IN_AGAIN` with no cookie, allow 5 attempts per cookie (the 6th is 429 and clears it), and on confirm return the recovery codes and clear the cookie; no session is minted), and `./dist/pages/first-enroll` (the page: QR, the key as selectable text under "Enter this code manually:", a sentence saying the authenticator is for this app only, the recovery codes, then "sign in again").
+- **ADDITIVE: `CredentialSignInForm` takes an optional `firstEnrolHref`**, and `credential-sign-in-client` has a new result kind `enrol_required` (returned only when the answer carries `enrolmentRequired: true` with `nextStep: 'enroll_mfa'`). With the prop set the form navigates there; **without it the form shows "This app has no authenticator setup page, so sign-in cannot continue. Tell the app owner." and does not loop.** A consumer that does not adopt it sees that sentence instead of the old silent loop. Generated apps from `@payez/cli` mount the routes and page and pass the prop (CLI release follows this one).
+- Tests: `test/credential-login.test.cjs`, `credential-sign-in-client.test.cjs`, `first-enrol-core.test.cjs`, `first-enrol-routes.test.cjs`, `first-enrol-panel.test.cjs` (with in-memory mutants, `test/lib/compile-mutant.cjs`).
+
+**Also in this release (additive, BAPert 88395/88454):**
 
 - **ADDITIVE (MINOR when released): SMS-first sign-up learns the `EMAIL_CONFIRMATION_REQUIRED` step (BAPert 88395 #2, 88454 #3; NextPert 88471).** The server (door 3b) now answers `verify-sms-code` with 200 success, `next_step = EMAIL_CONFIRMATION_REQUIRED` and NO reset token when the email is still unconfirmed. Before this, `accountApi.verifyOnboardingSmsCode` returned `{ success: true, resetToken: '' }` for that answer, which a consumer reads as "verified" and then calls set-password with an EMPTY token. Now: (a) the result type is the exported `SmsCodeVerification` and gains an OPTIONAL `nextStep` (`nextStep` ALONE is read from the nested shapes AND from a flat body; `reset_token`, `email` and `client_key` are still read from the nested shapes only, as before, so a consumer behind a proxy that forwards a flat body gets no token and the helper then says `more_steps`, the safe direction; absent / null / '' = no step; any other value, including `false`, `0` and a non-string, is kept as a non-empty UNRECOGNISED string, never dropped, so a server that means "no step" must send nothing or null); (b) new pure `interpretSmsVerification(result)` returns `verified` (only with a non-empty reset token and no step), `email_confirmation_required` (the package sentence "Your phone is verified. Confirm your email to finish signing up.", no error styling), `more_steps` ("One more step is needed to finish signing up." for ANY other step, and for success with an empty reset token) or `not_verified`; `success: false` WINS over any step (`not_verified`, so a failed answer never says "Your phone is verified"), and for every other answer it tests `nextStep` BEFORE the token; the sentences are the package's own, never the server's text. **The method itself still returns the server's `success` unchanged: a consumer MUST use `interpretSmsVerification` (or test `nextStep` first) and must not treat `success` alone as "verified", because `success: true` with an empty `resetToken` is what the server now sends for the unconfirmed-email case.** No breaking type change: a consumer that ignores `nextStep` compiles unchanged (test S6), and the email variant `verifyOnboardingCode` is untouched. **A consumer must adopt `interpretSmsVerification` (or branch on `nextStep` itself) to show the new screen; until it does, it behaves as before.** There is no SMS-first page in this package: the screen lives in the consuming sites, so the deploy of the server change (PR 85) waits on every live consumer taking this release. Tests: `test/sms-next-step.test.cjs` (32), `test/sms-next-step-mutants.test.cjs` (9 hand mutants, one per branch).
 

package/dist/api-handlers/auth/credential-login.js

@@ -52,6 +52,8 @@ const device_id_1 = require("../../lib/device-id");
 const twofa_rejection_1 = require("../../lib/twofa-rejection");
 const bearer_fetch_1 = require("../../lib/bearer-fetch");
 const log_safe_1 = require("../../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).
+const first_enrol_1 = require("../../lib/first-enrol");
 // `export const runtime = 'nodejs'` must be written LITERALLY in the app's route file (Next ignores a re-exported segment config).
 /**
  * The device id to forward to the IDP for THIS caller — card 240566.
@@ -325,6 +327,50 @@ async function POST(req) {
         const vresult = verifyData?.data?.result ?? verifyData?.data ?? verifyData;
         const vAccess = vresult?.access_token;
         const vRefresh = 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 = server_1.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(first_enrol_1.ENROL_COOKIE, vAccess, { httpOnly: true, secure: process.env.NODE_ENV === 'production', sameSite: 'strict', path: '/', maxAge: first_enrol_1.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 server_1.NextResponse.json({ success: false, error: 'Authentication service returned an incomplete response' }, { status: 502 });

package/dist/api-handlers/mfa/first-enrol.d.ts

@@ -0,0 +1,5 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { type EnrolStep } from '../../lib/first-enrol';
+export declare function enrolStepPOST(step: EnrolStep): (req: NextRequest) => Promise<NextResponse>;
+export declare const POST_ENROLL: (req: NextRequest) => Promise<NextResponse>;
+export declare const POST_CONFIRM: (req: NextRequest) => Promise<NextResponse>;

package/dist/api-handlers/mfa/first-enrol.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST_CONFIRM = exports.POST_ENROLL = void 0;
+exports.enrolStepPOST = enrolStepPOST;
+const node_crypto_1 = require("node:crypto");
+const server_1 = require("next/server");
+const idp_client_config_1 = require("../../lib/idp-client-config");
+const client_key_1 = require("../../lib/client-key");
+const mfa_json_guard_1 = require("../../lib/mfa-json-guard");
+const first_enrol_1 = require("../../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) => (0, node_crypto_1.createHash)('sha256').update(s).digest('hex');
+const cookieOpts = (maxAge) => ({ httpOnly: true, secure: process.env.NODE_ENV === 'production', sameSite: 'strict', path: '/', maxAge });
+function reply(status, body, clear) {
+    const res = server_1.NextResponse.json(body, { status, headers: mfa_json_guard_1.NO_STORE });
+    if (clear)
+        res.cookies.set(first_enrol_1.ENROL_COOKIE, '', cookieOpts(0));
+    return res;
+}
+function enrolStepPOST(step) {
+    return async function POST(req) {
+        const refused = (0, mfa_json_guard_1.refuseNonJson)(req);
+        if (refused)
+            return refused;
+        const token = req.cookies.get(first_enrol_1.ENROL_COOKIE)?.value;
+        if (!token)
+            return reply(401, { success: false, code: 'SIGN_IN_AGAIN' }, false);
+        if (!(0, first_enrol_1.attemptAllowed)(`${step}|ck|${digest(token)}`, first_enrol_1.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 (0, idp_client_config_1.getIDPClientConfig)();
+            clientKey = (0, client_key_1.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 (0, first_enrol_1.runEnrolStep)({ fetchImpl: (u, i) => fetch(u, i), idp, clientKey }, { step, token, body });
+        return reply(r.status, r.body, r.cookie === 'clear');
+    };
+}
+exports.POST_ENROLL = enrolStepPOST('enroll');
+exports.POST_CONFIRM = enrolStepPOST('confirm');

package/dist/components/auth/CredentialSignInForm.d.ts

@@ -33,7 +33,12 @@ 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;
 }
 export declare function resolveDestination(explicit?: string): string;
-export declare function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPassword, enrollHref }: Props): import("react/jsx-runtime").JSX.Element;
+export declare function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPassword, enrollHref, firstEnrolHref }: Props): import("react/jsx-runtime").JSX.Element;
 export default CredentialSignInForm;

package/dist/components/auth/CredentialSignInForm.js

@@ -31,7 +31,7 @@ function resolveDestination(explicit) {
     }
     return (0, safe_callback_1.safeCallbackPath)((0, authorize_resume_1.authorizeResumeHref)(returnUrl), (0, safe_callback_1.safeCallbackPath)(raw, '/dashboard'));
 }
-function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPassword = false, enrollHref }) {
+function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPassword = false, enrollHref, firstEnrolHref }) {
     const [step, setStep] = (0, react_1.useState)('credentials');
     const [email, setEmail] = (0, react_1.useState)('');
     const [password, setPassword] = (0, react_1.useState)('');
@@ -62,6 +62,20 @@ function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPa
                     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/dist/components/mfa/FirstEnrolPanel.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 declare const FIRST_ENROL_ENROLL_URL = "/api/auth/first-enrol/enroll";
+export declare 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 declare 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 declare const DONE_SENTENCE = "Your authenticator is set. Sign in with your password and the code from your app.";
+export declare const SIGN_IN_AGAIN_SENTENCE = "This setup timed out or the sign-in expired. Sign in again to continue.";
+export declare function FirstEnrolPanel({ fetchImpl, signInHref, onSignInAgain, }?: {
+    fetchImpl?: typeof fetch;
+    signInHref?: string;
+    onSignInAgain?: (href: string) => void;
+}): import("react/jsx-runtime").JSX.Element;
+export default FirstEnrolPanel;

package/dist/components/mfa/FirstEnrolPanel.js

@@ -0,0 +1,115 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SIGN_IN_AGAIN_SENTENCE = exports.DONE_SENTENCE = exports.PER_APP_SENTENCE = exports.FIRST_ENROL_CONFIRM_URL = exports.FIRST_ENROL_ENROLL_URL = void 0;
+exports.FirstEnrolPanel = FirstEnrolPanel;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const QrCode_1 = require("./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.
+ */
+exports.FIRST_ENROL_ENROLL_URL = '/api/auth/first-enrol/enroll';
+exports.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). */
+exports.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.';
+exports.DONE_SENTENCE = 'Your authenticator is set. Sign in with your password and the code from your app.';
+exports.SIGN_IN_AGAIN_SENTENCE = 'This setup timed out or the sign-in expired. Sign in again to continue.';
+const REFUSAL_COPY = {
+    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.';
+const readJson = async (res) => res.json().catch(() => null);
+function FirstEnrolPanel({ fetchImpl, signInHref = '/account-auth/login', onSignInAgain, } = {}) {
+    const doFetch = fetchImpl ?? ((...a) => fetch(...a));
+    const [stage, setStage] = (0, react_1.useState)('starting');
+    const [enroll, setEnroll] = (0, react_1.useState)(null);
+    const [code, setCode] = (0, react_1.useState)('');
+    const [error, setError] = (0, react_1.useState)(null);
+    const [codes, setCodes] = (0, react_1.useState)(null);
+    const [busy, setBusy] = (0, react_1.useState)(false);
+    const started = (0, react_1.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(exports.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] ?? FALLBACK_COPY);
+            setStage('failed');
+        }
+        catch {
+            setError(REFUSAL_COPY.UNAVAILABLE);
+            setStage('failed');
+        }
+        finally {
+            setBusy(false);
+        }
+    }
+    (0, react_1.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(exports.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) => typeof c === 'string') : null);
+                setStage('done');
+                return;
+            }
+            setCode('');
+            setError(REFUSAL_COPY[body?.code] ?? FALLBACK_COPY);
+        }
+        catch {
+            setError(REFUSAL_COPY.UNAVAILABLE);
+        }
+        finally {
+            setBusy(false);
+        }
+    }
+    if (stage === 'done') {
+        return ((0, jsx_runtime_1.jsxs)("div", { "data-testid": "first-enrol-done", role: "status", children: [(0, jsx_runtime_1.jsx)("p", { children: exports.DONE_SENTENCE }), codes && codes.length > 0 ? ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("p", { children: "Save these recovery codes somewhere safe. Each one works once, and they are not shown again." }), (0, jsx_runtime_1.jsx)("ul", { "data-testid": "first-enrol-codes", children: codes.map((c) => ((0, jsx_runtime_1.jsx)("li", { children: (0, jsx_runtime_1.jsx)("code", { children: c }) }, c))) })] })) : ((0, jsx_runtime_1.jsx)("p", { "data-testid": "first-enrol-no-codes", children: "We could not show your recovery codes. You can create new ones after you sign in." })), (0, jsx_runtime_1.jsx)("p", { children: (0, jsx_runtime_1.jsx)("a", { href: signInHref, children: "Sign in" }) })] }));
+    }
+    return ((0, jsx_runtime_1.jsxs)("div", { "data-testid": "first-enrol-panel", style: { display: 'flex', flexDirection: 'column', gap: 12, alignItems: 'flex-start' }, children: [(0, jsx_runtime_1.jsx)("p", { "data-testid": "first-enrol-per-app", children: exports.PER_APP_SENTENCE }), stage === 'starting' ? (0, jsx_runtime_1.jsx)("p", { "data-testid": "first-enrol-starting", children: "Setting up\u2026" }) : null, stage === 'enrolling' && enroll ? ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("p", { children: "Open your authenticator app and scan this code. A phone camera works too." }), (0, jsx_runtime_1.jsx)(QrCode_1.QrCode, { value: enroll.otpauth_uri }), (0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("div", { children: "Can't scan? Enter this code manually:" }), (0, jsx_runtime_1.jsx)("code", { "data-testid": "first-enrol-secret", style: { wordBreak: 'break-all' }, children: enroll.secret })] }), (0, jsx_runtime_1.jsxs)("form", { onSubmit: (e) => {
+                            e.preventDefault();
+                            void confirm();
+                        }, children: [(0, jsx_runtime_1.jsx)("label", { htmlFor: "first-enrol-code", children: "Enter the 6-digit code from your app:" }), (0, jsx_runtime_1.jsx)("br", {}), (0, jsx_runtime_1.jsx)("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)) }), ' ', (0, jsx_runtime_1.jsx)("button", { type: "submit", "data-testid": "first-enrol-confirm", disabled: busy || code.length !== 6, children: "Confirm" })] })] })) : null, error ? ((0, jsx_runtime_1.jsx)("p", { role: "alert", "data-testid": "first-enrol-error", children: error })) : null, stage === 'failed' ? ((0, jsx_runtime_1.jsx)("p", { children: (0, jsx_runtime_1.jsx)("a", { href: signInHref, children: "Sign in again" }) })) : null] }));
+}
+exports.default = FirstEnrolPanel;

package/dist/lib/credential-sign-in-client.d.ts

@@ -25,6 +25,10 @@ export type CredentialSignInResult = {
     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;

package/dist/lib/credential-sign-in-client.js

@@ -80,8 +80,20 @@ async function credentialSignIn(args, fetchImpl = (input, init) => fetch(input,
             const code = body?.code === 'second_factor_rate_limited' ? 'second_factor_rate_limited' : 'too_many_attempts';
             return { kind: 'rate_limited', message: (0, sign_in_failure_1.tooManyAttemptsMessage)(body?.retryAfter, code), code };
         }
-        if (body?.requiresTwoFactor)
+        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 = { kind: 'error', message: exports.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: (0, code_step_copy_1.readCodeRequest)(body), devCode: readDevCode(body), nextStep: readNextStep(body) };
+        }
         if (!res.ok || body?.success !== true) {
             const offerEmailCode = body?.offerEmailCode === true;
             if ((0, sign_in_failure_1.isSignInFailureCode)(body?.code))

package/dist/lib/first-enrol.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 declare const ENROL_COOKIE = "payez_enrol";
+export declare const ENROL_COOKIE_MAX_AGE = 600;
+export type EnrolStep = 'enroll' | 'confirm';
+export declare const ENROL_STEPS: readonly EnrolStep[];
+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';
+};
+export declare function enrolIdpPath(step: EnrolStep): string;
+/** The body each step may carry: enroll { friendly_name? }, confirm { enrollment_id, code }. null = nothing is sent. */
+export declare function enrolBodyFor(step: EnrolStep, raw: unknown): Record<string, unknown> | null;
+export declare function parseEnrol(body: unknown): {
+    secret: string;
+    otpauthUri: string;
+    enrollmentId: number;
+} | null;
+export declare function parseConfirmed(body: unknown): boolean;
+export declare function parseCodes(body: unknown): string[] | null;
+export declare function codesForDisplay(codes: readonly string[]): string[];
+/** 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 declare function enrolRefusal(step: EnrolStep, status: number, body: unknown): {
+    status: number;
+    code: string;
+    text: string;
+} | 'sign-in';
+export declare function runEnrolStep(deps: CoreDeps, input: {
+    step: EnrolStep;
+    token: string;
+    body: unknown;
+}): Promise<CoreResult>;
+export declare const LIMIT_PER_COOKIE = 5;
+/**
+ * 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 declare 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 declare function attemptAllowed(key: string, limit: number, now?: number): boolean;
+export declare function _resetAttempts(): void;
+export declare function _trackedKeys(): number;

package/dist/lib/first-enrol.js

@@ -0,0 +1,188 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TRACKED_KEYS = exports.LIMIT_PER_COOKIE = exports.ENROL_STEPS = exports.ENROL_COOKIE_MAX_AGE = exports.ENROL_COOKIE = void 0;
+exports.enrolIdpPath = enrolIdpPath;
+exports.enrolBodyFor = enrolBodyFor;
+exports.parseEnrol = parseEnrol;
+exports.parseConfirmed = parseConfirmed;
+exports.parseCodes = parseCodes;
+exports.codesForDisplay = codesForDisplay;
+exports.enrolRefusal = enrolRefusal;
+exports.runEnrolStep = runEnrolStep;
+exports.attemptAllowed = attemptAllowed;
+exports._resetAttempts = _resetAttempts;
+exports._trackedKeys = _trackedKeys;
+exports.ENROL_COOKIE = 'payez_enrol';
+exports.ENROL_COOKIE_MAX_AGE = 600;
+exports.ENROL_STEPS = ['enroll', 'confirm'];
+const SENTENCE_UNAVAILABLE = 'We could not reach the sign-in service. Nothing was changed. Try again in a moment.';
+function enrolIdpPath(step) {
+    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. */
+function enrolBodyFor(step, raw) {
+    const src = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+    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) => {
+    if (!b || typeof b !== 'object' || Array.isArray(b))
+        return null;
+    const o = b;
+    return o.data && typeof o.data === 'object' && !Array.isArray(o.data) ? o.data : o;
+};
+const str = (v) => (typeof v === 'string' && v !== '' ? v : null);
+function parseEnrol(body) {
+    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 };
+}
+function parseConfirmed(body) {
+    return unwrap(body)?.confirmed === true;
+}
+function parseCodes(body) {
+    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;
+}
+function codesForDisplay(codes) {
+    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. */
+function enrolRefusal(step, status, body) {
+    if (status === 401 || status === 403)
+        return 'sign-in';
+    const c = (() => {
+        const b = body;
+        if (b && typeof b.code === 'string')
+            return b.code;
+        if (b && typeof b.error === 'object' && b.error && typeof b.error.code === 'string')
+            return b.error.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, clientKey) => ({
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+    Authorization: `Bearer ${token}`,
+    'X-Client-Id': clientKey,
+});
+const asJson = async (res) => res.json().catch(() => null);
+async function runEnrolStep(deps, input) {
+    const body = enrolBodyFor(input.step, input.body);
+    if (body === null)
+        return { status: 400, body: { success: false, code: 'INVALID_REQUEST' }, cookie: 'keep' };
+    let res;
+    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 = 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 = exports.ENROL_COOKIE_MAX_AGE * 1000;
+exports.LIMIT_PER_COOKIE = 5;
+const hits = new Map();
+/**
+ * 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).
+ */
+exports.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). */
+function attemptAllowed(key, limit, now = Date.now()) {
+    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 > exports.MAX_TRACKED_KEYS) {
+        const oldest = hits.keys().next().value;
+        if (oldest === undefined)
+            break;
+        hits.delete(oldest);
+    }
+    return allowed;
+}
+function _resetAttempts() {
+    hits.clear();
+}
+function _trackedKeys() {
+    return hits.size;
+}

package/dist/pages/first-enroll/page.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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(): import("react/jsx-runtime").JSX.Element;