@payez/next-mvp 4.5.2 → 4.5.4

package/dist/auth/auth-decision.js

@@ -61,8 +61,10 @@ function decide(context) {
         return {
             type: 'redirect',
             location: '/account-auth/login?error=ServiceUnavailable&reason=CircuitBreakerOpen',
-            reason: 'CircuitBreakerOpen',
-            clearCookies: true
+            reason: 'CircuitBreakerOpen'
+            // PAY-2147: NO clearCookies. The breaker opening is not a verdict on the session; clearing here logged out every
+            // user who made a request during a blip. (Deprecated twin: it cannot express a 503 or the /service-unavailable
+            // page - createMvpMiddleware does, see serviceUnavailableResponse.)
         };
     }
     // No session pointer (JWT cookie) - need to login

package/dist/middleware/create-middleware.js

@@ -160,6 +160,31 @@ function refreshFailureResponse(request, location, errorCode, clearCookies = fal
     }
     return redirectTo(request, location, clearCookies);
 }
+/**
+ * PAY-2147: the terminal answer when the middleware CANNOT TELL whether the session is good
+ * (circuit breaker open, a half-open breaker refusing a refresh attempt, or the viability read failed).
+ *
+ * "I could not check" is not a verdict on the session, so this NEVER touches a cookie: a transient blip
+ * in the IdP / viability path used to wipe the session of every user who made any request while the
+ * breaker was open. Cookies are cleared only on a POSITIVE signal (force_invalidated, stale_session,
+ * pre_2fa_token_expired, refresh 401/403, explicit sign-out) - never from here.
+ *
+ *  - /api/*  -> 503 JSON a caller can branch on (a redirect would be followed by fetch() into a 200 HTML page).
+ *  - pages   -> /service-unavailable (public + allowDuringCircuitBreakerOpen, so it cannot loop), carrying the
+ *               requested path as `callbackUrl` so "Try again" returns the user to it still signed in. The path goes
+ *               through safeCallbackPath (URL-parser origin check): an off-origin or auth-surface value is dropped.
+ */
+function serviceUnavailableResponse(request) {
+    const { pathname, search } = request.nextUrl;
+    if (pathname.startsWith('/api/')) {
+        return server_1.NextResponse.json({ error: 'ServiceUnavailable' }, { status: 503 });
+    }
+    const target = new URL('/service-unavailable', request.url);
+    const callback = (0, safe_callback_1.safeCallbackPath)(pathname + search);
+    if (callback !== '/')
+        target.searchParams.set('callbackUrl', callback);
+    return server_1.NextResponse.redirect(target);
+}
 // =============================================================================
 // AUTH DECISION ENGINE
 // =============================================================================
@@ -198,15 +223,12 @@ function makeAuthDecision(ctx) {
         return { type: 'allow' };
     }
     // --- Circuit breaker open: Service degraded ---
