securial 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a67cb5167555d544a8787d5731542215aa5d43a50955cbb4a0a929d9df39ed08
-  data.tar.gz: 6ee38fc5624167b7cf6d9307dc07224e0762a163145df864247350c523b09a5a
+  metadata.gz: 1628d056fdb0a93bc954107766c8f5ed2975d4690c58dbdbe56a0d45e63eefa3
+  data.tar.gz: 166ce5d80dc63642239a0f6c26702e4bbca469c2f7d886d322aa07e119ef8928
 SHA512:
-  metadata.gz: a85b1cd94066087eab59f7c883e4b822a16e91e03a2df80e4100f7a81cc25712427d35719bb90dbf509c028081bbd215436d097e2056e054e13433fc1b97d9ef
-  data.tar.gz: a39f8dfd001c239fc2f5612e9777f587d688c93de8070656fe7e8fa38a3610463ce18502bef35b12d75c45eb9ee5f27608f8a25d2dc00aa9394f2f8dd5a7bc38
+  metadata.gz: 997ba8dc253bf3772ef806e9c81cce2fb7a7b0dd263527f0896badf74e5ea09ab5560ca804162cde01441054ac5b5d0fca9c39dfc2607cf18086ec6bb4667af2
+  data.tar.gz: b7ff4072c37645e9dc6f1bd5551bb47ec829cbefd412221bcdf13e5a2e788450243c1e7853e918248a2b1faaea61aec40122ddea32f1ef80a1ae013367d9d349

data/README.md

@@ -1,6 +1,3 @@
-![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)
@@ -10,6 +7,16 @@
 [![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)
 
+> [!WARNING]
+>
+> **Securial is currently in active development (major version zero).**
+>
+> While the gem is functional and versioned, it is not yet considered stable. Until v1.0.0 is released, any updates may introduce breaking changes as the API and features continue to evolve. If you plan to use Securial in production, please do so with caution and pin a specific version.
+>
+> You can track the roadmap and remaining tasks for the v1.0.0 release in [this GitHub issue](https://github.com/AlyBadawy/Securial/issues/64).
+
+---
+
 **Securial** is a mountable Rails engine that provides robust, extensible authentication and access control for Rails applications. It supports:
 
 - ✅ JWT-based authentication
@@ -20,33 +27,13 @@
 - ✅ Database-agnostic support
 
 
-### 🚀 Why Choose Securial?
-
-Securial isn't just another auth library — it's designed to give you control, flexibility, and peace of mind when building secure Rails APIs.
+### 🚀 Why Securial?
 
-**🔧 Built for Developers**  
-- Easy to mount and extend using familiar Rails conventions.  
-- Fully customizable controllers, serializers, and logic — no more black-box auth.
+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.
 
-**🧩 Modular by Design**  
-- Use only the components you need: JWT, sessions, API tokens — or all of them together.  
-- Clean separation of concerns makes testing and debugging simpler.
+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.
 
-**⚡ API-First Approach**  
-- JSON-only responses make Securial ideal for frontend frameworks and mobile apps.  
-- No HTML views or form helpers — just clean endpoints that work out of the box.
 
-**🛡️ Secure by Default**  
-- Uses industry best practices for token management and access control.  
-- No reliance on client-side sessions or cookies.
-
-**📦 Lightweight, Database-Agnostic**  
-- No assumptions about your schema or ORM — works with any relational database.  
-- Minimal dependencies, fast to integrate.
-
-**🌱 Ready to Grow With You**  
-- Start small with basic JWT auth, scale to multi-token API clients, admin scopes, or full RBAC.  
-- Perfect for startups, side projects, and production APIs alike.
 
 ## 🚀 Installation
 
@@ -133,3 +120,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/alybad
 ## ⚖️ 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).
+
+---
+
+![image](https://github.com/user-attachments/assets/d7cb9645-c28e-4cca-9c1b-5085a91c11d4)

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

@@ -32,9 +32,9 @@ module Securial
       if auth_header.present? && auth_header.start_with?("Bearer ")
         token = auth_header.split(" ").last
         begin
-          decoded_token = Securial::Sessions::SessionEncoder.decode(token)
+          decoded_token = Securial::Auth::AuthEncoder.decode(token)
           Current.session = Session.find_by!(id: decoded_token["jti"], revoked: false)
-        rescue Securial::Sessions::Errors::SessionDecodeError, ActiveRecord::RecordNotFound => e
+        rescue Securial::Auth::Errors::AuthDecodeError, ActiveRecord::RecordNotFound => e
           render status: :unauthorized, json: { error: "Invalid token: #{e.message}" } and return
         end
       else
@@ -43,19 +43,11 @@ module Securial
     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
+      Securial::Auth::SessionCreator.create_session(user, request)
     end
 
     def create_jwt_for_current_session
-      Securial::Sessions::SessionEncoder.encode(Current.session)
+      Securial::Auth::AuthEncoder.encode(Current.session)
     end
 
     def internal_rails_request?

data/app/controllers/securial/sessions_controller.rb

@@ -14,18 +14,12 @@ module Securial
     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,
-               }
+        render_login_response(user)
       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",
+                 instructions: "Make sure to send the correct 'email_address' and 'password' in the payload",
                }
       end
     end
@@ -72,5 +66,23 @@ module Securial
       id = params[:id]
       @securial_session = id ? Current.user.sessions.find(params.expect(:id)) : Current.session
     end
+
+    def render_login_response(user)
+      if user.password_expired?
+        render status: :forbidden,
+               json: {
+                 error: "Password expired",
+                 instructions: "Please reset your password before logging in.",
+               }
+      else
+        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,
+               }
+      end
+    end
   end
 end

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

