@djangocfg/api 2.1.448 → 2.1.450

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,19 +1,30 @@
 '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';
+import { isTokenExpiringSoon } from '../utils/jwt';
 
 // Configuration
 const TOKEN_REFRESH_THRESHOLD_MS = 10 * 60 * 1000; // 10 minutes before expiry
@@ -29,83 +40,42 @@ interface UseTokenRefreshOptions {
 }
 
 /**
- * Decode JWT and get expiry time
- */
-function getTokenExpiry(token: string): number | null {
-  try {
-    const payload = JSON.parse(atob(token.split('.')[1]));
-    return payload.exp * 1000; // Convert to milliseconds
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Check if token is expiring soon
- */
-function isTokenExpiringSoon(token: string, thresholdMs: number): boolean {
-  const expiry = getTokenExpiry(token);
-  if (!expiry) return false;
-
-  const timeUntilExpiry = expiry - Date.now();
-  return timeUntilExpiry < thresholdMs;
-}
-
-/**
- * Hook for automatic token refresh
+ * Hook for proactive automatic token refresh.
+ * (JWT expiry helpers live in ../utils/jwt so they can be unit-tested and
+ * reused by the auth-bootstrap validation path.)
  */
 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 +91,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/utils/jwt.ts

@@ -0,0 +1,66 @@
+/**
+ * JWT inspection helpers (browser-safe, dependency-free).
+ *
+ * These decode ONLY the `exp` claim to reason about token freshness on the
+ * client. They do NOT verify the signature — that is the server's job. The
+ * point is purely to avoid firing doomed requests with a token we can already
+ * see is malformed or expired, and to let auth bootstrap collapse a dead
+ * session to the login form instead of hanging on a preloader.
+ *
+ * A JWT that cannot be decoded is treated as EXPIRED/invalid (fail-closed):
+ * better to re-authenticate than to loop on 401s with garbage in storage.
+ */
+
+/** Base64url-decode a JWT segment. Returns null on any malformation. */
+function decodeSegment(segment: string): unknown {
+  try {
+    const base64 = segment.replace(/-/g, '+').replace(/_/g, '/');
+    // atob is defined in browsers and modern Node (global). Guard anyway.
+    if (typeof atob !== 'function') return null;
+    const json = atob(base64);
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract the `exp` claim (epoch ms), or null if the token is undecodable or
+ * has no numeric `exp`.
+ */
+export function getTokenExpiry(token: string | null | undefined): number | null {
+  if (!token || typeof token !== 'string') return null;
+  const parts = token.split('.');
+  if (parts.length !== 3) return null; // not a well-formed JWT
+  const payload = decodeSegment(parts[1]);
+  if (!payload || typeof payload !== 'object') return null;
+  const exp = (payload as { exp?: unknown }).exp;
+  if (typeof exp !== 'number' || !Number.isFinite(exp)) return null;
+  return exp * 1000;
+}
+
+/**
+ * True when the token is missing, malformed, or already past its `exp`.
+ * `skewMs` treats a token expiring within the skew window as already expired
+ * (default 0). Fail-closed: an undecodable token is considered expired.
+ */
+export function isTokenExpired(token: string | null | undefined, skewMs = 0, now = Date.now()): boolean {
+  const expiry = getTokenExpiry(token);
+  if (expiry === null) return true; // undecodable / no exp → treat as dead
+  return expiry - skewMs <= now;
+}
+
+/**
+ * True when a valid token exists but expires within `thresholdMs` (used by the
+ * proactive refresher). A missing/undecodable token returns false here — that
+ * case is handled by the "expired" path, not the "expiring soon" path.
+ */
+export function isTokenExpiringSoon(
+  token: string | null | undefined,
+  thresholdMs: number,
+  now = Date.now(),
+): boolean {
+  const expiry = getTokenExpiry(token);
+  if (expiry === null) return false;
+  return expiry - now < thresholdMs;
+}

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();
-  }
-}