yourwillyourwish/docs/OAUTH_SETUP.md

# OAuth Setup Guide

This guide explains how to enable Google, GitHub, Facebook, and Discord authentication in the Estate Platform.

## Overview

The application supports OAuth sign-in through multiple providers. Once configured, users will see provider-specific login buttons on the login/register modal.

## Setup Instructions

### 1. Google OAuth Setup

#### Step 1: Create a Google Cloud Project
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Click the project dropdown and select "New Project"
3. Enter a project name (e.g., "Estate Platform") and click "Create"

#### Step 2: Enable Google+ API
1. In the Google Cloud Console, go to "APIs & Services" > "Library"
2. Search for "Google+ API"
3. Click on it and press "Enable"

#### Step 3: Create OAuth 2.0 Credentials
1. Go to "APIs & Services" > "Credentials"
2. Click "Create Credentials" > "OAuth Client ID"
3. If prompted, configure the OAuth consent screen first:
   - Select "External" user type
   - Fill in the required fields (app name, user support email, etc.)
   - Add scopes: `email`, `profile`
   - Add test users if needed
4. After consent screen setup, return to create credentials:
   - Application type: "Web Application"
   - Name: "Estate Platform"
   - Authorized JavaScript origins:
     - `http://localhost:3001` (development)
     - `https://yourdomain.com` (production)
   - Authorized redirect URIs:
     - `http://localhost:3001/auth/google/callback` (development)
     - `https://yourdomain.com/auth/google/callback` (production)
5. Click "Create" and copy your Client ID and Client Secret

#### Step 4: Add to System Configuration
1. Open or create `data/system-config.json`
2. Update the Google OAuth section:
```json
{
  "oauth": {
    "google": {
      "enabled": true,
      "clientId": "YOUR_GOOGLE_CLIENT_ID_HERE",
      "clientSecret": "YOUR_GOOGLE_CLIENT_SECRET_HERE"
    }
  }
}
```

### 2. GitHub OAuth Setup

