rails_iam 0.1.0

data/app/services/rails_iam/authorization/role_checker.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module RailsIam
+  module Authorization
+    class RoleChecker < RailsIam::RailsIamService
+      def initialize(context)
+        super()
+        @context = context
+      end
+
+      def call
+        return true if @context.required_roles.empty?
+
+        success =
+          case @context.role_match
+          when :any
+            (@context.roles.to_a & @context.required_roles).any?
+
+          when :all
+            (@context.required_roles - @context.roles.to_a).empty?
+
+          else
+            raise ArgumentError, "Unknown role_match #{@context.role_match}"
+          end
+
+        return true if success
+
+        raise RailsIam::Authorization::Exceptions::MissingRoleError.new(
+          required: @context.required_roles,
+          actual: @context.roles,
+        )
+      end
+    end
+  end
+end

data/app/services/rails_iam/authorization/role_resolver.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RailsIam
+  module Authorization
+    class RoleResolver < RailsIam::RailsIamService
+      def initialize(user)
+        super()
+        @user = user
+      end
+
+      def call
+        Cache.read_or_write(Cache::ROLES, user.id) do
+          resolve
+        end
+      end
+
+      private
+
+      attr_reader :user
+
+      def resolve
+        user.roles
+            .pluck(:name)
+            .map!(&:to_s)
+            .to_set
+            .freeze
+      end
+    end
+  end
+end

data/app/services/rails_iam/authorization/skip_authorization_rule.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RailsIam
+  module Authorization
+    SkipAuthorizationRule = Data.define(
+      :only,
+      :except,
+    ) do
+      def matches?(action)
+        action = action.to_sym
+
+        return Array(only).map(&:to_sym).include?(action) if only.present?
+        return Array(except).map(&:to_sym).exclude?(action) if except.present?
+
+        true
+      end
+    end
+  end
+end

data/app/services/rails_iam/rails_iam_service.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsIam
+  class RailsIamService < ApplicationService
+    include RailsIam::ConfigLoader
+
+    def self.call(...)
+      new(...).call
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+Rails.application.routes.draw do
+  sign_in_path  = RailsIam.configuration.authentication.sign_in_path
+  sign_out_path = RailsIam.configuration.authentication.sign_out_path
+  refresh_token_path = RailsIam.configuration.authentication.refresh_token_path
+
+  if sign_in_path.present?
+    post sign_in_path,
+         to: "rails_iam/auth#sign_in",
+         as: :rails_iam_sign_in
+  end
+
+  if sign_out_path.present?
+    post sign_out_path,
+         to: "rails_iam/auth#sign_out",
+         as: :rails_iam_sign_out
+  end
+
+  if refresh_token_path.present?
+    post refresh_token_path,
+         to: "rails_iam/auth#refresh",
+         as: :rails_iam_refresh
+  end
+end

data/lib/generators/rails_iam/install_generator.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module RailsIam
+  class InstallGenerator < Rails::Generators::Base
+    include ActiveRecord::Generators::Migration
+
+    source_root File.expand_path("templates", __dir__)
+
+    def copy_migrations
+      say "Copying migration file", :yellow
+      migration_template "create_rails_iam_tables.rb.erb", "db/migrate/create_rails_iam_tables.rb"
+    end
+
+    def create_initializer
+      say "Copying initializer file", :yellow
+      template "initializer.rb", "config/initializers/rails_iam.rb"
+    end
+
+    def show_readme
+      say "\n=======================================================", :yellow
+      say " RailsIam installed successfully!", :green
+      say "=======================================================", :yellow
+      say "Next steps:", :yellow
+      say ""
+      say "1. Open: config/initializers/rails_iam.rb", :green
+      say ""
+      say "2. Configure your user model if you have an existing authentication model:", :green
+      say "   • If you have existing authentication (Devise, Auth0, custom, etc.)", :green
+      say "     - config.user_class = 'User' (or Account, Member, Admin...)", :green
+      say "     - config.current_user_method = :current_user (or :current_account)", :green
+      say "     - Add `acts_as_rails_iam_user` to your user (or Account, Member, Admin...) authentication  model.", :green
+      say ""
+      say "   • If you use RailsIam authentication", :green
+      say "     - Keep the default configuration.", :green
+      say ""
+      say "3. Run: bin/rails db:migrate", :green
+      say ""
+      say "You're ready to start using RailsIam 🚀", :green
+      say "=======================================================\n", :yellow
+    end
+
+    def self.next_migration_number(dirname)
+      ActiveRecord::Generators::Base.next_migration_number(dirname)
+    end
+  end
+end

