@payez/next-mvp 4.4.5 → 4.4.6

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;
     }
 
@@ -1383,26 +1408,7 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
       }
     }
 
-    // After successful OAuth callback: exchange the PROVIDER identity for IDP tokens.
-    //
-    // ⚠ WAS "exchange Google identity" — and it meant it literally. This call
-    // site passed no provider, so it took exchangeOAuthForIdpTokens's
-    // `provider: string = 'google'` default and asserted "google" to
-    // /api/ExternalAuth/oauth-callback for EVERY provider. That was harmless
-    // while Google was the only one wired, and became wrong the moment a second
-    // provider shipped: a GitHub sign-in forwarded a GitHub access_token
-    // labelled `provider: 'google'`, so the IDP tried to verify it as a Google
-    // identity and fail-closed with 401 UNVERIFIED_ASSERTION in
-    // `response_time_ms: 0` — it never had to call anyone to know it was wrong.
-    //
-    // The diagnostics made this maximally confusing: `access_token_forwarded:
-    // true` is correct and the token really did arrive. The FIELD was fine; the
-    // LABEL on it was a lie. Nothing on the client half is broken.
-    //
-    // The provider was never unavailable — it is the path segment this very
-    // `if` matches on (/api/auth/callback/github). Derive it instead of
-    // defaulting, because a default here cannot be right for more than one
-    // provider at a time.
+    // After successful OAuth callback: exchange Google identity for IDP tokens
     const url = new URL(request.url);
     if (url.pathname.includes('/callback/') && response.status === 302) {
       try {
@@ -1418,32 +1424,8 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
 
           const session = await auth.api.getSession({ headers });
           if (session?.session?.token) {
-            // /api/auth/callback/<provider>[?query] -> "<provider>"
-            const callbackProvider = url.pathname
-              .split('/callback/')[1]
-              ?.split('/')[0]
-              ?.split('?')[0]
-              ?.trim()
-              .toLowerCase() || '';
-
-            if (!callbackProvider) {
-              // Do NOT quietly fall back to 'google'. That silent default is the
-              // exact defect this block fixes, and re-introducing it here would
-              // reproduce it for whatever unparseable shape got us here.
-              console.error(
-                '[BETTER_AUTH] OAuth callback matched /callback/ but no provider could be derived from',
-                url.pathname,
-                '— refusing to assert a guessed provider to the IDP. No exchange performed.'
-              );
-            } else {
-              console.log(
-                '[BETTER_AUTH] Got session token from callback:',
-                session.session.token.substring(0, 10),
-                '| provider:', callbackProvider,
-                '| email:', session.user?.email
-              );
-              await exchangeOAuthForIdpTokens(session.session.token, callbackProvider);
-            }
+            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`);

package/src/components/admin/SessionsTab.tsx

@@ -45,6 +45,13 @@ export interface SessionsTabProps {
 // COMPONENT
 // -----------------------------------------------------------------------------
 
+// PAY-1429: admin handlers return a fixed message plus a correlationId (never upstream or
+// exception text). Surface the id so an admin can quote it to an operator.
+function errorWithRef(data: any, fallback: string): string {
+  const msg = typeof data?.error === 'string' ? data.error : fallback;
+  return data?.correlationId ? `${msg} (ref ${data.correlationId})` : msg;
+}
+
 export function SessionsTab({ isDark = true, apiBasePath = '/api/admin/sessions' }: SessionsTabProps) {
   const [sessions, setSessions] = useState<LoginSession[]>([]);
   const [isLoading, setIsLoading] = useState(false);
@@ -80,7 +87,7 @@ export function SessionsTab({ isDark = true, apiBasePath = '/api/admin/sessions'
         setSessions(data.sessions || []);
         setLastRefresh(new Date());
       } else {
-        setError(data.error || 'Failed to fetch sessions');
+        setError(errorWithRef(data, 'Failed to fetch sessions'));
       }
     } catch (err) {
       setError('Network error. Please try again.');
@@ -132,7 +139,7 @@ export function SessionsTab({ isDark = true, apiBasePath = '/api/admin/sessions'
         await fetchSessions();
         await fetchStats();
       } else {
-        alert(data.error || 'Failed to revoke session');
+        alert(errorWithRef(data, 'Failed to revoke session'));
       }
     } catch (err) {
       alert('Network error. Please try again.');
@@ -162,7 +169,7 @@ export function SessionsTab({ isDark = true, apiBasePath = '/api/admin/sessions'
         await fetchSessions();
         await fetchStats();
       } else {
-        alert(data.error || 'Failed to revoke sessions');
+        alert(errorWithRef(data, 'Failed to revoke sessions'));
       }
     } catch (err) {
       alert('Network error. Please try again.');

package/src/components/recovery/RequestedStep.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import React from 'react';
+
+interface Props {
+  onGoToLogin: () => void;
+}
+
+/**
+ * PAY-1588 (rigpert 60711): what a caller sees when the recovery request produced NO recovery session - an unknown
+ * address, a locked account, a throttled caller. ONE sentence, identical for all of them, so the screen cannot be used
+ * to tell which. It must not claim a reset happened (that is CompleteStep, reached only after a successful reset) and it
+ * must not name a cause.
+ */
+export function RequestedStep({ onGoToLogin }: Props) {
+  return (
+    <div className="bg-white border border-gray-300 rounded p-8 text-center">
+      <h2 className="text-2xl font-semibold text-gray-900 mb-2">Check your email</h2>
+
+      <p className="text-gray-600 mb-6">If an account exists for that email, we've sent instructions to reset your password.</p>
+
+      <button
+        onClick={onGoToLogin}
+        className="w-full py-2 px-4 border border-gray-300 rounded text-gray-900 font-medium hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-gray-400"
+      >
+        Back to sign in
+      </button>
+    </div>
+  );
+}

package/src/components/recovery/SetPasswordStep.tsx

@@ -1,6 +1,8 @@
 'use client';
 
-import React, { useState } from 'react';
+import React, { useEffect, useState } from 'react';
+import { usePasswordValidation } from '../../hooks/usePasswordValidation';
+import { passwordRulesText } from '../../lib/password-rules';
 
 interface Props {
   onSubmit: (password: string, confirmPassword: string) => void;
@@ -15,6 +17,14 @@ export function SetPasswordStep({ onSubmit, loading }: Props) {
 
   const passwordsMatch = password === confirmPassword && password !== '';
 
+  // PAY-1591: ADVISORY only. It shows the rules and what is missing; it never disables submit, because the validator
+  // may be down and the IdP is the authority (a dead validator must not trap a user who already spent their code).
+  const { setPassword: validateAsYouType, policy, failedRequirements } = usePasswordValidation();
+  // The policy only comes back with a validation, so ask once on mount with a one-character probe (it never leaves the
+  // policy question; the answer is what the rules line is built from). Until it lands the line says the rules are coming.
+  useEffect(() => { validateAsYouType('a'); }, [validateAsYouType]);
+  const missing = failedRequirements.filter((r) => !/^(Unable to validate|Password validation)/i.test(r));
+
   const handleSubmit = (e: React.FormEvent) => {
     e.preventDefault();
     if (passwordsMatch) {
@@ -25,9 +35,12 @@ export function SetPasswordStep({ onSubmit, loading }: Props) {
   return (
     <div className="bg-white border border-gray-300 rounded p-8">
       <h2 className="text-xl font-semibold text-gray-900 mb-2">Set New Password</h2>
-      <p className="text-sm text-gray-600 mb-6">
+      <p className="text-sm text-gray-600 mb-2">
         Choose a strong password for your account.
       </p>
+      <p data-testid="password-rules" className="text-sm text-gray-700 mb-6">
+        {passwordRulesText(policy)}
+      </p>
 
       <form onSubmit={handleSubmit} className="space-y-4">
         <div>
@@ -39,7 +52,7 @@ export function SetPasswordStep({ onSubmit, loading }: Props) {
               type={showPassword ? 'text' : 'password'}
               id="password"
               value={password}
-              onChange={(e) => setPassword(e.target.value)}
+              onChange={(e) => { setPassword(e.target.value); validateAsYouType(e.target.value); }}
               required
               disabled={loading}
               className="w-full px-3 py-2 border border-gray-300 rounded focus:ring-2 focus:ring-gray-900 focus:outline-none disabled:opacity-50 disabled:bg-gray-50 pr-10"
@@ -78,6 +91,14 @@ export function SetPasswordStep({ onSubmit, loading }: Props) {
           </div>
         </div>
 
+        {password && missing.length > 0 && (
+          <ul data-testid="password-missing" className="text-sm text-gray-700 list-disc pl-5">
+            {missing.map((r) => (
+              <li key={r}>{r}</li>
+            ))}
+          </ul>
+        )}
+
         {!passwordsMatch && confirmPassword && (
           <div className="bg-red-50 border border-red-200 rounded p-3">
             <p className="text-red-700 text-sm">Passwords do not match</p>

package/src/hooks/useViabilitySession.ts

@@ -43,7 +43,8 @@ export interface ViabilityState {
 
 interface ViabilityResponse {
   authenticated: boolean;
-  sessionToken?: string;
+  /** PAY-1481: tokenLogId of the session token (correlation only); the token itself is never returned. */
+  sessionTokenId?: string | null;
   requires2FA?: boolean;
   twoFactorComplete?: boolean;
   accessTokenExpired?: boolean;

package/src/lib/app-slug.ts

@@ -27,6 +27,56 @@ export function getAppSlug(): string {
   return cachedSlug;
 }
 
+/**
+ * The session cookie name has TWO producers: better-auth mints `${idpConfig.clientSlug || getAppSlug()}.session-token`, while
+ * the gate and every reader use getSessionCookieName() = getAppSlug() = APP_SLUG || CLIENT_ID. When the IdP's slug is known and
+ * differs, the gate looks for a cookie that was never set and every better-auth (Google) session bounces to
+ * /sign-in?error=SessionInvalid straight after a successful 2FA (rigpert 60743, live on :4797 with CLIENT_ID=idp-admin-ui-graft
+ * against clientSlug idp_admin_ui_graft). FAIL CLOSED: refuse rather than run with two names. No IdP slug -> nothing to compare.
+ */
+export function slugMismatchReason(idpClientSlug: string | null | undefined): string | null {
+  if (!idpClientSlug) return null;
+  const gateSlug = getAppSlug();
+  return idpClientSlug !== gateSlug ? `SLUG_MISMATCH: cookie=${idpClientSlug} gate=${gateSlug}` : null;
+}
+
+/**
+ * rigpert 60813: when the IdP returns NO client slug for this app (an unknown client: the config fetch failed or came back
+ * without one), startup must fail LOUD. Silently defaulting would run with a cookie name nobody verified against the IdP. The
+ * startup path swallows a failed config fetch when BETTER_AUTH_SECRET is supplied by env, so without this an unregistered
+ * CLIENT_ID (e.g. payez_idp_customer_web, absent on dev-93) would boot 'fine'.
+ */
+export function assertIdpSlugKnown(idpClientSlug: string | null | undefined): void {
+  if (idpClientSlug) return;
+  throw new Error(
+    `[FATAL] The IdP returned no client slug for this app (gate slug "${getAppSlug()}"). Either CLIENT_ID/APP_SLUG names a client ` +
+      `the IdP does not know, or its config could not be fetched. Refusing to start with an unverified session cookie name.`,
+  );
+}
+
+/**
+ * The health-endpoint view: a mismatch is always reportable; an UNKNOWN slug is reported only once startup has actually been
+ * attempted (before that nothing is known yet and health must not go red on a pod that has not started initialising).
+ */
+export function slugStateReason(idpClientSlug: string | null | undefined, startupAttempted: boolean): string | null {
+  const mismatch = slugMismatchReason(idpClientSlug);
+  if (mismatch) return mismatch;
+  if (startupAttempted && !idpClientSlug) return `SLUG_UNKNOWN: the IdP returned no client slug for this app gate=${getAppSlug()}`;
+  return null;
+}
+
+export function assertAppSlugMatchesIdp(idpClientSlug: string | null | undefined): void {
+  if (!idpClientSlug) return;
+  const gateSlug = getAppSlug();
+  if (slugMismatchReason(idpClientSlug) !== null) {
+    throw new Error(
+      `[FATAL] Session cookie name would have two sources: the IdP client slug is "${idpClientSlug}" but this app's slug ` +
+        `(APP_SLUG, else CLIENT_ID) is "${gateSlug}". better-auth would set "${idpClientSlug}.session-token" while the gate reads ` +
+        `"${gateSlug}.session-token", so every better-auth session would be rejected. Set APP_SLUG (or CLIENT_ID) to "${idpClientSlug}".`,
+    );
+  }
+}
+
 /**
  * Clears the cached slug (useful for testing).
  */

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

