@ic-reactor/react 3.12.4 → 3.13.0

package/src/auth/authentication-manager.ts

@@ -1,5 +1,6 @@
 import type { Identity } from "@icp-sdk/core/agent"
 import { AnonymousIdentity } from "@icp-sdk/core/agent"
+import { isDelegationValid, type DelegationChain } from "@icp-sdk/core/identity"
 import type {
   AuthClientLike,
   AuthClientSignInOptions,
@@ -22,6 +23,15 @@ import {
   LOCAL_INTERNET_IDENTITY_CANISTER_ID,
   localInternetIdentityProvider,
 } from "./constants.js"
+import { recordAuthentication } from "../ownedAuthentication.js"
+import {
+  detectAuthClientFlavor,
+  detectAuthClientInstanceFlavor,
+  toAuthClientConstructorOptions,
+  toAuthClientSignInOptions,
+  type AuthClientFlavor,
+  type IdentityProviderPairing,
+} from "./auth-client-compat.js"
 
 export interface AuthenticationManagerParameters extends AuthenticationClientOptions {
   clientManager: ClientManager
@@ -34,8 +44,20 @@ export interface AuthenticationManagerParameters extends AuthenticationClientOpt
   internetIdentityId?: string
 }
 
+/**
+ * What `@icp-sdk/auth` v9 and later add to a client, read by shape because
+ * {@link AuthClientLike} describes the methods every supported major shares.
+ */
+type SubscribableAuthClient = AuthClientLike & {
+  subscribe?: (listener: () => void) => () => void
+  getPrincipal?: () => Principal | undefined
+}
+
 type AuthClientConstructor = {
-  new (options?: AuthenticationClientOptions): AuthClientLike
+  // The translated options are the installed client's shape, not IC Reactor's:
+  // `toAuthClientConstructorOptions` rewrites them per detected flavor, so this
+  // stays deliberately open rather than asserting a contract that varies.
+  new (options?: unknown): AuthClientLike
 }
 
 /**
@@ -59,6 +81,7 @@ export class AuthenticationManager {
     AuthClientConstructor | undefined
   >
   private authModuleMissing = false
+  private authClientFlavor: AuthClientFlavor = "legacy"
   private authClientOptions?: AuthenticationClientOptions
   private authStateValue: AuthState = {
     identity: null,
@@ -66,8 +89,26 @@ export class AuthenticationManager {
     isAuthenticated: false,
     error: undefined,
   }
+  /** See {@link sessionChecked}. */
+  private sessionCheckedValue = false
+  private sessionCheckedSubscribers: Array<() => void> = []
+  /** Stops following the current client's session record; see `watchClient()`. */
+  private unwatchClient?: () => void
+  /**
+   * Set when the client's session record changed while an operation of this
+   * manager's own was running; see `followClient()`.
+   */
+  private clientChangedDuringOperation = false
+  /** Counts `followClient()` passes, so that only the latest one publishes. */
+  private followRevision = 0
+  /** Counts `dispose()` calls; see {@link releaseCount}. */
+  private releases = 0
   private readonly identityProvider?: string | URL
+  /** The provider taken from the `ic_env` cookie, when no caller set one. */
+  private readonly envIdentityProvider?: string | URL
   private readonly internetIdentityId?: string
+  /** Whether `internetIdentityId` came from the caller rather than the cookie. */
+  private readonly internetIdentityIdIsExplicit: boolean
   /**
    * Which authorize path the locally deployed Internet Identity serves, once
    * probed. `undefined` means not probed yet; `null` means it serves no sign-in
@@ -91,15 +132,19 @@ export class AuthenticationManager {
     ...clientOptions
   }: AuthenticationManagerParameters) {
     this.clientManager = clientManager
+    // For `createReactorProvider`, which disposes the managers built while
+    // its factory ran, and leaves alone those built elsewhere.
+    recordAuthentication(this)
     const canisterEnv =
       typeof window !== "undefined" ? getAuthenticationCanisterEnv() : undefined
-    this.identityProvider =
-      identityProvider ||
-      acceptEnvIdentityProvider(
-        canisterEnv?.[INTERNET_IDENTITY_PROVIDER_ENV_KEY] ||
-          canisterEnv?.["PUBLIC_INTERNET_IDENTITY_PROVIDER"],
-        clientManager
-      )
+    this.envIdentityProvider = identityProvider
+      ? undefined
+      : acceptEnvIdentityProvider(
+          canisterEnv?.[INTERNET_IDENTITY_PROVIDER_ENV_KEY] ||
+            canisterEnv?.["PUBLIC_INTERNET_IDENTITY_PROVIDER"],
+          clientManager
+        )
+    this.identityProvider = identityProvider || this.envIdentityProvider
     // Same cookie, same decision. This one only ever reaches a local provider
     // URL, but `allowEnvConfig: false` has to mean the cookie is not consulted
     // rather than mostly not consulted.
@@ -112,11 +157,18 @@ export class AuthenticationManager {
               canisterEnv?.["CANISTER_ID_INTERNET_IDENTITY"]
           )
         : undefined)
+    this.internetIdentityIdIsExplicit = Boolean(internetIdentityId)
     this.defaultClientOptions = clientOptions
 
     if (authClient) {
       this.authClientWasProvided = true
       this.authClient = authClient
+      // A caller-built client never goes through the module loader that
+      // detects the flavor, so read it off the instance. Without this a v10
+      // client handed in here was treated as v8, and `targets` reached it
+      // without the warning that it is ignored.
+      this.authClientFlavor = detectAuthClientInstanceFlavor(authClient)
+      this.watchClient(authClient)
       this.syncStateFromClient(this.authStateRevision).catch((error) => {
         this.updateState({ error: error as Error, isAuthenticating: false })
       })
@@ -132,11 +184,137 @@ export class AuthenticationManager {
     return this.authClient
   }
 
+  /**
+   * @internal Used by the auth hooks.
+   *
+   * Whether this manager has checked its client for a session: a restore has
+   * settled, whether it found a session, found none or failed, or a sign-in or
+   * sign-out has completed. Until then {@link authState} is the signed-out state
+   * the manager starts in, which says nothing about the session, so the auth
+   * hooks report `isAuthenticating: true` instead.
+   */
+  public get sessionChecked(): boolean {
+    return this.sessionCheckedValue
+  }
+
+  /**
+   * @internal Used by the auth hooks.
+   *
+   * Records that the session has been checked, and tells the auth hooks the
+   * first time. A restore that failed counts: waiting on one that will not be
+   * retried would leave the hooks reporting `isAuthenticating: true` for good.
+   */
+  public markSessionChecked() {
+    if (this.sessionCheckedValue) return
+    this.sessionCheckedValue = true
+    const subscribers = this.sessionCheckedSubscribers
+    this.sessionCheckedSubscribers = []
+    for (const subscriber of subscribers) subscriber()
+  }
+
+  /**
+   * @internal Used by the auth hooks.
+   *
+   * How many times {@link dispose} has run. A restore the hooks started
+   * compares it with the count it began with, to tell whether the manager was
+   * released while it ran.
+   */
+  public get releaseCount(): number {
+    return this.releases
+  }
+
+  /**
+   * @internal Used by the auth hooks.
+   *
+   * Calls `callback` once, when {@link sessionChecked} turns true. Nothing else
+   * announces it when the check that settles it publishes no state, as a
+   * restore that failed before it read the client does not.
+   *
+   * @returns An unsubscribe function.
+   */
+  public subscribeSessionChecked(callback: () => void) {
+    if (this.sessionCheckedValue) return () => {}
+    const subscription = () => callback()
+    this.sessionCheckedSubscribers.push(subscription)
+    return () => {
+      this.sessionCheckedSubscribers = this.sessionCheckedSubscribers.filter(
+        (subscriber) => subscriber !== subscription
+      )
+    }
+  }
+
+  /**
+   * Releases the `@icp-sdk/auth` client this manager built.
+   *
+   * A v10 client hooks the page when it is built: activity listeners on
+   * `document`, focus and visibility listeners, a watch on the session record
+   * that every tab shares and, once signed in, a refresh timer. Nothing
+   * releases them when the manager is dropped, so a manager built per mount,
+   * as a server-rendered app builds one in its provider, left one live client
+   * behind on each remount. Call this when you discard the manager, from the
+   * cleanup of whatever built it.
+   *
+   * The client is disposed and forgotten, so a later {@link prepareClient},
+   * {@link login}, {@link logout} or restore that needs a client builds a new
+   * one. That keeps it safe in an effect cleanup under React's StrictMode,
+   * which runs the cleanup and then the effect again on the same manager. With
+   * `@icp-sdk/auth` v8 there is nothing to release, and the manager only drops
+   * its reference. A client passed in as `authClient` belongs to the caller: it
+   * is never disposed, and the manager goes on using it, but stops following its
+   * session record until its next {@link prepareClient}, {@link login} or
+   * {@link authenticate}, so that the caller's client does not keep a
+   * discarded manager alive.
+   *
+   * The auth state and the identity on the agent are left as they are. A
+   * restore reading the client when it is released ends without publishing
+   * what it read, and a sign-in or sign-out under way ends with what the
+   * released client reports. A restore `useAuth()` started stops, and
+   * releases any client it built meanwhile, once no `useAuth()` of this
+   * manager is mounted; one mounted later restores again.
+   *
+   * @example
+   * ```tsx
+   * const [authentication] = useState(
+   *   () => new AuthenticationManager({ clientManager })
+   * )
+   * useEffect(() => () => authentication.dispose(), [authentication])
+   * ```
+   */
+  public dispose(): void {
+    this.releases++
+    this.stopWatchingClient()
+    if (this.authClientWasProvided) {
+      return
+    }
+    const client = this.authClient
+    this.authClient = undefined
+    this.authClientOptions = undefined
+    if (client) {
+      disposeClient(client)
+    }
+  }
+
+  /**
+   * Subscribes to auth state changes.
+   *
+   * Callbacks run in the order they subscribed, after the state has changed. A
+   * callback that throws does not stop the others; the first error is rethrown
+   * to whatever made the change once they have all run. When a callback itself
+   * changes the state, the newer state is the last each callback hears.
+   *
+   * @param callback - Function called with the new state.
+   * @returns An unsubscribe function.
+   */
   public subscribeAuthState(callback: (state: AuthState) => void) {
-    this.authStateSubscribers.push(callback)
+    // Each subscription gets an entry of its own, so the unsubscribe it returns
+    // removes that one registration and no other. Filtering on the callback
+    // itself removed every registration of a function subscribed twice, as
+    // `ClientManager.subscribe` did before #513.
+    const subscription = (state: AuthState) => callback(state)
+    this.authStateSubscribers.push(subscription)
     return () => {
       this.authStateSubscribers = this.authStateSubscribers.filter(
-        (subscriber) => subscriber !== callback
+        (subscriber) => subscriber !== subscription
       )
     }
   }
@@ -158,6 +336,7 @@ export class AuthenticationManager {
     const clientOptions = this.resolveClientOptions(options)
 
     if (this.authClient && !this.shouldRecreateClient(clientOptions)) {
+      this.watchClient(this.authClient)
       return this.authClient
     }
 
@@ -187,7 +366,19 @@ export class AuthenticationManager {
     // An inconclusive probe must not change behaviour: the canister may be
     // fine and merely unreachable from here, and a diagnostic that blocks a
     // working login is worse than the failure it explains.
-    this.localAuthorizePath = inconclusive ? "/authorize" : path
+    const authorizePath = inconclusive ? "/authorize" : path
+
+    // With no sign-in UI, login fails with advice that depends on the
+    // installed @icp-sdk/auth major. A client IC Reactor builds itself shows
+    // its major only once the module has loaded, and that import is usually
+    // still in flight when the probe answers. Wait for it before recording the
+    // finding, so nothing reads `null` while the flavor still holds its
+    // `legacy` default and hands a v10 app the v8 advice.
+    if (authorizePath === null && !this.authClientWasProvided) {
+      await this.loadAuthClientConstructor().catch(() => undefined)
+    }
+
+    this.localAuthorizePath = authorizePath
 
     if (path === "/#authorize" && !inconclusive) {
       console.warn(
@@ -213,28 +404,46 @@ export class AuthenticationManager {
   }
 
   public authenticate = async (): Promise<Identity | undefined> => {
+    const releases = this.releases
+    try {
+      return await this.checkSession()
+    } finally {
+      // Marked once the result is published, so the hooks never show the
+      // starting state as the answer. A failed restore settles it too. One
+      // that `dispose()` cut short read nothing, and leaves the check to the
+      // restore of whatever mounts this manager again.
+      if (releases === this.releases || this.authClient) {
+        this.markSessionChecked()
+      }
+    }
+  }
+
+  private async checkSession(): Promise<Identity | undefined> {
+    if (this.authClient) {
+      this.watchClient(this.authClient)
+    }
     if (this.authState.isAuthenticated) {
       // Returning on the cached flag alone meant a delegation that expired
       // mid-session was never re-observed: the UI kept rendering a signed-in
       // state while every update call failed, and only a reload recovered.
       // Re-ask the client, which reads the cached expiry rather than hitting
       // storage. A throw here is treated as "still valid" so a transient
-      // failure cannot sign anyone out.
+      // failure cannot sign anyone out. A v8 delegation that has expired is
+      // not valid whatever the client answers: see vouchesFor().
       if (!this.authClient) {
         return this.authState.identity || undefined
       }
-      const stillValid = await Promise.resolve(
+      const isAuthenticated = await Promise.resolve(
         this.authClient.isAuthenticated()
       ).catch(() => true)
-      if (stillValid) {
+      if (this.vouchesFor(this.authState.identity, isAuthenticated)) {
         return this.authState.identity || undefined
       }
-      // Expired. Re-deriving state from the client will not help: the v8
-      // client keeps handing out the lapsed delegation from getIdentity()
-      // until signOut() runs (only a fresh page load purges it), so the
-      // expired identity would go straight back on the agent and every
-      // refetch would be signed with it. End the session explicitly.
-      await this.expireSession()
+      // Expired, or ended in another tab. The v8 client keeps handing out the
+      // lapsed delegation from getIdentity() until signOut() runs (only a
+      // fresh page load purges it). End the session explicitly, in this tab
+      // only: see expireSession().
+      await this.expireSession(isAuthenticated)
       return undefined
     }
     if (this.authPromise) {
@@ -263,17 +472,36 @@ export class AuthenticationManager {
       // would put the signed-out user's delegation back on the agent.
       const revision = this.authStateRevision
       try {
-        if (!this.authClient) {
-          const authClient = await this.initializeClient(
-            this.resolveClientOptions()
-          )
-          if (!authClient) {
+        let client =
+          this.authClient ??
+          (await this.initializeClient(this.resolveClientOptions()))
+        if (!client) {
+          this.updateState({ isAuthenticating: false })
+          return undefined
+        }
+        let { clientIdentity, isAuthenticated } =
+          await this.readClientSession(client)
+        // Per-call options can replace the client while it is read, and
+        // `dispose()` can release it. Both answers used to be read from
+        // whichever client was current at the time, so they could come from two
+        // clients. A v10 client disposed while it restores hands out the
+        // anonymous identity, and the record its replacement reads still says
+        // signed in: the manager reported the anonymous principal signed in.
+        // The client in use now is read instead, and a manager that let go of
+        // its client publishes nothing. Nothing may be signed with what a
+        // released client held.
+        while (
+          revision === this.authStateRevision &&
+          client !== this.authClient
+        ) {
+          if (!this.authClient) {
             this.updateState({ isAuthenticating: false })
-            return undefined
+            return this.authState.identity || undefined
           }
+          client = this.authClient
+          ;({ clientIdentity, isAuthenticated } =
+            await this.readClientSession(client))
         }
-        const clientIdentity = await this.authClient!.getIdentity()
-        const isAuthenticated = await this.authClient!.isAuthenticated()
 
         if (revision !== this.authStateRevision) {
           // Superseded — leave whatever ran in the meantime in place.
@@ -281,7 +509,9 @@ export class AuthenticationManager {
         }
         // A client that says it is not authenticated but still hands out a
         // non-anonymous identity is holding a delegation it will no longer
-        // vouch for (expired, mid-session). Nothing may be signed with it.
+        // vouch for (expired, mid-session). So is a v8 client that says it is,
+        // once another tab has signed in again, while it hands out the
+        // delegation that lapsed in this one. Nothing may be signed with it.
         const identity =
           isAuthenticated || clientIdentity.getPrincipal().isAnonymous()
             ? clientIdentity
@@ -347,7 +577,7 @@ export class AuthenticationManager {
       }
 
       this.clientManager.updateAgent(identity)
-      this.updateState({
+      this.publishSession({
         identity,
         isAuthenticated: true,
         isAuthenticating: false,
@@ -363,37 +593,80 @@ export class AuthenticationManager {
       }
     } catch (error) {
       if (!didCompleteSignIn) {
-        await loginOptions?.onError?.((error as Error).message)
+        // Recorded before the callback runs, as on success: an onError that
+        // rejected used to skip this and strand `isAuthenticating: true` with
+        // no error on record.
         this.updateState({
           error: error as Error,
           isAuthenticating: false,
         })
+        await loginOptions?.onError?.((error as Error).message)
       }
       throw error
     }
   }
 
   public logout = async (options?: { returnTo?: string }) => {
-    if (!this.authClient) {
+    // None built yet, or released by `dispose()`. Signing out needs no user
+    // gesture, so one can be built here.
+    const client = this.authClient ?? (await this.ensureClient())
+    if (!client) {
       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 })
     try {
-      await this.authClient.signOut(options)
-      const identity = await this.authClient.getIdentity()
+      // The client the sign-out started on, even once `dispose()` has released
+      // it, as when the sign-out closes the widget that built this manager.
+      // Reading `this.authClient` then failed the sign-out with a TypeError.
+      await client.signOut(options)
+      const identity = await client.getIdentity()
       this.clientManager.updateAgent(identity)
-      this.updateState({
+      this.publishSession({
         identity,
         isAuthenticated: false,
         isAuthenticating: false,
       })
     } catch (error) {
-      // Without this the manager was left with `isAuthenticating: true` and no
-      // recorded error, so a button disabled on `isAuthenticating` stayed stuck
-      // and nothing told the app why.
-      this.updateState({ error: error as Error, isAuthenticating: false })
+      // A failed signOut does not always mean the session survived. v10 wipes
+      // the device and drops to an anonymous identity before it raises a revoke
+      // the canister did not answer, so keeping the session here left the app
+      // signed in and the agent signing as the user who had just signed out.
+      // Follow the client instead: once it no longer vouches for the session,
+      // nothing may sign with it, which is the rule `authenticate()` applies
+      // too. A v8 client that failed before forgetting anything still vouches
+      // for its session and keeps it, unless its delegation has lapsed (see
+      // vouchesFor()). A check that throws keeps it as well.
+      //
+      // Anything that changes auth state while that check is in flight, such
+      // as a login that finishes meanwhile, bumps this. The check then
+      // describes a client that has been used since, and its answer must not
+      // replace the newer state, as in `authenticate()`.
+      const revision = this.authStateRevision
+      const stillSignedIn = await Promise.resolve()
+        .then(() => client.isAuthenticated())
+        .catch(() => true)
+      if (revision !== this.authStateRevision) {
+        throw error
+      }
+      if (this.vouchesFor(this.authState.identity, stillSignedIn)) {
+        // Without this the manager was left with `isAuthenticating: true` and
+        // no recorded error, so a button disabled on `isAuthenticating` stayed
+        // stuck and nothing told the app why.
+        this.publishSession({ error: error as Error, isAuthenticating: false })
+      } else {
+        const identity = new AnonymousIdentity()
+        this.clientManager.updateAgent(identity)
+        // The error stays recorded: the device is signed out, but the session
+        // may still be live at the identity provider.
+        this.publishSession({
+          identity,
+          isAuthenticated: false,
+          isAuthenticating: false,
+          error: error as Error,
+        })
+      }
       throw error
     }
   }
@@ -407,32 +680,225 @@ export class AuthenticationManager {
       return undefined
     }
 
-    this.authClient = new AuthClient(options)
+    // Every mounted `useAuth()` prepares the client at the same moment, and
+    // each call arrives here after the same await. Building one per caller
+    // left all but the last running with nothing able to reach them: on v8
+    // each registered the app's `onIdle` on the shared IdleManager again, so it
+    // fired once per consumer, and on v10 each kept its browser listeners and
+    // its session's refresh timer. Take the client an earlier caller built for
+    // the same options instead.
+    if (this.authClient && !this.shouldRecreateClient(options)) {
+      return this.authClient
+    }
+
+    return this.installClient(
+      new AuthClient(this.toClientOptions(options)),
+      options
+    )
+  }
+
+  /**
+   * Makes `client`, which this manager built for `options`, the current one.
+   *
+   * The client it replaces was built here too, for other options: a caller's
+   * `authClient` is never replaced. It was dropped with nothing released, so a
+   * v10 client kept its browser listeners, its state subscription and its
+   * session's refresh timer for the life of the page, one more for each switch
+   * between option sets, such as a one-click sign-in and a plain one (#729).
+   * v10 asks for `dispose()` on a client being discarded, and a new
+   * interaction already takes its signer channel from the old client, so this
+   * adds no failure of its own. A v8 client has nothing to dispose; see
+   * `withSharedIdleCallback()` for the callback it leaves registered.
+   */
+  private installClient(
+    client: AuthClientLike,
+    options?: AuthenticationClientOptions
+  ): AuthClientLike {
+    const replaced = this.authClient
+    this.stopWatchingClient()
+    this.authClient = client
     this.authClientOptions = options
-    return this.authClient
+    if (replaced && replaced !== client) {
+      disposeClient(replaced)
+    }
+    this.watchClient(client)
+    return client
+  }
+
+  /**
+   * Follows a v10 client's session record, which every tab of the origin
+   * shares.
+   *
+   * The manager learned about the session only through its own calls, while a
+   * v10 client follows the other tabs. After a sign-out in another tab, this
+   * tab's client dropped the session and its manager went on reporting the
+   * user signed in, with the replaced identity on the agent signing calls as
+   * the account the user had left. After a sign-in there as another account,
+   * the manager kept the old account while the client held the new one. When
+   * the old identity's app delegation then lapsed, its mint was refused and
+   * the client removed the record every tab reads, signing the new account out
+   * of every tab (#754). `subscribe()` fires after the record changes, here or
+   * in another tab, and the manager then reads the client again.
+   *
+   * v8 has no notification and never revokes a session, so a v8 client is not
+   * followed.
+   */
+  private watchClient(client: AuthClientLike) {
+    if (this.unwatchClient || this.authClientFlavor !== "session") {
+      return
+    }
+    const { subscribe } = client as SubscribableAuthClient
+    if (typeof subscribe !== "function") {
+      return
+    }
+    this.unwatchClient = subscribe.call(client, () => {
+      // The client tells its listeners before it starts restoring for the new
+      // record, which it does right after they return. Reading it a microtask
+      // later waits for that restore. The state is published whether or not a
+      // subscriber throws, and there is no caller to hand that error to.
+      void Promise.resolve()
+        .then(() => this.followClient(client))
+        .catch(() => undefined)
+    })
+  }
+
+  private stopWatchingClient() {
+    this.unwatchClient?.()
+    this.unwatchClient = undefined
+  }
+
+  /**
+   * Reads the session from `client` after its record changed, and publishes
+   * it when it differs from what this manager holds, as `syncStateFromClient()`
+   * derives it. An error recorded for the session it replaces goes with it.
+   *
+   * An operation of the manager's own, which sets `isAuthenticating`, writes
+   * the record itself and publishes what the client holds when it ends, so a
+   * change during one is read again once it has. So is a change whose read
+   * something else published over.
+   */
+  private async followClient(client: AuthClientLike): Promise<void> {
+    if (client !== this.authClient) {
+      return
+    }
+    if (this.authState.isAuthenticating) {
+      this.clientChangedDuringOperation = true
+      return
+    }
+    const pass = ++this.followRevision
+    const revision = this.authStateRevision
+    const session = await this.readFollowedSession(client)
+    if (pass !== this.followRevision || client !== this.authClient) {
+      return
+    }
+    if (revision !== this.authStateRevision) {
+      return this.followClient(client)
+    }
+    if (!session) {
+      return
+    }
+    const current = this.authState
+    const anonymous = session.identity.getPrincipal().isAnonymous()
+    const unchanged =
+      session.isAuthenticated === current.isAuthenticated &&
+      (session.identity === current.identity ||
+        (!session.isAuthenticated &&
+          anonymous &&
+          current.identity?.getPrincipal().isAnonymous() === true))
+    if (unchanged) {
+      this.markSessionChecked()
+      return
+    }
+    // As in `authenticate()`, an agent that is anonymous already is left as
+    // it is.
+    if (!anonymous || !this.agentIsAnonymous()) {
+      this.clientManager.updateAgent(session.identity)
+    }
+    this.publishSession({
+      identity: session.identity,
+      isAuthenticated: session.isAuthenticated,
+      isAuthenticating: false,
+      error: undefined,
+    })
+  }
+
+  /**
+   * The identity `client` hands out, and whether it vouches for it (see
+   * `vouchesFor()`). Both are read from the same client.
+   */
+  private async readClientSession(client: AuthClientLike) {
+    const clientIdentity = await client.getIdentity()
+    const isAuthenticated = this.vouchesFor(
+      clientIdentity,
+      await client.isAuthenticated()
+    )
+    return { clientIdentity, isAuthenticated }
+  }
+
+  /**
+   * The session `client` holds, or `undefined` to leave the manager's as it is.
+   *
+   * v10 refuses to hand out an identity while the record names a sign-in it
+   * holds no credential for, as when restoring the account another tab signed
+   * in as failed. The session this manager holds is kept then only while the
+   * record still names its account. One for any other account must not stay
+   * on the agent.
+   */
+  private async readFollowedSession(
+    client: AuthClientLike
+  ): Promise<{ identity: Identity; isAuthenticated: boolean } | undefined> {
+    try {
+      const { clientIdentity, isAuthenticated } =
+        await this.readClientSession(client)
+      // The rule `authenticate()` applies to an identity the client no longer
+      // vouches for.
+      const identity =
+        isAuthenticated || clientIdentity.getPrincipal().isAnonymous()
+          ? clientIdentity
+          : new AnonymousIdentity()
+      return { identity, isAuthenticated }
+    } catch {
+      const { isAuthenticated, identity } = this.authState
+      const held = isAuthenticated
+        ? identity?.getPrincipal().toText()
+        : undefined
+      const named = (client as SubscribableAuthClient)
+        .getPrincipal?.()
+        ?.toText()
+      if (held === undefined || held === named) {
+        return undefined
+      }
+      return { identity: new AnonymousIdentity(), isAuthenticated: false }
+    }
   }
 
   /** @internal Used by IdentityAttributesManager. */
   public async signInOrRecoverIdentity(
     options?: AuthClientSignInOptions
   ): Promise<Identity> {
-    if (!this.authClient) {
+    // Held, because `dispose()` can release it while the popup is open. The
+    // recovery below then failed with a TypeError instead of the client's own
+    // error.
+    const client = this.authClient
+    if (!client) {
       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)
+      return await client.signIn(
+        toAuthClientSignInOptions(options, this.authClientFlavor)
+      )
     } catch (error) {
-      const identity = await Promise.resolve(
-        this.authClient.getIdentity()
-      ).catch(() => null)
+      const identity = await Promise.resolve(client.getIdentity()).catch(
+        () => null
+      )
       const isAuthenticated = await Promise.resolve(
-        this.authClient.isAuthenticated()
+        client.isAuthenticated()
       ).catch(() => false)
 
-      if (identity && isAuthenticated) {
+      if (identity && this.vouchesFor(identity, isAuthenticated)) {
         return identity
       }
 
@@ -444,6 +910,7 @@ export class AuthenticationManager {
     options?: AuthenticationClientOptions
   ): AuthClientLike | undefined {
     if (this.authClient && !this.shouldRecreateClient(options)) {
+      this.watchClient(this.authClient)
       return this.authClient
     }
 
@@ -452,9 +919,111 @@ export class AuthenticationManager {
       return undefined
     }
 
-    this.authClient = new AuthClient(options)
-    this.authClientOptions = options
-    return this.authClient
+    return this.installClient(
+      new AuthClient(this.toClientOptions(options)),
+      options
+    )
+  }
+
+  /**
+   * Hands the installed client the option shape it actually accepts.
+   *
+   * `authClientOptions` keeps the untranslated values, and `shouldRecreateClient`
+   * compares them with the installed major in mind: two calls that differ only
+   * in a key that major drops count as the same options, so the client is not
+   * rebuilt for them.
+   */
+  private toClientOptions(options?: AuthenticationClientOptions): unknown {
+    return toAuthClientConstructorOptions(
+      this.authClientFlavor === "legacy"
+        ? withSharedIdleCallback(options)
+        : options,
+      this.authClientFlavor,
+      this.identityProviderPairing(options?.identityProvider),
+      this.sessionAgentOptions()
+    )
+  }
+
+  /**
+   * Options for the agent a v9+ client mints delegations with, off mainnet.
+   *
+   * That client makes its own calls to the Internet Identity canister, through
+   * an agent built from these options alone. Without a root key it checks every
+   * certificate against mainnet's, which a local replica or testnet cannot
+   * satisfy, so sign-in would fail at the first mint. Off mainnet it gets the
+   * replica this app already talks to and fetches that network's root key, the
+   * same trust the app's own agent needs there. When the app passed its own
+   * `agentOptions.rootKey`, which its agent keeps, the minting agent gets that
+   * key instead and verifies against it too. On mainnet nothing is passed, and
+   * the client keeps its defaults.
+   */
+  private sessionAgentOptions(): Record<string, unknown> | undefined {
+    if (!this.clientManager.isLocal) {
+      return undefined
+    }
+    const host = this.clientManager.agentHost
+    const rootKey = this.clientManager.explicitRootKey
+    return {
+      ...(host ? { host: host.toString() } : {}),
+      ...(rootKey ? { rootKey } : { shouldFetchRootKey: true }),
+    }
+  }
+
+  /**
+   * Which canister a v9+ client should pair with `identityProvider`.
+   *
+   * v9+ names a provider by its authorize URL and the canister that mints its
+   * delegations, and nothing about the canister follows from the URL. The
+   * mainnet URL goes with mainnet's canister unless the caller named another.
+   * A canister read from the `ic_env` cookie belongs to a local deployment, so
+   * it never overrides that. Any other URL takes `internetIdentityId`, or the
+   * well-known local canister when the URL is one IC Reactor derived for a
+   * local deployment. A URL the caller set with no canister stays `unknown`.
+   */
+  private identityProviderPairing(
+    identityProvider?: string | URL
+  ): IdentityProviderPairing {
+    if (String(identityProvider) === IC_INTERNET_IDENTITY_PROVIDER) {
+      return this.internetIdentityIdIsExplicit && this.internetIdentityId
+        ? { kind: "pair", canisterId: this.internetIdentityId }
+        : { kind: "mainnet" }
+    }
+    if (this.internetIdentityId) {
+      return { kind: "pair", canisterId: this.internetIdentityId }
+    }
+    if (
+      identityProvider !== undefined &&
+      this.isDerivedLocalProvider(identityProvider)
+    ) {
+      return { kind: "pair", canisterId: LOCAL_INTERNET_IDENTITY_CANISTER_ID }
+    }
+    return { kind: "unknown" }
+  }
+
+  /**
+   * Whether `identityProvider` is a local provider IC Reactor chose, from the
+   * `ic_env` cookie or built for the local replica, rather than one a caller
+   * configured.
+   */
+  private isDerivedLocalProvider(identityProvider: string | URL): boolean {
+    if (this.envIdentityProvider !== undefined) {
+      return String(identityProvider) === String(this.envIdentityProvider)
+    }
+    if (
+      this.identityProvider !== undefined ||
+      !this.clientManager.isLocal ||
+      this.localAuthorizePath === null
+    ) {
+      return false
+    }
+    return (
+      String(identityProvider) ===
+      localInternetIdentityProvider(
+        Number(this.clientManager.agentHost?.port) || 4943,
+        this.internetIdentityId,
+        this.localAuthorizePath
+      )
+    )
   }
 
   /**
@@ -468,7 +1037,11 @@ export class AuthenticationManager {
     if (this.authClientWasProvided) {
       return false
     }
-    return !isSameAuthClientOptions(this.authClientOptions, options)
+    return !isSameAuthClientOptions(
+      this.authClientOptions,
+      options,
+      this.authClientFlavor
+    )
   }
 
   /**
@@ -497,17 +1070,76 @@ export class AuthenticationManager {
   }
 
   /**
-   * End a session whose delegation has lapsed: ask the client to forget it,
-   * put the anonymous identity on the agent -- which also sweeps the previous
-   * user's caller-scoped cache entries and refetches the rest anonymously --
-   * and publish the signed-out state. `signOut` failing changes nothing here:
-   * the delegation is already unusable, and the agent must not keep it.
+   * @internal Used by IdentityAttributesManager.
+   *
+   * Whether the client vouches for `identity`, given what its
+   * `isAuthenticated()` answered.
+   *
+   * A v8 client's answer is not about the identity it holds. It reads the
+   * delegation expiry v8 keeps in the `localStorage` every tab shares, while
+   * `getIdentity()` returns the identity this client restored or signed in
+   * with, and v8 never reads storage again once it has loaded. When the session
+   * lapses and the user signs in again in another tab, that tab writes a new
+   * expiry, and the answer is yes again for the delegation this tab still
+   * holds, which the replica refuses. So a v8 identity whose own delegation
+   * has expired is not vouched for, whatever the answer. Nor is the anonymous
+   * identity, which a v8 client that loaded signed out, or signed out, goes on
+   * handing out once another tab signs in and the answer turns yes. It signs
+   * no one in.
+   *
+   * A v10 client's answer is about the session it holds, and its identity
+   * replaces its short-lived delegation as it ages, so the delegation it holds
+   * can be past its expiry while the session is live. The answer stands alone.
    */
-  private async expireSession() {
-    try {
-      await this.authClient?.signOut()
-    } catch {
-      // Nothing to keep; fall through to anonymous either way.
+  public vouchesFor(
+    identity: Identity | null | undefined,
+    isAuthenticated: boolean
+  ): boolean {
+    return (
+      isAuthenticated &&
+      !(
+        this.authClientFlavor === "legacy" &&
+        (identity?.getPrincipal().isAnonymous() ||
+          hasExpiredDelegation(identity))
+      )
+    )
+  }
+
+  /**
+   * End a session the client no longer vouches for: put the anonymous
+   * identity on the agent -- which also sweeps the previous user's
+   * caller-scoped cache entries and refetches the rest anonymously -- and
+   * publish the signed-out state.
+   *
+   * A v8 client is also asked to forget the session when its
+   * `isAuthenticated()` answered no, since it keeps handing out the lapsed
+   * delegation until `signOut()` runs. That answer reads the expiry kept in
+   * the `localStorage` every tab shares, so it is no only once the session
+   * stored for every tab is over, and v8's `signOut()` takes no lock and
+   * revokes nothing. `signOut` failing changes nothing here: the delegation is
+   * already unusable, and the agent must not keep it. When the answer was yes,
+   * the delegation this tab holds lapsed under a session another tab has
+   * signed in to since, and `signOut()` would delete that session from the
+   * storage every tab shares. The client is left alone, and `vouchesFor()`
+   * keeps the lapsed delegation it goes on handing out off the agent.
+   *
+   * A v10 client is left alone, as `commitSignedOut()` leaves it. Its
+   * `signOut()` ends the sign-in for every tab of the origin: it takes the
+   * sign-in lock from a sign-in another tab has in progress, which then fails,
+   * revokes whatever session the shared store holds, and removes the record
+   * every tab reads. Another tab may have signed in again since this one last
+   * looked, and finding a session over is not the user asking to sign out.
+   * The client already stopped vouching for the session on its own.
+   *
+   * @param isAuthenticated - What the client's `isAuthenticated()` answered.
+   */
+  private async expireSession(isAuthenticated: boolean) {
+    if (this.authClientFlavor !== "session" && !isAuthenticated) {
+      try {
+        await this.authClient?.signOut()
+      } catch {
+        // Nothing to keep; fall through to anonymous either way.
+      }
     }
     const identity = new AnonymousIdentity()
     this.clientManager.updateAgent(identity)
@@ -524,18 +1156,33 @@ export class AuthenticationManager {
       return
     }
 
-    const identity = await this.authClient.getIdentity()
-    const isAuthenticated = await this.authClient.isAuthenticated()
-    if (revision !== this.authStateRevision) {
-      return
+    try {
+      const clientIdentity = await this.authClient.getIdentity()
+      const isAuthenticated = this.vouchesFor(
+        clientIdentity,
+        await this.authClient.isAuthenticated()
+      )
+      if (revision !== this.authStateRevision) {
+        return
+      }
+      // The rule `authenticate()` applies. A caller-built client can outlive
+      // the manager it was first given to, and once its session has lapsed it
+      // still hands out the lapsed identity while no longer vouching for it.
+      // Nothing may be signed with that.
+      const identity =
+        isAuthenticated || clientIdentity.getPrincipal().isAnonymous()
+          ? clientIdentity
+          : new AnonymousIdentity()
+      this.clientManager.updateAgent(identity)
+      this.updateState({
+        identity,
+        isAuthenticated,
+        isAuthenticating: false,
+        error: undefined,
+      })
+    } finally {
+      this.markSessionChecked()
     }
-    this.clientManager.updateAgent(identity)
-    this.updateState({
-      identity,
-      isAuthenticated,
-      isAuthenticating: false,
-      error: undefined,
-    })
   }
 
   /** @internal Used by IdentityAttributesManager. */
@@ -553,7 +1200,7 @@ export class AuthenticationManager {
       await this.clientManager.initializeAgent()
     }
     this.clientManager.updateAgent(identity)
-    this.updateState({ identity, isAuthenticated, isAuthenticating: false })
+    this.publishSession({ identity, isAuthenticated, isAuthenticating: false })
   }
 
   /** @internal Used by IdentityAttributesManager. */
@@ -566,6 +1213,34 @@ export class AuthenticationManager {
     this.updateState({ error, isAuthenticating: false })
   }
 
+  /** @internal Used by IdentityAttributesManager. */
+  public settleAuthenticating() {
+    this.updateState({ isAuthenticating: false })
+  }
+
+  /**
+   * @internal Used by IdentityAttributesManager.
+   *
+   * Signs this manager out after the client lost its session under it, as when
+   * another tab signed out. The client itself is left alone: a v10 sign-out
+   * clears the storage every tab shares and takes the sign-in lock, so it would
+   * also end a sign-in the other tab has made or started since.
+   */
+  public commitSignedOut() {
+    const identity = new AnonymousIdentity()
+    // As in `authenticate()`, an agent that is anonymous already is left as it
+    // is: its cache holds no signed-in user's data, and re-installing it would
+    // only refetch every query.
+    if (!this.agentIsAnonymous()) {
+      this.clientManager.updateAgent(identity)
+    }
+    this.publishSession({
+      identity,
+      isAuthenticated: false,
+      isAuthenticating: false,
+    })
+  }
+
   private getDefaultIdentityProvider(): string | URL {
     if (this.identityProvider) {
       return this.identityProvider
@@ -582,7 +1257,10 @@ export class AuthenticationManager {
     // it, instead of opening a popup onto the gateway's verification-error page
     // and leaving the app waiting until the user closes it.
     if (this.localAuthorizePath === null) {
-      throw localInternetIdentityUnavailableError(canisterId)
+      throw localInternetIdentityUnavailableError(
+        canisterId,
+        this.authClientFlavor
+      )
     }
 
     return localInternetIdentityProvider(
@@ -592,13 +1270,63 @@ export class AuthenticationManager {
     )
   }
 
+  /**
+   * Publishes what a check of the session found, then marks the session
+   * checked. In that order, so the auth hooks never take the state before it
+   * for the answer.
+   */
+  private publishSession(newState: Partial<AuthState>) {
+    try {
+      this.updateState(newState)
+    } finally {
+      this.markSessionChecked()
+    }
+  }
+
+  /**
+   * Records a change, then tells every subscriber about it.
+   *
+   * Every subscriber is called even when one throws, and the first error is
+   * rethrown once they all have been, so the caller still sees it. A throw
+   * used to end the loop: an app's subscriber registered at module scope comes
+   * before every `useAuth()`, and one that failed on a sign-in left them all
+   * showing `isAuthenticating: true` while the agent signed as the user.
+   *
+   * A subscriber that changes the state again from its callback has told every
+   * subscriber about that newer state, so the loop stops rather than deliver
+   * this older one after it. The list is copied first, so a subscriber added
+   * during the loop is first called for the next change. `ClientManager`
+   * notifies its subscribers the same way.
+   */
   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)
-    )
+    const revision = ++this.authStateRevision
+    const state = { ...this.authStateValue, ...newState }
+    this.authStateValue = state
+
+    let failure: { error: unknown } | undefined
+    for (const subscriber of [...this.authStateSubscribers]) {
+      if (revision !== this.authStateRevision) break
+      try {
+        subscriber(state)
+      } catch (error) {
+        failure ??= { error }
+      }
+    }
+    // The operation that held off `followClient()` is over: read the client
+    // again, once its caller has moved on.
+    const client = this.authClient
+    if (
+      this.clientChangedDuringOperation &&
+      !this.authStateValue.isAuthenticating &&
+      client
+    ) {
+      this.clientChangedDuringOperation = false
+      void Promise.resolve()
+        .then(() => this.followClient(client))
+        .catch(() => undefined)
+    }
+    if (failure) throw failure.error
   }
 
   private async loadAuthClientConstructor() {
@@ -618,6 +1346,7 @@ export class AuthenticationManager {
           }
 
           this.authClientConstructor = AuthClient
+          this.authClientFlavor = detectAuthClientFlavor(AuthClient)
           return AuthClient
         })
         .catch((error) => {
@@ -668,6 +1397,74 @@ function importAuthClientModule(): Promise<unknown> {
   }
 }
 
+/**
+ * Releases a client IC Reactor built and no longer uses. `dispose()` exists
+ * from `@icp-sdk/auth` v9; a v8 client has nothing to release. A throw is
+ * ignored: the client is being discarded either way.
+ */
+function disposeClient(client: AuthClientLike) {
+  try {
+    ;(client as { dispose?: () => void }).dispose?.()
+  } catch {
+    // Nothing more can be done for a client that failed to let go.
+  }
+}
+
+/** The wrapper each app `onIdle` gets; see {@link withSharedIdleCallback}. */
+const sharedIdleCallbacks = new WeakMap<() => unknown, () => unknown>()
+
+/**
+ * Hands every v8 client the same wrapper around the app's `idleOptions.onIdle`.
+ *
+ * v8's `IdleManager` is one per page. Each client registers its `onIdle` on it
+ * once it signs in or restores a session, and a callback cannot be removed, so
+ * a manager that rebuilt its client for per-call options ran the app's `onIdle`
+ * once per client it had built on every idle period: three times after a
+ * sign-in, a one-click sign-in and another sign-in (#729). The `IdleManager`
+ * runs its callbacks in one synchronous loop, so the wrapper runs `onIdle` on
+ * the first call of a loop and skips the calls after it. The same function
+ * gets the same wrapper however many managers pass it.
+ */
+function withSharedIdleCallback(
+  options?: AuthenticationClientOptions
+): AuthenticationClientOptions | undefined {
+  const onIdle = options?.idleOptions?.onIdle
+  if (!onIdle) {
+    return options
+  }
+  let shared = sharedIdleCallbacks.get(onIdle)
+  if (!shared) {
+    let running = false
+    shared = () => {
+      if (running) return undefined
+      running = true
+      // Cleared once the loop that called it is over, so the next idle period
+      // runs `onIdle` again.
+      queueMicrotask(() => {
+        running = false
+      })
+      return onIdle()
+    }
+    sharedIdleCallbacks.set(onIdle, shared)
+  }
+  return { ...options, idleOptions: { ...options.idleOptions, onIdle: shared } }
+}
+
+/**
+ * Whether `identity` signs with a delegation chain that has expired, as a
+ * `DelegationIdentity` or `PartialDelegationIdentity` does once its session
+ * lapses. Read by shape rather than `instanceof`, which a second copy of
+ * `@icp-sdk/core` in the app would defeat.
+ */
+function hasExpiredDelegation(identity: Identity | null | undefined): boolean {
+  const delegated = identity as
+    { getDelegation?: () => DelegationChain } | null | undefined
+  if (typeof delegated?.getDelegation !== "function") {
+    return false
+  }
+  return !isDelegationValid(delegated.getDelegation())
+}
+
 function getAuthClientOptions(
   options?: AuthenticationClientOptions
 ): AuthenticationClientOptions | undefined {
@@ -685,6 +1482,7 @@ function getAuthClientOptions(
     idleOptions: options.idleOptions,
     identity: options.identity,
     transport: options.transport,
+    disableBrowserActivity: options.disableBrowserActivity,
   }
 }
 
@@ -703,9 +1501,18 @@ function getAuthClientOpenIdProvider(
  * options (`storage`, `identity`, `idleOptions`) are compared by reference,
  * which is what module-scoped configuration produces.
  */
+/**
+ * Whether two option sets build the same client on the installed major.
+ *
+ * A key that major drops cannot change the client it builds, so a difference
+ * there must not cause a rebuild, which would throw away the prepared client:
+ * the v8-only `storage`, `keyType`, `idleOptions` and `identity` on v10, and the
+ * v10-only `disableBrowserActivity` on v8.
+ */
 function isSameAuthClientOptions(
-  current?: AuthenticationClientOptions,
-  next?: AuthenticationClientOptions
+  current: AuthenticationClientOptions | undefined,
+  next: AuthenticationClientOptions | undefined,
+  flavor: AuthClientFlavor
 ): boolean {
   if (current === next) {
     return true
@@ -714,19 +1521,24 @@ function isSameAuthClientOptions(
     return false
   }
 
-  return (
+  const sameShared =
     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
-  )
+
+  const sameForFlavor =
+    flavor === "session"
+      ? current.disableBrowserActivity === next.disableBrowserActivity
+      : current.storage === next.storage &&
+        current.keyType === next.keyType &&
+        current.idleOptions === next.idleOptions &&
+        current.identity === next.identity
+
+  return sameShared && sameForFlavor
 }
 
 /**
@@ -832,15 +1644,24 @@ function getAuthenticationCanisterEnv(): Record<string, string> | undefined {
     return undefined
   }
 
+  // Anything able to set a cookie here can write this one, a sibling subdomain
+  // or, on localhost, an app on another port. A value that is not valid
+  // percent-encoding is ignored, as `safeGetCanisterEnv` ignores it: throwing
+  // would fail the constructor, and every `useAuth()` render with it.
+  let decodedValue: string
+  try {
+    decodedValue = decodeURIComponent(encodedValue)
+  } catch {
+    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)]
-      })
+    decodedValue.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
@@ -855,6 +1676,7 @@ function getSignInOptions(
 
   return {
     maxTimeToLive: options.maxTimeToLive,
+    maxTimeToIdle: options.maxTimeToIdle,
     targets: options.targets,
   }
 }