@icp-sdk/auth 8.0.3 → 9.0.0

package/dist/esm/client/slots.js

@@ -0,0 +1,67 @@
+/**
+ * Every name one client writes under, and the one thing that knows the whole set.
+ *
+ * Its own module rather than living beside the credential store or the state
+ * store, because it belongs to neither: the credentials and the state of a
+ * sign-in are named from one namespace, and a list that sat in either file would
+ * have to reach across to the other.
+ */
+/**
+ * The bare names, before a namespace is applied.
+ *
+ * One list, so a name cannot be added to some of the places that need it and
+ * missed in others. It was two lists and a hand-written mapping, and the state
+ * record was left out of the namespacing for exactly that reason.
+ */
+const SLOT_NAMES = {
+    /** The session's key and the chain issued to it. */
+    session: 'session',
+    /**
+     * Where a sign-in ceremony keeps its key until it returns.
+     *
+     * Its own name rather than {@link SLOT_NAMES.session}, so a ceremony that is
+     * cancelled or never comes back cannot take a working session with it.
+     */
+    sessionPending: 'session-pending',
+    /** The key an application signs with, and its delegation. */
+    app: 'app',
+    /**
+     * Where a ceremony keeps the credential it minted until its session is stored.
+     *
+     * The store reaches every tab of the origin, so writing to the app name during
+     * a ceremony — or clearing it first — would change what those tabs act with
+     * before the sign-in has succeeded. This is promoted instead, once there is a
+     * session behind it.
+     */
+    appPending: 'app-pending',
+    /**
+     * The record of who is signed in here and until when.
+     *
+     * Not a credential slot, and named here anyway: a namespace that moved the
+     * credentials and left this fixed would give two clients their own keys and one
+     * shared answer to who is signed in.
+     */
+    state: 'ic-session-state',
+};
+/**
+ * What separates a namespace from the name it prefixes.
+ *
+ * A cross-origin contract rather than a detail: a sibling subdomain reads the
+ * state record by name, so both sides have to agree on this byte.
+ */
+const NAMESPACE_SEPARATOR = ':';
+/**
+ * The names one client writes under, prefixed where a namespace is set.
+ *
+ * Assigned in one place rather than defaulted by each store: implementations
+ * choosing their own is what produced three colliding slots in the arrangement
+ * this replaces, and one assigner cannot collide with itself. A namespace moves
+ * all of them at once, so an application running two clients under one origin
+ * separates them with one string rather than renaming some and missing others.
+ * @param namespace - Prefix for every name, or `undefined` for the bare ones.
+ */
+export function slotsFor(namespace) {
+    const prefix = namespace === undefined ? '' : `${namespace}${NAMESPACE_SEPARATOR}`;
+    return Object.fromEntries(Object.entries(SLOT_NAMES).map(([key, name]) => [key, `${prefix}${name}`]));
+}
+//# sourceMappingURL=slots.js.map

package/dist/esm/client/slots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.js","sourceRoot":"","sources":["../../../src/client/slots.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,GAAG;IACjB,oDAAoD;IACpD,OAAO,EAAE,SAAS;IAElB;;;;;OAKG;IACH,cAAc,EAAE,iBAAiB;IAEjC,6DAA6D;IAC7D,GAAG,EAAE,KAAK;IAEV;;;;;;;OAOG;IACH,UAAU,EAAE,aAAa;IAEzB;;;;;;OAMG;IACH,KAAK,EAAE,kBAAkB;CACjB,CAAC;AAEX;;;;;GAKG;AACH,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAKhC;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,SAAkB;IACzC,MAAM,MAAM,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,mBAAmB,EAAE,CAAC;IACnF,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,GAAG,MAAM,GAAG,IAAI,EAAE,CAAC,CAAC,CAClE,CAAC;AACb,CAAC"}

