rails_simple_auth 1.0.1 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 407b27862ed25ee5daa7fff450777ba4cec5f2e91d967df7ecc79f3a8831b285
-  data.tar.gz: 2a687ca739d79dcb1e1c1c9d8b8b7a4dd9aa6b9a31558cda56ea7a1fe3084e50
+  metadata.gz: 5fb876e2f8ec9c1f40ed2dbb8d97fdd984e7e5927e11c56be6a2ac4b2aa593a4
+  data.tar.gz: 29a914c7c8f77a85199d6f7188ce77ab24460554ca90421b22b38646f15464f5
 SHA512:
-  metadata.gz: a0c7a9ae65587337dc327ef68ecd0ae9b2ff84d00a775431f40138e2664fd8ef6c072d18bb7bc5323919adaacc1eeeab76d2960f7d24e8082251f673a020244b
-  data.tar.gz: 8f40cb9b06ac207555fad164f7c6428f1ba26101a9737c7401e8c8a5f42ebed50ec9033c64a6923ff3270b50f9bb220e6149c3edf9bac09ff3ca5c7f65d87b4c
+  metadata.gz: 8a7d0926e4e1e3a8c7da6ec9ab4de80768ae98a1316a32b6d9bf6aa790f266fc494598344b9a47444bfac1241ab55ea6d11c4c89a56bb2d270cff816a0bb3178
+  data.tar.gz: b9ea5fa54ad39f51e86dae6852df477760bfb8c28a3c002cae421c40d44e5d3fb74e0ecfaa6ab6d65705cb3ba579d72e4c47061aa2b06d848d5f4639ca9f1eaf

data/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.3] - 2025-01-19
+
+### Added
+
+- **Temporary Users Support** - Allow users to try the app without signing up, then convert to permanent accounts
+  - `TemporaryUser` concern with `temporary?` and `permanent?` methods
+  - Scopes: `temporary`, `permanent`, `temporary_expired`
+  - `convert_to_permanent!(email:, password:)` method for account conversion
+  - Generator: `rails g rails_simple_auth:temporary_users` for migration
+  - Configuration options: `temporary_users_enabled`, `temporary_user_cleanup_days`
+  - Automatic cleanup of expired temporary users via `User.cleanup_expired_temporary!`
+  - Session invalidation on account conversion
+  - Automatic destruction of temporary user when signing in with different account
+- **Email Reconfirmation Flow** - Support for users changing their email address
+  - `unconfirmed_email` column support for pending email changes
+  - `reconfirming?` and `unconfirmed_or_reconfirming?` helper methods
+  - `confirmable_email` helper returns the email needing confirmation
+  - Confirmation emails sent to new email address during reconfirmation
+- Comprehensive test suite (126 tests, 247 assertions)
+
+### Fixed
+
+- `confirm!` now uses `has_attribute?(:temporary)` instead of `respond_to?(:temporary?)` to prevent errors when `Authenticatable` is included without the temporary database column
+- `confirm!` properly handles race conditions with `RecordNotUnique` rescue during reconfirmation
+- `convert_to_permanent!` validates password presence to prevent users being left without credentials
+- `convert_to_permanent!` reloads after transaction to check actual database state (not stale in-memory state)
+- `convert_to_permanent!` resets `confirmed_at` to require email verification for new address
+- `cleanup_expired_temporary!` now returns accurate count (only increments when destroy succeeds)
+- `magic_link_login` checks `confirm!` return value and shows error if confirmation fails
+- `confirmations_controller#show` checks `confirm!` return value and displays appropriate error message
+- `destroy_temporary_user_session` skips destruction when user is re-authenticating as themselves
+- `AuthMailer#confirmation` sends to `confirmable_email` for correct recipient during reconfirmation
+
+### Changed
+
+- Confirmation token purpose changed from `:email_confirmation` to `:confirm_email` (**Breaking**: existing confirmation tokens will be invalidated)
+
+## [1.0.2] - 2025-01-18
+
+### Fixed
+
+- Session invalidation and batch cleanup for temporary users
+
 ## [1.0.0] - 2025-01-18
 
 ### Added

data/README.md

@@ -4,15 +4,16 @@ Simple, secure authentication for Rails 8+ applications. Built on Rails primitiv
 
 ## Features
 
