@djangocfg/api 2.1.455 → 2.1.457

package/dist/auth.d.cts

@@ -16,6 +16,14 @@ declare const AUTH_CONSTANTS: {
     readonly BACKUP_CODE_MAX_LENGTH: 12;
 };
 
+type SessionStatus = 'authenticated' | 'anonymous';
+type SessionSnapshot = {
+    /** 'authenticated' = a live access token OR a live refresh token exists. */
+    status: SessionStatus;
+    /** ms-epoch expiry of the current access token (null: no token / no exp). */
+    accessExpiresAt: number | null;
+};
+
 /**
  * Nested serializer for Centrifugo WebSocket connection token.
  */
@@ -146,10 +154,6 @@ type PatchedCfgUserUpdateRequest = {
      */
     timezone?: string;
 };
-type TokenRefresh = {
-    readonly access: string;
-    refresh: string;
-};
 /**
  * Serializer for user details.
  */
@@ -439,11 +443,23 @@ interface AuthConfig {
     };
     onLogout?: () => void;
 }
+/**
+ * AuthConfig.routes resolved against the framework conventions — no field is
+ * optional here. This is what components consume (via `useAuth().routes`)
+ * instead of defaulting to route constants themselves.
+ */
+interface ResolvedAuthRoutes {
+    auth: string;
+    defaultCallback: string;
+    defaultAuthCallback: string;
+}
 interface AuthContextType {
     user: UserProfile | null;
     isLoading: boolean;
     isAuthenticated: boolean;
     isAdminUser: boolean;
+    /** Resolved route conventions (config override or framework default). */
+    routes: ResolvedAuthRoutes;
     loadCurrentProfile: (callerId?: string) => Promise<void>;
     checkAuthAndRedirect: () => Promise<void>;
     getToken: () => string | null;
@@ -488,15 +504,14 @@ declare const AuthContext: React$1.Context<AuthContextType>;
  * AuthProvider — wraps AccountsProvider + AuthProviderInternal.
  *
  * Memoised: re-renders only when `config` reference or `children` change.
- * Internal auth state is isolated inside AuthProviderInternal.
  */
 declare function AuthProviderRaw({ children, config, enabled }: AuthProviderProps): react_jsx_runtime.JSX.Element;
 declare const AuthProvider: React$1.MemoExoticComponent<typeof AuthProviderRaw>;
 /**
- * Hook to access auth context
+ * Hook to access auth context.
  *
- * SSR-safe: Returns default unauthenticated state when called outside AuthProvider
- * (e.g., during static page generation or server-side rendering)
+ * SSR-safe: returns default unauthenticated state when called outside
+ * AuthProvider (e.g. during static page generation).
  */
 declare const useAuth: () => AuthContextType;
 
@@ -523,7 +538,6 @@ interface AccountsContextValue {
     }) => Promise<User | undefined>;
     requestOTP: (data: OtpRequestRequest) => Promise<OtpRequestResponse>;
     verifyOTP: (data: OtpVerifyRequest) => Promise<OtpVerifyResponse>;
