@payez/next-mvp 4.12.1 → 4.13.1

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

package/dist/routes/auth/viability.js

@@ -15,7 +15,7 @@
  * @since auth-ready-v2
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GET = GET;
+exports.GET = void 0;
 const revocation_fields_1 = require("../../auth/revocation-fields");
 const server_1 = require("next/server");
 const auth_1 = require("../../server/auth");
@@ -23,6 +23,7 @@ const session_store_1 = require("../../lib/session-store");
 const idp_client_config_1 = require("../../lib/idp-client-config");
 const safe_error_response_1 = require("../../lib/safe-error-response");
 const token_log_id_1 = require("../../lib/token-log-id");
+const no_store_1 = require("../../lib/no-store");
 const sessions_1 = require("../../vibe/sessions");
 /**
  * Get tenant-wide 2FA requirement from cached client config (from broker handshake)
@@ -135,7 +136,7 @@ function resolveClientId(sessionClientId) {
  * - needsRefresh: boolean - Whether a refresh is recommended
  * - expiresIn: number - Seconds until token expires
  */
-async function GET(req) {
+async function getHandler(req) {
     try {
         // PAY-2216: ask for the session's STATE, not a session-or-null. A null used to cover a store outage, a deleted
         // session and no cookie alike, so this route answered 'No session found' to all three and the middleware could
@@ -187,6 +188,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 +282,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).
@@ -486,3 +496,5 @@ 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);

package/dist/routes/health.d.ts

@@ -0,0 +1 @@
+export declare const GET: () => Promise<Response>;

package/dist/routes/health.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GET = void 0;
+/**
+ * Ready-to-use /api/health route: reports Redis reachability (PAY-2804).
+ *
+ * @example
+ * ```typescript
+ * // app/api/health/route.ts
+ * export const runtime = 'nodejs';
+ * export { GET } from '@payez/next-mvp/routes/health';
+ * ```
+ */
+const health_1 = require("../api-handlers/health");
+const redis_1 = require("../lib/redis");
+exports.GET = (0, health_1.createHealthHandler)(() => (0, redis_1.getRedis)());

package/dist/routes/mfa/methods.d.ts

@@ -10,8 +10,8 @@
  * ```
  */
 import { NextRequest } from 'next/server';
-import { GET as listMethods } from '../../api-handlers/mfa/methods';
-export declare const GET: typeof listMethods;
+/** PAY-2994: the user's MFA methods; never cached (noStore). */
+export declare const GET: (req: NextRequest) => Promise<Response>;
 type Ctx = {
     params: Promise<{
         id: string;

package/dist/routes/mfa/methods.js

@@ -3,7 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GET = void 0;
 exports.DELETE = DELETE;
 const methods_1 = require("../../api-handlers/mfa/methods");
-exports.GET = methods_1.GET;
+const no_store_1 = require("../../lib/no-store");
+/** PAY-2994: the user's MFA methods; never cached (noStore). */
+exports.GET = (0, no_store_1.noStore)(methods_1.GET);
 async function DELETE(req, ctx) {
     const { id } = await ctx.params;
     return (0, methods_1.DELETE)(req, id);

package/dist/routes/passkeys/list.d.ts

@@ -1,10 +1,2 @@
-/**
- * Ready-to-Use Passkey List Route
- *
- * @example
- * ```typescript
- * // app/api/passkeys/route.ts
- * export { GET } from '@payez/next-mvp/routes/passkeys/list';
- * ```
- */
-export { GET } from '../../api-handlers/passkeys/list';
+/** PAY-2994: the signed-in user's passkeys; never cached (noStore). */
+export declare const GET: (req: import("next/server").NextRequest) => Promise<Response>;

package/dist/routes/passkeys/list.js

@@ -10,5 +10,7 @@ exports.GET = void 0;
  * export { GET } from '@payez/next-mvp/routes/passkeys/list';
  * ```
  */
-var list_1 = require("../../api-handlers/passkeys/list");
-Object.defineProperty(exports, "GET", { enumerable: true, get: function () { return list_1.GET; } });
+const list_1 = require("../../api-handlers/passkeys/list");
+const no_store_1 = require("../../lib/no-store");
+/** PAY-2994: the signed-in user's passkeys; never cached (noStore). */
+exports.GET = (0, no_store_1.noStore)(list_1.GET);

package/dist/routes/session/refresh-viability.d.ts

@@ -13,4 +13,5 @@
  * @version 2.0.0
  * @since auth-ready-v2
  */
-export { GET } from '../../api-handlers/session/refresh-viability';
+/** PAY-2994: refresh-token viability of this session; never cached (noStore). */
+export declare const GET: (req: import("next/server").NextRequest) => Promise<Response>;

package/dist/routes/session/refresh-viability.js

@@ -16,5 +16,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GET = void 0;
-var refresh_viability_1 = require("../../api-handlers/session/refresh-viability");
-Object.defineProperty(exports, "GET", { enumerable: true, get: function () { return refresh_viability_1.GET; } });
+const refresh_viability_1 = require("../../api-handlers/session/refresh-viability");
+const no_store_1 = require("../../lib/no-store");
+/** PAY-2994: refresh-token viability of this session; never cached (noStore). */
+exports.GET = (0, no_store_1.noStore)(refresh_viability_1.GET);

package/dist/utils/api.d.ts

@@ -49,6 +49,38 @@ export declare const RESET_BREACHED_TEXT = "This password appears in a known dat
  *                 they can retry.
  */
 export declare function resetFailureText(status: number, rules?: string[], policy?: boolean, tokenInvalid?: boolean): string;
+/**
+ * SMS-first sign-up (door 3b): when the phone code is right but the email is still unconfirmed, the server answers 200 success with
+ * `next_step = EMAIL_CONFIRMATION_REQUIRED` and NO reset token. `verifyOnboardingSmsCode` surfaces that as `nextStep`;
+ * `interpretSmsVerification` turns a result into ONE outcome, testing `nextStep` BEFORE `success`, so a consumer that uses it can
+ * never reach "verified" without a reset token or with an unfinished step. The sentences are the package's own, never the server's text.
+ */
+export declare const SMS_NEXT_STEP_EMAIL_CONFIRMATION_REQUIRED = "EMAIL_CONFIRMATION_REQUIRED";
+export declare const SMS_EMAIL_CONFIRMATION_TEXT = "Your phone is verified. Confirm your email to finish signing up.";
+export declare const SMS_MORE_STEPS_TEXT = "One more step is needed to finish signing up.";
+export interface SmsCodeVerification {
+    success: boolean;
+    resetToken: string;
+    email: string;
+    clientKey: string;
+    /** Present when the server says more steps remain (an UNRECOGNISED value is kept as a non-empty string, never dropped). */
+    nextStep?: string;
+}
+export type SmsVerificationOutcome = {
+    kind: 'verified';
+    resetToken: string;
+    email: string;
+    clientKey: string;
+} | {
+    kind: 'email_confirmation_required';
+    message: string;
+} | {
+    kind: 'more_steps';
+    message: string;
+} | {
+    kind: 'not_verified';
+};
+export declare function interpretSmsVerification(result: SmsCodeVerification): SmsVerificationOutcome;
 export declare class AccountApi {
     /**
      * Get masked user info (email, phone, authenticator status)
@@ -90,12 +122,7 @@ export declare class AccountApi {
         email: string;
         clientKey: string;
     }>;
-    verifyOnboardingSmsCode(onboardToken: string, code: string, clientKey?: string): Promise<{
-        success: boolean;
-        resetToken: string;
-        email: string;
-        clientKey: string;
-    }>;
+    verifyOnboardingSmsCode(onboardToken: string, code: string, clientKey?: string): Promise<SmsCodeVerification>;
     setOnboardingPassword(data: {
         onboardToken: string;
         email: string;

package/dist/utils/api.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.accountApi = exports.AccountApi = exports.RESET_BREACHED_TEXT = exports.RESET_NEUTRAL_TEXT = exports.RECOVERY_EXPIRED_TEXT = exports.ApiError = void 0;
+exports.accountApi = exports.AccountApi = exports.SMS_MORE_STEPS_TEXT = exports.SMS_EMAIL_CONFIRMATION_TEXT = exports.SMS_NEXT_STEP_EMAIL_CONFIRMATION_REQUIRED = exports.RESET_BREACHED_TEXT = exports.RESET_NEUTRAL_TEXT = exports.RECOVERY_EXPIRED_TEXT = exports.ApiError = void 0;
 exports.apiFetch = apiFetch;
 exports.resetFailureText = resetFailureText;
+exports.interpretSmsVerification = interpretSmsVerification;
 const standardized_client_api_1 = require("../lib/standardized-client-api");
 const password_rules_1 = require("../lib/password-rules");
 class ApiError extends Error {
@@ -110,6 +111,30 @@ function resetFailureText(status, rules = [], policy = false, tokenInvalid = fal
     }
     return "We couldn't reset your password just now. Please try again.";
 }
+/**
+ * SMS-first sign-up (door 3b): when the phone code is right but the email is still unconfirmed, the server answers 200 success with
+ * `next_step = EMAIL_CONFIRMATION_REQUIRED` and NO reset token. `verifyOnboardingSmsCode` surfaces that as `nextStep`;
+ * `interpretSmsVerification` turns a result into ONE outcome, testing `nextStep` BEFORE `success`, so a consumer that uses it can
+ * never reach "verified" without a reset token or with an unfinished step. The sentences are the package's own, never the server's text.
+ */
+exports.SMS_NEXT_STEP_EMAIL_CONFIRMATION_REQUIRED = 'EMAIL_CONFIRMATION_REQUIRED';
+exports.SMS_EMAIL_CONFIRMATION_TEXT = 'Your phone is verified. Confirm your email to finish signing up.';
+exports.SMS_MORE_STEPS_TEXT = 'One more step is needed to finish signing up.';
+function interpretSmsVerification(result) {
+    // success:false WINS over any step (BAPert 88508): a failed answer must never say "Your phone is verified".
+    if (!result.success)
+        return { kind: 'not_verified' };
+    // For every answer that is not a failure, nextStep comes BEFORE the token test: a step that is not finished is never "verified".
+    if (result.nextStep) {
+        return result.nextStep === exports.SMS_NEXT_STEP_EMAIL_CONFIRMATION_REQUIRED
+            ? { kind: 'email_confirmation_required', message: exports.SMS_EMAIL_CONFIRMATION_TEXT }
+            : { kind: 'more_steps', message: exports.SMS_MORE_STEPS_TEXT };
+    }
+    // success with an EMPTY reset token is the shape that is dangerous (set-password would be called with ''): not verified.
+    if (!result.resetToken)
+        return { kind: 'more_steps', message: exports.SMS_MORE_STEPS_TEXT };
+    return { kind: 'verified', resetToken: result.resetToken, email: result.email, clientKey: result.clientKey };
+}
 class AccountApi {
     /**
      * Get masked user info (email, phone, authenticator status)
@@ -303,11 +328,19 @@ class AccountApi {
         }
         // Extract from nested data structure
         const data = result.data?.data || result.data || {};
+        // next_step (door 3b): read from the nested shapes AND a flat body. Absent / null / '' = no step; a non-string value is an
+        // UNRECOGNISED step and is kept as a non-empty string (never dropped, never mistaken for the known one). That includes false and 0:
+        // a server that means "no step" must send nothing or null (or '').
+        const rawStep = data.next_step ?? result.next_step;
+        const nextStep = rawStep === undefined || rawStep === null || rawStep === ''
+            ? undefined
+            : typeof rawStep === 'string' ? rawStep : 'UNRECOGNISED_NEXT_STEP';
         return {
             success: data.success !== false,
             resetToken: data.reset_token || '',
             email: data.email || '',
-            clientKey: data.client_key || ''
+            clientKey: data.client_key || '',
+            ...(nextStep !== undefined ? { nextStep } : {})
         };
     }
     async setOnboardingPassword(data, clientKey) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.12.1",
+  "version": "4.13.1",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -505,6 +505,11 @@
       "require": "./dist/api-handlers/auth/validate.js",
       "default": "./api-handlers/auth/validate.js"
     },
+    "./api-handlers/health": {
+      "types": "./dist/api-handlers/health.d.ts",
+      "require": "./dist/api-handlers/health.js",
+      "default": "./dist/api-handlers/health.js"
+    },
     "./api-handlers/session/refresh-viability": {
       "types": "./dist/api-handlers/session/refresh-viability.d.ts",
       "require": "./dist/api-handlers/session/refresh-viability.js",
@@ -705,6 +710,11 @@
       "require": "./dist/routes/auth/viability.js",
       "default": "./dist/routes/auth/viability.js"
     },
+    "./routes/health": {
+      "types": "./dist/routes/health.d.ts",
+      "require": "./dist/routes/health.js",
+      "default": "./dist/routes/health.js"
+    },
     "./routes/session/refresh-viability": {
       "types": "./dist/routes/session/refresh-viability.d.ts",
       "require": "./dist/routes/session/refresh-viability.js",
@@ -1084,6 +1094,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": {