securial 1.0.1 → 1.0.2

data/app/controllers/securial/sessions_controller.rb

@@ -1,16 +1,52 @@
 module Securial
+  #
+  # SessionsController
+  #
+  # Controller for managing user authentication sessions.
+  #
+  # This controller handles session-related operations including:
+  #   - User login and token issuance
+  #   - Session listing and management
+  #   - Token refresh
+  #   - Session revocation and logout
+  #
+  # Session management is a critical security component, providing users
+  # with the ability to authenticate and manage their active sessions.
+  #
+  # Routes typically mounted at Securial/sessions/* in the host application.
+  #
   class SessionsController < ApplicationController
     skip_authentication! only: %i[login refresh]
 
     before_action :set_session, only: %i[show revoke logout]
 
+    # Lists all active sessions for the current user.
+    #
+    # Retrieves all active sessions belonging to the authenticated user,
+    # enabling users to monitor their login activity across devices.
+    #
+    # @return [void] Renders index view with the user's active sessions
     def index
       @securial_sessions = Current.user.sessions
     end
 
+    # Shows details for a specific session.
+    #
+    # Retrieves and displays information for a single session.
+    #
+    # @param [Integer] params[:id] The ID of the session to display
+    # @return [void] Renders show view with the specified session
     def show
     end
 
+    # Authenticates a user and creates a new session.
+    #
+    # Validates the provided credentials and, if successful, creates a new
+    # session and returns access and refresh tokens.
+    #
+    # @param [String] params[:email_address] The user's email address
+    # @param [String] params[:password] The user's password
+    # @return [void] Renders tokens with 201 Created status or error with 401 status
     def login
       params.require([:email_address, :password])
       if user = User.authenticate_by(params.permit([:email_address, :password]))
@@ -18,18 +54,30 @@ module Securial
       else
         render status: :unauthorized,
                json: {
-                 error: "Invalid email address or password.",
+                 errors: ["Invalid email address or password."],
                  instructions: "Make sure to send the correct 'email_address' and 'password' in the payload",
                }
       end
     end
 
+    # Ends the current user's session.
+    #
+    # Revokes the active session token, effectively logging the user out.
+    #
+    # @return [void] Returns 204 No Content status
     def logout
       @securial_session.revoke!
       Current.session = nil
       head :no_content
     end
 
+    # Issues new tokens using a valid refresh token.
+    #
+    # Validates the provided refresh token and, if valid, issues new
+    # access and refresh tokens to extend the user's session.
+    #
+    # @param [String] params[:refresh_token] The refresh token to validate
+    # @return [void] Renders new tokens with 201 Created status or error with 422 status
     def refresh
       if Current.session = Securial::Session.find_by(refresh_token: params[:refresh_token])
         if Current.session.is_valid_session_request?(request)
@@ -43,15 +91,29 @@ module Securial
           return
         end
       end
-      render status: :unprocessable_entity, json: { error: "Invalid or expired token." }
+      render status: :unprocessable_entity, json: {
+        error: "Invalid or expired token.",
+        instructions: "Please log in again to obtain a new access token.",
+      }
     end
 
+    # Revokes a specific session.
+    #
+    # Invalidates the specified session, preventing further use of its tokens.
+    #
+    # @param [Integer] params[:id] The ID of the session to revoke
+    # @return [void] Returns 204 No Content status
     def revoke
       @securial_session.revoke!
       Current.session = nil if @securial_session == Current.session
       head :no_content
     end
 
+    # Revokes all of the current user's sessions.
+    #
+    # Invalidates all active sessions for the current user, forcing logout across all devices.
+    #
+    # @return [void] Returns 204 No Content status
     def revoke_all
       Current.user.sessions.each(&:revoke!)
       Current.session = nil
@@ -60,16 +122,28 @@ module Securial
 
     private
 
+    # Finds and sets the session to be manipulated.
+    #
+    # Uses the provided ID or defaults to the current session if no ID is provided.
+    #
+    # @return [void]
     def set_session
       id = params[:id]
       @securial_session = id ? Current.user.sessions.find(params[:id]) : Current.session
     end
 
+    # Renders the appropriate response after successful authentication.
+    #
+    # Checks if the user's password has expired and either prompts for reset
+    # or creates a new session with tokens for the authenticated user.
+    #
+    # @param [User] user The authenticated user
+    # @return [void] Renders tokens with 201 Created status or error with 403 status
     def render_login_response(user)
       if user.password_expired?
         render status: :forbidden,
                json: {
-                 error: "Password expired",
+                 errors: ["Password expired"],
                  instructions: "Please reset your password before logging in.",
                }
       else

