@payez/next-mvp 4.12.0 → 4.12.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog — @payez/next-mvp
 
+## 4.12.2 (BACKPORT: to be published under dist-tag `backport` only, never `next` or `latest`; = 4.12.1 + the PAY-2994 no-store commit and nothing else)
+
+A patch cut from the 4.12.1 tree (DevOps commit 603bbcd2, whose src equals the published 4.12.1 tarball file for file). Carries ONE change, so the portal can take the no-store fix without 4.13.0's behaviour changes. 4.13.1 carries the same fix on the 4.13.x line.
+
+- **FIX (PAY-2994): eight GET routes now answer `Cache-Control: no-store` on every response.** The portal's BFF no-store ratchet found that these re-exported routes sent no Cache-Control, though their answers carry per-user data and some carry tokens, so a browser or an intermediate cache could keep them. New internal `lib/no-store` (`noStore(handler)`): it sets `no-store` on whatever the handler returns (errors and redirects too), REPLACES a looser existing value, rebuilds a Response whose headers are immutable (e.g. `Response.redirect`) with status, body and every `Set-Cookie` intact, passes the handler's arguments through, and hands a non-Response back untouched. Wrapped: `api-handlers/account/profile` GET, `api-handlers/anon/preferences` GET, `auth/better-auth` `createAuthGetHandler`, `routes/auth/session` GET, `routes/mfa/methods` GET, `routes/passkeys/list` GET, `routes/session/refresh-viability` GET, `routes/auth/viability` GET; and, as the same data under a second export path, `api-handlers/session/viability` GET and `api-handlers/session/refresh-viability` GET. No other behaviour changes. Package test `test/next-mvp-pay-2994-no-store.test.cjs` calls the REAL compiled GET of each and a mutant (wrapper removed) goes red.
+- **NOT covered (follow-up):** GET answers in `api-handlers/auth/status`, `api-handlers/auth/validate`, `routes/auth/session-reset`, `routes/auth/settings` and `api-handlers/oauth/resume` (a redirect that sets cookies) still send no `no-store`.
+
+## 4.12.1 (to be published under dist-tag `next` only, after 4.12.0; `latest` stays 4.8.9 until Jon says otherwise)
+
+A patch cut from the 4.12.0 tree carrying ONE change: the PAY-2425 hygiene fix below (PR 1500).
+
+- **CHANGE (PAY-2425, hygiene): the refresh no longer invents authentication claims for an OAuth (Google) session.** `lib/ensure-fresh-access-token` answered an OAuth session whose stored authentication methods were empty with `amr ['pwd','mfa']`, `two_factor_method 'oauth'` and an `acr` raised from '1' to '2' ("OAuth IS a form of multi-factor auth"), and echoed a stored `mfaVerified` as `two_factor_verified` whatever the session's methods said. OAuth is federated sign-in, not a second factor (BAPert 77404). The refresh body now carries only what the session records: empty stays empty, `acr` is the session's own level, no method is named from silence, and `two_factor_verified` is sent only when the session's recorded methods contain `mfa`, `sms`, `totp` or `email`. A session that really attests `mfa` still sends it. The IdP ignores these request fields and mints `amr`/`acr` from the stored refresh row, so this removes a false claim from the wire; it does not establish that any bypass existed or is closed. **What changes for a caller:** a Google user on a `require2FA` client is asked for a code, as before, because the IdP decides that; a Google-only client that wants no second factor sets `require2FA = false` explicitly. An earlier version of this fix on `nextpert/375639-amr-fabrication` (e6e3b6c3, e3b3bb12) was never merged; the refresh path has since moved into this helper. Rows: `test/next-mvp-pay-2425-no-fabricated-mfa.test.cjs` (R1/R2/R3, C1, N1 and four mutants).
+
 ## 4.12.0 (to be published under dist-tag `next` only, after 4.11.0; `latest` stays 4.8.9 until Jon says otherwise)
 
 A minor: PII-in-logs groups 1, 2, 3a and 3b, the GOV-023 signout BREAKING change, the logout-401 FIX (PAY-2396), and the BREAKING site-logger signatures (3b: callers of `siteEvents.loginFailed` / `siteEvents.error` must change).

package/dist/api-handlers/account/profile.d.ts

@@ -1,41 +1,4 @@
 import { NextRequest, NextResponse } from 'next/server';
