@payez/next-mvp 4.10.0 → 4.12.0

package/dist/api-handlers/auth/signout.js

@@ -15,6 +15,9 @@ exports.createSignoutHandler = createSignoutHandler;
 const server_1 = require("next/server");
 const headers_1 = require("next/headers");
 const session_store_1 = require("../../lib/session-store");
+const idp_logout_1 = require("../../lib/idp-logout");
+const log_safe_1 = require("../../lib/log-safe");
+const logout_1 = require("../../routes/auth/logout");
 const auth_1 = require("../../server/auth");
 const app_slug_1 = require("../../lib/app-slug");
 const token_log_id_1 = require("../../lib/token-log-id");
@@ -130,9 +133,39 @@ function createSignoutHandler() {
                 console.warn('[SIGNOUT] Manual JWT decode failed to extract session token');
             }
         }
-        // Delete the session from EVERY store (181922): canonical + BA secondary.
-        // Canonical-only deletion let the ba: record resurrect the session.
+        // GOV-023 (BAPert 76687): ending the session ends the IdP GRANT first, the same IdP-first path as routes/auth/logout. Before this, this
+        // handler only deleted the local record, so a consumer who mounted it left the IdP refresh token live until it expired.
+        // A failed or unresolved revoke is the same typed failure as a failed local delete (SESSION_NOT_ENDED + cause); the local delete still
+        // runs and the cookies are cleared either way.
+        let idpRevokeFailed = false;
+        let localDeleteFailed = false;
         if (redisSessionToken) {
+            // Does the stored session hold an IdP refresh token? (revokeSessionAtIdp reads the canonical row, then the Better Auth record.)
+            let heldRefreshToken = false;
+            try {
+                const stored = (await (0, session_store_1.getSession)(redisSessionToken)) ?? (await (0, session_store_1.getBetterAuthSession)(redisSessionToken));
+                heldRefreshToken = !!stored?.idpRefreshToken;
+            }
+            catch {
+                // unknown: treated as "none held", so an unreadable store does not turn a clean sign-out into a failure on its own
+            }
+            try {
+                const outcome = await (0, idp_logout_1.revokeSessionAtIdp)(req);
+                // 'nothing-to-revoke' while a refresh token IS held means the helper could not resolve this session from the request (this
+                // handler also finds the session by decoding the cookie when Better Auth cannot): the grant is NOT ended, so say so.
+                if (outcome === 'nothing-to-revoke' && heldRefreshToken) {
+                    idpRevokeFailed = true;
+                    console.error('[SIGNOUT] IdP revoke could not resolve the session - the IdP refresh token is STILL LIVE');
+                }
+            }
+            catch (revokeError) {
+                idpRevokeFailed = true;
+                console.error(revokeError?.grantLive === true
+                    ? '[SIGNOUT] IdP revoke failed - the IdP refresh token is STILL LIVE:'
+                    : '[SIGNOUT] IdP revoke could not be confirmed (the grant may already be dead):', (0, log_safe_1.errForLog)(revokeError));
+            }
+            // Delete the session from EVERY store (181922): canonical + BA secondary.
+            // Canonical-only deletion let the ba: record resurrect the session.
             try {
                 await (0, session_store_1.deleteSessionEverywhere)(redisSessionToken);
                 console.info('[SIGNOUT] Redis session cleanup successful', {
@@ -140,21 +173,25 @@ function createSignoutHandler() {
                 });
             }
             catch (sessionError) {
-                // Log error but don't fail the signout process
-                console.error('[SIGNOUT] Redis session cleanup failed', { error: sessionError });
+                localDeleteFailed = true;
+                console.error('[SIGNOUT] Redis session cleanup failed - the server session is STILL LIVE:', (0, log_safe_1.errForLog)(sessionError));
             }
         }
         else {
             console.warn('[SIGNOUT] No Redis session token (UUID) extracted from cookie; skipping Redis deletion');
         }
-        // Build response
+        // Build response. A sign-out that did not end the session must not say it did (same typed answer as routes/auth/logout).
         const responseData = {
             success: true,
             message: sessionToken ? 'Session deleted successfully' : 'No active session found',
             sessionDeleted: !!sessionToken,
             chunkCookiesDeleted: chunkCookies.length
         };
-        const response = server_1.NextResponse.json(responseData);
+        const response = (localDeleteFailed || idpRevokeFailed)
+            ? server_1.NextResponse.json(localDeleteFailed
+                ? { success: false, code: logout_1.SESSION_NOT_ENDED_CODE, cause: 'local_delete_failed', message: logout_1.SESSION_NOT_ENDED_LOCAL_MESSAGE }
+                : { success: false, code: logout_1.SESSION_NOT_ENDED_CODE, cause: 'idp_unconfirmed', message: logout_1.SESSION_NOT_ENDED_IDP_MESSAGE }, { status: 500 })
+            : server_1.NextResponse.json(responseData);
         // Always clear cookies, regardless of success/failure (using app-slug prefixed names)
         try {
             response.cookies.delete(sessionCookieName);

package/dist/api-handlers/mfa/backup-code-verify.js

@@ -62,6 +62,7 @@ const test_aware_get_token_1 = require("../../lib/test-aware-get-token");
 const session_store_1 = require("../../lib/session-store");
 const jwt_decode_1 = require("../../lib/jwt-decode");
 const two_factor_verify_failure_1 = require("../../lib/two-factor-verify-failure");
+const log_safe_1 = require("../../lib/log-safe");
 async function POST(req) {
     try {
         const body = await req.json();
@@ -141,7 +142,7 @@ async function POST(req) {
         }, { status: 200 });
     }
     catch (error) {
-        console.error('[VERIFY_BACKUP_CODE] Error:', error);
+        console.error('[VERIFY_BACKUP_CODE] Error:', (0, log_safe_1.errForLog)(error));
         return server_1.NextResponse.json({
             success: false,
             error: 'Failed to verify backup code',

package/dist/api-handlers/mfa/totp-verify.js

@@ -37,6 +37,7 @@ const test_aware_get_token_1 = require("../../lib/test-aware-get-token");
 const session_store_1 = require("../../lib/session-store");
 const jwt_decode_1 = require("../../lib/jwt-decode");
 const two_factor_verify_failure_1 = require("../../lib/two-factor-verify-failure");
+const log_safe_1 = require("../../lib/log-safe");
 async function POST(req) {
     try {
         const body = await req.json();
@@ -141,7 +142,7 @@ async function POST(req) {
         }, { status: 200 });
     }
     catch (error) {
-        console.error('[VERIFY_TOTP] Error:', error);
+        console.error('[VERIFY_TOTP] Error:', (0, log_safe_1.errForLog)(error));
         return server_1.NextResponse.json({
             success: false,
             error: 'Failed to verify code',

package/dist/api-handlers/session/refresh-viability.js

@@ -7,6 +7,7 @@ const refresh_token_validator_1 = require("../../lib/refresh-token-validator");
 const test_aware_get_token_1 = require("../../lib/test-aware-get-token");
 const logger_1 = require("../../config/logger");
 const token_log_id_1 = require("../../lib/token-log-id");
+const log_safe_1 = require("../../lib/log-safe");
 const auth_1 = require("../../server/auth");
 async function GET(req) {
     try {
@@ -53,8 +54,8 @@ async function GET(req) {
     }
     catch (error) {
         const correlationId = globalThis.crypto.randomUUID();
-        logger_1.logger.error('[REFRESH-VIABILITY] Error checking refresh viability', { correlationId, error: error instanceof Error ? error.message : String(error) });
-        // PAY-1438: the exception text stays in the log above; the caller gets the id.
+        logger_1.logger.error('[REFRESH-VIABILITY] Error checking refresh viability', { correlationId, error: (0, log_safe_1.errForLog)(error) });
+        // PAY-1438: the caller gets the id; the log line names the error only (errForLog), never its message (PII-in-logs group 1, BAPert 76553).
         return server_1.NextResponse.json({ canRefresh: false, reason: 'check_error', error: 'Failed to check refresh viability', code: 'INTERNAL_ERROR', correlationId }, { status: 500 });
     }
 }

package/dist/api-handlers/session/viability.js

@@ -14,6 +14,7 @@ const startup_init_1 = require("../../lib/startup-init");
 const idp_client_config_1 = require("../../lib/idp-client-config");
 const token_log_id_1 = require("../../lib/token-log-id");
 const sessions_1 = require("../../vibe/sessions");
+const log_safe_1 = require("../../lib/log-safe");
 async function GET(req) {
     try {
         // Ensure initialization is complete (auth signing secret resolved from IDP)
@@ -213,7 +214,7 @@ async function GET(req) {
         return server_1.NextResponse.json({ authenticated: false });
     }
     catch (error) {
-        console.error('[API Viability] Error checking session viability:', error);
+        console.error('[API Viability] Error checking session viability:', (0, log_safe_1.errForLog)(error));
         return server_1.NextResponse.json({ authenticated: false }, { status: 500 });
     }
 }

package/dist/auth/better-auth.js

@@ -76,6 +76,7 @@ const redis_1 = require("../lib/redis");
 const single_flight_1 = require("../lib/single-flight");
 const session_store_1 = require("../lib/session-store");
 const token_log_id_1 = require("../lib/token-log-id");
+const log_safe_1 = require("../lib/log-safe");
 /**
  * 185121: short sha256 fingerprint for secrets/tokens in log lines — enough
  * to tell "same" from "divergent", never enough to reconstruct. 12 hex chars
@@ -740,7 +741,7 @@ function createBetterAuthInstance(idpConfig, opts = {}) {
                     await deleteSession(key);
                 }
                 catch (err) {
-                    console.warn('[BETTER_AUTH] secondary delete: canonical store cleanup failed:', err);
+                    console.warn('[BETTER_AUTH] secondary delete: canonical store cleanup failed:', (0, log_safe_1.errForLog)(err));
                 }
             },
         },
@@ -1188,7 +1189,7 @@ async function exchangeOAuthForIdpTokens(sessionToken, provider = 'google') {
         return stored;
     }
     catch (err) {
-        console.error('[BETTER_AUTH] IDP token exchange failed:', err instanceof Error ? err.message : String(err));
+        console.error('[BETTER_AUTH] IDP token exchange failed:', (0, log_safe_1.errForLog)(err));
         return false;
     }
 }
@@ -1270,7 +1271,7 @@ async function storeIdpTokensInSession(sessionToken, idpTokenData, authProvider)
         return true;
     }
     catch (err) {
-        console.error('[BETTER_AUTH] storeIdpTokensInSession failed:', err instanceof Error ? err.message : String(err));
+        console.error('[BETTER_AUTH] storeIdpTokensInSession failed:', (0, log_safe_1.errForLog)(err));
         return false;
     }
 }
@@ -1359,14 +1360,14 @@ async function abortOAuthSignIn(callbackResponse, sessionToken, cookieHeader, lo
                 headers.append('set-cookie', sc);
         }
         catch (err) {
-            console.warn('[BETTER_AUTH] abort: Better Auth signOut failed, deleting the record directly:', err instanceof Error ? err.message : String(err));
+            console.warn('[BETTER_AUTH] abort: Better Auth signOut failed, deleting the record directly:', (0, log_safe_1.errForLog)(err));
         }
         try {
             const config = await (0, idp_client_config_1.getIDPClientConfig)();
             await (0, redis_1.getRedis)().del(`ba:${config.clientSlug || (0, app_slug_1.getAppSlug)()}:${sessionToken}`);
         }
         catch (err) {
-            console.error('[BETTER_AUTH] abort: could not delete the Better Auth session record', (0, token_log_id_1.tokenLogId)(sessionToken), err instanceof Error ? err.message : String(err));
+            console.error('[BETTER_AUTH] abort: could not delete the Better Auth session record', (0, token_log_id_1.tokenLogId)(sessionToken), (0, log_safe_1.errForLog)(err));
         }
     }
     for (const sc of expireSetCookies(callbackResponse.headers.getSetCookie?.() ?? []))
@@ -1484,7 +1485,7 @@ function createAuthGetHandler(loginPath = '/account-auth/login') {
                     }
                 }
                 catch (err) {
-                    console.error('[BETTER_AUTH] IDP token exchange failed:', err.message);
+                    console.error('[BETTER_AUTH] IDP token exchange failed:', (0, log_safe_1.errForLog)(err));
                 }
                 if (exchange !== true) {
                     // A specific IdP error code goes on the URL; otherwise the generic OAUTH_SIGN_IN_FAILED.

package/dist/auth/idp-oauth.js

@@ -27,6 +27,7 @@ exports.createIdpOAuthHooks = createIdpOAuthHooks;
  * case-insensitively, at the authorize step). Both come from ONE value: the `redirectURI` of the provider config.
  */
 const jose_1 = require("jose");
+const log_safe_1 = require("../lib/log-safe");
 const DISCOVERY_TTL_MS = 10 * 60 * 1000;
 const HTTP_TIMEOUT_MS = 10_000;
 /** The URI sent at authorize AND token time. Explicit env wins; else the registered {app}/api/auth/callback form. */
@@ -252,7 +253,8 @@ function createIdpOAuthHooks(opts) {
                 console.warn('[BETTER_AUTH] payez-idp token response address is masked or unusable; ignored');
             const email = resolveEmail(payload, responseEmailUsable ? responseEmailRaw : undefined);
             if (!email) {
-                throw new Error(responseMasked ? 'response address is masked' : 'no usable email (needs data.user.email or an email claim, address-shaped, equal when both are present)');
+                // A closed `code` rides on the error so the refusal log tells an operator WHY (errForLog prints a closed UPPER_SNAKE code) with no value (BAPert 76998 E11).
+                throw Object.assign(new Error(responseMasked ? 'response address is masked' : 'no usable email (needs data.user.email or an email claim, address-shaped, equal when both are present)'), { code: responseMasked ? 'RESPONSE_ADDRESS_MASKED' : 'NO_USABLE_EMAIL' });
             }
             const name = (typeof payload.name === 'string' && payload.name.trim()) ||
                 (typeof payload.full_name === 'string' && payload.full_name.trim()) ||
@@ -272,7 +274,7 @@ function createIdpOAuthHooks(opts) {
         }
         catch (err) {
             // Reason only, never the token.
-            console.warn('[BETTER_AUTH] payez-idp access token refused:', err instanceof Error ? err.message : String(err));
+            console.warn('[BETTER_AUTH] payez-idp access token refused:', (0, log_safe_1.errForLog)(err));
             return null;
         }
     }

package/dist/auth/utils/idp-client.js

@@ -19,6 +19,7 @@ exports.idpLogin = idpLogin;
 exports.idpRefreshToken = idpRefreshToken;
 exports.idpVerify2FA = idpVerify2FA;
 exports.idpSend2FACode = idpSend2FACode;
+const log_safe_1 = require("../../lib/log-safe");
 // ============================================================================
 // CONFIGURATION
 // ============================================================================
@@ -95,7 +96,7 @@ async function idpLogin(credentials, clientHeaders) {
         };
     }
     catch (error) {
-        console.error('[IDP_CLIENT] Login request failed:', error);
+        console.error('[IDP_CLIENT] Login request failed:', (0, log_safe_1.errForLog)(error));
         return {
             success: false,
             error: {
@@ -211,7 +212,7 @@ async function idpRefreshToken(refreshToken, mfaContext) {
         };
     }
     catch (error) {
-        console.error('[IDP_CLIENT] Token refresh request failed:', error);
+        console.error('[IDP_CLIENT] Token refresh request failed:', (0, log_safe_1.errForLog)(error));
         return {
             success: false,
             error: {
@@ -261,7 +262,7 @@ async function idpVerify2FA(accessToken, code, method) {
         return { success: true };
     }
     catch (error) {
-        console.error('[IDP_CLIENT] 2FA verification failed:', error);
+        console.error('[IDP_CLIENT] 2FA verification failed:', (0, log_safe_1.errForLog)(error));
         return {
             success: false,
             error: {
@@ -303,7 +304,7 @@ async function idpSend2FACode(accessToken, method) {
         return { success: true };
     }
     catch (error) {
-        console.error('[IDP_CLIENT] Send 2FA code failed:', error);
+        console.error('[IDP_CLIENT] Send 2FA code failed:', (0, log_safe_1.errForLog)(error));
         return {
             success: false,
             error: {

package/dist/auth/utils/token-utils.d.ts

@@ -46,7 +46,7 @@ export declare function extractAmrFromToken(decoded: DecodedIdpAccessToken): str
  * Check if a token expiry timestamp indicates the token needs refresh.
  *
  * @param expiresAt - Token expiry timestamp (Unix milliseconds)
- * @param bufferMs - How early to trigger refresh (default 5 minutes)
+ * @param bufferMs - How early to trigger refresh (default: the one refresh window, `REFRESH_WINDOW_MS`, 5 minutes)
  * @returns true if token is expired or will expire within buffer period
  */
 export declare function tokenNeedsRefresh(expiresAt: number | undefined, bufferMs?: number): boolean;

package/dist/auth/utils/token-utils.js

@@ -20,6 +20,8 @@ exports.msUntilExpiry = msUntilExpiry;
 exports.expClaimToMs = expClaimToMs;
 exports.validateTokenExpiry = validateTokenExpiry;
 const jwt_decode_1 = require("../../lib/jwt-decode");
+const refresh_window_1 = require("../../lib/refresh-window");
+const log_safe_1 = require("../../lib/log-safe");
 // Re-export header utilities for consumers
 var jwt_decode_2 = require("../../lib/jwt-decode");
 Object.defineProperty(exports, "decodeJwtHeader", { enumerable: true, get: function () { return jwt_decode_2.decodeJwtHeader; } });
@@ -38,7 +40,7 @@ function decodeIdpAccessToken(token) {
         return (0, jwt_decode_1.jwtDecode)(token);
     }
     catch (error) {
-        console.error('[TOKEN_UTILS] Failed to decode access token:', error);
+        console.error('[TOKEN_UTILS] Failed to decode access token:', (0, log_safe_1.errForLog)(error));
         return null;
     }
 }
@@ -63,7 +65,7 @@ function decodeIdpAccessTokenFull(token) {
         };
     }
     catch (error) {
-        console.error('[TOKEN_UTILS] Failed to decode access token (full):', error);
+        console.error('[TOKEN_UTILS] Failed to decode access token (full):', (0, log_safe_1.errForLog)(error));
         return null;
     }
 }
@@ -129,10 +131,10 @@ function extractAmrFromToken(decoded) {
  * Check if a token expiry timestamp indicates the token needs refresh.
  *
  * @param expiresAt - Token expiry timestamp (Unix milliseconds)
- * @param bufferMs - How early to trigger refresh (default 5 minutes)
+ * @param bufferMs - How early to trigger refresh (default: the one refresh window, `REFRESH_WINDOW_MS`, 5 minutes)
  * @returns true if token is expired or will expire within buffer period
  */
-function tokenNeedsRefresh(expiresAt, bufferMs = 5 * 60 * 1000) {
+function tokenNeedsRefresh(expiresAt, bufferMs = refresh_window_1.REFRESH_WINDOW_MS) {
     if (!expiresAt) {
         return true; // No expiry info = assume needs refresh
     }
@@ -212,7 +214,7 @@ function validateTokenExpiry(accessToken, cachedExpiresAt) {
         };
     }
     catch (error) {
-        console.error('[TOKEN_UTILS] Failed to validate token expiry:', error);
+        console.error('[TOKEN_UTILS] Failed to validate token expiry:', (0, log_safe_1.errForLog)(error));
         return { valid: false, actualExpiresAt: null, mismatch: false };
     }
 }

package/dist/config/logger.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.redisLogger = exports.tokenRefreshLogger = exports.tokenSyncLogger = exports.tokenLogger = exports.circuitBreakerLogger = exports.apiLogger = exports.idpLogger = exports.authLogger = exports.logger = exports.log = void 0;
 const logging_config_1 = require("./logging-config");
 const vibe_log_transport_1 = require("./vibe-log-transport");
+const log_safe_1 = require("../lib/log-safe");
 let loggingConfig = (0, logging_config_1.getLoggingConfigSync)();
 (0, logging_config_1.startConfigWatching)();
 const isEdgeRuntime = () => {
@@ -48,7 +49,7 @@ const createLogger = () => {
         return winston.createLogger({ level: loggingConfig.logLevel, levels: loggingConfig.levels, format: winston.format.combine(winston.format.timestamp(), winston.format.errors({ stack: true }), winston.format.json()), transports, exitOnError: false });
     }
     catch (error) {
-        console.warn('Failed to initialize Winston logger, falling back to EdgeLogger:', error);
+        console.warn('Failed to initialize Winston logger, falling back to EdgeLogger:', (0, log_safe_1.errForLog)(error));
         return new EdgeLogger();
     }
 };

package/dist/config/logging-config.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.removeConfigWatcher = exports.addConfigWatcher = exports.stopConfigWatching = exports.startConfigWatching = exports.getLoggingConfigSync = exports.getLoggingConfig = exports.loggingConfigManager = void 0;
 const fs_1 = require("fs");
 const fs_2 = require("fs");
+const log_safe_1 = require("../lib/log-safe");
 const isEdgeRuntime = typeof globalThis.EdgeRuntime !== 'undefined' || process.env.NEXT_RUNTIME === 'edge';
 class LoggingConfigManager {
     config = null;
@@ -39,7 +40,7 @@ class LoggingConfigManager {
             return config;
         }
         catch (error) {
-            console.warn(`Failed to load logging config from ${this.configPath}:`, error);
+            console.warn(`Failed to load logging config from ${this.configPath}:`, (0, log_safe_1.errForLog)(error));
             return this.getDefaultConfig();
         }
     }
@@ -61,7 +62,7 @@ class LoggingConfigManager {
         } });
     }
     catch (error) {
-        console.warn('Failed to start watching logging config file:', error);
+        console.warn('Failed to start watching logging config file:', (0, log_safe_1.errForLog)(error));
     } }
     stopWatching() { if (this.isEdgeRuntime || this.isBrowser) {
         return;
@@ -75,7 +76,7 @@ class LoggingConfigManager {
         cb(config);
     }
     catch (error) {
-        console.error('Error in logging config watcher:', error);
+        console.error('Error in logging config watcher:', (0, log_safe_1.errForLog)(error));
     } }); }
     validateAndMergeConfig(rawConfig) {
         const defaults = this.getDefaultConfig();

package/dist/config/vibe-log-transport.js

@@ -15,6 +15,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VibeLogTransport = void 0;
 exports.createVibeLogTransport = createVibeLogTransport;
 const redis_1 = require("../lib/redis");
+const log_safe_1 = require("../lib/log-safe");
 // Dynamic import — winston is a peerDependency and may not be installed.
 // We resolve the base class lazily so builds don't break without it.
 let TransportBase;
@@ -144,7 +145,7 @@ class VibeLogTransport extends TransportBase {
                 this.batch = [...entries, ...this.batch].slice(0, 100);
             }
             // Log to console as fallback
-            console.error('[VibeLogTransport] Failed to flush logs:', err);
+            console.error('[VibeLogTransport] Failed to flush logs:', (0, log_safe_1.errForLog)(err));
         }
         finally {
             this.isFlushing = false;

package/dist/lib/api-handler.js

@@ -21,6 +21,7 @@ const nanoid_1 = require("nanoid");
 const session_store_1 = require("./session-store");
 const test_aware_get_token_1 = require("./test-aware-get-token");
 const internal_api_1 = require("./internal-api");
+const refresh_window_1 = require("./refresh-window");
 // ============================================================================
 // API Response Builder (for backward compatibility)
 // ============================================================================
@@ -189,7 +190,7 @@ class ApiHandler {
             // Skip the optimization (hasRefreshToken check) when access token is missing —
             // some session shapes store the refresh token under different field names,
             // and we still want a refresh attempt to populate the access token.
-            const thresholdMs = 5 * 60 * 1000;
+            const thresholdMs = refresh_window_1.REFRESH_WINDOW_MS;
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const expires = sessionData.idpAccessTokenExpires || sessionData.accessTokenExpires || 0;
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -305,7 +306,7 @@ class ApiHandler {
         try {
             // Double-check if still needs refresh
             const latest = await (0, session_store_1.getSession)(sessionToken);
-            const thresholdMs = 5 * 60 * 1000;
+            const thresholdMs = refresh_window_1.REFRESH_WINDOW_MS;
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const latestAny = latest;
             // Sessions may store the access token under either `accessToken` or `idpAccessToken`,
@@ -348,7 +349,7 @@ class ApiHandler {
                 const session = await (0, session_store_1.getSession)(sessionToken);
                 if (session?.accessToken) {
                     const expires = session.accessTokenExpires || 0;
-                    if ((expires - Date.now()) > (5 * 60 * 1000)) {
+                    if ((expires - Date.now()) > refresh_window_1.REFRESH_WINDOW_MS) {
                         return { success: true };
                     }
                 }

package/dist/lib/ensure-fresh-access-token.d.ts

@@ -4,10 +4,15 @@ export interface EnsureFreshConfig {
     refreshEndpoint?: string;
 }
 export interface EnsureFreshOptions {
-    /** 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;
     /** Max wait while another caller holds the refresh lock. Default 5000. */
     lockWaitMs?: number;
+    /**
+     * The refresh ROUTE sets this (BAPert 76449, R-over-E PR 2): a session with no refresh token is refused with the terminal NO_REFRESH_TOKEN
+     * even when its access token is still fresh, as the route always did. Other callers leave it unset and get `already_fresh` for a fresh token.
+     */
+    requireRefreshToken?: boolean;
     /**
      * 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.)
@@ -20,6 +25,14 @@ export type EnsureFreshResult = {
     accessTokenExpires: number;
     /** True if we refreshed (or a concurrent refresh completed); false if the stored token was already fresh. */
     refreshed: boolean;
+    /**
+     * WHY this result is ok (BAPert 76449, additive; `api-handlers/auth/refresh` reproduces its bodies from it and `lib/token-lifecycle` reads
+     * `already_fresh`): 'already_fresh' = nothing was needed; 'completed_by_concurrent_request' = another request refreshed and we returned
+     * its result; 'refreshed' = THIS call refreshed.
+     */
+    reason: 'refreshed' | 'already_fresh' | 'completed_by_concurrent_request';
+    /** Whether the stored session holds a refresh token (the refresh route reports it in its body). */
+    hasRefreshToken: boolean;
     /**
      * CARD 320072. Is the token in THIS result actually in the session store?
      *
@@ -56,4 +69,14 @@ export type EnsureFreshResult = {
     retryable?: boolean;
     resolution?: string;
 };
+/**
+ * The refresh envelope rule (BAPert 76455 (B)): `success` is a boolean; `success:true` needs a `data` object holding a string `access_token`;
+ * `success:false` needs `error.code` as a string; `meta`, `request_id` and `time_stamp` are optional; a non-2xx can not say success:true.
+ */
+export declare function checkRefreshEnvelope(body: any, httpOk: boolean): {
+    ok: true;
+} | {
+    ok: false;
+    why: string;
+};
 export declare function ensureFreshAccessToken(sessionToken: string, config: EnsureFreshConfig, options?: EnsureFreshOptions): Promise<EnsureFreshResult>;