@payez/next-mvp 4.1.20 → 4.4.0

package/src/routes/mfa/totp-enroll.ts

@@ -1,10 +1,10 @@
-/**
- * Ready-to-Use TOTP Enrol Route
- *
- * @example
- * ```typescript
- * // app/api/mfa/totp/enroll/route.ts
- * export { POST } from '@payez/next-mvp/routes/mfa/totp-enroll';
- * ```
- */
-export { POST } from '../../api-handlers/mfa/totp-enroll';
+/**
+ * Ready-to-Use TOTP Enrol Route
+ *
+ * @example
+ * ```typescript
+ * // app/api/mfa/totp/enroll/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/totp-enroll';
+ * ```
+ */
+export { POST } from '../../api-handlers/mfa/totp-enroll';

package/src/routes/mfa/totp-verify.ts

@@ -1,14 +1,14 @@
-/**
- * Ready-to-Use TOTP Verify Route (2FA CHALLENGE, not enrolment)
- *
- * Verifies an authenticator code at LOGIN and transitions the session to
- * MFA-verified. Pair with totp-enroll/totp-confirm, which only ENROL a factor
- * and deliberately do not touch session 2FA state.
- *
- * @example
- * ```typescript
- * // app/api/mfa/totp/verify/route.ts
- * export { POST } from '@payez/next-mvp/routes/mfa/totp-verify';
- * ```
- */
-export { POST } from '../../api-handlers/mfa/totp-verify';
+/**
+ * Ready-to-Use TOTP Verify Route (2FA CHALLENGE, not enrolment)
+ *
+ * Verifies an authenticator code at LOGIN and transitions the session to
+ * MFA-verified. Pair with totp-enroll/totp-confirm, which only ENROL a factor
+ * and deliberately do not touch session 2FA state.
+ *
+ * @example
+ * ```typescript
+ * // app/api/mfa/totp/verify/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/totp-verify';
+ * ```
+ */
+export { POST } from '../../api-handlers/mfa/totp-verify';

package/src/routes/passkeys/list.ts

@@ -1,10 +1,10 @@
-/**
- * Ready-to-Use Passkey List Route
- *
- * @example
- * ```typescript
- * // app/api/passkeys/route.ts
- * export { GET } from '@payez/next-mvp/routes/passkeys/list';
- * ```
- */
-export { GET } from '../../api-handlers/passkeys/list';
+/**
+ * Ready-to-Use Passkey List Route
+ *
+ * @example
+ * ```typescript
+ * // app/api/passkeys/route.ts
+ * export { GET } from '@payez/next-mvp/routes/passkeys/list';
+ * ```
+ */
+export { GET } from '../../api-handlers/passkeys/list';

package/src/routes/passkeys/manage.ts

@@ -1,23 +1,23 @@
-/**
- * Ready-to-Use Passkey Manage Route (rename / revoke one key)
- *
- * @example
- * ```typescript
- * // app/api/passkeys/[id]/route.ts
- * export { PATCH, DELETE } from '@payez/next-mvp/routes/passkeys/manage';
- * ```
- */
-import { NextRequest } from 'next/server';
-import { PATCH as patchOne, DELETE as deleteOne } from '../../api-handlers/passkeys/manage';
-
-type Ctx = { params: Promise<{ id: string }> };
-
-export async function PATCH(req: NextRequest, ctx: Ctx) {
-  const { id } = await ctx.params;
-  return patchOne(req, id);
-}
-
-export async function DELETE(req: NextRequest, ctx: Ctx) {
-  const { id } = await ctx.params;
-  return deleteOne(req, id);
-}
+/**
+ * Ready-to-Use Passkey Manage Route (rename / revoke one key)
+ *
+ * @example
+ * ```typescript
+ * // app/api/passkeys/[id]/route.ts
+ * export { PATCH, DELETE } from '@payez/next-mvp/routes/passkeys/manage';
+ * ```
+ */
+import { NextRequest } from 'next/server';
+import { PATCH as patchOne, DELETE as deleteOne } from '../../api-handlers/passkeys/manage';
+
+type Ctx = { params: Promise<{ id: string }> };
+
+export async function PATCH(req: NextRequest, ctx: Ctx) {
+  const { id } = await ctx.params;
+  return patchOne(req, id);
+}
+
+export async function DELETE(req: NextRequest, ctx: Ctx) {
+  const { id } = await ctx.params;
+  return deleteOne(req, id);
+}

