@payez/next-mvp 4.13.0 → 4.14.0

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

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/first-enrol-confirm.d.ts

@@ -0,0 +1,10 @@
+/**
+ * AUTH-045 first-enrolment: confirm the first authenticator code, clear the enrolment cookie, return the recovery codes. Mints no session.
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/first-enrol/confirm/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/first-enrol-confirm';
+ * ```
+ */
+export { POST_CONFIRM as POST } from '../../api-handlers/mfa/first-enrol';

package/dist/routes/mfa/first-enrol-confirm.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+/**
+ * AUTH-045 first-enrolment: confirm the first authenticator code, clear the enrolment cookie, return the recovery codes. Mints no session.
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/first-enrol/confirm/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/first-enrol-confirm';
+ * ```
+ */
+var first_enrol_1 = require("../../api-handlers/mfa/first-enrol");
+Object.defineProperty(exports, "POST", { enumerable: true, get: function () { return first_enrol_1.POST_CONFIRM; } });

package/dist/routes/mfa/first-enrol-enroll.d.ts

@@ -0,0 +1,10 @@
+/**
+ * AUTH-045 first-enrolment: begin TOTP enrolment for a user the IdP told to enrol (uses ONLY the httpOnly enrolment cookie the credential door parked).
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/first-enrol/enroll/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/first-enrol-enroll';
+ * ```
+ */
+export { POST_ENROLL as POST } from '../../api-handlers/mfa/first-enrol';

package/dist/routes/mfa/first-enrol-enroll.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+/**
+ * AUTH-045 first-enrolment: begin TOTP enrolment for a user the IdP told to enrol (uses ONLY the httpOnly enrolment cookie the credential door parked).
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/first-enrol/enroll/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/first-enrol-enroll';
+ * ```
+ */
+var first_enrol_1 = require("../../api-handlers/mfa/first-enrol");
+Object.defineProperty(exports, "POST", { enumerable: true, get: function () { return first_enrol_1.POST_ENROLL; } });

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.14.0",
   "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",
@@ -980,6 +990,16 @@
       "require": "./dist/routes/mfa/totp-confirm.js",
       "default": "./dist/routes/mfa/totp-confirm.js"
     },
+    "./routes/mfa/first-enrol-enroll": {
+      "types": "./dist/routes/mfa/first-enrol-enroll.d.ts",
+      "require": "./dist/routes/mfa/first-enrol-enroll.js",
+      "default": "./dist/routes/mfa/first-enrol-enroll.js"
+    },
+    "./routes/mfa/first-enrol-confirm": {
+      "types": "./dist/routes/mfa/first-enrol-confirm.d.ts",
+      "require": "./dist/routes/mfa/first-enrol-confirm.js",
+      "default": "./dist/routes/mfa/first-enrol-confirm.js"
+    },
     "./routes/mfa/totp-verify": {
       "types": "./dist/routes/mfa/totp-verify.d.ts",
       "require": "./dist/routes/mfa/totp-verify.js",
@@ -1090,6 +1110,11 @@
       "require": "./dist/components/mfa/TotpEnrollPanel.js",
       "default": "./dist/components/mfa/TotpEnrollPanel.js"
     },
