@ic-reactor/react 3.6.0 → 3.8.0

package/README.md

@@ -13,6 +13,11 @@ pnpm add @ic-reactor/react @icp-sdk/core @tanstack/react-query
 pnpm add @icp-sdk/auth
 ```
 
+`@icp-sdk/auth` is an optional peer. `AuthenticationManager` reaches it through a
+literal `import("@icp-sdk/auth/client")`, so Vite, Rollup and webpack resolve it
+at build time and code-split it into its own chunk — and tree-shake it away
+entirely in apps that never reference the class.
+
 ## Quick Start
 
 ```tsx
@@ -25,7 +30,6 @@ export const queryClient = new QueryClient()
 
 export const clientManager = new ClientManager({
   queryClient,
-  withCanisterEnv: true,
 })
 
 export const backend = new Reactor<_SERVICE>({
@@ -81,8 +85,10 @@ export function App() {
 
 - `createActorHooks(reactor)` for per-canister hooks like `useActorQuery` and
   `useActorMutation`
-- `createAuthHooks(clientManager)` for `useAuth`, `useAgentState`,
-  `useUserPrincipal`, and identity attribute hooks
+- `createAuthHooks(authentication)` for `useAuth`, `useAgentState`, and
+  `useUserPrincipal`
+- `createIdentityAttributeHooks(identityAttributes)` for signed identity
+  attribute requests
 - direct reactor hooks like `useReactorQuery` when you want to pass the reactor
   instance at call time
 - factory helpers like `createQuery`, `createSuspenseQuery`,
@@ -134,18 +140,118 @@ const mutation = updateProfile.useMutation({
 })
 ```
 
-## Identity Attributes / OpenID email and profile values
+## Internet Identity
+
+`defineReactor` wires up Internet Identity for you — `useAuth`,
+`useUserPrincipal`, `useAgentState` and `useIdentityAttributes` come back
+alongside the actor hooks:
+
+```tsx
+// src/reactor.ts
+export const { useActorQuery, useAuth, useIdentityAttributes, authentication } =
+  defineReactor<_SERVICE>({
+    name: "backend",
+    idlFactory,
+    auth: {
+      // Required when the app is served from more than one origin, so every
+      // origin resolves to the same principal.
+      derivationOrigin: "https://app.example.com",
+      // The default signs the user out and reloads after 10 minutes idle.
+      idleOptions: { disableIdle: true },
+    },
+  })
+```
+
+Auth options are forwarded to the underlying `@icp-sdk/auth` client:
+`identityProvider`, `derivationOrigin`, `windowOpenerFeatures`,
+`openIdProvider`, `storage`, `keyType`, `idleOptions`, `identity`, and
+`transport`. Only the `"google" | "apple" | "microsoft"` aliases are accepted
+for `openIdProvider`; any other value is dropped, since raw issuer URLs are
+only meaningful on `requestOpenIdAttributes`, where they scope the keys.
+
+Pass `authentication` from one reactor into another to share a single session
+across canisters. That reactor adopts the manager's `ClientManager` so sign-in
+updates the agent it calls through, so pass either `authentication` or `auth` —
+not both.
 
-`createAuthHooks(clientManager)` exposes `useIdentityAttributes()` for signed
-identity attributes from `@icp-sdk/auth` v7. Existing `useAuth()`, `login()`,
-`logout()`, and `useUserPrincipal()` consumers keep the same IC Reactor API, but
-the configured auth client must support the v7 constructor/sign-in/sign-out API.
+Set up manually when you need more control:
 
 ```tsx
-import { createAuthHooks } from "@ic-reactor/react"
+// src/auth.ts
+import {
+  AuthenticationManager,
+  IdentityAttributesManager,
+  createAuthHooks,
+  createIdentityAttributeHooks,
+} from "@ic-reactor/react"
 import { clientManager } from "./reactor"
 
-const { useIdentityAttributes } = createAuthHooks(clientManager)
+const authentication = new AuthenticationManager({ clientManager })
+export const { useAuth, useAgentState, useUserPrincipal } =
+  createAuthHooks(authentication)
+
+const identityAttributes = new IdentityAttributesManager(authentication)
+export const { useIdentityAttributes } =
+  createIdentityAttributeHooks(identityAttributes)
+```
+
+`useAuth()` calls `authentication.prepareClient()` on mount. Outside React, do
+it yourself during startup — it preloads the auth module so `login()` can open
+the identity provider window synchronously inside a click handler, which is
+what browser popup blockers require:
+
+```ts
+// once, at startup — awaits the dynamic import and builds the AuthClient
+await authentication.prepareClient()
+
+// later, inside the click handler — no await before signIn(), so the popup
+// still counts as user-initiated
+button.onclick = () => authentication.login()
+```
+
+`authentication.getPreparedClient()` returns the already-built client
+synchronously, or `undefined` when the module has not loaded yet.
+
+If your bundler cannot resolve the optional peer at all, construct the client
+yourself and inject it — IC Reactor then never imports `@icp-sdk/auth`:
+
+```ts
+import { AuthClient } from "@icp-sdk/auth/client"
+
+const authentication = new AuthenticationManager({
+  clientManager,
+  authClient: new AuthClient(),
+})
+```
+
+## Identity Attributes / OpenID email and profile values
+
+Identity attributes use a dedicated `IdentityAttributesManager`, with React
+bindings created by `createIdentityAttributeHooks`. Works with `@icp-sdk/auth`
+v7 and v8; the two versions disagree on the nonce contract and IC Reactor
+normalizes whichever form you pass.
+
+**Pass the nonce as a callback.** Awaiting your backend before calling
+`requestOpenIdAttributes` ends the user gesture, and the browser then blocks
+the Internet Identity window:
+
+```tsx
+// ✅ window opens immediately, nonce resolves while the user is in II
+await requestOpenIdAttributes({
+  nonce: () => backend.registerBegin(),
+  openIdProvider: "google",
+  keys: ["email", "name"],
+})
+
+// ❌ gesture is gone by the time the window would open
+const nonce = await backend.registerBegin()
+await requestOpenIdAttributes({ nonce, openIdProvider: "google", keys })
+```
+
+```tsx
+// src/RegisterWithOpenIdProvider.tsx
+import { useIdentityAttributes } from "./auth"
+import { backend } from "./reactor"
 
 function RegisterWithOpenIdProvider() {
   const {
@@ -156,10 +262,8 @@ function RegisterWithOpenIdProvider() {
   } = useIdentityAttributes()
 
   async function handleProviderLogin() {
-    const nonce = await backend.registerBegin()
-
     const result = await requestOpenIdAttributes({
-      nonce,
+      nonce: () => backend.registerBegin(),
       openIdProvider: "microsoft",
       keys: ["email", "name"],
       windowOpenerFeatures: popupCenter(),

package/dist/auth/authentication-manager.d.ts

@@ -0,0 +1,98 @@
+import type { Identity } from "@icp-sdk/core/agent";
+import type { AuthClientLike, AuthClientSignInOptions, AuthState, AuthenticationClientOptions, AuthenticationSignInOptions } from "./types.js";
+import { ClientManager } from "@ic-reactor/core";
+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;
+}
+/**
+ * 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 declare class AuthenticationManager {
+    private authClient?;
+    private authPromise?;
+    private authClientWasProvided;
+    private authStateRevision;
+    private authStateSubscribers;
+    private authClientConstructor?;
+    private authClientConstructorPromise?;
+    private authModuleMissing;
+    private authClientOptions?;
+    private authStateValue;
+    private readonly identityProvider?;
+    private readonly internetIdentityId?;
+    private readonly defaultClientOptions;
+    readonly clientManager: ClientManager;
+    /** The current authentication state. */
+    get authState(): AuthState;
+    constructor({ clientManager, authClient, identityProvider, internetIdentityId, ...clientOptions }: AuthenticationManagerParameters);
+    /** @internal Used by IdentityAttributesManager. */
+    get client(): AuthClientLike | undefined;
+    subscribeAuthState(callback: (state: AuthState) => void): () => void;
+    /**
+     * 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.
+     */
+    prepareClient(options?: AuthenticationClientOptions): Promise<AuthClientLike | undefined>;
+    /**
+     * 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.
+     */
+    getPreparedClient(options?: AuthenticationClientOptions): AuthClientLike | undefined;
+    authenticate: () => Promise<Identity | undefined>;
+    login: (loginOptions?: AuthenticationSignInOptions) => Promise<void>;
+    logout: (options?: {
+        returnTo?: string;
+    }) => Promise<void>;
+    private initializeClient;
+    /** @internal Used by IdentityAttributesManager. */
+    signInOrRecoverIdentity(options?: AuthClientSignInOptions): Promise<Identity>;
+    private ensurePreparedClient;
+    /**
+     * 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;
+    /**
+     * Merges constructor-level defaults with per-call overrides and fills in the
+     * network-appropriate identity provider.
+     */
+    private resolveClientOptions;
+    private syncStateFromClient;
+    /** @internal Used by IdentityAttributesManager. */
+    ensureClient(options?: AuthenticationClientOptions): Promise<AuthClientLike | undefined>;
+    /** @internal Used by IdentityAttributesManager. */
+    commitIdentity(identity: Identity, isAuthenticated: boolean): Promise<void>;
+    /** @internal Used by IdentityAttributesManager. */
+    setAuthenticating(): void;
+    /** @internal Used by IdentityAttributesManager. */
+    setAuthenticationError(error: Error): void;
+    private getDefaultIdentityProvider;
+    private updateState;
+    private loadAuthClientConstructor;
+}
+//# sourceMappingURL=authentication-manager.d.ts.map

package/dist/auth/authentication-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authentication-manager.d.ts","sourceRoot":"","sources":["../../src/auth/authentication-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,KAAK,EACV,cAAc,EACd,uBAAuB,EACvB,SAAS,EACT,2BAA2B,EAC3B,2BAA2B,EAC5B,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,aAAa,EAAS,MAAM,kBAAkB,CAAA;AASvD,MAAM,WAAW,+BAAgC,SAAQ,2BAA2B;IAClF,aAAa,EAAE,aAAa,CAAA;IAC5B;;;OAGG;IACH,UAAU,CAAC,EAAE,cAAc,CAAA;IAC3B,2DAA2D;IAC3D,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAMD;;;;;;;;;GASG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,UAAU,CAAC,CAAgB;IACnC,OAAO,CAAC,WAAW,CAAC,CAA+B;IACnD,OAAO,CAAC,qBAAqB,CAAQ;IACrC,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,oBAAoB,CAAwC;IACpE,OAAO,CAAC,qBAAqB,CAAC,CAAuB;IACrD,OAAO,CAAC,4BAA4B,CAAC,CAEpC;IACD,OAAO,CAAC,iBAAiB,CAAQ;IACjC,OAAO,CAAC,iBAAiB,CAAC,CAA6B;IACvD,OAAO,CAAC,cAAc,CAKrB;IACD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAc;IAChD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAQ;IAC5C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA6B;IAClE,SAAgB,aAAa,EAAE,aAAa,CAAA;IAE5C,wCAAwC;IACxC,IAAW,SAAS,IAAI,SAAS,CAEhC;gBAEW,EACV,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,GAAG,aAAa,EACjB,EAAE,+BAA+B;IA4BlC,mDAAmD;IACnD,IAAW,MAAM,+BAEhB;IAEM,kBAAkB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI;IAS9D;;;;;;;OAOG;IACU,aAAa,CAAC,OAAO,CAAC,EAAE,2BAA2B;IAUhE;;;;;;;OAOG;IACI,iBAAiB,CACtB,OAAO,CAAC,EAAE,2BAA2B,GACpC,cAAc,GAAG,SAAS;IAItB,YAAY,QAAa,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CA0D5D;IAEM,KAAK,GAAU,eAAe,2BAA2B,mBAwD/D;IAEM,MAAM,GAAU,UAAU;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,mBAerD;YAEa,gBAAgB;IAc9B,mDAAmD;IACtC,uBAAuB,CAClC,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,QAAQ,CAAC;IAyBpB,OAAO,CAAC,oBAAoB;IAiB5B;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAO5B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;YAed,mBAAmB;IAmBjC,mDAAmD;IACtC,YAAY,CAAC,OAAO,CAAC,EAAE,2BAA2B;IAQ/D,mDAAmD;IACtC,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,eAAe,EAAE,OAAO;IAQxE,mDAAmD;IAC5C,iBAAiB;IAIxB,mDAAmD;IAC5C,sBAAsB,CAAC,KAAK,EAAE,KAAK;IAI1C,OAAO,CAAC,0BAA0B;IAYlC,OAAO,CAAC,WAAW;YASL,yBAAyB;CAuCxC"}