@payez/next-mvp 4.13.0 → 4.13.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog — @payez/next-mvp
 
+## Unreleased
+
+- **ADDITIVE (MINOR when released): SMS-first sign-up learns the `EMAIL_CONFIRMATION_REQUIRED` step (BAPert 88395 #2, 88454 #3; NextPert 88471).** The server (door 3b) now answers `verify-sms-code` with 200 success, `next_step = EMAIL_CONFIRMATION_REQUIRED` and NO reset token when the email is still unconfirmed. Before this, `accountApi.verifyOnboardingSmsCode` returned `{ success: true, resetToken: '' }` for that answer, which a consumer reads as "verified" and then calls set-password with an EMPTY token. Now: (a) the result type is the exported `SmsCodeVerification` and gains an OPTIONAL `nextStep` (`nextStep` ALONE is read from the nested shapes AND from a flat body; `reset_token`, `email` and `client_key` are still read from the nested shapes only, as before, so a consumer behind a proxy that forwards a flat body gets no token and the helper then says `more_steps`, the safe direction; absent / null / '' = no step; any other value, including `false`, `0` and a non-string, is kept as a non-empty UNRECOGNISED string, never dropped, so a server that means "no step" must send nothing or null); (b) new pure `interpretSmsVerification(result)` returns `verified` (only with a non-empty reset token and no step), `email_confirmation_required` (the package sentence "Your phone is verified. Confirm your email to finish signing up.", no error styling), `more_steps` ("One more step is needed to finish signing up." for ANY other step, and for success with an empty reset token) or `not_verified`; `success: false` WINS over any step (`not_verified`, so a failed answer never says "Your phone is verified"), and for every other answer it tests `nextStep` BEFORE the token; the sentences are the package's own, never the server's text. **The method itself still returns the server's `success` unchanged: a consumer MUST use `interpretSmsVerification` (or test `nextStep` first) and must not treat `success` alone as "verified", because `success: true` with an empty `resetToken` is what the server now sends for the unconfirmed-email case.** No breaking type change: a consumer that ignores `nextStep` compiles unchanged (test S6), and the email variant `verifyOnboardingCode` is untouched. **A consumer must adopt `interpretSmsVerification` (or branch on `nextStep` itself) to show the new screen; until it does, it behaves as before.** There is no SMS-first page in this package: the screen lives in the consuming sites, so the deploy of the server change (PR 85) waits on every live consumer taking this release. Tests: `test/sms-next-step.test.cjs` (32), `test/sms-next-step-mutants.test.cjs` (9 hand mutants, one per branch).
+
+## 4.13.1 (to be published under dist-tag `next` only, after 4.13.0; `latest` stays 4.8.9 until Jon says otherwise)
+
+A patch: ONE change, the PAY-2994 no-store fix for 8 GET routes (re-cut on GitHub from DevOps PR 1757, BAPert 92969; the DevOps repo is frozen).
+
+- **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 (NightHawk 92964 Low 1), `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, so the next ratchet run is expected, NightHawk 92964 Low 2):** 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`. They were not in the ratchet's finding.
+
 ## 4.13.0 (2026-11-05; published under dist-tag `next` only, after 4.12.1; `latest` stays 4.8.9 until Jon says otherwise)
 
 A minor. Numbered 4.13.0 because everything new is additive or opt-in and no export was removed (two exports were added: `./components/mfa/TotpEnrollPanel` and `./dist/pages/enroll`), but three changes alter behaviour for every consumer and are listed first so nobody is surprised. Built from GitHub `keelsecurity/keelauth-next` main (the code is e0ccb0b9; this release commit changes only this file and the version). Base: 4.12.1 (PR 1500 only). PR numbers are the GitHub-era numbers where the PR was opened after the cutover, else the ADO number. Consumers keep their own pins: nothing here bumps or pins any consumer, and the portal stays on 4.12.1 until its owner says otherwise.
@@ -42,6 +53,7 @@ Not covered: Safari/Firefox (Chromium only), non-browser clients and browsers th
 
 ## Earlier entries now rolled into 4.13.0 (previously "Unreleased: PAY-2568 / PAY-2279, draft PR; no release, no pin")
 
+
 - **CHANGE: a failed credential sign-in shows a fixed sentence chosen by a stable code, never the server text.** `lib/sign-in-failure` is one closed table: `invalid_credentials` ("Incorrect email or password.", wrong password, unknown account and any other refusal, identical), `not_a_member` (the IdP code `NotAMemberOfThisApp` at any HTTP status - the public door relays it as 400 - shown only to someone who proved the credentials), `too_many_attempts` (429, `AccountLocked`, `UserLockedOut`, one sentence for all). `/api/auth/admin-login` now answers `code` + the fixed sentence in `error`; the browser client takes the sentence from the table by code and ignores the body text (an unmapped refusal gets one generic sentence, `sign_in_failed`). Each rendered error carries `data-error-code` (form and login page). Allowlisted policy refusals (SsoRequired, InvalidRequest) still show their detail under code `policy_message`, as a plain text node, at most 200 characters (BAPert 85432); no other server text reaches the page. **What changes for a caller:** the 429 sentence and the `?error=CredentialsSignin` sentence changed; a custom UI that read `body.error` still gets a fixed sentence there. Rows: `test/signin-failure-copy.test.cjs` S1-S7 (RED on master, six mutants).
 - **FIX: the code step of a credential sign-in (wrong, unavailable, locked) shows its own sentence again (BAPert 85795).** The code-step branch of `api-handlers/auth/credential-login` sent no `code`, so after the change above every second-factor refusal fell to the generic "Could not sign in. Check your details and try again.", including the "problem on our side, not with your code" answer. The branch now sends `invalid_second_factor` ("That code is not correct. Check the code and try again."), `second_factor_unavailable` (the existing our-side sentence, with the Email-me-a-code offer kept) or `too_many_attempts`, chosen by the existing `classifyTwofaRejection` and never from IdP wording. The lockout sentence now states the window: `Too many sign-in attempts. Try again in N minutes, or reset your password.`, N = the server's `retryAfter` (seconds) rounded up to whole minutes and clamped to 1..60; with no usable number it stays the plain sentence (only a number is ever printed). The password-step 429 no longer invents a `retryAfter` of 60 when the IdP sent no Retry-After. A plain IdP 429 on the code step (a lane rate limit, not a `locked` lockout) has its own code `second_factor_rate_limited`: "Too many attempts. Try again in N minutes." (same N rule; plain fallback "Too many attempts. Wait a few minutes and try again."), so it no longer tells a user to reset their password; it makes no claim that the code is still valid (unproven here), and `twofa-rejection` no longer invents a 60 s `retryAfter`. Sentences lost by the 1719 regression in this lane: the wrong-code sentence, the our-side-fault sentence (with its Email-me-a-code offer text) and the lockout window. Test: `test/second-factor-copy.test.cjs` (T1-T15, mutants RED).
 

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

@@ -8,23 +8,10 @@
  */
 import { NextRequest, NextResponse } from 'next/server';
 import { AnonSessionPreferences } from '../../lib/anon-session';
-/**
- * GET handler - retrieves 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;
-}>>;
 /**
  * POST handler - updates anonymous session preferences
  */
+export declare const GET: (request: NextRequest) => Promise<Response>;
 export declare function POST(request: NextRequest): Promise<NextResponse<{
     success: boolean;
     error: string;

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;
@@ -53,6 +52,7 @@ async function GET(request) {
 /**
  * POST handler - updates anonymous session preferences
  */
+exports.GET = (0, no_store_1.noStore)(getPreferences);
 async function POST(request) {
     try {
         const cookieStore = await (0, headers_1.cookies)();

package/dist/api-handlers/health.d.ts

@@ -0,0 +1,5 @@
+export interface HealthRedis {
+    ping(): Promise<unknown>;
+}
+export type RedisState = 'up' | 'down' | 'unknown';
+export declare function createHealthHandler(getRedis: () => HealthRedis): () => Promise<Response>;

package/dist/api-handlers/health.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHealthHandler = createHealthHandler;
+/**
+ * /api/health handler (PAY-2804, AUTH-045; BAPert ruling 88065).
+ *
+ * Sessions are Redis-only. The body reports state ONLY: `redis: 'up' | 'down' | 'unknown'` and
+ * `status: 'ok' | 'degraded'`. No REDIS_URL, host, port, error text or stack, to any caller (anonymous route).
+ *
+ * The HTTP status is 200 even when Redis is down: this route is the ALB target-group check, and a 503
+ * there would make the ALB pull every task for an outage that replacing tasks cannot fix.
+ * HEALTH_REDIS_FAILS_STATUS=1 turns Redis-down into 503 as a READINESS setting for a deployer's OWN probe;
+ * it is default off and must never be set on a load-balancer health check.
+ */
+const server_1 = require("next/server");
+const PING_BUDGET_MS = 2000;
+async function probe(redis) {
+    let timer;
+    try {
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error('ping timeout')), PING_BUDGET_MS);
+        });
+        await Promise.race([redis.ping(), timeout]);
+        return 'up';
+    }
+    catch {
+        return 'down';
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function createHealthHandler(getRedis) {
+    return async function GET() {
+        let redis;
+        let client;
+        try {
+            client = getRedis();
+        }
+        catch {
+            client = undefined;
+        }
+        redis = client ? await probe(client) : 'unknown';
+        const failsStatus = process.env.HEALTH_REDIS_FAILS_STATUS === '1';
+        return server_1.NextResponse.json({ status: redis === 'up' ? 'ok' : 'degraded', redis }, { status: redis !== 'up' && failsStatus ? 503 : 200, headers: { 'Cache-Control': 'no-store' } });
+    };
+}

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) {
@@ -222,3 +223,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-exposure.d.ts

@@ -0,0 +1,11 @@
+export declare const MAGIC_LINK_ADVISORY = "GHSA-965c-763c-88jm";
+export declare const MAGIC_LINK_FIX_VERSION = "1.7.7";
+/** The installed better-auth version, read from its own package.json (the package does not export './package.json'), or null when it cannot be found. */
+export declare function installedBetterAuthVersion(): string | null;
+/** True when `version` is strictly below `floor` (numeric major.minor.patch; a pre-release suffix is ignored). An unparseable version is NOT proven fixed, so it counts as below. */
+export declare function versionBelow(version: string | null, floor: string): boolean;
+/**
+ * Warn when the magic-link plugin is enabled on a better-auth below the fix. Returns whether it warned (so a test can assert it). `warn` and `version` are
+ * injectable for the same reason.
+ */
+export declare function warnIfMagicLinkBelowFix(magicLinkEnabled: boolean, warn?: (msg: string) => void, version?: string | null): boolean;

package/dist/auth/better-auth-exposure.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAGIC_LINK_FIX_VERSION = exports.MAGIC_LINK_ADVISORY = void 0;
+exports.installedBetterAuthVersion = installedBetterAuthVersion;
+exports.versionBelow = versionBelow;
+exports.warnIfMagicLinkBelowFix = warnIfMagicLinkBelowFix;
+/**
+ * PAY-2592 slice 1: the exposure guard for better-auth GHSA-965c-763c-88jm (critical, CVSS 9.1; affected >=1.4.0-beta.18 <1.7.7).
+ *
+ * "OAuth state can be used as a Magic Link to sign in as another user." It needs ALL of: the Magic Link plugin enabled, an OAuth provider, and OAuth state
+ * stored with `account.storeStateStrategy: "database"` (better-auth's default when a database OR secondaryStorage exists). This package has secondaryStorage,
+ * so what keeps it unexposed is, today:
+ *   1. `account.storeStateStrategy: 'cookie'` is pinned in better-auth.ts (the advisory: cookie-backed state blocks the path), and
+ *   2. the magic-link plugin registers ONLY when a consumer passes `opts.magicLink`.
+ * Nothing in this package fixes the flaw; the fix is better-auth >= 1.7.7 (PAY-2592, spike pending). Until then a consumer that turns the plugin on is told, loudly,
+ * once per process.
+ *
+ * test/next-mvp-pay-2592-exposure-pins.test.cjs holds both conditions and this warning.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+exports.MAGIC_LINK_ADVISORY = 'GHSA-965c-763c-88jm';
+exports.MAGIC_LINK_FIX_VERSION = '1.7.7';
+/** The installed better-auth version, read from its own package.json (the package does not export './package.json'), or null when it cannot be found. */
+function installedBetterAuthVersion() {
+    try {
+        let dir = (0, node_path_1.dirname)(require.resolve('better-auth'));
+        for (let i = 0; i < 8; i++) {
+            try {
+                const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, 'package.json'), 'utf8'));
+                if (pkg.name === 'better-auth' && typeof pkg.version === 'string')
+                    return pkg.version;
+            }
+            catch {
+                /* no package.json at this level */
+            }
+            const up = (0, node_path_1.dirname)(dir);
+            if (up === dir)
+                break;
+            dir = up;
+        }
+    }
+    catch {
+        /* unresolvable */
+    }
+    return null;
+}
+/** True when `version` is strictly below `floor` (numeric major.minor.patch; a pre-release suffix is ignored). An unparseable version is NOT proven fixed, so it counts as below. */
+function versionBelow(version, floor) {
+    const parse = (v) => /^(\d+)\.(\d+)\.(\d+)/.exec(v)?.slice(1, 4).map(Number) ?? null;
+    const a = version ? parse(version) : null;
+    const b = parse(floor);
+    if (!a || !b)
+        return true;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] < b[i];
+    }
+    return false;
+}
+/**
+ * Warn when the magic-link plugin is enabled on a better-auth below the fix. Returns whether it warned (so a test can assert it). `warn` and `version` are
+ * injectable for the same reason.
+ */
+function warnIfMagicLinkBelowFix(magicLinkEnabled, warn = (m) => console.warn(m), version = installedBetterAuthVersion()) {
+    if (!magicLinkEnabled)
+        return false;
+    if (!versionBelow(version, exports.MAGIC_LINK_FIX_VERSION))
+        return false;
+    warn(`[BETTER_AUTH] WARNING ${exports.MAGIC_LINK_ADVISORY} (critical): the magic-link plugin is enabled on better-auth ${version ?? '(version unknown)'}, below the fix ${exports.MAGIC_LINK_FIX_VERSION}. ` +
+        `This package keeps account.storeStateStrategy='cookie', which blocks the attack; do NOT change that while magic link is on, and upgrade better-auth (PAY-2592).`);
+    return true;
+}