data/lib/generators/rails_iam/templates/create_rails_iam_tables.rb.erb

@@ -0,0 +1,119 @@
+migration_version = "#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}"
+
+
+class CreateRailsIamTables < ActiveRecord::Migration[migration_version.to_f]
+ 
+  def change
+  
+   primary_key_type = Rails.application.config.generators.options.dig(:active_record, :primary_key_type) || :bigint
+   user_class_name = RailsIam.configuration&.user_class || "RailsIam::User"
+   user_table_name = user_class_name.underscore.pluralize.tr('/', '_')
+
+    create_table :rails_iam_users, id: primary_key_type do |t|
+      t.string :email, index: { unique: true }
+      t.string :password_digest
+
+      # Custom Audit Tracking Columns
+      t.string :created_by
+      t.string :updated_by
+      t.timestamp :deleted_at
+      t.string :deleted_by
+
+      t.timestamps
+    end
+
+    create_table :rails_iam_roles, id: primary_key_type do |t|
+      t.string :name, index: { unique: true }
+      t.text :description
+
+      # Custom Audit Tracking Columns
+      t.string :created_by
+      t.string :updated_by
+      t.timestamp :deleted_at
+      t.string :deleted_by
+
+      t.timestamps
+    end
+
+    create_table :rails_iam_permissions, id: primary_key_type do |t|
+      t.string :code, index: { unique: true }
+      t.text :description
+
+      # Custom Audit Tracking Columns
+      t.string :created_by
+      t.string :updated_by
+      t.timestamp :deleted_at
+      t.string :deleted_by
+
+      t.timestamps
+    end
+
+    create_table :rails_iam_user_roles, id: primary_key_type do |t|
+      t.references :user, null: false, type: primary_key_type, foreign_key: { to_table: user_table_name }
+      t.references :role, null: false, type: primary_key_type, foreign_key: { to_table: :rails_iam_roles }
+
+      # Custom Audit Tracking Columns
+      t.string :created_by
+      t.string :updated_by
+      t.timestamp :deleted_at
+      t.string :deleted_by
+
+      t.timestamps
+    end
+
+
+    create_table :rails_iam_user_permissions, id: primary_key_type do |t|
+      t.references :permission, null: false, type: primary_key_type, foreign_key: { to_table: :rails_iam_permissions }
+      t.references :user, null: false, type: primary_key_type, foreign_key: { to_table: user_table_name }
+
+      # Custom Audit Tracking Columns
+      t.string :created_by
+      t.string :updated_by
+      t.timestamp :deleted_at
+      t.string :deleted_by
+
+      t.timestamps
+    end
+
+    create_table :rails_iam_role_permissions, id: primary_key_type do |t|
+      t.references :permission, null: false, type: primary_key_type, foreign_key: { to_table: :rails_iam_permissions }
+      t.references :role, null: false,  type: primary_key_type, foreign_key: { to_table: :rails_iam_roles }
+
+      # Custom Audit Tracking Columns
+      t.string :created_by
+      t.string :updated_by
+      t.timestamp :deleted_at
+      t.string :deleted_by
+
+      t.timestamps
+    end
+
+    create_table :rails_iam_user_denied_permissions, id: primary_key_type do |t|
+      t.references :permission, null: false, type: primary_key_type,  foreign_key: { to_table: :rails_iam_permissions }
+      t.references :user, null: false, type: primary_key_type,  foreign_key: { to_table: user_table_name }
+
+      # Custom Audit Tracking Columns
+      t.string :created_by
+      t.string :updated_by
+      t.timestamp :deleted_at
+      t.string :deleted_by
+
+      t.timestamps
+    end
+
+    create_table :rails_iam_refresh_tokens, id: primary_key_type do |t|
+      t.references :user, null: false, type: primary_key_type, foreign_key: { to_table: user_table_name }
+      t.string :token_digest, index: { unique: true }
+      t.datetime :expires_at, null: false
+      # to invalidate the token
+      t.datetime :revoked_at 
+      t.datetime :last_used_at
+      # Jti from access token
+      t.string :jti, index: { unique: true } 
+      t.string :ip_address
+      t.string :user_agent
+
+      t.timestamps
+    end
+  end
+end

