@payez/next-mvp 4.9.0 → 4.11.0

package/src/lib/refresh-in-doubt.ts

@@ -0,0 +1,79 @@
+/**
+ * The IdP fetch timeout and the "refresh in doubt" marker (BAPert 76397 decision 3, corrected by 76403; Core facts DotNetPert 76400).
+ *
+ * THE PROBLEM. Core consumes a refresh token with one atomic UPDATE and has NO reuse grace: re-presenting a used token revokes every newer
+ * refresh token the USER holds, on every device (RevokeDescendantTokens). So when OUR fetch to the IdP times out, we do not know whether Core
+ * consumed the token and minted a replacement whose answer we never saw. The store still holds the token we SENT (nothing was persisted).
+ * Holding the refresh lock only delays the next request by its 60 s TTL; after that the next request re-reads the same token and replays it.
+ *
+ * THE RULE. A timed-out refresh answers 504 UPSTREAM_TIMEOUT and records, on the session row, an IDENTITY (a SHA-256, never the token and
+ * never a prefix of it) of the token that was sent. Any later attempt whose token-to-send matches that identity refuses WITHOUT calling the
+ * IdP: terminal REFRESH_OUTCOME_UNKNOWN / REAUTHENTICATE. One login on one session is better than a user-wide revocation. The marker is
+ * dropped by the same write that stores a DIFFERENT refresh token (session-store `dropStaleDiscardMarker`); nothing tries to resolve the doubt
+ * without a login.
+ *
+ * Leaf module: no imports from the rest of the package, so session-store can use it without a cycle.
+ */
+import { createHash } from 'crypto';
+
+/** How long a refresh fetch (connect, response and body) may take. 5 s lock wait + this + the persist stays well inside the 60 s lock TTL. */
+export const REFRESH_FETCH_TIMEOUT_MS = 10_000;
+
+/** The typed terminal answer for an attempt that would re-send an in-doubt token. */
+export const REFRESH_OUTCOME_UNKNOWN_CODE = 'REFRESH_OUTCOME_UNKNOWN';
+
+/** The typed answer for the timed-out call itself. */
+export const UPSTREAM_TIMEOUT_CODE = 'UPSTREAM_TIMEOUT';
+
+/** A one-way identity for a refresh token. Not reversible and not a prefix. */
+export function refreshTokenIdentity(token: string): string {
+  return createHash('sha256').update(token, 'utf8').digest('hex');
+}
+
+/** The row fields recorded at a timeout. */
+export function inDoubtPatch(sentToken: string): { refreshInDoubtTokenHash: string; refreshInDoubtAt: number } {
+  return { refreshInDoubtTokenHash: refreshTokenIdentity(sentToken), refreshInDoubtAt: Date.now() };
+}
+
+/** True when the token we are about to send is the one a previous attempt left in doubt. */
+export function isRefreshInDoubt(
+  session: { refreshInDoubtTokenHash?: string | null } | null | undefined,
+  tokenToSend: string | null | undefined,
+): boolean {
+  if (!session || typeof session.refreshInDoubtTokenHash !== 'string' || !session.refreshInDoubtTokenHash) return false;
+  if (typeof tokenToSend !== 'string' || tokenToSend.length === 0) return false;
+  return refreshTokenIdentity(tokenToSend) === session.refreshInDoubtTokenHash;
+}
+
+/** True for the error `AbortSignal.timeout` produces (a DOMException named TimeoutError); AbortError is treated the same. */
+export function isTimeoutError(err: unknown): boolean {
+  const name = (err as { name?: string } | null | undefined)?.name;
+  return name === 'TimeoutError' || name === 'AbortError';
+}
+
+/**
+ * The ONLY transport error codes that PROVE the request never left this process (BAPert 76433 item 4): the connection was refused, or the
+ * name did not resolve. Anything else (ECONNRESET, UND_ERR_SOCKET, a timeout, an error with no code) may have happened AFTER the request was
+ * written, so the IdP may have consumed the token: outcome unknown. The cost is lopsided on purpose: a false in-doubt costs one re-login, a
+ * missed one costs a user-wide revocation. Do NOT add a code here without proof it can only occur before the request is sent.
+ */
+export const REQUEST_NEVER_LEFT_CODES: ReadonlySet<string> = new Set(['ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN']);
+
+/** Every `code` on the error, its `cause`, and the members of an AggregateError (undici wraps the socket error in `cause`). */
+function transportCodes(err: unknown, depth = 0, out: string[] = []): string[] {
+  if (!err || typeof err !== 'object' || depth > 4) return out;
+  const e = err as { code?: unknown; cause?: unknown; errors?: unknown };
+  if (typeof e.code === 'string' && e.code) out.push(e.code);
+  if (e.cause) transportCodes(e.cause, depth + 1, out);
+  if (Array.isArray(e.errors)) for (const inner of e.errors) transportCodes(inner, depth + 1, out);
+  return out;
+}
+
+/**
+ * True only when the error carries at least one cause code and EVERY code it carries is in the never-left allowlist. An error with no code
+ * is NOT proof, so it is in-doubt.
+ */
+export function requestNeverLeft(err: unknown): boolean {
+  const codes = transportCodes(err);
+  return codes.length > 0 && codes.every((c) => REQUEST_NEVER_LEFT_CODES.has(c));
+}

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/refresh-token-validator.ts

