securial 1.0.0 → 1.0.2

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/bin/securial

@@ -1,26 +1,9 @@
 #!/usr/bin/env ruby
 
-require "fileutils"
-require_relative "../lib/securial/cli/show_version"
-require_relative "../lib/securial/cli/show_help"
-require_relative "../lib/securial/cli/run"
-require_relative "../lib/securial/cli/securial_new"
+# Set up the load path for local development or gem installation
+lib = File.expand_path("../../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
-case ARGV[0]
-when "-v", "--version"
-  show_version
-when "-h", "--help"
-  show_help
-when "new"
-  if ARGV[1]
-    app_name = ARGV[1]
-    rails_options = ARGV[2..] || []
-    securial_new(app_name, rails_options)
-  else
-    show_help
-    exit(1)
-  end
-else
-  show_help
-  exit(1)
-end
+require "securial/cli"
+
+Securial::CLI.start(ARGV)

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/generators/securial/install/install_generator.rb

@@ -4,10 +4,10 @@ require "rake"
 module Securial
   module Generators
     class InstallGenerator < Rails::Generators::Base
-      source_root File.expand_path("templates", __dir__)
-
       desc "initializes Securial in your application."
 
+      source_root File.expand_path("templates", __dir__)
+
       def copy_initializer
         say_status("copying", "Securial Initializers", :green)
         template "securial_initializer.erb", "config/initializers/securial.rb"

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

@@ -5,9 +5,10 @@ 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."
 
+        source_root Securial::Engine.root.join("app", "views", "securial").to_s
+
         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))

data/lib/generators/securial/jbuilder/jbuilder_generator.rb

@@ -1,6 +1,8 @@
 module Securial
   module Generators
     class JbuilderGenerator < Rails::Generators::NamedBase
+      desc "Generates Jbuilder view files for a given resource."
+
       source_root File.expand_path("templates", __dir__)
 
       argument :attributes, type: :array, default: [], banner: "field:type field:type"

data/lib/generators/securial/scaffold/scaffold_generator.rb

@@ -5,6 +5,8 @@ require "rails/generators/named_base"
 module Securial
   module Generators
     class ScaffoldGenerator < Rails::Generators::NamedBase
+      desc "Creates a scaffold for a given resource, including model, controller, views, routes, and tests."
+
       include Rails::Generators::ResourceHelpers
 
       allow_incompatible_default_type!

data/lib/securial/auth/auth_encoder.rb

@@ -3,7 +3,7 @@ require "jwt"
 module Securial
   module Auth
     module AuthEncoder
-      module_function
+      extend self
 
       def encode(session)
         return nil unless session && session.class == Securial::Session
@@ -37,6 +37,8 @@ module Securial
         decoded.first
       end
 
+      private
+
       def secret
         Securial.configuration.session_secret
       end
@@ -48,8 +50,6 @@ module Securial
       def expiry_duration
         Securial.configuration.session_expiration_duration
       end
-
-      private_class_method :secret, :algorithm, :expiry_duration
     end
   end
 end

data/lib/securial/auth/session_creator.rb

@@ -1,7 +1,7 @@
 module Securial
   module Auth
     module SessionCreator
-      module_function
+      extend self
 
       def create_session!(user, request)
         valid_user = user && user.is_a?(Securial::User) && user.persisted?

data/lib/securial/auth/token_generator.rb

@@ -4,22 +4,22 @@ require "securerandom"
 module Securial
   module Auth
     module TokenGenerator
-      class << self
-        def generate_refresh_token
-          secret = Securial.configuration.session_secret
-          algo = "SHA256"
+      extend self
 
-          random_data = SecureRandom.hex(32)
-          digest = OpenSSL::Digest.new(algo)
-          hmac = OpenSSL::HMAC.hexdigest(digest, secret, random_data)
+      def generate_refresh_token
+        secret = Securial.configuration.session_secret
+        algo = "SHA256"
 
-          "#{hmac}#{random_data}"
-        end
+        random_data = SecureRandom.hex(32)
+        digest = OpenSSL::Digest.new(algo)
+        hmac = OpenSSL::HMAC.hexdigest(digest, secret, random_data)
 
-        def generate_password_reset_token
-          token = SecureRandom.alphanumeric(12)
-          "#{token[0, 6]}-#{token[6, 6]}"
-        end
+        "#{hmac}#{random_data}"
+      end
+
+      def generate_password_reset_token
+        token = SecureRandom.alphanumeric(12)
+        "#{token[0, 6]}-#{token[6, 6]}"
       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

