securial 1.0.1 → 1.0.3

data/app/models/securial/user.rb

@@ -1,4 +1,34 @@
 module Securial
+  #
+  # User
+  #
+  # This class represents a user in the Securial authentication and authorization system.
+  #
+  # Users can have multiple roles assigned to them, which define their permissions
+  # and access levels within the application.
+  #
+  # The User model includes functionality for password reset, email normalization,
+  # and various validations to ensure data integrity.
+  #
+  # ## Attributes
+  # - `email_address`: The user's email address, which is normalized
+  # - `username`: A unique username for the user, with specific format requirements
+  # - `first_name`: The user's first name, required and limited in length
+  # - `last_name`: The user's last name, required and limited in length
+  # - `phone`: An optional phone number, limited in length
+  # - `bio`: An optional biography, limited in length
+  #
+  # ## Validations
+  # - Email address must be present, unique, and formatted correctly
+  # - Username must be present, unique (case insensitive), and formatted correctly
+  # - First and last names must be present and limited in length
+  # - Phone and bio fields are optional but have length restrictions
+  #
+  # ## Associations
+  # - Has many role assignments, allowing users to have multiple roles
+  # - Has many roles through role assignments, enabling flexible permission management
+  # - Has many sessions, allowing for session management and tracking
+  #
   class User < ApplicationRecord
     include Securial::PasswordResettable
 
@@ -45,6 +75,10 @@ module Securial
     has_many :sessions, dependent: :destroy
 
 
+    # Checks if the user has the specified role.
+    #
+    # @param [String] role_name The name of the role to check
+    # @return [Boolean] Returns true if the user has the specified role, false otherwise.
     def is_admin?
       roles.exists?(role_name: Securial.titleized_admin_role)
     end

data/lib/generators/factory_bot/model/model_generator.rb

@@ -1,6 +1,7 @@
 require "rails/generators"
 require "rails/generators/named_base"
 
+# @!ignore
 module FactoryBot
   module Generators
     class ModelGenerator < Rails::Generators::NamedBase

data/lib/securial/auth/auth_encoder.rb

@@ -1,10 +1,58 @@
+# @title Securial Authentication Token Encoder
+#
+# JWT token encoding and decoding for session authentication.
+#
+# This module provides secure JWT token creation and validation for user sessions
+# in the Securial authentication system. It handles the encoding of session data
+# into JWT tokens and the secure decoding/validation of those tokens, including
+# signature verification and claim validation.
+#
+# @example Encoding a session into a JWT token
+#   session = Securial::Session.find(session_id)
+#   token = Securial::Auth::AuthEncoder.encode(session)
+#   # => "eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIxMjM0NTY3ODkwIiwic3ViIjoiM..."
+#
+# @example Decoding and validating a JWT token
+#   begin
+#     payload = Securial::Auth::AuthEncoder.decode(token)
+#     session_id = payload['jti']
+#     # Use session_id to retrieve session from database
+#   rescue Securial::Error::Auth::TokenDecodeError => e
+#     # Handle invalid token
+#   end
 require "jwt"
 
 module Securial
   module Auth
+    # Handles JWT token encoding and decoding for session authentication.
+    #
+    # This module provides methods to securely encode session information into
+    # JWT tokens and decode/validate those tokens. It uses HMAC signing with
+    # a configurable secret and includes standard JWT claims for security.
+    #
+    # The tokens include:
+    # - Session ID (jti claim) for session lookup
+    # - Expiration time (exp claim) for automatic invalidation
+    # - Subject (sub claim) identifying the token type
+    # - Custom claims for IP address and user agent validation
+    #
+    # @see https://datatracker.ietf.org/doc/html/rfc7519 JWT RFC
     module AuthEncoder
       extend self
 
+      # Encodes a session object into a signed JWT token.
+      #
+      # Creates a JWT token containing the session ID and metadata for later
+      # validation. The token is signed using the configured secret and algorithm.
+      #
+      # @param [Securial::Session] session The session object to encode
+      # @return [String, nil] The encoded JWT token, or nil if session is invalid
+      # @raise [Securial::Error::Auth::TokenEncodeError] If JWT encoding fails
+      #
+      # @example
+      #   session = Securial::Session.create!(user: current_user)
+      #   token = AuthEncoder.encode(session)
+      #   # => "eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIxMjM0NTY3ODkw..."
       def encode(session)
         return nil unless session && session.class == Securial::Session
 
