@payez/next-mvp 4.4.6 → 4.4.8

package/src/lib/two-factor-verify-failure.ts

@@ -25,6 +25,7 @@ export type TwoFactorVerifyFailureCode =
   | 'LOCKED'
   | 'RATE_LIMITED'
   | 'SESSION_REJECTED'
+  | 'STEP_UP_FACTOR_NOT_ALLOWED'
   | 'VERIFY_UNAVAILABLE'
   | 'VERIFY_FAILED';
 
@@ -35,7 +36,7 @@ const INVALID_CODE_TEXT: Record<TwoFactorVerifyMethod, string> = {
   backup_code: 'Invalid backup code. Please try again.',
 };
 
-const FIXED_TEXT: Record<Exclude<TwoFactorVerifyFailureCode, 'INVALID_CODE'>, string> = {
+const FIXED_TEXT: Record<Exclude<TwoFactorVerifyFailureCode, 'INVALID_CODE' | 'STEP_UP_FACTOR_NOT_ALLOWED'>, string> = {
   LOCKED: 'Too many incorrect codes. Verification is locked for 15 minutes - wait before entering another code.',
   RATE_LIMITED: 'Too many attempts. Please wait a moment and try again.',
   SESSION_REJECTED: 'We could not verify the code for this session. Please try again.',
@@ -70,6 +71,78 @@ const IDP_UNAVAILABLE = /^(?:service_unavailable|server_error)$|code\s*=\s*(?:se
 
 const WRONG_CODE = /\b(invalid|incorrect|wrong|expired)\b[^.]{0,40}\b(code|otp|totp|token)\b|\binvalid_code\b/i;
 
+/**
+ * PAY-1611: the IdP's 403 STEP_UP_FACTOR_NOT_ALLOWED refusal (Core ExternalAuthController.DeliveredCodeStepUpRefusal).
+ * A session signed in with an emailed/texted code only cannot re-prove itself with another emailed/texted code; the
+ * IdP says which factors it WILL take and what the user can do instead. The portal can only offer those options if
+ * this BFF relays them, so on that one refusal we emit the code plus ALLOWLISTED copies of the two lists.
+ *
+ * On the wire PayEzControllerBase.OnActionExecuted re-envelopes the action's object: the code is `error.code` and the
+ * object sits under `error.details`, so the lists are `error.details.allowed_methods` / `error.details.next_steps`.
+ * The unenveloped action shape (top-level `error` string, lists at top level) is accepted too.
+ *
+ * NEVER relayed (PAY-1443 stands): `error_description` or any other IdP prose, and any IdP `endpoint` - the consumer
+ * maps each action to its OWN route from a constant table. Unknown methods/actions are dropped, not passed through;
+ * missing or malformed lists give EMPTY lists, never invented ones.
+ */
+export const STEP_UP_REFUSAL_CODE = 'STEP_UP_FACTOR_NOT_ALLOWED';
+const STEP_UP_METHODS = ['totp', 'webauthn', 'backup_code'] as const;
+const STEP_UP_ACTIONS = ['use_authenticator', 'reset_password', 'enroll_authenticator'] as const;
+export type StepUpMethod = (typeof STEP_UP_METHODS)[number];
+export type StepUpAction = (typeof STEP_UP_ACTIONS)[number];
+export type StepUpNextStep = { action: 'use_authenticator'; methods: StepUpMethod[] } | { action: Exclude<StepUpAction, 'use_authenticator'> };
+export type StepUpRefusal = { allowed_methods: StepUpMethod[]; next_steps: StepUpNextStep[] };
+
+const STEP_UP_TEXT =
+  'This session was signed in with an emailed or texted code only, so another emailed or texted code cannot confirm it is you.';
+
+function allowedMethods(v: unknown): StepUpMethod[] {
+  if (!Array.isArray(v)) return [];
+  const out: StepUpMethod[] = [];
+  for (const m of v) {
+    if ((STEP_UP_METHODS as readonly unknown[]).includes(m) && !out.includes(m as StepUpMethod)) out.push(m as StepUpMethod);
+  }
+  return out;
+}
+
+/** The step-up refusal's allowlisted lists, or null when this is not that refusal (status 403 + the exact code only). */
+export function stepUpRefusal(status: number, json: unknown): StepUpRefusal | null {
+  if (status !== 403 || !json || typeof json !== 'object') return null;
+  const j = json as Record<string, unknown>;
+  const err = j.error;
+  let code: unknown;
+  let src: Record<string, unknown> = j;
+  if (err && typeof err === 'object') {
+    const e = err as Record<string, unknown>;
+    code = e.code;
+    src = e.details && typeof e.details === 'object' ? (e.details as Record<string, unknown>) : {};
+  } else {
+    code = err;
+  }
+  if (code !== STEP_UP_REFUSAL_CODE) return null;
+  const next_steps: StepUpNextStep[] = [];
+  const seen = new Set<string>();
+  for (const step of Array.isArray(src.next_steps) ? src.next_steps : []) {
+    if (!step || typeof step !== 'object') continue;
+    const action = (step as Record<string, unknown>).action;
+    if (typeof action !== 'string' || !(STEP_UP_ACTIONS as readonly string[]).includes(action) || seen.has(action)) continue;
+    seen.add(action);
+    next_steps.push(
+      action === 'use_authenticator'
+        ? { action, methods: allowedMethods((step as Record<string, unknown>).methods) }
+        : { action: action as Exclude<StepUpAction, 'use_authenticator'> },
+    );
+  }
+  return { allowed_methods: allowedMethods(src.allowed_methods), next_steps };
+}
+
+function stepUpResponse(refusal: StepUpRefusal, attemptedRefresh: boolean): NextResponse {
+  return NextResponse.json(
+    { success: false, error: STEP_UP_TEXT, code: STEP_UP_REFUSAL_CODE, ...refusal, meta: { attemptedRefresh } },
+    { status: 403 },
+  );
+}
+
 /**
  * Every string the IDP might have put anywhere in the error envelope, unwrapped from
  * `{ message = X }` ToString form. Classification input only.
@@ -97,6 +170,8 @@ export function upstreamErrorTexts(json: unknown): string[] {
 }
 
 export function classifyTwoFactorVerifyFailure(status: number, json: unknown): TwoFactorVerifyFailureCode {
+  // PAY-1611: checked FIRST - an exact code on a 403, so no prose rule below can claim it first.
+  if (stepUpRefusal(status, json)) return 'STEP_UP_FACTOR_NOT_ALLOWED';
   // PAY-902 (BAPert R484): the IdP's lockout CODE, not its prose. Door A is post-authentication, so stating
   // the lockout discloses nothing; telling a locked-out user "try again" sends them to spend attempts.
   //
@@ -118,8 +193,10 @@ export function twoFactorVerifyFailure(
   result: { status: number; json: unknown; attemptedRefresh: boolean },
   method: TwoFactorVerifyMethod,
 ): NextResponse {
+  const refusal = stepUpRefusal(result.status, result.json);
+  if (refusal) return stepUpResponse(refusal, result.attemptedRefresh);
   const code = classifyTwoFactorVerifyFailure(result.status, result.json);
-  const error = code === 'INVALID_CODE' ? INVALID_CODE_TEXT[method] : FIXED_TEXT[code];
+  const error = code === 'INVALID_CODE' ? INVALID_CODE_TEXT[method] : FIXED_TEXT[code as keyof typeof FIXED_TEXT];
   return NextResponse.json(
     { success: false, error, code, meta: { attemptedRefresh: result.attemptedRefresh } },
     { status: result.status },
@@ -137,12 +214,14 @@ export type TwoFactorSendMethod = 'sms' | 'email';
 export type TwoFactorSendFailureCode =
   | 'RATE_LIMITED'
   | 'SESSION_REJECTED'
+  | 'STEP_UP_FACTOR_NOT_ALLOWED'
   | 'SEND_UNAVAILABLE'
   | 'SEND_FAILED';
 
 const SEND_LABEL: Record<TwoFactorSendMethod, string> = { sms: 'text message', email: 'email' };
 
-export function classifyTwoFactorSendFailure(status: number): TwoFactorSendFailureCode {
+export function classifyTwoFactorSendFailure(status: number, json?: unknown): TwoFactorSendFailureCode {
+  if (stepUpRefusal(status, json)) return 'STEP_UP_FACTOR_NOT_ALLOWED'; // PAY-1611, before the 401/403 branch
   if (status === 429) return 'RATE_LIMITED';
   if (status === 401 || status === 403) return 'SESSION_REJECTED';
   if (status >= 500 || status === 0) return 'SEND_UNAVAILABLE';
@@ -150,10 +229,12 @@ export function classifyTwoFactorSendFailure(status: number): TwoFactorSendFailu
 }
 
 export function twoFactorSendCodeFailure(
-  result: { status: number; attemptedRefresh: boolean },
+  result: { status: number; attemptedRefresh: boolean; json?: unknown },
   method: TwoFactorSendMethod,
 ): NextResponse {
-  const code = classifyTwoFactorSendFailure(result.status);
+  const refusal = stepUpRefusal(result.status, result.json);
+  if (refusal) return stepUpResponse(refusal, result.attemptedRefresh);
+  const code = classifyTwoFactorSendFailure(result.status, result.json);
   const label = SEND_LABEL[method];
   const error =
     code === 'RATE_LIMITED' ? FIXED_TEXT.RATE_LIMITED

package/src/middleware/create-middleware.ts

@@ -256,6 +256,29 @@ function makeAuthDecision(ctx: AuthContext): AuthAction {
   const { pathname, isPublicRoute, isLoginPage: onLoginPage, searchParams, sessionPointer, sessionStatus, circuitBreakerOpen } = ctx;
   const safeCallback = getSafeCallbackUrl(pathname);
 
+  // --- PAY-884: a provisional (pre-2FA) session whose token has expired can never finish 2FA ---
+  // The IdP issues no refresh token until 2FA completes, and it validates token lifetime, so
+  // once the provisional access token expires neither refresh nor code verification can
+  // succeed. Sending the user to the verify-code page (or to error=SessionExpired, which the
+  // login page deliberately shows as NO message) strands them mid-2FA with no explanation.
+  // Say what happened instead, and clear the dead session so the next sign-in starts clean.
+  // Scoped to the verify-code page and protected pages: /api/ keeps its 401-JSON carve-out
+  // (307290), the login page stays reachable, and public pages are left to the existing arms.
+  if (
+    isExpiredProvisionalSession(sessionPointer, sessionStatus) &&
+    !pathname.startsWith('/api/') &&
+    !onLoginPage &&
+    (pathname === VERIFY_CODE_PAGE || !isPublicRoute)
+  ) {
+    const callback = pathname === VERIFY_CODE_PAGE ? getSafeCallbackUrl(pathname, searchParams) : safeCallback;
+    return {
+      type: 'redirect',
+      location: `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(callback)}&error=${TWO_FACTOR_TIMEOUT_ERROR}`,
+      reason: 'pre_2fa_token_expired',
+      clearCookies: true,
+    };
+  }
+
   // --- Public routes: Allow, but enforce 2FA for authenticated users ---
   if (isPublicRoute && !onLoginPage) {
     if (needsTwoFactorRedirect(pathname, sessionPointer, sessionStatus)) {
@@ -364,6 +387,25 @@ function makeAuthDecision(ctx: AuthContext): AuthAction {
   return { type: 'allow' };
 }
 
+/** Login error code for a pre-2FA session that expired before the code was verified (PAY-884). */
+export const TWO_FACTOR_TIMEOUT_ERROR = 'TwoFactorTimeout';
+
+/**
+ * PAY-884: 2FA outstanding, access token expired, and no refresh token to renew it.
+ * Only a viability answer that positively says the session exists qualifies (null = check failed).
+ */
+function isExpiredProvisionalSession(session: SessionPointer, status: SessionStatus): boolean {
+  return (
+    session.exists &&
+    status.exists === true &&
+    status.forceInvalid === false &&
+    status.requires2FA &&
+    !status.twoFactorComplete &&
+    session.expired === true &&
+    !session.hasRefreshToken
+  );
+}
+
 /** Check if user needs 2FA redirect */
 function needsTwoFactorRedirect(pathname: string, session: SessionPointer, status: SessionStatus): boolean {
   if (!session.exists || !status.exists) return false;

package/src/pages/login/page.tsx

@@ -141,6 +141,10 @@ function LoginForm({ altAuthSlot }: { altAuthSlot?: React.ReactNode }) {
         // Session expiration is normal - don't show as error
         console.log('[LOGIN] SessionExpired detected - normal behavior');
         friendlyError = null;
+      } else if (urlError === 'TwoFactorTimeout') {
+        // PAY-884: the sign-in expired while the verification code was outstanding. Unlike
+        // SessionExpired this is NOT silent - the user was mid-2FA and must know why they are here.
+        friendlyError = 'Your verification step timed out before the code was confirmed. Please sign in again.';
       } else if (urlError === 'ServiceUnavailable') {
         friendlyError = 'Authentication service is temporarily unavailable. Please try again in a few minutes.';
       } else if (urlError.startsWith("Unexpected token")) {

package/src/pages/verify-code/page.tsx

@@ -336,7 +336,8 @@ function VerifyCodeForm({ enrollHref }: { enrollHref: string }) {
             sessionStorage.removeItem(VERIFY_IN_PROGRESS_KEY);
           }
           const safeCallback = callbackUrl.startsWith('/account-auth/') ? '/dashboard' : callbackUrl;
-          const errorParam = isJwtExpired ? '&error=SessionExpired' : '';
+          // PAY-884: an expired JWT here is the provisional pre-2FA token - say so on the login page.
+          const errorParam = isJwtExpired ? '&error=TwoFactorTimeout' : '';
           router.push(`/account-auth/login?callbackUrl=${encodeURIComponent(safeCallback)}${errorParam}`);
         }, 1500);
         return;
@@ -411,7 +412,8 @@ function VerifyCodeForm({ enrollHref }: { enrollHref: string }) {
             sessionStorage.removeItem(VERIFY_IN_PROGRESS_KEY);
           }
           const safeCallback = callbackUrl.startsWith('/account-auth/') ? '/dashboard' : callbackUrl;
-          const errorParam = isJwtExpired ? '&error=SessionExpired' : '';
+          // PAY-884: an expired JWT here is the provisional pre-2FA token - say so on the login page.
+          const errorParam = isJwtExpired ? '&error=TwoFactorTimeout' : '';
           router.push(`/account-auth/login?callbackUrl=${encodeURIComponent(safeCallback)}${errorParam}`);
         }, 1500);
         return;

package/src/routes/auth/settings.ts

@@ -29,6 +29,7 @@
 
 import { NextResponse } from 'next/server';
 import { getIDPClientConfig } from '../../lib/idp-client-config';
+import { secretSafeJson } from '../../lib/never-in-response';
 
 export interface PublicAuthSettings {
     // OAuth providers enabled for this client
@@ -170,8 +171,11 @@ export async function GET() {
         allowed2FAMethods: authSettings.allowed2FAMethods,
     };
 
-    return NextResponse.json(
+    // PAY-1529: the public policy is built from an allowlist above; secretSafeJson is the runtime backstop
+    // that answers 500 instead of serving it if a registered secret ever reaches this body anyway.
+    return secretSafeJson(
         { success: true, data: settings },
         { headers: { 'Cache-Control': 'no-store' } },
+        'GET /api/auth/settings',
     );
 }

package/src/server/auth.ts

@@ -6,17 +6,13 @@
  */
 
 import 'server-only';
-import { createBetterAuthInstance, secretFingerprint } from '../auth/better-auth';
-import { getIDPClientConfig } from '../lib/idp-client-config';
+import { getBetterAuthInstance } from '../auth/better-auth';
 import {
   getSession as getRedisSession,
   getBetterAuthSession as getBetterAuthRedisSession,
   type SessionData,
 } from '../lib/session-store';
 import { resolveVerifiedSessionTokenFromRequest } from './verified-session-token';
-import { createSingleFlight } from '../lib/single-flight';
-
-let authInstance: ReturnType<typeof createBetterAuthInstance> | null = null;
 
 export type IdpTokenResult =
   | { success: true; accessToken: string; sessionData: SessionData }
@@ -102,32 +98,30 @@ function attachSessionData(session: any, sessionData: SessionData | null, sessio
  * test/single-flight-retry.test.cjs, which imports dist/ and therefore
  * exercises the artefact that actually ships.
  *
- * Semantics, all asserted by that suite: concurrent callers share ONE
- * underlying init; a rejection reaches every caller awaiting that attempt
- * (failures stay loud -- getIDPClientConfig is fail-loud by design and callers
- * depend on it); the NEXT call after a failure starts a fresh attempt; and a
- * slow failure never evicts a newer in-flight attempt.
+ * PAY-1623 (package half, BAPert 62449): THIS FUNNEL NO LONGER BUILDS ITS OWN
+ * INSTANCE. It used to call `createBetterAuthInstance(config)` with no opts, so
+ * it carried NONE of the app-supplied plugins registered by the host app at
+ * startup (`configureBetterAuth()` -> `state.configuredOpts`). `samlAcs()` and
+ * `passkeySignIn()` arrive only that way, so `getAuthInstance()` returned an
+ * instance on which `auth.api.samlAcs` was `undefined` — the exact package twin
+ * of the portal ACS crash `t.api.samlAcs is not a function` (Jon's walk,
+ * 2026-09-21; Portal PR 517 fixed the portal by importing the CONFIGURED
+ * instance, `getBetterAuthInstance`, which is why this file must now resolve the
+ * same one). It also silently created a SECOND, divergent instance beside the
+ * one every /api/auth/* route uses — two instances, two secrets, one process.
+ *
+ * It now DELEGATES to that configured funnel, which is the single source of
+ * truth for the process's Better Auth instance:
+ *   - it carries `state.configuredOpts` (better-auth.ts:930), so the app
+ *     plugins are present;
+ *   - its init is already single-flighted with the retry semantics described in
+ *     lib/single-flight.ts (see getBetterAuthInstance, card 244549/338215), so
+ *     this function keeps the same no-latch recovery contract;
+ *   - there is now ONE instance, so the double-init / divergent-secret hazard
+ *     this path used to create is gone by construction.
  */
-const authInit = createSingleFlight(async () => {
-  const config = await getIDPClientConfig(true);
-  authInstance = createBetterAuthInstance(config);
-  // 185121 line 1, path 2: this module-scope instance had NO creation log
-  // line — first-called during a config transition window it pinned a
-  // divergent secret INVISIBLY. Name the path and the secret fingerprint
-  // (the createBetterAuthInstance line already logged the same hash;
-  // this line is what attributes it to THIS init path).
-  // Guard matches createBetterAuthInstance's: getIDPClientConfig currently
-  // throws FATAL on a missing authSecret (QAPert 27328 verified), but that
-  // guarantee is one refactor away — log ABSENT rather than ever throw here.
-  console.log(
-    `[AUTH] getAuthInstance: created BA instance via server/auth.ts — authSecret ${config.authSecret ? `sha256:${secretFingerprint(config.authSecret as string)}` : 'ABSENT'}`
-  );
-  return authInstance;
-});
-
 export async function getAuthInstance() {
-  if (authInstance) return authInstance;
-  return authInit.get();
+  return getBetterAuthInstance();
 }