@payez/next-mvp 4.4.5 → 4.4.7

package/src/auth/better-auth.ts

@@ -21,9 +21,11 @@ import { resolveClientKey } from '../lib/client-key';
 import { genericOAuth } from 'better-auth/plugins/generic-oauth';
 import type { IDPClientConfig } from '../lib/idp-client-config';
 import { getIDPClientConfig } from '../lib/idp-client-config';
-import { getAppSlug } from '../lib/app-slug';
+import { getAppSlug, assertAppSlugMatchesIdp } from '../lib/app-slug';
 import { getRedis } from '../lib/redis';
+import { createSingleFlight, type SingleFlight } from '../lib/single-flight';
 import { SESSION_TTL } from '../lib/session-store';
+import { tokenLogId } from '../lib/token-log-id';
 
 /**
  * 185121: short sha256 fingerprint for secrets/tokens in log lines — enough
@@ -518,6 +520,7 @@ export function createBetterAuthInstance(
   idpConfig: IDPClientConfig,
   opts: CreateBetterAuthInstanceOptions = {}
 ) {
+  assertAppSlugMatchesIdp(idpConfig.clientSlug);
   const appSlug = idpConfig.clientSlug || getAppSlug();
 
   // 185121 line 1: name the secret this instance PINNED, as a hash, never the
@@ -817,6 +820,19 @@ export function createBetterAuthInstance(
       },
     },
 
+    // PAY-1781 B: KEEP OAUTH STATE IN THE ENCRYPTED COOKIE, as it was on better-auth 1.5.6.
+    // 1.5.6 resolved the default as `options.database ? 'database' : 'cookie'` - we have no
+    // database, so: cookie. 1.6.13+ resolves it as `(database || secondaryStorage) ? 'database'
+    // : 'cookie'`, and we DO have secondaryStorage, so the upgrade alone would silently move every
+    // OAuth state record into Redis through the adapter above (its enrichment read-modify-write
+    // and key handling were built for session records, not state). Pinned so the upgrade changes
+    // the version, not the design. The cookie branch is where GHSA-wxw3-q3m9-c3jr lived; 1.6.2+
+    // compares the returned `state` with the nonce sealed in the cookie, and our provider is also
+    // pkce:true, which the advisory required to be false. Test: oauth-state-strategy-cookie.
+    account: {
+      storeStateStrategy: 'cookie',
+    },
+
     // Cookie prefix must match slim-middleware expectations ({slug}.session-token)
     advanced: {
       cookiePrefix: appSlug,
@@ -867,6 +883,9 @@ interface BetterAuthModuleState {
   cachedInstance: any;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   initPromise: Promise<any> | null;
+  // PAY-642: the init attempt, single-flighted so a REJECTED attempt clears itself (see getBetterAuthInstance).
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  initFlight?: SingleFlight<any>;
   configuredOpts: CreateBetterAuthInstanceOptions;
 }
 
@@ -902,19 +921,36 @@ export function configureBetterAuth(opts: CreateBetterAuthInstanceOptions): void
   state.configuredOpts = opts;
 }
 
+/**
+ * PAY-642 (card 338215): the init attempt no longer LATCHES A FAILURE.
+ *
+ * This used to be `state.initPromise ??= getIDPClientConfig(true).then(...)` with no .catch and no reset. One
+ * auth request against a cold process while the IdP was unreachable stored a rejected promise, and every later
+ * caller replayed it until the process restarted, even after the IdP recovered. This funnel backs every
+ * /api/auth/* route, the login GET handler and withAuth. server/auth.ts getAuthInstance() already used
+ * createSingleFlight for this exact bug; this sibling funnel was missed.
+ *
+ * Now the attempt runs through the same helper: concurrent callers share one attempt, a failure still rejects
+ * for every caller of THAT attempt (loud), the next call starts a fresh attempt, and a success is cached in
+ * state.cachedInstance as before. The flight lives on the globalThis state for the same reason the instance
+ * does (duplicated route chunks must share one init).
+ */
 export async function getBetterAuthInstance() {
   if (state.cachedInstance) return state.cachedInstance;
 
-  if (!state.initPromise) {
-    state.initPromise = getIDPClientConfig(true).then(config => {
+  state.initFlight ??= createSingleFlight(() =>
+    getIDPClientConfig(true).then(config => {
       const instance = createBetterAuthInstance(config, state.configuredOpts);
       state.cachedInstance = instance;
       console.log('[BETTER_AUTH] Instance created for', config.clientSlug || config.clientId);
       return instance;
-    });
-  }
+    })
+  );
 
-  return state.initPromise;
+  const attempt = state.initFlight.get();
+  // Kept for callers that inspect it; it always points at the CURRENT attempt, never a settled failure.
+  state.initPromise = attempt;
+  return attempt;
 }
 
 /**
@@ -961,7 +997,7 @@ export async function exchangeOAuthForIdpTokens(
     // Read the BA session from Redis
     const baRaw = await getRedis().get(baKey).catch(() => null);
     if (!baRaw) {
-      console.warn('[BETTER_AUTH] exchangeOAuthForIdpTokens: session not found in Redis for token', sessionToken.substring(0, 10));
+      console.warn('[BETTER_AUTH] exchangeOAuthForIdpTokens: session not found in Redis for token', tokenLogId(sessionToken));
       return false;
     }
 
@@ -1038,7 +1074,9 @@ export async function exchangeOAuthForIdpTokens(
     });
 
     const oauthResText = await oauthRes.text();
-    console.log('[BETTER_AUTH] IDP oauth-callback response:', oauthRes.status, oauthResText.substring(0, 500));
+    // PAY-1427 (QAPert, PR 154 thread 326): this printed the first 500 chars of the oauth-callback TOKEN
+    // envelope on EVERY successful OAuth login (it runs before the !ok check). Status + length only.
+    console.log('[BETTER_AUTH] IDP oauth-callback response:', { status: oauthRes.status, bodyLength: oauthResText.length });
 
     if (!oauthRes.ok) {
       console.error('[BETTER_AUTH] IDP oauth-callback failed:', oauthRes.status);
@@ -1276,7 +1314,7 @@ export async function storeIdpTokensInSession(
       // conjured here would carry no Better Auth cookie, so it would be
       // unreachable by the browser and invisible to every other consumer —
       // failing as "silently signed out" rather than as an error.
-      console.warn('[BETTER_AUTH] storeIdpTokensInSession: no BA session for token', sessionToken.substring(0, 10));
+      console.warn('[BETTER_AUTH] storeIdpTokensInSession: no BA session for token', tokenLogId(sessionToken));
       return false;
     }
 
@@ -1306,12 +1344,79 @@ export async function storeIdpTokensInSession(
   }
 }
 
+/**
+ * The `?error=` code the login page receives when an OAuth sign-in is ABORTED because the IdP exchange did not
+ * store tokens (PAY-1733). Hosts map it to ONE neutral line; the card's words are "That sign-in didn't work.
+ * Try again or use another method." The cause stays in the server log, never on the page.
+ */
+export const OAUTH_SIGN_IN_FAILED_ERROR = 'OAUTH_SIGN_IN_FAILED';
+
+/**
+ * Re-emit each cookie the callback response SET as an immediate expiry, keeping the attributes that decide
+ * WHICH cookie the browser overwrites (Path, Domain, Secure, SameSite, HttpOnly - a `__Secure-` name is only
+ * accepted with Secure) and dropping Expires/Max-Age in favour of Max-Age=0.
+ */
+export function expireSetCookies(setCookies: readonly string[]): string[] {
+  const out: string[] = [];
+  for (const sc of setCookies) {
+    const [pair, ...attrs] = sc.split(';').map((s) => s.trim());
+    const eq = pair.indexOf('=');
+    const name = eq > 0 ? pair.slice(0, eq) : '';
+    if (!name) continue;
+    const kept = attrs.filter((a) => /^(path|domain|secure|samesite|httponly)\b/i.test(a));
+    out.push([`${name}=`, ...kept, 'Max-Age=0'].join('; '));
+  }
+  return out;
+}
+
+/**
+ * PAY-1733 (Jon, live on :4797): ABORT an OAuth sign-in whose IdP exchange did not store tokens.
+ *
+ * Before this, a failed exchange was a console.error and the user kept the Better Auth session the callback had
+ * just created: signed in, holding NO IdP tokens. The host then routed that session to 2FA, which painted the
+ * user's email and failed every call - a red "sign in again" screen about an account the app could no longer
+ * authenticate. The IdP's 401 was CORRECT (it fail-closes unverified assertions); keeping the session was the bug.
+ *
+ * So: no session without IdP tokens. The Better Auth session is destroyed (its own signOut, best effort, then the
+ * `ba:<slug>:<token>` record directly - that record is what makes it resolvable), every cookie the callback set is
+ * expired, and the user goes to the login page with OAUTH_SIGN_IN_FAILED. Relative Location, as for the state-error
+ * branch above (328439: an absolute URL built from request.url is a dead tab in a container).
+ */
+async function abortOAuthSignIn(
+  callbackResponse: Response,
+  sessionToken: string | null,
+  cookieHeader: string,
+  loginPath: string,
+): Promise<Response> {
+  const headers = new Headers();
+  if (sessionToken) {
+    try {
+      const auth = await getBetterAuthInstance();
+      const out = await auth?.api?.signOut?.({ headers: new Headers({ cookie: cookieHeader }), asResponse: true });
+      for (const sc of (out as Response | undefined)?.headers?.getSetCookie?.() ?? []) headers.append('set-cookie', sc);
+    } catch (err) {
+      console.warn('[BETTER_AUTH] abort: Better Auth signOut failed, deleting the record directly:', err instanceof Error ? err.message : String(err));
+    }
+    try {
+      const config = await getIDPClientConfig();
+      await getRedis().del(`ba:${config.clientSlug || getAppSlug()}:${sessionToken}`);
+    } catch (err) {
+      console.error('[BETTER_AUTH] abort: could not delete the Better Auth session record', tokenLogId(sessionToken), err instanceof Error ? err.message : String(err));
+    }
+  }
+  for (const sc of expireSetCookies(callbackResponse.headers.getSetCookie?.() ?? [])) headers.append('set-cookie', sc);
+  headers.set('location', `${loginPath}${loginPath.includes('?') ? '&' : '?'}error=${OAUTH_SIGN_IN_FAILED_ERROR}`);
+  console.warn('[BETTER_AUTH] OAuth sign-in ABORTED: the IdP exchange stored no tokens, so no session is kept (PAY-1733)', sessionToken ? tokenLogId(sessionToken) : '(no session)');
+  return new Response(null, { status: 302, headers });
+}
+
 /**
  * Create a production-ready GET handler for the auth catch-all route.
  *
  * Wraps better-auth's GET handler with:
  * - OAuth state error recovery (redirects to login instead of error page)
- * - IDP token exchange after successful OAuth callback
+ * - IDP token exchange after successful OAuth callback - and, when it stores no tokens, the sign-in is ABORTED
+ *   (session destroyed, cookies expired, login page with OAUTH_SIGN_IN_FAILED; PAY-1733)
  *
  * Usage in host app:
  * ```ts
@@ -1383,67 +1488,28 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
       }
     }
 
-    // After successful OAuth callback: exchange the PROVIDER identity for IDP tokens.
-    //
-    // ⚠ WAS "exchange Google identity" — and it meant it literally. This call
-    // site passed no provider, so it took exchangeOAuthForIdpTokens's
-    // `provider: string = 'google'` default and asserted "google" to
-    // /api/ExternalAuth/oauth-callback for EVERY provider. That was harmless
-    // while Google was the only one wired, and became wrong the moment a second
-    // provider shipped: a GitHub sign-in forwarded a GitHub access_token
-    // labelled `provider: 'google'`, so the IDP tried to verify it as a Google
-    // identity and fail-closed with 401 UNVERIFIED_ASSERTION in
-    // `response_time_ms: 0` — it never had to call anyone to know it was wrong.
-    //
-    // The diagnostics made this maximally confusing: `access_token_forwarded:
-    // true` is correct and the token really did arrive. The FIELD was fine; the
-    // LABEL on it was a lie. Nothing on the client half is broken.
-    //
-    // The provider was never unavailable — it is the path segment this very
-    // `if` matches on (/api/auth/callback/github). Derive it instead of
-    // defaulting, because a default here cannot be right for more than one
-    // provider at a time.
+    // After the OAuth callback: exchange the provider identity for IDP tokens. If that does NOT store tokens - the
+    // IdP refused (401), no session was found, or anything threw - the sign-in is ABORTED (PAY-1733). A session is
+    // kept only when it holds IdP tokens.
     const url = new URL(request.url);
     if (url.pathname.includes('/callback/') && response.status === 302) {
+      const setCookies = response.headers.getSetCookie?.() || [];
+      const cookieHeader = setCookies
+        .map((c: string) => c.split(';')[0])
+        .join('; ');
+      let sessionToken: string | null = null;
+      let exchanged = false;
       try {
         const auth = await getBetterAuthInstance();
         if (auth?.api?.getSession) {
-          const setCookies = response.headers.getSetCookie?.() || [];
-          const cookieHeader = setCookies
-            .map((c: string) => c.split(';')[0])
-            .join('; ');
-
           const headers = new Headers();
           headers.set('cookie', cookieHeader);
 
           const session = await auth.api.getSession({ headers });
           if (session?.session?.token) {
-            // /api/auth/callback/<provider>[?query] -> "<provider>"
-            const callbackProvider = url.pathname
-              .split('/callback/')[1]
-              ?.split('/')[0]
-              ?.split('?')[0]
-              ?.trim()
-              .toLowerCase() || '';
-
-            if (!callbackProvider) {
-              // Do NOT quietly fall back to 'google'. That silent default is the
-              // exact defect this block fixes, and re-introducing it here would
-              // reproduce it for whatever unparseable shape got us here.
-              console.error(
-                '[BETTER_AUTH] OAuth callback matched /callback/ but no provider could be derived from',
-                url.pathname,
-                '— refusing to assert a guessed provider to the IDP. No exchange performed.'
-              );
-            } else {
-              console.log(
-                '[BETTER_AUTH] Got session token from callback:',
-                session.session.token.substring(0, 10),
-                '| provider:', callbackProvider,
-                '| email:', session.user?.email
-              );
-              await exchangeOAuthForIdpTokens(session.session.token, callbackProvider);
-            }
+            sessionToken = session.session.token;
+            console.log('[BETTER_AUTH] Got session token from callback:', tokenLogId(session.session.token), '| email:', session.user?.email);
+            exchanged = await exchangeOAuthForIdpTokens(session.session.token);
           } else {
             console.warn('[BETTER_AUTH] Could not get session after OAuth callback');
           }
@@ -1451,6 +1517,7 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
       } catch (err: any) {
         console.error('[BETTER_AUTH] IDP token exchange failed:', err.message);
       }
+      if (!exchanged) return abortOAuthSignIn(response, sessionToken, cookieHeader, loginPath);
     }
 
     return response;

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

@@ -215,7 +215,8 @@ export async function idpRefreshToken(
 
     if (!response.ok) {
       const errorText = await response.text().catch(() => 'Unknown error');
-      console.error('[IDP_CLIENT] Token refresh failed:', response.status, errorText);
+      // PAY-1427: never the raw upstream body (the refresh.ts:528 twin PR 139 fixed). Status + length only.
+      console.error('[IDP_CLIENT] Token refresh failed:', { status: response.status, bodyLength: errorText.length });
       return {
         success: false,
         error: {

package/src/components/admin/DataBrowserTab.tsx

@@ -214,7 +214,10 @@ export function DataBrowserTab({
 
       if (!response.ok) {
         const errData = await response.json().catch(() => ({}));
-        throw new Error(errData.error?.message || 'Delete failed');
+        // PAY-1425: the handler returns a fixed message plus a correlationId (never upstream
+        // text). Surface the id so an admin can quote it to an operator.
+        const ref = errData.error?.correlationId ? ` (ref ${errData.error.correlationId})` : '';
+        throw new Error(`${errData.error?.message || 'Delete failed'}${ref}`);
       }
 
       setSuccess(`Record ${id} deleted`);

package/src/components/admin/SessionsTab.tsx

@@ -45,6 +45,13 @@ export interface SessionsTabProps {
 // COMPONENT
 // -----------------------------------------------------------------------------
 
+// PAY-1429: admin handlers return a fixed message plus a correlationId (never upstream or
+// exception text). Surface the id so an admin can quote it to an operator.
+function errorWithRef(data: any, fallback: string): string {
+  const msg = typeof data?.error === 'string' ? data.error : fallback;
+  return data?.correlationId ? `${msg} (ref ${data.correlationId})` : msg;
+}
+
 export function SessionsTab({ isDark = true, apiBasePath = '/api/admin/sessions' }: SessionsTabProps) {
   const [sessions, setSessions] = useState<LoginSession[]>([]);
   const [isLoading, setIsLoading] = useState(false);
@@ -80,7 +87,7 @@ export function SessionsTab({ isDark = true, apiBasePath = '/api/admin/sessions'
         setSessions(data.sessions || []);
         setLastRefresh(new Date());
       } else {
-        setError(data.error || 'Failed to fetch sessions');
+        setError(errorWithRef(data, 'Failed to fetch sessions'));
       }
     } catch (err) {
       setError('Network error. Please try again.');
@@ -132,7 +139,7 @@ export function SessionsTab({ isDark = true, apiBasePath = '/api/admin/sessions'
         await fetchSessions();
         await fetchStats();
       } else {
-        alert(data.error || 'Failed to revoke session');
+        alert(errorWithRef(data, 'Failed to revoke session'));
       }
     } catch (err) {
       alert('Network error. Please try again.');
@@ -162,7 +169,7 @@ export function SessionsTab({ isDark = true, apiBasePath = '/api/admin/sessions'
         await fetchSessions();
         await fetchStats();
       } else {
-        alert(data.error || 'Failed to revoke sessions');
+        alert(errorWithRef(data, 'Failed to revoke sessions'));
       }
     } catch (err) {
       alert('Network error. Please try again.');

package/src/components/recovery/RequestedStep.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import React from 'react';
+
+interface Props {
+  onGoToLogin: () => void;
+}
+
+/**
+ * PAY-1588 (rigpert 60711): what a caller sees when the recovery request produced NO recovery session - an unknown
+ * address, a locked account, a throttled caller. ONE sentence, identical for all of them, so the screen cannot be used
+ * to tell which. It must not claim a reset happened (that is CompleteStep, reached only after a successful reset) and it
+ * must not name a cause.
+ */
+export function RequestedStep({ onGoToLogin }: Props) {
+  return (
+    <div className="bg-white border border-gray-300 rounded p-8 text-center">
+      <h2 className="text-2xl font-semibold text-gray-900 mb-2">Check your email</h2>
+
+      <p className="text-gray-600 mb-6">If an account exists for that email, we've sent instructions to reset your password.</p>
+
+      <button
+        onClick={onGoToLogin}
+        className="w-full py-2 px-4 border border-gray-300 rounded text-gray-900 font-medium hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-gray-400"
+      >
+        Back to sign in
+      </button>
+    </div>
+  );
+}