@@ -0,0 +1,282 @@
+# @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)
+      exit(result) if result
+
+      # Otherwise handle commands
+      exit(handle_commands(argv))
+    end
+
+    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
+
+      begin
+        parser.order!(argv)
+        nil # Continue to command handling
+      rescue OptionParser::InvalidOption => e
+        warn "ERROR: Illegal option(s): #{e.args.join(' ')}"
+        puts parser
+        1
+      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
+
+      case cmd
+      when "new"
+        handle_new_command(argv)
+      else
+        puts create_option_parser
+        1
+      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
+
+      if app_name.nil?
+        puts "ERROR: Please provide an app name."
+        puts create_option_parser
+        return 1
+      end
+
+      securial_new(app_name, argv)
+      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"
+
+        opts.separator ""
+        opts.separator "Commands:"
+        opts.separator "    new APP_NAME [rails_options...]    # Create a new Rails app with Securial pre-installed"
+        opts.separator ""
+        opts.separator "Options:"
+
+        opts.on("-v", "--version", "Show Securial version") do
+          show_version
+          exit(0)
+        end
+
+        opts.on("-h", "--help", "Show this help message") do
+          puts opts
+          exit(0)
+        end
+      end
+    end
+
+    # Displays the current Securial version.
+    #
+    # @return [void]
+    #
+    def show_version
+      require "securial/version"
+      puts "Securial v#{Securial::VERSION}"
+    rescue LoadError
+      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}"
+
+      create_rails_app(app_name, rails_options)
+      add_securial_gem(app_name)
+      install_gems(app_name)
+      install_securial(app_name)
+      mount_securial_engine(app_name)
+      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")
+      routes = File.read(routes_path)
+      updated = routes.sub("Rails.application.routes.draw do") do |match|
+        "#{match}\n  mount Securial::Engine => '/securial'"
+      end
+      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!
+        ✅  Your app is ready at: ./#{app_name}
+
+        ➡️  Next steps:
+            cd #{app_name}
+        ⚙️  Optional: Configure Securial in config/initializers/securial.rb
+            rails server
+      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 =
+        if chdir
+          Dir.chdir(chdir) { system(*command) }
+        else
+          system(*command)
+        end
+
+      unless result
+        abort("❌ Command failed: #{command}")
+      end
+      0
+    end
+  end
+end
+
+# rubocop:enable Rails/Exit, Rails/Output

data/lib/securial/config/signature.rb

@@ -47,7 +47,7 @@ module Securial
 
       def roles_signature
         {
-          admin_role: { type: String, required: true, default: "admin" },
+          admin_role: { type: Symbol, required: true, default: :admin },
         }
       end
 

data/lib/securial/config/validation.rb

@@ -3,68 +3,67 @@ require "securial/logger"
 module Securial
   module Config
     module Validation
-      class << self
-        def validate_all!(securial_config)
-          signature = Securial::Config::Signature.config_signature
+      extend self
+      def validate_all!(securial_config)
+        signature = Securial::Config::Signature.config_signature
 
-          validate_required_fields!(signature, securial_config)
-          validate_types_and_values!(signature, securial_config)
-          validate_password_lengths!(securial_config)
-        end
+        validate_required_fields!(signature, securial_config)
+        validate_types_and_values!(signature, securial_config)
+        validate_password_lengths!(securial_config)
+      end
 
-        private
+      private
 
-        def validate_required_fields!(signature, config)
-          signature.each do |key, options|
-            value = config.send(key)
-            required = options[:required]
-            if required == true && value.nil?
-              raise_error("#{key} is required but not provided.")
-            elsif required.is_a?(String)
-              dynamic_required = config.send(required)
-              signature[key][:required] = dynamic_required
-              if dynamic_required && value.nil?
-                raise_error("#{key} is required but not provided when #{required} is true.")
-              end
+      def validate_required_fields!(signature, config)
+        signature.each do |key, options|
+          value = config.send(key)
+          required = options[:required]
+          if required == true && value.nil?
+            raise_error("#{key} is required but not provided.")
+          elsif required.is_a?(String)
+            dynamic_required = config.send(required)
+            signature[key][:required] = dynamic_required
+            if dynamic_required && value.nil?
+              raise_error("#{key} is required but not provided when #{required} is true.")
             end
           end
         end
+      end
 
-        def validate_types_and_values!(signature, config)
-          signature.each do |key, options|
-            next unless signature[key][:required]
-            value = config.send(key)
-            types = Array(options[:type])
+      def validate_types_and_values!(signature, config)
+        signature.each do |key, options|
+          next unless signature[key][:required]
+          value = config.send(key)
+          types = Array(options[:type])
 
-            unless types.any? { |type| value.is_a?(type) }
-              raise_error("#{key} must be of type(s) #{types.join(', ')}, but got #{value.class}.")
-            end
-
-            if options[:type] == ActiveSupport::Duration && value <= 0
-              raise_error("#{key} must be a positive duration, but got #{value}.")
-            end
+          unless types.any? { |type| value.is_a?(type) }
+            raise_error("#{key} must be of type(s) #{types.join(', ')}, but got #{value.class}.")
+          end
 
-            if options[:type] == Numeric && value < 0
-              raise_error("#{key} must be a non-negative numeric value, but got #{value}.")
-            end
+          if options[:type] == ActiveSupport::Duration && value <= 0
+            raise_error("#{key} must be a positive duration, but got #{value}.")
+          end
 
-            if options[:allowed_values] && options[:allowed_values].exclude?(value)
-              raise_error("#{key} must be one of #{options[:allowed_values].join(', ')}, but got #{value}.")
-            end
+          if options[:type] == Numeric && value < 0
+            raise_error("#{key} must be a non-negative numeric value, but got #{value}.")
           end
-        end
 
-        def validate_password_lengths!(config)
-          if config.password_min_length > config.password_max_length
-            raise_error("password_min_length cannot be greater than password_max_length.")
+          if options[:allowed_values] && options[:allowed_values].exclude?(value)
+            raise_error("#{key} must be one of #{options[:allowed_values].join(', ')}, but got #{value}.")
           end
         end
+      end
 
-        def raise_error(msg)
-          Securial.logger.fatal msg
-          raise Securial::Error::Config::InvalidConfigurationError, msg
+      def validate_password_lengths!(config)
+        if config.password_min_length > config.password_max_length
+          raise_error("password_min_length cannot be greater than password_max_length.")
         end
       end
+
+      def raise_error(msg)
+        Securial.logger.fatal msg
+        raise Securial::Error::Config::InvalidConfigurationError, msg
+      end
     end
   end
 end