-/**
- * Account Profile API Handler
- *
- * GET /api/account/profile  - Get user profile
- * PUT /api/account/profile  - Update user profile
- *
- * WHY THIS WAS REWRITTEN (2026-08-02, QAPert defect #7)
- * Reported as "/api/account/profile 401s on the same cookie masked-info
- * accepts (200)". Two endpoints disagreeing about one cookie meant two auth
- * implementations, and they were:
- *
- *   masked-info.ts  idpFetchJSON(req, ...)           resolves the caller's token
- *                                                    from the server-side session
- *   profile.ts      req.headers.get('authorization') required an INBOUND bearer
- *
- * A browser sends a session COOKIE and no Authorization header, so the old
- * profile.ts 401'd EVERY browser request by construction. Nothing was revoked
- * and no token was stale — the handler demanded a credential the app does not
- * use.
- *
- * THE OLD AUTH CHECK WAS A VENEER. It tested that the header was PRESENT, never
- * that it was valid, then forwarded it upstream unexamined. Any string at all
- * got past it and the IDP did the real work. It looked like enforcement and
- * enforced nothing.
- *
- * WHAT THE WORKAROUND COST US: consumers could not call this with a cookie, so
- * the graft's useProfile hook fetched the raw IDP access token from
- * /api/session/idp-token INTO BROWSER JAVASCRIPT and re-sent it as a bearer.
- * That defeats the reason idpFetchJSON exists — it keeps the token server-side
- * precisely so client-side script can never hold it. The bearer-only handler
- * did not merely fail; it pushed its callers into exposing the token.
- *
- * Switching to idpFetchJSON makes the cookie work, so the hook's token round
- * trip can be deleted and /api/session/idp-token drops to a single deliberate
- * caller: the jwt-inspect debug page.
- *
- * @package @payez/next-mvp
- */
-export declare function GET(req: NextRequest): Promise<NextResponse<any>>;
+/** PAY-2994: the profile is one person's data; never cached (noStore). */
+export declare const GET: (req: NextRequest) => Promise<Response>;
 export declare function PUT(req: NextRequest): Promise<NextResponse<any>>;

package/dist/api-handlers/account/profile.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GET = GET;
+exports.GET = void 0;
 exports.PUT = PUT;
 const server_1 = require("next/server");
 const idp_fetch_1 = require("../../lib/idp-fetch");
 const env_1 = require("../../config/env");
+const no_store_1 = require("../../lib/no-store");
 /**
  * Account Profile API Handler
  *
@@ -43,7 +44,7 @@ const env_1 = require("../../config/env");
  *
  * @package @payez/next-mvp
  */