@@ -1,5 +1,6 @@
 import { jwtDecode } from './jwt-decode';
 import { tokenRefreshLogger } from '../config/logger';
+import { REFRESH_WINDOW_MS } from './refresh-window';
 
 interface RefreshTokenPayload { exp: number; iat: number; jti: string; user_id: string; token_type: string; binding: string; }
 
@@ -38,7 +39,7 @@ export function checkRefreshViability(sessionData: any): RefreshViabilityCheck {
     if (typeof expiresAtMs === 'string') expiresAtMs = parseInt(expiresAtMs, 10);
     if (expiresAtMs < 1000000000000) expiresAtMs = expiresAtMs * 1000;
     accessTokenTimeRemaining = Math.floor((expiresAtMs - now) / 1000);
-    const bufferSec = 5 * 60; // 5 minutes pre-expiry buffer
+    const bufferSec = REFRESH_WINDOW_MS / 1000; // the one refresh window (lib/refresh-window), in seconds
     accessTokenExpired = accessTokenTimeRemaining <= bufferSec;
     tokenRefreshLogger.debug('[REFRESH_VIABILITY] Access token expiration check', { now, expiresAtMs, accessTokenTimeRemaining, bufferSec, accessTokenExpired });
   }

package/src/lib/refresh-window.ts

@@ -0,0 +1,16 @@
+/**
+ * THE freshness window for an IdP access token (BAPert 76397 decision 1; Core facts DotNetPert 76400).
+ *
+ * An access token with this much life left or less is treated as stale and refreshed; with more, it is served as it is. One value for
+ * every path that decides: the mounted refresh route (`api-handlers/auth/refresh`), `ensureFreshAccessToken`, and `lib/idp-fetch`'s own
+ * pre-check. They used to disagree (5 min, 60 s, 5 min), so the same session was "stale" to one path and "fresh" to another, which is how
+ * two callers each rotated a token the other had just rotated.
+ *
+ * WHY 5 MINUTES: Core mints access tokens with a fixed 15-minute lifetime (a code constant, not configuration: Core
+ * `TokenConstants.ACCESS_TOKEN_LIFETIME_MINUTES = 15`, read-only in `TokenSettings`). The ruling is 5 minutes when the lifetime is at least 15
+ * minutes, and lifetime / 3 otherwise. If Core ever shortens the lifetime, this value MUST be revisited: a window at or above the lifetime
+ * makes every request refresh.
+ *
+ * A caller that needs another value passes it explicitly (`ensureFreshAccessToken`'s `safetyWindowMs` option still exists and still wins).
+ */
+export const REFRESH_WINDOW_MS = 5 * 60 * 1000;

package/src/lib/safe-trace-id.ts

@@ -0,0 +1,21 @@
+/**
+ * A caller-supplied trace id (the `x-request-id` header) is attacker-chosen text, and it goes to the log sink (PAY-2376; BAPert 76321 item 4,
+ * NightHawk 76316). Two problems if it is logged as it arrives: a value with a newline forges a log line, and an unbounded value is a log
+ * flood. This is the one place that makes it safe to log: control characters are removed, the length is capped, and anything that is not a
+ * non-empty string becomes `undefined` (so the log carries no trace id rather than a forged one).
+ *
+ * It is for LOG CORRELATION ONLY. It is never a lock identity and never a security decision (the lock id is minted server-side).
+ */
+
+/** Longest trace id that is logged. 64 covers a UUID (36) and common trace formats; longer input is cut, not rejected. */
+export const MAX_TRACE_ID_LENGTH = 64;
+
+// C0 controls (incl. CR, LF, TAB, ESC), DEL, C1 controls (incl. NEL U+0085), and the Unicode line/paragraph separators U+2028 / U+2029.
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g;
+
+export function sanitizeTraceId(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const cleaned = value.replace(CONTROL_CHARS, '').slice(0, MAX_TRACE_ID_LENGTH);
+  return cleaned.length > 0 ? cleaned : undefined;
+}

