aven 0.0.1 → 0.0.2

data/app/controllers/aven/oauth/documentation/github.md

@@ -0,0 +1,329 @@
+# GitHub OAuth Implementation Documentation
+
+## Overview
+
+GitHub OAuth 2.0 integration for the Aven application. This implementation supports authentication using GitHub accounts.
+
+**Controller**: `app/controllers/aven/oauth/github_controller.rb`
+**Routes**: `config/routes.rb:22-24`
+
+---
+
+## Default Scopes
+
+```
+user:email
+```
+
+### Scope Breakdown
+
+| Scope | Purpose | Description |
+|-------|---------|-------------|
+| `user:email` | Read email addresses | Grants read-only access to user's email addresses (including private emails) |
+
+**Note**: GitHub scopes don't require admin approval. Users consent individually.
+
+---
+
+## OAuth 2.0 Flow
+
+### 1. Authorization Request
+
+**Endpoint**: `https://github.com/login/oauth/authorize`
+
+**Parameters**:
+```ruby
+{
+  client_id: "YOUR_CLIENT_ID",
+  redirect_uri: "https://yourdomain.com/oauth/github/callback",
+  scope: "user:email",
+  state: "RANDOM_STATE_TOKEN"
+}
+```
+
+### 2. Token Exchange
+
+**Endpoint**: `https://github.com/login/oauth/access_token`
+
+**Parameters**:
+```ruby
+{
+  client_id: "YOUR_CLIENT_ID",
+  client_secret: "YOUR_CLIENT_SECRET",
+  code: "AUTHORIZATION_CODE",
+  redirect_uri: "https://yourdomain.com/oauth/github/callback"
+}
+```
+
+**Headers**:
+```ruby
+{
+  "Accept" => "application/json"
+}
+```
+
+### 3. User Info Retrieval
+
+**User Profile Endpoint**: `https://api.github.com/user`
+
+**Response**:
+```json
+{
+  "id": 12345678,
+  "login": "johndoe",
+  "name": "John Doe",
+  "email": "john@example.com",
+  "avatar_url": "https://avatars.githubusercontent.com/u/12345678",
+  "bio": "Developer",
+  "company": "Acme Inc"
+}
+```
+
+**User Emails Endpoint**: `https://api.github.com/user/emails`
+
+Used when public email is not available.
+
+**Response**:
+```json
+[
+  {
+    "email": "john@example.com",
+    "primary": true,
+    "verified": true,
+    "visibility": "private"
+  }
+]
+```
+
+**Implementation Logic**:
+- First tries to get email from user profile
+- If email is null/blank, fetches from `/user/emails` endpoint
+- Uses the primary verified email
+
+---
+
+## Configuration
+
+### Application Configuration
+
+```ruby
+config.oauth_providers = {
+  github: {
+    client_id: ENV['GITHUB_CLIENT_ID'],
+    client_secret: ENV['GITHUB_CLIENT_SECRET'],
+    # Optional configurations:
+    scope: "user:email read:user"
+  }
+}
+```
+
+### Environment Variables
+
+```bash
+GITHUB_CLIENT_ID=Iv1.a1b2c3d4e5f6g7h8
+GITHUB_CLIENT_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
+```
+
+---
+
+## GitHub OAuth App Setup
+
+### 1. Create OAuth App
+
+1. Go to [GitHub Settings](https://github.com/settings/developers)
+2. Click **OAuth Apps** > **New OAuth App**
+3. Fill in:
+   - **Application name**: Your application name
+   - **Homepage URL**: `https://yourdomain.com`
+   - **Authorization callback URL**: `https://yourdomain.com/oauth/github/callback`
+   - **Application description**: (optional)
+4. Click **Register application**
+5. Copy the **Client ID**
+6. Click **Generate a new client secret**
+7. Copy the **Client Secret** (shown only once)
+
+### 2. Note Your Credentials
+
+- **Client ID**: `Iv1.a1b2c3d4e5f6g7h8`
+- **Client Secret**: `a1b2c3d4e5f6g7h8i9j0...`
+
+---
+
+## Routes
+
+```ruby
+# GitHub OAuth
+get "github", to: "github#create", as: :github
+get "github/callback", to: "github#callback", as: :github_callback
+```
+
+**Available Routes**:
+- `GET /oauth/github` → Initiates OAuth flow
+- `GET /oauth/github/callback` → Handles OAuth callback
+
+**Named Routes**:
+- `oauth_github_path` → `/oauth/github`
+- `oauth_github_callback_path` → `/oauth/github/callback`
+
+---
+
+## Additional Scopes (Optional)
+
+### User Information
+
+```ruby
+scope: "user:email read:user"
+```
+
+- `read:user` - Read all user profile data
+- `user` - Full access to user profile (read and write)
+
+### Repository Access
+
+```ruby
+scope: "user:email repo"
+```
+
+- `repo` - Full control of private repositories
+- `public_repo` - Access to public repositories only
+
+### Organization Access
+
+```ruby
+scope: "user:email read:org"
+```
+
+- `read:org` - Read org and team membership
+- `write:org` - Manage org and teams
+
+### Gist Access
+
+```ruby
+scope: "user:email gist"
+```
+
+- `gist` - Create and edit gists
+
+---
+
+## GitHub API Usage
+
+After authentication, use the access token to call GitHub API v3:
+
+### Get User Repositories
+
+```ruby
+GET https://api.github.com/user/repos
+Authorization: Bearer {access_token}
+Accept: application/vnd.github.v3+json
+```
+
+### Get User Organizations
+
+```ruby
+GET https://api.github.com/user/orgs
+Authorization: Bearer {access_token}
+Accept: application/vnd.github.v3+json
+```
+
+### Get Authenticated User
+
+```ruby
+GET https://api.github.com/user
+Authorization: Bearer {access_token}
+Accept: application/vnd.github.v3+json
+```
+
+---
+
+## Official Documentation
+
+1. **GitHub OAuth Documentation**
+   https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps
+
+2. **GitHub API Documentation**
+   https://docs.github.com/en/rest
+
+3. **GitHub OAuth Scopes**
+   https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps
+
+4. **GitHub REST API - Users**
+   https://docs.github.com/en/rest/users/users
+
+---
+
+## Implementation Details
+
+### Email Handling
+
+The implementation has special logic for retrieving emails:
+
+```ruby
+# Fetch user profile
+user_data = github_api_request(USER_INFO_URL, access_token)
+
+# Fetch primary email if not public
+email = user_data[:email]
+if email.blank?
+  emails_data = github_api_request(USER_EMAIL_URL, access_token)
+  primary_email = emails_data.find { |e| e[:primary] && e[:verified] }
+  email = primary_email[:email] if primary_email
+end
+```
+
+This ensures we always get an email, even if the user's GitHub email is private.
+
+### API Request Headers
+
+GitHub requires specific headers:
+
+```ruby
+request["Authorization"] = "Bearer #{access_token}"
+request["Accept"] = "application/vnd.github.v3+json"
+```
+
+---
+
+## Troubleshooting
+
+### "redirect_uri_mismatch"
+
+**Solution**: Ensure the callback URL in your GitHub OAuth App settings exactly matches:
+```
+https://yourdomain.com/oauth/github/callback
+```
+
+### "bad_verification_code"
+
+**Solution**: The authorization code has already been used or expired. Ask user to try again.
+
+### No email returned
+
+**Solution**: Ensure you're requesting the `user:email` scope. The implementation will fallback to the `/user/emails` endpoint.
+
+### API rate limiting
+
+**Solution**: Authenticated requests have a limit of 5,000 requests per hour. For unauthenticated requests, it's 60 per hour.
+
+---
+
+## Security Considerations
+
+### Token Expiration
+
+GitHub access tokens **do not expire** by default (unlike other OAuth providers). This means:
+- Tokens remain valid until manually revoked
+- No need for refresh token logic
+- Important to handle token revocation properly
+
+Users can revoke access at: https://github.com/settings/applications
+
+### Scope Permissions
+
+Request only the minimum scopes needed:
+- ✅ `user:email` - For authentication only
+- ❌ `repo` - Don't request unless you need repository access
+
+---
+
+**Last Updated**: October 15, 2025

data/app/controllers/aven/oauth/documentation/google.md

@@ -0,0 +1,253 @@
+# Google OAuth Implementation Documentation
+
+## Overview
+
+Google OAuth 2.0 integration for the Aven application. This implementation supports authentication using Google accounts (both personal Gmail accounts and Google Workspace accounts).
+
+**Controller**: `app/controllers/aven/oauth/google_controller.rb`
+**Routes**: `config/routes.rb:18-20`
+
+---
+
+## Default Scopes
+
+```
+openid email profile
+```
+
+### Scope Breakdown
+
+| Scope | Purpose | Admin Consent Required |
+|-------|---------|------------------------|
+| `openid` | OpenID Connect authentication | No |
+| `email` | Access user's email address | No |
+| `profile` | Access user's basic profile (name, picture) | No |
+
+**Note**: These are basic OAuth scopes that don't require admin approval. Users consent individually.
+
+---
+
+## OAuth 2.0 Flow
+
+### 1. Authorization Request
+
+**Endpoint**: `https://accounts.google.com/o/oauth2/v2/auth`
+
+**Parameters**:
+```ruby
+{
+  client_id: "YOUR_CLIENT_ID",
+  redirect_uri: "https://yourdomain.com/oauth/google/callback",
+  response_type: "code",
+  scope: "openid email profile",
+  state: "RANDOM_STATE_TOKEN",
+  access_type: "offline",  # Optional: for refresh tokens
+  prompt: "select_account" # Optional: force account selection
+}
+```
+
+### 2. Token Exchange
+
+**Endpoint**: `https://www.googleapis.com/oauth2/v4/token`
+
+**Parameters**:
+```ruby
+{
+  code: "AUTHORIZATION_CODE",
+  client_id: "YOUR_CLIENT_ID",
+  client_secret: "YOUR_CLIENT_SECRET",
+  redirect_uri: "https://yourdomain.com/oauth/google/callback",
+  grant_type: "authorization_code"
+}
+```
+
+### 3. User Info Retrieval
+
+**Endpoint**: `https://www.googleapis.com/oauth2/v3/userinfo`
+
+**Response**:
+```json
+{
+  "sub": "1234567890",
+  "email": "user@gmail.com",
+  "email_verified": true,
+  "name": "John Doe",
+  "picture": "https://lh3.googleusercontent.com/a/..."
+}
+```
+
+---
+
+## Configuration
+
+### Application Configuration
+
+```ruby
+config.oauth_providers = {
+  google: {
+    client_id: ENV['GOOGLE_CLIENT_ID'],
+    client_secret: ENV['GOOGLE_CLIENT_SECRET'],
+    # Optional configurations:
+    scope: "openid email profile",
+    access_type: "offline",      # Receive refresh tokens
+    prompt: "select_account"     # Force account selection
+  }
+}
+```
+
+### Environment Variables
+
+```bash
+GOOGLE_CLIENT_ID=123456789-abcdefghijklmnop.apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=GOCSPX-your_client_secret
+```
+
+---
+
+## Google Cloud Console Setup
+
+### 1. Create OAuth Client ID
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com)
+2. Select or create a project
+3. Navigate to **APIs & Services** > **Credentials**
+4. Click **Create Credentials** > **OAuth client ID**
+5. Select **Web application**
+6. Configure:
+   - **Name**: Your application name
+   - **Authorized JavaScript origins**: `https://yourdomain.com`
+   - **Authorized redirect URIs**: `https://yourdomain.com/oauth/google/callback`
+7. Click **Create**
+8. Copy the **Client ID** and **Client Secret**
+
+### 2. Configure OAuth Consent Screen
+
+1. Go to **APIs & Services** > **OAuth consent screen**
+2. Select **External** (for public apps) or **Internal** (for Google Workspace only)
+3. Fill in:
+   - **App name**: Your application name
+   - **User support email**: Your email
+   - **Developer contact information**: Your email
+4. Add scopes (optional for basic profile)
+5. Save and continue
+
+### 3. Note Your Credentials
+
+- **Client ID**: `123456789-...apps.googleusercontent.com`
+- **Client Secret**: `GOCSPX-...`
+
+---
+
+## Routes
+
+```ruby
+# Google OAuth
+get "google", to: "google#create", as: :google
+get "google/callback", to: "google#callback", as: :google_callback
+```
+
+**Available Routes**:
+- `GET /oauth/google` → Initiates OAuth flow
+- `GET /oauth/google/callback` → Handles OAuth callback
+
+**Named Routes**:
+- `oauth_google_path` → `/oauth/google`
+- `oauth_google_callback_path` → `/oauth/google/callback`
+
+---
+
+## Additional Scopes (Optional)
+
+If you need access to more Google services, add these scopes:
+
+### Gmail API
+
+```ruby
+scope: "openid email profile https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/gmail.send"
+```
+
+- `gmail.readonly` - Read emails
+- `gmail.send` - Send emails
+- `gmail.modify` - Read and modify emails
+
+### Google Calendar
+
+```ruby
+scope: "openid email profile https://www.googleapis.com/auth/calendar.readonly"
+```
+
+- `calendar.readonly` - Read calendar events
+- `calendar` - Full calendar access
+
+### Google Drive
+
+```ruby
+scope: "openid email profile https://www.googleapis.com/auth/drive.readonly"
+```
+
+- `drive.readonly` - Read Drive files
+- `drive.file` - Access files created by app
+- `drive` - Full Drive access
+
+**Important**: Extended scopes may require verification by Google if your app is public.
+
+---
+
+## Official Documentation
+
+1. **Google OAuth 2.0 Guide**
+   https://developers.google.com/identity/protocols/oauth2
+
+2. **Using OAuth 2.0 to Access Google APIs**
+   https://developers.google.com/identity/protocols/oauth2/web-server
+
+3. **Google API Scopes**
+   https://developers.google.com/identity/protocols/oauth2/scopes
+
+4. **OpenID Connect**
+   https://developers.google.com/identity/openid-connect/openid-connect
+
+---
+
+## Security Considerations
+
+### Refresh Tokens
+
+Set `access_type: "offline"` to receive refresh tokens for long-term access:
+
+```ruby
+access_type: oauth_config[:access_type] || "offline"
+```
+
+### Account Selection
+
+Use `prompt: "select_account"` to force users to select which Google account to use:
+
+```ruby
+prompt: oauth_config[:prompt] || "select_account"
+```
+
+This is useful if users have multiple Google accounts.
+
+---
+
+## Troubleshooting
+
+### "redirect_uri_mismatch"
+
+**Solution**: Ensure the redirect URI in Google Cloud Console exactly matches:
+```
+https://yourdomain.com/oauth/google/callback
+```
+
+### "invalid_client"
+
+**Solution**: Check that your Client ID and Client Secret are correct.
+
+### "access_denied"
+
+**Solution**: User declined the consent screen. This is normal user behavior.
+
+---
+
+**Last Updated**: October 15, 2025

