@payez/next-mvp 4.13.0 → 4.14.0

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

@@ -0,0 +1,13 @@
+/**
+ * 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 declare const NO_STORE_VALUE = "no-store";
+export declare function withNoStoreHeader(res: Response): Response;
+export declare function noStore<A extends unknown[], R extends Response>(handler: (...args: A) => R | Promise<R>): (...args: A) => Promise<Response>;

package/dist/lib/no-store.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_STORE_VALUE = void 0;
+exports.withNoStoreHeader = withNoStoreHeader;
+exports.noStore = noStore;
+/**
+ * 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).
+ */
+exports.NO_STORE_VALUE = 'no-store';
+function withNoStoreHeader(res) {
+    // 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.headers)
+        return res;
+    try {
+        res.headers.set('Cache-Control', exports.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', exports.NO_STORE_VALUE);
+        return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+    }
+}
+function noStore(handler) {
+    return async (...args) => withNoStoreHeader(await handler(...args));
+}

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;

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/auth/session.d.ts

@@ -13,15 +13,8 @@
  * @since auth-ready-v2
  */
 import { NextRequest, NextResponse } from 'next/server';
-/**
- * GET /api/auth/session - Check current session status
- *
- * Returns the current session information including:
- * - User details
- * - Token expiry status
- * - Session validity
- */
-export declare function GET(req: NextRequest): Promise<NextResponse<{}>>;
+/** PAY-2994: session state is per-user and some answers carry tokens; never cached (noStore). */
+export declare const GET: (req: NextRequest) => Promise<Response>;
 /**
  * POST /api/auth/session - Update session METADATA
  *

package/dist/routes/auth/session.js

@@ -14,8 +14,9 @@
  * @since auth-ready-v2
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GET = GET;
+exports.GET = void 0;
 exports.POST = POST;
+const no_store_1 = require("../../lib/no-store");
 const server_1 = require("next/server");
 const auth_1 = require("../../server/auth");
 const session_store_1 = require("../../lib/session-store");
@@ -29,7 +30,7 @@ const token_log_id_1 = require("../../lib/token-log-id");
  * - Token expiry status
  * - Session validity
  */
-async function GET(req) {
+async function getHandler(req) {
     try {
         const authSession = await (0, auth_1.getSession)(req);
         if (!authSession) {
@@ -116,6 +117,8 @@ async function GET(req) {
         }, { status: 500 });
     }
 }
+/** PAY-2994: session state is per-user and some answers carry tokens; never cached (noStore). */
+exports.GET = (0, no_store_1.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.

package/dist/routes/auth/viability.d.ts

@@ -13,57 +13,6 @@
  * @version 2.0.0
  * @since auth-ready-v2
  */
-import { NextRequest, NextResponse } from 'next/server';
-import { type RevocationStatus } from '../../vibe/sessions';
-/**
- * GET /api/session/viability - Check if session is viable
- *
- * Returns:
- * - viable: boolean - Whether the session can be used
- * - needsRefresh: boolean - Whether a refresh is recommended
- * - expiresIn: number - Seconds until token expires
- */
-export declare function GET(req: NextRequest): Promise<NextResponse<{
-    viable: boolean;
-    needsRefresh: boolean;
-    authenticated: boolean;
-    revocationStatus: RevocationStatus;
-    unavailable: boolean;
-    error: string;
-    code: string;
-}> | NextResponse<{
-    viable: boolean;
-    needsRefresh: boolean;
-    authenticated: boolean;
-    reason: string;
-}> | NextResponse<{
-    tenantRequiresTwoFactor: boolean;
-    userHasCompletedTenantTwoFactorRequirements: boolean;
-    userStillNeedsTwoFactor: boolean;
-    tenantAllowed2FAMethods: string[] | null;
-    nextStep: "enroll_mfa" | "mfa_verify" | null | undefined;
-    requires2FA: boolean;
-    twoFactorComplete: boolean;
-    accessTokenExpired: boolean;
-    expiresAt: string;
-    roles: string[];
-    clientId: string | null;
-    forceInvalid: boolean;
-    unavailable: boolean;
-    revoked: boolean;
-    viable: boolean;
-    needsRefresh: boolean;
-    expiresIn: number;
-    hasRefreshToken: boolean;
-    authenticated: boolean;
-    sessionTokenId: string | null;
-    revocationStatus: RevocationStatus;
-}> | NextResponse<{
-    viable: boolean;
-    needsRefresh: boolean;
-    authenticated: boolean;
-    revocationStatus: RevocationStatus;
-    error: string;
-    code: string;
-    correlationId: string;
-}>>;
+import { NextRequest } from 'next/server';
+/** PAY-2994: session state is per-user and some answers carry tokens; never cached (noStore). */
+export declare const GET: (req: NextRequest) => Promise<Response>;