data/lib/generators/rails_iam/templates/initializer.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+#
+# RailsIam Configuration
+#
+# Use this file to configure how your application handles authentication,
+# authorization scopes, JWT token properties, caching, and error handling.
+#
+RailsIam.configure do |config|
+  # =========================================================================
+  # Host Application Integration
+  # =========================================================================
+
+  # - The class name of your main User/Account model which will be used to login
+  # - It's been used throughout RailsIam for authentication, authorization, associations and user lookup.
+  # - Configure this only if you use a different model
+  #   or you have your own authentication mechanism (devise or jwt/bcrypt)
+  # - Default: 'RailsIam::User'
+  # config.user_class = 'RailsIam::User'
+
+  # - The method name your controllers use to look up the currently active session user.
+  # - Default: :current_user
+  # config.current_user_method = :current_user
+
+  # - The performer method that rails_iam use to track who creates and assign role/permission
+  # - Support symbol and proc
+  # - Default: :email
+  # config.audit_performer_method = :email
+
+  # =========================================================================
+  # Authentication Settings (config.authentication)
+  # =========================================================================
+
+  # - The key used when storing or reading the access token from cookies or parameters.
+  # - Default: 'access_token'
+  # config.authentication.access_token_key = 'access_token'
+
+  # - The key used when storing or reading the long-lived refresh token.
+  # - Default: 'refresh_token'
+  # config.authentication.refresh_token_key = 'refresh_token'
+
+  # - Supported authentication delivery strategies.
+  # - Options: [:cookie], [:bearer], or combined [:cookie, :bearer]
+  # - For :bearer, the gem expects the token in authorization header with `Bearer your_token`
+  # - Default: [:cookie]
+  # config.authentication.authentication_strategies = [:cookie] # httponly
+
+  # - Cookie configuration (Web / Cookie-based Strategy)
+  # - Configure the security and behavior properties for session cookies issued by
+  # - the RailsIam engine. These settings strictly apply when using the :cookie authentication strategy.
+  # - Default: { httponly: true, secure: Rails.env.production?, same_site: :lax, }
+  # config.authentication.cookie_options = { httponly: true, secure: Rails.env.production?, same_site: :lax, }
+
+  # - Refresh Token Transport, only needed if authentication_strategies uses :bearer
+  # - Determines how RailsIam receives the refresh token for
+  #   refresh and sign-out requests when using bearer authentication.
+  # - Will use the same @refresh_token_key to get the header
+  #   i,e: request.get_header(refresh_token_key.upcase) -> HTTP_X_REFRESH_TOKEN
+  # - Options: :header, :request_body
+  # - Default: :header
+  # config.authentication.refresh_token_transport = :header
+
+  # - Session persistence limit strategy.
+  #   [:single] - Forces one active device/session per user at any time (invalidates old tokens).
+  #   [:multi]  - Allows concurrent login sessions across multiple devices or browsers.
+  # - Default: :single
+  # config.authentication.session_strategy = :single
+
+  #
+  # Built-in Authentication Routes
+  #
+  # - Routes exposed by RailsIam when using its built-in authentication
+  #   controllers. Put `nil` if  you don't  want RailsIam to provide
+  #   the HTTP sign-in, sign-out and refresh token endpoints. You don't need to add
+  #   anything to your host application. RailsIam  will map this routes
+  #   to your host application i,e: example.com/auth/sign_in
+  #
+  # You can also:
+  # - Use Devise (or another authentication library) and leave these default nil.
+  # - Build your own authentication controllers and use RailsIam's
+  #   JWT encoder/decoder, refresh token services, or login/logout
+  #   services without exposing the built-in routes.
+  # - Mix both approaches (e.g. use RailsIam's sign-in route but your
+  #   own sign-out route).
+  # - Use nil if your application already have authentication routes
+  # config.authentication.sign_in_path = '/auth/sign_in'
+  # config.authentication.sign_out_path = '/auth/sign_out'
+  # config.authentication.refresh_token_path = '/auth/refresh
+
+  # - Lifespan for the Access Token used to set httponly cookie expiration
+  # - Keep the value sync jwt expiry time
+  # - Default: 15.minutes
+  # config.authentication.access_token_expires_in = 15.minutes
+
+  # - Lifespan for the Refresh Token used to request replacement access tokens.
+  # - Default: 30.days
+  # config.authentication.refresh_token_expires_in = 30.days
+
+  # - Custom system error messages emitted during authentication edge cases.
+  # - Configure the error messages if you need different messages
+  # config.authentication.token_error          = 'The provided authentication token is invalid or malformed.'
+  # config.authentication.token_expired_error  = 'The authentication token has expired. Please re-authenticate.'
+  # config.authentication.authentication_error = 'Invalid email or password.'
+  # config.authentication.authentication_strategy_error = 'Unknown authentication strategy. Please configure it from rails_iam initializer'
+  # config.authentication.session_strategy_error = 'Unknown session strategy. Please configure it from rails_iam initializer'
+  # config.authentication.refresh_token_transport_error = 'Unknown refresh token transport. Please configure it from rails_iam initializer'
+
+  # =========================================================================
+  # Authorization & Cache Settings (config.authorization)
+  # =========================================================================
+
+  # - Custom formatters for policy denial messaging.
+  # - Accepts plain Strings, dynamic blocks, or Lambdas with positional keywords.
+  #
+  # config.authorization.missing_role_error = lambda do |required:, actual:|
+  #   "Missing roles: #{required}. You only have: #{actual}"
+  # end
+  #
+  # config.authorization.missing_permission_error = lambda do |required:|
+  #   "Missing permission(s): #{required.join(', ')}"
+  # end
+
+  # - Error message if permission is not applied on endpoint
+  # - Example: No authorization rule for users#show
+  # config.authorization.authorization_rule_error = "No authorization rule for "
+
+  # - The store engine to cache resolved roles and permissions queries for low DB footprints.
+  # - Default: Rails.cache
+  # config.authorization.cache_store = Rails.cache
+
+  # - Lifespan duration for records cached within the authorization engine layer.
+  # - Default: 15.minutes
+  # config.authorization.cache_ttl = 15.minutes
+
+  # - Controller namespaces excluded from automatic authorization.
+  # - Use this when a third-party library or Rails engine (such as Devise, or another mounted engine) provides controllers
+  # - that inherit from your ApplicationController but should not be subject to RailsIam authorization.
+  # - Example: [/\ADevise::/, /\ARailsIam::/]
+  # - Default []
+  # config.authorization.excluded_controller_patterns = []
+
+  # =========================================================================
+  # JWT Cryptography Settings (config.jwt)
+  # =========================================================================
+
+  # - Secret verification string used to sign security tokens.
+  # - Default: ENV['JWT_SECRET'] or Rails.application.secret_key_base
+  # config.jwt.secret = ENV['JWT_SECRET']
+
+  # - Digital signature algorithm category mapping.
+  # - Default: 'HS256'
+  # config.jwt.algorithm = 'HS256'
+
+  # - Jwt expiry, default to 15 minutes, same as access token in cookie expiry
+  # config.jwt.jwt_expires_in = 15.minutes
+
+  # - Optional security claim validations (RFC 7519 standard targets).
+  # - Leave nil to disable strict validation checks.
+  # - You can also dynamically set them in `extra_claims` at `JwtEncoder`
+  # config.jwt.issuer   = 'https://yourdomain.com'
+  # config.jwt.audience = 'your_application_client_id'
+end

