@icp-sdk/auth 8.0.3 → 9.0.0

package/dist/esm/client/auth-client.d.ts

@@ -1,11 +1,7 @@
-import { type Identity, type SignIdentity } from '@icp-sdk/core/agent';
-import { type PartialIdentity } from '@icp-sdk/core/identity';
-import type { Principal } from '@icp-sdk/core/principal';
-import { IdleManager, type IdleManagerOptions } from './idle-manager.js';
-import { type AuthClientStorage } from './storage.js';
-declare const ECDSA_KEY_LABEL = "ECDSA";
-declare const ED25519_KEY_LABEL = "Ed25519";
-type BaseKeyType = typeof ECDSA_KEY_LABEL | typeof ED25519_KEY_LABEL;
+import { type HttpAgentOptions, type Identity } from '@icp-sdk/core/agent';
+import { Principal } from '@icp-sdk/core/principal';
+import type { CredentialStorage } from './credential-storage.js';
+import { type StateStorage } from './state-storage.js';
 export type OpenIdProvider = 'google' | 'apple' | 'microsoft';
 export declare const OPENID_PROVIDER_URLS: {
     readonly google: "https://accounts.google.com";
@@ -13,36 +9,72 @@ export declare const OPENID_PROVIDER_URLS: {
     readonly microsoft: "https://login.microsoftonline.com/{tid}/v2.0";
 };
 declare const DEFAULT_OPENID_SCOPE_KEYS: readonly ["name", "email", "verified_email"];
+declare const DEFAULT_SSO_SCOPE_KEYS: readonly ["name", "email"];
 /**
- * Options for creating an {@link AuthClient}.
+ * Options for creating an {@link AuthClient}, other than the one-click sign-in
+ * entry point. See {@link AuthClientCreateOptions}.
  */
-export interface AuthClientCreateOptions {
+export interface AuthClientBaseOptions {
+    /**
+     * Where credentials are kept. Defaults to IndexedDB.
+     */
+    credentialStorage?: CredentialStorage;
     /**
-     * An identity to authenticate via delegation.
+     * Prefix for every slot this client writes under.
+     *
+     * Slots are assigned in one place rather than defaulted by each store, and this
+     * moves all of them at once — so an application running two clients under one
+     * origin separates them with a single string and cannot rename some while
+     * missing others.
+     *
+     * Leave it unset unless a second client shares this origin.
      */
-    identity?: SignIdentity | PartialIdentity;
+    namespace?: string;
     /**
-     * Persistent storage backend. Defaults to IndexedDB.
-     * @default IdbStorage
+     * Where the state of the sign-in is kept: which account is signed in here,
+     * and until when. Defaults to `localStorage`.
      */
-    storage?: AuthClientStorage;
+    stateStorage?: StateStorage;
     /**
-     * Type of session key to generate on each sign-in.
+     * Stops this client from watching the browser for signs that somebody is here.
      *
-     * Use `'Ed25519'` when your storage provider does not support `CryptoKey`.
-     * @default 'ECDSA'
+     * All of them together, because they make one claim: the page being shown, the
+     * window regaining focus, a pointer or a key. A backgrounded tab has its timers
+     * throttled, so its delegation can lapse while nobody is looking and the first
+     * click after coming back waits for a mint; returning to the tab is early
+     * enough to hide that.
+     *
+     * Nothing is hooked where there is no DOM, so a client outside a browser needs
+     * no option. Setting it makes requests the only thing that says this session is
+     * in use — including to the identity provider, which ends a session nothing
+     * has minted from for long enough. An application whose users read more than
+     * they click should leave it alone.
+     * @default false
      */
-    keyType?: BaseKeyType;
+    disableBrowserActivity?: boolean;
     /**
-     * Idle timeout configuration.
-     * @default after 10 minutes, invalidates the identity
+     * Where the identity provider is, as two values rather than one.
+     *
+     * A ceremony is rendered at a URL and delegations are minted by a canister,
+     * and they are not the same address: a custom domain can front the mainnet
+     * canister, and a local deployment changes both. Nothing is derived from the
+     * URL — the origin of one is not a promise about which canister answers
+     * there — so a deployment is named by both or by neither. Omit the option and
+     * both are mainnet's.
      */
-    idleOptions?: IdleOptions;
+    identityProvider?: {
+        /** The authorize URL a ceremony is rendered at. */
+        authorizeUrl: string | URL;
+        /** The canister that mints and revokes this application's delegations. */
+        canisterId: Principal | string;
+    };
     /**
-     * Identity provider URL.
-     * @default "https://id.ai/authorize"
+     * Options for the agent that makes the mint and revoke calls.
+     *
+     * `identity` is not among them: the agent signs as the session, which is what
+     * those calls rest on.
      */
-    identityProvider?: string | URL;
+    agentOptions?: Omit<HttpAgentOptions, 'identity'>;
     /**
      * Derivation origin for the identity provider.
      * @see https://github.com/dfinity/internet-identity/blob/main/docs/internet-identity-spec.adoc
@@ -76,38 +108,103 @@ export interface AuthClientCreateOptions {
      * @see https://github.com/dfinity/wg-identity-authentication/blob/main/topics/icrc_167_browser_url_transport.md
      */
     transport?: 'window' | 'redirect';
+    /**
+     * Whether Internet Identity may answer without user interaction.
+     *
+     * - `'login'` (the effect of omitting it): run a normal sign-in ceremony.
+     * - `'none'`: Internet Identity answers from a session it already holds for
+     *   this app and returns without rendering anything, or fails with an
+     *   `interaction_required` error if it cannot. Pair with {@link hint} to name
+     *   which account to re-issue for. Use it on a page load where the state names
+     *   an account this origin has no credentials for — a sibling subdomain signed
+     *   in — so this origin acquires its own without a ceremony.
+     *
+     * Sent as a `prompt` query param on the authorize URL. An Internet Identity
+     * extension inspired by OpenID Connect's `prompt`, and not part of any ICRC
+     * standard — which is why it travels on the URL rather than in the request.
+     */
+    prompt?: 'none' | 'login';
+    /**
+     * The account to re-issue for, which is the principal the state names.
+     *
+     * Sent as text in a `hint` query param on the authorize URL; Internet Identity
+     * uses it to pick which session a {@link prompt} `'none'` request resolves to
+     * when the user has more than one for this app. Inspired by OpenID Connect's
+     * `login_hint`.
+     */
+    hint?: Principal;
+    /**
+     * Whether Internet Identity may keep this sign-in so that a later
+     * {@link prompt} `'none'` request can be answered from it.
+     *
+     * Defaults to what {@link AuthClientCreateOptions.stateStorage} says, which is
+     * `true` only for {@link CookieStateStorage}: an application declares this
+     * intent by choosing a store whose record reaches its siblings, and making it
+     * say so a second time would be noise. Set it here for a cross-origin
+     * arrangement that is not sibling subdomains, or to force it off for siblings
+     * that should each sign in properly.
+     *
+     * Off means the provider keeps no session for this app on this device, so
+     * there is nothing for a silent request to find. It says nothing about how
+     * long a session lasts: {@link AuthClientSignInOptions.maxTimeToIdle} applies
+     * either way.
+     *
+     * Sent as a `resumable` query param on the authorize URL, for the same reason
+     * {@link prompt} is: the URL is assembled once, here.
+     */
+    resumable?: boolean;
+}
+/**
+ * Options for creating an {@link AuthClient}.
+ *
+ * At most one one-click sign-in entry point may be set: `openIdProvider` for a
+ * hardcoded provider, or `ssoDomain` for an organization's own SSO.
+ */
+export type AuthClientCreateOptions = AuthClientBaseOptions & ({
     /**
      * OpenID provider for one-click sign-in. When set, the identity provider
      * URL includes an `openid` search param so the user authenticates via
      * the chosen provider (e.g. Google) instead of seeing Internet Identity directly.
      */
     openIdProvider?: OpenIdProvider;
-}
-export interface IdleOptions extends IdleManagerOptions {
-    /**
-     * Disables idle functionality entirely.
-     * @default false
-     */
-    disableIdle?: boolean;
+    ssoDomain?: never;
+} | {
+    openIdProvider?: never;
     /**
-     * Disables the default idle callback (sign-out & reload).
-     * @default false
+     * Organization domain for one-click SSO sign-in, e.g. `'dfinity.org'`.
+     * When set, the identity provider URL includes an `sso` search param so
+     * the user authenticates via that organization's own provider.
+     *
+     * A value that is not a domain with an optional port throws. Use
+     * {@link isValidSsoDomain} to check a domain the user typed.
      */
-    disableDefaultIdleCallback?: boolean;
-}
+    ssoDomain?: string;
+});
 /**
  * Options for {@link AuthClient.signIn}.
  */
 export interface AuthClientSignInOptions {
     /**
-     * Maximum lifetime of the delegation in nanoseconds.
-     * @default 8 hours
+     * The longest the session may last, in nanoseconds.
+     * @default the identity provider's, currently 30 days
      */
     maxTimeToLive?: bigint;
     /**
-     * Restrict the delegation to specific canisters.
+     * How long a signed-in user may be idle before the sign-in ends, in nanoseconds.
+     * @default the identity provider's, currently 7 days
+     */
+    maxTimeToIdle?: bigint;
+    /**
+     * Where to go once the sign-in completes, ignored unless it is a same-origin
+     * `http(s)` target.
+     *
+     * For the flow that leaves the page: a redirect sign-in comes back to whatever
+     * URL the ceremony was started from, which is rarely where the user was. It is
+     * journaled, so it survives the round trip, and the navigation replaces the
+     * current history entry rather than adding one — the sign-in page and the
+     * redirect chain are not somewhere a back button should return to.
      */
-    targets?: Principal[];
+    returnTo?: string;
 }
 export interface SignedAttributes {
     data: Uint8Array;
@@ -123,9 +220,70 @@ export interface SignedAttributes {
  *   ? await authClient.getIdentity()
  *   : await authClient.signIn();
  */
+/**
+ * Who is signed in for this origin, and until when.
+ *
+ * `principal` and `expiresAtMs` are present in every case where a record
+ * exists, so an application can name the account and count down to the end of a
+ * sign-in without reading the store itself.
+ */
+export type SessionStatus = {
+    state: 'signed-in';
+    principal: Principal;
+    expiresAtMs: number;
+}
+/**
+ * Someone is signed in on this domain, but this origin holds no credential
+ * for them, so it cannot act yet. Acquire one silently, or ask the user.
+ */
+ | {
+    state: 'signed-in-elsewhere';
+    principal: Principal;
+    expiresAtMs: number;
+} | {
+    state: 'expired';
+    principal: Principal;
+    expiresAtMs: number;
+} | {
+    state: 'signed-out';
+};
+/**
+ * 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 declare class SessionNotHeldError extends Error {
+    constructor(message?: string);
+}
+/**
+ * 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();
+ *
+ * const identity = authClient.isAuthenticated()
+ *   ? 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 declare class SupersededError extends Error {
+    constructor(message?: string);
+}
 export declare class AuthClient {
     #private;
-    idleManager: IdleManager | undefined;
     constructor(options?: AuthClientCreateOptions);
     /**
      * Returns the current identity, restoring a previous session if available.
@@ -136,21 +294,59 @@ export declare class AuthClient {
      */
     isAuthenticated(): boolean;
     /**
-     * Opens the identity provider, requests a delegation, and returns the authenticated identity.
+     * 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(): Principal | undefined;
+    /**
+     * Who is signed in for this origin right now.
+     *
+     * Synchronous, so a page can render on it without opening a store.
+     */
+    getStatus(): SessionStatus;
+    /**
+     * Watches who is signed in here, and returns a function that stops watching.
      *
-     * @param options - Sign-in options.
-     * @param options.maxTimeToLive - Maximum lifetime of the delegation in nanoseconds.
-     * @param options.targets - Restrict the delegation to specific canisters.
-     * @returns The authenticated identity.
-     * @throws When authentication fails.
+     * `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.
      *
-     * @example
-     * try {
-     *   const identity = await authClient.signIn();
-     * } catch (error) {
-     *   console.error('Sign-in failed:', error);
-     * }
+     * 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: () => void): () => void;
+    /**
+     * 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(): void;
     signIn(options?: AuthClientSignInOptions): Promise<Identity>;
     /**
      * Requests signed identity attributes from the identity provider.
@@ -244,6 +440,27 @@ export declare class AuthClient {
  */
 export declare function scopedKeys<P extends keyof typeof OPENID_PROVIDER_URLS, K extends string = (typeof DEFAULT_OPENID_SCOPE_KEYS)[number]>(params: {
     openIdProvider: P;
+    ssoDomain?: never;
     keys?: readonly K[];
 }): `openid:${(typeof OPENID_PROVIDER_URLS)[P]}:${K}`[];
+/**
+ * Scopes attribute keys to an organization's SSO.
+ *
+ * When using one-click SSO sign-in, attributes can be scoped to the same
+ * organization so the user grants access in a single step.
+ *
+ * @param params.ssoDomain - The organization domain the keys should be scoped to.
+ * @param params.keys - The attribute keys to scope. Defaults to `['name', 'email']`;
+ *   `verified_email` is not available for an organization SSO.
+ * @returns The scoped attribute keys as `sso:<domain>:<key>`.
+ *
+ * @example
+ * scopedKeys({ ssoDomain: 'dfinity.org', keys: ['email'] });
+ * // ['sso:dfinity.org:email']
+ */
+export declare function scopedKeys<D extends string, K extends string = (typeof DEFAULT_SSO_SCOPE_KEYS)[number]>(params: {
+    ssoDomain: D;
+    openIdProvider?: never;
+    keys?: readonly K[];
+}): `sso:${Lowercase<D>}:${K}`[];
 export {};