package/dist/esm/client/sso.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Normalizes an SSO domain to the authority the identity provider fetches the
+ * discovery document from: lowercased, IDNA-encoded, host and optional port.
+ *
+ * @param domain - The organization domain.
+ * @returns The normalized authority.
+ * @throws When `domain` is not a domain with an optional port.
+ */
+export declare function normalizeSsoDomain(domain: string): string;
+/**
+ * Checks whether an organization domain can be used for SSO sign-in: it is a
+ * domain name, and it publishes `/.well-known/ii-openid-configuration` with a
+ * `client_id` and an `openid_configuration` URL.
+ *
+ * The document must be served with `Access-Control-Allow-Origin: *`.
+ *
+ * The check waits on a third-party server and has no deadline of its own, so
+ * `signal` sets one. Pass `AbortSignal.timeout(...)` for a one-shot check, or a
+ * controller you abort per keystroke when checking as the user types.
+ *
+ * @param domain - The organization domain.
+ * @param signal - Bounds the check.
+ * @returns Whether the domain is usable for SSO sign-in.
+ * @throws When `signal` aborts — an abandoned check is not a verdict on the
+ *   domain, so it must not be read as `false`.
+ *
+ * @example
+ * if (await isValidSsoDomain(input.value, AbortSignal.timeout(5_000))) {
+ *   const authClient = new AuthClient({ ssoDomain: input.value });
+ *   await authClient.signIn();
+ * }
+ */
+export declare function isValidSsoDomain(domain: string, signal: AbortSignal): Promise<boolean>;

package/dist/esm/client/sso.js

@@ -0,0 +1,120 @@
+// The identity provider's cap on the domain it will fetch.
+const MAX_AUTHORITY_LENGTH = 255;
+const WELL_KNOWN_PATH = '/.well-known/ii-openid-configuration';
+/**
+ * `localhost` / `127.0.0.1`, optionally followed by `:<port>`. IPv6 loopback
+ * (`[::1]`, etc.) is intentionally not handled — the identity provider doesn't
+ * recognise it either, and its e2e setup uses the hostname form.
+ */
+function isLoopbackHost(host) {
+    let url;
+    try {
+        // Parse as a URL authority so the optional `:<port>` is split off for us
+        // rather than by hand. Invalid input throws and is treated as non-loopback.
+        url = new URL(`http://${host}`);
+    }
+    catch {
+        return false;
+    }
+    // A bare `host[:port]` has no path/query/fragment; reject e.g. `localhost/x`.
+    if (url.pathname !== '/' || url.search !== '' || url.hash !== '') {
+        return false;
+    }
+    return url.hostname === 'localhost' || url.hostname === '127.0.0.1';
+}
+/**
+ * Normalizes an SSO domain to the authority the identity provider fetches the
+ * discovery document from: lowercased, IDNA-encoded, host and optional port.
+ *
+ * @param domain - The organization domain.
+ * @returns The normalized authority.
+ * @throws When `domain` is not a domain with an optional port.
+ */
+export function normalizeSsoDomain(domain) {
+    const trimmed = domain.trim();
+    if (trimmed.length === 0) {
+        throw new Error('ssoDomain cannot be empty');
+    }
+    let url;
+    try {
+        url = new URL(`https://${trimmed}`);
+    }
+    catch {
+        throw new Error(`ssoDomain is not a domain: ${trimmed}`);
+    }
+    const authority = url.host;
+    // Rebuilding from the host and port alone has to reproduce what was parsed,
+    // so anything else the domain carried shows up as a difference.
+    if (new URL(`https://${authority}`).href !== url.href) {
+        throw new Error(`ssoDomain must be a domain and optional port, nothing else: ${trimmed}`);
+    }
+    if (authority.length > MAX_AUTHORITY_LENGTH) {
+        throw new Error(`ssoDomain exceeds ${MAX_AUTHORITY_LENGTH} characters`);
+    }
+    // A bare hostname is a half-typed domain, not something worth a request.
+    if (!authority.includes('.') && !isLoopbackHost(authority)) {
+        throw new Error(`ssoDomain is not a domain name: ${trimmed}`);
+    }
+    return authority;
+}
+function publishesSsoConfiguration(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const { client_id, openid_configuration } = value;
+    return typeof client_id === 'string' && typeof openid_configuration === 'string';
+}
+/**
+ * Checks whether an organization domain can be used for SSO sign-in: it is a
+ * domain name, and it publishes `/.well-known/ii-openid-configuration` with a
+ * `client_id` and an `openid_configuration` URL.
+ *
+ * The document must be served with `Access-Control-Allow-Origin: *`.
+ *
+ * The check waits on a third-party server and has no deadline of its own, so
+ * `signal` sets one. Pass `AbortSignal.timeout(...)` for a one-shot check, or a
+ * controller you abort per keystroke when checking as the user types.
+ *
+ * @param domain - The organization domain.
+ * @param signal - Bounds the check.
+ * @returns Whether the domain is usable for SSO sign-in.
+ * @throws When `signal` aborts — an abandoned check is not a verdict on the
+ *   domain, so it must not be read as `false`.
+ *
+ * @example
+ * if (await isValidSsoDomain(input.value, AbortSignal.timeout(5_000))) {
+ *   const authClient = new AuthClient({ ssoDomain: input.value });
+ *   await authClient.signIn();
+ * }
+ */
+export async function isValidSsoDomain(domain, signal) {
+    signal.throwIfAborted();
+    let normalized;
+    try {
+        normalized = normalizeSsoDomain(domain);
+    }
+    catch {
+        return false;
+    }
+    const scheme = isLoopbackHost(normalized) ? 'http' : 'https';
+    try {
+        const response = await fetch(`${scheme}://${normalized}${WELL_KNOWN_PATH}`, {
+            headers: { Accept: 'application/json' },
+            signal,
+        });
+        if (!response.ok) {
+            return false;
+        }
+        const valid = publishesSsoConfiguration(await response.json());
+        signal.throwIfAborted();
+        return valid;
+    }
+    catch (error) {
+        if (signal.aborted) {
+            throw error;
+        }
+        // A DNS, TLS, CORS, or parse failure all leave the domain unusable.
+        return false;
+    }
+}
+//# sourceMappingURL=sso.js.map

