@icp-sdk/auth 8.0.3 → 9.0.0

package/dist/esm/client/app-delegation-source.d.ts

@@ -0,0 +1,65 @@
+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 declare class SessionGoneError extends Error {
+    constructor(message?: string);
+}
+/**
+ * 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 declare class SessionUnsupportedError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare class AccountMismatchError extends Error {
+    constructor();
+}
+/**
+ * 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 declare const sameKey: (a: Uint8Array, b: Uint8Array) => boolean;
+/** The leaf of a chain: the key it authorises. */
+export declare const delegatesTo: (chain: DelegationChain) => Uint8Array | undefined;
+/**
+ * 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 declare const chainAuthorisesKey: (chain: DelegationChain, keyDer: Uint8Array) => boolean;

package/dist/esm/client/app-delegation-source.js

@@ -0,0 +1,58 @@
+/**
+ * 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) {
+        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';
+    }
+}
+/** Whether two DER-encoded keys are the same bytes. */
+export const sameKey = (a, b) => a.length === b.length && a.every((byte, i) => byte === b[i]);
+/** The leaf of a chain: the key it authorises. */
+export const delegatesTo = (chain) => 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, keyDer) => {
+    const leaf = delegatesTo(chain);
+    return leaf !== undefined && sameKey(new Uint8Array(leaf), new Uint8Array(keyDer));
+};
+//# sourceMappingURL=app-delegation-source.js.map

package/dist/esm/client/app-delegation-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-delegation-source.js","sourceRoot":"","sources":["../../../src/client/app-delegation-source.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC,YAAY,OAAO,GAAG,mDAAmD;QACvE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C;QACE,KAAK,CAAC,kEAAkE,CAAC,CAAC;QAC1E,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAqBD,uDAAuD;AACvD,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAa,EAAE,CAAa,EAAW,EAAE,CAC/D,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE/D,kDAAkD;AAClD,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAsB,EAA0B,EAAE,CAC5E,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,KAAsB,EAAE,MAAkB,EAAW,EAAE;IACxF,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAChC,OAAO,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;AACrF,CAAC,CAAC"}

package/dist/esm/client/app-lock.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Runs `mint` while holding a named lock, where the environment has one.
+ *
+ * The lock is the library coordinating with itself rather than anything a store
+ * provides, so a store answers only whether another tab can read it and needs to
+ * know nothing about the Web Locks API.
+ *
+ * Where there is no lock — an older browser, or a store no other tab reads —
+ * `mint` runs straight away and every tab mints for itself. That costs calls and
+ * never correctness: coordination may only ever suppress a mint, never be
+ * required for one.
+ *
+ * `mint` is handed a signal that fires when the lock is taken away by
+ * {@link stealMintLock}. It is the only thing a mint can act on, because a call
+ * already sent cannot be recalled: the mint runs to completion and the signal is
+ * what tells it to throw away the result rather than store it.
+ * @param name - The lock to hold, or `null` to run without one.
+ * @param mint - The work to serialise, taking the signal described above.
+ */
+export declare function withMintLock<T>(name: string | null, mint: (stolen: AbortSignal) => Promise<T>): Promise<T>;
+/**
+ * Takes the lock away from whoever holds it, without waiting for them.
+ *
+ * What signing out does. Queueing would make a sign-out the user asked for wait
+ * on a canister call in another tab, and a mint that finished afterwards would
+ * write a credential into the slot the sign-out had just cleared.
+ * @param name - The lock to take, or `null` where none is held.
+ */
+export declare function stealMintLock(name: string | null): Promise<void>;
+/**
+ * A lock this holder keeps until it gives it up, and a signal for losing it.
+ *
+ * Unlike {@link withMintLock}, what needs guarding here is not one call but a
+ * span — a ceremony is several calls and then several writes — so the lock is
+ * held across it and released by the holder rather than by a callback returning.
+ */
+export interface HeldLock {
+    /** Fires when someone else takes this lock away. */
+    readonly stolen: AbortSignal;
+    /**
+     * Gives the lock up.
+     *
+     * Idempotent, and safe to call after it was stolen: releasing a lock this
+     * holder no longer has does nothing.
+     */
+    release(): void;
+}
+/**
+ * Takes a lock away from whoever holds it and keeps it until released.
+ *
+ * Taken rather than queued for, like {@link stealMintLock} and for the same
+ * reason: the newer intent is the one to honour. A user who presses sign in
+ * again means the second press, and an origin has one signer window, so the two
+ * cannot both proceed anyway. The incumbent finds out through {@link
+ * HeldLock.stolen} and throws its result away instead of writing it.
+ *
+ * Where there is no lock — an older browser, or a caller that passes `null`
+ * because nothing else could be holding one — the result never reports a steal
+ * and releasing does nothing. That costs coordination, never correctness:
+ * coordination may only ever suppress work, never be required for it.
+ * @param name - The lock to take, or `null` to take none.
+ */
+export declare function stealLock(name: string | null): HeldLock;

package/dist/esm/client/app-lock.js

