Using React with the Current Authentication Setup#

This document outlines considerations and patterns for integrating a React frontend with the existing Express backend's authentication system, which relies on iron-session and HttpOnly cookies.

Core Principles:#

1. HttpOnly Cookies Remain Server-Managed:

   • The HttpOnly session cookie (e.g., sid) set by the backend will continue to be the primary mechanism for session persistence.
   • The browser will automatically send this cookie with API requests to the backend.
   • React client-side code cannot and should not attempt to directly access or manipulate this HttpOnly cookie.

2. Client-Side Authentication State:

   • While the browser handles the cookie, the React application needs its own internal state to know if a user is authenticated and who the user is. This state will drive UI changes (e.g., showing user-specific content, login/logout buttons).

Recommended Patterns:#

1. Dedicated API Endpoint for User Data (/api/me):

   • Create a new backend endpoint (e.g., /api/me).
   • This endpoint should use the existing getSessionAgent logic (or similar) to check for a valid session cookie.
   • If authenticated, it should return relevant user information (e.g., DID, display name, profile details).
   • If not authenticated, it should return an appropriate error (e.g., 401 Unauthorized).

2. Fetching User Data on App Load:

   • When the React app initializes, it should make a request to the /api/me endpoint.
   • Based on the response, the React app updates its internal authentication state (e.g., in React Context, Redux, Zustand, or component state).

3. Login Flow:

   • The React app's login button/action should redirect the browser to the backend's existing /login route (e.g., window.location.href = '/login').
   • The backend handles the entire OAuth flow and sets the HttpOnly session cookie upon successful authentication.
   • After the OAuth callback, the backend should redirect the user back to the React application (e.g., to the main page or a specific post-login page).
   • Upon returning to the React app, it can either re-fetch from /api/me or the backend redirect could include a signal for the app to know the login was successful, prompting a fetch to /api/me.

4. Logout Flow:

   • The React app's logout button/action should make an API call (e.g., POST) to the backend's existing /logout route.
   • The backend destroys the iron-session, clearing the HttpOnly cookie.
   • Upon a successful response from the logout API, the React app should clear its internal authentication state and update the UI.

5. Authenticated API Calls from React:

   • When making other API calls to protected backend routes (e.g., posting a status), React's fetch or axios calls will automatically include the HttpOnly session cookie if the requests are to the same domain (or if CORS and credentials: 'include' are correctly configured for cross-domain scenarios).
   • No special handling is needed in the React code to attach the session cookie itself.

6. UI Updates:

   • The React app uses its internal authentication state to conditionally render UI elements:
     • Show user profile / logout button if authenticated.
     • Show login button if not authenticated.
     • Enable/disable features based on authentication status.

Example Workflow:#

1. User opens React App:
   • React app calls GET /api/me.
   • Browser automatically sends sid cookie if present.
   • Backend validates cookie:
     • If valid: Returns user data (e.g., { did: '...', displayName: '...' }). React app sets user state.
     • If invalid/missing: Returns 401. React app sets user state to null.
2. User clicks "Login":
   • React app redirects to GET /login on the backend.
   • Backend initiates OAuth, user authenticates with PDS.
   • Backend's /oauth/callback receives PDS response, creates iron-session, sets sid cookie.
   • Backend redirects back to React app (e.g., https://your-react-app.com/).
   • React app (on load or via a specific effect) calls GET /api/me again, gets user data, updates UI.
3. User clicks "Post Status":
   • React app makes POST /status request to backend with status data.
   • Browser automatically sends sid cookie.
   • Backend's /status route uses getSessionAgent to validate session and process the request.
4. User clicks "Logout":
   • React app calls POST /logout on the backend.
   • Backend destroys iron-session, clearing the sid cookie.
   • React app clears its local user state, updates UI.

This approach leverages the security of HttpOnly cookies managed by the server while allowing the React SPA to maintain its own awareness of the authentication state for a responsive user experience.