securial 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 166aa60d38c7fecac2ec442467982af0fb09a7521aa12233b5a57a459aeba328
-  data.tar.gz: b4a27ad795aef20268a7912c0efc4df11c1cf58b62bf5d8814ee583c549f6f35
+  metadata.gz: 9f93334f493089fe07b825a71ccbe4c8eb2b3ae9b924e2e7cab16f4818d0bb4a
+  data.tar.gz: 47e73ee83002a71737e3d7e16c31fe428652ddb9a6d4104eb2d622b9bc9dc666
 SHA512:
-  metadata.gz: 3b5e7ebd0df4540a6814df63530ce6af969120ce50a34dbc5e6157103fd14108fcf19dffee65d318e5d31ee9851e3385a3d0069bd96cd3c8124dbd73f2e6db58
-  data.tar.gz: 00ac53e81274914b952e609ab57f777c9a4128520cbfff5044caad442f49ef2b89efeb84e6bec09d0f14e127a141b3ce53e9a352ab29082b68b3aee2a50a14f4
+  metadata.gz: 3108d25afcf5df41d3f7578b12fdb496402deb3ba7ce9e8485ed90e96e3d71dd7d4297c67dd49911d73ffd2a31100845e792e5e1670d3a35cbe877bad8066ba6
+  data.tar.gz: 1c403ba8a424348b2ac80c0a46c7cc71e9e720bff838a735caac6d263884c3eab06480917d3bff8c8f7a7ed295bc4ecac1e5cf53caf609c361aa2a5159533e0e

data/.yardopts

@@ -0,0 +1,4 @@
+--private
+--title "Securial Gem Documentation"
+--exclude
+lib/generators/factory_bot/model/model_generator.rb

data/README.md