data/lib/rails_iam/config/authentication.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RailsIam
+  module Config
+    class Authentication
+      attr_accessor :access_token_key,
+                    :refresh_token_key,
+                    :authentication_strategies,
+                    :session_strategy,
+                    :sign_in_path,
+                    :sign_out_path,
+                    :refresh_token_path,
+                    :refresh_token_transport,
+                    :access_token_expires_in,
+                    :refresh_token_expires_in,
+                    :token_error,
+                    :token_expired_error,
+                    :authentication_error,
+                    :authentication_strategy_error,
+                    :session_strategy_error,
+                    :refresh_token_transport_error,
+                    :cookie_options
+
+      def initialize
+        # The key used when storing or reading the access token from cookies or parameters.
+        @access_token_key = "access_token"
+
+        # The key used when storing or reading the long-lived refresh token.
+        @refresh_token_key = "refresh_token"
+
+        # Authentication Strategy
+        # Supported: [:cookie], [:bearer], or combined [:cookie, :bearer]
+        @authentication_strategies = %i[cookie]
+
+        # Session Strategy, allowing user to login from multiple device at the same time
+        # Supported: :single || :multi
+        @session_strategy = :single
+
+        # Determines how RailsIam receives the refresh token for :bearer strategy
+        # Supported: :header || :request_body
+        @refresh_token_transport = :header
+
+        # Authentication Endpoints
+        @sign_in_path = "/auth/sign_in"
+        @sign_out_path = "/auth/sign_out"
+        @refresh_token_path = "/auth/refresh"
+
+        # expiry for access token
+        @access_token_expires_in = 15.minutes
+        @refresh_token_expires_in = 30.days
+
+        # cookie options
+        @cookie_options = { httponly: true, secure: Rails.env.production?, same_site: :lax }.freeze
+
+        # Authentication Messages
+        @token_error = "The provided authentication token is invalid or malformed."
+        @token_expired_error = "The authentication token has expired. Please re-authenticate."
+        @authentication_error = "Invalid email or password."
+        @authentication_strategy_error = "Unknown authentication strategy. Please configure it from rails_iam initializer"
+        @session_strategy_error = "Unknown session strategy. Please configure it from rails_iam initializer"
+        @refresh_token_transport_error = "Unknown refresh token transport. Please configure it from rails_iam initializer"
+      end
+    end
+  end
+end

