@payez/next-mvp 4.1.14 → 4.1.21

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

@@ -0,0 +1,31 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { idpFetchJSON } from '../../lib/idp-fetch';
+import { ENV_CONFIG } from '../../config/env';
+
+/**
+ * List the signed-in user's passkeys (GET /api/Passkeys, user JWT).
+ * Probe-verified live 2026-08-01 (anon -> 401 = routed).
+ * No session -> upstream 401, passed through, never invented locally.
+ */
+export async function GET(req: NextRequest) {
+  const result = await idpFetchJSON(req, `${ENV_CONFIG.IDP_URL}/api/Passkeys`, { method: 'GET' });
+
+  if (!result.ok) {
+    return NextResponse.json(
+      {
+        success: false,
+        message: 'Upstream error',
+        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+        meta: { attemptedRefresh: result.attemptedRefresh },
+      },
+      { status: result.status },
+    );
+  }
+
+  const bodyJson: any = result.json;
+  if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
+    if (bodyJson.success === true) return NextResponse.json(bodyJson.data, { status: 200 });
+    return NextResponse.json(bodyJson, { status: 200 });
+  }
+  return NextResponse.json(bodyJson ?? {}, { status: 200 });
+}

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

@@ -0,0 +1,54 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { idpFetchJSON } from '../../lib/idp-fetch';
+import { ENV_CONFIG } from '../../config/env';
+
+/**
+ * Manage ONE passkey (PATCH rename / DELETE revoke, /api/Passkeys/{id},
+ * user JWT). The id arrives from the Next dynamic segment via the routes
+ * wrapper — it is never read from the body.
+ */
+
+function upstreamError(result: { status: number; json: unknown; attemptedRefresh: boolean }) {
+  return NextResponse.json(
+    {
+      success: false,
+      message: 'Upstream error',
+      error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+      meta: { attemptedRefresh: result.attemptedRefresh },
+    },
+    { status: result.status },
+  );
+}
+
+function passthrough(json: unknown) {
+  const bodyJson: any = json;
+  if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
+    if (bodyJson.success === true) return NextResponse.json(bodyJson.data ?? { success: true }, { status: 200 });
+    return NextResponse.json(bodyJson, { status: 200 });
+  }
+  return NextResponse.json(bodyJson ?? { success: true }, { status: 200 });
+}
+
+export async function PATCH(req: NextRequest, id: string) {
+  let body = '{}';
+  try {
+    const raw = await req.text();
+    if (raw && raw.trim().length > 0) body = raw;
+  } catch {}
+
+  const result = await idpFetchJSON(req, `${ENV_CONFIG.IDP_URL}/api/Passkeys/${encodeURIComponent(id)}`, {
+    method: 'PATCH',
+    headers: { 'Content-Type': 'application/json' },
+    body,
+  });
+  if (!result.ok) return upstreamError(result);
+  return passthrough(result.json);
+}
+
+export async function DELETE(req: NextRequest, id: string) {
+  const result = await idpFetchJSON(req, `${ENV_CONFIG.IDP_URL}/api/Passkeys/${encodeURIComponent(id)}`, {
+    method: 'DELETE',
+  });
+  if (!result.ok) return upstreamError(result);
+  return passthrough(result.json);
+}

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

@@ -0,0 +1,42 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { idpFetchJSON } from '../../lib/idp-fetch';
+import { ENV_CONFIG } from '../../config/env';
+
+/**
+ * Begin the passkey REGISTRATION ceremony (POST /api/Passkeys/register/options,
+ * user JWT — a credential change; the IDP may demand step-up, surfaced as-is).
+ * Returns the WebAuthn PublicKeyCredentialCreationOptions (ride the envelope
+ * `data`, per the archived hand-roll contract).
+ */
+export async function POST(req: NextRequest) {
+  let body = '{}';
+  try {
+    const raw = await req.text();
+    if (raw && raw.trim().length > 0) body = raw;
+  } catch {}
+
+  const result = await idpFetchJSON(req, `${ENV_CONFIG.IDP_URL}/api/Passkeys/register/options`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body,
+  });
+
+  if (!result.ok) {
+    return NextResponse.json(
+      {
+        success: false,
+        message: 'Upstream error',
+        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+        meta: { attemptedRefresh: result.attemptedRefresh },
+      },
+      { status: result.status },
+    );
+  }
+
+  const bodyJson: any = result.json;
+  if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
+    if (bodyJson.success === true) return NextResponse.json(bodyJson.data, { status: 200 });
+    return NextResponse.json(bodyJson, { status: 200 });
+  }
+  return NextResponse.json(bodyJson ?? {}, { status: 200 });
+}

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

