securial 0.4.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2e0abc0d4c0a4b2a56220ab298edd28f767b4d8909a6af78f3097421cfc2fdda
+  data.tar.gz: 9230d0f2c93d1899cb642206adf79ceec04936894720dc989cc2b25c873f8774
+SHA512:
+  metadata.gz: 04102e38f339f980e2792c6dcc0559ef68a48506c31fc6b6625f44f7cc8f0a668d32c7e42583dfb7abe2d45690ca3e0df9ed9acb916f5c1630c651966413f8b2
+  data.tar.gz: 7db35473e9c983e9c6f803889da638ac210795ea8a9bc1270efd8136fc6a7c293ac01b7b8ca53b43fa695b33e872884e215a0496763222a0159a8c0dd5efe3d0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Aly Badawy
+
+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,90 @@
+![image](https://github.com/user-attachments/assets/d7cb9645-c28e-4cca-9c1b-5085a91c11d4)
+
+---
+# Securial
+
+[![Gem Version](https://img.shields.io/gem/v/securial?logo=rubygems&logoColor=ffffff&logoSize=auto&label=version&color=violet&cacheSeconds=120)](https://rubygems.org/gems/securial)
+[![Gem Downloads](https://img.shields.io/gem/dt/securial.svg)](https://rubygems.org/gems/securial)
+[![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)
+
+**Securial** is a mountable Rails engine that provides robust, extensible authentication and access control for Rails applications. It supports:
+
+- ✅ JWT-based authentication
+- ✅ API tokens
+- ✅ Session-based auth
+- ✅ Simple integration with web and mobile apps
+- ✅ Clean, JSON-based API responses
+- ✅ Database-agnostic support
+
+Next, mount the engine in `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount Securial::Engine => "/securial"
+end
+```
+
+Full installation steps are available in the [Wiki › Installation](https://github.com/AlyBadawy/Securial/wiki/Installation).
+
+## ⚙️ Configuration
+
+**Securial** generates an initializer with sensible defaults and full control over logging, mailers, session settings, and roles.
+
+For all configuration options and examples, refer to the [Wiki › Configuration](https://github.com/AlyBadawy/Securial/wiki/Configuration)
+
+## 📦 Usage
+
+After installation and mounting, **Securial** exposes endpoints like:
+
+- GET /securial/status — Check service availability
+- POST /securial/sessions — Sign in (JWT or session)
+- DELETE /securial/sessions — Sign out
+- GET /securial/accounts/cool_username — Get a user profile by username
+- GET /securial/admins/roles — View roles
+
+**Securial** returns consistent JSON API responses.
+
+Full details, including authentication flows and protected routes, are available in the [Wiki › Authentication module docs](https://github.com/AlyBadawy/Securial/wiki/Authentication).
+
+🧩 Modules
+
+**Securial** is organized into modular components including:
+
+- Authentication
+- User Management
+- Generators
+- Securial::Identity concern
+
+Explore all modules in the [Wiki](https://github.com/AlyBadawy/Securial/wiki).
+
+## 🛠 Development & Testing
+
+To run the test suite:
+
+```bash
+$ RAILS_ENV=test bundle db:schema:load
+$ bundle exec rspec
+```
+
+View the coverage report:
+
+```bash
+$ open coverage/index.html
+```
+
+## 🤝 Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/alybadawy/securial.
+
+1. Fork the repo
+2. Create your feature branch (git checkout -b my-feature)
+3. Commit your changes (git commit -am 'Add my feature')
+4. Push to the branch (git push origin my-feature)
+5. Open a Pull Request
+
+## ⚖️ License
+
+The gem is available as open source under the terms of the [MIT license](https://github.com/AlyBadawy/Securial?tab=MIT-1-ov-file#readme).

data/Rakefile

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

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

@@ -0,0 +1,67 @@
+module Securial
+  module Identity
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :authenticate_user!
+      helper_method :current_user if respond_to?(:helper_method)
+    end
+
+    class_methods do
+      def skip_authentication!(**options)
+        skip_before_action :authenticate_user!, **options
+      end
+    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
+    end
+
+    def current_user
+      Current.session&.user
+    end
+
+    private
+
+    def authenticate_user!
+      return if internal_rails_request?
+
+      auth_header = request.headers["Authorization"]
+      if auth_header.present? && auth_header.start_with?("Bearer ")
+        token = auth_header.split(" ").last
+        begin
+          decoded_token = AuthHelper.decode(token)
+          Current.session = Session.find_by!(id: decoded_token["jti"], revoked: false)
+        rescue JWT::DecodeError, ActiveRecord::RecordNotFound => e
+          render status: :unauthorized, json: { error: "Invalid token: #{e.message}" } and return
+        end
+      else
+        render status: :unauthorized, json: { error: "Missing or invalid Authorization header" } and return
+      end
+    end
+
+    def start_new_session_for(user)
+      user.sessions.create!(
+        user_agent: request.user_agent,
+        ip_address: request.remote_ip,
+        refresh_token: SecureRandom.hex(64),
+        last_refreshed_at: Time.current,
+        refresh_token_expires_at: 1.week.from_now,
+      ).tap do |session|
+        Current.session = session
+      end
+    end
+
+    def create_jwt_for_current_session
+      AuthHelper.encode(Current.session)
+    end
+
+    def internal_rails_request?
+      defined?(Rails::InfoController) && is_a?(Rails::InfoController) ||
+      defined?(Rails::MailersController) && is_a?(Rails::MailersController) ||
+      defined?(Rails::WelcomeController) && is_a?(Rails::WelcomeController)
+    end
+  end
+end

data/app/controllers/securial/accounts_controller.rb

@@ -0,0 +1,60 @@
+module Securial
+  class AccountsController < ApplicationController
+    def me
+      @securial_user = Current.user
+
+      render :show, status: :ok, location: @securial_user
+    end
+
+    def show
+      @securial_user = User.find_by(username: params.expect(:username))
+      render_user_profile
+    end
+
+    def register
+      @securial_user = User.new(user_params)
+      if @securial_user.save
+        render :show, status: :created, location: @securial_user
+      else
+        render json: { errors: @securial_user.errors.full_messages }, status: :unprocessable_entity
+      end
+    end
+
+    def update_profile
+      @securial_user = Current.user
+      if @securial_user.authenticate(params[:securial_user][:current_password])
+        if @securial_user.update(user_params)
+          render :show, status: :ok, location: @securial_user
+        else
+          render json: { errors: @securial_user.errors.full_messages }, status: :unprocessable_entity
+        end
+      else
+        render json: { error: "Current password is incorrect" }, status: :unprocessable_entity
+      end
+    end
+
+    def delete_account
+      @securial_user = Current.user
+      if @securial_user.authenticate(params.expect(securial_user: [:current_password]).dig(:current_password))
+        @securial_user.destroy
+        render json: { message: "Account deleted successfully" }, status: :ok
+      else
+        render json: { error: "Current password is incorrect" }, status: :unprocessable_entity
+      end
+    end
+
+    private
+
+    def user_params
+      params.expect(securial_user: [:email_address, :password, :password_confirmation, :first_name, :last_name, :phone, :username, :bio])
+    end
+
+    def render_user_profile
+      if @securial_user
+        render :show, status: :ok, location: @securial_user
+      else
+        render json: { error: "User not found" }, status: :not_found
+      end
+    end
+  end
+end

data/app/controllers/securial/application_controller.rb

@@ -0,0 +1,18 @@
+module Securial
+  class ApplicationController < ActionController::API
+    prepend_view_path Securial::Engine.root.join("app", "views")
+
+    rescue_from ActiveRecord::RecordNotFound, with: :render_404
+    rescue_from ActionController::ParameterMissing, with: :render_400
+
+    private
+
+    def render_404
+      render status: :not_found, json: { error: "Record not found" }
+    end
+
+    def render_400(exception)
+      render status: :bad_request, json: { error: exception.message }
+    end
+  end
+end

data/app/controllers/securial/passwords_controller.rb

@@ -0,0 +1,35 @@
+module Securial
+  class PasswordsController < ApplicationController
+    skip_authentication!
+    before_action :set_user_by_password_token, only: %i[ reset_password ]
+
+    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
+      end
+
+      render status: :ok, json: { message: "Password reset instructions sent (if user with that email address exists)." }
+    end
+
+    def reset_password
+      @user.clear_reset_password_token!
+      if @user.update(params.permit(:password, :password_confirmation))
+        render status: :ok, json: { message: "Password has been reset." }
+      else
+        render status: :unprocessable_entity, json: { errors: @user.errors }
+      end
+    end
+
+    private
+
+    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" } }
+      end
+    rescue ActiveSupport::MessageVerifier::InvalidSignature, ActiveRecord::RecordNotFound
+      render status: :unprocessable_entity, json: { errors: { token: "is invalid or has expired" } } and return
+    end
+  end
+end

data/app/controllers/securial/role_assignments_controller.rb

@@ -0,0 +1,49 @@
+module Securial
+  class RoleAssignmentsController < ApplicationController
+    def create
+      return unless define_user_and_role
+
+      if @user.roles.exists?(@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
+
+    def destroy
+      return unless define_user_and_role
+      @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
+      end
+    end
+
+    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?
+        render json: { error: "User not found" }, status: :unprocessable_entity
+        return false
+      end
+      if @role.nil?
+        render json: { error: "Role not found" }, status: :unprocessable_entity
+        return false
+      end
+
+      true
+    end
+
+    def securial_role_assignment_params
+      params.expect(securial_role_assignment: [:user_id, :role_id])
+    end
+  end
+end

data/app/controllers/securial/roles_controller.rb

@@ -0,0 +1,44 @@
+module Securial
+  class RolesController < ApplicationController
+    before_action :set_securial_role, only: [:show, :update, :destroy]
+
+    def index
+      @securial_roles = Role.all
+    end
+
+    def show
+    end
+
+    def create
+      @securial_role = Role.new(securial_role_params)
+
+      if @securial_role.save
+        render :show, status: :created, location: @securial_role
+      else
+        render json: @securial_role.errors, status: :unprocessable_entity
+      end
+    end
+
+    def update
+      if @securial_role.update(securial_role_params)
+        render :show
+      else
+        render json: @securial_role.errors, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      @securial_role.destroy
+    end
+
+    private
+
+    def set_securial_role
+      @securial_role = Role.find(params[:id])
+    end
+
+    def securial_role_params
+      params.expect(securial_role: [:role_name, :hide_from_profile])
+    end
+  end
+end

data/app/controllers/securial/sessions_controller.rb

@@ -0,0 +1,76 @@
+module Securial
+  class SessionsController < ApplicationController
+    skip_authentication! only: %i[login refresh]
+
+    before_action :set_session, only: %i[show revoke logout]
+
+    def index
+      @securial_sessions = Current.user.sessions
+    end
+
+    def show
+    end
+
+    def login
+      params.require([:email_address, :password])
+      if user = User.authenticate_by(params.permit([:email_address, :password]))
+        start_new_session_for user
+        render status: :created,
+               json: {
+                 access_token: create_jwt_for_current_session,
+                 refresh_token: Current.session.refresh_token,
+                 refresh_token_expires_at: Current.session.refresh_token_expires_at,
+               }
+      else
+        render status: :unauthorized,
+               json: {
+                 error: "Invalid email address or password.",
+                 fix: "Make sure to send the correct 'email_address' and 'password' in the payload",
+               }
+      end
+    end
+
+    def logout
+      @securial_session.revoke!
+      Current.session = nil
+      head :no_content
+    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
+          Current.session.refresh!
+          render status: :created,
+                 json: {
+                   access_token: create_jwt_for_current_session,
+                   refresh_token: Current.session.refresh_token,
+                   refresh_token_expires_at: Current.session.refresh_token_expires_at,
+                 }
+          return
+        end
+      end
+      render status: :unprocessable_entity, json: { error: "Invalid or expired token." }
+    end
+
+    def revoke
+      @securial_session.revoke!
+      Current.session = nil if @securial_session == Current.session
+      head :no_content
+    end
+
+    def revoke_all
+      Current.user.sessions.each(&:revoke!)
+      Current.session = nil
+      head :no_content
+    end
+
+    private
+
+    def set_session
+      id = params[:id]
+      @securial_session = id ? Current.user.sessions.find(params.expect(:id)) : Current.session
+    end
+  end
+end

data/app/controllers/securial/status_controller.rb

@@ -0,0 +1,9 @@
+module Securial
+  class StatusController < ApplicationController
+    skip_authentication!
+
+    def show
+      Securial::ENGINE_LOGGER.info("Status check initiated")
+    end
+  end
+end

data/app/controllers/securial/users_controller.rb

@@ -0,0 +1,53 @@
+module Securial
+  class UsersController < ApplicationController
+    before_action :set_securial_user, only: [:show, :update, :destroy]
+
+    def index
+      @securial_users = User.all
+    end
+
+    def show
+    end
+
+    def create
+      @securial_user = User.new(securial_user_params)
+
+      if @securial_user.save
+        render :show, status: :created, location: @securial_user
+      else
+        render json: @securial_user.errors, status: :unprocessable_entity
+      end
+    end
+
+    def update
+      if @securial_user.update(securial_user_params)
+        render :show, status: :ok, location: @securial_user
+      else
+        render json: @securial_user.errors, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      @securial_user.destroy!
+    end
+
+    private
+
+    def set_securial_user
+      @securial_user = User.find(params.expect(:id))
+    end
+
+    def securial_user_params
+      params.expect(securial_user: [
+                      :email_address,
+                      :password,
+                      :password_confirmation,
+                      :first_name,
+                      :last_name,
+                      :phone,
+                      :username,
+                      :bio
+                    ])
+    end
+  end
+end

data/app/jobs/securial/application_job.rb

@@ -0,0 +1,4 @@
+module Securial
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/securial/application_mailer.rb

@@ -0,0 +1,6 @@
+module Securial
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/mailers/securial/securial_mailer.rb

@@ -0,0 +1,17 @@
+module Securial
+  class SecurialMailer < ApplicationMailer
+    default from: Securial.configuration.mailer_sender
+
+    def reset_password(securial_user)
+      @user = securial_user
+      subject = reset_password_subject
+      mail subject: subject, to: securial_user.email_address
+    end
+
+    private
+
+    def reset_password_subject
+      Securial.configuration.password_reset_email_subject
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+module Securial
+  module PasswordResettable
+    extend ActiveSupport::Concern
+
+    included do
+      has_secure_password
+
+      validates :password,
+                length: {
+                  minimum: Securial.configuration.password_min_length,
+                  maximum: Securial.configuration.password_max_length,
+                },
+                format: {
+                  with: Securial.configuration.password_complexity,
+                  message: "must contain at least one uppercase letter, one lowercase letter, one digit, and one special character",
+                },
+                allow_nil: true
+
+      validates :password_confirmation,
+                presence: true,
+                if: -> { new_record? || !password.nil? }
+    end
+
+    def generate_reset_password_token!
+      update!(
+        reset_password_token: SecureRandom.urlsafe_base64,
+        reset_password_token_created_at: Time.current
+      )
+    end
+
+    def reset_password_token_valid?
+      return false if reset_password_token.blank? || reset_password_token_created_at.blank?
+
+      duration = Securial.configuration.reset_password_token_expires_in
+      return false unless duration.is_a?(ActiveSupport::Duration)
+
+      reset_password_token_created_at > duration.ago
+    end
+
+    def clear_reset_password_token!
+      update!(
+        reset_password_token: nil,
+        reset_password_token_created_at: nil
+      )
+    end
+  end
+end

data/app/models/securial/application_record.rb

@@ -0,0 +1,18 @@
+module Securial
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+
+    before_create :generate_uuid_v7
+
+    private
+
+    # Generates a UUIDv7 for the `id` field if it is blank.
+    # This method is triggered by the `before_create` callback.
+    # The generated ID is expected to be a UUIDv7 string.
+    def generate_uuid_v7
+      return if self.id.present? || self.class.type_for_attribute(:id).type != :string
+
+      self.id ||= Random.uuid_v7
+    end
+  end
+end

data/app/models/securial/current.rb

@@ -0,0 +1,6 @@
+module Securial
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :session
+    delegate :user, to: :session, allow_nil: true
+  end
+end

data/app/models/securial/role.rb

@@ -0,0 +1,10 @@
+module Securial
+  class Role < ApplicationRecord
+    normalizes :role_name, with: ->(e) { Securial::NormalizingHelper.normalize_role_name(e) }
+
+    validates :role_name, presence: true, uniqueness: { case_sensitive: false }
+
+    has_many :role_assignments, dependent: :destroy
+    has_many :users, through: :role_assignments
+  end
+end

data/app/models/securial/role_assignment.rb

@@ -0,0 +1,6 @@
+module Securial
+  class RoleAssignment < ApplicationRecord
+    belongs_to :user
+    belongs_to :role
+  end
+end