package/src/routes/passkeys/register-options.ts

@@ -1,10 +1,10 @@
-/**
- * Ready-to-Use Passkey Registration Options Route
- *
- * @example
- * ```typescript
- * // app/api/passkeys/register/options/route.ts
- * export { POST } from '@payez/next-mvp/routes/passkeys/register-options';
- * ```
- */
-export { POST } from '../../api-handlers/passkeys/register-options';
+/**
+ * Ready-to-Use Passkey Registration Options Route
+ *
+ * @example
+ * ```typescript
+ * // app/api/passkeys/register/options/route.ts
+ * export { POST } from '@payez/next-mvp/routes/passkeys/register-options';
+ * ```
+ */
+export { POST } from '../../api-handlers/passkeys/register-options';

package/src/routes/passkeys/register-verify.ts

@@ -1,10 +1,10 @@
-/**
- * Ready-to-Use Passkey Registration Verify Route
- *
- * @example
- * ```typescript
- * // app/api/passkeys/register/verify/route.ts
- * export { POST } from '@payez/next-mvp/routes/passkeys/register-verify';
- * ```
- */
-export { POST } from '../../api-handlers/passkeys/register-verify';
+/**
+ * Ready-to-Use Passkey Registration Verify Route
+ *
+ * @example
+ * ```typescript
+ * // app/api/passkeys/register/verify/route.ts
+ * export { POST } from '@payez/next-mvp/routes/passkeys/register-verify';
+ * ```
+ */
+export { POST } from '../../api-handlers/passkeys/register-verify';

package/src/server/auth-guard.ts

@@ -110,31 +110,38 @@ export async function authGuard(options?: AuthGuardOptions): Promise<AuthGuardRe
   }
 
   // --- 2FA check ---
+  // This try wraps ONLY the config fetch, because that is the only thing here
+  // that can genuinely fail. Do NOT widen it to cover the redirect below:
+  // next/navigation's redirect() signals by THROWING a NEXT_REDIRECT digest, so
+  // a redirect inside this try is caught by the catch and rewritten into a
+  // service-unavailable page - denying a 2FA user the one page that would let
+  // them satisfy the challenge, and reporting it as an outage. See card 312242.
+  let requires2FA: boolean;
   try {
     const config = await getIDPClientConfig();
-    const requires2FA = config.authSettings?.require2FA ?? true;
-
-    if (requires2FA) {
-      const mfaVerified = sessionData.mfaVerified ?? (sessionData as any).twoFactorComplete ?? false;
-      const mfaExpiresAt = sessionData.mfaExpiresAt || 0;
-      const mfaExpired = mfaExpiresAt > 0 && mfaExpiresAt < Date.now();
-
-      if (!mfaVerified || mfaExpired) {
-        console.log('[AUTH-GUARD] 2FA required', {
-          mfaVerified,
-          mfaExpired,
-          userId: sessionData.userId,
-          pathname,
-        });
-        redirect(`${verifyCodeUrl}?callbackUrl=${callbackUrl}`);
-      }
-    }
+    requires2FA = config.authSettings?.require2FA ?? true;
   } catch (error) {
     // If we can't check 2FA config, fail closed
     console.error('[AUTH-GUARD] 2FA config check failed:', error instanceof Error ? error.message : String(error));
     redirect(serviceUnavailableUrl);
   }
 
