A social knowledge tool for researchers built on ATProto
cosmik.network
1# Using React with the Current Authentication Setup
2
3This 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.
4
5## Core Principles:
6
71. **`HttpOnly` Cookies Remain Server-Managed:**
8 - The `HttpOnly` session cookie (e.g., `sid`) set by the backend will continue to be the primary mechanism for session persistence.
9 - The browser will automatically send this cookie with API requests to the backend.
10 - React client-side code **cannot and should not** attempt to directly access or manipulate this `HttpOnly` cookie.
11
122. **Client-Side Authentication State:**
13 - 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).
14
15## Recommended Patterns:
16
171. **Dedicated API Endpoint for User Data (`/api/me`):**
18 - Create a new backend endpoint (e.g., `/api/me`).
19 - This endpoint should use the existing `getSessionAgent` logic (or similar) to check for a valid session cookie.
20 - If authenticated, it should return relevant user information (e.g., DID, display name, profile details).
21 - If not authenticated, it should return an appropriate error (e.g., 401 Unauthorized).
22
232. **Fetching User Data on App Load:**
24 - When the React app initializes, it should make a request to the `/api/me` endpoint.
25 - Based on the response, the React app updates its internal authentication state (e.g., in React Context, Redux, Zustand, or component state).
26
273. **Login Flow:**
28 - The React app's login button/action should redirect the browser to the backend's existing `/login` route (e.g., `window.location.href = '/login'`).
29 - The backend handles the entire OAuth flow and sets the `HttpOnly` session cookie upon successful authentication.
30 - 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).
31 - 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`.
32
334. **Logout Flow:**
34 - The React app's logout button/action should make an API call (e.g., `POST`) to the backend's existing `/logout` route.
35 - The backend destroys the `iron-session`, clearing the `HttpOnly` cookie.
36 - Upon a successful response from the logout API, the React app should clear its internal authentication state and update the UI.
37
385. **Authenticated API Calls from React:**
39 - 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).
40 - No special handling is needed in the React code to attach the session cookie itself.
41
426. **UI Updates:**
43 - The React app uses its internal authentication state to conditionally render UI elements:
44 - Show user profile / logout button if authenticated.
45 - Show login button if not authenticated.
46 - Enable/disable features based on authentication status.
47
48## Example Workflow:
49
501. **User opens React App:**
51 - React app calls `GET /api/me`.
52 - Browser automatically sends `sid` cookie if present.
53 - Backend validates cookie:
54 - If valid: Returns user data (e.g., `{ did: '...', displayName: '...' }`). React app sets `user` state.
55 - If invalid/missing: Returns 401. React app sets `user` state to `null`.
562. **User clicks "Login":**
57 - React app redirects to `GET /login` on the backend.
58 - Backend initiates OAuth, user authenticates with PDS.
59 - Backend's `/oauth/callback` receives PDS response, creates `iron-session`, sets `sid` cookie.
60 - Backend redirects back to React app (e.g., `https://your-react-app.com/`).
61 - React app (on load or via a specific effect) calls `GET /api/me` again, gets user data, updates UI.
623. **User clicks "Post Status":**
63 - React app makes `POST /status` request to backend with status data.
64 - Browser automatically sends `sid` cookie.
65 - Backend's `/status` route uses `getSessionAgent` to validate session and process the request.
664. **User clicks "Logout":**
67 - React app calls `POST /logout` on the backend.
68 - Backend destroys `iron-session`, clearing the `sid` cookie.
69 - React app clears its local `user` state, updates UI.
70
71This 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.