@@ -46,6 +46,32 @@ export type EnsureFreshResult =
       accessTokenExpires: number;
       /** True if we refreshed (or a concurrent refresh completed); false if the stored token was already fresh. */
       refreshed: boolean;
+      /**
+       * CARD 320072. Is the token in THIS result actually in the session store?
+       *
+       * ON THIS BRANCH OF THE UNION IT IS ALWAYS `true`, AND THAT IS THE POINT.
+       * Every `ok: true` return either read the token back from the store or
+       * wrote it and confirmed the write. An unpersisted refresh does not reach
+       * an `ok: true` result at all — it returns `ok:false, SESSION_PERSIST_FAILED`
+       * from the other branch below.
+       *
+       * READ THIS BEFORE YOU DELETE THE FIELD. It is declared `boolean` rather
+       * than the literal `true` on purpose: it is the assertable witness that the
+       * escalation is still wired. If someone later re-weakens the persist site
+       * back to reporting success, this field is where that regression becomes
+       * visible to a test instead of invisible to everyone. Cases 2 and 7 in
+       * test/ensure-fresh-persist-failure.test.cjs assert on it.
+       *
+       * WHAT THIS COMMENT USED TO SAY, AND WHY IT IS GONE. It documented `false`
+       * as a live value on an ok:true result — "we hold a valid token that was
+       * not persisted" — because that WAS the contract before this merge, when
+       * the dropped write was reported as a success with a flag on it. Blending
+       * in the escalation made that sentence describe a state the code can no
+       * longer produce. A docblock asserting an impossible semantic is exactly
+       * the defect f5ac6dc3 was written to fix, one file over; reproducing it
+       * here while merging that fix would be absurd.
+       */
+      persisted: boolean;
     }
   | {
       ok: false;
@@ -113,7 +139,8 @@ export async function ensureFreshAccessToken(
   const msUntilExpiry = effectiveExpires - now;
 
   if (msUntilExpiry > safetyWindowMs) {
-    return { ok: true, accessToken: storedToken, accessTokenExpires: effectiveExpires, refreshed: false };
+    // Durable by construction: this token came OUT of the store and we wrote nothing.
+    return { ok: true, accessToken: storedToken, accessTokenExpires: effectiveExpires, refreshed: false, persisted: true };
   }
 
   if (!session.idpRefreshToken) {
@@ -152,6 +179,8 @@ export async function ensureFreshAccessToken(
                 accessToken: after.idpAccessToken,
                 accessTokenExpires: after.idpAccessTokenExpires,
                 refreshed: true,
+                // Read back from the store after the winner's refresh - durable.
+                persisted: true,
               };
             }
           }
@@ -188,6 +217,8 @@ export async function ensureFreshAccessToken(
           accessToken: latest.idpAccessToken,
           accessTokenExpires: latest.idpAccessTokenExpires,
           refreshed: true,
+          // Post-lock re-read: another caller already refreshed and stored this.
+          persisted: true,
         };
       }
     }
