feat(auth): Update Google OAuth integration to enhance response structure and improve callback handling

docs/google_oauth_integration.md

@@ -10,7 +10,7 @@ To enable Google OAuth 2.1 authentication, the following environment variables m
 
 *   `GOOGLE_CLIENT_ID`: Your Google OAuth 2.1 Client ID.
 *   `GOOGLE_CLIENT_SECRET`: Your Google OAuth 2.1 Client Secret.
-*   `GOOGLE_REDIRECT_URL`: The URL to which Google will redirect the user after successful authentication. This must match one of the authorized redirect URIs configured in your Google Cloud Console.
+*   `GOOGLE_REDIRECT_URL`: The URL to which Google will redirect the user after successful authentication. This must match one of the authorized redirect URIs configured in your Google Cloud Console (e.g., `http://127.0.0.1:8080/api/v1/auth/google/callback`).
 
 ### Obtaining Credentials from Google Cloud Console
 
@@ -46,11 +46,13 @@ To enable Google OAuth 2.1 authentication, the following environment variables m
 
 *   **Endpoint:** `/api/v1/auth/google/callback`
 *   **Method:** `GET`
-*   **Description:** This endpoint handles the redirect from Google after the user has authenticated and granted permissions. Google sends an authorization `code` and a `state` parameter to this URL. The application then uses this `code` to exchange it for an access token and user information with Google. Upon successful validation and user creation/login, a full `LoginResponse` object is returned, identical to the credential-based login, which includes an access token, refresh token, and user details.
+*   **Description:** This endpoint handles the redirect from Google after the user has authenticated and granted permissions. Google sends an authorization `code` and a `state` parameter to this URL. The application then uses this `code` to exchange it for an access token and user information with Google. Upon successful validation and user creation/login, a JSON response is returned containing authentication tokens and user details, identical to the credential-based login endpoint.
 
 *   **Query Parameters:**
-    *   `code` (required): The authorization code provided by Google.
-    *   `state` (required): The CSRF token generated during the login initiation.
+  * `code` (required): The authorization code provided by Google.
+  * `state` (required): The CSRF token generated during the login initiation.
+
+*   **Response:** Returns a JSON object containing authentication tokens and user information.
 
 *   **Example `curl` command (conceptual, as `code` and `state` are dynamic):**
 