@@ -0,0 +1,92 @@
+/**
+ * Runs `mint` while holding a named lock, where the environment has one.
+ *
+ * The lock is the library coordinating with itself rather than anything a store
+ * provides, so a store answers only whether another tab can read it and needs to
+ * know nothing about the Web Locks API.
+ *
+ * Where there is no lock — an older browser, or a store no other tab reads —
+ * `mint` runs straight away and every tab mints for itself. That costs calls and
+ * never correctness: coordination may only ever suppress a mint, never be
+ * required for one.
+ *
+ * `mint` is handed a signal that fires when the lock is taken away by
+ * {@link stealMintLock}. It is the only thing a mint can act on, because a call
+ * already sent cannot be recalled: the mint runs to completion and the signal is
+ * what tells it to throw away the result rather than store it.
+ * @param name - The lock to hold, or `null` to run without one.
+ * @param mint - The work to serialise, taking the signal described above.
+ */
+export function withMintLock(name, mint) {
+    const locks = globalThis.navigator?.locks;
+    if (name === null || locks === undefined) {
+        // Nothing can take a lock that was never held, so the signal never fires.
+        return mint(new AbortController().signal);
+    }
+    const stolen = new AbortController();
+    const held = locks.request(name, () => mint(stolen.signal));
+    // A steal releases this tab's lock and rejects this promise, in this document.
+    // That rejection is the only notice another tab's sign-out can deliver, so it
+    // is turned into the signal `mint` was given rather than being surfaced: the
+    // mint decides what to do about it, and the caller sees whatever it returns.
+    held.catch(() => stolen.abort());
+    return held;
+}
+/**
+ * Takes the lock away from whoever holds it, without waiting for them.
+ *
+ * What signing out does. Queueing would make a sign-out the user asked for wait
+ * on a canister call in another tab, and a mint that finished afterwards would
+ * write a credential into the slot the sign-out had just cleared.
+ * @param name - The lock to take, or `null` where none is held.
+ */
+export async function stealMintLock(name) {
+    const locks = globalThis.navigator?.locks;
+    if (name === null || locks === undefined)
+        return;
+    // Granted at once, and released at once: holding it would only make the caller
+    // the next thing a queued mint waits for.
+    await locks.request(name, { steal: true }, () => undefined).catch(() => undefined);
+}
+/**
+ * Takes a lock away from whoever holds it and keeps it until released.
+ *
+ * Taken rather than queued for, like {@link stealMintLock} and for the same
+ * reason: the newer intent is the one to honour. A user who presses sign in
+ * again means the second press, and an origin has one signer window, so the two
+ * cannot both proceed anyway. The incumbent finds out through {@link
+ * HeldLock.stolen} and throws its result away instead of writing it.
+ *
+ * Where there is no lock — an older browser, or a caller that passes `null`
+ * because nothing else could be holding one — the result never reports a steal
+ * and releasing does nothing. That costs coordination, never correctness:
+ * coordination may only ever suppress work, never be required for it.
+ * @param name - The lock to take, or `null` to take none.
+ */
+export function stealLock(name) {
+    const stolen = new AbortController();
+    const locks = globalThis.navigator?.locks;
+    if (name === null || locks === undefined) {
+        return { stolen: stolen.signal, release: () => { } };
+    }
+    // The callback holds the lock for as long as what it returns is pending, so
+    // this is what `release` settles. A steal rejects the `request` promise in this
+    // document, which is the only notice the platform gives.
+    let release = () => { };
+    const held = new Promise((resolve) => {
+        release = resolve;
+    });
+    void locks
+        .request(name, { steal: true }, () => held)
+        .catch((error) => {
+        // Only a steal, which arrives as an `AbortError`. A request can fail for
+        // reasons that are nothing to do with another holder — a frame going away
+        // takes its callback with it — and reporting one of those as a steal would
+        // tell the caller its work was superseded when nothing had superseded it.
+        if (error instanceof DOMException && error.name === 'AbortError') {
+            stolen.abort();
+        }
+    });
+    return { stolen: stolen.signal, release: () => release() };
+}
+//# sourceMappingURL=app-lock.js.map

package/dist/esm/client/app-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-lock.js","sourceRoot":"","sources":["../../../src/client/app-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAmB,EACnB,IAAyC;IAEzC,MAAM,KAAK,GAAG,UAAU,CAAC,SAAS,EAAE,KAAK,CAAC;IAC1C,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACzC,0EAA0E;QAC1E,OAAO,IAAI,CAAC,IAAI,eAAe,EAAE,CAAC,MAAM,CAAC,CAAC;IAC5C,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAe,CAAC;IAE1E,+EAA+E;IAC/E,8EAA8E;IAC9E,6EAA6E;IAC7E,6EAA6E;IAC7E,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IACjC,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAmB;IACrD,MAAM,KAAK,GAAG,UAAU,CAAC,SAAS,EAAE,KAAK,CAAC;IAC1C,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO;IAEjD,+EAA+E;IAC/E,0CAA0C;IAC1C,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;AACrF,CAAC;AAsBD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,SAAS,CAAC,IAAmB;IAC3C,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,MAAM,KAAK,GAAG,UAAU,CAAC,SAAS,EAAE,KAAK,CAAC;IAC1C,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACzC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC;IACtD,CAAC;IAED,4EAA4E;IAC5E,gFAAgF;IAChF,yDAAyD;IACzD,IAAI,OAAO,GAAe,GAAG,EAAE,GAAE,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACzC,OAAO,GAAG,OAAO,CAAC;IACpB,CAAC,CAAC,CAAC;IACH,KAAK,KAAK;SACP,OAAO,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC;SAC1C,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACxB,yEAAyE;QACzE,0EAA0E;QAC1E,2EAA2E;QAC3E,0EAA0E;QAC1E,IAAI,KAAK,YAAY,YAAY,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YACjE,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;IACH,CAAC,CAAC,CAAC;IAEL,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC;AAC7D,CAAC"}