@payez/next-mvp 4.1.20 → 4.4.0

package/dist/lib/idp-url-guard.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 declare function assertAbsoluteIdpUrl(targetUrl: string): void;

package/dist/lib/idp-url-guard.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertAbsoluteIdpUrl = assertAbsoluteIdpUrl;
+/**
+ * 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.
+ */
+function assertAbsoluteIdpUrl(targetUrl) {
+    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/dist/lib/redis.js

@@ -8,14 +8,86 @@ exports.getRedis = getRedis;
 // E:\Repos\PayEz-Next-MVP\packages\next-mvp\src\lib\redis.ts
 const ioredis_1 = __importDefault(require("ioredis"));
 let client = 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 = {
+    commandTimeout: 3000,
+    maxRetriesPerRequest: 1,
+};
 function createClient() {
     const url = process.env.REDIS_URL;
-    if (url && url.trim() !== '') {
-        // Use a standard configuration for better Docker compatibility
-        return new ioredis_1.default(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 ioredis_1.default({ lazyConnect: true });
+    const instance = url && url.trim() !== ''
+        // Use a standard configuration for better Docker compatibility
+        ? new ioredis_1.default(url, REDIS_OPTIONS)
+        // NOTE: this does NOT fail fast - see the block above. It targets
+        // localhost:6379 by ioredis default.
+        : new ioredis_1.default({ ...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) => {
+        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;
 }
 function getRedis() {
     if (!client) {

package/dist/lib/session-cookie-shape.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 declare function extractSessionTokenFromCookieValue(rawValue: string | null | undefined): ExtractedSessionToken | 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 declare function extractSessionTokenFromCookie(request: Request): string | null;

package/dist/lib/session-cookie-shape.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractSessionTokenFromCookieValue = extractSessionTokenFromCookieValue;
+exports.extractSessionTokenFromCookie = extractSessionTokenFromCookie;
+const app_slug_1 = require("./app-slug");
+/**
+ * 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.
+ */
+function extractSessionTokenFromCookieValue(rawValue) {
+    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. */
+function extractSessionTokenFromCookie(request) {
+    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([(0, app_slug_1.getJwtCookieName)(), (0, app_slug_1.getSecureSessionCookieName)(), (0, app_slug_1.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();
+    const chunksByName = new Map();
+    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 = 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/dist/lib/session-store.d.ts

@@ -40,7 +40,10 @@ export declare function getSession(sessionToken: string): Promise<SessionData |
  * 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 declare function getBetterAuthSession(sessionToken: string, appSlug?: string): Promise<SessionData | null>;
@@ -75,6 +78,21 @@ export declare function isAccessTokenFresh(sessionToken: string, currentAccessTo
  * @param sessionToken The session token to delete.
  */
 export declare function deleteSession(sessionToken: string): Promise<void>;
+/**
+ * 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 declare function deleteSessionEverywhere(sessionToken: string, appSlug?: string): Promise<void>;
 /**
  * Sets a session directly (for testing or migrations).
  * @param sessionToken The session token.
@@ -117,10 +135,25 @@ export declare function transitionTo2FASession(sessionToken: string, tokens: {
 export declare function updateTokens(sessionToken: string, idpAccessToken: string, idpRefreshToken: string, idpAccessTokenExpires: number, idpRefreshTokenExpires?: number): Promise<SessionData | null>;
 /**
  * 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 declare function mark2FAComplete(sessionToken: string): Promise<SessionData | null>;
+export declare function mark2FAComplete(sessionToken: string, accessToken?: string): Promise<SessionData | null>;
 /**
  * Checks if MFA is complete for a session.
  * @param sessionToken The session token.

package/dist/lib/session-store.js

@@ -21,6 +21,7 @@ exports.touchSession = touchSession;
 exports.getSessionWithVersion = getSessionWithVersion;
 exports.isAccessTokenFresh = isAccessTokenFresh;
 exports.deleteSession = deleteSession;
+exports.deleteSessionEverywhere = deleteSessionEverywhere;
 exports.setSession = setSession;
 exports.updateSession = updateSession;
 exports.transitionTo2FASession = transitionTo2FASession;
@@ -108,15 +109,37 @@ async function getSession(sessionToken) {
  * 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.
  */
 async function getBetterAuthSession(sessionToken, appSlug) {
     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 || (0, app_slug_1.getAppSlug)();
     const key = getBetterAuthSessionKey(sessionToken, slug);
     const json = await redis_1.default.get(key);
     if (!json) {
@@ -135,6 +158,11 @@ async function getBetterAuthSession(sessionToken, appSlug) {
                 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 —
@@ -216,6 +244,26 @@ async function deleteSession(sessionToken) {
     const versionKey = getSessionVersionKey(sessionToken);
     await redis_1.default.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.
+ */
+async function deleteSessionEverywhere(sessionToken, appSlug) {
+    if (!sessionToken) {
+        return;
+    }
+    await redis_1.default.del(getSessionKey(sessionToken), getSessionVersionKey(sessionToken), getBetterAuthSessionKey(sessionToken, appSlug || (0, app_slug_1.getAppSlug)()));
+}
 /**
  * Sets a session directly (for testing or migrations).
  * @param sessionToken The session token.
@@ -271,6 +319,53 @@ async function updateSession(sessionToken, updates) {
         .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) {
+    if (!accessToken)
+        return {};
+    const decoded = (0, token_utils_1.decodeIdpAccessToken)(accessToken);
+    if (!decoded)
+        return {};
+    const fields = {};
+    // 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.
@@ -306,6 +401,9 @@ async function transitionTo2FASession(sessionToken, tokens, mfaMethod) {
         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;
     if (refreshExpires !== undefined) {
@@ -316,6 +414,12 @@ async function transitionTo2FASession(sessionToken, tokens, mfaMethod) {
         twoFactorComplete: updates.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);
     console.log('[transitionTo2FASession] Result:', {
@@ -343,12 +447,39 @@ async function updateTokens(sessionToken, idpAccessToken, idpRefreshToken, idpAc
 }
 /**
  * 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.
  */
-async function mark2FAComplete(sessionToken) {
+async function mark2FAComplete(sessionToken, accessToken) {
+    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/dist/lib/single-flight.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 declare function createSingleFlight<T>(factory: () => Promise<T>): SingleFlight<T>;