package/src/lib/session-store.ts

@@ -14,6 +14,7 @@ import { SessionData } from '../models/SessionModel';
 import { getSessionPrefix, getRefreshLockPrefix, getAppSlug } from './app-slug';
 import { extractKidFromToken, decodeIdpAccessToken } from '../auth/utils/token-utils';
 import { tokenLogId } from './token-log-id';
+import { refreshTokenIdentity } from './refresh-in-doubt';
 
 // Re-export SessionData for consumers
 export type { SessionData } from '../models/SessionModel';
@@ -284,7 +285,36 @@ 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 {
+  let 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;
+    s = rest;
+  }
+  // BAPert 76403: the refresh-IN-DOUBT marker (lib/refresh-in-doubt) is cleared by the same write that stores a NEW refresh token, i.e. one
+  // whose identity differs from the one left in doubt. A write that stores the SAME token (any caller spreading the whole row back) does
+  // NOT clear it: that token is still the in-doubt one.
+  if (
+    typeof s.refreshInDoubtTokenHash === 'string' &&
+    typeof s.idpRefreshToken === 'string' && s.idpRefreshToken.length > 0 &&
+    refreshTokenIdentity(s.idpRefreshToken) !== s.refreshInDoubtTokenHash
+  ) {
+    const { refreshInDoubtTokenHash: _hash, refreshInDoubtAt: _doubtAt, ...rest } = s;
+    s = rest;
+  }
+  return s as T;
+}
+
 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 +454,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/lib/token-lifecycle.ts

@@ -26,9 +26,10 @@ import { getSession as getBetterAuthSession } from '../server/auth';
 import { getRedis } from './redis';
 import { getAppSlug } from './app-slug';
 import { tokenLogId } from './token-log-id';
+import { REFRESH_WINDOW_MS } from './refresh-window';
 
-// 5 minute threshold for "needs refresh" - matches refresh handler pattern
-const REFRESH_THRESHOLD_MS = 5 * 60 * 1000;
+// "needs refresh" threshold: THE one freshness window (lib/refresh-window), the same value the refresh route, ensureFreshAccessToken and idp-fetch use.
+const REFRESH_THRESHOLD_MS = REFRESH_WINDOW_MS;
 
 // Concurrent refresh handling configuration
 const CONCURRENT_REFRESH_POLL_INTERVAL_MS = 200; // How often to poll session during concurrent refresh

package/src/models/SessionModel.ts

@@ -59,6 +59,13 @@ export interface SessionData {
 
   /** When the IDP refresh token expires (Unix timestamp ms) */
   idpRefreshTokenExpires?: number;
+  /**
+   * BAPert 76403 (lib/refresh-in-doubt): set when a refresh fetch TIMED OUT. A SHA-256 identity of the refresh token that was sent (never the
+   * token), and when. A later attempt whose token-to-send matches refuses without calling the IdP. Cleared by the write that stores a different
+   * refresh token.
+   */
+  refreshInDoubtTokenHash?: string;
+  refreshInDoubtAt?: number;
 
   /** Decoded IDP access token claims (for quick access without re-decoding) */
   decodedAccessToken?: any;

package/src/server/auth.ts

@@ -407,7 +407,7 @@ export interface FreshIdpTokenConfig {
   idpBaseUrl: string;
   clientId: string;
   refreshEndpoint?: string;
-  /** Refresh if the access token is within this many ms of expiry. Default 60_000. */
+  /** Refresh if the access token is within this many ms of expiry. Default REFRESH_WINDOW_MS (5 min, lib/refresh-window). */
   safetyWindowMs?: number;
 }
 

package/src/stores/authStore.ts

@@ -27,6 +27,7 @@ import {
   getSecureCsrfCookieName
 } from '../lib/app-slug';
 import { tokenLogId } from '../lib/token-log-id';
+import { REFRESH_WINDOW_MS } from '../lib/refresh-window';
 
 // ===============================
 // INTERFACES & TYPES
@@ -752,8 +753,8 @@ export const useAuthStore = create<AuthStore>()(
               const now = Date.now();
               const timeUntilExpiry = tokenExpiry - now;
               
-              // Token should be fresh (not expiring in next 5 minutes)
-              if (timeUntilExpiry < (5 * 60 * 1000)) {
+              // Token should be fresh (not expiring within the one refresh window)
+              if (timeUntilExpiry < REFRESH_WINDOW_MS) {
                 throw new Error(`Fresh token still expires soon: ${timeUntilExpiry}ms`);
               }
               

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;