refactor(auth-next-server): enforce zero-config=sandbox, full-config=provide-all

Align with team policy: provide nothing → full sandbox; provide config → provide everything.

Zero config (createAuthConfig with no args):
- Always use sandbox client ID (deriveDefaultClientId returns DEFAULT_SANDBOX_CLIENT_ID)
- No environment detection; avoids conflicts when nothing is configured

Full config (createAuthConfig with config):
- Require clientId and redirectUri when config is provided
- Throw if either is missing to prevent partial config conflicts
- No merging with derived defaults when config is passed

Bug fixes (Cursor Bugbot):
- createDefaultLogoutConfig: forward authenticationDomain to avoid logout failures in custom envs
- wallets-connect-with-nextjs callback: use deriveDefaultClientId() for consistency with login flow

Author: rodrigo-fournier-immutable

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

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

packages/auth-next-client/README.md

@@ -106,7 +106,7 @@ export default function Callback() {
 
 ### Default Auth (Zero Config)
 
-When using `createAuthConfig()` with no args on the server, you can call login/logout with no config—clientId and redirectUri are auto-detected:
+When using `createAuthConfig()` with no args on the server, you can call login/logout with no config—sandbox clientId and redirectUri are used:
 
 ```tsx
 // With default auth - no config needed

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

@@ -117,6 +117,7 @@ function createDefaultLogoutConfig(config?: LogoutConfig): LogoutConfig {
   return {
     clientId: config?.clientId || deriveDefaultClientId(),
     logoutRedirectUri: config?.logoutRedirectUri || deriveDefaultLogoutRedirectUri(),
+    authenticationDomain: config?.authenticationDomain || DEFAULT_AUTH_DOMAIN,
   };
 }
 

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

@@ -60,7 +60,7 @@ export type {
 } from '@imtbl/auth';
 export { MarketingConsentStatus } from '@imtbl/auth';
 
-// Re-export constants for consumer convenience
+// Re-export constants and default config helpers for consumer convenience
 export {
   DEFAULT_AUTH_DOMAIN,
   DEFAULT_AUDIENCE,
@@ -72,3 +72,4 @@ export {
   DEFAULT_POPUP_REDIRECT_URI_PATH,
   DEFAULT_LOGOUT_REDIRECT_URI_PATH,
 } from './constants';
+export { deriveDefaultClientId, deriveDefaultRedirectUri } from '@imtbl/auth-next-server';

packages/auth-next-server/README.md

@@ -81,11 +81,13 @@ AUTH_SECRET=your-secret-key-min-32-characters
 
 ## Default Auth (Zero Config)
 
-For development and quick prototyping, you can use `createAuthConfig()` with no configuration. It auto-detects:
-- `clientId` based on environment (sandbox for localhost/sandbox hostnames or when `NODE_ENV=development`, production otherwise)
-- `redirectUri` from `window.location.origin + '/callback'`
+Policy: **provide nothing → full sandbox; provide config → provide everything.**
 
-> **Server-side detection:** On the server, `window` is unavailable, so sandbox is inferred from `NODE_ENV === 'development'`. This keeps client and server in sync when running locally with `next dev`. For production deployments, pass `clientId` explicitly.
+With no configuration, `createAuthConfig()` uses sandbox defaults:
+- `clientId`: sandbox (public Immutable client ID)
+- `redirectUri`: from `window.location.origin + '/callback'` (path only on server)
+
+When providing config, pass `clientId` and `redirectUri` (and optionally `audience`, `scope`, `authenticationDomain`) to avoid conflicts.
 
 ```typescript
 // lib/auth.ts
@@ -99,10 +101,11 @@ export const { handlers, auth, signIn, signOut } = NextAuth(createAuthConfig());
 With partial overrides:
 
 ```typescript
-// Override only clientId, rest uses defaults
+// With config - provide clientId and redirectUri
 export const { handlers, auth, signIn, signOut } = NextAuth(
   createAuthConfig({
     clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
+    redirectUri: `${process.env.NEXT_PUBLIC_BASE_URL}/callback`,
   }),
 );
 ```
@@ -140,8 +143,8 @@ const { handlers, auth, signIn, signOut } = NextAuth(
 
 | Option                 | Type     | Required | Description                                                              |
 | ---------------------- | -------- | -------- | ------------------------------------------------------------------------ |
-| `clientId`             | `string` | Optional | Your Immutable application client ID (default: auto-detected)             |
-| `redirectUri`          | `string` | Yes      | OAuth redirect URI configured in Immutable Hub                           |
+| `clientId`             | `string` | Yes*     | Your Immutable application client ID (*required when config is provided) |
+| `redirectUri`          | `string` | Yes*     | OAuth redirect URI (*required when config is provided)                   |
 | `audience`             | `string` | No       | OAuth audience (default: `"platform_api"`)                               |
 | `scope`                | `string` | No       | OAuth scopes (default: `"openid profile email offline_access transact"`) |
 | `authenticationDomain` | `string` | No       | Auth domain (default: `"https://auth.immutable.com"`)                    |

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

@@ -58,15 +58,15 @@ async function validateTokens(
 /**
  * Create Auth.js v5 configuration for Immutable authentication.
  *
- * Config is optional - when omitted, sensible defaults are used:
- * - `clientId`: Auto-detected (sandbox for localhost/sandbox hostnames or NODE_ENV=development, production otherwise)
- * - `redirectUri`: Auto-derived from `window.location.origin + '/callback'` (path only on server)
+ * Policy: provide nothing → full sandbox config; provide config → provide everything.
+ * - Zero config: sandbox clientId, auto-derived redirectUri. No conflicts.
+ * - With config: clientId and redirectUri required. Pass full config to avoid conflicts.
  *
- * @param config - Optional configuration. All fields can be overridden.
+ * @param config - Optional. When omitted, uses sandbox defaults. When provided, clientId and redirectUri are required.
  *
  * @example
  * ```typescript
- * // Zero config - only AUTH_SECRET required in .env
+ * // Zero config - sandbox, only AUTH_SECRET required in .env
  * import NextAuth from "next-auth";
  * import { createAuthConfig } from "@imtbl/auth-next-server";
  *
@@ -75,7 +75,7 @@ async function validateTokens(
  *
  * @example
  * ```typescript
- * // With custom config
+ * // With config - provide clientId and redirectUri (and optionally audience, scope, authenticationDomain)
  * import NextAuth from "next-auth";
  * import { createAuthConfig } from "@imtbl/auth-next-server";
  *
@@ -85,9 +85,24 @@ async function validateTokens(
  * }));
  * ```
  */
-export function createAuthConfig(config?: Partial<ImmutableAuthConfig>): NextAuthConfig {
-  const clientId = config?.clientId || deriveDefaultClientId();
-  const redirectUri = config?.redirectUri || deriveDefaultRedirectUri();
+export function createAuthConfig(config?: ImmutableAuthConfig): NextAuthConfig {
+  let clientId: string;
+  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();
+    redirectUri = deriveDefaultRedirectUri();
+  }
+
   const resolvedConfig: ImmutableAuthConfig = {
     clientId,
     redirectUri,

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

@@ -6,37 +6,19 @@
  */
 
 import {
-  DEFAULT_PRODUCTION_CLIENT_ID,
   DEFAULT_SANDBOX_CLIENT_ID,
   DEFAULT_REDIRECT_URI_PATH,
 } from './constants';
 
 /**
- * Detect if we're in a sandbox/test environment based on the current URL.
- * Client-side: checks if the hostname includes 'sandbox' or 'localhost'.
- * Server-side: uses NODE_ENV === 'development' as fallback so server and client
- * use the same sandbox client ID when running locally (e.g. `next dev`).
+ * 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.
  *
- * @returns true if in sandbox environment, false otherwise
- */
-export function isSandboxEnvironment(): boolean {
-  if (typeof window === 'undefined') {
-    // Server-side: NODE_ENV is set by Next.js (development in `next dev`, production in `next build` + `next start`)
-    return process.env.NODE_ENV === 'development';
-  }
-
-  const hostname = window.location.hostname.toLowerCase();
-  return hostname.includes('sandbox') || hostname.includes('localhost');
-}
-
-/**
- * Derive the default clientId based on the environment.
- * Uses public Immutable client IDs for sandbox and production.
- *
- * @returns Default client ID for the current environment
+ * @returns Sandbox client ID (used when createAuthConfig is called with no args)
  */
 export function deriveDefaultClientId(): string {
-  return isSandboxEnvironment() ? DEFAULT_SANDBOX_CLIENT_ID : DEFAULT_PRODUCTION_CLIENT_ID;
+  return DEFAULT_SANDBOX_CLIENT_ID;
 }
 
 /**

packages/passport/sdk-sample-app/src/lib/immutable-auth.server.ts

@@ -37,8 +37,7 @@ export const prodAuth = NextAuth({
 });
 
 // Default auth (zero config): uses createAuthConfig() with no args.
-// Auto-detects sandbox (NODE_ENV=development) or production client ID.
-// Enables testing default auth with wallet and transactions.
+// Always uses sandbox. Enables testing default auth with wallet and transactions.
 export const defaultAuth = NextAuth({
   ...createAuthConfig(),
   ...sharedAuthOptions,

packages/passport/sdk-sample-app/src/types/index.ts

@@ -11,7 +11,7 @@ export enum EnvironmentNames {
   DEV = 'dev',
   SANDBOX = 'sandbox',
   PRODUCTION = 'production',
-  /** Zero-config auth: uses createAuthConfig() with no args, auto-detects sandbox/production */
+  /** Zero-config auth: uses createAuthConfig() with no args, always sandbox */
   DEFAULT = 'default',
 }