data/app/controllers/securial/status_controller.rb

@@ -1,7 +1,31 @@
 module Securial
+  #
+  # StatusController
+  #
+  # Controller for checking system status and authentication state.
+  #
+  # This controller provides a simple endpoint for checking if the Securial
+  # system is operational and retrieving basic information about the current
+  # authentication state, if applicable. This endpoint is publicly accessible
+  # and does not require authentication.
+  #
+  # Typically used for:
+  #   - Health checks from monitoring systems
+  #   - Client applications to verify API availability
+  #   - Testing authentication status without making authenticated requests
+  #
+  # Routes typically mounted at Securial/status/* in the host application.
+  #
   class StatusController < ApplicationController
     skip_authentication!
 
+    # Shows the current Securial Engine status.
+    #
+    # Provides information about the engine's operational state and,
+    # if the request includes a valid authentication token, the current user.
+    # This endpoint is always accessible without authentication.
+    #
+    # @return [void] Renders status information with 200 OK status
     def show
       @current_user = current_user
       Securial.logger.info("Status check initiated")

data/app/controllers/securial/users_controller.rb

@@ -1,14 +1,48 @@
 module Securial
+  #
+  # UsersController
+  #
+  # Controller for managing users in the Securial authentication system.
+  #
+  # This controller provides administrative CRUD operations for user management, including:
+  #   - Listing all users in the system
+  #   - Creating new user accounts
+  #   - Viewing user details
+  #   - Updating user information
+  #   - Deleting user accounts
+  #
+  # All operations require admin authentication and are typically used for
+  # administrative user management rather than self-service account management.
+  #
+  # Routes typically mounted at Securial/admins/users/* in the host application.
+  #
   class UsersController < ApplicationController
     before_action :set_securial_user, only: [:show, :update, :destroy]
 
+    # Lists all users in the system.
+    #
+    # Retrieves all users for administrative display and management.
+    #
+    # @return [void] Renders index view with all users
     def index
       @securial_users = User.all
     end
 
+    # Shows details for a specific user.
+    #
+    # Retrieves and displays information for a single user.
+    #
+    # @param [Integer] params[:id] The ID of the user to display
+    # @return [void] Renders show view with the specified user
     def show
     end
 
+    # Creates a new user in the system.
+    #
+    # Adds a new user with the provided attributes.
+    #
+    # @param [Hash] params[:securial_user] User attributes including email_address, username, etc.
+    # @return [void] Renders the created user with 201 Created status or errors with 422
     def create
       @securial_user = User.new(securial_user_params)
 
@@ -19,6 +53,13 @@ module Securial
       end
     end
 
+    # Updates an existing user.
+    #
+    # Modifies the attributes of an existing user.
+    #
+    # @param [Integer] params[:id] The ID of the user to update
+    # @param [Hash] params[:securial_user] Updated user attributes
+    # @return [void] Renders the updated user or errors with 422 status
     def update
       if @securial_user.update(securial_user_params)
         render :show, status: :ok, location: @securial_user
@@ -27,6 +68,12 @@ module Securial
       end
     end
 
+    # Deletes an existing user.
+    #
+    # Permanently removes a user from the system.
+    #
+    # @param [Integer] params[:id] The ID of the user to delete
+    # @return [void] Returns 204 No Content status
     def destroy
       @securial_user.destroy
       head :no_content
@@ -34,10 +81,17 @@ module Securial
 
     private
 
+    # Finds and sets a specific user for show, update and destroy actions.
+    #
+    # @return [void]
+    #
     def set_securial_user
       @securial_user = User.find(params[:id])
     end
 
