@payez/next-mvp 4.4.4 → 4.4.6

package/src/lib/password-rules.ts

@@ -0,0 +1,50 @@
+/**
+ * PAY-1591: the one sentence that states the password rules on the recovery set-password step.
+ *
+ * Built ONLY from the policy the IdP reported (usePasswordValidation.policy). A rule that is off is not stated, and with
+ * no policy at all we state no number: telling a user "at least 8 characters" when the client is configured for 12 is
+ * the same defect as saying nothing, one step later.
+ */
+export interface PasswordPolicyLike {
+  min_length?: number;
+  require_uppercase?: boolean;
+  require_lowercase?: boolean;
+  require_digit?: boolean;
+  require_special?: boolean;
+}
+
+export function passwordRulesText(policy: PasswordPolicyLike | undefined | null): string {
+  if (!policy || typeof policy.min_length !== 'number') {
+    return "Use a password that meets this site's rules. We'll show what is missing as you type.";
+  }
+  const parts = [`at least ${policy.min_length} characters`];
+  if (policy.require_uppercase) parts.push('an upper-case letter');
+  if (policy.require_lowercase) parts.push('a lower-case letter');
+  if (policy.require_digit) parts.push('a number');
+  if (policy.require_special) parts.push('a symbol');
+  const [first, ...rest] = parts;
+  return rest.length ? `Your password needs ${first}, with ${rest.join(', ')}.` : `Your password needs ${first}.`;
+}
+
+/**
+ * PAY-1591: the IdP's reset refusal names WHICH rules failed as codes (error.details.rules). This is the closed set the
+ * portal accepts and the one plain sentence for each. Anything outside it is dropped, never displayed or forwarded.
+ */
+export const PASSWORD_RULE_SENTENCES: Readonly<Record<string, string>> = {
+  min_length: 'Use a longer password.',
+  uppercase: 'Add an upper-case letter.',
+  lowercase: 'Add a lower-case letter.',
+  digit: 'Add a number.',
+  special: 'Add a symbol.',
+  unique_chars: 'Use more different characters.',
+  recent_password: "Choose a password you haven't used recently.",
+};
+
+export function knownPasswordRules(rules: unknown): string[] {
+  if (!Array.isArray(rules)) return [];
+  return rules.filter((r): r is string => typeof r === 'string' && Object.prototype.hasOwnProperty.call(PASSWORD_RULE_SENTENCES, r));
+}
+
+export function passwordRuleSentences(rules: string[]): string {
+  return rules.map((r) => PASSWORD_RULE_SENTENCES[r]).join(' ');
+}

package/src/lib/safe-error-response.ts

