@ic-reactor/react 3.6.0 → 3.8.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ic-reactor/react",
-  "version": "3.6.0",
-  "description": "IC Reactor React Library",
+  "version": "3.8.0",
+  "description": "IC Reactor React library for building Internet Computer apps",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,12 +12,17 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "src",
-    "README.md"
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "!**/*.tsbuildinfo",
+    "README.md",
+    "llms.txt"
   ],
   "repository": {
     "type": "git",
@@ -27,7 +32,7 @@
   "bugs": {
     "url": "https://github.com/B3Pay/ic-reactor/issues"
   },
-  "homepage": "https://ic-reactor.dev",
+  "homepage": "https://ic-reactor.b3pay.net/v3/packages/react",
   "keywords": [
     "internet-computer",
     "icp",
@@ -37,40 +42,39 @@
     "web3",
     "blockchain",
     "canister",
-    "tanstack-query"
+    "tanstack-query",
+    "ic-reactor",
+    "llms",
+    "ai-friendly"
   ],
   "author": "Behrad Deylami",
   "license": "MIT",
   "dependencies": {
-    "@ic-reactor/core": "^3.6.0"
+    "@ic-reactor/core": "^3.8.0"
   },
   "peerDependencies": {
-    "@icp-sdk/auth": "^7.0.0",
+    "@icp-sdk/auth": "^7.1.0 || ^8.0.0",
+    "@icp-sdk/core": "^6.0.0",
     "@tanstack/react-query": "^5.0.0",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0"
   },
-  "peerDependenciesMeta": {
-    "@icp-sdk/auth": {
-      "optional": true
-    }
-  },
   "devDependencies": {
-    "@icp-sdk/auth": "^7.0.0",
-    "@icp-sdk/core": "^5.4.0",
+    "@icp-sdk/auth": "^8.0.0",
+    "@icp-sdk/core": "^6.0.0",
     "@size-limit/preset-small-lib": "^12.1.0",
-    "@tanstack/react-query": "^5.100.10",
+    "@tanstack/react-query": "^5.101.4",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
-    "@types/react": "^19.2.14",
+    "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "fake-indexeddb": "^6.2.5",
     "jsdom": "^29.1.1",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "size-limit": "^12.1.0",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.10"
   },
   "size-limit": [
     {
@@ -82,14 +86,21 @@
         "react",
         "react-dom",
         "@ic-reactor/core",
-        "@tanstack/react-query"
+        "@tanstack/react-query",
+        "@icp-sdk/auth"
       ]
     }
   ],
+  "peerDependenciesMeta": {
+    "@icp-sdk/auth": {
+      "optional": true
+    }
+  },
   "scripts": {
-    "build": "tsc",
+    "build": "rm -rf dist tsconfig.tsbuildinfo && tsc",
     "test": "vitest run",
     "size": "size-limit",
-    "analyze": "size-limit"
+    "analyze": "size-limit",
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json"
   }
 }

package/src/auth/authentication-manager.ts

