securial 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6955f517ae29e92b5a870f5e951782374d39f7c5eeb19de024d818106a57cc82
-  data.tar.gz: a91673febf7143ab6b245feab4154d1d511ca62b7f78f6a94c758b974c2860ed
+  metadata.gz: d5d32016af493f09599093d6a47f3ad2ec6b1be080a82d1ef275374249802808
+  data.tar.gz: 75b64439f12e4b9f581a625967d83b39ebd07215be6c722ce4fbe81c50d3b0c9
 SHA512:
-  metadata.gz: 18a435b9714861bf5f76e516d54b5ed0a3ad4b9d1e192825f2766fab494f90d0579a89d5f5d812b67cc33bb876a174e9341980997ead6a6a5e134bce26637fed
-  data.tar.gz: f584db4b3d36d73d0a5fe83439ef75b409e2fe971337a3ad8b25bb9335727053fed1f272057062a2061b0b2b8c01d866f91e894570c77e4320277ea69ead268c
+  metadata.gz: 0da8943af4c5a85090d711e862d0e00185f0af951c9a619796fc9d3de3cfb37ab939fea73c690b6378495e66794b9f5ebe26f010fd44bc95118acc727654114a
+  data.tar.gz: 6785f1890063c01eac1a2b8f3b15aee18eb6cc8429eead79c15c65aadf5854a5496ab8bf5f0ac572f5a47020108dce77d23bbf49bd091062b3f5900a0fb4f002

data/README.md