-    refreshToken: (refresh: string) => Promise<TokenRefresh>;
     logout: () => void;
 }
 interface AccountsProviderProps {
@@ -532,6 +546,8 @@ interface AccountsProviderProps {
 declare function AccountsProvider({ children }: AccountsProviderProps): react_jsx_runtime.JSX.Element;
 declare function useAccountsContext(): AccountsContextValue;
 
+declare function useSession(): SessionSnapshot;
+
 /**
  * Universal Router Hook with BasePath Support
  *
@@ -841,6 +857,17 @@ interface AuthRedirectOptions {
     fallbackUrl?: string;
     clearOnUse?: boolean;
 }
+/**
+ * Read the saved back-url without clearing it. Null when nothing saved —
+ * unlike getFinalRedirectUrl, never substitutes a fallback.
+ */
+declare const peekSavedRedirect: () => string | null;
+/**
+ * Read AND clear the saved back-url (single-use intent). Null when nothing
+ * saved. This is the one primitive every post-auth navigator uses to honor
+ * "return the user to where the guard bounced them from".
+ */
+declare const consumeSavedRedirect: () => string | null;
 declare const useAuthRedirectManager: (options?: AuthRedirectOptions) => {
     redirectUrl: string;
     setRedirect: (url: string) => void;
@@ -851,18 +878,6 @@ declare const useAuthRedirectManager: (options?: AuthRedirectOptions) => {
     useAndClearRedirect: () => string;
 };
 
-interface UseAuthGuardOptions {
-    redirectTo?: string;
-    requireAuth?: boolean;
-    /** Whether to save current URL for redirect after auth (default: true) */
-    saveRedirectUrl?: boolean;
-}
-declare const useAuthGuard: (options?: UseAuthGuardOptions) => {
-    isAuthenticated: boolean;
-    isLoading: boolean;
-    isRedirecting: boolean;
-};
-
 /**
  * Simple sessionStorage hook with better error handling
  * @param key - Storage key
@@ -943,24 +958,6 @@ declare function getCacheMetadata(): {
     expiresIn?: number;
 } | null;
 
-interface UseTokenRefreshOptions {
-    /** Enable automatic token refresh (default: true) */
-    enabled?: boolean;
-    /** Callback when token is refreshed */
-    onRefresh?: (newToken: string) => void;
-    /** Callback when refresh fails */
-    onRefreshError?: (error: Error) => void;
-}
-/**
- * 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.)
- */
-declare function useTokenRefresh(options?: UseTokenRefreshOptions): {
-    refreshToken: () => Promise<boolean>;
-    checkAndRefresh: () => Promise<void>;
-};
-
 interface DeleteAccountResult {
     success: boolean;
     message: string;
@@ -1044,48 +1041,6 @@ declare function resolveGuardIsLoading(s: GuardInput): boolean;
 declare function shouldRedirectToAuth(s: GuardInput): boolean;
 /** The effective authenticated flag the guard exposes to consumers. */
 declare function resolveGuardIsAuthenticated(s: Pick<GuardInput, 'requireAuth' | 'isAuthenticated'>): boolean;
-/**
- * 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.
- */
-declare function nextAuthEvaluationDelay(accessExp: number | null, refreshExp: number | null, now: number): number | null;
-
-/**
- * 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.
- */
-/**
- * Extract the `exp` claim (epoch ms), or null if the token is undecodable or
- * has no numeric `exp`.
- */
-declare function getTokenExpiry(token: string | null | undefined): number | null;
-/**
- * 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.
- */
-declare function isTokenExpired(token: string | null | undefined, skewMs?: number, now?: number): boolean;
-/**
- * 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.
- */
-declare function isTokenExpiringSoon(token: string | null | undefined, thresholdMs: number, now?: number): boolean;
 
 /**
  * Path normalization for auth routing.
@@ -1156,4 +1111,4 @@ declare const Analytics: {
     setUser(userId: string): void;
 };
 
-export { AUTH_CONSTANTS, type AccountsContextValue, AccountsProvider, Analytics, AnalyticsCategory, type AnalyticsCategoryType, AnalyticsEvent, type AnalyticsEventType, type AuthConfig, AuthContext, type AuthContextType, type AuthFormAutoSubmit, type AuthFormReturn, type AuthFormState, type AuthFormStateHandlers, type AuthFormSubmitHandlers, type AuthFormValidation, AuthProvider, type AuthProviderProps, type AuthStep, type DeleteAccountResult, type GuardInput, type OTPRequestResult, type PatchedCfgUserUpdateRequest, PatchedCfgUserUpdateRequestSchema, type ProfileCacheOptions, type TwoFactorDevice, type TwoFactorSetupData, type UseAuthFormOptions, type UseAuthFormStateReturn, type UseAutoAuthOptions, type UseDeleteAccountReturn, type UseGithubAuthOptions, type UseGithubAuthReturn, type UseTwoFactorOptions, type UseTwoFactorReturn, type UseTwoFactorSetupOptions, type UseTwoFactorSetupReturn, type UseTwoFactorStatusReturn, type UserProfile, type WebmailLink, authLogger, clearProfileCache, decodeBase64, encodeBase64, formatAuthError, getCacheMetadata, getCachedProfile, getTokenExpiry, hasValidCache, isAllowedAuthPath, isTokenExpired, isTokenExpiringSoon, logger, nextAuthEvaluationDelay, normalizePath, resolveGuardIsAuthenticated, resolveGuardIsLoading, setCachedProfile, shouldRedirectToAuth, useAccountsContext, useAuth, useAuthForm, useAuthFormState, useAuthGuard, useAuthRedirectManager, useAuthValidation, useAutoAuth, useBase64, useCfgRouter, useDeleteAccount, useGithubAuth, useLocalStorage, useQueryParams, useSessionStorage, useTokenRefresh, useTwoFactor, useTwoFactorSetup, useTwoFactorStatus, validateEmail, validateIdentifier };
+export { AUTH_CONSTANTS, type AccountsContextValue, AccountsProvider, Analytics, AnalyticsCategory, type AnalyticsCategoryType, AnalyticsEvent, type AnalyticsEventType, type AuthConfig, AuthContext, type AuthContextType, type AuthFormAutoSubmit, type AuthFormReturn, type AuthFormState, type AuthFormStateHandlers, type AuthFormSubmitHandlers, type AuthFormValidation, AuthProvider, type AuthProviderProps, type AuthStep, type DeleteAccountResult, type GuardInput, type OTPRequestResult, type PatchedCfgUserUpdateRequest, PatchedCfgUserUpdateRequestSchema, type ProfileCacheOptions, type SessionSnapshot, type SessionStatus, type TwoFactorDevice, type TwoFactorSetupData, type UseAuthFormOptions, type UseAuthFormStateReturn, type UseAutoAuthOptions, type UseDeleteAccountReturn, type UseGithubAuthOptions, type UseGithubAuthReturn, type UseTwoFactorOptions, type UseTwoFactorReturn, type UseTwoFactorSetupOptions, type UseTwoFactorSetupReturn, type UseTwoFactorStatusReturn, type UserProfile, type WebmailLink, authLogger, clearProfileCache, consumeSavedRedirect, decodeBase64, encodeBase64, formatAuthError, getCacheMetadata, getCachedProfile, hasValidCache, isAllowedAuthPath, logger, normalizePath, peekSavedRedirect, resolveGuardIsAuthenticated, resolveGuardIsLoading, setCachedProfile, shouldRedirectToAuth, useAccountsContext, useAuth, useAuthForm, useAuthFormState, useAuthRedirectManager, useAuthValidation, useAutoAuth, useBase64, useCfgRouter, useDeleteAccount, useGithubAuth, useLocalStorage, useQueryParams, useSession, useSessionStorage, useTwoFactor, useTwoFactorSetup, useTwoFactorStatus, validateEmail, validateIdentifier };

package/dist/auth.d.ts

@@ -16,6 +16,14 @@ declare const AUTH_CONSTANTS: {
     readonly BACKUP_CODE_MAX_LENGTH: 12;
 };
 
+type SessionStatus = 'authenticated' | 'anonymous';
+type SessionSnapshot = {
+    /** 'authenticated' = a live access token OR a live refresh token exists. */
+    status: SessionStatus;
+    /** ms-epoch expiry of the current access token (null: no token / no exp). */
+    accessExpiresAt: number | null;
+};
+
 /**
  * Nested serializer for Centrifugo WebSocket connection token.
  */
@@ -146,10 +154,6 @@ type PatchedCfgUserUpdateRequest = {
      */
     timezone?: string;
 };
-type TokenRefresh = {
-    readonly access: string;
-    refresh: string;
-};
 /**
  * Serializer for user details.
  */
@@ -439,11 +443,23 @@ interface AuthConfig {
     };
     onLogout?: () => void;
 }
+/**
+ * AuthConfig.routes resolved against the framework conventions — no field is
+ * optional here. This is what components consume (via `useAuth().routes`)
+ * instead of defaulting to route constants themselves.
+ */
+interface ResolvedAuthRoutes {
+    auth: string;
+    defaultCallback: string;
+    defaultAuthCallback: string;
+}
 interface AuthContextType {
     user: UserProfile | null;
     isLoading: boolean;
     isAuthenticated: boolean;
     isAdminUser: boolean;
+    /** Resolved route conventions (config override or framework default). */
+    routes: ResolvedAuthRoutes;
     loadCurrentProfile: (callerId?: string) => Promise<void>;
     checkAuthAndRedirect: () => Promise<void>;
     getToken: () => string | null;
@@ -488,15 +504,14 @@ declare const AuthContext: React$1.Context<AuthContextType>;
  * AuthProvider — wraps AccountsProvider + AuthProviderInternal.
  *
  * Memoised: re-renders only when `config` reference or `children` change.
- * Internal auth state is isolated inside AuthProviderInternal.
  */
 declare function AuthProviderRaw({ children, config, enabled }: AuthProviderProps): react_jsx_runtime.JSX.Element;
 declare const AuthProvider: React$1.MemoExoticComponent<typeof AuthProviderRaw>;
 /**
- * Hook to access auth context
+ * Hook to access auth context.
  *
- * SSR-safe: Returns default unauthenticated state when called outside AuthProvider
- * (e.g., during static page generation or server-side rendering)
+ * SSR-safe: returns default unauthenticated state when called outside
+ * AuthProvider (e.g. during static page generation).
  */
 declare const useAuth: () => AuthContextType;
 
@@ -523,7 +538,6 @@ interface AccountsContextValue {
     }) => Promise<User | undefined>;
     requestOTP: (data: OtpRequestRequest) => Promise<OtpRequestResponse>;
     verifyOTP: (data: OtpVerifyRequest) => Promise<OtpVerifyResponse>;
-    refreshToken: (refresh: string) => Promise<TokenRefresh>;
     logout: () => void;
 }
 interface AccountsProviderProps {
@@ -532,6 +546,8 @@ interface AccountsProviderProps {
 declare function AccountsProvider({ children }: AccountsProviderProps): react_jsx_runtime.JSX.Element;
 declare function useAccountsContext(): AccountsContextValue;
 
+declare function useSession(): SessionSnapshot;
+
 /**
  * Universal Router Hook with BasePath Support
  *
@@ -841,6 +857,17 @@ interface AuthRedirectOptions {
     fallbackUrl?: string;
     clearOnUse?: boolean;
 }
+/**
+ * Read the saved back-url without clearing it. Null when nothing saved —
+ * unlike getFinalRedirectUrl, never substitutes a fallback.
+ */
+declare const peekSavedRedirect: () => string | null;
+/**
+ * Read AND clear the saved back-url (single-use intent). Null when nothing
+ * saved. This is the one primitive every post-auth navigator uses to honor
+ * "return the user to where the guard bounced them from".
+ */
+declare const consumeSavedRedirect: () => string | null;
 declare const useAuthRedirectManager: (options?: AuthRedirectOptions) => {
     redirectUrl: string;
     setRedirect: (url: string) => void;
@@ -851,18 +878,6 @@ declare const useAuthRedirectManager: (options?: AuthRedirectOptions) => {
     useAndClearRedirect: () => string;
 };
 
-interface UseAuthGuardOptions {
-    redirectTo?: string;
-    requireAuth?: boolean;
-    /** Whether to save current URL for redirect after auth (default: true) */
-    saveRedirectUrl?: boolean;
-}
-declare const useAuthGuard: (options?: UseAuthGuardOptions) => {
-    isAuthenticated: boolean;
-    isLoading: boolean;
-    isRedirecting: boolean;
-};
-
 /**
  * Simple sessionStorage hook with better error handling
  * @param key - Storage key
@@ -943,24 +958,6 @@ declare function getCacheMetadata(): {
     expiresIn?: number;
 } | null;
 
-interface UseTokenRefreshOptions {
-    /** Enable automatic token refresh (default: true) */
-    enabled?: boolean;
-    /** Callback when token is refreshed */
-    onRefresh?: (newToken: string) => void;
-    /** Callback when refresh fails */
-    onRefreshError?: (error: Error) => void;
-}
-/**
- * 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.)
- */
-declare function useTokenRefresh(options?: UseTokenRefreshOptions): {
-    refreshToken: () => Promise<boolean>;
-    checkAndRefresh: () => Promise<void>;
-};
-
 interface DeleteAccountResult {
     success: boolean;
     message: string;
@@ -1044,48 +1041,6 @@ declare function resolveGuardIsLoading(s: GuardInput): boolean;
 declare function shouldRedirectToAuth(s: GuardInput): boolean;
 /** The effective authenticated flag the guard exposes to consumers. */
 declare function resolveGuardIsAuthenticated(s: Pick<GuardInput, 'requireAuth' | 'isAuthenticated'>): boolean;
-/**
- * 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.
- */
-declare function nextAuthEvaluationDelay(accessExp: number | null, refreshExp: number | null, now: number): number | null;
-
-/**
- * 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.
- */
-/**
- * Extract the `exp` claim (epoch ms), or null if the token is undecodable or
- * has no numeric `exp`.
- */
-declare function getTokenExpiry(token: string | null | undefined): number | null;
-/**
- * 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.
- */
-declare function isTokenExpired(token: string | null | undefined, skewMs?: number, now?: number): boolean;
-/**
- * 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.
- */
-declare function isTokenExpiringSoon(token: string | null | undefined, thresholdMs: number, now?: number): boolean;
 
 /**
  * Path normalization for auth routing.
@@ -1156,4 +1111,4 @@ declare const Analytics: {
     setUser(userId: string): void;
 };
 
-export { AUTH_CONSTANTS, type AccountsContextValue, AccountsProvider, Analytics, AnalyticsCategory, type AnalyticsCategoryType, AnalyticsEvent, type AnalyticsEventType, type AuthConfig, AuthContext, type AuthContextType, type AuthFormAutoSubmit, type AuthFormReturn, type AuthFormState, type AuthFormStateHandlers, type AuthFormSubmitHandlers, type AuthFormValidation, AuthProvider, type AuthProviderProps, type AuthStep, type DeleteAccountResult, type GuardInput, type OTPRequestResult, type PatchedCfgUserUpdateRequest, PatchedCfgUserUpdateRequestSchema, type ProfileCacheOptions, type TwoFactorDevice, type TwoFactorSetupData, type UseAuthFormOptions, type UseAuthFormStateReturn, type UseAutoAuthOptions, type UseDeleteAccountReturn, type UseGithubAuthOptions, type UseGithubAuthReturn, type UseTwoFactorOptions, type UseTwoFactorReturn, type UseTwoFactorSetupOptions, type UseTwoFactorSetupReturn, type UseTwoFactorStatusReturn, type UserProfile, type WebmailLink, authLogger, clearProfileCache, decodeBase64, encodeBase64, formatAuthError, getCacheMetadata, getCachedProfile, getTokenExpiry, hasValidCache, isAllowedAuthPath, isTokenExpired, isTokenExpiringSoon, logger, nextAuthEvaluationDelay, normalizePath, resolveGuardIsAuthenticated, resolveGuardIsLoading, setCachedProfile, shouldRedirectToAuth, useAccountsContext, useAuth, useAuthForm, useAuthFormState, useAuthGuard, useAuthRedirectManager, useAuthValidation, useAutoAuth, useBase64, useCfgRouter, useDeleteAccount, useGithubAuth, useLocalStorage, useQueryParams, useSessionStorage, useTokenRefresh, useTwoFactor, useTwoFactorSetup, useTwoFactorStatus, validateEmail, validateIdentifier };
+export { AUTH_CONSTANTS, type AccountsContextValue, AccountsProvider, Analytics, AnalyticsCategory, type AnalyticsCategoryType, AnalyticsEvent, type AnalyticsEventType, type AuthConfig, AuthContext, type AuthContextType, type AuthFormAutoSubmit, type AuthFormReturn, type AuthFormState, type AuthFormStateHandlers, type AuthFormSubmitHandlers, type AuthFormValidation, AuthProvider, type AuthProviderProps, type AuthStep, type DeleteAccountResult, type GuardInput, type OTPRequestResult, type PatchedCfgUserUpdateRequest, PatchedCfgUserUpdateRequestSchema, type ProfileCacheOptions, type SessionSnapshot, type SessionStatus, type TwoFactorDevice, type TwoFactorSetupData, type UseAuthFormOptions, type UseAuthFormStateReturn, type UseAutoAuthOptions, type UseDeleteAccountReturn, type UseGithubAuthOptions, type UseGithubAuthReturn, type UseTwoFactorOptions, type UseTwoFactorReturn, type UseTwoFactorSetupOptions, type UseTwoFactorSetupReturn, type UseTwoFactorStatusReturn, type UserProfile, type WebmailLink, authLogger, clearProfileCache, consumeSavedRedirect, decodeBase64, encodeBase64, formatAuthError, getCacheMetadata, getCachedProfile, hasValidCache, isAllowedAuthPath, logger, normalizePath, peekSavedRedirect, resolveGuardIsAuthenticated, resolveGuardIsLoading, setCachedProfile, shouldRedirectToAuth, useAccountsContext, useAuth, useAuthForm, useAuthFormState, useAuthRedirectManager, useAuthValidation, useAutoAuth, useBase64, useCfgRouter, useDeleteAccount, useGithubAuth, useLocalStorage, useQueryParams, useSession, useSessionStorage, useTwoFactor, useTwoFactorSetup, useTwoFactorStatus, validateEmail, validateIdentifier };