rails_simple_auth 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d9299c78e7be2bfe4bc6e338150d03ec03d80e6c624616e09c30b48c5bf16c6
-  data.tar.gz: 145ebfad74f0188f138a9e8e006bfac26a6404b89d3690a0a8484246a5b01d9f
+  metadata.gz: 5fb876e2f8ec9c1f40ed2dbb8d97fdd984e7e5927e11c56be6a2ac4b2aa593a4
+  data.tar.gz: 29a914c7c8f77a85199d6f7188ce77ab24460554ca90421b22b38646f15464f5
 SHA512:
-  metadata.gz: 92302e8e2c6d489ebda9e82b222e0a53f31c52f0b8958bf3af2a4240f654f0de7bd81892e350ee92892df16d747ef88d4b43ae69b6af0e510ee1504925755693
-  data.tar.gz: 07d17cb9ca09fe1f01446cf1faf4cc67fb303d5c0553b6e2c242595054700a88fff187838820aed8639c65b3fd839e3679771acb178700f7966cf17f0f1ce258
+  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,16 +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.)
-- **Temporary users** (guest mode) with conversion to permanent
-- **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
 
@@ -204,9 +204,20 @@ class User < ApplicationRecord
 end
 ```
 
-## Temporary Users (Guest Mode)
+## Temporary Users (Guest Accounts)
 
-Allow visitors to try your app without signing up, then convert to permanent accounts later.
+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
 
@@ -217,7 +228,7 @@ rails generate rails_simple_auth:temporary_users
 rails db:migrate
 ```
 
-2. Include the concern in your User model:
+2. Add the concern to your User model:
 
 ```ruby
 class User < ApplicationRecord
@@ -237,42 +248,110 @@ 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
-# Create a temporary user (no email/password required)
-temp_user = User.create!(
-  email: "temp_#{SecureRandom.hex(8)}@temp.local",
-  password: SecureRandom.hex(16),
-  temporary: true
-)
+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
-# When user decides to sign up for real
-temp_user.convert_to_permanent!(
-  email: "real@example.com",
-  password: "secure_password"
-)
-# Sends confirmation email automatically if email confirmation is enabled
+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?
 ```
 
-### Scopes
+### Cleanup
+
+Temporary users are automatically eligible for cleanup after `temporary_user_cleanup_days`. Run cleanup manually or via scheduled job:
 
 ```ruby
-User.temporary          # All temporary users
-User.permanent          # All permanent users
-User.temporary_expired  # Temporary users older than cleanup_days
-User.temporary_expired(14)  # Custom days
+# In a rake task or background job
+User.cleanup_expired_temporary!
+
+# With custom retention period
+User.cleanup_expired_temporary!(days: 14)
 ```
 
-### Cleanup Task
+Add to your scheduler (e.g., `config/recurring.yml` for Solid Queue):
 
-Add to your scheduler (cron, Sidekiq, etc.):
+```yaml
+cleanup_temporary_users:
+  schedule: every day at 3am
+  class: CleanupTemporaryUsersJob
+```
 
 ```ruby
-# Delete expired temporary users
-User.temporary_expired.destroy_all
+class CleanupTemporaryUsersJob < ApplicationJob
+  def perform
+    count = User.cleanup_expired_temporary!
+    Rails.logger.info "Cleaned up #{count} expired temporary users"
+  end
+end
 ```
 
 ## Controller Customization
@@ -402,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

@@ -15,9 +15,15 @@ module RailsSimpleAuth
       user = user_class.find_signed(params[:token], purpose: :confirm_email)
 
       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.'
+        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

data/app/controllers/rails_simple_auth/sessions_controller.rb

@@ -70,7 +70,13 @@ module RailsSimpleAuth
       user = user_class.find_signed(params[:token], purpose: :magic_link)
 
       if user
