yourwillyourwish/docs/BETTERAUTH_OAUTH_ADMIN_SETUP.md

# BetterAuth OAuth Configuration - Admin Setup Guide

## Overview
Your application uses **BetterAuth** framework for OAuth authentication. OAuth providers (Google, GitHub, Facebook, Discord) can be:
- ✅ Configured via `/admin/setup` page (recommended)
- ✅ Enabled/disabled dynamically without server restart
- ✅ Credentials saved to `data/system-config.json`

## Quick Start

### 1. Access Admin Setup Page
```
http://localhost:3001/admin/setup
```

### 2. Scroll to "OAuth Providers (BetterAuth)" Section
You'll see 4 provider cards:
- 🔍 Google
- 🐙 GitHub  
- 👍 Facebook
- 💬 Discord

### 3. For Each Provider You Want to Enable:
1. Check the "Enable [Provider] OAuth" checkbox
2. Enter Client ID and Client Secret
3. Click "💾 Save Settings"

---

## Getting OAuth Credentials

### 🔍 Google OAuth Setup

#### Step 1: Create Google Cloud Project
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Click "Select a Project" → "New Project"
3. Enter project name: `estate-platform`
4. Click "Create"

#### Step 2: Enable OAuth 2.0
1. In sidebar, go to **APIs & Services** → **Library**
2. Search for "Google+ API"
3. Click it and click "Enable"

#### Step 3: Create OAuth Credentials
1. Go to **APIs & Services** → **Credentials**
2. Click "Create Credentials" → "OAuth client ID"
3. Choose application type: **Web application**
4. Name it: `estate-platform-web`

#### Step 4: Configure Redirect URIs
In the "Authorized redirect URIs" section, add:
```
http://localhost:3001/auth/google/callback
```

For production, also add:
```
https://yourdomain.com/auth/google/callback
```

#### Step 5: Copy Credentials
1. Click your created credential
2. Copy the **Client ID** and **Client Secret**
3. Paste them in the Google section on `/admin/setup`

---

### 🐙 GitHub OAuth Setup

#### Step 1: Register OAuth Application
1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
2. Click "OAuth Apps" → "New OAuth App"
3. Fill in:
   - **Application name**: `estate-platform`
   - **Homepage URL**: `http://localhost:3001`
   - **Authorization callback URL**: `http://localhost:3001/auth/github/callback`

#### Step 2: Copy Credentials
1. You'll see **Client ID** immediately
2. Click "Generate a new client secret"
3. Copy both **Client ID** and **Client Secret**
4. Paste them in the GitHub section on `/admin/setup`

#### For Production:
Update the callback URL to:
```
https://yourdomain.com/auth/github/callback
```

---

### 👍 Facebook OAuth Setup