package/dist/esm/client/sso.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sso.js","sourceRoot":"","sources":["../../../src/client/sso.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAEjC,MAAM,eAAe,GAAG,sCAAsC,CAAC;AAE/D;;;;GAIG;AACH,SAAS,cAAc,CAAC,IAAY;IAClC,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,yEAAyE;QACzE,4EAA4E;QAC5E,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,8EAA8E;IAC9E,IAAI,GAAG,CAAC,QAAQ,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,IAAI,GAAG,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;QACjE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,GAAG,CAAC,QAAQ,KAAK,WAAW,IAAI,GAAG,CAAC,QAAQ,KAAK,WAAW,CAAC;AACtE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,WAAW,OAAO,EAAE,CAAC,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,8BAA8B,OAAO,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,SAAS,GAAG,GAAG,CAAC,IAAI,CAAC;IAC3B,4EAA4E;IAC5E,gEAAgE;IAChE,IAAI,IAAI,GAAG,CAAC,WAAW,SAAS,EAAE,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,+DAA+D,OAAO,EAAE,CAAC,CAAC;IAC5F,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,GAAG,oBAAoB,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,qBAAqB,oBAAoB,aAAa,CAAC,CAAC;IAC1E,CAAC;IACD,yEAAyE;IACzE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,mCAAmC,OAAO,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,yBAAyB,CAAC,KAAc;IAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,KAAgC,CAAC;IAC7E,OAAO,OAAO,SAAS,KAAK,QAAQ,IAAI,OAAO,oBAAoB,KAAK,QAAQ,CAAC;AACnF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAc,EAAE,MAAmB;IACxE,MAAM,CAAC,cAAc,EAAE,CAAC;IAExB,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IAC7D,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,MAAM,MAAM,UAAU,GAAG,eAAe,EAAE,EAAE;YAC1E,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE;YACvC,MAAM;SACP,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,KAAK,GAAG,yBAAyB,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QAC/D,MAAM,CAAC,cAAc,EAAE,CAAC;QACxB,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,MAAM,KAAK,CAAC;QACd,CAAC;QACD,oEAAoE;QACpE,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/esm/client/state-storage.d.ts

