@payez/next-mvp 4.13.0 → 4.13.1

package/dist/routes/health.d.ts

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

package/dist/routes/health.js

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

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

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

package/dist/routes/mfa/methods.js

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

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

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

package/dist/routes/passkeys/list.js

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

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

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

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

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

package/dist/utils/api.d.ts

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

package/dist/utils/api.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.13.0",
+  "version": "4.13.1",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -505,6 +505,11 @@
       "require": "./dist/api-handlers/auth/validate.js",
       "default": "./api-handlers/auth/validate.js"
     },
+    "./api-handlers/health": {
+      "types": "./dist/api-handlers/health.d.ts",
+      "require": "./dist/api-handlers/health.js",
+      "default": "./dist/api-handlers/health.js"
+    },
     "./api-handlers/session/refresh-viability": {
       "types": "./dist/api-handlers/session/refresh-viability.d.ts",
       "require": "./dist/api-handlers/session/refresh-viability.js",
@@ -705,6 +710,11 @@
       "require": "./dist/routes/auth/viability.js",
       "default": "./dist/routes/auth/viability.js"
     },
+    "./routes/health": {
+      "types": "./dist/routes/health.d.ts",
+      "require": "./dist/routes/health.js",
+      "default": "./dist/routes/health.js"
+    },
     "./routes/session/refresh-viability": {
       "types": "./dist/routes/session/refresh-viability.d.ts",
       "require": "./dist/routes/session/refresh-viability.js",

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/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/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) {
@@ -241,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
@@ -1596,7 +1608,7 @@ export function authErrorCodeFromLocation(location: string): string | null {
  * ```
  */
 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).
@@ -1711,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/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
@@ -525,4 +526,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/health.ts

@@ -0,0 +1,14 @@
+/**
+ * Ready-to-use /api/health route: reports Redis reachability (PAY-2804).
+ *
+ * @example
+ * ```typescript
+ * // app/api/health/route.ts
+ * export const runtime = 'nodejs';
+ * export { GET } from '@payez/next-mvp/routes/health';
+ * ```
+ */
+import { createHealthHandler } from '../api-handlers/health';
+import { getRedis } from '../lib/redis';
+
+export const GET = createHealthHandler(() => getRedis());

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