Trackeep/Others/oauth-service/README-OLD.md

Centralized OAuth Service

This is a standalone OAuth service that handles GitHub authentication and email verification for all users. Users never need to set up their own OAuth applications - everything is centralized.

🎯 How It Works

For Users:

1. GitHub OAuth: Click "Connect GitHub" → GitHub authorization → Automatic login with GitHub profile
2. Email Verification: Enter email → Receive verification code → Verify email for 2FA

For Developers:

1. Zero setup - No OAuth app creation needed
2. Simple integration - Just redirect to our service
3. Secure authentication - We handle all the complexity
4. User management - Centralized user database

🚀 Quick Start

1. Setup the OAuth Service

# Navigate to the OAuth service
cd oauth-service

# Run the setup script
./setup.sh

# Edit the .env file with your GitHub OAuth credentials
nano .env

# Start the service
go run main.go

2. GitHub OAuth App Setup (One Time)

1. Go to GitHub Settings → Developer settings → OAuth Apps
2. Create a new OAuth app with:
   • Application name: Trackeep OAuth Service
   • Homepage URL: http://localhost:9090
   • Authorization callback URL: http://localhost:9090/auth/github/callback
3. Copy the Client ID and Client Secret to .env

3. Email Verification Setup (One Time)

1. Configure smtp.purelymail.com for sending verification emails:
   • SMTP Host: smtp.purelymail.com
   • SMTP Port: 587
   • Username: Your purelymail SMTP username
   • Password: Your purelymail SMTP password
2. Add SMTP credentials to .env file
3. The service will send 6-digit verification codes for 2FA

4. Integration in Your App

// Redirect to GitHub OAuth
const connectGitHub = () => {
  window.location.href = 'http://localhost:9090/auth/github?redirect_uri=' + 
    encodeURIComponent(window.location.origin);
};

// Send email verification code
const sendEmailVerification = (email) => {
  fetch('http://localhost:9090/api/v1/email/send', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email })
  }).then(response => response.json())
    .then(data => {
      if (data.demo_code) {
        console.log('Demo verification code:', data.demo_code);
      }
    });
};

// Verify email code
const verifyEmailCode = (email, code) => {
  fetch('http://localhost:9090/api/v1/email/verify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, code })
  }).then(response => response.json())
    .then(data => {
      if (data.verified) {
        console.log('Email verified successfully!');
      }
    });
};

// Handle callback (works for both GitHub and Email)
const handleCallback = () => {
  const urlParams = new URLSearchParams(window.location.search);
  const token = urlParams.get('token');
  const username = urlParams.get('user');
  
  if (token) {
    localStorage.setItem('token', token);
    localStorage.setItem('username', username);
    // Redirect to dashboard
    window.location.href = '/app';
  }
};

📡 API Endpoints

OAuth Endpoints:

• GET /auth/github - Initiate GitHub OAuth flow
• GET /auth/github/callback - Handle GitHub callback

Email Verification Endpoints:

• POST /api/v1/email/send - Send verification code to email
• POST /api/v1/email/verify - Verify email code for 2FA

API Endpoints:

• GET /api/v1/user/me - Get current user info
• GET /api/v1/user/:username/repos - Get user repositories
• POST /api/v1/webhook/github - GitHub webhook handler
• POST /api/v1/email/verify - Verify email code

Utility:

• GET /health - Service health check

🔧 Configuration

Environment Variables:

# GitHub OAuth (Admin Only)
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GITHUB_REDIRECT_URL=http://localhost:9090/auth/github/callback

# Email Verification Configuration (Admin Only)
SMTP_HOST=smtp.purelymail.com
SMTP_PORT=587
SMTP_USERNAME=your_purelymail_username
SMTP_PASSWORD=your_purelymail_password

# Service Configuration
PORT=9090
JWT_SECRET=your-super-secret-jwt-key
DEFAULT_CLIENT_URL=http://localhost:5173

# CORS
CORS_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:8080

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   User App      │    │  OAuth Service   │    │     GitHub      │
│                 │    │                  │    │                 │
│ Connect GitHub ─┼───>│ /auth/github     ────>│ OAuth Flow      │
│                 │    │                  │    │                 │
│ Handle Callback │<───>│ /auth/callback   │<───>│ Return Token   │
│                 │    │                  │    │                 │
│ Store Token     │    │ Generate JWT     │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘

🔒 Security Features

• CSRF Protection: State parameter validation
• Secure JWT: Signed tokens with expiration
• CORS Support: Configurable allowed origins
• Webhook Support: Optional webhook secret validation
• Rate Limiting: GitHub API rate limit awareness

📊 User Management

The service maintains a centralized user database:

type User struct {
    ID        int       `json:"id"`
    GitHubID  int       `json:"github_id"`
    Username  string    `json:"username"`
    Email     string    `json:"email"`
    Name      string    `json:"name"`
    AvatarURL string    `json:"avatar_url"`
    CreatedAt time.Time `json:"created_at"`
    LastLogin time.Time `json:"last_login"`
}

🔄 Multi-Application Support

The same OAuth service can serve multiple applications:

// App 1
window.location.href = 'http://localhost:9090/auth/github?redirect_uri=http://app1.com';

// App 2  
window.location.href = 'http://localhost:9090/auth/github?redirect_uri=http://app2.com';

// App 3
window.location.href = 'http://localhost:9090/auth/github?redirect_uri=http://app3.com';

🚀 Production Deployment

Docker Deployment:

FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY . .
RUN go mod download && go build -o oauth-service

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/oauth-service .
COPY .env .
EXPOSE 9090
CMD ["./oauth-service"]

Docker Compose:

version: '3.8'
services:
  oauth-service:
    build: ./oauth-service
    ports:
      - "9090:9090"
    environment:
      - GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}
      - GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}
      - JWT_SECRET=${JWT_SECRET}
    restart: unless-stopped

🛠️ Development

# Install dependencies
go mod tidy

# Run in development
go run main.go

# Build for production
go build -o oauth-service main.go

# Run tests
go test ./...

📝 Benefits

For Users:

• ✅ Zero configuration - No OAuth app setup
• ✅ Single sign-on - One GitHub account for all apps
• ✅ Secure - Enterprise-grade security
• ✅ Fast - Instant authentication

For Developers:

• ✅ Easy integration - Just redirect to our service
• ✅ No OAuth management - We handle everything
• ✅ Centralized users - Shared user database
• ✅ Scalable - Serve unlimited applications

For Administrators:

• ✅ Single control point - Manage all OAuth in one place
• ✅ Security oversight - Monitor all authentication
• ✅ Easy updates - Update OAuth settings once
• ✅ Cost effective - One OAuth app for all services

🎯 Use Cases

• SaaS platforms - Multiple products, one authentication
• Development teams - Internal tools with GitHub login
• Open source projects - Contributor authentication
• Enterprise - Internal service authentication
• API services - Secure API access with GitHub OAuth

This service completely abstracts away OAuth complexity while providing enterprise-grade authentication for all your applications!