@payez/next-mvp 4.4.5 → 4.4.6

package/src/pages/test-env/redact-credentials.ts

@@ -0,0 +1,96 @@
+/**
+ * redact-credentials - what the test-env debug pages may show of a credential: a stable hash and a length, never
+ * characters of the value (PAY-1470, BAPert rulings 59022 and 59040).
+ *
+ * PAY-1481 item 2 (QAPert, PR 186 review 59083): this was a DENYLIST (keys ending in token/secret/password/...).
+ * Opaque credentials under `tokens.access`, `redisSessionId`, `sid`, `authorization`, `cookie`, `backupCodes[]` and
+ * `code` passed unmasked. It is now an ALLOWLIST: a string is shown only when its key is a known DISPLAYABLE field
+ * (identity, roles, timestamps, provider and flag metadata, standard JWT claims). Every other string - an unknown
+ * key, an array item under an unknown key, a top-level string - becomes maskToken. A new field is hidden until
+ * someone decides it is displayable, which is the safe direction for a page reachable in production builds.
+ *
+ * Kept from the denylist era, and applied EVEN under a displayable key, because a credential can sit under an
+ * innocent name: a JWT (three base64url segments, length floors so "4.1.42" is not one), a PEM armour band, and the
+ * password in scheme://user:password@host. Numbers, booleans and null are never credentials and stay readable.
+ *
+ * There is no Reveal and no copy. "Never renders token material" includes click-to-reveal (59040).
+ */
+import { tokenLogId } from '../../lib/token-log-id';
+
+/** A stable, non-reversible stand-in for a credential: `h:<12 hex>  (<n> chars, hidden)`. */
+export function maskToken(value: string): string {
+  return `${tokenLogId(value)}  (${value.length} chars, hidden)`;
+}
+
+/**
+ * Keys whose string values are displayable. Exact names (case-insensitive), plus timestamp / flag suffix patterns.
+ * An exact listed key wins (tokenType is metadata); otherwise a key naming a credential (CREDENTIAL_NAME) is refused.
+ */
+const DISPLAYABLE_KEYS = new Set(
+  [
+    // identity
+    'id', 'userId', 'user_id', 'sub', 'email', 'name', 'given_name', 'family_name', 'preferred_username', 'image',
+    'picture', 'locale', 'phone_number_verified',
+    // authorisation metadata
+    'role', 'roles', 'scope', 'scopes', 'permissions', 'authenticationMethods', 'authenticationLevel', 'amr', 'acr',
+    'oauthProvider', 'provider', 'providerId', 'tokenType', 'token_type', 'type', 'typ', 'alg', 'kid', 'iss', 'aud',
+    'azp', 'jti',
+    // client / tenant
+    'clientId', 'client_id', 'idpClientId', 'clientSlug', 'slug', 'tenant', 'tenantId', 'merchantId', 'appSlug',
+    // result / status fields of the test-env routes
+    'status', 'statusText', 'success', 'action', 'message', 'error', 'reason', 'outcome', 'source', 'shape', 'mode',
+  ].map((k) => k.toLowerCase()),
+);
+/** Timestamps, durations and booleans-as-strings by suffix: expires, accessTokenExpires, mfaCompletedAt, iat... */
+const DISPLAYABLE_SUFFIX = /(expires|_at|iat|exp|nbf|hours|seconds|verified|required|enabled|count|version)$/i;
+/** camelCase timestamps (createdAt, mfaCompletedAt): tested on the ORIGINAL key so `format` / `chat` do not match. */
+const CAMEL_AT = /[a-z0-9]At$/;
+/** A key that names a credential is never displayable, whatever suffix it has (e.g. refreshTokenCreatedAt stays OK
+ *  because it names a TIME; `authorization`, `cookie`, `sid`, `code` are credentials). */
+const CREDENTIAL_NAME = /(token|secret|password|passwd|apikey|api_key|credential|authorization|cookie|^sid$|session_?id$|^code$|codes?$|otp|pin$|signature|private)/i;
+
+const URL_WITH_USERINFO = /^([a-z][a-z0-9+.-]*:\/\/)([^/\s:@]+):([^/\s@]+)@/i;
+const PEM_BLOCK = /-----BEGIN [A-Z0-9][A-Z0-9 ]*-----/;
+
+function looksLikeJwt(v: string): boolean {
+  if (v.length < 40) return false;
+  const parts = v.split('.');
+  return parts.length === 3 && parts.every((p) => p.length >= 8 && /^[A-Za-z0-9_-]+$/.test(p));
+}
+
+/** Is a string under this key displayable? Credential names lose even when a timestamp suffix matches. */
+export function isDisplayableKey(keyName: string): boolean {
+  if (!keyName) return false;
+  const k = keyName.toLowerCase();
+  // 1. An exact, deliberately listed field (tokenType is metadata even though it says "token").
+  if (DISPLAYABLE_KEYS.has(k)) return true;
+  // 2. A key naming a credential is refused - unless what it names is a TIME about it (accessTokenExpires).
+  const namesTime = /(expires|_at|iat|exp|nbf|hours|seconds)$/i.test(k) || CAMEL_AT.test(keyName);
+  if (CREDENTIAL_NAME.test(k) && !namesTime) return false;
+  // 3. Metadata by suffix: timestamps, durations, flags, counts, versions, URLs (userinfo is still masked).
+  return DISPLAYABLE_SUFFIX.test(k) || CAMEL_AT.test(keyName) || /url$/i.test(k);
+}
+
+/** A deep copy of `value` in which every string not under a displayable key is replaced by maskToken. */
+export function redactCredentials(value: unknown, keyName = ''): unknown {
+  // Array items inherit the array's key: backupCodes[] items are credentials, roles[] items are not.
+  if (Array.isArray(value)) return value.map((v) => redactCredentials(v, keyName));
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>).map(([k, v]) => [k, redactCredentials(v, k)]),
+    );
+  }
+  // NightHawk (PR 204 review): a numeric OTP / code under a credential-named key is a credential too.
+  if (typeof value === 'number' && keyName && !isDisplayableKey(keyName) && CREDENTIAL_NAME.test(keyName)) {
+    return maskToken(String(value));
+  }
+  if (typeof value !== 'string' || value.length === 0) return value;
+  if (looksLikeJwt(value)) return maskToken(value);
+  if (PEM_BLOCK.test(value)) return '••• PEM block redacted (' + value.length + ' chars) •••';
+  if (!isDisplayableKey(keyName)) return maskToken(value);
+  let shown = value;
+  if (URL_WITH_USERINFO.test(shown)) shown = shown.replace(URL_WITH_USERINFO, '$1$2:•••••@');
+  // NightHawk (PR 204 review): a URL's query and fragment carry tokens (?token=, #access_token=). Names stay, values go.
+  shown = shown.replace(/([?&#][^=&#\s]+=)[^&#\s]*/g, '$1•••');
+  return shown;
+}

package/src/pages/verify-code/page.tsx

@@ -458,7 +458,8 @@ function VerifyCodeForm({ enrollHref }: { enrollHref: string }) {
           if (!updateRes.ok) {
             console.warn('[2FA] update-session returned non-OK status:', updateRes.status);
             const errorData = await updateRes.json();
-            console.warn('[2FA] update-session error:', errorData);
+            // PAY-1427: the request carried access_token/refresh_token; log the error envelope's shape, never its contents.
+            console.warn('[2FA] update-session error:', { keys: errorData && typeof errorData === 'object' ? Object.keys(errorData) : typeof errorData, code: errorData?.error?.code ?? errorData?.code });
           } else {
             console.log('[2FA] Session updated successfully with MFA tokens');
           }

package/src/routes/auth/logout.ts

@@ -25,6 +25,7 @@ import {
   getCallbackUrlCookieName,
 } from '../../lib/app-slug';
 import { siteEvents, getClientIp } from '../../lib/site-logger';
+import { logExceptionWithCorrelation } from '../../lib/safe-error-response';
 
 /**
  * POST /api/auth/logout - Sign out and clean up session
@@ -101,10 +102,11 @@ export async function POST(req: NextRequest) {
 
     return response;
   } catch (error) {
-    console.error('[LOGOUT_ROUTE] Error during logout:', error);
+    const correlationId = logExceptionWithCorrelation('[LOGOUT_ROUTE] Error during logout:', error);
     return NextResponse.json({
       error: 'Failed to logout',
-      details: error instanceof Error ? error.message : 'Unknown error'
+      code: 'INTERNAL_ERROR',
+      correlationId,
     }, { status: 500 });
   }
 }

package/src/routes/auth/session.ts

@@ -16,6 +16,8 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession as getBetterAuthSession } from '../../server/auth';
 import { getSession as getRedisSession, updateSession } from '../../lib/session-store';
+import { logExceptionWithCorrelation } from '../../lib/safe-error-response';
+import { tokenLogId } from '../../lib/token-log-id';
 
 /**
  * GET /api/auth/session - Check current session status
@@ -42,7 +44,7 @@ export async function GET(req: NextRequest) {
       userId: authSession.user?.id,
       email: authSession.user?.email,
       name: authSession.user?.name,
-      redisSessionId: redisSessionId ? redisSessionId.substring(0, 8) + '...' : 'MISSING',
+      redisSessionId: redisSessionId ? tokenLogId(redisSessionId) : 'MISSING',
     });
 
     // Fetch full session data from Redis
@@ -70,7 +72,7 @@ export async function GET(req: NextRequest) {
     if (!session) {
       console.error('[SESSION_ROUTE] Redis session MISS — refusing to report authenticated', {
         userId: authSession.user?.id,
-        redisSessionId: redisSessionId ? redisSessionId.substring(0, 8) + '...' : 'MISSING',
+        redisSessionId: redisSessionId ? tokenLogId(redisSessionId) : 'MISSING',
         reason: redisSessionId ? 'session expired or evicted' : 'no session token on auth session',
       });
       return NextResponse.json({});
@@ -98,20 +100,23 @@ export async function GET(req: NextRequest) {
         idpClientId: session?.idpClientId,
         merchantId: session?.merchantId,
       },
-      // Session tokens
-      sessionToken: redisSessionId,
-      accessToken: session?.idpAccessToken,
-      refreshToken: session?.idpRefreshToken,
+      // PAY-1481 item 1: NO token material. This body is read by browser JS, so returning the session token and the
+      // IdP access/refresh tokens handed them to any script on the page (the refresh token outlives the session).
+      // Server routes read tokens from the session store; the UI only needs presence and expiry.
+      hasAccessToken: !!session?.idpAccessToken,
+      hasRefreshToken: !!session?.idpRefreshToken,
       accessTokenExpires: session?.idpAccessTokenExpires,
       expires: authSession.session?.expiresAt
         ? new Date(authSession.session.expiresAt).toISOString()
         : new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
     });
   } catch (error) {
-    console.error('[SESSION_ROUTE] Error checking session:', error);
+    // PAY-1438: pre-auth route - the exception text stays in the log, keyed by correlationId.
+    const correlationId = logExceptionWithCorrelation('[SESSION_ROUTE] Error checking session:', error);
     return NextResponse.json({
       error: 'Failed to check session',
-      details: error instanceof Error ? error.message : 'Unknown error'
+      code: 'INTERNAL_ERROR',
+      correlationId,
     }, { status: 500 });
   }
 }
@@ -247,10 +252,11 @@ export async function POST(req: NextRequest) {
       message: 'Session updated successfully'
     });
   } catch (error) {
-    console.error('[SESSION_ROUTE] Error updating session:', error);
+    const correlationId = logExceptionWithCorrelation('[SESSION_ROUTE] Error updating session:', error);
     return NextResponse.json({
       error: 'Failed to update session',
-      details: error instanceof Error ? error.message : 'Unknown error'
+      code: 'INTERNAL_ERROR',
+      correlationId,
     }, { status: 500 });
   }
 }

package/src/routes/auth/viability.ts

@@ -21,6 +21,8 @@ import {
   getBetterAuthSession as getBetterAuthRedisSession,
 } from '../../lib/session-store';
 import { getIDPClientConfig } from '../../lib/idp-client-config';
+import { logExceptionWithCorrelation } from '../../lib/safe-error-response';
+import { tokenLogId } from '../../lib/token-log-id';
 
 /**
  * Get tenant-wide 2FA requirement from cached client config (from broker handshake)
@@ -175,7 +177,7 @@ export async function GET(req: NextRequest) {
         viable: false,
         needsRefresh: false,
         authenticated: false,
-        sessionToken, // Return sessionToken so middleware can detect and clear stale cookie
+        sessionTokenId: tokenLogId(sessionToken), // PAY-1481: a correlation id, never the token; middleware only needs presence to clear the stale cookie
         reason: 'Stale session - cookie exists but session not found in Redis'
       });
     }
@@ -309,7 +311,7 @@ export async function GET(req: NextRequest) {
         viable: true,
         needsRefresh: true,
         authenticated: true,
-        sessionToken,
+        sessionTokenId: sessionToken ? tokenLogId(sessionToken) : null,
         // Clear names for middleware decision-making
         tenantRequiresTwoFactor,
         userHasCompletedTenantTwoFactorRequirements,
@@ -351,7 +353,7 @@ export async function GET(req: NextRequest) {
 
     // DEBUG: Log what we're reading from the session
     console.log('[VIABILITY] Session 2FA state:', {
-      sessionToken: sessionToken?.substring(0, 8) + '...',
+      sessionToken: tokenLogId(sessionToken),
       'session.mfaVerified': session?.mfaVerified,
       'session.twoFactorComplete': (session as any)?.twoFactorComplete,
       mfaVerifiedInSession,
@@ -379,7 +381,7 @@ export async function GET(req: NextRequest) {
         expiresIn: 0,
         hasRefreshToken,
         authenticated: true,
-        sessionToken,
+        sessionTokenId: sessionToken ? tokenLogId(sessionToken) : null,
         // Clear names
         tenantRequiresTwoFactor,
         userHasCompletedTenantTwoFactorRequirements,
@@ -403,7 +405,7 @@ export async function GET(req: NextRequest) {
       expiresIn,
       hasRefreshToken,
       authenticated: true,
-      sessionToken,
+      sessionTokenId: sessionToken ? tokenLogId(sessionToken) : null,
       // Clear names
       tenantRequiresTwoFactor,
       userHasCompletedTenantTwoFactorRequirements,
@@ -420,13 +422,15 @@ export async function GET(req: NextRequest) {
       clientId: resolveClientId(session?.idpClientId),
     });
   } catch (error) {
-    console.error('[VIABILITY_ROUTE] Error checking session viability:', error);
+    // PAY-1438: pre-auth probe - the exception text stays in the log, keyed by correlationId.
+    const correlationId = logExceptionWithCorrelation('[VIABILITY_ROUTE] Error checking session viability:', error);
     return NextResponse.json({
       viable: false,
       needsRefresh: false,
       authenticated: false,
       error: 'Failed to check session',
-      details: error instanceof Error ? error.message : 'Unknown error'
+      code: 'INTERNAL_ERROR',
+      correlationId
     }, { status: 500 });
   }
 }

package/src/server/auth.ts

@@ -13,7 +13,7 @@ import {
   getBetterAuthSession as getBetterAuthRedisSession,
   type SessionData,
 } from '../lib/session-store';
-import { extractSessionTokenFromCookie } from '../lib/session-cookie-shape';
+import { resolveVerifiedSessionTokenFromRequest } from './verified-session-token';
 import { createSingleFlight } from '../lib/single-flight';
 
 let authInstance: ReturnType<typeof createBetterAuthInstance> | null = null;
@@ -172,14 +172,18 @@ export async function getSession(request?: Request): Promise<any> {
     return attachSessionData(betterAuthSession, sessionData, sessionToken);
   }
 
-  // Path B — Better Auth said null/incomplete. Fall back to manual cookie
+  // Path B — Better Auth said null/incomplete. Fall back to a VERIFIED cookie
   // decode + Redis-canonical liveness check. This catches cases where the
   // canonical app session at `{slug}:{token}` is still alive but Better
   // Auth's `ba:{slug}:{token}` secondary record was evicted or the
-  // in-memory cookie cache returned stale-null. No JWT signature check —
-  // Redis lookup is the validation: an attacker forging a session-token
-  // claim hits NO_SESSION because Redis has no matching entry.
-  const sessionToken = extractSessionTokenFromCookie(request);
+  // in-memory cookie cache returned stale-null.
+  //
+  // PAY-1476: this path used to take the token with NO signature check, on the
+  // theory that "Redis lookup is the validation". It is not: a leaked token has
+  // a live record, so the token string alone authenticated, with any garbage in
+  // the signature position, and a forged JWS too. The token now comes only from
+  // the shared verified resolver (HMAC or JWS signature checked first).
+  const sessionToken = await resolveVerifiedSessionTokenFromRequest(request);
   if (!sessionToken) return null;
 
   let sessionData: SessionData | null = null;

package/src/server/decode-session.ts

@@ -7,12 +7,14 @@
 
 import 'server-only';
 import { cookies } from 'next/headers';
-import { jwtVerify, type JWTPayload } from 'jose';
+import { type JWTPayload } from 'jose';
 import { getSession, type SessionData } from '../lib/session-store';
 import { getIDPClientConfig } from '../lib/idp-client-config';
 import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
 import { ensureInitialized } from '../lib/startup-init';
 import { extractSessionTokenFromCookieValue } from '../lib/session-cookie-shape';
+import { resolveVerifiedSessionCookie } from './verified-session-token';
+import { tokenLogId } from '../lib/token-log-id';
 
 export interface DecodedSession {
   sessionData: SessionData;
@@ -137,7 +139,7 @@ async function tryBetterAuthSession(
     if (!idpTokens?.roles?.length) {
       console.warn(
         '[DECODE-SESSION] Leg 1 declining: idpTokens unusable (no roles) for session',
-        result.session.token.substring(0, 10),
+        tokenLogId(result.session.token),
         '— falling through to the sess: leg'
       );
       return null;
@@ -252,32 +254,20 @@ export async function decodeSession(
     // death, because the ONLY fallback was structurally blind to the only
     // shape it would ever be handed.
     //
-    // Check the shape FIRST. A BA-hmac cookie skips jose entirely and goes
-    // straight to the Redis-canonical liveness check below — same posture
-    // as the JWS path always had (no signature re-check here either; Redis
-    // presence is the authority). A JWS-shaped cookie (legacy NextAuth-era,
-    // if any still linger) keeps the original jwtVerify path unchanged.
+    // PAY-1476: the shape still decides HOW to verify, but BOTH shapes are now
+    // verified, by the shared resolver. This branch used to take a BA-hmac
+    // cookie's token with no signature check ("Redis presence is the
+    // authority"), so `{leaked token}.{anything}` authenticated here - including
+    // behind the portal's admin API gate. The resolver checks the HMAC with
+    // timingSafeEqual (ba-hmac) or runs jwtVerify (jws) against the same
+    // env-first auth secret, and returns null on any failure.
     const shaped = extractSessionTokenFromCookieValue(cookieValue);
-
-    let sessionToken: string | undefined;
-    let payload: JWTPayload | undefined;
-
-    if (shaped?.shape === 'ba-hmac') {
-      sessionToken = shaped.token;
-    } else {
-      const secretKey = new TextEncoder().encode(secret);
-      try {
-        const result = await jwtVerify(cookieValue, secretKey);
-        payload = result.payload;
-      } catch (jwtError) {
-        console.warn('[DECODE-SESSION] JWT verification failed:', jwtError instanceof Error ? jwtError.message : String(jwtError));
-        return null;
-      }
-      sessionToken = (payload as any).sessionToken || (payload as any).redisSessionId;
-    }
+    const verified = await resolveVerifiedSessionCookie(cookieValue);
+    const sessionToken = verified?.token;
+    const payload: JWTPayload | undefined = verified?.payload;
 
     if (!sessionToken) {
-      console.warn('[DECODE-SESSION] No sessionToken resolved from cookie (shape:', shaped?.shape ?? 'unrecognized', ')');
+      console.warn('[DECODE-SESSION] Session cookie did not verify (shape:', shaped?.shape ?? 'unrecognized', ')');
       return null;
     }
 
@@ -292,7 +282,7 @@ export async function decodeSession(
       // fixing a silent path.
       console.warn(
         '[DECODE-SESSION] No sess: record for token',
-        sessionToken.substring(0, 10),
+        tokenLogId(sessionToken),
         '— no fallback available, session will be signed out'
       );
       return null;

package/src/server/verified-session-token.ts

@@ -0,0 +1,103 @@
+/**
+ * PAY-1476 / card 372275 (R941 s1b) - THE ONE SHARED VERIFIED RESOLVER for a session token taken from a cookie.
+ *
+ * THE DEFECT (4.4.5, measured at the deployed portal by QAPert-NightHawk, mail 59030):
+ *   Module A  server/decode-session.ts  the ba-hmac branch took `{token}.{anything}` and used segment 0 unread.
+ *   Module B  server/auth.ts  Path B    took the token from ANY recognised shape and never verified anything;
+ *                                       a forged JWS resolved there too.
+ * Both then treated "a Redis record exists" as the validation. So a leaked session token string was a bearer
+ * credential with no signature needed, including on the portal's admin API gate (api-admin-gate -> decodeSession).
+ *
+ * THE RULE THIS MODULE ENFORCES: a cookie yields a session token ONLY after its signature checks out against
+ * the auth secret. Every caller that turns a cookie into a token for the session store awaits this function.
+ * lib/session-cookie-shape.ts stays classification-only and secret-free (it cannot verify, by construction).
+ *
+ *   ba-hmac  `{token}.{sig}` as Better Auth mints it (better-call signCookieValue): sig =
+ *            base64(HMAC-SHA256(secret, token)), standard padding, 44 characters. Compared with
+ *            crypto.timingSafeEqual over equal-length buffers.
+ *   jws      legacy NextAuth-era cookie: jose jwtVerify with the same secret, then the sessionToken
+ *            (or redisSessionId) claim.
+ *   anything else, a missing secret, or a failed check -> null. Never throws.
+ *
+ * THE SECRET is the auth secret from getIDPClientConfig(), which resolves env-first (BETTER_AUTH_SECRET,
+ * NEXTAUTH_SECRET, then IdP config; PAY-1460). The cookie HMAC key IS the auth secret, so the resolver and the
+ * config loader cannot disagree about which secret signs sessions (BAPert 59034).
+ */
+import { createHmac, timingSafeEqual } from 'crypto';
+import { jwtVerify, type JWTPayload } from 'jose';
+import { getIDPClientConfig } from '../lib/idp-client-config';
+import { extractSessionCookieValue, extractSessionTokenFromCookieValue } from '../lib/session-cookie-shape';
+
+/** Better Auth's signature: base64 of a 32-byte HMAC-SHA256, padded = 44 chars ending in '='. */
+const BA_SIGNATURE_LENGTH = 44;
+
+async function authSecret(): Promise<string | null> {
+  try {
+    const config = await getIDPClientConfig();
+    return config?.authSecret ? String(config.authSecret) : null;
+  } catch {
+    return null;
+  }
+}
+
+function verifyBaHmac(rawValue: string, secret: string): string | null {
+  const dot = rawValue.lastIndexOf('.');
+  if (dot < 1) return null;
+  const token = rawValue.slice(0, dot);
+  let signature = rawValue.slice(dot + 1);
+  if (signature.includes('%')) {
+    try {
+      signature = decodeURIComponent(signature);
+    } catch {
+      return null;
+    }
+  }
+  if (signature.length !== BA_SIGNATURE_LENGTH || !signature.endsWith('=')) return null;
+  const expected = createHmac('sha256', secret).update(token, 'utf8').digest('base64');
+  const a = Buffer.from(signature, 'utf8');
+  const b = Buffer.from(expected, 'utf8');
+  if (a.length !== b.length) return null;
+  return timingSafeEqual(a, b) ? token : null;
+}
+
+export interface VerifiedSessionCookie {
+  token: string;
+  shape: 'ba-hmac' | 'jws';
+  /** The verified JWS payload (jws shape only). */
+  payload?: JWTPayload;
+}
+
+async function verifyJws(rawValue: string, secret: string): Promise<VerifiedSessionCookie | null> {
+  try {
+    const { payload } = await jwtVerify(rawValue, new TextEncoder().encode(secret));
+    const claim = (payload as Record<string, unknown>).sessionToken ?? (payload as Record<string, unknown>).redisSessionId;
+    return typeof claim === 'string' && claim ? { token: claim, shape: 'jws', payload } : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The verified session cookie (token, shape, JWS payload), or null unless its signature verifies. */
+export async function resolveVerifiedSessionCookie(rawValue: string | null | undefined): Promise<VerifiedSessionCookie | null> {
+  if (!rawValue) return null;
+  const shaped = extractSessionTokenFromCookieValue(rawValue);
+  if (!shaped) return null;
+  const secret = await authSecret();
+  if (!secret) return null;
+  if (shaped.shape === 'ba-hmac') {
+    const token = verifyBaHmac(rawValue, secret);
+    return token ? { token, shape: 'ba-hmac' } : null;
+  }
+  return verifyJws(rawValue, secret);
+}
+
+/** The session token carried by a raw session-cookie value, or null unless its signature verifies. */
+export async function resolveVerifiedSessionToken(rawValue: string | null | undefined): Promise<string | null> {
+  const verified = await resolveVerifiedSessionCookie(rawValue);
+  return verified ? verified.token : null;
+}
+
+/** Same, reading the session cookie (every name it is minted under, chunks joined) from a Request. */
+export async function resolveVerifiedSessionTokenFromRequest(request: Request): Promise<string | null> {
+  return resolveVerifiedSessionToken(extractSessionCookieValue(request));
+}

package/src/stores/authStore.ts

@@ -26,6 +26,7 @@ import {
   getCsrfCookieName,
   getSecureCsrfCookieName
 } from '../lib/app-slug';
+import { tokenLogId } from '../lib/token-log-id';
 
 // ===============================
 // INTERFACES & TYPES
@@ -484,19 +485,28 @@ export const useAuthStore = create<AuthStore>()(
 
       forceLogoutAndRedirect: async (reason: string) => {
         const state = get();
-        
+        // Same truncation convention as the server-side session logs (session-store.ts,
+        // refresh.ts): a session token is a bearer credential, and this line goes to the
+        // browser console (and whatever aggregates authLogger client-side) - full value
+        // was leftover debug logging (DotNetPert-Scout, mail 58678).
+        // PAY-1505: the ternary that used to stand here fell back to the RAW token on its false arm.
+        // Safe only by the unenforced property that the arm is reached when the token is falsy -
+        // exactly the shape the source guard exists to refuse. tokenLogId already answers 'none'
+        // for an absent token, so the fallback is not needed.
+        const sessionTokenPrefix = tokenLogId(state.session?.sessionToken);
+
         // AGGRESSIVE LOGGING TO TRACK EXECUTION
         console.error('🚨 FORCE LOGOUT INITIATED 🚨', {
           reason,
           userId: state.user?.id,
-          sessionToken: state.session?.sessionToken,
+          sessionToken: sessionTokenPrefix,
           timestamp: new Date().toISOString()
         });
-        
+
         authLogger.error('[AuthStore] Force logout initiated', {
           reason,
           userId: state.user?.id,
-          sessionToken: state.session?.sessionToken
+          sessionToken: sessionTokenPrefix
         });
         
         try {
@@ -1870,7 +1880,8 @@ export const useAuthStore = create<AuthStore>()(
         
         // If this event is about the current user, update their state
         if (data.userId === state.user?.id && state.session) {
-          authLogger.info('[AuthStore] Updating current user state from SignalR:', data);
+          // PAY-1427: the event is user state; log its shape, not its contents.
+          authLogger.info('[AuthStore] Updating current user state from SignalR:', { keys: Object.keys(data || {}) });
           // ... user state update logic would go here
         }
       },

package/src/types/recovery.ts

@@ -1,4 +1,4 @@
-export type RecoveryStep = 'initiate' | 'select-method' | 'verify-code' | 'set-password' | 'complete';
+export type RecoveryStep = 'initiate' | 'select-method' | 'verify-code' | 'set-password' | 'requested' | 'complete';
 
 export interface RecoverySession {
   recoveryToken: string;