Google OAuth 2.0 Integration

# Implement Google OAuth 2.0 Authentication

## Overview

Implement Google OAuth 2.0 authentication to allow users to sign in to the system using their Google account.

The authentication flow should use Google's official OAuth 2.0 authorization protocol and securely handle authentication callbacks, tokens, sessions, and user information.

Reference: Google Identity — OAuth 2.0
https://developers.google.com/identity/protocols/oauth2

## Objectives

* Add **Sign in with Google** functionality.
* Authenticate users through Google's OAuth 2.0 authorization flow.
* Retrieve the authenticated user's basic profile information.
* Create or associate a local user account after successful authentication.
* Maintain the authenticated user's session within the PHP application.
* Prevent unauthorized access to protected pages.
* Handle authentication failures and cancelled authorization attempts gracefully.

## Proposed Authentication Flow

```text
User
│
│ Click "Continue with Google"
▼
PHP Application
│
│ Redirect to Google OAuth
▼
Google Authorization
│
│ User grants permission
▼
Google OAuth Callback
│
│ Authorization code
▼
PHP Backend
│
│ Exchange code for tokens
▼
Google OAuth Server
│
│ Access token / ID information
▼
PHP Application
│
│ Find or create local user
▼
PHP Session
│
▼
Authenticated User
```

## Implementation Tasks

### Google OAuth Configuration

* [ ] Create/configure a Google Cloud project.
* [ ] Configure the OAuth consent screen.
* [ ] Create OAuth 2.0 credentials.
* [ ] Configure the authorized redirect URI.
* [ ] Store the Google Client ID securely.
* [ ] Store the Google Client Secret securely.
* [ ] Ensure credentials are not committed to Git.

### Backend Integration

* [ ] Create a Google authentication endpoint.
* [ ] Redirect users to Google's authorization endpoint.
* [ ] Generate and validate the OAuth `state` parameter.
* [ ] Handle Google's OAuth callback.
* [ ] Exchange the authorization code for tokens.
* [ ] Retrieve the authenticated user's Google profile.
* [ ] Validate the returned user information.
* [ ] Find an existing local account using the Google account identifier/email.
* [ ] Create a local account when appropriate.
* [ ] Create a PHP session after successful authentication.

### Session & Authorization

* [ ] Implement authentication checks for protected pages.
* [ ] Prevent unauthenticated users from accessing protected resources.
* [ ] Implement logout functionality.
* [ ] Destroy the local session during logout.
* [ ] Regenerate the PHP session ID after successful authentication.

### Error Handling

Handle at least the following cases:

* [ ] User cancels Google authentication.
* [ ] Invalid or expired authorization code.
* [ ] Invalid OAuth `state`.
* [ ] Google authentication request fails.
* [ ] Google account information cannot be retrieved.
* [ ] Existing local account cannot be matched.
* [ ] Database operation fails.

## Security Requirements

* Never expose the Google Client Secret in frontend code.
* Never commit OAuth credentials to the repository.
* Store credentials using environment variables or a secure configuration mechanism.
* Validate the OAuth `state` parameter to protect against CSRF.
* Use HTTPS in production.
* Validate the identity information returned by Google.
* Store only the user information required by the application.
* Do not expose access tokens or client secrets in logs or error messages.

## Suggested User Data

Depending on the application's requirements, the following information may be stored:

```text
google_id
email
name
profile_picture
created_at
updated_at
```

The Google account's unique identifier should be used when associating a Google account with a local account rather than relying solely on the user's display name.

## Acceptance Criteria

* [ ] A user can click **Continue with Google**.
* [ ] The user is redirected to Google's authentication page.
* [ ] The user can authorize the application.
* [ ] Google redirects the user back to the configured callback URL.
* [ ] The PHP backend successfully processes the OAuth response.
* [ ] A new user can be created when no matching account exists.
* [ ] An existing user can sign in using their linked Google account.
* [ ] A PHP session is created after successful authentication.
* [ ] Protected pages require authentication.
* [ ] Users can log out successfully.
* [ ] Invalid or failed authentication attempts do not create an authenticated session.
* [ ] OAuth credentials are not exposed in the repository.

## References

* Google OAuth 2.0 Documentation: https://developers.google.com/identity/protocols/oauth2
* Google Identity Documentation: https://developers.google.com/identity