@@ -0,0 +1,135 @@
+import { Principal } from '@icp-sdk/core/principal';
+/**
+ * What a client knows about its sign-in without holding a credential: which
+ * account is signed in here, and when that ends.
+ *
+ * Both fields are public. The principal is what an application's canisters see
+ * as the caller, and the expiration is what the identity provider granted, so
+ * neither is a secret and both can live somewhere a page reads synchronously.
+ */
+export interface SessionState {
+    principal: Principal;
+    /** Nanoseconds since the epoch, matching `Delegation.expiration`. */
+    expiration: bigint;
+    /**
+     * Whether this origin holds a credential for that account, or only knows the
+     * sign-in exists.
+     *
+     * Derived on read and never published: where the record reaches further than
+     * one origin, the record itself cannot carry a per-origin fact. A sibling
+     * subdomain that has not acquired its own credential reads the sign-in with
+     * `held: false`, which is what tells it to acquire one.
+     */
+    held: boolean;
+}
+/**
+ * Holds the state of a sign-in.
+ *
+ * This is what decides whether this origin is signed in and as whom. It is a
+ * store of its own because it has to be readable without awaiting, which a
+ * credential store does not.
+ *
+ * A record can be stale — a session revoked at the canister still reads as
+ * signed in until something calls and is refused — so it is the state as this
+ * browser knows it rather than an authority against the network.
+ */
+export interface StateStorage {
+    /** The state, or `null` where nothing is signed in within this store's reach. */
+    get(key: string): SessionState | null;
+    set(key: string, state: Omit<SessionState, 'held'>): void;
+    /**
+     * Removes the state, and anything this store publishes beyond this origin.
+     *
+     * What signing out does: the user ended the sign-in, so a sibling reading a
+     * shared record must stop seeing one.
+     */
+    remove(key: string): void;
+    /**
+     * Removes what this origin holds, leaving anything shared alone.
+     *
+     * What finding out does, which is a different act. An origin whose chain turns
+     * out to be dead cannot tell whether the session was revoked or replaced by a
+     * sibling 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.
+     *
+     * A store that publishes nothing beyond this origin answers it with
+     * {@link remove}, which is one line and the right answer.
+     */
+    discard(key: string): void;
+    /**
+     * Whether a sign-in kept in this store may be resumed without a ceremony.
+     *
+     * True only where the record reaches past this origin, because that is the
+     * case a silent re-issue exists for: a sibling reads the sign-in, holds no
+     * credential of its own, and needs the identity provider to remember the
+     * session it can extend. A store the origin keeps to itself has nothing to
+     * gain and would only be asking the provider to persist a sign-in on a device
+     * where nothing wanted one kept.
+     *
+     * Absent means false, which is the answer for a store that never considered
+     * the question.
+     */
+    readonly resumable?: boolean;
+    /**
+     * Registers a listener fired when the state under `key` changes, including
+     * when something other than this client changed it. Returns a function that
+     * unregisters it.
+     *
+     * Required rather than optional: two clients can share one store, even a
+     * store with no medium behind it, and a client that cannot be told the record
+     * changed under it goes on answering for a sign-in that is no longer there.
+     */
+    subscribe(key: string, listener: () => void): () => void;
+}
+/**
+ * State held for the lifetime of the instance and shared with nothing.
+ *
+ * For tests and for environments with no `localStorage`, where a client is
+ * alone and a reload starts from nothing.
+ * @see implements {@link StateStorage}
+ */
+export declare class MemoryStateStorage implements StateStorage {
+    #private;
+    get(key: string): SessionState | null;
+    set(key: string, state: Omit<SessionState, 'held'>): void;
+    remove(key: string): void;
+    /** The same as {@link remove}: this store publishes nothing at all. */
+    discard(key: string): void;
+    /**
+     * Fires when the state changes, which here means when something writes to
+     * this instance.
+     *
+     * Nothing outside the process can reach a `Map`, so a medium is not what makes
+     * this worth having: two clients can be handed the same instance, and this is
+     * how the one that did not write finds out. Each listener is told only when the
+     * record actually changed since it was last told, so a client's own writes do
+     * not come back to it as news.
+     */
+    subscribe(key: string, listener: () => void): () => void;
+}
+/**
+ * State in `localStorage`, so every tab of an origin agrees on it and it
+ * survives a reload.
+ *
+ * The two fields are written as `<principal>|<expiration>` rather than JSON,
+ * because an expiration is a `bigint` and JSON has no way to carry one.
+ * @see implements {@link StateStorage}
+ */
+export declare class LocalStateStorage implements StateStorage {
+    #private;
+    get(key: string): SessionState | null;
+    set(key: string, state: Omit<SessionState, 'held'>): void;
+    remove(key: string): void;
+    /** The same as {@link remove}: this store publishes nothing beyond the origin. */
+    discard(key: string): void;
+    /**
+     * Fires when the state changes, here or in another tab of this origin.
+     *
+     * `localStorage` raises `storage` in every tab except the one that wrote, so
+     * that event carries a change between tabs and a same-tab write is announced
+     * directly. Either way the record is readable before it is announced, so a
+     * listener asking who is signed in sees what it was told about.
+     */
+    subscribe(key: string, listener: () => void): () => void;
+}

