@icp-sdk/auth 5.0.0 → 6.1.0

package/src/client/auth-client.ts

@@ -1,12 +1,5 @@
+import { AnonymousIdentity, type Identity, type SignIdentity } from '@icp-sdk/core/agent';
 import {
-  AnonymousIdentity,
-  type DerEncodedPublicKey,
-  type Identity,
-  type Signature,
-  type SignIdentity,
-} from '@icp-sdk/core/agent';
-import {
-  Delegation,
   DelegationChain,
   DelegationIdentity,
   ECDSAKeyIdentity,
@@ -16,7 +9,9 @@ import {
   type PartialIdentity,
 } from '@icp-sdk/core/identity';
 import type { Principal } from '@icp-sdk/core/principal';
-import { IdleManager, type IdleManagerOptions } from './idle-manager.ts';
+import { Signer } from '@icp-sdk/signer';
+import { PostMessageTransport } from '@icp-sdk/signer/web';
+import { IdleManager, type IdleManagerOptions } from './idle-manager.js';
 import {
   type AuthClientStorage,
   IdbStorage,
@@ -25,592 +20,556 @@ import {
   KEY_VECTOR,
   LocalStorage,
   type StoredKey,
-} from './storage.ts';
+} from './storage.js';
 
 const NANOSECONDS_PER_SECOND = BigInt(1_000_000_000);
 const SECONDS_PER_HOUR = BigInt(3_600);
 const NANOSECONDS_PER_HOUR = NANOSECONDS_PER_SECOND * SECONDS_PER_HOUR;
 
-const IDENTITY_PROVIDER_DEFAULT = 'https://identity.internetcomputer.org';
-const IDENTITY_PROVIDER_ENDPOINT = '#authorize';
-
+const IDENTITY_PROVIDER_DEFAULT = 'https://id.ai/authorize';
 const DEFAULT_MAX_TIME_TO_LIVE = BigInt(8) * NANOSECONDS_PER_HOUR;
 
 const ECDSA_KEY_LABEL = 'ECDSA';
 const ED25519_KEY_LABEL = 'Ed25519';
 type BaseKeyType = typeof ECDSA_KEY_LABEL | typeof ED25519_KEY_LABEL;
 
-const INTERRUPT_CHECK_INTERVAL = 500;
+// localStorage key used to cache the delegation expiration so that
+// isAuthenticated() can answer synchronously without hitting IndexedDB.
+const KEY_STORAGE_EXPIRATION = 'ic-delegation_expiration';
+
+export type OpenIdProvider = 'google' | 'apple' | 'microsoft';
+
+export const OPENID_PROVIDER_URLS = {
+  google: 'https://accounts.google.com',
+  apple: 'https://appleid.apple.com',
+  microsoft: 'https://login.microsoftonline.com/{tid}/v2.0',
+} as const satisfies Record<OpenIdProvider, string>;
 
-export const ERROR_USER_INTERRUPT = 'UserInterrupt';
+const DEFAULT_OPENID_SCOPE_KEYS = ['name', 'email', 'verified_email'] as const;
 
 /**
- * List of options for creating an {@link AuthClient}.
+ * Options for creating an {@link AuthClient}.
  */
 export interface AuthClientCreateOptions {
   /**
-   * An {@link SignIdentity} or {@link PartialIdentity} to authenticate via delegation.
+   * An identity to authenticate via delegation.
    */
   identity?: SignIdentity | PartialIdentity;
+
   /**
-   * Optional storage with get, set, and remove. Uses {@link IdbStorage} by default.
-   * @see {@link AuthClientStorage}
+   * Persistent storage backend. Defaults to IndexedDB.
+   * @default IdbStorage
    */
   storage?: AuthClientStorage;
 
   /**
-   * Type to use for the base key.
+   * Type of session key to generate on each sign-in.
    *
-   * If you are using a custom storage provider that does not support CryptoKey storage,
-   * you should use `Ed25519` as the key type, as it can serialize to a string.
+   * Use `'Ed25519'` when your storage provider does not support `CryptoKey`.
    * @default 'ECDSA'
    */
   keyType?: BaseKeyType;
 
   /**
-   * Options to handle idle timeouts
+   * Idle timeout configuration.
    * @default after 10 minutes, invalidates the identity
    */
   idleOptions?: IdleOptions;
 
   /**
-   * Options to handle login, passed to the login method
-   */
-  loginOptions?: AuthClientLoginOptions;
-}
-
-export interface IdleOptions extends IdleManagerOptions {
-  /**
-   * Disables idle functionality for {@link IdleManager}
-   * @default false
-   */
-  disableIdle?: boolean;
-
-  /**
-   * Disables default idle behavior - call logout & reload window
-   * @default false
-   */
-  disableDefaultIdleCallback?: boolean;
-}
-
-export type OnSuccessFunc =
-  | (() => void | Promise<void>)
-  | ((message: InternetIdentityAuthResponseSuccess) => void | Promise<void>);
-
-export type OnErrorFunc = (error?: string) => void | Promise<void>;
-
-export interface AuthClientLoginOptions {
-  /**
-   * Identity provider
-   * @default "https://identity.internetcomputer.org"
+   * Identity provider URL.
+   * @default "https://id.ai/authorize"
    */
   identityProvider?: string | URL;
+
   /**
-   * Expiration of the authentication in nanoseconds
-   * @default  BigInt(8) hours * BigInt(3_600_000_000_000) nanoseconds
-   */
-  maxTimeToLive?: bigint;
-  /**
-   * If present, indicates whether or not the Identity Provider should allow the user to authenticate and/or register using a temporary key/PIN identity. Authenticating dapps may want to prevent users from using Temporary keys/PIN identities because Temporary keys/PIN identities are less secure than Passkeys (webauthn credentials) and because Temporary keys/PIN identities generally only live in a browser database (which may get cleared by the browser/OS).
-   */
-  allowPinAuthentication?: boolean;
-  /**
-   * Origin for Identity Provider to use while generating the delegated identity. For II, the derivation origin must authorize this origin by setting a record at `<derivation-origin>/.well-known/ii-alternative-origins`.
+   * Derivation origin for the identity provider.
    * @see https://github.com/dfinity/internet-identity/blob/main/docs/internet-identity-spec.adoc
    */
   derivationOrigin?: string | URL;
+
   /**
-   * Auth Window feature config string
+   * Window features string for the authentication popup.
    * @example "toolbar=0,location=0,menubar=0,width=500,height=500,left=100,top=100"
    */
   windowOpenerFeatures?: string;
+
   /**
-   * Callback once login has completed
+   * OpenID provider for one-click sign-in. When set, the identity provider
+   * URL includes an `openid` search param so the user authenticates via
+   * the chosen provider (e.g. Google) instead of seeing Internet Identity directly.
    */
-  onSuccess?: OnSuccessFunc;
+  openIdProvider?: OpenIdProvider;
+}
+
+export interface IdleOptions extends IdleManagerOptions {
   /**
-   * Callback in case authentication fails
+   * Disables idle functionality entirely.
+   * @default false
    */
-  onError?: OnErrorFunc;
+  disableIdle?: boolean;
+
   /**
-   * Extra values to be passed in the login request during the authorize-ready phase
+   * Disables the default idle callback (logout & reload).
+   * @default false
    */
-  customValues?: Record<string, unknown>;
+  disableDefaultIdleCallback?: boolean;
 }
 
-interface InternetIdentityAuthRequest {
-  kind: 'authorize-client';
-  sessionPublicKey: Uint8Array;
+/**
+ * Options for {@link AuthClient.signIn}.
+ */
+export interface AuthClientSignInOptions {
+  /**
+   * Maximum lifetime of the delegation in nanoseconds.
+   * @default 8 hours
+   */
   maxTimeToLive?: bigint;
-  allowPinAuthentication?: boolean;
-  derivationOrigin?: string;
-}
 
-export interface InternetIdentityAuthResponseSuccess {
-  kind: 'authorize-client-success';
-  delegations: {
-    delegation: {
-      pubkey: Uint8Array;
-      expiration: bigint;
-      targets?: Principal[];
-    };
-    signature: Uint8Array;
-  }[];
-  userPublicKey: Uint8Array;
-  authnMethod: 'passkey' | 'pin' | 'recovery';
-}
-
-interface AuthReadyMessage {
-  kind: 'authorize-ready';
-}
-
-interface AuthResponseSuccess {
-  kind: 'authorize-client-success';
-  delegations: {
-    delegation: {
-      pubkey: Uint8Array;
-      expiration: bigint;
-      targets?: Principal[];
-    };
-    signature: Uint8Array;
-  }[];
-  userPublicKey: Uint8Array;
-  authnMethod: 'passkey' | 'pin' | 'recovery';
+  /**
+   * Restrict the delegation to specific canisters.
+   */
+  targets?: Principal[];
 }
 
-interface AuthResponseFailure {
-  kind: 'authorize-client-failure';
-  text: string;
+export interface SignedAttributes {
+  data: Uint8Array;
+  signature: Uint8Array;
 }
 
-type IdentityServiceResponseMessage = AuthReadyMessage | AuthResponse;
-type AuthResponse = AuthResponseSuccess | AuthResponseFailure;
-
 /**
- * Tool to manage authentication and identity
- * @see {@link AuthClient}
+ * Manages authentication and identity for Internet Computer web apps.
+ *
+ * @example
+ * const authClient = new AuthClient();
+ *
+ * const identity = authClient.isAuthenticated()
+ *   ? await authClient.getIdentity()
+ *   : await authClient.signIn();
  */
 export class AuthClient {
-  /**
-   * Create an AuthClient to manage authentication and identity
-   * @param {AuthClientCreateOptions} options - Options for creating an {@link AuthClient}
-   * @see {@link AuthClientCreateOptions}
-   * @param options.identity Optional Identity to use as the base
-   * @see {@link SignIdentity}
-   * @param options.storage Storage mechanism for delegation credentials
-   * @see {@link AuthClientStorage}
-   * @param options.keyType Type of key to use for the base key
-   * @param {IdleOptions} options.idleOptions Configures an {@link IdleManager}
-   * @see {@link IdleOptions}
-   * Default behavior is to clear stored identity and reload the page when a user goes idle, unless you set the disableDefaultIdleCallback flag or pass in a custom idle callback.
-   * @example
-   * const authClient = await AuthClient.create({
-   *   idleOptions: {
-   *     disableIdle: true
-   *   }
-   * })
-   */
-  public static async create(options: AuthClientCreateOptions = {}): Promise<AuthClient> {
-    const storage = options.storage ?? new IdbStorage();
-    const keyType = options.keyType ?? ECDSA_KEY_LABEL;
+  #identity: Identity | PartialIdentity = new AnonymousIdentity();
+  #chain: DelegationChain | null = null;
+  #storage: AuthClientStorage;
+  #signer: Signer;
+  #options: AuthClientCreateOptions;
+  #initPromise: Promise<void> | null = null;
+  idleManager: IdleManager | undefined;
+
+  constructor(options: AuthClientCreateOptions = {}) {
+    this.#options = options;
+    this.#storage = options.storage ?? new IdbStorage();
 
-    let key: null | SignIdentity | PartialIdentity = null;
-    if (options.identity) {
-      key = options.identity;
-    } else {
-      let maybeIdentityStorage = await storage.get(KEY_STORAGE_KEY);
-      if (!maybeIdentityStorage) {
-        // Attempt to migrate from localstorage
-        try {
-          const fallbackLocalStorage = new LocalStorage();
-          const localChain = await fallbackLocalStorage.get(KEY_STORAGE_DELEGATION);
-          const localKey = await fallbackLocalStorage.get(KEY_STORAGE_KEY);
-          // not relevant for Ed25519
-          if (localChain && localKey && keyType === ECDSA_KEY_LABEL) {
-            console.log('Discovered an identity stored in localstorage. Migrating to IndexedDB');
-            await storage.set(KEY_STORAGE_DELEGATION, localChain);
-            await storage.set(KEY_STORAGE_KEY, localKey);
-
-            maybeIdentityStorage = localChain;
-            // clean up
-            await fallbackLocalStorage.remove(KEY_STORAGE_DELEGATION);
-            await fallbackLocalStorage.remove(KEY_STORAGE_KEY);
-          }
-        } catch (error) {
-          console.error(`error while attempting to recover localstorage: ${error}`);
-        }
-      }
-      if (maybeIdentityStorage) {
-        try {
-          if (typeof maybeIdentityStorage === 'object') {
-            if (keyType === ED25519_KEY_LABEL && typeof maybeIdentityStorage === 'string') {
-              key = Ed25519KeyIdentity.fromJSON(maybeIdentityStorage);
-            } else {
-              key = await ECDSAKeyIdentity.fromKeyPair(maybeIdentityStorage);
-            }
-          } else if (typeof maybeIdentityStorage === 'string') {
-            // This is a legacy identity, which is a serialized Ed25519KeyIdentity.
-            key = Ed25519KeyIdentity.fromJSON(maybeIdentityStorage);
-          }
-        } catch {
-          // Ignore this, this means that the localStorage value isn't a valid Ed25519KeyIdentity or ECDSAKeyIdentity
-          // serialization.
-        }
-      }
+    const identityProviderUrl = new URL(
+      options.identityProvider?.toString() || IDENTITY_PROVIDER_DEFAULT,
+    );
+    if (options.openIdProvider) {
+      identityProviderUrl.searchParams.set('openid', OPENID_PROVIDER_URLS[options.openIdProvider]);
     }
 
-    let identity: SignIdentity | PartialIdentity = new AnonymousIdentity() as PartialIdentity;
-    let chain: null | DelegationChain = null;
-    if (key) {
-      try {
-        const chainStorage = await storage.get(KEY_STORAGE_DELEGATION);
-        if (typeof chainStorage === 'object' && chainStorage !== null) {
-          throw new Error(
-            'Delegation chain is incorrectly stored. A delegation chain should be stored as a string.',
-          );
-        }
-
-        if (options.identity) {
-          identity = options.identity;
-        } else if (chainStorage) {
-          chain = DelegationChain.fromJSON(chainStorage);
-
-          // Verify that the delegation isn't expired.
-          if (!isDelegationValid(chain)) {
-            await _deleteStorage(storage);
-            key = null;
-          } else {
-            // If the key is a public key, then we create a PartialDelegationIdentity.
-            if ('toDer' in key) {
-              identity = PartialDelegationIdentity.fromDelegation(key, chain);
-              // otherwise, we create a DelegationIdentity.
-            } else {
-              identity = DelegationIdentity.fromDelegation(key, chain);
-            }
-          }
-        }
-      } catch (e) {
-        console.error(e);
-        // If there was a problem loading the chain, delete the key.
-        await _deleteStorage(storage);
-        key = null;
-      }
-    }
-    let idleManager: IdleManager | undefined;
-    if (options.idleOptions?.disableIdle) {
-      idleManager = undefined;
-    }
-    // if there is a delegation chain or provided identity, setup idleManager
-    else if (chain || options.identity) {
-      idleManager = IdleManager.create(options.idleOptions);
-    }
+    const transport = new PostMessageTransport({
+      url: identityProviderUrl.toString(),
+      windowOpenerFeatures: options.windowOpenerFeatures,
+    });
 
-    if (!key) {
-      // Create a new key (whether or not one was in storage).
-      if (keyType === ED25519_KEY_LABEL) {
-        key = Ed25519KeyIdentity.generate();
-      } else {
-        if (options.storage && keyType === ECDSA_KEY_LABEL) {
-          console.warn(
-            `You are using a custom storage provider that may not support CryptoKey storage. If you are using a custom storage provider that does not support CryptoKey storage, you should use '${ED25519_KEY_LABEL}' as the key type, as it can serialize to a string`,
-          );
-        }
-        key = await ECDSAKeyIdentity.generate();
-      }
-      await persistKey(storage, key);
-    }
+    this.#signer = new Signer({
+      transport,
+      derivationOrigin: options.derivationOrigin?.toString(),
+    });
+
+    this.#registerDefaultIdleCallback();
 
-    return new AuthClient(identity, key, chain, storage, idleManager, options);
+    // Eagerly start restoring a previous session from storage.
+    // The result is awaited in getIdentity() before returning.
+    this.#init();
   }
 
-  protected constructor(
-    private _identity: Identity | PartialIdentity,
-    private _key: SignIdentity | PartialIdentity,
-    private _chain: DelegationChain | null,
-    private _storage: AuthClientStorage,
-    public idleManager: IdleManager | undefined,
-    private _createOptions: AuthClientCreateOptions | undefined,
-    // A handle on the IdP window.
-    private _idpWindow?: Window,
-    // The event handler for processing events from the IdP.
-    private _eventHandler?: (event: MessageEvent) => void,
-  ) {
-    this._registerDefaultIdleCallback();
+  /**
+   * Returns the current identity, restoring a previous session if available.
+   */
+  async getIdentity(): Promise<Identity> {
+    await this.#init();
+    return this.#identity;
   }
 
-  private _registerDefaultIdleCallback() {
-    const idleOptions = this._createOptions?.idleOptions;
-    /**
-     * Default behavior is to clear stored identity and reload the page.
-     * By either setting the disableDefaultIdleCallback flag or passing in a custom idle callback, we will ignore this config
-     */
-    if (!idleOptions?.onIdle && !idleOptions?.disableDefaultIdleCallback) {
-      this.idleManager?.registerCallback(() => {
-        this.logout();
-        location.reload();
-      });
-    }
+  /**
+   * Checks whether the user has an active, non-expired session.
+   */
+  isAuthenticated(): boolean {
+    // Uses a cached expiration in localStorage to avoid an async IndexedDB read.
+    const expiration = getExpirationFlag();
+    if (expiration === null) return false;
+    const nowNs = BigInt(Date.now()) * BigInt(1_000_000);
+    return nowNs < expiration;
   }
 
-  private async _handleSuccess(
-    message: InternetIdentityAuthResponseSuccess,
-    onSuccess?: OnSuccessFunc,
-  ) {
-    const delegations = message.delegations.map((signedDelegation) => {
-      return {
-        delegation: new Delegation(
-          signedDelegation.delegation.pubkey,
-          signedDelegation.delegation.expiration,
-          signedDelegation.delegation.targets,
-        ),
-        signature: signedDelegation.signature as Signature,
-      };
-    });
+  /**
+   * Opens the identity provider, requests a delegation, and returns the authenticated identity.
+   *
+   * @param options - Sign-in options.
+   * @param options.maxTimeToLive - Maximum lifetime of the delegation in nanoseconds.
+   * @param options.targets - Restrict the delegation to specific canisters.
+   * @returns The authenticated identity.
+   * @throws When authentication fails.
+   *
+   * @example
+   * try {
+   *   const identity = await authClient.signIn();
+   * } catch (error) {
+   *   console.error('Sign-in failed:', error);
+   * }
+   */
+  async signIn(options?: AuthClientSignInOptions): Promise<Identity> {
+    await this.#signer.openChannel();
 
-    const delegationChain = DelegationChain.fromDelegations(
-      delegations,
-      message.userPublicKey as DerEncodedPublicKey,
-    );
+    const maxTimeToLive = options?.maxTimeToLive ?? DEFAULT_MAX_TIME_TO_LIVE;
 
-    const key = this._key;
-    if (!key) {
-      return;
-    }
+    // Fresh key per sign-in so each session has its own cryptographic identity.
+    const key =
+      this.#options.identity ?? (await generateKey(this.#options.keyType ?? ECDSA_KEY_LABEL));
+
+    const delegationChain = await this.#signer.requestDelegation({
+      publicKey: key.getPublicKey(),
+      targets: options?.targets,
+      maxTimeToLive,
+    });
 
-    this._chain = delegationChain;
+    this.#chain = delegationChain;
 
+    // PartialIdentity only has the public key — no signing capability.
     if ('toDer' in key) {
-      this._identity = PartialDelegationIdentity.fromDelegation(key, this._chain);
+      this.#identity = PartialDelegationIdentity.fromDelegation(key, this.#chain);
     } else {
-      this._identity = DelegationIdentity.fromDelegation(key, this._chain);
+      this.#identity = DelegationIdentity.fromDelegation(key, this.#chain);
     }
 
-    this._idpWindow?.close();
-    const idleOptions = this._createOptions?.idleOptions;
-    // create the idle manager on a successful login if we haven't disabled it
-    // and it doesn't already exist.
+    const idleOptions = this.#options?.idleOptions;
     if (!this.idleManager && !idleOptions?.disableIdle) {
       this.idleManager = IdleManager.create(idleOptions);
-      this._registerDefaultIdleCallback();
+      this.#registerDefaultIdleCallback();
     }
 
-    this._removeEventListener();
-    delete this._idpWindow;
+    // Persist so the session survives page reloads.
+    await persistChain(this.#storage, this.#chain);
+    await persistKey(this.#storage, key);
+
+    return this.#identity;
+  }
+
+  /**
+   * Requests signed identity attributes from the identity provider.
+   *
+   * @param params - Request parameters.
+   * @param params.keys - Attribute keys to request (e.g. `['email', 'name']`).
+   * @param params.nonce - 32-byte nonce issued by the RP canister.
+   * @returns Signed attribute data and signature.
+   * @throws When the identity provider returns an error or an invalid response.
+   */
+  async requestAttributes(params: {
+    keys: string[];
+    nonce: Uint8Array;
+  }): Promise<SignedAttributes> {
+    const nonceBytes = params.nonce;
+
+    const response = await this.#signer.sendRequest({
+      jsonrpc: '2.0',
+      method: 'ii-icrc3-attributes',
+      params: { keys: params.keys, nonce: toBase64(nonceBytes) },
+    });
 
-    if (this._chain) {
-      await this._storage.set(KEY_STORAGE_DELEGATION, JSON.stringify(this._chain.toJSON()));
+    if ('error' in response) {
+      throw new Error(response.error.message);
     }
 
-    // Ensure the stored key in persistent storage matches the in-memory key that
-    // was used to obtain the delegation. This avoids key/delegation mismatches
-    // across multiple tabs overwriting each other's cached keys.
-    await persistKey(this._storage, this._key);
+    const result = response.result as Record<string, unknown> | undefined;
+    if (typeof result?.data !== 'string' || typeof result?.signature !== 'string') {
+      throw new Error('Invalid response: missing data or signature');
+    }
 
-    // onSuccess should be the last thing to do to avoid consumers
-    // interfering by navigating or refreshing the page
-    onSuccess?.(message);
+    try {
+      return {
+        data: fromBase64(result.data),
+        signature: fromBase64(result.signature),
+      };
+    } catch (cause) {
+      throw new Error('Invalid response: data or signature is not valid base64', { cause });
+    }
   }
 
-  public getIdentity(): Identity {
-    return this._identity;
+  /**
+   * Clears the stored session and resets the client to an anonymous state.
+   *
+   * @param options - Logout options.
+   * @param options.returnTo - URL to navigate to after logout.
+   */
+  async logout(options: { returnTo?: string } = {}): Promise<void> {
+    await deleteStorage(this.#storage);
+
+    this.#identity = new AnonymousIdentity();
+    this.#chain = null;
+
+    if (options.returnTo) {
+      try {
+        window.history.pushState({}, '', options.returnTo);
+      } catch {
+        window.location.href = options.returnTo;
+      }
+    }
   }
 
-  public async isAuthenticated(): Promise<boolean> {
-    return (
-      !this.getIdentity().getPrincipal().isAnonymous() &&
-      this._chain !== null &&
-      isDelegationValid(this._chain)
-    );
+  // Memoized — only runs #hydrate once, returns the same promise on repeat calls.
+  #init(): Promise<void> {
+    if (!this.#initPromise) {
+      this.#initPromise = this.#hydrate();
+    }
+    return this.#initPromise;
   }
 
-  /**
-   * AuthClient Login - Opens up a new window to authenticate with Internet Identity
-   * @param {AuthClientLoginOptions} options - Options for logging in, merged with the options set during creation if any. Note: we only perform a shallow merge for the `customValues` property.
-   * @param options.identityProvider Identity provider
-   * @param options.maxTimeToLive Expiration of the authentication in nanoseconds
-   * @param options.allowPinAuthentication If present, indicates whether or not the Identity Provider should allow the user to authenticate and/or register using a temporary key/PIN identity. Authenticating dapps may want to prevent users from using Temporary keys/PIN identities because Temporary keys/PIN identities are less secure than Passkeys (webauthn credentials) and because Temporary keys/PIN identities generally only live in a browser database (which may get cleared by the browser/OS).
-   * @param options.derivationOrigin Origin for Identity Provider to use while generating the delegated identity
-   * @param options.windowOpenerFeatures Configures the opened authentication window
-   * @param options.onSuccess Callback once login has completed
-   * @param options.onError Callback in case authentication fails
-   * @param options.customValues Extra values to be passed in the login request during the authorize-ready phase. Note: we only perform a shallow merge for the `customValues` property.
-   * @example
-   * const authClient = await AuthClient.create();
-   * authClient.login({
-   *  identityProvider: 'http://<canisterID>.127.0.0.1:8000',
-   *  maxTimeToLive: BigInt (7) * BigInt(24) * BigInt(3_600_000_000_000), // 1 week
-   *  windowOpenerFeatures: "toolbar=0,location=0,menubar=0,width=500,height=500,left=100,top=100",
-   *  onSuccess: () => {
-   *    console.log('Login Successful!');
-   *  },
-   *  onError: (error) => {
-   *    console.error('Login Failed: ', error);
-   *  }
-   * });
-   */
-  public async login(options?: AuthClientLoginOptions): Promise<void> {
-    // Merge the passed options with the options set during creation
-    const loginOptions = mergeLoginOptions(this._createOptions?.loginOptions, options);
+  // Attempts to restore a previous session (key + delegation chain) from
+  // storage. If found and still valid, sets #identity and #chain so the
+  // client is ready to use without a new signIn().
+  async #hydrate(): Promise<void> {
+    const key =
+      this.#options.identity ??
+      (await restoreKey(this.#storage, this.#options.keyType ?? ECDSA_KEY_LABEL));
+    if (!key) return;
 
-    // Set default maxTimeToLive to 8 hours
-    const maxTimeToLive = loginOptions?.maxTimeToLive ?? DEFAULT_MAX_TIME_TO_LIVE;
+    const chain = await restoreChain(this.#storage);
+    if (!chain) return;
 
-    // Create the URL of the IDP. (e.g. https://XXXX/#authorize)
-    const identityProviderUrl = new URL(
-      loginOptions?.identityProvider?.toString() || IDENTITY_PROVIDER_DEFAULT,
-    );
-    // Set the correct hash if it isn't already set.
-    identityProviderUrl.hash = IDENTITY_PROVIDER_ENDPOINT;
+    this.#chain = chain;
+    if ('toDer' in key) {
+      this.#identity = PartialDelegationIdentity.fromDelegation(key, chain);
+    } else {
+      this.#identity = DelegationIdentity.fromDelegation(key, chain);
+    }
 
-    // If `login` has been called previously, then close/remove any previous windows
-    // and event listeners.
-    this._idpWindow?.close();
-    this._removeEventListener();
+    if (!this.#options.idleOptions?.disableIdle && !this.idleManager) {
+      this.idleManager = IdleManager.create(this.#options.idleOptions);
+      this.#registerDefaultIdleCallback();
+    }
+  }
 
-    // Add an event listener to handle responses.
-    this._eventHandler = this._getEventHandler(identityProviderUrl, {
-      maxTimeToLive,
-      ...loginOptions,
-    });
-    window.addEventListener('message', this._eventHandler);
-
-    // Open a new window with the IDP provider.
-    this._idpWindow =
-      window.open(
-        identityProviderUrl.toString(),
-        'idpWindow',
-        loginOptions?.windowOpenerFeatures,
-      ) ?? undefined;
-
-    // Check if the _idpWindow is closed by user.
-    const checkInterruption = (): void => {
-      // The _idpWindow is opened and not yet closed by the client
-      if (this._idpWindow) {
-        if (this._idpWindow.closed) {
-          this._handleFailure(ERROR_USER_INTERRUPT, loginOptions?.onError);
-        } else {
-          setTimeout(checkInterruption, INTERRUPT_CHECK_INTERVAL);
-        }
-      }
-    };
-    checkInterruption();
+  #registerDefaultIdleCallback() {
+    const idleOptions = this.#options?.idleOptions;
+    if (!idleOptions?.onIdle && !idleOptions?.disableDefaultIdleCallback) {
+      this.idleManager?.registerCallback(() => {
+        this.logout();
+        location.reload();
+      });
+    }
   }
+}
 
-  private _getEventHandler(identityProviderUrl: URL, options?: AuthClientLoginOptions) {
-    return async (event: MessageEvent) => {
-      if (event.origin !== identityProviderUrl.origin) {
-        // Ignore any event that is not from the identity provider
-        return;
-      }
+/**
+ * Encodes a Uint8Array to a base64 string.
+ * @param bytes - The bytes to encode.
+ */
+function toBase64(bytes: Uint8Array): string {
+  if ('toBase64' in bytes && typeof bytes.toBase64 === 'function') {
+    return bytes.toBase64();
+  }
+  let binary = '';
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return globalThis.btoa(binary);
+}
 
-      const message = event.data as IdentityServiceResponseMessage;
-
-      switch (message.kind) {
-        case 'authorize-ready': {
-          // IDP is ready. Send a message to request authorization.
-          const request: InternetIdentityAuthRequest = {
-            kind: 'authorize-client',
-            sessionPublicKey: new Uint8Array(this._key?.getPublicKey().toDer()),
-            maxTimeToLive: options?.maxTimeToLive,
-            allowPinAuthentication: options?.allowPinAuthentication,
-            derivationOrigin: options?.derivationOrigin?.toString(),
-            // Pass any custom values to the IDP.
-            ...options?.customValues,
-          };
-          this._idpWindow?.postMessage(request, identityProviderUrl.origin);
-          break;
-        }
-        case 'authorize-client-success':
-          // Create the delegation chain and store it.
-          try {
-            await this._handleSuccess(message, options?.onSuccess);
-          } catch (err) {
-            this._handleFailure((err as Error).message, options?.onError);
-          }
-          break;
-        case 'authorize-client-failure':
-          this._handleFailure(message.text, options?.onError);
-          break;
-        default:
-          break;
-      }
-    };
+/**
+ * Decodes a base64 string to a Uint8Array.
+ * @param str - The base64-encoded string.
+ */
+function fromBase64(str: string): Uint8Array {
+  if ('fromBase64' in Uint8Array && typeof Uint8Array.fromBase64 === 'function') {
+    return Uint8Array.fromBase64(str);
+  }
+  const binary = globalThis.atob(str);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
   }
+  return bytes;
+}
 
-  private _handleFailure(errorMessage?: string, onError?: (error?: string) => void): void {
-    this._idpWindow?.close();
-    onError?.(errorMessage);
-    this._removeEventListener();
-    delete this._idpWindow;
+/**
+ * Generates a new session key.
+ * @param keyType - The key algorithm to use.
+ */
+async function generateKey(keyType: BaseKeyType): Promise<SignIdentity> {
+  if (keyType === ED25519_KEY_LABEL) {
+    return Ed25519KeyIdentity.generate();
   }
+  return await ECDSAKeyIdentity.generate();
+}
 
-  private _removeEventListener() {
-    if (this._eventHandler) {
-      window.removeEventListener('message', this._eventHandler);
+/**
+ * Saves a session key to storage.
+ * @param storage - The storage backend.
+ * @param key - The key to persist.
+ */
+async function persistKey(
+  storage: AuthClientStorage,
+  key: SignIdentity | PartialIdentity,
+): Promise<void> {
+  await storage.set(KEY_STORAGE_KEY, serializeKey(key));
+}
+
+/**
+ * Loads a session key from storage. Falls back to migrating a legacy
+ * key from localStorage if nothing is found in the primary store.
+ * @param storage - The storage backend.
+ * @param keyType - The expected key algorithm (determines deserialization).
+ */
+async function restoreKey(
+  storage: AuthClientStorage,
+  keyType: BaseKeyType,
+): Promise<SignIdentity | PartialIdentity | null> {
+  let stored = await storage.get(KEY_STORAGE_KEY);
+  if (!stored) {
+    stored = await migrateFromLocalStorage(storage, keyType);
+  }
+  if (!stored) return null;
+
+  try {
+    // CryptoKeyPair (object) → ECDSA, JSON string → Ed25519
+    if (typeof stored === 'object') {
+      return await ECDSAKeyIdentity.fromKeyPair(stored);
     }
-    this._eventHandler = undefined;
+    return Ed25519KeyIdentity.fromJSON(stored);
+  } catch {
+    // The stored value may be corrupt or from an incompatible version.
+    // Returning null lets the caller fall through to key generation,
+    // which is safer than crashing on startup.
+    return null;
   }
+}
 
-  public async logout(options: { returnTo?: string } = {}): Promise<void> {
-    await _deleteStorage(this._storage);
+/**
+ * Converts a key into a format suitable for storage.
+ * @param key - The key to serialize.
+ */
+function serializeKey(key: SignIdentity | PartialIdentity): StoredKey {
+  if (key instanceof ECDSAKeyIdentity) return key.getKeyPair();
+  if (key instanceof Ed25519KeyIdentity) return JSON.stringify(key.toJSON());
+  throw new Error('Unsupported key type');
+}
 
-    // Reset this auth client to a non-authenticated state.
-    this._identity = new AnonymousIdentity();
-    this._chain = null;
+/**
+ * Saves the delegation chain and caches its earliest expiration
+ * in localStorage so {@link AuthClient.isAuthenticated} can check it synchronously.
+ * @param storage - The storage backend.
+ * @param chain - The delegation chain to persist.
+ */
+async function persistChain(storage: AuthClientStorage, chain: DelegationChain): Promise<void> {
+  await storage.set(KEY_STORAGE_DELEGATION, JSON.stringify(chain.toJSON()));
 
-    if (options.returnTo) {
-      try {
-        window.history.pushState({}, '', options.returnTo);
-      } catch {
-        window.location.href = options.returnTo;
-      }
+  let earliest: bigint | null = null;
+  for (const { delegation } of chain.delegations) {
+    if (earliest === null || delegation.expiration < earliest) {
+      earliest = delegation.expiration;
+    }
+  }
+  if (earliest !== null) {
+    localStorage.setItem(KEY_STORAGE_EXPIRATION, earliest.toString());
+  }
+}
+
+/**
+ * Loads the delegation chain from storage. Returns `null` and wipes
+ * storage if the chain is expired or corrupted.
+ * @param storage - The storage backend.
+ */
+async function restoreChain(storage: AuthClientStorage): Promise<DelegationChain | null> {
+  try {
+    const raw = await storage.get(KEY_STORAGE_DELEGATION);
+    if (!raw || typeof raw !== 'string') return null;
+
+    const chain = DelegationChain.fromJSON(raw);
+    if (!isDelegationValid(chain)) {
+      await deleteStorage(storage);
+      return null;
     }
+    return chain;
+  } catch (e) {
+    console.error(e);
+    await deleteStorage(storage);
+    return null;
   }
 }
 
-async function _deleteStorage(storage: AuthClientStorage) {
+/**
+ * Clears all session data from storage.
+ * @param storage - The storage backend.
+ */
+async function deleteStorage(storage: AuthClientStorage): Promise<void> {
   await storage.remove(KEY_STORAGE_KEY);
   await storage.remove(KEY_STORAGE_DELEGATION);
   await storage.remove(KEY_VECTOR);
+  localStorage.removeItem(KEY_STORAGE_EXPIRATION);
 }
 
-function mergeLoginOptions(
-  loginOptions: AuthClientLoginOptions | undefined,
-  otherLoginOptions: AuthClientLoginOptions | undefined,
-): AuthClientLoginOptions | undefined {
-  if (!loginOptions && !otherLoginOptions) {
-    return undefined;
-  }
-
-  const customValues =
-    loginOptions?.customValues || otherLoginOptions?.customValues
-      ? {
-          ...loginOptions?.customValues,
-          ...otherLoginOptions?.customValues,
-        }
-      : undefined;
-
-  return {
-    ...loginOptions,
-    ...otherLoginOptions,
-    customValues,
-  };
+/** Reads the cached delegation expiration from localStorage (nanoseconds). */
+function getExpirationFlag(): bigint | null {
+  const value = localStorage.getItem(KEY_STORAGE_EXPIRATION);
+  if (value === null) return null;
+  return BigInt(value);
 }
 
-function toStoredKey(key: SignIdentity | PartialIdentity): StoredKey {
-  if (key instanceof ECDSAKeyIdentity) {
-    return key.getKeyPair();
-  }
-  if (key instanceof Ed25519KeyIdentity) {
-    return JSON.stringify(key.toJSON());
+/**
+ * One-time migration: moves a legacy session stored in localStorage
+ * into the primary storage, then cleans up the old entries.
+ * @param storage - The target storage backend.
+ * @param keyType - The expected key algorithm (only ECDSA keys are migrated).
+ */
+async function migrateFromLocalStorage(
+  storage: AuthClientStorage,
+  keyType: BaseKeyType,
+): Promise<StoredKey | null> {
+  try {
+    const fallback = new LocalStorage();
+    const localChain = await fallback.get(KEY_STORAGE_DELEGATION);
+    const localKey = await fallback.get(KEY_STORAGE_KEY);
+
+    if (!localChain || !localKey || keyType !== ECDSA_KEY_LABEL) return null;
+
+    console.log('Discovered an identity stored in localstorage. Migrating to IndexedDB');
+    await storage.set(KEY_STORAGE_DELEGATION, localChain);
+    await storage.set(KEY_STORAGE_KEY, localKey);
+    await fallback.remove(KEY_STORAGE_DELEGATION);
+    await fallback.remove(KEY_STORAGE_KEY);
+
+    return localKey;
+  } catch (error) {
+    console.error(`error while attempting to recover localstorage: ${error}`);
+    return null;
   }
-  throw new Error('Unsupported key type');
 }
 
-async function persistKey(
-  storage: AuthClientStorage,
-  key: SignIdentity | PartialIdentity,
-): Promise<void> {
-  const serialized = toStoredKey(key);
-  await storage.set(KEY_STORAGE_KEY, serialized);
+/**
+ * Scopes attribute keys to an OpenID provider.
+ *
+ * When using one-click sign-in, attributes can be scoped to the same provider
+ * so the user grants access in a single step without an additional prompt.
+ *
+ * @param params.openIdProvider - The OpenID provider the keys should be scoped to.
+ * @param params.keys - The attribute keys to scope. Defaults to `['name', 'email', 'verified_email']`.
+ * @returns The scoped attribute keys as `openid:<provider-url>:<key>`.
+ *
+ * @example
+ * scopedKeys({ openIdProvider: 'google', keys: ['email'] });
+ * // ['openid:https://accounts.google.com:email']
+ */
+export function scopedKeys<
+  P extends keyof typeof OPENID_PROVIDER_URLS,
+  K extends string = (typeof DEFAULT_OPENID_SCOPE_KEYS)[number],
+>(params: {
+  openIdProvider: P;
+  keys?: readonly K[];
+}): `openid:${(typeof OPENID_PROVIDER_URLS)[P]}:${K}`[] {
+  const provider = OPENID_PROVIDER_URLS[params.openIdProvider];
+  const keys = params.keys ?? DEFAULT_OPENID_SCOPE_KEYS;
+  return keys.map(
+    (key) => `openid:${provider}:${key}` as `openid:${(typeof OPENID_PROVIDER_URLS)[P]}:${K}`,
+  );
 }