@icp-sdk/auth 8.0.2 → 9.0.0

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

@@ -1,39 +1,59 @@
-import { AnonymousIdentity } from '@icp-sdk/core/agent';
-import { DelegationChain, DelegationIdentity, ECDSAKeyIdentity, Ed25519KeyIdentity, isDelegationValid, PartialDelegationIdentity, } from '@icp-sdk/core/identity';
+import { AnonymousIdentity, } from '@icp-sdk/core/agent';
+import { isDelegationValid, } from '@icp-sdk/core/identity';
+import { Principal } from '@icp-sdk/core/principal';
 import { Signer } from '@icp-sdk/signer';
 import { PostMessageTransport, UrlTransport } 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;
+import { AccountMismatchError, chainAuthorisesKey } from './app-delegation-source.js';
+import { stealLock, stealMintLock } from './app-lock.js';
+import { fromBase64, toBase64 } from './base64.js';
+import { watchActivity, watchForeground } from './foreground-refresh.js';
+import { IdbCredentialStorage } from './idb-credential-storage.js';
+import { requestSessionDelegation } from './session-delegation.js';
+import { SessionIdentity } from './session-identity.js';
+import { SessionMinter } from './session-minter.js';
+import { slotsFor } from './slots.js';
+import { normalizeSsoDomain } from './sso.js';
+import { LocalStateStorage } from './state-storage.js';
+/**
+ * The lock one signer interaction at a time holds.
+ *
+ * Per origin rather than per namespace, because what cannot be shared is not
+ * namespaced: an origin has one signer window — `${origin}-signer-window` — and
+ * one redirect journal per route. Two clients in different namespaces are two
+ * sign-ins, and they still cannot both have the window.
+ */
+const CHANNEL_LOCK = 'ic-auth-signer-channel';
+/** The lock over one namespace's sign-in, which `signIn` and `signOut` both move. */
+const signInLockFor = (stateSlot) => `${stateSlot}:sign-in`;
 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';
-// localStorage key used to cache the delegation expiration so that
-// isAuthenticated() can answer synchronously without hitting IndexedDB.
-const KEY_STORAGE_EXPIRATION = 'ic-delegation_expiration';
-// Storage key prefix for a redirect flow's session key, held only while the
-// flow is in progress (keyed by a per-flow id) and removed once the delegation
-// is persisted. See AuthClient.#acquireSessionKey.
-const PENDING_KEY_PREFIX = 'ic-auth-pending-key:';
-// The storage backend has no key enumeration, so pending-key slots are tracked
-// explicitly here: an abandoned flow never removes its key, so a later flow
-// prunes expired orphans by slot instead of leaking them forever.
-const PENDING_KEYS_REGISTRY_KEY = 'ic-auth-pending-keys';
-// Past the URL transport's ~10-min flow window the flow can't resume, so a
-// pending key older than this is treated as abandoned.
-const PENDING_KEY_TTL_MS = 10 * 60 * 1000;
+const IDENTITY_CANISTER_DEFAULT = 'rdmx6-jaaaa-aaaaa-aaadq-cai';
 export const OPENID_PROVIDER_URLS = {
     google: 'https://accounts.google.com',
     apple: 'https://appleid.apple.com',
     microsoft: 'https://login.microsoftonline.com/{tid}/v2.0',
 };
 const DEFAULT_OPENID_SCOPE_KEYS = ['name', 'email', 'verified_email'];
+const DEFAULT_SSO_SCOPE_KEYS = ['name', 'email'];
+/**
+ * Thrown when a sign-in exists within the state store's reach but this origin
+ * holds no credential for it.
+ *
+ * A sibling subdomain reads the shared record on its first load and is in exactly
+ * this position: someone is signed in, and it has nothing to act with until it
+ * acquires its own. Catching this is where a silent re-issue belongs.
+ */
+export class SessionNotHeldError extends Error {
+    constructor(message = 'A sign-in exists for this domain, but this origin holds no credential for it') {
+        super(message);
+        this.name = 'SessionNotHeldError';
+    }
+}
 /**
  * Manages authentication and identity for Internet Computer web apps.
  *
+ * `getStatus()`, `isAuthenticated()` and `getPrincipal()` are synchronous, so a
+ * page renders on them; `getIdentity()` is what an agent signs with.
+ *
  * @example
  * const authClient = new AuthClient();
  *
@@ -41,24 +61,149 @@ const DEFAULT_OPENID_SCOPE_KEYS = ['name', 'email', 'verified_email'];
  *   ? await authClient.getIdentity()
  *   : await authClient.signIn();
  */