package/src/components/recovery/SetPasswordStep.tsx

@@ -1,6 +1,8 @@
 'use client';
 
-import React, { useState } from 'react';
+import React, { useEffect, useState } from 'react';
+import { usePasswordValidation } from '../../hooks/usePasswordValidation';
+import { passwordRulesText } from '../../lib/password-rules';
 
 interface Props {
   onSubmit: (password: string, confirmPassword: string) => void;
@@ -15,6 +17,14 @@ export function SetPasswordStep({ onSubmit, loading }: Props) {
 
   const passwordsMatch = password === confirmPassword && password !== '';
 
+  // PAY-1591: ADVISORY only. It shows the rules and what is missing; it never disables submit, because the validator
+  // may be down and the IdP is the authority (a dead validator must not trap a user who already spent their code).
+  const { setPassword: validateAsYouType, policy, failedRequirements } = usePasswordValidation();
+  // The policy only comes back with a validation, so ask once on mount with a one-character probe (it never leaves the
+  // policy question; the answer is what the rules line is built from). Until it lands the line says the rules are coming.
+  useEffect(() => { validateAsYouType('a'); }, [validateAsYouType]);
+  const missing = failedRequirements.filter((r) => !/^(Unable to validate|Password validation)/i.test(r));
+
   const handleSubmit = (e: React.FormEvent) => {
     e.preventDefault();
     if (passwordsMatch) {
@@ -25,9 +35,12 @@ export function SetPasswordStep({ onSubmit, loading }: Props) {
   return (
     <div className="bg-white border border-gray-300 rounded p-8">
       <h2 className="text-xl font-semibold text-gray-900 mb-2">Set New Password</h2>
-      <p className="text-sm text-gray-600 mb-6">
+      <p className="text-sm text-gray-600 mb-2">
         Choose a strong password for your account.
       </p>
+      <p data-testid="password-rules" className="text-sm text-gray-700 mb-6">
+        {passwordRulesText(policy)}
+      </p>
 
       <form onSubmit={handleSubmit} className="space-y-4">
         <div>
@@ -39,7 +52,7 @@ export function SetPasswordStep({ onSubmit, loading }: Props) {
               type={showPassword ? 'text' : 'password'}
               id="password"
               value={password}
-              onChange={(e) => setPassword(e.target.value)}
+              onChange={(e) => { setPassword(e.target.value); validateAsYouType(e.target.value); }}
               required
               disabled={loading}
               className="w-full px-3 py-2 border border-gray-300 rounded focus:ring-2 focus:ring-gray-900 focus:outline-none disabled:opacity-50 disabled:bg-gray-50 pr-10"
@@ -78,6 +91,14 @@ export function SetPasswordStep({ onSubmit, loading }: Props) {
           </div>
         </div>
 
+        {password && missing.length > 0 && (
+          <ul data-testid="password-missing" className="text-sm text-gray-700 list-disc pl-5">
+            {missing.map((r) => (
+              <li key={r}>{r}</li>
+            ))}
+          </ul>
+        )}
+
         {!passwordsMatch && confirmPassword && (
           <div className="bg-red-50 border border-red-200 rounded p-3">
             <p className="text-red-700 text-sm">Passwords do not match</p>

package/src/config/env.ts

@@ -29,8 +29,6 @@ export const API_ENDPOINTS = {
     profile: '/api/account/profile',
     updateProfile: '/api/account/profile',
     maskedInfo: '/api/account/masked-info',
-    sendResetCode: '/api/account/send-reset-code',
-    verifyResetCode: '/api/account/verify-reset-code',
     resetPassword: '/api/account/reset-password',
     changePassword: '/api/account/change-password',
     validatePassword: '/api/account/validate-password'

package/src/hooks/useViabilitySession.ts

@@ -43,7 +43,8 @@ export interface ViabilityState {
 
 interface ViabilityResponse {
   authenticated: boolean;
-  sessionToken?: string;
+  /** PAY-1481: tokenLogId of the session token (correlation only); the token itself is never returned. */
+  sessionTokenId?: string | null;
   requires2FA?: boolean;
   twoFactorComplete?: boolean;
   accessTokenExpired?: boolean;

package/src/index.ts

@@ -23,6 +23,10 @@ export type { AuthConfig } from './types/auth';
 // Route configuration (client-safe)
 export { makeAuthDecision } from './auth/auth-decision';
 export { isUnauthenticatedRoute, configurePublicRoutes, getRouteConfig } from './auth/route-config';
+
+// The ONE callback-target guard (N7 / PAY-1989): apps import this instead of
+// copying it. Exposed from the main index AND as the subpath ./auth/safe-callback.
+export { safeCallbackPath, isSafeCallbackPath, resolveCallbackDestination, DEFAULT_CALLBACK } from './auth/safe-callback';
 export { createMvpMiddleware } from './middleware/create-middleware';
 
 // Account Components

package/src/lib/app-slug.ts

@@ -27,6 +27,56 @@ export function getAppSlug(): string {
   return cachedSlug;
 }
 
+/**
+ * The session cookie name has TWO producers: better-auth mints `${idpConfig.clientSlug || getAppSlug()}.session-token`, while
+ * the gate and every reader use getSessionCookieName() = getAppSlug() = APP_SLUG || CLIENT_ID. When the IdP's slug is known and
+ * differs, the gate looks for a cookie that was never set and every better-auth (Google) session bounces to
+ * /sign-in?error=SessionInvalid straight after a successful 2FA (rigpert 60743, live on :4797 with CLIENT_ID=idp-admin-ui-graft
+ * against clientSlug idp_admin_ui_graft). FAIL CLOSED: refuse rather than run with two names. No IdP slug -> nothing to compare.
+ */
+export function slugMismatchReason(idpClientSlug: string | null | undefined): string | null {
+  if (!idpClientSlug) return null;
+  const gateSlug = getAppSlug();
+  return idpClientSlug !== gateSlug ? `SLUG_MISMATCH: cookie=${idpClientSlug} gate=${gateSlug}` : null;
+}
+
+/**
+ * rigpert 60813: when the IdP returns NO client slug for this app (an unknown client: the config fetch failed or came back
+ * without one), startup must fail LOUD. Silently defaulting would run with a cookie name nobody verified against the IdP. The
+ * startup path swallows a failed config fetch when BETTER_AUTH_SECRET is supplied by env, so without this an unregistered
+ * CLIENT_ID (e.g. payez_idp_customer_web, absent on dev-93) would boot 'fine'.
+ */
+export function assertIdpSlugKnown(idpClientSlug: string | null | undefined): void {
+  if (idpClientSlug) return;
+  throw new Error(
+    `[FATAL] The IdP returned no client slug for this app (gate slug "${getAppSlug()}"). Either CLIENT_ID/APP_SLUG names a client ` +
+      `the IdP does not know, or its config could not be fetched. Refusing to start with an unverified session cookie name.`,
+  );
+}
+
+/**
+ * The health-endpoint view: a mismatch is always reportable; an UNKNOWN slug is reported only once startup has actually been
+ * attempted (before that nothing is known yet and health must not go red on a pod that has not started initialising).
+ */
+export function slugStateReason(idpClientSlug: string | null | undefined, startupAttempted: boolean): string | null {
+  const mismatch = slugMismatchReason(idpClientSlug);
+  if (mismatch) return mismatch;
+  if (startupAttempted && !idpClientSlug) return `SLUG_UNKNOWN: the IdP returned no client slug for this app gate=${getAppSlug()}`;
+  return null;
+}
+
+export function assertAppSlugMatchesIdp(idpClientSlug: string | null | undefined): void {
+  if (!idpClientSlug) return;
+  const gateSlug = getAppSlug();
+  if (slugMismatchReason(idpClientSlug) !== null) {
+    throw new Error(
+      `[FATAL] Session cookie name would have two sources: the IdP client slug is "${idpClientSlug}" but this app's slug ` +
+        `(APP_SLUG, else CLIENT_ID) is "${gateSlug}". better-auth would set "${idpClientSlug}.session-token" while the gate reads ` +
+        `"${gateSlug}.session-token", so every better-auth session would be rejected. Set APP_SLUG (or CLIENT_ID) to "${idpClientSlug}".`,
+    );
+  }
+}
+
 /**
  * Clears the cached slug (useful for testing).
  */