#### Step 1: Create Facebook App
1. Go to [Facebook Developers](https://developers.facebook.com/)
2. Click "My Apps" → "Create App"
3. Choose app type: **Consumer**
4. Fill in app details:
   - **App Name**: `estate-platform`
   - **App Contact Email**: your-email@example.com
   - **Purpose**: Select appropriate category

#### Step 2: Add Facebook Login Product
1. In app dashboard, click "Add Product"
2. Find "Facebook Login" and click "Set Up"
3. Choose platform: **Web**
4. Skip to "Settings"

#### Step 3: Configure OAuth Redirect URLs
1. In **Facebook Login** → **Settings**
2. Under "Valid OAuth Redirect URIs", add:
   ```
   http://localhost:3001/auth/facebook/callback
   ```
   
   For production:
   ```
   https://yourdomain.com/auth/facebook/callback
   ```

#### Step 4: Copy Credentials
1. Go to **Settings** → **Basic**
2. Copy **App ID** (use as Client ID)
3. Copy **App Secret** (use as Client Secret)
4. Paste them in the Facebook section on `/admin/setup`

---

### 💬 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 name: `estate-platform`
4. Accept terms and create

#### Step 2: Generate OAuth Credentials
1. In sidebar, click "OAuth2"
2. Under **CLIENT INFORMATION**, you'll see:
   - **CLIENT ID** (copy this)
   - Click "Reset Secret" to get **CLIENT SECRET** (copy this)

#### Step 3: Set Redirect URI
1. Under **REDIRECTS**, click "Add Redirect"
2. Enter: `http://localhost:3001/auth/discord/callback`
3. Click "Save Changes"

For production:
```
https://yourdomain.com/auth/discord/callback
```

#### Step 4: Paste Credentials
Copy Client ID and Client Secret to Discord section on `/admin/setup`

---

## Configuration via Admin Setup Page

### Location
```
/admin/setup
```

### What You'll See
A clean 2x2 grid of OAuth provider cards:

```
┌─────────────────────────┬─────────────────────────┐
│ 🔍 Google               │ 🐙 GitHub               │
│                         │                         │
│ ☐ Enable Google OAuth   │ ☐ Enable GitHub OAuth   │
│ [Client ID input]       │ [Client ID input]       │
│ [Client Secret input]   │ [Client Secret input]   │
└─────────────────────────┴─────────────────────────┘
┌─────────────────────────┬─────────────────────────┐
│ 👍 Facebook             │ 💬 Discord              │
│                         │                         │
│ ☐ Enable Facebook OAuth │ ☐ Enable Discord OAuth  │
│ [App ID input]          │ [Client ID input]       │
│ [App Secret input]      │ [Client Secret input]   │
└─────────────────────────┴─────────────────────────┘
```

### How to Configure

#### For Each Provider:
1. **Check the checkbox** to enable OAuth for that provider
2. **Enter Client ID** - The public identifier from the provider
3. **Enter Client Secret** - Keep this secret! Only use in secure environments
4. **Click "💾 Save Settings"** at the bottom

### What Happens After Saving
- Credentials are saved to `data/system-config.json`
- BetterAuth automatically picks up the new configuration
- OAuth buttons appear on login page for enabled providers
- Users can immediately use OAuth sign-in

---

## Testing OAuth Flow

### Step 1: Enable at Least One Provider
Go to `/admin/setup` and enable Google (easiest to test)

### Step 2: Visit Login Page
Go to `http://localhost:3001` and click login button

### Step 3: Click OAuth Button
Click "Continue with Google" button

### Step 4: Verify Redirect
You should be redirected to Google's login page:
```
https://accounts.google.com/o/oauth2/v2/auth?client_id=...
```

### Step 5: Complete Authentication
1. Sign in with your Google account
2. Grant permissions if prompted
3. You should be redirected back and logged in

---

## Troubleshooting

### OAuth Buttons Don't Show
**Problem**: No OAuth buttons on login page even after configuration
**Solutions**:
1. Clear browser cache: `Ctrl+Shift+Delete`
2. Refresh page: `Ctrl+R`
3. Check admin setup page - provider might not be enabled
4. Verify JSON syntax in system-config.json

### "Invalid Client ID" Error
**Problem**: Error when trying to use OAuth
**Solutions**:
1. Verify Client ID is correct - copy from developer console again
2. Check spelling - no extra spaces
3. Ensure provider is enabled (checkbox checked)
4. Restart server: `npm run dev`

### Redirect URI Mismatch
**Problem**: Provider says "redirect_uri mismatch"
**Solutions**:
1. Verify exact callback URL in provider console:
   - Development: `http://localhost:3001/auth/{provider}/callback`
   - Production: `https://yourdomain.com/auth/{provider}/callback`
2. Check for typos - URLs are case-sensitive
3. Don't include query parameters
4. Save changes in provider console

### "Invalid Client Secret"
**Problem**: Error during OAuth callback
**Solutions**:
1. Double-check Client Secret - copy from provider console again
2. Ensure no extra spaces before/after
3. Verify it's not Client ID instead
4. Some providers show secret only once - regenerate if lost

### Provider Not Responding
**Problem**: Redirect hangs or takes forever
**Solutions**:
1. Check internet connection
2. Verify provider status page - provider may be down
3. Check firewall - may be blocking external requests
4. Check `BETTER_AUTH_SECRET` is set in .env

---

## Environment Variables (Optional)

Instead of using admin setup page, you can set environment variables in `.env`:

```bash
# Google OAuth
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

# GitHub OAuth
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

# Facebook OAuth
FACEBOOK_CLIENT_ID=your-app-id
FACEBOOK_CLIENT_SECRET=your-app-secret

# Discord OAuth
DISCORD_CLIENT_ID=your-client-id
DISCORD_CLIENT_SECRET=your-client-secret

# BetterAuth Secret (REQUIRED)
BETTER_AUTH_SECRET=your-32-character-secret
```

**Note**: Admin setup page takes precedence over environment variables

---

## Production Deployment

### Important Security Notes:
1. **Never commit credentials** to Git
2. **Use environment variables** in production (not system-config.json)
3. **Use HTTPS** for all callback URLs
4. **Enable CSRF protection** (currently disabled for development)
5. **Rotate secrets** regularly

### Callback URL Format:
```
https://yourdomain.com/auth/{provider}/callback
```

Replace with your actual domain for each provider!

### Update Provider Consoles:
1. Google Cloud Console
2. GitHub OAuth App Settings
3. Facebook App Settings
4. Discord Developer Portal

All must have production URL as redirect URI.

---

## File Locations

### Configuration Storage
```
data/system-config.json
```

Example structure:
```json
{
  "oauth": {
    "google": {
      "enabled": true,
      "clientId": "YOUR_CLIENT_ID",
      "clientSecret": "YOUR_CLIENT_SECRET"
    },
    "github": {
      "enabled": true,
      "clientId": "YOUR_CLIENT_ID",
      "clientSecret": "YOUR_CLIENT_SECRET"
    },
    "facebook": {
      "enabled": true,
      "clientId": "YOUR_APP_ID",
      "clientSecret": "YOUR_APP_SECRET"
    },
    "discord": {
      "enabled": true,
      "clientId": "YOUR_CLIENT_ID",
      "clientSecret": "YOUR_CLIENT_SECRET"
    }
  }
}
```

### BetterAuth Configuration
```
lib/auth.ts
```

### Admin Setup Page
```
app/admin/setup/page.tsx
```

### OAuth Callback Routes
```
app/auth/google/callback/route.ts
app/auth/github/callback/route.ts
app/auth/facebook/callback/route.ts
app/auth/discord/callback/route.ts
```

### Frontend Login Modal
```
components/auth/AuthModal.tsx
```

---

## Summary

✅ **OAuth is configured via BetterAuth framework**
✅ **Admin setup page at `/admin/setup` for easy configuration**
✅ **Support for 4 major OAuth providers**
✅ **Enable/disable providers without server restart**
✅ **Credentials saved in system-config.json**

For detailed setup of each provider, follow the step-by-step guides above!