+    // PAY-2147: the breaker opening says the IdP/viability path is unreachable, NOT that the session is bad.
+    // Answer "service unavailable" (503 for /api, /service-unavailable for pages) and leave every cookie alone.
     if (circuitBreakerOpen) {
         if (onLoginPage)
             return { type: 'allow' };
-        return {
-            type: 'redirect',
-            location: `${LOGIN_PAGE}?error=ServiceUnavailable`,
-            reason: 'circuit_breaker_open',
-            clearCookies: true
-        };
+        return { type: 'service_error', reason: 'circuit_breaker_open' };
     }
     // --- No session cookie: Need to login ---
     if (!sessionPointer.exists) {
@@ -227,6 +249,8 @@ function makeAuthDecision(ctx) {
     }
     // --- Service error: Can't verify session ---
     if (sessionStatus.exists === null || sessionStatus.forceInvalid === null) {
+        if (onLoginPage)
+            return { type: 'allow' }; // the login page must stay reachable while the check is down
         return { type: 'service_error', reason: 'viability_check_failed' };
     }
     // --- Session force-invalidated (admin action, password change, etc.) ---
@@ -466,6 +490,17 @@ function decideForceInvalid(data, revocationFailMode) {
     // No revocationStatus: an older boolean producer. Absence of both stays false.
     return data.forceInvalid === true || data.revoked === true;
 }
+/**
+ * PAY-2147: does the request carry a session cookie? Used ONLY when the viability read itself FAILED.
+ * Before this, a failed read left sessionPointer.exists=false, so the decision engine took its `no_session` arm
+ * (pages -> the LOGIN page, /api -> straight through) and its `exists === null` -> service_error arm below it was
+ * unreachable dead code: a user holding a perfectly good session was told to sign in during an outage. With a
+ * cookie present and the check down we do not know the session is bad, so the engine must say "service
+ * unavailable", not "sign in". No cookie -> unchanged (no_session).
+ */
+function hasSessionCookie(request) {
+    return !!(request.cookies.get((0, app_slug_1.getSessionCookieName)())?.value || request.cookies.get((0, app_slug_1.getSecureSessionCookieName)())?.value);
+}
 /** Check session viability via internal API */
 async function checkViability(request, endpoint, log, revocationFailMode) {
     const sessionStatus = {
@@ -540,7 +575,16 @@ async function checkViability(request, endpoint, log, revocationFailMode) {
             // booleans for unknown/not_configured. The booleans are read ONLY when
             // revocationStatus is ABSENT (idealresume.online's older boolean route).
             sessionStatus.forceInvalid = decideForceInvalid(data, revocationFailMode);
-            sessionPointer.exists = sessionStatus.exists ?? false;
+            // PAY-2216: a STALE session - the cookie resolved to a token, but no store holds the session - used to set
+            // pointer.exists=false, so makeAuthDecision took no_session (login, cookie NOT cleared) and its stale_session
+            // arm (clearCookies) was unreachable: a dead cookie lingered and re-ran viability on every request.
+            // Stale is a POSITIVE signal and needs ALL of: this 2xx read, exists === false, a sessionTokenId (every
+            // producer sets it only when a cookie resolved to a token: routes/auth/viability.ts, api-handlers/session/
+            // viability.ts, refresh-viability.ts 'session_not_found'), and a session cookie on THIS request (plain or
+            // __Secure-). A FAILED read never gets here (exists=null -> service_error, PAY-2147); a store error throws
+            // inside every producer and answers 5xx or 'unknown' WITHOUT a sessionTokenId; no cookie -> no_session.
+            const stale = sessionStatus.exists === false && !!data.sessionTokenId && hasSessionCookie(request);
+            sessionPointer.exists = stale ? true : (sessionStatus.exists ?? false);
             sessionPointer.sessionTokenId = data.sessionTokenId ?? null;
             sessionPointer.expired = data.accessTokenExpired || false;
             sessionPointer.hasRefreshToken = data.hasRefreshToken ?? data.canRefresh ?? false;
@@ -551,12 +595,14 @@ async function checkViability(request, endpoint, log, revocationFailMode) {
             log.error('Viability check failed', { status: response.status });
             sessionStatus.exists = null;
             sessionStatus.forceInvalid = null;
+            sessionPointer.exists = hasSessionCookie(request); // PAY-2147: see hasSessionCookie
         }
     }
     catch (error) {
         log.error('Viability check error', { error: error instanceof Error ? error.message : String(error) });
         sessionStatus.exists = null;
         sessionStatus.forceInvalid = null;
+        sessionPointer.exists = hasSessionCookie(request); // PAY-2147: see hasSessionCookie
     }
     return { sessionStatus, sessionPointer };
 }
@@ -569,7 +615,7 @@ async function executeDecision(request, decision, pathname, sessionPointer, sess
         case 'redirect':
             return redirectTo(request, decision.location, decision.clearCookies);
         case 'service_error':
-            return server_1.NextResponse.redirect(new URL('/service-unavailable', request.url));
+            return serviceUnavailableResponse(request);
         case 'refresh_needed':
             // PAY-2136: a speculative request must not spend (rotate) a single-use refresh token or, on a 401/403,
             // clear the session. Let it through; the real navigation refreshes.
@@ -583,7 +629,12 @@ const RBAC_EXEMPT_PATHS = ['/error', '/unauthorized', '/service-unavailable'];
 /** Handle 'allow' decision - run RBAC if enabled */
 async function handleAllow(request, pathname, sessionPointer, sessionStatus, rbacExemptPaths = []) {
     const isPublic = (0, route_config_1.isUnauthenticatedRoute)(pathname);
-    if ((0, rbac_check_1.isRBACEnabled)() && !isPublic && sessionPointer.exists) {
+    // PAY-2216: RBAC needs a session that viability CONFIRMED. A stale /api request (pointer.exists only says the
+    // cookie is present, status.exists is false) is allowed through so the route handler answers its own 401 - not an
+    // RBAC 401 here. TRUTHY, not `=== true` (NightHawk 71960): status.exists carries the producer's JSON value as-is,
+    // and a consumer route may answer authenticated: 1 / "true"; `=== true` skipped RBAC for those healthy sessions
+    // (fail-OPEN). Truthy keeps 4.5.3's RBAC coverage exactly and still excludes stale (false) and a failed read (null).
+    if ((0, rbac_check_1.isRBACEnabled)() && !isPublic && sessionPointer.exists && sessionStatus.exists) {
         // Skip RBAC for error/fallback pages (prevent redirect loops) and app-configured exempt paths
         if (RBAC_EXEMPT_PATHS.some(p => pathname.startsWith(p)) ||
             rbacExemptPaths.some(p => pathname.startsWith(p))) {
@@ -629,7 +680,9 @@ async function handleRefresh(request, safeCallback, opts) {
     // Check if circuit breaker allows refresh attempt
     if (!cb.canAttemptRefresh()) {
         log.warn('Circuit breaker preventing refresh attempt');
-        return refreshFailureResponse(request, `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=ServiceUnavailable`, 'ServiceUnavailable', true);
+        // PAY-2147: a breaker that merely declines to TRY a refresh has learned nothing about the session; wiping the
+        // cookies here logged out every user on the first request after a blip (HALF_OPEN refuses all but one probe).
+        return serviceUnavailableResponse(request);
     }
     try {
         const baseUrl = (0, internal_api_url_1.getInternalApiUrl)(request);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.5.2",
+  "version": "4.5.4",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/auth/auth-decision.ts

@@ -103,8 +103,10 @@ function decide(context: AuthContext): AuthAction {
     return {
       type: 'redirect',
       location: '/account-auth/login?error=ServiceUnavailable&reason=CircuitBreakerOpen',
-      reason: 'CircuitBreakerOpen',
-      clearCookies: true
+      reason: 'CircuitBreakerOpen'
+      // PAY-2147: NO clearCookies. The breaker opening is not a verdict on the session; clearing here logged out every
+      // user who made a request during a blip. (Deprecated twin: it cannot express a 503 or the /service-unavailable
+      // page - createMvpMiddleware does, see serviceUnavailableResponse.)
     };
   }
 

package/src/middleware/create-middleware.ts

@@ -19,7 +19,7 @@
 
 import { NextRequest, NextResponse } from 'next/server';
 import { isUnauthenticatedRoute, should2FABypass } from '../auth/route-config';
-import { resolveCallbackDestination } from '../auth/safe-callback';
+import { resolveCallbackDestination, safeCallbackPath } from '../auth/safe-callback';
 import { getInternalApiUrl } from '../edge/internal-api-url';
 import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
 import { checkPagePermission, isRBACEnabled } from './rbac-check';
@@ -290,6 +290,31 @@ function refreshFailureResponse(
   return redirectTo(request, location, clearCookies);
 }
 
+/**
+ * PAY-2147: the terminal answer when the middleware CANNOT TELL whether the session is good
+ * (circuit breaker open, a half-open breaker refusing a refresh attempt, or the viability read failed).
+ *
+ * "I could not check" is not a verdict on the session, so this NEVER touches a cookie: a transient blip
+ * in the IdP / viability path used to wipe the session of every user who made any request while the
+ * breaker was open. Cookies are cleared only on a POSITIVE signal (force_invalidated, stale_session,
+ * pre_2fa_token_expired, refresh 401/403, explicit sign-out) - never from here.
+ *
+ *  - /api/*  -> 503 JSON a caller can branch on (a redirect would be followed by fetch() into a 200 HTML page).
+ *  - pages   -> /service-unavailable (public + allowDuringCircuitBreakerOpen, so it cannot loop), carrying the
+ *               requested path as `callbackUrl` so "Try again" returns the user to it still signed in. The path goes
+ *               through safeCallbackPath (URL-parser origin check): an off-origin or auth-surface value is dropped.
+ */
+function serviceUnavailableResponse(request: NextRequest): NextResponse {
+  const { pathname, search } = request.nextUrl;
+  if (pathname.startsWith('/api/')) {
+    return NextResponse.json({ error: 'ServiceUnavailable' }, { status: 503 });
+  }
+  const target = new URL('/service-unavailable', request.url);
+  const callback = safeCallbackPath(pathname + search);
+  if (callback !== '/') target.searchParams.set('callbackUrl', callback);
+  return NextResponse.redirect(target);
+}
+
 // =============================================================================
 // AUTH DECISION ENGINE
 // =============================================================================
@@ -334,14 +359,11 @@ function makeAuthDecision(ctx: AuthContext): AuthAction {
   }
 
   // --- Circuit breaker open: Service degraded ---
+  // PAY-2147: the breaker opening says the IdP/viability path is unreachable, NOT that the session is bad.
+  // Answer "service unavailable" (503 for /api, /service-unavailable for pages) and leave every cookie alone.
   if (circuitBreakerOpen) {
     if (onLoginPage) return { type: 'allow' };
-    return {
-      type: 'redirect',
-      location: `${LOGIN_PAGE}?error=ServiceUnavailable`,
-      reason: 'circuit_breaker_open',
-      clearCookies: true
-    };
+    return { type: 'service_error', reason: 'circuit_breaker_open' };
   }
 
   // --- No session cookie: Need to login ---
@@ -363,6 +385,7 @@ function makeAuthDecision(ctx: AuthContext): AuthAction {
 
   // --- Service error: Can't verify session ---
   if (sessionStatus.exists === null || sessionStatus.forceInvalid === null) {
+    if (onLoginPage) return { type: 'allow' }; // the login page must stay reachable while the check is down
     return { type: 'service_error', reason: 'viability_check_failed' };
   }
 
@@ -622,6 +645,18 @@ export function decideForceInvalid(
   return data.forceInvalid === true || data.revoked === true;
 }
 
+/**
+ * PAY-2147: does the request carry a session cookie? Used ONLY when the viability read itself FAILED.
+ * Before this, a failed read left sessionPointer.exists=false, so the decision engine took its `no_session` arm
+ * (pages -> the LOGIN page, /api -> straight through) and its `exists === null` -> service_error arm below it was
+ * unreachable dead code: a user holding a perfectly good session was told to sign in during an outage. With a
+ * cookie present and the check down we do not know the session is bad, so the engine must say "service
+ * unavailable", not "sign in". No cookie -> unchanged (no_session).
+ */
+function hasSessionCookie(request: NextRequest): boolean {
+  return !!(request.cookies.get(getSessionCookieName())?.value || request.cookies.get(getSecureSessionCookieName())?.value);
+}
+
 /** Check session viability via internal API */
 async function checkViability(
   request: NextRequest,
@@ -706,7 +741,16 @@ async function checkViability(
       // booleans for unknown/not_configured. The booleans are read ONLY when
       // revocationStatus is ABSENT (idealresume.online's older boolean route).
       sessionStatus.forceInvalid = decideForceInvalid(data, revocationFailMode);
-      sessionPointer.exists = sessionStatus.exists ?? false;
+      // PAY-2216: a STALE session - the cookie resolved to a token, but no store holds the session - used to set
+      // pointer.exists=false, so makeAuthDecision took no_session (login, cookie NOT cleared) and its stale_session
+      // arm (clearCookies) was unreachable: a dead cookie lingered and re-ran viability on every request.
+      // Stale is a POSITIVE signal and needs ALL of: this 2xx read, exists === false, a sessionTokenId (every
+      // producer sets it only when a cookie resolved to a token: routes/auth/viability.ts, api-handlers/session/
+      // viability.ts, refresh-viability.ts 'session_not_found'), and a session cookie on THIS request (plain or
+      // __Secure-). A FAILED read never gets here (exists=null -> service_error, PAY-2147); a store error throws
+      // inside every producer and answers 5xx or 'unknown' WITHOUT a sessionTokenId; no cookie -> no_session.
+      const stale = sessionStatus.exists === false && !!data.sessionTokenId && hasSessionCookie(request);
+      sessionPointer.exists = stale ? true : (sessionStatus.exists ?? false);
       sessionPointer.sessionTokenId = data.sessionTokenId ?? null;
       sessionPointer.expired = data.accessTokenExpired || false;
       sessionPointer.hasRefreshToken = data.hasRefreshToken ?? data.canRefresh ?? false;
@@ -716,11 +760,13 @@ async function checkViability(
       log.error('Viability check failed', { status: response.status });
       sessionStatus.exists = null;
       sessionStatus.forceInvalid = null;
+      sessionPointer.exists = hasSessionCookie(request); // PAY-2147: see hasSessionCookie
     }
   } catch (error) {
     log.error('Viability check error', { error: error instanceof Error ? error.message : String(error) });
     sessionStatus.exists = null;
     sessionStatus.forceInvalid = null;
+    sessionPointer.exists = hasSessionCookie(request); // PAY-2147: see hasSessionCookie
   }
 
   return { sessionStatus, sessionPointer };
@@ -755,7 +801,7 @@ async function executeDecision(
       return redirectTo(request, decision.location, decision.clearCookies);
 
     case 'service_error':
-      return NextResponse.redirect(new URL('/service-unavailable', request.url));
+      return serviceUnavailableResponse(request);
 
     case 'refresh_needed':
       // PAY-2136: a speculative request must not spend (rotate) a single-use refresh token or, on a 401/403,
@@ -778,7 +824,12 @@ async function handleAllow(
 ): Promise<NextResponse> {
   const isPublic = isUnauthenticatedRoute(pathname);
 
-  if (isRBACEnabled() && !isPublic && sessionPointer.exists) {
+  // PAY-2216: RBAC needs a session that viability CONFIRMED. A stale /api request (pointer.exists only says the
+  // cookie is present, status.exists is false) is allowed through so the route handler answers its own 401 - not an
+  // RBAC 401 here. TRUTHY, not `=== true` (NightHawk 71960): status.exists carries the producer's JSON value as-is,
+  // and a consumer route may answer authenticated: 1 / "true"; `=== true` skipped RBAC for those healthy sessions
+  // (fail-OPEN). Truthy keeps 4.5.3's RBAC coverage exactly and still excludes stale (false) and a failed read (null).
+  if (isRBACEnabled() && !isPublic && sessionPointer.exists && sessionStatus.exists) {
     // Skip RBAC for error/fallback pages (prevent redirect loops) and app-configured exempt paths
     if (RBAC_EXEMPT_PATHS.some(p => pathname.startsWith(p)) ||
         rbacExemptPaths.some(p => pathname.startsWith(p))) {
@@ -843,12 +894,9 @@ async function handleRefresh(
   // Check if circuit breaker allows refresh attempt
   if (!cb.canAttemptRefresh()) {
     log.warn('Circuit breaker preventing refresh attempt');
-    return refreshFailureResponse(
-      request,
-      `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=ServiceUnavailable`,
-      'ServiceUnavailable',
-      true
-    );
+    // PAY-2147: a breaker that merely declines to TRY a refresh has learned nothing about the session; wiping the
+    // cookies here logged out every user on the first request after a blip (HALF_OPEN refuses all but one probe).
+    return serviceUnavailableResponse(request);
   }
 
   try {