clavis 0.7.1 → 0.8.0

data/README.md

@@ -8,36 +8,37 @@ You should be able to install and go in 5 minutes.
 
 > 🔑 **Fun fact**: The name "Clavis" comes from the Latin word for "key" - a fitting name for a gem that unlocks secure authentication!
 
+## Assumptions
+
+Before installing Clavis, note these assumptions:
+
+1. You're using 8+
+2. You've got a User model (maybe has_secure_password, maybe not)
+3. You want speed over configuration flexibility
+
 ## Quick Start Guide
 
-Get up and running with OAuth authentication in just three steps:
+Get up and running with OAuth authentication in these simple steps:
+
+### Step 1: Installation
 
 ```ruby
-# 1. Add to your Gemfile and run bundle install
+# Add to your Gemfile and run bundle install
 gem 'clavis'
 ```
 
 ```bash
-# 2. Run the installation generator
-# This automatically:
-#   - Creates the necessary migrations
-#   - Creates a configuration initializer
-#   - Adds OAuth fields to your User model
-#   - Mounts the engine at '/auth' in routes.rb
+# Run the installation generator
 rails generate clavis:install
 rails db:migrate
 ```
 
+### Step 2: Configuration
+
 ```ruby
-# 3. Configure a provider (in config/initializers/clavis.rb)
-# The generator created this file for you - just update with your credentials
+# Configure a provider in config/initializers/clavis.rb
 Clavis.configure do |config|
   config.providers = {
-    google: {
-      client_id: ENV['GOOGLE_CLIENT_ID'],
-      client_secret: ENV['GOOGLE_CLIENT_SECRET'],
-      redirect_uri: 'https://your-app.com/auth/google/callback'
-    },
     github: {
       client_id: ENV['GITHUB_CLIENT_ID'],
       client_secret: ENV['GITHUB_CLIENT_SECRET'],
@@ -47,11 +48,56 @@ Clavis.configure do |config|
 end
 ```
 
-Then add an OAuth login button to your view:
+### Step 3: Add OAuth Button
+
 ```erb
+<!-- Add to your login view -->
 <%= clavis_oauth_button :github %>
 ```
 
+### Step 4: ⚠️ IMPORTANT - Customize User Creation
+
+You MUST customize the user creation code to include all required fields for your User model:
+
+```ruby
+# Edit app/models/concerns/clavis_user_methods.rb
+def find_or_create_from_clavis(auth_hash)
+  # ... existing identity lookup code ...
+  
+  if user.nil?
+    info = auth_hash[:info].with_indifferent_access if auth_hash[:info]
+    
+    user = new(
+      email: info&.dig(:email),
+      # Add your required fields here:
+      first_name: info&.dig(:given_name) || info&.dig(:first_name),
+      last_name: info&.dig(:family_name) || info&.dig(:last_name)
+      # Add other required fields specific to your User model
+    )
+    
+    user.skip_password_validation = true
+    user.save!
+  end
+  
+  # ... create identity and return user ...
+end
+```
+
+### For Password-Protected Users
+
+If your User model uses `has_secure_password`, handle password validation:
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  include ClavisUserMethods
+  
+  # Skip password validation for OAuth users
+  validates :password, presence: true, 
+    unless: -> { skip_password_validation }, on: :create
+end
+```
+
 That's it! You now have "Sign in with GitHub" functionality in your Rails app.
 
 If you are an AI Agent or LLM, read this: [llms.md](llms.md)
@@ -61,40 +107,26 @@ If you are a human, who likes reading documentation, and you recently touched gr
 ## Table of Contents
 
 1. [Assumptions](#assumptions)
-2. [Installation](#installation)
-3. [Basic Configuration](#basic-configuration)
-4. [Database Setup](#database-setup)
-5. [Controller Integration](#controller-integration)
-6. [User Model Integration](#user-model-integration)
-7. [View Integration](#view-integration)
-8. [Routes Configuration](#routes-configuration)
-9. [Session Management](#session-management)
-10. [Integration with has_secure_password](#integration-with-has_secure_password)
-11. [Token Refresh](#token-refresh)
-12. [Custom Providers](#custom-providers)
-13. [Provider-Specific Setup](#provider-specific-setup)
-14. [Rate Limiting](#rate-limiting)
-15. [Testing Your Integration](#testing-your-integration)
-16. [Troubleshooting](#troubleshooting)
-17. [Development](#development)
-18. [Contributing](#contributing)
-19. [License](#license)
-20. [Code of Conduct](#code-of-conduct)
-
-## Assumptions
-
-Before installing Clavis, note these assumptions:
-
-1. You're using Rails 7+
-2. You've got a User model and some form of authentication already
-3. You want speed over configuration flexibility
-
-## Installation
+2. [Quick Start Guide](#quick-start-guide)
+3. [Installation & Setup](#installation--setup)
+4. [Configuration](#configuration)
+5. [User Management](#user-management)
+6. [View Integration](#view-integration)
+7. [Advanced Features](#advanced-features)
+8. [Provider Setup](#provider-setup)
+9. [Security & Rate Limiting](#security--rate-limiting)
+10. [Troubleshooting](#troubleshooting)
+11. [Development](#development)
+12. [Contributing](#contributing)
+
+## Installation & Setup
+
+### Installation
 
 Add to your Gemfile:
 
 ```ruby
