@payez/next-mvp 4.9.0 → 4.10.0

package/src/api-handlers/auth/refresh.ts

@@ -41,6 +41,7 @@ import { getSession, updateSession, acquireRefreshLock, releaseRefreshLock, chec
 import { computeTokenExpiries } from '../../lib/token-expiry';
 import { extractKidFromToken } from '../../auth/utils/token-utils';
 import { tokenLogId } from '../../lib/token-log-id';
+import { rotatedRowIsUsable } from '../../lib/refresh-rotation';
 
 interface RefreshConfig {
   idpBaseUrl: string;
@@ -333,7 +334,43 @@ export function createRefreshHandler(config: RefreshConfig) {
       // Note: Token is NOT cleared preemptively - it will be replaced on success.
       // The lock mechanism prevents concurrent refresh attempts within the same session.
       // If IDP call fails, user can retry with the same token.
-      const originalRefreshToken = currentSession.idpRefreshToken as string;
+      // 4.9.0 (BAPert 76298 (b2), 76330): the token we SEND is the one read AFTER the lock was taken (`latestAfterLock`), and it is the ONLY
+      // source: there is NO fallback to `currentSession`, which was read BEFORE the lock. Between those reads another request can rotate the
+      // refresh token (sending the pre-lock value would send a SPENT token) or DISCARD it (the IdP answered 401 for it; re-sending it is a
+      // reuse). The IdP treats reuse as compromise and revokes descendants across devices. So:
+      //   - the post-lock read has NO ROW: the session vanished while we waited; it is not ours to refresh -> the 'No session' 401, no IdP call
+      //   - the row has NO refresh token: -> the same terminal NO_REFRESH_TOKEN as the pre-lock guard, no IdP call; the row is left exactly as
+      //     it is (a discard marker stays on it)
+      // (A row whose access token is still fresh was answered `already_fresh` above and never reaches here.)
+      if (!latestAfterLock) {
+        console.warn('[AUTH_REFRESH] Session vanished while waiting for the refresh lock; not refreshing', { userId });
+        if (weAcquiredLock) {
+          await releaseRefreshLock(sessionToken, requestId, releaseLockVersion);
+          weAcquiredLock = false;
+        }
+        return NextResponse.json({
+          error: 'No session available for refresh',
+          code: 'UNAUTHORIZED'
+        }, { status: 401 });
+      }
+      if (!latestAfterLock.idpRefreshToken) {
+        console.warn('[AUTH_REFRESH] No refresh token after the lock was taken; not calling the IdP', { userId });
+        if (weAcquiredLock) {
+          await releaseRefreshLock(sessionToken, requestId, releaseLockVersion);
+          weAcquiredLock = false;
+        }
+        return NextResponse.json({
+          error: 'No refresh token available',
+          code: 'NO_REFRESH_TOKEN',
+          terminal: true,
+          resolution: 'User must re-authenticate'
+        }, { status: 401 });
+      }
+      const originalRefreshToken = latestAfterLock.idpRefreshToken as string;
+      // The base of everything WRITTEN BACK after a successful exchange is the same post-lock read (BAPert 76318 item 4): writing
+      // `...currentSession` over a rotated row would put a SPENT token back. With no new refresh token from the IdP the stored token is the
+      // one that was SENT (`originalRefreshToken`).
+      const baseSession = latestAfterLock;
 
       try {
         // Extract 2FA claims from current session
@@ -565,7 +602,7 @@ export function createRefreshHandler(config: RefreshConfig) {
               // (race-fix follow-up #1).
               discardToken = false;
               console.warn('[AUTH_REFRESH] Discard suppressed: refresh token already rotated by a concurrent refresh — returning the fresh token (race-safe).');
-              if (postRefresh?.idpAccessToken && postRefresh.idpAccessTokenExpires) {
+              if (rotatedRowIsUsable(postRefresh)) {
                 return NextResponse.json({
                   refreshed: true,
                   reason: 'completed_by_concurrent_request',
@@ -573,6 +610,16 @@ export function createRefreshHandler(config: RefreshConfig) {
                   hasRefreshToken: !!postRefresh.idpRefreshToken,
                 });
               }
+              // Rotated by a concurrent refresh but the row it left is NOT usable (BAPert 76359): the retryable 502, the rotated token kept,
+              // no marker. Same meaning in every branch (lib/refresh-rotation).
+              return NextResponse.json({
+                error: errorMessage,
+                code: errorCode,
+                discardToken: false,
+                retryable: true,
+                resolution,
+                status: 502
+              }, { status: 502 });
             }
           }
 
@@ -631,30 +678,59 @@ export function createRefreshHandler(config: RefreshConfig) {
             errorKeys: Object.keys(idpError),
           });
 
+          // 4.9.0 (BAPert 76298 (c)): ONE IdP answer, ONE meaning, in both refresh implementations. This branch used to answer the upstream
+          // status, i.e. HTTP 200, with an error body, so `internalRefresh` reported `ok` and idpFetchJSON's 401-retry trusted a refresh that
+          // had failed; and it wrote a DIFFERENT marker (IDP_SUCCESS_FALSE_DISCARD) than the IdP-401 branch, which the logout dead-grant check
+          // does not recognise. Now:
+          //   success:false + discard_token  -> the stored token is discarded (same CAS as the 401 branch) with the IDP_DISCARD_TOKEN marker, and the
+          //                                     answer is 401 (never 200 with an error body)
+          //   success:false, no discard_token -> 502 retryable, the token is KEPT
           if (discardToken) {
-            console.error('[AUTH_REFRESH] ⚠️ REFRESH_TOKEN_REMOVAL: IDP success:false with discard_token', {
-              reason: 'IDP_SUCCESS_FALSE_DISCARD',
-              errorCode,
-              userId,
-              sessionToken: tokenLogId(sessionToken),
-              hadRefreshToken: !!currentSession.idpRefreshToken,
-              stack: new Error().stack
-            });
-            await updateSession(sessionToken, {
-              idpRefreshToken: '',
-              idpRefreshTokenExpires: undefined,
-              refreshTokenClearedAt: Date.now(),
-              refreshTokenClearedReason: `IDP_SUCCESS_FALSE_DISCARD:${errorCode}`
-            });
+            const postRefresh = await getSession(sessionToken);
+            const tokenUnchanged = !!originalRefreshToken && postRefresh?.idpRefreshToken === originalRefreshToken;
+            if (tokenUnchanged) {
+              console.error('[AUTH_REFRESH] ⚠️ REFRESH_TOKEN_REMOVAL: IDP success:false with discard_token', {
+                reason: 'IDP_DISCARD_TOKEN',
+                errorCode,
+                userId,
+                sessionToken: tokenLogId(sessionToken),
+                hadRefreshToken: !!currentSession.idpRefreshToken,
+                stack: new Error().stack
+              });
+              await updateSession(sessionToken, {
+                idpRefreshToken: '',
+                idpRefreshTokenExpires: undefined,
+                refreshTokenClearedAt: Date.now(),
+                refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${errorCode}`
+              });
+              return NextResponse.json({
+                error: idpError.message || 'Token refresh failed',
+                code: errorCode,
+                discardToken: true,
+                retryable: false,
+                resolution: idpError.resolution || null,
+                status: 401
+              }, { status: 401 });
+            }
+            // A concurrent refresh already rotated the token: ours is stale. Return the fresh tokens if there are any (as the 401 branch does).
+            if (rotatedRowIsUsable(postRefresh)) {
+              return NextResponse.json({
+                refreshed: true,
+                reason: 'completed_by_concurrent_request',
+                accessTokenExpires: postRefresh.idpAccessTokenExpires,
+                hasRefreshToken: !!postRefresh.idpRefreshToken,
+              });
+            }
           }
 
           return NextResponse.json({
             error: idpError.message || 'Token refresh failed',
             code: errorCode,
-            discardToken,
-            retryable,
-            resolution: idpError.resolution || null
-          }, { status: refreshResponse.status || 400 });
+            discardToken: false,
+            retryable: true,
+            resolution: idpError.resolution || null,
+            status: 502
+          }, { status: 502 });
         }
 
         // Extract tokens from response
@@ -701,24 +777,24 @@ export function createRefreshHandler(config: RefreshConfig) {
               : decodedAccessToken.amr;
           } catch (e) {
             console.warn('[AUTH_REFRESH] Failed to parse AMR claims', { amr: decodedAccessToken.amr });
-            amrClaims = currentSession.authenticationMethods || [];
+            amrClaims = baseSession.authenticationMethods || [];
           }
         } else {
-          amrClaims = currentSession.authenticationMethods || [];
+          amrClaims = baseSession.authenticationMethods || [];
         }
-        const acrLevel = String(decodedAccessToken.acr || currentSession.authenticationLevel || '1');
+        const acrLevel = String(decodedAccessToken.acr || baseSession.authenticationLevel || '1');
 
         // Extract MFA timing claims
-        const mfaTime = decodedAccessToken.mfa_time ? parseInt(decodedAccessToken.mfa_time) * 1000 : currentSession.mfaCompletedAt;
-        const mfaExpires = decodedAccessToken.mfa_expires ? parseInt(decodedAccessToken.mfa_expires) * 1000 : currentSession.mfaExpiresAt;
-        const mfaValidityHours = decodedAccessToken.mfa_validity_hours ? parseInt(decodedAccessToken.mfa_validity_hours) : currentSession.mfaValidityHours;
+        const mfaTime = decodedAccessToken.mfa_time ? parseInt(decodedAccessToken.mfa_time) * 1000 : baseSession.mfaCompletedAt;
+        const mfaExpires = decodedAccessToken.mfa_expires ? parseInt(decodedAccessToken.mfa_expires) * 1000 : baseSession.mfaExpiresAt;
+        const mfaValidityHours = decodedAccessToken.mfa_validity_hours ? parseInt(decodedAccessToken.mfa_validity_hours) : baseSession.mfaValidityHours;
 
         // Update session with new tokens
         const hasNewRefresh = typeof refreshToken === 'string' && refreshToken.length > 0;
         const newRefreshTokenExpires = hasNewRefresh ? computedRefreshTokenExpires : undefined;
 
         // CRITICAL: Log if we're about to clear the refresh token due to missing new token
-        if (!hasNewRefresh && currentSession.idpRefreshToken) {
+        if (!hasNewRefresh && baseSession.idpRefreshToken) {
           console.error('[AUTH_REFRESH] ⚠️ REFRESH_TOKEN_REMOVAL: No new refresh token in IDP response', {
             reason: 'NO_NEW_REFRESH_TOKEN_IN_RESPONSE',
             userId,
@@ -747,14 +823,14 @@ export function createRefreshHandler(config: RefreshConfig) {
         }
 
         const sessionUpdate: any = {
-          ...currentSession,
+          ...baseSession,
           idpAccessToken: accessToken,
           idpAccessTokenExpires: accessTokenExpires,
-          idpRefreshToken: hasNewRefresh ? (refreshToken as string) : currentSession.idpRefreshToken,
-          idpRefreshTokenExpires: hasNewRefresh ? newRefreshTokenExpires : currentSession.idpRefreshTokenExpires,
+          idpRefreshToken: hasNewRefresh ? (refreshToken as string) : originalRefreshToken,
+          idpRefreshTokenExpires: hasNewRefresh ? newRefreshTokenExpires : baseSession.idpRefreshTokenExpires,
           decodedAccessToken: decodedAccessToken,
           // Bearer key ID from JWT header (may change on key rotation)
-          bearerKeyId: newBearerKeyId || currentSession.bearerKeyId,
+          bearerKeyId: newBearerKeyId || baseSession.bearerKeyId,
           authenticationMethods: amrClaims,
           authenticationLevel: acrLevel,
           // 170007 rule 2 (BAPert ruling on 121350): '||' is the wrong operator

package/src/lib/ensure-fresh-access-token.ts

@@ -24,6 +24,7 @@ import {
 } from './session-store';
 import { computeTokenExpiries } from './token-expiry';
 import { extractKidFromToken } from '../auth/utils/token-utils';
+import { rotatedRowIsUsable } from './refresh-rotation';
 
 export interface EnsureFreshConfig {
   idpBaseUrl: string;
@@ -353,7 +354,7 @@ export async function ensureFreshAccessToken(
           // freshly-rotated token directly so the loser succeeds without a retry round-trip
           // (race-fix follow-up #1).
           discardToken = false;
-          if (postRefresh?.idpAccessToken && postRefresh.idpAccessTokenExpires) {
+          if (rotatedRowIsUsable(postRefresh)) {
             return {
               ok: true,
               accessToken: postRefresh.idpAccessToken,
@@ -363,6 +364,17 @@ export async function ensureFreshAccessToken(
               persisted: true,
             };
           }
+          // Rotated by a concurrent refresh but the row it left is NOT usable (BAPert 76359): the retryable 502, the rotated token kept, no
+          // marker. Same meaning in every branch (lib/refresh-rotation).
+          return {
+            ok: false,
+            code,
+            message: idpError.message || 'Token refresh failed',
+            status: 502,
+            discardToken: false,
+            retryable: true,
+            resolution: idpError.resolution,
+          };
         }
       }
       return {
@@ -378,6 +390,55 @@ export async function ensureFreshAccessToken(
     }
 
     // Validate canonical envelope.
+    // 4.9.0 (BAPert 76298 (c)): ONE IdP answer, ONE meaning, in both refresh implementations (api-handlers/auth/refresh.ts has the twin of
+    // this block). A 200 envelope with success:false used to be a generic 502 here, with discard_token ignored, while the other twin
+    // honoured it. Now: success:false + discard_token discards the stored token (same CAS as the HTTP-401 branch above, same
+    // IDP_DISCARD_TOKEN marker) and answers terminal 401; success:false without discard_token is a retryable 502 and the token is KEPT.
+    if (responseData && typeof responseData === 'object' && responseData.success === false) {
+      const idpError = responseData.error || {};
+      const code = idpError.code || 'UPSTREAM_VALIDATION_ERROR';
+      if (idpError.discard_token === true) {
+        const postRefresh = await getSession(sessionToken);
+        const tokenUnchanged = !!sentRefreshToken && postRefresh?.idpRefreshToken === sentRefreshToken;
+        if (tokenUnchanged) {
+          await updateSession(sessionToken, {
+            idpRefreshToken: '',
+            idpRefreshTokenExpires: undefined,
+            refreshTokenClearedAt: Date.now(),
+            refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${code}`,
+          });
+          return {
+            ok: false,
+            code,
+            message: idpError.message || 'Token refresh failed',
+            status: 401,
+            discardToken: true,
+            retryable: false,
+            resolution: idpError.resolution,
+            terminal: true,
+          };
+        }
+        if (rotatedRowIsUsable(postRefresh)) {
+          return {
+            ok: true,
+            accessToken: postRefresh.idpAccessToken,
+            accessTokenExpires: postRefresh.idpAccessTokenExpires,
+            refreshed: true,
+            persisted: true,
+          };
+        }
+      }
+      return {
+        ok: false,
+        code,
+        message: idpError.message || 'Token refresh failed',
+        status: 502,
+        discardToken: false,
+        retryable: true,
+        resolution: idpError.resolution,
+      };
+    }
+
     if (
       !responseData ||
       typeof responseData !== 'object' ||

package/src/lib/idp-logout.ts

@@ -14,8 +14,10 @@ import { ENV_CONFIG } from '../config/env';
  *   'revoked'            the IdP answered 2xx.
  *   'nothing-to-revoke'  the session holds no IdP refresh token (a provisional pre-2FA session has none). No call is made, because
  *                        without a token Core would pick the newest session.
- *   'grant-already-dead' the revoke was refused (401/403) and the refresh that followed was answered 401: refresh.ts calls that
- *                        "definitively invalid", the token is expired or revoked, so there is nothing left to end (BAPert 76289 item 3).
+ *   'grant-already-dead' the revoke was refused AND the refresh that followed was answered 401 AND the session carries the IdP's own
+ *                        discard marker (refreshTokenClearedReason starting 'IDP_DISCARD_TOKEN'). A refresh 401 alone is NOT proof
+ *                        (refresh.ts also answers 401 for 'no session', the x-session-token rejection and NO_REFRESH_TOKEN), and neither
+ *                        is an empty token (BAPert 76297). Anything else is UNKNOWN.
  * THROWS for an UNKNOWN outcome: a transport error, a 5xx, a refresh that could not be attempted or failed some other way. The caller
  * turns that into SESSION_NOT_ENDED.
  *

package/src/lib/refresh-rotation.ts

@@ -0,0 +1,18 @@
+/**
+ * 4.9.0 (BAPert 76359): ONE predicate for "a concurrent refresh already rotated the refresh token, and the row it left is usable", shared by
+ * all four places that decide it (api-handlers/auth/refresh.ts and lib/ensure-fresh-access-token.ts, each for the HTTP-401 branch and the
+ * 200 success:false branch). Before, two said "usable" meant PRESENT (an access token and an expiry exist) and two said UNEXPIRED, so a rotated
+ * row whose access token had already expired was answered as a successful refresh by some branches and not by others.
+ *
+ * Usable = an access token exists AND its recorded expiry is in the future. A row that is rotated but NOT usable is answered with the
+ * retryable 502, its (rotated) refresh token KEPT and NO discard marker, in every branch. The CAS that decides "rotated" (a different
+ * stored refresh token than the one we sent) is unchanged: a different token is never discarded.
+ *
+ * A leaf module: no imports.
+ */
+export function rotatedRowIsUsable<T extends { idpAccessToken?: string | null; idpAccessTokenExpires?: number | null }>(
+  session: T | null | undefined,
+  now: number = Date.now(),
+): session is T & { idpAccessToken: string; idpAccessTokenExpires: number } {
+  return !!(session && session.idpAccessToken && session.idpAccessTokenExpires && session.idpAccessTokenExpires > now);
+}

package/src/lib/session-store.ts

@@ -284,7 +284,25 @@ export async function deleteSessionEverywhere(sessionToken: string, appSlug?: st
  * @param sessionToken The session token.
  * @param data The session data.
  */
+/**
+ * 4.9.0 (BAPert 76308 item 2): A LEFTOVER DISCARD MARKER MUST NEVER OUTLIVE A TOKEN. A discard (`refresh.ts`, `ensure-fresh-access-token.ts`)
+ * writes `idpRefreshToken: ''` TOGETHER WITH `refreshTokenClearedReason: 'IDP_DISCARD_TOKEN:<code>'`; logout's dead-grant check reads that marker
+ * as proof the IdP's grant is gone. If a later write stores a NEW refresh token on the same row (a successful refresh, a re-sign-in into the
+ * same row) and the marker stays, a later own-auth 401 would read as "grant already dead" while the grant is live. So any write that leaves a
+ * non-empty refresh token on the row drops the marker, in the same write. No code path was found that gives a discarded row a new token
+ * today; this is the defence BAPert ruled to keep anyway.
+ */
+function dropStaleDiscardMarker<T extends object>(session: T): T {
+  const s = session as any;
+  if (typeof s.idpRefreshToken === 'string' && s.idpRefreshToken.length > 0 && (s.refreshTokenClearedReason !== undefined || s.refreshTokenClearedAt !== undefined)) {
+    const { refreshTokenClearedReason: _reason, refreshTokenClearedAt: _at, ...rest } = s;
+    return rest as T;
+  }
+  return session;
+}
+
 export async function setSession(sessionToken: string, data: SessionData): Promise<void> {
+  data = dropStaleDiscardMarker(data);
   const key = getSessionKey(sessionToken);
   const versionKey = getSessionVersionKey(sessionToken);
   await redis.multi()
@@ -424,7 +442,7 @@ export async function updateSession(
   }
 
   // Merge current session with updates
-  const updatedSession = { ...currentSession, ...updates };
+  const updatedSession = dropStaleDiscardMarker({ ...currentSession, ...updates });
 
   // Write the entire updated session back to Redis with version increment
   await redis.multi()

package/dist/api/auth-handler.d.ts

@@ -1,64 +0,0 @@
-/**
- * Enhanced Auth Handler with Coordinated Token Refresh
- *
- * Provides a middleware wrapper that automatically handles token lifecycle:
- * - Checks token expiry before each request
- * - Automatically refreshes expired or near-expired tokens
- * - Uses Redis locks for coordinated refresh (prevents race conditions)
- * - Retries requests on 401 responses with fresh tokens
- *
- * Pattern ported from website-membership simple-api-handler.ts
- *
- * @version 2.1.0
- * @since auth-ready-v2
- */
-import { NextRequest, NextResponse } from 'next/server';
-export interface AuthContext {
-    token: any;
-    accessToken: string;
-    userId: string;
-    sessionToken: string;
-    refreshToken?: string;
-}
-export interface AuthHandlerOptions {
-    /** Whether authentication is required for this route (default: true) */
-    requireAuth?: boolean;
-    /** Automatically refresh expired or near-expired tokens (default: true) */
-    autoRefresh?: boolean;
-    /** Buffer time in seconds before token expiry to trigger refresh (default: 300 = 5 minutes) */
-    refreshBuffer?: number;
-    /** Retry request on 401 response after refreshing token (default: true) */
-    retryOn401?: boolean;
-    /** Maximum number of retry attempts on 401 (default: 1) */
-    maxRetries?: number;
-    /** IDP base URL for refresh requests */
-    idpBaseUrl?: string;
-    /** OAuth client ID */
-    clientId?: string;
-}
-export type HandlerFunction = (req: NextRequest, context: any, auth: AuthContext) => Promise<NextResponse | Response>;
-/**
- * Creates an auth-aware handler with automatic token refresh
- *
- * @example
- * ```typescript
- * import { createAuthHandler } from '@payez/next-mvp/api';
- *
- * const handler = createAuthHandler({ requireAuth: true });
- *
- * export const GET = handler.handle(async (req, context, auth) => {
- *   // auth.accessToken is guaranteed to be fresh
- *   const response = await fetch('https://api.example.com/data', {
- *     headers: { 'Authorization': `Bearer ${auth.accessToken}` }
- *   });
- *   return NextResponse.json(await response.json());
- * });
- * ```
- */
-export declare function createAuthHandler(options?: AuthHandlerOptions): {
-    handle: (handler: HandlerFunction) => (req: NextRequest, context?: any) => Promise<Response>;
-};
-/**
- * Default export for convenience
- */
-export default createAuthHandler;