@@ -0,0 +1,41 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { idpFetchJSON } from '../../lib/idp-fetch';
+import { ENV_CONFIG } from '../../config/env';
+
+/**
+ * Finish the passkey REGISTRATION ceremony (POST /api/Passkeys/register/verify,
+ * user JWT). Body forwarded VERBATIM — it carries the enrolment handle plus the
+ * authenticator attestation produced by navigator.credentials.create().
+ */
+export async function POST(req: NextRequest) {
+  let body = '{}';
+  try {
+    const raw = await req.text();
+    if (raw && raw.trim().length > 0) body = raw;
+  } catch {}
+
+  const result = await idpFetchJSON(req, `${ENV_CONFIG.IDP_URL}/api/Passkeys/register/verify`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body,
+  });
+
+  if (!result.ok) {
+    return NextResponse.json(
+      {
+        success: false,
+        message: 'Upstream error',
+        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+        meta: { attemptedRefresh: result.attemptedRefresh },
+      },
+      { status: result.status },
+    );
+  }
+
+  const bodyJson: any = result.json;
+  if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
+    if (bodyJson.success === true) return NextResponse.json(bodyJson.data, { status: 200 });
+    return NextResponse.json(bodyJson, { status: 200 });
+  }
+  return NextResponse.json(bodyJson ?? {}, { status: 200 });
+}

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

@@ -117,6 +117,25 @@ export async function GET(req: NextRequest) {
           // 2FA fields - critical for middleware redirect logic
           requires2FA, // From cached client config (client-wide setting)
           twoFactorComplete: effectiveTwoFactorComplete, // From session, BUT respects MFA TTL
+          // Cards 141688/141741 — the IDP's routing decision, relayed verbatim.
+          //
+          // THIS IS THE SECOND IMPLEMENTATION OF VIABILITY. The other is
+          // routes/auth/viability.ts, which is what the admin graft mounts.
+          // Both are publicly exported entry points, so both can be a consumer's
+          // only source of this answer. Adding the relay to just one would leave
+          // an app that mounts THIS one still blind to enroll_mfa — the exact
+          // seam these cards are about, reopened one export over.
+          //
+          // 'enroll_mfa' = no USABLE method, the user cannot complete a
+          // challenge. 'mfa_verify' = usable method exists. null = nothing due.
+          // NOT a completion signal: twoFactorComplete still owns that.
+          //
+          // No `?? null`: undefined (never captured — every session minted
+          // before this change) must stay distinguishable from null (the IDP
+          // said nothing is outstanding). Defaulting to null would tell the
+          // gate that every pre-existing session is fully authenticated,
+          // including zero-method users who must be routed to enrol.
+          nextStep: sessionData.nextStep,
           // Token status for refresh decisions
           accessTokenExpired,
           hasRefreshToken: !!sessionData.idpRefreshToken

package/src/auth/better-auth.ts

@@ -20,6 +20,7 @@ import type { IDPClientConfig } from '../lib/idp-client-config';
 import { getIDPClientConfig } from '../lib/idp-client-config';
 import { getAppSlug } from '../lib/app-slug';
 import { getRedis } from '../lib/redis';
+import { SESSION_TTL } from '../lib/session-store';
 
 /**
  * Better Auth social provider config shape.
@@ -170,6 +171,27 @@ export function buildBetterAuthProviders(
  */
 export interface CreateBetterAuthInstanceOptions {
   magicLink?: MagicLinkOptions;
+  /**
+   * Extra Better Auth plugins supplied by the consuming app.
+   *
+   * WHY THIS EXISTS — session minting is not delegable any other way. BA's
+   * `setSessionCookie` requires a `GenericEndpointContext`, which only BA's own
+   * endpoint machinery constructs, so an app that must mint a session for an
+   * identity established OUTSIDE BA's built-in providers (passkey sign-in being
+   * the first) cannot do it from a route handler. It needs a real BA endpoint,
+   * and endpoints only arrive via plugins.
+   *
+   * Deliberately GENERIC. The package gains "an app may supply plugins" rather
+   * than any knowledge of passkeys — the alternative was teaching this file
+   * about a specific auth method, which is how a package accumulates a consumer's
+   * feature list.
+   *
+   * The alternative to this option is an app hand-rolling the session cookie
+   * (`{token}.{base64(hmac)}`, standard padding, runtime `authSecret` from
+   * Redis). That fails as a session which DECODES BUT DOES NOT AUTHENTICATE —
+   * so this option exists specifically to make that shortcut unnecessary.
+   */
+  plugins?: Parameters<typeof betterAuth>[0]['plugins'];
 }
 
 /**
@@ -210,15 +232,19 @@ export function createBetterAuthInstance(
     // Redis-backed session storage via secondaryStorage
     secondaryStorage: {
       get: async (key: string) => {
-        return await getRedis().get(`ba:${appSlug}:${key}`);
+        try {
+          return await getRedis().get(`ba:${appSlug}:${key}`);
+        } catch { return null; }
       },
       set: async (key: string, value: string, ttl?: number) => {
-        const redis = getRedis();
-        if (ttl) {
-          await redis.setex(`ba:${appSlug}:${key}`, ttl, value);
-        } else {
-          await redis.setex(`ba:${appSlug}:${key}`, 7 * 24 * 60 * 60, value);
-        }
+        try {
+          const redis = getRedis();
+          if (ttl) {
+            await redis.setex(`ba:${appSlug}:${key}`, ttl, value);
+          } else {
+            await redis.setex(`ba:${appSlug}:${key}`, SESSION_TTL, value);
+          }
+        } catch { /* Redis unavailable — cookie cache still works */ }
       },
       delete: async (key: string) => {
         try {
@@ -265,6 +291,9 @@ export function createBetterAuthInstance(
     plugins: [
       nextCookies(),
       ...(opts.magicLink ? [magicLink(opts.magicLink)] : []),
+      // App-supplied plugins last: they may depend on the built-ins above, and
+      // ordering is BA's own concern once they are in the array.
+      ...(opts.plugins ?? []),
     ],
   });
 }