-gem 'clavis', '~> 0.6.2'
+gem 'clavis'
 ```
 
 Install and set up:
@@ -105,7 +137,35 @@ rails generate clavis:install
 rails db:migrate
 ```
 
-## Basic Configuration
+### Database Setup
+
+The generator creates migrations for:
+
+1. OAuth identities table
+2. User model OAuth fields
+
+### Routes Configuration
+
+The generator mounts the engine:
+
+```ruby
+# config/routes.rb
+mount Clavis::Engine => "/auth"
+```
+
+### Integrating with Existing Authentication
+
+1. Configure as shown in the Quick Start
+2. Run the generator
+3. Include the module in your User model:
+   ```ruby
+   # app/models/user.rb
+   include Clavis::Models::OauthAuthenticatable
+   ```
+
+## Configuration
+
+### Basic Configuration
 
 Configure in an initializer:
 
@@ -129,285 +189,243 @@ end
 
 > ⚠️ **Important**: The `redirect_uri` must match EXACTLY what you've registered in the provider's developer console. If there's a mismatch, you'll get errors like "redirect_uri_mismatch". Pay attention to the protocol (http/https), domain, port, and path - all must match precisely.
 
-## Setting Up OAuth Redirect URIs in Provider Consoles
+### Configuration Options
 
-When setting up OAuth, correctly configuring redirect URIs in both your app and the provider's developer console is crucial:
+See `config/initializers/clavis.rb` for all configuration options.
 