@@ -5,7 +5,8 @@
 [![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/AlyBadawy/Securial?tab=MIT-1-ov-file#readme)
 
 [![Tests](https://github.com/alybadawy/securial/actions/workflows/ci.yml/badge.svg)](https://github.com/alybadawy/securial/actions)
-[![Coverage Status](https://coveralls.io/repos/github/AlyBadawy/Securial/badge.svg?branch=main)](https://coveralls.io/github/AlyBadawy/Securial?branch=main)
+[![Coveralls](https://img.shields.io/coverallsCoverage/github/AlyBadawy/Securial?branch=main&logo=coveralls&logoColor=%233F5767&labelColor=ddeedd)
+](https://coveralls.io/github/AlyBadawy/Securial?branch=main)
 
 > [!WARNING]
 >
@@ -26,15 +27,12 @@
 - ✅ Clean, JSON-based API responses
 - ✅ Database-agnostic support
 
-
 ### 🚀 Why Securial?
 
 Securial was built to offer a clean, modular, and API-first authentication system for Rails developers who want full control without the black-box complexity. Whether you're building for the web, mobile, or both, Securial gives you the flexibility to implement exactly what you need — from simple JWT authentication to more advanced setups involving sessions, API tokens, and role-based access.
 
 It follows familiar Rails conventions, stays lightweight and database-agnostic, and keeps security at the core. With fully customizable controllers, serializers, and logic, Securial is designed to grow with your project — making it an ideal choice for everything from side projects to production-grade APIs.
 
-
-
 ## 🚀 Installation
 
 Securial can be installed on an existing Rails application or use the `securial new app_name` command to create a new Securial-ready Rails app.
@@ -94,7 +92,6 @@ Explore all modules in the [Wiki](https://github.com/AlyBadawy/Securial/wiki).
 - Run `bundle install`
 - Start coding right away 🏃‍♂️
 
-
 To run the test suite:
 
 ```bash

data/app/controllers/concerns/securial/identity.rb

@@ -14,9 +14,10 @@ module Securial
     end
 
     def authenticate_admin!
-      unless current_user.is_admin?
-        render status: :forbidden, json: { error: "You are not authorized to perform this action" } and return
-      end
+      authenticate_user!
+      return if current_user.blank? || current_user.is_admin?
+
+      render status: :forbidden, json: { error: "You are not authorized to perform this action" }
     end
 
     def current_user
@@ -28,26 +29,26 @@ module Securial
     def authenticate_user!
       return if internal_rails_request?
 
+      Current.session = nil
       auth_header = request.headers["Authorization"]
       if auth_header.present? && auth_header.start_with?("Bearer ")
         token = auth_header.split(" ").last
         begin
           decoded_token = Securial::Auth::AuthEncoder.decode(token)
-          Current.session = Session.find_by!(id: decoded_token["jti"], revoked: false)
-        rescue Securial::Auth::Errors::AuthDecodeError, ActiveRecord::RecordNotFound => e
-          render status: :unauthorized, json: { error: "Invalid token: #{e.message}" } and return
+          session = Session.find_by(id: decoded_token["jti"], revoked: false)
+          if session.present? &&
+             session.is_valid_session? &&
+             session.ip_address == request.remote_ip &&
+             session.user_agent == request.user_agent
+            Current.session = session
+            return # Authenticated
+          end
+        rescue Securial::Error::Auth::TokenDecodeError, ActiveRecord::RecordNotFound => e
+          Securial.logger.debug "Authentication failed: #{e.message}"
         end
-      else
-        render status: :unauthorized, json: { error: "Missing or invalid Authorization header" } and return
       end
-    end
-
-    def start_new_session_for(user)
-      Securial::Auth::SessionCreator.create_session(user, request)
-    end
-
-    def create_jwt_for_current_session
-      Securial::Auth::AuthEncoder.encode(Current.session)
+      # If we reach here, authentication failed
+      render status: :unauthorized, json: { error: "You are not signed in" } and return
     end
 
     def internal_rails_request?

data/app/controllers/securial/accounts_controller.rb

@@ -7,12 +7,12 @@ module Securial
     end
 
     def show
-      @securial_user = User.find_by(username: params.expect(:username))
+      @securial_user = Securial::User.find_by(username: params.expect(:username))
       render_user_profile
     end
 
     def register
-      @securial_user = User.new(user_params)
+      @securial_user = Securial::User.new(user_params)
       if @securial_user.save
         render :show, status: :created, location: @securial_user
       else

data/app/controllers/securial/passwords_controller.rb

@@ -6,7 +6,7 @@ module Securial
     def forgot_password
       if user = User.find_by(email_address: params.require(:email_address))
         user.generate_reset_password_token!
-        Securial::SecurialMailer.reset_password(user).deliver_later
+        Securial::SecurialMailer.forgot_password(user).deliver_later
       end
 
       render status: :ok, json: { message: "Password reset instructions sent (if user with that email address exists)." }
@@ -26,7 +26,7 @@ module Securial
     def set_user_by_password_token
       @user = User.find_by_reset_password_token!(params[:token]) # rubocop:disable Rails/DynamicFindBy
       unless @user.reset_password_token_valid?
-        render status: :unprocessable_entity, json: { errors: { token: "is invalid or has expired" } }
+        render status: :unprocessable_entity, json: { errors: { token: "is invalid or has expired" } } and return
       end
     rescue ActiveSupport::MessageVerifier::InvalidSignature, ActiveRecord::RecordNotFound
       render status: :unprocessable_entity, json: { errors: { token: "is invalid or has expired" } } and return

data/app/controllers/securial/role_assignments_controller.rb

@@ -3,13 +3,12 @@ module Securial
     def create
       return unless define_user_and_role
 
-      if @user.roles.exists?(@role.id)
+      if @securial_user.roles.exists?(@securial_role.id)
         render json: { error: "Role already assigned to user" }, status: :unprocessable_entity
         return
       end
       @securial_role_assignment = RoleAssignment.new(securial_role_assignment_params)
       @securial_role_assignment.save
-      @securial_user = @user
       render :show, status: :created
     end
 
@@ -18,7 +17,6 @@ module Securial
       @role_assignment = RoleAssignment.find_by(securial_role_assignment_params)
       if @role_assignment
         @role_assignment.destroy!
-        @securial_user = @user
         render :show, status: :ok
       else
         render json: { error: "Role is not assigned to user" }, status: :unprocessable_entity
@@ -28,13 +26,13 @@ module Securial
     private
 
     def define_user_and_role
-      @user = User.find_by(id: params.expect(securial_role_assignment: [:user_id]).dig(:user_id))
-      @role = Role.find_by(id: params.expect(securial_role_assignment: [:role_id]).dig(:role_id))
-      if @user.nil?
+      @securial_user = User.find_by(id: params.expect(securial_role_assignment: [:user_id]).dig(:user_id))
+      @securial_role = Role.find_by(id: params.expect(securial_role_assignment: [:role_id]).dig(:role_id))
+      if @securial_user.nil?
         render json: { error: "User not found" }, status: :unprocessable_entity
         return false
       end
-      if @role.nil?
+      if @securial_role.nil?
         render json: { error: "Role not found" }, status: :unprocessable_entity
         return false
       end

data/app/controllers/securial/roles_controller.rb

@@ -29,6 +29,7 @@ module Securial
 
     def destroy
       @securial_role.destroy
+      head :no_content
     end
 
     private

data/app/controllers/securial/sessions_controller.rb

@@ -31,14 +31,12 @@ module Securial
     end
 
     def refresh
-      if Current.session = Session.find_by(refresh_token: params[:refresh_token])
-        if Current.session.is_valid_session? &&
-           Current.session.ip_address == request.ip &&
-           Current.session.user_agent == request.user_agent
+      if Current.session = Securial::Session.find_by(refresh_token: params[:refresh_token])
+        if Current.session.is_valid_session_request?(request)
           Current.session.refresh!
           render status: :created,
                  json: {
-                   access_token: create_jwt_for_current_session,
+                   access_token: Securial::Auth::AuthEncoder.encode(Current.session),
                    refresh_token: Current.session.refresh_token,
                    refresh_token_expires_at: Current.session.refresh_token_expires_at,
                  }
@@ -64,7 +62,7 @@ module Securial
 
     def set_session
       id = params[:id]
-      @securial_session = id ? Current.user.sessions.find(params.expect(:id)) : Current.session
+      @securial_session = id ? Current.user.sessions.find(params[:id]) : Current.session
     end
 
     def render_login_response(user)
@@ -75,10 +73,10 @@ module Securial
                  instructions: "Please reset your password before logging in.",
                }
       else
-        start_new_session_for user
+        Securial::Auth::SessionCreator.create_session!(user, request)
         render status: :created,
                json: {
-                 access_token: create_jwt_for_current_session,
+                 access_token: Securial::Auth::AuthEncoder.encode(Current.session),
                  refresh_token: Current.session.refresh_token,
                  refresh_token_expires_at: Current.session.refresh_token_expires_at,
                }

data/app/controllers/securial/users_controller.rb

@@ -28,26 +28,27 @@ module Securial
     end
 
     def destroy
-      @securial_user.destroy!
+      @securial_user.destroy
+      head :no_content
     end
 
     private
 
     def set_securial_user
-      @securial_user = User.find(params.expect(:id))
+      @securial_user = User.find(params[:id])
     end
 
     def securial_user_params
       params.expect(securial_user: [
                       :email_address,
-                      :password,
-                      :password_confirmation,
+                      :username,
                       :first_name,
                       :last_name,
                       :phone,
-                      :username,
-                      :bio
-                    ])
+                      :bio,
+                      :password,
+                      :password_confirmation
+        ])
     end
   end
 end

data/app/mailers/securial/securial_mailer.rb

@@ -1,17 +1,28 @@
 module Securial
   class SecurialMailer < ApplicationMailer
-    default from: Securial.configuration.mailer_sender
+    def welcome(securial_user)
+      @user = securial_user
+      subject = Securial.configuration.mailer_sign_up_subject
+      mail subject: subject, to: securial_user.email_address
+    end
 
-    def reset_password(securial_user)
+    def sign_in(securial_user, securial_session)
       @user = securial_user
-      subject = reset_password_subject
+      @session = securial_session
+      subject = Securial.configuration.mailer_sign_in_subject
       mail subject: subject, to: securial_user.email_address
     end
 
-    private
+    def update_account(securial_user)
+      @user = securial_user
+      subject = Securial.configuration.mailer_update_account_subject
+      mail subject: subject, to: securial_user.email_address
+    end
 
-    def reset_password_subject
-      Securial.configuration.password_reset_email_subject
+    def forgot_password(securial_user)
+      @user = securial_user
+      subject = Securial.configuration.mailer_forgot_password_subject
+      mail subject: subject, to: securial_user.email_address
     end
   end
 end

data/app/models/concerns/securial/password_resettable.rb

@@ -25,7 +25,7 @@ module Securial
 
     def generate_reset_password_token!
       update!(
-        reset_password_token: SecureRandom.urlsafe_base64,
+        reset_password_token: Auth::TokenGenerator.generate_password_reset_token,
         reset_password_token_created_at: Time.current
       )
     end

data/app/models/securial/application_record.rb

@@ -12,7 +12,7 @@ module Securial
     def generate_uuid_v7
       return if self.id.present? || self.class.type_for_attribute(:id).type != :string
 
-      self.id ||= Random.uuid_v7
+      self.id = Random.uuid_v7
     end
   end
 end

data/app/models/securial/session.rb

@@ -11,17 +11,28 @@ module Securial
     end
 
     def is_valid_session?
-      !revoked && refresh_token_expires_at > Time.current
+      revoked? || expired? ? false : true
+    end
+
+    def is_valid_session_request?(request)
+      is_valid_session? && ip_address == request.ip && user_agent == request.user_agent
     end
 
     def refresh!
-      raise Securial::Auth::Errors::AuthRevokedError, "Session is revoked" if revoked
-      raise Securial::Auth::Errors::AuthExpiredError, "Session is expired" if refresh_token_expires_at < Time.current
+      raise Securial::Error::Auth::TokenRevokedError if revoked?
+      raise Securial::Error::Auth::TokenExpiredError if expired?
+
+      new_refresh_token = Securial::Auth::TokenGenerator.generate_refresh_token
 
-      update!(refresh_token: SecureRandom.hex(64),
+      refresh_token_duration = Securial.configuration.session_refresh_token_expires_in
+
+      update!(refresh_token: new_refresh_token,
               refresh_count: self.refresh_count + 1,
               last_refreshed_at: Time.current,
-              refresh_token_expires_at: 1.week.from_now)
+              refresh_token_expires_at: refresh_token_duration.from_now)
     end
+
+    def revoked?; revoked; end
+    def expired?; refresh_token_expires_at < Time.current; end
   end
 end

data/app/models/securial/user.rb

@@ -46,9 +46,7 @@ module Securial
 
 
     def is_admin?
-      titleized_role_name = Securial.configuration.admin_role.to_s.strip.titleize
-
-      roles.exists?(role_name: titleized_role_name)
+      roles.exists?(role_name: Securial.titleized_admin_role)
     end
   end
 end

data/app/views/securial/securial_mailer/forgot_password.html.erb

@@ -0,0 +1,20 @@
+<h1>Password Reset Instructions for <%= Securial.configuration.app_name || Rails.application.class.module_parent_name %></h1>
+<p>
+  Hello <%= @user.first_name || @user.email_address %>,
+</p>
+<p>
+  We received a request to reset your password for your account.
+</p>
+<p>
+  To reset your password, use the following token:
+</p>
+<p style="font-size: 1.2em; font-weight: bold; letter-spacing: 2px; background: #f7f7f7; padding: 8px 16px; display: inline-block;">
+  <%= @user.reset_password_token %>
+</p>
+<p>
+  If you did not request a password reset, please ignore this email.
+</p>
+<p>
+  Best regards,<br>
+  The <%= Securial.configuration.app_name || Rails.application.class.module_parent_name %> Team
+</p>

data/app/views/securial/securial_mailer/forgot_password.text.erb

@@ -0,0 +1,14 @@
+Password Reset Instructions for <%= Securial.configuration.app_name || Rails.application.class.module_parent_name %>
+
+Hello <%= @user.first_name || @user.email_address %>,
+
+We received a request to reset your password for your account.
+
+To reset your password, use the following token:
+
+<%= @user.reset_password_token %>
+
+If you did not request a password reset, please ignore this email.
+
+Best regards,
+The <%= Securial.configuration.app_name || Rails.application.class.module_parent_name %> Team

data/app/views/securial/securial_mailer/sign_in.html.erb

@@ -0,0 +1,31 @@
+<h1>Sign-in Alert for <%= Securial.configuration.app_name || Rails.application.class.module_parent_name %></h1>
+<p>
+  Hello <%= @user.first_name || @user.email_address %>,
+</p>
+<p>
+  We noticed a sign-in to your account.
+</p>
+<table style="border-collapse: collapse;">
+  <tr>
+    <td style="padding: 4px 8px; font-weight: bold;">IP Address:</td>
+    <td style="padding: 4px 8px;"><%= @session.ip_address %></td>
+  </tr>
+  <tr>
+    <td style="padding: 4px 8px; font-weight: bold;">Device/Browser:</td>
+    <td style="padding: 4px 8px;"><%= @session.user_agent %></td>
+  </tr>
+  <% if @session.respond_to?(:created_at) %>
+  <tr>
+    <td style="padding: 4px 8px; font-weight: bold;">Time:</td>
+    <td style="padding: 4px 8px;"><%= @session.created_at.strftime("%B %d, %Y at %H:%M %Z") %></td>
+  </tr>
+  <% end %>
+</table>
+<p>
+  If this was you, you can safely ignore this message.<br>
+  If you did not sign in, please reset your password immediately or contact support.
+</p>
+<p>
+  Best regards,<br>
+  The <%= Securial.configuration.app_name || Rails.application.class.module_parent_name %> Team
+</p>

data/app/views/securial/securial_mailer/sign_in.text.erb

@@ -0,0 +1,17 @@
+Sign-in Alert for <%= Securial.configuration.app_name || Rails.application.class.module_parent_name %>
+
+Hello <%= @user.first_name || @user.email_address %>,
+
+We noticed a sign-in to your account.
+
+IP Address: <%= @session.ip_address %>
+Device/Browser: <%= @session.user_agent %>
+<% if @session.respond_to?(:created_at) %>
+Time: <%= @session.created_at.strftime("%B %d, %Y at %H:%M %Z") %>
+<% end %>
+
+If this was you, you can safely ignore this message.
+If you did not sign in, please reset your password immediately or contact support.
+
+Best regards,
+The <%= Securial.configuration.app_name || Rails.application.class.module_parent_name %> Team

data/app/views/securial/securial_mailer/update_account.html.erb

@@ -0,0 +1,15 @@
+<h1>Your Account Has Been Updated on <%= Securial.configuration.app_name || Rails.application.class.module_parent_name %></h1>
+<p>
+  Hello <%= @user.first_name || @user.email_address %>,
+</p>
+<p>
+  This is a confirmation that changes were made to your account.
+</p>
+<p>
+  If you made these changes, you do not need to do anything further.<br>
+  If you did not update your account, please review your account security or contact support immediately.
+</p>
+<p>
+  Best regards,<br>
+  The <%= Securial.configuration.app_name || Rails.application.class.module_parent_name %> Team
+</p>

data/app/views/securial/securial_mailer/update_account.text.erb

@@ -0,0 +1,11 @@
+Your Account Has Been Updated on <%= Securial.configuration.app_name || Rails.application.class.module_parent_name %>
+
+Hello <%= @user.first_name || @user.email_address %>,
+
+This is a confirmation that changes were made to your account.
+
+If you made these changes, you do not need to do anything further.
+If you did not update your account, please review your account security or contact support immediately.
+
+Best regards,
+The <%= Securial.configuration.app_name || Rails.application.class.module_parent_name %> Team

data/app/views/securial/securial_mailer/welcome.html.erb

@@ -0,0 +1,11 @@
+<h1>Welcome to <%= Securial.configuration.app_name || Rails.application.class.module_parent_name %>, <%= @user.first_name || @user.email_address %>!</h1>
+<p>
+  Thank you for signing up. We're excited to have you on board.
+</p>
+<p>
+  If you have any questions or need help getting started, feel free to reply to this email.
+</p>
+<p>
+  Best regards,<br>
+  The <%= Securial.configuration.app_name || Rails.application.class.module_parent_name %> Team
+</p>

data/app/views/securial/securial_mailer/welcome.text.erb

@@ -0,0 +1,8 @@
+Welcome to <%= Securial.configuration.app_name || Rails.application.class.module_parent_name %>, <%= @user.first_name || @user.email_address %>!
+
+Thank you for signing up. We're excited to have you on board.
+
+If you have any questions or need help getting started, feel free to reply to this email.
+
+Best regards,
+The <%= Securial.configuration.app_name || Rails.application.class.module_parent_name %> Team

data/app/views/securial/users/_securial_user.json.jbuilder

@@ -1,15 +1,21 @@
 json.id securial_user.id
 
+json.email_address securial_user.email_address
+json.username securial_user.username
 json.first_name securial_user.first_name
 json.last_name securial_user.last_name
 json.phone securial_user.phone
-json.username securial_user.username
 json.bio securial_user.bio
+json.email_verified securial_user.email_verified
+json.locked securial_user.locked
+json.locked_at securial_user.locked_at
 
-json.password_expired securial_user.password_expired?
+# json.password_expired securial_user.password_expired?
+# This field is currently commented out because it is not required in the JSON response.
+# Uncomment this line if the `password_expired` field needs to be included in the future.
 
 json.roles securial_user.roles, partial: "securial/roles/securial_role", as: :securial_role
 
 json.partial! "securial/shared/timestamps", record: securial_user
 
-json.url securial.user_url(securial_user, format: :json)
+json.url securial.users_url(securial_user, format: :json)

data/config/routes.rb

@@ -1,8 +1,12 @@
+Rails.application.routes.default_url_options = { host: "localhost", port: 3000, protocol: "http" }
+
 Securial::Engine.routes.draw do
+  default_url_options host: "example.com"
+
   defaults format: :json do
     get "/status", to: "status#show", as: :status
 
-    scope Securial.admin_namespace do
+    scope Securial.protected_namespace do
       resources :roles
       resources :users
       namespace :role_assignments, as: "role_assignments" do

data/db/migrate/{20250515104930_create_securial_roles.rb → 20250603130214_create_securial_roles.rb}

@@ -6,7 +6,5 @@ class CreateSecurialRoles < ActiveRecord::Migration[8.0]
 
       t.timestamps
     end
-
-    add_index :securial_roles, :role_name, unique: true
   end
 end

data/db/migrate/{20250517155521_create_securial_users.rb → 20250604110520_create_securial_users.rb}

@@ -1,16 +1,21 @@
 class CreateSecurialUsers < ActiveRecord::Migration[8.0]
   def change
     create_table :securial_users, id: :string do |t|
-      t.string    :email_address
+      t.string    :email_address, null: false
+      t.boolean   :email_verified, null: false, default: false
+      t.string    :email_verification_token
+      t.datetime  :email_verification_token_created_at
+      t.string    :username, null: false
       t.string    :first_name
       t.string    :last_name
       t.string    :phone
-      t.string    :username
       t.string    :bio
       t.string    :password_digest
+      t.datetime  :password_changed_at
       t.string    :reset_password_token
       t.datetime  :reset_password_token_created_at
-      t.datetime  :password_changed_at
+      t.boolean   :locked, null: false, default: false
+      t.datetime  :locked_at
 
       t.timestamps
     end

data/db/migrate/{20250519075407_create_securial_sessions.rb → 20250604184841_create_securial_sessions.rb}

@@ -2,13 +2,17 @@ class CreateSecurialSessions < ActiveRecord::Migration[8.0]
   def change
     create_table :securial_sessions, id: :string do |t|
       t.references :user, null: false, type: :string, foreign_key: { to_table: :securial_users }
+
       t.string :ip_address, null: false
       t.string :user_agent, null: false
+
       t.string :refresh_token, null: false
       t.integer :refresh_count, default: 0
       t.datetime :last_refreshed_at
       t.datetime :refresh_token_expires_at
+
       t.boolean :revoked, default: false, null: false
+
       t.timestamps
     end
   end

data/lib/generators/securial/install/templates/securial_initializer.erb

@@ -60,7 +60,7 @@ Securial.configure do |config|
   ## Set the password reset email subject
   # This is the subject line that will be used for the password reset
   # email. The default is "Password Reset Instructions".
-  config.password_reset_email_subject = "Password Reset Instructions"
+  config.mailer_forgot_password_subject = "Password Reset Instructions"
 
   ## Set the minimum password length
   # This is the minimum length that a password must have

data/lib/generators/securial/scaffold/templates/controller.erb

@@ -29,6 +29,7 @@ module Securial
 
     def destroy
       @<%= singular_table_name %>.destroy
+      head :no_content
     end
 
     private

data/lib/generators/securial/scaffold/templates/routes.erb

@@ -2,7 +2,7 @@ Securial::Engine.routes.draw do
   defaults format: :json do
     get "/status", to: "status#show", as: :status
 
-    namespace Securial.admin_namespace do
+    namespace Securial.protected_namespace do
       # Placeholder for admin-specific routes. Add routes here as needed.
       # For example:
       # resources :users, only: [:index, :show]