@@ -28,6 +76,21 @@ module Securial
         end
       end
 
+      # Decodes and validates a JWT token, returning the payload.
+      #
+      # Verifies the token signature, expiration, and other claims before
+      # returning the decoded payload. The token must have been signed with
+      # the current secret and must not be expired.
+      #
+      # @param [String] token The JWT token to decode and validate
+      # @return [Hash] The decoded token payload containing session information
+      # @raise [Securial::Error::Auth::TokenDecodeError] If token is invalid, expired, or malformed
+      #
+      # @example
+      #   payload = AuthEncoder.decode("eyJhbGciOiJIUzI1NiJ9...")
+      #   session_id = payload['jti']
+      #   ip_address = payload['ip']
+      #   user_agent = payload['agent']
       def decode(token)
         begin
           decoded = ::JWT.decode(token, secret, true, { algorithm: algorithm, verify_jti: true, iss: "securial" })
@@ -39,14 +102,29 @@ module Securial
 
       private
 
+      # Returns the secret key used for JWT signing and verification.
+      #
+      # @return [String] The configured session secret
+      # @api private
+      #
       def secret
         Securial.configuration.session_secret
       end
 
+      # Returns the algorithm used for JWT signing.
+      #
+      # @return [String] The configured session algorithm in uppercase
+      # @api private
+      #
       def algorithm
         Securial.configuration.session_algorithm.to_s.upcase
       end
 
+      # Returns the token expiration duration.
+      #
+      # @return [ActiveSupport::Duration] The configured session expiration duration
+      # @api private
+      #
       def expiry_duration
         Securial.configuration.session_expiration_duration
       end

data/lib/securial/auth/session_creator.rb

@@ -1,8 +1,57 @@
+# @title Securial Session Creator
+#
+# Session creation utilities for the Securial authentication system.
+#
+# This module provides functionality to create authenticated user sessions with
+# proper token generation and metadata tracking. It handles the validation of
+# user and request objects before creating database records and setting up
+# the current session context.
+#
+# @example Creating a session for a user
+#   user = Securial::User.find_by(email: "user@example.com")
+#   session = Securial::Auth::SessionCreator.create_session!(user, request)
+#   # => #<Securial::Session id: "abc123", user_id: "user123", ...>
+#
+# @example Handling invalid inputs
+#   invalid_session = Securial::Auth::SessionCreator.create_session!(nil, request)
+#   # => nil
 module Securial
   module Auth
+    # Creates and manages user authentication sessions.
+    #
+    # This module provides methods to create new authenticated sessions for users,
+    # including proper validation of inputs, generation of refresh tokens, and
+    # setting up session metadata such as IP addresses and user agents.
+    #
+    # Created sessions are automatically set as the current session context and
+    # include all necessary tokens and expiration information for secure
+    # authentication management.
+    #
     module SessionCreator
       extend self
 
+      # Creates a new authenticated session for the given user and request.
+      #
+      # Validates the provided user and request objects, then creates a new session
+      # record with appropriate metadata and tokens. The newly created session is
+      # automatically set as the current session context.
+      #
+      # @param [Securial::User] user The user object to create a session for
+      # @param [ActionDispatch::Request] request The HTTP request object containing metadata
+      # @return [Securial::Session, nil] The created session object, or nil if validation fails
+      #
+      # @example Creating a session after successful authentication
+      #   user = Securial::User.authenticate(email, password)
+      #   if user
+      #     session = SessionCreator.create_session!(user, request)
+      #     # User is now authenticated with active session
+      #   end
+      #
+      # @example Handling validation failures
+      #   # Invalid user (not persisted)
+      #   new_user = Securial::User.new
+      #   session = SessionCreator.create_session!(new_user, request)
+      #   # => nil
       def create_session!(user, request)
         valid_user = user && user.is_a?(Securial::User) && user.persisted?
         valid_request = request.is_a?(ActionDispatch::Request)

data/lib/securial/auth/token_generator.rb

