@payez/next-mvp 4.10.0 → 4.11.0

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.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}`;
@@ -280,12 +281,21 @@ async function deleteSessionEverywhere(sessionToken, appSlug) {
  * today; this is the defence BAPert ruled to keep anyway.
  */
 function dropStaleDiscardMarker(session) {
-    const s = 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;
-        return rest;
-    }
-    return session;
+        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);

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,18 +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;
-    status: number;
-}> | 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.10.0",
+  "version": "4.11.0",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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' },