@@ -449,8 +478,20 @@ export async function exchangeOAuthForIdpTokens(
     }
 
     // Build IDP token data
-    // CRITICAL: If the IDP withholds refresh_token without setting requiresTwoFactor,
-    // treat missing refresh token as "2FA required" so middleware redirects to verify-code.
+    // ORIGINAL INTENT: IDP withholds refresh_token until 2FA is complete, so
+    // !hasRefreshToken was a reliable "2FA required" signal.
+    //
+    // BUG [IDP-2FA-BUG]: IDP is currently returning refresh_token on the initial
+    // oauth-callback even for require_2fa tenants that haven't done 2FA yet.
+    // This made !hasRefreshToken=false → requiresTwoFactor=false → mfaVerified=true,
+    // bypassing the 2FA gate entirely.
+    //
+    // FIX: Always set mfaVerified=false on the initial OAuth exchange.
+    // The tenant's require_2fa setting is enforced by the viability endpoint
+    // (tenantRequiresTwoFactor=true), which redirects to verify-code whenever
+    // mfaVerified=false. After real 2FA, transitionTo2FASession() sets it true.
+    // Revert this comment + restore `mfaVerified: !requiresTwoFactor` once the
+    // IDP correctly withholds refresh_token until post-2FA.
     const hasRefreshToken = !!result.refresh_token;
     const requiresTwoFactor = result.user?.requiresTwoFactor ?? result.requiresTwoFactor ?? !hasRefreshToken;
     const idpTokenData = {
@@ -464,32 +505,131 @@ export async function exchangeOAuthForIdpTokens(
       name: result.user?.full_name || result.user?.name || result.name || name,
       image: image,
       roles: result.user?.roles || result.roles || [],
-      mfaVerified: !requiresTwoFactor,
+      mfaVerified: false, // Always false post-OAuth — see IDP-2FA-BUG note above
+      // Cards 141688/141741 — RELAYED, NOT DERIVED.
+      //
+      // The IDP already decides this (ExternalAuthController:943 and :2024,
+      // WO 113023): "enroll_mfa" = no CONFIRMED method, "mfa_verify" = a
+      // confirmed method exists, null = fully authenticated. It was emitted
+      // here and dropped on this line — `idpTokenData` is built field-by-field,
+      // so anything not named is silently discarded. Both downstream consumers
+      // (the middleware gate and the verify-code page) then reasoned in its
+      // absence and sent zero-method users to a page they cannot act on.
+      //
+      // WIRE NAME IS SNAKE: `next_step`, per [JsonPropertyName("next_step")] on
+      // BOTH OAuthCallbackResponse and ExternalTokenResponse. Reading
+      // `result.nextStep` here would be `undefined` forever and fail silently —
+      // the same camel/snake break `requires_two_factor` already cost us once.
+      //
+      // Do NOT recompute this from a method query. The IDP owns the fact; it is
+      // already usable-aware (confirmed and not revoked, per DotNetPert), which
+      // is the distinction that decides correctness: a revoked-TOTP user has
+      // count>0 but usable=0, and deriving it locally would let through exactly
+      // the users we must challenge.
+      // No `?? null`: if the response has no `next_step` at all (older IDP
+      // build, or a path that does not set it), that is UNKNOWN, not "fully
+      // authenticated". Defaulting it to null here would manufacture a
+      // clean-bill-of-health the IDP never gave and fail open at the gate.
+      nextStep: result.next_step,
       idpClientId: result.client_id ? String(result.client_id) : undefined,
       merchantId: result.merchant_id ? String(result.merchant_id) : undefined,
     };
 
-    // Store in BA Redis session (for decodeSession)
+    // Storage is shared with the passkey sign-in path — see storeIdpTokensInSession.
+    const stored = await storeIdpTokensInSession(sessionToken, idpTokenData, provider);
+    if (stored) console.log('[BETTER_AUTH] IDP tokens stored in session for', email);
+    return stored;
+  } catch (err) {
+    console.error('[BETTER_AUTH] IDP token exchange failed:', err instanceof Error ? err.message : String(err));
+    return false;
+  }
+}
+
+/**
+ * Write IDP tokens into an EXISTING Better Auth session. Storage only — this
+ * function never acquires tokens and never decides who the caller is.
+ *
+ * ── WHY THIS IS SPLIT OUT (BAPert ruling, 2026-08-04) ────────────────────────
+ *
+ * `exchangeOAuthForIdpTokens` above does TWO things: it ACQUIRES tokens by
+ * POSTing to `/api/ExternalAuth/oauth-callback`, and then it STORES them. Only
+ * the second half is reusable, and the first half is actively dangerous to
+ * reuse:
+ *
+ *   oauth-callback mints an IDP bearer from an ASSERTED EMAIL with no
+ *   cryptographic verification of any kind (card 138635).
+ *
+ * Passkey sign-in already holds something strictly better — a grant issued by
+ * `/api/ExternalAuth/passwordless/passkey/verify`, which checked a real
+ * signature against a registered credential. Routing that through
+ * oauth-callback to obtain a session would DOWNGRADE a cryptographically
+ * verified assertion into an unverified one, make passkey sign-in weaker than
+ * its own ceremony, and inherit 138635 wholesale.
+ *
+ * That is not hypothetical: "do what the OAuth path does" is the obvious
+ * implementation and it is the wrong one. Splitting acquisition from storage is
+ * what makes the wrong one hard to write by accident.
+ *
+ * ── WHAT CALLERS MUST HAVE DONE FIRST ───────────────────────────────────────
+ *
+ * A Better Auth session must ALREADY EXIST for `sessionToken`. This function
+ * enriches; it does not create. Better Auth owns session creation and cookie
+ * signing, and nothing in this package should replicate either — the cookie is
+ * `{token}.{base64(hmac)}` with standard padding, signed with the runtime
+ * `authSecret` from Redis, and hand-rolling that produces a session which
+ * decodes but does not authenticate.
+ *
+ * @param sessionToken  the Better Auth session token (from its Set-Cookie)
+ * @param idpTokenData  tokens + identity, already obtained by the CALLER'S OWN
+ *                      verified route. Built field-by-field by the caller so an
+ *                      unnamed field cannot ride along silently.
+ * @param authProvider  provenance label recorded on the canonical row. Written
+ *                      to the historical `oauthProvider` key, which predates
+ *                      non-OAuth callers; the NAME is legacy, the VALUE should
+ *                      state what actually authenticated ('passkey', 'google').
+ */
+export async function storeIdpTokensInSession(
+  sessionToken: string,
+  idpTokenData: Record<string, unknown>,
+  authProvider: string,
+): Promise<boolean> {
+  try {
+    const config = await getIDPClientConfig();
+    const appSlug = config.clientSlug || getAppSlug();
+    const baKey = `ba:${appSlug}:${sessionToken}`;
+
+    const baRaw = await getRedis().get(baKey).catch(() => null);
+    if (!baRaw) {
+      // No session to enrich. Do NOT create one as a fallback: a session
+      // 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));
+      return false;
+    }
+
+    const baData = JSON.parse(baRaw);
     baData.idpTokens = idpTokenData;
-    await getRedis().setex(baKey, 7 * 24 * 60 * 60, JSON.stringify(baData));
+    await getRedis().setex(baKey, SESSION_TTL, JSON.stringify(baData));
 
-    // Write to canonical session store so refresh handler and token lifecycle can find the tokens.
-    // Key format: {sessionPrefix}{token} — same key that getSession() reads from.
+    // Canonical store — the key getSession() reads, used by the refresh handler
+    // and token lifecycle. A failure here leaves the BA session correct and the
+    // canonical row missing, so it is warned and not fatal: the user is signed
+    // in, and refresh degrades rather than the sign-in failing outright.
     try {
       const { getSessionPrefix } = await import('../lib/app-slug');
       const canonicalKey = `${getSessionPrefix()}${sessionToken}`;
-      await getRedis().setex(canonicalKey, 7 * 24 * 60 * 60, JSON.stringify({
+      await getRedis().setex(canonicalKey, SESSION_TTL, JSON.stringify({
         ...idpTokenData,
-        oauthProvider: provider,
+        oauthProvider: authProvider,
       }));
     } catch (canonicalErr) {
       console.warn('[BETTER_AUTH] Failed to write canonical session:', canonicalErr instanceof Error ? canonicalErr.message : String(canonicalErr));
     }
 
-    console.log('[BETTER_AUTH] IDP tokens stored in session for', email);
     return true;
   } catch (err) {
-    console.error('[BETTER_AUTH] IDP token exchange failed:', err instanceof Error ? err.message : String(err));
+    console.error('[BETTER_AUTH] storeIdpTokensInSession failed:', err instanceof Error ? err.message : String(err));
     return false;
   }
 }

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

@@ -150,105 +150,23 @@ function getLoginErrorMessage(status: number, responseData: any): string {
 // ============================================================================
 
 /**
- * Register/authenticate OAuth user with IDP.
+ * idpOAuthCallback REMOVED 2026-08-05 (NextPert, BAPert 20168 / QAPert 20166).
  *
- * Called after OAuth provider (Google, etc.) redirects back.
- * Creates or retrieves IDP user and returns IDP tokens.
+ * It POSTed to /api/ExternalAuth/oauth-callback with provider, email, name,
+ * tokens and client_id — ALL ASSERTIONS, no id_token, nothing verifiable. After
+ * the 170003 fix (13436d56e) that call can only ever return 401.
  *
- * @param oauthData - Data from OAuth provider
- * @returns IDP response with tokens and user info
- */
-export async function idpOAuthCallback(oauthData: {
-  provider: string;
-  providerAccountId: string;
-  email: string;
-  name?: string;
-  image?: string;
-  accessToken?: string;
-  refreshToken?: string;
-  expiresAt?: number;
-}): Promise<IdpOAuthCallbackResponse> {
-  const idpUrl = getIdpUrl();
-  const clientId = getClientId();
-
-  try {
-    const response = await fetch(`${idpUrl}/api/ExternalAuth/oauth-callback`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'X-Client-Id': clientId,
-      },
-      body: JSON.stringify({
-        provider: oauthData.provider,
-        provider_account_id: oauthData.providerAccountId,
-        email: oauthData.email,
-        name: oauthData.name || '',
-        image: oauthData.image || '',
-        access_token: oauthData.accessToken || '',
-        refresh_token: oauthData.refreshToken || '',
-        expires_at: oauthData.expiresAt || 0,
-        client_id: clientId,
-      }),
-    });
-
-    if (!response.ok) {
-      const errorText = await response.text().catch(() => 'Unknown error');
-      console.error('[IDP_CLIENT] OAuth callback failed:', response.status, errorText);
-      return {
-        success: false,
-        error: {
-          code: `HTTP_${response.status}`,
-          message: 'OAuth registration failed',
-        },
-      };
-    }
-
-    const data = await response.json();
-    const responseData = data.data || data;
-
-    // Normalize snake_case to camelCase
-    return {
-      success: responseData.success !== false,
-      data: responseData.success !== false
-        ? {
-            accessToken: responseData.accessToken || responseData.access_token,
-            refreshToken: responseData.refreshToken || responseData.refresh_token,
-            isNewUser: responseData.isNewUser ?? responseData.is_new_user ?? false,
-            user: responseData.user
-              ? {
-                  userId: responseData.user.userId || responseData.user.user_id,
-                  email: responseData.user.email || responseData.user.Email,
-                  fullName: responseData.user.fullName || responseData.user.full_name || responseData.user.name,
-                  roles: responseData.user.roles || [],
-                }
-              : undefined,
-          }
-        : undefined,
-      error: responseData.error,
-    };
-  } catch (error) {
-    console.error('[IDP_CLIENT] OAuth callback request failed:', error);
-    return {
-      success: false,
-      error: {
-        code: 'NETWORK_ERROR',
-        message: 'Failed to connect to authentication service',
-      },
-    };
-  }
-}
-
-// ============================================================================
-// TOKEN REFRESH
-// ============================================================================
-
-/**
- * Refresh an expired access token using the refresh token.
+ * It was a SECOND caller of the same endpoint, and only the first
+ * (better-auth.ts, card 138635) was hardened — the same duplicated-integration
+ * trap the viability code documents ("adding the relay to just one would leave
+ * an app that mounts THIS one still blind").
  *
- * @param refreshToken - The refresh token from previous login
- * @param mfaContext - MFA context to preserve across refresh
- * @returns New tokens or error
+ * It had no call sites and was not reachable through the package exports map
+ * (no ./auth/utils key, no wildcard), so removing it breaks nothing. Deleted
+ * rather than fixed, because an unreachable function whose only outcome is a
+ * 401 that LOOKS like a security success is a trap for whoever finds it next.
  */
+
 export async function idpRefreshToken(
   refreshToken: string,
   mfaContext?: {

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

@@ -95,6 +95,13 @@ export async function ensureFreshAccessToken(
 
   const storedToken = session.idpAccessToken;
   if (!storedToken) {
+    // Card 187871: same conflation as getIdpToken (server/auth.ts) - a live
+    // session with no access token and mfaVerified !== true is a user
+    // mid-2FA, not dead. Only terminal once the session itself claims 2FA
+    // is already done.
+    if (session.mfaVerified !== true) {
+      return { ok: false, code: 'NO_TOKEN_PENDING_2FA', message: 'Two-factor authentication required', status: 401, terminal: false };
+    }
     return { ok: false, code: 'NO_TOKEN', message: 'No IDP access token in session', status: 401, terminal: true };
   }
 
@@ -206,8 +213,16 @@ export async function ensureFreshAccessToken(
       acrValue = '2';
     }
 
+    // WO-2: send the POST-lock current refresh token, not the pre-lock snapshot.
+    // `session` was read before we acquired the lock; a concurrent refresh that
+    // completed while we waited rotates the token, so the pre-lock value is stale
+    // and would draw an avoidable 401 (the CAS now catches the resulting wipe, but
+    // the round-trip is wasted). `latest` is the authoritative post-lock session.
+    // Auth-context (amr/acr/2FA) intentionally still derives from `session` — it is
+    // the identity context of THIS request, unchanged by a token rotation.
+    const sentRefreshToken = latest?.idpRefreshToken ?? session.idpRefreshToken;
     const body: Record<string, unknown> = {
-      refresh_token: session.idpRefreshToken,
+      refresh_token: sentRefreshToken,
       amr: authMethods,
       acr: acrValue,
     };
@@ -246,15 +261,41 @@ export async function ensureFreshAccessToken(
     if (!idpResponse.ok) {
       const idpError = responseData?.error || {};
       const code = idpError.code || 'UNKNOWN_ERROR';
-      const discardToken = idpResponse.status === 401 || idpError.discard_token === true;
+      let discardToken = idpResponse.status === 401 || idpError.discard_token === true;
       const retryable = idpResponse.status !== 401 && idpError.retryable === true;
       if (discardToken) {
-        await updateSession(sessionToken, {
-          idpRefreshToken: '',
-          idpRefreshTokenExpires: undefined,
-          refreshTokenClearedAt: Date.now(),
-          refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${code}`,
-        });
+        // Race-safe discard (CAS): only clear if the refresh token we used is STILL
+        // current. A concurrent refresh may have already rotated it — our 401 is then
+        // stale/expected, and wiping here would silently log out a healthy session
+        // (the rotation-race wipe, QA 6873 site 1/2). Compare-and-skip if it changed;
+        // a concurrent rotation is NOT a terminal condition.
+        const postRefresh = await getSession(sessionToken);
+        // CAS compares against the token we ACTUALLY SENT (WO-2: sentRefreshToken,
+        // the post-lock value), not the pre-lock snapshot — otherwise a token rotated
+        // between pre-lock read and our send would be misjudged.
+        const tokenUnchanged =
+          !!sentRefreshToken && postRefresh?.idpRefreshToken === sentRefreshToken;
+        if (tokenUnchanged) {
+          await updateSession(sessionToken, {
+            idpRefreshToken: '',
+            idpRefreshTokenExpires: undefined,
+            refreshTokenClearedAt: Date.now(),
+            refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${code}`,
+          });
+        } 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
+          // (race-fix follow-up #1).
+          discardToken = false;
+          if (postRefresh?.idpAccessToken && postRefresh.idpAccessTokenExpires) {
+            return {
+              ok: true,
+              accessToken: postRefresh.idpAccessToken,
+              accessTokenExpires: postRefresh.idpAccessTokenExpires,
+              refreshed: true,
+            };
+          }
+        }
       }
       return {
         ok: false,

package/src/lib/session-store.ts

@@ -26,7 +26,10 @@ const getSessionVersionKey = (token: string) => `${getSessionPrefix()}ver:${toke
 const getBetterAuthSessionKey = (token: string, appSlug?: string) => `ba:${appSlug || 'app'}:${token}`;
 
 const REFRESH_LOCK_TTL = 60; // 60 seconds
-const SESSION_TTL = 3 * 24 * 60 * 60; // 3 days in seconds (matches refresh token lifetime)
+// 3 days in seconds (matches refresh token lifetime). EXPORTED as the single source
+// of session TTL — better-auth.ts derives its BA-session Redis TTL from this so the
+// two can never drift apart again (the 7d-vs-3d drift = the zombie-session window, QA 6952).
+export const SESSION_TTL = 3 * 24 * 60 * 60;
 
 export interface RefreshLockInfo {
   sessionToken: string;
@@ -122,6 +125,13 @@ export async function getBetterAuthSession(sessionToken: string, appSlug?: strin
         idpRefreshToken: data.idpTokens?.idpRefreshToken,
         idpAccessTokenExpires: data.idpTokens?.idpAccessTokenExpires,
         mfaVerified: data.idpTokens?.mfaVerified ?? false,
+        // Cards 141688/141741 — the IDP's routing decision, carried not derived.
+        // `null` is a real value here (IDP said nothing is outstanding), so it
+        // must stay distinguishable from `undefined` (we never captured it —
+        // true of every session minted before this change). No `?? null`:
+        // defaulting would turn "unknown" into "fully authenticated" and
+        // fail open on the existing session population.
+        nextStep: data.idpTokens?.nextStep,
         roles: data.idpTokens?.roles || [],
         idpClientId: data.idpTokens?.idpClientId ?? data.idpTokens?.clientId ?? data.idpClientId,
         merchantId: data.idpTokens?.merchantId ?? data.merchantId,