@@ -1,11 +1,48 @@
+# @title Securial Token Generator
+#
+# Secure token generation utilities for the Securial authentication system.
+#
+# This module provides cryptographically secure token generation for various
+# authentication purposes, including refresh tokens and password reset tokens.
+# All tokens are generated using secure random sources and include appropriate
+# entropy for their intended use cases.
+#
+# @example Generating a refresh token
+#   refresh_token = Securial::Auth::TokenGenerator.generate_refresh_token
+#   # => "a1b2c3d4e5f6...9876543210abcdef1234567890"
+#
+# @example Generating a password reset token
+#   reset_token = Securial::Auth::TokenGenerator.generate_password_reset_token
+#   # => "aBc123-DeF456"
+#
 require "openssl"
 require "securerandom"
 
 module Securial
   module Auth
+    # Generates secure tokens for authentication operations.
+    #
+    # This module provides methods to generate cryptographically secure tokens
+    # for different authentication scenarios. All tokens use secure random
+    # generation and appropriate cryptographic techniques to ensure uniqueness
+    # and security.
     module TokenGenerator
       extend self
 
+      # Generates a secure refresh token using HMAC and random data.
+      #
+      # Creates a refresh token by combining an HMAC signature with random data,
+      # providing both integrity verification and sufficient entropy. The token
+      # is suitable for long-term storage and session refresh operations.
+      #
+      # @return [String] A secure refresh token (96 characters hexadecimal)
+      #
+      # @example
+      #   token = TokenGenerator.generate_refresh_token
+      #   # => "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456789012345678901234567890abcdef"
+      #
+      # @see #generate_password_reset_token
+      #
       def generate_refresh_token
         secret = Securial.configuration.session_secret
         algo = "SHA256"
@@ -17,10 +54,47 @@ module Securial
         "#{hmac}#{random_data}"
       end
 
+      # Generates a user-friendly password reset token.
+      #
+      # Creates a short, alphanumeric token formatted for easy user entry.
+      # The token is suitable for password reset flows where users need to
+      # manually enter the token from an email or SMS message.
+      #
+      # @return [String] A formatted password reset token (format: "ABC123-DEF456")
+      #
+      # @example
+      #   token = TokenGenerator.generate_password_reset_token
+      #   # => "aBc123-DeF456"
+      #
+      # @note This token has lower entropy than refresh tokens and should have
+      #   shorter expiration times and rate limiting protection.
+      #
+      # @see #generate_refresh_token
+      #
       def generate_password_reset_token
         token = SecureRandom.alphanumeric(12)
         "#{token[0, 6]}-#{token[6, 6]}"
       end
+
+      # Generates a URL-safe friendly token for general use.
+      #
+      # Creates a secure, URL-safe token suitable for various authentication
+      # operations that require a balance between security and usability.
+      #
+      # @param [Integer] length The desired length of the generated token (default: 20)
+      # @return [String] A URL-safe token containing letters, numbers, and safe symbols
+      #
+      # @example
+      #   token = TokenGenerator.friendly_token
+      #   # => "aBcDeF123456GhIjKl78"
+      #
+      # @example With custom length
+      #   token = TokenGenerator.friendly_token(32)
+      #   # => "aBcDeF123456GhIjKl789012MnOpQr34"
+      #
+      def friendly_token(length = 20)
+        SecureRandom.urlsafe_base64(length).tr("lIO0", "sxyz")[0, length]
+      end
     end
   end
 end

data/lib/securial/auth.rb

@@ -1,12 +1,50 @@
+# @title Securial Authentication System
+#
+# Core authentication components for the Securial framework.
+#
+# This file serves as the entry point for authentication-related functionality in Securial,
+# loading specialized modules that handle token generation, encoding/decoding, and session management.
+# These components work together to provide a secure, flexible authentication system supporting
+# token-based and session-based authentication patterns.
+#
+# @example Encoding a session token
+#   # Create an encoded JWT representing a user session
+#   token = Securial::Auth::AuthEncoder.encode(user_session)
+#   # => "eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIxMjM0NTY3ODkwIiwic3ViIjoiM..."
+#
+# @example Creating a new user session
+#   # Authenticate user and create a new session with tokens
+#   Securial::Auth::SessionCreator.create_session!(user, request)
+#
+#   # Access the newly created session
+#   current_session = Current.session
+#
+# @example Generating secure tokens
+#   # Generate a password reset token
+#   reset_token = Securial::Auth::TokenGenerator.friendly_token
+#   # => "aBc123DeF456gHi789"
+#
 require "securial/auth/auth_encoder"
 require "securial/auth/session_creator"
 require "securial/auth/token_generator"
 
 module Securial
