@icp-sdk/auth 10.0.2 → 11.1.0

package/src/client/auth-client.ts

@@ -13,17 +13,29 @@ import {
 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 { type HeldLock, stealLock, stealMintLock } from './app-lock.js';
 import { fromBase64, toBase64 } from './base64.js';
 import type { Credential, CredentialStorage } from './credential-storage.js';
 import { watchActivity, watchForeground } from './foreground-refresh.js';
 import { IdbCredentialStorage } from './idb-credential-storage.js';
+import {
+  NotificationConsent,
+  type NotificationConsentStatus,
+  // 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 { type Slots, slotsFor } from './slots.js';
 import { normalizeSsoDomain } from './sso.js';
+import { createSsoDomainService, type SsoStatus, SsoStatusChecker } from './sso-status.js';
 import { LocalStateStorage, type SessionState, type StateStorage } from './state-storage.js';
 
 /**
@@ -235,8 +247,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;
       }
@@ -384,6 +405,8 @@ export class AuthClient {
   // interaction rather than two.
   #interactions = 0;
   #channelLock: HeldLock | undefined;
+  // Set only for a client built with `ssoDomain`.
+  readonly #sso: SsoStatusChecker | undefined;
 
   constructor(options: AuthClientCreateOptions = {}) {
     this.#options = options;
@@ -467,7 +490,18 @@ 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: string | { invalid: string };
+      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) {
@@ -476,6 +510,14 @@ export class AuthClient {
           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
@@ -621,6 +663,45 @@ 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(): SsoStatus | undefined {
+    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(): void {
+    this.#sso?.refresh();
+  }
+
   /** Reads the record and builds the answer `getStatus` hands out. */
   #readStatus(): SessionStatus {
     const record = this.#stateStorage.get(this.#slots.state);
@@ -637,22 +718,24 @@ export class AuthClient {
   }
 
   /**
-   * 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: () => void): () => void {
@@ -667,10 +750,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(): void {
+    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.
@@ -1116,6 +1201,97 @@ export class AuthClient {
     }
   }
 
+  /**
+   * 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(): Promise<NotificationConsentStatus> {
+    // 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(): Promise<void> {
+    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(): Promise<NotificationConsentStatus> {
+    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(): Promise<NotificationConsent> {
+    // 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,
+    });
+  }
+
   /**
    * Runs and journals a piece of your own async work so its result stays stable
    * across the `'redirect'` flow.

package/src/client/index.ts

@@ -14,6 +14,14 @@ export { watchActivity, watchForeground } from './foreground-refresh.js';
 export { IdbCredentialStorage } from './idb-credential-storage.js';
 export { LocalCredentialStorage } from './local-credential-storage.js';
 export { MemoryCredentialStorage } from './memory-credential-storage.js';
+export {
+  NotificationConsent,
+  type NotificationConsentOptions,
+  type NotificationConsentService,
+  type NotificationConsentStatus,
+  NotificationsUnsupportedError,
+  requestNotificationConsent,
+} from './notification-consent.js';
 export { InteractionRequiredError, requestSessionDelegation } from './session-delegation.js';
 export { SessionIdentity, type SessionIdentityOptions } from './session-identity.js';
 export { SessionMinter, type SessionMinterOptions } from './session-minter.js';
@@ -21,7 +29,7 @@ export {
   DEFAULT_SHARED_MEMORY_NAME,
   SharedMemoryCredentialStorage,
 } from './shared-memory-credential-storage.js';
-export { isValidSsoDomain } from './sso.js';
+export type { SsoStatus } from './sso-status.js';
 export {
   LocalStateStorage,
   MemoryStateStorage,

package/src/client/notification-consent.ts

@@ -0,0 +1,214 @@
+import { Actor, HttpAgent, type HttpAgentOptions, type SignIdentity } from '@icp-sdk/core/agent';
+import type { IDL } from '@icp-sdk/core/candid';
+import { type DelegationChain, DelegationIdentity } from '@icp-sdk/core/identity';
+import type { Principal } from '@icp-sdk/core/principal';
+import type { Signer } from '@icp-sdk/signer';
+import { SessionGoneError } from './app-delegation-source.js';
+import { InteractionRequiredError } from './session-delegation.js';
+import { assertChainReaches } from './session-minter.js';
+
+/**
+ * The method Internet Identity answers with the user's decision about being
+ * notified. Named for its provider because a JSON-RPC method travels over a
+ * transport shared with other signers, unlike a canister method.
+ */
+const NOTIFICATION_CONSENT_METHOD = 'ii_notification_consent';
+
+/** The code Internet Identity denies a `prompt: 'none'` request with. */
+const INTERACTION_REQUIRED_CODE = 3002;
+
+/** JSON-RPC's own code for a method the receiver does not implement. */
+const METHOD_NOT_FOUND_CODE = -32601;
+
+/**
+ * Whether the user has allowed this application to notify them.
+ *
+ * A record rather than a bare boolean, mirroring what the canister answers: a
+ * second fact about the decision can then be reported without a breaking change
+ * to anything that already reads `granted`.
+ */
+export interface NotificationConsentStatus {
+  granted: boolean;
+}
+
+/**
+ * Thrown where the identity provider does not send notifications at all.
+ *
+ * Its own error because its remedy is its own: there is nothing to retry and no
+ * ceremony to run, so an application hides the control rather than reporting a
+ * failure to the user. A deployment either carries the feature or does not.
+ */
+export class NotificationsUnsupportedError extends Error {
+  constructor(message = 'This Internet Identity does not send notifications') {
+    super(message);
+    this.name = 'NotificationsUnsupportedError';
+  }
+}
+
+/**
+ * Asks the user, through the identity provider, whether this application may
+ * notify them, and registers the browser for delivery where they agree.
+ *
+ * A refusal is an answer: it comes back as `granted: false` rather than as an
+ * error, because the user decided and the application has something to render.
+ *
+ * @param signer - The channel to the identity provider.
+ * @param derivationOrigin - The origin the account is derived for, where the
+ *   application signs in under one other than its own.
+ * @returns What the provider recorded, read back rather than reported from the
+ *   screen.
+ * @throws {InteractionRequiredError} Where the request asked not to render.
+ * @throws {NotificationsUnsupportedError} Where the provider does not notify.
+ */
+export async function requestNotificationConsent(
+  signer: Signer,
+  derivationOrigin?: string,
+): Promise<NotificationConsentStatus> {
+  const response = await signer.sendRequest({
+    jsonrpc: '2.0' as const,
+    id: globalThis.crypto.randomUUID(),
+    method: NOTIFICATION_CONSENT_METHOD,
+    // Every member is optional, so an application with nothing to pass sends an
+    // empty object rather than no `params` at all.
+    params: derivationOrigin === undefined ? {} : { icrc95DerivationOrigin: derivationOrigin },
+  });
+
+  if ('error' in response) {
+    if (response.error.code === METHOD_NOT_FOUND_CODE) {
+      throw new NotificationsUnsupportedError(response.error.message);
+    }
+    if (response.error.code === INTERACTION_REQUIRED_CODE) {
+      throw new InteractionRequiredError(response.error.message);
+    }
+    throw new Error(response.error.message);
+  }
+
+  const result = response.result as Record<string, unknown> | undefined;
+  if (typeof result?.granted !== 'boolean') {
+    throw new Error('Invalid response: missing granted');
+  }
+  return { granted: result.granted };
+}
+
+/** What the canister answers either consent call with. */
+type NotificationConsentError = { NoSuchSession: null } | { InternalCanisterError: string };
+type Result<T> = { Ok: T } | { Err: NotificationConsentError };
+
+/** The two Internet Identity methods an application makes about its own consent. */
+export interface NotificationConsentService {
+  app_notification_consent_status(): Promise<Result<{ is_granted: boolean }>>;
+  app_revoke_notification_consent(): Promise<Result<null>>;
+}
+
+/**
+ * Written out for the same reason as the session methods in `session-minter.ts`:
+ * this package carries no Internet Identity declarations.
+ */
+const idlFactory: IDL.InterfaceFactory = ({ IDL }) => {
+  const ConsentError = IDL.Variant({
+    NoSuchSession: IDL.Null,
+    InternalCanisterError: IDL.Text,
+  });
+  const Status = IDL.Record({ is_granted: IDL.Bool });
+  return IDL.Service({
+    app_notification_consent_status: IDL.Func(
+      [],
+      [IDL.Variant({ Ok: Status, Err: ConsentError })],
+      ['query'],
+    ),
+    app_revoke_notification_consent: IDL.Func(
+      [],
+      [IDL.Variant({ Ok: IDL.Null, Err: ConsentError })],
+      [],
+    ),
+  });
+};
+
+/**
+ * Unwraps a canister result, turning the one terminal error into
+ * {@link SessionGoneError} and the other into a plain failure.
+ */
+const unwrap = <T>(result: Result<T>, failed: string): T => {
+  if ('Ok' in result) return result.Ok;
+  if ('NoSuchSession' in result.Err) throw new SessionGoneError();
+  // A candid variant, so interpolating it directly renders "[object Object]" and
+  // throws away the canister's own explanation of what went wrong.
+  const detail = result.Err.InternalCanisterError;
+  throw new Error(`${failed}${detail === '' ? '' : `: ${detail}`}`);
+};
+
+export interface NotificationConsentOptions {
+  /** The key the session chain delegates to. Signs the calls made here. */
+  sessionKey: SignIdentity;
+
+  /** The chain proving those calls come from the session. Restricted to II. */
+  sessionChain: DelegationChain;
+
+  /** The canister these calls go to. */
+  canisterId: Principal;
+
+  /**
+   * Options for the agent making them. `identity` is not among them: the agent
+   * signs as the session, which is what both calls are authorised by.
+   */
+  agentOptions?: Omit<HttpAgentOptions, 'identity'>;
+}
+
+/** Reads and withdraws an application's consent, at the Internet Identity canister. */
+export class NotificationConsent {
+  readonly #service: NotificationConsentService;
+
+  private constructor(service: NotificationConsentService) {
+    this.#service = service;
+  }
+
+  /**
+   * Builds the calls as the session.
+   *
+   * As the session and not as the application: Internet Identity authorises both
+   * methods by the principal the session signs with, which is the one that mints
+   * app delegations rather than any of the ones minted from it.
+   */
+  static async create(options: NotificationConsentOptions): Promise<NotificationConsent> {
+    const { canisterId } = options;
+    assertChainReaches(options.sessionChain, canisterId);
+    const agent = await HttpAgent.create({
+      ...options.agentOptions,
+      // Last, so no agent option can replace the session these calls are made as.
+      identity: DelegationIdentity.fromDelegation(options.sessionKey, options.sessionChain),
+    });
+    return new NotificationConsent(
+      Actor.createActor<NotificationConsentService>(idlFactory, { agent, canisterId }),
+    );
+  }
+
+  /**
+   * Whether this application may notify the signed-in user.
+   *
+   * A query, so the answer is uncertified: it is what a control is painted from,
+   * not something to rest a decision on.
+   */
+  async status(): Promise<NotificationConsentStatus> {
+    const status = unwrap(
+      await this.#service.app_notification_consent_status(),
+      'Internet Identity could not report this notification consent',
+    );
+    return { granted: status.is_granted };
+  }
+
+  /**
+   * Withdraws this application's consent to notify the signed-in user.
+   *
+   * Idempotent at the canister: consent that is already withdrawn is `Ok`, because
+   * the caller wanted it gone and it is gone. What comes back as an error is the
+   * canister failing to write, and it is raised rather than dropped — an
+   * application that told a user it had turned notifications off should be able to
+   * find out that it had not.
+   */
+  async revoke(): Promise<void> {
+    unwrap(
+      await this.#service.app_revoke_notification_consent(),
+      'Internet Identity could not withdraw this notification consent',
+    );
+  }
+}