clavis 0.7.1

data/docs/integration.md

@@ -0,0 +1,272 @@
+# Integrating Clavis with Existing Applications
+
+This guide covers how to integrate Clavis with your existing Ruby on Rails application, particularly if you already have an authentication system in place.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Database Setup](#database-setup)
+3. [User Model Integration](#user-model-integration)
+4. [Controller Integration](#controller-integration)
+5. [View Integration](#view-integration)
+6. [Route Configuration](#route-configuration)
+7. [Working with Multiple Authentication Methods](#working-with-multiple-authentication-methods)
+8. [Troubleshooting](#troubleshooting)
+
+## Overview
+
+Clavis is designed to work alongside your existing authentication system, providing OAuth/OIDC capabilities without replacing your current setup. This guide assumes you have an existing application with:
+
+- A `User` model
+- Some form of authentication (e.g., `has_secure_password`, Devise, etc.)
+- Session management
+
+## Database Setup
+
+Clavis stores OAuth identities in a separate table with a polymorphic relationship to your user model.
+
+1. **Run the installation generator**:
+
+   ```bash
+   rails generate clavis:install
+   ```
+
+2. **Review and run the migration**:
+
+   ```bash
+   rails db:migrate
+   ```
+
+   This creates a `clavis_oauth_identities` table with:
+   
+   ```ruby
+   create_table :clavis_oauth_identities do |t|
+     t.references :user, polymorphic: true, null: false, index: true
+     t.string :provider, null: false
+     t.string :uid, null: false
+     t.json :auth_data
+     t.string :token
+     t.string :refresh_token
+     t.datetime :expires_at
+     t.timestamps
+     
+     t.index [:provider, :uid], unique: true
+   end
+   ```
+
+## User Model Integration
+
+Include the `OauthAuthenticatable` concern in your User model:
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  include Clavis::Models::OauthAuthenticatable
+  
+  # Your existing authentication code (e.g., has_secure_password)
+  
+  # Optional: Customize how users are created/found from OAuth data
+  def self.find_for_oauth(auth_hash)
+    super do |user, auth|
+      # Set additional attributes based on the OAuth data
+      user.name = auth[:info][:name] if user.respond_to?(:name=)
+      user.username = auth[:info][:nickname] if user.respond_to?(:username=)
+      # You can access profile image with auth[:info][:image]
+      # You can access email with auth[:info][:email]
+    end
+  end
+end
+```
+
+## Controller Integration
+
+You have a few options for controller integration:
+
+### Option 1: Use your existing authentication controller
+
+```ruby
+# app/controllers/sessions_controller.rb
+class SessionsController < ApplicationController
+  include Clavis::Controllers::Concerns::Authentication
+  
+  # Your existing login/logout actions...
+  
+  # Add OAuth callback handler
+  def oauth_callback
+    auth_hash = process_callback(params[:provider])
+    
+    # Find or create a user with the OAuth data
+    @user = User.find_for_oauth(auth_hash)
+    
+    # Sign in the user (using your existing authentication system)
+    session[:user_id] = @user.id
+    
+    redirect_to root_path, notice: "Signed in successfully!"
+  rescue Clavis::AuthenticationError => e
+    redirect_to login_path, alert: "Authentication failed: #{e.message}"
+  end
+  
+  # Add OAuth authorization handler
+  def oauth_authorize
+    redirect_to auth_url(params[:provider])
+  end
+end
+```
+
+### Option 2: Generate a dedicated OAuth controller
+
+```bash
+rails generate clavis:controller Auth
+```
+
+This creates:
+- `app/controllers/auth_controller.rb` with OAuth methods
+- Views for login/etc.
+- Routes for the OAuth flow
+
+## View Integration
+
+### Add OAuth buttons to your login form:
+
+```erb
+<%# app/views/sessions/new.html.erb %>
+<h1>Sign In</h1>
+
+<%# Your existing login form... %>
+
+<div class="oauth-buttons">
+  <p>Or sign in with:</p>
+  <%= clavis_oauth_button :google %>
+  <%= clavis_oauth_button :github %>
+</div>
+```
+
+### Customize button appearance:
+
+```erb
+<%= clavis_oauth_button :google, text: "Continue with Google", class: "my-custom-button" %>
+```
+
+## Route Configuration
+
+Add the necessary routes to your application:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # Your existing routes...
+  
+  # OAuth routes
+  get '/auth/:provider', to: 'sessions#oauth_authorize', as: :auth
+  get '/auth/:provider/callback', to: 'sessions#oauth_callback'
+end
+```
+
+## Working with Multiple Authentication Methods
+
+When a user signs in with OAuth, you'll need to decide how to handle users who might already have password-based accounts:
+
+### Email Matching Strategy
+
+This is the default strategy in Clavis - when a user signs in with OAuth:
+
+1. Clavis tries to find an existing `OauthIdentity` for the provider/uid
+2. If not found, it looks for a user with a matching email address
+3. If a user with matching email is found, it associates the OAuth identity with that user
+4. If no user is found, it creates a new user and associates the OAuth identity
+
+### Linking Accounts
+
+You might want to allow users to link multiple OAuth providers to their account:
+
+```ruby
+# app/controllers/profiles_controller.rb
+def link_oauth
+  # Store the user_id in the session
+  session[:linking_user_id] = current_user.id
+  
+  # Redirect to the OAuth provider
+  redirect_to auth_path(params[:provider])
+end
+
+# app/controllers/sessions_controller.rb
+def oauth_callback
+  auth_hash = process_callback(params[:provider])
+  
+  # Check if we're linking an existing account
+  if session[:linking_user_id].present?
+    user = User.find(session[:linking_user_id])
+    session.delete(:linking_user_id)
+    
+    # Find or create the identity
+    identity = Clavis::OauthIdentity.find_or_initialize_by(
+      provider: auth_hash[:provider],
+      uid: auth_hash[:uid]
+    )
+    
+    # Associate with the user
+    identity.user = user
+    identity.auth_data = auth_hash[:info]
+    identity.token = auth_hash[:credentials][:token]
+    identity.refresh_token = auth_hash[:credentials][:refresh_token]
+    identity.expires_at = auth_hash[:credentials][:expires_at] ? Time.at(auth_hash[:credentials][:expires_at]) : nil
+    identity.save!
+    
+    redirect_to edit_profile_path, notice: "Successfully linked #{params[:provider].capitalize} account"
+  else
+    # Normal login flow...
+  end
+end
+```
+
+## Troubleshooting
+
+### View Helper Issues
+
+If you're having trouble with the `clavis_oauth_button` helper, ensure your application helper includes Clavis's view helpers:
+
+```ruby
+# app/helpers/application_helper.rb
+module ApplicationHelper
+  include Clavis::ViewHelpers
+  # ...
+end
+```
+
+### Database Issues
+
+If you see errors about the `clavis_oauth_identities` table, make sure you've run:
+
+```bash
+rails db:migrate
+```
+
+### Session Issues
+
+If you're experiencing session-related issues:
+
+1. Ensure you're not using `session.clear` which would remove Clavis's state parameters
+2. Consider enabling session rotation in your Clavis configuration:
+
+```ruby
+Clavis.configure do |config|
+  config.rotate_session_after_login = true
+end
+```
+
+### Missing Routes
+
+If you see errors about missing routes for OAuth buttons, ensure you've added:
+
+```ruby
+get '/auth/:provider', to: 'sessions#oauth_authorize', as: :auth
+get '/auth/:provider/callback', to: 'sessions#oauth_callback'
+```
+
+### Security Concerns
+
+For production environments, always ensure:
+
+1. You're using HTTPS
+2. Your OAuth provider credentials are properly secured (e.g., using Rails credentials)
+3. You've configured allowed redirect hosts in Clavis configuration 

data/error_handling.md

@@ -0,0 +1,355 @@
+# Clavis Error Handling Strategy
+
+## Overview
+
+Clavis implements a structured error handling system that provides:
+
+1. Clear, descriptive error messages
+2. Specific error types for different failures
+3. Rails logger integration
+4. Easy error rescue patterns for application code
+
+## Error Hierarchy
+
+```
+Clavis::Error (base class)
+├── ConfigurationError
+│   ├── ProviderNotConfigured
+│   └── MissingConfiguration
+├── AuthenticationError
+│   ├── InvalidState
+│   ├── MissingState
+│   └── AuthorizationDenied
+├── TokenError
+│   ├── InvalidToken
+│   ├── ExpiredToken
+│   ├── InvalidGrant
+│   └── InvalidAccessToken
+└── ProviderError
+    ├── UnsupportedProvider
+    └── ProviderAPIError
+```
+
+## Error Classes
+
+### Configuration Errors
+
+- **ConfigurationError**: Base class for configuration-related errors
+- **ProviderNotConfigured**: Raised when trying to use an unconfigured provider
+- **MissingConfiguration**: Raised when required configuration values are missing
+
+### Authentication Errors
+
+- **AuthenticationError**: Base class for authentication flow errors
+- **InvalidState**: Raised when state parameter validation fails (CSRF protection)
+- **MissingState**: Raised when state parameter is missing from the session
+- **AuthorizationDenied**: Raised when the user denies authorization at the provider
+
+### Token Errors
+
+- **TokenError**: Base class for token-related errors
+- **InvalidToken**: Raised when token validation fails
+- **ExpiredToken**: Raised when a token has expired
+- **InvalidGrant**: Raised when an authorization code is invalid or expired
+- **InvalidAccessToken**: Raised when using an invalid access token
+
+### Provider Errors
+
+- **ProviderError**: Base class for provider-related errors
+- **UnsupportedProvider**: Raised when trying to use an unsupported provider
+- **ProviderAPIError**: Raised when a provider API returns an error
+
+## Implementation
+
+```ruby
+# lib/clavis/errors.rb
+module Clavis
+  # Base error class
+  class Error < StandardError
+    def initialize(message = nil)
+      @message = message
+      super(format_message)
+    end
+    
+    private
+    
+    def format_message
+      return @message if @message
+      
+      class_name = self.class.name.split('::').last
+      words = class_name.gsub(/([A-Z])/, ' \1').strip.split(' ')
+      words.join(' ').downcase
+    end
+  end
+  
+  # Configuration errors
+  class ConfigurationError < Error; end
+  
+  class ProviderNotConfigured < ConfigurationError
+    def initialize(provider)
+      @provider = provider
+      super("Provider '#{provider}' is not configured")
+    end
+  end
+  
+  class MissingConfiguration < ConfigurationError
+    def initialize(option)
+      @option = option
+      super("Missing required configuration option: #{option}")
+    end
+  end
+  
+  # Authentication errors
+  class AuthenticationError < Error; end
+  
+  class InvalidState < AuthenticationError
+    def initialize
+      super("Invalid state parameter. This may be a CSRF attempt or the session expired")
+    end
+  end
+  
+  class MissingState < AuthenticationError
+    def initialize
+      super("Missing state parameter in session. Session may have expired")
+    end
+  end
+  
+  class AuthorizationDenied < AuthenticationError
+    def initialize(reason = nil)
+      @reason = reason
+      super(reason ? "Authorization denied: #{reason}" : "Authorization denied by user")
+    end
+  end
+  
+  # Token errors
+  class TokenError < Error; end
+  
+  class InvalidToken < TokenError
+    def initialize(reason = nil)
+      @reason = reason
+      super(reason ? "Invalid token: #{reason}" : "Token validation failed")
+    end
+  end
+  
+  class ExpiredToken < TokenError
+    def initialize
+      super("Token has expired")
+    end
+  end
+  
+  class InvalidGrant < TokenError
+    def initialize(reason = nil)
+      @reason = reason
+      super(reason ? "Invalid grant: #{reason}" : "Authorization code is invalid or expired")
+    end
+  end
+  
+  class InvalidAccessToken < TokenError
+    def initialize
+      super("Access token is invalid or expired")
+    end
+  end
+  
+  # Provider errors
+  class ProviderError < Error; end
+  
+  class UnsupportedProvider < ProviderError
+    def initialize(provider)
+      @provider = provider
+      super("Provider '#{provider}' is not supported")
+    end
+  end
+  
+  class ProviderAPIError < ProviderError
+    def initialize(provider, error = nil)
+      @provider = provider
+      @error = error
+      message = "Error from #{provider} API"
+      message += ": #{error}" if error
+      super(message)
+    end
+  end
+end
+```
+
+## Logging Integration
+
+All errors are automatically logged with appropriate log levels:
+
+```ruby
+# lib/clavis/logging.rb
+module Clavis
+  module Logging
+    def self.log_error(error)
+      case error
+      when Clavis::AuthorizationDenied
+        # User chose to cancel, not a real error
+        Rails.logger.info("[Clavis] Authorization denied: #{error.message}")
+      when Clavis::InvalidState, Clavis::MissingState
+        # Could be session expiration or CSRF attempt
+        Rails.logger.warn("[Clavis] Security issue: #{error.class.name} - #{error.message}")
+      when Clavis::ProviderAPIError
+        # Provider API errors
+        Rails.logger.error("[Clavis] Provider API error: #{error.message}")
+      when Clavis::ConfigurationError
+        # Configuration issues
+        Rails.logger.error("[Clavis] Configuration error: #{error.message}")
+      else
+        # All other errors
+        Rails.logger.error("[Clavis] #{error.class.name}: #{error.message}")
+      end
+      
+      # Only log backtraces for unexpected errors in debug mode
+      unless error.is_a?(Clavis::AuthorizationDenied)
+        Rails.logger.debug("[Clavis] #{error.backtrace.join("\n")}")
+      end
+    end
+  end
+end
+```
+
+## Error Handling in Controllers
+
+Example of how to handle Clavis errors in a controller:
+
+```ruby
+# app/controllers/sessions_controller.rb
+class SessionsController < ApplicationController
+  include Clavis::Controllers::Concerns::Authentication
+  
+  def create_from_oauth
+    oauth_callback do |user, auth_hash|
+      session[:user_id] = user.id
+      redirect_to root_path, notice: "Signed in successfully!"
+    end
+  rescue Clavis::AuthorizationDenied
+    # User cancelled the authentication
+    redirect_to login_path, notice: "Authentication cancelled"
+  rescue Clavis::InvalidState, Clavis::MissingState
+    # Session expired or possible CSRF attempt
+    redirect_to login_path, alert: "Authentication session expired. Please try again."
+  rescue Clavis::TokenError => e
+    # Token-related errors
+    Clavis::Logging.log_error(e)
+    redirect_to login_path, alert: "Authentication failed. Please try again."
+  rescue Clavis::ProviderAPIError => e
+    # Provider API errors
+    Clavis::Logging.log_error(e)
+    redirect_to login_path, alert: "Service temporarily unavailable. Please try again later."
+  rescue Clavis::Error => e
+    # Catch all other Clavis errors
+    Clavis::Logging.log_error(e)
+    redirect_to login_path, alert: "Authentication failed: #{e.message}"
+  end
+end
+```
+
+## Custom Error Pages
+
+For a better user experience, consider creating custom error pages:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # Authentication failure routes
+  get '/auth/failure', to: 'sessions#failure'
+  
+  # Other routes...
+end
+
+# app/controllers/sessions_controller.rb
+class SessionsController < ApplicationController
+  def failure
+    reason = params[:message] || "unknown reason"
+    redirect_to login_path, alert: "Authentication failed: #{reason}"
+  end
+end
+```
+
+## Handling OAuth Error Responses
+
+The OAuth 2.0 specification defines standard error responses. Clavis maps these to specific exceptions:
+
+| OAuth Error | Clavis Exception |
+|-------------|------------------|
+| `invalid_request` | `Clavis::AuthenticationError` |
+| `unauthorized_client` | `Clavis::AuthenticationError` |
+| `access_denied` | `Clavis::AuthorizationDenied` |
+| `unsupported_response_type` | `Clavis::ConfigurationError` |
+| `invalid_scope` | `Clavis::ConfigurationError` |
+| `server_error` | `Clavis::ProviderAPIError` |
+| `temporarily_unavailable` | `Clavis::ProviderAPIError` |
+| `invalid_client` | `Clavis::ConfigurationError` |
+| `invalid_grant` | `Clavis::InvalidGrant` |
+| `invalid_token` | `Clavis::InvalidToken` |
+
+## Exception Middleware
+
+For Rails API applications, consider adding a middleware to handle Clavis exceptions:
+
+```ruby
+# lib/clavis/middleware/exception_handler.rb
+module Clavis
+  module Middleware
+    class ExceptionHandler
+      def initialize(app)
+        @app = app
+      end
+      
+      def call(env)
+        @app.call(env)
+      rescue Clavis::Error => e
+        Clavis::Logging.log_error(e)
+        
+        # Convert to appropriate HTTP response
+        case e
+        when Clavis::AuthorizationDenied
+          # User cancelled
+          [302, { 'Location' => '/auth/failure?message=denied' }, []]
+        when Clavis::InvalidState, Clavis::MissingState
+          # Security issues
+          [302, { 'Location' => '/auth/failure?message=session_expired' }, []]
+        when Clavis::TokenError
+          # Token issues
+          [302, { 'Location' => '/auth/failure?message=token_error' }, []]
+        when Clavis::ProviderAPIError
+          # Provider API issues
+          [302, { 'Location' => '/auth/failure?message=provider_error' }, []]
+        else
+          # Other Clavis errors
+          [302, { 'Location' => "/auth/failure?message=#{CGI.escape(e.message)}" }, []]
+        end
+      end
+    end
+  end
+end
+```
+
+## Testing Error Handling
+
+```ruby
+# spec/error_handling_spec.rb
+RSpec.describe "Error Handling" do
+  describe "AuthorizationDenied error" do
+    it "redirects to login path with appropriate message" do
+      # Simulate user denying authorization
+      get "/auth/google/callback", params: { error: "access_denied" }
+      
+      expect(response).to redirect_to(login_path)
+      expect(flash[:notice]).to include("Authentication cancelled")
+    end
+  end
+  
+  describe "InvalidState error" do
+    it "redirects to login path with session expired message" do
+      # Simulate CSRF attack with invalid state
+      get "/auth/google/callback", params: { code: "123", state: "invalid" }
+      
+      expect(response).to redirect_to(login_path)
+      expect(flash[:alert]).to include("session expired")
+    end
+  end
+  
+  # More error handling tests...
+end
+```