auth-handler.ts

export interface HttpHeaders {
  [key: string]: string;
}

/**
 * Pluggable authentication handler for HTTP requests.
 *
 * - {@link headers} is called before each request to supply additional
 *   request headers (typically `Authorization`).
 * - {@link shouldRetryWithHeaders} is called after every response and
 *   decides whether the request should be retried with new headers,
 *   typically in response to a 401 / 403 or a WWW-Authenticate.
 * - {@link onSuccessfulRetry}, if defined, is called when a retry
 *   succeeds, giving the handler a chance to persist the new headers.
 */
export interface AuthenticationHandler {
  /** Returns request headers (may include `Authorization`). */
  headers: () => Promise<HttpHeaders>;

  /**
   * Called for every response. Returns new headers if the request
   * should be retried, or `undefined` to skip the retry.
   */
  shouldRetryWithHeaders: (req: RequestInit, res: Response) => Promise<HttpHeaders | undefined>;

  /**
   * Called when a retry using the headers from
   * {@link shouldRetryWithHeaders} succeeded. Lets the handler persist
   * those headers for subsequent requests.
   */
  onSuccessfulRetry?: (headers: HttpHeaders) => Promise<void>;
}

/**
 * Wraps `fetch` with authentication handling. The returned function
 * injects headers from `authHandler.headers()`, retries when
 * `authHandler.shouldRetryWithHeaders` returns new headers, and notifies
 * via `onSuccessfulRetry` when the retry succeeds.
 * Caller-provided headers take precedence on both requests, regardless of casing.
 */
export function createAuthenticatingFetchWithRetry(
  fetchImpl: typeof fetch,
  authHandler: AuthenticationHandler
): typeof fetch {
  async function authFetch(url: RequestInfo | URL, init?: RequestInit): Promise<Response> {
    const authHeaders = (await authHandler.headers()) || {};
    const mergedInit: RequestInit = {
      ...(init || {}),
      headers: mergeHeaders(authHeaders, init?.headers),
    };

    let response = await fetchImpl(url, mergedInit);

    const updatedHeaders = await authHandler.shouldRetryWithHeaders(mergedInit, response);
    if (updatedHeaders) {
      const retryInit: RequestInit = {
        ...(init || {}),
        headers: mergeHeaders(updatedHeaders, init?.headers),
      };
      response = await fetchImpl(url, retryInit);

      if (response.ok && authHandler.onSuccessfulRetry) {
        await authHandler.onSuccessfulRetry(updatedHeaders);
      }
    }

    return response;
  }

  // Preserve fetch's own properties so the wrapped function is a drop-in.
  Object.setPrototypeOf(authFetch, Object.getPrototypeOf(fetchImpl));
  Object.defineProperties(authFetch, Object.getOwnPropertyDescriptors(fetchImpl));

  return authFetch;
}

function mergeHeaders(authHeaders: HttpHeaders, callerHeaders?: HeadersInit): Headers {
  const headers = new Headers(authHeaders);
  new Headers(callerHeaders).forEach((value, name) => headers.set(name, value));
  return headers;
}