@@ -62,7 +64,7 @@ To enable Google OAuth 2.1 authentication, the following environment variables m
     curl -v "http://127.0.0.1:8080/api/v1/auth/google/callback?code=<AUTHORIZATION_CODE>&state=<CSRF_STATE>"
     ```
 
-    A successful response will typically return a JSON object containing the generated JWT:
+*   **Success Response (200 OK):**
 
     ```json
     {
@@ -92,20 +94,298 @@ To enable Google OAuth 2.1 authentication, the following environment variables m
     }
     ```
 
+## React Frontend Implementation
+
+This section outlines how to integrate the Google OAuth 2.1 flow into a React application using the JSON API response approach.
+
+### 1. Initiating the Login Flow
+
+Users will click a button or link to initiate the Google OAuth process. You can implement this using either a popup window or a full page redirect approach.
+
+#### Approach 1: Popup Window (Recommended)
+
+```jsx
+// Example React Component for Google Login with Popup
+import React, { useState } from 'react';
+
+function GoogleLoginButton() {
+  const [isLoading, setIsLoading] = useState(false);
+
+  const handleLogin = () => {
+    setIsLoading(true);
+    
+    // Open Google OAuth in popup window
+    const popup = window.open(
+      'http://127.0.0.1:8080/api/v1/auth/google/login',
+      'googleOAuth',
+      'width=500,height=600,scrollbars=yes,resizable=yes'
+    );
+
+    // Check if popup is closed manually
+    const checkClosed = setInterval(() => {
+      if (popup.closed) {
+        clearInterval(checkClosed);
+        setIsLoading(false);
+        console.log('OAuth popup was closed without completion');
+      }
+    }, 1000);
+
+    // Listen for the popup to navigate to the callback URL
+    const checkCallback = setInterval(async () => {
+      try {
+        if (popup.location.href.includes('/api/v1/auth/google/callback')) {
+          clearInterval(checkCallback);
+          clearInterval(checkClosed);
+          
+          // Wait a moment for the request to complete, then get the response
+          setTimeout(async () => {
+            try {
+              // The popup now contains the JSON response from the callback
+              const response = await fetch(popup.location.href);
+              const data = await response.json();
+              
+              if (response.ok) {
+                // Store tokens securely
+                localStorage.setItem('accessToken', data.token.access_token);
+                localStorage.setItem('refreshToken', data.token.refresh_token);
+                localStorage.setItem('user', JSON.stringify(data.user));
+                
+                popup.close();
+                setIsLoading(false);
+                
+                // Redirect to dashboard or update app state
+                window.location.href = '/dashboard';
+              } else {
+                throw new Error('Authentication failed');
+              }
+            } catch (error) {
+              console.error('OAuth callback error:', error);
+              popup.close();
+              setIsLoading(false);
+              alert('Google login failed. Please try again.');
+            }
+          }, 1000);
+        }
+      } catch (error) {
+        // Cross-origin error is expected until callback URL is reached
+      }
+    }, 1000);
+  };
+
+  return (
+    <button onClick={handleLogin} disabled={isLoading}>
+      {isLoading ? 'Logging in...' : 'Login with Google'}
+    </button>
+  );
+}
+
+export default GoogleLoginButton;
+```
+
+#### Approach 2: Full Page Redirect
+
+```jsx
+// Example React Component for Google Login with Full Redirect
+import React from 'react';
+
+function GoogleLoginButton() {
+  const handleLogin = () => {
+    // Store current location to redirect back after auth
+    localStorage.setItem('preAuthLocation', window.location.pathname);
+    
+    // Redirect to backend's Google OAuth login endpoint
+    window.location.href = 'http://127.0.0.1:8080/api/v1/auth/google/login';
+  };
+
+  return (
+    <button onClick={handleLogin}>
+      Login with Google
+    </button>
+  );
+}
+
+export default GoogleLoginButton;
+```
+
+### 2. Handling the OAuth Callback (For Full Redirect Approach)
+
+If using the full page redirect approach, you'll need a callback component to handle the OAuth response.
+
+```jsx
+// Example React Component for Google OAuth Callback Handler
+import React, { useEffect, useState } from 'react';
+import { useLocation, useNavigate } from 'react-router-dom';
+
+function GoogleAuthCallback() {
+  const location = useLocation();
+  const navigate = useNavigate();
+  const [isProcessing, setIsProcessing] = useState(true);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    const handleCallback = async () => {
+      try {
+        // Extract query parameters from current URL
+        const params = new URLSearchParams(location.search);
+        const code = params.get('code');
+        const state = params.get('state');
+
+        if (!code || !state) {
+          throw new Error('Missing required OAuth parameters');
+        }
+
+        // Make request to your backend callback endpoint
+        const response = await fetch(
+          `http://127.0.0.1:8080/api/v1/auth/google/callback${location.search}`,
+          {
+            method: 'GET',
+            headers: {
+              'Content-Type': 'application/json',
+            },
+          }
+        );
+
+        if (!response.ok) {
+          throw new Error(`HTTP error! status: ${response.status}`);
+        }
+
+        const data = await response.json();
+
+        // Store authentication data
+        localStorage.setItem('accessToken', data.token.access_token);
+        localStorage.setItem('refreshToken', data.token.refresh_token);
+        localStorage.setItem('user', JSON.stringify(data.user));
+
+        // Redirect to intended location or dashboard
+        const preAuthLocation = localStorage.getItem('preAuthLocation') || '/dashboard';
+        localStorage.removeItem('preAuthLocation');
+        
+        navigate(preAuthLocation, { replace: true });
+
+      } catch (error) {
+        console.error('Google OAuth callback error:', error);
+        setError(error.message);
+        setIsProcessing(false);
+      }
+    };
+
+    handleCallback();
+  }, [location, navigate]);
+
+  if (error) {
+    return (
+      <div>
+        <h2>Authentication Failed</h2>
+        <p>Error: {error}</p>
+        <button onClick={() => navigate('/login')}>
+          Back to Login
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      <h2>Processing Google Login...</h2>
+      <p>Please wait while we complete your authentication...</p>
+    </div>
+  );
+}
+
+export default GoogleAuthCallback;
+```
+
+### 3. Example React Router Setup
+
+Ensure your React application's routing is set up to handle the callback URL (only needed if using the full redirect approach).
+
+```jsx
+// Example App.js or main router file
+import React from 'react';
+import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
+import GoogleLoginButton from './components/GoogleLoginButton';
+import GoogleAuthCallback from './components/GoogleAuthCallback';
+import Dashboard from './components/Dashboard';
+import LoginPage from './components/LoginPage';
+
+function App() {
+  return (
+    <Router>
+      <Routes>
+        <Route path="/login" element={<LoginPage />} />
+        <Route path="/auth/google/callback" element={<GoogleAuthCallback />} />
+        <Route path="/dashboard" element={<Dashboard />} />
+        {/* Other routes */}
+      </Routes>
+    </Router>
+  );
+}
+
+export default App;
+```
+
+### 4. Using the Authentication Tokens
+
+Once you have the tokens, you can use them to make authenticated requests to your API:
+
+```jsx
+// Example of making authenticated API requests
+const makeAuthenticatedRequest = async (url, options = {}) => {
+  const accessToken = localStorage.getItem('accessToken');
+  
+  const response = await fetch(url, {
+    ...options,
+    headers: {
+      ...options.headers,
+      'Authorization': `Bearer ${accessToken}`,
+      'Content-Type': 'application/json',
+    },
+  });
+
+  if (response.status === 401) {
+    // Token might be expired, try to refresh or redirect to login
+    localStorage.removeItem('accessToken');
+    localStorage.removeItem('refreshToken');
+    localStorage.removeItem('user');
+    window.location.href = '/login';
+    return;
+  }
+
+  return response;
+};
+```
+
 ## OAuth Flow Diagram
 
 ```mermaid
 graph TD