data/lib/rails_iam/config/authorization.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RailsIam
+  module Config
+    class Authorization
+      attr_accessor :missing_role_error,
+                    :missing_permission_error,
+                    :authorization_rule_error,
+                    :cache_store,
+                    :cache_ttl,
+                    :excluded_controller_patterns
+
+      def initialize
+        # Accepts plain Strings, dynamic blocks, or Lambdas with positional keywords.
+        @missing_role_error = lambda do |required:, actual:|
+          "Missing roles: #{required.join(', ')}. You only have: #{actual.join(', ')}"
+        end
+
+        @missing_permission_error = lambda do |required:|
+          "Missing permission(s): #{required.join(', ')}"
+        end
+
+        @authorization_rule_error = "No authorization rule applied for"
+
+        # The store engine to cache resolved roles and permissions queries for low DB footprints.
+        @cache_store = Rails.cache
+        @cache_ttl = 15.minutes
+
+        # Useful for third-party gems and mounted engines (e.g. Devise)
+        # whose controllers inherit from ApplicationController but
+        # should bypass RailsIam authorization.
+        @excluded_controller_patterns = []
+      end
+    end
+  end
+end

data/lib/rails_iam/config/jwt.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RailsIam
+  module Config
+    class Jwt
+      attr_accessor :secret,
+                    :algorithm,
+                    :issuer,
+                    :audience,
+                    :jwt_expires_in
+
+      def initialize
+        # Secret verification string used to sign security tokens.
+        @secret = ENV["JWT_SECRET"].presence || Rails.application&.secret_key_base
+
+        # Digital signature algorithm category mapping.
+        @algorithm = "HS256"
+        @jwt_expires_in = 15.minutes
+
+        # Optional security claim validations (RFC 7519 standard targets).
+        # Leave nil to disable strict validation checks.
+        @issuer = nil
+        @audience = nil
+      end
+    end
+  end
+end

data/lib/rails_iam/configuration.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RailsIam
+  class Configuration
+    attr_reader :authorization, :jwt, :authentication
+
+    attr_accessor :user_class, :current_user_method, :audit_performer_method
+
+    def initialize
+      # Each concern has its own configuration object to keep the
+      @authorization = RailsIam::Config::Authorization.new
+      @jwt = RailsIam::Config::Jwt.new
+      @authentication = RailsIam::Config::Authentication.new
+
+      # Host Application User Model, defaults to RailsIam::User
+      # Used throughout RailsIam for authentication, authorization associations, and user lookup.
+      @user_class = "RailsIam::User"
+
+      # Current User Resolver, defaults to current_user
+      # Method used by RailsIam to obtain the authenticated user when
+      # the host application already manages authentication (e.g. Devise,)
+      @current_user_method = :current_user
+
+      # Audit performer method
+      # Used to audit who created/assigned what permission
+      # support symbol both symbol and proc i,e ->(user) { "#{user.id}:#{user.username}" }
+      @audit_performer_method = :email
+    end
+  end
+end

data/lib/rails_iam/controller_dsl.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RailsIam
+  module ControllerDsl
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def rails_iam(*features)
+        features.each do |feature|
+          case feature.to_sym
+          when :authentication
+            include RailsIam::Authentication::Authenticatable
+
+            install_authentication_rescue_handler
+
+          when :authorization
+            include RailsIam::Authorization::Authorizable
+
+            install_authorization_rescue_handler
+          else
+            raise ArgumentError, "Unknown RailsIam feature: #{feature.inspect}, only support :authentication and :authorization"
+          end
+        end
+      end
+
+      private
+
+      def install_authentication_rescue_handler
+        rescue_from RailsIam::Authentication::Exceptions::AuthenticationError do |exception|
+          render_rails_iam_authentication_error(exception)
+        end
+      end
+
+      def install_authorization_rescue_handler
+        rescue_from RailsIam::Authorization::Exceptions::AuthorizationError do |exception|
+          render_rails_iam_authorization_error(exception)
+        end
+      end
+    end
+  end
+end