@djangocfg/api 2.1.598 → 2.1.600

package/src/auth/hooks/useGithubAuth.ts

@@ -1,45 +1,15 @@
 'use client';
 
-import { useCallback, useState } from 'react';
+import { useCallback } from 'react';
 
-import { auth } from '../../_api/generated/helpers/auth';
-import { CFG_KEYS } from '../../_api/generated/helpers/keys';
-import { CfgAccountsOauth } from '../../_api/generated/sdk.gen';
-import type { OAuthTokenResponse } from '../../_api/generated/types.gen';
-import { Analytics, AnalyticsCategory, AnalyticsEvent } from '../utils/analytics';
-import { formatAuthError } from '../utils/errors';
-import { authLogger } from '../utils/logger';
-import { useCfgRouter } from './useCfgRouter';
+import { type UseOAuthLoginOptions, useOAuthLogin } from './useOAuthLogin';
 
-const OAUTH_STATE_KEY = CFG_KEYS.oauthState.key;
-const OAUTH_PROVIDER_KEY = CFG_KEYS.oauthProvider.key;
+export type { OAuthUser } from './useOAuthLogin';
 
-/**
- * The user payload as the OAuth endpoint declares it.
- *
- * Derived from the generated response rather than restated, so a schema change
- * reaches callers through `make gen` instead of drifting silently. Today the
- * backend types it as a free-form object; when it names a real user model, this
- * narrows on its own.
- */
-export type OAuthUser = NonNullable<OAuthTokenResponse['user']>;
-
-export interface UseGithubAuthOptions {
-  sourceUrl?: string;
-  /**
-   * The OAuth endpoint's OpenAPI schema types `user` as a free-form object, so
-   * this is what the server actually promises — not a `User`. Narrow it at the
-   * call site; typing it tighter here would be an assertion, not a fact.
-   */
-  onSuccess?: (user: OAuthUser, isNewUser: boolean) => void;
-  onError?: (error: string) => void;
-  /** Callback when 2FA is required */
-  onRequires2FA?: (sessionId: string, shouldPrompt2FA: boolean) => void;
-  redirectUrl?: string;
-  /** Skip automatic redirect after success (caller handles navigation) */
-  skipRedirect?: boolean;
-}
+/** @deprecated Use `UseOAuthLoginOptions`. */
+export type UseGithubAuthOptions = UseOAuthLoginOptions;
 