@@ -5,6 +5,8 @@ module Securial
     included do
       has_secure_password
 
+      before_save :update_password_changed_at, if: :will_save_change_to_password_digest?
+
       validates :password,
                 length: {
                   minimum: Securial.configuration.password_min_length,
@@ -43,5 +45,18 @@ module Securial
         reset_password_token_created_at: nil
       )
     end
+
+    def password_expired?
+      return false unless Securial.configuration.password_expires
+      return true unless password_changed_at
+
+      password_changed_at < Securial.configuration.password_expires_in.ago
+    end
+
+    private
+
+    def update_password_changed_at
+      self.password_changed_at = Time.current
+    end
   end
 end

data/app/models/securial/session.rb

@@ -15,8 +15,8 @@ module Securial
     end
 
     def refresh!
-      raise Securial::Sessions::Errors::SessionRevokedError, "Session is revoked" if revoked
-      raise Securial::Sessions::Errors::SessionExpiredError, "Session is expired" if refresh_token_expires_at < Time.current
+      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
 
       update!(refresh_token: SecureRandom.hex(64),
               refresh_count: self.refresh_count + 1,

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

@@ -6,6 +6,8 @@ json.phone securial_user.phone
 json.username securial_user.username
 json.bio securial_user.bio
 
+json.password_expired securial_user.password_expired?
+
 json.roles securial_user.roles, partial: "securial/roles/securial_role", as: :securial_role
 
 json.partial! "securial/shared/timestamps", record: securial_user

data/config/routes.rb

@@ -28,7 +28,6 @@ Securial::Engine.routes.draw do
       post "login", to: "sessions#login", as: :login
       delete "logout", to: "sessions#logout", as: :logout
       put "refresh", to: "sessions#refresh", as: :refresh_session
-      delete "revoke", to: "sessions#revoke", as: :revoke_current_session
       delete "id/:id/revoke", to: "sessions#revoke", as: :revoke_session_by_id
       delete "revoke_all", to: "sessions#revoke_all", as: :revoke_all_sessions
     end

data/db/migrate/20250517155521_create_securial_users.rb

@@ -1,13 +1,16 @@
 class CreateSecurialUsers < ActiveRecord::Migration[8.0]
   def change
     create_table :securial_users, id: :string do |t|
-      t.string :email_address
-      t.string :password_digest
-      t.string :first_name
-      t.string :last_name
-      t.string :phone
-      t.string :username
-      t.string :bio
+      t.string    :email_address
+      t.string    :first_name
+      t.string    :last_name
+      t.string    :phone
+      t.string    :username
+      t.string    :bio
+      t.string    :password_digest
+      t.string    :reset_password_token
+      t.datetime  :reset_password_token_created_at
+      t.datetime  :password_changed_at
 
       t.timestamps
     end

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

@@ -14,7 +14,7 @@ Securial.configure do |config|
   config.log_file_level = :info
 
   # Set log level for stdout logger
-  config.log_stdout_level = :info
+  config.log_stdout_level = :debug
 
   ##### User Roles
   ## Set the role for admin users
@@ -26,7 +26,7 @@ Securial.configure do |config|
   # in the `/securial/superusers` namespace.
   config.admin_role = :admin
 
-  #### Session Configuration
+  ##### Session Configuration
   ## Set the session expiration duration
   # This is the time after which a session will be considered expired.
   # After this time, the session will be invalidated and the user
@@ -35,14 +35,6 @@ Securial.configure do |config|
   # The default is 3 minutes.
   config.session_expiration_duration = 3.minutes
 
-  ## Set the session renewal duration
-  # This is the time after which a session will be renewed.
-  # After this time, the session will be renewed and the expiration
-  # time will be extended. This is useful for keeping users logged in
-  # without requiring them to log in again. The renewal time is set
-  # in seconds, minutes, or hours. The default is 3 days.
-  config.session_renewal_duration = 3.days
-
   ## Set the session secret
   # This secret is used to sign the session tokens and ensure
   # that they cannot be tampered with. It is important to keep this
@@ -56,7 +48,7 @@ Securial.configure do |config|
   # Other options include :hs256, :hs384, and :hs512
   config.session_algorithm = :hs256
 
-  #### Securial Mailer Configuration
+  ##### Securial Mailer Configuration
   ## Set the mailer sender address
   # This is the email address that will be used as the sender
   # for all emails sent by the Securial engine. This includes
@@ -64,7 +56,7 @@ Securial.configure do |config|
   # notifications.
   config.mailer_sender = "no-reply@example.com"
 
-  #### Password configuration
+  ##### Password configuration
   ## 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".
@@ -107,7 +99,7 @@ Securial.configure do |config|
   # secret secure and not share it with anyone.
   config.reset_password_token_secret = "reset_secret"
 
-  ### Timestamp Configuration
+  ##### Timestamp Configuration
   ## Set whether to use timestamps in the json responses.
   # The options are:
   # :none - no timestamps will be included in the json responses.
@@ -117,4 +109,42 @@ Securial.configure do |config|
   # :all - the created_at and updated_at timestamps will be included
   #   for all users. This is useful for debugging and development purposes.
   config.timestamps_in_response = Rails.env.production? ? :admins_only : :all
+
+  ##### Response Configuration
+  ## Set the format of the JSON keys in the responses.
+  # The options are:
+  # :snake_case - the keys will be in snake_case format.
+  # :lowerCamelCase - the keys will be in lowerCamelCase format.
+  # :upperCamelCase - the keys will be in UpperCamelCase format.
+  config.response_keys_format = :snake_case
+
+  ##### Security Configuration
+  ## Set the security headers to be included in the responses.
+  # Read more about security headers here: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers or in the gem documentation.
+  # The options are:
+  # :default - the default security headers will be included.
+  # :strict - the strict security headers will be included.
+  config.security_headers = :strict
+  ## set whether to enable request rate limiting
+  # This is useful for preventing abuse and denial of service attacks.
+  config.rate_limiting_enabled = true
+  ## Set the rate limit for requests
+  # This is the maximum number of requests that a user can make
+  # in a given time period. The default is 60 requests per minute.
+  # This is only applied if `rate_limiting_enabled` is set to true.
+  config.rate_limit_requests_per_minute = 60
+  ## Set the rate limit response status code
+  # This is the status code that will be returned when a user exceeds
+  # the rate limit. The status code should be a 4xx or 5xx code
+  # to indicate an error. Commonly used codes are 429 Too Many Requests
+  # or 503 Service Unavailable. The default is 429 Too Many Requests.
+  # This is only applied if `rate_limiting_enabled` is set to true.
+  config.rate_limit_response_status = 429
+  ## Set the rate limit response message
+  # This is the message that will be returned when a user exceeds
+  # the rate limit. The default is "Too many requests, please try again later."
+  # This is only applied if `rate_limiting_enabled` is set to true.
+  config.rate_limit_response_message = "Too many requests, please try again later."
+
+
 end

data/lib/generators/securial/install/views_generastor.rb

@@ -0,0 +1,25 @@
+require "rails/generators"
+require "rake"
+
+module Securial
+  module Generators
+    module Install
+      class ViewsGenerator < Rails::Generators::Base
+        source_root Securial::Engine.root.join("app", "views", "securial").to_s
+        desc "Copies Securial model-related views to your application for customization."
+
+        def copy_model_views
+          Dir.glob(File.join(self.class.source_root, "**/*")).each do |path|
+            relative_path = Pathname.new(path).relative_path_from(Pathname.new(self.class.source_root))
+
+            if File.directory?(path)
+              empty_directory "app/views/securial/#{relative_path}"
+            else
+              copy_file path, "app/views/securial/#{relative_path}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/securial/auth/_index.rb

@@ -0,0 +1,3 @@
+require_relative "errors"
+require_relative "auth_encoder"
+require_relative "session_creator"

data/lib/securial/{sessions/session_encoder.rb → auth/auth_encoder.rb}

@@ -1,6 +1,6 @@
 module Securial
-  module Sessions
-    module SessionEncoder
+  module Auth
+    module AuthEncoder
       class << self
         def encode(session)
           return nil unless session && session.class == Securial::Session
@@ -21,7 +21,7 @@ module Securial
           begin
             JWT.encode(payload, secret, algorithm, { kid: "hmac" })
           rescue JWT::EncodeError => e
-            raise Errors::SessionEncodeError, "Failed to encode session: #{e.message}"
+            raise Errors::AuthEncodeError, "Failed to encode session: #{e.message}"
           end
         end
 
@@ -29,7 +29,7 @@ module Securial
           begin
           decoded = JWT.decode(token, secret, true, { algorithm: algorithm, verify_jti: true, iss: "securial" })
           rescue JWT::DecodeError => e
-            raise Securial::Sessions::Errors::SessionDecodeError, "Failed to decode session token: #{e.message}"
+            raise Securial::Auth::Errors::AuthDecodeError, "Failed to decode session token: #{e.message}"
           end
           decoded.first
         end

data/lib/securial/auth/errors.rb

@@ -0,0 +1,15 @@
+module Securial
+  module Auth
+    module Errors
+      class BaseAuthError < StandardError
+        def backtrace; []; end
+      end
+
+      class AuthEncodeError < BaseAuthError; end
+      class AuthDecodeError < BaseAuthError; end
+
+      class AuthRevokedError < BaseAuthError; end
+      class AuthExpiredError < BaseAuthError; end
+    end
+  end
+end

data/lib/securial/auth/session_creator.rb

@@ -0,0 +1,21 @@
+module Securial
+  module Auth
+    module SessionCreator
+      class << self
+        def create_session(user, request)
+          return nil unless user && user.persisted? && request.is_a?(ActionDispatch::Request)
+
+          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
+      end
+    end
+  end
+end

data/lib/securial/config/configuration.rb

@@ -1,41 +1,61 @@
+require_relative "../helpers/_index"
 module Securial
   module Config
     VALID_SESSION_ENCRYPTION_ALGORITHMS = [:hs256, :hs384, :hs512].freeze
     VALID_TIMESTAMP_OPTIONS = [:all, :admins_only, :none].freeze
+    VALID_RESPONSE_KEYS_FORMATS = [:snake_case, :lowerCamelCase, :UpperCamelCase].freeze
+    VALID_SECURITY_HEADERS = [:strict, :default, :none].freeze
 
     class Configuration
-      attr_accessor :log_to_file, :log_to_stdout
-      attr_accessor :log_file_level, :log_stdout_level
-      attr_accessor :admin_role
-      attr_accessor :session_expiration_duration
-      attr_accessor :session_secret, :session_algorithm
-      attr_accessor :mailer_sender
-      attr_accessor :password_reset_email_subject
-      attr_accessor :password_min_length, :password_max_length
-      attr_accessor :password_complexity
-      attr_accessor :password_expires_in
-      attr_accessor :reset_password_token_expires_in
-      attr_accessor :reset_password_token_secret
-      attr_accessor :timestamps_in_response
+      def self.config_attributes # rubocop:disable Metrics/MethodLength
+        {
+          log_to_file: !Rails.env.test?,
+          log_to_stdout: !Rails.env.test?,
+          log_file_level: :info,
+          log_stdout_level: :debug,
+          admin_role: :admin,
+          session_expiration_duration: 3.minutes,
+          session_secret: "secret",
+          session_algorithm: :hs256,
+          mailer_sender: "no-reply@example.com",
+          password_reset_email_subject: "SECURIAL: Password Reset Instructions",
+          password_min_length: 8,
+          password_max_length: 128,
+          password_complexity: Securial::RegexHelper::PASSWORD_REGEX,
+          password_expires: true,
+          password_expires_in: 90.days,
+          reset_password_token_expires_in: 2.hours,
+          reset_password_token_secret: "reset_secret",
+          timestamps_in_response: :all,
+          response_keys_format: :snake_case,
+          security_headers: :strict,
+          rate_limiting_enabled: true,
+          rate_limit_requests_per_minute: 60,
+          rate_limit_response_status: 429,
+          rate_limit_response_message: "Too many requests, please try again later.",
+        }
+      end
 
       def initialize
-        @log_to_file = !Rails.env.test?
-        @log_to_stdout = !Rails.env.test?
-        @log_file_level = :info
-        @log_stdout_level = :info
-        @admin_role = :admin
-        @session_expiration_duration = 3.minutes
-        @session_secret = "secret"
-        @session_algorithm = :hs256
-        @mailer_sender = "no-reply@example.com"
-        @password_reset_email_subject = "SECURIAL: Password Reset Instructions"
-        @password_min_length = 8
-        @password_max_length = 128
-        @password_complexity = Securial::RegexHelper::PASSWORD_REGEX
-        @password_expires_in = 90.days
-        @reset_password_token_expires_in = 2.hours
-        @reset_password_token_secret = "reset_secret"
-        @timestamps_in_response = :all
+        self.class.config_attributes.each do |attr, default|
+          instance_variable_set("@#{attr}", default)
+        end
+        validate!
+      end
+
+      config_attributes.each_key do |attr|
+        define_method(attr) { instance_variable_get("@#{attr}") }
+
+        define_method("#{attr}=") do |value|
+          instance_variable_set("@#{attr}", value)
+          validate!
+        end
+      end
+
+      private
+
+      def validate!
+        Securial::Config::Validation.validate_all!(self)
       end
     end
   end

data/lib/securial/config/errors.rb

@@ -13,7 +13,8 @@ module Securial
 
       class ConfigMailerSenderError < BaseConfigError; end
       class ConfigPasswordError < BaseConfigError; end
-      class ConfigTimestampsInResponseError < BaseConfigError; end
+      class ConfigResponseError < BaseConfigError; end
+      class ConfigSecurityError < BaseConfigError; end
     end
   end
 end