@@ -0,0 +1,126 @@
+/**
+ * PAY-1438: what a USER-FACING handler may put in an error response.
+ *
+ * Several of these routes are reachable before authentication (session check, viability probe,
+ * logout, auth status, refresh-viability), so whatever lands in the body reaches an anonymous caller.
+ *
+ * Class A - an EXCEPTION: its text (ioredis `connect ECONNREFUSED host:port`, undici `fetch failed`,
+ * JSON parse errors quoting payload bytes) stays server-side. The response carries a fixed message,
+ * a code and a correlationId; the log line carries the exception and the same id.
+ *
+ * Class B - an IDP ERROR ENVELOPE ({ success, message, error: { code, message, details, support } }):
+ * never passed through whole. Only the display contract is projected: code, message, resolution,
+ * request_id - each only when it is a string. `details` (free-form, may carry validation internals
+ * or exception data) is dropped, except for the password-policy messages change-password's UI reads.
+ */
+
+import { knownPasswordRules } from './password-rules';
+
+export interface IdpErrorProjection {
+  code?: string;
+  message?: string;
+  resolution?: string;
+  request_id?: string;
+}
+
+const str = (v: unknown): string | undefined => (typeof v === 'string' ? v : undefined);
+
+/** Log an exception with a fresh correlationId and return the id for the response body. */
+export function logExceptionWithCorrelation(tag: string, err: unknown): string {
+  const correlationId = globalThis.crypto.randomUUID();
+  console.error(tag, { correlationId, error: err });
+  return correlationId;
+}
+
+/** Whitelisted projection of an IDP error envelope: code / message / resolution / request_id only. */
+export function projectIdpError(json: unknown): IdpErrorProjection {
+  if (!json || typeof json !== 'object') return {};
+  const top = json as Record<string, unknown>;
+  const err = top.error && typeof top.error === 'object' ? (top.error as Record<string, unknown>) : {};
+  const support = err.support && typeof err.support === 'object' ? (err.support as Record<string, unknown>) : {};
+  const out: IdpErrorProjection = {};
+  const code = str(err.code) ?? str(top.code) ?? str(top.error_code);
+  const message = str(err.message) ?? str(top.message);
+  const resolution = str(err.resolution) ?? str(top.resolution);
+  const requestId = str(support.request_id) ?? str(top.request_id);
+  if (code !== undefined) out.code = code;
+  if (message !== undefined) out.message = message;
+  if (resolution !== undefined) out.resolution = resolution;
+  if (requestId !== undefined) out.request_id = requestId;
+  return out;
+}
+
+/**
+ * change-password's `details`: the security pages show `details.value[0].message` (else
+ * `details.message`) as the password-policy error (QAPert census on PAY-1438). Keep exactly those
+ * strings; drop everything else.
+ */
+export function projectPasswordPolicyDetails(details: unknown): { message?: string; value?: Array<{ message: string }> } | undefined {
+  if (!details || typeof details !== 'object') return undefined;
+  const d = details as Record<string, unknown>;
+  const out: { message?: string; value?: Array<{ message: string }> } = {};
+  if (Array.isArray(d.value)) {
+    const value = d.value
+      .map((v) => (v && typeof v === 'object' ? str((v as Record<string, unknown>).message) : undefined))
+      .filter((m): m is string => m !== undefined)
+      .map((message) => ({ message }));
+    if (value.length) out.value = value;
+  }
+  const message = str(d.message);
+  if (message !== undefined) out.message = message;
+  return out.value || out.message !== undefined ? out : undefined;
+}
+
+/**
+ * For proxies that used to pass the IDP response through WHOLE on every status (account recovery,
+ * reset-password, passkey sign-in - all anonymous): on a non-OK status, return the same envelope
+ * SHAPE callers already read (`message`, `error.code`, `error.message`) built only from the
+ * whitelisted projection. The success path keeps its passthrough.
+ */
+export function idpErrorEnvelope(json: unknown, fallbackMessage = 'Request failed'): {
+  success: false;
+  message: string;
+  error: { code?: string; message: string; resolution?: string };
+  request_id?: string;
+} {
+  const p = projectIdpError(json);
+  const message = p.message ?? fallbackMessage;
+  const error: { code?: string; message: string; resolution?: string } = { message };
+  if (p.code !== undefined) error.code = p.code;
+  if (p.resolution !== undefined) error.resolution = p.resolution;
+  const out: { success: false; message: string; error: typeof error; request_id?: string } = { success: false, message, error };
+  if (p.request_id !== undefined) out.request_id = p.request_id;
+  return out;
+}
+
+/**
+ * PAY-1591: the IdP refuses a reset password with error.details = { code: 'password_policy', rules: [codes], requirements:
+ * [English] }. This route is anonymous, so only the CODES cross, and only the known ones: never `requirements`, never an
+ * unknown string. Returns undefined when this is NOT a password-policy refusal, and [] when it is one but names no rule we know
+ * (the caller must be able to tell a refused password from a dead recovery session).
+ */
+/**
+ * True only when the IdP EXPLICITLY says the recovery token itself is unusable: details.code token_expired / token_used, or an
+ * ASP.NET Identity `InvalidToken` error in details.value (what the served IdP sends when ResetPasswordAsync refuses a used or
+ * expired token, AccountController.ResetPassword line ~699 at b5c56e6c0). Only this boolean crosses the anonymous route, never the
+ * Identity error text. Anything else is NOT a dead-link signal (rigpert 60822): an older IdP sends a weak-password refusal with
+ * no code at all, and calling that 'link expired' loops the user.
+ */
+export function projectResetTokenInvalid(json: unknown): boolean {
+  if (!json || typeof json !== 'object') return false;
+  const top = json as Record<string, unknown>;
+  const err = top.error && typeof top.error === 'object' ? (top.error as Record<string, unknown>) : {};
+  const details = (err.details && typeof err.details === 'object' ? err.details : top.details && typeof top.details === 'object' ? top.details : null) as Record<string, unknown> | null;
+  if (!details) return false;
+  if (details.code === 'token_expired' || details.code === 'token_used') return true;
+  return Array.isArray(details.value) && details.value.some((v) => !!v && typeof v === 'object' && (v as Record<string, unknown>).code === 'InvalidToken');
+}
+
+export function projectPasswordPolicyRules(json: unknown): string[] | undefined {
+  if (!json || typeof json !== 'object') return undefined;
+  const top = json as Record<string, unknown>;
+  const err = top.error && typeof top.error === 'object' ? (top.error as Record<string, unknown>) : {};
+  const details = (err.details && typeof err.details === 'object' ? err.details : top.details && typeof top.details === 'object' ? top.details : null) as Record<string, unknown> | null;
+  if (!details || details.code !== 'password_policy') return undefined;
+  return knownPasswordRules(details.rules);
+}

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

