@payez/next-mvp 4.8.9 → 4.10.0

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

@@ -13,6 +13,7 @@
  * Single-use refresh-token semantics are preserved via Redis-backed
  * single-flight locking (see `acquireRefreshLock`).
  */
+import { randomUUID } from 'crypto';
 import {
   getSession,
   getBetterAuthSession,
@@ -23,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;
@@ -35,7 +37,10 @@ export interface EnsureFreshOptions {
   safetyWindowMs?: number;
   /** Max wait while another caller holds the refresh lock. Default 5000. */
   lockWaitMs?: number;
-  /** Optional caller request id for lock attribution. */
+  /**
+   * Optional caller request id, for LOG CORRELATION ONLY. It is never the lock identity: the lock id is minted here with
+   * crypto.randomUUID(). (BAPert 76298 (b): the lock id used to be this value, taken from the request's x-request-id header.)
+   */
   requestId?: string;
 }
 
@@ -106,7 +111,13 @@ export async function ensureFreshAccessToken(
   const { idpBaseUrl, clientId, refreshEndpoint = '/api/ExternalAuth/refresh' } = config;
   const safetyWindowMs = options.safetyWindowMs ?? DEFAULT_SAFETY_WINDOW_MS;
   const lockWaitMs = options.lockWaitMs ?? DEFAULT_LOCK_WAIT_MS;
-  const requestId = options.requestId ?? `ensure_fresh_${Date.now()}`;
+  // LOCK IDENTITY IS MINTED SERVER-SIDE (BAPert 76298 (b)), exactly as api-handlers/auth/refresh.ts does. It used to be
+  // `options.requestId ?? ensure_fresh_${Date.now()}`, and server/auth.ts passed the request's x-request-id header, so a caller chose the
+  // value that the branch below compared against the lock holder's id. A lock that protects against refresh-token REUSE (the IdP treats
+  // reuse as compromise and revokes descendants across devices) must not be bypassable by an id the caller picks. Date.now() also
+  // collided for two calls in the same millisecond. The caller's id is kept as `traceId`, for logs only.
+  const requestId = `ensure_fresh_${randomUUID()}`;
+  const traceId = options.requestId;
 
   let session = await getSession(sessionToken);
   if (!session || !session.idpRefreshToken) {
@@ -159,8 +170,7 @@ export async function ensureFreshAccessToken(
   let releaseVersion: number | undefined;
 
   if (!lock.acquired) {
-    const existing = await checkRefreshLock(sessionToken);
-    if (!existing || existing.acquiredBy !== requestId) {
+    {
       const startWait = Date.now();
       while (Date.now() - startWait < lockWaitMs) {
         await new Promise(r => setTimeout(r, 200));
@@ -336,6 +346,7 @@ export async function ensureFreshAccessToken(
             console.warn('[ENSURE-FRESH] discard-token clear did not persist - no canonical session row', {
               code,
               requestId,
+              traceId,
             });
           }
         } else {
@@ -343,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,
@@ -353,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 {
@@ -368,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' ||
@@ -480,6 +551,7 @@ export async function ensureFreshAccessToken(
     if (!persisted) {
       console.warn('[ENSURE-FRESH] refresh succeeded but was NOT persisted - no canonical session row', {
         requestId,
+        traceId,
         refreshTokenRotated: hasNewRefresh,
         persisted: false,
       });

package/src/lib/idp-fetch.ts

@@ -28,6 +28,23 @@ export interface IdpFetchResult<T = any> {
    * It used to be dropped here, so no BFF could state the real lock window. Absent otherwise.
    */
   retryAfterSeconds?: number;
+  /** 4.8.10: set when `opts.initFor` returned null for the FIRST call: no request was made. */
+  skipped?: true;
+  /**
+   * 4.8.10: how the refresh that followed a 401/403 ended: the status the internal refresh answered, or null when it threw. Absent
+   * when no refresh was attempted. refresh.ts treats a 401 as "definitively invalid - always discard", i.e. the grant is gone.
+   */
+  refreshStatus?: number | null;
+}
+
+export interface IdpFetchOptions {
+  /**
+   * 4.8.10: a call whose BODY names a token that a refresh ROTATES (logout names the refresh token) cannot be built before the
+   * refresh. Called with the session token AFTER the pre-call refresh, for the first call, and again AFTER the refresh that follows a
+   * 401/403, for the retry. It returns the init to send, or null for "nothing to send": null on the first call returns
+   * `skipped: true` without a request; null on the retry leaves the first answer standing. Absent: `init` is used as before.
+   */
+  initFor?: (sessionToken: string) => Promise<RequestInit | null>;
 }
 
 function buildHeaders(req: NextRequest, bearer?: string, extra?: Record<string, string>) {
@@ -121,14 +138,23 @@ async function ensureFreshAccessToken(req: NextRequest): Promise<{ sessionToken?
 export async function idpFetchJSON<T = any>(
   req: NextRequest,
   targetUrl: string,
-  init: RequestInit = {}
+  init: RequestInit = {},
+  opts: IdpFetchOptions = {}
 ): Promise<IdpFetchResult<T>> {
   let attemptedRefresh = false;
+  let refreshStatus: number | null | undefined;
   let { accessToken, sessionToken, hasRefreshToken } = await ensureFreshAccessToken(req);
 
   assertAbsoluteIdpUrl(targetUrl);
 
-  const makeCall = async (bearer?: string) => {
+  let firstInit: RequestInit = init;
+  if (opts.initFor) {
+    const built = sessionToken ? await opts.initFor(sessionToken) : null;
+    if (!built) return { ok: false, status: 0, json: null, attemptedRefresh: false, skipped: true };
+    firstInit = built;
+  }
+
+  const makeCall = async (bearer?: string, callInit: RequestInit = firstInit) => {
     // NOTE (307290): this fetch is UNGUARDED, and so is the first call to it at
     // the "First attempt" below. Only the JSON PARSE (try/catch immediately
     // after) and the RETRY are guarded. A transport-level failure - DNS, refused,
@@ -141,8 +167,8 @@ export async function idpFetchJSON<T = any>(
     // carve-out. Correcting b4b8ffae's message, which wrongly said every risky
     // branch here is try/caught.
     const res = await fetch(targetUrl, {
-      ...init,
-      headers: buildHeaders(req, bearer, init.headers as any),
+      ...callInit,
+      headers: buildHeaders(req, bearer, callInit.headers as any),
     });
     let json: any = null;
     try { json = await res.json(); } catch { json = null; }
@@ -158,13 +184,15 @@ export async function idpFetchJSON<T = any>(
     try {
       // Use centralized internal API helper for server-to-server calls
       const rf = await internalRefresh(req.headers.get('cookie') || '', sessionToken);
+      refreshStatus = rf.status;
       if (rf.ok) {
         const fresh = await getSession(sessionToken);
-        ({ res, json } = await makeCall(fresh?.idpAccessToken));
+        const retryInit = opts.initFor ? await opts.initFor(sessionToken) : firstInit;
+        if (retryInit) ({ res, json } = await makeCall(fresh?.idpAccessToken, retryInit));
       }
-    } catch {}
+    } catch { if (refreshStatus === undefined) refreshStatus = null; }
   }
 
   const retryAfterSeconds = parseRetryAfterSeconds(res.headers?.get?.('Retry-After'));
-  return { ok: res.ok, status: res.status, json: json as T | null, attemptedRefresh, ...(retryAfterSeconds ? { retryAfterSeconds } : {}) };
+  return { ok: res.ok, status: res.status, json: json as T | null, attemptedRefresh, ...(refreshStatus !== undefined ? { refreshStatus } : {}), ...(retryAfterSeconds ? { retryAfterSeconds } : {}) };
 }

package/src/lib/idp-logout.ts

@@ -0,0 +1,68 @@
+import type { NextRequest } from 'next/server';
+import { idpFetchJSON } from './idp-fetch';
+import { getSession, getBetterAuthSession } from './session-store';
+import { ENV_CONFIG } from '../config/env';
+
+/**
+ * 4.8.10 (BAPert 76255 item 1, 76289): sign-out must end the IdP grant, not only the portal session.
+ *
+ * Core: POST /api/Account/logout, Bearer, body { refresh_token } (DotNetPert 76259). It revokes that refresh token and blacklists the
+ * presented access token. The token is ALWAYS sent: with it omitted Core revokes the caller's NEWEST session, which on a
+ * multi-device user is another device's.
+ *
+ * Outcomes (all three are a SUCCESSFUL sign-out):
+ *   '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 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.
+ *
+ * The session is the one idpFetchJSON resolves from the request cookie. The body is built by `initFor`, AFTER idpFetchJSON's own refresh and again after the refresh that follows a 401: a refresh ROTATES the
+ * refresh token, and a body built earlier would name the old one (NightHawk 76288).
+ */
+export type IdpLogoutOutcome = 'revoked' | 'nothing-to-revoke' | 'grant-already-dead';
+
+export async function revokeSessionAtIdp(req: NextRequest): Promise<IdpLogoutOutcome> {
+  let resolvedSession: string | undefined;
+  const result = await idpFetchJSON(
+    req,
+    `${ENV_CONFIG.IDP_URL}/api/Account/logout`,
+    {},
+    {
+      initFor: async (token) => {
+        resolvedSession = token;
+        let session = await getSession(token);
+        if (!session?.idpRefreshToken) session = (await getBetterAuthSession(token)) ?? session;
+        const refreshToken = session?.idpRefreshToken;
+        if (!refreshToken) return null;
+        return {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ refresh_token: refreshToken }),
+        };
+      },
+    },
+  );
+  if (result.skipped) return 'nothing-to-revoke';
+  if (result.ok) return 'revoked';
+  if (result.attemptedRefresh && result.refreshStatus === 401 && resolvedSession && (await grantWasDiscarded(resolvedSession))) return 'grant-already-dead';
+  throw new Error(`IdP logout answered ${result.status}`);
+}
+
+/**
+ * A refresh 401 is not by itself "the grant is gone" (NightHawk 76295, BAPert 76297): refresh.ts also answers 401 for 'no session', for
+ * the x-session-token rejection and for NO_REFRESH_TOKEN, none of which says anything about the IdP's token. Only its IdP-401 branch
+ * DISCARDS the stored refresh token and WRITES THE MARKER refreshTokenClearedReason 'IDP_DISCARD_TOKEN:<code>'. The marker is the only
+ * proof: an EMPTY token is not (NO_REFRESH_TOKEN has an empty store, and so does a dropped persist with the grant still live at the
+ * IdP). So the grant counts as dead only when the session row exists AND carries that marker. Anything else is UNKNOWN.
+ */
+async function grantWasDiscarded(sessionToken: string): Promise<boolean> {
+  let session = await getSession(sessionToken);
+  if (!session) session = await getBetterAuthSession(sessionToken);
+  if (!session) return false;
+  return String((session as any).refreshTokenClearedReason ?? '').startsWith('IDP_DISCARD_TOKEN');
+}

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/src/routes/auth/logout.ts

@@ -17,6 +17,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession } from '../../server/auth';
 import { deleteSessionEverywhere } from '../../lib/session-store';
+import { revokeSessionAtIdp } from '../../lib/idp-logout';
 import {
   getSessionCookieName,
   getSecureSessionCookieName,
@@ -27,15 +28,29 @@ import {
 import { siteEvents, getClientIp } from '../../lib/site-logger';
 import { logExceptionWithCorrelation } from '../../lib/safe-error-response';
 
-/** 4.8.9: answered (status 500) when the server-side session delete failed. The browser's cookies are cleared either way. */
+/**
+ * 4.8.9: answered (status 500) when a sign-out did not finish. 4.8.10 (BAPert 76297): TWO sentences, one per cause, each true for its
+ * cause, neither promising a retry (the local session is gone, so there is nothing to retry from). The browser's cookies and the local
+ * session are cleared either way.
+ *   SESSION_NOT_ENDED_IDP_MESSAGE    the IdP outcome is UNKNOWN (revoke refused or unreachable, and no IdP discard marker proves the grant dead)
+ *   SESSION_NOT_ENDED_LOCAL_MESSAGE  the local session-store DELETE failed (the server record is still live)
+ * Both causes at once: the LOCAL sentence, because a live server record is the worse and more actionable fact.
+ */
 export const SESSION_NOT_ENDED_CODE = 'SESSION_NOT_ENDED';
-export const SESSION_NOT_ENDED_MESSAGE = 'You were signed out on this device, but we could not end your session on the server. Try signing out again.';
+/**
+ * The machine-readable cause on the 500 body (Nextpert-Scout 76300): the portal never reads response text, so it picks its notice from
+ * this closed set. `code` stays SESSION_NOT_ENDED for 4.8.9 callers; `cause` is additive. Both causes at once: local_delete_failed.
+ * A dead-grant or ordinary success carries neither.
+ */
+export type SessionNotEndedCause = 'idp_unconfirmed' | 'local_delete_failed';
+export const SESSION_NOT_ENDED_IDP_MESSAGE = 'We could not confirm the sign-out with the identity service.';
+export const SESSION_NOT_ENDED_LOCAL_MESSAGE = 'We could not finish signing you out on this device.';
 
 /**
  * POST /api/auth/logout - Sign out and clean up session
  *
  * Performs complete logout:
- * 1. Revokes tokens at IDP (if refresh token available)
+ * 1. Revokes the refresh token at the IDP (POST /api/Account/logout) when the session has one; a failed revoke answers SESSION_NOT_ENDED
  * 2. Deletes session from store
  * 3. Clears session cookies
  */
@@ -54,7 +69,19 @@ export async function POST(req: NextRequest) {
     const sessionId = session.session?.token;
     // 4.8.9: a sign-out that did not end the session must not say it did. The delete below can fail (a faulting store); the
     // cookies are still cleared, but the answer is then a typed failure instead of success:true.
-    let serverDeleteFailed = false;
+    let localDeleteFailed = false;
+    let idpRevokeFailed = false;
+
+    // 4.8.10: end the IdP grant FIRST, while the session still holds its tokens. A failed revoke is the same typed failure as a failed
+    // delete: the IdP refresh token is still valid, so the sign-out did not end the session. The local delete below still runs.
+    if (sessionId) {
+      try {
+        await revokeSessionAtIdp(req);
+      } catch (error) {
+        idpRevokeFailed = true;
+        console.error('[LOGOUT_ROUTE] IdP revoke failed - the IdP refresh token is STILL LIVE:', error);
+      }
+    }
 
     // Delete session from EVERY store — canonical + BA secondary (181922).
     // Canonical-only deletion let the ba: record resurrect the session.
@@ -63,7 +90,7 @@ export async function POST(req: NextRequest) {
         await deleteSessionEverywhere(sessionId);
         console.info('[LOGOUT_ROUTE] Session deleted from store');
       } catch (error) {
-        serverDeleteFailed = true;
+        localDeleteFailed = true;
         console.error('[LOGOUT_ROUTE] Failed to delete session - the server session is STILL LIVE:', error);
       }
     }
@@ -82,8 +109,13 @@ export async function POST(req: NextRequest) {
     }
 
     // Build response that clears session cookies
-    const response = serverDeleteFailed
-      ? NextResponse.json({ success: false, code: SESSION_NOT_ENDED_CODE, message: SESSION_NOT_ENDED_MESSAGE }, { status: 500 })
+    const response = (localDeleteFailed || idpRevokeFailed)
+      ? NextResponse.json(
+          localDeleteFailed
+            ? { success: false, code: SESSION_NOT_ENDED_CODE, cause: 'local_delete_failed' as SessionNotEndedCause, message: SESSION_NOT_ENDED_LOCAL_MESSAGE }
+            : { success: false, code: SESSION_NOT_ENDED_CODE, cause: 'idp_unconfirmed' as SessionNotEndedCause, message: SESSION_NOT_ENDED_IDP_MESSAGE },
+          { status: 500 },
+        )
       : NextResponse.json({
           success: true,
           message: 'Logged out successfully'

package/src/server/auth.ts

@@ -442,7 +442,7 @@ export async function getFreshIdpToken(
     },
     {
       safetyWindowMs: config.safetyWindowMs,
-      requestId: request?.headers?.get('x-request-id') ?? undefined,
+      // 4.8.10 (BAPert 76298 (b)): the request's x-request-id is NOT passed. It used to become the refresh lock's identity.
     }
   );
 

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;