@@ -1,4 +1,4 @@
-# Securial
+# Securial Gem
 
 [![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)
@@ -8,19 +8,22 @@
 [![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)
 
+[![Documentation](https://img.shields.io/badge/yard-Documentation-blue?style=flat&logo=readthedocs&logoColor=%238CA1AF&label=yard&link=https%3A%2F%2Fwww.rubydoc.info%2Fgems%2Fsecurial%2Findex)](https://alybadawy.github.io/Securial/_index.html)
+
 ---
 
+## Overview
+
 ### 🛡️ What is Securial?
 
 **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
-- 🟦 Simple user management with roles
-- 🟦 Database-agnostic support
+- 🔑 JWT-based authentication
+- ↪️ API session tokens, with refresh tokens
+- 🤳 Simple integration with web and mobile apps
+- 🧹 Clean, JSON-based API responses
+- 🧍 User management with roles
+- 🫙 Database-agnostic support
 
 ### 👀 Why Securial?
 
@@ -34,12 +37,13 @@ Securial can be installed on an existing Rails application or use the `securial
 
 ### Installation on an existing Rails app:
 
-To add Securial to an existing Rails app:
+Add Securial to an existing Rails app is as simple as 1..2..3:
 
 - Add `gem "securial"` to your GemFile
 - Run `bundle install`
 - Run `rails generate securial:install`
 - Mount the Securial engine in your Rails application `config/routes.rb` file:
+
   ```ruby
   Rails.application.routes.draw do
     mount Securial::Engine => "/securial"
@@ -47,6 +51,7 @@ To add Securial to an existing Rails app:
     # The rest of your routes
   end
   ```
+
 - Run the migrations by running the command: `rails db:migrate`
 
 💡 Full installation steps are available in the [Wiki › Installation](https://github.com/AlyBadawy/Securial/wiki/Installation).

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

@@ -1,4 +1,10 @@
 module Securial
+  # Identity Concern
+  #
+  # Provides authentication and user identification functionality for controllers.
+  # This concern adds before_action hooks for user identification and authentication,
+  # and provides helper methods for accessing the current user and enforcing authentication.
+  #
   module Identity
     extend ActiveSupport::Concern
 
@@ -8,6 +14,41 @@ module Securial
       helper_method :current_user if respond_to?(:helper_method)
     end
 
+    # @!method skip_authentication!(options = {})
+    # Skips authentication for specified controller actions, making them publicly accessible.
+    #
+    # This class method allows you to bypass the `authenticate_user!` before_action
+    # that is applied by default to all controller actions when including the Identity concern.
+    # It's useful for endpoints that should be publicly accessible, such as landing pages,
+    # password reset, login, or registration.
+    #
+    # @param [Hash] options Options to pass to skip_before_action
+    # @option options [Symbol, Array<Symbol>] :only Specific action(s) to skip authentication for
+    # @option options [Symbol, Array<Symbol>] :except Action(s) to exclude from skipping
+    #
+    # @example Skip authentication for login and registration actions
+    #   class SessionsController < ApplicationController
+    #     include Securial::Identity
+    #
+    #     skip_authentication! only: [:new, :create]
+    #
+    #     def new
+    #       # Login form action
+    #     end
+    #
+    #     def create
+    #       # Authentication logic
+    #     end
+    #   end
+    #
+    # @example Skip authentication for all actions except protected ones
+    #   class PublicController < ApplicationController
+    #     include Securial::Identity
+    #
+    #     skip_authentication! except: [:dashboard, :account]
+    #   end
+    #
+    # @return [void]
     class_methods do
       def skip_authentication!(**options)
         skip_before_action :authenticate_user!, **options
@@ -15,15 +56,34 @@ module Securial
     end
 
 
+    # Returns the currently authenticated user or nil if no user is authenticated.
+    #
+    # This method provides access to the current user object from the session
+    # tracked in Current.session.
+    #
+    # @return [Securial::User, nil] The current authenticated user or nil
+    #
     def current_user
       Current.session&.user
     end
 
+    # Ensures the current user has admin privileges.
+    #
+    # This method checks if a user is authenticated and has admin privileges.
+    # If the user is not an admin, it renders a forbidden response.
+    # If no user is authenticated, it calls authenticate_user! to handle the unauthorized case.
+    #
+    # @return [void]
+    #
     def authenticate_admin!
       if current_user
         return if current_user.is_admin?
 
-        render status: :forbidden, json: { error: "You are not authorized to perform this action" }
+        render status: :forbidden,
+               json: {
+                errors: ["You are not authorized to perform this action"],
+                instructions: "Please contact an administrator if you believe this is an error.",
+              }
       else
         authenticate_user!
       end
@@ -31,6 +91,18 @@ module Securial
 
     private
 
+    # Identifies the current user from the Authorization header.
+    #
+    # This method attempts to identify the user by:
+    # 1. Checking for a valid Bearer token in the Authorization header
+    # 2. Decoding the token to extract the session ID
+    # 3. Finding and validating the corresponding session
+    # 4. Ensuring IP address and user agent match for security
+    #
+    # If identification succeeds, the session is stored in Current.session
+    #
+    # @return [void]
+    #
     def identify_user
       return if internal_rails_request?
 
@@ -53,13 +125,30 @@ module Securial
       end
     end
 
+    # Ensures a user is authenticated before proceeding.
+    #
+    # This method checks if a user has been successfully identified.
+    # If not, it renders an unauthorized response and halts the request.
+    # Internal Rails requests are exempt from authentication requirements.
+    #
+    # @return [void]
     def authenticate_user!
       return if internal_rails_request?
       return if Current.session&.user
 
-      render status: :unauthorized, json: { error: "You are not signed in" } and return
+      render status: :unauthorized,
+             json: {
+               errors: ["You are not signed in"],
+               instructions: "Please sign in to access this resource.",
+               } and return
     end
 
+    # Determines if the current request is from internal Rails controllers.
+    #
+    # This method checks if the current controller is one of Rails' internal
+    # controllers (Info, Mailers, Welcome) which should bypass authentication.
+    #
+    # @return [Boolean] true if the request is from internal Rails controllers, false otherwise
     def internal_rails_request?
       defined?(Rails::InfoController) && is_a?(Rails::InfoController) ||
       defined?(Rails::MailersController) && is_a?(Rails::MailersController) ||

data/app/controllers/securial/accounts_controller.rb

@@ -1,59 +1,122 @@
 module Securial
+  #
+  # AccountsController
+  #
+  # This controller handles user account-related operations including:
+  #   - User registration
+  #   - Profile viewing and management
+  #   - Account updates
+  #   - Account deletion
+  #
+  # Routes typically mounted at Securial/accounts/* in the host application.
+  #
   class AccountsController < ApplicationController
+    # Retrieves the current user's profile.
+    #
+    # Provides the authenticated user's complete profile information.
+    # Requires authentication via the Identity concern.
+    #
+    # @return [void] Renders user profile with 200 OK status
     def me
       @securial_user = Current.user
 
       render :show, status: :ok, location: @securial_user
     end
 
+    # Shows a specific user's profile by username.
+    #
+    # Retrieves and displays public profile information for the requested user.
+    #
+    # @param [String] params[:username] The username of the requested user profile
+    # @return [void] Renders user profile with 200 OK status or 404 if not found
     def show
       @securial_user = Securial::User.find_by(username: params.expect(:username))
       render_user_profile
     end
 
+    # Registers a new user account.
+    #
+    # Creates a new user in the system with the provided registration information.
+    #
+    # @param [Hash] params[:securial_user] User attributes including email_address, password, etc.
+    # @return [void] Renders new user with 201 Created status or errors with 422
     def register
       @securial_user = Securial::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
+        render json: {
+          errors: @securial_user.errors.full_messages }, status: :unprocessable_entity
       end
     end
 
+    # Updates the current user's profile information.
+    #
+    # Allows users to modify their profile after authenticating with their current password.
+    #
+    # @param [String] current_password User's current password for verification
+    # @param [Hash] params[:securial_user] Updated user attributes
+    # @return [void] Renders updated user with 200 OK status or errors with 422
     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
+          render json: {
+            errors: @securial_user.errors.full_messages,
+            instructions: "Please ensure all required fields are filled out correctly.",
+            }, status: :unprocessable_entity
         end
       else
-        render json: { error: "Current password is incorrect" }, status: :unprocessable_entity
+        render json: {
+          errors: ["Current password is incorrect"],
+          instructions: "Please verify your current password and try again.",
+          }, status: :unprocessable_entity
       end
     end
 
+    # Permanently deletes the current user's account.
+    #
+    # Removes the user account and all associated data after password verification.
+    #
+    # @param [String] params[:current_password] User's current password for verification
+    # @return [void] Renders success message with 200 OK status or error with 422
     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
+        render json: {
+          errors: ["Current password is incorrect"],
+          instructions: "Please verify your current password and try again.",
+        }, status: :unprocessable_entity
       end
     end
 
     private
 
+    # Permits and extracts user parameters from the request.
+    #
+    # @return [ActionController::Parameters] Permitted user parameters
+    #
     def user_params
       params.expect(securial_user: [:email_address, :password, :password_confirmation, :first_name, :last_name, :phone, :username, :bio])
     end
 
+    # Renders the user profile or a not found response.
+    #
+    # @return [void] Renders user profile or not found error
+    #
     def render_user_profile
       if @securial_user
         render :show, status: :ok, location: @securial_user
       else
-        render json: { error: "User not found" }, status: :not_found
+        render json: {
+          errors: ["User not found"],
+          instructions: "Please check the username and try again.",
+        }, status: :not_found
       end
     end
   end

data/app/controllers/securial/application_controller.rb

@@ -1,4 +1,16 @@
 module Securial
+  #
+  # ApplicationController
+  #
+  # This is the base controller for the Securial engine, inheriting from ActionController::API.
+  # and provides common functionality for all Securial controllers, including:
+  #   - Custom view path configuration
+  #   - Common exception handling for API responses
+  #   - Standardized error rendering
+  #
+  # All other controllers in the Securial engine inherit from this controller
+  # to ensure consistent behavior across the API.
+  #
   class ApplicationController < ActionController::API
     prepend_view_path Securial::Engine.root.join("app", "views")
 
@@ -7,12 +19,32 @@ module Securial
 
     private
 
+    # Renders a standardized 404 Not Found JSON response.
+    #
+    # Called automatically when an ActiveRecord::RecordNotFound exception is raised,
+    # ensuring consistent error responses across the API.
+    #
+    # @param [ActiveRecord::RecordNotFound] exception The exception raised when a record is not found
+    # @return [void]
     def render_404
-      render status: :not_found, json: { error: "Record not found" }
+      render status: :not_found, json: {
+        errors: ["Record not found"],
+        instructions: "Please check the requested resource and try again.",
+      }
     end
 
+    # Renders a standardized 400 Bad Request JSON response.
+    #
+    # Called automatically when an ActionController::ParameterMissing exception is raised,
+    # providing the client with information about the missing parameter.
+    #
+    # @param [ActionController::ParameterMissing] exception The exception raised for missing parameters
+    # @return [void]
     def render_400(exception)
-      render status: :bad_request, json: { error: exception.message }
+      render status: :bad_request, json: {
+        errors: [exception.message],
+        instructions: "Please ensure all required parameters are provided and formatted correctly.",
+       }
     end
   end
 end

data/app/controllers/securial/passwords_controller.rb

@@ -1,8 +1,30 @@
 module Securial
+  #
+  # PasswordsController
+  #
+  # Controller for managing user password operations in the Securial authentication system.
+  #
+  # This controller handles password-related operations including:
+  #   - Forgot password functionality
+  #   - Password reset with secure tokens
+  #
+  # All actions in this controller skip standard authentication requirements to allow
+  # unauthenticated users to recover their accounts.
+  #
+  # Routes typically mounted at Securial/password/* in the host application.
+  #
   class PasswordsController < ApplicationController
     skip_authentication!
     before_action :set_user_by_password_token, only: %i[ reset_password ]
 
+    # Initiates the password reset process for a user.
+    #
+    # Looks up a user by email address and, if found, generates a secure reset token
+    # and sends password reset instructions via email. To prevent user enumeration attacks,
+    # returns the same success response regardless of whether the email exists.
+    #
+    # @param [String] params[:email_address] The email address of the user requesting password reset
+    # @return [void] Renders success message with 200 OK status
     def forgot_password
       if user = User.find_by(email_address: params.require(:email_address))
         user.generate_reset_password_token!
@@ -12,6 +34,15 @@ module Securial
       render status: :ok, json: { message: "Password reset instructions sent (if user with that email address exists)." }
     end
 
+    # Resets a user's password using a valid reset token.
+    #
+    # Validates the provided token, clears it to prevent reuse, and updates
+    # the user's password if the new password is valid.
+    #
+    # @param [String] params[:token] The password reset token from the email
+    # @param [String] params[:password] The new password
+    # @param [String] params[:password_confirmation] Confirmation of the new password
+    # @return [void] Renders success message with 200 OK status or errors with 422
     def reset_password
       @user.clear_reset_password_token!
       if @user.update(params.permit(:password, :password_confirmation))
@@ -23,13 +54,22 @@ module Securial
 
     private
 
+    # Locates and validates a user by their password reset token.
+    #
+    # Sets @user instance variable if the token is valid and not expired.
+    # Renders an error response if the token is invalid or expired.
+    #
+    # @param [String] params[:token] The password reset token to validate
+    # @return [void]
     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?
+      begin
+        @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" } } and return
+        end
+      rescue ActiveSupport::MessageVerifier::InvalidSignature, ActiveRecord::RecordNotFound
         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
     end
   end
 end

data/app/controllers/securial/role_assignments_controller.rb

@@ -1,10 +1,35 @@
 module Securial
+  #
+  # RoleAssignmentsController
+  #
+  # Controller for managing role assignments in the Securial authorization system.
+  #
+  # This controller handles role management operations including:
+  #   - Assigning roles to users
+  #   - Removing roles from users
+  #
+  # All operations require admin authentication and are typically used for
+  # user permission management within the application.
+  #
+  # Routes typically mounted at Securial/admins/role_assignments/* in the host application.
+  #
   class RoleAssignmentsController < ApplicationController
+    # Assigns a role to a user.
+    #
+    # Creates a new role assignment between the specified user and role.
+    # Validates that the assignment doesn't already exist.
+    #
+    # @param [Integer] params[:user_id] The ID of the user to assign the role to
+    # @param [Integer] params[:role_id] The ID of the role to be assigned
+    # @return [void] Renders the created assignment with 201 Created status or errors with 422
     def create
       return unless define_user_and_role
 
       if @securial_user.roles.exists?(@securial_role.id)
-        render json: { error: "Role already assigned to user" }, status: :unprocessable_entity
+        render json: {
+          errors: ["Role already assigned to user"],
+          instructions: "Please check the user's current roles before assigning a new one.",
+          }, status: :unprocessable_entity
         return
       end
       @securial_role_assignment = RoleAssignment.new(securial_role_assignment_params)
@@ -12,6 +37,14 @@ module Securial
       render :show, status: :created
     end
 
+    # Removes a role from a user.
+    #
+    # Deletes an existing role assignment between the specified user and role.
+    # Validates that the assignment exists before attempting deletion.
+    #
+    # @param [Integer] params[:user_id] The ID of the user to remove the role from
+    # @param [Integer] params[:role_id] The ID of the role to be removed
+    # @return [void] Renders the deleted assignment with 200 OK status or errors with 422
     def destroy
       return unless define_user_and_role
       @role_assignment = RoleAssignment.find_by(securial_role_assignment_params)
@@ -19,27 +52,45 @@ module Securial
         @role_assignment.destroy!
         render :show, status: :ok
       else
-        render json: { error: "Role is not assigned to user" }, status: :unprocessable_entity
+        render json: {
+          errors: ["Role is not assigned to user"],
+          instructions: "Please check the user's current roles before attempting to remove a role.",
+          }, status: :unprocessable_entity
       end
     end
 
     private
 
+    # Looks up and validates the existence of both the user and role.
+    #
+    # Sets @securial_user and @securial_role instance variables if both exist.
+    # Renders error responses if either cannot be found.
+    #
+    # @return [Boolean] true if both user and role were found, false otherwise
     def define_user_and_role
       @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
+        render json: {
+          errors: ["User not found"],
+          instructions: "Please check the user ID and try again.",
+          }, status: :unprocessable_entity
         return false
       end
       if @securial_role.nil?
-        render json: { error: "Role not found" }, status: :unprocessable_entity
+        render json: {
+          errors: ["Role not found"],
+          instructions: "Please check the role ID and try again.",
+        }, status: :unprocessable_entity
         return false
       end
 
       true
     end
 
+    # Permits and extracts role assignment parameters from the request.
+    #
+    # @return [ActionController::Parameters] Permitted role assignment parameters
     def securial_role_assignment_params
       params.expect(securial_role_assignment: [:user_id, :role_id])
     end

data/app/controllers/securial/roles_controller.rb

@@ -1,14 +1,47 @@
 module Securial
+  #
+  # RolesController
+  #
+  # Controller for managing roles in the Securial authorization system.
+  #
+  # This controller handles role management operations including:
+  #   - Creating new roles
+  #   - Listing available roles
+  #   - Updating role properties
+  #   - Deleting roles
+  #
+  # All operations require admin authentication and are typically used for
+  # setting up and managing the application's permission structure.
+  #
+  # Routes typically mounted at Securial/admins/roles/* in the host application.
+  #
   class RolesController < ApplicationController
     before_action :set_securial_role, only: [:show, :update, :destroy]
 
+    # Lists all roles in the system.
+    #
+    # Retrieves all roles for administrative display and management.
+    #
+    # @return [void] Renders index view with all roles
     def index
       @securial_roles = Role.all
     end
 
+    # Shows details for a specific role.
+    #
+    # Retrieves and displays information for a single role.
+    #
+    # @param [Integer] params[:id] The ID of the role to display
+    # @return [void] Renders show view with the specified role
     def show
     end
 
+    # Creates a new role in the system.
+    #
+    # Adds a new role with the provided attributes.
+    #
+    # @param [Hash] params[:securial_role] Role attributes including role_name and hide_from_profile
+    # @return [void] Renders the created role with 201 Created status or errors with 422
     def create
       @securial_role = Role.new(securial_role_params)
 
@@ -19,6 +52,13 @@ module Securial
       end
     end
 
+    # Updates an existing role.
+    #
+    # Modifies the attributes of an existing role.
+    #
+    # @param [Integer] params[:id] The ID of the role to update
+    # @param [Hash] params[:securial_role] Updated role attributes
+    # @return [void] Renders the updated role or errors with 422 status
     def update
       if @securial_role.update(securial_role_params)
         render :show
@@ -27,6 +67,12 @@ module Securial
       end
     end
 
+    # Deletes an existing role.
+    #
+    # Permanently removes a role from the system.
+    #
+    # @param [Integer] params[:id] The ID of the role to delete
+    # @return [void] Returns 204 No Content status
     def destroy
       @securial_role.destroy
       head :no_content
@@ -34,10 +80,18 @@ module Securial
 
     private
 
+    # Finds and sets a specific role for show, update and destroy actions.
+    #
+    # @param [Integer] params[:id] The ID of the role to find
+    # @return [void]
     def set_securial_role
       @securial_role = Role.find(params[:id])
     end
 
+    # Permits and extracts role parameters from the request.
+    #
+    # @return [ActionController::Parameters] Permitted role parameters
+    #
     def securial_role_params
       params.expect(securial_role: [:role_name, :hide_from_profile])
     end