@icp-sdk/auth 10.0.2 → 11.1.0

package/src/client/sso-status.ts

@@ -0,0 +1,257 @@
+import { Actor, AnonymousIdentity, HttpAgent, type HttpAgentOptions } from '@icp-sdk/core/agent';
+import type { IDL } from '@icp-sdk/core/candid';
+import type { Principal } from '@icp-sdk/core/principal';
+
+/**
+ * Whether the organization domain a client was built with can be signed in with.
+ *
+ * - `checking`: Internet Identity has not answered yet.
+ * - `available`: the domain resolves to a usable SSO configuration. `name` is
+ *   the label the organization publishes, for a "Continue with Acme" button.
+ * - `invalid`: the value is not a domain, so no check is made and a retry
+ *   cannot help. The user has to change what they typed. `reason` names every
+ *   problem with it, to show as is.
+ * - `unavailable`: the domain publishes no usable configuration, or fetching
+ *   it is failing. While `retryAfter` is in the future Internet Identity will
+ *   not fetch again, so a retry before then gets the same answer; without it,
+ *   a retry cannot help. `reason` is Internet Identity's explanation, when it
+ *   gives one, to show as is.
+ */
+export type SsoStatus =
+  | { state: 'checking' }
+  | { state: 'available'; name?: string }
+  | { state: 'invalid'; reason: string }
+  | { state: 'unavailable'; retryAfter?: Date; reason?: string };
+
+type CandidSsoDomainStatus =
+  | { Available: { name: [] | [string] } }
+  | { Pending: null }
+  | { Unavailable: { retry_after: [] | [bigint]; reason: [] | [string] } };
+
+/** The two Internet Identity methods an SSO domain check calls. */
+export interface SsoDomainService {
+  app_sso_domain_check(domain: string): Promise<void>;
+  app_sso_domain_status(domain: string): Promise<CandidSsoDomainStatus>;
+}
+
+/**
+ * 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 Timestamp = IDL.Nat64;
+  const Status = IDL.Variant({
+    Available: IDL.Record({ name: IDL.Opt(IDL.Text) }),
+    Pending: IDL.Null,
+    Unavailable: IDL.Record({ retry_after: IDL.Opt(Timestamp), reason: IDL.Opt(IDL.Text) }),
+  });
+  return IDL.Service({
+    app_sso_domain_check: IDL.Func([IDL.Text], [], []),
+    app_sso_domain_status: IDL.Func([IDL.Text], [Status], ['query']),
+  });
+};
+
+/**
+ * Builds the service an SSO domain check calls, as the anonymous caller: the
+ * check runs before anyone has signed in.
+ */
+export async function createSsoDomainService(options: {
+  canisterId: Principal;
+  agentOptions?: Omit<HttpAgentOptions, 'identity'>;
+}): Promise<SsoDomainService> {
+  const agent = await HttpAgent.create({
+    ...options.agentOptions,
+    // Last, so no agent option can make the check call as someone.
+    identity: new AnonymousIdentity(),
+  });
+  return Actor.createActor<SsoDomainService>(idlFactory, {
+    agent,
+    canisterId: options.canisterId,
+  });
+}
+
+/** The first and the longest wait between two status reads. */
+export const SSO_POLL_MIN_MS = 500;
+export const SSO_POLL_MAX_MS = 2_000;
+
+/**
+ * How long a check may read `Pending` before it is started again. Matches the
+ * age at which Internet Identity treats a fetch as abandoned.
+ */
+export const SSO_RECHECK_AFTER_MS = 120_000;
+
+const CHECKING: SsoStatus = Object.freeze({ state: 'checking' });
+
+const NANOS_PER_MILLI = 1_000_000n;
+
+function fromCandid(status: CandidSsoDomainStatus): SsoStatus | undefined {
+  if ('Available' in status) {
+    const name = status.Available.name[0];
+    return name === undefined ? { state: 'available' } : { state: 'available', name };
+  }
+  if ('Unavailable' in status) {
+    const retryAfterNs = status.Unavailable.retry_after[0];
+    const reason = status.Unavailable.reason[0];
+    return {
+      state: 'unavailable',
+      ...(retryAfterNs !== undefined && {
+        retryAfter: new Date(Number(retryAfterNs / NANOS_PER_MILLI)),
+      }),
+      ...(reason !== undefined && { reason }),
+    };
+  }
+  // Pending: the fetch is still running, which is what `checking` already says.
+  return undefined;
+}
+
+function sameStatus(a: SsoStatus, b: SsoStatus): boolean {
+  switch (a.state) {
+    case 'checking':
+      return b.state === 'checking';
+    case 'available':
+      return b.state === 'available' && a.name === b.name;
+    case 'invalid':
+      return b.state === 'invalid' && a.reason === b.reason;
+    case 'unavailable':
+      return (
+        b.state === 'unavailable' &&
+        a.retryAfter?.getTime() === b.retryAfter?.getTime() &&
+        a.reason === b.reason
+      );
+  }
+}
+
+/**
+ * Asks Internet Identity whether one SSO domain can be signed in with, and holds
+ * the answer.
+ *
+ * One update starts the fetch, then the status is read with a query until it is
+ * final: a query needs no consensus, so polling it is cheap where polling an
+ * update is not. A read that fails is retried at the next interval, so a check
+ * ends only on an answer from Internet Identity, or on {@link dispose}.
+ */
+export class SsoStatusChecker {
+  readonly #domain: string | undefined;
+  readonly #createService: () => Promise<SsoDomainService>;
+  readonly #onChange: () => void;
+  #service: Promise<SsoDomainService> | undefined;
+  #status: SsoStatus;
+  #timer: ReturnType<typeof setTimeout> | undefined;
+  // Bumped by every start and by dispose, so a run that was replaced drops its
+  // late answers instead of overwriting a newer one.
+  #run = 0;
+  #disposed = false;
+
+  /**
+   * @param domain - The normalized domain, or, for a value that is not one, why
+   *   not: `invalid` from the start and never checked.
+   * @param createService - Builds the service on the first call.
+   * @param onChange - Called after the status changes.
+   */
+  constructor(
+    domain: string | { invalid: string },
+    createService: () => Promise<SsoDomainService>,
+    onChange: () => void,
+  ) {
+    this.#domain = typeof domain === 'string' ? domain : undefined;
+    this.#createService = createService;
+    this.#onChange = onChange;
+    this.#status =
+      typeof domain === 'string'
+        ? CHECKING
+        : Object.freeze({ state: 'invalid', reason: domain.invalid });
+    if (typeof domain === 'string') this.#start(0);
+  }
+
+  /** The current answer. The same object until it changes. */
+  get status(): SsoStatus {
+    return this.#status;
+  }
+
+  /** Checks again. Does nothing for an `invalid` domain, or once disposed. */
+  refresh(): void {
+    if (this.#domain === undefined || this.#disposed) return;
+    this.#set(CHECKING);
+    this.#start(0);
+  }
+
+  /** Stops checking. A call already sent is not recalled; its answer is dropped. */
+  dispose(): void {
+    this.#disposed = true;
+    this.#run += 1;
+    clearTimeout(this.#timer);
+    this.#timer = undefined;
+  }
+
+  #start(delayMs: number): void {
+    this.#run += 1;
+    const run = this.#run;
+    clearTimeout(this.#timer);
+    this.#timer = setTimeout(() => {
+      void this.#check(run);
+    }, delayMs);
+  }
+
+  #isCurrent(run: number): boolean {
+    return run === this.#run && !this.#disposed;
+  }
+
+  async #check(run: number): Promise<void> {
+    const domain = this.#domain;
+    if (domain === undefined || !this.#isCurrent(run)) return;
+    const checkedAt = Date.now();
+    try {
+      const service = await this.#serviceFor();
+      if (!this.#isCurrent(run)) return;
+      await service.app_sso_domain_check(domain);
+    } catch {
+      // The reads below still see whatever Internet Identity has, and a check
+      // that never started is started again after `SSO_RECHECK_AFTER_MS`.
+    }
+    await this.#poll(run, domain, checkedAt, SSO_POLL_MIN_MS);
+  }
+
+  async #poll(run: number, domain: string, checkedAt: number, nextDelayMs: number): Promise<void> {
+    if (!this.#isCurrent(run)) return;
+    let answer: SsoStatus | undefined;
+    try {
+      const service = await this.#serviceFor();
+      if (!this.#isCurrent(run)) return;
+      answer = fromCandid(await service.app_sso_domain_status(domain));
+    } catch {
+      answer = undefined;
+    }
+    if (!this.#isCurrent(run)) return;
+    if (answer !== undefined) {
+      this.#set(answer);
+      return;
+    }
+    if (Date.now() - checkedAt >= SSO_RECHECK_AFTER_MS) {
+      this.#timer = setTimeout(() => {
+        void this.#check(run);
+      }, nextDelayMs);
+      return;
+    }
+    this.#timer = setTimeout(() => {
+      void this.#poll(run, domain, checkedAt, Math.min(nextDelayMs * 2, SSO_POLL_MAX_MS));
+    }, nextDelayMs);
+  }
+
+  #serviceFor(): Promise<SsoDomainService> {
+    if (this.#service === undefined) {
+      const created = this.#createService();
+      this.#service = created;
+      // A service that could not be built is built again on the next call.
+      created.catch(() => {
+        if (this.#service === created) this.#service = undefined;
+      });
+    }
+    return this.#service;
+  }
+
+  #set(next: SsoStatus): void {
+    if (sameStatus(this.#status, next)) return;
+    this.#status = next;
+    this.#onChange();
+  }
+}

