@payez/next-mvp 4.12.1 → 4.13.1

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;
@@ -64,6 +63,8 @@ export async function GET(request: NextRequest) {
 /**
  * POST handler - updates anonymous session preferences
  */
+export const GET = noStore(getPreferences);
+
 export async function POST(request: NextRequest) {
   try {
     const cookieStore = await cookies();

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

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

package/src/api-handlers/health.ts

@@ -0,0 +1,53 @@
+/**
+ * /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.
+ */
+import { NextResponse } from 'next/server';
+
+export interface HealthRedis {
+  ping(): Promise<unknown>;
+}
+
+export type RedisState = 'up' | 'down' | 'unknown';
+
+const PING_BUDGET_MS = 2000;
+
+async function probe(redis: HealthRedis): Promise<RedisState> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const timeout = new Promise<never>((_, 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);
+  }
+}
+
+export function createHealthHandler(getRedis: () => HealthRedis) {
+  return async function GET(): Promise<Response> {
+    let redis: RedisState;
+    let client: HealthRedis | undefined;
+    try {
+      client = getRedis();
+    } catch {
+      client = undefined;
+    }
+    redis = client ? await probe(client) : 'unknown';
+    const failsStatus = process.env.HEALTH_REDIS_FAILS_STATUS === '1';
+    return NextResponse.json(
+      { status: redis === 'up' ? 'ok' : 'degraded', redis },
+      { status: redis !== 'up' && failsStatus ? 503 : 200, headers: { 'Cache-Control': 'no-store' } },
+    );
+  };
+}

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

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

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

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

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

@@ -0,0 +1,69 @@
+/**
+ * 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.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const MAGIC_LINK_ADVISORY = 'GHSA-965c-763c-88jm';
+export 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 function installedBetterAuthVersion(): string | null {
+  try {
+    let dir = dirname(require.resolve('better-auth'));
+    for (let i = 0; i < 8; i++) {
+      try {
+        const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { name?: string; version?: string };
+        if (pkg.name === 'better-auth' && typeof pkg.version === 'string') return pkg.version;
+      } catch {
+        /* no package.json at this level */
+      }
+      const up = 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. */
+export function versionBelow(version: string | null, floor: string): boolean {
+  const parse = (v: string) => /^(\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.
+ */
+export function warnIfMagicLinkBelowFix(
+  magicLinkEnabled: boolean,
+  warn: (msg: string) => void = (m) => console.warn(m),
+  version: string | null = installedBetterAuthVersion(),
+): boolean {
+  if (!magicLinkEnabled) return false;
+  if (!versionBelow(version, MAGIC_LINK_FIX_VERSION)) return false;
+  warn(
+    `[BETTER_AUTH] WARNING ${MAGIC_LINK_ADVISORY} (critical): the magic-link plugin is enabled on better-auth ${version ?? '(version unknown)'}, below the fix ${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/src/auth/better-auth.ts

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

@@ -92,6 +92,15 @@ const defaultUnauthenticatedRoutes: UnauthenticatedRouteConfig[] = [
     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/src/auth/session-reset-link.ts

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

package/src/components/auth/CredentialSignInForm.tsx

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