@ic-reactor/react 3.7.0 → 3.8.0

package/src/auth/authentication-manager.ts

@@ -5,7 +5,7 @@ import type {
   AuthState,
   AuthenticationClientOptions,
   AuthenticationSignInOptions,
-} from "./types"
+} from "./types.js"
 import { ClientManager, isDev } from "@ic-reactor/core"
 
 import { safeGetCanisterEnv } from "@icp-sdk/core/agent/canister-env"
@@ -13,12 +13,16 @@ import {
   IC_INTERNET_IDENTITY_PROVIDER,
   INTERNET_IDENTITY_PROVIDER_ENV_KEY,
   localInternetIdentityProvider,
-} from "./constants"
+} from "./constants.js"
 
-export interface AuthenticationManagerParameters {
+export interface AuthenticationManagerParameters extends AuthenticationClientOptions {
   clientManager: ClientManager
+  /**
+   * Bring your own client instance. When provided, IC Reactor never constructs
+   * one and never applies the options below to it.
+   */
   authClient?: AuthClientLike
-  identityProvider?: string | URL
+  /** Canister ID of a locally deployed Internet Identity. */
   internetIdentityId?: string
 }
 
@@ -26,8 +30,6 @@ type AuthClientConstructor = {
   new (options?: AuthenticationClientOptions): AuthClientLike
 }
 
-const AUTH_CLIENT_MODULE = "@icp-sdk/auth/client"
-
 /**
  * Manages Internet Identity sign-in, session restoration, and authentication
  * state for a {@link ClientManager}.
@@ -49,6 +51,7 @@ export class AuthenticationManager {
     AuthClientConstructor | undefined
   >
   private authModuleMissing = false
+  private authClientOptions?: AuthenticationClientOptions
   private authStateValue: AuthState = {
     identity: null,
     isAuthenticating: false,
@@ -57,6 +60,7 @@ export class AuthenticationManager {
   }
   private readonly identityProvider?: string | URL
   private readonly internetIdentityId?: string
+  private readonly defaultClientOptions: AuthenticationClientOptions
   public readonly clientManager: ClientManager
 
   /** The current authentication state. */
@@ -69,6 +73,7 @@ export class AuthenticationManager {
     authClient,
     identityProvider,
     internetIdentityId,
+    ...clientOptions
   }: AuthenticationManagerParameters) {
     this.clientManager = clientManager
     const canisterEnv =
@@ -82,6 +87,7 @@ export class AuthenticationManager {
       canisterEnv?.["internet_identity"] ||
       canisterEnv?.["PUBLIC_CANISTER_ID:internet_identity"] ||
       canisterEnv?.["CANISTER_ID_INTERNET_IDENTITY"]
+    this.defaultClientOptions = clientOptions
 
     if (authClient) {
       this.authClientWasProvided = true
@@ -111,25 +117,37 @@ export class AuthenticationManager {
   }
 
   /**
-   * Preloads and creates an AuthClient before a user gesture is needed.
+   * Preloads the auth module and creates an AuthClient ahead of time.
+   *
+   * Call (and await) this before wiring up a login button: it makes
+   * {@link login} and {@link IdentityAttributesManager.request} able to open
+   * the identity provider synchronously inside the click handler, which is
+   * what browser popup blockers and the ICRC-29 transport require.
    */
   public async prepareClient(options?: AuthenticationClientOptions) {
-    const clientOptions = getAuthClientOptions({
-      ...options,
-      identityProvider:
-        options?.identityProvider ?? this.getDefaultIdentityProvider(),
-    })
+    const clientOptions = this.resolveClientOptions(options)
 
-    if (
-      this.authClient &&
-      (!this.shouldRecreateClient(clientOptions) || this.authClientWasProvided)
-    ) {
+    if (this.authClient && !this.shouldRecreateClient(clientOptions)) {
       return this.authClient
     }
 
     return this.initializeClient(clientOptions)
   }
 
+  /**
+   * Returns an AuthClient without awaiting, or `undefined` when the auth
+   * module has not been loaded yet.
+   *
+   * Callers that must stay inside a user gesture use this instead of
+   * {@link ensureClient}; awaiting anything before opening the identity
+   * provider window loses the gesture.
+   */
+  public getPreparedClient(
+    options?: AuthenticationClientOptions
+  ): AuthClientLike | undefined {
+    return this.ensurePreparedClient(this.resolveClientOptions(options))
+  }
+
   public authenticate = async (): Promise<Identity | undefined> => {
     if (this.authState.isAuthenticated) {
       return this.authState.identity || undefined
@@ -157,9 +175,7 @@ export class AuthenticationManager {
       try {
         if (!this.authClient) {
           const authClient = await this.initializeClient(
-            getAuthClientOptions({
-              identityProvider: this.getDefaultIdentityProvider(),
-            })
+            this.resolveClientOptions()
           )
           if (!authClient) {
             this.updateState({ isAuthenticating: false })
@@ -168,7 +184,12 @@ export class AuthenticationManager {
         }
         const identity = await this.authClient!.getIdentity()
         const isAuthenticated = await this.authClient!.isAuthenticated()
-        this.clientManager.updateAgent(identity)
+        // Restoring an anonymous session is the common first-load case; pushing
+        // it through updateAgent would invalidate the whole query cache on
+        // every mount for nothing.
+        if (isAuthenticated || !identity.getPrincipal().isAnonymous()) {
+          this.clientManager.updateAgent(identity)
+        }
         this.updateState({
           identity,
           isAuthenticated,
@@ -191,13 +212,10 @@ export class AuthenticationManager {
     let didCompleteSignIn = false
 
     try {
-      const identityProvider =
-        loginOptions?.identityProvider || this.getDefaultIdentityProvider()
-      const authClientOptions = getAuthClientOptions({
-        ...loginOptions,
-        identityProvider,
-      })
+      const authClientOptions = this.resolveClientOptions(loginOptions)
 
+      // Stays synchronous when `prepareClient()` has already loaded the auth
+      // module, so `signIn()` still runs inside the caller's click handler.
       if (!this.ensurePreparedClient(authClientOptions)) {
         await this.initializeClient(authClientOptions)
       }
@@ -208,7 +226,7 @@ export class AuthenticationManager {
 
       if (!this.authClient) {
         throw new Error(
-          "Authentication module is missing or failed to initialize. To use login, please install the auth package: npm install @icp-sdk/auth"
+          "Authentication module is missing or failed to initialize. To use login, install the optional auth peer: npm install @icp-sdk/auth. If it is already installed and your bundler could not resolve it, pass a pre-constructed client instead: new AuthenticationManager({ clientManager, authClient: new AuthClient(...) })"
         )
       }
 
@@ -251,7 +269,7 @@ export class AuthenticationManager {
   public logout = async (options?: { returnTo?: string }) => {
     if (!this.authClient) {
       throw new Error(
-        "Authentication module is missing or failed to initialize. To use logout, please install the auth package: npm install @icp-sdk/auth"
+        "Authentication module is missing or failed to initialize. To use logout, install the optional auth peer: npm install @icp-sdk/auth. If it is already installed and your bundler could not resolve it, pass a pre-constructed client instead: new AuthenticationManager({ clientManager, authClient: new AuthClient(...) })"
       )
     }
     this.updateState({ isAuthenticating: true, error: undefined })
@@ -275,6 +293,7 @@ export class AuthenticationManager {
     }
 
     this.authClient = new AuthClient(options)
+    this.authClientOptions = options
     return this.authClient
   }
 
@@ -284,7 +303,7 @@ export class AuthenticationManager {
   ): Promise<Identity> {
     if (!this.authClient) {
       throw new Error(
-        "Authentication module is missing or failed to initialize. To use login, please install the auth package: npm install @icp-sdk/auth"
+        "Authentication module is missing or failed to initialize. To use login, install the optional auth peer: npm install @icp-sdk/auth. If it is already installed and your bundler could not resolve it, pass a pre-constructed client instead: new AuthenticationManager({ clientManager, authClient: new AuthClient(...) })"
       )
     }
 
@@ -309,10 +328,7 @@ export class AuthenticationManager {
   private ensurePreparedClient(
     options?: AuthenticationClientOptions
   ): AuthClientLike | undefined {
-    if (
-      this.authClient &&
-      (!this.shouldRecreateClient(options) || this.authClientWasProvided)
-    ) {
+    if (this.authClient && !this.shouldRecreateClient(options)) {
       return this.authClient
     }
 
@@ -322,11 +338,41 @@ export class AuthenticationManager {
     }
 
     this.authClient = new AuthClient(options)
+    this.authClientOptions = options
     return this.authClient
   }
 
+  /**
+   * Only rebuild the client when the effective options actually changed.
+   *
+   * Recreating on every call would discard the client warmed up by
+   * `prepareClient()` and register a duplicate sign-out callback on the
+   * shared IdleManager singleton each time.
+   */
   private shouldRecreateClient(options?: AuthenticationClientOptions): boolean {
-    return !this.authClientWasProvided && hasAuthClientOptions(options)
+    if (this.authClientWasProvided) {
+      return false
+    }
+    return !isSameAuthClientOptions(this.authClientOptions, options)
+  }
+
+  /**
+   * Merges constructor-level defaults with per-call overrides and fills in the
+   * network-appropriate identity provider.
+   */
+  private resolveClientOptions(
+    options?: AuthenticationClientOptions
+  ): AuthenticationClientOptions {
+    const merged = getAuthClientOptions({
+      ...this.defaultClientOptions,
+      ...options,
+    })
+
+    return {
+      ...merged,
+      identityProvider:
+        merged?.identityProvider ?? this.getDefaultIdentityProvider(),
+    }
   }
 
   private async syncStateFromClient(revision = this.authStateRevision) {
@@ -350,11 +396,7 @@ export class AuthenticationManager {
 
   /** @internal Used by IdentityAttributesManager. */
   public async ensureClient(options?: AuthenticationClientOptions) {
-    const clientOptions = getAuthClientOptions({
-      ...options,
-      identityProvider:
-        options?.identityProvider ?? this.getDefaultIdentityProvider(),
-    })
+    const clientOptions = this.resolveClientOptions(options)
     if (!this.ensurePreparedClient(clientOptions)) {
       await this.initializeClient(clientOptions)
     }
@@ -407,11 +449,12 @@ export class AuthenticationManager {
     }
 
     if (!this.authClientConstructorPromise) {
-      // Keep the optional auth peer out of non-auth bundles. Vite/Rollup/esbuild
-      // can otherwise try to resolve this package even when auth APIs are unused.
-      this.authClientConstructorPromise = import(
-        /* @vite-ignore */ AUTH_CLIENT_MODULE
-      )
+      // The specifier must stay a literal: a variable specifier (or /* @vite-ignore */)
+      // makes bundlers skip this import entirely, so the bare specifier survives into
+      // the browser, where it cannot be resolved without an import map and every login
+      // path fails. A literal lets Vite/Rollup/webpack code-split the optional peer,
+      // and lets them tree-shake it away for apps that never reference this class.
+      this.authClientConstructorPromise = import("@icp-sdk/auth/client")
         .then((authModule) => {
           const AuthClient = (
             authModule as { AuthClient?: AuthClientConstructor }
@@ -452,6 +495,12 @@ function getAuthClientOptions(
     identityProvider: options.identityProvider,
     windowOpenerFeatures: options.windowOpenerFeatures,
     openIdProvider: getAuthClientOpenIdProvider(options.openIdProvider),
+    derivationOrigin: options.derivationOrigin,
+    storage: options.storage,
+    keyType: options.keyType,
+    idleOptions: options.idleOptions,
+    identity: options.identity,
+    transport: options.transport,
   }
 }
 
@@ -465,11 +514,34 @@ function getAuthClientOpenIdProvider(
     : undefined
 }
 
-function hasAuthClientOptions(options?: AuthenticationClientOptions): boolean {
-  return Boolean(
-    options?.identityProvider ||
-    options?.windowOpenerFeatures ||
-    options?.openIdProvider
+/**
+ * Compares the options two AuthClients would be built from. Object-valued
+ * options (`storage`, `identity`, `idleOptions`) are compared by reference,
+ * which is what module-scoped configuration produces.
+ */
+function isSameAuthClientOptions(
+  current?: AuthenticationClientOptions,
+  next?: AuthenticationClientOptions
+): boolean {
+  if (current === next) {
+    return true
+  }
+  if (!current || !next) {
+    return false
+  }
+
+  return (
+    String(current.identityProvider ?? "") ===
+      String(next.identityProvider ?? "") &&
+    current.windowOpenerFeatures === next.windowOpenerFeatures &&
+    current.openIdProvider === next.openIdProvider &&
+    String(current.derivationOrigin ?? "") ===
+      String(next.derivationOrigin ?? "") &&
+    current.storage === next.storage &&
+    current.keyType === next.keyType &&
+    current.idleOptions === next.idleOptions &&
+    current.identity === next.identity &&
+    current.transport === next.transport
   )
 }
 

package/src/auth/createIdentityAttributeHooks.ts

@@ -1,10 +1,10 @@
 import { useCallback, useState } from "react"
-import type { IdentityAttributesManager } from "./identity-attributes-manager"
+import type { IdentityAttributesManager } from "./identity-attributes-manager.js"
 import type {
   IdentityAttributeResult,
   RequestIdentityAttributesParameters,
   RequestOpenIdIdentityAttributesParameters,
-} from "./types"
+} from "./types.js"
 
 export interface UseIdentityAttributesReturn {
   requestAttributes: (

package/src/auth/identity-attributes-manager.ts

@@ -1,25 +1,33 @@
 import type {
-  AuthenticationClientOptions,
+  AuthClientLike,
+  IdentityAttributeNonce,
   IdentityAttributeResult,
   RequestIdentityAttributesParameters,
   RequestOpenIdIdentityAttributesParameters,
-} from "./types"
+} from "./types.js"
 
-import { AuthenticationManager } from "./authentication-manager"
+import { AuthenticationManager } from "./authentication-manager.js"
 import {
   decodeIdentityAttributeValues,
   identityAttributeKeys,
   normalizeSignedIdentityAttributes,
-} from "./identity-attributes"
+} from "./identity-attributes.js"
 
 /**
  * Requests and decodes signed identity attributes for an authenticated
  * Internet Identity session.
  *
+ * Await `authentication.prepareClient()` once during startup (the `useAuth`
+ * hook already does) so that {@link request} can open the identity provider
+ * window synchronously from a click handler.
+ *
  * @example
  * ```ts
  * const attributes = new IdentityAttributesManager(authentication)
- * const result = await attributes.request({ keys: ["name"] })
+ * const result = await attributes.request({
+ *   keys: ["name"],
+ *   nonce: () => fetchNonceFromCanister(),
+ * })
  * ```
  */
 export class IdentityAttributesManager {
@@ -28,37 +36,40 @@ export class IdentityAttributesManager {
   public request = async ({
     keys,
     nonce,
-    identityProvider,
-    openIdProvider,
-    windowOpenerFeatures,
     signIn = true,
     maxTimeToLive,
     targets,
+    ...clientOptions
   }: RequestIdentityAttributesParameters): Promise<IdentityAttributeResult> => {
-    const authClient = await this.authentication.ensureClient(
-      getAuthClientOptions({
-        identityProvider,
-        windowOpenerFeatures,
-        openIdProvider,
-      })
-    )
+    // Nothing may be awaited before `requestAttributes` / `signIn` are invoked:
+    // the ICRC-29 transport only opens the identity provider window while the
+    // browser still considers us inside the user gesture. `getPreparedClient`
+    // is synchronous whenever `prepareClient()` has run.
+    const preparedClient = this.authentication.getPreparedClient(clientOptions)
+    const authClient =
+      preparedClient ?? (await this.authentication.ensureClient(clientOptions))
 
     if (!authClient) {
       throw new Error(
-        "Authentication module is missing or failed to initialize. To request identity attributes, please install @icp-sdk/auth v7 or provide a compatible authClient."
+        "Authentication module is missing or failed to initialize. To request identity attributes, please install @icp-sdk/auth v7 or later, or provide a compatible authClient."
       )
     }
 
     this.authentication.setAuthenticating()
 
     try {
+      // `signIn` first: it opens the transport channel synchronously, and the
+      // attribute request then reuses that same channel and window.
       const identityPromise = signIn
         ? this.authentication.signInOrRecoverIdentity({
             maxTimeToLive,
             targets,
           })
         : Promise.resolve(authClient.getIdentity())
-      const requestPromise = authClient.requestAttributes({ keys, nonce })
+      const requestPromise = authClient.requestAttributes({
+        keys,
+        nonce: toAuthClientNonce(authClient, nonce),
+      })
 
       const [signedAttributes, identity] = await Promise.all([
         requestPromise,
@@ -88,40 +99,38 @@ export class IdentityAttributesManager {
     }
   }
 
-  public requestOpenId = async ({
-    nonce,
-    openIdProvider,
+  public requestOpenId = ({
     keys,
-    identityProvider,
-    windowOpenerFeatures,
-    signIn,
-    maxTimeToLive,
-    targets,
+    openIdProvider,
+    ...rest
   }: RequestOpenIdIdentityAttributesParameters): Promise<IdentityAttributeResult> => {
+    // Called (not awaited) synchronously so the user gesture is preserved.
     return this.request({
-      keys: identityAttributeKeys({ openIdProvider, keys }),
-      nonce,
-      identityProvider,
+      ...rest,
       openIdProvider,
-      windowOpenerFeatures,
-      signIn,
-      maxTimeToLive,
-      targets,
+      keys: identityAttributeKeys({ openIdProvider, keys }),
     })
   }
 }
 
-function getAuthClientOptions(
-  options: AuthenticationClientOptions
-): AuthenticationClientOptions {
-  return {
-    identityProvider: options.identityProvider,
-    windowOpenerFeatures: options.windowOpenerFeatures,
-    openIdProvider:
-      options.openIdProvider === "google" ||
-      options.openIdProvider === "apple" ||
-      options.openIdProvider === "microsoft"
-        ? options.openIdProvider
-        : undefined,
+/**
+ * Bridges the two `@icp-sdk/auth` nonce contracts.
+ *
+ * v8 takes `() => Promise<Uint8Array>` (it journals the value so a redirect
+ * flow replays the same bytes); v7 takes `Uint8Array | Promise<Uint8Array>`.
+ * Both open the transport channel synchronously for the deferred forms, so we
+ * always hand over the deferred shape the installed client understands.
+ * `memoize` only exists from v8 onwards, which makes it a reliable marker.
+ */
+function toAuthClientNonce(
+  authClient: AuthClientLike,
+  nonce: IdentityAttributeNonce
+): Uint8Array | Promise<Uint8Array> | (() => Promise<Uint8Array>) {
+  const supportsNonceThunk = typeof authClient.memoize === "function"
+
+  if (supportsNonceThunk) {
+    return () => Promise.resolve(typeof nonce === "function" ? nonce() : nonce)
   }
+
+  return Promise.resolve(typeof nonce === "function" ? nonce() : nonce)
 }

package/src/auth/identity-attributes.ts

@@ -4,8 +4,8 @@ import type {
   IdentityAttributeOpenIdProvider,
   IdentityAttributeValues,
   SignedIdentityAttributes,
-} from "./types"
-import { IC_INTERNET_IDENTITY_PROVIDER } from "./constants"
+} from "./types.js"
+import { IC_INTERNET_IDENTITY_PROVIDER } from "./constants.js"
 
 export const IDENTITY_ATTRIBUTES_PROVIDER = IC_INTERNET_IDENTITY_PROVIDER
 

package/src/auth/index.ts

@@ -1,7 +1,7 @@
-export * from "./authentication-manager"
-export * from "./identity-attributes-manager"
-export * from "./identity-attributes"
-export * from "./constants"
-export * from "./types"
-export * from "../hooks/createAuthHooks"
-export * from "./createIdentityAttributeHooks"
+export * from "./authentication-manager.js"
+export * from "./identity-attributes-manager.js"
+export * from "./identity-attributes.js"
+export * from "./constants.js"
+export * from "./types.js"
+export * from "../hooks/createAuthHooks.js"
+export * from "./createIdentityAttributeHooks.js"