@icp-sdk/auth 5.0.0 → 6.0.0

package/dist/esm/client/auth-client.js

@@ -1,341 +1,336 @@
-import { AnonymousIdentity } from "@icp-sdk/core/agent";
-import { Ed25519KeyIdentity, ECDSAKeyIdentity, DelegationChain, isDelegationValid, PartialDelegationIdentity, DelegationIdentity, Delegation } from "@icp-sdk/core/identity";
-import { IdleManager } from "./idle-manager.js";
-import { IdbStorage, KEY_STORAGE_KEY, LocalStorage, KEY_STORAGE_DELEGATION, KEY_VECTOR } from "./storage.js";
-const NANOSECONDS_PER_SECOND = BigInt(1e9);
-const SECONDS_PER_HOUR = BigInt(3600);
+import { AnonymousIdentity } from '@icp-sdk/core/agent';
+import { DelegationChain, DelegationIdentity, ECDSAKeyIdentity, Ed25519KeyIdentity, isDelegationValid, PartialDelegationIdentity, } from '@icp-sdk/core/identity';
+import { Signer } from '@icp-sdk/signer';
+import { PostMessageTransport } from '@icp-sdk/signer/web';
+import { IdleManager } from './idle-manager.js';
+import { IdbStorage, KEY_STORAGE_DELEGATION, KEY_STORAGE_KEY, KEY_VECTOR, LocalStorage, } 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";
-const INTERRUPT_CHECK_INTERVAL = 500;
-const ERROR_USER_INTERRUPT = "UserInterrupt";
-class AuthClient {
-  constructor(_identity, _key, _chain, _storage, idleManager, _createOptions, _idpWindow, _eventHandler) {
-    this._identity = _identity;
-    this._key = _key;
-    this._chain = _chain;
-    this._storage = _storage;
-    this.idleManager = idleManager;
-    this._createOptions = _createOptions;
-    this._idpWindow = _idpWindow;
-    this._eventHandler = _eventHandler;
-    this._registerDefaultIdleCallback();
-  }
-  /**
-   * 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
-   *   }
-   * })
-   */
-  static async create(options = {}) {
-    const storage = options.storage ?? new IdbStorage();
-    const keyType = options.keyType ?? ECDSA_KEY_LABEL;
-    let key = null;
-    if (options.identity) {
-      key = options.identity;
-    } else {
-      let maybeIdentityStorage = await storage.get(KEY_STORAGE_KEY);
-      if (!maybeIdentityStorage) {
-        try {
-          const fallbackLocalStorage = new LocalStorage();
-          const localChain = await fallbackLocalStorage.get(KEY_STORAGE_DELEGATION);
-          const localKey = await fallbackLocalStorage.get(KEY_STORAGE_KEY);
-          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;
-            await fallbackLocalStorage.remove(KEY_STORAGE_DELEGATION);
-            await fallbackLocalStorage.remove(KEY_STORAGE_KEY);
-          }
-        } catch (error) {
-          console.error(`error while attempting to recover localstorage: ${error}`);
+const ECDSA_KEY_LABEL = 'ECDSA';
+const ED25519_KEY_LABEL = 'Ed25519';
+// localStorage key used to cache the delegation expiration so that
+// isAuthenticated() can answer synchronously without hitting IndexedDB.
+const KEY_STORAGE_EXPIRATION = 'ic-delegation_expiration';
+const OPENID_PROVIDER_URLS = {
+    google: 'https://accounts.google.com',
+    apple: 'https://appleid.apple.com',
+    microsoft: 'https://login.microsoftonline.com/{tid}/v2.0',
+};
+/**
+ * Manages authentication and identity for Internet Computer web apps.
+ *
+ * @example
+ * const authClient = new AuthClient();
+ *
+ * if (authClient.isAuthenticated()) {
+ *   const identity = await authClient.getIdentity();
+ * }
+ *
+ * await authClient.login({
+ *   onSuccess: () => console.log('Logged in!'),
+ * });
+ */
+export class AuthClient {
+    #identity = new AnonymousIdentity();
+    #chain = null;
+    #storage;
+    #signer;
+    #options;
+    #initPromise = null;
+    idleManager;
+    constructor(options = {}) {
+        this.#options = options;
+        this.#storage = options.storage ?? new IdbStorage();
+        const identityProviderUrl = new URL(options.identityProvider?.toString() || IDENTITY_PROVIDER_DEFAULT);
+        if (options.openIdProvider) {
+            identityProviderUrl.searchParams.set('openid', OPENID_PROVIDER_URLS[options.openIdProvider]);
         }
-      }
-      if (maybeIdentityStorage) {
+        const transport = new PostMessageTransport({
+            url: identityProviderUrl.toString(),
+            windowOpenerFeatures: options.windowOpenerFeatures,
+        });
+        this.#signer = new Signer({
+            transport,
+            derivationOrigin: options.derivationOrigin?.toString(),
+        });
+        this.#registerDefaultIdleCallback();
+        // Eagerly start restoring a previous session from storage.
+        // The result is awaited in getIdentity() before returning.
+        this.#init();
+    }
+    /**
+     * Returns the current identity, restoring a previous session if available.
+     */
+    async getIdentity() {
+        await this.#init();
+        return this.#identity;
+    }
+    /**
+     * Checks whether the user has an active, non-expired session.
+     */
+    isAuthenticated() {
+        // 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;
+    }
+    /**
+     * Opens the identity provider and requests a delegation.
+     *
+     * @param options - Login options.
+     * @param options.maxTimeToLive - Maximum lifetime of the delegation in nanoseconds.
+     * @param options.targets - Restrict the delegation to specific canisters.
+     * @param options.onSuccess - Called after a successful login.
+     * @param options.onError - Called when login fails. When provided the error is not re-thrown.
+     * @throws When authentication fails and no `onError` callback is provided.
+     *
+     * @example
+     * await authClient.login({
+     *   onSuccess: () => console.log('Logged in!'),
+     *   onError: (err) => console.error(err),
+     * });
+     */
+    async login(options) {
         try {
-          if (typeof maybeIdentityStorage === "object") {
-            if (keyType === ED25519_KEY_LABEL && typeof maybeIdentityStorage === "string") {
-              key = Ed25519KeyIdentity.fromJSON(maybeIdentityStorage);
-            } else {
-              key = await ECDSAKeyIdentity.fromKeyPair(maybeIdentityStorage);
+            await this.#signer.openChannel();
+            const maxTimeToLive = options?.maxTimeToLive ?? DEFAULT_MAX_TIME_TO_LIVE;
+            // Fresh key per login 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;
+            // PartialIdentity only has the public key — no signing capability.
+            if ('toDer' in key) {
+                this.#identity = PartialDelegationIdentity.fromDelegation(key, this.#chain);
             }
-          } else if (typeof maybeIdentityStorage === "string") {
-            key = Ed25519KeyIdentity.fromJSON(maybeIdentityStorage);
-          }
-        } catch {
+            else {
+                this.#identity = DelegationIdentity.fromDelegation(key, this.#chain);
+            }
+            const idleOptions = this.#options?.idleOptions;
+            if (!this.idleManager && !idleOptions?.disableIdle) {
+                this.idleManager = IdleManager.create(idleOptions);
+                this.#registerDefaultIdleCallback();
+            }
+            // Persist so the session survives page reloads.
+            await persistChain(this.#storage, this.#chain);
+            await persistKey(this.#storage, key);
+            await options?.onSuccess?.();
         }
-      }
-    }
-    let identity = new AnonymousIdentity();
-    let chain = 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."
-          );
+        catch (error) {
+            // If an onError callback is provided, delegate error handling to the caller.
+            // Otherwise, re-throw so the error can be caught with try/catch or .catch().
+            if (options?.onError) {
+                await options.onError(error instanceof Error ? error.message : String(error));
+            }
+            else {
+                throw error;
+            }
         }
-        if (options.identity) {
-          identity = options.identity;
-        } else if (chainStorage) {
-          chain = DelegationChain.fromJSON(chainStorage);
-          if (!isDelegationValid(chain)) {
-            await _deleteStorage(storage);
-            key = null;
-          } else {
-            if ("toDer" in key) {
-              identity = PartialDelegationIdentity.fromDelegation(key, chain);
-            } else {
-              identity = DelegationIdentity.fromDelegation(key, chain);
+    }
+    /**
+     * 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 = {}) {
+        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;
             }
-          }
         }
-      } catch (e) {
-        console.error(e);
-        await _deleteStorage(storage);
-        key = null;
-      }
     }
-    let idleManager;
-    if (options.idleOptions?.disableIdle) {
-      idleManager = void 0;
-    } else if (chain || options.identity) {
-      idleManager = IdleManager.create(options.idleOptions);
+    // Memoized — only runs #hydrate once, returns the same promise on repeat calls.
+    #init() {
+        if (!this.#initPromise) {
+            this.#initPromise = this.#hydrate();
+        }
+        return this.#initPromise;
     }
-    if (!key) {
-      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`
-          );
+    // 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 login().
+    async #hydrate() {
+        const key = this.#options.identity ??
+            (await restoreKey(this.#storage, this.#options.keyType ?? ECDSA_KEY_LABEL));
+        if (!key)
+            return;
+        const chain = await restoreChain(this.#storage);
+        if (!chain)
+            return;
+        this.#chain = chain;
+        if ('toDer' in key) {
+            this.#identity = PartialDelegationIdentity.fromDelegation(key, chain);
+        }
+        else {
+            this.#identity = DelegationIdentity.fromDelegation(key, chain);
+        }
+        if (!this.#options.idleOptions?.disableIdle && !this.idleManager) {
+            this.idleManager = IdleManager.create(this.#options.idleOptions);
+            this.#registerDefaultIdleCallback();
         }
-        key = await ECDSAKeyIdentity.generate();
-      }
-      await persistKey(storage, key);
     }
-    return new AuthClient(identity, key, chain, storage, idleManager, options);
-  }
-  _registerDefaultIdleCallback() {
-    const idleOptions = this._createOptions?.idleOptions;
-    if (!idleOptions?.onIdle && !idleOptions?.disableDefaultIdleCallback) {
-      this.idleManager?.registerCallback(() => {
-        this.logout();
-        location.reload();
-      });
+    #registerDefaultIdleCallback() {
+        const idleOptions = this.#options?.idleOptions;
+        if (!idleOptions?.onIdle && !idleOptions?.disableDefaultIdleCallback) {
+            this.idleManager?.registerCallback(() => {
+                this.logout();
+                location.reload();
+            });
+        }
     }
-  }
-  async _handleSuccess(message, onSuccess) {
-    const delegations = message.delegations.map((signedDelegation) => {
-      return {
-        delegation: new Delegation(
-          signedDelegation.delegation.pubkey,
-          signedDelegation.delegation.expiration,
-          signedDelegation.delegation.targets
-        ),
-        signature: signedDelegation.signature
-      };
-    });
-    const delegationChain = DelegationChain.fromDelegations(
-      delegations,
-      message.userPublicKey
-    );
-    const key = this._key;
-    if (!key) {
-      return;
+}
+/**
+ * Generates a new session key.
+ * @param keyType - The key algorithm to use.
+ */
+async function generateKey(keyType) {
+    if (keyType === ED25519_KEY_LABEL) {
+        return Ed25519KeyIdentity.generate();
     }
-    this._chain = delegationChain;
-    if ("toDer" in key) {
-      this._identity = PartialDelegationIdentity.fromDelegation(key, this._chain);
-    } else {
-      this._identity = DelegationIdentity.fromDelegation(key, this._chain);
+    return await ECDSAKeyIdentity.generate();
+}
+/**
+ * Saves a session key to storage.
+ * @param storage - The storage backend.
+ * @param key - The key to persist.
+ */
+async function persistKey(storage, key) {
+    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, keyType) {
+    let stored = await storage.get(KEY_STORAGE_KEY);
+    if (!stored) {
+        stored = await migrateFromLocalStorage(storage, keyType);
     }
-    this._idpWindow?.close();
-    const idleOptions = this._createOptions?.idleOptions;
-    if (!this.idleManager && !idleOptions?.disableIdle) {
-      this.idleManager = IdleManager.create(idleOptions);
-      this._registerDefaultIdleCallback();
+    if (!stored)
+        return null;
+    try {
+        // CryptoKeyPair (object) → ECDSA, JSON string → Ed25519
+        if (typeof stored === 'object') {
+            return await ECDSAKeyIdentity.fromKeyPair(stored);
+        }
+        return Ed25519KeyIdentity.fromJSON(stored);
     }
-    this._removeEventListener();
-    delete this._idpWindow;
-    if (this._chain) {
-      await this._storage.set(KEY_STORAGE_DELEGATION, JSON.stringify(this._chain.toJSON()));
+    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;
     }
-    await persistKey(this._storage, this._key);
-    onSuccess?.(message);
-  }
-  getIdentity() {
-    return this._identity;
-  }
-  async isAuthenticated() {
-    return !this.getIdentity().getPrincipal().isAnonymous() && this._chain !== null && isDelegationValid(this._chain);
-  }
-  /**
-   * 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);
-   *  }
-   * });
-   */
-  async login(options) {
-    const loginOptions = mergeLoginOptions(this._createOptions?.loginOptions, options);
-    const maxTimeToLive = loginOptions?.maxTimeToLive ?? DEFAULT_MAX_TIME_TO_LIVE;
-    const identityProviderUrl = new URL(
-      loginOptions?.identityProvider?.toString() || IDENTITY_PROVIDER_DEFAULT
-    );
-    identityProviderUrl.hash = IDENTITY_PROVIDER_ENDPOINT;
-    this._idpWindow?.close();
-    this._removeEventListener();
-    this._eventHandler = this._getEventHandler(identityProviderUrl, {
-      maxTimeToLive,
-      ...loginOptions
-    });
-    window.addEventListener("message", this._eventHandler);
-    this._idpWindow = window.open(
-      identityProviderUrl.toString(),
-      "idpWindow",
-      loginOptions?.windowOpenerFeatures
-    ) ?? void 0;
-    const checkInterruption = () => {
-      if (this._idpWindow) {
-        if (this._idpWindow.closed) {
-          this._handleFailure(ERROR_USER_INTERRUPT, loginOptions?.onError);
-        } else {
-          setTimeout(checkInterruption, INTERRUPT_CHECK_INTERVAL);
-        }
-      }
-    };
-    checkInterruption();
-  }
-  _getEventHandler(identityProviderUrl, options) {
-    return async (event) => {
-      if (event.origin !== identityProviderUrl.origin) {
-        return;
-      }
-      const message = event.data;
-      switch (message.kind) {
-        case "authorize-ready": {
-          const request = {
-            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;
+}
+/**
+ * Converts a key into a format suitable for storage.
+ * @param key - The key to serialize.
+ */
+function serializeKey(key) {
+    if (key instanceof ECDSAKeyIdentity)
+        return key.getKeyPair();
+    if (key instanceof Ed25519KeyIdentity)
+        return JSON.stringify(key.toJSON());
+    throw new Error('Unsupported key type');
+}
+/**
+ * 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, chain) {
+    await storage.set(KEY_STORAGE_DELEGATION, JSON.stringify(chain.toJSON()));
+    let earliest = null;
+    for (const { delegation } of chain.delegations) {
+        if (earliest === null || delegation.expiration < earliest) {
+            earliest = delegation.expiration;
         }
-        case "authorize-client-success":
-          try {
-            await this._handleSuccess(message, options?.onSuccess);
-          } catch (err) {
-            this._handleFailure(err.message, options?.onError);
-          }
-          break;
-        case "authorize-client-failure":
-          this._handleFailure(message.text, options?.onError);
-          break;
-      }
-    };
-  }
-  _handleFailure(errorMessage, onError) {
-    this._idpWindow?.close();
-    onError?.(errorMessage);
-    this._removeEventListener();
-    delete this._idpWindow;
-  }
-  _removeEventListener() {
-    if (this._eventHandler) {
-      window.removeEventListener("message", this._eventHandler);
     }
-    this._eventHandler = void 0;
-  }
-  async logout(options = {}) {
-    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;
-      }
+    if (earliest !== null) {
+        localStorage.setItem(KEY_STORAGE_EXPIRATION, earliest.toString());
     }
-  }
 }
-async function _deleteStorage(storage) {
-  await storage.remove(KEY_STORAGE_KEY);
-  await storage.remove(KEY_STORAGE_DELEGATION);
-  await storage.remove(KEY_VECTOR);
+/**
+ * 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) {
+    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;
+    }
 }
-function mergeLoginOptions(loginOptions, otherLoginOptions) {
-  if (!loginOptions && !otherLoginOptions) {
-    return void 0;
-  }
-  const customValues = loginOptions?.customValues || otherLoginOptions?.customValues ? {
-    ...loginOptions?.customValues,
-    ...otherLoginOptions?.customValues
-  } : void 0;
-  return {
-    ...loginOptions,
-    ...otherLoginOptions,
-    customValues
-  };
+/**
+ * Clears all session data from storage.
+ * @param storage - The storage backend.
+ */
+async function deleteStorage(storage) {
+    await storage.remove(KEY_STORAGE_KEY);
+    await storage.remove(KEY_STORAGE_DELEGATION);
+    await storage.remove(KEY_VECTOR);
+    localStorage.removeItem(KEY_STORAGE_EXPIRATION);
 }
-function toStoredKey(key) {
-  if (key instanceof ECDSAKeyIdentity) {
-    return key.getKeyPair();
-  }
-  if (key instanceof Ed25519KeyIdentity) {
-    return JSON.stringify(key.toJSON());
-  }
-  throw new Error("Unsupported key type");
+/** Reads the cached delegation expiration from localStorage (nanoseconds). */
+function getExpirationFlag() {
+    const value = localStorage.getItem(KEY_STORAGE_EXPIRATION);
+    if (value === null)
+        return null;
+    return BigInt(value);
 }
-async function persistKey(storage, key) {
-  const serialized = toStoredKey(key);
-  await storage.set(KEY_STORAGE_KEY, serialized);
+/**
+ * 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, keyType) {
+    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;
+    }
 }
-export {
-  AuthClient,
-  ERROR_USER_INTERRUPT
-};
-//# sourceMappingURL=auth-client.js.map
+//# sourceMappingURL=auth-client.js.map