+/** @deprecated Use `UseOAuthLoginReturn`. */
 export interface UseGithubAuthReturn {
   isLoading: boolean;
   error: string | null;
@@ -48,195 +18,15 @@ export interface UseGithubAuthReturn {
 }
 
 /**
- * Hook for GitHub OAuth authentication flow.
- *
- * Usage:
- * 1. Call startGithubAuth() to redirect user to GitHub
- * 2. After GitHub redirects back, call handleGithubCallback(code, state)
- *
- * @example
- * ```tsx
- * const { isLoading, error, startGithubAuth } = useGithubAuth({
- *   onSuccess: (user) => router.push('/dashboard'),
- *   onError: (error) => console.error(error),
- * });
- *
- * <Button onClick={startGithubAuth} disabled={isLoading}>
- *   Continue with GitHub
- * </Button>
- * ```
+ * @deprecated Use `useOAuthLogin` (`start('github')`, `complete('github', code, state)`).
+ * Kept for one minor release; behaviour is `useOAuthLogin` with the provider fixed.
  */
 export const useGithubAuth = (options: UseGithubAuthOptions = {}): UseGithubAuthReturn => {
-  const { sourceUrl, onSuccess, onError, onRequires2FA, redirectUrl, skipRedirect = false } = options;
-  const router = useCfgRouter();
-
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-
-  /**
-   * Start GitHub OAuth flow - redirects user to GitHub authorization page.
-   */
-  const startGithubAuth = useCallback(async () => {
-    setIsLoading(true);
-    setError(null);
-    // Match the OTP flow: a new login must not leave an older persistent
-    // session available after this browser is intentionally made session-only.
-    auth.clearSession();
-
-    try {
-      authLogger.info('Starting GitHub OAuth flow...');
-
-      // Track OAuth start
-      Analytics.event(AnalyticsEvent.AUTH_OAUTH_START, {
-        category: AnalyticsCategory.AUTH,
-        label: 'github',
-      });
-
-      // Call API to get authorization URL
-      // The API will auto-generate redirect_uri from config if not provided
-      const result = await CfgAccountsOauth.cfgAccountsOauthGithubAuthorizeCreate({
-        body: {
-          source_url: sourceUrl || (typeof window !== 'undefined' ? window.location.href : ''),
-        },
-        throwOnError: true,
-      });
-      const response = result.data;
-
-      if (!response.authorization_url) {
-        throw new Error('Failed to get authorization URL');
-      }
-
-      authLogger.info('Redirecting to GitHub...', response.authorization_url);
-
-      if (typeof window !== 'undefined') {
-        sessionStorage.setItem(OAUTH_STATE_KEY, response.state);
-        sessionStorage.setItem(OAUTH_PROVIDER_KEY, 'github');
-      }
-
-      window.location.href = response.authorization_url;
-
-    } catch (err) {
-      const errorMessage = formatAuthError(err, 'Failed to start GitHub authentication');
-      authLogger.error('GitHub OAuth start error:', err);
-      setError(errorMessage);
-      onError?.(errorMessage);
-
-      // Track OAuth error
-      Analytics.event(AnalyticsEvent.AUTH_OAUTH_FAIL, {
-        category: AnalyticsCategory.AUTH,
-        label: 'github',
-      });
-    } finally {
-      setIsLoading(false);
-    }
-  }, [sourceUrl, onError]);
-
-  /**
-   * Handle GitHub OAuth callback - exchanges code for JWT tokens.
-   *
-   * @param code - Authorization code from GitHub callback
-   * @param state - State token for CSRF verification
-   */
-  const handleGithubCallback = useCallback(async (code: string, state: string) => {
-    setIsLoading(true);
-    setError(null);
-
-    try {
-      authLogger.info('Processing GitHub OAuth callback...');
-
-      // Verify state matches what we stored
-      if (typeof window !== 'undefined') {
-        const storedState = sessionStorage.getItem(OAUTH_STATE_KEY);
-        if (storedState && storedState !== state) {
-          throw new Error('Invalid OAuth state - possible CSRF attack');
-        }
-        // Clear stored state
-        sessionStorage.removeItem(OAUTH_STATE_KEY);
-        sessionStorage.removeItem(OAUTH_PROVIDER_KEY);
-
-      }
-
-      const result = await CfgAccountsOauth.cfgAccountsOauthGithubCallbackCreate({
-        body: { code, state },
-        throwOnError: true,
-      });
-      const response = result.data;
-
-      // Check if 2FA is required
-      if (response.requires_2fa && response.session_id) {
-          authLogger.info('GitHub OAuth requires 2FA, session:', response.session_id);
-
-          // Track 2FA requirement
-          Analytics.event(AnalyticsEvent.AUTH_OAUTH_START, {
-            category: AnalyticsCategory.AUTH,
-            label: 'github-2fa-required',
-          });
-
-          // Call 2FA callback
-          onRequires2FA?.(response.session_id, response.should_prompt_2fa || false);
-        return;
-      }
-
-      if (!response.access || !response.refresh) {
-        throw new Error('Invalid response from OAuth callback');
-      }
-
-      authLogger.info('GitHub OAuth successful, user:', response.user);
-
-        // The ONE write path — atomic pair + session notification. Storage is
-        // always localStorage; session length is the server's call.
-        // See AccountsContext.verifyOTP.
-      auth.setSession({ access: response.access, refresh: response.refresh });
-
-        // Track successful OAuth
-      Analytics.event(AnalyticsEvent.AUTH_LOGIN_SUCCESS, {
-          category: AnalyticsCategory.AUTH,
-          label: 'github',
-      });
-
-        // Set user ID for future tracking
-      if (response.user?.id) {
-        Analytics.setUser(String(response.user.id));
-      }
-
-        // Call success callback.
-        //
-        // Guarded because the schema allows `user: null` — the 2FA branch returns
-        // no user — and five lines up this same value is read through `?.`. The
-        // old `any` let one line be careful and the next not.
-      if (response.user) {
-        onSuccess?.(response.user, response.is_new_user || false);
-      }
-
-        // Redirect (unless skipRedirect is true)
-      if (!skipRedirect) {
-          // Use hardPush for full page reload - ensures all React contexts reinitialize
-        const finalRedirectUrl = redirectUrl || '/private';
-        router.hardPush(finalRedirectUrl);
-      }
-
-      return;
-
-    } catch (err) {
-      const errorMessage = formatAuthError(err, 'GitHub authentication failed');
-      authLogger.error('GitHub OAuth callback error:', err);
-      setError(errorMessage);
-      onError?.(errorMessage);
-
-      // Track OAuth error
-      Analytics.event(AnalyticsEvent.AUTH_OAUTH_FAIL, {
-        category: AnalyticsCategory.AUTH,
-        label: 'github',
-      });
-    } finally {
-      setIsLoading(false);
-    }
-  }, [onSuccess, onError, onRequires2FA, redirectUrl, router, skipRedirect]);
-
-  return {
-    isLoading,
-    error,
-    startGithubAuth,
-    handleGithubCallback,
-  };
+  const { isLoading, error, start, complete } = useOAuthLogin(options);
+  const startGithubAuth = useCallback(() => start('github'), [start]);
+  const handleGithubCallback = useCallback(
+    (code: string, state: string) => complete('github', code, state),
+    [complete],
+  );
+  return { isLoading, error, startGithubAuth, handleGithubCallback };
 };

package/src/auth/hooks/useOAuthLogin.ts

@@ -0,0 +1,237 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { auth } from '../../_api/generated/helpers/auth';
+import { CFG_KEYS, cfgStorage } from '../../_api/generated/helpers/keys';
+import { CfgAccountsOauth } from '../../_api/generated/sdk.gen';
+import type {
+  OAuthAuthorizeRequestRequest,
+  OAuthAuthorizeResponse,
+  OAuthCallbackRequestRequest,
+  OAuthTokenResponse,
+} from '../../_api/generated/types.gen';
+import { Analytics, AnalyticsCategory, AnalyticsEvent } from '../utils/analytics';
+import { authLogger } from '../utils/logger';
+import { type OAuthFailureCode, type OAuthProviderId, readOAuthFailure } from '../utils/oauthErrors';
+import { consumeSavedRedirect } from './useAuthRedirect';
+import { useCfgRouter } from './useCfgRouter';
+
+/**
+ * The user payload as the OAuth endpoint declares it.
+ *
+ * Derived from the generated response rather than restated, so a schema change
+ * reaches callers through `make generate` instead of drifting silently.
+ */
+export type OAuthUser = NonNullable<OAuthTokenResponse['user']>;
+
+interface OAuthAdapter {
+  authorize: (body: OAuthAuthorizeRequestRequest) => Promise<OAuthAuthorizeResponse>;
+  callback: (body: OAuthCallbackRequestRequest) => Promise<OAuthTokenResponse>;
+}
+
+/**
+ * One entry per provider the backend can offer. Keyed by the generated enum:
+ * when the backend adds a provider, this stops compiling until it is wired.
+ */
+const ADAPTERS: Record<OAuthProviderId, OAuthAdapter> = {
+  github: {
+    authorize: async (body) =>
+      (await CfgAccountsOauth.cfgAccountsOauthGithubAuthorizeCreate({ body, throwOnError: true })).data,
+    callback: async (body) =>
+      (await CfgAccountsOauth.cfgAccountsOauthGithubCallbackCreate({ body, throwOnError: true })).data,
+  },
+  google: {
+    authorize: async (body) =>
+      (await CfgAccountsOauth.cfgAccountsOauthGoogleAuthorizeCreate({ body, throwOnError: true })).data,
+    callback: async (body) =>
+      (await CfgAccountsOauth.cfgAccountsOauthGoogleCallbackCreate({ body, throwOnError: true })).data,
+  },
+};
+
+/** Provider ids this client can run, in the order the adapters are declared. */
+export const OAUTH_PROVIDER_IDS = Object.keys(ADAPTERS) as OAuthProviderId[];
+
+export const isOAuthProviderId = (value: unknown): value is OAuthProviderId =>
+  typeof value === 'string' && Object.hasOwn(ADAPTERS, value);
+
+const STATE_KEY = CFG_KEYS.oauthState.key;
+const PROVIDER_KEY = CFG_KEYS.oauthProvider.key;
+
+/** Forget the stored state: the attempt is over without an exchange (Cancel, a provider error). */
+export const clearOAuthAttempt = (): void => {
+  cfgStorage.remove(STATE_KEY);
+  cfgStorage.remove(PROVIDER_KEY);
+};
+
+export interface UseOAuthLoginOptions {
+  sourceUrl?: string;
+  /** The endpoint types `user` as a free-form object; narrow it at the call site. */
+  onSuccess?: (user: OAuthUser, isNewUser: boolean, provider: OAuthProviderId) => void;
+  /** `message` is server prose or an English fallback; `code` lets the caller choose its own copy. */
+  onError?: (message: string, code?: OAuthFailureCode) => void;
+  /** Called when 2FA is required instead of a session. */
+  onRequires2FA?: (sessionId: string, shouldPrompt2FA: boolean) => void;
+  redirectUrl?: string;
+  /** Skip the automatic redirect after success (the caller navigates). */
+  skipRedirect?: boolean;
+}
+
+export interface UseOAuthLoginReturn {
+  /** True from the click until the page leaves (start) or the exchange settles (complete). */
+  isLoading: boolean;
+  /** The provider whose flow is in flight; disable the other buttons, show progress on this one. */
+  loadingProvider: OAuthProviderId | null;
+  error: string | null;
+  errorCode: OAuthFailureCode | null;
+  /** Redirects the tab to the provider. Resolves only if it failed to start. */
+  start: (provider: OAuthProviderId) => Promise<void>;
+  /** Exchanges the `code` the provider returned. The stored `state` must match; there is no unchecked path. */
+  complete: (provider: OAuthProviderId, code: string, state: string) => Promise<void>;
+}
+
+/**
+ * Sign in with a third-party provider: one hook for every provider.
+ *
+ * Flow, full page in the same tab so the saved return URL survives:
+ * `start(provider)` stores the server's `state`, then navigates to the provider.
+ * The provider returns to `/auth?provider=<id>&code&state`; `complete(...)`
+ * verifies that `state` against the stored one (login CSRF defence), exchanges
+ * the code and writes the session.
+ */
+export const useOAuthLogin = (options: UseOAuthLoginOptions = {}): UseOAuthLoginReturn => {
+  const router = useCfgRouter();
+
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const routerRef = useRef(router);
+  routerRef.current = router;
+
+  const [loadingProvider, setLoadingProvider] = useState<OAuthProviderId | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [errorCode, setErrorCode] = useState<OAuthFailureCode | null>(null);
+
+  // Coming back with the back button restores this page from the bfcache with
+  // the spinner still on; the provider page was left, so the flow is over.
+  useEffect(() => {
+    const onShow = (event: PageTransitionEvent) => {
+      if (event.persisted) setLoadingProvider(null);
+    };
+    window.addEventListener('pageshow', onShow);
+    return () => window.removeEventListener('pageshow', onShow);
+  }, []);
+
+  const fail = useCallback((provider: OAuthProviderId, message: string, code?: OAuthFailureCode) => {
+    setError(message);
+    setErrorCode(code ?? null);
+    setLoadingProvider(null);
+    optionsRef.current.onError?.(message, code);
+    Analytics.event(AnalyticsEvent.AUTH_OAUTH_FAIL, {
+      category: AnalyticsCategory.AUTH,
+      label: provider,
+    });
+  }, []);
+
+  const start = useCallback(async (provider: OAuthProviderId) => {
+    setLoadingProvider(provider);
+    setError(null);
+    setErrorCode(null);
+    // Match the OTP flow: a new login must not leave an older persistent
+    // session available after this browser is intentionally made session-only.
+    auth.clearSession();
+
+    try {
+      Analytics.event(AnalyticsEvent.AUTH_OAUTH_START, {
+        category: AnalyticsCategory.AUTH,
+        label: provider,
+      });
+
+      // No `redirect_uri`: the server derives it from the request origin.
+      const sourceUrl = optionsRef.current.sourceUrl || window.location.href;
+      const response = await ADAPTERS[provider].authorize({ source_url: sourceUrl });
+      if (!response.authorization_url || !response.state) {
+        throw new Error('Failed to get authorization URL');
+      }
+
+      cfgStorage.write(STATE_KEY, response.state);
+      cfgStorage.write(PROVIDER_KEY, provider);
+      authLogger.info(`Redirecting to ${provider}...`);
+      // Loading stays on: the tab is leaving.
+      window.location.href = response.authorization_url;
+    } catch (err) {
+      authLogger.error(`${provider} OAuth start error:`, err);
+      const failure = readOAuthFailure(err, 'Failed to start authentication');
+      fail(provider, failure.message, failure.code);
+    }
+  }, [fail]);
+
+  const complete = useCallback(async (provider: OAuthProviderId, code: string, state: string) => {
+    setLoadingProvider(provider);
+    setError(null);
+    setErrorCode(null);
+
+    // The stored state is the proof that THIS browser started the flow. A
+    // missing one is as wrong as a different one: an attacker's link carries a
+    // valid code and state for the attacker's account. Spent before any await.
+    const storedState = cfgStorage.read(STATE_KEY);
+    const storedProvider = cfgStorage.read(PROVIDER_KEY);
+    clearOAuthAttempt();
+    if (!storedState || storedState !== state || (storedProvider && storedProvider !== provider)) {
+      authLogger.warn(`${provider} OAuth callback rejected: state does not match this browser`);
+      fail(provider, 'Invalid sign-in attempt. Please try again.', 'invalid_state');
+      return;
+    }
+
+    try {
+      const response = await ADAPTERS[provider].callback({ code, state });
+
+      if (response.requires_2fa && response.session_id) {
+        Analytics.event(AnalyticsEvent.AUTH_OAUTH_START, {
+          category: AnalyticsCategory.AUTH,
+          label: `${provider}-2fa-required`,
+        });
+        optionsRef.current.onRequires2FA?.(response.session_id, response.should_prompt_2fa || false);
+        setLoadingProvider(null);
+        return;
+      }
+
+      if (!response.access || !response.refresh) {
+        throw new Error('Invalid response from OAuth callback');
+      }
+
+      // The ONE write path — atomic pair + session notification.
+      auth.setSession({ access: response.access, refresh: response.refresh });
+
+      Analytics.event(AnalyticsEvent.AUTH_LOGIN_SUCCESS, {
+        category: AnalyticsCategory.AUTH,
+        label: provider,
+      });
+      if (response.user?.id) {
+        Analytics.setUser(String(response.user.id));
+      }
+      if (response.user) {
+        optionsRef.current.onSuccess?.(response.user, response.is_new_user || false, provider);
+      }
+
+      setLoadingProvider(null);
+      if (!optionsRef.current.skipRedirect) {
+        // Full reload so every React context reinitialises with the new session.
+        // The saved back-url (where a guard bounced the visitor from) comes first.
+        routerRef.current.hardPush(consumeSavedRedirect() || optionsRef.current.redirectUrl || '/private');
+      }
+    } catch (err) {
+      authLogger.error(`${provider} OAuth callback error:`, err);
+      const failure = readOAuthFailure(err, 'Authentication failed');
+      fail(provider, failure.message, failure.code);
+    }
+  }, [fail]);
+
+  return {
+    isLoading: loadingProvider !== null,
+    loadingProvider,
+    error,
+    errorCode,
+    start,
+    complete,
+  };
+};

package/src/auth/hooks/useOAuthProviders.ts

@@ -0,0 +1,76 @@
+'use client';
+
+import { useMemo, useSyncExternalStore } from 'react';
+
+import { useCfgAccountsOauthProvidersRetrieve } from '../../_api/generated/_cfg_accounts/hooks/useCfgAccountsOauthProvidersRetrieve';
+import { CFG_KEYS, cfgStorage } from '../../_api/generated/helpers/keys';
+import type { OAuthProviderInfo } from '../../_api/generated/types.gen';
+import { OAUTH_PROVIDER_IDS } from './useOAuthLogin';
+
+export interface UseOAuthProvidersReturn {
+  /** Providers the server has configured, in the server's display order. Empty until ready and on failure. */
+  providers: OAuthProviderInfo[];
+  /** False only while the first request is in flight and nothing is cached. */
+  isReady: boolean;
+}
+
+const EMPTY: OAuthProviderInfo[] = [];
+const CACHE_KEY = CFG_KEYS.oauthProviders.key;
+
+const isInfo = (value: unknown): value is OAuthProviderInfo =>
+  typeof value === 'object' && value !== null && typeof (value as { id?: unknown }).id === 'string';
+
+// useSyncExternalStore needs a stable snapshot: parse again only when the stored text changed.
+let lastRaw: string | null = null;
+let lastParsed: OAuthProviderInfo[] | undefined;
+
+/** The list the previous page of this tab fetched; `undefined` when none or unreadable. */
+const readCached = (): OAuthProviderInfo[] | undefined => {
+  const raw = cfgStorage.read(CACHE_KEY);
+  if (raw === lastRaw) return lastParsed;
+  lastRaw = raw;
+  try {
+    const parsed: unknown = raw === null ? null : JSON.parse(raw);
+    lastParsed = Array.isArray(parsed) && parsed.every(isInfo) ? parsed : undefined;
+  } catch {
+    lastParsed = undefined;
+  }
+  return lastParsed;
+};
+
+const subscribe = () => () => {};
+const serverSnapshot = () => undefined;
+
+/**
+ * The sign-in providers the server offers (`GET /cfg/accounts/oauth/providers/`).
+ *
+ * Fetched once per page session and kept in `sessionStorage`, so a reload or
+ * "Try again" after a failed callback shows the buttons at once; the server
+ * answer always wins. A failure yields the cached list, else `[]`, with
+ * `isReady: true`: the email form never waits on, or breaks because of, this
+ * list. Ids this client has no adapter for (a newer backend) are dropped.
+ */
+export const useOAuthProviders = (): UseOAuthProvidersReturn => {
+  // Server and first client render see `undefined`, so hydration matches.
+  const cached = useSyncExternalStore(subscribe, readCached, serverSnapshot);
+
+  const { data, error, isLoading } = useCfgAccountsOauthProvidersRetrieve(undefined, {
+    revalidateOnFocus: false,
+    revalidateOnReconnect: false,
+    revalidateOnMount: true,
+    shouldRetryOnError: false,
+    dedupingInterval: 60 * 60 * 1000,
+    fallbackData: cached && { providers: cached },
+    onSuccess: (response) => {
+      cfgStorage.writeJSON(CACHE_KEY, response.providers);
+    },
+  });
+
+  const providers = useMemo(
+    () => data?.providers.filter((p) => OAUTH_PROVIDER_IDS.includes(p.id)) ?? EMPTY,
+    [data],
+  );
+
+  // SWR keeps `isLoading` on while it revalidates fallback data; a cached list is already usable.
+  return { providers, isReady: !isLoading || Boolean(error) || cached !== undefined };
+};

package/src/auth/utils/index.ts

@@ -7,6 +7,14 @@ export {
   type AuthErrorCopy,
   type AuthErrorKey,
 } from './errors';
+export {
+  readOAuthFailure,
+  type OAuthClientErrorCode,
+  type OAuthErrorCode,
+  type OAuthFailure,
+  type OAuthFailureCode,
+  type OAuthProviderId,
+} from './oauthErrors';
 export {
   resolveGuardIsLoading,
   shouldRedirectToAuth,

package/src/auth/utils/oauthErrors.ts

@@ -0,0 +1,45 @@
+import { OAuthErrorCodeEnum, type OAuthProviderEnum } from '../../_api/generated/types.gen';
+import { formatAuthError } from './errors';
+
+/** A provider the server can offer. Derived from the generated enum, so a new backend provider is a type error until it gets an adapter. */
+export type OAuthProviderId = `${OAuthProviderEnum}`;
+
+/** Every `error` value the OAuth endpoints can return (closed set from the OpenAPI schema). */
+export type OAuthErrorCode = `${OAuthErrorCodeEnum}`;
+
+/** Failures the browser detects itself, before or instead of a server answer. */
+export type OAuthClientErrorCode = 'cancelled' | 'unknown_provider';
+
+export type OAuthFailureCode = OAuthErrorCode | OAuthClientErrorCode;
+
+export interface OAuthFailure {
+  /** Set when the cause is one the UI can explain; absent for transport faults. */
+  code?: OAuthFailureCode;
+  /** English text for callers without a translator: server prose, else a generic sentence. */
+  message: string;
+}
+
+// Read from the generated enum: a code the backend adds arrives with `make generate`.
+const SERVER_CODES: ReadonlySet<string> = new Set<string>(Object.values(OAuthErrorCodeEnum));
+
+const record = (value: unknown): Record<string, unknown> | null =>
+  typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : null;
+
+/**
+ * Read `{error, error_description}` off a thrown API error.
+ *
+ * The transport keeps the parsed body on `response`; `formatAuthError` alone
+ * would surface the machine code (`invalid_state`) as if it were prose.
+ */
+export const readOAuthFailure = (err: unknown, fallback: string): OAuthFailure => {
+  const body = record(record(err)?.response);
+  const code = body?.error;
+  if (typeof code === 'string' && SERVER_CODES.has(code)) {
+    const description = body?.error_description;
+    return {
+      code: code as OAuthErrorCode,
+      message: typeof description === 'string' && description ? description : fallback,
+    };
+  }
+  return { message: formatAuthError(err, fallback) };
+};