@payez/next-mvp 4.12.0 → 4.13.0

package/dist/middleware/prefetch-guard-status.d.ts

@@ -0,0 +1,21 @@
+/**
+ * PAY-2218 P1 (BAPert 86123, reworded 86209): say, once, at middleware creation, that the HEADER-based router-prefetch guard cannot see router prefetches
+ * on this Next version. After P2 the session-cookie clear no longer depends on it (it keys on Sec-Fetch-Mode/Dest), so this is information, not a call to
+ * migrate. No behaviour change: this only logs.
+ *
+ * MEASURED (adapter.js read in each version's own node_modules): Next 15.5.9 and 16.1.5 delete the flight headers (rsc, next-router-prefetch, ...)
+ * from the request middleware sees UNCONDITIONALLY, and 15.5.9 also strips `_rsc` from the URL, so isPrefetchRequest() is false for every router
+ * prefetch and no config can change that. Next 16.2.x skips the strip when `skipProxyUrlNormalize: true`.
+ *
+ * NOT warned, on purpose: Next >= 16.2 (the flag is a build-time define that user middleware code cannot reliably read back, so a warning there
+ * would be a guess) and Next 14 (not measured). Unparseable or missing version: silent.
+ */
+export type PrefetchGuardStatus = {
+    dead: boolean;
+    reason: string;
+};
+export declare function prefetchGuardStatus(nextVersion: string | undefined | null): PrefetchGuardStatus;
+/** Logs PAYEZ_PREFETCH_GUARD_DEAD once per process when the guard is dead on this Next version. Returns true when it logged. */
+export declare function warnPrefetchGuardDeadOnce(warn: (message: string, data?: unknown) => void, nextVersion?: string | undefined | null): boolean;
+/** Test seam: forget that the warning was logged. */
+export declare function resetPrefetchGuardWarningForTests(): void;

package/dist/middleware/prefetch-guard-status.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prefetchGuardStatus = prefetchGuardStatus;
+exports.warnPrefetchGuardDeadOnce = warnPrefetchGuardDeadOnce;
+exports.resetPrefetchGuardWarningForTests = resetPrefetchGuardWarningForTests;
+function prefetchGuardStatus(nextVersion) {
+    const m = /^(\d+)\.(\d+)\./.exec(String(nextVersion ?? '').trim());
+    if (!m)
+        return { dead: false, reason: 'unknown version' };
+    const major = Number(m[1]);
+    const minor = Number(m[2]);
+    if (major === 15 || (major === 16 && minor < 2)) {
+        return { dead: true, reason: 'strips the router-prefetch headers (rsc, next-router-prefetch) before middleware runs and has no opt-out' };
+    }
+    return { dead: false, reason: 'not measured as dead' };
+}
+function detectNextVersion() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require('next/package.json').version;
+    }
+    catch {
+        return undefined;
+    }
+}
+let warned = false;
+/** Logs PAYEZ_PREFETCH_GUARD_DEAD once per process when the guard is dead on this Next version. Returns true when it logged. */
+function warnPrefetchGuardDeadOnce(warn, nextVersion = detectNextVersion()) {
+    if (warned)
+        return false;
+    const s = prefetchGuardStatus(nextVersion);
+    if (!s.dead)
+        return false;
+    warned = true;
+    warn(`PAYEZ_PREFETCH_GUARD_DEAD next=${nextVersion}: this Next version ${s.reason}, so isPrefetchRequest() cannot see a router prefetch. ` +
+        "The session-cookie clear relies on the browser's Sec-Fetch-Mode/Dest instead (PAY-2218 P2); non-browser clients and browsers that send no Sec-Fetch headers are not covered.");
+    return true;
+}
+/** Test seam: forget that the warning was logged. */
+function resetPrefetchGuardWarningForTests() {
+    warned = false;
+}

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

@@ -0,0 +1,7 @@
+/**
+ * PAY-2631: /account-auth/enroll in a generated app. The page SHELL is public (every /account-auth/* path is public by default);
+ * what needs a session is each action: enrol and confirm answer 401 without one and the panel then says to sign in (measured on a
+ * scaffolded app: POST enrol with no cookie -> 401, no secret in the body). The scaffold lists the path on the 2FA bypass list
+ * because public routes still redirect a 2FA-incomplete session to verify-code, which sends enroll_mfa users back here: a loop.
+ */
+export default function EnrollPage(): import("react/jsx-runtime").JSX.Element;

package/dist/pages/enroll/page.js

@@ -0,0 +1,15 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = EnrollPage;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const TotpEnrollPanel_1 = require("../../components/mfa/TotpEnrollPanel");
+/**
+ * PAY-2631: /account-auth/enroll in a generated app. The page SHELL is public (every /account-auth/* path is public by default);
+ * what needs a session is each action: enrol and confirm answer 401 without one and the panel then says to sign in (measured on a
+ * scaffolded app: POST enrol with no cookie -> 401, no secret in the body). The scaffold lists the path on the 2FA bypass list
+ * because public routes still redirect a 2FA-incomplete session to verify-code, which sends enroll_mfa users back here: a loop.
+ */
+function EnrollPage() {
+    return ((0, jsx_runtime_1.jsxs)("main", { style: { maxWidth: 480, margin: '48px auto', padding: '0 16px' }, children: [(0, jsx_runtime_1.jsx)("h1", { children: "Set up an authenticator app" }), (0, jsx_runtime_1.jsx)(TotpEnrollPanel_1.TotpEnrollPanel, {}), (0, jsx_runtime_1.jsx)("p", { style: { marginTop: 24 }, children: (0, jsx_runtime_1.jsx)("a", { href: "/", children: "Continue to the app" }) })] }));
+}

