@idp.global/sdk 18.0.1 → 18.2.0

package/ts_relyingparty/classes.idpoidcprovider.ts

@@ -0,0 +1,386 @@
+import * as plugins from './plugins.js';
+import {
+  OidcIntrospectionClient,
+  OidcIntrospectionError,
+} from '../ts_server/classes.oidc-introspection-client.js';
+
+export interface IOidcAuthorizationOptions {
+  state: string;
+  nonce: string;
+  pkceVerifier: string;
+}
+
+export interface IOidcCompletionOptions extends IOidcAuthorizationOptions {
+  /** the callback as the application's own public origin saw it */
+  callbackUrl: URL;
+}
+
+/** One organization the provider reports for the subject; display data, not an authorization grant. */
+export interface IOidcOrganizationClaim {
+  id: string;
+  name: string;
+  slug: string;
+  roles: string[];
+}
+
+export interface IOidcCompletion {
+  subject: string;
+  accessToken: string;
+  refreshToken?: string;
+  /** epoch milliseconds; `0` when the token response named no lifetime */
+  accessTokenExpiresAt: number;
+  email?: string;
+  emailVerified: boolean;
+  displayName?: string;
+  organizations: IOidcOrganizationClaim[];
+}
+
+/**
+ * One live observation of a subject's authority in one organization, as
+ * `POST /oauth/introspect` answers it. An inactive answer names no reason:
+ * revoked token, dead login session, removed membership and disconnected app
+ * are deliberately indistinguishable.
+ */
+export interface IOidcOrganizationObservation {
+  active: boolean;
+  /** the sorted membership role keys; empty when inactive */
+  roles: readonly string[];
+  /** the observation's own `exp` in epoch milliseconds; `0` when inactive */
+  expiresAt: number;
+}
+
+export interface IOidcRefreshedTokens {
+  accessToken: string;
+  /** the rotated refresh token; absent when the provider returned none */
+  refreshToken?: string;
+  /** epoch milliseconds; `0` when the token response named no lifetime */
+  accessTokenExpiresAt: number;
+}
+
+/** Why an observation or a refresh could not be made; never why access was refused. */
+export type TOidcAuthorityFailure = 'unavailable' | 'invalid_response';
+
+/** The provider could not be asked, or did not answer in its own contract. The caller fails closed on it. */
+export class OidcAuthorityUnavailableError extends Error {
+  constructor(
+    public readonly reason: TOidcAuthorityFailure,
+    causeArg?: unknown,
+  ) {
+    super('The identity provider could not be observed', { cause: causeArg });
+    this.name = 'OidcAuthorityUnavailableError';
+  }
+}
+
+/** The provider refused the refresh with `invalid_grant`: the refresh family is revoked, expired or was reused. */
+export class OidcRefreshRefusedError extends Error {
+  constructor(causeArg?: unknown) {
+    super('The identity provider refused the refresh', { cause: causeArg });
+    this.name = 'OidcRefreshRefusedError';
+  }
+}
+
+export type TOidcTokenHint = 'access_token' | 'refresh_token';
+
+export type TOidcCompletionFailureStage = 'token_exchange' | 'token_validation' | 'userinfo';
+
+export class OidcCompletionError extends Error {
+  constructor(
+    public readonly stage: TOidcCompletionFailureStage,
+    causeArg: unknown,
+  ) {
+    super('OIDC completion failed', { cause: causeArg });
+    this.name = 'OidcCompletionError';
+  }
+}
+
+/**
+ * What the session layer needs from the provider. `IdpOidcProvider` is the
+ * implementation; tests bind a double to it, so no test opens a socket.
+ */
+export interface IOidcProvider {
+  /**
+   * The deadline of every provider request, in seconds. The refresh lock that
+   * keeps two replicas from spending one refresh token outlives it.
+   */
+  readonly requestTimeoutSeconds: number;
+  init(): Promise<void>;
+  buildAuthorizationUrl(optionsArg: IOidcAuthorizationOptions): Promise<URL>;
+  completeAuthorization(optionsArg: IOidcCompletionOptions): Promise<IOidcCompletion>;
+  revokeToken(tokenArg: string, hintArg: TOidcTokenHint): Promise<void>;
+  /** Throws `OidcAuthorityUnavailableError` rather than guessing an answer. */
+  introspectOrganization(optionsArg: {
+    accessToken: string;
+    subject: string;
+    organizationId: string;
+  }): Promise<IOidcOrganizationObservation>;
+  /** Throws `OidcRefreshRefusedError` on `invalid_grant`, `OidcAuthorityUnavailableError` for everything else. */
+  refreshTokens(refreshTokenArg: string): Promise<IOidcRefreshedTokens>;
+}
+
+/**
+ * The scopes a relying party asks for. `organizations` and `roles` are what
+ * idp.global reports memberships under.
+ */
+export const IDP_OIDC_DEFAULT_SCOPES = 'openid profile email organizations roles';
+
+export const IDP_OIDC_DEFAULT_REQUEST_TIMEOUT_SECONDS = 10;
+
+export interface IIdpOidcProviderOptions {
+  /** the issuer origin, `https://…`; the introspection client refuses anything else */
+  issuer: URL;
+  clientId: string;
+  clientSecret: string;
+  /** the registered callback, on the application's public origin */
+  redirectUri: URL;
+  scopes?: string;
+  /** deadline of discovery, token, UserInfo, refresh and revocation requests */
+  requestTimeoutSeconds?: number;
+  /** deadline of one introspection; the introspection client's default applies when absent */
+  introspectionTimeoutMs?: number;
+}
+
+const optionalString = (valueArg: unknown): string | undefined =>
+  typeof valueArg === 'string' && valueArg.trim().length > 0 ? valueArg.trim() : undefined;
+
+/** When an access token dies, from the `expires_in` of a token response; `0` when it names none. */
+const expiryOf = (expiresInArg: number | undefined): number =>
+  typeof expiresInArg === 'number' && Number.isFinite(expiresInArg) && expiresInArg > 0
+    ? Date.now() + Math.floor(expiresInArg) * 1_000
+    : 0;
+
+/**
+ * Organization claims as idp.global documents them: `id`, `name`, `slug` and
+ * the member's roles. Anything that is not that exact shape is dropped rather
+ * than guessed at.
+ */
+export const readOrganizationClaims = (valueArg: unknown): IOidcOrganizationClaim[] => {
+  if (!Array.isArray(valueArg)) {
+    return [];
+  }
+  const organizations: IOidcOrganizationClaim[] = [];
+  for (const entry of valueArg) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      continue;
+    }
+    const candidate = entry as Record<string, unknown>;
+    const id = optionalString(candidate.id);
+    const name = optionalString(candidate.name);
+    const slug = optionalString(candidate.slug);
+    if (!id || !name || !slug) {
+      continue;
+    }
+    const roles = Array.isArray(candidate.roles)
+      ? candidate.roles.filter((roleArg): roleArg is string => typeof roleArg === 'string')
+      : [];
+    organizations.push({ id, name, slug, roles });
+  }
+  return organizations;
+};
+
+/**
+ * The relying-party side of the authorization code flow with S256 PKCE on
+ * `openid-client`, in the profile idp.global supports: code responses, S256
+ * challenges, RS256 ID tokens and `client_secret_basic` for a confidential
+ * client. Live organization authority is observed with the sdk's
+ * `OidcIntrospectionClient`.
+ */
+export class IdpOidcProvider implements IOidcProvider {
+  public readonly requestTimeoutSeconds: number;
+  readonly #options: IIdpOidcProviderOptions;
+  #configuration?: plugins.openidClient.Configuration;
+  #introspection?: OidcIntrospectionClient;
+
+  constructor(optionsArg: IIdpOidcProviderOptions) {
+    if (!(optionsArg?.issuer instanceof URL) || !(optionsArg.redirectUri instanceof URL)) {
+      throw new Error('IdpOidcProvider needs the issuer and the redirect URI as URLs');
+    }
+    if (!optionalString(optionsArg.clientId) || !optionalString(optionsArg.clientSecret)) {
+      throw new Error('IdpOidcProvider needs a client id and a client secret');
+    }
+    const timeout = optionsArg.requestTimeoutSeconds ?? IDP_OIDC_DEFAULT_REQUEST_TIMEOUT_SECONDS;
+    if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 60) {
+      throw new Error('IdpOidcProvider requestTimeoutSeconds must be an integer from 1 to 60');
+    }
+    this.requestTimeoutSeconds = timeout;
+    this.#options = optionsArg;
+  }
+
+  private get configuration(): plugins.openidClient.Configuration {
+    if (!this.#configuration) {
+      throw new Error('The identity provider is not initialized');
+    }
+    return this.#configuration;
+  }
+
+  public async init(): Promise<void> {
+    if (this.#configuration) {
+      return;
+    }
+    const options = this.#options;
+    // the timeout given to discovery bounds discovery itself and stays on the
+    // resolved configuration for every later request
+    const configuration = await plugins.openidClient.discovery(
+      options.issuer,
+      options.clientId,
+      {
+        client_secret: options.clientSecret,
+        token_endpoint_auth_method: 'client_secret_basic',
+        id_token_signed_response_alg: 'RS256',
+      },
+      plugins.openidClient.ClientSecretBasic(options.clientSecret),
+      { timeout: this.requestTimeoutSeconds },
+    );
+    const metadata = configuration.serverMetadata();
+    if (!metadata.authorization_endpoint || !metadata.token_endpoint || !metadata.jwks_uri) {
+      throw new Error('The identity provider is missing required OIDC endpoints');
+    }
+    if (!metadata.code_challenge_methods_supported?.includes('S256')) {
+      throw new Error('The identity provider must support PKCE S256');
+    }
+    if (
+      metadata.id_token_signing_alg_values_supported
+      && !metadata.id_token_signing_alg_values_supported.includes('RS256')
+    ) {
+      throw new Error('The identity provider must sign ID tokens with RS256');
+    }
+    if (metadata.grant_types_supported && !metadata.grant_types_supported.includes('authorization_code')) {
+      throw new Error('The identity provider must support the authorization_code grant');
+    }
+    if (metadata.grant_types_supported && !metadata.grant_types_supported.includes('refresh_token')) {
+      // without rotation the access token dies long before the session does
+      throw new Error('The identity provider must support the refresh_token grant');
+    }
+    this.#introspection = new OidcIntrospectionClient({
+      issuer: options.issuer.origin,
+      clientId: options.clientId,
+      clientSecret: options.clientSecret,
+      ...(options.introspectionTimeoutMs !== undefined ? { timeoutMs: options.introspectionTimeoutMs } : {}),
+    });
+    this.#configuration = configuration;
+  }
+
+  public async buildAuthorizationUrl(optionsArg: IOidcAuthorizationOptions): Promise<URL> {
+    const codeChallenge = await plugins.openidClient.calculatePKCECodeChallenge(optionsArg.pkceVerifier);
+    return plugins.openidClient.buildAuthorizationUrl(this.configuration, {
+      redirect_uri: this.#options.redirectUri.href,
+      response_type: 'code',
+      scope: this.#options.scopes ?? IDP_OIDC_DEFAULT_SCOPES,
+      code_challenge: codeChallenge,
+      code_challenge_method: 'S256',
+      state: optionsArg.state,
+      nonce: optionsArg.nonce,
+    });
+  }
+
+  public async completeAuthorization(optionsArg: IOidcCompletionOptions): Promise<IOidcCompletion> {
+    let tokens: Awaited<ReturnType<typeof plugins.openidClient.authorizationCodeGrant>>;
+    try {
+      tokens = await plugins.openidClient.authorizationCodeGrant(this.configuration, optionsArg.callbackUrl, {
+        pkceCodeVerifier: optionsArg.pkceVerifier,
+        expectedState: optionsArg.state,
+        expectedNonce: optionsArg.nonce,
+        idTokenExpected: true,
+      });
+    } catch (error) {
+      throw new OidcCompletionError('token_exchange', error);
+    }
+
+    let subject: string;
+    try {
+      const claims = tokens.claims();
+      if (!claims?.sub) {
+        throw new Error('The token response carries no subject');
+      }
+      subject = claims.sub;
+    } catch (error) {
+      throw new OidcCompletionError('token_validation', error);
+    }
+
+    // UserInfo is the current view of profile and organization claims; the ID
+    // token proves the login. Both are read, and the subjects must agree.
+    let userInfo: Awaited<ReturnType<typeof plugins.openidClient.fetchUserInfo>>;
+    try {
+      userInfo = await plugins.openidClient.fetchUserInfo(this.configuration, tokens.access_token, subject);
+    } catch (error) {
+      throw new OidcCompletionError('userinfo', error);
+    }
+    if (userInfo.sub !== subject) {
+      throw new OidcCompletionError('token_validation', new Error('The UserInfo subject does not match the ID token'));
+    }
+
+    return {
+      subject,
+      accessToken: tokens.access_token,
+      ...(tokens.refresh_token ? { refreshToken: tokens.refresh_token } : {}),
+      accessTokenExpiresAt: expiryOf(tokens.expires_in),
+      email: optionalString(userInfo.email),
+      emailVerified: userInfo.email_verified === true,
+      displayName: optionalString(userInfo.name) || optionalString(userInfo.preferred_username),
+      organizations: readOrganizationClaims(Reflect.get(userInfo, 'organizations')),
+    };
+  }
+
+  public async revokeToken(tokenArg: string, hintArg: TOidcTokenHint): Promise<void> {
+    await plugins.openidClient.tokenRevocation(this.configuration, tokenArg, { token_type_hint: hintArg });
+  }
+
+  /**
+   * One `POST /oauth/introspect` through the confidential introspection
+   * client, which validates the whole answer before this code sees it. A
+   * refusal (`active: false`) is an answer; anything else is a failure to
+   * observe.
+   */
+  public async introspectOrganization(optionsArg: {
+    accessToken: string;
+    subject: string;
+    organizationId: string;
+  }): Promise<IOidcOrganizationObservation> {
+    if (!this.#introspection) {
+      throw new Error('The identity provider is not initialized');
+    }
+    let response: Awaited<ReturnType<OidcIntrospectionClient['introspect']>>;
+    try {
+      response = await this.#introspection.introspect({
+        token: optionsArg.accessToken,
+        subject: optionsArg.subject,
+        organizationId: optionsArg.organizationId,
+      });
+    } catch (error) {
+      if (error instanceof OidcIntrospectionError) {
+        if (error.code === 'invalid_request') {
+          // a request the endpoint's own client refuses is a defect of the
+          // caller, never an answer about access
+          throw error;
+        }
+        throw new OidcAuthorityUnavailableError(error.code, error);
+      }
+      throw new OidcAuthorityUnavailableError('unavailable', error);
+    }
+    if (!response.active) {
+      return { active: false, roles: [], expiresAt: 0 };
+    }
+    return {
+      active: true,
+      roles: response.idp_global_authority.roles,
+      expiresAt: response.exp * 1_000,
+    };
+  }
+
+  /** The refresh grant with rotation; a superseded refresh token is never kept by the caller. */
+  public async refreshTokens(refreshTokenArg: string): Promise<IOidcRefreshedTokens> {
+    let tokens: Awaited<ReturnType<typeof plugins.openidClient.refreshTokenGrant>>;
+    try {
+      tokens = await plugins.openidClient.refreshTokenGrant(this.configuration, refreshTokenArg);
+    } catch (error) {
+      if (error instanceof plugins.openidClient.ResponseBodyError && error.error === 'invalid_grant') {
+        throw new OidcRefreshRefusedError(error);
+      }
+      throw new OidcAuthorityUnavailableError('unavailable', error);
+    }
+    return {
+      accessToken: tokens.access_token,
+      ...(tokens.refresh_token ? { refreshToken: tokens.refresh_token } : {}),
+      accessTokenExpiresAt: expiryOf(tokens.expires_in),
+    };
+  }
+}