fix(auth): use Symbols for callback IDs to resolve Next.js 16 compatibility

Author: mandarini

packages/core/auth-js/src/GoTrueClient.ts

@@ -35,6 +35,7 @@ import {
   decodeJWT,
   deepClone,
   Deferred,
+  generateCallbackId,
   getAlgorithm,
   getCodeChallengeAndMethod,
   getItemAsync,
@@ -48,7 +49,6 @@ import {
   sleep,
   supportsLocalStorage,
   userNotAvailableProxy,
-  uuid,
   validateExp,
 } from './lib/helpers'
 import { memoryLocalStorageAdapter } from './lib/local-storage'
@@ -241,7 +241,7 @@ export default class GoTrueClient {
    */
   protected userStorage: SupportedStorage | null = null
   protected memoryStorage: { [key: string]: string } | null = null
-  protected stateChangeEmitters: Map<string, Subscription> = new Map()
+  protected stateChangeEmitters: Map<string | symbol, Subscription> = new Map()
   protected autoRefreshTicker: ReturnType<typeof setInterval> | null = null
   protected visibilityChangedCallback: (() => Promise<any>) | null = null
   protected refreshingDeferred: Deferred<CallRefreshTokenResult> | null = null
@@ -2161,7 +2161,7 @@ export default class GoTrueClient {
   ): {
     data: { subscription: Subscription }
   } {
-    const id: string = uuid()
+    const id: string | symbol = generateCallbackId()
     const subscription: Subscription = {
       id,
       callback,
@@ -2186,7 +2186,7 @@ export default class GoTrueClient {
     return { data: { subscription } }
   }
 
-  private async _emitInitialSession(id: string): Promise<void> {
+  private async _emitInitialSession(id: string | symbol): Promise<void> {
     return await this._useSession(async (result) => {
       try {
         const {

packages/core/auth-js/src/lib/helpers.ts

@@ -9,46 +9,21 @@ export function expiresAt(expiresIn: number) {
   return timeNow + expiresIn
 }
 
-// Counter for SSR-safe UUID generation
-let ssrUuidCounter = 0
-
 /**
- * Generates a UUID v4 string.
+ * Generates a unique identifier for internal callback subscriptions.
  *
- * This function is SSR-aware to handle Next.js 16 pre-rendering constraints:
- * - In browsers: Uses crypto.randomUUID() or crypto.getRandomValues() for cryptographic randomness
- * - During SSR: Uses a deterministic fallback (timestamp + counter)
+ * This function uses JavaScript Symbols to create guaranteed-unique identifiers
+ * for auth state change callbacks. Symbols are ideal for this use case because:
+ * - They are guaranteed unique by the JavaScript runtime
+ * - They work in all environments (browser, SSR, Node.js)
+ * - They avoid issues with Next.js 16 deterministic rendering requirements
+ * - They are perfect for internal, non-serializable identifiers
  *
- * Note: The SSR fallback is safe because:
- * 1. UUIDs from this function are only used for internal subscription IDs, not security-critical operations
- * 2. During SSR/pre-rendering, auth callbacks don't actually fire
- * 3. Once in the browser, proper cryptographic APIs are always used
+ * Note: This function is only used for internal subscription management,
+ * not for security-critical operations like session tokens.
  */
-export function uuid() {
-  // Modern browsers and Node.js 19+ - use native crypto.randomUUID()
-  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
-    return crypto.randomUUID()
-  }
-
-  // Browsers with crypto.getRandomValues() support
-  if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
-    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
-      const array = new Uint8Array(1)
-      crypto.getRandomValues(array)
-      const r = array[0] % 16
-      const v = c == 'x' ? r : (r & 0x3) | 0x8
-      return v.toString(16)
-    })
-  }
-
-  // SSR/pre-render fallback - deterministic but unique within session
-  // This only generates subscription IDs during pre-render; real UUIDs use crypto in browser
-  const timestamp = Date.now()
-  const counter = ssrUuidCounter++
-  const random1 = Math.floor(timestamp / 1000000) % 10000
-  const random2 = (timestamp % 1000000) % 10000
-
-  return `ssr-${timestamp.toString(16)}-${counter.toString(16)}-${random1.toString(16)}-${random2.toString(16)}`
+export function generateCallbackId(): symbol {
+  return Symbol('auth-callback')
 }
 
 export const isBrowser = () => typeof window !== 'undefined' && typeof document !== 'undefined'

packages/core/auth-js/src/lib/types.ts

@@ -503,9 +503,11 @@ export interface AdminUserAttributes extends Omit<UserAttributes, 'data'> {
 
 export interface Subscription {
   /**
-   * The subscriber UUID. This will be set by the client.
+   * A unique identifier for this subscription, set by the client.
+   * This is an internal identifier used for managing callbacks and should not be
+   * relied upon by application code. Use the unsubscribe() method to remove listeners.
    */
-  id: string
+  id: string | symbol
   /**
    * The function to call every time there is an event. eg: (eventName) => {}
    */