package/src/client/sso.ts

@@ -1,122 +1,107 @@
 // 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';
+// The identity provider's own limits on a DNS name (idna's strict mode).
+const MAX_DNS_NAME_LENGTH = 253;
+const MAX_DNS_LABEL_LENGTH = 63;
+
+const MAX_QUOTED_LENGTH = 100;
+
+/** `value` for an error message: cut short, and quoted so control characters show escaped. */
+function quote(value: string): string {
+  return JSON.stringify(
+    value.length > MAX_QUOTED_LENGTH ? `${value.slice(0, MAX_QUOTED_LENGTH)}…` : value,
+  );
+}
 
 /**
- * `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.
+ * `localhost`, `127.0.0.1`, or a name under `.localhost` (RFC 6761 reserves the
+ * whole domain for loopback), like the identity provider's own check. IPv6
+ * loopback is not one, there either.
  */
-function isLoopbackHost(host: string): boolean {
-  let url: 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;
+function isLoopbackHost(hostname: string): boolean {
+  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname.endsWith('.localhost');
+}
+
+/** What keeps `hostname` from being a DNS name, by the identity provider's rules. */
+function dnsNameProblems(hostname: string): string[] {
+  const labels = hostname.split('.');
+  const problems: string[] = [];
+  if (labels.length < 2) problems.push('a single label');
+  if (labels.some((label) => label.length === 0)) problems.push('an empty label');
+  if (labels.some((label) => label.length > MAX_DNS_LABEL_LENGTH)) {
+    problems.push(`a label longer than ${MAX_DNS_LABEL_LENGTH} characters`);
   }
-  // A bare `host[:port]` has no path/query/fragment; reject e.g. `localhost/x`.
-  if (url.pathname !== '/' || url.search !== '' || url.hash !== '') {
-    return false;
+  if (labels.some((label) => /[^a-z0-9-]/.test(label))) {
+    problems.push('a character other than a letter, digit, or hyphen');
   }
-  return url.hostname === 'localhost' || url.hostname === '127.0.0.1';
+  if (labels.some((label) => label.startsWith('-') || label.endsWith('-'))) {
+    problems.push('a label starting or ending with a hyphen');
+  }
+  // `--` in the third and fourth places is reserved, except for punycode.
+  if (labels.some((label) => label.slice(2, 4) === '--' && !label.startsWith('xn--'))) {
+    problems.push('a label with "--" in its third and fourth places');
+  }
+  if (hostname.length > MAX_DNS_NAME_LENGTH) {
+    problems.push(`a name longer than ${MAX_DNS_NAME_LENGTH} characters`);
+  }
+  return problems;
+}
+
+function listed(items: string[]): string {
+  return items.length < 2 ? items.join('') : `${items.slice(0, -1).join(', ')} and ${items.at(-1)}`;
 }
 
 /**
  * Normalizes an SSO domain to the authority the identity provider fetches the
- * discovery document from: lowercased, IDNA-encoded, host and optional port.
+ * discovery document from: lowercased and IDNA-encoded. A loopback host may
+ * carry a port, for a local mock provider; any other host may not.
  *
  * @param domain - The organization domain.
  * @returns The normalized authority.
- * @throws When `domain` is not a domain with an optional port.
+ * @throws When `domain` is not a domain, naming every problem with it.
  */
 export function normalizeSsoDomain(domain: string): string {
   const trimmed = domain.trim();
   if (trimmed.length === 0) {
     throw new Error('ssoDomain cannot be empty');
   }
+  const scheme = /^[a-z][a-z0-9+.-]*:\/\//i.exec(trimmed)?.[0];
+  const rest = scheme === undefined ? trimmed : trimmed.slice(scheme.length);
   let url: URL;
   try {
-    url = new URL(`https://${trimmed}`);
+    url = new URL(`https://${rest}`);
   } 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}`);
+    throw new Error(`ssoDomain ${quote(trimmed)} is not a domain`);
   }
-  return authority;
-}
+  const { username, password, pathname, hostname, port, host, href } = url;
+  // `URL` drops an empty or default port such as `:443`, so the typed one is read
+  // from the input itself.
+  const typedAuthority = rest.split(/[/?#]/)[0] ?? '';
+  const typedPort = /:([0-9]*)$/.exec(
+    typedAuthority.slice(typedAuthority.lastIndexOf('@') + 1),
+  )?.[1];
+  const [beforeFragment = ''] = href.split('#');
 
-function publishesSsoConfiguration(value: unknown): boolean {
-  if (typeof value !== 'object' || value === null) {
-    return false;
+  const problems: string[] = [];
+  if (scheme !== undefined) problems.push('a scheme');
+  if (username !== '' || password !== '') problems.push('userinfo');
+  if (pathname !== '/') problems.push('a path');
+  if (beforeFragment.includes('?')) problems.push('a query');
+  if (href.includes('#')) problems.push('a fragment');
+  const loopback = isLoopbackHost(hostname);
+  if (typedPort !== undefined && !loopback) {
+    problems.push('a port, which only loopback hosts may carry');
+  } else if (typedPort !== undefined && (typedPort === '' || typedPort !== port)) {
+    problems.push('an empty or default port');
   }
-  const { client_id, openid_configuration } = value as Record<string, unknown>;
-  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: string, signal: AbortSignal): Promise<boolean> {
-  signal.throwIfAborted();
-
-  let normalized: string;
-  try {
-    normalized = normalizeSsoDomain(domain);
-  } catch {
-    return false;
+  if (trimmed.length > MAX_AUTHORITY_LENGTH) {
+    problems.push(`more than ${MAX_AUTHORITY_LENGTH} characters`);
+  } else if (!loopback) {
+    problems.push(...dnsNameProblems(hostname));
   }
-
-  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;
+  if (problems.length > 0) {
+    throw new Error(`ssoDomain ${quote(trimmed)} has ${listed(problems)}`);
   }
+  return host;
 }