package/dist/auth/better-auth.js

@@ -78,6 +78,10 @@ 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 better_auth_exposure_1 = require("./better-auth-exposure");
+const no_store_1 = require("../lib/no-store");
+/** PAY-2592: the magic-link advisory warning fires once per process. */
+let magicLinkAdvisoryWarned = false;
 /**
  * 185121: short sha256 fingerprint for secrets/tokens in log lines — enough
  * to tell "same" from "divergent", never enough to reconstruct. 12 hex chars
@@ -489,6 +493,12 @@ function buildBetterAuthProviders(config) {
 function createBetterAuthInstance(idpConfig, opts = {}) {
     (0, app_slug_1.assertAppSlugMatchesIdp)(idpConfig.clientSlug);
     const appSlug = idpConfig.clientSlug || (0, app_slug_1.getAppSlug)();
+    // PAY-2592 (GHSA-965c-763c-88jm): a consumer that enables the magic-link plugin on a better-auth below 1.7.7 is told, once per process. What keeps the
+    // package unexposed is account.storeStateStrategy='cookie' below plus the plugin being opt-in; see better-auth-exposure.ts.
+    if (opts.magicLink && !magicLinkAdvisoryWarned) {
+        magicLinkAdvisoryWarned = true;
+        (0, better_auth_exposure_1.warnIfMagicLinkBelowFix)(true);
+    }
     // 185121 line 1: name the secret this instance PINNED, as a hash, never the
     // secret. 183047's surviving fork is HMAC-fail vs record-miss; an HMAC-fail
     // caused by a divergent secret is only diagnosable if every instance
@@ -1410,7 +1420,7 @@ function authErrorCodeFromLocation(location) {
  * ```
  */
 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).
@@ -1523,4 +1533,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/auth/route-config.js

@@ -75,6 +75,15 @@ const defaultUnauthenticatedRoutes = [
         allowDuringCircuitBreakerOpen: true,
         requiresRateLimit: false
     },
+    {
+        // PAY-2804: the exact path. '/api/health/*' matches startsWith('/api/health/'), which the bare
+        // '/api/health' (the ALB check) does not, so without this entry it sat behind sign-in.
+        pattern: '/api/health',
+        description: 'Health check endpoint (ALB target; anonymous, state only)',
+        allowDuringCircuitBreakerOpen: true,
+        // An ALB check comes from few IPs: a rate limit here would answer 429 and get tasks pulled (NightHawk 89179).
+        requiresRateLimit: false
+    },
     {
         pattern: '/api/health/*',
         description: 'Health check endpoints',

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
@@ -495,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);