-    A[User] --> B{Access /api/v1/auth/google/login};
-    B --> C[Backend generates Auth URL];
-    C --> D{Redirect to Google Auth Page};
-    D --> E[User Authenticates with Google];
-    E --> F{Google Redirects to /api/v1/auth/google/callback};
-    F --> G[Backend Exchanges Code for Token];
-    G --> H[Backend Fetches User Info];
-    H --> I{User Exists?};
-    I -- Yes --> J[Retrieve User];
-    I -- No --> K[Create New User];
-    J --> L[Generate JWT];
-    K --> L;
-    L --> M[Return JWT to User];
+    A[User] --> B{Click Google Login Button}
+    B --> C[Frontend opens popup/redirects to /api/v1/auth/google/login]
+    C --> D[Backend redirects to Google Auth]
+    D --> E[User authenticates with Google]
+    E --> F[Google redirects to /api/v1/auth/google/callback]
+    F --> G[Backend exchanges code for Google token]
+    G --> H[Backend fetches user info from Google]
+    H --> I{User exists in database?}
+    I -- Yes --> J[Get existing user]
+    I -- No --> K[Create new user with Google info]
+    J --> L[Generate JWT access and refresh tokens]
+    K --> L
+    L --> M[Return JSON response with tokens and user data]
+    M --> N[Frontend stores tokens securely]
+    N --> O[Redirect user to dashboard/protected area]
+```
+
+## Security Considerations
+
+1. **Token Storage**: Store tokens securely in httpOnly cookies or secure storage mechanisms rather than localStorage in production.
+
+2. **HTTPS Only**: Always use HTTPS in production to protect tokens in transit.
+
+3. **Token Expiration**: Implement proper token refresh logic when access tokens expire.
+
+4. **CORS Configuration**: Ensure your backend has proper CORS configuration for the frontend domain.
+
+5. **State Validation**: The backend validates the CSRF state parameter to prevent CSRF attacks.
+
+6. **Scope Limitation**: Only request necessary OAuth scopes from Google (email and profile in this case).