+/**
+ * Thrown when a later sign-in or sign-out took over from this one.
+ *
+ * Not a failure of the operation so much as a change of mind: an origin has one
+ * signer window and one sign-in, so the newer intent is the one honoured, and
+ * the earlier one reports this rather than writing what it had assembled. A
+ * caller may usually ignore it — the user is getting what they asked for second.
+ */
+export class SupersededError extends Error {
+    constructor(message = 'A later sign-in or sign-out took over from this one') {
+        super(message);
+        this.name = 'SupersededError';
+    }
+}
 export class AuthClient {
     #identity = new AnonymousIdentity();
-    #chain = null;
-    #storage;
+    #credentialStorage;
+    #slots;
+    #canisterId;
+    #unwatchForeground;
+    #unwatchState;
+    #unwatchActivity;
+    // `mousemove` fires by the dozen per second, and each call awaits a restore
+    // before it can decide there is nothing to do. One at a time is enough: the
+    // next event finds a fresher answer than the one already in flight anyway.
+    #refreshingInForeground = false;
+    #disposed = false;
+    // Set while a further restore is pending, so a burst of changes is one pass.
+    #restoreQueued = false;
+    // What `getStatus` answers with, replaced only when the record changes.
+    #status;
+    #listeners = new Set();
+    // Set while a restore is running, so its own writes are not news.
+    #restoring = false;
+    #stateStorage;
     #signer;
     // Set only in redirect mode, so the redirect-specific paths (nonce/key
     // journaling) can reach `memoize`. Undefined in the default 'window' mode.
     #urlTransport;
     #options;
     #initPromise = null;
-    idleManager;
+    // Signer interactions this client has in flight. One lock covers all of them:
+    // `signIn` and `requestAttributes` overlapped share a channel on purpose, and
+    // the channel closes when the last request settles, so they are one
+    // interaction rather than two.
+    #interactions = 0;
+    #channelLock;
     constructor(options = {}) {
         this.#options = options;
-        this.#storage = options.storage ?? new IdbStorage();
-        const identityProviderUrl = new URL(options.identityProvider?.toString() || IDENTITY_PROVIDER_DEFAULT);
+        this.#credentialStorage = options.credentialStorage ?? new IdbCredentialStorage();
+        this.#slots = slotsFor(options.namespace);
+        this.#stateStorage = options.stateStorage ?? new LocalStateStorage();
+        // A string or URL is what this option used to be, and a caller still passing
+        // one would otherwise be silently ignored — both halves falling back to
+        // mainnet, which is the kind of misconfiguration that only shows up as calls
+        // going to the wrong canister.
+        if (typeof options.identityProvider === 'string' || options.identityProvider instanceof URL) {
+            throw new TypeError('identityProvider is now an object: pass { authorizeUrl, canisterId } — the URL a ceremony is rendered at, and the canister that mints');
+        }
+        const provider = options.identityProvider ?? {
+            authorizeUrl: IDENTITY_PROVIDER_DEFAULT,
+            canisterId: IDENTITY_CANISTER_DEFAULT,
+        };
+        // Both or neither, for the same reason a bare URL is refused above: half of
+        // a deployment renders the ceremony at one provider and mints against
+        // another. The type says so, and this says it to a caller without one.
+        if (provider.authorizeUrl === undefined || provider.canisterId === undefined) {
+            throw new TypeError('identityProvider names authorizeUrl and canisterId together, or neither: nothing about the canister is derived from the URL');
+        }
+        this.#canisterId = Principal.from(provider.canisterId);
+        const identityProviderUrl = new URL(provider.authorizeUrl.toString());
+        if (!options.disableBrowserActivity) {
+            // The identity decides whether a mint is due; these only say the moment is
+            // a good one. Nothing is hooked where there is no DOM.
+            //
+            // The page arriving and the user using it are the same claim — somebody is
+            // here — so both trigger the same refresh and one option governs both.
+            const refresh = () => {
+                void this.#refreshInForeground();
+            };
+            this.#unwatchForeground = watchForeground(refresh);
+            this.#unwatchActivity = watchActivity(refresh);
+        }
+        // The third outside signal, and the one that is not about a moment being a
+        // good one: the record can be replaced under this client — by a peer client
+        // on this page sharing its stores, or by another tab — and nothing about a
+        // restore already done reflects that. Hooked whatever
+        // `disableBrowserActivity` says, because it is not a refresh: a client
+        // answering for a sign-in the record no longer names is wrong rather than
+        // stale.
+        this.#status = this.#readStatus();
+        this.#unwatchState = this.#stateStorage.subscribe(this.#slots.state, () => {
+            // The held answer first, then the listeners, then whatever this client has
+            // to do about it — so a listener asking who is signed in sees what it was
+            // told about, whether or not the guard below lets a restore run.
+            this.#status = this.#readStatus();
+            for (const listener of [...this.#listeners])
+                listener();
+            // Only a change this client did not cause. A ceremony writes this record
+            // itself and installs the identity that goes with it, and a restore writes
+            // it too when what it found turns out not to be usable — reacting to
+            // either would re-hydrate mid-ceremony, when the app slot still holds the
+            // previous account's credential. The same reason the foreground refresh
+            // stands down for a ceremony.
+            //
+            // What this gives up is a peer's change arriving during our own restore,
+            // which the next change reports.
+            if (this.#interactions > 0 || this.#restoring || this.#disposed)
+                return;
+            this.#restoreAgain();
+        });
+        if (options.openIdProvider !== undefined && options.ssoDomain !== undefined) {
+            throw new Error('openIdProvider and ssoDomain are mutually exclusive');
+        }
         if (options.openIdProvider) {
             identityProviderUrl.searchParams.set('openid', OPENID_PROVIDER_URLS[options.openIdProvider]);
         }
+        if (options.ssoDomain !== undefined) {
+            identityProviderUrl.searchParams.set('sso', normalizeSsoDomain(options.ssoDomain));
+            // The SSO ceremony starts before a delegation is requested, so the
+            // channel carries the derivation origin too late to resolve the client.
+            if (options.derivationOrigin !== undefined) {
+                identityProviderUrl.searchParams.set('derivationOrigin', options.derivationOrigin.toString());
+            }
+        }
+        // `prompt` and `hint` are Internet Identity extensions, so they ride on the
+        // authorize URL rather than in the ICRC request. Baking them in here, as
+        // `openid` is, means a client is configured for one authorize intent —
+        // construct a separate client for a silent re-issue and for an interactive
+        // sign-in. Both share this client's storage, so whichever resolves populates
+        // the same session.
+        if (options.prompt) {
+            identityProviderUrl.searchParams.set('prompt', options.prompt);
+        }
+        if (options.hint) {
+            identityProviderUrl.searchParams.set('hint', options.hint.toText());
+        }
+        // The store already carries the intent, so the option only has to override
+        // it. Written only when true: absent is what the provider reads as "keep
+        // nothing", and an explicit `false` would say the same thing louder.
+        if (options.resumable ?? this.#stateStorage.resumable ?? false) {
+            identityProviderUrl.searchParams.set('resumable', 'true');
+        }
         const transport = options.transport === 'redirect'
             ? new UrlTransport({
                 url: identityProviderUrl.toString(),
@@ -83,7 +228,6 @@ export class AuthClient {
             // the producer without persisting anything.
             derivationOrigin: this.memoize(() => options.derivationOrigin?.toString()),
         });
-        this.#registerDefaultIdleCallback();
         // Eagerly start restoring a previous session from storage.
         // The result is awaited in getIdentity() before returning.
         this.#init();
@@ -93,18 +237,156 @@ export class AuthClient {
      */
     async getIdentity() {
         await this.#init();
+        // A record exists and this client holds nothing to act with. Handing back an
+        // anonymous identity here is the dangerous answer: calls would go out
+        // unauthenticated while `isAuthenticated()` and the record both say someone
+        // is signed in. Failing by name is what lets a caller acquire one.
+        //
+        // Any record, not only one this origin does not hold. A sibling subdomain
+        // arriving without a credential is the case this was written for, and it is
+        // not the only way to get here: a store that cannot report a change — or
+        // reports it wrongly — leaves this client on an answer the record has moved
+        // past, and `held` is `true` for every record a same-origin store keeps, so
+        // asking about it would have let exactly that through.
+        //
+        // A disposed client is exempt: it holds nothing because it was told to stop,
+        // which is not the same as being unable to act on a sign-in that exists. So
+        // is a record past its expiry: it names a session that has ended, and there
+        // is nothing to acquire for one of those.
+        const live = this.#readStatus().state;
+        if ((live === 'signed-in' || live === 'signed-in-elsewhere') &&
+            !this.#disposed &&
+            this.#identity instanceof AnonymousIdentity) {
+            throw new SessionNotHeldError();
+        }
         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;
+        return this.getStatus().state === 'signed-in';
+    }
+    /**
+     * Who this origin can act as, or `undefined` where it cannot act.
+     *
+     * The same question {@link isAuthenticated} answers, returning who rather than
+     * whether — so the two never disagree. Synchronous, and read from the state
+     * rather than from whatever material happens to be held, so a page renders on
+     * it without opening a store and without waiting for a mint. That is the
+     * difference from `(await getIdentity()).getPrincipal()`, which is asynchronous
+     * and, on a load with no delegation worth adopting, waits for one to be minted.
+     *
+     * A principal here means calls made as it will be accepted, so an expired
+     * record answers `undefined` even though it still names an account, and so does
+     * a record naming an account this origin holds nothing for. Returning one
+     * anyway would have an application acting on a session that has ended: the
+     * check most reach for is `if (getPrincipal())`, and it has to mean what it
+     * looks like it means.
+     *
+     * {@link getStatus} is where those cases are readable, and it carries the
+     * account principal in each of them — so nothing is lost by this being narrow,
+     * and an application wanting to say whose session ended asks there.
+     */
+    getPrincipal() {
+        const status = this.getStatus();
+        return status.state === 'signed-in' ? status.principal : undefined;
+    }
+    /**
+     * Who is signed in for this origin right now.
+     *
+     * Synchronous, so a page can render on it without opening a store.
+     */
+    getStatus() {
+        // The same object until something actually changes. A page renders on this,
+        // and a framework asking "did it change?" compares the object rather than
+        // its contents — a fresh one per call reads as a change on every render, and
+        // `useSyncExternalStore` refuses a snapshot that never settles. Returning
+        // the held one also means no `Principal.fromText` per call.
+        //
+        // Expiry is the one transition with no write behind it, so it is the one
+        // thing checked here: a number comparison, and the answer is rebuilt once
+        // when it flips.
+        if (this.#status.state !== 'signed-out' && Date.now() >= this.#status.expiresAtMs) {
+            if (this.#status.state !== 'expired') {
+                const { principal, expiresAtMs } = this.#status;
+                this.#status = { state: 'expired', principal, expiresAtMs };
+            }
+        }
+        return this.#status;
+    }
+    /** Reads the record and builds the answer `getStatus` hands out. */
+    #readStatus() {
+        const record = this.#stateStorage.get(this.#slots.state);
+        if (record === null)
+            return { state: 'signed-out' };
+        const { principal } = record;
+        const expiresAtMs = Number(record.expiration / 1000000n);
+        if (Date.now() >= expiresAtMs) {
+            return { state: 'expired', principal, expiresAtMs };
+        }
+        return record.held
+            ? { state: 'signed-in', principal, expiresAtMs }
+            : { state: 'signed-in-elsewhere', principal, expiresAtMs };
+    }
+    /**
+     * Watches who is signed in here, and returns a function that stops watching.
+     *
+     * `getStatus()` and the predicates beside it are snapshots, so an application
+     * rendering on them needs to be told when to read again. The record changes
+     * for reasons that are nothing to do with this client — another tab signing
+     * out, a sibling subdomain publishing a sign-in, a peer client on this page
+     * re-issuing silently — and this is how those arrive.
+     *
+     * Fired once the record is readable, so a listener asking who is signed in
+     * sees what it was told about. It says that something changed and not what: a
+     * listener reads the answer it wants, which for most is `getStatus()`.
+     *
+     * What it does not cover is the identity being replaced under an application
+     * that holds one — an app delegation rotating is deliberately invisible, and
+     * nothing about who is signed in has changed when it does.
+     * @param listener - Called after the record changes.
+     * @returns A function that unregisters it.
+     */
+    subscribe(listener) {
+        // Fired by this client rather than by the store, because the answer has to
+        // be up to date before a listener asks for it: the store announcing first
+        // would let a listener read a status one change behind.
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    /**
+     * Releases what this client hooked: the browser listeners, the state
+     * subscription, and the refresh the identity has scheduled. Call it when
+     * discarding a client, so nothing it registered outlives it.
+     */
+    dispose() {
+        // Recorded, because the constructor starts the restore without awaiting it:
+        // a client disposed while one is in flight would otherwise have an identity
+        // installed afterwards, scheduling refreshes nobody can stop.
+        this.#disposed = true;
+        if (this.#identity instanceof SessionIdentity)
+            this.#identity.dispose();
+        // Its own interaction and no one else's: the locks it holds are released
+        // rather than taken, its own channel is closed, and nothing shared is
+        // written. Disposing means stop using this client, not sign out — another
+        // instance may be acting on the same slots.
+        //
+        // Fired rather than awaited, because this stays synchronous: an application
+        // discarding a client has nothing to do with the answer.
+        if (this.#interactions > 0) {
+            void this.#signer.closeChannel().catch(() => undefined);
+        }
+        this.#channelLock?.release();
+        this.#channelLock = undefined;
+        this.#unwatchForeground?.();
+        this.#unwatchForeground = undefined;
+        this.#unwatchActivity?.();
+        this.#unwatchActivity = undefined;
+        this.#unwatchState?.();
+        this.#unwatchState = undefined;
     }
     /**
      * Opens the identity provider, requests a delegation, and returns the authenticated identity.
@@ -122,9 +404,115 @@ export class AuthClient {
      *   console.error('Sign-in failed:', error);
      * }
      */
+    /**
+     * Records that an interaction is under way, without asking the browser for
+     * anything.
+     *
+     * Separate from taking the lock because of when each may happen: the count has
+     * to be up before the first await, and a lock may only be asked for once the
+     * signer window is open.
+     */
+    /**
+     * Installs the identity this client acts with, releasing the one it replaces.
+     *
+     * A {@link SessionIdentity} holds a scheduled refresh, so dropping the
+     * reference without disposing leaves a timer that can still mint — into a slot
+     * this client may no longer be the writer of, for a session it may no longer
+     * hold. Every assignment goes through here so that no path can forget, which
+     * matters most for the paths that give up rather than the ones that succeed:
+     * those are the paths written to stop acting.
+     */
+    #installIdentity(next) {
+        const previous = this.#identity;
+        if (previous !== next && previous instanceof SessionIdentity)
+            previous.dispose();
+        this.#identity = next;
+    }
+    #beginInteraction() {
+        this.#interactions += 1;
+    }
+    /**
+     * Opens the signer channel and takes the lock that makes this the only
+     * interaction on it.
+     *
+     * One method because the order is the whole point. A popup may only be opened
+     * from the task the click started, so nothing may be asked of the browser
+     * before `openChannel` — two lock requests in front of it were enough for
+     * Chromium to refuse the window — and the lock has to be taken as soon as it
+     * is open. Two callers doing that by hand is one place too many for the order
+     * to come out backwards.
+     */
+    async #openSignerChannel() {
+        await this.#signer.openChannel();
+        if (this.#channelLock === undefined) {
+            const lock = stealLock(CHANNEL_LOCK);
+            // Whoever took the channel has already renavigated the window this one was
+            // talking to, so its requests will never be answered. Closing it is what
+            // turns waiting forever into failing, and it releases the window for the
+            // interaction that took over.
+            lock.stolen.addEventListener('abort', () => {
+                void this.#signer.closeChannel().catch(() => undefined);
+            }, { once: true });
+            this.#channelLock = lock;
+        }
+    }
+    #endInteraction() {
+        this.#interactions -= 1;
+        if (this.#interactions === 0) {
+            this.#channelLock?.release();
+            this.#channelLock = undefined;
+        }
+    }
+    /**
+     * Refuses to go on where this operation is no longer the current one.
+     *
+     * Asked after the calls have returned and before anything shared is written,
+     * which is where `acquireCredential` asks it for a mint and for the same
+     * reason: a call already sent cannot be recalled, so the only thing left to
+     * decide is whether to keep its result.
+     */
+    #assertCurrent(signInLock) {
+        if (this.#disposed) {
+            throw new SupersededError('This client was disposed while signing in');
+        }
+        if (this.#channelLock?.stolen.aborted === true) {
+            throw new SupersededError('Another signer interaction took the channel');
+        }
+        if (signInLock.stolen.aborted) {
+            throw new SupersededError();
+        }
+    }
     async signIn(options) {
-        const maxTimeToLive = options?.maxTimeToLive ?? DEFAULT_MAX_TIME_TO_LIVE;
-        const keyType = this.#options.keyType ?? ECDSA_KEY_LABEL;
+        // Counted here and locked inside, once the window is open: a ceremony is
+        // both things — the signer channel an origin has one of, and this
+        // namespace's sign-in, which `signOut` moves too — but neither lock may be
+        // asked for before the popup exists.
+        //
+        // The count is also what stands the foreground refresh down: a ceremony
+        // backgrounds this tab and foregrounds it again on its way back, so without
+        // it the return fires a refresh against the identity this call is in the
+        // middle of replacing — a mint spent on a session being discarded, and
+        // written to the store as though it were current. It asks the browser for
+        // nothing, so it is safe to do first.
+        this.#beginInteraction();
+        try {
+            return await this.#runSignIn(options);
+        }
+        finally {
+            this.#endInteraction();
+        }
+    }
+    async #runSignIn(options) {
+        // Journaled first, so a redirect flow finds it on the load that comes back:
+        // the ceremony returns to the URL it was started from, which is rarely where
+        // the user was. Journaled only when the caller gave one, so the journal of a
+        // flow that omits it is unchanged.
+        //
+        // Validated inside the producer, so what is written down is an already-safe
+        // href or nothing — never the raw value, which the journal would otherwise
+        // carry across the round trip for the return leg to trust.
+        const raw = options?.returnTo;
+        const returnTo = raw === undefined ? undefined : this.memoize(() => sameOriginTarget(raw)?.href ?? null);
         // Start session-key acquisition BEFORE opening the channel, awaiting it only
         // after. In the redirect flow the acquisition's first `transport.memoize`
         // runs synchronously when invoked, so its in-flight bump lands in the same
@@ -134,105 +522,175 @@ export class AuthClient {
         // faster concurrent request from flushing before this flow's delegation
         // request is buffered.
         const sessionKeyPromise = this.#urlTransport
-            ? this.#ensureSessionKeyForRedirectFlow(this.#urlTransport, keyType)
-            : this.#ensureSessionKeyForWindowFlow(keyType).then((key) => ({ key }));
+            ? this.#ensureSessionKeyForRedirectFlow(this.#urlTransport)
+            : this.#ensureSessionKeyForWindowFlow().then((key) => ({ key }));
         // The acquisition is started eagerly, before the awaits below. If one of
         // those throws first, `sessionKeyPromise` is never awaited, so attach a
         // no-op rejection handler now to keep a later acquisition failure from
         // surfacing as an unhandled rejection. The `await` below still observes a
         // rejection and propagates it when reached.
         void sessionKeyPromise.catch(() => undefined);
-        await this.#signer.openChannel();
-        const { key, pendingKeySlot } = await sessionKeyPromise;
-        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 {
-            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);
-        // The flow is complete: the delegation is bound to this key and stored, so
-        // the per-flow pending copy is no longer needed. Best-effort — the user is
-        // already signed in, so a cleanup failure must not fail signIn(); a later
-        // flow sweeps whatever is left behind.
-        if (pendingKeySlot !== undefined) {
-            try {
-                await this.#storage.remove(pendingKeySlot);
-                await unregisterPendingKey(this.#storage, pendingKeySlot);
+        // Must stay the first await: it opens the signer window, which the browser
+        // allows only in the tick the click started.
+        await this.#openSignerChannel();
+        // The other lock a ceremony needs, taken once the window is open for the
+        // same reason. Stolen rather than queued for, so the newer intent wins and
+        // the loser learns of it before writing anything.
+        //
+        // A local, not a field: two overlapping calls would each write the field,
+        // and then both the supersede check and the release would read whichever
+        // wrote last — leaving the running call unlocked and unable to notice a
+        // steal, while the stolen lock's own signal went to an object nothing held.
+        const signInLock = stealLock(signInLockFor(this.#slots.state));
+        // Every shared write goes through this. One check before the first write is
+        // not enough: the lock reaches across tabs, so a sign-out can land between
+        // any two of the writes below, clear the slots and the record, and this flow
+        // would put them all back — signing the user out and straight back in.
+        const guarded = async (write) => {
+            this.#assertCurrent(signInLock);
+            await write();
+        };
+        // Released here rather than by the caller: the lock belongs to this call,
+        // and a call that hands it to a field cannot tell its own from another's.
+        try {
+            // Wait for the constructor's session restore, so this flow's storage
+            // writes cannot interleave with hydration's reads.
+            await this.#init();
+            const { key, pending } = await sessionKeyPromise;
+            if (!('sign' in key)) {
+                // Unreachable for a typed caller, since `identity` is a SignIdentity.
+                // Minting is a canister call signed by the session key, so a key that
+                // cannot sign cannot hold a session, and failing here beats handing back
+                // an identity whose first request fails for a reason nothing explains.
+                throw new Error('A session needs a key that can sign');
             }
-            catch {
-                // ignore
+            const sessionChain = await requestSessionDelegation(this.#signer, {
+                sessionPublicKey: key.getPublicKey().toDer(),
+                // Both bounds are sent only where the caller asked, so the provider's
+                // own defaults apply otherwise rather than numbers this library
+                // invented. How long a sign-in lasts is the provider's policy, narrowed
+                // by what the user chooses at consent and by an organization's cap.
+                maxTimeToLive: options?.maxTimeToLive,
+                maxTimeToIdle: options?.maxTimeToIdle,
+                derivationOrigin: this.#options.derivationOrigin?.toString(),
+            });
+            // The chain comes from the signer over a transport shared with others, so
+            // the key it delegates to is checked here rather than assumed. A chain for
+            // another key mints nothing, and failing now names the cause instead of
+            // leaving it to the first request.
+            if (!chainAuthorisesKey(sessionChain, key.getPublicKey().toDer())) {
+                throw new Error('The session chain does not delegate to the key it was requested for');
+            }
+            // Mint inside the ceremony the user is already waiting through, so the first
+            // request after signing in does not wait. This is also where the account key
+            // comes from: the session chain is rooted at the session's own key, and only
+            // a mint reports the key an application's canisters will see.
+            //
+            // Into the ceremony's own slot, not the one every tab of this origin acts
+            // with. Clearing that slot up front, or writing to it here, would change what
+            // those tabs hold before this sign-in has succeeded — and a ceremony that
+            // then failed would have cost each of them a mint for nothing.
+            const minter = await this.#minterFor(key, sessionChain);
+            const appKey = await this.#credentialStorage.create();
+            const appChain = await minter.mint(appKey.getPublicKey().toDer());
+            // Everything above was a call, and none of it is shared; everything below is
+            // a write four other things read.
+            await guarded(() => this.#credentialStorage.set(this.#slots.appPending, { identity: appKey, chain: appChain }));
+            // The session and the state first, because the state is what makes this
+            // account the one this origin answers for; promoting ahead of it would
+            // publish a credential for a sign-in nothing has recorded yet.
+            await guarded(() => this.#persistSession(key, sessionChain, appChain.publicKey));
+            await guarded(() => this.#promoteAppCredential(appKey, appChain));
+            await guarded(async () => {
+                this.#installIdentity(await this.#openSession(key, sessionChain, minter));
+            });
+            // Best-effort — the user is already signed in, so a cleanup failure must not
+            // fail signIn(), and the next ceremony overwrites what is left behind.
+            if (pending) {
+                try {
+                    await this.#credentialStorage.remove(this.#slots.sessionPending);
+                }
+                catch {
+                    // ignore
+                }
             }
+            // Last, once the sign-in is stored, because this leaves the page: navigating
+            // earlier would abandon the flow partway. Replaced rather than pushed, so the
+            // sign-in page and the redirect chain are not what a back button returns to.
+            // `await` above resolved the journaled value to a validated href or null.
+            const target = await returnTo;
+            if (typeof target === 'string')
+                location.replace(target);
+            return this.#identity;
+        }
+        finally {
+            signInLock.release();
         }
-        return this.#identity;
     }
     // Window flow: sign-in completes in a single load, so a fresh session key per
-    // sign-in is enough (or the caller-provided identity), with nothing to
-    // persist for a later load.
-    async #ensureSessionKeyForWindowFlow(keyType) {
-        return this.#options.identity ?? (await generateKey(keyType));
+    // sign-in is enough, with nothing to persist for a later load.
+    #ensureSessionKeyForWindowFlow() {
+        return this.#credentialStorage.create();
     }
     // Redirect flow: `signIn` runs twice — once on the load that navigates to the
     // identity provider, and again on the return load that replays the delegation
-    // minted for the FIRST load's key. Both runs must therefore use the same key.
-    // A per-flow key id is journaled via the transport (stable across the
-    // redirect) and the key is kept in storage under that id, so the return load
-    // restores the same key rather than generating a fresh one that would not
-    // match the replayed delegation. A caller-provided identity is already stable
-    // across the redirect, so it is used as-is with nothing persisted.
-    async #ensureSessionKeyForRedirectFlow(transport, keyType) {
-        if (this.#options.identity !== undefined) {
-            return { key: this.#options.identity };
-        }
-        const keyId = await transport.memoize(() => globalThis.crypto.randomUUID());
-        const pendingKeySlot = `${PENDING_KEY_PREFIX}${keyId}`;
-        // Acquire the per-flow key inside a `memoize` producer so the transport
-        // holds its batch flush across the (async) key restore/generate + storage
-        // write. The transport coalesces concurrently issued requests into one
-        // redirect by flushing on a macrotask once no memoize producer is in
-        // flight; without this hold, a faster concurrent request (e.g. the nonce
-        // path of `requestAttributes`) buffers first and trips that flush before
-        // this flow's delegation request — issued only once the key is ready — is
-        // buffered, splitting what should be one redirect into two.
+    // minted for the FIRST load's key. Both runs must therefore use the same key,
+    // so the first load writes it to the pending slot and the return load reads it
+    // back.
+    async #ensureSessionKeyForRedirectFlow(transport) {
+        // A redirect leaves the document, so the key this flow starts with has to be
+        // readable again on the load that comes back, which takes a medium that
+        // survives the teardown. Refusing before navigating beats sending the user to
+        // the identity provider and failing on their return.
+        //
+        // A store other tabs can read is not enough. It answers only while one of
+        // them is open, so the same flow in the only tab of an origin loses the key
+        // the moment it navigates — a rule that holds sometimes is worse than one
+        // that holds never, because it fails on the user rather than on the
+        // developer.
+        if (!this.#credentialStorage.durable) {
+            throw new Error('A redirect sign-in needs a credential store that survives the navigation, and this one does not. Use a durable store or the window transport.');
+        }
+        // Acquire the key inside a `memoize` producer so the transport holds its
+        // batch flush across the (async) key read/create + storage write. The
+        // transport coalesces concurrently issued requests into one redirect by
+        // flushing on a macrotask once no memoize producer is in flight; without
+        // this hold, a faster concurrent request (e.g. the nonce path of
+        // `requestAttributes`) buffers first and trips that flush before this flow's
+        // delegation request — issued only once the key is ready — is buffered,
+        // splitting what should be one redirect into two.
         //
-        // The key is captured in a closure, not read back after the producer: on
-        // the FIRST load the producer sets `acquired`, so the delegation request
-        // that follows is issued with no intervening storage read — a read there
-        // would re-open the very flush gap this closes. The producer is skipped on
-        // the replay load (its result is journaled), where the key is instead
-        // restored from storage. Only the id is journaled; the key lives in storage.
+        // The key is captured in a closure, not read back after the producer: on the
+        // FIRST load the producer sets `acquired`, so the delegation request that
+        // follows is issued with no intervening storage read — a read there would
+        // re-open the very flush gap this closes. The producer is skipped on the
+        // replay load (its result is journaled), where the key is instead read from
+        // the pending slot.
+        //
+        // What is journaled is the key's *public* half: not a secret, it survives the
+        // redirect as text, and on the return load it says whether the pending slot
+        // still holds the key this ceremony started with.
         let acquired = null;
-        await transport.memoize(async () => {
-            acquired = await restoreKeyAt(this.#storage, pendingKeySlot);
-            if (acquired === null) {
-                acquired = await generateKey(keyType);
-                // Register before writing the key: if the write then fails, a stray
-                // registry entry is harmless (swept on expiry), whereas a key with no
-                // registry entry would leak un-sweepably.
-                await sweepAndRegisterPendingKey(this.#storage, pendingKeySlot, Date.now());
-                await this.#storage.set(pendingKeySlot, serializeKey(acquired));
+        const startedWith = await transport.memoize(async () => {
+            const stored = await this.#credentialStorage.get(this.#slots.sessionPending);
+            if (stored !== null) {
+                acquired = stored.identity;
+            }
+            else {
+                acquired = await this.#credentialStorage.create();
+                await this.#credentialStorage.set(this.#slots.sessionPending, { identity: acquired });
             }
-            return keyId;
+            return publicKeyOf(acquired);
         });
-        const key = acquired ?? (await restoreKeyAt(this.#storage, pendingKeySlot));
-        if (key === null) {
-            throw new Error('Session key missing after acquisition');
+        const key = acquired ?? (await this.#credentialStorage.get(this.#slots.sessionPending))?.identity ?? null;
+        // Empty or holding another flow's key: either way the key this ceremony
+        // journaled is no longer in the slot, so the delegation being replayed was
+        // minted for a key this flow does not have. The caller retries, and by then
+        // the sign-in that superseded it has usually been promoted.
+        if (key === null || publicKeyOf(key) !== startedWith) {
+            throw new Error('This sign-in was superseded by another one in this browser');
         }
-        return { key, pendingKeySlot };
+        return { key, pending: true };
     }
     /**
      * Requests signed identity attributes from the identity provider.
@@ -258,6 +716,18 @@ export class AuthClient {
      * @throws When the identity provider returns an error or an invalid response.
      */
     async requestAttributes(params) {
+        // The channel lock and not the sign-in lock: this opens the signer channel,
+        // which an origin has one of, and writes nothing anyone else reads. Held
+        // together with a `signIn` overlapping it, which shares the same channel.
+        this.#beginInteraction();
+        try {
+            return await this.#runRequestAttributes(params);
+        }
+        finally {
+            this.#endInteraction();
+        }
+    }
+    async #runRequestAttributes(params) {
         // In redirect mode the nonce is journaled (base64, since the journal is
         // JSON) so the replay on the return load signs against the same bytes.
         const nonceBytes = this.#urlTransport
@@ -299,31 +769,53 @@ export class AuthClient {
      * @param options.returnTo - URL to navigate to after sign-out.
      */
     async signOut(options = {}) {
-        await deleteStorage(this.#storage);
-        this.#identity = new AnonymousIdentity();
-        this.#chain = null;
+        // Wait for the constructor's session restore: hydration racing the
+        // deletion below could re-populate the identity from already-read state.
+        await this.#init();
+        // The same lock a ceremony takes, and taken the same way: this is the other
+        // operation that moves this namespace's sign-in. No channel lock — a revoke
+        // is an agent call to the canister, so nothing here touches the signer.
+        const signOutLock = stealLock(signInLockFor(this.#slots.state));
+        // Read before anything is cleared: the revoke call is made as the session,
+        // so it needs what the wipe is about to remove.
+        const session = await this.#credentialStorage.get(this.#slots.session).catch(() => null);
+        // Taken away rather than queued for. Waiting would make a sign-out the user
+        // asked for wait on a canister call in another tab; the tab that loses the
+        // lock finishes the call it cannot recall, sees that it lost it, and throws
+        // the result away rather than writing a credential into the slot cleared
+        // below. Nothing holds the lock where no other tab can read the store.
+        await stealMintLock(this.#credentialStorage.shared ? this.#slots.app : null);
+        // Ending the session at the canister and clearing what is held here are
+        // independent, so they run together: a slow or failing revoke must not hold
+        // up a wipe the user asked for, and a user who pressed sign out must not
+        // stay signed in on the device in front of them because a call failed.
+        //
+        // A failed revoke is carried rather than thrown, so the wipe below still
+        // finishes, and rather than dropped, so it can be raised once it has.
+        const revoked = session?.chain === undefined || !('sign' in session.identity)
+            ? Promise.resolve(undefined)
+            : this.#revoke(session.identity, session.chain).then(() => undefined, (error) => error);
+        const cleared = this.#endSession();
+        this.#installIdentity(new AnonymousIdentity());
+        const [revokeFailure] = await Promise.all([revoked, cleared]);
+        signOutLock.release();
+        // Raised after the wipe and before the navigation. The device is signed out
+        // whatever happened at the canister, and an application that told a user it
+        // had signed them out of their apps can find out that it had not — which it
+        // could not if this were swallowed, and could not act on if it arrived after
+        // the page had left.
+        if (revokeFailure !== undefined)
+            throw revokeFailure;
         if (options.returnTo !== undefined) {
-            // Navigate exactly as before (pushState, else location.href), but only to
-            // a validated same-origin http(s) target, and feed that validated
-            // `target.href` to both sinks rather than the raw `returnTo`. An invalid
-            // or cross-origin `returnTo` is ignored, so the fallback can no longer be
-            // turned into an open redirect or a `javascript:` execution.
-            let target;
-            try {
-                target = new URL(options.returnTo, window.location.href);
-            }
-            catch {
-                target = undefined;
-            }
-            if (target !== undefined &&
-                (target.protocol === 'https:' || target.protocol === 'http:') &&
-                target.origin === window.location.origin) {
-                try {
-                    window.history.pushState({}, '', target.href);
-                }
-                catch {
-                    window.location.href = target.href;
-                }
+            // A navigation rather than a `pushState`: nothing obliges an application to
+            // re-render when the history entry changes — `pushState` fires no
+            // `popstate` — so the signed-in view would sit under a signed-out URL. The
+            // validated `href` is what reaches the sink rather than the raw value, so
+            // neither an open redirect nor a `javascript:` execution can be built
+            // from it.
+            const target = sameOriginTarget(options.returnTo);
+            if (target !== undefined) {
+                window.location.assign(target.href);
             }
         }
     }
@@ -335,7 +827,7 @@ export class AuthClient {
     // normal close behaviour.
     async #resolveNonce(nonce) {
         const value = nonce();
-        await this.#signer.openChannel();
+        await this.#openSignerChannel();
         const previousAutoClose = this.#signer.autoCloseTransportChannel;
         this.#signer.autoCloseTransportChannel = false;
         try {
@@ -345,313 +837,424 @@ export class AuthClient {
             this.#signer.autoCloseTransportChannel = previousAutoClose;
         }
     }
-    // Memoized — only runs #hydrate once, returns the same promise on repeat calls.
-    #init() {
-        if (!this.#initPromise) {
-            this.#initPromise = this.#hydrate();
+    /**
+     * Mints ahead of the next request when the page comes back, if one is due.
+     *
+     * Silent by design: this is not a request anyone is waiting on, so a failure
+     * leaves what is held in place for the next one to retry.
+     */
+    async #refreshInForeground() {
+        if (this.#interactions > 0 || this.#refreshingInForeground)
+            return;
+        this.#refreshingInForeground = true;
+        try {
+            await this.#refreshIfDue();
+        }
+        finally {
+            this.#refreshingInForeground = false;
         }
-        return this.#initPromise;
     }
-    // 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() {
-        const key = this.#options.identity ??
-            (await restoreKey(this.#storage, this.#options.keyType ?? ECDSA_KEY_LABEL));
-        if (!key)
+    async #refreshIfDue() {
+        // Waited for rather than raced: a `pageshow` or a pointer arriving before the
+        // restore has installed an identity would find an anonymous one and do
+        // nothing, and the moment would be spent. The restore mints on its own where
+        // a load needs one, so what this adds is the page coming back from the
+        // back-forward cache, and every later sign that somebody is here.
+        //
+        // Nothing is waiting on this, so a restore that fails is not this path's to
+        // report — and an unhandled rejection from an event handler is worse than
+        // the mint it was going to attempt.
+        const restored = await this.#init().then(() => true, () => false);
+        if (!restored)
             return;
-        const chain = await restoreChain(this.#storage);
-        if (!chain)
+        // Re-checked: a ceremony can start while the restore is resolving.
+        if (this.#interactions > 0)
             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();
-        }
-    }
-    #registerDefaultIdleCallback() {
-        const idleOptions = this.#options?.idleOptions;
-        if (!idleOptions?.onIdle && !idleOptions?.disableDefaultIdleCallback) {
-            // Invoked without being awaited, so handle the promise here. Reload only
-            // after teardown resolves, and only if it succeeded — a reload before or
-            // without teardown lets #hydrate restore the still-valid session.
-            this.idleManager?.registerCallback(() => {
-                void this.signOut()
-                    .then(() => location.reload())
-                    .catch(() => { });
-            });
-        }
-    }
-}
-/**
- * Encodes a Uint8Array to a base64 string.
- * @param bytes - The bytes to encode.
- */
-function toBase64(bytes) {
-    if ('toBase64' in bytes && typeof bytes.toBase64 === 'function') {
-        return bytes.toBase64();
+        const identity = this.#identity;
+        if (identity instanceof SessionIdentity)
+            await identity.refresh().catch(() => undefined);
     }
-    let binary = '';
-    for (let i = 0; i < bytes.byteLength; i++) {
-        binary += String.fromCharCode(bytes[i]);
-    }
-    return globalThis.btoa(binary);
-}
-/**
- * Decodes a base64 string to a Uint8Array.
- * @param str - The base64-encoded string.
- */
-function fromBase64(str) {
-    if ('fromBase64' in Uint8Array && typeof Uint8Array.fromBase64 === 'function') {
-        return Uint8Array.fromBase64(str);
+    /** Ends the session at the canister, so nothing more can be minted from it. */
+    async #revoke(key, sessionChain) {
+        const minter = await SessionMinter.create({
+            sessionKey: key,
+            sessionChain,
+            canisterId: this.#canisterId,
+            agentOptions: this.#options.agentOptions,
+        });
+        await minter.revoke();
     }
-    const binary = globalThis.atob(str);
-    const bytes = new Uint8Array(binary.length);
-    for (let i = 0; i < binary.length; i++) {
-        bytes[i] = binary.charCodeAt(i);
+    /**
+     * Moves what a ceremony minted into the slot every tab acts with.
+     *
+     * Overwrites rather than clearing and re-filling, so there is no moment where
+     * the origin holds nothing — and what it replaces is a credential rooted at
+     * whatever account the previous session belonged to.
+     */
+    async #promoteAppCredential(identity, chain) {
+        // Written from what the ceremony minted rather than read back out of the
+        // pending slot: a read that came back empty returned silently and left the
+        // slot holding the previous account's credential, which the identity opened
+        // on the next line would then adopt.
+        await this.#credentialStorage.set(this.#slots.app, { identity, chain });
+        // Best-effort: what is left behind is a spent five-minute record in a slot
+        // nothing reads, replaced by the next ceremony.
+        await this.#credentialStorage.remove(this.#slots.appPending).catch(() => undefined);
     }
-    return bytes;
-}
-/**
- * Generates a new session key.
- * @param keyType - The key algorithm to use.
- */
-async function generateKey(keyType) {
-    if (keyType === ED25519_KEY_LABEL) {
-        return Ed25519KeyIdentity.generate();
+    #minterFor(key, sessionChain) {
+        return SessionMinter.create({
+            sessionKey: key,
+            sessionChain,
+            canisterId: this.#canisterId,
+            agentOptions: this.#options.agentOptions,
+        });
     }
-    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);
+    /**
+     * Builds the identity an application acts with, from a session it holds.
+     *
+     * Little more than a constructor call: the identity resolves the account key it
+     * needs, so this passes the session's own shape and the slot to use and nothing
+     * more.
+     * @param key - The session key, which signs the mints.
+     * @param sessionChain - The chain that authorises it, and whose earliest
+     *   delegation bounds how long anything can be minted.
+     * @param source - A minter already built for this session, where the caller has
+     *   one. A sign-in does; a page load does not.
+     */
+    async #openSession(key, sessionChain, source) {
+        const minter = source ?? (await this.#minterFor(key, sessionChain));
+        // The account comes from the record, which both callers have already
+        // written or checked: a ceremony persists the session before this runs, and
+        // a restore refuses a record that names nobody. Without it the identity
+        // would take its account from whatever the app slot held, which a previous
+        // sign-in may still own.
+        const held = this.#stateStorage.get(this.#slots.state);
+        // True only for the mint a ceremony's own session is opened with. A session
+        // refused there never worked: `signIn` rejects, and a record saying a
+        // session ended here would describe one nobody ever used. Every refusal
+        // after it is a session that was in use ending.
+        let opening = source !== undefined;
+        const identity = await SessionIdentity.create({
+            sessionExpiresAtMs: earliestExpiryMs(sessionChain),
+            source: minter,
+            storage: this.#credentialStorage,
+            slot: this.#slots.app,
+            expectedAccount: held?.principal,
+            onSessionGone: () => {
+                void this.#endOrDrop(held, !opening).catch(() => undefined);
+                this.#installIdentity(new AnonymousIdentity());
+            },
+        });
+        opening = false;
+        return identity;
     }
-    if (!stored)
-        return null;
-    try {
-        // CryptoKeyPair (object) → ECDSA, JSON string → Ed25519
-        if (typeof stored === 'object') {
-            return await ECDSAKeyIdentity.fromKeyPair(stored);
+    /**
+     * Ends the sign-in, or only this origin's claim on it.
+     *
+     * A refused mint says the session this origin held is dead, and a domain has
+     * one: it cannot be revived, only replaced. So if the record still names what
+     * this origin was operating under — same account, same expiry — it names a
+     * session nobody can use, and it is published as over. If it has moved on in
+     * either respect, someone else owns the sign-in now and this origin converges
+     * to them rather than retracting what they published.
+     * @param held - The record as it stood when the session was opened.
+     * @param ended - Whether a session that was in use has ended, as opposed to a
+     *   ceremony's session being refused before it was ever usable. The first is
+     *   published as expired; the second leaves nothing behind.
+     */
+    async #endOrDrop(held, ended) {
+        const now = this.#stateStorage.get(this.#slots.state);
+        const unchanged = held !== null &&
+            now !== null &&
+            now.principal.compareTo(held.principal) === 'eq' &&
+            now.expiration === held.expiration;
+        if (!unchanged) {
+            await this.#dropSession();
+            return;
         }
-        return Ed25519KeyIdentity.fromJSON(stored);
+        await (ended ? this.#expireSession(now.principal) : this.#endSession());
     }
-    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;
+    /**
+     * Publishes the sign-in as over, rather than as never having happened.
+     *
+     * A session that ran out or was revoked ended on its own, and an application
+     * says so differently: "your session ended, sign back in" names the account it
+     * ended for, which a removed record cannot. Every tab and sibling reads
+     * `expired` from it for the same reason. Signing out removes the record
+     * instead — that is the user asking to leave, not a session running its
+     * course.
+     * @param principal - The account whose session ended.
+     */
+    async #expireSession(principal) {
+        this.#stateStorage.set(this.#slots.state, {
+            principal,
+            expiration: BigInt(Date.now()) * 1000000n,
+        });
+        await this.#clearCredentials();
     }
-}
-// Reads the pending-key registry, dropping malformed entries. The value comes
-// from storage, so guard against corruption: keep only real pending-key slots
-// with a finite expiry (a NaN expiry compares false forever and never sweeps;
-// a foreign slot would make the sweep remove an unrelated storage key).
-async function readPendingRegistry(storage) {
-    const raw = await storage.get(PENDING_KEYS_REGISTRY_KEY);
-    if (typeof raw !== 'string')
-        return [];
-    try {
-        const parsed = JSON.parse(raw);
-        if (!Array.isArray(parsed))
-            return [];
-        return parsed.filter((entry) => {
-            if (typeof entry !== 'object' || entry === null)
-                return false;
-            const { slot, expiresAt } = entry;
-            return (typeof slot === 'string' &&
-                slot.startsWith(PENDING_KEY_PREFIX) &&
-                typeof expiresAt === 'number' &&
-                Number.isFinite(expiresAt));
+    /**
+     * Restores again, because the record changed under this client.
+     *
+     * Queued behind whatever restore is in flight rather than replacing it: two
+     * restores reading one store would both install an identity, and the order
+     * they finished in would decide which. A failure is forgotten the same way
+     * {@link AuthClient.#init} forgets one, so the next call tries again.
+     */
+    #restoreAgain() {
+        // Coalescing, not queueing: a pass that has not started yet will read the
+        // same record a second one would, so any burst collapses to one more pass.
+        // Each pass can install an identity, and installing disposes the one it
+        // replaces — redundant passes mean disposing an identity with requests in
+        // flight against it.
+        if (this.#restoreQueued)
+            return;
+        this.#restoreQueued = true;
+        const promise = (this.#initPromise ?? Promise.resolve())
+            .catch(() => undefined)
+            .then(() => {
+            this.#restoreQueued = false;
+            return this.#restore();
+        })
+            .catch((error) => {
+            this.#restoreQueued = false;
+            if (this.#initPromise === promise) {
+                this.#initPromise = null;
+            }
+            throw error;
         });
+        this.#initPromise = promise;
+        // Nothing is waiting on this yet — the next `getIdentity()` is — so a
+        // rejection here would be unhandled until then.
+        promise.catch(() => undefined);
     }
-    catch {
-        return [];
+    // Memoized — only runs #hydrate once, returns the same promise on repeat calls.
+    //
+    // Forgotten again if it rejected, so a later call restores rather than
+    // replaying the failure: a restore reaches the network, and one unreachable
+    // boundary node at load would otherwise leave every `getIdentity()` for the
+    // life of the page rejecting with an error nothing can retry past.
+    #init() {
+        if (!this.#initPromise) {
+            const promise = this.#restore().catch((error) => {
+                if (this.#initPromise === promise) {
+                    this.#initPromise = null;
+                }
+                throw error;
+            });
+            this.#initPromise = promise;
+        }
+        return this.#initPromise;
     }
-}
-async function writePendingRegistry(storage, entries) {
-    if (entries.length === 0) {
-        await storage.remove(PENDING_KEYS_REGISTRY_KEY);
-        return;
+    // Marks a restore as running, so what it writes does not come back as a
+    // record that changed under this client.
+    async #restore() {
+        this.#restoring = true;
+        try {
+            await this.#hydrate();
+        }
+        finally {
+            this.#restoring = false;
+        }
     }
-    await storage.set(PENDING_KEYS_REGISTRY_KEY, JSON.stringify(entries));
-}
-// Removes expired pending-key slots, then registers `slot` with a fresh expiry.
-async function sweepAndRegisterPendingKey(storage, slot, now) {
-    const entries = await readPendingRegistry(storage);
-    const live = [];
-    for (const entry of entries) {
-        if (entry.slot === slot)
-            continue; // re-registered with a fresh expiry below
-        if (entry.expiresAt <= now) {
-            await storage.remove(entry.slot);
-        }
-        else {
-            live.push(entry);
-        }
-    }
-    live.push({ slot, expiresAt: now + PENDING_KEY_TTL_MS });
-    await writePendingRegistry(storage, live);
-}
-// Drops a slot from the pending-key registry once its flow completes.
-async function unregisterPendingKey(storage, slot) {
-    const entries = await readPendingRegistry(storage);
-    const remaining = entries.filter((entry) => entry.slot !== slot);
-    if (remaining.length !== entries.length) {
-        await writePendingRegistry(storage, remaining);
+    // 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() {
+        const restored = await this.#restoreSession();
+        const key = restored?.identity;
+        const chain = restored?.chain;
+        if (!key || !chain) {
+            // Nothing to restore, so this origin cannot act — and saying otherwise is
+            // what the state leading forbids. Discarded rather than removed, because a
+            // record that reaches past this origin belongs to whoever published it. A
+            // record already past its expiry says the session ended rather than that
+            // this origin holds it, so it is left to say so.
+            if (this.#readStatus().state === 'signed-in')
+                await this.#dropSession();
+            this.#installIdentity(new AnonymousIdentity());
+            return;
+        }
+        // The state decides whether this origin is signed in, so a chain it does not
+        // back belongs to a sign-in that has ended: drop it rather than restore it,
+        // or getIdentity() would hand back an identity isAuthenticated() calls
+        // signed out. Asked after the chain is read, so a visitor who was never
+        // signed in removes nothing.
+        if (this.#stateStorage.get(this.#slots.state) === null) {
+            await this.#endSession();
+            return;
+        }
+        if (!('sign' in key)) {
+            this.#installIdentity(new AnonymousIdentity());
+            return;
+        }
+        let identity;
+        try {
+            identity = await this.#openSession(key, chain);
+        }
+        catch (error) {
+            // The record names an account this session cannot produce a credential
+            // for, so it is not a sign-in this origin can act on. Dropped rather than
+            // ended: on a shared store the record belongs to whoever published it,
+            // and only the identity provider can say it is stale.
+            if (!(error instanceof AccountMismatchError))
+                throw error;
+            await this.#dropSession();
+            this.#installIdentity(new AnonymousIdentity());
+            return;
+        }
+        if (this.#disposed) {
+            // Disposed while this was in flight: install nothing, and stop the refresh
+            // this identity has already scheduled for itself.
+            identity.dispose();
+            return;
+        }
+        // The state decides who is signed in here, and a sibling subdomain can have
+        // changed it while this origin was away. Credentials rooted at an account the
+        // state no longer names belong to a sign-in that has ended, so they go rather
+        // than being restored — the app credential with them, since `#openSession`
+        // may have minted one for an account the state no longer names.
+        const state = this.#stateStorage.get(this.#slots.state);
+        if (state === null || state.principal.toText() !== identity.getPrincipal().toText()) {
+            // Both of them: the one just opened, which was never installed, and
+            // whatever this client was still answering with.
+            identity.dispose();
+            this.#installIdentity(new AnonymousIdentity());
+            await this.#dropSession();
+            return;
+        }
+        this.#installIdentity(identity);
     }
-}
-/**
- * Loads a session key from a specific storage slot, deserializing by stored
- * shape (`CryptoKeyPair` → ECDSA, JSON string → Ed25519). Unlike
- * {@link restoreKey} it does not migrate from localStorage — it reads only the
- * given slot, as used for a redirect flow's per-flow pending key.
- * @param storage - The storage backend.
- * @param storageKey - The slot to read.
- */
-async function restoreKeyAt(storage, storageKey) {
-    const stored = await storage.get(storageKey);
-    if (!stored)
-        return null;
-    try {
-        if (typeof stored === 'object') {
-            return await ECDSAKeyIdentity.fromKeyPair(stored);
+    /**
+     * Stores the session as one record and records the state it puts this origin
+     * in, so {@link isAuthenticated} can answer without reading it back.
+     */
+    async #persistSession(identity, chain, accountKey) {
+        await this.#credentialStorage.set(this.#slots.session, { identity, chain });
+        let earliest = null;
+        for (const { delegation } of chain.delegations) {
+            if (earliest === null || delegation.expiration < earliest) {
+                earliest = delegation.expiration;
+            }
+        }
+        if (earliest !== null) {
+            // The account is what a mint reported, and the sign-in lasts as long as
+            // the session chain's earliest delegation.
+            this.#stateStorage.set(this.#slots.state, {
+                principal: Principal.selfAuthenticating(new Uint8Array(accountKey)),
+                expiration: earliest,
+            });
         }
-        return Ed25519KeyIdentity.fromJSON(stored);
     }
-    catch {
-        return null;
+    /**
+     * Loads the stored session. Returns `null` and ends the sign-in where the
+     * delegation has expired or the record cannot be read.
+     */
+    async #restoreSession() {
+        const credential = await this.#credentialStorage.get(this.#slots.session);
+        if (credential === null)
+            return null;
+        // A record with no chain is not a session: only a ceremony's own slot may
+        // hold a key alone. The credentials go, and the record stays: its expiry is
+        // the session's, so a chain this old leaves a record that reads as expired —
+        // which is what a page loading after a session ran out should say.
+        if (credential.chain === undefined || !isDelegationValid(credential.chain)) {
+            await this.#clearCredentials();
+            return null;
+        }
+        return credential;
+    }
+    /**
+     * Ends the sign-in: what a user pressing sign out asks for.
+     *
+     * Retracts the state, including anything the store publishes beyond this
+     * origin, because a sibling reading a shared record must stop seeing one.
+     */
+    async #endSession() {
+        this.#stateStorage.remove(this.#slots.state);
+        await this.#clearCredentials();
+    }
+    /**
+     * Drops this origin's claim on a sign-in without retracting what is published.
+     *
+     * What finding out does, which is a different act. 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 the shared record was written by that
+     * sibling a moment ago, so retracting it would tell it that the session it just
+     * obtained is gone.
+     */
+    async #dropSession() {
+        this.#stateStorage.discard(this.#slots.state);
+        await this.#clearCredentials();
+    }
+    // Every slot a completed sign-in writes. Not the ceremony's pending slot: a
+    // flow that completed has already emptied it, and one that has not may still
+    // return for it — a sign-out here cannot tell an abandoned key from a live one.
+    //
+    // The state is retracted before this by both callers: it is what says whether
+    // this origin is signed in, and a teardown that failed partway must not leave
+    // it saying yes.
+    //
+    // Both are attempted whatever either does, since a credential that survives can
+    // still be adopted; the first failure is reported once neither is left behind.
+    async #clearCredentials() {
+        const outcomes = await Promise.allSettled([
+            this.#credentialStorage.remove(this.#slots.session),
+            this.#credentialStorage.remove(this.#slots.app),
+        ]);
+        const failed = outcomes.find((outcome) => outcome.status === 'rejected');
+        if (failed !== undefined)
+            throw failed.reason;
     }
 }
-/**
- * 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()));
+/** The moment a chain stops being usable: its earliest delegation's expiry. */
+function earliestExpiryMs(chain) {
     let earliest = 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());
-    }
+    return earliest === null ? 0 : Number(earliest / 1000000n);
 }
-/**
- * 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;
-    }
+/** A key's public half as text, for comparing two keys without holding both. */
+function publicKeyOf(key) {
+    return toBase64(new Uint8Array(key.getPublicKey().toDer()));
 }
 /**
- * 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);
-}
-/** 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);
-}
-/**
- * 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).
+ * The `returnTo` as a URL this origin may navigate to, or `undefined`.
+ *
+ * Same-origin and `http(s)` only. Anything else is ignored rather than refused,
+ * because a `returnTo` is a convenience and failing a sign-in or a sign-out over
+ * one would be worse than landing on the page the caller started from. Returning
+ * the parsed URL rather than a boolean is what lets callers navigate to
+ * `target.href` instead of to the raw value they were handed.
  */
-async function migrateFromLocalStorage(storage, keyType) {
+function sameOriginTarget(returnTo) {
+    let target;
     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;
+        target = new URL(returnTo, window.location.href);
+    }
+    catch {
+        return undefined;
     }
-    catch (error) {
-        console.error(`error while attempting to recover localstorage: ${error}`);
-        return null;
+    if ((target.protocol === 'https:' || target.protocol === 'http:') &&
+        target.origin === window.location.origin) {
+        return target;
     }
+    return undefined;
 }
-/**
- * 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(params) {
+    if (params.openIdProvider !== undefined && params.ssoDomain !== undefined) {
+        throw new Error('openIdProvider and ssoDomain are mutually exclusive');
+    }
+    if (params.ssoDomain !== undefined) {
+        const domain = normalizeSsoDomain(params.ssoDomain);
+        const keys = params.keys ?? DEFAULT_SSO_SCOPE_KEYS;
+        return keys.map((key) => `sso:${domain}:${key}`);
+    }
+    if (params.openIdProvider === undefined) {
+        throw new Error('scopedKeys requires either openIdProvider or ssoDomain');
+    }
     const provider = OPENID_PROVIDER_URLS[params.openIdProvider];
     const keys = params.keys ?? DEFAULT_OPENID_SCOPE_KEYS;
     return keys.map((key) => `openid:${provider}:${key}`);