#### Step 1: Create GitHub OAuth App
1. Go to GitHub Settings > Developer settings > [OAuth Apps](https://github.com/settings/developers)
2. Click "New OAuth App"
3. Fill in the form:
   - Application name: "Estate Platform"
   - Homepage URL: `http://localhost:3001` (development) or your domain
   - Application description: "Estate Platform - Digital Estate Planning"
   - Authorization callback URL:
     - `http://localhost:3001/auth/github/callback` (development)
     - `https://yourdomain.com/auth/github/callback` (production)
4. Click "Register application"

#### Step 2: Generate Client Secret
1. On the app details page, you'll see the Client ID
2. Click "Generate a new client secret" and copy it
3. Keep both Client ID and Client Secret safe

#### Step 3: Add to System Configuration
1. Open `data/system-config.json`
2. Update the GitHub OAuth section:
```json
{
  "oauth": {
    "github": {
      "enabled": true,
      "clientId": "YOUR_GITHUB_CLIENT_ID_HERE",
      "clientSecret": "YOUR_GITHUB_CLIENT_SECRET_HERE"
    }
  }
}
```

### 3. Facebook OAuth Setup

#### Step 1: Create Facebook App
1. Go to [Facebook Developers](https://developers.facebook.com/)
2. Click "My Apps" > "Create App"
3. Select "Consumer" as the app type
4. Fill in the app details:
   - App Name: "Estate Platform"
   - App Contact Email: your@email.com
   - App Purpose: Select appropriate category
5. Click "Create App"

#### Step 2: Add Facebook Login Product
1. In the app dashboard, click "Add Product"
2. Find "Facebook Login" and click "Set Up"
3. Choose "Web" as the platform
4. In the settings for Facebook Login:
   - Valid OAuth Redirect URIs:
     - `http://localhost:3001/auth/facebook/callback` (development)
     - `https://yourdomain.com/auth/facebook/callback` (production)
5. Save changes

#### Step 3: Get Credentials
1. Go to Settings > Basic to find:
   - App ID (Client ID)
   - App Secret (Client Secret)
2. Keep these secure

#### Step 4: Add to System Configuration
1. Open `data/system-config.json`
2. Update the Facebook OAuth section:
```json
{
  "oauth": {
    "facebook": {
      "enabled": true,
      "clientId": "YOUR_FACEBOOK_APP_ID_HERE",
      "clientSecret": "YOUR_FACEBOOK_APP_SECRET_HERE"
    }
  }
}
```

### 4. Discord OAuth Setup

#### Step 1: Create Discord Application
1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
2. Click "New Application"
3. Enter a name (e.g., "Estate Platform") and click "Create"

#### Step 2: Generate OAuth Credentials
1. In the left sidebar, click "OAuth2"
2. Copy the "Client ID"
3. Under "CLIENT SECRET", click "Reset Secret" and copy it

#### Step 3: Add Redirect URLs
1. In OAuth2 settings, scroll to "Redirects"
2. Click "Add Redirect" and add:
   - `http://localhost:3001/auth/discord/callback` (development)
   - `https://yourdomain.com/auth/discord/callback` (production)
3. Click "Save Changes"

#### Step 4: Add to System Configuration
1. Open `data/system-config.json`
2. Update the Discord OAuth section:
```json
{
  "oauth": {
    "discord": {
      "enabled": true,
      "clientId": "YOUR_DISCORD_CLIENT_ID_HERE",
      "clientSecret": "YOUR_DISCORD_CLIENT_SECRET_HERE"
    }
  }
}
```

## Verification

After configuring any provider:

1. Restart your development server: `npm run dev`
2. Visit the login/register page
3. You should see buttons for enabled providers
4. Test the OAuth flow by clicking a provider button

## Environment Variables (Alternative Method)

Instead of `system-config.json`, you can set environment variables:

```bash
# Google
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

# GitHub
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret

# Facebook
FACEBOOK_CLIENT_ID=your_facebook_client_id
FACEBOOK_CLIENT_SECRET=your_facebook_client_secret

# Discord
DISCORD_CLIENT_ID=your_discord_client_id
DISCORD_CLIENT_SECRET=your_discord_client_secret
```

## Troubleshooting

### "Invalid Client ID" Error
- Verify the Client ID is correct and matches the provider
- Check that the redirect URI is exactly correct (including protocol and path)
- Ensure the OAuth app is in the correct environment (development vs production)

### Redirect URI Mismatch
- Common issue: mixing `http://` and `https://`
- Ensure the redirect URI in the provider settings matches exactly:
  - `http://localhost:3001/auth/[provider]/callback`

### User Not Created After OAuth
- Check database connectivity
- Verify email is being returned from the OAuth provider
- Check server logs for error messages

### Session Not Persisting
- Clear browser cookies and try again
- Verify JWT secret is configured in `system-config.json` or `.env`
- Check that httpOnly cookies are enabled

## Security Notes

- **Never commit credentials** to version control
- Use environment variables for production
- Regularly rotate secrets in provider dashboards
- Use HTTPS in production (required by most providers)
- Keep Redirect URIs restricted to your domain only
- Monitor OAuth app usage in provider dashboards

## Disabling Providers

To disable a provider:

1. Set `"enabled": false` in `system-config.json`, or
2. Remove the environment variable, or
3. Leave the Client ID and Client Secret empty

The OAuth buttons will not appear for disabled providers.

## Support

For issues with specific providers, refer to their documentation:
- [Google OAuth Documentation](https://developers.google.com/identity/protocols/oauth2)
- [GitHub OAuth Documentation](https://docs.github.com/en/developers/apps/building-oauth-apps)
- [Facebook Login Documentation](https://developers.facebook.com/docs/facebook-login)
- [Discord OAuth Documentation](https://discord.com/developers/docs/topics/oauth2)