-  module Auth
-    # This is a placeholder for the Auth module.
-    # It can be used to include authentication-related methods or constants
-    # that are not specific to encoding or session creation.
-    # Currently, it serves as a namespace for the AuthEncoder and SessionCreator modules.
-  end
+  # Namespace for authentication-related functionality in the Securial framework.
+  #
+  # The Auth module contains components that work together to provide a complete
+  # authentication system for Securial-powered applications:
+  #
+  # - {AuthEncoder} - Handles JWT token encoding and decoding with security measures
+  # - {SessionCreator} - Creates and manages authenticated user sessions
+  # - {TokenGenerator} - Generates secure random tokens for various authentication needs
+  #
+  # These components handle the cryptographic and security aspects of user authentication,
+  # ensuring that best practices are followed for token generation, validation, and session
+  # management throughout the application lifecycle.
+  #
+  # @see Securial::Auth::AuthEncoder
+  # @see Securial::Auth::SessionCreator
+  # @see Securial::Auth::TokenGenerator
+  #
+  module Auth; end
 end

data/lib/securial/cli.rb

@@ -1,13 +1,51 @@
+# @title Securial Command Line Interface
+#
+# Command line interface for the Securial framework.
+#
+# This file implements the CLI tool for Securial, providing command-line utilities
+# for creating new Rails applications with Securial pre-installed. It handles
+# command parsing, option flags, and orchestrates the application setup process.
+#
+# @example Creating a new Rails application with Securial
+#   # Create a basic Securial application
+#   $ securial new myapp
+#
+#   # Create an API-only Securial application with PostgreSQL
+#   $ securial new myapi --api --database=postgresql
+#
 require "optparse"
 
 # rubocop:disable Rails/Exit, Rails/Output
 
 module Securial
+  # Command-line interface for the Securial gem.
+  #
+  # This class provides the command-line functionality for Securial, enabling users
+  # to create new Rails applications with Securial pre-installed and configured.
+  # It handles command parsing, flag processing, and orchestrates the setup of
+  # new applications.
+  #
   class CLI
+    # Entry point for the CLI application.
+    #
+    # Creates a new CLI instance and delegates to its start method.
+    #
+    # @param argv [Array<String>] command line arguments
+    # @return [Integer] exit status code (0 for success, non-zero for errors)
+    #
     def self.start(argv)
       new.start(argv)
     end
 
+    # Processes command line arguments and executes the appropriate action.
+    #
+    # This method handles both option flags (like --version) and commands
+    # (like 'new'), delegating to specialized handlers and returning
+    # the appropriate exit code.
+    #
+    # @param argv [Array<String>] command line arguments
+    # @return [Integer] exit status code (0 for success, non-zero for errors)
+    #
     def start(argv)
       # Process options and exit if a flag was handled
       result = handle_flags(argv)
@@ -19,6 +57,14 @@ module Securial
 
     private
 
+    # Processes option flags from the command line arguments.
+    #
+    # Parses options like --version and --help, executing their actions
+    # if present and removing them from the argument list.
+    #
+    # @param argv [Array<String>] command line arguments
+    # @return [nil, Integer] nil to continue processing, or exit code
+    #
     def handle_flags(argv)
       parser = create_option_parser
 
@@ -32,6 +78,14 @@ module Securial
       end
     end
 
+    # Processes commands from the command line arguments.
+    #
+    # Identifies the command (e.g., 'new') and delegates to the appropriate
+    # handler method for that command.
+    #
+    # @param argv [Array<String>] command line arguments
+    # @return [Integer] exit status code (0 for success, non-zero for errors)
+    #
     def handle_commands(argv)
       cmd = argv.shift
 
@@ -44,6 +98,14 @@ module Securial
       end
     end
 
