@djangocfg/api 2.1.448 → 2.1.449

package/src/auth/context/AuthContext.tsx

@@ -16,11 +16,13 @@ import { APIError } from '../../_api/generated/helpers';
 import { clearProfileCache, getCachedProfile } from '../hooks/useProfileCache';
 import { useAuthRedirectManager } from '../hooks/useAuthRedirect';
 import { useTokenRefresh } from '../hooks/useTokenRefresh';
+import { ensureRefreshHandler } from '../refreshHandler';
 import { Analytics, AnalyticsCategory, AnalyticsEvent } from '../utils/analytics';
 import { authLogger } from '../utils/logger';
 import { AccountsProvider, useAccountsContext } from './AccountsContext';
 
 import type { AuthConfig, AuthContextType, AuthProviderProps, UserProfile } from './types';
+import type { OTPRequestResult } from '../types';
 
 // Default routes
 const defaultRoutes = {
@@ -43,6 +45,12 @@ const hasValidTokens = (): boolean => {
 const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config }) => {
   const accounts = useAccountsContext();
 
+  // Register the canonical refresh strategy exactly once, synchronously on the
+  // first render, BEFORE any request can 401. This lights up the generated
+  // client's built-in 401 recovery (single-flight + retry + rotated-token
+  // persistence). Idempotent — safe across remounts / multiple providers.
+  ensureRefreshHandler();
+
   // Redirect URL manager for saving URL before auth redirect
   const redirectManager = useAuthRedirectManager({
     fallbackUrl: config?.routes?.defaultCallback || defaultRoutes.defaultCallback,
@@ -353,7 +361,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
 
   // OTP methods - email only - now uses AccountsContext
   const requestOTP = useCallback(
-    async (identifier: string, sourceUrl?: string): Promise<{ success: boolean; message: string; statusCode?: number; retryAfter?: number }> => {
+    async (identifier: string, sourceUrl?: string): Promise<OTPRequestResult> => {
       // Clear tokens before requesting OTP
       apiAccounts.clearToken();
 
@@ -372,6 +380,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
         return {
           success: true,
           message: result.message || `OTP code sent to your email address`,
+          webmail: result.webmail ?? null,
         };
       } catch (error) {
         authLogger.error('Request OTP error:', error);

package/src/auth/hooks/useAuthForm.ts

@@ -66,6 +66,7 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
     setTwoFactorCode,
     setUseBackupCode,
     startRateLimitCountdown,
+    setWebmail,
   } = formState;
 
   // 2FA verification hook - skip redirect so we can show success screen
@@ -142,6 +143,7 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
 
       if (result.success) {
         saveIdentifierToStorage(identifier);
+        setWebmail(result.webmail ?? null);
         setStep('otp');
         onIdentifierSuccess?.(identifier);
       } else {
@@ -163,7 +165,7 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
   }, [
     identifier, acceptedTerms, requireTermsAcceptance,
     validateIdentifier, requestOTP, saveIdentifierToStorage,
-    setError, setIsLoading, setStep, clearError,
+    setError, setIsLoading, setStep, clearError, setWebmail,
     startRateLimitCountdown, onIdentifierSuccess, onError, sourceUrl,
   ]);
 
@@ -235,6 +237,7 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
 
       if (result.success) {
         saveIdentifierToStorage(identifier);
+        setWebmail(result.webmail ?? null);
         setOtp('');
       } else {
         if (result.retryAfter) {
@@ -252,7 +255,7 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
     } finally {
       setIsLoading(false);
     }
-  }, [identifier, requestOTP, saveIdentifierToStorage, setOtp, setError, setIsLoading, clearError, startRateLimitCountdown, onError, sourceUrl]);
+  }, [identifier, requestOTP, saveIdentifierToStorage, setOtp, setError, setIsLoading, clearError, startRateLimitCountdown, setWebmail, onError, sourceUrl]);
 
   const handleBackToIdentifier = useCallback(() => {
     setStep('identifier');

package/src/auth/hooks/useAuthFormState.ts

@@ -2,7 +2,7 @@
 
 import { useCallback, useEffect, useRef, useState } from 'react';
 
-import type { AuthFormState, AuthFormStateHandlers, AuthStep } from '../types';
+import type { AuthFormState, AuthFormStateHandlers, AuthStep, WebmailLink } from '../types';
 
 const formatCountdown = (s: number): string => {
   if (s <= 0) return '';
@@ -25,6 +25,7 @@ export const useAuthFormState = (
   const [acceptedTerms, setAcceptedTerms] = useState(true);
   const [step, setStep] = useState<AuthStep>('identifier');
   const [error, setError] = useState('');
+  const [webmail, setWebmail] = useState<WebmailLink | null>(null);
 
   // 2FA state
   const [twoFactorSessionId, setTwoFactorSessionId] = useState<string | null>(null);
@@ -72,6 +73,7 @@ export const useAuthFormState = (
     rateLimitSeconds,
     isRateLimited: rateLimitSeconds > 0,
     rateLimitLabel: formatCountdown(rateLimitSeconds),
+    webmail,
     // Handlers
     setIdentifier,
     setOtp,
@@ -85,5 +87,6 @@ export const useAuthFormState = (
     setTwoFactorCode,
     setUseBackupCode,
     startRateLimitCountdown,
+    setWebmail,
   };
 };

package/src/auth/hooks/useTokenRefresh.ts

@@ -1,18 +1,28 @@
 'use client';
 
 /**
- * Token Refresh Hook
+ * Token Refresh Hook (proactive trigger only)
  *
- * Provides automatic token refresh functionality:
- * - Proactively refreshes token before expiry
- * - Refreshes on window focus
- * - Refreshes on network reconnect
+ * Refreshes the access token BEFORE it expires, and on window focus / network
+ * reconnect. This hook deliberately owns NO refresh logic of its own — it only
+ * decides WHEN to refresh and delegates HOW to the canonical path
+ * (`triggerRefresh` → `api.refreshNow` → the store's single-flight
+ * `tryRefresh`). That path handles token rotation, concurrent de-duplication,
+ * and persisting the rotated refresh token.
+ *
+ * Historical note: this hook (and a now-removed fetch middleware) used to run
+ * their own refresh calls and persisted the OLD refresh token instead of the
+ * rotated one the server returned. With Django's default
+ * ROTATE_REFRESH_TOKENS + BLACKLIST_AFTER_ROTATION that produced a
+ * "Token is blacklisted" 401 on the following refresh and logged users out.
+ * Funnelling every refresh through one implementation removes that whole class
+ * of bug — see auth/refreshHandler.ts.
  */
 
-import { useCallback, useEffect, useRef } from 'react';
+import { useCallback, useEffect } from 'react';
 
 import { api as apiAccounts } from '../../';
-import { CfgAccountsAuth } from '../../_api/generated/sdk.gen';
+import { triggerRefresh } from '../refreshHandler';
 import { authLogger } from '../utils/logger';
 
 // Configuration
@@ -29,83 +39,61 @@ interface UseTokenRefreshOptions {
 }
 
 /**
- * Decode JWT and get expiry time
+ * Decode JWT and get expiry time (ms epoch), or null if undecodable.
  */
 function getTokenExpiry(token: string): number | null {
   try {
     const payload = JSON.parse(atob(token.split('.')[1]));
-    return payload.exp * 1000; // Convert to milliseconds
+    return payload.exp * 1000;
   } catch {
     return null;
   }
 }
 
 /**
- * Check if token is expiring soon
+ * Check if token is expiring within the threshold.
  */
 function isTokenExpiringSoon(token: string, thresholdMs: number): boolean {
   const expiry = getTokenExpiry(token);
   if (!expiry) return false;
-
-  const timeUntilExpiry = expiry - Date.now();
-  return timeUntilExpiry < thresholdMs;
+  return expiry - Date.now() < thresholdMs;
 }
 
 /**
- * Hook for automatic token refresh
+ * Hook for proactive automatic token refresh.
  */
 export function useTokenRefresh(options: UseTokenRefreshOptions = {}) {
   const { enabled = true, onRefresh, onRefreshError } = options;
-  const isRefreshingRef = useRef(false);
 
   /**
-   * Refresh the token
+   * Refresh the token via the canonical single-flight path. Returns true on
+   * success. No local in-flight guard needed — `triggerRefresh` shares the
+   * store's single-flight promise, so overlapping calls coalesce.
    */
   const refreshToken = useCallback(async (): Promise<boolean> => {
-    if (isRefreshingRef.current) {
-      authLogger.debug('Token refresh already in progress');
-      return false;
-    }
-
-    const refreshTokenValue = apiAccounts.getRefreshToken();
-    if (!refreshTokenValue) {
+    if (!apiAccounts.getRefreshToken()) {
       authLogger.warn('No refresh token available');
       return false;
     }
 
-    isRefreshingRef.current = true;
     authLogger.info('Refreshing token...');
-
     try {
-      // Use generated API client with correct URL (/cfg/accounts/token/refresh/)
-      const result = await CfgAccountsAuth.cfgAccountsTokenRefreshCreate({
-        body: { refresh: refreshTokenValue },
-        throwOnError: true,
-      });
-
-      const newAccessToken = result.data.access;
-
+      const newAccessToken = await triggerRefresh();
       if (!newAccessToken) {
-        throw new Error('No access token in refresh response');
+        throw new Error('Token refresh failed');
       }
-
-      apiAccounts.setToken(newAccessToken);
-      apiAccounts.setRefreshToken(refreshTokenValue);
       authLogger.info('Token refreshed successfully');
-
       onRefresh?.(newAccessToken);
       return true;
     } catch (error) {
       authLogger.error('Token refresh error:', error);
       onRefreshError?.(error instanceof Error ? error : new Error(String(error)));
       return false;
-    } finally {
-      isRefreshingRef.current = false;
     }
   }, [onRefresh, onRefreshError]);
 
   /**
-   * Check and refresh if needed
+   * Check and refresh if the current token is expiring soon.
    */
   const checkAndRefresh = useCallback(async () => {
     const token = apiAccounts.getToken();
@@ -121,12 +109,8 @@ export function useTokenRefresh(options: UseTokenRefreshOptions = {}) {
   useEffect(() => {
     if (!enabled) return;
 
-    // Check immediately
     checkAndRefresh();
-
-    // Set up interval
     const intervalId = setInterval(checkAndRefresh, CHECK_INTERVAL_MS);
-
     return () => clearInterval(intervalId);
   }, [enabled, checkAndRefresh]);
 

package/src/auth/middlewares/index.ts

@@ -1,8 +1,8 @@
 export { proxyMiddleware, proxyMiddlewareConfig } from './proxy';
-export {
-  refreshAccessToken,
-  createAutoRefreshFetch,
-  isTokenExpiringSoon,
-  refreshIfExpiringSoon,
-  isAuthenticationError,
-} from './tokenRefresh'; 
+
+// NOTE: The former `tokenRefresh` middleware (createAutoRefreshFetch /
+// refreshAccessToken / refreshIfExpiringSoon) was removed. Automatic 401
+// recovery and proactive refresh now live in a single implementation: the
+// generated client interceptor (helpers/auth.ts `installAuthOnClient`) plus the
+// canonical strategy in `auth/refreshHandler.ts`. Do not reintroduce a parallel
+// refresh path here — see auth/refreshHandler.ts for the rationale.

package/src/auth/refreshHandler.ts

@@ -0,0 +1,79 @@
+'use client';
+
+/**
+ * Canonical refresh strategy — registered ONCE, used by every refresh path.
+ *
+ * The generated client (`installAuthOnClient` in helpers/auth.ts) already owns
+ * the hard parts of token refresh: single-flight de-duplication of concurrent
+ * 401s, one automatic retry of the failed request, and — crucially —
+ * persisting the ROTATED refresh token the server returns. It only needs a
+ * strategy telling it HOW to call the refresh endpoint. That strategy is here.
+ *
+ * Why this matters: Django (SimpleJWT via django-cfg) ships with
+ * `ROTATE_REFRESH_TOKENS=True` + `BLACKLIST_AFTER_ROTATION=True` by default.
+ * Every successful refresh returns a NEW refresh token and blacklists the old
+ * one. The handler MUST return `{ access, refresh }` so the store persists the
+ * rotated token; reusing the old one yields a "Token is blacklisted" 401 on the
+ * next refresh. The canonical store (auth.tryRefresh) does the persistence — we
+ * only surface the rotated token to it.
+ *
+ * This is the single source of truth. Proactive refresh (useTokenRefresh) and
+ * reactive 401 recovery (the response interceptor) both funnel through it via
+ * `api.refreshNow()` / `tryRefresh()`. Do NOT re-implement refresh anywhere
+ * else.
+ */
+
+import { api as apiAccounts } from '../';
+import { CfgAccountsAuth } from '../_api/generated/sdk.gen';
+import { authLogger } from './utils/logger';
+
+let _registered = false;
+
+/**
+ * Register the canonical refresh handler on the shared auth store. Idempotent:
+ * safe to call from every AuthProvider mount; only the first call wires it.
+ */
+export function ensureRefreshHandler(): void {
+  if (_registered) return;
+  _registered = true;
+
+  apiAccounts.setRefreshHandler(async (refresh: string) => {
+    const result = await CfgAccountsAuth.cfgAccountsTokenRefreshCreate({
+      body: { refresh },
+      throwOnError: true,
+    });
+
+    const access = result.data?.access;
+    if (!access) {
+      authLogger.error('Refresh response missing access token');
+      return null;
+    }
+
+    // Return the ROTATED refresh token so the store persists it. Fall back to
+    // the current one only if the server omits it (rotation disabled).
+    return { access, refresh: result.data?.refresh ?? refresh };
+  });
+
+  authLogger.debug('Canonical refresh handler registered');
+}
+
+/**
+ * Proactively run the canonical refresh now, sharing the SAME single-flight as
+ * 401 recovery (rotation + dedup + rotated-token persistence handled by the
+ * store). Ensures the handler is registered first. Returns the fresh access
+ * token, or null if refresh failed / no refresh token / no handler.
+ *
+ * Use this for expiry-timer / focus / reconnect triggers — never re-implement
+ * the refresh call itself.
+ */
+export function triggerRefresh(): Promise<string | null> {
+  ensureRefreshHandler();
+  // `refreshNow` is provided by the generated auth facade (helpers/auth.ts +
+  // per-group api.ts). Guarded so this compiles even before regeneration.
+  const maybe = apiAccounts as unknown as { refreshNow?: () => Promise<string | null> };
+  if (typeof maybe.refreshNow === 'function') {
+    return maybe.refreshNow();
+  }
+  authLogger.warn('api.refreshNow() unavailable — run `make generate` to regenerate the client');
+  return Promise.resolve(null);
+}

package/src/auth/types/form.ts

@@ -7,6 +7,10 @@
 
 import type { MutableRefObject } from 'react';
 
+import type { WebmailLink } from '../../_api/generated/types.gen';
+
+export type { WebmailLink };
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Step Types
 // ─────────────────────────────────────────────────────────────────────────────
@@ -22,6 +26,8 @@ export interface OTPRequestResult {
   message: string;
   statusCode?: number;
   retryAfter?: number;
+  /** Webmail deep-link for the recipient's provider, or null if unknown. */
+  webmail?: WebmailLink | null;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -55,6 +61,8 @@ export interface AuthFormState {
   isRateLimited: boolean;
   /** Formatted countdown label, e.g. "19:00" or "42s" */
   rateLimitLabel: string;
+  /** Webmail deep-link for the current identifier's provider (null = no button). */
+  webmail: WebmailLink | null;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -75,6 +83,8 @@ export interface AuthFormStateHandlers {
   setUseBackupCode: (useBackup: boolean) => void;
   /** Start a countdown timer that disables submit for `seconds` seconds */
   startRateLimitCountdown: (seconds: number) => void;
+  /** Set (or clear) the webmail deep-link for the current identifier */
+  setWebmail: (webmail: WebmailLink | null) => void;
 }
 
 export interface AuthFormSubmitHandlers {

package/src/auth/types/index.ts

@@ -13,6 +13,7 @@ export type {
   AuthFormReturn,
   UseAuthFormOptions,
   OTPRequestResult,
+  WebmailLink,
 } from './form';
 
 // Re-export context types

package/src/auth/middlewares/tokenRefresh.ts

@@ -1,161 +0,0 @@
-/**
- * Token Auto-Refresh Middleware
- *
- * Automatically refreshes access token when receiving 401 responses.
- * Implements request queuing to prevent multiple simultaneous refresh attempts.
- */
-
-import { api as apiAccounts } from '../../';
-import { CfgAccountsAuth } from '../../_api/generated/sdk.gen';
-import { authLogger } from '../utils/logger';
-
-// Refresh state management
-let isRefreshing = false;
-let refreshSubscribers: Array<(token: string | null) => void> = [];
-
-/**
- * Subscribe to token refresh completion
- */
-function subscribeTokenRefresh(callback: (token: string | null) => void): void {
-  refreshSubscribers.push(callback);
-}
-
-/**
- * Notify all subscribers when token is refreshed
- */
-function onTokenRefreshed(token: string | null): void {
-  refreshSubscribers.forEach(callback => callback(token));
-  refreshSubscribers = [];
-}
-
-/**
- * Attempt to refresh the access token using the refresh token
- * @returns New access token or null if refresh failed
- */
-export async function refreshAccessToken(): Promise<string | null> {
-  // If already refreshing, wait for completion
-  if (isRefreshing) {
-    return new Promise(resolve => {
-      subscribeTokenRefresh(token => resolve(token));
-    });
-  }
-
-  isRefreshing = true;
-  authLogger.info('Starting token refresh...');
-
-  try {
-    const refreshToken = apiAccounts.getRefreshToken();
-    if (!refreshToken) {
-      authLogger.warn('No refresh token available for refresh');
-      onTokenRefreshed(null);
-      return null;
-    }
-
-    // Use generated API client with correct URL (/cfg/accounts/token/refresh/)
-    const result = await CfgAccountsAuth.cfgAccountsTokenRefreshCreate({
-      body: { refresh: refreshToken },
-      throwOnError: true,
-    });
-
-    const newAccessToken = result.data.access;
-
-    if (!newAccessToken) {
-      authLogger.error('Token refresh response missing access token');
-      onTokenRefreshed(null);
-      return null;
-    }
-
-    // Update tokens in storage
-    apiAccounts.setToken(newAccessToken);
-    apiAccounts.setRefreshToken(refreshToken);
-    authLogger.info('Token refreshed successfully');
-
-    onTokenRefreshed(newAccessToken);
-    return newAccessToken;
-  } catch (error) {
-    authLogger.error('Token refresh error:', error);
-    onTokenRefreshed(null);
-    return null;
-  } finally {
-    isRefreshing = false;
-  }
-}
-
-/**
- * Check if a response indicates an authentication error
- */
-export function isAuthenticationError(response: Response): boolean {
-  return response.status === 401;
-}
-
-/**
- * Create a fetch wrapper that automatically refreshes tokens on 401
- *
- * @param originalFetch - The original fetch function to wrap
- * @returns Wrapped fetch function with auto-refresh capability
- */
-export function createAutoRefreshFetch(originalFetch: typeof fetch): typeof fetch {
-  return async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
-    // Make the initial request
-    let response = await originalFetch(input, init);
-
-    // If 401 and we have a refresh token, try to refresh
-    if (isAuthenticationError(response) && apiAccounts.getRefreshToken()) {
-      authLogger.info('Received 401, attempting token refresh...');
-
-      const newToken = await refreshAccessToken();
-
-      if (newToken) {
-        // Retry the request with new token
-        const newInit: RequestInit = {
-          ...init,
-          headers: {
-            ...init?.headers,
-            Authorization: `Bearer ${newToken}`,
-          },
-        };
-
-        authLogger.info('Retrying request with new token...');
-        response = await originalFetch(input, newInit);
-      } else {
-        authLogger.warn('Token refresh failed, returning original 401 response');
-      }
-    }
-
-    return response;
-  };
-}
-
-/**
- * Check if token is about to expire (within threshold)
- * @param thresholdMs - Time in ms before expiry to consider "expiring soon"
- * @returns true if token expires within threshold
- */
-export function isTokenExpiringSoon(thresholdMs: number = 5 * 60 * 1000): boolean {
-  const token = apiAccounts.getToken();
-  if (!token) return false;
-
-  try {
-    // Decode JWT payload (base64)
-    const payload = JSON.parse(atob(token.split('.')[1]));
-    const expiresAt = payload.exp * 1000; // Convert to milliseconds
-    const now = Date.now();
-    const timeUntilExpiry = expiresAt - now;
-
-    return timeUntilExpiry < thresholdMs;
-  } catch (error) {
-    authLogger.error('Error checking token expiry:', error);
-    return false;
-  }
-}
-
-/**
- * Proactively refresh token if it's expiring soon
- * Call this periodically or before important operations
- */
-export async function refreshIfExpiringSoon(thresholdMs: number = 5 * 60 * 1000): Promise<void> {
-  if (isTokenExpiringSoon(thresholdMs)) {
-    authLogger.info('Token expiring soon, proactively refreshing...');
-    await refreshAccessToken();
-  }
-}