@payez/next-mvp 4.11.0 → 4.12.0

package/src/api-handlers/session/refresh-viability.ts

@@ -4,6 +4,7 @@ import { checkRefreshViability } from '../../lib/refresh-token-validator';
 import { getTokenTestAware } from '../../lib/test-aware-get-token';
 import { logger } from '../../config/logger';
 import { tokenLogId } from '../../lib/token-log-id';
+import { errForLog } from '../../lib/log-safe';
 import { resolveSessionState } from '../../server/auth';
 
 export async function GET(req: NextRequest) {
@@ -49,8 +50,8 @@ export async function GET(req: NextRequest) {
     return NextResponse.json({ canRefresh: viabilityCheck.canRefresh, reason: viabilityCheck.reason, timeRemaining: viabilityCheck.timeRemaining, expiresAt: viabilityCheck.expiresAt, accessTokenExpired: viabilityCheck.accessTokenExpired, accessTokenTimeRemaining: viabilityCheck.accessTokenTimeRemaining, sessionTokenId: tokenLogId(finalSessionToken), twoFactorComplete: sessionData.mfaVerified ?? false, userId: sessionData.userId, refreshInProgress: false });
   } catch (error) {
     const correlationId = globalThis.crypto.randomUUID();
-    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.error('[REFRESH-VIABILITY] Error checking refresh viability', { correlationId, error: 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 NextResponse.json({ canRefresh: false, reason: 'check_error', error: 'Failed to check refresh viability', code: 'INTERNAL_ERROR', correlationId }, { status: 500 });
   }
 }

package/src/api-handlers/session/viability.ts

@@ -12,6 +12,7 @@ import { isInitializationFailed, ensureInitialized } from '../../lib/startup-ini
 import { getIDPClientConfig } from '../../lib/idp-client-config';
 import { tokenLogId } from '../../lib/token-log-id';
 import { getRevocationStatus, warnNonNumericUserId, resolveNumericIdpUserId, type RevocationStatus } from '../../vibe/sessions';
+import { errForLog } from '../../lib/log-safe';
 
 export async function GET(req: NextRequest) {
   try {
@@ -233,7 +234,7 @@ export async function GET(req: NextRequest) {
     return NextResponse.json({ authenticated: false });
 
   } catch (error) {
-    console.error('[API Viability] Error checking session viability:', error);
+    console.error('[API Viability] Error checking session viability:', errForLog(error));
     return NextResponse.json({ authenticated: false }, { status: 500 });
   }
 }

package/src/auth/better-auth.ts

@@ -33,6 +33,7 @@ import { getRedis } from '../lib/redis';
 import { createSingleFlight, type SingleFlight } from '../lib/single-flight';
 import { SESSION_TTL } from '../lib/session-store';
 import { tokenLogId } from '../lib/token-log-id';
+import { errForLog } from '../lib/log-safe';
 
 /**
  * 185121: short sha256 fingerprint for secrets/tokens in log lines — enough
@@ -855,7 +856,7 @@ export function createBetterAuthInstance(
           const { deleteSession } = await import('../lib/session-store');
           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:', errForLog(err));
         }
       },
     },
@@ -1356,7 +1357,7 @@ export async function exchangeOAuthForIdpTokens(
     // true = success (tokens stored). false = a non-IdP failure with no specific code (generic abort).
     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:', errForLog(err));
     return false;
   }
 }
@@ -1446,7 +1447,7 @@ export async function storeIdpTokensInSession(
 
     return true;
   } catch (err) {
-    console.error('[BETTER_AUTH] storeIdpTokensInSession failed:', err instanceof Error ? err.message : String(err));
+    console.error('[BETTER_AUTH] storeIdpTokensInSession failed:', errForLog(err));
     return false;
   }
 }
@@ -1547,13 +1548,13 @@ async function abortOAuthSignIn(
       const out = await auth?.api?.signOut?.({ headers: new Headers({ cookie: cookieHeader }), asResponse: true });
       for (const sc of (out as Response | undefined)?.headers?.getSetCookie?.() ?? []) 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:', errForLog(err));
     }
     try {
       const config = await getIDPClientConfig();
       await getRedis().del(`ba:${config.clientSlug || getAppSlug()}:${sessionToken}`);
     } catch (err) {
-      console.error('[BETTER_AUTH] abort: could not delete the Better Auth session record', tokenLogId(sessionToken), err instanceof Error ? err.message : String(err));
+      console.error('[BETTER_AUTH] abort: could not delete the Better Auth session record', tokenLogId(sessionToken), errForLog(err));
     }
   }
   for (const sc of expireSetCookies(callbackResponse.headers.getSetCookie?.() ?? [])) headers.append('set-cookie', sc);
@@ -1673,7 +1674,7 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
           }
         }
       } catch (err: any) {
-        console.error('[BETTER_AUTH] IDP token exchange failed:', err.message);
+        console.error('[BETTER_AUTH] IDP token exchange failed:', errForLog(err));
       }
       if (exchange !== true) {
         // A specific IdP error code goes on the URL; otherwise the generic OAUTH_SIGN_IN_FAILED.

package/src/auth/idp-oauth.ts

@@ -19,6 +19,7 @@
  * case-insensitively, at the authorize step). Both come from ONE value: the `redirectURI` of the provider config.
  */
 import { createRemoteJWKSet, decodeProtectedHeader, jwtVerify, type JWTVerifyGetKey } from 'jose';
+import { errForLog } from '../lib/log-safe';
 
 export interface IdpTokenGrant {
   accessToken: string;
@@ -281,7 +282,11 @@ export function createIdpOAuthHooks(opts: IdpOAuthHookOptions) {
       if (responseMasked) console.warn('[BETTER_AUTH] payez-idp token response address is masked or unusable; ignored');
       const email = resolveEmail(payload as Record<string, unknown>, 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()) ||
@@ -301,7 +306,7 @@ export function createIdpOAuthHooks(opts: IdpOAuthHookOptions) {
       return { id: claims.sub, email: claims.email, name: claims.name, emailVerified: claims.emailVerified };
     } 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:', errForLog(err));
       return null;
     }
   }

package/src/auth/utils/idp-client.ts

@@ -18,6 +18,7 @@ import type {
   IdpRefreshResponse,
   LoginCredentials,
 } from '../types/auth-types';
+import { errForLog } from '../../lib/log-safe';
 
 // ============================================================================
 // CONFIGURATION
@@ -109,7 +110,7 @@ export async function idpLogin(
       result: responseData.result,
     };
   } catch (error) {
-    console.error('[IDP_CLIENT] Login request failed:', error);
+    console.error('[IDP_CLIENT] Login request failed:', errForLog(error));
     return {
       success: false,
       error: {
@@ -246,7 +247,7 @@ export async function idpRefreshToken(
       },
     };
   } catch (error) {
-    console.error('[IDP_CLIENT] Token refresh request failed:', error);
+    console.error('[IDP_CLIENT] Token refresh request failed:', errForLog(error));
     return {
       success: false,
       error: {
@@ -304,7 +305,7 @@ export async function idpVerify2FA(
 
     return { success: true };
   } catch (error) {
-    console.error('[IDP_CLIENT] 2FA verification failed:', error);
+    console.error('[IDP_CLIENT] 2FA verification failed:', errForLog(error));
     return {
       success: false,
       error: {
@@ -352,7 +353,7 @@ export async function idpSend2FACode(
 
     return { success: true };
   } catch (error) {
-    console.error('[IDP_CLIENT] Send 2FA code failed:', error);
+    console.error('[IDP_CLIENT] Send 2FA code failed:', errForLog(error));
     return {
       success: false,
       error: {

package/src/auth/utils/token-utils.ts

@@ -10,6 +10,7 @@
 import { jwtDecode, decodeJwtHeader, extractKidFromToken, JwtHeader } from '../../lib/jwt-decode';
 import type { DecodedIdpAccessToken } from '../types/auth-types';
 import { REFRESH_WINDOW_MS } from '../../lib/refresh-window';
+import { errForLog } from '../../lib/log-safe';
 
 // Re-export header utilities for consumers
 export { decodeJwtHeader, extractKidFromToken, type JwtHeader } from '../../lib/jwt-decode';
@@ -28,7 +29,7 @@ export function decodeIdpAccessToken(token: string): DecodedIdpAccessToken | nul
   try {
     return jwtDecode<DecodedIdpAccessToken>(token);
   } catch (error) {
-    console.error('[TOKEN_UTILS] Failed to decode access token:', error);
+    console.error('[TOKEN_UTILS] Failed to decode access token:', errForLog(error));
     return null;
   }
 }
@@ -59,7 +60,7 @@ export function decodeIdpAccessTokenFull(token: string): {
       bearerKeyId: header.kid,
     };
   } catch (error) {
-    console.error('[TOKEN_UTILS] Failed to decode access token (full):', error);
+    console.error('[TOKEN_UTILS] Failed to decode access token (full):', errForLog(error));
     return null;
   }
 }
@@ -238,7 +239,7 @@ export function validateTokenExpiry(
       mismatch,
     };
   } catch (error) {
-    console.error('[TOKEN_UTILS] Failed to validate token expiry:', error);
+    console.error('[TOKEN_UTILS] Failed to validate token expiry:', errForLog(error));
     return { valid: false, actualExpiresAt: null, mismatch: false };
   }
 }

package/src/config/logger.ts

@@ -1,6 +1,7 @@
 import { getLoggingConfigSync, startConfigWatching, addConfigWatcher } from './logging-config';
 import { LoggingConfig } from '../types/logging';
 import { createVibeLogTransport } from './vibe-log-transport';
+import { errForLog } from '../lib/log-safe';
 
 let loggingConfig: LoggingConfig = getLoggingConfigSync();
 startConfigWatching();
@@ -41,7 +42,7 @@ const createLogger = (): any => {
       console.log('[LOGGER] Vibe Redis transport DISABLED - no REDIS_URL configured');
     }
     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); return new EdgeLogger(); }
+  } catch (error) { console.warn('Failed to initialize Winston logger, falling back to EdgeLogger:', errForLog(error)); return new EdgeLogger(); }
 };
 
 let logger: any;

package/src/config/logging-config.ts

@@ -1,6 +1,7 @@
 import { promises as fs } from 'fs';
 import { watch, existsSync } from 'fs';
 import { LoggingConfig, LogLevel } from '../types/logging';
+import { errForLog } from '../lib/log-safe';
 
 const isEdgeRuntime = typeof (globalThis as any).EdgeRuntime !== 'undefined' || process.env.NEXT_RUNTIME === 'edge';
 
@@ -35,7 +36,7 @@ class LoggingConfigManager {
       const config = this.validateAndMergeConfig(rawConfig);
       this.config = config; this.notifyWatchers(config); 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}:`, errForLog(error));
       return this.getDefaultConfig();
     }
   }
@@ -43,11 +44,11 @@ class LoggingConfigManager {
   async getConfig(): Promise<LoggingConfig> { if (!this.config) { return await this.loadConfig(); } return this.config; }
   getConfigSync(): LoggingConfig { return this.config || this.getDefaultConfig(); }
 
-  startWatching(): void { if (this.isEdgeRuntime || this.isBrowser) { return; } if (this.fileWatcher) { return; } try { if (!existsSync(this.configPath)) { console.warn(`Logging config file not found at ${this.configPath} — watch disabled`); return; } this.fileWatcher = watch(this.configPath, { persistent: false }, (eventType) => { if (eventType === 'change') { this.loadConfig().catch(console.error); } }); } catch (error) { console.warn('Failed to start watching logging config file:', error); } }
+  startWatching(): void { if (this.isEdgeRuntime || this.isBrowser) { return; } if (this.fileWatcher) { return; } try { if (!existsSync(this.configPath)) { console.warn(`Logging config file not found at ${this.configPath} — watch disabled`); return; } this.fileWatcher = watch(this.configPath, { persistent: false }, (eventType) => { if (eventType === 'change') { this.loadConfig().catch(console.error); } }); } catch (error) { console.warn('Failed to start watching logging config file:', errForLog(error)); } }
   stopWatching(): void { if (this.isEdgeRuntime || this.isBrowser) { return; } if (this.fileWatcher) { this.fileWatcher.close(); this.fileWatcher = null; } }
   addWatcher(callback: (config: LoggingConfig) => void): void { this.watchers.add(callback); }
   removeWatcher(callback: (config: LoggingConfig) => void): void { this.watchers.delete(callback); }
-  private notifyWatchers(config: LoggingConfig): void { this.watchers.forEach(cb => { try { cb(config); } catch (error) { console.error('Error in logging config watcher:', error); } }); }
+  private notifyWatchers(config: LoggingConfig): void { this.watchers.forEach(cb => { try { cb(config); } catch (error) { console.error('Error in logging config watcher:', errForLog(error)); } }); }
 
   private validateAndMergeConfig(rawConfig: any): LoggingConfig {
     const defaults = this.getDefaultConfig();

package/src/config/vibe-log-transport.ts

@@ -12,6 +12,7 @@
  */
 
 import { getRedis } from '../lib/redis';
+import { errForLog } from '../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.
@@ -188,7 +189,7 @@ export 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:', errForLog(err));
     } finally {
       this.isFlushing = false;
     }

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

@@ -35,6 +35,7 @@ import {
   isRefreshInDoubt,
   requestNeverLeft,
 } from './refresh-in-doubt';
+import { errForLog } from './log-safe';
 
 export interface EnsureFreshConfig {
   idpBaseUrl: string;
@@ -412,7 +413,7 @@ export async function ensureFreshAccessToken(
       try {
         await updateSession(sessionToken, inDoubtPatch(sentRefreshToken as string));
       } catch (markError) {
-        console.error('[ENSURE-FRESH] could not record the in-doubt marker', { error: markError instanceof Error ? markError.message : String(markError) });
+        console.error('[ENSURE-FRESH] could not record the in-doubt marker', { error: errForLog(markError) });
       }
       return {
         ok: false,

package/src/lib/geolocation.ts

@@ -1,3 +1,4 @@
+import { errForLog } from './log-safe';
 /**
  * =============================================================================
  * GEOLOCATION UTILITY
@@ -103,7 +104,7 @@ export async function getPublicIP(): Promise<string | null> {
         // Validate it looks like an IP
         if (ip && /^[\d.]+$/.test(ip) || /^[a-f0-9:]+$/i.test(ip)) {
           cachedPublicIP = { ip, timestamp: Date.now() };
-          console.log(`[geolocation] Public IP resolved: ${ip}`);
+          console.log("[geolocation] Public IP resolved");
           return ip;
         }
       }
@@ -163,7 +164,7 @@ export async function getLocationFromIP(ip: string, resolvePublicIP: boolean = t
     if (resolvePublicIP) {
       const publicIP = await getPublicIP();
       if (publicIP && !isPrivateIP(publicIP)) {
-        console.log(`[geolocation] Private IP ${ip} -> using public IP ${publicIP}`);
+        console.log("[geolocation] Private IP -> using the resolved public IP");
         // Recursively call with public IP (but don't resolve again to prevent loops)
         return getLocationFromIP(publicIP, false);
       }
@@ -201,7 +202,7 @@ export async function getLocationFromIP(ip: string, resolvePublicIP: boolean = t
     const data = await response.json();
 
     if (data.status !== 'success') {
-      console.warn(`[geolocation] Lookup failed for ${ip}: ${data.message}`);
+      console.warn("[geolocation] Lookup failed (upstream refused)");
       // Cache the failure to avoid repeated lookups
       geoCache.set(ip, { location: null, timestamp: Date.now() });
       return null;
@@ -224,7 +225,7 @@ export async function getLocationFromIP(ip: string, resolvePublicIP: boolean = t
     return location;
 
   } catch (error) {
-    console.error(`[geolocation] Error looking up ${ip}:`, error);
+    console.error("[geolocation] lookup failed:", errForLog(error)); // no IP on a routine line (BAPert 76553 Q1)
     return null;
   }
 }

package/src/lib/idp-client-config.ts

@@ -43,6 +43,7 @@
 import 'server-only';
 import { createHash, randomUUID } from 'crypto';
 import { markNeverInResponse } from './never-in-response';
+import { errForLog } from './log-safe';
 // REDIS IS IMPORTED LAZILY, AND THAT IS LOAD-BEARING.
 // A module-scope `import redis from './redis'` drags ioredis into EVERY bundle that
 // touches this file - including instrumentation.ts. Next compiles the instrumentation
@@ -360,7 +361,7 @@ async function getConfigFromRedis(): Promise<IDPClientConfig | null> {
 
         return parsed.config;
     } catch (error) {
-        console.warn('[IDP_CONFIG] Failed to read from Redis cache:', error);
+        console.warn('[IDP_CONFIG] Failed to read from Redis cache:', errForLog(error));
         return null;
     }
 }
@@ -377,7 +378,7 @@ async function setConfigInRedis(config: IDPClientConfig): Promise<void> {
         // Store with TTL slightly longer than the logical expiry to allow for clock skew
         await (await getRedis()).set(key, JSON.stringify(data), 'EX', ttlSeconds + 10);
     } catch (error) {
-        console.warn('[IDP_CONFIG] Failed to write to Redis cache:', error);
+        console.warn('[IDP_CONFIG] Failed to write to Redis cache:', errForLog(error));
     }
 }
 
@@ -633,7 +634,7 @@ export async function clearConfigRedisCache(): Promise<void> {
         await (await getRedis()).del(key);
         console.log('[IDP_CONFIG] Redis cache cleared:', key);
     } catch (error) {
-        console.warn('[IDP_CONFIG] Failed to clear Redis cache:', error);
+        console.warn('[IDP_CONFIG] Failed to clear Redis cache:', errForLog(error));
     }
 }
 

package/src/lib/idp-fetch.ts

@@ -46,6 +46,14 @@ export interface IdpFetchOptions {
    * `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>;
+  /**
+   * 4.12: the refresh that follows a 401/403 is done by THIS function instead of the HTTP self-call to /api/auth/refresh. Sign-out supplies one that
+   * calls `ensureFreshAccessToken` in-process with a window that cannot be "fresh": a logout 401 with a locally-fresh token usually means Core
+   * invalidated the token (password change), and only the IdP's answer to a real refresh (401 + the discard marker = the grant is dead; success =
+   * the grant is live) can say which. No header on the public refresh route, so nothing a browser sends can force a refresh (BAPert 77022).
+   * Returns the status the refresh route would have answered. Absent: `internalRefresh` as before.
+   */
+  refreshOnAuthFailure?: (sessionToken: string) => Promise<{ ok: boolean; status: number }>;
 }
 
 function buildHeaders(req: NextRequest, bearer?: string, extra?: Record<string, string>) {
@@ -184,7 +192,9 @@ export async function idpFetchJSON<T = any>(
     attemptedRefresh = true;
     try {
       // Use centralized internal API helper for server-to-server calls
-      const rf = await internalRefresh(req.headers.get('cookie') || '', sessionToken);
+      const rf = opts.refreshOnAuthFailure
+        ? await opts.refreshOnAuthFailure(sessionToken)
+        : await internalRefresh(req.headers.get('cookie') || '', sessionToken);
       refreshStatus = rf.status;
       if (rf.ok) {
         const fresh = await getSession(sessionToken);

package/src/lib/idp-logout.ts

@@ -26,6 +26,19 @@ import { ENV_CONFIG } from '../config/env';
  */
 export type IdpLogoutOutcome = 'revoked' | 'nothing-to-revoke' | 'grant-already-dead';
 
+/**
+ * The revoke could not be confirmed. `grantLive` is true ONLY when the IdP itself showed the grant is alive: the forced refresh SUCCEEDED (it issued
+ * new tokens) and the logout still did not end it. Every other unknown (a transport error, a 5xx, a refresh that threw or answered something
+ * else) leaves it false: the grant may be live or dead, and the log must not claim either (BAPert 77013). The closed `code` is what errForLog prints.
+ */
+export class IdpLogoutUnconfirmedError extends Error {
+  readonly code = 'IDP_LOGOUT_UNCONFIRMED';
+  constructor(status: number, readonly grantLive: boolean) {
+    super(`IdP logout answered ${status}`);
+    this.name = 'IdpLogoutUnconfirmedError';
+  }
+}
+
 export async function revokeSessionAtIdp(req: NextRequest): Promise<IdpLogoutOutcome> {
   let resolvedSession: string | undefined;
   const result = await idpFetchJSON(
@@ -33,6 +46,9 @@ export async function revokeSessionAtIdp(req: NextRequest): Promise<IdpLogoutOut
     `${ENV_CONFIG.IDP_URL}/api/Account/logout`,
     {},
     {
+      // A logout 401 with a locally-fresh token must reach a REAL refresh, so the IdP's answer can prove the grant dead (BAPert 77013). Done
+      // in-process, not through the public refresh route, so no request header can force it (NightHawk 77021, BAPert 77022).
+      refreshOnAuthFailure: forceRefreshAtIdp,
       initFor: async (token) => {
         resolvedSession = token;
         let session = await getSession(token);
@@ -50,7 +66,26 @@ export async function revokeSessionAtIdp(req: NextRequest): Promise<IdpLogoutOut
   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}`);
+  const refreshSucceeded = result.attemptedRefresh && typeof result.refreshStatus === 'number' && result.refreshStatus >= 200 && result.refreshStatus < 300;
+  throw new IdpLogoutUnconfirmedError(result.status, refreshSucceeded);
+}
+
+/**
+ * Refresh the session NOW, ignoring "the stored access token looks fresh", by calling `ensureFreshAccessToken` in this process (the one
+ * implementation that talks to the IdP, holds the lock and writes the discard marker). Config is read the way `oauth/resume` reads it
+ * (IDP_URL, CLIENT_ID, the default refresh endpoint). It answers with the status the refresh route would have: 200 on success, 401 for
+ * NO_SESSION / NO_REFRESH_TOKEN, 409 for a lost lock, otherwise E's own status (a discarded IdP 401 is 401 with the marker written).
+ * Missing config or a throw is an UNKNOWN outcome: the caller treats a thrown refresh as `refreshStatus: null`.
+ */
+async function forceRefreshAtIdp(sessionToken: string): Promise<{ ok: boolean; status: number }> {
+  const idpBaseUrl = process.env.IDP_URL;
+  const clientId = process.env.CLIENT_ID;
+  if (!idpBaseUrl || !clientId) throw new Error('IDP_URL and CLIENT_ID are required to prove a grant dead');
+  const { ensureFreshAccessToken } = await import('./ensure-fresh-access-token');
+  const r = await ensureFreshAccessToken(sessionToken, { idpBaseUrl, clientId }, { requireRefreshToken: true, safetyWindowMs: Number.MAX_SAFE_INTEGER });
+  if (r.ok) return { ok: true, status: 200 };
+  const status = r.code === 'NO_SESSION' || r.code === 'NO_REFRESH_TOKEN' ? 401 : r.code === 'CONFLICT' ? 409 : r.status;
+  return { ok: false, status };
 }
 
 /**

package/src/lib/jwt-decode-client.ts

@@ -3,6 +3,8 @@
  * This is a lightweight version for browser usage
  */
 
+import { errForLog } from './log-safe';
+
 // Decode base64url
 function base64urlDecode(base64url: string): string {
   try {
@@ -39,7 +41,7 @@ export function jwtDecode<T = any>(token: string): T | null {
 
     return parsedPayload;
   } catch (e) {
-    console.error('[JWT] Decode failed:', e instanceof Error ? e.message : 'Unknown error');
+    console.error('[JWT] Decode failed:', errForLog(e));
     return null;
   }
 }

package/src/lib/jwt-decode.ts

@@ -1,4 +1,5 @@
 import { jwtDecode as originalJwtDecode } from 'jwt-decode';
+import { errForLog } from './log-safe';
 
 // Define JwtPayload interface since jwt-decode v4 doesn't export it
 export interface JwtPayload {
@@ -65,7 +66,7 @@ export function decodeJwtHeader(token: string): JwtHeader | null {
 
         return JSON.parse(headerJson) as JwtHeader;
     } catch (error) {
-        console.error('[JWT_DECODE] Failed to decode JWT header:', error);
+        console.error('[JWT_DECODE] Failed to decode JWT header:', errForLog(error));
         return null;
     }
 }

package/src/lib/log-safe.ts

@@ -0,0 +1,30 @@
+/**
+ * log-safe: the ONLY way a caught error or an upstream `code` goes into a server log (PII-in-logs census, BAPert 76553 group 1; ported from the
+ * portal's api-error-response.ts, BAPert 76470).
+ *
+ * Server logs persist and are read beyond the person who made the request. An error's `message`, `stack`, `cause` and `details` can carry an
+ * email, a phone number, a code, a token, a SQL fragment or a host: an IdP error's message is the upstream's own free text, and V8's JSON parse
+ * error quotes its input. So a log line gets the error's NAME and a closed STATUS / CODE, nothing else. Every field is matched against a closed
+ * shape; anything that does not match is dropped, not truncated.
+ *
+ * No imports on purpose: this is a leaf, loaded by modules that must not pull in anything else.
+ */
+
+/** An upstream `code` is loggable only if it is a closed token (UPPER_SNAKE). Anything else, including free text, becomes null. */
+export function closedCodeForLog(code: unknown): string | null {
+  return typeof code === 'string' && /^[A-Z0-9_]{1,64}$/.test(code) ? code : null;
+}
+
+/**
+ * Describe a caught error for a log line: `error=<Name> [status=<n>] [code=<CLOSED_CODE>]`.
+ * It NEVER carries `message`, `stack`, `cause` or `details`. A name that is not a short identifier (a hostile or free-text `name`) becomes
+ * `NonError`; a status outside 100-599 is dropped; a code outside the closed token shape is dropped.
+ */
+export function errForLog(err: unknown): string {
+  const e = (err !== null && typeof err === 'object' ? err : {}) as { name?: unknown; status?: unknown; code?: unknown };
+  const name = typeof e.name === 'string' && /^[A-Za-z0-9_]{1,48}$/.test(e.name) ? e.name : 'NonError';
+  const status = typeof e.status === 'number' && Number.isInteger(e.status) && e.status >= 100 && e.status <= 599 ? ` status=${e.status}` : '';
+  const closed = closedCodeForLog(e.code);
+  const code = closed ? ` code=${closed}` : '';
+  return `error=${name}${status}${code}`;
+}

package/src/lib/redis.ts

@@ -1,5 +1,6 @@
 // E:\Repos\PayEz-Next-MVP\packages\next-mvp\src\lib\redis.ts
 import Redis, { RedisOptions } from 'ioredis';
+import { errForLog } from './log-safe';
 
 let client: Redis | null = null;
 
@@ -76,7 +77,7 @@ function createClient(): Redis {
   // unhandled EventEmitter error, which can take the whole PROCESS down -
   // a Redis blip becoming a dead server is worse than the spinner was.
   instance.on('error', (err) => {
-    console.error(`[redis] PATH FAILURE ${new Date().toISOString()}: ${err instanceof Error ? err.message : String(err)}`);
+    console.error(`[redis] PATH FAILURE ${new Date().toISOString()}: ${errForLog(err)}`);
   });
 
   // 185121 line 3: the 16:05 event left no named trigger because ONLY 'error'

package/src/lib/safe-error-response.ts

@@ -15,6 +15,7 @@
  */
 
 import { knownPasswordRules } from './password-rules';
+import { errForLog } from './log-safe';
 
 export interface IdpErrorProjection {
   code?: string;
@@ -25,10 +26,14 @@ export interface IdpErrorProjection {
 
 const str = (v: unknown): string | undefined => (typeof v === 'string' ? v : undefined);
 
-/** Log an exception with a fresh correlationId and return the id for the response body. */
+/**
+ * Log an exception with a fresh correlationId and return the id for the response body.
+ * The log line carries the error's NAME and closed code/status only (errForLog), never its message, stack or cause: those can hold an
+ * email, a phone number, a token or a quoted request body (PII-in-logs, BAPert 76553 group 1). The correlationId still ties the response to the line.
+ */
 export function logExceptionWithCorrelation(tag: string, err: unknown): string {
   const correlationId = globalThis.crypto.randomUUID();
-  console.error(tag, { correlationId, error: err });
+  console.error(tag, { correlationId, error: errForLog(err) });
   return correlationId;
 }
 

package/src/lib/session-store.ts

@@ -15,6 +15,7 @@ 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';
+import { errForLog } from './log-safe';
 
 // Re-export SessionData for consumers
 export type { SessionData } from '../models/SessionModel';
@@ -65,7 +66,7 @@ export async function createSession(data: SessionData): Promise<string> {
       .setex(versionKey, SESSION_TTL, '1')
       .exec();
   } catch (error) {
-    console.error('[SESSION-STORE] Failed to create session:', error);
+    console.error('[SESSION-STORE] Failed to create session:', errForLog(error));
     throw error;
   }
 

package/src/lib/site-logger.ts

@@ -11,6 +11,7 @@
  */
 
 import { getRedis } from './redis';
+import { closedCodeForLog, errForLog } from './log-safe';
 
 // Redis key for site logs (separate from data_logs)
 const REDIS_SITE_LOG_KEY = 'vibe:site-logs:pending';
@@ -74,11 +75,11 @@ export async function logSiteEvent(entry: SiteLogEntry): Promise<void> {
       console.log('[site-logger] Redis push success, queue length:', result);
       redis.expire(REDIS_SITE_LOG_KEY, REDIS_LOG_TTL).catch(() => {});
     }).catch(err => {
-      console.error('[site-logger] Redis push failed:', err.message);
+      console.error('[site-logger] Redis push failed:', errForLog(err));
     });
   } catch (error) {
     // Fail silently - logging should never break the app
-    console.error('[site-logger] Failed to log event:', error);
+    console.error('[site-logger] Failed to log event:', errForLog(error));
   }
 }
 
@@ -120,12 +121,14 @@ export const siteEvents = {
     });
   },
 
-  loginFailed: (opts: { reason: string; email?: string; url?: string; user_agent?: string; ip_address?: string }) => {
+  // BREAKING (PII-in-logs group 3b, BAPert 76553 Q2): no `email` parameter. A failed login is told apart by a CLOSED reason code (UPPER_SNAKE),
+  // never by the address that was tried; anything that is not a closed code is stored as UNSPECIFIED. A caller that still passes `email` fails to compile.
+  loginFailed: (opts: { reason: string; url?: string; user_agent?: string; ip_address?: string }) => {
     logSiteEvent({
       level: 'warn',
       category: 'auth',
       message: 'Login failed',
-      context: { reason: opts.reason, email: opts.email },
+      context: { reason: closedCodeForLog(opts.reason) ?? 'UNSPECIFIED' },
       url: opts.url || '/auth/login',
       user_agent: opts.user_agent,
       ip_address: opts.ip_address,
@@ -214,12 +217,15 @@ export const siteEvents = {
     });
   },
 
-  error: (opts: { message: string; error?: string; stack?: string; user_id?: string | number; url?: string; user_agent?: string; ip_address?: string }) => {
+  // BREAKING (PII-in-logs group 3b, BAPert 76553 Q2): takes a CLOSED code, not caller text, an error string or a stack. The stored message is the fixed
+  // sentence 'Application error'; the code (UPPER_SNAKE, else UNSPECIFIED) goes in context. A caller that still passes `message`, `error` or `stack`
+  // fails to compile.
+  error: (opts: { code: string; user_id?: string | number; url?: string; user_agent?: string; ip_address?: string }) => {
     logSiteEvent({
       level: 'error',
       category: 'error',
-      message: opts.message,
-      context: { error: opts.error, stack: opts.stack },
+      message: 'Application error',
+      context: { code: closedCodeForLog(opts.code) ?? 'UNSPECIFIED' },
       user_id: opts.user_id,
       url: opts.url,
       user_agent: opts.user_agent,