-        user.confirm! if user.respond_to?(:confirm!) && user.respond_to?(:unconfirmed?) && user.unconfirmed?
+        # Auto-confirm unconfirmed users via magic link (email ownership verified)
+        if user.respond_to?(:confirm!) && user.respond_to?(:unconfirmed?) && user.unconfirmed? && !user.confirm!
+          # Confirmation failed (e.g., email already taken during reconfirmation)
+          error_message = user.errors.full_messages.first || 'Could not confirm email.'
+          redirect_to new_session_path, alert: error_message
+          return
+        end
         sign_in_and_redirect(user)
       else
         redirect_to new_session_path, alert: 'Invalid or expired magic link.'

data/app/mailers/rails_simple_auth/auth_mailer.rb

@@ -4,6 +4,9 @@ module RailsSimpleAuth
   class AuthMailer < ApplicationMailer
     default from: -> { RailsSimpleAuth.configuration.mailer_sender }
 
+    # Use the mailers folder for templates instead of auth_mailer
+    self.mailer_name = 'rails_simple_auth/mailers'
+
     def confirmation(user, token)
       @user = user
       @token = token

data/lib/rails_simple_auth/models/concerns/confirmable.rb

@@ -44,7 +44,7 @@ module RailsSimpleAuth
         # Returns true on success, false on failure (with errors populated)
         def confirm!
           attrs = { confirmed_at: Time.current }
-          attrs[:temporary] = false if respond_to?(:temporary?)
+          attrs[:temporary] = false if has_attribute?(:temporary)
 
           if reconfirming?
             # Email change confirmation - check email uniqueness first
@@ -62,6 +62,10 @@ module RailsSimpleAuth
             # Already confirmed and not reconfirming
             true
           end
+        rescue ActiveRecord::RecordNotUnique
+          # Race condition: email was taken between check and update
+          errors.add(:email, 'is already taken by another user')
+          false
         end
 
         # Generate email confirmation token using Rails signed_id

data/lib/rails_simple_auth/models/concerns/temporary_user.rb

@@ -28,6 +28,12 @@ module RailsSimpleAuth
         # Convert a temporary user to a permanent user with email and password
         # Returns self on success, false on failure (with errors populated)
         def convert_to_permanent!(email:, password:)
+          # Validate password presence upfront
+          if password.blank?
+            errors.add(:password, "can't be blank")
+            return false
+          end
+
           # Validate email uniqueness upfront (better UX than failing inside transaction)
           if self.class.where.not(id: id).exists?(email: email)
             errors.add(:email, 'has already been taken')
@@ -55,7 +61,11 @@ module RailsSimpleAuth
             raise ActiveRecord::Rollback unless update(attrs)
           end
 
-          # Check if transaction was rolled back
+          # Reload to get actual database state after transaction
+          # (in-memory attributes may be stale if transaction was rolled back)
+          reload
+
+          # Check if conversion actually succeeded
           return false if errors.any? || temporary?
 
           invalidate_all_sessions!
@@ -75,8 +85,7 @@ module RailsSimpleAuth
           def cleanup_expired_temporary!(days: nil, batch_size: 100)
             count = 0
             temporary_expired(days).find_each(batch_size: batch_size) do |user|
-              user.destroy
-              count += 1
+              count += 1 if user.destroy
             end
             Rails.logger.info("[RailsSimpleAuth] Cleaned up #{count} expired temporary users")
             count

data/lib/rails_simple_auth/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsSimpleAuth
-  VERSION = '1.0.2'
+  VERSION = '1.0.3'
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_simple_auth
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Ivan Kuznetsov
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-01-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bcrypt
@@ -100,6 +101,7 @@ metadata:
   bug_tracker_uri: https://github.com/ivankuznetsov/rails_simple_auth/issues
   documentation_uri: https://github.com/ivankuznetsov/rails_simple_auth#readme
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -114,7 +116,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Simple, secure authentication for Rails 8+ applications
 test_files: []