@@ -276,12 +307,37 @@ export async function ensureFreshAccessToken(
         const tokenUnchanged =
           !!sentRefreshToken && postRefresh?.idpRefreshToken === sentRefreshToken;
         if (tokenUnchanged) {
-          await updateSession(sessionToken, {
+          /**
+           * 320072: this is the OTHER updateSession call in this file, and it
+           * does NOT escalate on a null return the way the persist site below
+           * does. Checked, not overlooked: reaching here requires
+           * `tokenUnchanged`, which requires `postRefresh?.idpRefreshToken` to
+           * equal the token we sent — so the CAS read three lines up already
+           * proved the row exists. A missing row makes tokenUnchanged false and
+           * routes to the else branch instead, so the dropped-write path is
+           * very nearly unreachable here.
+           *
+           * "Very nearly" is why the return IS still captured. The residual both
+           * halves of this merge identified is real: the row can expire between
+           * that CAS read and this write, in which case the dead refresh token is
+           * NOT cleared and the "we discarded it" claim in the error below is
+           * false. That costs nothing to observe and cannot be inferred from any
+           * other line, so it is warned rather than assumed — see `if (!cleared)`
+           * immediately below. The RESULT is unchanged either way: the session is
+           * unusable and we return the same non-ok payload.
+           */
+          const cleared = await updateSession(sessionToken, {
             idpRefreshToken: '',
             idpRefreshTokenExpires: undefined,
             refreshTokenClearedAt: Date.now(),
             refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${code}`,
           });
+          if (!cleared) {
+            console.warn('[ENSURE-FRESH] discard-token clear did not persist - no canonical session row', {
+              code,
+              requestId,
+            });
+          }
         } else {
           // Concurrent refresh already rotated the token — our 401 is stale. Return the
           // freshly-rotated token directly so the loser succeeds without a retry round-trip
@@ -293,6 +349,8 @@ export async function ensureFreshAccessToken(
               accessToken: postRefresh.idpAccessToken,
               accessTokenExpires: postRefresh.idpAccessTokenExpires,
               refreshed: true,
+              // `postRefresh` is a store read, so this token is by definition stored.
+              persisted: true,
             };
           }
         }
@@ -351,7 +409,14 @@ export async function ensureFreshAccessToken(
     const hasNewRefresh = typeof newRefresh === 'string' && newRefresh.length > 0;
     const newKid = extractKidFromToken(newAccess);
 
-    await updateSession(sessionToken, {
+    // *** CARD 320072. CAPTURE THIS RETURN. ***
+    // `updateSession` returns null - and writes nothing - when the canonical
+    // session row is missing, which happens whenever the BA fallback above is what
+    // resolved this session. Discarding the return is what let this function
+    // report `ok:true, refreshed:true` for a refresh it had just thrown away.
+    // The full rationale for what we DO about it is at the `if (!persisted)`
+    // block below; this line only makes the answer available.
+    const persisted = await updateSession(sessionToken, {
       ...session,
       idpAccessToken: newAccess,
       idpAccessTokenExpires: accessTokenExpires,
@@ -371,7 +436,71 @@ export async function ensureFreshAccessToken(
       mfaValidityHours: decoded?.mfa_validity_hours ? parseInt(decoded.mfa_validity_hours) : session.mfaValidityHours,
     });
 
-    return { ok: true, accessToken: newAccess, accessTokenExpires, refreshed: true };
+    /**
+     * 320072: DO NOT REPORT SUCCESS FOR A WRITE THAT WAS DISCARDED.
+     *
+     * `updateSession` returns null when the canonical session row is absent,
+     * which silently throws away EVERYTHING above — the new access token, the
+     * rotated refresh token, decodedAccessToken, authenticationMethods,
+     * mfaVerified, mfaCompletedAt, mfaExpiresAt. This return value was
+     * previously ignored, and the line below then reported
+     * `ok: true, refreshed: true`.
+     *
+     * WHY THAT IS WORSE THAN A PLAIN LOST WRITE. By this point the exchange at
+     * the IDP has ALREADY HAPPENED, so if refresh tokens are single-use the
+     * token we sent is now spent and its replacement is the thing we just
+     * dropped. The stored credential is therefore dead, and every later attempt
+     * re-sends that same dead token and fails. The user is bounced to LOGIN —
+     * not to verify-code — with nothing in the logs naming the cause.
+     *
+     * It did not even surface as a wrong answer to our one caller: server/auth.ts
+     * calls getRedisSession immediately after us, which is this same `getSession`,
+     * so it finds the same missing row and returns a generic NO_SESSION one frame
+     * later. The false `ok: true` was thus invisible AND the real cause — a
+     * dropped persist — was reported as an unrelated missing session.
+     *
+     * Naming it here is the point: the failure is reported at its true cause,
+     * with a code that says the refresh succeeded and the PERSIST is what
+     * failed. Not retryable — retrying burns another refresh token the same way.
+     *
+     * This is the card's option (b), deliberately. Option (a) — teaching
+     * updateSession to write through to whichever store holds the session,
+     * mirroring the read fallback above — is the better end state but changes
+     * write-path storage semantics for every caller, which is not this card.
+     *
+     * AND IT IS ALSO LOGGED, WHICH IS NOT THE SAME THING (BAPert R1134 §7,
+     * re-affirmed in R1145 §2c). Returning a named code tells the CALLER. §7
+     * requires that `persisted:false` reach a log A HUMAN READS, because the one
+     * caller — server/auth.ts — converts every non-ok result into the same
+     * generic 401 and keeps no record of which code produced it. Without this
+     * line the distinction we just bought at the type level is erased one frame
+     * later and no operator ever sees the word PERSIST. The escalation is the
+     * contract; the warn is the evidence.
+     */
+    if (!persisted) {
+      console.warn('[ENSURE-FRESH] refresh succeeded but was NOT persisted - no canonical session row', {
+        requestId,
+        refreshTokenRotated: hasNewRefresh,
+        persisted: false,
+      });
+      return {
+        ok: false,
+        code: 'SESSION_PERSIST_FAILED',
+        message:
+          'Token refresh succeeded at the IDP but the session could not be persisted; the rotated tokens were discarded.',
+        status: 401,
+        terminal: true,
+        retryable: false,
+        discardToken: true,
+        resolution: 'REAUTHENTICATE',
+      };
+    }
+
+    // `persisted: true` is not decoration and not a leftover: the `if` above is
+    // the only way out for a dropped write, so by construction anything reaching
+    // this line WAS written. Keeping the field keeps the ok:true branch of
+    // EnsureFreshResult total (Cases 2 and 7 assert on it) — BAPert R1145 §2d.
+    return { ok: true, accessToken: newAccess, accessTokenExpires, refreshed: true, persisted: true };
   } finally {
     if (weHoldLock) {
       await releaseRefreshLock(sessionToken, requestId, releaseVersion);