@djangocfg/api 2.1.619 → 2.1.622

package/dist/auth.d.cts

@@ -17,6 +17,53 @@ declare const AUTH_CONSTANTS: {
     readonly RESEND_COOLDOWN_SECONDS: 30;
 };
 
+/**
+ * Auth trace: a persisted record of what the auth layer did, readable after any reload or redirect.
+ *
+ * Why storage and not `window`: a sign-in problem usually ends in a reload or a redirect, which throws away
+ * everything held in memory and in the console. The events live in `localStorage` (falling back to
+ * `sessionStorage`, then memory), so the next page can still print them. `window.__cfgAuth` is only the reader.
+ *
+ * Read it in the browser console, on any page of the origin, even after the redirect:
+ *
+ *   __cfgAuth.dump()    // copy-ready text with a header; paste it into the report
+ *   __cfgAuth.trace()   // the raw array
+ *   __cfgAuth.clear()   // empty it before reproducing
+ *   __cfgAuth.copy()    // dump to the clipboard; __cfgAuth.download() saves the raw JSON
+ *
+ * What is recorded is the decision, never the secret: no token, code, address, cookie value or password.
+ * Values are primitives, strings are cut, and keys that look sensitive are dropped (`SENSITIVE`).
+ */
+type Primitive = string | number | boolean | null;
+type TraceFields = Record<string, Primitive>;
+interface TraceEntry {
+    /** Wall clock, ms since epoch. */
+    t: number;
+    /** ms since this page started (`performance.now()`), so a reload shows as the counter restarting. */
+    p: number;
+    /** Short random id of this page load: one sequence, several loads, told apart by this. */
+    tab: string;
+    ev: string;
+    f?: TraceFields;
+    /** Times this exact event repeated back to back (absent = once). A loop must not push the start of the chain out of the buffer. */
+    n?: number;
+}
+/** Record one auth event. Safe anywhere: it never throws and does nothing on the server. */
+declare function authTrace(ev: string, fields?: TraceFields): void;
+/** The recorded events, oldest first. */
+/** @internal for tests */
+declare function resetAuthTraceForTests(): void;
+declare function readAuthTrace(): TraceEntry[];
+/** Empty the trace. */
+declare function clearAuthTrace(): void;
+/** Copy-ready text: a short header, then one line per event. Reloads show as a new `[tab]`. */
+declare function dumpAuthTrace(): string;
+/**
+ * Install the reader. Called once from the package entry; idempotent across copies of this module.
+ * The generated auth store forwards through `globalThis.__cfgAuthTrace` and queues until this runs.
+ */
+declare function installAuthTrace(): void;
+
 type SessionStatus = 'authenticated' | 'anonymous';
 type SessionSnapshot = {
     /** 'authenticated' = a live access token OR a live refresh token exists. */
@@ -691,6 +738,8 @@ interface ResolvedAuthRoutes {
 interface AuthContextType {
     user: UserProfile | null;
     isLoading: boolean;
+    /** The one linear auth state: 'resolving' until the client has read the session and its profile, then 'authenticated' or 'anonymous'. */
+    status: 'resolving' | 'authenticated' | 'anonymous';
     isAuthenticated: boolean;
     isAdminUser: boolean;
     /** Resolved route conventions (config override or framework default). */
@@ -1456,6 +1505,35 @@ declare const normalizePath: (path: string | null | undefined) => string;
  */
 declare const isAllowedAuthPath: (pathname: string | null | undefined, allowedPaths: string[]) => boolean;
 
+/**
+ * The one auth state: a single value answers "may this page render?".
+ *
+ *   resolving      the client has not read the session yet, or a live session is still loading its profile
+ *   authenticated  a live session and its profile settled
+ *   anonymous      no session (store and React snapshot agree)
+ *
+ * Every consumer (the page guard, the "leave /auth" effect, the trace) reads this and nothing else. The
+ * inputs are plain booleans so the whole table is unit-tested.
+ *
+ * Termination: `resolving` is left in finite time. `timedOut` is set by one timer in the provider, and
+ * when it fires the React snapshot decides. There is no input combination that stays `resolving` with
+ * `timedOut` true.
+ */
+type AuthStatus = 'resolving' | 'authenticated' | 'anonymous';
+interface AuthStateInput {
+    /** The first client effect has run (the hydration commit is over). */
+    clientReady: boolean;
+    /** `useSession()` says authenticated (the React snapshot; the server snapshot is always anonymous). */
+    snapshotAuthenticated: boolean;
+    /** `auth.isAuthenticated()` read straight from the store at this render. */
+    storeAuthenticated: boolean;
+    /** The profile for a live session has loaded, failed in a way that keeps the session, or was cached. */
+    profileSettled: boolean;
+    /** The provider's single safety timer fired. */
+    timedOut: boolean;
+}
+declare function resolveAuthStatus(s: AuthStateInput): AuthStatus;
+
 declare const logger: consola.ConsolaInstance;
 /**
  * Auth-specific logger
@@ -1531,5 +1609,5 @@ declare const Analytics: {
     setUser(userId: string | null): void;
 };
 
-export { AUTH_CONSTANTS, AUTH_ERROR_KEYS, AccountsProvider, Analytics, AnalyticsCategory, AnalyticsEvent, AuthContext, AuthProvider, OAUTH_PROVIDER_IDS, authLogger, beginTwoFactorChallenge, clearOAuthAttempt, clearProfileCache, consumeSavedRedirect, decodeBase64, encodeBase64, endTwoFactorChallenge, formatAuthError, getCacheMetadata, getCachedProfile, hasValidCache, isAllowedAuthPath, isForbidden, isOAuthProviderId, logAuthFailure, logger, normalizePath, peekSavedRedirect, readOAuthFailure, resolveAuthError, resolveGuardIsAuthenticated, resolveGuardIsLoading, setAnalyticsSink, setCachedProfile, shouldRedirectToAuth, useAccountsContext, useAuth, useAuthForm, useAuthFormState, useAuthRedirectManager, useAuthValidation, useAutoAuth, useBase64, useCfgRouter, useDeleteAccount, useGithubAuth, useLocalStorage, useOAuthLogin, useOAuthProviders, useQueryParams, useSession, useSessionStorage, useTimezone, useTwoFactor, useTwoFactorChallenge, useTwoFactorSetup, useTwoFactorStatus, useTwoFactorVerify, validateEmail, validateIdentifier };
-export type { AccountsContextValue, AnalyticsCategoryType, AnalyticsEventType, AnalyticsSink, AuthConfig, AuthContextType, AuthErrorCopy, AuthErrorKey, AuthFormAutoSubmit, AuthFormReturn, AuthFormState, AuthFormStateHandlers, AuthFormSubmitHandlers, AuthFormValidation, AuthProviderProps, AuthStep, DeleteAccountResult, GuardInput, OAuthClientErrorCode, OAuthErrorCode, OAuthFailure, OAuthFailureCode, OAuthProviderId, OAuthUser, OTPRequestConsent, OTPRequestResult, PasswordLoginOptions, PasswordLoginResult, PatchedCfgUserUpdateRequest, ProfileCacheOptions, SessionSnapshot, SessionStatus, TwoFactorChallenge, TwoFactorDevice, TwoFactorSetupData, UseAuthFormOptions, UseAuthFormStateReturn, UseAutoAuthOptions, UseDeleteAccountReturn, UseGithubAuthOptions, UseGithubAuthReturn, UseOAuthLoginOptions, UseOAuthLoginReturn, UseOAuthProvidersReturn, UseTimezoneReturn, UseTwoFactorOptions, UseTwoFactorReturn, UseTwoFactorSetupOptions, UseTwoFactorSetupReturn, UseTwoFactorStatusReturn, UseTwoFactorVerifyOptions, UseTwoFactorVerifyReturn, UserProfile, WebmailLink };
+export { AUTH_CONSTANTS, AUTH_ERROR_KEYS, AccountsProvider, Analytics, AnalyticsCategory, AnalyticsEvent, AuthContext, AuthProvider, OAUTH_PROVIDER_IDS, authLogger, authTrace, beginTwoFactorChallenge, clearAuthTrace, clearOAuthAttempt, clearProfileCache, consumeSavedRedirect, decodeBase64, dumpAuthTrace, encodeBase64, endTwoFactorChallenge, formatAuthError, getCacheMetadata, getCachedProfile, hasValidCache, installAuthTrace, isAllowedAuthPath, isForbidden, isOAuthProviderId, logAuthFailure, logger, normalizePath, peekSavedRedirect, readAuthTrace, readOAuthFailure, resetAuthTraceForTests, resolveAuthError, resolveAuthStatus, resolveGuardIsAuthenticated, resolveGuardIsLoading, setAnalyticsSink, setCachedProfile, shouldRedirectToAuth, useAccountsContext, useAuth, useAuthForm, useAuthFormState, useAuthRedirectManager, useAuthValidation, useAutoAuth, useBase64, useCfgRouter, useDeleteAccount, useGithubAuth, useLocalStorage, useOAuthLogin, useOAuthProviders, useQueryParams, useSession, useSessionStorage, useTimezone, useTwoFactor, useTwoFactorChallenge, useTwoFactorSetup, useTwoFactorStatus, useTwoFactorVerify, validateEmail, validateIdentifier };
+export type { AccountsContextValue, AnalyticsCategoryType, AnalyticsEventType, AnalyticsSink, AuthConfig, AuthContextType, AuthErrorCopy, AuthErrorKey, AuthFormAutoSubmit, AuthFormReturn, AuthFormState, AuthFormStateHandlers, AuthFormSubmitHandlers, AuthFormValidation, AuthProviderProps, AuthStateInput, AuthStatus, AuthStep, DeleteAccountResult, GuardInput, OAuthClientErrorCode, OAuthErrorCode, OAuthFailure, OAuthFailureCode, OAuthProviderId, OAuthUser, OTPRequestConsent, OTPRequestResult, PasswordLoginOptions, PasswordLoginResult, PatchedCfgUserUpdateRequest, ProfileCacheOptions, SessionSnapshot, SessionStatus, TraceEntry, TraceFields, TwoFactorChallenge, TwoFactorDevice, TwoFactorSetupData, UseAuthFormOptions, UseAuthFormStateReturn, UseAutoAuthOptions, UseDeleteAccountReturn, UseGithubAuthOptions, UseGithubAuthReturn, UseOAuthLoginOptions, UseOAuthLoginReturn, UseOAuthProvidersReturn, UseTimezoneReturn, UseTwoFactorOptions, UseTwoFactorReturn, UseTwoFactorSetupOptions, UseTwoFactorSetupReturn, UseTwoFactorStatusReturn, UseTwoFactorVerifyOptions, UseTwoFactorVerifyReturn, UserProfile, WebmailLink };

package/dist/auth.d.ts

@@ -17,6 +17,53 @@ declare const AUTH_CONSTANTS: {
     readonly RESEND_COOLDOWN_SECONDS: 30;
 };
 
+/**
+ * Auth trace: a persisted record of what the auth layer did, readable after any reload or redirect.
+ *
+ * Why storage and not `window`: a sign-in problem usually ends in a reload or a redirect, which throws away
+ * everything held in memory and in the console. The events live in `localStorage` (falling back to
+ * `sessionStorage`, then memory), so the next page can still print them. `window.__cfgAuth` is only the reader.
+ *
+ * Read it in the browser console, on any page of the origin, even after the redirect:
+ *
+ *   __cfgAuth.dump()    // copy-ready text with a header; paste it into the report
+ *   __cfgAuth.trace()   // the raw array
+ *   __cfgAuth.clear()   // empty it before reproducing
+ *   __cfgAuth.copy()    // dump to the clipboard; __cfgAuth.download() saves the raw JSON
+ *
+ * What is recorded is the decision, never the secret: no token, code, address, cookie value or password.
+ * Values are primitives, strings are cut, and keys that look sensitive are dropped (`SENSITIVE`).
+ */
+type Primitive = string | number | boolean | null;
+type TraceFields = Record<string, Primitive>;
+interface TraceEntry {
+    /** Wall clock, ms since epoch. */
+    t: number;
+    /** ms since this page started (`performance.now()`), so a reload shows as the counter restarting. */
+    p: number;
+    /** Short random id of this page load: one sequence, several loads, told apart by this. */
+    tab: string;
+    ev: string;
+    f?: TraceFields;
+    /** Times this exact event repeated back to back (absent = once). A loop must not push the start of the chain out of the buffer. */
+    n?: number;
+}
+/** Record one auth event. Safe anywhere: it never throws and does nothing on the server. */
+declare function authTrace(ev: string, fields?: TraceFields): void;
+/** The recorded events, oldest first. */
+/** @internal for tests */
+declare function resetAuthTraceForTests(): void;
+declare function readAuthTrace(): TraceEntry[];
+/** Empty the trace. */
+declare function clearAuthTrace(): void;
+/** Copy-ready text: a short header, then one line per event. Reloads show as a new `[tab]`. */
+declare function dumpAuthTrace(): string;
+/**
+ * Install the reader. Called once from the package entry; idempotent across copies of this module.
+ * The generated auth store forwards through `globalThis.__cfgAuthTrace` and queues until this runs.
+ */
+declare function installAuthTrace(): void;
+
 type SessionStatus = 'authenticated' | 'anonymous';
 type SessionSnapshot = {
     /** 'authenticated' = a live access token OR a live refresh token exists. */
@@ -691,6 +738,8 @@ interface ResolvedAuthRoutes {
 interface AuthContextType {
     user: UserProfile | null;
     isLoading: boolean;
+    /** The one linear auth state: 'resolving' until the client has read the session and its profile, then 'authenticated' or 'anonymous'. */
+    status: 'resolving' | 'authenticated' | 'anonymous';
     isAuthenticated: boolean;
     isAdminUser: boolean;
     /** Resolved route conventions (config override or framework default). */
@@ -1456,6 +1505,35 @@ declare const normalizePath: (path: string | null | undefined) => string;
  */
 declare const isAllowedAuthPath: (pathname: string | null | undefined, allowedPaths: string[]) => boolean;
 
+/**
+ * The one auth state: a single value answers "may this page render?".
+ *
+ *   resolving      the client has not read the session yet, or a live session is still loading its profile
+ *   authenticated  a live session and its profile settled
+ *   anonymous      no session (store and React snapshot agree)
+ *
+ * Every consumer (the page guard, the "leave /auth" effect, the trace) reads this and nothing else. The
+ * inputs are plain booleans so the whole table is unit-tested.
+ *
+ * Termination: `resolving` is left in finite time. `timedOut` is set by one timer in the provider, and
+ * when it fires the React snapshot decides. There is no input combination that stays `resolving` with
+ * `timedOut` true.
+ */
+type AuthStatus = 'resolving' | 'authenticated' | 'anonymous';
+interface AuthStateInput {
+    /** The first client effect has run (the hydration commit is over). */
+    clientReady: boolean;
+    /** `useSession()` says authenticated (the React snapshot; the server snapshot is always anonymous). */
+    snapshotAuthenticated: boolean;
+    /** `auth.isAuthenticated()` read straight from the store at this render. */
+    storeAuthenticated: boolean;
+    /** The profile for a live session has loaded, failed in a way that keeps the session, or was cached. */
+    profileSettled: boolean;
+    /** The provider's single safety timer fired. */
+    timedOut: boolean;
+}
+declare function resolveAuthStatus(s: AuthStateInput): AuthStatus;
+
 declare const logger: consola.ConsolaInstance;
 /**
  * Auth-specific logger
@@ -1531,5 +1609,5 @@ declare const Analytics: {
     setUser(userId: string | null): void;
 };
 
-export { AUTH_CONSTANTS, AUTH_ERROR_KEYS, AccountsProvider, Analytics, AnalyticsCategory, AnalyticsEvent, AuthContext, AuthProvider, OAUTH_PROVIDER_IDS, authLogger, beginTwoFactorChallenge, clearOAuthAttempt, clearProfileCache, consumeSavedRedirect, decodeBase64, encodeBase64, endTwoFactorChallenge, formatAuthError, getCacheMetadata, getCachedProfile, hasValidCache, isAllowedAuthPath, isForbidden, isOAuthProviderId, logAuthFailure, logger, normalizePath, peekSavedRedirect, readOAuthFailure, resolveAuthError, resolveGuardIsAuthenticated, resolveGuardIsLoading, setAnalyticsSink, setCachedProfile, shouldRedirectToAuth, useAccountsContext, useAuth, useAuthForm, useAuthFormState, useAuthRedirectManager, useAuthValidation, useAutoAuth, useBase64, useCfgRouter, useDeleteAccount, useGithubAuth, useLocalStorage, useOAuthLogin, useOAuthProviders, useQueryParams, useSession, useSessionStorage, useTimezone, useTwoFactor, useTwoFactorChallenge, useTwoFactorSetup, useTwoFactorStatus, useTwoFactorVerify, validateEmail, validateIdentifier };
-export type { AccountsContextValue, AnalyticsCategoryType, AnalyticsEventType, AnalyticsSink, AuthConfig, AuthContextType, AuthErrorCopy, AuthErrorKey, AuthFormAutoSubmit, AuthFormReturn, AuthFormState, AuthFormStateHandlers, AuthFormSubmitHandlers, AuthFormValidation, AuthProviderProps, AuthStep, DeleteAccountResult, GuardInput, OAuthClientErrorCode, OAuthErrorCode, OAuthFailure, OAuthFailureCode, OAuthProviderId, OAuthUser, OTPRequestConsent, OTPRequestResult, PasswordLoginOptions, PasswordLoginResult, PatchedCfgUserUpdateRequest, ProfileCacheOptions, SessionSnapshot, SessionStatus, TwoFactorChallenge, TwoFactorDevice, TwoFactorSetupData, UseAuthFormOptions, UseAuthFormStateReturn, UseAutoAuthOptions, UseDeleteAccountReturn, UseGithubAuthOptions, UseGithubAuthReturn, UseOAuthLoginOptions, UseOAuthLoginReturn, UseOAuthProvidersReturn, UseTimezoneReturn, UseTwoFactorOptions, UseTwoFactorReturn, UseTwoFactorSetupOptions, UseTwoFactorSetupReturn, UseTwoFactorStatusReturn, UseTwoFactorVerifyOptions, UseTwoFactorVerifyReturn, UserProfile, WebmailLink };
+export { AUTH_CONSTANTS, AUTH_ERROR_KEYS, AccountsProvider, Analytics, AnalyticsCategory, AnalyticsEvent, AuthContext, AuthProvider, OAUTH_PROVIDER_IDS, authLogger, authTrace, beginTwoFactorChallenge, clearAuthTrace, clearOAuthAttempt, clearProfileCache, consumeSavedRedirect, decodeBase64, dumpAuthTrace, encodeBase64, endTwoFactorChallenge, formatAuthError, getCacheMetadata, getCachedProfile, hasValidCache, installAuthTrace, isAllowedAuthPath, isForbidden, isOAuthProviderId, logAuthFailure, logger, normalizePath, peekSavedRedirect, readAuthTrace, readOAuthFailure, resetAuthTraceForTests, resolveAuthError, resolveAuthStatus, resolveGuardIsAuthenticated, resolveGuardIsLoading, setAnalyticsSink, setCachedProfile, shouldRedirectToAuth, useAccountsContext, useAuth, useAuthForm, useAuthFormState, useAuthRedirectManager, useAuthValidation, useAutoAuth, useBase64, useCfgRouter, useDeleteAccount, useGithubAuth, useLocalStorage, useOAuthLogin, useOAuthProviders, useQueryParams, useSession, useSessionStorage, useTimezone, useTwoFactor, useTwoFactorChallenge, useTwoFactorSetup, useTwoFactorStatus, useTwoFactorVerify, validateEmail, validateIdentifier };
+export type { AccountsContextValue, AnalyticsCategoryType, AnalyticsEventType, AnalyticsSink, AuthConfig, AuthContextType, AuthErrorCopy, AuthErrorKey, AuthFormAutoSubmit, AuthFormReturn, AuthFormState, AuthFormStateHandlers, AuthFormSubmitHandlers, AuthFormValidation, AuthProviderProps, AuthStateInput, AuthStatus, AuthStep, DeleteAccountResult, GuardInput, OAuthClientErrorCode, OAuthErrorCode, OAuthFailure, OAuthFailureCode, OAuthProviderId, OAuthUser, OTPRequestConsent, OTPRequestResult, PasswordLoginOptions, PasswordLoginResult, PatchedCfgUserUpdateRequest, ProfileCacheOptions, SessionSnapshot, SessionStatus, TraceEntry, TraceFields, TwoFactorChallenge, TwoFactorDevice, TwoFactorSetupData, UseAuthFormOptions, UseAuthFormStateReturn, UseAutoAuthOptions, UseDeleteAccountReturn, UseGithubAuthOptions, UseGithubAuthReturn, UseOAuthLoginOptions, UseOAuthLoginReturn, UseOAuthProvidersReturn, UseTimezoneReturn, UseTwoFactorOptions, UseTwoFactorReturn, UseTwoFactorSetupOptions, UseTwoFactorSetupReturn, UseTwoFactorStatusReturn, UseTwoFactorVerifyOptions, UseTwoFactorVerifyReturn, UserProfile, WebmailLink };