+  if (requires2FA) {
+    const mfaVerified = sessionData.mfaVerified ?? (sessionData as any).twoFactorComplete ?? false;
+    const mfaExpiresAt = sessionData.mfaExpiresAt || 0;
+    const mfaExpired = mfaExpiresAt > 0 && mfaExpiresAt < Date.now();
+
+    if (!mfaVerified || mfaExpired) {
+      console.log('[AUTH-GUARD] 2FA required', {
+        mfaVerified,
+        mfaExpired,
+        userId: sessionData.userId,
+        pathname,
+      });
+      redirect(`${verifyCodeUrl}?callbackUrl=${callbackUrl}`);
+    }
+  }
+
   // --- Custom checks (beta, admin, etc.) ---
   if (options?.checks) {
     for (const check of options.checks) {

package/src/server/auth.ts

@@ -6,21 +6,29 @@
  */
 
 import 'server-only';
-import { createBetterAuthInstance } from '../auth/better-auth';
+import { createBetterAuthInstance, secretFingerprint } from '../auth/better-auth';
 import { getIDPClientConfig } from '../lib/idp-client-config';
 import {
   getSession as getRedisSession,
   getBetterAuthSession as getBetterAuthRedisSession,
   type SessionData,
 } from '../lib/session-store';
-import { getSessionCookieName } from '../lib/app-slug';
+import { extractSessionTokenFromCookie } from '../lib/session-cookie-shape';
+import { createSingleFlight } from '../lib/single-flight';
 
 let authInstance: ReturnType<typeof createBetterAuthInstance> | null = null;
-let authInitPromise: Promise<ReturnType<typeof createBetterAuthInstance>> | null = null;
 
 export type IdpTokenResult =
   | { success: true; accessToken: string; sessionData: SessionData }
-  | { success: false; error: 'NO_SESSION' | 'NO_TOKEN'; terminal: true };
+  | { success: false; error: 'NO_SESSION'; terminal: true }
+  // Card 187871: a Better Auth session can exist with NO idpAccessToken yet
+  // because 2FA is required and not yet completed - the IDP never issued the
+  // full token. That is a RECOVERABLE state (route to 2FA), not a dead
+  // session. Only collapse it to NO_TOKEN/terminal when the session itself
+  // already claims 2FA is done (sessionData.mfaVerified === true) and there is
+  // still no token - that combination is genuinely broken.
+  | { success: false; error: 'NO_TOKEN'; terminal: true }
+  | { success: false; error: 'NO_TOKEN_PENDING_2FA'; terminal: false; sessionData: SessionData };
 
 function buildSessionDataFromAuthSession(session: any): SessionData | null {
   const user = session?.user;
@@ -83,81 +91,45 @@ function attachSessionData(session: any, sessionData: SessionData | null, sessio
 
 /**
  * Get the initialized Better Auth instance (singleton).
+ *
+ * 244549: the single-flight memoisation lives in lib/single-flight.ts rather
+ * than inline here, and that placement is deliberate rather than tidiness.
+ * The bug being fixed -- a REJECTED init promise cached for the life of the
+ * process, so recovery was restart-only -- went unnoticed precisely because
+ * this module cannot be loaded in a unit test: importing it pulls in
+ * better-auth and the whole IDP config stack. Extracted into a zero-import
+ * module, the retry semantics are covered by
+ * test/single-flight-retry.test.cjs, which imports dist/ and therefore
+ * exercises the artefact that actually ships.
+ *
+ * Semantics, all asserted by that suite: concurrent callers share ONE
+ * underlying init; a rejection reaches every caller awaiting that attempt
+ * (failures stay loud -- getIDPClientConfig is fail-loud by design and callers
+ * depend on it); the NEXT call after a failure starts a fresh attempt; and a
+ * slow failure never evicts a newer in-flight attempt.
  */
+const authInit = createSingleFlight(async () => {
+  const config = await getIDPClientConfig(true);
+  authInstance = createBetterAuthInstance(config);
+  // 185121 line 1, path 2: this module-scope instance had NO creation log
+  // line — first-called during a config transition window it pinned a
+  // divergent secret INVISIBLY. Name the path and the secret fingerprint
+  // (the createBetterAuthInstance line already logged the same hash;
+  // this line is what attributes it to THIS init path).
+  // Guard matches createBetterAuthInstance's: getIDPClientConfig currently
+  // throws FATAL on a missing authSecret (QAPert 27328 verified), but that
+  // guarantee is one refactor away — log ABSENT rather than ever throw here.
+  console.log(
+    `[AUTH] getAuthInstance: created BA instance via server/auth.ts — authSecret ${config.authSecret ? `sha256:${secretFingerprint(config.authSecret as string)}` : 'ABSENT'}`
+  );
+  return authInstance;
+});
+
 export async function getAuthInstance() {
   if (authInstance) return authInstance;
-  if (!authInitPromise) {
-    authInitPromise = getIDPClientConfig(true).then(config => {
-      authInstance = createBetterAuthInstance(config);
-      return authInstance;
-    });
-  }
-  return authInitPromise;
-}
-
-/**
- * JWT body-decode helper — base64-decode only, NO signature verification.
- * Safe because the value is then used as a Redis lookup key: Redis is the
- * liveness gate, so an attacker forging a JWT body with a guessed
- * sessionToken claim still has to land on a real Redis session (infeasible
- * against high-entropy UUIDs). Used by the canonical-fallback path in
- * `getSession` to extract the session token when Better Auth's primary
- * path returns null (cookie cache miss / secondary storage eviction).
- */
-function decodeJwtBody(jwt: string): any {
-  try {
-    const parts = jwt.split('.');
-    if (parts.length !== 3) return null;
-    const decoded = Buffer.from(parts[1], 'base64').toString('utf-8');
-    return JSON.parse(decoded);
-  } catch {
-    return null;
-  }
+  return authInit.get();
 }
 
-/** Extract the session-token claim 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
- *  JWTs across `{name}.0`, `{name}.1`, …). Returns the raw `sessionToken`
- *  claim suitable for use as a Redis key. Returns null if no cookie is
- *  present or the JWT can't be parsed. */
-function extractSessionTokenFromCookie(request: Request): string | null {
-  const cookieHeader = request.headers.get('cookie');
-  if (!cookieHeader) return null;
-
-  const cookieName = getSessionCookieName();
-  let rawJwt: string | null = null;
-
-  // Direct cookie first.
-  const chunks: Array<{ idx: number; value: string }> = [];
-  for (const part of cookieHeader.split(';')) {
-    const trimmed = part.trim();
-    const eq = trimmed.indexOf('=');
-    if (eq === -1) continue;
-    const k = trimmed.slice(0, eq);
-    const v = trimmed.slice(eq + 1);
-    if (k === cookieName) {
-      rawJwt = decodeURIComponent(v);
-      break;
-    }
-    if (k.startsWith(`${cookieName}.`)) {
-      const idx = parseInt(k.split('.').pop() || '0', 10);
-      if (Number.isFinite(idx)) chunks.push({ idx, value: decodeURIComponent(v) });
-    }
-  }
-  // Chunked cookies fallback (Better Auth splits long JWTs across .0/.1/.2 …).
-  if (!rawJwt && chunks.length > 0) {
-    chunks.sort((a, b) => a.idx - b.idx);
-    rawJwt = chunks.map(c => c.value).join('');
-  }
-  if (!rawJwt) return null;
-
-  const decoded = decodeJwtBody(rawJwt);
-  if (decoded && typeof decoded === 'object' && typeof decoded.sessionToken === 'string') {
-    return decoded.sessionToken;
-  }
-  return null;
-}
 
 /**
  * Get the current session from a request.
@@ -271,6 +243,14 @@ export async function getIdpToken(request?: Request): Promise<IdpTokenResult> {
 
   const accessToken = sessionData.idpAccessToken || (sessionData as any).accessToken;
   if (!accessToken) {
+    // Card 187871: a live Better Auth session with no idpAccessToken and
+    // mfaVerified !== true is a user mid-2FA, not a dead session - the IDP
+    // withholds the full token until 2FA completes (idp-fetch.ts:81/113).
+    // Only treat this as terminal once the session itself claims 2FA is
+    // already done; a token missing AFTER that is genuinely broken.
+    if (sessionData.mfaVerified !== true) {
+      return { success: false, error: 'NO_TOKEN_PENDING_2FA', terminal: false, sessionData };
+    }
     return { success: false, error: 'NO_TOKEN', terminal: true };
   }
 

package/src/server/decode-session.ts

@@ -12,6 +12,7 @@ import { getSession, type SessionData } from '../lib/session-store';
 import { getIDPClientConfig } from '../lib/idp-client-config';
 import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
 import { ensureInitialized } from '../lib/startup-init';
+import { extractSessionTokenFromCookieValue } from '../lib/session-cookie-shape';
 
 export interface DecodedSession {
   sessionData: SessionData;
@@ -100,6 +101,48 @@ async function tryBetterAuthSession(
       }
     } catch { /* Redis unavailable */ }
 
+    // LEG-1 FAIL-CLOSED ON UNUSABLE ROLES (card 340015, BAPert R412, 2026-09-03).
+    //
+    // `idpTokens.roles` is the ONLY source of roles for every role-gated route
+    // (see :109 below). When it is empty this leg used to return a perfectly
+    // valid-LOOKING session carrying `roles: []` — so the caller was
+    // authenticated but authorised for nothing. Every admin screen 403s and
+    // renders its chrome with no data and NO ERROR TEXT: it does not look
+    // broken, it looks empty.
+    //
+    // Three independent causes produce that state, so the test is on the
+    // CONDITION THAT ACTUALLY HARMS — "no usable roles" — rather than on any
+    // one route to it. A fourth cause is then covered for free:
+    //   A  MINT        the password / admin-login lane never writes the block
+    //                  (it never calls storeIdpTokensInSession), so it is
+    //                  absent from birth.
+    //   B  CLOBBER     better-auth's own 24h session refresh rebuilds the
+    //                  `ba:` record as `{session, user}` and drops the
+    //                  `idpTokens` SIBLING structurally, not conditionally
+    //                  (better-auth internal-adapter.mjs:287). This hits the
+    //                  OAuth and passkey lanes too — they are safe for 24
+    //                  hours and then stop being safe.
+    //   C  DERIVATION  the block is PRESENT and fully populated with only
+    //                  `roles` empty (card 339748). `!idpTokens` is FALSE
+    //                  here and cannot see it — which is exactly why the
+    //                  predicate is `!idpTokens?.roles?.length` and not an
+    //                  absence check.
+    //
+    // Declining here hands the request to the legacy `{slug}:sess:` leg below,
+    // which carries the same roles. *** IF THAT RECORD IS ALSO ABSENT THE USER
+    // IS SIGNED OUT. THAT IS DELIBERATE AND ACCEPTED, NOT A REGRESSION *** —
+    // an honest, visible sign-out in place of a silently half-authorised
+    // session. Read the commit message before treating a sign-out here as a
+    // bug introduced by this fix.
+    if (!idpTokens?.roles?.length) {
+      console.warn(
+        '[DECODE-SESSION] Leg 1 declining: idpTokens unusable (no roles) for session',
+        result.session.token.substring(0, 10),
+        '— falling through to the sess: leg'
+      );
+      return null;
+    }
+
     // Map Better Auth session + IDP tokens to SessionData
     const sessionData: SessionData = {
       userId: idpTokens?.userId || result.user.id || '',
@@ -111,6 +154,9 @@ async function tryBetterAuthSession(
       idpAccessTokenExpires: idpTokens?.idpAccessTokenExpires
         || (result.session.expiresAt ? new Date(result.session.expiresAt).getTime() : Date.now() + 24 * 60 * 60 * 1000),
       mfaVerified: idpTokens?.mfaVerified ?? false,
+      // R807 (362550): fail-closed collapse above stays; this preserves the bit it
+      // destroys. Explicit `false` counts as a signal - hence `!== undefined`.
+      mfaSignalPresent: idpTokens?.mfaVerified !== undefined,
       /**
        * ⚠ WAS HARDCODED `'google'` — third site of QAPert finding #3 (card
        * 167892), found by sweeping rather than by report.
@@ -193,24 +239,62 @@ export async function decodeSession(
       return null;
     }
 
-    const secretKey = new TextEncoder().encode(secret);
-    let payload: JWTPayload;
-    try {
-      const result = await jwtVerify(cookieValue, secretKey);
-      payload = result.payload;
-    } catch (jwtError) {
-      console.warn('[DECODE-SESSION] JWT verification failed:', jwtError instanceof Error ? jwtError.message : String(jwtError));
-      return null;
+    // BA-SHAPE-AWARE FALLBACK LEG (183047, 2026-08-08).
+    //
+    // Better Auth mints session cookies as `{token}.{base64(hmac)}` — TWO
+    // segments, one dot. jose's `jwtVerify()` below requires a genuine
+    // compact JWS — THREE segments — and throws "Invalid Compact JWS" on a
+    // BA-shaped cookie unconditionally, before it ever looks at the secret.
+    // Since Better Auth is the only minter in production, that meant this
+    // fallback could never succeed for the cookies it actually receives: any
+    // single Better-Auth-primary miss (secondary-storage eviction, disabled
+    // cookie cache, in-flight secret divergence) read as total session
+    // death, because the ONLY fallback was structurally blind to the only
+    // shape it would ever be handed.
+    //
+    // Check the shape FIRST. A BA-hmac cookie skips jose entirely and goes
+    // straight to the Redis-canonical liveness check below — same posture
+    // as the JWS path always had (no signature re-check here either; Redis
+    // presence is the authority). A JWS-shaped cookie (legacy NextAuth-era,
+    // if any still linger) keeps the original jwtVerify path unchanged.
+    const shaped = extractSessionTokenFromCookieValue(cookieValue);
+
+    let sessionToken: string | undefined;
+    let payload: JWTPayload | undefined;
+
+    if (shaped?.shape === 'ba-hmac') {
+      sessionToken = shaped.token;
+    } else {
+      const secretKey = new TextEncoder().encode(secret);
+      try {
+        const result = await jwtVerify(cookieValue, secretKey);
+        payload = result.payload;
+      } catch (jwtError) {
+        console.warn('[DECODE-SESSION] JWT verification failed:', jwtError instanceof Error ? jwtError.message : String(jwtError));
+        return null;
+      }
+      sessionToken = (payload as any).sessionToken || (payload as any).redisSessionId;
     }
 
-    const sessionToken = (payload as any).sessionToken || (payload as any).redisSessionId;
     if (!sessionToken) {
-      console.warn('[DECODE-SESSION] JWT payload missing sessionToken/redisSessionId');
+      console.warn('[DECODE-SESSION] No sessionToken resolved from cookie (shape:', shaped?.shape ?? 'unrecognized', ')');
       return null;
     }
 
     const sessionData = await getSession(sessionToken);
     if (!sessionData) {
+      // The OTHER half of R412(ii). There are two ways decodeSession returns
+      // null and they mean different things, so they must not both be silent:
+      // Leg 1 declining is routine and recoverable (this leg normally holds
+      // the roles), whereas reaching HERE means there is no fallback record
+      // either and the caller is about to be signed out. Different meanings,
+      // different remediations — do not ship a second silent path while
+      // fixing a silent path.
+      console.warn(
+        '[DECODE-SESSION] No sess: record for token',
+        sessionToken.substring(0, 10),
+        '— no fallback available, session will be signed out'
+      );
       return null;
     }
 
@@ -226,7 +310,7 @@ export async function decodeSession(
 
     return {
       sessionData,
-      jwtPayload: payload as DecodedSession['jwtPayload'],
+      jwtPayload: (payload ?? { sessionToken }) as DecodedSession['jwtPayload'],
     };
   } catch (error) {
     console.error('[DECODE-SESSION] Error:', error instanceof Error ? error.message : String(error));

package/src/templates/instrumentation.ts

@@ -34,8 +34,27 @@ export async function register() {
       console.log('Server startup initialization complete!');
       console.log('');
     } catch (error) {
-      console.error('Server startup initialization failed:', error);
-      console.error('Will retry initialization on first request.');
+      // DO NOT SWALLOW THIS. The previous version logged "Will retry initialization on
+      // first request" and let the server come up - so a site printed "Ready" while
+      // holding NO auth config, and betterAuth() got an empty secret, which it silently
+      // upgrades to the public DEFAULT_SECRET. Unavailable beats forgeable.
+      //
+      // payez_idp_admin_web/src/instrumentation.ts is the reference: it does not catch
+      // at all, and has a deliberate, named EMERGENCY_BYPASS_IDP escape hatch instead.
+      const msg = error instanceof Error ? error.message : String(error);
+      console.error('');
+      console.error('╔══════════════════════════════════════════════════════════════╗');
+      console.error('║   STARTUP FAILED — REFUSING TO SERVE                         ║');
+      console.error('╚══════════════════════════════════════════════════════════════╝');
+      console.error('');
+      console.error('  ' + msg);
+      console.error('');
+      console.error('  This server cannot obtain its auth configuration from the IDP,');
+      console.error('  so it has no signing secret and no sign-in policy.');
+      console.error('');
+      // Next CATCHES errors thrown from register() and continues; exiting is the only
+      // thing that actually stops the server coming up.
+      process.exit(1);
     }
   }
 }

package/src/types/auth.ts

@@ -4,7 +4,27 @@ export type AuthMode = 'traditional' | 'federated';
 export type FederatedProvider = 'google' | 'microsoft' | 'facebook' | 'github' | 'apple';
 
 export interface AuthConfig {
+  /**
+   * @deprecated Superseded by allowFederatedLogin / allowTraditionalLogin.
+   * A single mode made the two mutually exclusive, so a site could only ever show ONE of
+   * OAuth or username/password - and because sites set it themselves, a client's sign-in
+   * screen could contradict what its own IDP offered. Kept so existing callers compile.
+   */
   mode: AuthMode;
+
+  /**
+   * Whether federated (OAuth) sign-in is offered. Defaults to what the IDP reports at
+   * /api/auth/settings; a site may override. Both this and allowTraditionalLogin can be
+   * true at once - that is the normal case.
+   */
+  allowFederatedLogin?: boolean;
+
+  /**
+   * Whether username/password sign-in is offered. DEFAULTS ON. The IDP does not carry an
+   * explicit flag for it yet; until it does, it is available unless a site opts out.
+   * An OAuth-only client is a deliberate choice, never the default.
+   */
+  allowTraditionalLogin?: boolean;
   providers: FederatedProvider[];
   enableRecovery: boolean;
   enableEmailSignup: boolean;

package/dist/lib/auth-secret.d.ts

@@ -1,17 +0,0 @@
-import 'server-only';
-/**
- * Resolve the Better Auth signing secret (server-only).
- *
- * Priority:
- * 1) Use process.env.BETTER_AUTH_SECRET (preferred) or NEXTAUTH_SECRET (legacy)
- *    if present — allows overrides/production via env.
- * 2) Fetch from IDP broker endpoint — IDP handles all Key Vault/signing.
- * 3) Cache result in-memory and set process.env.BETTER_AUTH_SECRET for
- *    subsequent calls.
- *
- * NOTE on naming: this secret is the cryptographic key Better Auth uses to
- * sign session JWTs. The IDP backend still names the broker endpoint and
- * response field with the legacy "next-auth" / "nextAuthSecret" names; we
- * read both new and legacy on the wire during the migration window.
- */
-export declare function resolveAuthSecret(): Promise<string>;