-### Google
-1. Go to [Google Cloud Console](https://console.cloud.google.com)
-2. Navigate to "APIs & Services" > "Credentials"
-3. Create or edit an OAuth 2.0 Client ID
-4. Under "Authorized redirect URIs" add exactly the same URI as in your Clavis config:
-   - For development: `http://localhost:3000/auth/google/callback`
-   - For production: `https://your-app.com/auth/google/callback`
+#### Verbose Logging
 
-### GitHub
-1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
-2. Navigate to "OAuth Apps" and create or edit your app
-3. In the "Authorization callback URL" field, add exactly the same URI as in your Clavis config
+By default, Clavis keeps its logs minimal to avoid cluttering your application logs. If you need more detailed logs during authentication processes for debugging purposes, you can enable verbose logging:
 
-### Common Errors
-- **Error 400: redirect_uri_mismatch** - This means the URI in your code doesn't match what's registered in the provider's console
-- **Solution**: Ensure both URIs match exactly, including protocol (http/https), domain, port, and full path
+```ruby
+Clavis.configure do |config|
+  # Enable detailed authentication flow logs
+  config.verbose_logging = true
+end
+```
 
-## Database Setup
+When enabled, this will log details about:
+- Token exchanges
+- User info requests
+- Token refreshes and verifications
+- Authorization requests and callbacks
 
-The generator creates migrations for:
+This is particularly useful for debugging OAuth integration issues, but should typically be disabled in production.
 
-1. OAuth identities table
-2. User model OAuth fields
+## User Management
 
-## Integrating with Existing Authentication
+Clavis delegates user creation and management to your application through the `find_or_create_from_clavis` method. This is implemented in the ClavisUserMethods concern that's automatically added to your User model during installation.
 
-1. Configure as shown above
-2. Run the generator
-3. Include the module in your User model:
-   ```ruby
-   # app/models/user.rb
-   include Clavis::Models::OauthAuthenticatable
-   ```
-4. Add OAuth buttons to your login page:
-   ```erb
-   <%= clavis_oauth_button :github, class: "oauth-button github" %>
-   <%= clavis_oauth_button :google, class: "oauth-button google" %>
-   ```
+The concern provides:
+- Helper methods for accessing OAuth data
+- Logic to create or find users based on OAuth data
+- Support for skipping password validation for OAuth users
 
-## Controller Integration
+### The OauthIdentity Model
 
-Include the authentication concern:
+Clavis stores OAuth credentials and user information in a polymorphic `OauthIdentity` model. This model has a `belongs_to :authenticatable, polymorphic: true` relationship, allowing it to be associated with any type of user model.
+
+For convenience, the model also provides `user` and `user=` methods that are aliases for `authenticatable` and `authenticatable=`:
 
 ```ruby
-# app/controllers/auth_controller.rb
-class AuthController < ApplicationController
-  include Clavis::Controllers::Concerns::Authentication
-  
-  def oauth_authorize
-    redirect_to auth_url(params[:provider])
-  end
-  
-  def oauth_callback
-    auth_hash = process_callback(params[:provider])
-    user = User.find_for_oauth(auth_hash)
-    session[:user_id] = user.id
-    redirect_to after_sign_in_path
-  rescue Clavis::Error => e
-    redirect_to sign_in_path, alert: "Authentication failed: #{e.message}"
-  end
-  
-  private
-  
-  def after_sign_in_path
-    stored_location || root_path
-  end
-end
+# These are equivalent:
+identity.user = current_user
+identity.authenticatable = current_user
 ```
 
-## User Model Integration
+This allows you to use `identity.user` in your code even though the underlying database uses the `authenticatable` columns.
 
-Clavis delegates user creation and management to your application through a finder method. After installing Clavis, you need to set up your User model to handle OAuth users:
+#### Key features of the OauthIdentity model:
 
-```bash
-# Generate the Clavis user methods concern
-rails generate clavis:user_method
-```
+- Secure token storage (tokens are automatically encrypted/decrypted)
+- User information stored in the `auth_data` JSON column
+- Automatic token refresh capabilities
+- Unique index on `provider` and `uid` to prevent duplicate identities
 
-This generates:
-1. A `ClavisUserMethods` concern in `app/models/concerns/clavis_user_methods.rb`
-2. Adds `include ClavisUserMethods` to your User model
+### Integration with has_secure_password
 
-The concern provides:
-- Integration with the `OauthAuthenticatable` module for helper methods
-- A `find_or_create_from_clavis` class method that handles user creation/lookup
-- Conditional validation for password requirements (commented by default)
+If your User model uses `has_secure_password` for authentication, you'll need to handle password validation carefully when creating users from OAuth. The generated ClavisUserMethods concern provides several strategies for dealing with this:
 
-### Customizing User Creation
+#### Option 1: Skip Password Validation (Recommended)
 
-The generated concern includes a method to find or create users from OAuth data. By default, it only sets the email field, which may not be sufficient for your User model:
+This approach adds a temporary attribute to mark OAuth users and skip password validation for them:
 
 ```ruby
-# In app/models/concerns/clavis_user_methods.rb
-def find_or_create_from_clavis(auth_hash)
-  # For OpenID Connect providers (like Google), we use the sub claim as the stable identifier
-  # For other providers, we use the uid
-  identity = if auth_hash[:id_token_claims]&.dig(:sub)
-              Clavis::OauthIdentity.find_by(
-                provider: auth_hash[:provider],
-                uid: auth_hash[:id_token_claims][:sub]
-              )
-            else
-              Clavis::OauthIdentity.find_by(
-                provider: auth_hash[:provider],
-                uid: auth_hash[:uid]
-              )
-            end
-  return identity.user if identity&.user
-
-  # Finding existing user logic...
-  
-  # Create new user if none exists
-  if user.nil?
-    # Convert hash data to HashWithIndifferentAccess for reliable key access
-    info = auth_hash[:info].with_indifferent_access if auth_hash[:info]
-    
-    user = new(
-      email: info&.dig(:email)
-      # You MUST add other required fields for your User model here!
-    )
-    
-    user.save!
-  end
-  
-  # Create or update the OAuth identity...
+# app/models/user.rb
+class User < ApplicationRecord
+  include ClavisUserMethods
+  has_secure_password
+
+  # Skip password validation for OAuth users
+  validates :password, presence: true, length: { minimum: 8 },
+           unless: -> { skip_password_validation }, on: :create
 end
 ```
 
-### OpenID Connect Providers and Stable Identifiers
-
-For OpenID Connect providers (like Google), Clavis uses the `sub` claim from the ID token as the stable identifier. This is important because:
-
-1. The `sub` claim is guaranteed to be unique and stable for each user
-2. Other fields like `uid` might change between logins
-3. This follows the OpenID Connect specification
-
-For non-OpenID Connect providers (like GitHub), Clavis continues to use the `uid` field as the identifier.
+The `skip_password_validation` attribute is set automatically in the OAuth flow.
 
-⚠️ **IMPORTANT**: You **MUST** customize this method to set all required fields for your User model!
+#### Option 2: Set Random Password
 
-We use `with_indifferent_access` to reliably access fields regardless of whether keys are strings or symbols. The auth_hash typically contains:
+Another approach is to set a random secure password for OAuth users:
 
 ```ruby
-# Access these fields with info.dig(:field_name) 
-info = auth_hash[:info].with_indifferent_access
-
-# Common fields available in info:
-info[:email]           # User's email address
-info[:name]            # User's full name
-info[:given_name]      # First name (Google)
-info[:first_name]      # First name (some providers)
-info[:family_name]     # Last name (Google)
-info[:last_name]       # Last name (some providers)
-info[:nickname]        # Username or handle
-info[:picture]         # Profile picture URL (Google)
-info[:image]           # Profile picture URL (some providers)
-```
-
-Example of customized user creation:
+# app/models/user.rb
+class User < ApplicationRecord
+  include ClavisUserMethods
+  has_secure_password
 
-```ruby
-# Convert to HashWithIndifferentAccess for reliable key access
-info = auth_hash[:info].with_indifferent_access if auth_hash[:info]
-
-user = new(
-  email: info&.dig(:email),
-  first_name: info&.dig(:given_name) || info&.dig(:first_name),
-  last_name: info&.dig(:family_name) || info&.dig(:last_name),
-  username: info&.dig(:nickname) || "user_#{SecureRandom.hex(4)}",
-  avatar_url: info&.dig(:picture) || info&.dig(:image),
-  terms_accepted: true
-)
+  # Set a random password for OAuth users
+  before_validation :set_random_password, 
+                   if: -> { skip_password_validation && respond_to?(:password=) }
+  
+  private
+  
+  def set_random_password
+    self.password = SecureRandom.hex(16)
+    self.password_confirmation = password if respond_to?(:password_confirmation=)
+  end
+end
 ```
 
-### Helper Methods
+#### Option 3: Bypass Validations (Use with Caution)
 
-The concern includes the `OauthAuthenticatable` module, which provides helper methods:
+As a last resort, you can bypass validations entirely when creating OAuth users:
 
 ```ruby
-# Available on any user instance
-user.oauth_user?        # => true if the user has any OAuth identities
-user.oauth_identity     # => the primary OAuth identity
-user.oauth_avatar_url   # => the profile picture URL
-user.oauth_name         # => the name from OAuth
-user.oauth_email        # => the email from OAuth
-user.oauth_token        # => the access token
+# In app/models/concerns/clavis_user_methods.rb
+def self.find_or_create_from_clavis(auth_hash)
+  # ... existing code ...
+  
+  # Create a new user if none exists
+  if user.nil?
+    # ... set user attributes ...
+    
+    # Bypass validations
+    user.save(validate: false)
+  end
+  
+  # ... remainder of method ...
+end
 ```
 
-### Handling Password Requirements
+This approach isn't recommended as it might bypass important validations, but can be necessary in complex scenarios.
 
-For password-protected User models, the concern includes a commented-out conditional validation:
+#### Database Setup
+
+The Clavis generator automatically adds an `oauth_user` boolean field to your User model to help track which users were created through OAuth:
 
 ```ruby
-# Uncomment in app/models/concerns/clavis_user_methods.rb
-validates :password, presence: true, unless: :oauth_user?
+# This is added automatically by the generator
+add_column :users, :oauth_user, :boolean, default: false
 ```
 
-This allows you to:
-1. Skip password requirements for OAuth users
-2. Keep your regular password validations for non-OAuth users
-3. Avoid storing useless random passwords in your database
+This field is useful for conditional logic related to authentication methods.
 
-### Using a Different Class or Method
+### Session Management
 
-You can configure Clavis to use a different class or method name:
+Clavis handles user sessions through a concern module that is automatically included in your ApplicationController:
 
 ```ruby
-# config/initializers/clavis.rb
-Clavis.configure do |config|
-  # Use a different class
-  config.user_class = "Account"
-  
-  # Use a different method name
-  config.user_finder_method = :create_from_oauth
+# Available in your controllers after installation:
+# include Clavis::Controllers::Concerns::Authentication
+# include Clavis::Controllers::Concerns::SessionManagement
+
+# Current user helper method
+def current_user
+  @current_user ||= cookies.signed[:user_id] && User.find_by(id: cookies.signed[:user_id])
+end
+
+# Sign in helper
+def sign_in_user(user)
+  cookies.signed[:user_id] = {
+    value: user.id,
+    httponly: true,
+    same_site: :lax,
+    secure: Rails.env.production?
+  }
 end
 ```
 
+#### Authentication Methods
+
+The SessionManagement concern provides:
+
+- `current_user` - Returns the currently authenticated user
+- `authenticated?` - Returns whether a user is authenticated
+- `sign_in_user(user)` - Signs in a user by setting a secure cookie
+- `sign_out_user` - Signs out the current user
+- `store_location` - Stores URL to return to after authentication
+- `after_login_path` - Path to redirect to after login
+- `after_logout_path` - Path to redirect to after logout
+
 ## View Integration
 
-Include view helpers:
+Include view helpers in your application:
 
 ```ruby
-# app/helpers/oauth_helper.rb
-module OauthHelper
+# app/helpers/application_helper.rb
+module ApplicationHelper
   include Clavis::ViewHelpers
 end
 ```
 
-### Importing Stylesheets
-
-The Clavis install generator will attempt to automatically add the required stylesheets to your application. If you need to manually include them:
-
-For Sprockets (asset pipeline):
-```css
-/* app/assets/stylesheets/application.css */
-/*
- *= require clavis
- *= require_self
- */
-```
-
-For Webpacker/Importmap:
-```scss
-/* app/assets/stylesheets/application.scss */
-@import 'clavis';
-```
-
-### Using Buttons
+### Using OAuth Buttons
 
-Use in views:
+Basic button usage:
 
 ```erb
 <div class="oauth-buttons">
   <%= clavis_oauth_button :google %>
   <%= clavis_oauth_button :github %>
+  <%= clavis_oauth_button :microsoft %>
+  <%= clavis_oauth_button :facebook %>
+  <%= clavis_oauth_button :apple %>
 </div>
 ```
 
-Customize buttons:
+Customizing buttons:
 
 ```erb
+<!-- Custom text -->
 <%= clavis_oauth_button :google, text: "Continue with Google" %>
+
+<!-- Custom CSS class -->
 <%= clavis_oauth_button :github, class: "my-custom-button" %>
+
+<!-- Additional HTML attributes -->
+<%= clavis_oauth_button :apple, html: { data: { turbo: false } } %>
+
+<!-- All customization options -->
+<%= clavis_oauth_button :github, 
+    text: "Sign in via GitHub",
+    class: "custom-button github-button",
+    icon_class: "custom-icon",
+    html: { id: "github-login" } %>
 ```
 
-## Routes Configuration
+The buttons come with built-in styles and brand-appropriate icons for the supported providers.
 
-The generator mounts the engine:
+## Advanced Features
+
+### Testing Your Integration
+
+Access standardized user info:
 
 ```ruby
-# config/routes.rb
-mount Clavis::Engine => "/auth"
+# From most recent OAuth provider
+current_user.oauth_email
+current_user.oauth_name
+current_user.oauth_avatar_url
+
+# From specific provider
+current_user.oauth_email("google")
+current_user.oauth_name("github")
+
+# Check if OAuth user
+current_user.oauth_user?
 ```
 
-## Token Refresh
+### Token Refresh
 
 Provider support:
 
@@ -426,7 +444,7 @@ provider = Clavis.provider(:google, redirect_uri: "https://your-app.com/auth/goo
 new_tokens = provider.refresh_token(oauth_identity.refresh_token)
 ```
 
-## Custom Providers
+### Custom Providers
 
 Use the Generic provider:
 
@@ -466,22 +484,116 @@ end
 Clavis.register_provider(:example_oauth, ExampleOAuth)
 ```
 
-## Provider-Specific Setup
+## Provider Setup
+
+### Setting Up OAuth Redirect URIs in Provider Consoles
 
-Callback URI format for all providers:
+When setting up OAuth, correctly configuring redirect URIs in both your app and the provider's developer console is crucial:
 
+#### Google
+1. Go to [Google Cloud Console](https://console.cloud.google.com)
+2. Navigate to "APIs & Services" > "Credentials"
+3. Create or edit an OAuth 2.0 Client ID
+4. Under "Authorized redirect URIs" add exactly the same URI as in your Clavis config:
+   - For development: `http://localhost:3000/auth/google/callback`
+   - For production: `https://your-app.com/auth/google/callback`
+
+#### GitHub
+1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
+2. Navigate to "OAuth Apps" and create or edit your app
+3. In the "Authorization callback URL" field, add exactly the same URI as in your Clavis config
+   - For development: `http://localhost:3000/auth/github/callback`
+   - For production: `https://your-app.com/auth/github/callback`
+
+#### Common Errors
+- **Error 400: redirect_uri_mismatch** - This means the URI in your code doesn't match what's registered in the provider's console
+- **Solution**: Ensure both URIs match exactly, including protocol (http/https), domain, port, and full path
+
+#### GitHub Enterprise Support
+
+Clavis supports GitHub Enterprise installations with custom configuration options:
+
+```ruby
+config.providers = {
+  github: {
+    client_id: ENV["GITHUB_CLIENT_ID"],
+    client_secret: ENV["GITHUB_CLIENT_SECRET"],
+    redirect_uri: "https://your-app.com/auth/github/callback",
+    # GitHub Enterprise settings:
+    site_url: "https://api.github.yourdomain.com",           # Your Enterprise API endpoint
+    authorize_url: "https://github.yourdomain.com/login/oauth/authorize",
+    token_url: "https://github.yourdomain.com/login/oauth/access_token"
+  }
+}
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `site_url` | Base URL for the GitHub API | `https://api.github.com` |
+| `authorize_url` | Authorization endpoint URL | `https://github.com/login/oauth/authorize` |
+| `token_url` | Token exchange endpoint URL | `https://github.com/login/oauth/access_token` |
+
+#### Facebook
+1. Go to [Facebook Developer Portal](https://developers.facebook.com)
+2. Create or select a Facebook app
+3. Navigate to Settings > Basic to find your App ID and App Secret
+4. Set up "Facebook Login" and configure "Valid OAuth Redirect URIs" with the exact URI from your Clavis config:
+   - For development: `http://localhost:3000/auth/facebook/callback`
+   - For production: `https://your-app.com/auth/facebook/callback`
+
+### Provider Configuration Options
+
+Providers can be configured with additional options for customizing behavior:
+
+#### Facebook Provider Options
+
+```ruby
+config.providers = {
+  facebook: {
+    client_id: ENV["FACEBOOK_CLIENT_ID"],
+    client_secret: ENV["FACEBOOK_CLIENT_SECRET"],
+    redirect_uri: "https://your-app.com/auth/facebook/callback",
+    # Optional settings:
+    display: "popup",               # Display mode - options: page, popup, touch
+    auth_type: "rerequest",         # Auth type - useful for permission re-requests
+    image_size: "large",            # Profile image size - small, normal, large, square
+    # Alternative: provide exact dimensions
+    image_size: { width: 200, height: 200 },
+    secure_image_url: true          # Force HTTPS for image URLs (default true)
+  }
+}
 ```
-https://your-domain.com/auth/:provider/callback
+
+| Option | Description | Values | Default |
+|--------|-------------|--------|---------|
+| `display` | Controls how the authorization dialog is displayed | `page`, `popup`, `touch` | `page` |
+| `auth_type` | Specifies the auth flow behavior | `rerequest`, `reauthenticate` | N/A |
+| `image_size` | Profile image size | String: `small`, `normal`, `large`, `square` or Hash: `{ width: 200, height: 200 }` | N/A |
+| `secure_image_url` | Force HTTPS for profile image URLs | `true`, `false` | `true` |
+
+#### Using Facebook Long-Lived Tokens
+
+Facebook access tokens are short-lived by default. The Facebook provider includes methods to exchange these for long-lived tokens:
+
+```ruby
+# Exchange a short-lived token for a long-lived token
+provider = Clavis.provider(:facebook)
+long_lived_token_data = provider.exchange_for_long_lived_token(oauth_identity.access_token)
+
+# Update the OAuth identity with the new token
+oauth_identity.update(
+  access_token: long_lived_token_data[:access_token],
+  expires_at: Time.now + long_lived_token_data[:expires_in].to_i.seconds
+)
 ```
 
-Setup guides for:
-- [Google](#google)
-- [GitHub](#github)
-- [Apple](#apple)
-- [Facebook](#facebook)
-- [Microsoft](#microsoft)
+#### Common Errors
+
+- **Error 400: Invalid OAuth access token** - The token is invalid or expired
+- **Error 400: redirect_uri does not match** - Mismatch between registered and provided redirect URI
+- **Solution**: Ensure the redirect URI in your code matches exactly what's registered in Facebook Developer Portal
 
-## Rate Limiting
+## Security & Rate Limiting
 
 Clavis includes built-in integration with the [Rack::Attack](https://github.com/rack/rack-attack) gem to protect your OAuth endpoints against DDoS and brute force attacks.
 
@@ -552,287 +664,14 @@ ActiveSupport::Notifications.subscribe("throttle.rack_attack") do |name, start,
 end
 ```
 
-## Testing Your Integration
-
-Access standardized user info:
-
-```ruby
-# From most recent OAuth provider
-current_user.oauth_email
-current_user.oauth_name
-current_user.oauth_avatar_url
-
-# From specific provider
-current_user.oauth_email("google")
-current_user.oauth_name("github")
-
-# Check if OAuth user
-current_user.oauth_user?
-```
-
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 The `rails-app` directory contains a Rails application used for integration testing and is not included in the gem package.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Usage
-
-### Basic Setup
-
-1. Install the gem
-2. Run the installation generator:
-
-```
-rails generate clavis:install
-```
-
-3. Configure your OAuth providers in `config/initializers/clavis.rb`:
-
-```ruby
-Clavis.configure do |config|
-  # Configure your OAuth providers
-  config.provider :github, client_id: "your-client-id", client_secret: "your-client-secret"
-  
-  # Add other configurations as needed
-end
-```
-
-4. Generate an authentication controller:
-
-```
-rails generate clavis:controller Auth
-```
-
-5. Add the routes to your application:
-
-```ruby
-# config/routes.rb
-Rails.application.routes.draw do
-  get 'auth/:provider/callback', to: 'auth#callback'
-  get 'auth/failure', to: 'auth#failure'
-  get 'auth/:provider', to: 'auth#authorize', as: :auth
-  # ...
-end
-```
-
-### User Management
-
-Clavis creates a concern module that you can include in your User model:
-
-```ruby
-# app/models/user.rb
-class User < ApplicationRecord
-  include Clavis::Models::Concerns::ClavisUserMethods
-  
-  # Your existing user model code
-end
-```
-
-This provides your User model with the `find_or_create_from_clavis` method that manages user creation from OAuth data.
-
-### Session Management
-
-Clavis handles user sessions through a concern module that is automatically included in your ApplicationController:
-
-```ruby
-# app/controllers/application_controller.rb
-class ApplicationController < ActionController::Base
-  # Clavis automatically includes:
-  # include Clavis::Controllers::Concerns::Authentication
-  # include Clavis::Controllers::Concerns::SessionManagement
-  
-  # Your existing controller code
-end
-```
-
-#### Secure Cookie-Based Authentication
-
-The SessionManagement concern uses a secure cookie-based approach that is compatible with Rails 8's authentication patterns:
-
-- **Signed Cookies**: User IDs are stored in signed cookies with security settings like `httponly`, `same_site: :lax`, and `secure: true` (in production)
-- **Security-First**: Cookies are configured with security best practices to protect against XSS, CSRF, and cookie theft
-- **No Session Storage**: User authentication state is not stored in the session, avoiding session fixation attacks
-
-#### Authentication Methods
-
-The SessionManagement concern provides the following methods:
-
-- `current_user` - Returns the currently authenticated user (if any)
-- `authenticated?` - Returns whether a user is currently authenticated
-- `sign_in_user(user)` - Signs in a user by setting a secure cookie
-- `sign_out_user` - Signs out the current user by clearing cookies
-- `store_location` - Stores the current URL to return to after authentication (uses session for this temporary data only)
-- `after_login_path` - Returns the path to redirect to after successful login (stored location or root path)
-- `after_logout_path` - Returns the path to redirect to after logout (login path or root path)
-
-#### Compatibility with Existing Authentication
-
-The system is designed to work with various authentication strategies:
-
-1. **Devise**: If your application uses Devise, Clavis will automatically use Devise's `sign_in` and `sign_out` methods.
-
-2. **Rails 8 Authentication**: Compatible with Rails 8's cookie-based authentication approach.
-
-3. **Custom Cookie Usage**: If you're already using `cookies.signed[:user_id]`, Clavis will work with this approach.
-
-#### Customizing Session Management
-
-You can override any of these methods in your ApplicationController to customize the behavior:
-
-```ruby
-# app/controllers/application_controller.rb
-class ApplicationController < ActionController::Base
-  # Override the default after_login_path
-  def after_login_path
-    dashboard_path  # Redirect to dashboard instead of root
-  end
-  
-  # Override sign_in_user to add additional behavior
-  def sign_in_user(user)
-    super  # Call the original method
-    log_user_sign_in(user)  # Add your custom behavior
-  end
-  
-  # Use a different cookie name or format
-  def sign_in_user(user)
-    cookies.signed.permanent[:auth_token] = {
-      value: user.generate_auth_token,
-      httponly: true,
-      same_site: :lax,
-      secure: Rails.env.production?
-    }
-  end
-  
-  # Customize how users are found
-  def find_user_by_cookie
-    return nil unless cookies.signed[:auth_token]
-    User.find_by_auth_token(cookies.signed[:auth_token])
-  end
-end
-```
-
-## Configuration
-
-See `config/initializers/clavis.rb` for all configuration options.
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/your-username/clavis.
-
-### Integration with has_secure_password
-
-If your User model uses `has_secure_password` for authentication, you'll need to handle password validation carefully when creating users from OAuth. The generated ClavisUserMethods concern provides several strategies for dealing with this:
-
-#### Option 1: Skip Password Validation (Recommended)
-
-This approach adds a temporary attribute to mark OAuth users and skip password validation for them:
-
-```ruby
-# app/models/user.rb
-class User < ApplicationRecord
-  include ClavisUserMethods
-  has_secure_password
-
-  # Skip password validation for OAuth users
-  validates :password, presence: true, length: { minimum: 8 },
-           unless: -> { skip_password_validation }, on: :create
-end
-```
-
-The `skip_password_validation` attribute is set automatically in the OAuth flow.
-
-#### Option 2: Set Random Password
-
-Another approach is to set a random secure password for OAuth users:
-
-```ruby
-# app/models/user.rb
-class User < ApplicationRecord
-  include ClavisUserMethods
-  has_secure_password
-
-  # Set a random password for OAuth users
-  before_validation :set_random_password, 
-                   if: -> { skip_password_validation && respond_to?(:password=) }
-  
-  private
-  
-  def set_random_password
-    self.password = SecureRandom.hex(16)
-    self.password_confirmation = password if respond_to?(:password_confirmation=)
-  end
-end
-```
-
-#### Option 3: Bypass Validations (Use with Caution)
-
-As a last resort, you can bypass validations entirely when creating OAuth users:
-
-```ruby
-# In app/models/concerns/clavis_user_methods.rb
-def self.find_or_create_from_clavis(auth_hash)
-  # ... existing code ...
-  
-  # Create a new user if none exists
-  if user.nil?
-    # ... set user attributes ...
-    
-    # Bypass validations
-    user.save(validate: false)
-  end
-  
-  # ... remainder of method ...
-end
-```
-
-This approach isn't recommended as it might bypass important validations, but can be necessary in complex scenarios.
-
-#### Database Setup
-
-The Clavis generator automatically adds an `oauth_user` boolean field to your User model to help track which users were created through OAuth:
-
-```ruby
-# This is added automatically by the generator
-add_column :users, :oauth_user, :boolean, default: false
-```
-
-This field is useful for conditional logic related to authentication methods.
-
-### Session Management
-
-```ruby
-Clavis.configure do |config|
-  config.session_key = :clavis_current_user_id
-  config.user_finder_method = :find_or_create_from_clavis
-end
-```
-
-### The OauthIdentity Model
-
-Clavis stores OAuth credentials and user information in a polymorphic `OauthIdentity` model. This model has a `belongs_to :authenticatable, polymorphic: true` relationship, allowing it to be associated with any type of user model.
-
-For convenience, the model also provides `user` and `user=` methods that are aliases for `authenticatable` and `authenticatable=`:
-
-```ruby
-# These are equivalent:
-identity.user = current_user
-identity.authenticatable = current_user
-```
-
-This allows you to use `identity.user` in your code even though the underlying database uses the `authenticatable` columns.
-
-#### Key features of the OauthIdentity model:
-
-- Secure token storage (tokens are automatically encrypted/decrypted)
-- User information stored in the `auth_data` JSON column
-- Automatic token refresh capabilities
-- Unique index on `provider` and `uid` to prevent duplicate identities
-
-### Webhook Providers
+Bug reports and pull requests are welcome on GitHub at https://github.com/clayton/clavis.