@icp-sdk/auth 8.0.2 → 9.0.0

package/src/client/base64.ts

@@ -0,0 +1,28 @@
+/**
+ * Base64 for the JSON-RPC wire, which carries bytes as strings.
+ *
+ * Uses the built-in `Uint8Array` methods where the runtime has them, since they
+ * are faster than a byte-at-a-time loop, and falls back where it does not.
+ */
+export 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);
+}
+
+export 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;
+}

package/src/client/cookie-state-storage.ts

@@ -0,0 +1,277 @@
+import { Principal } from '@icp-sdk/core/principal';
+import { LocalStateStorage, type SessionState, type StateStorage } from './state-storage.js';
+
+/**
+ * How long the browser keeps the record, which is not how long the sign-in
+ * lasts: the record says when the session expires, and it is kept past that so
+ * every sibling can say the session ended rather than that nobody signed in.
+ * Signing in rewrites it and signing out removes it, so this is only the
+ * ceiling on a record nothing came back for.
+ *
+ * Four hundred days because that is what browsers allow — Chrome, Edge and
+ * Firefox cap a persistent cookie there and silently truncate anything longer.
+ * Safari caps a cookie written by script to seven days, which shortens this
+ * without breaking it: the record lapses to signed out, the same answer a
+ * cleared store gives.
+ */
+const RECORD_MAX_AGE_SECONDS = 400 * 24 * 60 * 60;
+
+/**
+ * Whether a hostname is loopback, which browsers treat as a secure context, so a
+ * cookie set there needs no `Secure` attribute.
+ */
+const isLoopbackHost = (hostname: string): boolean =>
+  hostname === 'localhost' ||
+  hostname.endsWith('.localhost') ||
+  hostname === '127.0.0.1' ||
+  hostname === '[::1]';
+
+export interface CookieStateStorageOptions {
+  /**
+   * Domain to scope the cookie to, e.g. `example.com` so `a.example.com` and
+   * `b.example.com` share one sign-in.
+   *
+   * Must be the current host or a domain above it: the browser rejects a cookie
+   * scoped to anything else, including a sibling subdomain, and refuses a public
+   * suffix — so an over-broad value fails rather than leaking to unrelated sites.
+   * Nothing needs to be served at the domain; it is only a scope.
+   */
+  domain: string;
+}
+
+/**
+ * The state of a sign-in, in a cookie, so every sibling of a domain shares it.
+ *
+ * A cookie is the only thing that crosses between origins, which is what lets one
+ * sign-out end them all: the record is the domain's rather than this origin's, so
+ * removing it is what tells a sibling the sign-in is over. It carries no chain
+ * and no key, so a sibling acting on it asks the identity provider to re-issue
+ * rather than treating it as proof.
+ * @see implements {@link StateStorage}
+ */
+export class CookieStateStorage implements StateStorage {
+  /**
+   * A sign-in kept here may be resumed without a ceremony.
+   *
+   * This is the store whose record reaches past one origin, so it is the store
+   * whose siblings arrive holding no credential and needing the identity
+   * provider to remember the session they can be given one from. Asking a
+   * provider to keep a sign-in is only worth the persistence where somebody is
+   * going to come back to it, and here somebody will.
+   */
+  public readonly resumable = true;
+
+  readonly #attributes: string;
+  #subscribers = new Map<string, Set<() => void>>();
+
+  // The cookie is the domain's and says who is signed in; this says whether it
+  // was this origin that acquired a credential for them. A cookie cannot carry
+  // that — every sibling reads the same bytes — so it is kept per origin and
+  // composed in on read, under the same key the cookie uses.
+  readonly #local = new LocalStateStorage();
+
+  constructor(options: CookieStateStorageOptions) {
+    // Both sides, because this decides whether to skip the check below and drop
+    // the `Domain` attribute. Taken from the configured domain alone, a
+    // `domain: 'localhost'` on a real host would do both — accept the
+    // misconfiguration and write a host-only cookie — which is the silent
+    // failure the check exists to prevent.
+    const hostname = globalThis.location?.hostname;
+    const loopback =
+      isLoopbackHost(options.domain) && (hostname === undefined || isLoopbackHost(hostname));
+
+    // A browser silently ignores `document.cookie` when the domain is not this
+    // host or one above it, and this cookie is the state itself, so the sign-in
+    // would appear to be over the moment it was written. Refusing here names the
+    // cause; the silent version does not.
+    if (
+      !loopback &&
+      hostname !== undefined &&
+      hostname !== options.domain &&
+      !hostname.endsWith(`.${options.domain}`)
+    ) {
+      throw new Error(
+        `A cookie cannot be scoped to '${options.domain}' from '${hostname}': the domain has to be this host or one above it`,
+      );
+    }
+
+    const secure = globalThis.location?.protocol === 'https:';
+    this.#attributes = [
+      // Host-only on loopback: browsers reject `Domain=localhost`, and a
+      // host-only cookie already spans ports, which local multi-origin needs.
+      ...(loopback ? [] : [`Domain=${options.domain}`]),
+      'Path=/',
+      'SameSite=Lax',
+      // Loopback is a secure context, but a `Secure` cookie over http is not
+      // reliably accepted.
+      ...(secure ? ['Secure'] : []),
+    ].join('; ');
+
+    // The check above cannot see a public suffix: 'app.co.uk' ends with '.co.uk',
+    // so `domain: 'co.uk'` passes it and the browser then refuses the cookie. No
+    // API exposes the list, so the only test that agrees with the browser is to
+    // write one and read it back — which catches cookies being switched off at
+    // the same time.
+    if (typeof document !== 'undefined') {
+      const probe = 'ic-cookie-probe';
+      let accepted = false;
+      try {
+        // No Max-Age, so even a cleanup that fails dies with the browser.
+        // biome-ignore lint/suspicious/noDocumentCookie: as elsewhere in this class.
+        document.cookie = `${probe}=1; ${this.#attributes}`;
+        accepted = readCookie(probe) !== null;
+      } finally {
+        // biome-ignore lint/suspicious/noDocumentCookie: as above.
+        document.cookie = `${probe}=; ${this.#attributes}; Max-Age=0`;
+      }
+      if (!accepted) {
+        throw new Error(
+          `A cookie scoped to '${options.domain}' cannot be written from '${hostname}': the browser refused it. The domain may be a public suffix, or cookies may be disabled.`,
+        );
+      }
+    }
+  }
+
+  public get(key: string): SessionState | null {
+    const raw = readCookie(key);
+    if (raw === null) return null;
+
+    const [principalText, expiration] = raw.split('|');
+    if (principalText === undefined || expiration === undefined) return null;
+    try {
+      const principal = Principal.fromText(principalText);
+      // Compared, not merely counted: a record can outlive the sign-in it was
+      // written for — an expired one is kept on purpose, so an application can
+      // say the session ended — and a sibling signing in as someone else then
+      // publishes a cookie this origin has no credential for. Asking only whether
+      // some local record exists would read that as held.
+      // The record's own fields are the shared truth, read as written. `held` is
+      // the only thing derived here, because it is the one fact a record every
+      // sibling reads cannot carry.
+      const local = this.#local.get(key);
+      return {
+        principal,
+        expiration: BigInt(expiration),
+        held: local !== null && local.principal.compareTo(principal) === 'eq',
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  public set(key: string, state: Omit<SessionState, 'held'>): void {
+    // The local record first, so nothing reads the cookie as held before it is.
+    this.#local.set(key, state);
+    const payload = `${state.principal.toText()}|${state.expiration.toString()}`;
+    // biome-ignore lint/suspicious/noDocumentCookie: the Cookie Store API is async, and this record is read synchronously alongside isAuthenticated().
+    document.cookie = `${encodeURIComponent(key)}=${encodeURIComponent(payload)}; ${this.#attributes}; Max-Age=${RECORD_MAX_AGE_SECONDS}`;
+    this.#fire(key);
+  }
+
+  public remove(key: string): void {
+    this.#local.remove(key);
+    // biome-ignore lint/suspicious/noDocumentCookie: same reason as set().
+    document.cookie = `${encodeURIComponent(key)}=; ${this.#attributes}; Max-Age=0`;
+    this.#fire(key);
+  }
+
+  /**
+   * Drops this origin's claim on the sign-in, leaving the cookie for the siblings.
+   *
+   * An origin whose chain turns out to be dead cannot tell a revoked session from
+   * one a sibling replaced by signing in, and in the second case that sibling
+   * wrote this cookie a moment ago. So the record stands and this origin reads it
+   * as not held, which is what sends it to acquire one of its own.
+   */
+  public discard(key: string): void {
+    this.#local.remove(key);
+    this.#fire(key);
+  }
+
+  /**
+   * Fires when the state changes, including when a sibling subdomain changes it.
+   *
+   * `document.cookie` raises no event and no `BroadcastChannel` crosses origins,
+   * so a sibling's sign-out is visible only by looking: the Cookie Store API
+   * where the browser has it, and otherwise a re-check whenever this page is
+   * shown or its window regains focus, which is when the user is about to act on
+   * the answer.
+   */
+  public subscribe(key: string, listener: () => void): () => void {
+    // One logical change can arrive from several sources at once, so each is
+    // routed through a check that fires only when what is stored actually
+    // changed since the last one.
+    //
+    // Compared on what `get` answers and not on the cookie alone. `held` is the
+    // per-origin half, and `discard` changes only that — leaving the cookie for
+    // the siblings is the whole point of it — so watching the cookie would make
+    // this origin losing its claim the one change nothing reported.
+    let last = stateOf(this.get(key));
+    const check = (): void => {
+      const now = stateOf(this.get(key));
+      if (now !== last) {
+        last = now;
+        listener();
+      }
+    };
+    const listeners = this.#subscribers.get(key) ?? new Set();
+    listeners.add(check);
+    this.#subscribers.set(key, listeners);
+
+    const onVisible = (): void => {
+      if (document.visibilityState === 'visible') check();
+    };
+    // The local half is in `localStorage`, which raises `storage` in every tab
+    // of this origin but the one that wrote. That is how a sibling tab hears
+    // that this origin dropped its claim, which no cookie event can carry.
+    const onStorage = (event: StorageEvent): void => {
+      // `key` is null when a tab cleared the whole store, which changes this too.
+      if (event.key === key || event.key === null) check();
+    };
+    globalThis.addEventListener('storage', onStorage);
+    document.addEventListener('visibilitychange', onVisible);
+    globalThis.addEventListener('pageshow', check);
+    globalThis.addEventListener('focus', check);
+
+    const cookieStore = (globalThis as { cookieStore?: EventTarget }).cookieStore;
+    cookieStore?.addEventListener('change', check);
+
+    return () => {
+      listeners.delete(check);
+      globalThis.removeEventListener('storage', onStorage);
+      document.removeEventListener('visibilitychange', onVisible);
+      globalThis.removeEventListener('pageshow', check);
+      globalThis.removeEventListener('focus', check);
+      cookieStore?.removeEventListener('change', check);
+    };
+  }
+
+  #fire(key: string): void {
+    for (const check of [...(this.#subscribers.get(key) ?? [])]) check();
+  }
+}
+
+/**
+ * What {@link CookieStateStorage.get} answers, as one comparable string.
+ *
+ * Both halves in it: the cookie every sibling reads, and the `held` this origin
+ * derives, because a change in either is a change to the answer.
+ */
+const stateOf = (state: SessionState | null): string =>
+  state === null ? '' : `${state.principal.toText()}|${state.expiration}|${state.held}`;
+
+/** Reads a cookie value by name, or `null` if absent. */
+function readCookie(name: string): string | null {
+  for (const entry of document.cookie.split(';')) {
+    const separator = entry.indexOf('=');
+    if (separator === -1) continue;
+    // Any cookie on this domain lands here, including ones this library did not
+    // write. A stray `%` makes `decodeURIComponent` throw, and one unrelated
+    // cookie must not be able to break reading the state.
+    try {
+      if (decodeURIComponent(entry.slice(0, separator).trim()) !== name) continue;
+      return decodeURIComponent(entry.slice(separator + 1).trim());
+    } catch {}
+  }
+  return null;
+}

package/src/client/credential-storage.ts

@@ -0,0 +1,56 @@
+import type { SignIdentity } from '@icp-sdk/core/agent';
+import type { DelegationChain } from '@icp-sdk/core/identity';
+
+/**
+ * An identity, and the delegation that authorises it.
+ *
+ * The two are one record because a delegation is issued to a key: held apart
+ * they can disagree, and every reader then has to decide what a chain whose key
+ * is missing means. Stored together, the half that would be dangerous — a chain
+ * with no key to sign for it — cannot be written down at all.
+ */
+export interface Credential<T extends SignIdentity = SignIdentity> {
+  identity: T;
+
+  /**
+   * Absent only while a ceremony is in flight, under the session-pending slot: there
+   * is a key, and no delegation for it yet.
+   */
+  chain?: DelegationChain;
+}
+
+/**
+ * Holds the material a client acts with, a credential per slot.
+ *
+ * Asynchronous, because using a credential means making a call and a
+ * non-extractable key needs a store that can hold one. What a page renders on is
+ * the state rather than this, so nothing here has to answer without awaiting.
+ *
+ * A store knows two things about its medium that the library cannot infer, and
+ * declares both.
+ */
+export interface CredentialStorage<T extends SignIdentity = SignIdentity> {
+  /** Whether another tab of this origin reads what this writes. */
+  readonly shared: boolean;
+
+  /** Whether what this writes survives the document being torn down. */
+  readonly durable: boolean;
+
+  /**
+   * A fresh identity of this store's own type, not persisted.
+   *
+   * Generation belongs to the store because the medium decides the key type: one
+   * that has to serialise needs a key whose private bytes are readable, and one
+   * that does not should not have them. Kept together so an application cannot
+   * pair a non-extractable key with a store that cannot hold one and find out at
+   * runtime.
+   */
+  create(): Promise<T>;
+
+  /** The credential stored under `slot`, or `null` where there is none. */
+  get(slot: string): Promise<Credential<T> | null>;
+
+  set(slot: string, credential: Credential<T>): Promise<void>;
+
+  remove(slot: string): Promise<void>;
+}

package/src/client/db.ts

@@ -1,5 +1,7 @@
 import { type IDBPDatabase, openDB } from 'idb';
-import { DB_VERSION, KEY_STORAGE_DELEGATION, KEY_STORAGE_KEY } from './storage.js';
+
+// Increment when the shape of what is stored changes.
+export const DB_VERSION = 1;
 
 type Database = IDBPDatabase<unknown>;
 type IDBValidKey = string | number | Date | BufferSource | IDBValidKey[];
@@ -10,12 +12,8 @@ const _openDbStore = async (
   dbName = AUTH_DB_NAME,
   storeName = OBJECT_STORE_NAME,
   version: number,
+  onTerminated?: () => void,
 ) => {
-  // Clear legacy stored delegations
-  if (globalThis.localStorage?.getItem(KEY_STORAGE_DELEGATION)) {
-    globalThis.localStorage.removeItem(KEY_STORAGE_DELEGATION);
-    globalThis.localStorage.removeItem(KEY_STORAGE_KEY);
-  }
   return await openDB(dbName, version, {
     upgrade: (database) => {
       if (database.objectStoreNames.contains(storeName)) {
@@ -23,6 +21,7 @@ const _openDbStore = async (
       }
       database.createObjectStore(storeName);
     },
+    terminated: onTerminated,
   });
 };
 
@@ -72,16 +71,61 @@ export class IdbKeyVal {
       storeName = OBJECT_STORE_NAME,
       version = DB_VERSION,
     } = options ?? {};
-    const db = await _openDbStore(dbName, storeName, version);
-    return new IdbKeyVal(db, storeName);
+    const keyVal = new IdbKeyVal(dbName, storeName, version);
+    // Open eagerly so an unavailable database fails at creation time.
+    await keyVal._openDb();
+    return keyVal;
   }
 
+  private _dbPromise: Promise<Database> | null = null;
+
   // Do not use - instead prefer create
   private constructor(
-    private _db: Database,
+    private _dbName: string,
     private _storeName: string,
+    private _version: number,
   ) {}
 
+  // The browser can force-close the connection at any time; the `terminated`
+  // hook drops it so the next operation opens a fresh one.
+  private _openDb(): Promise<Database> {
+    if (this._dbPromise === null) {
+      const promise = _openDbStore(this._dbName, this._storeName, this._version, () => {
+        if (this._dbPromise === promise) {
+          this._dbPromise = null;
+        }
+      }).catch((error) => {
+        if (this._dbPromise === promise) {
+          this._dbPromise = null;
+        }
+        throw error;
+      });
+      this._dbPromise = promise;
+    }
+    return this._dbPromise;
+  }
+
+  // Chrome can force-close a connection without firing `terminated`; the next
+  // transaction then throws an InvalidStateError. Drop the dead connection and
+  // retry once on a fresh one.
+  private async _withDb<T>(action: (db: Database) => Promise<T>): Promise<T> {
+    const promise = this._openDb();
+    const db = await promise;
+    try {
+      return await action(db);
+    } catch (error) {
+      // Matched by name: a DOMException does not inherit from Error.
+      const name = error !== null && typeof error === 'object' && 'name' in error && error.name;
+      if (name !== 'InvalidStateError') {
+        throw error;
+      }
+      if (this._dbPromise === promise) {
+        this._dbPromise = null;
+      }
+      return await action(await this._openDb());
+    }
+  }
+
   /**
    * Basic setter
    * @param {IDBValidKey} key string | number | Date | BufferSource | IDBValidKey[]
@@ -89,7 +133,7 @@ export class IdbKeyVal {
    * @returns void
    */
   public async set<T>(key: IDBValidKey, value: T) {
-    return await _setValue<T>(this._db, this._storeName, key, value);
+    return await this._withDb((db) => _setValue<T>(db, this._storeName, key, value));
   }
   /**
    * Basic getter
@@ -100,7 +144,7 @@ export class IdbKeyVal {
    * await get<string>('exampleKey') -> 'exampleValue'
    */
   public async get<T>(key: IDBValidKey): Promise<T | null> {
-    return (await _getValue<T>(this._db, this._storeName, key)) ?? null;
+    return await this._withDb(async (db) => (await _getValue<T>(db, this._storeName, key)) ?? null);
   }
 
   /**
@@ -109,6 +153,6 @@ export class IdbKeyVal {
    * @returns void
    */
   public async remove(key: IDBValidKey) {
-    return await _removeValue(this._db, this._storeName, key);
+    return await this._withDb((db) => _removeValue(db, this._storeName, key));
   }
 }

package/src/client/foreground-refresh.ts

@@ -0,0 +1,92 @@
+/**
+ * Calls back when the page is shown or the window regains focus.
+ *
+ * Its own module because it is the one part of the session machinery that needs a
+ * DOM. `AuthClient` runs outside a browser too, so nothing else may assume these
+ * APIs exist: where they do not, this and {@link watchActivity} return
+ * `undefined` and hook nothing.
+ *
+ * A backgrounded tab has its timers throttled, so a session's scheduled refresh
+ * may not run and its delegation lapses while nobody is looking. Coming back to
+ * the tab happens a second or two before the user's next click, which is room
+ * enough to mint in. Whether a mint is actually due is not decided here.
+ * @param onForeground - Invoked when the page becomes visible or regains focus.
+ * @returns A function that unhooks the listeners, or `undefined` where there is
+ *   no DOM to hook.
+ */
+export function watchForeground(onForeground: () => void): (() => void) | undefined {
+  // Every API this hooks, checked one at a time: a partial DOM polyfill can
+  // define `document` without the event methods, and throwing there would
+  // contradict the promise that this hooks nothing where there is no DOM.
+  if (
+    typeof document === 'undefined' ||
+    typeof document.addEventListener !== 'function' ||
+    typeof document.removeEventListener !== 'function' ||
+    typeof globalThis.addEventListener !== 'function' ||
+    typeof globalThis.removeEventListener !== 'function'
+  ) {
+    return undefined;
+  }
+
+  const onVisible = (): void => {
+    if (document.visibilityState === 'visible') onForeground();
+  };
+
+  document.addEventListener('visibilitychange', onVisible);
+  // `focus` catches two visible windows side by side, where moving between them
+  // is not a visibility change. `pageshow` catches a page restored from the
+  // back-forward cache, which resumes with timers that never ran.
+  globalThis.addEventListener('focus', onForeground);
+  globalThis.addEventListener('pageshow', onForeground);
+
+  return () => {
+    document.removeEventListener('visibilitychange', onVisible);
+    globalThis.removeEventListener('focus', onForeground);
+    globalThis.removeEventListener('pageshow', onForeground);
+  };
+}
+
+// `pointerdown` covers a mouse, a finger and a pen in one, which is the only
+// press event a phone reliably produces. The list the retired idle timer
+// listened to, put to the opposite use: it ended a session on their absence,
+// and they now keep one alive by their presence.
+const ACTIVITY_EVENTS = ['pointerdown', 'mousedown', 'mousemove', 'keydown', 'touchstart', 'wheel'];
+
+/**
+ * Calls back when somebody is using the page.
+ *
+ * A user moving a mouse is very likely about to do something that needs a
+ * delegation, so this is the same claim {@link watchForeground} makes — this
+ * page is in front of a person right now — from the other direction. Whether a
+ * mint is actually due is not decided here, and the identity's pre-mint
+ * threshold is what keeps a resting hand from costing more than one mint per
+ * refresh interval.
+ *
+ * It matters beyond saving the first request a mint: a session bounded by how
+ * long it goes unminted would otherwise end under a user who is reading rather
+ * than clicking.
+ * @param onActivity - Invoked on any sign of use.
+ * @returns A function that unhooks the listeners, or `undefined` where there is
+ *   no DOM to hook.
+ */
+export function watchActivity(onActivity: () => void): (() => void) | undefined {
+  if (
+    typeof document === 'undefined' ||
+    typeof document.addEventListener !== 'function' ||
+    typeof document.removeEventListener !== 'function'
+  ) {
+    return undefined;
+  }
+
+  // Passive: these never call `preventDefault`, and saying so keeps a listener on
+  // `mousemove` and `wheel` off the path that decides whether a scroll may start.
+  for (const event of ACTIVITY_EVENTS) {
+    document.addEventListener(event, onActivity, { passive: true });
+  }
+
+  return () => {
+    for (const event of ACTIVITY_EVENTS) {
+      document.removeEventListener(event, onActivity);
+    }
+  };
+}

package/src/client/idb-credential-storage.ts

@@ -0,0 +1,82 @@
+import { DelegationChain, ECDSAKeyIdentity } from '@icp-sdk/core/identity';
+import type { Credential, CredentialStorage } from './credential-storage.js';
+import { type DBCreateOptions, IdbKeyVal } from './db.js';
+
+/** What one slot holds in the database: a key handle, and the chain as JSON. */
+interface StoredCredential {
+  keyPair: CryptoKeyPair;
+  chain?: string;
+}
+
+/**
+ * Credentials in IndexedDB, which is what a browser offers that can hold a key
+ * whose private half is unreadable.
+ *
+ * A non-extractable `CryptoKeyPair` survives a structured clone, so what another
+ * tab reads is a handle that signs and cannot be exported — no key material is
+ * written anywhere.
+ * @see implements {@link CredentialStorage}
+ */
+export class IdbCredentialStorage implements CredentialStorage<ECDSAKeyIdentity> {
+  public readonly shared = true;
+  public readonly durable = true;
+
+  #options: DBCreateOptions;
+
+  /**
+   * @param options - Database name, store name and version.
+   */
+  constructor(options?: DBCreateOptions) {
+    this.#options = options ?? {};
+  }
+
+  // Opened on first use, and forgotten again if opening failed, so a later call
+  // retries rather than reusing a rejected promise.
+  #dbPromise: Promise<IdbKeyVal> | null = null;
+  get #db(): Promise<IdbKeyVal> {
+    if (this.#dbPromise === null) {
+      const promise = IdbKeyVal.create(this.#options).catch((error) => {
+        if (this.#dbPromise === promise) {
+          this.#dbPromise = null;
+        }
+        throw error;
+      });
+      this.#dbPromise = promise;
+    }
+    return this.#dbPromise;
+  }
+
+  public create(): Promise<ECDSAKeyIdentity> {
+    return ECDSAKeyIdentity.generate({ extractable: false });
+  }
+
+  public async get(slot: string): Promise<Credential<ECDSAKeyIdentity> | null> {
+    const db = await this.#db;
+    const stored = await db.get<StoredCredential>(slot);
+    if (!stored) return null;
+
+    try {
+      const identity = await ECDSAKeyIdentity.fromKeyPair(stored.keyPair);
+      const chain = stored.chain === undefined ? undefined : DelegationChain.fromJSON(stored.chain);
+      return { identity, chain };
+    } catch {
+      // A record written by an incompatible version, or one the browser has
+      // truncated. Reporting nothing lets the caller acquire again, which is
+      // safer than throwing on a page load.
+      return null;
+    }
+  }
+
+  public async set(slot: string, credential: Credential<ECDSAKeyIdentity>): Promise<void> {
+    const db = await this.#db;
+    await db.set<StoredCredential>(slot, {
+      keyPair: credential.identity.getKeyPair(),
+      chain: credential.chain && JSON.stringify(credential.chain.toJSON()),
+    });
+  }
+
+  public async remove(slot: string): Promise<void> {
+    const db = await this.#db;
+    await db.remove(slot);
+  }
+}