@payez/next-mvp 4.0.46 → 4.0.49

package/src/api-handlers/auth/update-session.ts

@@ -38,29 +38,19 @@ interface UpdateSessionResponse {
   twoFactorMethod?: string;
 }
 
-interface UpdateSessionConfig {
-  nextAuthSecret?: string; // Legacy - no longer used by Better Auth
-}
-
 /**
- * Creates an update-session handler for Next.js API routes
+ * Creates an update-session handler for Next.js API routes.
  *
- * @param config Configuration for NextAuth
- * @returns Next.js POST handler function
+ * Better Auth resolves its session from cookies, so this handler takes no
+ * configuration. Use the default `POST` export below for typical usage.
  *
  * @example
  * ```typescript
  * // In your app's /app/api/auth/update-session/route.ts
- * import { createUpdateSessionHandler } from '@payez/next-mvp/api-handlers/auth/update-session';
- *
- * export const POST = createUpdateSessionHandler({
- *   nextAuthSecret: process.env.NEXTAUTH_SECRET!
- * });
+ * export { POST } from '@payez/next-mvp/api-handlers/auth/update-session';
  * ```
  */
-export function createUpdateSessionHandler(config: UpdateSessionConfig) {
-  const { nextAuthSecret } = config;
-
+export function createUpdateSessionHandler() {
   return async function POST(req: NextRequest) {
     try {
       let body: UpdateSessionRequest;
@@ -115,9 +105,6 @@ export function createUpdateSessionHandler(config: UpdateSessionConfig) {
 }
 
 /**
- * Default export for backward compatibility
- * Requires environment variable: NEXTAUTH_SECRET
+ * Default POST export — drop-in for `app/api/auth/update-session/route.ts`.
  */
-export const POST = createUpdateSessionHandler({
-  nextAuthSecret: process.env.NEXTAUTH_SECRET || ''
-});
+export const POST = createUpdateSessionHandler();

package/src/api-handlers/auth/verify-code.ts

@@ -20,29 +20,19 @@ interface VerifyCodeRequest {
   refreshTokenExpires?: number;
 }
 
-interface VerifyCodeConfig {
-  nextAuthSecret?: string; // Legacy - no longer used by Better Auth
-}
-
 /**
- * Creates a verify-code/complete-2FA handler for Next.js API routes
+ * Creates a verify-code/complete-2FA handler for Next.js API routes.
  *
- * @param config Configuration for NextAuth
- * @returns Next.js POST handler function
+ * Better Auth resolves its session from cookies, so this handler takes no
+ * configuration. Use the default `POST` export below for typical usage.
  *
  * @example
  * ```typescript
  * // In your app's /app/api/auth/verify-code/route.ts
- * import { createVerifyCodeHandler } from '@payez/next-mvp/api-handlers/auth/verify-code';
- *
- * export const POST = createVerifyCodeHandler({
- *   nextAuthSecret: process.env.NEXTAUTH_SECRET!
- * });
+ * export { POST } from '@payez/next-mvp/api-handlers/auth/verify-code';
  * ```
  */
-export function createVerifyCodeHandler(config: VerifyCodeConfig) {
-  const { nextAuthSecret } = config;
-
+export function createVerifyCodeHandler() {
   return async function POST(req: NextRequest) {
     try {
       let body: VerifyCodeRequest;
@@ -117,9 +107,6 @@ export function createVerifyCodeHandler(config: VerifyCodeConfig) {
 }
 
 /**
- * Default export for backward compatibility
- * Requires environment variable: NEXTAUTH_SECRET
+ * Default POST export — drop-in for `app/api/auth/verify-code/route.ts`.
  */
-export const POST = createVerifyCodeHandler({
-  nextAuthSecret: process.env.NEXTAUTH_SECRET || ''
-});
+export const POST = createVerifyCodeHandler();

package/src/api-handlers/session/viability.ts

@@ -12,8 +12,8 @@ import { getIDPClientConfig } from '../../lib/idp-client-config';
 
 export async function GET(req: NextRequest) {
   try {
-    // Ensure initialization is complete
-    if (!process.env.NEXTAUTH_SECRET) {
+    // Ensure initialization is complete (auth signing secret resolved from IDP)
+    if (!process.env.BETTER_AUTH_SECRET && !process.env.NEXTAUTH_SECRET) {
       try {
         await ensureInitialized();
       } catch (error) {

package/src/auth/better-auth.ts

@@ -48,49 +48,25 @@ export function buildBetterAuthProviders(
   return providers;
 }
 
-/**
- * Optional extra plugins for createBetterAuthInstance.
- * Use to add credentials/custom signin endpoints from the host app.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type BetterAuthExtraPlugins = any[];
-
-/**
- * Optional overrides for createBetterAuthInstance.
- */
-export interface BetterAuthInstanceOptions {
-  /** Path suffix for the BA mount (default: '/api/auth'). Use '/api/ba-auth' for migration scenarios. */
-  basePath?: string;
-}
-
 /**
  * Create Better Auth instance from IDP config.
  *
  * No database — runs in stateless mode with JWE cookie cache.
  * Call after getIDPClientConfig() resolves.
- *
- * @param idpConfig IDP client config (from getIDPClientConfig)
- * @param extraPlugins Optional plugins to add (e.g., credentials plugin from host app)
- * @param options Optional overrides (e.g., basePath for migration scenarios)
  */
-export function createBetterAuthInstance(
-  idpConfig: IDPClientConfig,
-  extraPlugins: BetterAuthExtraPlugins = [],
-  options: BetterAuthInstanceOptions = {}
-) {
+export function createBetterAuthInstance(idpConfig: IDPClientConfig) {
   const appSlug = idpConfig.clientSlug || getAppSlug();
-  const basePath = options.basePath || '/api/auth';
 
   // Resolve base URL: BETTER_AUTH_URL env > IDP config > localhost fallback
-  // basePath defaults to /api/auth but can be overridden via options for migration scenarios
+  // Must include /api/auth since that's where the catch-all route is mounted
   const rawBaseURL = process.env.BETTER_AUTH_URL
     || idpConfig.baseClientUrl
     || `http://localhost:${process.env.PORT || '3000'}`;
-  const baseURL = rawBaseURL.replace(/\/+$/, '') + basePath;
+  const baseURL = rawBaseURL.replace(/\/+$/, '') + '/api/auth';
 
   return betterAuth({
     baseURL,
-    secret: idpConfig.nextAuthSecret as string,
+    secret: idpConfig.authSecret as string,
 
     socialProviders: buildBetterAuthProviders(idpConfig),
 
@@ -147,7 +123,6 @@ export function createBetterAuthInstance(
     },
 
     plugins: [
-      ...extraPlugins,
       nextCookies(),
     ],
   });
@@ -173,12 +148,12 @@ let initPromise: Promise<any> | null = null;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export { cachedInstance as __betterAuthInstance };
 
-export async function getBetterAuthInstance(extraPlugins: BetterAuthExtraPlugins = []) {
+export async function getBetterAuthInstance() {
   if (cachedInstance) return cachedInstance;
 
   if (!initPromise) {
     initPromise = getIDPClientConfig(true).then(config => {
-      const instance = createBetterAuthInstance(config, extraPlugins);
+      const instance = createBetterAuthInstance(config);
       cachedInstance = instance;
       console.log('[BETTER_AUTH] Instance created for', config.clientSlug || config.clientId);
       return instance;
@@ -287,7 +262,7 @@ export async function exchangeOAuthForIdpTokens(
     }
 
     // Build IDP token data
-    const requiresTwoFactor = result.requires_two_factor ?? result.user?.requiresTwoFactor ?? result.requiresTwoFactor ?? false;
+    const requiresTwoFactor = result.user?.requiresTwoFactor ?? result.requiresTwoFactor ?? false;
     const idpTokenData = {
       idpAccessToken: result.access_token,
       idpRefreshToken: result.refresh_token,

package/src/client/better-auth-client.ts

@@ -1,11 +1,10 @@
 /**
- * Better Auth Client (Phase 3)
+ * Better Auth Client.
  *
- * Drop-in replacement for next-auth/react hooks and functions.
  * Import from '@payez/next-mvp/client/better-auth-client'.
  *
- * Includes useSessionCompat() — returns NextAuth-shaped { data, status }
- * so existing components don't need destructure pattern changes.
+ * Includes useSessionCompat() — returns a { data, status } shape so existing
+ * components written against the legacy hook don't need destructure changes.
  */
 
 import { createAuthClient } from 'better-auth/react';

package/src/lib/{nextauth-secret.ts → auth-secret.ts}

@@ -1,23 +1,37 @@
 import 'server-only';
-import { validateNextAuthSecret } from './secret-validation';
+import { validateAuthSecret } from './secret-validation';
 import { randomUUID } from 'crypto';
 
 let cachedSecret: string | null = null;
 let lastFetchedAt = 0;
 
 /**
- * Resolve the NextAuth secret (server-only).
+ * Resolve the Better Auth signing secret (server-only).
  *
  * Priority:
- * 1) Use process.env.NEXTAUTH_SECRET if present (allows overrides/production)
- * 2) Fetch from IDP broker endpoint - IDP handles all Key Vault/signing
- * 3) Cache result in-memory and set process.env.NEXTAUTH_SECRET for subsequent calls
+ * 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 async function resolveNextAuthSecret(): Promise<string> {
-  // Check if already in environment
-  if (process.env.NEXTAUTH_SECRET && process.env.NEXTAUTH_SECRET.trim() !== '') {
+export async function resolveAuthSecret(): Promise<string> {
+  // Check if already in environment (prefer new name, fall back to legacy)
+  const envSecret =
+    (process.env.BETTER_AUTH_SECRET && process.env.BETTER_AUTH_SECRET.trim() !== ''
+      ? process.env.BETTER_AUTH_SECRET
+      : undefined) ||
+    (process.env.NEXTAUTH_SECRET && process.env.NEXTAUTH_SECRET.trim() !== ''
+      ? process.env.NEXTAUTH_SECRET
+      : undefined);
+  if (envSecret) {
     // Silent - already configured
-    return process.env.NEXTAUTH_SECRET;
+    return envSecret;
   }
 
   // Check if cached and fresh (within 5 minutes)
@@ -74,7 +88,8 @@ export async function resolveNextAuthSecret(): Promise<string> {
     throw new Error('IDP did not return a valid signed client assertion');
   }
 
-  // Step 2: Use the signed assertion to fetch the NextAuth secret
+  // Step 2: Use the signed assertion to fetch the auth secret
+  // (Endpoint is still served at /next-auth/secret on the IDP — legacy path.)
 
   const proxyUrl = new URL(`${base.replace(/\/$/, '')}/api/ExternalAuth/next-auth/secret`);
 
@@ -98,24 +113,25 @@ export async function resolveNextAuthSecret(): Promise<string> {
   const proxyBody: any = await proxyResp.json().catch(() => ({}));
 
   const secret = (proxyBody?.data?.secret ?? proxyBody?.secret) as string | undefined;
-  const configuration = (proxyBody?.data?.configuration ?? proxyBody?.configuration) as any | undefined;
-
   // Configuration is available but we don't log it verbosely
 
   if (!secret || typeof secret !== 'string') {
-    throw new Error('Proxy did not return a valid NextAuth secret');
+    throw new Error('Proxy did not return a valid auth secret');
   }
 
-  const validation = validateNextAuthSecret(secret);
+  const validation = validateAuthSecret(secret);
   if (!validation.valid) {
-    throw new Error(`Fetched NextAuth secret failed validation: ${validation.reason}`);
+    throw new Error(`Fetched auth secret failed validation: ${validation.reason}`);
   }
 
   cachedSecret = secret;
   lastFetchedAt = Date.now();
+  process.env.BETTER_AUTH_SECRET = secret;
+  // Also set legacy name during transition so any consumer still reading
+  // process.env.NEXTAUTH_SECRET keeps working until they upgrade.
   process.env.NEXTAUTH_SECRET = secret;
 
-  console.log('[NEXTAUTH-SECRET] Resolved from IDP (length:', secret.length + ')');
+  console.log('[AUTH-SECRET] Resolved from IDP (length:', secret.length + ')');
 
   return secret;
 }

package/src/lib/demo-mode.ts

@@ -9,5 +9,9 @@ export function isDemoMode(): boolean {
 
 export function isAuthConfigured(): boolean {
   if (isDemoMode()) return false;
-  return !!(process.env.NEXTAUTH_SECRET || (process.env.NEXT_CLIENT_ID && process.env.NEXT_CLIENT_PRIVATE_KEY_PEM));
+  return !!(
+    process.env.BETTER_AUTH_SECRET ||
+    process.env.NEXTAUTH_SECRET ||
+    (process.env.NEXT_CLIENT_ID && process.env.NEXT_CLIENT_PRIVATE_KEY_PEM)
+  );
 }

package/src/lib/idp-client-config.ts

@@ -5,7 +5,7 @@
  * - OAuth provider credentials (from Key Vault)
  * - 2FA/MFA settings
  * - Session configuration
- * - NextAuth secret
+ * - Better Auth signing secret
  * - Branding
  *
  * CACHING STRATEGY:
@@ -58,7 +58,11 @@ export interface BrandingConfig {
 export interface IDPClientConfig {
     clientId: string;
     clientSlug: string;
-    nextAuthSecret: string;
+    /**
+     * Cryptographic secret used by Better Auth to sign session JWTs.
+     * Historically named "nextAuthSecret" — kept under the new name now.
+     */
+    authSecret: string;
     configCacheTtlSeconds: number;
     oauthProviders: OAuthProviderConfig[];
     authSettings: AuthSettings;
@@ -170,14 +174,15 @@ export async function getIDPClientConfig(forceRefresh: boolean = false): Promise
             cachedConfig = redisConfig;
             cacheExpiry = Date.now() + ((redisConfig.configCacheTtlSeconds || 300) * 1000);
 
-            // Set NEXTAUTH_SECRET from cached config
-            if (redisConfig.nextAuthSecret) {
-                process.env.NEXTAUTH_SECRET = redisConfig.nextAuthSecret;
+            // Set BETTER_AUTH_SECRET from cached config (also set legacy
+            // NEXTAUTH_SECRET during the rename transition).
+            if (redisConfig.authSecret) {
+                process.env.BETTER_AUTH_SECRET = redisConfig.authSecret;
+                process.env.NEXTAUTH_SECRET = redisConfig.authSecret;
             }
 
-            // Set IDENTITY_CLIENT_BASE_EXTERNAL_URL from cached config
-            // AUTH_TRUST_HOST=true tells NextAuth to derive OAuth callback URLs from headers.
-            // Only set if not already defined (allows deployment override for beta/staging)
+            // Set IDENTITY_CLIENT_BASE_EXTERNAL_URL from cached config.
+            // Only set if not already defined (allows deployment override for beta/staging).
             if (redisConfig.baseClientUrl && !process.env.IDENTITY_CLIENT_BASE_EXTERNAL_URL) {
                 process.env.IDENTITY_CLIENT_BASE_EXTERNAL_URL = redisConfig.baseClientUrl;
             }
@@ -211,16 +216,17 @@ export async function getIDPClientConfig(forceRefresh: boolean = false): Promise
             // Store in Redis for persistence across module reloads
             await setConfigInRedis(config);
 
-            // Set NEXTAUTH_SECRET from config
-            if (config.nextAuthSecret) {
-                process.env.NEXTAUTH_SECRET = config.nextAuthSecret;
+            // Set BETTER_AUTH_SECRET from config (also set legacy
+            // NEXTAUTH_SECRET during the rename transition).
+            if (config.authSecret) {
+                process.env.BETTER_AUTH_SECRET = config.authSecret;
+                process.env.NEXTAUTH_SECRET = config.authSecret;
             } else {
-                throw new Error('[IDP_CONFIG] FATAL: IDP did not return nextAuthSecret');
+                throw new Error('[IDP_CONFIG] FATAL: IDP did not return authSecret');
             }
 
-            // Set IDENTITY_CLIENT_BASE_EXTERNAL_URL from config
-            // AUTH_TRUST_HOST=true tells NextAuth to derive OAuth callback URLs from headers.
-            // Only set if not already defined (allows deployment override for beta/staging)
+            // Set IDENTITY_CLIENT_BASE_EXTERNAL_URL from config.
+            // Only set if not already defined (allows deployment override for beta/staging).
             if (config.baseClientUrl && !process.env.IDENTITY_CLIENT_BASE_EXTERNAL_URL) {
                 process.env.IDENTITY_CLIENT_BASE_EXTERNAL_URL = config.baseClientUrl;
                 console.log("[IDP_CONFIG] Set IDENTITY_CLIENT_BASE_EXTERNAL_URL:", config.baseClientUrl);
@@ -305,7 +311,14 @@ async function fetchConfigFromInternalIDP(internalIdpUrl: string, clientIdStr: s
     const config: IDPClientConfig = {
         clientId: String(rawClientId),
         clientSlug: configData.clientSlug ?? configData.client_slug ?? configData.slug ?? '',
-        nextAuthSecret: configData.nextAuthSecret ?? configData.next_auth_secret ?? '',
+        // Wire compatibility: accept new authSecret first, fall back to legacy
+        // nextAuthSecret/next_auth_secret while IDP rename rolls out.
+        authSecret:
+            configData.authSecret ??
+            configData.auth_secret ??
+            configData.nextAuthSecret ??
+            configData.next_auth_secret ??
+            '',
         configCacheTtlSeconds: configData.configCacheTtlSeconds ?? configData.config_cache_ttl_seconds ?? 300,
         oauthProviders: (configData.oauthProviders ?? configData.oauth_providers ?? []).map((p: any) => ({
             provider: p.provider ?? '',
@@ -336,8 +349,8 @@ async function fetchConfigFromInternalIDP(internalIdpUrl: string, clientIdStr: s
         baseClientUrl: configData.baseClientUrl ?? configData.base_client_url ?? configData.BaseClientUrl
     };
 
-    if (!config.nextAuthSecret) {
-        throw new Error('[IDP_CONFIG] FATAL: Internal IDP did not return nextAuthSecret');
+    if (!config.authSecret) {
+        throw new Error('[IDP_CONFIG] FATAL: Internal IDP did not return authSecret');
     }
 
     console.log(`[IDP_CONFIG] Internal IDP config loaded for ${clientIdStr}`);
@@ -464,11 +477,18 @@ async function fetchConfigFromIDP(idpUrl: string, clientIdStr: string): Promise<
         throw new Error(`[IDP_CONFIG] FATAL: IDP response missing clientId/client_id. Got: ${JSON.stringify(Object.keys(configData))}`);
     }
 
-    // Map response to our interface (IDP always returns snake_case)
+    // Map response to our interface (IDP returns camelCase or snake_case).
+    // Wire compatibility: accept new authSecret first, fall back to legacy
+    // nextAuthSecret/next_auth_secret while IDP rename rolls out.
     const config: IDPClientConfig = {
         clientId: String(rawClientId),
         clientSlug: configData.clientSlug ?? configData.client_slug ?? configData.slug ?? '',
-        nextAuthSecret: configData.nextAuthSecret ?? configData.next_auth_secret ?? '',
+        authSecret:
+            configData.authSecret ??
+            configData.auth_secret ??
+            configData.nextAuthSecret ??
+            configData.next_auth_secret ??
+            '',
         configCacheTtlSeconds: configData.configCacheTtlSeconds ?? configData.config_cache_ttl_seconds ?? 300,
         oauthProviders: (configData.oauthProviders ?? configData.oauth_providers ?? []).map((p: any) => ({
             provider: p.provider ?? '',
@@ -517,8 +537,8 @@ async function fetchConfigFromIDP(idpUrl: string, clientIdStr: string): Promise<
     if (!config.clientId) {
         throw new Error('[IDP_CONFIG] FATAL: clientId is empty or missing after parsing');
     }
-    if (!config.nextAuthSecret) {
-        throw new Error('[IDP_CONFIG] FATAL: nextAuthSecret is empty after parsing');
+    if (!config.authSecret) {
+        throw new Error('[IDP_CONFIG] FATAL: authSecret is empty after parsing');
     }
 
     // Success - reset failure tracking

package/src/lib/secret-validation.ts

@@ -1,4 +1,4 @@
-export function validateNextAuthSecret(secret: string): { valid: boolean; reason?: string } {
+export function validateAuthSecret(secret: string): { valid: boolean; reason?: string } {
   if (!secret || typeof secret !== 'string') return { valid: false, reason: 'missing' };
   if (secret.length < 32) return { valid: false, reason: 'too_short' };
   const classes = [/[a-z]/, /[A-Z]/, /[0-9]/, /[^a-zA-Z0-9]/];

package/src/lib/startup-init.ts

@@ -4,8 +4,8 @@
  * This module ensures that critical initialization tasks are completed
  * before the application serves requests.
  *
- * Now uses unified IDP client config for:
- * - NEXTAUTH_SECRET
+ * Uses unified IDP client config for:
+ * - BETTER_AUTH_SECRET (the Better Auth signing secret)
  * - OAuth provider configuration
  * - Auth settings (2FA, session timeouts, etc.)
  */
@@ -75,7 +75,7 @@ export function logStartupStatus(): void {
     console.log('║            🚀 PayEz Next MVP - Starting Up                    ║');
     console.log('║                                                              ║');
     console.log('║  Async initialization in progress...                         ║');
-    console.log('║  - Resolving NEXTAUTH_SECRET from IDP                       ║');
+    console.log('║  - Resolving BETTER_AUTH_SECRET from IDP                     ║');
     console.log('║  - Verifying environment configuration                       ║');
     console.log('║                                                              ║');
     console.log('║  Check logs below for detailed initialization status:        ║');
@@ -117,16 +117,21 @@ async function performInitialization(): Promise<void> {
       console.log('[STARTUP] Client config loaded successfully');
       console.log('[STARTUP]    - Client ID:', config.clientId);
       console.log('[STARTUP]    - Client Slug:', config.clientSlug);
-      console.log('[STARTUP]    - Secret length:', config.nextAuthSecret?.length || 0, 'chars');
+      console.log('[STARTUP]    - Secret length:', config.authSecret?.length || 0, 'chars');
       console.log('[STARTUP]    - OAuth Providers:', config.oauthProviders?.filter(p => p.enabled).map(p => p.provider).join(', ') || 'none');
       console.log('[STARTUP]    - Require 2FA:', config.authSettings?.require2FA);
       console.log('[STARTUP]    - Cache TTL:', config.configCacheTtlSeconds, 'seconds');
       console.log('[STARTUP]    - Base Client URL:', config.baseClientUrl || '(not set)');
 
-      // Set NEXTAUTH_SECRET from IDP response if not already set
-      if (config.nextAuthSecret && !process.env.NEXTAUTH_SECRET) {
-        process.env.NEXTAUTH_SECRET = config.nextAuthSecret;
-        console.log('[STARTUP] Set NEXTAUTH_SECRET from IDP config');
+      // Set BETTER_AUTH_SECRET from IDP response if not already set.
+      // Also mirror to legacy NEXTAUTH_SECRET during the rename transition
+      // so any consumer code still reading the old name keeps working.
+      if (config.authSecret && !process.env.BETTER_AUTH_SECRET) {
+        process.env.BETTER_AUTH_SECRET = config.authSecret;
+        console.log('[STARTUP] Set BETTER_AUTH_SECRET from IDP config');
+      }
+      if (config.authSecret && !process.env.NEXTAUTH_SECRET) {
+        process.env.NEXTAUTH_SECRET = config.authSecret;
       }
     } catch (error) {
       const errorMsg = error instanceof Error ? error.message : String(error);
@@ -136,16 +141,16 @@ async function performInitialization(): Promise<void> {
       console.error('[STARTUP] No fallback available for auth secret resolution');
     }
 
-    // Step 2: Verify NEXTAUTH_SECRET is available - FAIL FAST if not
-    console.log('[STARTUP] Step 2/2: Verifying NEXTAUTH_SECRET...');
+    // Step 2: Verify BETTER_AUTH_SECRET is available - FAIL FAST if not
+    console.log('[STARTUP] Step 2/2: Verifying BETTER_AUTH_SECRET...');
 
-    const secret = process.env.NEXTAUTH_SECRET;
+    const secret = process.env.BETTER_AUTH_SECRET || process.env.NEXTAUTH_SECRET;
     if (!secret || secret.trim() === '') {
       console.error('');
       console.error('╔══════════════════════════════════════════════════════════════╗');
-      console.error('║   ❌ FATAL: NEXTAUTH_SECRET NOT AVAILABLE                     ║');
+      console.error('║   ❌ FATAL: BETTER_AUTH_SECRET NOT AVAILABLE                  ║');
       console.error('║                                                              ║');
-      console.error('║   The app cannot start without a valid NEXTAUTH_SECRET.      ║');
+      console.error('║   The app cannot start without a valid auth signing secret.  ║');
       console.error('║   This should be fetched from IDP at startup.                ║');
       console.error('║                                                              ║');
       console.error('║   Possible causes:                                           ║');
@@ -155,10 +160,10 @@ async function performInitialization(): Promise<void> {
       console.error('║   • Network connectivity issue                               ║');
       console.error('╚══════════════════════════════════════════════════════════════╝');
       console.error('');
-      throw new Error('FATAL: NEXTAUTH_SECRET not available - cannot start without valid secret from IDP');
+      throw new Error('FATAL: BETTER_AUTH_SECRET not available - cannot start without valid secret from IDP');
     }
 
-    console.log('[STARTUP] NEXTAUTH_SECRET verified (' + secret.length + ' chars)');
+    console.log('[STARTUP] BETTER_AUTH_SECRET verified (' + secret.length + ' chars)');
 
     // Step 3: Validate cookie name consistency
     // This catches bugs where getJwtCookieName() returns a different name than
@@ -192,9 +197,9 @@ async function performInitialization(): Promise<void> {
 
     console.error(`
 ╔══════════════════════════════════════════════════════════════╗
-║   ❌ FATAL: NEXTAUTH_SECRET NOT AVAILABLE                     ║
+║   ❌ FATAL: BETTER_AUTH_SECRET NOT AVAILABLE                  ║
 ║                                                              ║
-║   The app cannot start without a valid NEXTAUTH_SECRET.      ║
+║   The app cannot start without a valid auth signing secret.  ║
 ║   This should be fetched from IDP at startup.                ║
 ║                                                              ║
 ${connectionLine}║   Possible causes:                                           ║
@@ -225,7 +230,7 @@ export function getStartupIDPConfig(): IDPClientConfig | null {
 }
 
 /**
- * Check if initialization failed (NEXTAUTH_SECRET couldn't be retrieved)
+ * Check if initialization failed (auth signing secret couldn't be retrieved)
  */
 export function isInitializationFailed(): boolean {
   return initializationFailed;

package/src/lib/test-aware-get-token.ts

@@ -6,11 +6,11 @@ import { getSessionCookieName } from './app-slug';
 export async function getTokenTestAware(req: NextRequest): Promise<any> {
   if (process.env.TEST_MODE === 'true') {
     try {
-      let secret = process.env.NEXTAUTH_SECRET;
+      let secret = process.env.BETTER_AUTH_SECRET || process.env.NEXTAUTH_SECRET;
       if (!secret || secret.trim() === '') {
         const { getIDPClientConfig } = await import('./idp-client-config');
         const idpConfig = await getIDPClientConfig();
-        secret = idpConfig.nextAuthSecret as string;
+        secret = idpConfig.authSecret;
       }
       // Use app-slug prefixed cookie name
       const cookieName = getSessionCookieName();
@@ -37,54 +37,5 @@ export async function getTokenTestAware(req: NextRequest): Promise<any> {
     };
   }
 
-  // Fallback for legacy NextAuth-based sites: try next-auth/jwt with the
-  // app-slug-prefixed cookie name. Uses runtime require so consumers without
-  // next-auth installed are unaffected.
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-eval
-    const dynamicRequire = eval('require') as NodeRequire;
-    let nextAuthJwt: any = null;
-    try {
-      nextAuthJwt = dynamicRequire('next-auth/jwt');
-    } catch {
-      return null; // next-auth not installed → BA-only consumer
-    }
-    if (!nextAuthJwt?.getToken) return null;
-
-    const { resolveNextAuthSecret } = await import('./nextauth-secret');
-    const secret = await resolveNextAuthSecret();
-    if (!secret) return null;
-
-    const cookieName = getSessionCookieName();
-    let nextAuthToken = await nextAuthJwt.getToken({
-      req,
-      secret,
-      cookieName,
-      secureCookie: false,
-    });
-    if (nextAuthToken) {
-      logger.debug('[GET_TOKEN] Resolved via NextAuth JWT (cookieName=' + cookieName + ')');
-      return nextAuthToken;
-    }
-
-    // Try secure cookie variant for production
-    const { getSecureSessionCookieName } = await import('./app-slug');
-    const secureCookieName = getSecureSessionCookieName();
-    nextAuthToken = await nextAuthJwt.getToken({
-      req,
-      secret,
-      cookieName: secureCookieName,
-      secureCookie: true,
-    });
-    if (nextAuthToken) {
-      logger.debug('[GET_TOKEN] Resolved via NextAuth JWT (secure cookie)');
-      return nextAuthToken;
-    }
-  } catch (error) {
-    logger.debug('[GET_TOKEN] NextAuth fallback error', {
-      error: error instanceof Error ? error.message : String(error),
-    });
-  }
-
   return null;
 }

package/src/routes/account/masked-info.ts

@@ -28,7 +28,7 @@ export { POST } from '../../api-handlers/account/masked-info';
  * Environment variables used:
  * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
  * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
- * - NEXTAUTH_SECRET (required)
+ * - BETTER_AUTH_SECRET (required — fetched from IDP at startup)
  *
  * Returns:
  * - Masked email addresses

package/src/routes/account/send-code.ts

@@ -31,7 +31,7 @@ export { POST } from '../../api-handlers/account/send-code';
  * Environment variables used:
  * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
  * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
- * - NEXTAUTH_SECRET (required)
+ * - BETTER_AUTH_SECRET (required — fetched from IDP at startup)
  *
  * Returns:
  * - Success status

package/src/routes/account/verify-email.ts

@@ -30,7 +30,7 @@ export { POST } from '../../api-handlers/account/verify-email';
  * Environment variables used:
  * - IDP_URL or NEXT_PUBLIC_IDP_URL (default: http://localhost:32785)
  * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
- * - NEXTAUTH_SECRET (required)
+ * - BETTER_AUTH_SECRET (required — fetched from IDP at startup)
  *
  * Returns:
  * - Upgraded access token with MFA claim