@payez/next-mvp 4.8.1 → 4.8.3

package/src/lib/session-store.ts

@@ -1,1092 +1,1092 @@
-/**
- * Session Store for `@payez/next-mvp` using ioredis
- *
- * This module provides a Redis-backed session store that is compatible with the
- * `ioredis` client. It handles the creation, retrieval, and deletion of
- * session data, which is the single source of truth for authentication.
- *
- * Includes advanced distributed refresh coordination with version control.
- */
-
-import redis from './redis';
-import { randomBytes } from 'crypto';
-import { SessionData } from '../models/SessionModel';
-import { getSessionPrefix, getRefreshLockPrefix, getAppSlug } from './app-slug';
-import { extractKidFromToken, decodeIdpAccessToken } from '../auth/utils/token-utils';
-import { tokenLogId } from './token-log-id';
-
-// Re-export SessionData for consumers
-export type { SessionData } from '../models/SessionModel';
-
-// Use app-slug prefixes for multi-app isolation
-const getSessionKey = (token: string) => `${getSessionPrefix()}${token}`;
-const getRefreshLockKey = (token: string) => `${getRefreshLockPrefix()}${token}`;
-const getSessionVersionKey = (token: string) => `${getSessionPrefix()}ver:${token}`;
-
-// Better Auth uses a different key format: ba:{appSlug}:{token}
-const getBetterAuthSessionKey = (token: string, appSlug?: string) => `ba:${appSlug || 'app'}:${token}`;
-
-const REFRESH_LOCK_TTL = 60; // 60 seconds
-// 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;
-  acquiredAt: number;
-  acquiredBy: string; // request ID or process identifier
-  lockVersion: number;
-}
-
-/**
- * Generates a new session token.
- * @returns A new session token string.
- */
-export function generateSessionToken(): string {
-  return randomBytes(32).toString('hex');
-}
-
-/**
- * Creates a new session in Redis.
- *
- * @param data The session data to store.
- * @returns The generated session token (redisSessionId).
- */
-export async function createSession(data: SessionData): Promise<string> {
-  const sessionToken = randomBytes(32).toString('hex');
-  const key = getSessionKey(sessionToken);
-  const versionKey = getSessionVersionKey(sessionToken);
-
-  try {
-    await redis.multi()
-      .setex(key, SESSION_TTL, JSON.stringify(data))
-      .setex(versionKey, SESSION_TTL, '1')
-      .exec();
-  } catch (error) {
-    console.error('[SESSION-STORE] Failed to create session:', error);
-    throw error;
-  }
-
-  return sessionToken;
-}
-
-/**
- * Retrieves a session from Redis.
- *
- * @param sessionToken The session token (redisSessionId) to look up.
- * @returns The session data, or null if not found.
- */
-export async function getSession(sessionToken: string): Promise<SessionData | null> {
-  if (!sessionToken) {
-    return null;
-  }
-  const key = getSessionKey(sessionToken);
-  const json = await redis.get(key);
-  if (!json) {
-    return null;
-  }
-  try {
-    return JSON.parse(json) as SessionData;
-  } catch {
-    console.error('[SESSION-STORE] Failed to parse session data');
-    return null;
-  }
-}
-
-/**
- * Retrieves a Better Auth session from Redis.
- * Better Auth uses key format: ba:{appSlug}:{token}
- *
- * @param sessionToken The session token to look up.
- * @param appSlug The app slug. Defaults to getAppSlug() - the SAME source Better Auth
- *                writes under - so reader and writer cannot disagree. Pass explicitly
- *                only if a consumer sets createBetterAuthInstance's clientSlug to
- *                something other than getAppSlug().
- * @returns The session data, or null if not found.
- */
-export async function getBetterAuthSession(sessionToken: string, appSlug?: string): Promise<SessionData | null> {
-  if (!sessionToken) {
-    return null;
-  }
-  // 241875 / 213416 (partially-applied fix, completed here): this line used to be
-  //     appSlug || process.env.CLIENT_ID || 'idealvibe_online'
-  // which is a THIRD slug resolution, disagreeing with the two canonical ones in
-  // this same file - getSessionKey() uses getSessionPrefix() (i.e. getAppSlug()),
-  // and deleteSessionEverywhere() uses `appSlug || getAppSlug()`.
-  //
-  // WRITER vs READER, same keyspace, different answers. Better Auth WRITES
-  // ba:{getAppSlug()}:{token} - deleteSessionEverywhere's own docstring records
-  // that it mirrors createBetterAuthInstance's `config.clientSlug || getAppSlug()`.
-  // This function READ ba:{CLIENT_ID or 'idealvibe_online'}:{token}.
-  //
-  // MEASURED IN PRODUCTION (keelauth-portal-config, 2026-08-24): APP_SLUG is
-  // declared and CLIENT_ID is NOT. So the old chain fell through to the literal and
-  // every one of this function's 14 call sites looked under a key Better Auth never
-  // writes. It could not match, and it returned null silently rather than failing -
-  // so the BA-session fallback documented in 4.1.3 (viability falling back to BA
-  // Redis when the canonical store misses) has been a safety net with a hole in it.
-  //
-  // 213416 fixed this exact writer/reader split at deleteSessionEverywhere and did
-  // not reach here. Using getAppSlug() makes the two agree by construction.
-  const slug = appSlug || getAppSlug();
-  const key = getBetterAuthSessionKey(sessionToken, slug);
-  const json = await redis.get(key);
-  if (!json) {
-    return null;
-  }
-  try {
-    const data = JSON.parse(json);
-    // Better Auth stores the session differently - extract user data
-    if (data.user) {
-      return {
-        userId: data.user.id || data.user.email,
-        email: data.user.email,
-        name: data.user.name,
-        image: data.user.image,
-        idpAccessToken: data.idpTokens?.idpAccessToken,
-        idpRefreshToken: data.idpTokens?.idpRefreshToken,
-        idpAccessTokenExpires: data.idpTokens?.idpAccessTokenExpires,
-        mfaVerified: data.idpTokens?.mfaVerified ?? false,
-        // R807 (362550): the `?? false` above is CORRECT and stays - fail-closed for
-        // every security consumer. This records the bit it destroys, for viability
-        // only. Note `!== undefined`, not a truthiness test: an explicit `false` IS
-        // a signal, and is precisely the case viability needs to see.
-        mfaSignalPresent: data.idpTokens?.mfaVerified !== undefined,
-        // 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,
-      } as SessionData;
-    }
-    return data as SessionData;
-  } catch {
-    console.error('[SESSION-STORE] Failed to parse Better Auth session data');
-    return null;
-  }
-}
-
-/**
- * Refresh session TTL without reading/writing data (sliding window expiry).
- */
-export async function touchSession(token: string): Promise<void> {
-  const key = getSessionKey(token);
-  await redis.expire(key, SESSION_TTL);
-}
-
-/**
- * Retrieves a session along with a version identifier for optimistic locking.
- * @param sessionToken The session token to look up.
- * @returns An object with session and version, or null if not found.
- */
-export async function getSessionWithVersion(sessionToken: string): Promise<{ session: SessionData; version: string } | null> {
-  const session = await getSession(sessionToken);
-  if (!session) {
-    return null;
-  }
-
-  const versionKey = getSessionVersionKey(sessionToken);
-  const version = await redis.get(versionKey);
-
-  if (!version) {
-    // Session exists but version key missing - use idpAccessTokenExpires as fallback
-    const fallbackVersion = String(session.idpAccessTokenExpires || Date.now());
-    return { session, version: fallbackVersion };
-  }
-
-  return { session, version };
-}
-
-/**
- * Checks if the access token in a session is still fresh (not expired).
- * @param sessionToken The session token to check.
- * @param currentAccessToken The current access token to compare.
- * @param currentVersion Optional version to check for changes.
- * @returns Object with freshness status and latest token info.
- */
-export async function isAccessTokenFresh(
-  sessionToken: string,
-  currentAccessToken: string,
-  currentVersion?: string
-): Promise<{
-  isFresh: boolean;
-  latestAccessToken?: string;
-  latestVersion?: string;
-  versionChanged: boolean;
-}> {
-  const sessionWithVersion = await getSessionWithVersion(sessionToken);
-
-  if (!sessionWithVersion) {
-    return { isFresh: false, versionChanged: true };
-  }
-
-  const { session, version } = sessionWithVersion;
-  const versionChanged = currentVersion ? version !== currentVersion : false;
-
-  // If version changed, the token might be stale
-  // Use normalized field name (idpAccessToken)
-  const isFresh = !versionChanged && session.idpAccessToken === currentAccessToken;
-
-  return {
-    isFresh,
-    latestAccessToken: session.idpAccessToken || undefined,
-    latestVersion: version,
-    versionChanged
-  };
-}
-
-/**
- * Deletes a session from Redis.
- * @param sessionToken The session token to delete.
- */
-export async function deleteSession(sessionToken: string): Promise<void> {
-  if (!sessionToken) {
-    return;
-  }
-  const key = getSessionKey(sessionToken);
-  const versionKey = getSessionVersionKey(sessionToken);
-  await redis.del(key, versionKey);
-}
-
-/**
- * Deletes a session from EVERY store it can live in (181922): the canonical
- * {slug}:sess:{token} + version key AND the Better Auth secondary
- * ba:{slug}:{token}. Deleting only one lets the survivor resurrect the
- * session — getSession's Path B reads the ba: record when the canonical is
- * gone, so a replayed cookie still authenticated after "logout" (QAPert-
- * NightHawk, exercised on :4702). Every sign-out entry point must use THIS,
- * not deleteSession.
- *
- * The ba: key slug mirrors createBetterAuthInstance's
- * `config.clientSlug || getAppSlug()` — on every current consumer those are
- * the same value (the client-id aliases make it so). If a consumer ever sets
- * them differently, pass appSlug explicitly.
- */
-export async function deleteSessionEverywhere(sessionToken: string, appSlug?: string): Promise<void> {
-  if (!sessionToken) {
-    return;
-  }
-  await redis.del(
-    getSessionKey(sessionToken),
-    getSessionVersionKey(sessionToken),
-    getBetterAuthSessionKey(sessionToken, appSlug || getAppSlug()),
-  );
-}
-
-/**
- * Sets a session directly (for testing or migrations).
- * @param sessionToken The session token.
- * @param data The session data.
- */
-export async function setSession(sessionToken: string, data: SessionData): Promise<void> {
-  const key = getSessionKey(sessionToken);
-  const versionKey = getSessionVersionKey(sessionToken);
-  await redis.multi()
-    .setex(key, SESSION_TTL, JSON.stringify(data))
-    .incr(versionKey)
-    .expire(versionKey, SESSION_TTL)
-    .exec();
-}
-
-/**
- * Describe a credential-bearing value for a log line WITHOUT the value: its kind only.
- * Deliberately no length or fingerprint either - both narrow the value down.
- */
-function describeTokenValueForLog(v: unknown): string {
-  if (v === undefined) return 'undefined';
-  if (v === null) return 'null';
-  if (typeof v === 'string') return v.length === 0 ? 'empty string' : 'non-empty string (value withheld)';
-  return `${typeof v} (value withheld)`;
-}
-
-/**
- * Updates tokens within an existing session.
- *
- * CALLERS MUST CHECK THE RETURN VALUE (320072). A null return means the session
- * row was absent and EVERY field in `updates` was discarded — it is a dropped
- * write, not a no-op on unchanged data. Ignoring it is how a token refresh came
- * to report success while persisting nothing.
- *
- * @param sessionToken The session token to update.
- * @param updates Partial session data to update.
- * @returns The updated session data, or null if the session was not found — in
- *          which case NOTHING WAS WRITTEN.
- */
-export async function updateSession(
-  sessionToken: string,
-  updates: Partial<SessionData>
-): Promise<SessionData | null> {
-  const key = getSessionKey(sessionToken);
-  const versionKey = getSessionVersionKey(sessionToken);
-
-  // Get current session to merge with updates
-  const currentSession = await getSession(sessionToken);
-  if (!currentSession) {
-    /**
-     * 320072: THIS IS A DROPPED WRITE, AND IT USED TO LEAVE NO TRACE.
-     *
-     * Returning null here is correct — there is no row to merge into — but it
-     * was previously done in total silence: no throw, no log. Every caller that
-     * ignores the return value therefore believed it had persisted, and the
-     * most damaging caller did exactly that (ensure-fresh-access-token).
-     *
-     * The canonical row can legitimately be absent: better-auth.ts writes the
-     * `ba:` record and the canonical row in two steps, and the second is
-     * wrapped in a try/catch that only console.warn()s — a deliberate,
-     * documented degradation that leaves the BA session correct and this row
-     * missing. That decision is fine. What was NOT fine is that the READ side
-     * reported success anyway, so nothing ever surfaced it.
-     *
-     * Logged at error, not warn: the caller's data is gone. Callers that can
-     * tolerate a missing row should check the null return — which is now the
-     * documented contract — rather than rely on this being quiet.
-     */
-    /**
-     * DO NOT LOG `key` HERE. `getSessionKey()` (line 21) is
-     * `${getSessionPrefix()}${token}` — the prefix plus the WHOLE session
-     * token — so logging it writes a live, replayable credential into
-     * console.error, and logs travel further than the process that wrote them.
-     * The redacting idiom in this file is `substring(0, 8) + '...'`.
-     *
-     * NOTE ON WHAT THIS COMMENT NO LONGER CLAIMS. It used to say this was the
-     * single unredacted departure in the file, and gave a site count. Both were
-     * wrong: a RAW refresh token was being emitted at the
-     * REFRESH_TOKEN_BEING_CLEARED site below, and the count was stale. QAPert found that
-     * leak while reviewing PR 96 — he looked *because* this comment asserted
-     * there was nothing to find, which is the worst thing a comment can do.
-     * It is fixed in the same commit as this rewrite.
-     *
-     * So the counts are gone deliberately. A tally in prose decays silently on
-     * the next edit and then actively misleads; that decay is the defect being
-     * repaired here, and reproducing it in the fix would be absurd. If you need
-     * a number, measure it — do not trust this paragraph for one.
-     *
-     * What replaces the prose is enforcement. The invariant is
-     * NO RAW CREDENTIAL IS EVER EMITTED FROM THIS FUNCTION, and it is pinned by
-     * executable assertions, not by this text:
-     *   - Case 4 (session token, this log)
-     *   - Case 5 (refresh token, the REFRESH_TOKEN_BEING_CLEARED log below)
-     * in test/ensure-fresh-persist-failure.test.cjs. Both were proven to fail
-     * when their fix is mutated out. Delete a redaction and a test goes red;
-     * delete this comment and nothing does. Trust the tests.
-     *
-     * Caught by QAPert on 320072 and made binding by BAPert (R1043 s1).
-     *
-     * The prefix is logged SEPARATELY and deliberately, because it is the field
-     * that makes this line diagnostic rather than decorative: a "no canonical
-     * row" miss has two very different causes, and only the prefix tells them
-     * apart —
-     *   wrong keyspace  (slug/prefix disagreement — the 241875 / 213416 defect
-     *                    documented at line 111, where a writer and a reader
-     *                    resolved different slugs and every lookup silently
-     *                    missed), versus
-     *   absent row      (the documented better-auth.ts two-step degradation).
-     * The prefix is an app slug, not a secret. Redacting it too would leave a
-     * log that says only "something was missing".
-     */
-    console.error('[SESSION-STORE] UPDATE_DROPPED_NO_CANONICAL_ROW', {
-      keyPrefix: getSessionPrefix(),
-      sessionToken: tokenLogId(sessionToken),
-      updatedFields: Object.keys(updates),
-      note: 'updateSession found no session row; ALL updates were discarded and null was returned',
-    });
-    return null;
-  }
-
-  // CRITICAL: Track any refresh token changes (check both old and new field names)
-  const hadRefreshToken = !!(currentSession.idpRefreshToken || (currentSession as any).refreshToken);
-  const willHaveRefreshToken = (updates as any).idpRefreshToken !== undefined
-    ? !!(updates as any).idpRefreshToken
-    : (updates as any).refreshToken !== undefined
-      ? !!(updates as any).refreshToken
-      : hadRefreshToken;
-
-  if (hadRefreshToken && !willHaveRefreshToken) {
-    console.error('[SESSION-STORE] ⚠️ REFRESH_TOKEN_BEING_CLEARED', {
-      sessionToken: tokenLogId(sessionToken),
-      userId: currentSession.userId,
-      updateKeys: Object.keys(updates),
-      // NEVER the value: a refresh token is a long-lived credential and this line ships to the
-      // log sink. The old `idpRefreshToken || refreshToken` printed a live legacy token raw when
-      // idpRefreshToken was null/"" (which clears) and refreshToken still held one.
-      // Test: test/session-store-refresh-token-not-logged.test.cjs
-      idpRefreshTokenInUpdate: describeTokenValueForLog((updates as any).idpRefreshToken),
-      legacyRefreshTokenInUpdate: describeTokenValueForLog((updates as any).refreshToken),
-      refreshTokenClearedReason: (updates as any).refreshTokenClearedReason || 'UNKNOWN',
-      stack: new Error().stack
-    });
-  }
-
-  // Merge current session with updates
-  const updatedSession = { ...currentSession, ...updates };
-
-  // Write the entire updated session back to Redis with version increment
-  await redis.multi()
-    .setex(key, SESSION_TTL, JSON.stringify(updatedSession))
-    .incr(versionKey)
-    .expire(versionKey, SESSION_TTL)
-    .exec();
-
-  return updatedSession;
-}
-
-/**
- * Derives the MFA lifetime fields from an IDP access token.
- *
- * *** CARD 339563. THE FLAG AND THE EXPIRY ARE ONE UNIT - WRITE THEM TOGETHER. ***
- *
- * The 2FA-completion writers below used to set `mfaVerified: true` and never
- * write `mfaExpiresAt`, while every consumer reads the expiry as
- *     const mfaExpiresAt = sessionData.mfaExpiresAt || 0;
- *     const mfaExpired   = mfaExpiresAt > 0 && mfaExpiresAt < Date.now();
- * The `> 0` guard makes a MISSING expiry unfalsifiable, so `mfaExpired` is
- * forced false forever and the session's MFA state never ages out. The IDP is
- * NOT at fault: IdentityBearerTokenService emits mfa_time + mfa_expires +
- * mfa_validity_hours together inside one `if` block, so the claims arrive as an
- * atomic set or not at all. We were dropping them on the floor.
- *
- * *** THIS RETURNS `{}` WHEN THE TOKEN CARRIES NO mfa_expires, AND THAT IS
- * *** DELIBERATE - DO NOT DEFAULT IT TO `Date.now()` OR TO A CONSTANT. ***
- * The step-up policy omits mfa_time on purpose when the only factor was a
- * primary credential (e.g. passwordless email login): inventing a timestamp
- * because one was missing is forging the evidence. A lane with no claim is a
- * lane where we do not KNOW the expiry, and the honest fix for that case is to
- * make the consumers fail CLOSED on a missing expiry - a separate change, on
- * this same card, which MUST land after this one (the card's option (b)).
- *
- * Mirrors ensure-fresh-access-token.ts and api-handlers/auth/refresh.ts, which
- * already derive these three fields off the token on every exchange (170007
- * rule 2: re-derive from the token, never carry forward).
- */
-function mfaLifetimeFromAccessToken(accessToken?: string): Partial<SessionData> {
-  if (!accessToken) return {};
-
-  const decoded = decodeIdpAccessToken(accessToken);
-  if (!decoded) return {};
-
-  const fields: Partial<SessionData> = {};
-
-  /**
-   * *** TEST THE CONVERTED VALUE, NOT THE CLAIM'S PRESENCE. ***
-   *
-   * This guard previously branched on `claim !== undefined && claim !== null`
-   * and then wrote `Number(claim) * 1000`. Those are two different questions,
-   * and for a non-numeric claim they disagree: the claim IS present, so the
-   * branch is taken, and the value written is NaN. That single NaN defeats both
-   * guards in this system at once, in opposite directions:
-   *
-   *   - `mfaEvidencePresent = mfaLifetime.mfaExpiresAt !== undefined` is TRUE
-   *     for NaN, so R908(e) certifies a ceremony it never observed and GRANTS
-   *     mfaVerified.
-   *   - consumers read `mfaExpiresAt || 0`, and NaN is FALSY, so that collapses
-   *     to 0, `0 > 0` is false, and the session NEVER expires.
-   *
-   * Net: `mfaVerified: true` that nothing can ever expire — the exact
-   * pre-339563 fail-open described at the top of this function, restored
-   * through a malformed claim, and silent (neither warning below fires on NaN).
-   *
-   * So a claim that will not convert is treated as NO CLAIM: the key is OMITTED
-   * and R908(e) withholds the grant, identical to the absent-claim lane. Absent
-   * and unreadable are the same epistemic state — we do not know the expiry —
-   * and they must not produce opposite security outcomes.
-   *
-   * Omitted, never set-to-undefined: updateSession() merges with
-   * `{ ...current, ...updates }`, so a present-but-undefined key would CLOBBER
-   * a good stored value. Pinned by test/mfa-expiry-malformed-claim.test.cjs.
-   *
-   * *** `Number.isFinite` ALONE IS NOT ENOUGH — IT MUST ALSO BE POSITIVE. ***
-   * `Number([])` is 0, and 0 is perfectly finite. But the consumer guard reads
-   * `mfaExpiresAt || 0`, and 0 is FALSY, so a stored zero is indistinguishable
-   * from a missing value and fails open in precisely the same way NaN does —
-   * while still passing `!== undefined` and so still earning the R908(e) grant.
-   * The honest invariant is not "is it a number" but "can this value ever
-   * expire a session", and only a positive one can. A zero/negative
-   * `mfa_expires` is meaningless anyway (epoch 1970 or earlier).
-   *
-   * The `typeof` gate rejects objects and arrays outright rather than letting
-   * JS coercion invent a number for them: `[]` -> 0 and `[5]` -> 5 are accidents
-   * of coercion, not claims the IDP made.
-   */
-  const claimToNumber = (claim: unknown): number | undefined => {
-    if (typeof claim !== 'number' && typeof claim !== 'string') return undefined;
-    if (claim === '') return undefined;
-    const n = Number(claim);
-    return Number.isFinite(n) && n > 0 ? n : undefined;
-  };
-
-  // Claims are Unix SECONDS; SessionData stores milliseconds.
-  const mfaExpires = claimToNumber(decoded.mfa_expires);
-  if (mfaExpires !== undefined) {
-    fields.mfaExpiresAt = mfaExpires * 1000;
-  }
-  const mfaTime = claimToNumber(decoded.mfa_time);
-  if (mfaTime !== undefined) {
-    fields.mfaCompletedAt = mfaTime * 1000;
-  }
-  const mfaValidityHours = claimToNumber(decoded.mfa_validity_hours);
-  if (mfaValidityHours !== undefined) {
-    fields.mfaValidityHours = mfaValidityHours;
-  }
-
-  return fields;
-}
-
-/**
- * Transitions a session to a MFA-completed state.
- * @param sessionToken The session token to update.
- * @param tokens The new tokens received after MFA completion.
- * @param mfaMethod The MFA method used (email, sms, totp) - required for token refresh.
- * @returns The updated session data.
- */
-export async function transitionTo2FASession(
-  sessionToken: string,
-  tokens: {
-    accessToken?: string;
-    refreshToken?: string;
-    accessTokenExpires?: number;
-    refreshTokenExpires?: number;
-    // Support new field names
-    idpAccessToken?: string;
-    idpRefreshToken?: string;
-    idpAccessTokenExpires?: number;
-    idpRefreshTokenExpires?: number;
-  },
-  mfaMethod?: 'email' | 'sms' | 'totp'
-): Promise<SessionData | null> {
-  const newAccessToken = tokens.idpAccessToken || tokens.accessToken;
-
-  console.log('[transitionTo2FASession] Called with:', {
-    sessionToken: tokenLogId(sessionToken),
-    mfaMethod,
-    hasAccessToken: !!newAccessToken,
-    hasRefreshToken: !!(tokens.idpRefreshToken || tokens.refreshToken),
-  });
-
-  // Extract bearerKeyId from the new access token (IDP may use different key after 2FA)
-  let bearerKeyId: string | undefined;
-  if (newAccessToken) {
-    bearerKeyId = extractKidFromToken(newAccessToken);
-    if (bearerKeyId) {
-      console.log('[transitionTo2FASession] Extracted bearerKeyId (kid) from new JWT header:', bearerKeyId);
-    }
-  }
-
-  // 339563: derive the expiry ONCE - it is both a field to write and the
-  // evidence test below. Re-deriving it twice invites the two reads to drift.
-  const mfaLifetime = mfaLifetimeFromAccessToken(newAccessToken);
-
-  // *** R908(e). ABSENCE OF THE EXPIRY IS NOT A COMPLETED CEREMONY. ***
-  //
-  // `mfaExpiresAt` is the only evidence we hold that a real MFA ceremony took
-  // place and when it lapses. When the stepped-up token carries no `mfa_expires`
-  // claim we do NOT know that this session is MFA-verified, and R908(e) binds
-  // the consumer to the third arm:
-  //
-  //   producers degrade  ->  consumers RE-CHALLENGE  ->  nobody infers a
-  //   negative from a silence.
-  //
-  // So: never mint `mfaVerified: true` off a token that carries no expiry (that
-  // is forging evidence of a ceremony we did not observe - 12188/12390), and
-  // never hard-refuse the user either (R486: null is "cannot determine", not
-  // "not 2FA-backed"). Leave the session un-verified and set `nextStep:
-  // 'mfa_verify'`, which is the field the gate already reads to mean "a usable
-  // method exists; challenge them" (SessionModel.ts:136).
-  const mfaEvidencePresent = mfaLifetime.mfaExpiresAt !== undefined;
-
-  // Support both old and new field names in input
-  // CRITICAL: Set BOTH mfaVerified (new) AND twoFactorComplete (legacy) for compatibility
-  // auth.ts session callback reads twoFactorComplete, so we must set it here
-  const updates: Partial<SessionData> = {
-    idpAccessToken: newAccessToken,
-    idpRefreshToken: tokens.idpRefreshToken || tokens.refreshToken,
-    idpAccessTokenExpires: tokens.idpAccessTokenExpires || tokens.accessTokenExpires,
-    mfaVerified: mfaEvidencePresent,
-    twoFactorComplete: mfaEvidencePresent, // Legacy field - required by auth.ts session callback
-    mfaMethod: mfaMethod,
-    // Update bearerKeyId if extracted from new token
-    ...(bearerKeyId && { bearerKeyId }),
-    // 339563: write the expiry in the SAME update that sets the flag. We already
-    // hold the stepped-up token here and already decode its header above.
-    ...mfaLifetime,
-    // R908(e): no evidence -> route to the challenge, do not grant and do not eject.
-    ...(mfaEvidencePresent ? {} : { nextStep: 'mfa_verify' as const }),
-  };
-
-  if (!mfaEvidencePresent) {
-    console.warn(
-      '[transitionTo2FASession] R908(e): the stepped-up token carries NO mfa_expires ' +
-        'claim, so there is no evidence of an MFA ceremony to record. NOT setting ' +
-        'mfaVerified; setting nextStep=mfa_verify so the consumer re-challenges. ' +
-        'If this fires for a lane that DID complete a real ceremony, the defect is ' +
-        'on the emit side (R908(b)) - do not "fix" it by minting the flag here.',
-      {
-        sessionToken: tokenLogId(sessionToken),
-        mfaMethod,
-        hasAccessToken: !!newAccessToken,
-      }
-    );
-  }
-
-  const refreshExpires = tokens.idpRefreshTokenExpires || tokens.refreshTokenExpires;
-  if (refreshExpires !== undefined) {
-    updates.idpRefreshTokenExpires = refreshExpires;
-  }
-
-  console.log('[transitionTo2FASession] Updates to apply:', {
-    mfaVerified: updates.mfaVerified,
-    twoFactorComplete: (updates as any).twoFactorComplete,
-    mfaMethod: updates.mfaMethod,
-    hasIdpAccessToken: !!updates.idpAccessToken,
-    // 339563: surface the expiry we derived. `mfaExpiresAt: undefined` here is
-    // the passwordless/primary-credential lane (token carried no mfa_expires).
-    // Since R908(e) that absence no longer fails OPEN: it withholds mfaVerified
-    // and sets nextStep=mfa_verify instead, so log both together - the pair is
-    // the whole decision.
-    mfaExpiresAt: updates.mfaExpiresAt,
-    mfaExpiresAtISO: updates.mfaExpiresAt ? new Date(updates.mfaExpiresAt).toISOString() : undefined,
-    nextStep: (updates as any).nextStep,
-  });
-
-  const result = await updateSession(sessionToken, updates);
-
-  console.log('[transitionTo2FASession] Result:', {
-    success: !!result,
-    resultMfaVerified: result?.mfaVerified,
-  });
-
-  return result;
-}
-
-/**
- * Updates IDP tokens and their expiries in an existing session.
- * @param sessionToken The session token to update.
- * @param idpAccessToken The new IDP access token.
- * @param idpRefreshToken The new IDP refresh token.
- * @param idpAccessTokenExpires The access token expiry timestamp.
- * @param idpRefreshTokenExpires The refresh token expiry timestamp (optional).
- * @returns The updated session data.
- */
-export async function updateTokens(
-  sessionToken: string,
-  idpAccessToken: string,
-  idpRefreshToken: string,
-  idpAccessTokenExpires: number,
-  idpRefreshTokenExpires?: number
-): Promise<SessionData | null> {
-  return updateSession(sessionToken, {
-    idpAccessToken,
-    idpRefreshToken,
-    idpAccessTokenExpires,
-    idpRefreshTokenExpires,
-  } as Partial<SessionData>);
-}
-
-/**
- * Marks a session as having completed MFA.
- *
- * *** 339563: PASS `accessToken` - THE STEPPED-UP ONE THE IDP JUST RETURNED. ***
- * Without it this writes a `mfaVerified: true` that no consumer can ever expire
- * (see mfaLifetimeFromAccessToken above). The parameter is OPTIONAL only so
- * that this published package keeps its existing signature for external
- * callers; every in-tree caller supplies it, and omitting it re-opens the
- * fail-open for that call site.
- *
- * It is NOT defaulted to the session's stored token on purpose. Reading it back
- * would work today only because the sole caller happens to run `updateTokens()`
- * first, and depending on undocumented call ORDERING is how this class of bug
- * gets reintroduced. The token is an input, so take it as one.
- *
- * @param sessionToken The session token to update.
- * @param accessToken The access token minted AFTER MFA completion, carrying the
- *                    mfa_time / mfa_expires / mfa_validity_hours claim set.
- * @returns The updated session data.
- */
-export async function mark2FAComplete(
-  sessionToken: string,
-  accessToken?: string
-): Promise<SessionData | null> {
-  const mfaLifetime = mfaLifetimeFromAccessToken(accessToken);
-
-  if (!accessToken) {
-    console.warn(
-      '[mark2FAComplete] 339563: called with NO access token, so no mfaExpiresAt ' +
-      'can be derived. This session\'s MFA state will not expire until its next ' +
-      'token refresh repairs it. Pass the stepped-up access token.'
-    );
-  } else if (mfaLifetime.mfaExpiresAt === undefined) {
-    console.warn(
-      '[mark2FAComplete] 339563: access token carries NO mfa_expires claim, so ' +
-      'this session has no MFA expiry. Expected on a primary-credential lane ' +
-      '(e.g. passwordless email); unexpected on an ordinary 2FA completion.'
-    );
-  }
-
-  // R908(e): identical rule to transitionTo2FASession above - no expiry derived
-  // means no observed ceremony, so we re-challenge rather than mint the flag.
-  // This path matters more than its sibling: `mark2FAComplete(sessionToken)`
-  // with the accessToken omitted used to write a bare `mfaVerified: true` that
-  // NO consumer could ever expire, and it is reachable from route handlers that
-  // take their tokens from the request body.
-  const mfaEvidencePresent = mfaLifetime.mfaExpiresAt !== undefined;
-
-  if (!mfaEvidencePresent) {
-    console.warn(
-      '[mark2FAComplete] R908(e): no mfa_expires could be derived, so mfaVerified ' +
-      'is NOT being set. Writing nextStep=mfa_verify instead so the consumer ' +
-      're-challenges. A caller that needs the grant must pass the stepped-up ' +
-      'access token that carries the claim.'
-    );
-  }
-
-  return updateSession(sessionToken, {
-    mfaVerified: mfaEvidencePresent,
-    ...mfaLifetime,
-    ...(mfaEvidencePresent ? {} : { nextStep: 'mfa_verify' as const }),
-  });
-}
-
-/**
- * Checks if MFA is complete for a session.
- * @param sessionToken The session token.
- * @returns True if MFA is complete.
- */
-export async function is2FAComplete(sessionToken: string): Promise<boolean> {
-  const session = await getSession(sessionToken);
-  return session?.mfaVerified === true;
-}
-
-/**
- * Gets IDP tokens from a session.
- * @param sessionToken The session token.
- * @returns The tokens or null if session not found.
- */
-export async function getTokens(sessionToken: string): Promise<{
-  accessToken: string;
-  refreshToken: string;
-  // Also expose new names for clarity
-  idpAccessToken: string;
-  idpRefreshToken: string;
-} | null> {
-  const session = await getSession(sessionToken);
-  if (!session || !session.idpAccessToken || !session.idpRefreshToken) {
-    return null;
-  }
-  return {
-    // Legacy names for backward compatibility
-    accessToken: session.idpAccessToken,
-    refreshToken: session.idpRefreshToken,
-    // New normalized names
-    idpAccessToken: session.idpAccessToken,
-    idpRefreshToken: session.idpRefreshToken,
-  };
-}
-
-/**
- * Refreshes a JWT session (placeholder for compatibility).
- * @param sessionToken The session token.
- * @returns The session data or null.
- */
-export async function refreshJWTSession(sessionToken: string): Promise<SessionData | null> {
-  return getSession(sessionToken);
-}
-
-/**
- * Clears all sessions (for testing only).
- */
-export async function clearAllSessions(): Promise<void> {
-  console.warn('[SESSION-STORE] clearAllSessions called - this should only be used in testing');
-}
-
-/**
- * Lists all sessions (for testing/debugging only).
- * @returns An empty array (placeholder).
- */
-export async function listAllSessions(): Promise<string[]> {
-  console.warn('[SESSION-STORE] listAllSessions called - this should only be used in testing');
-  return [];
-}
-
-// ===============================
-// DISTRIBUTED REFRESH COORDINATION
-// ===============================
-
-/**
- * Attempt to acquire a refresh lock for a session
- * Uses Redis SET with NX (Not eXists) for atomic lock acquisition
- */
-export async function acquireRefreshLock(
-  sessionToken: string,
-  requestId: string,
-  maxWaitMs: number = 5000
-): Promise<{ acquired: boolean; lockInfo?: RefreshLockInfo }> {
-  const lockKey = getRefreshLockKey(sessionToken);
-  const acquiredAt = Date.now();
-  const lockVersion = Math.floor(Math.random() * 1000000);
-
-  const lockInfo: RefreshLockInfo = {
-    sessionToken,
-    acquiredAt,
-    acquiredBy: requestId,
-    lockVersion
-  };
-
-  try {
-    // Try to acquire the lock atomically
-    const result = await redis.set(lockKey, JSON.stringify(lockInfo), 'PX', REFRESH_LOCK_TTL * 1000, 'NX');
-
-    if (result === 'OK') {
-      console.debug('[SESSION-STORE] Refresh lock acquired', {
-        sessionToken: tokenLogId(sessionToken),
-        requestId,
-        lockVersion
-      });
-
-      return { acquired: true, lockInfo };
-    } else {
-      // Lock already exists, check if we should wait
-      if (maxWaitMs > 0) {
-        console.debug('[SESSION-STORE] Refresh lock already exists, waiting for release', {
-          sessionToken: tokenLogId(sessionToken),
-          requestId,
-          maxWaitMs
-        });
-
-        return await waitForRefreshLockRelease(sessionToken, requestId, maxWaitMs);
-      }
-
-      console.warn('[SESSION-STORE] Refresh lock already exists, not waiting', {
-        sessionToken: tokenLogId(sessionToken),
-        requestId
-      });
-
-      return { acquired: false };
-    }
-  } catch (error) {
-    console.error('[SESSION-STORE] Failed to acquire refresh lock', {
-      sessionToken: tokenLogId(sessionToken),
-      requestId,
-      error: error instanceof Error ? error.message : String(error)
-    });
-
-    return { acquired: false };
-  }
-}
-
-/**
- * Wait for a refresh lock to be released
- */
-async function waitForRefreshLockRelease(
-  sessionToken: string,
-  requestId: string,
-  maxWaitMs: number
-): Promise<{ acquired: boolean; lockInfo?: RefreshLockInfo }> {
-  const lockKey = getRefreshLockKey(sessionToken);
-  const startTime = Date.now();
-  const pollInterval = 100;
-
-  while (Date.now() - startTime < maxWaitMs) {
-    try {
-      const lockExists = await redis.exists(lockKey);
-
-      if (!lockExists) {
-        // Lock released - do not reacquire here to avoid double refresh
-        return { acquired: false };
-      }
-
-      // Wait before next check
-      await new Promise(resolve => setTimeout(resolve, pollInterval));
-    } catch (error) {
-      console.error('[SESSION-STORE] Error while waiting for refresh lock release', {
-        sessionToken: tokenLogId(sessionToken),
-        requestId,
-        error: error instanceof Error ? error.message : String(error)
-      });
-      break;
-    }
-  }
-
-  console.warn('[SESSION-STORE] Timeout waiting for refresh lock release', {
-    sessionToken: tokenLogId(sessionToken),
-    requestId,
-    waitedMs: Date.now() - startTime
-  });
-
-  return { acquired: false };
-}
-
-/**
- * Release a refresh lock
- * Uses Lua script to ensure atomic validation and release
- */
-export async function releaseRefreshLock(
-  sessionToken: string,
-  requestId: string,
-  lockVersion?: number
-): Promise<boolean> {
-  const lockKey = getRefreshLockKey(sessionToken);
-
-  try {
-    // Lua script for atomic lock validation and release
-    const luaScript = `
-      local lockKey = KEYS[1]
-      local expectedRequestId = ARGV[1]
-      local expectedVersion = ARGV[2]
-
-      local lockData = redis.call('GET', lockKey)
-      if not lockData then
-        return 0  -- Lock doesn't exist
-      end
-
-      local lockInfo = cjson.decode(lockData)
-      if lockInfo.acquiredBy == expectedRequestId then
-        if not expectedVersion or expectedVersion == '' or tostring(lockInfo.lockVersion) == expectedVersion then
-          redis.call('DEL', lockKey)
-          return 1  -- Successfully released
-        else
-          return -2  -- Version mismatch
-        end
-      else
-        return -1  -- Wrong owner
-      end
-    `;
-
-    const result = await redis.eval(
-      luaScript,
-      1,
-      lockKey,
-      requestId,
-      lockVersion ? lockVersion.toString() : ''
-    ) as number;
-
-    if (result === 1) {
-      console.debug('[SESSION-STORE] Refresh lock released successfully', {
-        sessionToken: tokenLogId(sessionToken),
-        requestId,
-        lockVersion
-      });
-      return true;
-    } else if (result === 0) {
-      console.warn('[SESSION-STORE] Attempted to release non-existent refresh lock', {
-        sessionToken: tokenLogId(sessionToken),
-        requestId
-      });
-      return false;
-    } else if (result === -1) {
-      console.error('[SESSION-STORE] Attempted to release refresh lock owned by another request', {
-        sessionToken: tokenLogId(sessionToken),
-        requestId
-      });
-      return false;
-    } else if (result === -2) {
-      console.error('[SESSION-STORE] Lock version mismatch during release', {
-        sessionToken: tokenLogId(sessionToken),
-        requestId,
-        lockVersion
-      });
-      return false;
-    } else {
-      console.error('[SESSION-STORE] Unexpected result from lock release script', {
-        sessionToken: tokenLogId(sessionToken),
-        requestId,
-        result
-      });
-      return false;
-    }
-  } catch (error) {
-    console.error('[SESSION-STORE] Failed to release refresh lock', {
-      sessionToken: tokenLogId(sessionToken),
-      requestId,
-      error: error instanceof Error ? error.message : String(error)
-    });
-
-    return false;
-  }
-}
-
-/**
- * Check if a refresh lock exists for a session
- */
-export async function checkRefreshLock(sessionToken: string): Promise<RefreshLockInfo | null> {
-  const lockKey = getRefreshLockKey(sessionToken);
-
-  try {
-    const lockData = await redis.get(lockKey);
-
-    if (!lockData) {
-      return null;
-    }
-
-    return JSON.parse(lockData) as RefreshLockInfo;
-  } catch (error) {
-    console.error('[SESSION-STORE] Failed to check refresh lock', {
-      sessionToken: tokenLogId(sessionToken),
-      error: error instanceof Error ? error.message : String(error)
-    });
-
-    return null;
-  }
-}
-
-/**
- * Simple check if a refresh is currently in progress for a session
- */
-export async function isRefreshInProgress(sessionToken: string): Promise<boolean> {
-  const lock = await checkRefreshLock(sessionToken);
-  return lock !== null;
-}
-
-/**
- * Force cleanup of expired or orphaned refresh locks
- */
-export async function cleanupRefreshLocks(): Promise<number> {
-  console.warn('[SESSION-STORE] cleanupRefreshLocks called - scanning for expired locks');
-  return 0;
-}
-
-/**
- * PAY-2136 DIAGNOSTIC (BAPert 70873): which of the session keys EXIST for a token, right now.
- *
- * Names/presence only - this returns booleans and the key PREFIX (an app slug, not a secret), never a value and
- * never any part of the token. It exists so a NO_SESSION can be read for what it was: canonical row gone with the
- * ba: record alive (the :330 asymmetry), both gone (expired/deleted), or the store could not be asked ('error').
- *
- * EXISTS, not GET: it cannot parse, cannot throw on a malformed blob, and cannot return a credential. Each key is
- * asked separately so one timeout does not hide the other two. Never throws.
- */
-export type KeyPresence = boolean | 'error';
-export async function describeSessionKeyPresence(
-  sessionToken: string
-): Promise<{ prefix: string; canonical: KeyPresence; ba: KeyPresence; ver: KeyPresence }> {
-  const ask = async (key: string): Promise<KeyPresence> => {
-    try {
-      return (await redis.exists(key)) > 0;
-    } catch {
-      return 'error';
-    }
-  };
-  let prefix = '';
-  try {
-    prefix = getSessionPrefix();
-  } catch {
-    prefix = '';
-  }
-  if (!sessionToken) return { prefix, canonical: false, ba: false, ver: false };
-  let canonicalKey = '';
-  let baKey = '';
-  let verKey = '';
-  try {
-    canonicalKey = getSessionKey(sessionToken);
-    baKey = getBetterAuthSessionKey(sessionToken, getAppSlug());
-    verKey = getSessionVersionKey(sessionToken);
-  } catch {
-    return { prefix, canonical: 'error', ba: 'error', ver: 'error' };
-  }
-  const [canonical, ba, ver] = await Promise.all([ask(canonicalKey), ask(baKey), ask(verKey)]);
-  return { prefix, canonical, ba, ver };
-}
+/**
+ * Session Store for `@payez/next-mvp` using ioredis
+ *
+ * This module provides a Redis-backed session store that is compatible with the
+ * `ioredis` client. It handles the creation, retrieval, and deletion of
+ * session data, which is the single source of truth for authentication.
+ *
+ * Includes advanced distributed refresh coordination with version control.
+ */
+
+import redis from './redis';
+import { randomBytes } from 'crypto';
+import { SessionData } from '../models/SessionModel';
+import { getSessionPrefix, getRefreshLockPrefix, getAppSlug } from './app-slug';
+import { extractKidFromToken, decodeIdpAccessToken } from '../auth/utils/token-utils';
+import { tokenLogId } from './token-log-id';
+
+// Re-export SessionData for consumers
+export type { SessionData } from '../models/SessionModel';
+
+// Use app-slug prefixes for multi-app isolation
+const getSessionKey = (token: string) => `${getSessionPrefix()}${token}`;
+const getRefreshLockKey = (token: string) => `${getRefreshLockPrefix()}${token}`;
+const getSessionVersionKey = (token: string) => `${getSessionPrefix()}ver:${token}`;
+
+// Better Auth uses a different key format: ba:{appSlug}:{token}
+const getBetterAuthSessionKey = (token: string, appSlug?: string) => `ba:${appSlug || 'app'}:${token}`;
+
+const REFRESH_LOCK_TTL = 60; // 60 seconds
+// 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;
+  acquiredAt: number;
+  acquiredBy: string; // request ID or process identifier
+  lockVersion: number;
+}
+
+/**
+ * Generates a new session token.
+ * @returns A new session token string.
+ */
+export function generateSessionToken(): string {
+  return randomBytes(32).toString('hex');
+}
+
+/**
+ * Creates a new session in Redis.
+ *
+ * @param data The session data to store.
+ * @returns The generated session token (redisSessionId).
+ */
+export async function createSession(data: SessionData): Promise<string> {
+  const sessionToken = randomBytes(32).toString('hex');
+  const key = getSessionKey(sessionToken);
+  const versionKey = getSessionVersionKey(sessionToken);
+
+  try {
+    await redis.multi()
+      .setex(key, SESSION_TTL, JSON.stringify(data))
+      .setex(versionKey, SESSION_TTL, '1')
+      .exec();
+  } catch (error) {
+    console.error('[SESSION-STORE] Failed to create session:', error);
+    throw error;
+  }
+
+  return sessionToken;
+}
+
+/**
+ * Retrieves a session from Redis.
+ *
+ * @param sessionToken The session token (redisSessionId) to look up.
+ * @returns The session data, or null if not found.
+ */
+export async function getSession(sessionToken: string): Promise<SessionData | null> {
+  if (!sessionToken) {
+    return null;
+  }
+  const key = getSessionKey(sessionToken);
+  const json = await redis.get(key);
+  if (!json) {
+    return null;
+  }
+  try {
+    return JSON.parse(json) as SessionData;
+  } catch {
+    console.error('[SESSION-STORE] Failed to parse session data');
+    return null;
+  }
+}
+
+/**
+ * Retrieves a Better Auth session from Redis.
+ * Better Auth uses key format: ba:{appSlug}:{token}
+ *
+ * @param sessionToken The session token to look up.
+ * @param appSlug The app slug. Defaults to getAppSlug() - the SAME source Better Auth
+ *                writes under - so reader and writer cannot disagree. Pass explicitly
+ *                only if a consumer sets createBetterAuthInstance's clientSlug to
+ *                something other than getAppSlug().
+ * @returns The session data, or null if not found.
+ */
+export async function getBetterAuthSession(sessionToken: string, appSlug?: string): Promise<SessionData | null> {
+  if (!sessionToken) {
+    return null;
+  }
+  // 241875 / 213416 (partially-applied fix, completed here): this line used to be
+  //     appSlug || process.env.CLIENT_ID || 'idealvibe_online'
+  // which is a THIRD slug resolution, disagreeing with the two canonical ones in
+  // this same file - getSessionKey() uses getSessionPrefix() (i.e. getAppSlug()),
+  // and deleteSessionEverywhere() uses `appSlug || getAppSlug()`.
+  //
+  // WRITER vs READER, same keyspace, different answers. Better Auth WRITES
+  // ba:{getAppSlug()}:{token} - deleteSessionEverywhere's own docstring records
+  // that it mirrors createBetterAuthInstance's `config.clientSlug || getAppSlug()`.
+  // This function READ ba:{CLIENT_ID or 'idealvibe_online'}:{token}.
+  //
+  // MEASURED IN PRODUCTION (keelauth-portal-config, 2026-08-24): APP_SLUG is
+  // declared and CLIENT_ID is NOT. So the old chain fell through to the literal and
+  // every one of this function's 14 call sites looked under a key Better Auth never
+  // writes. It could not match, and it returned null silently rather than failing -
+  // so the BA-session fallback documented in 4.1.3 (viability falling back to BA
+  // Redis when the canonical store misses) has been a safety net with a hole in it.
+  //
+  // 213416 fixed this exact writer/reader split at deleteSessionEverywhere and did
+  // not reach here. Using getAppSlug() makes the two agree by construction.
+  const slug = appSlug || getAppSlug();
+  const key = getBetterAuthSessionKey(sessionToken, slug);
+  const json = await redis.get(key);
+  if (!json) {
+    return null;
+  }
+  try {
+    const data = JSON.parse(json);
+    // Better Auth stores the session differently - extract user data
+    if (data.user) {
+      return {
+        userId: data.user.id || data.user.email,
+        email: data.user.email,
+        name: data.user.name,
+        image: data.user.image,
+        idpAccessToken: data.idpTokens?.idpAccessToken,
+        idpRefreshToken: data.idpTokens?.idpRefreshToken,
+        idpAccessTokenExpires: data.idpTokens?.idpAccessTokenExpires,
+        mfaVerified: data.idpTokens?.mfaVerified ?? false,
+        // R807 (362550): the `?? false` above is CORRECT and stays - fail-closed for
+        // every security consumer. This records the bit it destroys, for viability
+        // only. Note `!== undefined`, not a truthiness test: an explicit `false` IS
+        // a signal, and is precisely the case viability needs to see.
+        mfaSignalPresent: data.idpTokens?.mfaVerified !== undefined,
+        // 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,
+      } as SessionData;
+    }
+    return data as SessionData;
+  } catch {
+    console.error('[SESSION-STORE] Failed to parse Better Auth session data');
+    return null;
+  }
+}
+
+/**
+ * Refresh session TTL without reading/writing data (sliding window expiry).
+ */
+export async function touchSession(token: string): Promise<void> {
+  const key = getSessionKey(token);
+  await redis.expire(key, SESSION_TTL);
+}
+
+/**
+ * Retrieves a session along with a version identifier for optimistic locking.
+ * @param sessionToken The session token to look up.
+ * @returns An object with session and version, or null if not found.
+ */
+export async function getSessionWithVersion(sessionToken: string): Promise<{ session: SessionData; version: string } | null> {
+  const session = await getSession(sessionToken);
+  if (!session) {
+    return null;
+  }
+
+  const versionKey = getSessionVersionKey(sessionToken);
+  const version = await redis.get(versionKey);
+
+  if (!version) {
+    // Session exists but version key missing - use idpAccessTokenExpires as fallback
+    const fallbackVersion = String(session.idpAccessTokenExpires || Date.now());
+    return { session, version: fallbackVersion };
+  }
+
+  return { session, version };
+}
+
+/**
+ * Checks if the access token in a session is still fresh (not expired).
+ * @param sessionToken The session token to check.
+ * @param currentAccessToken The current access token to compare.
+ * @param currentVersion Optional version to check for changes.
+ * @returns Object with freshness status and latest token info.
+ */
+export async function isAccessTokenFresh(
+  sessionToken: string,
+  currentAccessToken: string,
+  currentVersion?: string
+): Promise<{
+  isFresh: boolean;
+  latestAccessToken?: string;
+  latestVersion?: string;
+  versionChanged: boolean;
+}> {
+  const sessionWithVersion = await getSessionWithVersion(sessionToken);
+
+  if (!sessionWithVersion) {
+    return { isFresh: false, versionChanged: true };
+  }
+
+  const { session, version } = sessionWithVersion;
+  const versionChanged = currentVersion ? version !== currentVersion : false;
+
+  // If version changed, the token might be stale
+  // Use normalized field name (idpAccessToken)
+  const isFresh = !versionChanged && session.idpAccessToken === currentAccessToken;
+
+  return {
+    isFresh,
+    latestAccessToken: session.idpAccessToken || undefined,
+    latestVersion: version,
+    versionChanged
+  };
+}
+
+/**
+ * Deletes a session from Redis.
+ * @param sessionToken The session token to delete.
+ */
+export async function deleteSession(sessionToken: string): Promise<void> {
+  if (!sessionToken) {
+    return;
+  }
+  const key = getSessionKey(sessionToken);
+  const versionKey = getSessionVersionKey(sessionToken);
+  await redis.del(key, versionKey);
+}
+
+/**
+ * Deletes a session from EVERY store it can live in (181922): the canonical
+ * {slug}:sess:{token} + version key AND the Better Auth secondary
+ * ba:{slug}:{token}. Deleting only one lets the survivor resurrect the
+ * session — getSession's Path B reads the ba: record when the canonical is
+ * gone, so a replayed cookie still authenticated after "logout" (QAPert-
+ * NightHawk, exercised on :4702). Every sign-out entry point must use THIS,
+ * not deleteSession.
+ *
+ * The ba: key slug mirrors createBetterAuthInstance's
+ * `config.clientSlug || getAppSlug()` — on every current consumer those are
+ * the same value (the client-id aliases make it so). If a consumer ever sets
+ * them differently, pass appSlug explicitly.
+ */
+export async function deleteSessionEverywhere(sessionToken: string, appSlug?: string): Promise<void> {
+  if (!sessionToken) {
+    return;
+  }
+  await redis.del(
+    getSessionKey(sessionToken),
+    getSessionVersionKey(sessionToken),
+    getBetterAuthSessionKey(sessionToken, appSlug || getAppSlug()),
+  );
+}
+
+/**
+ * Sets a session directly (for testing or migrations).
+ * @param sessionToken The session token.
+ * @param data The session data.
+ */
+export async function setSession(sessionToken: string, data: SessionData): Promise<void> {
+  const key = getSessionKey(sessionToken);
+  const versionKey = getSessionVersionKey(sessionToken);
+  await redis.multi()
+    .setex(key, SESSION_TTL, JSON.stringify(data))
+    .incr(versionKey)
+    .expire(versionKey, SESSION_TTL)
+    .exec();
+}
+
+/**
+ * Describe a credential-bearing value for a log line WITHOUT the value: its kind only.
+ * Deliberately no length or fingerprint either - both narrow the value down.
+ */
+function describeTokenValueForLog(v: unknown): string {
+  if (v === undefined) return 'undefined';
+  if (v === null) return 'null';
+  if (typeof v === 'string') return v.length === 0 ? 'empty string' : 'non-empty string (value withheld)';
+  return `${typeof v} (value withheld)`;
+}
+
+/**
+ * Updates tokens within an existing session.
+ *
+ * CALLERS MUST CHECK THE RETURN VALUE (320072). A null return means the session
+ * row was absent and EVERY field in `updates` was discarded — it is a dropped
+ * write, not a no-op on unchanged data. Ignoring it is how a token refresh came
+ * to report success while persisting nothing.
+ *
+ * @param sessionToken The session token to update.
+ * @param updates Partial session data to update.
+ * @returns The updated session data, or null if the session was not found — in
+ *          which case NOTHING WAS WRITTEN.
+ */
+export async function updateSession(
+  sessionToken: string,
+  updates: Partial<SessionData>
+): Promise<SessionData | null> {
+  const key = getSessionKey(sessionToken);
+  const versionKey = getSessionVersionKey(sessionToken);
+
+  // Get current session to merge with updates
+  const currentSession = await getSession(sessionToken);
+  if (!currentSession) {
+    /**
+     * 320072: THIS IS A DROPPED WRITE, AND IT USED TO LEAVE NO TRACE.
+     *
+     * Returning null here is correct — there is no row to merge into — but it
+     * was previously done in total silence: no throw, no log. Every caller that
+     * ignores the return value therefore believed it had persisted, and the
+     * most damaging caller did exactly that (ensure-fresh-access-token).
+     *
+     * The canonical row can legitimately be absent: better-auth.ts writes the
+     * `ba:` record and the canonical row in two steps, and the second is
+     * wrapped in a try/catch that only console.warn()s — a deliberate,
+     * documented degradation that leaves the BA session correct and this row
+     * missing. That decision is fine. What was NOT fine is that the READ side
+     * reported success anyway, so nothing ever surfaced it.
+     *
+     * Logged at error, not warn: the caller's data is gone. Callers that can
+     * tolerate a missing row should check the null return — which is now the
+     * documented contract — rather than rely on this being quiet.
+     */
+    /**
+     * DO NOT LOG `key` HERE. `getSessionKey()` (line 21) is
+     * `${getSessionPrefix()}${token}` — the prefix plus the WHOLE session
+     * token — so logging it writes a live, replayable credential into
+     * console.error, and logs travel further than the process that wrote them.
+     * The redacting idiom in this file is `substring(0, 8) + '...'`.
+     *
+     * NOTE ON WHAT THIS COMMENT NO LONGER CLAIMS. It used to say this was the
+     * single unredacted departure in the file, and gave a site count. Both were
+     * wrong: a RAW refresh token was being emitted at the
+     * REFRESH_TOKEN_BEING_CLEARED site below, and the count was stale. QAPert found that
+     * leak while reviewing PR 96 — he looked *because* this comment asserted
+     * there was nothing to find, which is the worst thing a comment can do.
+     * It is fixed in the same commit as this rewrite.
+     *
+     * So the counts are gone deliberately. A tally in prose decays silently on
+     * the next edit and then actively misleads; that decay is the defect being
+     * repaired here, and reproducing it in the fix would be absurd. If you need
+     * a number, measure it — do not trust this paragraph for one.
+     *
+     * What replaces the prose is enforcement. The invariant is
+     * NO RAW CREDENTIAL IS EVER EMITTED FROM THIS FUNCTION, and it is pinned by
+     * executable assertions, not by this text:
+     *   - Case 4 (session token, this log)
+     *   - Case 5 (refresh token, the REFRESH_TOKEN_BEING_CLEARED log below)
+     * in test/ensure-fresh-persist-failure.test.cjs. Both were proven to fail
+     * when their fix is mutated out. Delete a redaction and a test goes red;
+     * delete this comment and nothing does. Trust the tests.
+     *
+     * Caught by QAPert on 320072 and made binding by BAPert (R1043 s1).
+     *
+     * The prefix is logged SEPARATELY and deliberately, because it is the field
+     * that makes this line diagnostic rather than decorative: a "no canonical
+     * row" miss has two very different causes, and only the prefix tells them
+     * apart —
+     *   wrong keyspace  (slug/prefix disagreement — the 241875 / 213416 defect
+     *                    documented at line 111, where a writer and a reader
+     *                    resolved different slugs and every lookup silently
+     *                    missed), versus
+     *   absent row      (the documented better-auth.ts two-step degradation).
+     * The prefix is an app slug, not a secret. Redacting it too would leave a
+     * log that says only "something was missing".
+     */
+    console.error('[SESSION-STORE] UPDATE_DROPPED_NO_CANONICAL_ROW', {
+      keyPrefix: getSessionPrefix(),
+      sessionToken: tokenLogId(sessionToken),
+      updatedFields: Object.keys(updates),
+      note: 'updateSession found no session row; ALL updates were discarded and null was returned',
+    });
+    return null;
+  }
+
+  // CRITICAL: Track any refresh token changes (check both old and new field names)
+  const hadRefreshToken = !!(currentSession.idpRefreshToken || (currentSession as any).refreshToken);
+  const willHaveRefreshToken = (updates as any).idpRefreshToken !== undefined
+    ? !!(updates as any).idpRefreshToken
+    : (updates as any).refreshToken !== undefined
+      ? !!(updates as any).refreshToken
+      : hadRefreshToken;
+
+  if (hadRefreshToken && !willHaveRefreshToken) {
+    console.error('[SESSION-STORE] ⚠️ REFRESH_TOKEN_BEING_CLEARED', {
+      sessionToken: tokenLogId(sessionToken),
+      userId: currentSession.userId,
+      updateKeys: Object.keys(updates),
+      // NEVER the value: a refresh token is a long-lived credential and this line ships to the
+      // log sink. The old `idpRefreshToken || refreshToken` printed a live legacy token raw when
+      // idpRefreshToken was null/"" (which clears) and refreshToken still held one.
+      // Test: test/session-store-refresh-token-not-logged.test.cjs
+      idpRefreshTokenInUpdate: describeTokenValueForLog((updates as any).idpRefreshToken),
+      legacyRefreshTokenInUpdate: describeTokenValueForLog((updates as any).refreshToken),
+      refreshTokenClearedReason: (updates as any).refreshTokenClearedReason || 'UNKNOWN',
+      stack: new Error().stack
+    });
+  }
+
+  // Merge current session with updates
+  const updatedSession = { ...currentSession, ...updates };
+
+  // Write the entire updated session back to Redis with version increment
+  await redis.multi()
+    .setex(key, SESSION_TTL, JSON.stringify(updatedSession))
+    .incr(versionKey)
+    .expire(versionKey, SESSION_TTL)
+    .exec();
+
+  return updatedSession;
+}
+
+/**
+ * Derives the MFA lifetime fields from an IDP access token.
+ *
+ * *** CARD 339563. THE FLAG AND THE EXPIRY ARE ONE UNIT - WRITE THEM TOGETHER. ***
+ *
+ * The 2FA-completion writers below used to set `mfaVerified: true` and never
+ * write `mfaExpiresAt`, while every consumer reads the expiry as
+ *     const mfaExpiresAt = sessionData.mfaExpiresAt || 0;
+ *     const mfaExpired   = mfaExpiresAt > 0 && mfaExpiresAt < Date.now();
+ * The `> 0` guard makes a MISSING expiry unfalsifiable, so `mfaExpired` is
+ * forced false forever and the session's MFA state never ages out. The IDP is
+ * NOT at fault: IdentityBearerTokenService emits mfa_time + mfa_expires +
+ * mfa_validity_hours together inside one `if` block, so the claims arrive as an
+ * atomic set or not at all. We were dropping them on the floor.
+ *
+ * *** THIS RETURNS `{}` WHEN THE TOKEN CARRIES NO mfa_expires, AND THAT IS
+ * *** DELIBERATE - DO NOT DEFAULT IT TO `Date.now()` OR TO A CONSTANT. ***
+ * The step-up policy omits mfa_time on purpose when the only factor was a
+ * primary credential (e.g. passwordless email login): inventing a timestamp
+ * because one was missing is forging the evidence. A lane with no claim is a
+ * lane where we do not KNOW the expiry, and the honest fix for that case is to
+ * make the consumers fail CLOSED on a missing expiry - a separate change, on
+ * this same card, which MUST land after this one (the card's option (b)).
+ *
+ * Mirrors ensure-fresh-access-token.ts and api-handlers/auth/refresh.ts, which
+ * already derive these three fields off the token on every exchange (170007
+ * rule 2: re-derive from the token, never carry forward).
+ */
+function mfaLifetimeFromAccessToken(accessToken?: string): Partial<SessionData> {
+  if (!accessToken) return {};
+
+  const decoded = decodeIdpAccessToken(accessToken);
+  if (!decoded) return {};
+
+  const fields: Partial<SessionData> = {};
+
+  /**
+   * *** TEST THE CONVERTED VALUE, NOT THE CLAIM'S PRESENCE. ***
+   *
+   * This guard previously branched on `claim !== undefined && claim !== null`
+   * and then wrote `Number(claim) * 1000`. Those are two different questions,
+   * and for a non-numeric claim they disagree: the claim IS present, so the
+   * branch is taken, and the value written is NaN. That single NaN defeats both
+   * guards in this system at once, in opposite directions:
+   *
+   *   - `mfaEvidencePresent = mfaLifetime.mfaExpiresAt !== undefined` is TRUE
+   *     for NaN, so R908(e) certifies a ceremony it never observed and GRANTS
+   *     mfaVerified.
+   *   - consumers read `mfaExpiresAt || 0`, and NaN is FALSY, so that collapses
+   *     to 0, `0 > 0` is false, and the session NEVER expires.
+   *
+   * Net: `mfaVerified: true` that nothing can ever expire — the exact
+   * pre-339563 fail-open described at the top of this function, restored
+   * through a malformed claim, and silent (neither warning below fires on NaN).
+   *
+   * So a claim that will not convert is treated as NO CLAIM: the key is OMITTED
+   * and R908(e) withholds the grant, identical to the absent-claim lane. Absent
+   * and unreadable are the same epistemic state — we do not know the expiry —
+   * and they must not produce opposite security outcomes.
+   *
+   * Omitted, never set-to-undefined: updateSession() merges with
+   * `{ ...current, ...updates }`, so a present-but-undefined key would CLOBBER
+   * a good stored value. Pinned by test/mfa-expiry-malformed-claim.test.cjs.
+   *
+   * *** `Number.isFinite` ALONE IS NOT ENOUGH — IT MUST ALSO BE POSITIVE. ***
+   * `Number([])` is 0, and 0 is perfectly finite. But the consumer guard reads
+   * `mfaExpiresAt || 0`, and 0 is FALSY, so a stored zero is indistinguishable
+   * from a missing value and fails open in precisely the same way NaN does —
+   * while still passing `!== undefined` and so still earning the R908(e) grant.
+   * The honest invariant is not "is it a number" but "can this value ever
+   * expire a session", and only a positive one can. A zero/negative
+   * `mfa_expires` is meaningless anyway (epoch 1970 or earlier).
+   *
+   * The `typeof` gate rejects objects and arrays outright rather than letting
+   * JS coercion invent a number for them: `[]` -> 0 and `[5]` -> 5 are accidents
+   * of coercion, not claims the IDP made.
+   */
+  const claimToNumber = (claim: unknown): number | undefined => {
+    if (typeof claim !== 'number' && typeof claim !== 'string') return undefined;
+    if (claim === '') return undefined;
+    const n = Number(claim);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+  };
+
+  // Claims are Unix SECONDS; SessionData stores milliseconds.
+  const mfaExpires = claimToNumber(decoded.mfa_expires);
+  if (mfaExpires !== undefined) {
+    fields.mfaExpiresAt = mfaExpires * 1000;
+  }
+  const mfaTime = claimToNumber(decoded.mfa_time);
+  if (mfaTime !== undefined) {
+    fields.mfaCompletedAt = mfaTime * 1000;
+  }
+  const mfaValidityHours = claimToNumber(decoded.mfa_validity_hours);
+  if (mfaValidityHours !== undefined) {
+    fields.mfaValidityHours = mfaValidityHours;
+  }
+
+  return fields;
+}
+
+/**
+ * Transitions a session to a MFA-completed state.
+ * @param sessionToken The session token to update.
+ * @param tokens The new tokens received after MFA completion.
+ * @param mfaMethod The MFA method used (email, sms, totp) - required for token refresh.
+ * @returns The updated session data.
+ */
+export async function transitionTo2FASession(
+  sessionToken: string,
+  tokens: {
+    accessToken?: string;
+    refreshToken?: string;
+    accessTokenExpires?: number;
+    refreshTokenExpires?: number;
+    // Support new field names
+    idpAccessToken?: string;
+    idpRefreshToken?: string;
+    idpAccessTokenExpires?: number;
+    idpRefreshTokenExpires?: number;
+  },
+  mfaMethod?: 'email' | 'sms' | 'totp'
+): Promise<SessionData | null> {
+  const newAccessToken = tokens.idpAccessToken || tokens.accessToken;
+
+  console.log('[transitionTo2FASession] Called with:', {
+    sessionToken: tokenLogId(sessionToken),
+    mfaMethod,
+    hasAccessToken: !!newAccessToken,
+    hasRefreshToken: !!(tokens.idpRefreshToken || tokens.refreshToken),
+  });
+
+  // Extract bearerKeyId from the new access token (IDP may use different key after 2FA)
+  let bearerKeyId: string | undefined;
+  if (newAccessToken) {
+    bearerKeyId = extractKidFromToken(newAccessToken);
+    if (bearerKeyId) {
+      console.log('[transitionTo2FASession] Extracted bearerKeyId (kid) from new JWT header:', bearerKeyId);
+    }
+  }
+
+  // 339563: derive the expiry ONCE - it is both a field to write and the
+  // evidence test below. Re-deriving it twice invites the two reads to drift.
+  const mfaLifetime = mfaLifetimeFromAccessToken(newAccessToken);
+
+  // *** R908(e). ABSENCE OF THE EXPIRY IS NOT A COMPLETED CEREMONY. ***
+  //
+  // `mfaExpiresAt` is the only evidence we hold that a real MFA ceremony took
+  // place and when it lapses. When the stepped-up token carries no `mfa_expires`
+  // claim we do NOT know that this session is MFA-verified, and R908(e) binds
+  // the consumer to the third arm:
+  //
+  //   producers degrade  ->  consumers RE-CHALLENGE  ->  nobody infers a
+  //   negative from a silence.
+  //
+  // So: never mint `mfaVerified: true` off a token that carries no expiry (that
+  // is forging evidence of a ceremony we did not observe - 12188/12390), and
+  // never hard-refuse the user either (R486: null is "cannot determine", not
+  // "not 2FA-backed"). Leave the session un-verified and set `nextStep:
+  // 'mfa_verify'`, which is the field the gate already reads to mean "a usable
+  // method exists; challenge them" (SessionModel.ts:136).
+  const mfaEvidencePresent = mfaLifetime.mfaExpiresAt !== undefined;
+
+  // Support both old and new field names in input
+  // CRITICAL: Set BOTH mfaVerified (new) AND twoFactorComplete (legacy) for compatibility
+  // auth.ts session callback reads twoFactorComplete, so we must set it here
+  const updates: Partial<SessionData> = {
+    idpAccessToken: newAccessToken,
+    idpRefreshToken: tokens.idpRefreshToken || tokens.refreshToken,
+    idpAccessTokenExpires: tokens.idpAccessTokenExpires || tokens.accessTokenExpires,
+    mfaVerified: mfaEvidencePresent,
+    twoFactorComplete: mfaEvidencePresent, // Legacy field - required by auth.ts session callback
+    mfaMethod: mfaMethod,
+    // Update bearerKeyId if extracted from new token
+    ...(bearerKeyId && { bearerKeyId }),
+    // 339563: write the expiry in the SAME update that sets the flag. We already
+    // hold the stepped-up token here and already decode its header above.
+    ...mfaLifetime,
+    // R908(e): no evidence -> route to the challenge, do not grant and do not eject.
+    ...(mfaEvidencePresent ? {} : { nextStep: 'mfa_verify' as const }),
+  };
+
+  if (!mfaEvidencePresent) {
+    console.warn(
+      '[transitionTo2FASession] R908(e): the stepped-up token carries NO mfa_expires ' +
+        'claim, so there is no evidence of an MFA ceremony to record. NOT setting ' +
+        'mfaVerified; setting nextStep=mfa_verify so the consumer re-challenges. ' +
+        'If this fires for a lane that DID complete a real ceremony, the defect is ' +
+        'on the emit side (R908(b)) - do not "fix" it by minting the flag here.',
+      {
+        sessionToken: tokenLogId(sessionToken),
+        mfaMethod,
+        hasAccessToken: !!newAccessToken,
+      }
+    );
+  }
+
+  const refreshExpires = tokens.idpRefreshTokenExpires || tokens.refreshTokenExpires;
+  if (refreshExpires !== undefined) {
+    updates.idpRefreshTokenExpires = refreshExpires;
+  }
+
+  console.log('[transitionTo2FASession] Updates to apply:', {
+    mfaVerified: updates.mfaVerified,
+    twoFactorComplete: (updates as any).twoFactorComplete,
+    mfaMethod: updates.mfaMethod,
+    hasIdpAccessToken: !!updates.idpAccessToken,
+    // 339563: surface the expiry we derived. `mfaExpiresAt: undefined` here is
+    // the passwordless/primary-credential lane (token carried no mfa_expires).
+    // Since R908(e) that absence no longer fails OPEN: it withholds mfaVerified
+    // and sets nextStep=mfa_verify instead, so log both together - the pair is
+    // the whole decision.
+    mfaExpiresAt: updates.mfaExpiresAt,
+    mfaExpiresAtISO: updates.mfaExpiresAt ? new Date(updates.mfaExpiresAt).toISOString() : undefined,
+    nextStep: (updates as any).nextStep,
+  });
+
+  const result = await updateSession(sessionToken, updates);
+
+  console.log('[transitionTo2FASession] Result:', {
+    success: !!result,
+    resultMfaVerified: result?.mfaVerified,
+  });
+
+  return result;
+}
+
+/**
+ * Updates IDP tokens and their expiries in an existing session.
+ * @param sessionToken The session token to update.
+ * @param idpAccessToken The new IDP access token.
+ * @param idpRefreshToken The new IDP refresh token.
+ * @param idpAccessTokenExpires The access token expiry timestamp.
+ * @param idpRefreshTokenExpires The refresh token expiry timestamp (optional).
+ * @returns The updated session data.
+ */
+export async function updateTokens(
+  sessionToken: string,
+  idpAccessToken: string,
+  idpRefreshToken: string,
+  idpAccessTokenExpires: number,
+  idpRefreshTokenExpires?: number
+): Promise<SessionData | null> {
+  return updateSession(sessionToken, {
+    idpAccessToken,
+    idpRefreshToken,
+    idpAccessTokenExpires,
+    idpRefreshTokenExpires,
+  } as Partial<SessionData>);
+}
+
+/**
+ * Marks a session as having completed MFA.
+ *
+ * *** 339563: PASS `accessToken` - THE STEPPED-UP ONE THE IDP JUST RETURNED. ***
+ * Without it this writes a `mfaVerified: true` that no consumer can ever expire
+ * (see mfaLifetimeFromAccessToken above). The parameter is OPTIONAL only so
+ * that this published package keeps its existing signature for external
+ * callers; every in-tree caller supplies it, and omitting it re-opens the
+ * fail-open for that call site.
+ *
+ * It is NOT defaulted to the session's stored token on purpose. Reading it back
+ * would work today only because the sole caller happens to run `updateTokens()`
+ * first, and depending on undocumented call ORDERING is how this class of bug
+ * gets reintroduced. The token is an input, so take it as one.
+ *
+ * @param sessionToken The session token to update.
+ * @param accessToken The access token minted AFTER MFA completion, carrying the
+ *                    mfa_time / mfa_expires / mfa_validity_hours claim set.
+ * @returns The updated session data.
+ */
+export async function mark2FAComplete(
+  sessionToken: string,
+  accessToken?: string
+): Promise<SessionData | null> {
+  const mfaLifetime = mfaLifetimeFromAccessToken(accessToken);
+
+  if (!accessToken) {
+    console.warn(
+      '[mark2FAComplete] 339563: called with NO access token, so no mfaExpiresAt ' +
+      'can be derived. This session\'s MFA state will not expire until its next ' +
+      'token refresh repairs it. Pass the stepped-up access token.'
+    );
+  } else if (mfaLifetime.mfaExpiresAt === undefined) {
+    console.warn(
+      '[mark2FAComplete] 339563: access token carries NO mfa_expires claim, so ' +
+      'this session has no MFA expiry. Expected on a primary-credential lane ' +
+      '(e.g. passwordless email); unexpected on an ordinary 2FA completion.'
+    );
+  }
+
+  // R908(e): identical rule to transitionTo2FASession above - no expiry derived
+  // means no observed ceremony, so we re-challenge rather than mint the flag.
+  // This path matters more than its sibling: `mark2FAComplete(sessionToken)`
+  // with the accessToken omitted used to write a bare `mfaVerified: true` that
+  // NO consumer could ever expire, and it is reachable from route handlers that
+  // take their tokens from the request body.
+  const mfaEvidencePresent = mfaLifetime.mfaExpiresAt !== undefined;
+
+  if (!mfaEvidencePresent) {
+    console.warn(
+      '[mark2FAComplete] R908(e): no mfa_expires could be derived, so mfaVerified ' +
+      'is NOT being set. Writing nextStep=mfa_verify instead so the consumer ' +
+      're-challenges. A caller that needs the grant must pass the stepped-up ' +
+      'access token that carries the claim.'
+    );
+  }
+
+  return updateSession(sessionToken, {
+    mfaVerified: mfaEvidencePresent,
+    ...mfaLifetime,
+    ...(mfaEvidencePresent ? {} : { nextStep: 'mfa_verify' as const }),
+  });
+}
+
+/**
+ * Checks if MFA is complete for a session.
+ * @param sessionToken The session token.
+ * @returns True if MFA is complete.
+ */
+export async function is2FAComplete(sessionToken: string): Promise<boolean> {
+  const session = await getSession(sessionToken);
+  return session?.mfaVerified === true;
+}
+
+/**
+ * Gets IDP tokens from a session.
+ * @param sessionToken The session token.
+ * @returns The tokens or null if session not found.
+ */
+export async function getTokens(sessionToken: string): Promise<{
+  accessToken: string;
+  refreshToken: string;
+  // Also expose new names for clarity
+  idpAccessToken: string;
+  idpRefreshToken: string;
+} | null> {
+  const session = await getSession(sessionToken);
+  if (!session || !session.idpAccessToken || !session.idpRefreshToken) {
+    return null;
+  }
+  return {
+    // Legacy names for backward compatibility
+    accessToken: session.idpAccessToken,
+    refreshToken: session.idpRefreshToken,
+    // New normalized names
+    idpAccessToken: session.idpAccessToken,
+    idpRefreshToken: session.idpRefreshToken,
+  };
+}
+
+/**
+ * Refreshes a JWT session (placeholder for compatibility).
+ * @param sessionToken The session token.
+ * @returns The session data or null.
+ */
+export async function refreshJWTSession(sessionToken: string): Promise<SessionData | null> {
+  return getSession(sessionToken);
+}
+
+/**
+ * Clears all sessions (for testing only).
+ */
+export async function clearAllSessions(): Promise<void> {
+  console.warn('[SESSION-STORE] clearAllSessions called - this should only be used in testing');
+}
+
+/**
+ * Lists all sessions (for testing/debugging only).
+ * @returns An empty array (placeholder).
+ */
+export async function listAllSessions(): Promise<string[]> {
+  console.warn('[SESSION-STORE] listAllSessions called - this should only be used in testing');
+  return [];
+}
+
+// ===============================
+// DISTRIBUTED REFRESH COORDINATION
+// ===============================
+
+/**
+ * Attempt to acquire a refresh lock for a session
+ * Uses Redis SET with NX (Not eXists) for atomic lock acquisition
+ */
+export async function acquireRefreshLock(
+  sessionToken: string,
+  requestId: string,
+  maxWaitMs: number = 5000
+): Promise<{ acquired: boolean; lockInfo?: RefreshLockInfo }> {
+  const lockKey = getRefreshLockKey(sessionToken);
+  const acquiredAt = Date.now();
+  const lockVersion = Math.floor(Math.random() * 1000000);
+
+  const lockInfo: RefreshLockInfo = {
+    sessionToken,
+    acquiredAt,
+    acquiredBy: requestId,
+    lockVersion
+  };
+
+  try {
+    // Try to acquire the lock atomically
+    const result = await redis.set(lockKey, JSON.stringify(lockInfo), 'PX', REFRESH_LOCK_TTL * 1000, 'NX');
+
+    if (result === 'OK') {
+      console.debug('[SESSION-STORE] Refresh lock acquired', {
+        sessionToken: tokenLogId(sessionToken),
+        requestId,
+        lockVersion
+      });
+
+      return { acquired: true, lockInfo };
+    } else {
+      // Lock already exists, check if we should wait
+      if (maxWaitMs > 0) {
+        console.debug('[SESSION-STORE] Refresh lock already exists, waiting for release', {
+          sessionToken: tokenLogId(sessionToken),
+          requestId,
+          maxWaitMs
+        });
+
+        return await waitForRefreshLockRelease(sessionToken, requestId, maxWaitMs);
+      }
+
+      console.warn('[SESSION-STORE] Refresh lock already exists, not waiting', {
+        sessionToken: tokenLogId(sessionToken),
+        requestId
+      });
+
+      return { acquired: false };
+    }
+  } catch (error) {
+    console.error('[SESSION-STORE] Failed to acquire refresh lock', {
+      sessionToken: tokenLogId(sessionToken),
+      requestId,
+      error: error instanceof Error ? error.message : String(error)
+    });
+
+    return { acquired: false };
+  }
+}
+
+/**
+ * Wait for a refresh lock to be released
+ */
+async function waitForRefreshLockRelease(
+  sessionToken: string,
+  requestId: string,
+  maxWaitMs: number
+): Promise<{ acquired: boolean; lockInfo?: RefreshLockInfo }> {
+  const lockKey = getRefreshLockKey(sessionToken);
+  const startTime = Date.now();
+  const pollInterval = 100;
+
+  while (Date.now() - startTime < maxWaitMs) {
+    try {
+      const lockExists = await redis.exists(lockKey);
+
+      if (!lockExists) {
+        // Lock released - do not reacquire here to avoid double refresh
+        return { acquired: false };
+      }
+
+      // Wait before next check
+      await new Promise(resolve => setTimeout(resolve, pollInterval));
+    } catch (error) {
+      console.error('[SESSION-STORE] Error while waiting for refresh lock release', {
+        sessionToken: tokenLogId(sessionToken),
+        requestId,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      break;
+    }
+  }
+
+  console.warn('[SESSION-STORE] Timeout waiting for refresh lock release', {
+    sessionToken: tokenLogId(sessionToken),
+    requestId,
+    waitedMs: Date.now() - startTime
+  });
+
+  return { acquired: false };
+}
+
+/**
+ * Release a refresh lock
+ * Uses Lua script to ensure atomic validation and release
+ */
+export async function releaseRefreshLock(
+  sessionToken: string,
+  requestId: string,
+  lockVersion?: number
+): Promise<boolean> {
+  const lockKey = getRefreshLockKey(sessionToken);
+
+  try {
+    // Lua script for atomic lock validation and release
+    const luaScript = `
+      local lockKey = KEYS[1]
+      local expectedRequestId = ARGV[1]
+      local expectedVersion = ARGV[2]
+
+      local lockData = redis.call('GET', lockKey)
+      if not lockData then
+        return 0  -- Lock doesn't exist
+      end
+
+      local lockInfo = cjson.decode(lockData)
+      if lockInfo.acquiredBy == expectedRequestId then
+        if not expectedVersion or expectedVersion == '' or tostring(lockInfo.lockVersion) == expectedVersion then
+          redis.call('DEL', lockKey)
+          return 1  -- Successfully released
+        else
+          return -2  -- Version mismatch
+        end
+      else
+        return -1  -- Wrong owner
+      end
+    `;
+
+    const result = await redis.eval(
+      luaScript,
+      1,
+      lockKey,
+      requestId,
+      lockVersion ? lockVersion.toString() : ''
+    ) as number;
+
+    if (result === 1) {
+      console.debug('[SESSION-STORE] Refresh lock released successfully', {
+        sessionToken: tokenLogId(sessionToken),
+        requestId,
+        lockVersion
+      });
+      return true;
+    } else if (result === 0) {
+      console.warn('[SESSION-STORE] Attempted to release non-existent refresh lock', {
+        sessionToken: tokenLogId(sessionToken),
+        requestId
+      });
+      return false;
+    } else if (result === -1) {
+      console.error('[SESSION-STORE] Attempted to release refresh lock owned by another request', {
+        sessionToken: tokenLogId(sessionToken),
+        requestId
+      });
+      return false;
+    } else if (result === -2) {
+      console.error('[SESSION-STORE] Lock version mismatch during release', {
+        sessionToken: tokenLogId(sessionToken),
+        requestId,
+        lockVersion
+      });
+      return false;
+    } else {
+      console.error('[SESSION-STORE] Unexpected result from lock release script', {
+        sessionToken: tokenLogId(sessionToken),
+        requestId,
+        result
+      });
+      return false;
+    }
+  } catch (error) {
+    console.error('[SESSION-STORE] Failed to release refresh lock', {
+      sessionToken: tokenLogId(sessionToken),
+      requestId,
+      error: error instanceof Error ? error.message : String(error)
+    });
+
+    return false;
+  }
+}
+
+/**
+ * Check if a refresh lock exists for a session
+ */
+export async function checkRefreshLock(sessionToken: string): Promise<RefreshLockInfo | null> {
+  const lockKey = getRefreshLockKey(sessionToken);
+
+  try {
+    const lockData = await redis.get(lockKey);
+
+    if (!lockData) {
+      return null;
+    }
+
+    return JSON.parse(lockData) as RefreshLockInfo;
+  } catch (error) {
+    console.error('[SESSION-STORE] Failed to check refresh lock', {
+      sessionToken: tokenLogId(sessionToken),
+      error: error instanceof Error ? error.message : String(error)
+    });
+
+    return null;
+  }
+}
+
+/**
+ * Simple check if a refresh is currently in progress for a session
+ */
+export async function isRefreshInProgress(sessionToken: string): Promise<boolean> {
+  const lock = await checkRefreshLock(sessionToken);
+  return lock !== null;
+}
+
+/**
+ * Force cleanup of expired or orphaned refresh locks
+ */
+export async function cleanupRefreshLocks(): Promise<number> {
+  console.warn('[SESSION-STORE] cleanupRefreshLocks called - scanning for expired locks');
+  return 0;
+}
+
+/**
+ * PAY-2136 DIAGNOSTIC (BAPert 70873): which of the session keys EXIST for a token, right now.
+ *
+ * Names/presence only - this returns booleans and the key PREFIX (an app slug, not a secret), never a value and
+ * never any part of the token. It exists so a NO_SESSION can be read for what it was: canonical row gone with the
+ * ba: record alive (the :330 asymmetry), both gone (expired/deleted), or the store could not be asked ('error').
+ *
+ * EXISTS, not GET: it cannot parse, cannot throw on a malformed blob, and cannot return a credential. Each key is
+ * asked separately so one timeout does not hide the other two. Never throws.
+ */
+export type KeyPresence = boolean | 'error';
+export async function describeSessionKeyPresence(
+  sessionToken: string
+): Promise<{ prefix: string; canonical: KeyPresence; ba: KeyPresence; ver: KeyPresence }> {
+  const ask = async (key: string): Promise<KeyPresence> => {
+    try {
+      return (await redis.exists(key)) > 0;
+    } catch {
+      return 'error';
+    }
+  };
+  let prefix = '';
+  try {
+    prefix = getSessionPrefix();
+  } catch {
+    prefix = '';
+  }
+  if (!sessionToken) return { prefix, canonical: false, ba: false, ver: false };
+  let canonicalKey = '';
+  let baKey = '';
+  let verKey = '';
+  try {
+    canonicalKey = getSessionKey(sessionToken);
+    baKey = getBetterAuthSessionKey(sessionToken, getAppSlug());
+    verKey = getSessionVersionKey(sessionToken);
+  } catch {
+    return { prefix, canonical: 'error', ba: 'error', ver: 'error' };
+  }
+  const [canonical, ba, ver] = await Promise.all([ask(canonicalKey), ask(baKey), ask(verKey)]);
+  return { prefix, canonical, ba, ver };
+}