rails-auth-eassy 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 022e8a17beff8064ba4e48a9e57291c6380ef6240d753f2aac9b877619ad4525
+  data.tar.gz: f9c078225e321580caaa9d47bddd3905fbd5e6af673f1fd038430189100841e9
+SHA512:
+  metadata.gz: 908356f0e6c4d3bb58dfca0f2af495b3837435a6130158f463cb235e682c780ce82183a2f7d18563677d9d94b179b18580c62599849c303e0e486741503c6e12
+  data.tar.gz: 8e42c802b4fa14ad066f7e2258ab9ed4bbaa0ce3f454b13708c33e6ae04e0dfd64a8feff0a71d437734cdd2f8b6f039ea30451bf2b161b7bf34c72d8133cbe43

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2026 Shiboshree Roy, Gemini CLI
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,206 @@
+# 🛡️ Rails::Auth
+
+**Rails::Auth** is a high-performance, security-first authentication engine for Ruby on Rails. Designed as a modern, transparent alternative to Devise, it empowers users with deep visibility and control over their account security through database-backed sessions and enterprise-grade protection.
+
+[![Gem Version](https://badge.fury.io/rb/rails-auth.svg)](https://badge.fury.io/rb/rails-auth)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Rails Version](https://img.shields.io/badge/Rails-7.0+-red.svg)](https://rubyonrails.org)
+
+---
+
+## 📖 Table of Contents
+- [🚀 Key Features](#-key-features)
+- [📦 Installation](#-installation)
+- [🛠️ Getting Started](#-getting-started)
+- [📖 Usage](#-usage)
+  - [Controller Helpers](#controller-helpers)
+  - [Role-Based Access Control (RBAC)](#role-based-access-control-rbac)
+  - [Avatar Support](#avatar-support)
+- [🛡️ Security Dashboard](#-security-dashboard)
+- [⚙️ Configuration](#-configuration)
+- [🎨 Customization](#-customization)
+- [👥 Authors & Maintainers](#-authors--maintainers)
+- [📄 License](#-license)
+
+---
+
+## 🚀 Key Features
+
+### 🔐 Enterprise Security
+- **JWT Authentication**: Built-in support for stateless API authentication via `Authorization: Bearer <token>`.
+- **Security Audit Logs**: Comprehensive tracking of sensitive actions (login failures, MFA toggles, password changes).
+- **Admin Impersonation**: Securely log in as any user for customer support while tracking the original admin's actions.
+- **Two-Factor Authentication (MFA)**: Modern TOTP support (Google Authenticator, Authy) with automated QR codes.
+- **Account Locking (Lockable)**: Protection against brute-force attacks with email-based unlocking.
+- **Email Confirmation (Confirmable)**: Ensure every user is verified before they can access your app.
+- **Role-Based Access Control (RBAC)**: Built-in `user`, `moderator`, and `admin` roles with clean authorization helpers.
+
+### 📱 Advanced Session Management
+- **Database-Backed Sessions**: Every device login is tracked, allowing for complete transparency.
+- **Remote Device Revocation**: Log out of lost or stolen devices remotely from the dashboard.
+- **Global Sign-Out**: Instant "Sign out of all devices" for emergency account security.
+- **Device Intelligence**: Automatically identifies **Browser**, **OS**, and **IP Address** for every session.
+
+### 🛠️ Developer Experience
+- **Active Storage Ready**: Seamlessly integrated avatar/profile picture support.
+- **Model Independent**: Easily attach to `User`, `Admin`, `Member`, or any other model.
+- **Minimalistic Core**: Built on top of Rails' native `has_secure_password`.
+- **Generator Driven**: Scaffold everything you need in seconds.
+
+---
+
+## 📦 Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "rails-auth"
+```
+
+Then execute:
+```bash
+$ bundle install
+```
+
+---
+
+## 🛠️ Getting Started
+
+### 1. Run the Installer
+Scaffold the configuration and engine routes:
+```bash
+$ rails g rails_auth:install
+```
+
+### 2. Generate Your Authentication Model
+Create or update your user model (e.g., `User`):
+```bash
+$ rails g rails_auth:model User
+```
+This will generate:
+- The `User` & `Session` models.
+- Migrations for MFA, Lockable, Confirmable, and RBAC.
+
+### 3. Run Migrations
+```bash
+$ rails db:migrate
+```
+
+---
+
+## 📖 Usage
+
+### Base Controller Setup
+Include the authentication concern in your `ApplicationController`:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Rails::Auth::AuthenticatableController
+end
+```
+
+### Controller Helpers
+| Helper | Description |
+| :--- | :--- |
+| `authenticate_user!` | Before action to ensure the user is logged in. |
+| `current_user` | Returns the currently authenticated user. |
+| `current_session` | Returns the database record for the current session. |
+| `user_signed_in?` | Check if a user is currently authenticated. |
+| `require_admin!` | Authorization helper to restrict access to admins. |
+| `authorize_role!(*roles)` | Restrict access to specific roles (e.g., `:moderator`, `:admin`). |
+
+### Role-Based Access Control (RBAC)
+```ruby
+class Admin::SettingsController < ApplicationController
+  before_action :require_admin!
+  
+  def update
+    # Only admins can reach here
+  end
+end
+```
+
+### Avatar Support
+Rails::Auth uses Active Storage for avatars. Once Active Storage is installed in your host app:
+```erb
+<% if current_user.avatar.attached? %>
+  <%= image_tag current_user.avatar.variant(resize_to_limit: [50, 50]) %>
+<% end %>
+```
+
+### JWT API Authentication
+Rails::Auth automatically supports JWTs for API endpoints.
+1. Send a `POST` to `/auth/session.json` with email/password.
+2. Receive a token: `{ "token": "eyJhb..." }`.
+3. Use it in subsequent requests: `Authorization: Bearer eyJhb...`
+
+### Admin Impersonation
+Admins can impersonate users for support purposes:
+```ruby
+# Start Impersonation (Controller action)
+sign_in(user, impersonated_by: current_user)
+
+# Stop Impersonation
+rails_auth.stop_impersonations_path, method: :delete
+```
+*Note: Impersonation events are securely logged in the `SecurityEvent` table.*
+
+---
+
+## 🛡️ Security Dashboard
+
+Users can manage their security settings, view active sessions, and enable MFA at `/auth/security/sessions`.
+
+### Linking to the Dashboard
+```erb
+<%= link_to "Security Settings", rails_auth.security_sessions_path %>
+```
+
+---
+
+## ⚙️ Configuration
+
+Customize the gem behavior in `config/initializers/rails_auth.rb`:
+
+```ruby
+Rails::Auth.setup do |config|
+  config.user_class_name = "User"
+  config.session_class_name = "Session"
+end
+```
+
+---
+
+## 🎨 Customization
+
+### Views
+Override the default views by copying them to your application:
+```bash
+$ rails g rails_auth:views
+```
+
+### Controllers
+You can inherit from `Rails::Auth::ApplicationController` or include the `AuthenticatableController` in your own controllers for deep integration.
+
+---
+
+## 🧪 Testing
+
+Rails::Auth is tested against modern Rails versions. Run the suite:
+```bash
+$ bundle exec rake test
+```
+
+---
+
+## 👥 Authors & Maintainers
+
+- **Shiboshree Roy** - *Lead Developer*
+
+---
+
+## 📄 License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+---
+Built with ❤️ for the Rails Community by **Shiboshree Roy**.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/rails/auth/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/concerns/rails/auth/authenticatable_controller.rb

@@ -0,0 +1,114 @@
+module Rails
+  module Auth
+    module AuthenticatableController
+      extend ActiveSupport::Concern
+
+      included do
+        before_action :authenticate_user!
+        helper_method :current_user, :current_session, :user_signed_in?, :impersonating?
+      end
+
+      private
+
+      def authenticate_user!
+        redirect_to rails_auth.new_session_path unless user_signed_in?
+      end
+
+      def current_user
+        Rails::Auth::Current.user ||= (authenticate_by_session_token || authenticate_by_jwt)
+      end
+
+      def current_session
+        Rails::Auth::Current.session
+      end
+
+      def true_user
+        return nil unless current_session&.impersonated_by_id
+        Rails::Auth.user_class.find(current_session.impersonated_by_id)
+      end
+
+      def impersonating?
+        true_user.present?
+      end
+
+      def user_signed_in?
+        current_user.present?
+      end
+
+      def require_admin!
+        authorize_role!(:admin)
+      end
+
+      def authorize_role!(*roles)
+        unless user_signed_in? && roles.any? { |role| current_user.send("#{role}?") }
+          if request.format.json?
+            render json: { error: "Unauthorized" }, status: :forbidden
+          else
+            redirect_to main_app.root_path, alert: "You are not authorized to access this page."
+          end
+        end
+      end
+
+      def sign_in(user, impersonated_by: nil)
+        session_record = user.sessions.create!(
+          ip_address: request.remote_ip,
+          user_agent: request.user_agent,
+          impersonated_by_id: impersonated_by&.id,
+          last_active_at: Time.current
+        )
+
+        unless request.format.json?
+          cookies.signed.permanent[:session_token] = {
+            value: session_record.token,
+            httponly: true,
+            secure: Rails.env.production?
+          }
+        end
+
+        Rails::Auth::Current.user = user
+        Rails::Auth::Current.session = session_record
+
+        event = impersonated_by ? :impersonation_started : :login_success
+        user.log_security_event!(event, request, { impersonated_by_id: impersonated_by&.id })
+
+        session_record
+      end
+
+      def sign_out
+        current_user&.log_security_event!(:logout, request)
+        current_session&.destroy
+        cookies.delete(:session_token)
+        Rails::Auth::Current.user = nil
+        Rails::Auth::Current.session = nil
+      end
+
+      def authenticate_by_session_token
+        if token = cookies.signed[:session_token]
+          session_record = Rails::Auth.session_class.find_by(token: token)
+          if session_record
+            session_record.update(last_active_at: Time.current, ip_address: request.remote_ip)
+            Rails::Auth::Current.session = session_record
+            session_record.user
+          end
+        end
+      end
+
+      def authenticate_by_jwt
+        header = request.headers["Authorization"]
+        return nil unless header.present?
+
+        token = header.split(" ").last
+        decoded = Rails::Auth.decode_jwt(token)
+        return nil unless decoded
+
+        user = Rails::Auth.user_class.find_by(id: decoded[:user_id])
+        if user
+          # Optional: We could also track JWT sessions in the database if we wanted revocation,
+          # but usually JWTs are stateless. For "Ultimate" we might want to track them.
+          # Let's keep it simple for now or use a JTI claim.
+          user
+        end
+      end
+    end
+  end
+end

data/app/controllers/rails/auth/application_controller.rb

@@ -0,0 +1,9 @@
+module Rails
+  module Auth
+    class ApplicationController < ::ApplicationController
+      include Rails::Auth::AuthenticatableController
+
+      protect_from_forgery with: :exception
+    end
+  end
+end

data/app/controllers/rails/auth/confirmations_controller.rb

@@ -0,0 +1,18 @@
+module Rails
+  module Auth
+    class ConfirmationsController < ApplicationController
+      skip_before_action :authenticate_user!
+
+      def show
+        user = Rails::Auth.user_class.find_by(confirmation_token: params[:confirmation_token])
+        if user
+          user.confirm!
+          sign_in(user)
+          redirect_to main_app.root_path, notice: "Your account has been confirmed."
+        else
+          redirect_to new_session_path, alert: "Invalid confirmation token."
+        end
+      end
+    end
+  end
+end

data/app/controllers/rails/auth/impersonations_controller.rb

@@ -0,0 +1,46 @@
+module Rails
+  module Auth
+    class ImpersonationsController < ApplicationController
+      before_action :require_admin!
+      skip_before_action :require_admin!, only: [ :destroy ]
+
+      def create
+        user = Rails::Auth.user_class.find(params[:user_id])
+
+        if user == current_user
+          redirect_to main_app.root_path, alert: "You cannot impersonate yourself."
+          return
+        end
+
+        # Store the current admin session so we can go back
+        admin_user = current_user
+
+        # Sign out current session (admin)
+        sign_out
+
+        # Sign in as the target user, but mark it as impersonated
+        sign_in(user, impersonated_by: admin_user)
+
+        redirect_to main_app.root_path, notice: "You are now impersonating #{user.email}."
+      end
+
+      def destroy
+        unless impersonating?
+          redirect_to main_app.root_path, alert: "You are not impersonating anyone."
+          return
+        end
+
+        admin_user = true_user
+
+        # Sign out of the impersonated session
+        current_user.log_security_event!(:impersonation_stopped, request, { impersonated_by_id: admin_user.id })
+        sign_out
+
+        # Sign back in as the admin
+        sign_in(admin_user)
+
+        redirect_to main_app.root_path, notice: "Impersonation stopped. Welcome back, #{admin_user.email}."
+      end
+    end
+  end
+end

data/app/controllers/rails/auth/mfa_controller.rb

@@ -0,0 +1,26 @@
+module Rails
+  module Auth
+    class MfaController < ApplicationController
+      def show
+        current_user.generate_otp_secret! unless current_user.otp_secret
+        @qrcode = RQRCode::QRCode.new(current_user.otp_provisioning_uri)
+      end
+
+      def create
+        if current_user.verify_otp(params[:otp_code])
+          current_user.update(otp_enabled: true)
+          redirect_to security_sessions_path, notice: "Two-factor authentication enabled."
+        else
+          flash.now[:alert] = "Invalid OTP code. Please try again."
+          @qrcode = RQRCode::QRCode.new(current_user.otp_provisioning_uri)
+          render :show, status: :unprocessable_entity
+        end
+      end
+
+      def destroy
+        current_user.update(otp_enabled: false, otp_secret: nil)
+        redirect_to security_sessions_path, notice: "Two-factor authentication disabled."
+      end
+    end
+  end
+end

data/app/controllers/rails/auth/otp_verifications_controller.rb

@@ -0,0 +1,25 @@
+module Rails
+  module Auth
+    class OtpVerificationsController < ApplicationController
+      skip_before_action :authenticate_user!
+
+      def new
+        unless session[:otp_user_id]
+          redirect_to new_session_path, alert: "Session expired."
+        end
+      end
+
+      def create
+        user = Rails::Auth.user_class.find(session[:otp_user_id])
+        if user.verify_otp(params[:otp_code])
+          session.delete(:otp_user_id)
+          sign_in(user)
+          redirect_to main_app.root_path, notice: "Signed in successfully."
+        else
+          flash.now[:alert] = "Invalid OTP code."
+          render :new, status: :unprocessable_entity
+        end
+      end
+    end
+  end
+end

data/app/controllers/rails/auth/password_resets_controller.rb

@@ -0,0 +1,51 @@
+module Rails
+  module Auth
+    class PasswordResetsController < ApplicationController
+      skip_before_action :authenticate_user!
+      before_action :set_user, only: [ :edit, :update ]
+
+      def new
+      end
+
+      def create
+        @user = Rails::Auth.user_class.find_by(email: params[:email])
+        if @user
+          @user.generate_password_reset_token!
+          UserMailer.password_reset(@user).deliver_now
+        end
+        redirect_to rails_auth.new_session_path, notice: "If an account with that email exists, you will receive a password reset link shortly."
+      end
+
+      def edit
+        unless @user&.password_reset_token_valid?
+          redirect_to rails_auth.new_password_reset_path, alert: "Password reset link has expired or is invalid."
+        end
+      end
+
+      def update
+        if @user.password_reset_token_valid?
+          if @user.update(password_params)
+            @user.clear_password_reset_token!
+            @user.sessions.destroy_all # Security: Sign out of all sessions after password change
+            sign_in(@user)
+            redirect_to main_app.root_path, notice: "Password has been reset successfully and all other sessions have been signed out."
+          else
+            render :edit, status: :unprocessable_entity
+          end
+        else
+          redirect_to rails_auth.new_password_reset_path, alert: "Password reset link has expired."
+        end
+      end
+
+      private
+
+      def set_user
+        @user = Rails::Auth.user_class.find_by!(reset_token: params[:id])
+      end
+
+      def password_params
+        params.require(:user).permit(:password, :password_confirmation)
+      end
+    end
+  end
+end

data/app/controllers/rails/auth/profiles_controller.rb

@@ -0,0 +1,24 @@
+module Rails
+  module Auth
+    class ProfilesController < ApplicationController
+      def edit
+        @user = current_user
+      end
+
+      def update
+        @user = current_user
+        if @user.update(profile_params)
+          redirect_to security_sessions_path, notice: "Profile updated successfully."
+        else
+          render :edit, status: :unprocessable_entity
+        end
+      end
+
+      private
+
+      def profile_params
+        params.require(:user).permit(:email, :password, :password_confirmation, :avatar)
+      end
+    end
+  end
+end

data/app/controllers/rails/auth/registrations_controller.rb

@@ -0,0 +1,27 @@
+module Rails
+  module Auth
+    class RegistrationsController < ApplicationController
+      skip_before_action :authenticate_user!, only: [ :new, :create ]
+
+      def new
+        @user = Rails::Auth.user_class.new
+      end
+
+      def create
+        @user = Rails::Auth.user_class.new(user_params)
+        if @user.save
+          @user.send_confirmation_instructions
+          redirect_to rails_auth.new_session_path, notice: "A confirmation link has been sent to your email address. Please follow the link to activate your account."
+        else
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      private
+
+      def user_params
+        params.require(:user).permit(:email, :password, :password_confirmation, :avatar)
+      end
+    end
+  end
+end

data/app/controllers/rails/auth/security_controller.rb

@@ -0,0 +1,27 @@
+module Rails
+  module Auth
+    class SecurityController < ApplicationController
+      def sessions
+        @sessions = current_user.sessions.order(last_active_at: :desc)
+      end
+
+      def revoke_session
+        session_to_revoke = current_user.sessions.find(params[:id])
+        session_to_revoke.destroy
+
+        if session_to_revoke == current_session
+          sign_out
+          redirect_to rails_auth.new_session_path, notice: "Your current session was revoked. Please sign in again."
+        else
+          redirect_to rails_auth.security_sessions_path, notice: "Session revoked successfully."
+        end
+      end
+
+      def revoke_all_sessions
+        current_user.sessions.destroy_all
+        sign_out
+        redirect_to rails_auth.new_session_path, notice: "All sessions have been revoked. Please sign in again."
+      end
+    end
+  end
+end