+    # Handles the 'new' command for creating Rails applications.
+    #
+    # Validates that an application name is provided, then delegates to
+    # securial_new to create the application with Securial.
+    #
+    # @param argv [Array<String>] remaining command line arguments
+    # @return [Integer] exit status code (0 for success, non-zero for errors)
+    #
     def handle_new_command(argv)
       app_name = argv.shift
 
@@ -57,6 +119,12 @@ module Securial
       0
     end
 
+    # Creates and configures the option parser.
+    #
+    # Sets up the command-line options and their handlers.
+    #
+    # @return [OptionParser] configured option parser instance
+    #
     def create_option_parser
       OptionParser.new do |opts|
         opts.banner = "Usage: securial [options] <command> [command options]\n\n"
@@ -79,6 +147,10 @@ module Securial
       end
     end
 
+    # Displays the current Securial version.
+    #
+    # @return [void]
+    #
     def show_version
       require "securial/version"
       puts "Securial v#{Securial::VERSION}"
@@ -86,6 +158,15 @@ module Securial
       puts "Securial version information not available."
     end
 
+    # Creates a new Rails application with Securial pre-installed.
+    #
+    # Orchestrates the process of creating a Rails application, adding the
+    # Securial gem, installing dependencies, and configuring the application.
+    #
+    # @param app_name [String] name of the Rails application to create
+    # @param rails_options [Array<String>] options to pass to 'rails new'
+    # @return [void]
+    #
     def securial_new(app_name, rails_options)
       puts "🏗️  Creating new Rails app: #{app_name}"
 
@@ -97,27 +178,53 @@ module Securial
       print_final_instructions(app_name)
     end
 
+    # Creates a new Rails application.
+    #
+    # @param app_name [String] name of the Rails application to create
+    # @param rails_options [Array<String>] options to pass to 'rails new'
+    # @return [Integer] command exit status
+    #
     def create_rails_app(app_name, rails_options)
       rails_command = ["rails", "new", app_name, *rails_options]
       run(rails_command)
     end
 
+    # Adds the Securial gem to the application's Gemfile.
+    #
+    # @param app_name [String] name of the Rails application
+    # @return [void]
+    #
     def add_securial_gem(app_name)
       puts "📦  Adding Securial gem to Gemfile"
       gemfile_path = File.join(app_name, "Gemfile")
       File.open(gemfile_path, "a") { |f| f.puts "\ngem 'securial'" }
     end
 
+    # Installs gems for the application using Bundler.
+    #
+    # @param app_name [String] name of the Rails application
+    # @return [Integer] command exit status
+    #
     def install_gems(app_name)
       run("bundle install", chdir: app_name)
     end
 
+    # Installs and configures Securial in the application.
+    #
+    # @param app_name [String] name of the Rails application
+    # @return [Integer] command exit status
+    #
     def install_securial(app_name)
       puts "🔧  Installing Securial"
       run("bin/rails generate securial:install", chdir: app_name)
       run("bin/rails db:migrate", chdir: app_name)
     end
 
+    # Mounts the Securial engine in the application's routes.
+    #
+    # @param app_name [String] name of the Rails application
+    # @return [void]
+    #
     def mount_securial_engine(app_name)
       puts "🔗  Mounting Securial engine in routes"
       routes_path = File.join(app_name, "config/routes.rb")
@@ -128,6 +235,11 @@ module Securial
       File.write(routes_path, updated)
     end
 
+    # Prints final setup instructions after successful installation.
+    #
+    # @param app_name [String] name of the Rails application
+    # @return [void]
+    #
     def print_final_instructions(app_name)
       puts <<~INSTRUCTIONS
         🎉  Securial has been successfully installed in your Rails app!
@@ -140,6 +252,16 @@ module Securial
       INSTRUCTIONS
     end
 
+    # Runs a system command with optional directory change.
+    #
+    # Executes the provided command, optionally in a different directory,
+    # and handles success/failure conditions.
+    #
+    # @param command [String, Array<String>] command to run
+    # @param chdir [String, nil] directory to change to before running command
+    # @return [Integer] command exit status code (0 for success)
+    # @raise [SystemExit] if the command fails
+    #
     def run(command, chdir: nil)
       puts "→ #{command.inspect}"
       result =
@@ -156,3 +278,5 @@ module Securial
     end
   end
 end
+
+# rubocop:enable Rails/Exit, Rails/Output