package/dist/pages/login/page.js

@@ -180,7 +180,7 @@ function LoginForm({ altAuthSlot }) {
         .themed-status-submitting svg {
           color: ${buttonColor} !important;
         }
-      ` } }), (0, jsx_runtime_1.jsx)("div", { className: `min-h-screen flex items-center justify-center px-4 ${colors.background}`, children: (0, jsx_runtime_1.jsx)("div", { className: "max-w-md w-full", children: (0, jsx_runtime_1.jsxs)("div", { className: `rounded-2xl shadow-xl p-8 ${colors.card} ${colors.border} text-gray-800`, children: [(0, jsx_runtime_1.jsxs)("div", { className: "text-center mb-8", children: [(0, jsx_runtime_1.jsx)("h1", { className: "text-3xl font-bold mb-2", style: { color: 'inherit' }, children: branding.tagline || 'Welcome Back' }), (0, jsx_runtime_1.jsx)("p", { className: colors.muted, children: "Sign in to your account" })] }), shownError && ((0, jsx_runtime_1.jsx)("div", { role: "alert", "data-testid": "login-error", className: "mb-6 rounded-lg border border-red-200 bg-red-50 px-4 py-3 text-sm text-red-700", children: shownError })), googleEnabled && ((0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: (0, jsx_runtime_1.jsxs)("button", { type: "button", onClick: () => void handleGoogleSignIn(), disabled: googleLoading || isSubmitting, "data-testid": "google-sign-in", className: "w-full px-4 py-3 mb-6 rounded-lg border border-gray-300 font-semibold transition-colors flex items-center justify-center gap-2 disabled:opacity-50 disabled:cursor-not-allowed hover:bg-gray-50", style: { backgroundColor: 'white', color: '#1f2937' }, children: [googleLoading ? ((0, jsx_runtime_1.jsxs)("svg", { className: "animate-spin w-5 h-5", fill: "none", viewBox: "0 0 24 24", children: [(0, jsx_runtime_1.jsx)("circle", { className: "opacity-25", cx: "12", cy: "12", r: "10", stroke: "currentColor", strokeWidth: "4" }), (0, jsx_runtime_1.jsx)("path", { className: "opacity-75", fill: "currentColor", d: "M4 12a8 8 0 018-8v4a4 4 0 00-4 4H4z" })] })) : ((0, jsx_runtime_1.jsxs)("svg", { className: "w-5 h-5", viewBox: "0 0 24 24", fill: "currentColor", children: [(0, jsx_runtime_1.jsx)("path", { d: "M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z", fill: "#4285F4" }), (0, jsx_runtime_1.jsx)("path", { d: "M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z", fill: "#34A853" }), (0, jsx_runtime_1.jsx)("path", { d: "M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z", fill: "#FBBC05" }), (0, jsx_runtime_1.jsx)("path", { d: "M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z", fill: "#EA4335" })] })), googleLoading ? 'Redirecting to Google…' : 'Continue with Google'] }) })), altAuthSlot && (0, jsx_runtime_1.jsx)("div", { className: "mt-4", children: altAuthSlot }), (0, jsx_runtime_1.jsx)("div", { className: `mt-6 text-center text-sm ${colors.muted}`, children: (0, jsx_runtime_1.jsx)("a", { href: "/account-auth/recovery", className: "themed-link hover:underline", children: "Start account recovery" }) })] }) }) })] }));
+      ` } }), (0, jsx_runtime_1.jsx)("div", { className: `min-h-screen flex items-center justify-center px-4 ${colors.background}`, children: (0, jsx_runtime_1.jsx)("div", { className: "max-w-md w-full", children: (0, jsx_runtime_1.jsxs)("div", { className: `rounded-2xl shadow-xl p-8 ${colors.card} ${colors.border} text-gray-800`, children: [(0, jsx_runtime_1.jsxs)("div", { className: "text-center mb-8", children: [(0, jsx_runtime_1.jsx)("h1", { className: "text-3xl font-bold mb-2", style: { color: 'inherit' }, children: branding.tagline || 'Welcome Back' }), (0, jsx_runtime_1.jsx)("p", { className: colors.muted, children: "Sign in to your account" })] }), shownError && ((0, jsx_runtime_1.jsx)("div", { role: "alert", "data-testid": "login-error", "data-error-code": loginError === undefined ? ((0, login_error_message_1.loginErrorCode)(urlError) ?? undefined) : undefined, className: "mb-6 rounded-lg border border-red-200 bg-red-50 px-4 py-3 text-sm text-red-700", children: shownError })), googleEnabled && ((0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: (0, jsx_runtime_1.jsxs)("button", { type: "button", onClick: () => void handleGoogleSignIn(), disabled: googleLoading || isSubmitting, "data-testid": "google-sign-in", className: "w-full px-4 py-3 mb-6 rounded-lg border border-gray-300 font-semibold transition-colors flex items-center justify-center gap-2 disabled:opacity-50 disabled:cursor-not-allowed hover:bg-gray-50", style: { backgroundColor: 'white', color: '#1f2937' }, children: [googleLoading ? ((0, jsx_runtime_1.jsxs)("svg", { className: "animate-spin w-5 h-5", fill: "none", viewBox: "0 0 24 24", children: [(0, jsx_runtime_1.jsx)("circle", { className: "opacity-25", cx: "12", cy: "12", r: "10", stroke: "currentColor", strokeWidth: "4" }), (0, jsx_runtime_1.jsx)("path", { className: "opacity-75", fill: "currentColor", d: "M4 12a8 8 0 018-8v4a4 4 0 00-4 4H4z" })] })) : ((0, jsx_runtime_1.jsxs)("svg", { className: "w-5 h-5", viewBox: "0 0 24 24", fill: "currentColor", children: [(0, jsx_runtime_1.jsx)("path", { d: "M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z", fill: "#4285F4" }), (0, jsx_runtime_1.jsx)("path", { d: "M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z", fill: "#34A853" }), (0, jsx_runtime_1.jsx)("path", { d: "M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z", fill: "#FBBC05" }), (0, jsx_runtime_1.jsx)("path", { d: "M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z", fill: "#EA4335" })] })), googleLoading ? 'Redirecting to Google…' : 'Continue with Google'] }) })), altAuthSlot && (0, jsx_runtime_1.jsx)("div", { className: "mt-4", children: altAuthSlot }), (0, jsx_runtime_1.jsx)("div", { className: `mt-6 text-center text-sm ${colors.muted}`, children: (0, jsx_runtime_1.jsx)("a", { href: "/account-auth/recovery", className: "themed-link hover:underline", children: "Start account recovery" }) })] }) }) })] }));
 }
 function LoginPageFallback() {
     const colors = (0, useTheme_1.useColors)();

package/dist/routes/auth/session-reset.d.ts

@@ -18,4 +18,14 @@
  */
 import { NextRequest, NextResponse } from 'next/server';
 export declare const dynamic = "force-dynamic";
-export declare function GET(request: NextRequest): Promise<NextResponse>;
+export interface SessionResetOptions {
+    /**
+     * PAY-2218 opt-in, OFF by default (BAPert 83102). OFF: only a link signed with the env secret (BETTER_AUTH_SECRET / NEXTAUTH_SECRET) clears, so every app that can
+     * see the secret stays strict. ON: a link signed with the key derived from this request's own session cookie also clears. Turn it on only where the EDGE middleware
+     * cannot see the env secret, and set `sessionResetCookieKey: true` on createMvpMiddleware too, or the route refuses the link the middleware signed.
+     */
+    cookieKey?: boolean;
+}
+export declare function createSessionResetHandler(options?: SessionResetOptions): (request: NextRequest) => Promise<NextResponse>;
+/** The strict default: env-signed links only. An app that opted in uses createSessionResetHandler({ cookieKey: true }). */
+export declare const GET: (request: NextRequest) => Promise<NextResponse>;

package/dist/routes/auth/session-reset.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.dynamic = void 0;
-exports.GET = GET;
+exports.GET = exports.dynamic = void 0;
+exports.createSessionResetHandler = createSessionResetHandler;
 /**
  * PAY-2218 PR 2: the session-reset route. Mount it at app/api/auth/session-reset/route.ts:
  *
@@ -26,15 +26,40 @@ const session_cookie_clear_1 = require("../../auth/session-cookie-clear");
 const app_slug_1 = require("../../lib/app-slug");
 const session_reset_link_1 = require("../../auth/session-reset-link");
 exports.dynamic = 'force-dynamic';
-async function GET(request) {
-    if ((0, create_middleware_1.isPrefetchRequest)(request)) {
-        return new server_1.NextResponse(null, { status: 204, headers: { 'cache-control': 'no-store' } });
-    }
-    const bound = (0, session_reset_link_1.boundSessionCookie)((n) => request.cookies.get(n)?.value, (0, app_slug_1.getSessionCookieName)(), (0, app_slug_1.getSecureSessionCookieName)());
-    const { params, signed } = await (0, session_reset_link_1.readResetRequest)(request.nextUrl.searchParams, (0, session_reset_link_1.resetSecret)(), bound);
-    const response = server_1.NextResponse.redirect(new URL((0, session_reset_link_1.loginLocation)(params), request.url), 307);
-    response.headers.set('cache-control', 'no-store');
-    if (signed)
-        (0, session_cookie_clear_1.expireSessionCookies)(response, Array.from(request.cookies, ([name]) => name));
-    return response;
+function createSessionResetHandler(options = {}) {
+    const cookieKey = options.cookieKey === true;
+    let splitLogged = false;
+    let halfSetLogged = false;
+    return async function GET(request) {
+        if ((0, create_middleware_1.isPrefetchRequest)(request)) {
+            return new server_1.NextResponse(null, { status: 204, headers: { 'cache-control': 'no-store' } });
+        }
+        const bound = (0, session_reset_link_1.boundSessionCookie)((n) => request.cookies.get(n)?.value, (0, app_slug_1.getSessionCookieName)(), (0, app_slug_1.getSecureSessionCookieName)());
+        const env = (0, session_reset_link_1.resetSecret)();
+        const { params, signed, via } = cookieKey
+            ? await (0, session_reset_link_1.readResetRequestAnyKey)(request.nextUrl.searchParams, env, bound)
+            : { ...(await (0, session_reset_link_1.readResetRequest)(request.nextUrl.searchParams, env, bound)), via: null };
+        // The dev-93 prefetch walk reads this line: a link that verified ONLY with the cookie-derived key while this route sees the env secret is the
+        // edge-blind / route-sighted split deployment. Once per process, no values.
+        if (cookieKey && signed && via === 'cookie' && env && !splitLogged) {
+            splitLogged = true;
+            console.info('[next-mvp] session-reset: a link verified with the cookie-derived key while the env secret is visible to this route (the edge middleware signed without it: split deployment)');
+        }
+        // HALF-SET (NightHawk 83161): this route is strict (cookieKey OFF) but the middleware signed with the cookie-derived key (sessionResetCookieKey ON). The link is refused
+        // and the stale cookie survives. Probe ONLY refused links, for the cookie-derived key alone, and say so once per process. No values.
+        if (!cookieKey && !signed && !halfSetLogged) {
+            const probe = await (0, session_reset_link_1.readResetRequestAnyKey)(request.nextUrl.searchParams, undefined, bound);
+            if (probe.signed) {
+                halfSetLogged = true;
+                console.warn('[next-mvp] session-reset: refused a link signed with the cookie-derived key because this route has cookieKey OFF; the middleware has sessionResetCookieKey ON. Set createSessionResetHandler({ cookieKey: true }) or turn the middleware option off');
+            }
+        }
+        const response = server_1.NextResponse.redirect(new URL((0, session_reset_link_1.loginLocation)(params), request.url), 307);
+        response.headers.set('cache-control', 'no-store');
+        if (signed)
+            (0, session_cookie_clear_1.expireSessionCookies)(response, Array.from(request.cookies, ([name]) => name));
+        return response;
+    };
 }
+/** The strict default: env-signed links only. An app that opted in uses createSessionResetHandler({ cookieKey: true }). */
+exports.GET = createSessionResetHandler();

package/dist/routes/auth/viability.js

@@ -187,6 +187,9 @@ async function GET(req) {
         // stack just resolved the cookie cleanly. Keeps the two viability impls
         // (this route + `api-handlers/session/viability.ts`) in lockstep.
         let session = sessionToken ? await (0, session_store_1.getSession)(sessionToken) : null;
+        // PAY-2467: a row read from the CANONICAL store is the raw JSON the callback wrote, so an `mfaVerified` boolean on it is a
+        // MEASUREMENT (an absent key is a legacy row). Only the BA-record fallback collapses absent to false and needs mfaSignalPresent.
+        const fromCanonicalStore = !!session;
         if (sessionToken && !session) {
             session = await (0, session_store_1.getBetterAuthSession)(sessionToken);
             if (session) {
@@ -278,9 +281,15 @@ async function GET(req) {
          * middleware actually gates on; `tenantRequiresTwoFactor` stays pure —
          * it names TENANT policy, and this override is not tenant state.
          */
-        const oauthSessionNeedsTwoFactor = session?.mfaSignalPresent === true &&
+        const oauthSessionNeedsTwoFactor = 
+        // PAY-2467: the signal is present on the BA-fallback path (mfaSignalPresent) OR when the canonical row itself carries a boolean.
+        // Before this, the override was dead on the canonical path every consumer mounts, so gating rested on tenant config alone.
+        (session?.mfaSignalPresent === true || (fromCanonicalStore && typeof session?.mfaVerified === 'boolean')) &&
             session?.mfaVerified === false &&
-            !(session.idpRefreshToken || session?.refreshToken);
+            !(session.idpRefreshToken || session?.refreshToken) &&
+            // An IdP DISCARD (refresh.ts / ensure-fresh-access-token.ts write idpRefreshToken '' with refreshTokenClearedReason 'IDP_DISCARD_TOKEN:<code>') leaves
+            // mfaVerified false and no refresh token too, but that is a DEAD session, not a pending second factor: it must not be sent to verify-code (QAPert 84816).
+            !String(session?.refreshTokenClearedReason ?? '').startsWith('IDP_DISCARD_TOKEN');
         // --- Session revocation status (PAY-1882 step 4 producer half) ---
         /*
          * Resolve the four-state revocation status for this user (BAPert 66320).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.12.0",
+  "version": "4.13.0",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -1084,6 +1084,16 @@
       "types": "./dist/lib/credential-sign-in-client.d.ts",
       "require": "./dist/lib/credential-sign-in-client.js",
       "default": "./dist/lib/credential-sign-in-client.js"
+    },
+    "./components/mfa/TotpEnrollPanel": {
+      "types": "./dist/components/mfa/TotpEnrollPanel.d.ts",
+      "require": "./dist/components/mfa/TotpEnrollPanel.js",
+      "default": "./dist/components/mfa/TotpEnrollPanel.js"
+    },
+    "./dist/pages/enroll": {
+      "types": "./dist/pages/enroll/page.d.ts",
+      "require": "./dist/pages/enroll/page.js",
+      "default": "./dist/pages/enroll/page.js"
     }
   },
   "peerDependencies": {

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

@@ -38,6 +38,7 @@
  * lib/session-store.js").
  */
 import { NextRequest, NextResponse } from 'next/server';
+import { capPolicyDetail, classifySignInFailure, signInFailureMessage, type SignInFailureCode } from '../../lib/sign-in-failure';
 import { SignJWT } from 'jose';
 import { getIDPClientConfig } from '../../lib/idp-client-config';
 import { resolveClientKey } from '../../lib/client-key';
@@ -325,10 +326,15 @@ export async function POST(req: NextRequest) {
       // (MfaController.VerifyTotp answers a 15-minute lockout as 400 {code:"locked"}), which status-only
       // classification told to "try again".
       const rejection = classifyTwofaRejection(laneResults, idpResponse.headers.get('retry-after'));
+      // PAY-2568 follow-up (BAPert 85795): the page takes its sentence from a CODE in the closed table, so this lane must send one.
+      // The branch already decided the cause (classifyTwofaRejection); the code follows its status, the IdP's wording is never used.
+      const rejectionCode: SignInFailureCode =
+        rejection.status === 429 ? (rejection.rateLimited ? 'second_factor_rate_limited' : 'too_many_attempts') : rejection.status === 502 ? 'second_factor_unavailable' : 'invalid_second_factor';
       return NextResponse.json(
         {
           success: false,
-          error: rejection.error,
+          code: rejectionCode,
+          error: signInFailureMessage(rejectionCode),
           ...(rejection.retryAfter !== undefined ? { retryAfter: rejection.retryAfter } : {}),
           // PAY-2284: the card shows a real "email me a code" action only when this is true.
           ...(rejection.offerEmailCode ? { offerEmailCode: true } : {}),
@@ -389,19 +395,25 @@ export async function POST(req: NextRequest) {
   if (idpResponse.status === 429) {
     const retryAfter = idpResponse.headers.get('retry-after');
     return NextResponse.json(
-      { success: false, error: 'Too many attempts. Please try again later.', retryAfter: retryAfter ? parseInt(retryAfter, 10) : 60 },
+      {
+        success: false,
+        code: 'too_many_attempts',
+        error: signInFailureMessage('too_many_attempts'),
+        // BAPert 85807: the page prints this number as minutes, so only a real Retry-After is sent; no invented default.
+        ...(retryAfter && Number.isFinite(parseInt(retryAfter, 10)) && parseInt(retryAfter, 10) > 0 ? { retryAfter: parseInt(retryAfter, 10) } : {}),
+      },
       { status: 429 }
     );
   }
 
   if (!idpResponse.ok) {
     const f = logIdpAuthRefusal('non-ok', idpResponse.status, data);
-    return NextResponse.json({ success: false, error: publicRefusalMessage(f) }, { status: idpResponse.status });
+    return NextResponse.json(refusalBody(f, idpResponse.status), { status: idpResponse.status });
   }
 
   if (data?.success === false) {
     const f = logIdpAuthRefusal('envelope-success-false', idpResponse.status, data);
-    return NextResponse.json({ success: false, error: publicRefusalMessage(f) }, { status: 200 });
+    return NextResponse.json(refusalBody(f, idpResponse.status), { status: 200 });
   }
 
   // Unwrap the IDP's canonical envelope, same shape login.js normalizes.
@@ -761,6 +773,19 @@ function publicRefusalMessage(f: IdpFailure): string {
   return UNIFORM_REFUSAL;
 }
 
+/**
+ * The browser-facing body of a refusal (BAPert 85415): a stable machine `code` from the closed table in lib/sign-in-failure, and
+ * the fixed sentence for it. The IdP's own message text is never copied in. The one exception is the allowlisted policy refusals
+ * (SsoRequired / SsoRequiredBreakGlass / InvalidRequest): a property of the email domain or the request, not of an account, and the
+ * user cannot proceed without being told; they carry code 'policy_message' and the allowlisted detail (see SAFE_TO_SHOW).
+ */
+function refusalBody(f: IdpFailure, status: number): { success: false; code: string; error: string } {
+  const policy = f.code && SAFE_TO_SHOW.has(f.code) ? capPolicyDetail(f.detail) : null;
+  if (policy) return { success: false, code: 'policy_message', error: policy };
+  const code = classifySignInFailure(status, f.code);
+  return { success: false, code, error: signInFailureMessage(code) as string };
+}
+
 function logIdpAuthRefusal(branch: string, httpStatus: number, data: unknown): IdpFailure {
   const f = extractIdpFailure(data);
   const d = (data ?? {}) as Record<string, unknown>;

package/src/api-handlers/mfa/totp-confirm.ts

@@ -2,6 +2,7 @@ import { NextRequest, NextResponse } from 'next/server';
 import { idpFetchJSON } from '../../lib/idp-fetch';
 import { ENV_CONFIG } from '../../config/env';
 import { projectIdpError } from '../../lib/safe-error-response';
+import { NO_STORE, refuseNonJson } from '../../lib/mfa-json-guard';
 
 /**
  * Confirm TOTP enrolment with the first authenticator code
@@ -10,6 +11,8 @@ import { projectIdpError } from '../../lib/safe-error-response';
  * the method ACTIVE.
  */
 export async function POST(req: NextRequest) {
+  const refused = refuseNonJson(req);
+  if (refused) return refused;
   let body = '{}';
   try {
     const raw = await req.text();
@@ -30,14 +33,14 @@ export async function POST(req: NextRequest) {
         error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: projectIdpError(result.json) },
         meta: { attemptedRefresh: result.attemptedRefresh },
       },
-      { status: result.status },
+      { status: result.status, headers: NO_STORE },
     );
   }
 
   const bodyJson: any = result.json;
   if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
-    if (bodyJson.success === true) return NextResponse.json(bodyJson.data, { status: 200 });
-    return NextResponse.json(bodyJson, { status: 200 });
+    if (bodyJson.success === true) return NextResponse.json(bodyJson.data, { status: 200, headers: NO_STORE });
+    return NextResponse.json(bodyJson, { status: 200, headers: NO_STORE });
   }
-  return NextResponse.json(bodyJson ?? {}, { status: 200 });
+  return NextResponse.json(bodyJson ?? {}, { status: 200, headers: NO_STORE });
 }

package/src/api-handlers/mfa/totp-enroll.ts

@@ -2,6 +2,7 @@ import { NextRequest, NextResponse } from 'next/server';
 import { idpFetchJSON } from '../../lib/idp-fetch';
 import { ENV_CONFIG } from '../../config/env';
 import { projectIdpError } from '../../lib/safe-error-response';
+import { NO_STORE, refuseNonJson } from '../../lib/mfa-json-guard';
 
 /**
  * Begin TOTP enrolment (POST /api/Account/mfa/totp/enroll, user JWT).
@@ -10,6 +11,8 @@ import { projectIdpError } from '../../lib/safe-error-response';
  * as "Active" (MFA honesty fixes, 2026-08-01).
  */
 export async function POST(req: NextRequest) {
+  const refused = refuseNonJson(req);
+  if (refused) return refused;
   let body = '{}';
   try {
     const raw = await req.text();
@@ -30,14 +33,14 @@ export async function POST(req: NextRequest) {
         error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: projectIdpError(result.json) },
         meta: { attemptedRefresh: result.attemptedRefresh },
       },
-      { status: result.status },
+      { status: result.status, headers: NO_STORE },
     );
   }
 
   const bodyJson: any = result.json;
   if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
-    if (bodyJson.success === true) return NextResponse.json(bodyJson.data, { status: 200 });
-    return NextResponse.json(bodyJson, { status: 200 });
+    if (bodyJson.success === true) return NextResponse.json(bodyJson.data, { status: 200, headers: NO_STORE });
+    return NextResponse.json(bodyJson, { status: 200, headers: NO_STORE });
   }
-  return NextResponse.json(bodyJson ?? {}, { status: 200 });
+  return NextResponse.json(bodyJson ?? {}, { status: 200, headers: NO_STORE });
 }

package/src/api-handlers/session/viability.ts

@@ -76,6 +76,8 @@ export async function GET(req: NextRequest) {
     if (betterAuthSession && sessionToken) {
       // Try legacy session store first, then Better Auth format
       let sessionData = await getRedisSession(sessionToken);
+      // PAY-2467: see routes/auth/viability.ts - a boolean mfaVerified on the raw canonical row is a measurement.
+      const fromCanonicalStore = !!sessionData;
       if (!sessionData) {
         // Better Auth stores sessions with ba:{appSlug}:{token} prefix
         sessionData = await getBetterAuthSession(sessionToken);
@@ -127,9 +129,11 @@ export async function GET(req: NextRequest) {
         // keep gating on `mfaVerified`, which stays fail-closed at all five sites. R807 is
         // void if this signal reaches an auth decision.
         if (
-          sessionData.mfaSignalPresent === true &&
+          (sessionData.mfaSignalPresent === true || (fromCanonicalStore && typeof sessionData.mfaVerified === 'boolean')) &&
           sessionData.mfaVerified === false &&
-          !sessionData.idpRefreshToken
+          !sessionData.idpRefreshToken &&
+          // same exception as routes/auth/viability: an IdP-discarded refresh token is a dead session, not a pending second factor
+          !String((sessionData as any)?.refreshTokenClearedReason ?? '').startsWith('IDP_DISCARD_TOKEN')
         ) {
           requires2FA = true;
         }

package/src/auth/better-auth.ts

@@ -1563,6 +1563,20 @@ async function abortOAuthSignIn(
   return new Response(null, { status: 302, headers });
 }
 
+/**
+ * PAY-2568: the Better Auth error code of an /api/auth/error redirect (`?error=<code>`), or null when absent or not a plain
+ * token. The value rides a URL, so only a short [A-Za-z0-9_.-] token is ever returned for logging. Location may be relative
+ * or absolute; the base is a placeholder used only for parsing.
+ */
+export function authErrorCodeFromLocation(location: string): string | null {
+  try {
+    const code = new URL(location, 'http://placeholder.invalid').searchParams.get('error');
+    return code && /^[A-Za-z0-9_.-]{1,64}$/.test(code) ? code : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Create a production-ready GET handler for the auth catch-all route.
  *
@@ -1600,7 +1614,15 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
     if (response.status === 302) {
       const location = response.headers.get('location') || '';
       if (location.includes('/api/auth/error') || location.includes('please_restart')) {
-        console.warn('[BETTER_AUTH] OAuth state error, redirecting to login');
+        // PAY-2568: log WHICH error. Better Auth routes every callback failure to /api/auth/error?error=<code>
+        // (signup_disabled, state_mismatch, ...); the old fixed 'OAuth state error' sentence made distinct faults
+        // look identical. Only the code is logged - never the Location (it can carry other params).
+        const authErrorCode = authErrorCodeFromLocation(location);
+        if (authErrorCode) {
+          console.warn('[BETTER_AUTH] auth error code=' + authErrorCode + ', redirecting to login');
+        } else {
+          console.warn('[BETTER_AUTH] OAuth state error, redirecting to login');
+        }
         // *** DO NOT "TIDY" THIS BACK TO Response.redirect(). IT THROWS. (328439) ***
         // Response.redirect() REQUIRES an absolute URL — measured, on the leg's own
         // runtime and again on node 24:
@@ -1637,7 +1659,10 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
         // Works whether loginPath is relative (package default '/account-auth/login',
         // and the graft passes '/sign-in') or absolute — an absolute Location is also
         // legal, so a consumer passing a full URL still behaves.
-        return new Response(null, { status: 302, headers: { location: loginPath } });
+        // PAY-2554: the redirect used to carry NO code, so the login page showed nothing and looked like nothing happened.
+        // It now carries the same neutral OAUTH_SIGN_IN_FAILED the abort path uses (the login page maps it to one sentence;
+        // no provider text, URL or internal detail goes on the URL).
+        return new Response(null, { status: 302, headers: { location: `${loginPath}${loginPath.includes('?') ? '&' : '?'}error=${OAUTH_SIGN_IN_FAILED_ERROR}` } });
       }
     }
 

package/src/auth/session-reset-link.ts

@@ -91,6 +91,32 @@ export function resetSecret(): string | undefined {
   return process.env.BETTER_AUTH_SECRET || process.env.NEXTAUTH_SECRET || undefined;
 }
 
+/**
+ * The domain-separation label for the cookie-derived FALLBACK key (PAY-2218, BAPert 83028). It is the only place the session cookie is used as
+ * key material, and it is never the raw SHA-256 of the cookie (that is the binding, a different value for a different purpose).
+ */
+export const RESET_COOKIE_KEY_CONTEXT = 'payez:session-reset:v1:cookie-derived';
+
+/**
+ * The secret the reset link is signed and verified with.
+ *
+ *  1. The env secret (BETTER_AUTH_SECRET / NEXTAUTH_SECRET) when the edge can see it. ALWAYS FIRST: where it is present nothing changes.
+ *  2. Otherwise a key derived from the session cookie the link is bound to: HMAC(key = cookie value, message = RESET_COOKIE_KEY_CONTEXT).
+ *     Why that is safe: the cookie is HttpOnly and is the user's credential, so a third-party page that links a victim to the route cannot
+ *     produce a valid signature (the logout-CSRF protection the signature exists for), and anyone who holds the cookie can already act as
+ *     the user, logging out included. The edge holds only a one-way value computed per request from a cookie it already received.
+ *     RESIDUAL RISK, ACCEPTED (BAPert 83028): an attacker who controls a sibling subdomain can plant a cookie value they know under the
+ *     session cookie name and sign a link that clears THAT value. The effect is a forced logout, and an attacker in that position can already
+ *     set or shadow cookies and log the victim out, so the scheme adds no capability.
+ *  3. Neither: undefined ("cannot sign"; callers fall back to the direct clear).
+ * Never log the cookie value or the returned key.
+ */
+export async function resetSigningSecret(envSecret: string | undefined, sessionCookieValue: string | undefined): Promise<string | undefined> {
+  if (envSecret) return envSecret;
+  if (!sessionCookieValue) return undefined;
+  return b64url(await hmacBytes(encoder.encode(sessionCookieValue), RESET_COOKIE_KEY_CONTEXT));
+}
+
 /** The session cookie a reset is bound to: the __Secure- one when present, else the plain one. */
 export function boundSessionCookie(get: (name: string) => string | undefined, plainName: string, secureName: string): string | undefined {
   return get(secureName) || get(plainName) || undefined;
@@ -137,6 +163,27 @@ export async function signedResetHref(
   return `${route}?${q.toString()}`;
 }
 
+/**
+ * VERIFY side, ONLY for an app that opted in (sessionResetCookieKey + createSessionResetHandler({ cookieKey: true }); BAPert 83102). PAY-2218, BAPert 83074 option a: the signer and the verifier can see different things. The edge middleware may be BLIND to the env
+ * secret (it signs cookie-derived) while the Node route handler is SIGHTED (the IdP-supplied secret is in its process.env). So the route accepts a link
+ * signed with EITHER sound key: the env secret first (when it has one), then the key derived from THIS request's session cookie. Both are sound: the
+ * cookie-derived link is still bound to the request's own session cookie, carries its expiry inside the MAC, and is compared in constant time. A link
+ * signed with neither key, or with a key derived from a different cookie, is refused.
+ */
+export async function readResetRequestAnyKey(
+  search: URLSearchParams,
+  envSecret: string | undefined,
+  sessionCookieValue: string | undefined,
+  nowMs: number = Date.now()
+): Promise<{ params: ResetParams; signed: boolean; via: 'env' | 'cookie' | null }> {
+  if (envSecret) {
+    const viaEnv = await readResetRequest(search, envSecret, sessionCookieValue, nowMs);
+    if (viaEnv.signed) return { ...viaEnv, via: 'env' };
+  }
+  const viaCookie = await readResetRequest(search, await resetSigningSecret(undefined, sessionCookieValue), sessionCookieValue, nowMs);
+  return { ...viaCookie, via: viaCookie.signed ? 'cookie' : null };
+}
+
 /**
  * Read a reset request's query. `signed` is true only for a valid, unexpired signature over the normalised params AND
  * this request's own session cookie (`sessionCookieValue`). With no session cookie there is nothing to clear: false.

package/src/components/auth/CredentialSignInForm.tsx

@@ -6,11 +6,14 @@ import { safeCallbackPath } from '../../auth/safe-callback';
 import { authorizeResumeHref } from '../../lib/authorize-resume';
 import { NO_CODE_REQUEST, codeStepInstruction, type CodeRequest } from '../../lib/code-step-copy';
 import { DevCodeNotice } from './DevCodeNotice';
+import { EnrollAuthenticatorOffer } from './EnrollAuthenticatorOffer';
 import {
   credentialSignIn,
+  postSignInDestination,
   requestEmailCode,
   validateCredentials,
   type FetchLike,
+  type NextStep,
 } from '../../lib/credential-sign-in-client';
 
 /**
@@ -42,6 +45,12 @@ interface Props {
   /** Test seam: navigation after success. */
   onSignedIn?: (destination: string) => void;
   showForgotPassword?: boolean;
+  /**
+   * PAY-2630: the enrolment page a user the IdP told to enrol is taken to after signing in. NO DEFAULT: the offer renders only when
+   * the host passes this, because the host is the one that serves the page (the CLI scaffold writes no /account/security, so a
+   * default would 404 a generated app's user right after a good sign-in).
+   */
+  enrollHref?: string;
 }
 
 const inputStyle: React.CSSProperties = {
@@ -64,27 +73,32 @@ export function resolveDestination(explicit?: string): string {
   return safeCallbackPath(authorizeResumeHref(returnUrl), safeCallbackPath(raw, '/dashboard'));
 }
 
-export function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPassword = false }: Props) {
+export function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPassword = false, enrollHref }: Props) {
   const [step, setStep] = useState<'credentials' | 'code'>('credentials');
   const [email, setEmail] = useState('');
   const [password, setPassword] = useState('');
   const [code, setCode] = useState('');
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [errorCode, setErrorCode] = useState<string | null>(null);
   const [fieldError, setFieldError] = useState<string | null>(null);
   const [codeRequest, setCodeRequest] = useState<CodeRequest>(NO_CODE_REQUEST);
   const [offerEmailCode, setOfferEmailCode] = useState(false);
   const [devCode, setDevCode] = useState<string | null>(null);
   const [emailCodeMsg, setEmailCodeMsg] = useState<string | null>(null);
+  // PAY-2630: what the IdP said is outstanding on this client, and whether the user kept the 'take me to enrol' offer ticked.
+  const [nextStep, setNextStep] = useState<NextStep>(null);
+  const [enrolAfter, setEnrolAfter] = useState(true);
 
   async function submit(withCode?: string) {
     setBusy(true);
     setError(null);
+    setErrorCode(null);
     setOfferEmailCode(false);
     try {
       const r = await credentialSignIn({ email, password, code: withCode }, fetchImpl);
       if (r.kind === 'success') {
-        const destination = resolveDestination(callbackUrl);
+        const destination = postSignInDestination(resolveDestination(callbackUrl), nextStep, enrolAfter, enrollHref);
         if (onSignedIn) onSignedIn(destination);
         else window.location.href = destination;
         return;
@@ -92,10 +106,12 @@ export function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showF
       if (r.kind === 'two_factor') {
         setCodeRequest(r.codeRequest);
         setDevCode(r.devCode);
+        setNextStep(r.nextStep);
         setStep('code');
         return;
       }
       setError(r.message);
+      setErrorCode(r.code);
       if (r.kind === 'error') setOfferEmailCode(r.offerEmailCode);
     } finally {
       setBusy(false);
@@ -128,6 +144,7 @@ export function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showF
     setStep('credentials');
     setCodeRequest(NO_CODE_REQUEST);
     setDevCode(null);
+    setNextStep(null);
     setCode('');
     setFieldError(null);
     setError(null);
@@ -156,7 +173,7 @@ export function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showF
 
   const problem = fieldError ?? error;
   const problemLine = problem && (
-    <p role="alert" data-testid="credential-sign-in-error" className="text-sm mt-3" style={{ color: 'var(--color-error, #ef4444)' }}>
+    <p role="alert" data-testid="credential-sign-in-error" data-error-code={fieldError ? 'invalid_input' : (errorCode ?? undefined)} className="text-sm mt-3" style={{ color: 'var(--color-error, #ef4444)' }}>
       {problem}
     </p>
   );
@@ -198,6 +215,7 @@ export function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showF
             {busy ? 'Verifying…' : 'Verify'}
           </button>
         </form>
+        <EnrollAuthenticatorOffer nextStep={enrollHref ? nextStep : null} checked={enrolAfter} onChange={setEnrolAfter} disabled={busy} />
         <button type="button" onClick={onBack} disabled={busy} className="text-sm underline mt-4" style={{ background: 'none', border: 'none', padding: 0, color: 'var(--text-muted, #6b7280)' }}>
           Back
         </button>