@@ -0,0 +1,591 @@
+import type { Identity } from "@icp-sdk/core/agent"
+import type {
+  AuthClientLike,
+  AuthClientSignInOptions,
+  AuthState,
+  AuthenticationClientOptions,
+  AuthenticationSignInOptions,
+} from "./types.js"
+import { ClientManager, isDev } from "@ic-reactor/core"
+
+import { safeGetCanisterEnv } from "@icp-sdk/core/agent/canister-env"
+import {
+  IC_INTERNET_IDENTITY_PROVIDER,
+  INTERNET_IDENTITY_PROVIDER_ENV_KEY,
+  localInternetIdentityProvider,
+} from "./constants.js"
+
+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
+  /** Canister ID of a locally deployed Internet Identity. */
+  internetIdentityId?: string
+}
+
+type AuthClientConstructor = {
+  new (options?: AuthenticationClientOptions): AuthClientLike
+}
+
+/**
+ * Manages Internet Identity sign-in, session restoration, and authentication
+ * state for a {@link ClientManager}.
+ *
+ * @example
+ * ```ts
+ * const authentication = new AuthenticationManager({ clientManager })
+ * const identity = await authentication.authenticate()
+ * ```
+ */
+export class AuthenticationManager {
+  private authClient?: AuthClientLike
+  private authPromise?: Promise<Identity | undefined>
+  private authClientWasProvided = false
+  private authStateRevision = 0
+  private authStateSubscribers: Array<(state: AuthState) => void> = []
+  private authClientConstructor?: AuthClientConstructor
+  private authClientConstructorPromise?: Promise<
+    AuthClientConstructor | undefined
+  >
+  private authModuleMissing = false
+  private authClientOptions?: AuthenticationClientOptions
+  private authStateValue: AuthState = {
+    identity: null,
+    isAuthenticating: false,
+    isAuthenticated: false,
+    error: undefined,
+  }
+  private readonly identityProvider?: string | URL
+  private readonly internetIdentityId?: string
+  private readonly defaultClientOptions: AuthenticationClientOptions
+  public readonly clientManager: ClientManager
+
+  /** The current authentication state. */
+  public get authState(): AuthState {
+    return this.authStateValue
+  }
+
+  constructor({
+    clientManager,
+    authClient,
+    identityProvider,
+    internetIdentityId,
+    ...clientOptions
+  }: AuthenticationManagerParameters) {
+    this.clientManager = clientManager
+    const canisterEnv =
+      typeof window !== "undefined" ? getAuthenticationCanisterEnv() : undefined
+    this.identityProvider =
+      identityProvider ||
+      canisterEnv?.[INTERNET_IDENTITY_PROVIDER_ENV_KEY] ||
+      canisterEnv?.["PUBLIC_INTERNET_IDENTITY_PROVIDER"]
+    this.internetIdentityId =
+      internetIdentityId ||
+      canisterEnv?.["internet_identity"] ||
+      canisterEnv?.["PUBLIC_CANISTER_ID:internet_identity"] ||
+      canisterEnv?.["CANISTER_ID_INTERNET_IDENTITY"]
+    this.defaultClientOptions = clientOptions
+
+    if (authClient) {
+      this.authClientWasProvided = true
+      this.authClient = authClient
+      this.syncStateFromClient(this.authStateRevision).catch((error) => {
+        this.updateState({ error: error as Error, isAuthenticating: false })
+      })
+    } else if (typeof window !== "undefined") {
+      this.loadAuthClientConstructor().catch(() => {
+        // Optional auth support is reported when an auth method is used.
+      })
+    }
+  }
+
+  /** @internal Used by IdentityAttributesManager. */
+  public get client() {
+    return this.authClient
+  }
+
+  public subscribeAuthState(callback: (state: AuthState) => void) {
+    this.authStateSubscribers.push(callback)
+    return () => {
+      this.authStateSubscribers = this.authStateSubscribers.filter(
+        (subscriber) => subscriber !== callback
+      )
+    }
+  }
+
+  /**
+   * 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 = this.resolveClientOptions(options)
+
+    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
+    }
+    if (this.authPromise) {
+      return this.authPromise
+    }
+    if (this.authModuleMissing) {
+      return undefined
+    }
+
+    this.authPromise = (async () => {
+      if (isDev() && typeof window !== "undefined") {
+        console.info(
+          `%cic-reactor:%c Authenticating...`,
+          "color: #3b82f6; font-weight: bold",
+          "color: inherit",
+          {
+            network: this.clientManager.network,
+            authClient: this.authClient ? "Shared Instance" : "Dynamic Import",
+          }
+        )
+      }
+      this.updateState({ isAuthenticating: true })
+      try {
+        if (!this.authClient) {
+          const authClient = await this.initializeClient(
+            this.resolveClientOptions()
+          )
+          if (!authClient) {
+            this.updateState({ isAuthenticating: false })
+            return undefined
+          }
+        }
+        const identity = await this.authClient!.getIdentity()
+        const isAuthenticated = await this.authClient!.isAuthenticated()
+        // 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,
+          isAuthenticating: false,
+        })
+        return identity
+      } catch (error) {
+        this.updateState({ error: error as Error, isAuthenticating: false })
+        console.error("Authentication failed:", error)
+        throw error
+      } finally {
+        this.authPromise = undefined
+      }
+    })()
+
+    return this.authPromise
+  }
+
+  public login = async (loginOptions?: AuthenticationSignInOptions) => {
+    let didCompleteSignIn = false
+
+    try {
+      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)
+      }
+
+      if (!this.authClient) {
+        await this.authenticate()
+      }
+
+      if (!this.authClient) {
+        throw new Error(
+          "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(...) })"
+        )
+      }
+
+      this.updateState({ isAuthenticating: true, error: undefined })
+      const identity = await this.signInOrRecoverIdentity(
+        getSignInOptions(loginOptions)
+      )
+
+      if (!this.clientManager.agentState.isInitialized) {
+        await this.clientManager.initializeAgent()
+      }
+
+      this.clientManager.updateAgent(identity)
+      this.updateState({
+        identity,
+        isAuthenticated: true,
+        isAuthenticating: false,
+      })
+      didCompleteSignIn = true
+
+      try {
+        await loginOptions?.onSuccess?.()
+      } catch (callbackError) {
+        this.updateState({ error: callbackError as Error })
+        await loginOptions?.onError?.((callbackError as Error).message)
+        throw callbackError
+      }
+    } catch (error) {
+      if (!didCompleteSignIn) {
+        await loginOptions?.onError?.((error as Error).message)
+        this.updateState({
+          error: error as Error,
+          isAuthenticating: false,
+        })
+      }
+      throw error
+    }
+  }
+
+  public logout = async (options?: { returnTo?: string }) => {
+    if (!this.authClient) {
+      throw new Error(
+        "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 })
+    await this.authClient.signOut(options)
+    const identity = await this.authClient.getIdentity()
+    this.clientManager.updateAgent(identity)
+    this.updateState({
+      identity,
+      isAuthenticated: false,
+      isAuthenticating: false,
+    })
+  }
+
+  private async initializeClient(
+    options?: AuthenticationClientOptions
+  ): Promise<AuthClientLike | undefined> {
+    const AuthClient = await this.loadAuthClientConstructor()
+
+    if (!AuthClient) {
+      return undefined
+    }
+
+    this.authClient = new AuthClient(options)
+    this.authClientOptions = options
+    return this.authClient
+  }
+
+  /** @internal Used by IdentityAttributesManager. */
+  public async signInOrRecoverIdentity(
+    options?: AuthClientSignInOptions
+  ): Promise<Identity> {
+    if (!this.authClient) {
+      throw new Error(
+        "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(...) })"
+      )
+    }
+
+    try {
+      return await this.authClient.signIn(options)
+    } catch (error) {
+      const identity = await Promise.resolve(
+        this.authClient.getIdentity()
+      ).catch(() => null)
+      const isAuthenticated = await Promise.resolve(
+        this.authClient.isAuthenticated()
+      ).catch(() => false)
+
+      if (identity && isAuthenticated) {
+        return identity
+      }
+
+      throw error
+    }
+  }
+
+  private ensurePreparedClient(
+    options?: AuthenticationClientOptions
+  ): AuthClientLike | undefined {
+    if (this.authClient && !this.shouldRecreateClient(options)) {
+      return this.authClient
+    }
+
+    const AuthClient = this.authClientConstructor
+    if (!AuthClient || this.authClientWasProvided) {
+      return undefined
+    }
+
+    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 {
+    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) {
+    if (!this.authClient) {
+      return
+    }
+
+    const identity = await this.authClient.getIdentity()
+    const isAuthenticated = await this.authClient.isAuthenticated()
+    if (revision !== this.authStateRevision) {
+      return
+    }
+    this.clientManager.updateAgent(identity)
+    this.updateState({
+      identity,
+      isAuthenticated,
+      isAuthenticating: false,
+      error: undefined,
+    })
+  }
+
+  /** @internal Used by IdentityAttributesManager. */
+  public async ensureClient(options?: AuthenticationClientOptions) {
+    const clientOptions = this.resolveClientOptions(options)
+    if (!this.ensurePreparedClient(clientOptions)) {
+      await this.initializeClient(clientOptions)
+    }
+    return this.authClient
+  }
+
+  /** @internal Used by IdentityAttributesManager. */
+  public async commitIdentity(identity: Identity, isAuthenticated: boolean) {
+    if (!this.clientManager.agentState.isInitialized) {
+      await this.clientManager.initializeAgent()
+    }
+    this.clientManager.updateAgent(identity)
+    this.updateState({ identity, isAuthenticated, isAuthenticating: false })
+  }
+
+  /** @internal Used by IdentityAttributesManager. */
+  public setAuthenticating() {
+    this.updateState({ isAuthenticating: true, error: undefined })
+  }
+
+  /** @internal Used by IdentityAttributesManager. */
+  public setAuthenticationError(error: Error) {
+    this.updateState({ error, isAuthenticating: false })
+  }
+
+  private getDefaultIdentityProvider(): string | URL {
+    if (this.identityProvider) {
+      return this.identityProvider
+    }
+    return this.clientManager.isLocal
+      ? localInternetIdentityProvider(
+          Number(this.clientManager.agentHost?.port) || 4943,
+          this.internetIdentityId
+        )
+      : IC_INTERNET_IDENTITY_PROVIDER
+  }
+
+  private updateState(newState: Partial<AuthState>) {
+    if (isDev()) console.debug("[ic-reactor] Updating Auth State:", newState)
+    this.authStateRevision += 1
+    this.authStateValue = { ...this.authStateValue, ...newState }
+    this.authStateSubscribers.forEach((subscriber) =>
+      subscriber(this.authStateValue)
+    )
+  }
+
+  private async loadAuthClientConstructor() {
+    if (this.authClientConstructor) {
+      return this.authClientConstructor
+    }
+
+    if (!this.authClientConstructorPromise) {
+      // 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 }
+          ).AuthClient
+
+          if (!AuthClient) {
+            throw new Error("@icp-sdk/auth/client did not export AuthClient")
+          }
+
+          this.authClientConstructor = AuthClient
+          return AuthClient
+        })
+        .catch((error) => {
+          this.authModuleMissing = true
+          this.authClientConstructorPromise = undefined
+          if (
+            error instanceof Error &&
+            error.message.includes("did not export AuthClient")
+          ) {
+            throw error
+          }
+          return undefined
+        })
+    }
+
+    return this.authClientConstructorPromise
+  }
+}
+
+function getAuthClientOptions(
+  options?: AuthenticationClientOptions
+): AuthenticationClientOptions | undefined {
+  if (!options) {
+    return undefined
+  }
+
+  return {
+    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,
+  }
+}
+
+function getAuthClientOpenIdProvider(
+  openIdProvider?: AuthenticationClientOptions["openIdProvider"]
+): AuthenticationClientOptions["openIdProvider"] | undefined {
+  return openIdProvider === "google" ||
+    openIdProvider === "apple" ||
+    openIdProvider === "microsoft"
+    ? openIdProvider
+    : undefined
+}
+
+/**
+ * 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
+  )
+}
+
+function getAuthenticationCanisterEnv(): Record<string, string> | undefined {
+  const canisterEnv = safeGetCanisterEnv<Record<string, string>>()
+  if (canisterEnv) {
+    return canisterEnv as unknown as Record<string, string>
+  }
+
+  if (typeof document === "undefined") {
+    return undefined
+  }
+
+  const cookie = document.cookie
+    .split(";")
+    .find((part) => part.trim().startsWith("ic_env="))
+  const encodedValue = cookie?.split("=").slice(1).join("=")?.trim()
+  if (!encodedValue) {
+    return undefined
+  }
+
+  const env = Object.fromEntries(
+    decodeURIComponent(encodedValue)
+      .split("&")
+      .map((entry) => {
+        const separatorIndex = entry.indexOf("=")
+        return separatorIndex === -1
+          ? [entry, ""]
+          : [entry.slice(0, separatorIndex), entry.slice(separatorIndex + 1)]
+      })
+  )
+
+  return Object.keys(env).length ? env : undefined
+}
+
+function getSignInOptions(
+  options?: AuthenticationSignInOptions
+): AuthClientSignInOptions | undefined {
+  if (!options) {
+    return undefined
+  }
+
+  return {
+    maxTimeToLive: options.maxTimeToLive,
+    targets: options.targets,
+  }
+}