@payez/next-mvp 4.9.0 → 4.11.0

package/dist/lib/refresh-in-doubt.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUEST_NEVER_LEFT_CODES = exports.UPSTREAM_TIMEOUT_CODE = exports.REFRESH_OUTCOME_UNKNOWN_CODE = exports.REFRESH_FETCH_TIMEOUT_MS = void 0;
+exports.refreshTokenIdentity = refreshTokenIdentity;
+exports.inDoubtPatch = inDoubtPatch;
+exports.isRefreshInDoubt = isRefreshInDoubt;
+exports.isTimeoutError = isTimeoutError;
+exports.requestNeverLeft = requestNeverLeft;
+/**
+ * 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.
+ */
+const crypto_1 = require("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. */
+exports.REFRESH_FETCH_TIMEOUT_MS = 10_000;
+/** The typed terminal answer for an attempt that would re-send an in-doubt token. */
+exports.REFRESH_OUTCOME_UNKNOWN_CODE = 'REFRESH_OUTCOME_UNKNOWN';
+/** The typed answer for the timed-out call itself. */
+exports.UPSTREAM_TIMEOUT_CODE = 'UPSTREAM_TIMEOUT';
+/** A one-way identity for a refresh token. Not reversible and not a prefix. */
+function refreshTokenIdentity(token) {
+    return (0, crypto_1.createHash)('sha256').update(token, 'utf8').digest('hex');
+}
+/** The row fields recorded at a timeout. */
+function inDoubtPatch(sentToken) {
+    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. */
+function isRefreshInDoubt(session, tokenToSend) {
+    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. */
+function isTimeoutError(err) {
+    const name = err?.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.
+ */
+exports.REQUEST_NEVER_LEFT_CODES = 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, depth = 0, out = []) {
+    if (!err || typeof err !== 'object' || depth > 4)
+        return out;
+    const e = err;
+    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.
+ */
+function requestNeverLeft(err) {
+    const codes = transportCodes(err);
+    return codes.length > 0 && codes.every((c) => exports.REQUEST_NEVER_LEFT_CODES.has(c));
+}

package/dist/lib/refresh-rotation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 declare function rotatedRowIsUsable<T extends {
+    idpAccessToken?: string | null;
+    idpAccessTokenExpires?: number | null;
+}>(session: T | null | undefined, now?: number): session is T & {
+    idpAccessToken: string;
+    idpAccessTokenExpires: number;
+};

package/dist/lib/refresh-rotation.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rotatedRowIsUsable = rotatedRowIsUsable;
+/**
+ * 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.
+ */
+function rotatedRowIsUsable(session, now = Date.now()) {
+    return !!(session && session.idpAccessToken && session.idpAccessTokenExpires && session.idpAccessTokenExpires > now);
+}

package/dist/lib/refresh-token-validator.js

@@ -7,6 +7,7 @@ exports.getRefreshTokenTimeRemaining = getRefreshTokenTimeRemaining;
 exports.checkRefreshViability = checkRefreshViability;
 const jwt_decode_1 = require("./jwt-decode");
 const logger_1 = require("../config/logger");
+const refresh_window_1 = require("./refresh-window");
 function isRefreshTokenValid(token) {
     if (!token)
         return false;
@@ -81,7 +82,7 @@ function checkRefreshViability(sessionData) {
         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_1.REFRESH_WINDOW_MS / 1000; // the one refresh window (lib/refresh-window), in seconds
         accessTokenExpired = accessTokenTimeRemaining <= bufferSec;
         logger_1.tokenRefreshLogger.debug('[REFRESH_VIABILITY] Access token expiration check', { now, expiresAtMs, accessTokenTimeRemaining, bufferSec, accessTokenExpired });
     }

package/dist/lib/refresh-window.d.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 declare const REFRESH_WINDOW_MS: number;

package/dist/lib/refresh-window.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REFRESH_WINDOW_MS = void 0;
+/**
+ * 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).
+ */
+exports.REFRESH_WINDOW_MS = 5 * 60 * 1000;

package/dist/lib/safe-trace-id.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 declare const MAX_TRACE_ID_LENGTH = 64;
+export declare function sanitizeTraceId(value: unknown): string | undefined;

package/dist/lib/safe-trace-id.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TRACE_ID_LENGTH = void 0;
+exports.sanitizeTraceId = sanitizeTraceId;
+/** Longest trace id that is logged. 64 covers a UUID (36) and common trace formats; longer input is cut, not rejected. */
+exports.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;
+function sanitizeTraceId(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const cleaned = value.replace(CONTROL_CHARS, '').slice(0, exports.MAX_TRACE_ID_LENGTH);
+    return cleaned.length > 0 ? cleaned : undefined;
+}

package/dist/lib/session-store.d.ts

@@ -93,11 +93,6 @@ export declare function deleteSession(sessionToken: string): Promise<void>;
  * them differently, pass appSlug explicitly.
  */
 export declare function deleteSessionEverywhere(sessionToken: string, appSlug?: string): Promise<void>;
-/**
- * Sets a session directly (for testing or migrations).
- * @param sessionToken The session token.
- * @param data The session data.
- */
 export declare function setSession(sessionToken: string, data: SessionData): Promise<void>;
 /**
  * Updates tokens within an existing session.

package/dist/lib/session-store.js

@@ -43,6 +43,7 @@ const crypto_1 = require("crypto");
 const app_slug_1 = require("./app-slug");
 const token_utils_1 = require("../auth/utils/token-utils");
 const token_log_id_1 = require("./token-log-id");
+const refresh_in_doubt_1 = require("./refresh-in-doubt");
 // Use app-slug prefixes for multi-app isolation
 const getSessionKey = (token) => `${(0, app_slug_1.getSessionPrefix)()}${token}`;
 const getRefreshLockKey = (token) => `${(0, app_slug_1.getRefreshLockPrefix)()}${token}`;
@@ -271,7 +272,33 @@ async function deleteSessionEverywhere(sessionToken, appSlug) {
  * @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(session) {
+    let s = session;
+    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 &&
+        (0, refresh_in_doubt_1.refreshTokenIdentity)(s.idpRefreshToken) !== s.refreshInDoubtTokenHash) {
+        const { refreshInDoubtTokenHash: _hash, refreshInDoubtAt: _doubtAt, ...rest } = s;
+        s = rest;
+    }
+    return s;
+}
 async function setSession(sessionToken, data) {
+    data = dropStaleDiscardMarker(data);
     const key = getSessionKey(sessionToken);
     const versionKey = getSessionVersionKey(sessionToken);
     await redis_1.default.multi()
@@ -405,7 +432,7 @@ async function updateSession(sessionToken, updates) {
         });
     }
     // 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_1.default.multi()
         .setex(key, exports.SESSION_TTL, JSON.stringify(updatedSession))

package/dist/lib/token-lifecycle.js

@@ -28,8 +28,9 @@ const auth_1 = require("../server/auth");
 const redis_1 = require("./redis");
 const app_slug_1 = require("./app-slug");
 const token_log_id_1 = require("./token-log-id");
-// 5 minute threshold for "needs refresh" - matches refresh handler pattern
-const REFRESH_THRESHOLD_MS = 5 * 60 * 1000;
+const refresh_window_1 = require("./refresh-window");
+// "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_1.REFRESH_WINDOW_MS;
 // Concurrent refresh handling configuration
 const CONCURRENT_REFRESH_POLL_INTERVAL_MS = 200; // How often to poll session during concurrent refresh
 const CONCURRENT_REFRESH_MAX_WAIT_MS = 8000; // Max time to wait for concurrent refresh to complete

package/dist/models/SessionModel.d.ts

@@ -38,6 +38,13 @@ export interface SessionData {
     idpAccessTokenExpires: number;
     /** 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/dist/routes/auth/refresh.d.ts

@@ -14,17 +14,4 @@
  * @since auth-ready-v2
  */
 import { NextRequest } from 'next/server';
-export declare function POST(req: NextRequest): Promise<import("next/server").NextResponse<{
-    error: string;
-    code: string;
-}> | import("next/server").NextResponse<{
-    error: any;
-    code: any;
-    discardToken: boolean;
-    retryable: boolean;
-    resolution: any;
-}> | import("next/server").NextResponse<{
-    refreshed: boolean;
-    accessTokenExpires: number;
-    hasRefreshToken: boolean;
-}>>;
+export declare function POST(req: NextRequest): Promise<import("next/server").NextResponse<unknown>>;

package/dist/server/auth.d.ts

@@ -153,7 +153,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/dist/stores/authStore.js

@@ -56,6 +56,7 @@ const signalr_1 = require("@microsoft/signalr");
 const signalrActivityService_1 = require("../services/signalrActivityService");
 const app_slug_1 = require("../lib/app-slug");
 const token_log_id_1 = require("../lib/token-log-id");
+const refresh_window_1 = require("../lib/refresh-window");
 // ===============================
 // CACHE CONFIGURATION
 // ===============================
@@ -520,8 +521,8 @@ exports.useAuthStore = (0, zustand_1.create)()((0, middleware_1.devtools)((set,
                     const tokenExpiry = decoded.exp * 1000;
                     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_1.REFRESH_WINDOW_MS) {
                         throw new Error(`Fresh token still expires soon: ${timeUntilExpiry}ms`);
                     }
                     logger_1.authLogger.info('[AuthStore] Session rehydration successful', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.9.0",
+  "version": "4.11.0",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,7 +8,8 @@
     "dist",
     "scripts",
     "src",
-    "POST-INSTALL.md"
+    "POST-INSTALL.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "node -e \"const fs=require('fs');fs.rmSync('dist',{recursive:true,force:true});fs.rmSync('tsconfig.tsbuildinfo',{force:true})\" && npx tsc --project tsconfig.json",
@@ -669,16 +670,6 @@
       "require": "./dist/stores/authStore.js",
       "default": "./stores/authStore.js"
     },
-    "./api": {
-      "types": "./dist/api/index.d.ts",
-      "require": "./dist/api/index.js",
-      "default": "./dist/api/index.js"
-    },
-    "./api/auth-handler": {
-      "types": "./dist/api/auth-handler.d.ts",
-      "require": "./dist/api/auth-handler.js",
-      "default": "./dist/api/auth-handler.js"
-    },
     "./routes/auth/refresh": {
       "types": "./dist/routes/auth/refresh.d.ts",
       "require": "./dist/routes/auth/refresh.js",

package/scripts/verify-release-provenance.mjs

@@ -103,6 +103,7 @@ const CLASSES = [
   { cls: 'VERIFIED', test: (p) => p.startsWith('src/') },
   { cls: 'VERIFIED', test: (p) => p.startsWith('scripts/') },
   { cls: 'VERIFIED', test: (p) => p === 'POST-INSTALL.md' },
+  { cls: 'VERIFIED', test: (p) => p === 'CHANGELOG.md' },
   // npm always ships README regardless of "files"; it is committed, so verify it.
   { cls: 'VERIFIED', test: (p) => p === 'README.md' },
   { cls: 'VERIFIED', test: (p) => p === 'LICENSE' || p === 'LICENCE' },