refactor(auth-next): simplify config to no config or full config policy

- auth-next-server: remove redundant clientId/redirectUri validation (type
  already requires them); clean up defaultConfig and constants comments
- auth-next-client: replace createDefault* merge helpers with
  getSandbox*Config; use config ?? sandboxDefaults at call sites

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: rodrigo-fournier-immutable

examples/passport/wallets-connect-with-nextjs/app/callback-auth-next/page.tsx

@@ -1,11 +1,11 @@
 "use client";
 
-import { CallbackPage, deriveDefaultClientId } from "@imtbl/auth-next-client";
+import { CallbackPage, DEFAULT_SANDBOX_CLIENT_ID } from "@imtbl/auth-next-client";
 
 export default function AuthNextCallback() {
-  // Use deriveDefaultClientId() to match login flow (zero config = sandbox)
+  // Use DEFAULT_SANDBOX_CLIENT_ID to match login flow (zero config = sandbox)
   const config = {
-    clientId: deriveDefaultClientId(),
+    clientId: DEFAULT_SANDBOX_CLIENT_ID,
     redirectUri: typeof window !== 'undefined' ? `${window.location.origin}/callback-auth-next` : '/callback-auth-next',
   };
 

packages/auth-next-client/src/constants.ts

@@ -1,18 +1,18 @@
 /**
- * Re-export constants from auth-next-server for consistency.
- * All shared constants live in auth-next-server to avoid duplication.
+ * Client-side constants for @imtbl/auth-next-client.
+ * Defined locally to avoid importing from auth-next-server (which uses next/server).
+ * Values must stay in sync with auth-next-server constants.
  */
-export {
-  DEFAULT_AUTH_DOMAIN,
-  DEFAULT_AUDIENCE,
-  DEFAULT_SCOPE,
-  IMMUTABLE_PROVIDER_ID,
-  DEFAULT_NEXTAUTH_BASE_PATH,
-  DEFAULT_PRODUCTION_CLIENT_ID,
-  DEFAULT_SANDBOX_CLIENT_ID,
-  DEFAULT_REDIRECT_URI_PATH,
-  DEFAULT_POPUP_REDIRECT_URI_PATH,
-  DEFAULT_LOGOUT_REDIRECT_URI_PATH,
-  DEFAULT_TOKEN_EXPIRY_MS,
-  TOKEN_EXPIRY_BUFFER_MS,
-} from '@imtbl/auth-next-server';
+
+export const DEFAULT_AUTH_DOMAIN = 'https://auth.immutable.com';
+export const DEFAULT_AUDIENCE = 'platform_api';
+export const DEFAULT_SCOPE = 'openid profile email offline_access transact';
+export const IMMUTABLE_PROVIDER_ID = 'immutable';
+export const DEFAULT_NEXTAUTH_BASE_PATH = '/api/auth';
+export const DEFAULT_PRODUCTION_CLIENT_ID = 'PtQRK4iRJ8GkXjiz6xfImMAYhPhW0cYk';
+export const DEFAULT_SANDBOX_CLIENT_ID = 'mjtCL8mt06BtbxSkp2vbrYStKWnXVZfo';
+export const DEFAULT_REDIRECT_URI_PATH = '/callback';
+export const DEFAULT_POPUP_REDIRECT_URI_PATH = '/callback';
+export const DEFAULT_LOGOUT_REDIRECT_URI_PATH = '/';
+export const DEFAULT_TOKEN_EXPIRY_MS = 900_000;
+export const TOKEN_EXPIRY_BUFFER_MS = 60_000;

packages/auth-next-client/src/defaultConfig.ts

@@ -0,0 +1,16 @@
+/**
+ * Sandbox default redirect URI for zero-config mode.
+ * Defined locally to avoid importing from auth-next-server (which uses next/server).
+ * Server: path only. Client: full URL (origin + path).
+ *
+ * @internal
+ */
+
+import { DEFAULT_REDIRECT_URI_PATH } from './constants';
+
+export function deriveDefaultRedirectUri(): string {
+  if (typeof window === 'undefined') {
+    return DEFAULT_REDIRECT_URI_PATH;
+  }
+  return `${window.location.origin}${DEFAULT_REDIRECT_URI_PATH}`;
+}

packages/auth-next-client/src/hooks.test.tsx

@@ -23,21 +23,7 @@ jest.mock('@imtbl/auth', () => ({
   logoutWithRedirect: jest.fn(),
 }));
 
-// Mock auth-next-server to avoid loading next/server (Request not defined in Node/Jest)
-jest.mock('@imtbl/auth-next-server', () => ({
-  DEFAULT_AUTH_DOMAIN: 'https://auth.immutable.com',
-  DEFAULT_AUDIENCE: 'platform_api',
-  DEFAULT_SCOPE: 'openid profile email offline_access transact',
-  IMMUTABLE_PROVIDER_ID: 'immutable',
-  DEFAULT_NEXTAUTH_BASE_PATH: '/api/auth',
-  DEFAULT_PRODUCTION_CLIENT_ID: 'prod-client-id',
-  DEFAULT_SANDBOX_CLIENT_ID: 'sandbox-client-id',
-  DEFAULT_REDIRECT_URI_PATH: '/callback',
-  DEFAULT_POPUP_REDIRECT_URI_PATH: '/callback',
-  DEFAULT_LOGOUT_REDIRECT_URI_PATH: '/',
-  DEFAULT_TOKEN_EXPIRY_MS: 900000,
-  TOKEN_EXPIRY_BUFFER_MS: 60000,
-  deriveDefaultClientId: jest.fn(() => 'sandbox-client-id'),
+jest.mock('./defaultConfig', () => ({
   deriveDefaultRedirectUri: jest.fn(() => 'http://localhost:3000/callback'),
 }));
 

packages/auth-next-client/src/hooks.tsx

@@ -18,14 +18,11 @@ import {
   loginWithRedirect as rawLoginWithRedirect,
   logoutWithRedirect as rawLogoutWithRedirect,
 } from '@imtbl/auth';
-import {
-  deriveDefaultClientId,
-  deriveDefaultRedirectUri,
-} from '@imtbl/auth-next-server';
+import { deriveDefaultRedirectUri } from './defaultConfig';
 import {
   IMMUTABLE_PROVIDER_ID,
   TOKEN_EXPIRY_BUFFER_MS,
-  DEFAULT_POPUP_REDIRECT_URI_PATH,
+  DEFAULT_SANDBOX_CLIENT_ID,
   DEFAULT_LOGOUT_REDIRECT_URI_PATH,
   DEFAULT_AUTH_DOMAIN,
   DEFAULT_SCOPE,
@@ -55,69 +52,29 @@ function deduplicatedUpdate(
 }
 
 // ---------------------------------------------------------------------------
-// Default configuration helpers (extend shared logic from auth-next-server)
+// Sandbox defaults for zero-config (no config or full config - no merge)
 // ---------------------------------------------------------------------------
 
-/**
- * Derive the default popupRedirectUri based on the current URL.
- *
- * @returns Default popup redirect URI
- * @internal
- */
-function deriveDefaultPopupRedirectUri(): string {
-  if (typeof window === 'undefined') {
-    return DEFAULT_POPUP_REDIRECT_URI_PATH;
-  }
-
-  return `${window.location.origin}${DEFAULT_POPUP_REDIRECT_URI_PATH}`;
-}
-
-/**
- * Derive the default logoutRedirectUri based on the current URL.
- *
- * @returns Default logout redirect URI
- * @internal
- */
-function deriveDefaultLogoutRedirectUri(): string {
-  if (typeof window === 'undefined') {
-    return DEFAULT_LOGOUT_REDIRECT_URI_PATH;
-  }
-
-  return window.location.origin + DEFAULT_LOGOUT_REDIRECT_URI_PATH;
-}
-
-/**
- * Create a complete LoginConfig with default values.
- * All fields are optional and will be auto-derived if not provided.
- *
- * @param config - Optional login configuration (when provided, must be complete)
- * @returns Complete LoginConfig with defaults applied
- * @internal
- */
-function createDefaultLoginConfig(config?: LoginConfig): LoginConfig {
+function getSandboxLoginConfig(): LoginConfig {
+  const redirectUri = deriveDefaultRedirectUri();
   return {
-    clientId: config?.clientId || deriveDefaultClientId(),
-    redirectUri: config?.redirectUri || deriveDefaultRedirectUri(),
-    popupRedirectUri: config?.popupRedirectUri || deriveDefaultPopupRedirectUri(),
-    scope: config?.scope || DEFAULT_SCOPE,
-    audience: config?.audience || DEFAULT_AUDIENCE,
-    authenticationDomain: config?.authenticationDomain || DEFAULT_AUTH_DOMAIN,
+    clientId: DEFAULT_SANDBOX_CLIENT_ID,
+    redirectUri,
+    popupRedirectUri: redirectUri,
+    scope: DEFAULT_SCOPE,
+    audience: DEFAULT_AUDIENCE,
+    authenticationDomain: DEFAULT_AUTH_DOMAIN,
   };
 }
 
-/**
- * Create a complete LogoutConfig with default values.
- * All fields are optional and will be auto-derived if not provided.
- *
- * @param config - Optional logout configuration (when provided, must be complete)
- * @returns Complete LogoutConfig with defaults applied
- * @internal
- */
-function createDefaultLogoutConfig(config?: LogoutConfig): LogoutConfig {
+function getSandboxLogoutConfig(): LogoutConfig {
+  const logoutRedirectUri = typeof window === 'undefined'
+    ? DEFAULT_LOGOUT_REDIRECT_URI_PATH
+    : window.location.origin + DEFAULT_LOGOUT_REDIRECT_URI_PATH;
   return {
-    clientId: config?.clientId || deriveDefaultClientId(),
-    logoutRedirectUri: config?.logoutRedirectUri || deriveDefaultLogoutRedirectUri(),
-    authenticationDomain: config?.authenticationDomain || DEFAULT_AUTH_DOMAIN,
+    clientId: DEFAULT_SANDBOX_CLIENT_ID,
+    logoutRedirectUri,
+    authenticationDomain: DEFAULT_AUTH_DOMAIN,
   };
 }
 
@@ -557,7 +514,7 @@ export function useLogin(): UseLoginReturn {
     setError(null);
 
     try {
-      const fullConfig = createDefaultLoginConfig(config);
+      const fullConfig = config ?? getSandboxLoginConfig();
       const tokens = await rawLoginWithPopup(fullConfig, options);
       await signInWithTokens(tokens);
     } catch (err) {
@@ -579,7 +536,7 @@ export function useLogin(): UseLoginReturn {
     setError(null);
 
     try {
-      const fullConfig = createDefaultLoginConfig(config);
+      const fullConfig = config ?? getSandboxLoginConfig();
       const tokens = await rawLoginWithEmbedded(fullConfig);
       await signInWithTokens(tokens);
     } catch (err) {
@@ -606,7 +563,7 @@ export function useLogin(): UseLoginReturn {
     setError(null);
 
     try {
-      const fullConfig = createDefaultLoginConfig(config);
+      const fullConfig = config ?? getSandboxLoginConfig();
       await rawLoginWithRedirect(fullConfig, options);
       // Note: The page will redirect, so this code may not run
     } catch (err) {
@@ -739,7 +696,7 @@ export function useLogout(): UseLogoutReturn {
       await signOut({ redirect: false });
 
       // Create full config with defaults
-      const fullConfig = createDefaultLogoutConfig(config);
+      const fullConfig = config ?? getSandboxLogoutConfig();
 
       // Redirect to the auth domain's logout endpoint using the standalone function
       // This clears the upstream session (Auth0/Immutable) so that on next login,

packages/auth-next-client/src/index.ts

@@ -72,4 +72,4 @@ export {
   DEFAULT_POPUP_REDIRECT_URI_PATH,
   DEFAULT_LOGOUT_REDIRECT_URI_PATH,
 } from './constants';
-export { deriveDefaultClientId, deriveDefaultRedirectUri } from '@imtbl/auth-next-server';
+export { deriveDefaultRedirectUri } from './defaultConfig';

packages/auth-next-server/src/config.ts

@@ -8,10 +8,11 @@ import type { ImmutableAuthConfig, ImmutableTokenData, UserInfoResponse } from '
 import { isTokenExpired, refreshAccessToken, extractZkEvmFromIdToken } from './refresh';
 import {
   DEFAULT_AUTH_DOMAIN,
+  DEFAULT_SANDBOX_CLIENT_ID,
   IMMUTABLE_PROVIDER_ID,
   DEFAULT_SESSION_MAX_AGE_SECONDS,
 } from './constants';
-import { deriveDefaultClientId, deriveDefaultRedirectUri } from './defaultConfig';
+import { deriveDefaultRedirectUri } from './defaultConfig';
 
 // Handle ESM/CJS interop - in some bundler configurations, the default export
 // may be nested under a 'default' property
@@ -90,16 +91,10 @@ export function createAuthConfig(config?: ImmutableAuthConfig): NextAuthConfig {
   let redirectUri: string;
 
   if (config) {
-    if (!config.clientId || !config.redirectUri) {
-      throw new Error(
-        '[auth-next-server] When providing config, clientId and redirectUri are required. '
-        + 'Provide full config to avoid conflicts.',
-      );
-    }
     clientId = config.clientId;
     redirectUri = config.redirectUri;
   } else {
-    clientId = deriveDefaultClientId();
+    clientId = DEFAULT_SANDBOX_CLIENT_ID;
     redirectUri = deriveDefaultRedirectUri();
   }
 
@@ -256,7 +251,7 @@ export function createAuthConfig(config?: ImmutableAuthConfig): NextAuthConfig {
                   error: undefined,
                 };
               } catch (error) {
-              // eslint-disable-next-line no-console
+                // eslint-disable-next-line no-console
                 console.error('[auth-next-server] Force refresh failed:', error);
                 return {
                   ...token,
@@ -304,7 +299,7 @@ export function createAuthConfig(config?: ImmutableAuthConfig): NextAuthConfig {
                 error: undefined, // Clear any previous error
               };
             } catch (error) {
-            // eslint-disable-next-line no-console
+              // eslint-disable-next-line no-console
               console.error('[auth-next-server] Token refresh failed:', error);
               return {
                 ...token,

packages/auth-next-server/src/constants.ts

@@ -57,14 +57,14 @@ export const TOKEN_EXPIRY_BUFFER_MS = TOKEN_EXPIRY_BUFFER_SECONDS * 1000;
 export const DEFAULT_SESSION_MAX_AGE_SECONDS = 365 * 24 * 60 * 60;
 
 /**
- * Default Client IDs for auto-detection
- * These are public client IDs for Immutable's default applications
+ * Public client IDs for Immutable's default applications.
+ * auth-next zero-config uses DEFAULT_SANDBOX_CLIENT_ID only.
  */
 export const DEFAULT_PRODUCTION_CLIENT_ID = 'PtQRK4iRJ8GkXjiz6xfImMAYhPhW0cYk';
 export const DEFAULT_SANDBOX_CLIENT_ID = 'mjtCL8mt06BtbxSkp2vbrYStKWnXVZfo';
 
 /**
- * Default redirect URI fallback (will be replaced at runtime with window.location.origin + '/callback')
+ * Default redirect URI path for sandbox zero-config.
  */
 export const DEFAULT_REDIRECT_URI_PATH = '/callback';
 

packages/auth-next-server/src/defaultConfig.ts

@@ -1,31 +1,18 @@
 /**
- * Shared default configuration helpers for auth-next packages.
- * Used by both auth-next-server (config) and auth-next-client (hooks).
+ * Sandbox default configuration for zero-config mode.
+ * When createAuthConfig() is called with no args, these values are used.
+ * Used by auth-next-server (config) and auth-next-client (hooks).
  *
  * @internal
  */
 
-import {
-  DEFAULT_SANDBOX_CLIENT_ID,
-  DEFAULT_REDIRECT_URI_PATH,
-} from './constants';
+import { DEFAULT_REDIRECT_URI_PATH } from './constants';
 
 /**
- * Default client ID for zero-config mode.
- * When no config is provided, we always use sandbox to avoid conflicts.
- * Policy: provide nothing → full sandbox; provide config → provide everything.
+ * Sandbox default redirect URI for zero-config mode.
+ * Server: path only. Client: full URL (origin + path).
  *
- * @returns Sandbox client ID (used when createAuthConfig is called with no args)
- */
-export function deriveDefaultClientId(): string {
-  return DEFAULT_SANDBOX_CLIENT_ID;
-}
-
-/**
- * Derive the default redirectUri based on the current URL.
- * Server-side safe: returns path only when window is undefined.
- *
- * @returns Default redirect URI
+ * @returns Redirect URI path or full URL
  */
 export function deriveDefaultRedirectUri(): string {
   if (typeof window === 'undefined') {

packages/auth-next-server/src/index.ts

@@ -59,7 +59,7 @@ export {
   DEFAULT_TOKEN_EXPIRY_MS,
   TOKEN_EXPIRY_BUFFER_MS,
 } from './constants';
-export { deriveDefaultClientId, deriveDefaultRedirectUri } from './defaultConfig';
+export { deriveDefaultRedirectUri } from './defaultConfig';
 
 // ============================================================================
 // Type exports