@payez/next-mvp 4.1.21 → 4.4.0

package/src/lib/idp-url-guard.ts

@@ -0,0 +1,37 @@
+/**
+ * Name the missing variable instead of letting undici say "Failed to parse URL".
+ *
+ * Every caller builds its target as `${ENV_CONFIG.IDP_URL}/api/...`. IDP_URL is a
+ * BARE PASSTHROUGH in src/config/env.ts - no fallback, no validation - so when it
+ * is missing the interpolation yields a url that is not absolute. BOTH spellings
+ * of "missing" are caught here, which is why this tests for an absolute url
+ * rather than for a leading slash:
+ *   IDP_URL=      (empty, as the quickstart now ships) -> "/api/Account/profile"
+ *   IDP_URL unset (absent from the env entirely)       -> "undefined/api/Account/profile"
+ * A leading-slash test would have caught only the first.
+ *
+ * This already fails CLOSED: undici rejects a relative url, so the guard changes
+ * no outcome - it only makes the existing failure self-describing. It does NOT
+ * silently retarget the app's own origin. (QAPert tested that hypothesis and
+ * reported it disproved, mail 48139.)
+ *
+ * WHY THIS IS A LEAF MODULE WITH NO IMPORTS, AND NOT A THROW IN env.ts:
+ *   - env.ts is the wrong home: ENV_CONFIG is imported by 26 modules and
+ *     re-exported from the package index, so a module-load throw would crash
+ *     consumers that only render components and never call the IDP. QAPert
+ *     proposed exactly that (48139); it is the one shape this cannot take.
+ *   - idp-fetch.ts is the wrong home for the SHARED copy: importing it pulls
+ *     server-only, the session store and the logger, so the three direct-fetch
+ *     callers would drag that whole chain in for one regex - and the predicate
+ *     could not be unit-tested without a live server environment.
+ * Keep this file dependency-free so both stay true.
+ */
+export function assertAbsoluteIdpUrl(targetUrl: string): void {
+  if (!/^https?:\/\//i.test(targetUrl)) {
+    throw new Error(
+      `IDP_URL is not set. Refusing to call the IDP with the non-absolute URL "${targetUrl}". ` +
+      `Set IDP_URL in your environment (dev: http://10.0.0.93:32785). ` +
+      `Never set it to a production host in a development worktree.`
+    );
+  }
+}

package/src/lib/redis.ts

@@ -3,16 +3,94 @@ import Redis, { RedisOptions } from 'ioredis';
 
 let client: Redis | null = null;
 