package/dist/esm/client/state-storage.js

@@ -0,0 +1,178 @@
+import { Principal } from '@icp-sdk/core/principal';
+/**
+ * State held for the lifetime of the instance and shared with nothing.
+ *
+ * For tests and for environments with no `localStorage`, where a client is
+ * alone and a reload starts from nothing.
+ * @see implements {@link StateStorage}
+ */
+export class MemoryStateStorage {
+    #state = new Map();
+    #subscribers = new Map();
+    get(key) {
+        // Nothing reaches past this instance, so a record here is always one it holds.
+        const state = this.#state.get(key);
+        return state === undefined ? null : { ...state, held: true };
+    }
+    set(key, state) {
+        this.#state.set(key, state);
+        this.#fire(key);
+    }
+    remove(key) {
+        this.#state.delete(key);
+        this.#fire(key);
+    }
+    /** The same as {@link remove}: this store publishes nothing at all. */
+    discard(key) {
+        this.remove(key);
+    }
+    /**
+     * Fires when the state changes, which here means when something writes to
+     * this instance.
+     *
+     * Nothing outside the process can reach a `Map`, so a medium is not what makes
+     * this worth having: two clients can be handed the same instance, and this is
+     * how the one that did not write finds out. Each listener is told only when the
+     * record actually changed since it was last told, so a client's own writes do
+     * not come back to it as news.
+     */
+    subscribe(key, listener) {
+        let last = this.#raw(key);
+        const check = () => {
+            const now = this.#raw(key);
+            if (now !== last) {
+                last = now;
+                listener();
+            }
+        };
+        const listeners = this.#subscribers.get(key) ?? new Set();
+        listeners.add(check);
+        this.#subscribers.set(key, listeners);
+        return () => {
+            listeners.delete(check);
+        };
+    }
+    #fire(key) {
+        for (const check of [...(this.#subscribers.get(key) ?? [])])
+            check();
+    }
+    // The same shape `LocalStateStorage` keeps, so "changed" means the same thing
+    // in both: a record is one string, and comparing strings needs no field walk.
+    #raw(key) {
+        const state = this.#state.get(key);
+        return state === undefined
+            ? null
+            : `${state.principal.toText()}|${state.expiration.toString()}`;
+    }
+}
+/**
+ * State in `localStorage`, so every tab of an origin agrees on it and it
+ * survives a reload.
+ *
+ * The two fields are written as `<principal>|<expiration>` rather than JSON,
+ * because an expiration is a `bigint` and JSON has no way to carry one.
+ * @see implements {@link StateStorage}
+ */
+export class LocalStateStorage {
+    // Fired on a same-tab write: `storage` reaches the other tabs of an origin and
+    // deliberately not the one that wrote. Per key, because one store answers for
+    // whatever key it is handed.
+    #subscribers = new Map();
+    get(key) {
+        const raw = this.#localStorage().getItem(key);
+        if (raw === null)
+            return null;
+        const [principalText, expiration] = raw.split('|');
+        if (principalText === undefined || expiration === undefined)
+            return null;
+        try {
+            return {
+                principal: Principal.fromText(principalText),
+                expiration: BigInt(expiration),
+                // This record is written by this origin and read by no other, so having
+                // one and holding a credential for it are the same thing.
+                held: true,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    set(key, state) {
+        this.#localStorage().setItem(key, `${state.principal.toText()}|${state.expiration.toString()}`);
+        this.#fire(key);
+    }
+    remove(key) {
+        this.#localStorage().removeItem(key);
+        this.#fire(key);
+    }
+    /** The same as {@link remove}: this store publishes nothing beyond the origin. */
+    discard(key) {
+        this.remove(key);
+    }
+    /**
+     * Fires when the state changes, here or in another tab of this origin.
+     *
+     * `localStorage` raises `storage` in every tab except the one that wrote, so
+     * that event carries a change between tabs and a same-tab write is announced
+     * directly. Either way the record is readable before it is announced, so a
+     * listener asking who is signed in sees what it was told about.
+     */
+    subscribe(key, listener) {
+        let last = this.#raw(key);
+        const check = () => {
+            const now = this.#raw(key);
+            if (now !== last) {
+                last = now;
+                listener();
+            }
+        };
+        const listeners = this.#subscribers.get(key) ?? new Set();
+        listeners.add(check);
+        this.#subscribers.set(key, listeners);
+        const onStorage = (event) => {
+            // `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);
+        // `storage` is the only notice this store gets, and a page restored from the
+        // back-forward cache was not listening while it was frozen. So the record is
+        // re-read when the page is shown or its window regains focus, which is when
+        // somebody is about to act on the answer.
+        const onVisible = () => {
+            if (document.visibilityState === 'visible')
+                check();
+        };
+        const hooked = typeof document !== 'undefined';
+        if (hooked) {
+            document.addEventListener('visibilitychange', onVisible);
+            globalThis.addEventListener('pageshow', check);
+            globalThis.addEventListener('focus', check);
+        }
+        return () => {
+            listeners.delete(check);
+            globalThis.removeEventListener('storage', onStorage);
+            if (hooked) {
+                document.removeEventListener('visibilitychange', onVisible);
+                globalThis.removeEventListener('pageshow', check);
+                globalThis.removeEventListener('focus', check);
+            }
+        };
+    }
+    #fire(key) {
+        for (const check of [...(this.#subscribers.get(key) ?? [])])
+            check();
+    }
+    #raw(key) {
+        return this.#localStorage().getItem(key);
+    }
+    #localStorage() {
+        const ls = globalThis.localStorage;
+        if (!ls) {
+            throw new Error('Could not find local storage.');
+        }
+        return ls;
+    }
+}
+//# sourceMappingURL=state-storage.js.map

package/dist/esm/client/state-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-storage.js","sourceRoot":"","sources":["../../../src/client/state-storage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@icp-sdk/auth",
-  "version": "8.0.3",
+  "version": "9.0.0",
   "author": "DFINITY Stiftung <sdk@dfinity.org>",
   "license": "Apache-2.0",
   "description": "Authentication library for Internet Computer web apps",
@@ -60,6 +60,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json && pnpm lint:package",
     "test": "vitest",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
     "codestyle:check": "biome check",
     "codestyle:fix": "biome check --write",
     "lint:package": "publint --strict"

package/src/client/app-delegation-source.ts

@@ -0,0 +1,86 @@
+import type { DerEncodedPublicKey } from '@icp-sdk/core/agent';
+import type { DelegationChain } from '@icp-sdk/core/identity';
+
+/**
+ * Thrown when the canister has no session behind the caller: revoked, expired,
+ * pruned, or never one at all.
+ *
+ * This is the one terminal outcome. Everything else a mint can fail with, a
+ * transport error or an internal canister error, leaves the session alone and is
+ * worth retrying, so only this type may end a session.
+ */
+export class SessionGoneError extends Error {
+  constructor(message = 'The session behind this identity no longer exists') {
+    super(message);
+    this.name = 'SessionGoneError';
+  }
+}
+
+/**
+ * Thrown when the session is one this library cannot act for, however healthy it
+ * is.
+ *
+ * The third outcome, and the reason it is not either of the others: the session
+ * is neither gone nor worth retrying. Retrying returns the same answer forever,
+ * and reporting it as gone would retract a record for a sign-in that is alive,
+ * signing every tab on the domain out of it.
+ */
+export class SessionUnsupportedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SessionUnsupportedError';
+  }
+}
+
+/**
+ * Thrown when a mint answers for an account the caller was not expecting.
+ *
+ * The session is healthy and the mint succeeded; it is the pairing that is
+ * wrong. So it is neither gone nor retryable — asking again returns the same
+ * account — and the caller's own record is what has to give way.
+ */
+export class AccountMismatchError extends Error {
+  constructor() {
+    super('The minted delegation is not for the account this origin acts as');
+    this.name = 'AccountMismatchError';
+  }
+}
+
+/**
+ * Where {@link SessionIdentity} gets an app delegation from.
+ *
+ * The identity decides *when* to mint; this decides *how*. Splitting them is
+ * what lets the timing be tested without a replica, and what keeps the identity
+ * free of any agent or canister id.
+ */
+export interface AppDelegationSource {
+  /**
+   * Mint a delegation from the session to `appPublicKey`.
+   *
+   * Three outcomes. {@link SessionGoneError} where the session no longer
+   * exists, {@link SessionUnsupportedError} where it exists but this library
+   * cannot act for it, and anything else where the attempt may be worth
+   * repeating.
+   */
+  mint(appPublicKey: DerEncodedPublicKey): Promise<DelegationChain>;
+}
+
+/** Whether two DER-encoded keys are the same bytes. */
+export const sameKey = (a: Uint8Array, b: Uint8Array): boolean =>
+  a.length === b.length && a.every((byte, i) => byte === b[i]);
+
+/** The leaf of a chain: the key it authorises. */
+export const delegatesTo = (chain: DelegationChain): Uint8Array | undefined =>
+  chain.delegations[chain.delegations.length - 1]?.delegation.pubkey;
+
+/**
+ * Whether a chain's leaf authorises `keyDer` — the key that would sign with it.
+ *
+ * A chain paired with a key it does not authorise signs nothing the replica will
+ * accept, and fails with a signature error that points at neither half. Every
+ * place that holds both halves checks this.
+ */
+export const chainAuthorisesKey = (chain: DelegationChain, keyDer: Uint8Array): boolean => {
+  const leaf = delegatesTo(chain);
+  return leaf !== undefined && sameKey(new Uint8Array(leaf), new Uint8Array(keyDer));
+};