@idp.global/sdk 19.4.0 → 19.6.0

package/ts_browser/classes.relyingpartybearerclient.ts

@@ -1,13 +1,22 @@
 import {
+  isPkceVerifier,
   RELYING_PARTY_BEARER_MESSAGE_TYPE,
+  type IRelyingPartyBearerClaimRequest,
+  type IRelyingPartyBearerLoginQuery,
   type IRelyingPartyBearerLogoutAnswer,
+  type IRelyingPartyBearerLogoutRequest,
+  type IRelyingPartyBearerRefreshRequest,
   type IRelyingPartyBearerTokenAnswer,
 } from '../ts_relyingparty/contract.bearer.js';
 
 export type {
+  IRelyingPartyBearerClaimRequest,
   IRelyingPartyBearerErrorAnswer,
+  IRelyingPartyBearerLoginQuery,
   IRelyingPartyBearerLogoutAnswer,
+  IRelyingPartyBearerLogoutRequest,
   IRelyingPartyBearerMessage,
+  IRelyingPartyBearerRefreshRequest,
   IRelyingPartyBearerSessionAnswer,
   IRelyingPartyBearerSessionInfo,
   IRelyingPartyBearerTokenAnswer,
@@ -49,6 +58,19 @@ export interface IRelyingPartyBearerTokenStorage {
   clear(optionsArg: { signal: AbortSignal }): Promise<void>;
 }
 
+/**
+ * A PKCE pair (RFC 7636): the verifier the client keeps and the S256
+ * challenge it hands out. `codeVerifier` is the secret that makes a code
+ * worth anything; keep it like a pending login, never in a URL, a log or a
+ * message.
+ */
+export interface IRelyingPartyBearerPkce {
+  /** 43 characters from 32 random bytes */
+  codeVerifier: string;
+  /** BASE64URL(SHA-256(codeVerifier)) */
+  codeChallenge: string;
+}
+
 /**
  * A login on its way: what `createLogin` made and the receiver needs back.
  * A `web` login leaves the page, so the application keeps it until the
@@ -149,7 +171,7 @@ export type TRelyingPartyBearerClientErrorCode =
   | 'state_mismatch'
   /** the delivery carries no code; `deliveryError` says why */
   | 'login_failed'
-  /** this login was received once already; a code is claimed once, never again */
+  /** this login, or this PKCE pair, was received once already; a code is claimed once, never again */
   | 'already_received'
   /** the browser opened no popup */
   | 'popup_blocked'
@@ -219,6 +241,12 @@ const isText = (valueArg: unknown): valueArg is string => typeof valueArg === 's
 
 const isTime = (valueArg: unknown): valueArg is number => typeof valueArg === 'number' && Number.isFinite(valueArg);
 
+/** What the client posts to the bearer routes. */
+type TRelyingPartyBearerRequestBody =
+  | IRelyingPartyBearerClaimRequest
+  | IRelyingPartyBearerRefreshRequest
+  | IRelyingPartyBearerLogoutRequest;
+
 /** Throws `request_failed` once a section's deadline has fired: nothing is sent or written past it. */
 const inTime = (signalArg: AbortSignal): void => {
   if (signalArg.aborted) {
@@ -278,7 +306,9 @@ const tokenAnswerOf = (answerArg: unknown): IRelyingPartyBearerTokenAnswer | nul
  * request or write never holds the other tabs. A login replaces the stored
  * pair and ends that pair's session. Rotation is strict at the relying
  * party: a refresh token spent once ends the session when it comes back, so
- * nothing here retries a claim or a refresh.
+ * nothing here retries a claim or a refresh. A code that reaches the client
+ * another way, such as a device pairing, is claimed through `createPkce` and
+ * `claimCode` under the same rules, without a window.
  *
  * It needs the Web Locks API and Web Crypto, both of them only in a secure
  * context, and has no fallback for either.
@@ -296,6 +326,8 @@ export class RelyingPartyBearerClient {
   readonly #now: () => number;
   /** the states of the logins received here; a login is received once */
   readonly #receivedStates = new Set<string>();
+  /** the challenges of the pairs `claimCode` claimed with here; a pair is claimed with once */
+  readonly #claimedChallenges = new Set<string>();
 
   constructor(optionsArg: IRelyingPartyBearerClientOptions) {
     const origin = optionsArg?.origin;
@@ -375,17 +407,63 @@ export class RelyingPartyBearerClient {
     if (!isText(returnTarget)) {
       throw new Error('returnTarget must name the configured return target');
     }
-    const codeVerifier = randomBase64Url();
+    const { codeVerifier, codeChallenge } = await this.createPkce();
     const state = randomBase64Url();
+    const query: Required<IRelyingPartyBearerLoginQuery> = {
+      client_kind: clientKind,
+      return_target: returnTarget,
+      code_challenge: codeChallenge,
+      code_challenge_method: 'S256',
+      state,
+    };
     const url = new URL(this.#paths.login);
-    url.searchParams.set('client_kind', clientKind);
-    url.searchParams.set('return_target', returnTarget);
-    url.searchParams.set('code_challenge', await pkceChallengeOf(codeVerifier));
-    url.searchParams.set('code_challenge_method', 'S256');
-    url.searchParams.set('state', state);
+    for (const [name, value] of Object.entries(query)) {
+      url.searchParams.set(name, value);
+    }
     return { clientKind, returnTarget, state, codeVerifier, url: url.href };
   }
 
+  /**
+   * A fresh PKCE pair: a verifier from 32 random bytes and its S256
+   * challenge. For a code the client does not receive through its own login,
+   * such as one the application delivers to a device it pairs: the challenge
+   * goes to the application, and `claimCode` claims the code with the pair.
+   * Needs no window.
+   */
+  public async createPkce(): Promise<IRelyingPartyBearerPkce> {
+    const codeVerifier = randomBase64Url();
+    return { codeVerifier, codeChallenge: await pkceChallengeOf(codeVerifier) };
+  }
+
+  /**
+   * Claims a hand-off code that was bound to `pkceArg`'s challenge and
+   * reached this client some other way than its own login, such as a device
+   * pairing (`openBearerHandoff` at the relying party). It is received like
+   * a login: one claim, never retried, under `requestTimeoutMs`, and the
+   * claimed pair replaces the stored one under the lock, whose session is
+   * ended then (`IRelyingPartyBearerLoginResult`). A pair is claimed with
+   * once: a second call with it, after a failed claim too, is
+   * `already_received` and sends nothing. A pair that is not one (a
+   * malformed verifier, a challenge that is not its S256) or a code that is
+   * not text is refused before anything is sent. Needs no window.
+   */
+  public async claimCode(pkceArg: IRelyingPartyBearerPkce, codeArg: string): Promise<IRelyingPartyBearerLoginResult> {
+    const codeVerifier: unknown = pkceArg?.codeVerifier;
+    const codeChallenge: unknown = pkceArg?.codeChallenge;
+    if (!isPkceVerifier(codeVerifier) || typeof codeChallenge !== 'string' || codeChallenge !== await pkceChallengeOf(codeVerifier)) {
+      throw new Error('claimCode needs a PKCE pair: a verifier and its S256 challenge, as createPkce makes them');
+    }
+    if (!isText(codeArg)) {
+      throw new Error('claimCode needs the hand-off code as text');
+    }
+    if (this.#claimedChallenges.has(codeChallenge)) {
+      throw new RelyingPartyBearerClientError('already_received');
+    }
+    // taken before the claim is sent: a failed claim uses the pair up too
+    this.#claimedChallenges.add(codeChallenge);
+    return this.claim(codeArg, codeVerifier);
+  }
+
   /**
    * Receives a `web` login on its return target page. The delivery leaves
    * the address first, before anything is checked, so neither a reload nor
@@ -548,9 +626,14 @@ export class RelyingPartyBearerClient {
     if (!isText(codeArg)) {
       throw new RelyingPartyBearerClientError('unexpected_answer');
     }
+    return this.claim(codeArg, loginArg.codeVerifier);
+  }
+
+  /** Claims a code once with its verifier and stores the pair in place of the one before. */
+  private async claim(codeArg: string, codeVerifierArg: string): Promise<IRelyingPartyBearerLoginResult> {
+    const body: IRelyingPartyBearerClaimRequest = { code: codeArg, codeVerifier: codeVerifierArg };
     // the claim touches no stored pair, so it holds no lock, only its own deadline; a failed one leaves the stored pair as it was
-    const answer = tokenAnswerOf(await this.withDeadline((signalArg) =>
-      this.post(this.#paths.claim, { code: codeArg, codeVerifier: loginArg.codeVerifier }, {}, signalArg)));
+    const answer = tokenAnswerOf(await this.withDeadline((signalArg) => this.post(this.#paths.claim, body, {}, signalArg)));
     if (!answer) {
       throw new RelyingPartyBearerClientError('unexpected_answer', { status: 200 });
     }
@@ -695,8 +778,9 @@ export class RelyingPartyBearerClient {
         return current;
       }
       let answer: IRelyingPartyBearerTokenAnswer | null;
+      const body: IRelyingPartyBearerRefreshRequest = { refreshToken: current.refreshToken };
       try {
-        answer = tokenAnswerOf(await this.post(this.#paths.refresh, { refreshToken: current.refreshToken }, {}, signalArg));
+        answer = tokenAnswerOf(await this.post(this.#paths.refresh, body, {}, signalArg));
       } catch (error) {
         if (error instanceof RelyingPartyBearerClientError && error.answerError === 'invalid_bearer_grant') {
           // the session is over: this pair opens nothing any more
@@ -718,12 +802,8 @@ export class RelyingPartyBearerClient {
 
   /** Ends the session of a pair through the logout route and answers whether that ended a live one. */
   private async endSessionOf(pairArg: IRelyingPartyBearerStoredTokens, signalArg: AbortSignal): Promise<boolean> {
-    const answer = await this.post(
-      this.#paths.logout,
-      { refreshToken: pairArg.refreshToken },
-      { authorization: `Bearer ${pairArg.accessToken}` },
-      signalArg,
-    );
+    const body: IRelyingPartyBearerLogoutRequest = { refreshToken: pairArg.refreshToken };
+    const answer = await this.post(this.#paths.logout, body, { authorization: `Bearer ${pairArg.accessToken}` }, signalArg);
     if (!isRecord(answer) || typeof answer.endedLiveSession !== 'boolean') {
       throw new RelyingPartyBearerClientError('unexpected_answer', { status: 200 });
     }
@@ -772,7 +852,7 @@ export class RelyingPartyBearerClient {
    */
   private async post(
     urlArg: string,
-    bodyArg: Record<string, string>,
+    bodyArg: TRelyingPartyBearerRequestBody,
     headersArg: Record<string, string> = {},
     signalArg?: AbortSignal,
   ): Promise<unknown> {

package/ts_relyingparty/classes.errors.ts

@@ -14,6 +14,8 @@ export type TRelyingPartyErrorCode =
   | 'invalid_bearer_handoff'
   /** a refresh token that is unknown, rotated, expired, or of a session that is over */
   | 'invalid_bearer_grant'
+  /** `openBearerHandoff` named an opener that is no live provider login: unknown, ended, expired, of an inactive principal, or without a provider login of its own */
+  | 'invalid_handoff_opener'
   /** a `sessionsOfPrincipal` cursor that no page of it answered */
   | 'invalid_sessions_cursor';
 
@@ -27,6 +29,7 @@ const RELYING_PARTY_ERROR_STATUS: Readonly<Record<TRelyingPartyErrorCode, number
   return_target_not_allowed: 400,
   invalid_bearer_handoff: 400,
   invalid_bearer_grant: 400,
+  invalid_handoff_opener: 400,
   invalid_sessions_cursor: 400,
 };
 

package/ts_relyingparty/classes.idpoidcprovider.ts

@@ -70,24 +70,163 @@ export interface IOidcRefreshedTokens {
   accessTokenExpiresAt: number;
 }
 
+/**
+ * What failed when the provider was asked, as an application tells the cases
+ * apart; never why access was refused, which only an authority answer says.
+ */
+export type TOidcProviderErrorCode =
+  /**
+   * The provider refused the login: an OAuth error in the callback, for the
+   * code at the token endpoint, or for its token at UserInfo. `oauthError`
+   * names it, such as `invalid_grant` for a code that was used or expired.
+   */
+  | 'token_exchange_refused'
+  /**
+   * The callback or its ID token is not this login's: a `state` that is not
+   * the login's, or an ID token claim that does not match it (the nonce, and
+   * likewise the issuer, the audience or the authorized party).
+   */
+  | 'login_mismatch'
+  /**
+   * The provider answered outside its contract: an ID token whose signature
+   * does not verify against the JWKS or that has expired, no subject, another
+   * subject at UserInfo, or a body that is no OAuth answer.
+   */
+  | 'invalid_response'
+  /** The provider could not be asked: no answer in time, a transport failure, a 5xx, or no discovery yet. */
+  | 'provider_unreachable'
+  /** The refresh grant answered `invalid_grant`: the refresh family is revoked, expired or was reused. */
+  | 'refresh_refused';
+
+export const OIDC_PROVIDER_ERROR_CODES: readonly TOidcProviderErrorCode[] = [
+  'token_exchange_refused',
+  'login_mismatch',
+  'invalid_response',
+  'provider_unreachable',
+  'refresh_refused',
+];
+
+/** An OAuth error code is a short token; anything else a provider sends there is dropped, never kept. */
+const OAUTH_ERROR_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
+
+const oauthErrorOf = (valueArg: unknown): string | undefined =>
+  typeof valueArg === 'string' && OAUTH_ERROR_PATTERN.test(valueArg) ? valueArg : undefined;
+
+/** The OAuth error and HTTP status of an openid-client failure that is the provider's own answer; `null` for any other failure. */
+const providerAnswerOf = (errorArg: unknown): { oauthError?: string; status?: number } | null => {
+  const openidClient = plugins.openidClient;
+  if (errorArg instanceof openidClient.ResponseBodyError) {
+    return { oauthError: oauthErrorOf(errorArg.error), status: errorArg.status };
+  }
+  if (errorArg instanceof openidClient.AuthorizationResponseError) {
+    return { oauthError: oauthErrorOf(errorArg.error) };
+  }
+  if (errorArg instanceof openidClient.WWWAuthenticateChallengeError) {
+    return { oauthError: oauthErrorOf(errorArg.cause[0]?.parameters.error), status: errorArg.status };
+  }
+  return null;
+};
+
+/** openid-client's codes (`ClientError.code`) for a provider that did not answer in time or within HTTP's own contract. */
+const UNREACHABLE_CLIENT_ERROR_CODES: readonly string[] = ['OAUTH_TIMEOUT', 'OAUTH_ABORT', 'OAUTH_RESPONSE_IS_NOT_CONFORM'];
+/** openid-client's code for a JWT claim that is not the expected one: the nonce, the issuer, the audience or the authorized party. */
+const JWT_CLAIM_COMPARISON_CODE = 'OAUTH_JWT_CLAIM_COMPARISON_FAILED';
+
+/**
+ * The class of an openid-client failure of the code exchange or of UserInfo.
+ * The provider's own OAuth error answer is a refusal, or unreachable on a 5xx;
+ * a claim that does not match is not this login's; every other failure of
+ * openid-client's checks is an invalid response; and anything else (a
+ * transport failure is fetch's `TypeError`) is an unreachable provider.
+ */
+const classifyCompletionFailure = (errorArg: unknown): { code: TOidcProviderErrorCode; oauthError?: string } => {
+  if (errorArg instanceof OidcProviderError) {
+    return { code: errorArg.code, oauthError: errorArg.oauthError };
+  }
+  const answer = providerAnswerOf(errorArg);
+  if (answer) {
+    const code: TOidcProviderErrorCode = answer.status !== undefined && answer.status >= 500
+      ? 'provider_unreachable'
+      : 'token_exchange_refused';
+    return { code, oauthError: answer.oauthError };
+  }
+  if (errorArg instanceof plugins.openidClient.ClientError) {
+    if (errorArg.code === JWT_CLAIM_COMPARISON_CODE) {
+      return { code: 'login_mismatch' };
+    }
+    return { code: errorArg.code !== undefined && UNREACHABLE_CLIENT_ERROR_CODES.includes(errorArg.code) ? 'provider_unreachable' : 'invalid_response' };
+  }
+  return { code: 'provider_unreachable' };
+};
+
+/** Why a refresh could not be made: openid-client's checks failed on the answer, or the provider could not be asked. */
+const refreshFailureReasonOf = (errorArg: unknown): TOidcAuthorityFailure =>
+  errorArg instanceof plugins.openidClient.ClientError
+    && !(errorArg.code !== undefined && UNREACHABLE_CLIENT_ERROR_CODES.includes(errorArg.code))
+    ? 'invalid_response'
+    : 'unavailable';
+
+/**
+ * Every failure of the provider this module throws: its `code` says which
+ * case it is, `oauthError` the provider's own OAuth error code where it sent
+ * one (a short token, never its description). An application classifies a
+ * failure by these and never by openid-client's classes; `cause` keeps the
+ * original for a debugger, not for a log line.
+ */
+export class OidcProviderError extends Error {
+  public readonly code: TOidcProviderErrorCode;
+  public readonly oauthError?: string;
+
+  constructor(
+    messageArg: string,
+    detailArg: { code: TOidcProviderErrorCode; oauthError?: string },
+    causeArg?: unknown,
+  ) {
+    super(messageArg, { cause: causeArg });
+    this.name = 'OidcProviderError';
+    if (!OIDC_PROVIDER_ERROR_CODES.includes(detailArg?.code)) {
+      throw new TypeError('OidcProviderError needs one of OIDC_PROVIDER_ERROR_CODES');
+    }
+    this.code = detailArg.code;
+    const oauthError = oauthErrorOf(detailArg.oauthError);
+    if (oauthError !== undefined) {
+      this.oauthError = oauthError;
+    }
+  }
+}
+
 /** 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 {
+/**
+ * The provider could not be asked, or did not answer in its own contract. The
+ * caller fails closed on it. `code` is `provider_unreachable` or
+ * `invalid_response`, after `reason`.
+ */
+export class OidcAuthorityUnavailableError extends OidcProviderError {
   constructor(
     public readonly reason: TOidcAuthorityFailure,
     causeArg?: unknown,
   ) {
-    super('The identity provider could not be observed', { cause: causeArg });
+    super(
+      'The identity provider could not be observed',
+      {
+        code: reason === 'invalid_response' ? 'invalid_response' : 'provider_unreachable',
+        oauthError: providerAnswerOf(causeArg)?.oauthError,
+      },
+      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 {
+/**
+ * The provider refused the refresh with `invalid_grant`: the refresh family is
+ * revoked, expired or was reused. `code` is `refresh_refused`.
+ */
+export class OidcRefreshRefusedError extends OidcProviderError {
   constructor(causeArg?: unknown) {
-    super('The identity provider refused the refresh', { cause: causeArg });
+    super('The identity provider refused the refresh', { code: 'refresh_refused', oauthError: 'invalid_grant' }, causeArg);
     this.name = 'OidcRefreshRefusedError';
   }
 }
@@ -96,12 +235,18 @@ export type TOidcTokenHint = 'access_token' | 'refresh_token';
 
 export type TOidcCompletionFailureStage = 'token_exchange' | 'token_validation' | 'userinfo';
 
-export class OidcCompletionError extends Error {
+/**
+ * A login the provider half could not complete. `stage` says where it
+ * stopped, `code` what it was; without a `detailArg` the code is read from
+ * the cause, an openid-client failure.
+ */
+export class OidcCompletionError extends OidcProviderError {
   constructor(
     public readonly stage: TOidcCompletionFailureStage,
     causeArg: unknown,
+    detailArg?: { code: TOidcProviderErrorCode; oauthError?: string },
   ) {
-    super('OIDC completion failed', { cause: causeArg });
+    super('OIDC completion failed', detailArg ?? classifyCompletionFailure(causeArg), causeArg);
     this.name = 'OidcCompletionError';
   }
 }
@@ -151,7 +296,7 @@ export interface IIdpOidcProviderOptions {
   /** the registered callback, on the application's public origin */
   redirectUri: URL;
   scopes?: string;
-  /** deadline of discovery, token, UserInfo, refresh and revocation requests */
+  /** deadline of discovery, token, JWKS, UserInfo, refresh and revocation requests */
   requestTimeoutSeconds?: number;
   /** deadline of one introspection; the introspection client's default applies when absent */
   introspectionTimeoutMs?: number;
@@ -165,7 +310,7 @@ export interface IIdpOidcProviderOptions {
   trustedCaPem?: string | readonly string[];
   /**
    * Advanced: the fetch that carries every request of this provider —
-   * discovery, token, UserInfo, refresh, revocation and introspection.
+   * discovery, token, JWKS, UserInfo, refresh, revocation and introspection.
    * It owns the transport's trust decisions; https-only still holds. Not
    * combined with `trustedCaPem`.
    */
@@ -213,9 +358,9 @@ export const readOrganizationClaims = (valueArg: unknown): IOidcOrganizationClai
 /**
  * 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`.
+ * challenges, RS256 ID tokens whose signature is verified against the
+ * issuer's JWKS, 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;
@@ -262,7 +407,11 @@ export class IdpOidcProvider implements IOidcProvider {
     }
     const options = this.#options;
     // the timeout and the fetch given to discovery apply to discovery itself
-    // and stay on the resolved configuration for every later request
+    // and stay on the resolved configuration for every later request.
+    // `enableNonRepudiationChecks` verifies the signature of every ID token the
+    // code grant and the refresh grant answer against the issuer's JWKS
+    // (`jwks_uri`, fetched through the same fetch), so an ID token is never
+    // accepted on the trust of the TLS connection alone
     const configuration = await plugins.openidClient.discovery(
       options.issuer,
       options.clientId,
@@ -274,6 +423,7 @@ export class IdpOidcProvider implements IOidcProvider {
       plugins.openidClient.ClientSecretBasic(options.clientSecret),
       {
         timeout: this.requestTimeoutSeconds,
+        execute: [plugins.openidClient.enableNonRepudiationChecks],
         ...(this.#fetch ? { [plugins.openidClient.customFetch]: this.#fetch } : {}),
       },
     );
@@ -322,6 +472,15 @@ export class IdpOidcProvider implements IOidcProvider {
   }
 
   public async completeAuthorization(optionsArg: IOidcCompletionOptions): Promise<IOidcCompletion> {
+    // the one state of the callback is the login's, or nothing is exchanged
+    const states = optionsArg.callbackUrl.searchParams.getAll('state');
+    if (states.length !== 1 || states[0] !== optionsArg.state) {
+      throw new OidcCompletionError(
+        'token_exchange',
+        new Error('The callback state is not the state of this login'),
+        { code: 'login_mismatch' },
+      );
+    }
     let tokens: Awaited<ReturnType<typeof plugins.openidClient.authorizationCodeGrant>>;
     try {
       tokens = await plugins.openidClient.authorizationCodeGrant(this.configuration, optionsArg.callbackUrl, {
@@ -342,7 +501,7 @@ export class IdpOidcProvider implements IOidcProvider {
       }
       subject = claims.sub;
     } catch (error) {
-      throw new OidcCompletionError('token_validation', error);
+      throw new OidcCompletionError('token_validation', error, { code: 'invalid_response' });
     }
 
     // UserInfo is the current view of profile and organization claims; the ID
@@ -354,7 +513,11 @@ export class IdpOidcProvider implements IOidcProvider {
       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'));
+      throw new OidcCompletionError(
+        'token_validation',
+        new Error('The UserInfo subject does not match the ID token'),
+        { code: 'invalid_response' },
+      );
     }
 
     return {
@@ -426,7 +589,10 @@ export class IdpOidcProvider implements IOidcProvider {
       if (error instanceof plugins.openidClient.ResponseBodyError && error.error === 'invalid_grant') {
         throw new OidcRefreshRefusedError(error);
       }
-      throw new OidcAuthorityUnavailableError('unavailable', error);
+      // everything else fails closed: another OAuth error (`invalid_client` for a
+      // deactivated app) or a transport failure is unreachable, an answer that
+      // fails openid-client's checks (an ID token that does not verify) is invalid
+      throw new OidcAuthorityUnavailableError(refreshFailureReasonOf(error), error);
     }
     return {
       accessToken: tokens.access_token,