@baseplate-dev/plugin-auth 0.6.18 → 0.6.19

package/dist/local-auth/core/generators/react-session/generated/typed-templates.d.ts

@@ -1,21 +1,29 @@
 export declare const mainGroup: {
     userSessionClient: import("@baseplate-dev/core-generators").TsTemplateFile<{}, {
-        reactUtilsImports: import("@baseplate-dev/sync").ProviderType<import("@baseplate-dev/core-generators").InferTsImportMapFromSchema<{
-            getSafeLocalStorage: {};
-        }>>;
-    }, Record<never, Record<never, never>>>;
-    userSessionProvider: import("@baseplate-dev/core-generators").TsTemplateFile<{}, {
         authHooksImports: import("@baseplate-dev/sync").ProviderType<import("@baseplate-dev/core-generators").InferTsImportMapFromSchema<{
             SessionData: {
                 isTypeOnly: true;
             };
             useLogOut: {};
-            useRequiredUserId: {};
             useSession: {};
+            useUserIdOrThrow: {};
             AuthRole: {
                 isTypeOnly: true;
             };
         }>>;
+        graphqlImports: import("@baseplate-dev/sync").ProviderType<import("@baseplate-dev/core-generators").InferTsImportMapFromSchema<{
+            '*': {};
+            graphql: {};
+            readFragment: {};
+            FragmentType: {
+                isTypeOnly: true;
+            };
+        }>>;
+        reactUtilsImports: import("@baseplate-dev/sync").ProviderType<import("@baseplate-dev/core-generators").InferTsImportMapFromSchema<{
+            getSafeLocalStorage: {};
+        }>>;
+    }, Record<never, Record<never, never>>>;
+    userSessionProvider: import("@baseplate-dev/core-generators").TsTemplateFile<{}, {
         graphqlImports: import("@baseplate-dev/sync").ProviderType<import("@baseplate-dev/core-generators").InferTsImportMapFromSchema<{
             '*': {};
             graphql: {};
@@ -32,6 +40,7 @@ export declare const mainGroup: {
                 isTypeOnly: true;
             };
             Alert: {};
+            AlertAction: {};
             AlertDescription: {};
             AlertTitle: {};
             Autocomplete: {};
@@ -61,6 +70,7 @@ export declare const mainGroup: {
             buttonVariants: {};
             Calendar: {};
             Card: {};
+            CardAction: {};
             CardContent: {};
             CardDescription: {};
             CardFooter: {};
@@ -187,6 +197,10 @@ export declare const mainGroup: {
             NotFoundCard: {};
             NumberField: {};
             NumberFieldController: {};
+            PageHeader: {};
+            PageHeaderActions: {};
+            PageHeaderDescription: {};
+            PageHeaderTitle: {};
             Popover: {};
             PopoverContent: {};
             PopoverTrigger: {};
@@ -196,6 +210,11 @@ export declare const mainGroup: {
                 isTypeOnly: true;
             };
             ScrollArea: {};
+            Section: {};
+            SectionActions: {};
+            SectionDescription: {};
+            SectionHeader: {};
+            SectionTitle: {};
             Select: {};
             SelectField: {};
             SelectFieldController: {};
@@ -251,7 +270,27 @@ export declare const mainGroup: {
             Textarea: {};
             TextareaField: {};
             TextareaFieldController: {};
+            Toast: {};
+            toast: {};
+            ToastAction: {};
+            ToastClose: {};
+            ToastContent: {};
+            ToastDescription: {};
             Toaster: {};
+            toastManager: {};
+            ToastOptions: {
+                isTypeOnly: true;
+            };
+            ToastPortal: {};
+            ToastProvider: {};
+            ToastTitle: {};
+            ToastType: {
+                isTypeOnly: true;
+            };
+            ToastUpdateOptions: {
+                isTypeOnly: true;
+            };
+            ToastViewport: {};
             Tooltip: {};
             TooltipContent: {};
             TooltipProvider: {};
@@ -279,22 +318,30 @@ export declare const mainGroup: {
 export declare const LOCAL_AUTH_CORE_REACT_SESSION_TEMPLATES: {
     mainGroup: {
         userSessionClient: import("@baseplate-dev/core-generators").TsTemplateFile<{}, {
-            reactUtilsImports: import("@baseplate-dev/sync").ProviderType<import("@baseplate-dev/core-generators").InferTsImportMapFromSchema<{
-                getSafeLocalStorage: {};
-            }>>;
-        }, Record<never, Record<never, never>>>;
-        userSessionProvider: import("@baseplate-dev/core-generators").TsTemplateFile<{}, {
             authHooksImports: import("@baseplate-dev/sync").ProviderType<import("@baseplate-dev/core-generators").InferTsImportMapFromSchema<{
                 SessionData: {
                     isTypeOnly: true;
                 };
                 useLogOut: {};
-                useRequiredUserId: {};
                 useSession: {};
+                useUserIdOrThrow: {};
                 AuthRole: {
                     isTypeOnly: true;
                 };
             }>>;
+            graphqlImports: import("@baseplate-dev/sync").ProviderType<import("@baseplate-dev/core-generators").InferTsImportMapFromSchema<{
+                '*': {};
+                graphql: {};
+                readFragment: {};
+                FragmentType: {
+                    isTypeOnly: true;
+                };
+            }>>;
+            reactUtilsImports: import("@baseplate-dev/sync").ProviderType<import("@baseplate-dev/core-generators").InferTsImportMapFromSchema<{
+                getSafeLocalStorage: {};
+            }>>;
+        }, Record<never, Record<never, never>>>;
+        userSessionProvider: import("@baseplate-dev/core-generators").TsTemplateFile<{}, {
             graphqlImports: import("@baseplate-dev/sync").ProviderType<import("@baseplate-dev/core-generators").InferTsImportMapFromSchema<{
                 '*': {};
                 graphql: {};
@@ -311,6 +358,7 @@ export declare const LOCAL_AUTH_CORE_REACT_SESSION_TEMPLATES: {
                     isTypeOnly: true;
                 };
                 Alert: {};
+                AlertAction: {};
                 AlertDescription: {};
                 AlertTitle: {};
                 Autocomplete: {};
@@ -340,6 +388,7 @@ export declare const LOCAL_AUTH_CORE_REACT_SESSION_TEMPLATES: {
                 buttonVariants: {};
                 Calendar: {};
                 Card: {};
+                CardAction: {};
                 CardContent: {};
                 CardDescription: {};
                 CardFooter: {};
@@ -466,6 +515,10 @@ export declare const LOCAL_AUTH_CORE_REACT_SESSION_TEMPLATES: {
                 NotFoundCard: {};
                 NumberField: {};
                 NumberFieldController: {};
+                PageHeader: {};
+                PageHeaderActions: {};
+                PageHeaderDescription: {};
+                PageHeaderTitle: {};
                 Popover: {};
                 PopoverContent: {};
                 PopoverTrigger: {};
@@ -475,6 +528,11 @@ export declare const LOCAL_AUTH_CORE_REACT_SESSION_TEMPLATES: {
                     isTypeOnly: true;
                 };
                 ScrollArea: {};
+                Section: {};
+                SectionActions: {};
+                SectionDescription: {};
+                SectionHeader: {};
+                SectionTitle: {};
                 Select: {};
                 SelectField: {};
                 SelectFieldController: {};
@@ -530,7 +588,27 @@ export declare const LOCAL_AUTH_CORE_REACT_SESSION_TEMPLATES: {
                 Textarea: {};
                 TextareaField: {};
                 TextareaFieldController: {};
+                Toast: {};
+                toast: {};
+                ToastAction: {};
+                ToastClose: {};
+                ToastContent: {};
+                ToastDescription: {};
                 Toaster: {};
+                toastManager: {};
+                ToastOptions: {
+                    isTypeOnly: true;
+                };
+                ToastPortal: {};
+                ToastProvider: {};
+                ToastTitle: {};
+                ToastType: {
+                    isTypeOnly: true;
+                };
+                ToastUpdateOptions: {
+                    isTypeOnly: true;
+                };
+                ToastViewport: {};
                 Tooltip: {};
                 TooltipContent: {};
                 TooltipProvider: {};

package/dist/local-auth/core/generators/react-session/generated/typed-templates.js

@@ -5,7 +5,11 @@ import { localAuthHooksImportsProvider } from '#src/local-auth/core/generators/a
 const userSessionClient = createTsTemplateFile({
     fileOptions: { kind: 'singleton' },
     group: 'main',
-    importMapProviders: { reactUtilsImports: reactUtilsImportsProvider },
+    importMapProviders: {
+        authHooksImports: authHooksImportsProvider,
+        graphqlImports: graphqlImportsProvider,
+        reactUtilsImports: reactUtilsImportsProvider,
+    },
     name: 'user-session-client',
     projectExports: { UserSessionClient: {}, userSessionClient: {} },
     source: {
@@ -17,7 +21,6 @@ const userSessionProvider = createTsTemplateFile({
     fileOptions: { kind: 'singleton' },
     group: 'main',
     importMapProviders: {
-        authHooksImports: authHooksImportsProvider,
         graphqlImports: graphqlImportsProvider,
         localAuthHooksImports: localAuthHooksImportsProvider,
         reactComponentsImports: reactComponentsImportsProvider,

package/dist/local-auth/core/generators/react-session/react-session.generator.d.ts

@@ -23,8 +23,8 @@ export declare const reactSessionGenerator: import("@baseplate-dev/sync").Genera
                 isTypeOnly: true;
             };
             useLogOut: {};
-            useRequiredUserId: {};
             useSession: {};
+            useUserIdOrThrow: {};
             AuthRole: {
                 isTypeOnly: true;
             };
@@ -46,6 +46,7 @@ export declare const reactSessionGenerator: import("@baseplate-dev/sync").Genera
                 isTypeOnly: true;
             };
             Alert: {};
+            AlertAction: {};
             AlertDescription: {};
             AlertTitle: {};
             Autocomplete: {};
@@ -75,6 +76,7 @@ export declare const reactSessionGenerator: import("@baseplate-dev/sync").Genera
             buttonVariants: {};
             Calendar: {};
             Card: {};
+            CardAction: {};
             CardContent: {};
             CardDescription: {};
             CardFooter: {};
@@ -201,6 +203,10 @@ export declare const reactSessionGenerator: import("@baseplate-dev/sync").Genera
             NotFoundCard: {};
             NumberField: {};
             NumberFieldController: {};
+            PageHeader: {};
+            PageHeaderActions: {};
+            PageHeaderDescription: {};
+            PageHeaderTitle: {};
             Popover: {};
             PopoverContent: {};
             PopoverTrigger: {};
@@ -210,6 +216,11 @@ export declare const reactSessionGenerator: import("@baseplate-dev/sync").Genera
                 isTypeOnly: true;
             };
             ScrollArea: {};
+            Section: {};
+            SectionActions: {};
+            SectionDescription: {};
+            SectionHeader: {};
+            SectionTitle: {};
             Select: {};
             SelectField: {};
             SelectFieldController: {};
@@ -265,7 +276,27 @@ export declare const reactSessionGenerator: import("@baseplate-dev/sync").Genera
             Textarea: {};
             TextareaField: {};
             TextareaFieldController: {};
+            Toast: {};
+            toast: {};
+            ToastAction: {};
+            ToastClose: {};
+            ToastContent: {};
+            ToastDescription: {};
             Toaster: {};
+            toastManager: {};
+            ToastOptions: {
+                isTypeOnly: true;
+            };
+            ToastPortal: {};
+            ToastProvider: {};
+            ToastTitle: {};
+            ToastType: {
+                isTypeOnly: true;
+            };
+            ToastUpdateOptions: {
+                isTypeOnly: true;
+            };
+            ToastViewport: {};
             Tooltip: {};
             TooltipContent: {};
             TooltipProvider: {};
@@ -300,6 +331,22 @@ export declare const reactSessionGenerator: import("@baseplate-dev/sync").Genera
         }>, "getValues">>;
         paths: import("@baseplate-dev/sync").ProviderType<import("./generated/template-paths.js").LocalAuthCoreReactSessionPaths>;
     }, any>;
+    reactRouterConfig: import("@baseplate-dev/sync").GeneratorTask<any, {
+        reactRouterConfig: import("@baseplate-dev/sync").ProviderType<Omit<import("@baseplate-dev/utils").FieldMap<{
+            routerSetupFragments: import("@baseplate-dev/utils").MapContainer<string, import("@baseplate-dev/core-generators").TsCodeFragment>;
+            routerBodyFragments: import("@baseplate-dev/utils").MapContainer<string, import("@baseplate-dev/core-generators").TsCodeFragment>;
+            rootLayoutComponent: import("@baseplate-dev/utils").ScalarContainer<import("@baseplate-dev/core-generators").TsCodeFragment | undefined>;
+            rootContextFields: import("@baseplate-dev/utils").NamedArrayFieldContainer<import("@baseplate-dev/react-generators").RootRouteContextField>;
+            errorComponentHeaderFragments: import("@baseplate-dev/utils").MapContainer<string, import("@baseplate-dev/core-generators").TsCodeFragment>;
+            errorComponentBodyFragments: import("@baseplate-dev/utils").MapContainer<string, import("@baseplate-dev/core-generators").TsCodeFragment>;
+        }>, "getValues">>;
+        reactRouterImports: import("@baseplate-dev/sync").ProviderType<import("@baseplate-dev/core-generators").InferTsImportMapFromSchema<{
+            AppRoutes: {};
+            ErrorComponent: {};
+            router: {};
+        }>>;
+        paths: import("@baseplate-dev/sync").ProviderType<import("./generated/template-paths.js").LocalAuthCoreReactSessionPaths>;
+    }, any>;
     main: import("@baseplate-dev/sync").GeneratorTask<any, {
         renderers: import("@baseplate-dev/sync").ProviderType<import("./generated/template-renderers.js").LocalAuthCoreReactSessionRenderers>;
     }, any>;

package/dist/local-auth/core/generators/react-session/react-session.generator.js

@@ -1,5 +1,5 @@
 import { TsCodeUtils, tsImportBuilder } from '@baseplate-dev/core-generators';
-import { reactAppConfigProvider } from '@baseplate-dev/react-generators';
+import { reactAppConfigProvider, reactRouterConfigProvider, reactRouterImportsProvider, } from '@baseplate-dev/react-generators';
 import { createGenerator, createGeneratorTask } from '@baseplate-dev/sync';
 import { z } from 'zod';
 import { LOCAL_AUTH_CORE_REACT_SESSION_GENERATED as GENERATED_TEMPLATES } from './generated/index.js';
@@ -29,6 +29,40 @@ export const reactSessionGenerator = createGenerator({
                 });
             },
         }),
+        reactRouterConfig: createGeneratorTask({
+            dependencies: {
+                reactRouterConfig: reactRouterConfigProvider,
+                reactRouterImports: reactRouterImportsProvider,
+                paths: GENERATED_TEMPLATES.paths.provider,
+            },
+            run({ reactRouterConfig, reactRouterImports, paths }) {
+                reactRouterConfig.routerSetupFragments.set('auth-session-router-sync', TsCodeUtils.templateWithImports([
+                    tsImportBuilder(['useEffect']).from('react'),
+                    tsImportBuilder(['userSessionClient']).from(paths.userSessionClient),
+                    reactRouterImports.router.declaration(),
+                ]) `
+          // RouterProvider only copies the context into the router when it renders, so push
+          // the session in as soon as it changes. Otherwise a navigation triggered in the
+          // same tick as a sign in or sign out runs its guards against the old session.
+          useEffect(
+            () =>
+              userSessionClient.subscribe(() => {
+                const currentSession = userSessionClient.getSession();
+                if (!currentSession) return;
+                router.update({
+                  ...router.options,
+                  context: {
+                    ...router.options.context,
+                    session: currentSession,
+                    userId: currentSession.userId,
+                  },
+                });
+              }),
+            [],
+          );
+          `);
+            },
+        }),
         main: createGeneratorTask({
             dependencies: {
                 renderers: GENERATED_TEMPLATES.renderers.provider,

package/dist/local-auth/core/generators/react-session/templates/src/app/user-session-provider.js

@@ -5,7 +5,7 @@ import { AuthSessionContext } from '%localAuthHooksImports';
 import { ErrorableLoader } from '%reactComponentsImports';
 import { logError } from '%reactErrorImports';
 import { useApolloClient, useQuery } from '@apollo/client/react';
-import { useEffect, useMemo, useState } from 'react';
+import { useEffect, useRef, useSyncExternalStore } from 'react';
 const getCurrentUserSessionQuery = graphql(`
   query CurrentUserSession {
     currentUserSession {
@@ -15,55 +15,28 @@ const getCurrentUserSessionQuery = graphql(`
   }
 `);
 export function UserSessionProvider({ children, }) {
-    const [cachedUserId, setCachedUserId] = useState(userSessionClient.getUserId());
     const apolloClient = useApolloClient();
+    // The session comes from the session client rather than the query, since signing
+    // in clears the Apollo cache and would otherwise blank the session mid-transition.
+    const session = useSyncExternalStore(userSessionClient.subscribe, userSessionClient.getSession);
     const { data: sessionQueryData, error: sessionError } = useQuery(getCurrentUserSessionQuery, {
         notifyOnNetworkStatusChange: true,
     });
-    const session = useMemo(() => {
-        if (!sessionQueryData && cachedUserId) {
-            // wait for server to fetch before loading session
-            return undefined;
-        }
-        if (!sessionQueryData?.currentUserSession) {
-            return {
-                userId: undefined,
-                isAuthenticated: false,
-                roles: ['public'],
-            };
-        }
-        return {
-            userId: sessionQueryData.currentUserSession.userId,
-            isAuthenticated: true,
-            roles: sessionQueryData.currentUserSession.roles,
-        };
-    }, [sessionQueryData, cachedUserId]);
     useEffect(() => {
-        const unsubscribe = userSessionClient.onUserIdChange((newUserId) => {
-            if (newUserId !== cachedUserId) {
-                setCachedUserId(newUserId);
-                // Make sure to reset the Apollo client to clear any cached data
-                apolloClient.resetStore().catch(logError);
-            }
-        });
-        return unsubscribe;
-    }, [cachedUserId, apolloClient]);
-    useEffect(() => {
-        // Once we have server session data, sync it with the client
-        if (sessionQueryData) {
-            const serverUserId = sessionQueryData.currentUserSession?.userId;
-            const clientUserId = userSessionClient.getUserId();
-            // If server says different user (or no user), update the client
-            if (serverUserId !== clientUserId) {
-                if (serverUserId) {
-                    userSessionClient.signIn(serverUserId);
-                }
-                else {
-                    userSessionClient.signOut();
-                }
-            }
-        }
+        if (!sessionQueryData)
+            return;
+        userSessionClient.setServerSession(sessionQueryData.currentUserSession ?? undefined);
     }, [sessionQueryData]);
+    // The Apollo cache belongs to exactly one identity, so reset it whenever the
+    // identity changes and no data fetched for the previous user survives.
+    const cacheUserId = useRef(userSessionClient.getPersistedUserId());
+    useEffect(() => {
+        if (!session || session.userId === cacheUserId.current)
+            return;
+        cacheUserId.current = session.userId;
+        apolloClient.resetStore().catch(logError);
+    }, [session, apolloClient]);
+    // Only reachable before the first session is known, when nothing has mounted yet.
     if (!session) {
         return _jsx(ErrorableLoader, { error: sessionError });
     }

package/dist/local-auth/core/generators/react-session/templates/src/app/user-session-provider.tsx

@@ -1,6 +1,5 @@
 // @ts-nocheck
 
-import type { SessionData } from '%authHooksImports';
 import type React from 'react';
 
 import { userSessionClient } from '$userSessionClient';
@@ -9,7 +8,7 @@ import { AuthSessionContext } from '%localAuthHooksImports';
 import { ErrorableLoader } from '%reactComponentsImports';
 import { logError } from '%reactErrorImports';
 import { useApolloClient, useQuery } from '@apollo/client/react';
-import { useEffect, useMemo, useState } from 'react';
+import { useEffect, useRef, useSyncExternalStore } from 'react';
 
 interface UserSessionProviderProps {
   children: React.ReactNode;
@@ -27,11 +26,15 @@ const getCurrentUserSessionQuery = graphql(`
 export function UserSessionProvider({
   children,
 }: UserSessionProviderProps): React.JSX.Element {
-  const [cachedUserId, setCachedUserId] = useState<string | undefined>(
-    userSessionClient.getUserId(),
-  );
   const apolloClient = useApolloClient();
 
+  // The session comes from the session client rather than the query, since signing
+  // in clears the Apollo cache and would otherwise blank the session mid-transition.
+  const session = useSyncExternalStore(
+    userSessionClient.subscribe,
+    userSessionClient.getSession,
+  );
+
   const { data: sessionQueryData, error: sessionError } = useQuery(
     getCurrentUserSessionQuery,
     {
@@ -39,54 +42,23 @@ export function UserSessionProvider({
     },
   );
 
-  const session = useMemo((): SessionData | undefined => {
-    if (!sessionQueryData && cachedUserId) {
-      // wait for server to fetch before loading session
-      return undefined;
-    }
-    if (!sessionQueryData?.currentUserSession) {
-      return {
-        userId: undefined,
-        isAuthenticated: false,
-        roles: ['public'],
-      };
-    }
-    return {
-      userId: sessionQueryData.currentUserSession.userId,
-      isAuthenticated: true,
-      roles: sessionQueryData.currentUserSession.roles,
-    };
-  }, [sessionQueryData, cachedUserId]);
-
   useEffect(() => {
-    const unsubscribe = userSessionClient.onUserIdChange((newUserId) => {
-      if (newUserId !== cachedUserId) {
-        setCachedUserId(newUserId);
-        // Make sure to reset the Apollo client to clear any cached data
-        apolloClient.resetStore().catch(logError);
-      }
-    });
-
-    return unsubscribe;
-  }, [cachedUserId, apolloClient]);
+    if (!sessionQueryData) return;
+    userSessionClient.setServerSession(
+      sessionQueryData.currentUserSession ?? undefined,
+    );
+  }, [sessionQueryData]);
 
+  // The Apollo cache belongs to exactly one identity, so reset it whenever the
+  // identity changes and no data fetched for the previous user survives.
+  const cacheUserId = useRef(userSessionClient.getPersistedUserId());
   useEffect(() => {
-    // Once we have server session data, sync it with the client
-    if (sessionQueryData) {
-      const serverUserId = sessionQueryData.currentUserSession?.userId;
-      const clientUserId = userSessionClient.getUserId();
-
-      // If server says different user (or no user), update the client
-      if (serverUserId !== clientUserId) {
-        if (serverUserId) {
-          userSessionClient.signIn(serverUserId);
-        } else {
-          userSessionClient.signOut();
-        }
-      }
-    }
-  }, [sessionQueryData]);
+    if (!session || session.userId === cacheUserId.current) return;
+    cacheUserId.current = session.userId;
+    apolloClient.resetStore().catch(logError);
+  }, [session, apolloClient]);
 
+  // Only reachable before the first session is known, when nothing has mounted yet.
   if (!session) {
     return <ErrorableLoader error={sessionError} />;
   }

package/dist/local-auth/core/generators/react-session/templates/src/services/user-session-client.d.ts

@@ -1,55 +1,64 @@
+import type { SessionData } from '%authHooksImports';
+import type { AuthRole } from '%graphqlImports';
 /**
- * Callback function for user ID change events
+ * Callback function for session change events
  */
-type UserIdChangeCallback = (userId: string | undefined) => void;
-/**
- * User session client for managing session persistence using localStorage
- * Handles session state persistence and cross-tab synchronization
- */
-export declare class UserSessionClient {
-    private static readonly USER_ID_STORAGE_KEY;
-    private readonly storage;
-    private readonly callbacks;
-    private cleanupListener?;
-    constructor();
-    /**
-     * Sign in a user with the given user ID
-     * @param userId - The user ID to sign in
-     */
-    signIn(userId: string): void;
+type SessionChangeCallback = () => void;
+export interface UserSessionClient {
     /**
-     * Sign out the current user
+     * Get the current session, or `undefined` if it is not known yet.
+     *
+     * Returns a stable reference that only changes when the session itself changes,
+     * so it is safe to use as a `useSyncExternalStore` snapshot.
      */
-    signOut(): void;
+    getSession: () => SessionData | undefined;
     /**
-     * Subscribe to user ID changes
-     * @param callback - Function to call when user ID changes
+     * Subscribe to session changes
+     * @param callback - Function to call when the session changes
      * @returns Cleanup function to unsubscribe
      */
-    onUserIdChange(callback: UserIdChangeCallback): () => void;
+    subscribe: (callback: SessionChangeCallback) => () => void;
     /**
-     * Clean up resources when the client is no longer needed
+     * Sign in a user with a session the server has already returned
+     * @param userId - The user ID to sign in
+     * @param roles - The roles the server issued alongside the session
      */
-    destroy(): void;
+    signIn: (userId: string, roles: AuthRole[]) => void;
     /**
-     * Get the current user ID from storage
-     * @returns User ID or null if not authenticated
+     * Sign out the current user
      */
-    getUserId(): string | undefined;
+    signOut: () => void;
     /**
-     * Set the user ID in storage
-     * @param userId - User ID to store, or null to clear
+     * Apply the session reported by the server, confirming or replacing whatever was
+     * published locally
+     * @param session - The session from the server, or undefined if signed out
      */
-    private setUserId;
+    setServerSession: (session: {
+        userId: string;
+        roles: AuthRole[];
+    } | undefined) => void;
     /**
-     * Set up storage listener for cross-tab synchronization
+     * Get the user ID persisted in storage, which may not be confirmed yet
+     * @returns User ID or undefined if not signed in
      */
-    private setupStorageListener;
+    getPersistedUserId: () => string | undefined;
     /**
-     * Notify all registered callbacks of session changes
+     * Clean up resources when the client is no longer needed
      */
-    private notifyCallbacks;
+    destroy: () => void;
 }
+/**
+ * Creates the client-side source of truth for the current user session.
+ *
+ * The session is published synchronously when it is known locally (sign in / sign
+ * out) and refined asynchronously when the server confirms it. It is deliberately
+ * not derived from the Apollo cache, since signing in clears that cache.
+ *
+ * The user ID is persisted to localStorage for cold starts and cross-tab
+ * synchronisation. Roles are never persisted — they are only ever trusted from the
+ * server, and are enforced there regardless.
+ */
+export declare function createUserSessionClient(): UserSessionClient;
 /**
  * Global user session client instance
  */