@djangocfg/api 2.1.449 → 2.1.452

package/src/auth/hooks/useTokenRefresh.ts

@@ -24,6 +24,7 @@ import { useCallback, useEffect } from 'react';
 import { api as apiAccounts } from '../../';
 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
@@ -38,29 +39,10 @@ interface UseTokenRefreshOptions {
   onRefreshError?: (error: Error) => void;
 }
 
-/**
- * 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;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Check if token is expiring within the threshold.
- */
-function isTokenExpiringSoon(token: string, thresholdMs: number): boolean {
-  const expiry = getTokenExpiry(token);
-  if (!expiry) return false;
-  return expiry - Date.now() < thresholdMs;
-}
-
 /**
  * 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;

package/src/auth/utils/guard.ts

@@ -0,0 +1,79 @@
+/**
+ * Pure auth-guard state resolution.
+ *
+ * This is the decision that produced the "stuck on Authenticating…" bug: given
+ * the auth state, should the UI show a preloader, redirect to login, or render
+ * the protected content? Extracted from useAuthGuard (which lives in a package
+ * with no test infra) so the branching can be unit-tested in isolation — the
+ * hook just wires React state (mounted / isRedirecting) into these functions.
+ *
+ * Invariant that fixes the bug: once auth is resolved (`authLoading === false`)
+ * and the user is unauthenticated, `isLoading` must become false so the guard
+ * redirects to the form instead of spinning forever.
+ */
+
+export interface GuardInput {
+  /** First client render matches SSR (preloader) until mounted, to avoid hydration mismatch. */
+  mounted: boolean;
+  /** Whether this route requires authentication. */
+  requireAuth: boolean;
+  /** AuthContext still resolving initial state. */
+  authLoading: boolean;
+  /** A redirect to the auth page is in flight. */
+  isRedirecting: boolean;
+  /** User currently has a (valid-looking) session. */
+  isAuthenticated: boolean;
+}
+
+/**
+ * True while the guard should render a preloader rather than the protected
+ * content. Mirrors useAuthGuard's formula exactly.
+ */
+export function resolveGuardIsLoading(s: GuardInput): boolean {
+  if (!s.mounted) return true; // pre-hydration: always preloader
+  if (!s.requireAuth) return false; // public route: never blocks
+  return s.authLoading || s.isRedirecting || !s.isAuthenticated;
+}
+
+/**
+ * Whether the guard should trigger a redirect to the auth page. Only once
+ * mounted, on a protected route, after auth resolved, when unauthenticated and
+ * not already redirecting. This is the branch that must fire for a dead session.
+ */
+export function shouldRedirectToAuth(s: GuardInput): boolean {
+  return (
+    s.mounted &&
+    s.requireAuth &&
+    !s.authLoading &&
+    !s.isAuthenticated &&
+    !s.isRedirecting
+  );
+}
+
+/** The effective authenticated flag the guard exposes to consumers. */
+export function resolveGuardIsAuthenticated(s: Pick<GuardInput, 'requireAuth' | 'isAuthenticated'>): boolean {
+  return !s.requireAuth || s.isAuthenticated;
+}
+
+/**
+ * Delay (ms from `now`) until `isAuthenticated` should next be re-evaluated,
+ * given the access/refresh expiry timestamps (ms epoch, or null if absent).
+ *
+ * `isAuthenticated` is derived from token `exp`, so it can change with no event
+ * to trigger a recompute — a tab left open silently crosses an expiry boundary.
+ * We schedule a wake-up at the SOONEST future expiry (the next moment the answer
+ * could flip), plus a 1s cushion so we re-check strictly after the inclusive
+ * boundary. Returns null when nothing live remains to expire (no timer needed).
+ * Callers should clamp the result to the platform setTimeout ceiling.
+ */
+export function nextAuthEvaluationDelay(
+  accessExp: number | null,
+  refreshExp: number | null,
+  now: number,
+): number | null {
+  const future = [accessExp, refreshExp].filter(
+    (d): d is number => d !== null && d > now,
+  );
+  if (future.length === 0) return null;
+  return Math.max(0, Math.min(...future) - now) + 1000;
+}

package/src/auth/utils/index.ts

@@ -1,5 +1,14 @@
 export { validateEmail } from './validation';
 export { formatAuthError } from './errors';
+export {
+  resolveGuardIsLoading,
+  shouldRedirectToAuth,
+  resolveGuardIsAuthenticated,
+  nextAuthEvaluationDelay,
+  type GuardInput,
+} from './guard';
+export { getTokenExpiry, isTokenExpired, isTokenExpiringSoon } from './jwt';
+export { normalizePath, isAllowedAuthPath } from './path';
 export { logger, authLogger } from './logger';
 export {
   Analytics,

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/utils/path.ts

@@ -0,0 +1,34 @@
+/**
+ * Path normalization for auth routing.
+ *
+ * next-intl may keep a 2-letter locale prefix in the URL (e.g. `/ru/auth`), and
+ * paths arrive with or without trailing slashes. To match a pathname against a
+ * fixed allow-list (like `['/auth']`) reliably, strip the locale segment and
+ * trailing slashes first. Extracted from useAutoAuth so it can be unit-tested
+ * and reused.
+ */
+
+/**
+ * Strip a leading 2-letter locale segment and trailing slashes.
+ * '/ru/auth/' → '/auth', '/auth' → '/auth', '/' → '/', '' → ''.
+ */
+export const normalizePath = (path: string | null | undefined): string => {
+  if (!path) return '';
+  const withoutLocale = path.replace(/^\/[a-z]{2}(?=\/|$)/, '');
+  const trimmed = withoutLocale.replace(/\/+$/, '');
+  return trimmed || '/';
+};
+
+/**
+ * True when `pathname` (after locale/slash normalization) is one of the allowed
+ * paths, or nested under one of them (`/auth` matches `/auth/callback`).
+ */
+export const isAllowedAuthPath = (
+  pathname: string | null | undefined,
+  allowedPaths: string[],
+): boolean => {
+  const normalized = normalizePath(pathname);
+  return allowedPaths.some(
+    (p) => normalized === p || normalized.startsWith(p + '/'),
+  );
+};