+    # Permits and extracts user parameters from the request.
+    #
+    # @return [ActionController::Parameters] Permitted user parameters
     def securial_user_params
       params.expect(securial_user: [
                       :email_address,

data/app/jobs/securial/application_job.rb

@@ -1,4 +1,13 @@
 module Securial
+  #
+  # ApplicationJob
+  #
+  # This class serves as the base job class for all Securial jobs.
+  #
+  # It inherits from ActiveJob::Base, allowing it to be used with Rails' job
+  # processing framework. This class can be extended to create specific jobs
+  # related to the Securial authentication and authorization system.
+  #
   class ApplicationJob < ActiveJob::Base
   end
 end

data/app/mailers/securial/application_mailer.rb

@@ -1,4 +1,16 @@
 module Securial
+  #
+  # ApplicationMailer
+  #
+  # This class serves as the base mailer class for all Securial mailers.
+  #
+  # It inherits from ActionMailer::Base, allowing it to be used for sending
+  # emails related to the Securial authentication and authorization system.
+  #
+  # This class can be extended to create specific mailers for notifications,
+  # user communications, or other email-related functionality within the Securial
+  # system.
+  #
   class ApplicationMailer < ActionMailer::Base
     default from: "from@example.com"
     layout "mailer"

data/app/mailers/securial/securial_mailer.rb

@@ -1,11 +1,32 @@
 module Securial
+  #
+  # SecurialMailer
+  #
+  # # This class serves as the mailer for Securial, handling email notifications
+  # related to user account management, such as welcome emails, sign-in notifications,
+  # account updates, and password recovery.
+  #
+  # It inherits from ApplicationMailer, allowing it to utilize the base mailer functionality
+  # provided by Securial::ApplicationMailer.
+  #
+  # This class can be extended to add more email functionalities as needed.
+  #
   class SecurialMailer < ApplicationMailer
+    # Sends a welcome email to a new user.
+    #
+    # @param [Securial::User] securial_user The user to whom the welcome email will be sent.
+    # @return [void] Sends an email with the subject defined in Securial configuration.
     def welcome(securial_user)
       @user = securial_user
       subject = Securial.configuration.mailer_sign_up_subject
       mail subject: subject, to: securial_user.email_address
     end
 
+    # Sends a sign-in notification email.
+    #
+    # @param [Securial::User] securial_user The user who signed in.
+    # @param [<Type>] securial_session The session information for the sign-in.
+    # @return [void] Sends an email with the subject defined in Securial configuration
     def sign_in(securial_user, securial_session)
       @user = securial_user
       @session = securial_session
@@ -13,12 +34,21 @@ module Securial
       mail subject: subject, to: securial_user.email_address
     end
 
+    # Sends an account update notification email.
+    #
+    # @param [Securial::User] securial_user The user whose account was updated.
+    # @return [void] Sends an email with the subject defined in Securial configuration.
     def update_account(securial_user)
       @user = securial_user
       subject = Securial.configuration.mailer_update_account_subject
       mail subject: subject, to: securial_user.email_address
     end
 
+    # Sends a password recovery email.
+    #
+    # @param [Securial::User] securial_user The user who requested a password reset.
+    # @return [void] Sends an email with the subject defined in Securial configuration
+    # containing instructions for resetting the password.
     def forgot_password(securial_user)
       @user = securial_user
       subject = Securial.configuration.mailer_forgot_password_subject

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

@@ -1,4 +1,37 @@
 module Securial
+  #
+  # PasswordResettable Concern
+  #
+  # This module provides functionality for managing password reset tokens and
+  # password expiration for user accounts. It includes methods to generate,
+  # validate, and clear reset password tokens, as well as to check if a user's
+  # password has expired.
+  #
+  # It also includes validations for password complexity and length.
+  #
+  # ## Usage
+  # Include this module in your User model to enable password reset functionality.
+  # It requires the model to have a `password_digest` attribute for secure password storage.
+  # The module also provides methods to handle password reset tokens and password expiration.
+  #
+  # ## Example
+  #   class User < ApplicationRecord
+  #     include Securial::PasswordResettable
+  #     # Additional user model code...
+  #   end
+  #
+  # ## Configuration
+  # The module uses the Securial configuration for password complexity, length,
+  # and reset password token expiration settings. You can configure these settings
+  # in your Securial initializer.
+  #
+  # ## Validations
+  # - Password must meet complexity requirements defined in Securial.configuration
+  # - Password must be at least Securial.configuration.password_min_length characters long
+  # - Password must be at most Securial.configuration.password_max_length characters long
+  # - Password confirmation must be present if a new password is being set or if the password is not nil
+  # - Reset password token must be generated and cleared appropriately
+  # - Password expiration is managed based on the Securial.configuration.password_expires_in setting
   module PasswordResettable
     extend ActiveSupport::Concern
 
@@ -23,6 +56,9 @@ module Securial
                 if: -> { new_record? || !password.nil? }
     end
 
+    # Generates a secure reset password token for the user.
+    #
+    # @return [void] Updates the user's reset_password_token and reset_password_token_created_at attributes.
     def generate_reset_password_token!
       update!(
         reset_password_token: Auth::TokenGenerator.generate_password_reset_token,
@@ -30,6 +66,17 @@ module Securial
       )
     end
 
+    # Checks if the reset password token is valid.
+    #
+    # The token is considered valid if it was created within the configured expiration duration.
+    #
+    # @example
+    #   user.reset_password_token_valid? # => true or false
+    # @note The method checks both the presence of the token and its creation time.
+    # @note If the token is blank or the creation time is blank, it returns false.
+    # @note If the token is expired, it returns false.
+    # @note The method uses the configured expiration duration from Securial.configuration.
+    # @return [Boolean] Returns true if the reset password token is valid, false otherwise.
     def reset_password_token_valid?
       return false if reset_password_token.blank? || reset_password_token_created_at.blank?
 
@@ -39,6 +86,12 @@ module Securial
       reset_password_token_created_at > duration.ago
     end
 
+    # Clears the reset password token and its creation time.
+    #
+    # This method is typically called after a successful password reset
+    # to prevent the token from being reused.
+    #
+    # @return [void] Updates the user's reset_password_token and reset_password_token_created_at attributes to nil.
     def clear_reset_password_token!
       update!(
         reset_password_token: nil,
@@ -46,6 +99,18 @@ module Securial
       )
     end
 
+    # Checks if the user's password has expired.
+    #
+    # The password is considered expired if the last time it was changed
+    # is older than the configured expiration duration.
+    #
+    # @example
+    #   user.password_expired? # => true or false
+    # @note The method checks both the presence of the password_changed_at timestamp
+    #   and the configured expiration duration.
+    # @note If the password_changed_at timestamp is blank, it returns false.
+    # @note If the password is expired, it returns true.
+    # @return [Boolean] Returns true if the password is expired, false otherwise.
     def password_expired?
       return false unless Securial.configuration.password_expires
       return true unless password_changed_at
@@ -55,6 +120,11 @@ module Securial
 
     private
 
+    # Updates the password_changed_at timestamp to the current time.
+    #
+    # This method is called before saving the user record if the password digest has changed.
+    #
+    # @return [void] Sets the password_changed_at attribute to the current time.
     def update_password_changed_at
       self.password_changed_at = Time.current
     end

data/app/models/securial/application_record.rb

@@ -1,4 +1,18 @@
 module Securial
+  #
+  # ApplicationRecord
+  #
+  # This class serves as the base model class for all Securial models.
+  #
+  # It inherits from ActiveRecord::Base and provides a common functionality for all models in the
+  # Securial engine, including:
+  #   - UUIDv7 generation for the `id` field
+  #   - Abstract class definition to ensure it is not instantiated directly
+  #
+  #   - Custom behavior for the `before_create` callback to set the `id` field
+  #
+  # This class can be extended to add more model functionalities as needed.
+  #
   class ApplicationRecord < ActiveRecord::Base
     self.abstract_class = true
 
@@ -7,8 +21,13 @@ module Securial
     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.
+    #
+    # @return [void]
+    # @note This method will only set the `id` if it is not already present
+    # and if the `id` field is of type string.
     def generate_uuid_v7
       return if self.id.present? || self.class.type_for_attribute(:id).type != :string
 

data/app/models/securial/current.rb

@@ -1,4 +1,17 @@
 module Securial
+  #
+  # Current
+  #
+  # This class provides a way to access the current session and user
+  # throughout the application. It uses ActiveSupport::CurrentAttributes to
+  # store the session and delegate the user method to it.
+  #
+  # It allows you to access the current user in controllers, views, and jobs
+  # without having to pass the user object explicitly.
+  #
+  # Example usage:
+  #   Current.session = session
+  #   Current.user # => returns the current user object or nil if not authenticated
   class Current < ActiveSupport::CurrentAttributes
     attribute :session
     delegate :user, to: :session, allow_nil: true

data/app/models/securial/role.rb

@@ -1,4 +1,21 @@
 module Securial
+  #
+  # Role
+  #
+  # This class represents a role in the Securial authorization system.
+  #
+  # Roles are used to define permissions and access levels for users within the application.
+  #
+  # ## Attributes
+  # - `role_name`: The name of the role, which is normalized to ensure consistency.
+  #
+  # ## Validations
+  # - `role_name` must be present and unique (case insensitive).
+  #
+  # ## Associations
+  # - Has many role assignments, allowing users to be associated with this role
+  # - Has many users through role assignments, enabling flexible permission management
+  #
   class Role < ApplicationRecord
     normalizes :role_name, with: ->(e) { Securial::Helpers::NormalizingHelper.normalize_role_name(e) }
 

data/app/models/securial/role_assignment.rb

@@ -1,4 +1,20 @@
 module Securial
+  #
+  # RoleAssignment
+  #
+  # This class represents the association between a user and a role in the Securial system.
+  #
+  # It is used to manage which roles are assigned to which users, allowing for
+  # flexible permission management within the application.
+  #
+  ### Attributes
+  # - `user_id`: The ID of the user to whom the role is assigned
+  # - `role_id`: The ID of the role being assigned to the user
+  #
+  # ## Associations
+  # - Belongs to a user, linking the assignment to a specific user
+  # - Belongs to a role, linking the assignment to a specific role
+  #
   class RoleAssignment < ApplicationRecord
     belongs_to :user
     belongs_to :role

data/app/models/securial/session.rb

@@ -1,4 +1,29 @@
 module Securial
+  #
+  # Session
+  #
+  # # This class represents a user session in the Securial authentication system.
+  # # It is used to manage user sessions, including session creation, validation,
+  # and refresh functionality.
+  #
+  # ## Attributes
+  # - `user_id`: The ID of the user associated with the session
+  # - `ip_address`: The IP address from which the session was created
+  # - `user_agent`: The user agent string of the browser or client used to create
+  # the session
+  # - `refresh_token`: A token used to refresh the session
+  # - `refresh_token_expires_at`: The expiration time of the refresh token
+  # - `refresh_count`: The number of times the session has been refreshed
+  # - `last_refreshed_at`: The timestamp of the last time the session was refreshed
+  # - `revoked`: A boolean indicating whether the session has been revoked
+  #
+  # ## Associations
+  # - Belongs to a user, linking the session to a specific user
+  #
+  # ## Validations
+  # - `ip_address`: Must be present
+  # - `user_agent`: Must be present
+  # - `refresh_token`: Must be present
   class Session < ApplicationRecord
     belongs_to :user
 
@@ -6,18 +31,56 @@ module Securial
     validates :user_agent, presence: true
     validates :refresh_token, presence: true
 
+    # Revokes the session by setting the `revoked` attribute to true.
+    #
+    # This method updates the session record in the database to indicate that
+    # the session is no longer valid.
+    #
+    # @return [void] Updates the `revoked` attribute to true.
+    # @raise [ActiveRecord::RecordInvalid] if the update fails due to validation errors
+    # @example
+    #   session.revoke! # => Updates the session to be revoked
+    # @note This method does not delete the session record; it only marks it as revoked.
+    #
     def revoke!
       update!(revoked: true)
     end
 
+    # Checks if the session is valid based on its state.
+    #
+    # A session is considered valid if it is not revoked and has not expired.
+    #
+    # @return [Boolean] Returns true if the session is valid, false otherwise.
     def is_valid_session?
-      revoked? || expired? ? false : true
+      !(revoked? || expired?)
     end
 
+    # Checks if the session is valid for a specific request.
+    #
+    # A session is valid for a request if it is not revoked, has not expired,
+    # and the IP address and user agent match those of the request.
+    #
+    # @param [ActionDispatch::Request] request The request to validate against
+    # @return [Boolean] Returns true if the session is valid for the request, false otherwise.
     def is_valid_session_request?(request)
       is_valid_session? && ip_address == request.ip && user_agent == request.user_agent
     end
 
+    # Refreshes the session by generating a new refresh token and updating
+    # the session attributes.
+    #
+    # This method raises an error if the session is revoked or expired.
+    #
+    # @raise [Securial::Error::Auth::TokenRevokedError] if the session is revoked
+    # @raise [Securial::Error::Auth::TokenExpiredError] if the session is expired
+    # @return [void] Updates the session with a new refresh token and updates the refresh count and timestamps.
+    # @example
+    #   session.refresh! # => Updates the session with a new refresh token
+    # @note This method uses the Securial::Auth::TokenGenerator to
+    # generate a new refresh token and updates the session's attributes accordingly.
+    # @note The refresh token expiration duration is configured in Securial.configuration.session_refresh_token_expires_in.
+    #
+    # @see Securial::Auth::TokenGenerator
     def refresh!
       raise Securial::Error::Auth::TokenRevokedError if revoked?
       raise Securial::Error::Auth::TokenExpiredError if expired?
@@ -32,7 +95,22 @@ module Securial
               refresh_token_expires_at: refresh_token_duration.from_now)
     end
 
+    # Checks if the session is revoked.
+    #
+    # @return [Boolean] Returns true if the session is revoked, false otherwise.
+    #
+    # @example
+    #   session.revoked? # => true or false
+    # @note This method checks the `revoked` attribute of the session.
+    # @see Securial::Session#revoked
+    # @note This method is used to determine if the session is still active or has been revoked
     def revoked?; revoked; end
+
+    # Checks if the session has expired based on the refresh token expiration time.
+    #
+    # A session is considered expired if the `refresh_token_expires_at` time is in the past.
+    #
+    # @return [Boolean] Returns true if the session has expired, false otherwise.
     def expired?; refresh_token_expires_at < Time.current; end
   end
 end