-- **Email/Password authentication** with bcrypt
-- **Magic link** (passwordless) authentication
-- **Email confirmation** with signed tokens
-- **Password reset** with signed tokens
-- **OAuth support** (Google, GitHub, etc.)
-- **Rate limiting** built-in
-- **Session tracking** with IP and user agent
-- **Customizable styling** via CSS variables
-- **No dependencies** beyond Rails and bcrypt
+- [**Email/Password authentication**](#installation) - secure session-based auth
+- [**Magic link authentication**](#routes) - passwordless sign-in via email
+- [**Email confirmation**](#routes) - verify user email addresses
+- [**Password reset**](#routes) - secure password recovery flow
+- [**OAuth support**](#oauth-setup) - Google, GitHub, and more
+- [**Temporary users**](#temporary-users-guest-accounts) - guest accounts that convert to permanent
+- [**Rate limiting**](#rate-limiting) - built-in protection on all endpoints
+- [**Session tracking**](#session-management) - IP and user agent logging
+- [**Customizable styling**](#styling) - CSS variables for easy theming
+- [**Custom mailers**](#mailer) - use your own branded email templates
 
 ## Installation
 
@@ -67,7 +68,7 @@ class CreateUsers < ActiveRecord::Migration[8.0]
   def change
     create_table :users do |t|
       # Required by gem
-      t.string :email_address, null: false
+      t.string :email, null: false
       t.string :password_digest, null: false
       t.datetime :confirmed_at  # if using Confirmable
 
@@ -81,7 +82,7 @@ class CreateUsers < ActiveRecord::Migration[8.0]
       t.timestamps
     end
 
-    add_index :users, :email_address, unique: true
+    add_index :users, :email, unique: true
   end
 end
 ```
@@ -203,6 +204,156 @@ class User < ApplicationRecord
 end
 ```
 
+## Temporary Users (Guest Accounts)
+
+Temporary users allow visitors to try your app without creating an account. They get a real user record with full functionality, then can convert to a permanent account later by providing email and password.
+
+### Why Use Temporary Users?
+
+**Reduce friction**: Let users experience your app's value before asking them to sign up. This is especially useful for:
+
+- **E-commerce**: Users can add items to cart, save preferences, then checkout as guest or create account
+- **Productivity apps**: Users can create documents, try features, then save their work by signing up
+- **Games**: Users can start playing immediately, then create account to save progress
+- **Collaboration tools**: Users can join a shared workspace via link, then register to keep access
+
+**Preserve data**: Unlike anonymous sessions, temporary users have real database records. When they convert, all their data (orders, documents, settings) stays linked to their account.
+
+### Setup
+
+1. Generate the migration:
+
+```bash
+rails generate rails_simple_auth:temporary_users
+rails db:migrate
+```
+
+2. Add the concern to your User model:
+
+```ruby
+class User < ApplicationRecord
+  include RailsSimpleAuth::Models::Concerns::Authenticatable
+  include RailsSimpleAuth::Models::Concerns::TemporaryUser  # Add this
+end
+```
+
+3. Enable in configuration:
+
+```ruby
+RailsSimpleAuth.configure do |config|
+  config.temporary_users_enabled = true
+  config.temporary_user_cleanup_days = 7  # Auto-cleanup after 7 days
+end
+```
+
+### Creating Temporary Users
+
+Create a temporary user when someone needs to use your app without signing up:
+
+```ruby
+# In your controller
+def try_without_account
+  user = User.create!(
+    email: "temp_#{SecureRandom.hex(8)}@temporary.local",
+    password: SecureRandom.hex(32),
+    temporary: true
+  )
+
+  # Sign them in
+  create_session_for(user)
+  redirect_to dashboard_path
+end
+```
+
+Or create via an invite link:
+
+```ruby
+def accept_invite
+  # Create temporary user to access shared content
+  user = User.create!(temporary: true, ...)
+  create_session_for(user)
+  redirect_to shared_workspace_path(params[:workspace_id])
+end
+```
+
+### Converting to Permanent Account
+
+When a temporary user is ready to create a real account:
+
+```ruby
+# In your controller
+def convert_account
+  if current_user.convert_to_permanent!(
+    email: params[:email],
+    password: params[:password]
+  )
+    redirect_to dashboard_path, notice: "Account created! Please check your email to confirm."
+  else
+    # Validation failed (email taken, password blank, etc.)
+    render :convert_form, status: :unprocessable_entity
+  end
+end
+```
+
+The conversion:
+- Updates email and password
+- Sets `temporary: false`
+- Resets `confirmed_at` (requires email confirmation for new address)
+- Invalidates all existing sessions (security measure)
+- Sends confirmation email automatically
+
+### What Happens on Sign In?
+
+When a temporary user signs in with a different account (or signs up), the temporary user is automatically destroyed:
+
+```
+Temporary User (browsing) → Signs in with existing account → Temp user deleted
+Temporary User (browsing) → Creates new account → Temp user deleted
+Temporary User (browsing) → Converts their temp account → Keeps same user record
+```
+
+This prevents orphaned temporary records and ensures clean data.
+
+### Querying Users
+
+```ruby
+User.temporary           # All temporary users
+User.permanent           # All permanent users
+User.temporary_expired   # Temporary users older than cleanup_days
+
+current_user.temporary?  # Is this a guest?
+current_user.permanent?  # Is this a real account?
+```
+
+### Cleanup
+
+Temporary users are automatically eligible for cleanup after `temporary_user_cleanup_days`. Run cleanup manually or via scheduled job:
+
+```ruby
+# In a rake task or background job
+User.cleanup_expired_temporary!
+
+# With custom retention period
+User.cleanup_expired_temporary!(days: 14)
+```
+
+Add to your scheduler (e.g., `config/recurring.yml` for Solid Queue):
+
+```yaml
+cleanup_temporary_users:
+  schedule: every day at 3am
+  class: CleanupTemporaryUsersJob
+```
+
+```ruby
+class CleanupTemporaryUsersJob < ApplicationJob
+  def perform
+    count = User.cleanup_expired_temporary!
+    Rails.logger.info "Cleaned up #{count} expired temporary users"
+  end
+end
+```
+
 ## Controller Customization
 
 Subclass controllers for custom behavior:
@@ -266,19 +417,19 @@ class UserMailer < ApplicationMailer
   def confirmation(user, token)
     @user = user
     @confirmation_url = edit_confirmation_url(token: token)
-    mail(to: user.email_address, subject: "Confirm your email")
+    mail(to: user.email, subject: "Confirm your email")
   end
 
   def magic_link(user, token)
     @user = user
     @magic_link_url = magic_link_login_url(token: token)
-    mail(to: user.email_address, subject: "Your sign-in link")
+    mail(to: user.email, subject: "Your sign-in link")
   end
 
   def password_reset(user, token)
     @user = user
     @reset_url = edit_password_url(token: token)
-    mail(to: user.email_address, subject: "Reset your password")
+    mail(to: user.email, subject: "Reset your password")
   end
 end
 ```
@@ -330,6 +481,112 @@ The gem adds these routes:
 | POST | `/request_magic_link` | Send magic link |
 | GET | `/magic_link` | Login via magic link |
 
+## Rate Limiting
+
+All authentication endpoints are rate limited using Rails 8's `rate_limit` DSL to prevent brute force attacks.
+
+### Default Limits
+
+| Action | Limit | Period | Scope |
+|--------|-------|--------|-------|
+| Sign in | 5 requests | 15 minutes | per IP |
+| Sign up | 5 requests | 1 hour | per IP |
+| Magic link request | 3 requests | 10 minutes | per email |
+| Password reset | 3 requests | 1 hour | per IP |
+| Email confirmation | 3 requests | 1 hour | per IP |
+
+### Customizing Limits
+
+```ruby
+RailsSimpleAuth.configure do |config|
+  config.rate_limits = {
+    sign_in: { limit: 10, period: 30.minutes },
+    sign_up: { limit: 3, period: 1.hour },
+    magic_link: { limit: 5, period: 15.minutes },
+    password_reset: { limit: 5, period: 1.hour },
+    confirmation: { limit: 5, period: 1.hour }
+  }
+end
+```
+
+### Disabling Rate Limiting
+
+To disable rate limiting for a specific action, set it to `nil`:
+
+```ruby
+config.rate_limits = {
+  sign_in: nil,  # No rate limiting on sign in
+  sign_up: { limit: 5, period: 1.hour }
+}
+```
+
+When rate limited, users see a "Too many requests" error and must wait for the period to expire.
+
+## Session Management
+
+Sessions track user authentication state with IP address and user agent for security auditing.
+
+### What's Tracked
+
+Each session stores:
+- **user_id** - The authenticated user
+- **ip_address** - Client IP at sign-in time
+- **user_agent** - Browser/device information
+- **created_at** - When the session was created
+
+### Session Expiration
+
+Sessions expire after 30 days by default:
+
+```ruby
+RailsSimpleAuth.configure do |config|
+  config.session_expiry = 30.days  # Default
+  # config.session_expiry = 7.days  # Shorter sessions
+end
+```
+
+### Querying Sessions
+
+```ruby
+# All sessions for a user
+current_user.sessions
+
+# Recent sessions first
+current_user.sessions.recent
+
+# Active sessions (not expired)
+current_user.sessions.active
+
+# Expired sessions
+current_user.sessions.expired
+```
+
+### Session Cleanup
+
+Expired sessions can be cleaned up manually or via scheduled job:
+
+```ruby
+# Clean up all expired sessions
+RailsSimpleAuth::Session.cleanup_expired!
+```
+
+Add to your scheduler:
+
+```ruby
+class CleanupExpiredSessionsJob < ApplicationJob
+  def perform
+    count = RailsSimpleAuth::Session.cleanup_expired!
+    Rails.logger.info "Cleaned up #{count} expired sessions"
+  end
+end
+```
+
+### Security Behaviors
+
+- **Password change**: All sessions are invalidated when a user changes their password
+- **Account conversion**: All sessions are invalidated when a temporary user converts to permanent
+- **Sign out**: Only the current session is destroyed (other devices stay signed in)
+
 ## Security Features
 
 - **BCrypt password hashing** with salts

data/app/controllers/rails_simple_auth/confirmations_controller.rb

@@ -6,33 +6,41 @@ module RailsSimpleAuth
 
     unless Rails.env.local?
       rate_limit to: 3, within: 1.hour, by: -> { client_ip }, only: :create,
-                 with: -> { redirect_to new_confirmation_path, alert: "Too many confirmation requests. Please try again later." }
+                 with: lambda {
+                   redirect_to new_confirmation_path, alert: 'Too many confirmation requests. Please try again later.'
+                 }
     end
 
-    def new
+    def show
+      user = user_class.find_signed(params[:token], purpose: :confirm_email)
+
+      if user
+        confirmed = user.respond_to?(:confirm!) ? user.confirm! : true
+
+        if confirmed
+          run_after_confirmation_callback(user)
+          redirect_to resolve_path(:after_confirmation_path), notice: 'Email confirmed! You can now sign in.'
+        else
+          error_message = user.errors.full_messages.first || 'Could not confirm email.'
+          redirect_to new_confirmation_path, alert: error_message
+        end
+      else
+        redirect_to new_confirmation_path, alert: 'Invalid or expired confirmation link.'
+      end
     end
 
+    def new; end
+
     def create
-      user = user_class.find_by_email(params[:email_address])
+      user = user_class.find_by(email: params[:email])
 
-      if user && user.respond_to?(:unconfirmed?) && user.unconfirmed?
+      if user.respond_to?(:unconfirmed_or_reconfirming?) && user.unconfirmed_or_reconfirming?
         token = user.generate_confirmation_token
         RailsSimpleAuth.configuration.mailer.confirmation(user, token).deliver_later
       end
 
-      redirect_to new_session_path, notice: "If an unconfirmed account exists with that email, confirmation instructions have been sent."
-    end
-
-    def show
-      user = user_class.find_signed(params[:token], purpose: :email_confirmation)
-
-      if user
-        user.confirm! if user.respond_to?(:confirm!)
-        run_after_confirmation_callback(user)
-        redirect_to resolve_path(:after_confirmation_path), notice: "Email confirmed! You can now sign in."
-      else
-        redirect_to new_confirmation_path, alert: "Invalid or expired confirmation link."
-      end
+      redirect_to new_session_path,
+                  notice: 'If an unconfirmed account exists with that email, confirmation instructions have been sent.'
     end
 
     private

data/app/controllers/rails_simple_auth/omniauth_callbacks_controller.rb

@@ -6,27 +6,29 @@ module RailsSimpleAuth
     skip_before_action :verify_authenticity_token, only: :create
 
     def create
-      auth_hash = request.env["omniauth.auth"]
+      auth_hash = request.env['omniauth.auth']
       provider = params[:provider]
 
       unless RailsSimpleAuth.configuration.oauth_provider_enabled?(provider)
-        redirect_to new_session_path, alert: "OAuth provider not enabled."
+        redirect_to new_session_path, alert: 'OAuth provider not enabled.'
         return
       end
 
       user = user_class.from_oauth(auth_hash)
 
       if user&.persisted?
+        destroy_temporary_user_session(user)
         create_session_for(user)
         run_after_sign_in_callback(user)
-        redirect_to resolve_path(:after_sign_in_path), notice: "Signed in successfully with #{provider.to_s.capitalize}."
+        redirect_to resolve_path(:after_sign_in_path),
+                    notice: "Signed in successfully with #{provider.to_s.capitalize}."
       else
         redirect_to new_session_path, alert: "Could not authenticate with #{provider.to_s.capitalize}."
       end
     end
 
     def failure
-      redirect_to new_session_path, alert: "Authentication failed. Please try again."
+      redirect_to new_session_path, alert: 'Authentication failed. Please try again.'
     end
   end
 end

data/app/controllers/rails_simple_auth/passwords_controller.rb

@@ -7,31 +7,32 @@ module RailsSimpleAuth
 
     unless Rails.env.local?
       rate_limit to: 3, within: 1.hour, by: -> { client_ip }, only: :create,
-                 with: -> { redirect_to new_password_path, alert: "Too many password reset requests. Please try again later." }
+                 with: lambda {
+                   redirect_to new_password_path, alert: 'Too many password reset requests. Please try again later.'
+                 }
     end
 
-    def new
-    end
+    def new; end
+
+    def edit; end
 
     def create
-      user = user_class.find_by_email(params[:email_address])
+      user = user_class.find_by(email: params[:email])
 
       if user && can_reset_password?(user)
         token = user.generate_password_reset_token
         RailsSimpleAuth.configuration.mailer.password_reset(user, token).deliver_later
       end
 
-      redirect_to new_session_path, notice: "If an account exists with that email, password reset instructions have been sent."
-    end
-
-    def edit
+      redirect_to new_session_path,
+                  notice: 'If an account exists with that email, password reset instructions have been sent.'
     end
 
     def update
       ActiveRecord::Base.transaction do
         if @user.update(password_params)
           @user.invalidate_all_sessions!
-          redirect_to new_session_path, notice: "Password has been reset. Please sign in with your new password."
+          redirect_to new_session_path, notice: 'Password has been reset. Please sign in with your new password.'
         else
           render :edit, status: :unprocessable_content
           raise ActiveRecord::Rollback
@@ -42,14 +43,14 @@ module RailsSimpleAuth
         "[RailsSimpleAuth] Session invalidation failed after password reset for user #{@user.id}: #{e.message}"
       )
       # Password was rolled back due to transaction, redirect with error
-      redirect_to new_password_path, alert: "Password reset failed. Please try again."
+      redirect_to new_password_path, alert: 'Password reset failed. Please try again.'
     end
 
     private
 
     def set_user_from_token
       @user = user_class.find_signed(params[:token], purpose: :password_reset)
-      redirect_to new_password_path, alert: "Invalid or expired password reset link." unless @user
+      redirect_to new_password_path, alert: 'Invalid or expired password reset link.' unless @user
     end
 
     def can_reset_password?(user)
@@ -60,7 +61,7 @@ module RailsSimpleAuth
     end
 
     def password_params
-      params.require(:user).permit(:password, :password_confirmation)
+      params.expect(user: %i[password password_confirmation])
     end
   end
 end

data/app/controllers/rails_simple_auth/registrations_controller.rb

@@ -6,7 +6,7 @@ module RailsSimpleAuth
 
     unless Rails.env.local?
       rate_limit to: 5, within: 1.hour, by: -> { client_ip }, only: :create,
-                 with: -> { redirect_to sign_up_path, alert: "Too many sign up attempts. Please try again later." }
+                 with: -> { redirect_to sign_up_path, alert: 'Too many sign up attempts. Please try again later.' }
     end
 
     def new
@@ -27,18 +27,20 @@ module RailsSimpleAuth
     private
 
     def registration_params
-      params.require(:user).permit(:email_address, :password)
+      params.expect(user: %i[email password])
     end
 
     def after_successful_registration
+      destroy_temporary_user_session(@user)
+
       if RailsSimpleAuth.configuration.email_confirmation_enabled
         send_confirmation_email(@user)
         run_after_sign_up_callback(@user)
-        redirect_to new_session_path, notice: "Account created! Please check your email to confirm your account."
+        redirect_to new_session_path, notice: 'Account created! Please check your email to confirm your account.'
       else
         create_session_for(@user)
         run_after_sign_up_callback(@user)
-        redirect_to resolve_path(:after_sign_up_path), notice: "Account created successfully!"
+        redirect_to resolve_path(:after_sign_up_path), notice: 'Account created successfully!'
       end
     end