+// ── 183496: fail FAST and NAMED, never a 20s spinner ───────────────────────
+// The DEFAULTS were the defect (Nextpert-Scout's killable-proxy measurement,
+// BAPert 22626): no commandTimeout, so a command against a cut Redis path
+// hung 20s+, and maxRetriesPerRequest defaults to 20, so every command was
+// retried through every reconnect attempt. In the room that reads as "the
+// app hung", not "Redis blipped" - and self-heal was instant all along, so
+// the failure MODE was the whole defect.
+//
+// commandTimeout covers OFFLINE-QUEUED commands too (ioredis 5.8.2 Redis.js:
+// command.setTimeout runs BEFORE the queue/writable check), which makes it
+// the bounded offline queue the card asks for: no command, queued or sent,
+// outlives 3s. The queue itself stays ENABLED - a transient blip still
+// self-heals inside the window; only the failure mode changes. The throw
+// lands in with-auth's catch and comes out a fast 5xx, not a spinner.
+const REDIS_OPTIONS: RedisOptions = {
+  commandTimeout: 3000,
+  maxRetriesPerRequest: 1,
+};
+
 function createClient(): Redis {
   const url = process.env.REDIS_URL;
 
-  if (url && url.trim() !== '') {
-    // Use a standard configuration for better Docker compatibility
-    return new Redis(url);
+  // ── THE COMMENT THAT USED TO BE HERE WAS FALSE (Nextpert-Scout 35159). ──
+  //
+  // It said: "No REDIS_URL set, create a client that will fail fast."
+  // IT DOES NOT FAIL. Measured, not read:
+  //
+  //     new Redis({ commandTimeout, maxRetriesPerRequest, lazyConnect: true })
+  //       -> options.host === 'localhost',  options.port === 6379
+  //     (ioredis DEFAULT_REDIS_OPTIONS: port 6379, host "localhost")
+  //
+  // `lazyConnect` only DEFERS the connection to the first command; it does not
+  // prevent one. So with REDIS_URL absent this client silently targets
+  // localhost:6379. Whether that is a loud failure or a SILENT CONNECTION TO
+  // THE WRONG STORE depends entirely on what happens to be listening on the
+  // local loopback - which is not a property this module controls, and is
+  // exactly the kind of thing that differs between a container and a dev box.
+  //
+  // This mattered operationally: I told the team that deleting REDIS_URL from a
+  // configmap would be fail-closed, and recommended it as a hardening step for
+  // the 249808 remediation. That advice was wrong and rested on this comment.
+  // A loopback-exempt firewall rule also does not stop a client that has
+  // fallen back to loopback.
+  //
+  // Corrected rather than deleted, because the comment's INTENT was right and
+  // is worth preserving as a stated goal: an absent REDIS_URL SHOULD fail
+  // loudly. Making it actually do so means changing behaviour at module load
+  // (`const redis = getRedis()` at the bottom of this file runs on import), so
+  // it is carded rather than changed at speed - throwing on import would break
+  // every consumer that imports this module without needing Redis.
+  //
+  // What IS done here: the misconfiguration is now ANNOUNCED, so it can never
+  // again be silent even though it is not yet fatal.
+  if (!url || url.trim() === '') {
+    console.error(
+      '[redis] MISCONFIGURED: REDIS_URL is unset or empty. ' +
+      'This client will fall back to ioredis defaults (localhost:6379) and may ' +
+      'connect to whatever is listening there, or fail on first command. ' +
+      'It does NOT fail fast. Set REDIS_URL explicitly.',
+    );
   }
 
-  // No REDIS_URL set, create a client that will fail fast.
-  return new Redis({ lazyConnect: true });
+  const instance = url && url.trim() !== ''
+    // Use a standard configuration for better Docker compatibility
+    ? new Redis(url, REDIS_OPTIONS)
+    // NOTE: this does NOT fail fast - see the block above. It targets
+    // localhost:6379 by ioredis default.
+    : new Redis({ ...REDIS_OPTIONS, lazyConnect: true });
+
+  // Loud AND load-bearing: an ioredis 'error' event with NO listener is an
+  // unhandled EventEmitter error, which can take the whole PROCESS down -
+  // a Redis blip becoming a dead server is worse than the spinner was.
+  instance.on('error', (err) => {
+    console.error(`[redis] PATH FAILURE ${new Date().toISOString()}: ${err instanceof Error ? err.message : String(err)}`);
+  });
+
+  // 185121 line 3: the 16:05 event left no named trigger because ONLY 'error'
+  // was listened for. A reconnect or a clean end is silent in the artifact,
+  // so a session-death window could not be correlated with a redis event.
+  // One line per event; a recurrence now says whether redis moved at all.
+  instance.on('reconnecting', (delayMs: number) => {
+    console.warn(`[redis] RECONNECTING ${new Date().toISOString()}: next attempt in ${delayMs}ms`);
+  });
+  instance.on('end', () => {
+    console.error(`[redis] CONNECTION ENDED ${new Date().toISOString()}: no further reconnects — every session read now fails or misses`);
+  });
+
+  return instance;
 }
 
 export function getRedis(): Redis {
@@ -24,4 +102,4 @@ export function getRedis(): Redis {
 
 const redis = getRedis();
 export { redis };
-export default redis;
+export default redis;

package/src/lib/session-cookie-shape.ts

@@ -0,0 +1,184 @@
+import {
+  getJwtCookieName,
+  getSecureSessionCookieName,
+  getSessionCookieName,
+} from './app-slug';
+
+/**
+ * Session-cookie SHAPE detection — shared by every fallback path that must
+ * recover a Redis session token from a raw session-cookie value without
+ * going through Better Auth's `auth.api.getSession()`.
+ *
+ * WHY THIS EXISTS (183047 post-mortem, BAPert/QAPert/Scout, 2026-08-08):
+ *
+ * Two cookie shapes exist in this codebase's history, and until now no
+ * fallback path recognized both:
+ *
+ *  - JWS (3 dot-separated segments): the legacy NextAuth-era format. The
+ *    session token lives in the payload's `sessionToken` claim, base64-JSON
+ *    encoded in the middle segment.
+ *  - BA-hmac (2 segments — exactly ONE dot): Better Auth's own hand-rolled
+ *    cookie, `{token}.{base64(hmac)}` (see better-auth.ts's
+ *    CreateBetterAuthInstanceOptions.plugins doc comment). The token here
+ *    IS the first segment verbatim — there is no claim to decode.
+ *
+ * Every fallback that existed before this file assumed the JWS shape
+ * unconditionally:
+ *  - decode-session.ts's legacy path called jose's `jwtVerify()` directly on
+ *    the cookie value. `jwtVerify` requires a genuine compact JWS and throws
+ *    "Invalid Compact JWS" on a 2-segment value — secret-independent, before
+ *    any signature is even checked.
+ *  - auth.ts's `decodeJwtBody()` required `parts.length === 3` and returned
+ *    null otherwise.
+ *
+ * Since Better Auth is the only session minter in production, EVERY
+ * BA-shaped cookie hit both fallbacks' shape gate and failed structurally.
+ * That meant any single BA-primary miss (secondary-storage eviction,
+ * in-flight secret divergence, cookie-cache disabled) had no working
+ * fallback at all — a single cookie's failure read as total session death
+ * instead of degrading to one clean Redis-canonical lookup (or a genuine
+ * 401 if the record really is gone).
+ *
+ * No signature is verified for the BA-hmac shape here — same posture the
+ * pre-existing JWS fallback already took (see auth.ts's `getSession` Path B
+ * comment): Redis is the liveness authority downstream, so a forged token
+ * still has to land on a live session record to do anything. This function
+ * only recovers the CANDIDATE token; callers must still look it up.
+ */
+
+export type SessionCookieShape = 'jws' | 'ba-hmac';
+
+export interface ExtractedSessionToken {
+  token: string;
+  shape: SessionCookieShape;
+}
+
+/**
+ * Extract a candidate session token from a raw session-cookie value,
+ * regardless of which minter produced it.
+ *
+ * Returns null if the value doesn't match either known shape, or (for the
+ * JWS shape) if the payload segment doesn't decode to a `sessionToken`
+ * claim.
+ */
+export function extractSessionTokenFromCookieValue(rawValue: string | null | undefined): ExtractedSessionToken | null {
+  if (!rawValue) return null;
+
+  const segments = rawValue.split('.');
+
+  if (segments.length === 3) {
+    // JWS shape: base64-decode the payload segment (part 1), read the
+    // sessionToken claim. No signature check — see file header.
+    try {
+      const decoded = Buffer.from(segments[1], 'base64').toString('utf-8');
+      const payload = JSON.parse(decoded);
+      if (payload && typeof payload === 'object' && typeof payload.sessionToken === 'string') {
+        return { token: payload.sessionToken, shape: 'jws' };
+      }
+    } catch {
+      // fall through to null
+    }
+    return null;
+  }
+
+  if (segments.length === 2 && segments[0] && segments[1]) {
+    // BA-hmac shape: `{token}.{base64(hmac)}` — the token is the first
+    // segment verbatim, no decoding required.
+    return { token: segments[0], shape: 'ba-hmac' };
+  }
+
+  return null;
+}
+
+/** Extract the session token from the Better Auth session cookie WITHOUT
+ *  going through Better Auth's `auth.api.getSession()`. Handles both
+ *  single-cookie and chunked-cookie cases (Better Auth chunks long values
+ *  across `{name}.0`, `{name}.1`, …), and BOTH cookie shapes the codebase
+ *  has minted — JWS (legacy NextAuth) and BA-hmac (current Better Auth,
+ *  `{token}.{hmac}`) — via `extractSessionTokenFromCookieValue` (183047:
+ *  the shape-blind version of this function is what turned a single
+ *  BA-primary miss into total, secret-independent fallback failure for
+ *  every current cookie, since Better Auth never mints the JWS shape this
+ *  used to require). No signature check — Redis is the liveness gate, so
+ *  an attacker forging a token still has to land on a real Redis session
+ *  (infeasible against high-entropy UUIDs). Returns null if no cookie is
+ *  present or neither known shape matches. */
+export function extractSessionTokenFromCookie(request: Request): string | null {
+  const cookieHeader = request.headers.get('cookie');
+  if (!cookieHeader) return null;
+
+  // 240654: read EVERY name this session cookie is minted under, not just the
+  // bare one.
+  //
+  // getSessionCookieName() is ALWAYS `{slug}.session-token`. But the package's
+  // own read contract is getJwtCookieName() — "the cookie name that getToken()
+  // should use to READ" — and in production that resolves to the
+  // `__Secure-`-prefixed name. The admin-login door (238225) mints the legacy
+  // JWS session under the __Secure- name in prod, exactly per that contract.
+  //
+  // So this resolver — the Path-B fallback, and the ONLY resolver for legacy
+  // JWS sessions — could not see a production session at all. Measured live on
+  // portal.keelauth.com: the session was minted and present in Redis at
+  // `idp_admin_ui_graft:sess:{token}`, yet invisible to viability and
+  // middleware, so every page bounced to /sign-in. Dev survived because in
+  // development both helpers return the SAME string, which is precisely why
+  // the dev-93 walks passed while prod died.
+  //
+  // Checking BOTH names rather than just swapping to getJwtCookieName(): the
+  // graft currently double-writes both cookie names as an app-local mitigation
+  // (graft 8a5ac21), and a rollout necessarily spans sessions minted under
+  // either name. Reading both is correct before, during and after that
+  // double-write is retired, and costs one extra map lookup.
+  const candidateNames = Array.from(
+    new Set([getJwtCookieName(), getSecureSessionCookieName(), getSessionCookieName()]),
+  );
+
+  // Parse the header ONCE, then resolve per candidate. Chunked cookies are
+  // kept per-name: Better Auth splits long values across `{name}.0/.1/.2…`,
+  // and chunks from different cookie names must never be concatenated.
+  const direct = new Map<string, string>();
+  const chunksByName = new Map<string, Array<{ idx: number; value: string }>>();
+
+  for (const part of cookieHeader.split(';')) {
+    const trimmed = part.trim();
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+    const k = trimmed.slice(0, eq);
+    const v = trimmed.slice(eq + 1);
+
+    for (const name of candidateNames) {
+      if (k === name) {
+        if (!direct.has(name)) direct.set(name, decodeURIComponent(v));
+        break;
+      }
+      if (k.startsWith(`${name}.`)) {
+        const idx = parseInt(k.split('.').pop() || '0', 10);
+        if (Number.isFinite(idx)) {
+          const list = chunksByName.get(name) ?? [];
+          list.push({ idx, value: decodeURIComponent(v) });
+          chunksByName.set(name, list);
+        }
+        break;
+      }
+    }
+  }
+
+  let rawJwt: string | null = null;
+  for (const name of candidateNames) {
+    const whole = direct.get(name);
+    if (whole) {
+      rawJwt = whole;
+      break;
+    }
+    const parts = chunksByName.get(name);
+    if (parts && parts.length > 0) {
+      parts.sort((a, b) => a.idx - b.idx);
+      rawJwt = parts.map(c => c.value).join('');
+      break;
+    }
+  }
+
+  if (!rawJwt) return null;
+
+  return extractSessionTokenFromCookieValue(rawJwt)?.token ?? null;
+}

package/src/lib/session-store.ts

@@ -11,8 +11,8 @@
 import redis from './redis';
 import { randomBytes } from 'crypto';
 import { SessionData } from '../models/SessionModel';
-import { getSessionPrefix, getRefreshLockPrefix } from './app-slug';
-import { extractKidFromToken } from '../auth/utils/token-utils';
+import { getSessionPrefix, getRefreshLockPrefix, getAppSlug } from './app-slug';
+import { extractKidFromToken, decodeIdpAccessToken } from '../auth/utils/token-utils';
 
 // Re-export SessionData for consumers
 export type { SessionData } from '../models/SessionModel';
@@ -98,15 +98,37 @@ export async function getSession(sessionToken: string): Promise<SessionData | nu
  * Better Auth uses key format: ba:{appSlug}:{token}
  *
  * @param sessionToken The session token to look up.
- * @param appSlug The app slug (defaults to 'idealvibe_online' or extracted from env).
+ * @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;
   }
-  // Try to get appSlug from env if not provided
-  const slug = appSlug || process.env.CLIENT_ID || 'idealvibe_online';
+  // 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) {
@@ -125,6 +147,11 @@ export async function getBetterAuthSession(sessionToken: string, appSlug?: strin
         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 —
@@ -226,6 +253,31 @@ export async function deleteSession(sessionToken: string): Promise<void> {
   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.
@@ -292,6 +344,56 @@ export async function updateSession(
   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> = {};
+
+  // Claims are Unix SECONDS; SessionData stores milliseconds.
+  if (decoded.mfa_expires !== undefined && decoded.mfa_expires !== null) {
+    fields.mfaExpiresAt = Number(decoded.mfa_expires) * 1000;
+  }
+  if (decoded.mfa_time !== undefined && decoded.mfa_time !== null) {
+    fields.mfaCompletedAt = Number(decoded.mfa_time) * 1000;
+  }
+  if (decoded.mfa_validity_hours !== undefined && decoded.mfa_validity_hours !== null) {
+    fields.mfaValidityHours = Number(decoded.mfa_validity_hours);
+  }
+
+  return fields;
+}
+
 /**
  * Transitions a session to a MFA-completed state.
  * @param sessionToken The session token to update.
@@ -344,6 +446,9 @@ export async function transitionTo2FASession(
     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.
+    ...mfaLifetimeFromAccessToken(newAccessToken),
   };
 
   const refreshExpires = tokens.idpRefreshTokenExpires || tokens.refreshTokenExpires;
@@ -356,6 +461,12 @@ export async function transitionTo2FASession(
     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),
+    // NOT a bug - but it IS the case the consumers currently fail OPEN on, so
+    // it needs to be visible in the log rather than inferred from its absence.
+    mfaExpiresAt: updates.mfaExpiresAt,
+    mfaExpiresAtISO: updates.mfaExpiresAt ? new Date(updates.mfaExpiresAt).toISOString() : undefined,
   });
 
   const result = await updateSession(sessionToken, updates);
@@ -394,12 +505,47 @@ export async function updateTokens(
 
 /**
  * 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): Promise<SessionData | null> {
+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.'
+    );
+  }
+
   return updateSession(sessionToken, {
     mfaVerified: true,
+    ...mfaLifetime,
   });
 }
 

package/src/lib/single-flight.ts

@@ -0,0 +1,64 @@
+/**
+ * Single-flight memoisation that does NOT memoise failure — card 244549.
+ *
+ * The bug this exists to prevent: caching an in-flight promise to de-duplicate
+ * concurrent callers is correct, but if the cached promise REJECTS and is never
+ * cleared, the rejection is memoised for the life of the process. Every later
+ * caller re-awaits the same settled rejection and re-throws the same stale
+ * error, long after the underlying dependency has recovered. Recovery becomes
+ * restart-only, and — because the error text is identical every time — it looks
+ * exactly like the dependency is still down.
+ *
+ * Measured instance: @payez/next-mvp getAuthInstance() memoised a failed IDP
+ * config load. Re-injecting correct config into three running rigs on
+ * 2026-08-23 did not heal them; the processes were replaying a cached
+ * rejection rather than retrying.
+ *
+ * Contract:
+ *  - concurrent callers during a successful load share ONE underlying call
+ *  - a rejection is re-thrown to every caller awaiting that attempt (failures
+ *    stay LOUD — this never converts an error into a silent retry)
+ *  - the NEXT call after a failure starts a fresh attempt
+ *  - a slow failure never clears a newer in-flight attempt
+ *
+ * Zero imports on purpose: this must be unit-testable without loading the
+ * server auth stack, which is why the bug it fixes went untested for so long.
+ */
+export interface SingleFlight<T> {
+  /** Run (or join) the in-flight attempt. Rejects if the attempt rejects. */
+  get(): Promise<T>;
+  /** Test/diagnostic seam: is an attempt currently cached? */
+  isPending(): boolean;
+  /** Drop any cached attempt. */
+  reset(): void;
+}
+
+export function createSingleFlight<T>(factory: () => Promise<T>): SingleFlight<T> {
+  let pending: Promise<T> | null = null;
+
+  return {
+    get(): Promise<T> {
+      if (pending) return pending;
+
+      const attempt = factory();
+
+      // Cleanup runs on a SIDE branch so the promise handed to callers is the
+      // original one and still rejects. The identity guard means only the
+      // attempt that actually failed clears itself: without it, a slow failure
+      // could evict a newer attempt a later caller had already installed, and
+      // that caller would be de-duplicated against a promise nobody owns.
+      attempt.catch(() => {
+        if (pending === attempt) pending = null;
+      });
+
+      pending = attempt;
+      return pending;
+    },
+    isPending(): boolean {
+      return pending !== null;
+    },
+    reset(): void {
+      pending = null;
+    },
+  };
+}

package/src/lib/token-lifecycle.ts

@@ -351,6 +351,10 @@ export async function ensureFreshToken(
              * `mfaVerified || ... || false`).
              */
             mfaVerified: idpTokens?.mfaVerified ?? false,
+            // R807 (362550): the fail-closed default above stays exactly as documented;
+            // this records whether it was a measurement or a default. `!== undefined`
+            // deliberately - an explicit `false` is a signal.
+            mfaSignalPresent: idpTokens?.mfaVerified !== undefined,
             oauthProvider: idpTokens?.oauthProvider ?? baSession.oauthProvider ?? undefined,
             idpClientId: idpTokens?.idpClientId ?? idpTokens?.clientId ?? baSession.idpClientId,
             merchantId: idpTokens?.merchantId ?? baSession.merchantId,
@@ -377,6 +381,14 @@ export async function ensureFreshToken(
          * UNSET is the only honest provider. Both are fail-closed.
          */
         mfaVerified: false,
+        /**
+         * R807 (362550) - FIFTH construction site, not in the ruling's list of four.
+         * This path has NO IDP TOKENS AT ALL, so there is no producer statement to
+         * record: the `false` above is a DEFAULT, never a measurement. `false` is
+         * therefore the honest signal value, and it is the conservative one for
+         * viability (absent/false -> do not force a re-challenge).
+         */
+        mfaSignalPresent: false,
         oauthProvider: undefined,
       } as SessionData;
     }

package/src/middleware/create-middleware.ts

@@ -292,6 +292,17 @@ function makeAuthDecision(ctx: AuthContext): AuthAction {
     if (sessionPointer.hasRefreshToken) {
       return { type: 'refresh_needed' };
     }
+    // 307290: this is the TERMINAL arm of the expired branch - refresh is not
+    // possible here, so the only outcomes are "redirect" or "allow". Every other
+    // terminal branch in this function (:242 no_session, :259 force_invalidated,
+    // :271 stale_session, :318 2FA-incomplete) already exempts /api/ so the route
+    // can answer with a real 401 JSON; this one did not, and redirecting an API
+    // request to an HTML login page makes the failure INVISIBLE - fetch() follows
+    // the 307, gets 200 HTML, resolves successfully and parses garbage.
+    // MUST stay BELOW the hasRefreshToken check above: placed any higher it would
+    // intercept 'refresh_needed' and disable middleware token refresh for the
+    // entire API surface.
+    if (pathname.startsWith('/api/')) return { type: 'allow' }; // Let API return proper 401 JSON
     return {
       type: 'redirect',
       location: `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=SessionExpired`,