@@ -39,11 +39,16 @@ import {
  * 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.
+ * No signature is verified here, and none CAN be: this module is secret-free
+ * and synchronous. It only CLASSIFIES and recovers the candidate token.
+ *
+ * PAY-1476: the earlier claim that "Redis is the liveness authority, so a
+ * forged token still has to land on a live session record" was the defect.
+ * A LEAKED token lands on a live record by definition, so without a signature
+ * check the token string alone was a bearer credential. The candidate token
+ * returned here must NEVER be handed to the session store directly: go through
+ * server/verified-session-token.ts resolveVerifiedSessionToken, which verifies
+ * the HMAC (ba-hmac) or the JWS signature first.
  */
 
 export type SessionCookieShape = 'jws' | 'ba-hmac';
@@ -90,20 +95,18 @@ export function extractSessionTokenFromCookieValue(rawValue: string | null | und
   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 {
+/** The RAW session-cookie value from a Request, WITHOUT going through Better
+ *  Auth's `auth.api.getSession()`. Handles single and chunked cookies (Better
+ *  Auth chunks long values across `{name}.0`, `{name}.1`, …) and every name the
+ *  cookie is minted under (240654).
+ *
+ *  PAY-1476: this used to be `extractSessionTokenFromCookie`, which returned the
+ *  TOKEN with "No signature check — Redis is the liveness gate". That turned any
+ *  leaked token into a bearer credential. It now returns the raw value only, so
+ *  the one way to get a token out of a request cookie is
+ *  server/verified-session-token.ts resolveVerifiedSessionTokenFromRequest.
+ *  Returns null if no session cookie is present. */
+export function extractSessionCookieValue(request: Request): string | null {
   const cookieHeader = request.headers.get('cookie');
   if (!cookieHeader) return null;
 
@@ -178,7 +181,5 @@ export function extractSessionTokenFromCookie(request: Request): string | null {
     }
   }
 
-  if (!rawJwt) return null;
-
-  return extractSessionTokenFromCookieValue(rawJwt)?.token ?? null;
+  return rawJwt || null;
 }

package/src/lib/session-store.ts

@@ -13,6 +13,7 @@ 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';
@@ -293,11 +294,29 @@ export async function setSession(sessionToken: string, data: SessionData): Promi
     .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.
+ * @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,
@@ -309,6 +328,74 @@ export async function updateSession(
   // 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;
   }
 
@@ -322,10 +409,15 @@ export async function updateSession(
 
   if (hadRefreshToken && !willHaveRefreshToken) {
     console.error('[SESSION-STORE] ⚠️ REFRESH_TOKEN_BEING_CLEARED', {
-      sessionToken: sessionToken.substring(0, 8) + '...',
+      sessionToken: tokenLogId(sessionToken),
       userId: currentSession.userId,
       updateKeys: Object.keys(updates),
-      refreshTokenInUpdate: (updates as any).idpRefreshToken || (updates as any).refreshToken,
+      // 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
     });
@@ -380,15 +472,66 @@ function mfaLifetimeFromAccessToken(accessToken?: string): Partial<SessionData>
 
   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.
-  if (decoded.mfa_expires !== undefined && decoded.mfa_expires !== null) {
-    fields.mfaExpiresAt = Number(decoded.mfa_expires) * 1000;
+  const mfaExpires = claimToNumber(decoded.mfa_expires);
+  if (mfaExpires !== undefined) {
+    fields.mfaExpiresAt = mfaExpires * 1000;
   }
-  if (decoded.mfa_time !== undefined && decoded.mfa_time !== null) {
-    fields.mfaCompletedAt = Number(decoded.mfa_time) * 1000;
+  const mfaTime = claimToNumber(decoded.mfa_time);
+  if (mfaTime !== undefined) {
+    fields.mfaCompletedAt = mfaTime * 1000;
   }
-  if (decoded.mfa_validity_hours !== undefined && decoded.mfa_validity_hours !== null) {
-    fields.mfaValidityHours = Number(decoded.mfa_validity_hours);
+  const mfaValidityHours = claimToNumber(decoded.mfa_validity_hours);
+  if (mfaValidityHours !== undefined) {
+    fields.mfaValidityHours = mfaValidityHours;
   }
 
   return fields;
@@ -419,7 +562,7 @@ export async function transitionTo2FASession(
   const newAccessToken = tokens.idpAccessToken || tokens.accessToken;
 
   console.log('[transitionTo2FASession] Called with:', {
-    sessionToken: sessionToken?.substring(0, 8) + '...',
+    sessionToken: tokenLogId(sessionToken),
     mfaMethod,
     hasAccessToken: !!newAccessToken,
     hasRefreshToken: !!(tokens.idpRefreshToken || tokens.refreshToken),
@@ -483,7 +626,7 @@ export async function transitionTo2FASession(
         '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: sessionToken?.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         mfaMethod,
         hasAccessToken: !!newAccessToken,
       }
@@ -699,7 +842,7 @@ export async function acquireRefreshLock(
 
     if (result === 'OK') {
       console.debug('[SESSION-STORE] Refresh lock acquired', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         requestId,
         lockVersion
       });
@@ -709,7 +852,7 @@ export async function acquireRefreshLock(
       // Lock already exists, check if we should wait
       if (maxWaitMs > 0) {
         console.debug('[SESSION-STORE] Refresh lock already exists, waiting for release', {
-          sessionToken: sessionToken.substring(0, 8) + '...',
+          sessionToken: tokenLogId(sessionToken),
           requestId,
           maxWaitMs
         });
@@ -718,7 +861,7 @@ export async function acquireRefreshLock(
       }
 
       console.warn('[SESSION-STORE] Refresh lock already exists, not waiting', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         requestId
       });
 
@@ -726,7 +869,7 @@ export async function acquireRefreshLock(
     }
   } catch (error) {
     console.error('[SESSION-STORE] Failed to acquire refresh lock', {
-      sessionToken: sessionToken.substring(0, 8) + '...',
+      sessionToken: tokenLogId(sessionToken),
       requestId,
       error: error instanceof Error ? error.message : String(error)
     });
@@ -760,7 +903,7 @@ async function waitForRefreshLockRelease(
       await new Promise(resolve => setTimeout(resolve, pollInterval));
     } catch (error) {
       console.error('[SESSION-STORE] Error while waiting for refresh lock release', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         requestId,
         error: error instanceof Error ? error.message : String(error)
       });
@@ -769,7 +912,7 @@ async function waitForRefreshLockRelease(
   }
 
   console.warn('[SESSION-STORE] Timeout waiting for refresh lock release', {
-    sessionToken: sessionToken.substring(0, 8) + '...',
+    sessionToken: tokenLogId(sessionToken),
     requestId,
     waitedMs: Date.now() - startTime
   });
@@ -823,33 +966,33 @@ export async function releaseRefreshLock(
 
     if (result === 1) {
       console.debug('[SESSION-STORE] Refresh lock released successfully', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         requestId,
         lockVersion
       });
       return true;
     } else if (result === 0) {
       console.warn('[SESSION-STORE] Attempted to release non-existent refresh lock', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         requestId
       });
       return false;
     } else if (result === -1) {
       console.error('[SESSION-STORE] Attempted to release refresh lock owned by another request', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         requestId
       });
       return false;
     } else if (result === -2) {
       console.error('[SESSION-STORE] Lock version mismatch during release', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         requestId,
         lockVersion
       });
       return false;
     } else {
       console.error('[SESSION-STORE] Unexpected result from lock release script', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         requestId,
         result
       });
@@ -857,7 +1000,7 @@ export async function releaseRefreshLock(
     }
   } catch (error) {
     console.error('[SESSION-STORE] Failed to release refresh lock', {
-      sessionToken: sessionToken.substring(0, 8) + '...',
+      sessionToken: tokenLogId(sessionToken),
       requestId,
       error: error instanceof Error ? error.message : String(error)
     });
@@ -882,7 +1025,7 @@ export async function checkRefreshLock(sessionToken: string): Promise<RefreshLoc
     return JSON.parse(lockData) as RefreshLockInfo;
   } catch (error) {
     console.error('[SESSION-STORE] Failed to check refresh lock', {
-      sessionToken: sessionToken.substring(0, 8) + '...',
+      sessionToken: tokenLogId(sessionToken),
       error: error instanceof Error ? error.message : String(error)
     });
 

package/src/lib/startup-init.ts

@@ -12,6 +12,7 @@
 
 import 'server-only';
 import { getIDPClientConfig, clearConfigRedisCache, type IDPClientConfig } from './idp-client-config';
+import { slugStateReason } from './app-slug';
 
 let initializationStarted = false;
 let initializationComplete = false;
@@ -59,9 +60,21 @@ export async function ensureInitialized(): Promise<void> {
   // Mark as started
   initializationStarted = true;
 
-  // Start initialization
-  initializationPromise = performInitialization();
-  await initializationPromise;
+  // Start initialization.
+  //
+  // PAY-642: a FAILED attempt must not stay installed. This used to be
+  // `initializationPromise = performInitialization(); await initializationPromise;` with no reset, and the
+  // in-progress check above runs BEFORE the backoff check, so a pod that booted while the IdP was down replayed
+  // its first rejection to every caller forever: the 30 s backoff could never lead to a retry. Same latch, same
+  // fix, as createSingleFlight (lib/single-flight.ts): callers of the failing attempt still see the rejection
+  // (loud), then the attempt clears itself, identity-guarded so a slow failure never evicts a newer attempt.
+  // After a failure the backoff check above governs when the next attempt may start.
+  const attempt = performInitialization();
+  initializationPromise = attempt;
+  attempt.catch(() => {
+    if (initializationPromise === attempt) initializationPromise = null;
+  });
+  await attempt;
 }
 
 /**
@@ -168,8 +181,11 @@ async function performInitialization(): Promise<void> {
     // Step 3: Validate cookie name consistency
     // This catches bugs where getJwtCookieName() returns a different name than
     // what auth-options.ts configures, which causes sessions to fail in production
-    const { validateCookieNameConsistency, getSessionCookieName } = await import('./app-slug');
+    const { validateCookieNameConsistency, getSessionCookieName, assertAppSlugMatchesIdp, assertIdpSlugKnown } = await import('./app-slug');
     validateCookieNameConsistency();
+    // rigpert 60743: refuse to run with two cookie-name sources (IdP clientSlug vs APP_SLUG/CLIENT_ID).
+    assertIdpSlugKnown(cachedIDPConfig?.clientSlug);
+    assertAppSlugMatchesIdp(cachedIDPConfig?.clientSlug);
     console.log('[STARTUP] Cookie name consistency validated:', getSessionCookieName());
 
     // All done
@@ -225,6 +241,15 @@ ${connectionLine}║   Possible causes:
  * Get the cached IDP config after initialization.
  * Returns null if not yet initialized.
  */
+/**
+ * For health endpoints (rigpert 60765): a guard that does not stop the process is an empty red unless the mismatch is visible
+ * where operators and promote-fe look. Returns `SLUG_MISMATCH: cookie=<idp slug> gate=<app slug>` while the drift holds, else null;
+ * a health route should answer non-200 with this as the reason. Null until the IdP config has been fetched.
+ */
+export function getSlugMismatchReason(): string | null {
+  return slugStateReason(cachedIDPConfig?.clientSlug, initializationComplete || initializationFailed);
+}
+
 export function getStartupIDPConfig(): IDPClientConfig | null {
   return cachedIDPConfig;
 }

package/src/lib/token-lifecycle.ts

@@ -25,6 +25,7 @@ import { getSession as getRedisSession, SessionData } from './session-store';
 import { getSession as getBetterAuthSession } from '../server/auth';
 import { getRedis } from './redis';
 import { getAppSlug } from './app-slug';
+import { tokenLogId } from './token-log-id';
 
 // 5 minute threshold for "needs refresh" - matches refresh handler pattern
 const REFRESH_THRESHOLD_MS = 5 * 60 * 1000;
@@ -437,7 +438,7 @@ export async function ensureFreshToken(
     }
 
     console.log('[TOKEN_LIFECYCLE] ensureFreshToken check:', {
-      sessionToken: sessionToken.substring(0, 8) + '...',
+      sessionToken: tokenLogId(sessionToken),
       accessTokenExpires: tokenExpiresStr,
       now: new Date().toISOString(),
       needsRefresh: needsRefreshNow,