@payez/next-mvp 4.4.4 → 4.4.6

package/src/api-handlers/auth/signout.ts

@@ -21,6 +21,7 @@ import {
   getCallbackUrlCookieName,
   getJwtCookieName
 } from '../../lib/app-slug';
+import { tokenLogId } from '../../lib/token-log-id';
 
 // JWT decode helper - simple base64 decode without verification
 function jwtDecode(token: string): any {
@@ -152,7 +153,7 @@ export function createSignoutHandler() {
       try {
         await deleteSessionEverywhere(redisSessionToken);
         console.info('[SIGNOUT] Redis session cleanup successful', {
-          sessionToken: redisSessionToken.substring(0, 8) + '...'
+          sessionToken: tokenLogId(redisSessionToken)
         });
       } catch (sessionError) {
         // Log error but don't fail the signout process

package/src/api-handlers/auth/status.ts

@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession } from '../../server/auth';
 import { getSession as getRedisSession } from '../../lib/session-store';
+import { logExceptionWithCorrelation } from '../../lib/safe-error-response';
 
 export async function GET(req: NextRequest) {
   try {
@@ -15,6 +16,8 @@ export async function GET(req: NextRequest) {
     }
     return NextResponse.json({ success: true, userId: betterAuthSession?.user?.id || (sessionModel as any).userId || null });
   } catch (err) {
-    return NextResponse.json({ success: false, error: err instanceof Error ? err.message : 'Unknown error' }, { status: 500 });
+    // PAY-1438: this catch wraps both session reads (Better Auth + Redis), before any auth decision.
+    const correlationId = logExceptionWithCorrelation('[AUTH_STATUS] Error reading session:', err);
+    return NextResponse.json({ success: false, error: 'Failed to read session status', code: 'INTERNAL_ERROR', correlationId }, { status: 500 });
   }
 }

package/src/api-handlers/auth/update-session.ts

@@ -1,11 +1,28 @@
 /**
  * Authentication Update Session API Handler
  *
- * Handles session updates, particularly for 2FA status changes.
- * This handler is designed to be imported and used by Next.js applications
- * using the @payez/next-mvp package.
+ * *** THIS HANDLER DOES NOT PERSIST ANYTHING. IT IS AN ECHO. ***
  *
- * @version 2.0
+ * It authenticates the caller, reads `twoFactorSessionVerified` from the REQUEST
+ * BODY, and echoes that caller-asserted value straight back. There is no redis
+ * write, no cookie write, no JWT mint and no session-store call anywhere in this
+ * module - the only `.set(` calls are the security headers below. The 2FA state
+ * does NOT survive the request.
+ *
+ * Do not wire this expecting it to record a second factor. It is kept because
+ * live callers POST to it on the 2FA completion path and a 404/501 would break
+ * that flow; it is deliberately inert, NOT a session writer. Callers can detect
+ * this programmatically via `persisted: false` in the response.
+ *
+ * Card 391621 measured the consequence: because nothing is stored, downstream
+ * 2FA gates read no verified state and FAIL CLOSED. That is why this is an
+ * honesty/diagnosability defect rather than an auth bypass - but a future
+ * consumer that trusts `success: true` here would be trusting nothing.
+ *
+ * If you need to actually record 2FA completion, write to the session store
+ * (see `../../server/session-store`); do not extend this handler in place.
+ *
+ * @version 2.1
  * @requires Authentication (authenticated endpoint)
  */
 
@@ -36,11 +53,22 @@ interface UpdateSessionResponse {
   success: boolean;
   twoFactorSessionVerified: boolean;
   twoFactorMethod?: string;
+  /**
+   * ALWAYS `false`. This handler stores nothing, so the echoed
+   * `twoFactorSessionVerified` above reflects the REQUEST BODY and not any
+   * recorded state. Present so a consumer can detect the no-op without having
+   * to read this file. Additive: no pre-existing field changed meaning.
+   */
+  persisted: false;
 }
 
 /**
  * Creates an update-session handler for Next.js API routes.
  *
+ * *** NO-OP: this handler PERSISTS NOTHING. *** It requires a valid session,
+ * then echoes the caller-asserted `twoFactorSessionVerified` back with
+ * `persisted: false`. See the module header before wiring it.
+ *
  * Better Auth resolves its session from cookies, so this handler takes no
  * configuration. Use the default `POST` export below for typical usage.
  *
@@ -75,22 +103,28 @@ export function createUpdateSessionHandler() {
         ));
       }
 
-      // Update the session with 2FA challenge completion status
-      const updatedSession = {
+      // NOT a session update. This object is local, is never written anywhere,
+      // and is discarded when the request ends. Named for what it is so the
+      // next reader cannot mistake it for persisted state.
+      const echoedRequest = {
         twoFactorSessionVerified: !!twoFactorSessionVerified,
         twoFactorMethod: twoFactorMethod || (session as any).twoFactorMethod
       };
 
-      console.info('[UPDATE-SESSION] Session updated successfully', {
+      // Previously logged "Session updated successfully", which asserted a write
+      // that never happened and made the no-op invisible in production logs.
+      console.warn('[UPDATE-SESSION] NO-OP: nothing persisted; echoing caller-asserted 2FA state', {
         userId: session.user?.id,
-        twoFactorSessionVerified: updatedSession.twoFactorSessionVerified,
-        twoFactorMethod: updatedSession.twoFactorMethod
+        twoFactorSessionVerified: echoedRequest.twoFactorSessionVerified,
+        twoFactorMethod: echoedRequest.twoFactorMethod,
+        persisted: false
       });
 
       const responseData: UpdateSessionResponse = {
         success: true,
-        twoFactorSessionVerified: updatedSession.twoFactorSessionVerified as boolean,
-        twoFactorMethod: updatedSession.twoFactorMethod as string | undefined
+        twoFactorSessionVerified: echoedRequest.twoFactorSessionVerified as boolean,
+        twoFactorMethod: echoedRequest.twoFactorMethod as string | undefined,
+        persisted: false
       };
 
       return addSecurityHeaders(NextResponse.json(responseData));

package/src/api-handlers/auth/validate.ts

@@ -3,6 +3,7 @@ import { idpFetchJSON } from '../../lib/idp-fetch';
 import { ENV_CONFIG, API_ENDPOINTS } from '../../config/env';
 import { getTokenTestAware } from '../../lib/test-aware-get-token';
 import { getSession } from '../../lib/session-store';
+import { logExceptionWithCorrelation, projectIdpError } from '../../lib/safe-error-response';
 
 /**
  * Validates current access token with the IDP and returns normalized info.
@@ -33,12 +34,13 @@ export async function GET(req: NextRequest) {
     const result = await idpFetchJSON(req, url, { method: 'GET', headers: { Authorization: `Bearer ${bearer}` } });
 
     if (!result.ok) {
-      return NextResponse.json({ success: false, error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status }, data: result.json }, { status: result.status });
+      return NextResponse.json({ success: false, error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: projectIdpError(result.json) } }, { status: result.status });
     }
 
     // Passthrough normalized
     return NextResponse.json(result.json ?? { success: true }, { status: 200 });
   } catch (e: any) {
-    return NextResponse.json({ success: false, error: { code: 'INTERNAL_SERVER_ERROR', message: e?.message || 'validate error' } }, { status: 500 });
+    const correlationId = logExceptionWithCorrelation('[AUTH_VALIDATE] Error:', e);
+    return NextResponse.json({ success: false, error: { code: 'INTERNAL_SERVER_ERROR', message: 'validate error', correlationId } }, { status: 500 });
   }
 }

package/src/api-handlers/auth/verify-code.ts

@@ -12,6 +12,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession } from '../../server/auth';
 import { updateTokens, mark2FAComplete } from '../../lib/session-store';
+import { tokenLogId } from '../../lib/token-log-id';
 
 interface VerifyCodeRequest {
   accessToken: string;
@@ -64,7 +65,7 @@ export function createVerifyCodeHandler() {
       }
 
       console.info('[VERIFY-CODE] Updating session with new tokens after 2FA', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         userId: betterAuthSession?.user?.id,
         hasAccessToken: !!accessToken,
         hasRefreshToken: !!refreshToken,
@@ -88,7 +89,7 @@ export function createVerifyCodeHandler() {
       await mark2FAComplete(sessionToken, accessToken);
 
       console.info('[VERIFY-CODE] 2FA completion successful', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         userId: betterAuthSession?.user?.id
       });
 

package/src/api-handlers/mfa/backup-code-verify.ts

@@ -59,6 +59,7 @@ import { ENV_CONFIG } from '../../config/env';
 import { getTokenTestAware } from '../../lib/test-aware-get-token';
 import { transitionTo2FASession } from '../../lib/session-store';
 import { jwtDecode } from '../../lib/jwt-decode';
+import { twoFactorVerifyFailure } from '../../lib/two-factor-verify-failure';
 
 export async function POST(req: NextRequest) {
   try {
@@ -87,15 +88,9 @@ export async function POST(req: NextRequest) {
     );
 
     if (!result.ok) {
-      return NextResponse.json(
-        {
-          success: false,
-          error: result.json?.message || 'Verification failed',
-          code: result.json?.code || 'IDP_ERROR',
-          meta: { attemptedRefresh: result.attemptedRefresh },
-        },
-        { status: result.status }
-      );
+      // PAY-1443: never relay the IDP's error text - it arrives as a C# anonymous-object
+      // ToString ("{ message = ... }") on the deployed IDP. Classify it, answer a fixed sentence.
+      return twoFactorVerifyFailure(result, 'backup_code');
     }
 
     const unwrappedData = result.json?.data || result.json;

package/src/api-handlers/mfa/backup-codes.ts

@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { idpFetchJSON } from '../../lib/idp-fetch';
 import { ENV_CONFIG } from '../../config/env';
+import { projectIdpError } from '../../lib/safe-error-response';
 
 /**
  * Generate MFA backup codes (POST /api/Account/mfa/backup-codes, user JWT).
@@ -25,7 +26,7 @@ export async function POST(req: NextRequest) {
       {
         success: false,
         message: 'Upstream error',
-        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: projectIdpError(result.json) },
         meta: { attemptedRefresh: result.attemptedRefresh },
       },
       { status: result.status },

package/src/api-handlers/mfa/methods.ts

@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { idpFetchJSON } from '../../lib/idp-fetch';
 import { ENV_CONFIG } from '../../config/env';
+import { projectIdpError } from '../../lib/safe-error-response';
 
 /**
  * MFA methods (GET list / DELETE one, /api/Account/mfa/methods[/{id}],
@@ -13,7 +14,7 @@ function upstreamError(result: { status: number; json: unknown; attemptedRefresh
     {
       success: false,
       message: 'Upstream error',
-      error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+      error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: projectIdpError(result.json) },
       meta: { attemptedRefresh: result.attemptedRefresh },
     },
     { status: result.status },

package/src/api-handlers/mfa/totp-confirm.ts

@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { idpFetchJSON } from '../../lib/idp-fetch';
 import { ENV_CONFIG } from '../../config/env';
+import { projectIdpError } from '../../lib/safe-error-response';
 
 /**
  * Confirm TOTP enrolment with the first authenticator code
@@ -26,7 +27,7 @@ export async function POST(req: NextRequest) {
       {
         success: false,
         message: 'Upstream error',
-        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: projectIdpError(result.json) },
         meta: { attemptedRefresh: result.attemptedRefresh },
       },
       { status: result.status },

package/src/api-handlers/mfa/totp-enroll.ts

@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { idpFetchJSON } from '../../lib/idp-fetch';
 import { ENV_CONFIG } from '../../config/env';
+import { projectIdpError } from '../../lib/safe-error-response';
 
 /**
  * Begin TOTP enrolment (POST /api/Account/mfa/totp/enroll, user JWT).
@@ -26,7 +27,7 @@ export async function POST(req: NextRequest) {
       {
         success: false,
         message: 'Upstream error',
-        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: projectIdpError(result.json) },
         meta: { attemptedRefresh: result.attemptedRefresh },
       },
       { status: result.status },

package/src/api-handlers/mfa/totp-verify.ts

@@ -34,6 +34,7 @@ import { ENV_CONFIG } from '../../config/env';
 import { getTokenTestAware } from '../../lib/test-aware-get-token';
 import { transitionTo2FASession } from '../../lib/session-store';
 import { jwtDecode } from '../../lib/jwt-decode';
+import { twoFactorVerifyFailure } from '../../lib/two-factor-verify-failure';
 
 export async function POST(req: NextRequest) {
   try {
@@ -64,15 +65,9 @@ export async function POST(req: NextRequest) {
     );
 
     if (!result.ok) {
-      return NextResponse.json(
-        {
-          success: false,
-          error: result.json?.message || 'Verification failed',
-          code: result.json?.code || 'IDP_ERROR',
-          meta: { attemptedRefresh: result.attemptedRefresh },
-        },
-        { status: result.status }
-      );
+      // PAY-1443: never relay the IDP's error text - it arrives as a C# anonymous-object
+      // ToString ("{ message = ... }") on the deployed IDP. Classify it, answer a fixed sentence.
+      return twoFactorVerifyFailure(result, 'totp');
     }
 
     // Unwrap IDP envelope { success, data }

package/src/api-handlers/passkeys/list.ts

@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { idpFetchJSON } from '../../lib/idp-fetch';
 import { ENV_CONFIG } from '../../config/env';
+import { projectIdpError } from '../../lib/safe-error-response';
 
 /**
  * List the signed-in user's passkeys (GET /api/Passkeys, user JWT).
@@ -15,7 +16,7 @@ export async function GET(req: NextRequest) {
       {
         success: false,
         message: 'Upstream error',
-        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: projectIdpError(result.json) },
         meta: { attemptedRefresh: result.attemptedRefresh },
       },
       { status: result.status },

package/src/api-handlers/passkeys/manage.ts

@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { idpFetchJSON } from '../../lib/idp-fetch';
 import { ENV_CONFIG } from '../../config/env';
+import { projectIdpError } from '../../lib/safe-error-response';
 
 /**
  * Manage ONE passkey (PATCH rename / DELETE revoke, /api/Passkeys/{id},
@@ -13,7 +14,7 @@ function upstreamError(result: { status: number; json: unknown; attemptedRefresh
     {
       success: false,
       message: 'Upstream error',
-      error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+      error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: projectIdpError(result.json) },
       meta: { attemptedRefresh: result.attemptedRefresh },
     },
     { status: result.status },

package/src/api-handlers/passkeys/register-options.ts

@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { idpFetchJSON } from '../../lib/idp-fetch';
 import { ENV_CONFIG } from '../../config/env';
+import { projectIdpError } from '../../lib/safe-error-response';
 
 /**
  * Begin the passkey REGISTRATION ceremony (POST /api/Passkeys/register/options,
@@ -26,7 +27,7 @@ export async function POST(req: NextRequest) {
       {
         success: false,
         message: 'Upstream error',
-        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: projectIdpError(result.json) },
         meta: { attemptedRefresh: result.attemptedRefresh },
       },
       { status: result.status },

package/src/api-handlers/passkeys/register-verify.ts

@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { idpFetchJSON } from '../../lib/idp-fetch';
 import { ENV_CONFIG } from '../../config/env';
+import { projectIdpError } from '../../lib/safe-error-response';
 
 /**
  * Finish the passkey REGISTRATION ceremony (POST /api/Passkeys/register/verify,
@@ -25,7 +26,7 @@ export async function POST(req: NextRequest) {
       {
         success: false,
         message: 'Upstream error',
-        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: projectIdpError(result.json) },
         meta: { attemptedRefresh: result.attemptedRefresh },
       },
       { status: result.status },

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

@@ -3,6 +3,7 @@ import { getSession, isRefreshInProgress } from '../../lib/session-store';
 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';
 
 export async function GET(req: NextRequest) {
   try {
@@ -14,23 +15,25 @@ export async function GET(req: NextRequest) {
       finalSessionToken = (token?.sessionToken || token?.redisSessionId) as string;
     }
     if (!finalSessionToken) {
-      return NextResponse.json({ canRefresh: false, reason: 'not_logged_in', sessionToken: null }, { status: 200 });
+      return NextResponse.json({ canRefresh: false, reason: 'not_logged_in', sessionTokenId: null }, { status: 200 });
     }
     const refreshInProgress = await isRefreshInProgress(finalSessionToken);
     if (refreshInProgress) {
       // Still need to get session data for twoFactorComplete even when refresh is in progress
       const sessionData = await getSession(finalSessionToken);
-      logger.info('[REFRESH-VIABILITY] Refresh already in progress, telling middleware to wait', { sessionToken: finalSessionToken.substring(0, 8) + '...' });
-      return NextResponse.json({ canRefresh: true, reason: 'refresh_in_progress', refreshInProgress: true, sessionToken: finalSessionToken, twoFactorComplete: sessionData?.mfaVerified ?? false }, { status: 200 });
+      logger.info('[REFRESH-VIABILITY] Refresh already in progress, telling middleware to wait', { sessionToken: tokenLogId(finalSessionToken) });
+      return NextResponse.json({ canRefresh: true, reason: 'refresh_in_progress', refreshInProgress: true, sessionTokenId: tokenLogId(finalSessionToken), twoFactorComplete: sessionData?.mfaVerified ?? false }, { status: 200 });
     }
     const sessionData = await getSession(finalSessionToken);
     if (!sessionData) {
-      return NextResponse.json({ canRefresh: false, reason: 'session_not_found', sessionToken: finalSessionToken }, { status: 200 });
+      return NextResponse.json({ canRefresh: false, reason: 'session_not_found', sessionTokenId: tokenLogId(finalSessionToken) }, { status: 200 });
     }
     const viabilityCheck = checkRefreshViability(sessionData);
-    return NextResponse.json({ canRefresh: viabilityCheck.canRefresh, reason: viabilityCheck.reason, timeRemaining: viabilityCheck.timeRemaining, expiresAt: viabilityCheck.expiresAt, accessTokenExpired: viabilityCheck.accessTokenExpired, accessTokenTimeRemaining: viabilityCheck.accessTokenTimeRemaining, sessionToken: finalSessionToken, twoFactorComplete: sessionData.mfaVerified ?? false, userId: sessionData.userId, refreshInProgress: false });
+    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) {
-    logger.error('[REFRESH-VIABILITY] Error checking refresh viability', { error: error instanceof Error ? error.message : String(error) });
-    return NextResponse.json({ canRefresh: false, reason: 'check_error', error: error instanceof Error ? error.message : String(error) }, { status: 500 });
+    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.
+    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

@@ -9,6 +9,7 @@ import { getSession as getRedisSession, getBetterAuthSession } from '../../lib/s
 import { getSession } from '../../server/auth';
 import { isInitializationFailed, ensureInitialized } from '../../lib/startup-init';
 import { getIDPClientConfig } from '../../lib/idp-client-config';
+import { tokenLogId } from '../../lib/token-log-id';
 
 export async function GET(req: NextRequest) {
   try {
@@ -123,7 +124,7 @@ export async function GET(req: NextRequest) {
         const effectiveTwoFactorComplete = sessionMfaComplete && !mfaExpired;
 
         console.log('[VIABILITY] Session 2FA check:', {
-          sessionToken: sessionToken.substring(0, 8) + '...',
+          sessionToken: tokenLogId(sessionToken),
           mfaVerified: sessionData.mfaVerified,
           twoFactorComplete: (sessionData as any).twoFactorComplete,
           sessionMfaComplete,
@@ -141,7 +142,7 @@ export async function GET(req: NextRequest) {
 
         const response = {
           authenticated: true,
-          sessionToken, // Include token for middleware tracking
+          sessionTokenId: tokenLogId(sessionToken), // PAY-1481: correlation id for middleware tracking, never the token
           // 2FA fields - critical for middleware redirect logic
           requires2FA, // From cached client config (client-wide setting)
           twoFactorComplete: effectiveTwoFactorComplete, // From session, BUT respects MFA TTL
@@ -176,7 +177,7 @@ export async function GET(req: NextRequest) {
       console.warn('[VIABILITY] Stale cookie detected - session not in Redis');
       return NextResponse.json({
         authenticated: false,
-        sessionToken // Include token to enable stale cookie detection
+        sessionTokenId: sessionToken ? tokenLogId(sessionToken) : null // PAY-1481: presence + correlation for stale cookie detection
       });
     }
 

package/src/api-handlers/test/force-expire.ts

@@ -1,6 +1,8 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession as getBetterAuthSession } from '../../server/auth';
 import { getSession, updateSession } from '../../lib/session-store';
+import { logExceptionWithCorrelation } from '../../lib/safe-error-response';
+import { tokenLogId } from '../../lib/token-log-id';
 
 /**
  * ⚠️ DESTRUCTIVE TEST-ONLY HANDLER — DO NOT MOUNT IN PRODUCTION. ⚠️
@@ -146,7 +148,7 @@ export const POST = async (req: NextRequest) => {
     await updateSession(sessionToken, { idpAccessTokenExpires: forced });
 
     console.log('[TEST_EXPIRE] Forced access token expiry for session', {
-      sessionToken: sessionToken.substring(0, 8) + '...',
+      sessionToken: tokenLogId(sessionToken),
       previous: prev ? new Date(prev).toISOString() : null,
       newExpiry: new Date(forced).toISOString()
     });
@@ -159,7 +161,7 @@ export const POST = async (req: NextRequest) => {
       newExpiryIso: new Date(forced).toISOString()
     });
   } catch (e) {
-    console.error('[TEST_EXPIRE] Error:', e);
-    return NextResponse.json({ success: false, error: e instanceof Error ? e.message : String(e) }, { status: 500 });
+    const correlationId = logExceptionWithCorrelation('[TEST_EXPIRE] Error:', e);
+    return NextResponse.json({ success: false, error: 'Failed to force expiry', code: 'INTERNAL_ERROR', correlationId }, { status: 500 });
   }
 };

package/src/auth/auth-decision.ts

@@ -6,6 +6,7 @@
  */
 
 import { safeCallbackPath } from './safe-callback';
+import { tokenLogId } from '../lib/token-log-id';
 
 // Input types for the decision engine
 export interface AuthContext {
@@ -140,7 +141,7 @@ export function makeAuthDecision(context: AuthContext): AuthAction {
       pathname,
       isLoginPage,
       sessionExists: sessionStatus.exists,
-      sessionToken: sessionPointer.sessionToken?.substring(0, 8) + '...'
+      sessionToken: tokenLogId(sessionPointer.sessionToken)
     });
     
     // Already on the 2FA page

package/src/auth/better-auth.ts

@@ -21,9 +21,11 @@ import { resolveClientKey } from '../lib/client-key';
 import { genericOAuth } from 'better-auth/plugins/generic-oauth';
 import type { IDPClientConfig } from '../lib/idp-client-config';
 import { getIDPClientConfig } from '../lib/idp-client-config';
-import { getAppSlug } from '../lib/app-slug';
+import { getAppSlug, assertAppSlugMatchesIdp } from '../lib/app-slug';
 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';
 
 /**
  * 185121: short sha256 fingerprint for secrets/tokens in log lines — enough
@@ -518,6 +520,7 @@ export function createBetterAuthInstance(
   idpConfig: IDPClientConfig,
   opts: CreateBetterAuthInstanceOptions = {}
 ) {
+  assertAppSlugMatchesIdp(idpConfig.clientSlug);
   const appSlug = idpConfig.clientSlug || getAppSlug();
 
   // 185121 line 1: name the secret this instance PINNED, as a hash, never the
@@ -867,6 +870,9 @@ interface BetterAuthModuleState {
   cachedInstance: any;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   initPromise: Promise<any> | null;
+  // PAY-642: the init attempt, single-flighted so a REJECTED attempt clears itself (see getBetterAuthInstance).
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  initFlight?: SingleFlight<any>;
   configuredOpts: CreateBetterAuthInstanceOptions;
 }
 
@@ -902,19 +908,36 @@ export function configureBetterAuth(opts: CreateBetterAuthInstanceOptions): void
   state.configuredOpts = opts;
 }
 
+/**
+ * PAY-642 (card 338215): the init attempt no longer LATCHES A FAILURE.
+ *
+ * This used to be `state.initPromise ??= getIDPClientConfig(true).then(...)` with no .catch and no reset. One
+ * auth request against a cold process while the IdP was unreachable stored a rejected promise, and every later
+ * caller replayed it until the process restarted, even after the IdP recovered. This funnel backs every
+ * /api/auth/* route, the login GET handler and withAuth. server/auth.ts getAuthInstance() already used
+ * createSingleFlight for this exact bug; this sibling funnel was missed.
+ *
+ * Now the attempt runs through the same helper: concurrent callers share one attempt, a failure still rejects
+ * for every caller of THAT attempt (loud), the next call starts a fresh attempt, and a success is cached in
+ * state.cachedInstance as before. The flight lives on the globalThis state for the same reason the instance
+ * does (duplicated route chunks must share one init).
+ */
 export async function getBetterAuthInstance() {
   if (state.cachedInstance) return state.cachedInstance;
 
-  if (!state.initPromise) {
-    state.initPromise = getIDPClientConfig(true).then(config => {
+  state.initFlight ??= createSingleFlight(() =>
+    getIDPClientConfig(true).then(config => {
       const instance = createBetterAuthInstance(config, state.configuredOpts);
       state.cachedInstance = instance;
       console.log('[BETTER_AUTH] Instance created for', config.clientSlug || config.clientId);
       return instance;
-    });
-  }
+    })
+  );
 
-  return state.initPromise;
+  const attempt = state.initFlight.get();
+  // Kept for callers that inspect it; it always points at the CURRENT attempt, never a settled failure.
+  state.initPromise = attempt;
+  return attempt;
 }
 
 /**
@@ -961,7 +984,7 @@ export async function exchangeOAuthForIdpTokens(
     // Read the BA session from Redis
     const baRaw = await getRedis().get(baKey).catch(() => null);
     if (!baRaw) {
-      console.warn('[BETTER_AUTH] exchangeOAuthForIdpTokens: session not found in Redis for token', sessionToken.substring(0, 10));
+      console.warn('[BETTER_AUTH] exchangeOAuthForIdpTokens: session not found in Redis for token', tokenLogId(sessionToken));
       return false;
     }
 
@@ -1038,7 +1061,9 @@ export async function exchangeOAuthForIdpTokens(
     });
 
     const oauthResText = await oauthRes.text();
-    console.log('[BETTER_AUTH] IDP oauth-callback response:', oauthRes.status, oauthResText.substring(0, 500));
+    // PAY-1427 (QAPert, PR 154 thread 326): this printed the first 500 chars of the oauth-callback TOKEN
+    // envelope on EVERY successful OAuth login (it runs before the !ok check). Status + length only.
+    console.log('[BETTER_AUTH] IDP oauth-callback response:', { status: oauthRes.status, bodyLength: oauthResText.length });
 
     if (!oauthRes.ok) {
       console.error('[BETTER_AUTH] IDP oauth-callback failed:', oauthRes.status);
@@ -1276,7 +1301,7 @@ export async function storeIdpTokensInSession(
       // conjured here would carry no Better Auth cookie, so it would be
       // unreachable by the browser and invisible to every other consumer —
       // failing as "silently signed out" rather than as an error.
-      console.warn('[BETTER_AUTH] storeIdpTokensInSession: no BA session for token', sessionToken.substring(0, 10));
+      console.warn('[BETTER_AUTH] storeIdpTokensInSession: no BA session for token', tokenLogId(sessionToken));
       return false;
     }
 
@@ -1399,7 +1424,7 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
 
           const session = await auth.api.getSession({ headers });
           if (session?.session?.token) {
-            console.log('[BETTER_AUTH] Got session token from callback:', session.session.token.substring(0, 10), '| email:', session.user?.email);
+            console.log('[BETTER_AUTH] Got session token from callback:', tokenLogId(session.session.token), '| email:', session.user?.email);
             await exchangeOAuthForIdpTokens(session.session.token);
           } else {
             console.warn('[BETTER_AUTH] Could not get session after OAuth callback');

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

@@ -215,7 +215,8 @@ export async function idpRefreshToken(
 
     if (!response.ok) {
       const errorText = await response.text().catch(() => 'Unknown error');
-      console.error('[IDP_CLIENT] Token refresh failed:', response.status, errorText);
+      // PAY-1427: never the raw upstream body (the refresh.ts:528 twin PR 139 fixed). Status + length only.
+      console.error('[IDP_CLIENT] Token refresh failed:', { status: response.status, bodyLength: errorText.length });
       return {
         success: false,
         error: {

package/src/components/admin/DataBrowserTab.tsx

@@ -214,7 +214,10 @@ export function DataBrowserTab({
 
       if (!response.ok) {
         const errData = await response.json().catch(() => ({}));
-        throw new Error(errData.error?.message || 'Delete failed');
+        // PAY-1425: the handler returns a fixed message plus a correlationId (never upstream
+        // text). Surface the id so an admin can quote it to an operator.
+        const ref = errData.error?.correlationId ? ` (ref ${errData.error.correlationId})` : '';
+        throw new Error(`${errData.error?.message || 'Delete failed'}${ref}`);
       }
 
       setSuccess(`Record ${id} deleted`);