-async function GET(req) {
+async function getProfile(req) {
     const result = await (0, idp_fetch_1.idpFetchJSON)(req, `${env_1.ENV_CONFIG.IDP_URL}/api/Account/profile`, {
         method: 'GET',
         headers: { 'Content-Type': 'application/json' },
@@ -61,6 +62,8 @@ async function GET(req) {
     }
     return server_1.NextResponse.json(result.json, { status: 200 });
 }
+/** PAY-2994: the profile is one person's data; never cached (noStore). */
+exports.GET = (0, no_store_1.noStore)(getProfile);
 async function PUT(req) {
     let body = '{}';
     try {

package/dist/api-handlers/anon/preferences.d.ts

@@ -9,19 +9,9 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { AnonSessionPreferences } from '../../lib/anon-session';
 /**
- * GET handler - retrieves anonymous session preferences
+ * POST handler - updates anonymous session preferences
  */
-export declare function GET(request: NextRequest): Promise<NextResponse<{
-    success: boolean;
-    data: {
-        id: string;
-        preferences: AnonSessionPreferences;
-        metrics: import("../../lib/anon-session").AnonSessionMetrics;
-    };
-}> | NextResponse<{
-    success: boolean;
-    error: string;
-}>>;
+export declare const GET: (request: NextRequest) => Promise<Response>;
 /**
  * POST handler - updates anonymous session preferences
  */

package/dist/api-handlers/anon/preferences.js

@@ -8,17 +8,16 @@
  * Sets a cookie to track anonymous visitors and stores preferences in Redis.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GET = GET;
+exports.GET = void 0;
 exports.POST = POST;
 const server_1 = require("next/server");
 const headers_1 = require("next/headers");
 const anon_session_1 = require("../../lib/anon-session");
 const log_safe_1 = require("../../lib/log-safe");
+const no_store_1 = require("../../lib/no-store");
 const COOKIE_MAX_AGE = 90 * 24 * 60 * 60; // 90 days in seconds
-/**
- * GET handler - retrieves anonymous session preferences
- */
-async function GET(request) {
+/** Retrieves anonymous session preferences. Exported as GET below, wrapped in noStore (PAY-2994). */
+async function getPreferences(request) {
     try {
         const cookieStore = await (0, headers_1.cookies)();
         let anonId = cookieStore.get(anon_session_1.ANON_COOKIE_NAME)?.value;
@@ -50,6 +49,10 @@ async function GET(request) {
         return server_1.NextResponse.json({ success: false, error: 'Failed to get preferences' }, { status: 500 });
     }
 }
+/**
+ * POST handler - updates anonymous session preferences
+ */
+exports.GET = (0, no_store_1.noStore)(getPreferences);
 /**
  * POST handler - updates anonymous session preferences
  */

package/dist/api-handlers/session/refresh-viability.d.ts

@@ -1,15 +1,3 @@
-import { NextRequest, NextResponse } from 'next/server';
-export declare function GET(req: NextRequest): Promise<NextResponse<{
-    canRefresh: boolean;
-    reason: string;
-    error: string;
-    code: string;
-}> | NextResponse<{
-    canRefresh: boolean;
-    reason: string;
-    sessionTokenId: string;
-}> | NextResponse<{
-    canRefresh: boolean;
-    reason: string;
-    sessionTokenId: null;
-}>>;
+import { NextRequest } from 'next/server';
+/** PAY-2994 (NightHawk 92964 Low 1): the api-handlers/session/* path is also in the exports map; wrap here too so a consumer importing it is covered. */
+export declare const GET: (req: NextRequest) => Promise<Response>;

package/dist/api-handlers/session/refresh-viability.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GET = GET;
+exports.GET = void 0;
 const server_1 = require("next/server");
 const session_store_1 = require("../../lib/session-store");
 const refresh_token_validator_1 = require("../../lib/refresh-token-validator");
@@ -8,8 +8,9 @@ const test_aware_get_token_1 = require("../../lib/test-aware-get-token");
 const logger_1 = require("../../config/logger");
 const token_log_id_1 = require("../../lib/token-log-id");
 const log_safe_1 = require("../../lib/log-safe");
+const no_store_1 = require("../../lib/no-store");
 const auth_1 = require("../../server/auth");
-async function GET(req) {
+async function getRefreshViability(req) {
     try {
         const sessionToken = req.nextUrl.searchParams.get('token');
         let finalSessionToken = sessionToken;
@@ -59,3 +60,5 @@ async function GET(req) {
         return server_1.NextResponse.json({ canRefresh: false, reason: 'check_error', error: 'Failed to check refresh viability', code: 'INTERNAL_ERROR', correlationId }, { status: 500 });
     }
 }
+/** PAY-2994 (NightHawk 92964 Low 1): the api-handlers/session/* path is also in the exports map; wrap here too so a consumer importing it is covered. */
+exports.GET = (0, no_store_1.noStore)(getRefreshViability);

package/dist/api-handlers/session/viability.d.ts

@@ -3,11 +3,6 @@
  *
  * This API route is called by the middleware to securely check if a session is valid.
  */
-import { NextRequest, NextResponse } from 'next/server';
-export declare function GET(req: NextRequest): Promise<NextResponse<{
-    error: string;
-    message: string;
-    code: string;
-}> | NextResponse<{
-    authenticated: boolean;
-}>>;
+import { NextRequest } from 'next/server';
+/** PAY-2994 (NightHawk 92964 Low 1): the api-handlers/session/* path is also in the exports map; wrap here too so a consumer importing it is covered. */
+export declare const GET: (req: NextRequest) => Promise<Response>;

package/dist/api-handlers/session/viability.js

@@ -5,7 +5,7 @@
  * This API route is called by the middleware to securely check if a session is valid.
  */
 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 session_store_1 = require("../../lib/session-store");
@@ -15,7 +15,8 @@ const idp_client_config_1 = require("../../lib/idp-client-config");
 const token_log_id_1 = require("../../lib/token-log-id");
 const sessions_1 = require("../../vibe/sessions");
 const log_safe_1 = require("../../lib/log-safe");
-async function GET(req) {
+const no_store_1 = require("../../lib/no-store");
+async function getViability(req) {
     try {
         // Ensure initialization is complete (auth signing secret resolved from IDP)
         if (!process.env.BETTER_AUTH_SECRET && !process.env.NEXTAUTH_SECRET) {
@@ -218,3 +219,5 @@ async function GET(req) {
         return server_1.NextResponse.json({ authenticated: false }, { status: 500 });
     }
 }
+/** PAY-2994 (NightHawk 92964 Low 1): the api-handlers/session/* path is also in the exports map; wrap here too so a consumer importing it is covered. */
+exports.GET = (0, no_store_1.noStore)(getViability);

package/dist/auth/better-auth.js

@@ -77,6 +77,7 @@ const single_flight_1 = require("../lib/single-flight");
 const session_store_1 = require("../lib/session-store");
 const token_log_id_1 = require("../lib/token-log-id");
 const log_safe_1 = require("../lib/log-safe");
+const no_store_1 = require("../lib/no-store");
 /**
  * 185121: short sha256 fingerprint for secrets/tokens in log lines — enough
  * to tell "same" from "divergent", never enough to reconstruct. 12 hex chars
@@ -1395,7 +1396,7 @@ async function abortOAuthSignIn(callbackResponse, sessionToken, cookieHeader, lo
  * ```
  */
 function createAuthGetHandler(loginPath = '/account-auth/login') {
-    return async function GET(request) {
+    const get = async function GET(request) {
         // Card 138635: establish the request-scoped carrier for the provider's raw
         // id_token. It must wrap BOTH ba.GET (which invokes getUserInfo, the only
         // hook that sees the token) and the exchange below (which forwards it).
@@ -1496,4 +1497,6 @@ function createAuthGetHandler(loginPath = '/account-auth/login') {
             return response;
         });
     };
+    // PAY-2994: every Better Auth GET answer (session, OAuth callbacks, redirects) is per-user and may set cookies; never cached.
+    return (0, no_store_1.noStore)(get);
 }

package/dist/lib/ensure-fresh-access-token.js

@@ -257,17 +257,18 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
             }
             catch { /* fall through */ }
         }
-        const isOAuthSession = !!session.oauthProvider;
-        if (authMethods.length === 0 && isOAuthSession) {
-            authMethods = ['pwd', 'mfa'];
-        }
+        // PAY-2425 (BAPert 77400, NightHawk 77401): THE CLIENT DOES NOT INFER AUTHENTICATION STRENGTH FROM SILENCE. This block used to answer an OAuth
+        // (Google) session whose stored methods were EMPTY with amr ['pwd','mfa'], a two-factor method of 'oauth' and an acr raised from '1' to '2' ("OAuth IS
+        // a form of multi-factor auth"). That is false: OAuth is federated sign-in, one factor typed at the provider. It fired exactly when the session
+        // could tell us nothing and answered with the strongest claim available; on prod (4.10.0) a Google user on a require2FA client was then counted
+        // 2FA-complete with no code (RigPert 77398). What the session does not attest, the refresh body does not assert: empty stays empty, the level stays
+        // the session's own, and no method is named unless one is recorded. The IdP computes the real amr/acr for the minted token (and mfaVerified is
+        // re-derived from THAT token below); a session that really attests 'mfa' still sends it. History: the fix existed on nextpert/375639-amr-fabrication
+        // (e6e3b6c3, e3b3bb12) and was never merged.
         const twoFactorMethod = authMethods.find(m => ['sms', 'totp', 'email'].includes(m)) ||
             session.mfaMethod ||
-            (isOAuthSession ? 'oauth' : null);
-        let acrValue = String(session.authenticationLevel ?? '1');
-        if (isOAuthSession && session.mfaVerified && acrValue === '1') {
-            acrValue = '2';
-        }
+            null;
+        const acrValue = String(session.authenticationLevel ?? '1');
         // WO-2: send the POST-lock current refresh token, not the pre-lock snapshot.
         // `session` was read before we acquired the lock; a concurrent refresh that
         // completed while we waited rotates the token, so the pre-lock value is stale
@@ -300,7 +301,11 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
             amr: authMethods,
             acr: acrValue,
         };
-        if (session.mfaVerified)
+        // PAY-2425 (NightHawk 77414): a STORED mfaVerified flag is only echoed when the session's own recorded methods back it. Sessions created while the
+        // bug was live carry mfaVerified:true that the bug itself wrote, with no 'mfa' (or sms/totp/email) in their methods; echoing that flag would carry the
+        // poison across the upgrade. A genuine second factor leaves 'mfa' and its method in the recorded methods, so it is still sent.
+        const methodsAttestSecondFactor = authMethods.some(m => m === 'mfa' || ['sms', 'totp', 'email'].includes(m));
+        if (session.mfaVerified && methodsAttestSecondFactor)
             body.two_factor_verified = true;
         if (twoFactorMethod)
             body.two_factor_method = twoFactorMethod;

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/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
@@ -486,3 +487,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.12.0",
+  "version": "4.12.2",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/api-handlers/account/profile.ts

@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { idpFetchJSON } from '../../lib/idp-fetch';
 import { ENV_CONFIG } from '../../config/env';
+import { noStore } from '../../lib/no-store';
 
 /**
  * Account Profile API Handler
@@ -41,7 +42,7 @@ import { ENV_CONFIG } from '../../config/env';
  * @package @payez/next-mvp
  */
 
-export async function GET(req: NextRequest) {
+async function getProfile(req: NextRequest) {
   const result = await idpFetchJSON(req, `${ENV_CONFIG.IDP_URL}/api/Account/profile`, {
     method: 'GET',
     headers: { 'Content-Type': 'application/json' },
@@ -65,6 +66,9 @@ export async function GET(req: NextRequest) {
   return NextResponse.json(result.json, { status: 200 });
 }
 
+/** PAY-2994: the profile is one person's data; never cached (noStore). */
+export const GET = noStore(getProfile);
+
 export async function PUT(req: NextRequest) {
   let body = '{}';
   try {

package/src/api-handlers/anon/preferences.ts

@@ -16,13 +16,12 @@ import {
   AnonSessionPreferences,
 } from '../../lib/anon-session';
 import { errForLog } from '../../lib/log-safe';
+import { noStore } from '../../lib/no-store';
 
 const COOKIE_MAX_AGE = 90 * 24 * 60 * 60; // 90 days in seconds
 
-/**
- * GET handler - retrieves anonymous session preferences
- */
-export async function GET(request: NextRequest) {
+/** Retrieves anonymous session preferences. Exported as GET below, wrapped in noStore (PAY-2994). */
+async function getPreferences(request: NextRequest) {
   try {
     const cookieStore = await cookies();
     let anonId = cookieStore.get(ANON_COOKIE_NAME)?.value;
@@ -61,6 +60,11 @@ export async function GET(request: NextRequest) {
   }
 }
 
+/**
+ * POST handler - updates anonymous session preferences
+ */
+export const GET = noStore(getPreferences);
+
 /**
  * POST handler - updates anonymous session preferences
  */

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

@@ -5,9 +5,10 @@ import { getTokenTestAware } from '../../lib/test-aware-get-token';
 import { logger } from '../../config/logger';
 import { tokenLogId } from '../../lib/token-log-id';
 import { errForLog } from '../../lib/log-safe';
+import { noStore } from '../../lib/no-store';
 import { resolveSessionState } from '../../server/auth';
 
-export async function GET(req: NextRequest) {
+async function getRefreshViability(req: NextRequest) {
   try {
     const sessionToken = req.nextUrl.searchParams.get('token');
     let finalSessionToken = sessionToken;
@@ -55,3 +56,6 @@ export async function GET(req: NextRequest) {
     return NextResponse.json({ canRefresh: false, reason: 'check_error', error: 'Failed to check refresh viability', code: 'INTERNAL_ERROR', correlationId }, { status: 500 });
   }
 }
+
+/** PAY-2994 (NightHawk 92964 Low 1): the api-handlers/session/* path is also in the exports map; wrap here too so a consumer importing it is covered. */
+export const GET = noStore(getRefreshViability);

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

@@ -13,8 +13,9 @@ import { getIDPClientConfig } from '../../lib/idp-client-config';
 import { tokenLogId } from '../../lib/token-log-id';
 import { getRevocationStatus, warnNonNumericUserId, resolveNumericIdpUserId, type RevocationStatus } from '../../vibe/sessions';
 import { errForLog } from '../../lib/log-safe';
+import { noStore } from '../../lib/no-store';
 
-export async function GET(req: NextRequest) {
+async function getViability(req: NextRequest) {
   try {
     // Ensure initialization is complete (auth signing secret resolved from IDP)
     if (!process.env.BETTER_AUTH_SECRET && !process.env.NEXTAUTH_SECRET) {
@@ -237,4 +238,7 @@ export async function GET(req: NextRequest) {
     console.error('[API Viability] Error checking session viability:', errForLog(error));
     return NextResponse.json({ authenticated: false }, { status: 500 });
   }
-}
+}
+
+/** PAY-2994 (NightHawk 92964 Low 1): the api-handlers/session/* path is also in the exports map; wrap here too so a consumer importing it is covered. */
+export const GET = noStore(getViability);

package/src/auth/better-auth.ts

@@ -34,6 +34,7 @@ import { createSingleFlight, type SingleFlight } from '../lib/single-flight';
 import { SESSION_TTL } from '../lib/session-store';
 import { tokenLogId } from '../lib/token-log-id';
 import { errForLog } from '../lib/log-safe';
+import { noStore } from '../lib/no-store';
 
 /**
  * 185121: short sha256 fingerprint for secrets/tokens in log lines — enough
@@ -1582,7 +1583,7 @@ async function abortOAuthSignIn(
  * ```
  */
 export function createAuthGetHandler(loginPath: string = '/account-auth/login') {
-  return async function GET(request: Request): Promise<Response> {
+  const get = async function GET(request: Request): Promise<Response> {
     // Card 138635: establish the request-scoped carrier for the provider's raw
     // id_token. It must wrap BOTH ba.GET (which invokes getUserInfo, the only
     // hook that sees the token) and the exchange below (which forwards it).
@@ -1686,4 +1687,6 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
     return response;
     });
   };
+  // PAY-2994: every Better Auth GET answer (session, OAuth callbacks, redirects) is per-user and may set cookies; never cached.
+  return noStore(get);
 }

package/src/lib/ensure-fresh-access-token.ts

@@ -349,19 +349,20 @@ export async function ensureFreshAccessToken(
     } else if (typeof session.authenticationMethods === 'string') {
       try { authMethods = JSON.parse(session.authenticationMethods); } catch { /* fall through */ }
     }
-    const isOAuthSession = !!session.oauthProvider;
-    if (authMethods.length === 0 && isOAuthSession) {
-      authMethods = ['pwd', 'mfa'];
-    }
+    // PAY-2425 (BAPert 77400, NightHawk 77401): THE CLIENT DOES NOT INFER AUTHENTICATION STRENGTH FROM SILENCE. This block used to answer an OAuth
+    // (Google) session whose stored methods were EMPTY with amr ['pwd','mfa'], a two-factor method of 'oauth' and an acr raised from '1' to '2' ("OAuth IS
+    // a form of multi-factor auth"). That is false: OAuth is federated sign-in, one factor typed at the provider. It fired exactly when the session
+    // could tell us nothing and answered with the strongest claim available; on prod (4.10.0) a Google user on a require2FA client was then counted
+    // 2FA-complete with no code (RigPert 77398). What the session does not attest, the refresh body does not assert: empty stays empty, the level stays
+    // the session's own, and no method is named unless one is recorded. The IdP computes the real amr/acr for the minted token (and mfaVerified is
+    // re-derived from THAT token below); a session that really attests 'mfa' still sends it. History: the fix existed on nextpert/375639-amr-fabrication
+    // (e6e3b6c3, e3b3bb12) and was never merged.
     const twoFactorMethod =
       authMethods.find(m => ['sms', 'totp', 'email'].includes(m)) ||
       session.mfaMethod ||
-      (isOAuthSession ? 'oauth' : null);
+      null;
 
-    let acrValue = String(session.authenticationLevel ?? '1');
-    if (isOAuthSession && session.mfaVerified && acrValue === '1') {
-      acrValue = '2';
-    }
+    const acrValue = String(session.authenticationLevel ?? '1');
 
     // WO-2: send the POST-lock current refresh token, not the pre-lock snapshot.
     // `session` was read before we acquired the lock; a concurrent refresh that
@@ -397,7 +398,11 @@ export async function ensureFreshAccessToken(
       amr: authMethods,
       acr: acrValue,
     };
-    if (session.mfaVerified) body.two_factor_verified = true;
+    // PAY-2425 (NightHawk 77414): a STORED mfaVerified flag is only echoed when the session's own recorded methods back it. Sessions created while the
+    // bug was live carry mfaVerified:true that the bug itself wrote, with no 'mfa' (or sms/totp/email) in their methods; echoing that flag would carry the
+    // poison across the upgrade. A genuine second factor leaves 'mfa' and its method in the recorded methods, so it is still sent.
+    const methodsAttestSecondFactor = authMethods.some(m => m === 'mfa' || ['sms', 'totp', 'email'].includes(m));
+    if (session.mfaVerified && methodsAttestSecondFactor) body.two_factor_verified = true;
     if (twoFactorMethod) body.two_factor_method = twoFactorMethod;
     if (session.mfaCompletedAt) body.two_factor_completed_at = new Date(session.mfaCompletedAt).toISOString();
 

package/src/lib/no-store.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 const NO_STORE_VALUE = 'no-store';
+
+export function withNoStoreHeader(res: Response): Response {
+  // 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 as { headers?: unknown }).headers) return res;
+  try {
+    res.headers.set('Cache-Control', 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', NO_STORE_VALUE);
+    return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+  }
+}
+
+export function noStore<A extends unknown[], R extends Response>(handler: (...args: A) => R | Promise<R>): (...args: A) => Promise<Response> {
+  return async (...args: A) => withNoStoreHeader(await handler(...args));
+}

package/src/routes/auth/session.ts

@@ -13,6 +13,7 @@
  * @since auth-ready-v2
  */
 
+import { noStore } from '../../lib/no-store';
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession as getBetterAuthSession } from '../../server/auth';
 import { getSession as getRedisSession, updateSession } from '../../lib/session-store';
@@ -27,7 +28,7 @@ import { tokenLogId } from '../../lib/token-log-id';
  * - Token expiry status
  * - Session validity
  */
-export async function GET(req: NextRequest) {
+async function getHandler(req: NextRequest) {
   try {
     const authSession = await getBetterAuthSession(req);
 
@@ -121,6 +122,9 @@ export async function GET(req: NextRequest) {
   }
 }
 
+/** PAY-2994: session state is per-user and some answers carry tokens; never cached (noStore). */
+export const GET = 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/src/routes/auth/viability.ts

@@ -24,6 +24,7 @@ import {
 import { getIDPClientConfig } from '../../lib/idp-client-config';
 import { logExceptionWithCorrelation } from '../../lib/safe-error-response';
 import { tokenLogId } from '../../lib/token-log-id';
+import { noStore } from '../../lib/no-store';
 import { getRevocationStatus, warnNonNumericUserId, resolveNumericIdpUserId, type RevocationStatus } from '../../vibe/sessions';
 
 /**
@@ -141,7 +142,7 @@ function resolveClientId(sessionClientId: string | undefined): string | null {
  * - needsRefresh: boolean - Whether a refresh is recommended
  * - expiresIn: number - Seconds until token expires
  */
-export async function GET(req: NextRequest) {
+async function getHandler(req: NextRequest) {
   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
@@ -517,4 +518,7 @@ export async function GET(req: NextRequest) {
       correlationId
     }, { status: 500 });
   }
-}
+}
+
+/** PAY-2994: session state is per-user and some answers carry tokens; never cached (noStore). */
+export const GET = noStore(getHandler);

package/src/routes/mfa/methods.ts

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

package/src/routes/passkeys/list.ts

@@ -7,4 +7,8 @@
  * export { GET } from '@payez/next-mvp/routes/passkeys/list';
  * ```
  */
-export { GET } from '../../api-handlers/passkeys/list';
+import { GET as listPasskeys } from '../../api-handlers/passkeys/list';
+import { noStore } from '../../lib/no-store';
+
+/** PAY-2994: the signed-in user's passkeys; never cached (noStore). */
+export const GET = noStore(listPasskeys);

package/src/routes/session/refresh-viability.ts

@@ -14,4 +14,8 @@
  * @since auth-ready-v2
  */
 
-export { GET } from '../../api-handlers/session/refresh-viability';
+import { GET as refreshViability } from '../../api-handlers/session/refresh-viability';
+import { noStore } from '../../lib/no-store';
+
+/** PAY-2994: refresh-token viability of this session; never cached (noStore). */
+export const GET = noStore(refreshViability);