data/app/controllers/aven/oauth/entra_id_controller.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module Aven
+  module Oauth
+    class EntraIdController < BaseController
+      # Microsoft Entra ID (formerly Azure AD) OAuth endpoints
+      # Supports both single-tenant and multi-tenant configurations
+      #
+      # MINIMAL_SCOPE: Authentication only (no Graph API access)
+      # Use this for simple login without accessing user data beyond basic profile
+      MINIMAL_SCOPE = "openid email profile"
+
+      # DEFAULT_SCOPE: Includes Graph API access for contacts and email
+      DEFAULT_SCOPE = "openid email profile User.Read Contacts.Read Mail.Send Mail.Read"
+
+      protected
+
+        def authorization_url(state)
+          params = {
+            client_id: oauth_config[:client_id],
+            redirect_uri: callback_url,
+            response_type: "code",
+            scope: oauth_config[:scope] || DEFAULT_SCOPE,
+            state:,
+            response_mode: "query"
+          }
+
+          # Optionally add domain_hint for faster login
+          params[:domain_hint] = oauth_config[:domain_hint] if oauth_config[:domain_hint].present?
+
+          # Optionally add prompt parameter
+          params[:prompt] = oauth_config[:prompt] if oauth_config[:prompt].present?
+
+          "#{entra_authorization_url}?#{params.to_query}"
+        end
+
+        def exchange_code_for_token(code)
+          params = {
+            client_id: oauth_config[:client_id],
+            client_secret: oauth_config[:client_secret],
+            code:,
+            redirect_uri: callback_url,
+            grant_type: "authorization_code",
+            scope: oauth_config[:scope] || DEFAULT_SCOPE
+          }
+
+          oauth_request(URI(entra_token_url), params)
+        end
+
+        def fetch_user_info(access_token)
+          response = oauth_get_request(URI(entra_userinfo_url), access_token)
+
+          {
+            id: response[:id] || response[:sub],
+            email: response[:mail] || response[:userPrincipalName] || response[:email],
+            name: response[:displayName] || response[:name],
+            picture: nil # Microsoft Graph doesn't return picture in userinfo by default
+          }
+        end
+
+      private
+
+        def callback_url
+          aven.oauth_entra_id_callback_url(host: request.host, protocol: "https://")
+        end
+
+        def oauth_config
+          @oauth_config ||= Aven.configuration.oauth_providers[:entra_id] || raise("Microsoft Entra ID OAuth not configured")
+        end
+
+        def tenant_id
+          @tenant_id ||= oauth_config[:tenant_id] || "common"
+        end
+
+        def entra_authorization_url
+          "https://login.microsoftonline.com/#{tenant_id}/oauth2/v2.0/authorize"
+        end
+
+        def entra_token_url
+          "https://login.microsoftonline.com/#{tenant_id}/oauth2/v2.0/token"
+        end
+
+        def entra_userinfo_url
+          # Using Microsoft Graph API for user info
+          "https://graph.microsoft.com/v1.0/me"
+        end
+    end
+  end
+end