@icp-sdk/auth 10.0.2 → 11.1.0

package/README.md

@@ -7,146 +7,32 @@ Authentication library for Internet Computer web apps.
 
 > Still using `@dfinity/auth-client`? Migrate to [`@icp-sdk/auth`](https://js.icp.build/auth/latest/upgrading/v4)!
 
----
-
 ## Installation
 
-You can install the `@icp-sdk/auth` package with your package manager of choice:
-
-### npm
-
-```shell
-npm install @icp-sdk/auth
-```
-
-### pnpm
-
-```shell
-pnpm add @icp-sdk/auth
-```
-
-### yarn
-
 ```shell
-yarn add @icp-sdk/auth
+npm install @icp-sdk/auth @icp-sdk/core
 ```
 
-> Note: this package is only meant to be used in **browser** environments.
-
-## Usage Example
+This package is only meant to be used in **browser** environments.
 
-Here's a simple example of how to use the `@icp-sdk/auth` package to authenticate a user with Internet Identity on an Internet Computer web app:
+## Usage
 
 ```typescript
 import { AuthClient } from '@icp-sdk/auth/client';
 
 const authClient = new AuthClient();
 
-// restore an existing session if there is one, otherwise sign in
-let identity;
-try {
-  identity = authClient.isAuthenticated()
-    ? await authClient.getIdentity()
-    : await authClient.signIn();
-} catch (error) {
-  console.error('Sign-in failed:', error);
-  throw error;
-}
+await authClient.signIn();
+const identity = await authClient.getIdentity();
+console.log('Signed in as', identity.getPrincipal().toText());
 
-console.log('Identity:', identity.getPrincipal().toString());
-
-// later, to end the session
 await authClient.signOut();
 ```
 
-### One-Click OpenID Sign-In
-
-Skip the Internet Identity authentication method screen and offer sign-in options like Google directly in your app:
-
-```typescript
-const authClient = new AuthClient({
-  openIdProvider: 'google', // or 'apple' or 'microsoft'
-});
-```
-
-### Requesting Identity Attributes
-
-Internet Identity can provide signed identity attributes (e.g., email) alongside authentication. Your backend canister initiates the flow by issuing a nonce tied to the action — this way, even if an attribute bundle is intercepted, it can't be replayed or used for a different action.
-
-Here's a registration flow where the backend needs the user's email:
-
-```typescript
-import { AuthClient } from '@icp-sdk/auth/client';
-import { AttributesIdentity } from '@icp-sdk/core/identity';
-import { HttpAgent, Actor } from '@icp-sdk/core/agent';
-import { Principal } from '@icp-sdk/core/principal';
-
-const authClient = new AuthClient();
-
-// the backend issues a nonce scoped to registration —
-// this starts the action and binds the upcoming attributes to it
-const anonymousAgent = await HttpAgent.create();
-const backend = Actor.createActor(backendIdl, { agent: anonymousAgent, canisterId });
-const nonce: Uint8Array = await backend.registerBegin();
-
-// sign-in and attribute request happen in parallel — the user sees a single II interaction
-try {
-  const signInPromise = authClient.signIn();
-  const attributesPromise = authClient.requestAttributes({ keys: ['email'], nonce });
-
-  const identity = await signInPromise;
-  const { data, signature } = await attributesPromise;
-
-  // wrap the identity so the signed attributes are included in the canister call
-  const identityWithAttributes = new AttributesIdentity({
-    inner: identity,
-    attributes: { data, signature },
-    signer: { canisterId: Principal.fromText('rdmx6-jaaaa-aaaaa-aaadq-cai') }, // Internet Identity canister ID
-  });
-  const agent = await HttpAgent.create({ identity: identityWithAttributes });
-  const app = Actor.createActor(appIdl, { agent, canisterId });
-
-  // the backend verifies the nonce, origin, and timestamp, then extracts the email
-  await app.registerFinish();
-} catch (error) {
-  console.error('Registration failed:', error);
-}
-```
-
-The signed attribute bundle includes implicit fields that your backend canister should verify:
-
-- **`implicit:nonce`** — ties the attributes to a specific canister-initiated action, preventing replay and cross-action reuse. Must originate from the backend, not the frontend.
-- **`implicit:origin`** — the requesting origin, verified by the canister to prevent a malicious dapp from forwarding attribute bundles to your backend.
-- **`implicit:issued_at_timestamp_ns`** — issuance timestamp, allowing the canister to reject stale attributes even if the nonce hasn't expired yet.
-
-> Attributes can also be requested after sign-in — for example, when a user later triggers an action like linking an email. The flow is the same: the backend issues a nonce for that action, the frontend calls `requestAttributes`, and the backend verifies the result.
-
-#### OpenID-Scoped Attributes
-
-When using one-click sign-in, attributes can be scoped to the OpenID provider. Scoped attributes have implicit consent — the user authenticates and shares attributes in a single step without an additional prompt:
-
-```typescript
-import { AuthClient, scopedKeys } from '@icp-sdk/auth/client';
-
-const authClient = new AuthClient({
-  openIdProvider: 'google',
-});
-
-const nonce: Uint8Array = await backend.registerBegin();
-const signInPromise = authClient.signIn();
-// requests name, email, and verified_email from the
-// Google account linked to the user's Internet Identity
-const attributesPromise = authClient.requestAttributes({
-  keys: scopedKeys({ openIdProvider: 'google' }),
-  nonce,
-});
-
-await signInPromise;
-const { data, signature } = await attributesPromise;
-// ... wrap with AttributesIdentity and complete the action as above
-```
+## Documentation
 
-Additional documentation can be found [here](https://js.icp.build/auth/latest/).
+- [Guides](https://docs.internetcomputer.org/guides/authentication/internet-identity/): project setup, identity attributes, one-click sign-in, enterprise SSO, and shared sessions across subdomains.
+- [API reference and upgrade guides](https://js.icp.build/auth/latest/).
 
 ## Contributing
 

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

@@ -1,6 +1,8 @@
 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 NotificationConsentStatus } from './notification-consent.js';
+import { type SsoStatus } from './sso-status.js';
 import { type StateStorage } from './state-storage.js';
 export type OpenIdProvider = 'google' | 'apple' | 'microsoft';
 export declare const OPENID_PROVIDER_URLS: {
@@ -175,8 +177,17 @@ export type AuthClientCreateOptions = AuthClientBaseOptions & ({
      * 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.
+     * The value is trimmed, lowercased and IDNA-encoded, and has to be a
+     * domain and nothing else: no scheme, port, path, query, fragment or
+     * userinfo. A loopback host (`localhost`, `127.0.0.1`, or a name under
+     * `.localhost`) is accepted too, with a port, for a local mock provider.
+     *
+     * The client checks the domain with Internet Identity as soon as it is
+     * built, and {@link AuthClient.getSsoStatus} reports the answer. A value
+     * that is not a domain is reported as `invalid`, with the reason, rather
+     * than thrown, so a
+     * client can be built from whatever the user typed; a sign-in with it
+     * opens Internet Identity, which explains the error on its own screen.
      */
     ssoDomain?: string;
 });
@@ -322,29 +333,65 @@ export declare class AuthClient {
      */
     getStatus(): SessionStatus;
     /**
-     * Watches who is signed in here, and returns a function that stops watching.
+     * Whether the organization domain this client was built with can be signed
+     * in with, or `undefined` for a client built without `ssoDomain`.
+     *
+     * Synchronous, and the same object until the answer changes, like
+     * {@link getStatus}; {@link subscribe} says when to read it again. A client
+     * built with `ssoDomain` starts checking as soon as it is built: it asks
+     * Internet Identity to resolve the domain, then reads the result
+     * until it is final, so `checking` lasts until Internet Identity answers.
+     * Building the client also warms Internet Identity's cache for the domain, so
+     * a sign-in that follows starts without waiting on the fetch.
+     *
+     * {@link signIn} proceeds in every state: Internet Identity resolves the
+     * domain itself during the sign-in, and explains a failure, a value that is
+     * not a domain included, on its own screen.
+     *
+     * @example
+     * const client = new AuthClient({ ssoDomain: input.value });
+     * client.subscribe(() => render(client.getSsoStatus()));
+     * render(client.getSsoStatus());
+     */
+    getSsoStatus(): SsoStatus | undefined;
+    /**
+     * Checks the organization domain again, for a "Try again" button.
+     *
+     * The status goes back to `checking` and then to the new answer. Calling it
+     * while an `unavailable` answer's `retryAfter` is still in the future is
+     * harmless: Internet Identity does not fetch again before then, so the answer
+     * comes back the same at once. Nothing re-checks on its own once `retryAfter`
+     * passes. Does nothing for an `invalid` domain, which no retry can fix, or for
+     * a client built without `ssoDomain`.
+     */
+    refreshSsoStatus(): void;
+    /**
+     * Watches who is signed in here, and the SSO status of a client built with
+     * `ssoDomain`, 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.
+     * `getStatus()`, `getSsoStatus()` and the predicates beside them 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. The SSO status changes when
+     * Internet Identity answers. This is how both 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()`.
+     * Fired once the new answer is readable, so a listener sees what it was told
+     * about. It says that something changed and not what: a listener reads the
+     * answer it wants, `getStatus()` or `getSsoStatus()`.
      *
      * 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.
+     * @param listener - Called after the record or the SSO status 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.
+     * subscription, the refresh the identity has scheduled, and an SSO domain
+     * check still in progress. Call it when discarding a client, so nothing it
+     * registered outlives it.
      */
     dispose(): void;
     signIn(options?: AuthClientSignInOptions): Promise<Identity>;
@@ -376,6 +423,50 @@ export declare class AuthClient {
         keys: string[];
         nonce: () => Promise<Uint8Array>;
     }): Promise<SignedAttributes>;
+    /**
+     * Asks the user whether this application may notify them.
+     *
+     * Opens the identity provider the way a sign-in does, because consent is the
+     * user's answer and nothing else can stand in for it. Where they agree, the
+     * browser they answered on is registered for delivery.
+     *
+     * A refusal is an answer rather than a failure: it returns `granted: false`,
+     * and an application renders that. Calling it again where consent is already
+     * held returns what is recorded without asking a second time.
+     *
+     * @returns Whether this application may notify the user.
+     * @throws {InteractionRequiredError} Where the client was built with
+     *   `prompt: 'none'`, which no consent ceremony can be run under.
+     * @throws {NotificationsUnsupportedError} Where this identity provider does
+     *   not send notifications at all.
+     * @example
+     * const { granted } = await authClient.requestNotificationConsent();
+     */
+    requestNotificationConsent(): Promise<NotificationConsentStatus>;
+    /**
+     * Withdraws this application's consent to notify the user.
+     *
+     * A canister call made as the session, so it needs no ceremony and opens
+     * nothing: the user already decided, and this records that they changed their
+     * mind. Idempotent — consent that is already withdrawn is not an error.
+     *
+     * @throws {SessionGoneError} Where this origin holds no live session.
+     */
+    revokeNotificationConsent(): Promise<void>;
+    /**
+     * Whether this application may notify the signed-in user.
+     *
+     * What a notifications control is painted from. A query, so the answer is
+     * uncertified, and it reports the consent alone: whether a notification would
+     * reach the user also depends on the device they hold, which this does not
+     * speak for.
+     *
+     * @returns Whether this application may notify the user.
+     * @throws {SessionGoneError} Where this origin holds no live session.
+     * @example
+     * const { granted } = await authClient.getNotificationConsentStatus();
+     */
+    getNotificationConsentStatus(): Promise<NotificationConsentStatus>;
     /**
      * Runs and journals a piece of your own async work so its result stays stable
      * across the `'redirect'` flow.

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

@@ -3,16 +3,21 @@ 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 { AccountMismatchError, chainAuthorisesKey } from './app-delegation-source.js';
+import { AccountMismatchError, chainAuthorisesKey, SessionGoneError, } 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 { NotificationConsent, 
+// Aliased: the method below is this library's name for the operation, and this
+// is the request it sends.
+requestNotificationConsent as sendConsentRequest, } from './notification-consent.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 { createSsoDomainService, SsoStatusChecker } from './sso-status.js';
 import { LocalStateStorage } from './state-storage.js';
 /**
  * The lock one signer interaction at a time holds.
@@ -111,6 +116,8 @@ export class AuthClient {
     // interaction rather than two.
     #interactions = 0;
     #channelLock;
+    // Set only for a client built with `ssoDomain`.
+    #sso;
     constructor(options = {}) {
         this.#options = options;
         this.#credentialStorage = options.credentialStorage ?? new IdbCredentialStorage();
@@ -182,12 +189,26 @@ export class AuthClient {
             identityProviderUrl.searchParams.set('openid', OPENID_PROVIDER_URLS[options.openIdProvider]);
         }
         if (options.ssoDomain !== undefined) {
-            identityProviderUrl.searchParams.set('sso', normalizeSsoDomain(options.ssoDomain));
+            let domain;
+            try {
+                domain = normalizeSsoDomain(options.ssoDomain);
+            }
+            catch (error) {
+                domain = { invalid: error instanceof Error ? error.message : String(error) };
+            }
+            // A value that is not a domain goes to Internet Identity as typed, which
+            // explains it on its own screen.
+            identityProviderUrl.searchParams.set('sso', typeof domain === 'string' ? domain : options.ssoDomain.trim());
             // 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());
             }
+            const canisterId = this.#canisterId;
+            this.#sso = new SsoStatusChecker(domain, () => createSsoDomainService({ canisterId, agentOptions: options.agentOptions }), () => {
+                for (const listener of [...this.#listeners])
+                    listener();
+            });
         }
         // `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
@@ -321,6 +342,43 @@ export class AuthClient {
         }
         return this.#status;
     }
+    /**
+     * Whether the organization domain this client was built with can be signed
+     * in with, or `undefined` for a client built without `ssoDomain`.
+     *
+     * Synchronous, and the same object until the answer changes, like
+     * {@link getStatus}; {@link subscribe} says when to read it again. A client
+     * built with `ssoDomain` starts checking as soon as it is built: it asks
+     * Internet Identity to resolve the domain, then reads the result
+     * until it is final, so `checking` lasts until Internet Identity answers.
+     * Building the client also warms Internet Identity's cache for the domain, so
+     * a sign-in that follows starts without waiting on the fetch.
+     *
+     * {@link signIn} proceeds in every state: Internet Identity resolves the
+     * domain itself during the sign-in, and explains a failure, a value that is
+     * not a domain included, on its own screen.
+     *
+     * @example
+     * const client = new AuthClient({ ssoDomain: input.value });
+     * client.subscribe(() => render(client.getSsoStatus()));
+     * render(client.getSsoStatus());
+     */
+    getSsoStatus() {
+        return this.#sso?.status;
+    }
+    /**
+     * Checks the organization domain again, for a "Try again" button.
+     *
+     * The status goes back to `checking` and then to the new answer. Calling it
+     * while an `unavailable` answer's `retryAfter` is still in the future is
+     * harmless: Internet Identity does not fetch again before then, so the answer
+     * comes back the same at once. Nothing re-checks on its own once `retryAfter`
+     * passes. Does nothing for an `invalid` domain, which no retry can fix, or for
+     * a client built without `ssoDomain`.
+     */
+    refreshSsoStatus() {
+        this.#sso?.refresh();
+    }
     /** Reads the record and builds the answer `getStatus` hands out. */
     #readStatus() {
         const record = this.#stateStorage.get(this.#slots.state);
@@ -336,22 +394,24 @@ export class AuthClient {
             : { state: 'signed-in-elsewhere', principal, expiresAtMs };
     }
     /**
-     * Watches who is signed in here, and returns a function that stops watching.
+     * Watches who is signed in here, and the SSO status of a client built with
+     * `ssoDomain`, 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.
+     * `getStatus()`, `getSsoStatus()` and the predicates beside them 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. The SSO status changes when
+     * Internet Identity answers. This is how both 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()`.
+     * Fired once the new answer is readable, so a listener sees what it was told
+     * about. It says that something changed and not what: a listener reads the
+     * answer it wants, `getStatus()` or `getSsoStatus()`.
      *
      * 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.
+     * @param listener - Called after the record or the SSO status changes.
      * @returns A function that unregisters it.
      */
     subscribe(listener) {
@@ -365,10 +425,12 @@ export class AuthClient {
     }
     /**
      * 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.
+     * subscription, the refresh the identity has scheduled, and an SSO domain
+     * check still in progress. Call it when discarding a client, so nothing it
+     * registered outlives it.
      */
     dispose() {
+        this.#sso?.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.
@@ -764,6 +826,92 @@ export class AuthClient {
             throw new Error('Invalid response: data or signature is not valid base64', { cause });
         }
     }
+    /**
+     * Asks the user whether this application may notify them.
+     *
+     * Opens the identity provider the way a sign-in does, because consent is the
+     * user's answer and nothing else can stand in for it. Where they agree, the
+     * browser they answered on is registered for delivery.
+     *
+     * A refusal is an answer rather than a failure: it returns `granted: false`,
+     * and an application renders that. Calling it again where consent is already
+     * held returns what is recorded without asking a second time.
+     *
+     * @returns Whether this application may notify the user.
+     * @throws {InteractionRequiredError} Where the client was built with
+     *   `prompt: 'none'`, which no consent ceremony can be run under.
+     * @throws {NotificationsUnsupportedError} Where this identity provider does
+     *   not send notifications at all.
+     * @example
+     * const { granted } = await authClient.requestNotificationConsent();
+     */
+    async requestNotificationConsent() {
+        // The channel lock and not the sign-in lock, for the reason `requestAttributes`
+        // takes it: this opens the signer channel, which an origin has one of, and
+        // writes nothing anyone else reads.
+        this.#beginInteraction();
+        try {
+            const response = sendConsentRequest(this.#signer, this.#options.derivationOrigin?.toString());
+            this.#takeChannelLock();
+            return await response;
+        }
+        finally {
+            this.#endInteraction();
+        }
+    }
+    /**
+     * Withdraws this application's consent to notify the user.
+     *
+     * A canister call made as the session, so it needs no ceremony and opens
+     * nothing: the user already decided, and this records that they changed their
+     * mind. Idempotent — consent that is already withdrawn is not an error.
+     *
+     * @throws {SessionGoneError} Where this origin holds no live session.
+     */
+    async revokeNotificationConsent() {
+        await (await this.#consent()).revoke();
+    }
+    /**
+     * Whether this application may notify the signed-in user.
+     *
+     * What a notifications control is painted from. A query, so the answer is
+     * uncertified, and it reports the consent alone: whether a notification would
+     * reach the user also depends on the device they hold, which this does not
+     * speak for.
+     *
+     * @returns Whether this application may notify the user.
+     * @throws {SessionGoneError} Where this origin holds no live session.
+     * @example
+     * const { granted } = await authClient.getNotificationConsentStatus();
+     */
+    async getNotificationConsentStatus() {
+        return (await this.#consent()).status();
+    }
+    /**
+     * Builds the consent calls from the session this origin holds.
+     *
+     * Read at the call rather than kept, so a session replaced since the last call
+     * is not the one spoken for, and a sign-out between them is reported as what it
+     * is instead of answered from a stale actor.
+     */
+    async #consent() {
+        // Wait for the constructor's session restore, which is what puts the
+        // credential these calls are made with where this can read it.
+        await this.#init();
+        // The chain is checked and not just its presence: `#init()` resolves once, so a
+        // session that ran out while the page stayed open is still in the slot, and a
+        // call made with it would fail as a rejected signature rather than as what it is.
+        const session = await this.#credentialStorage.get(this.#slots.session);
+        if (session === null || session.chain === undefined || !isDelegationValid(session.chain)) {
+            throw new SessionGoneError();
+        }
+        return NotificationConsent.create({
+            sessionKey: session.identity,
+            sessionChain: session.chain,
+            canisterId: this.#canisterId,
+            agentOptions: this.#options.agentOptions,
+        });
+    }
     memoize(produce) {
         if (this.#urlTransport) {
             return this.#urlTransport.memoize(produce);