+    "./dist/pages/first-enroll": {
+      "types": "./dist/pages/first-enroll/page.d.ts",
+      "require": "./dist/pages/first-enroll/page.js",
+      "default": "./dist/pages/first-enroll/page.js"
+    },
     "./dist/pages/enroll": {
       "types": "./dist/pages/enroll/page.d.ts",
       "require": "./dist/pages/enroll/page.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/auth/credential-login.ts

@@ -49,6 +49,8 @@ import { DEVICE_ID_HEADER, isValidDeviceId } from '../../lib/device-id';
 import { classifyTwofaRejection, type TwofaLaneResult } from '../../lib/twofa-rejection';
 import { bearerFetch } from '../../lib/bearer-fetch';
 import { errForLog } from '../../lib/log-safe';
+// AUTH-045: the httpOnly cookie that carries the enrolment-scoped token from the code turn to the two enrolment routes (ONE name, defined in lib/first-enrol).
+import { ENROL_COOKIE, ENROL_COOKIE_MAX_AGE } from '../../lib/first-enrol';
 
 // `export const runtime = 'nodejs'` must be written LITERALLY in the app's route file (Next ignores a re-exported segment config).
 
@@ -348,6 +350,53 @@ export async function POST(req: NextRequest) {
     const vresult = verifyData?.data?.result ?? verifyData?.data ?? verifyData;
     const vAccess: string | undefined = vresult?.access_token;
     const vRefresh: string | undefined = vresult?.refresh_token;
+    // PAY-3083 (AUTH-045): ACCESS WITHOUT REFRESH AT THE CODE TURN IS NOT A FAILURE - IT IS ENROLMENT.
+    //
+    // The IdP withholds the refresh token for a user who has no usable second factor on THIS client.
+    // TOTP enrolment is PER CLIENT (DotNetPert 99446 sec A, client 90717 / user 1175): the password turn
+    // answered Require2FA=true, IssueRefreshToken=false, step=enroll_mfa, and this verify turn then
+    // accepted the emailed code as CONTACT PROOF and issued an ENROLMENT-SCOPED access token, again with
+    // no refresh token. That is exactly what PAY-2798 requires of the IdP - the IdP is RIGHT.
+    //
+    // This branch used to read "access, no refresh" as an incomplete response and answer 502, so the
+    // developer who had just proved their contact was told the server was broken and could never reach
+    // the enrolment page: the 502 the field saw as
+    //   '[ADMIN-LOGIN] verify response missing token { hasAccess: true, hasRefresh: false }'.
+    //
+    // Send them to ENROLMENT instead, in the ONE contract the door and the form already share for it
+    // (PAY-2630): requiresTwoFactor + nextStep 'enroll_mfa'. No session is minted - an enrolment-scoped
+    // token is not a signed-in session - and the token value is NEVER logged nor echoed (BAPert 99521 #2).
+    //
+    // Guard kept: no access token AT ALL (a refresh-only or empty body) is still a broken success and
+    // still 502 below - this widening is only for a genuine access-with-no-refresh answer.
+    if (vAccess && !vRefresh) {
+      const step = vresult?.next_step === 'enroll_mfa' || vresult?.next_step === 'mfa_verify' ? vresult.next_step : 'enroll_mfa';
+      const enrolling = step === 'enroll_mfa';
+      const answer = NextResponse.json(
+        {
+          success: false,
+          requiresTwoFactor: true,
+          acceptedFactors: acceptedFactorsFor('email'),
+          sentVia: null,
+          codeRequested: false,
+          emailSent: false,
+          nextStep: step,
+          // AUTH-045 (walk 14 Nov 2026): requiresTwoFactor alone is also the password turn's "a code was sent", so the form re-drew the code box
+          // and looped. This flag is the ONLY signal that means "go enrol"; it is set on this answer and nowhere else.
+          ...(enrolling ? { enrolmentRequired: true } : {}),
+        },
+        { status: 200 },
+      );
+      if (enrolling) {
+        // No session exists for an enrolment-scoped token, and the enrolment page's actions need one, so the token rides in this httpOnly
+        // cookie to the enrolment routes (the portal's PAY-2798 part 2 pattern): never in a body, a URL or a log; strict; 600 s.
+        answer.cookies.set(ENROL_COOKIE, vAccess, { httpOnly: true, secure: process.env.NODE_ENV === 'production', sameSite: 'strict', path: '/', maxAge: ENROL_COOKIE_MAX_AGE });
+        // The provisional bearer is spent: the enrolment token replaces it.
+        answer.cookies.set('adm2fa', '', { path: '/', maxAge: 0 });
+        answer.cookies.set('adm2fa_lane', '', { path: '/', maxAge: 0 });
+      }
+      return answer;
+    }
     if (!vAccess || !vRefresh) {
       console.error('[ADMIN-LOGIN] verify response missing tokens', { hasAccess: !!vAccess, hasRefresh: !!vRefresh });
       return NextResponse.json({ success: false, error: 'Authentication service returned an incomplete response' }, { status: 502 });

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/first-enrol.ts

@@ -0,0 +1,55 @@
+import { createHash } from 'node:crypto';
+import { NextRequest, NextResponse } from 'next/server';
+import { getIDPClientConfig } from '../../lib/idp-client-config';
+import { resolveClientKey } from '../../lib/client-key';
+import { NO_STORE, refuseNonJson } from '../../lib/mfa-json-guard';
+import { ENROL_COOKIE, LIMIT_PER_COOKIE, attemptAllowed, runEnrolStep, type EnrolStep } from '../../lib/first-enrol';
+
+/**
+ * AUTH-045 first-enrolment carry (PAY-2938, BAPert 100969 rows 3-5): the TWO routes a user the IdP told to enrol uses, built on lib/first-enrol.
+ *
+ * WHO MAY CALL: the browser that holds the httpOnly enrolment cookie the credential door parked (ENROL_COOKIE). This is the ONLY module besides the
+ * door that reads that cookie, and it serves ONLY these two operations; every other package route stays session-gated and answers 401 to a caller
+ * holding nothing but this cookie (a gate row holds that). No cookie -> 401 SIGN_IN_AGAIN and no IdP call.
+ *
+ * What follows a confirm (BAPert 100969 row 5): the cookie is cleared and the answer carries the recovery codes; NO session is minted here and no new
+ * way to mint one is added. The person signs in again with their password and the authenticator, through the same credential door as before.
+ *
+ * The token never leaves the server: not in a body, a URL, a log or a Referer. The IdP's prose is never relayed.
+ */
+const digest = (s: string) => createHash('sha256').update(s).digest('hex');
+
+const cookieOpts = (maxAge: number) => ({ httpOnly: true, secure: process.env.NODE_ENV === 'production', sameSite: 'strict' as const, path: '/', maxAge });
+
+function reply(status: number, body: Record<string, unknown>, clear: boolean): NextResponse {
+  const res = NextResponse.json(body, { status, headers: NO_STORE });
+  if (clear) res.cookies.set(ENROL_COOKIE, '', cookieOpts(0));
+  return res;
+}
+
+export function enrolStepPOST(step: EnrolStep) {
+  return async function POST(req: NextRequest): Promise<NextResponse> {
+    const refused = refuseNonJson(req);
+    if (refused) return refused;
+    const token = req.cookies.get(ENROL_COOKIE)?.value;
+    if (!token) return reply(401, { success: false, code: 'SIGN_IN_AGAIN' }, false);
+    if (!attemptAllowed(`${step}|ck|${digest(token)}`, LIMIT_PER_COOKIE)) return reply(429, { success: false, code: 'TOO_MANY', error: 'Too many attempts. Wait a few minutes and try again.' }, true);
+
+    const idp = process.env.IDP_URL;
+    let clientKey = '';
+    try {
+      const config = await getIDPClientConfig();
+      clientKey = resolveClientKey(config, 'first-enrol').key ?? '';
+    } catch {
+      return reply(503, { success: false, code: 'IDP_CONFIG_UNAVAILABLE' }, false);
+    }
+    if (!idp || !clientKey) return reply(503, { success: false, code: 'IDP_CONFIG_UNAVAILABLE' }, false);
+
+    const body = await req.json().catch(() => null);
+    const r = await runEnrolStep({ fetchImpl: (u, i) => fetch(u, i), idp, clientKey }, { step, token, body });
+    return reply(r.status, r.body, r.cookie === 'clear');
+  };
+}
+
+export const POST_ENROLL = enrolStepPOST('enroll');
+export const POST_CONFIRM = enrolStepPOST('confirm');

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