rails_iam 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bd559a06706a5935fa65efc0ddcf6441d82ed991ab95e02849f7eec59ae4a86f
+  data.tar.gz: ab21b61c3936c671742bdba0eeac35ca7676d0514d24f8d767c00832551ac0f5
+SHA512:
+  metadata.gz: 6c8fb9c39a9aaae9c15ef39c0be553f7fe6ffa9e271e5d05fb91ba73e29cc46bd9bf58a832e5a0c8e8b16a8a068530da53ed69c4a9bb8aa828486fc6c9807ed7
+  data.tar.gz: 7354acf8d1b2aa9d90355674350d853bc176e3242bd1ed2df90170b4f0f91041c78f375a8dfb686d786c4efe551f989f3b46b0f3ff9a2640816a03de9b80076e

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-08-06
+
+### Added
+
+- JWT authentication
+- Refresh token authentication
+- Access token authentication via HttpOnly cookies
+- Access token authentication via Bearer tokens
+- Refresh token rotation
+- Database-driven RBAC (Role-Based Access Control)
+- PBAC (Permission-Based Access Control)
+- Direct user permissions
+- User denied permissions
+- Automatic permission inference with `authorize_resource`
+- Endpoint-first authorization
+- Authorization caching
+- Authentication and authorization generators
+- RSpec testing guide
+- Comprehensive Wiki documentation

data/CONTRIBUTING.md

@@ -0,0 +1,145 @@
+# Contributing to RailsIAM
+
+First of all, thank you for your interest in contributing to RailsIAM! 🎉
+
+Whether you're reporting a bug, improving documentation, fixing a typo, or implementing a new feature, your contribution is greatly appreciated.
+
+## Before You Start
+
+Please check the existing:
+
+- [Issues](https://github.com/salmanx/rails_iam/issues)
+- [Pull Requests](https://github.com/salmanx/rails_iam/pulls)
+
+to make sure your idea or bug hasn't already been discussed.
+
+If you're planning a significant feature or architectural change, please open an issue first so we can discuss the design before implementation.
+
+---
+
+# Reporting Bugs
+
+When opening a bug report, please include as much information as possible:
+
+- Rails version
+- Ruby version
+- RailsIAM version
+- Authentication strategy
+- Database adapter
+- Steps to reproduce
+- Expected behavior
+- Actual behavior
+- A minimal reproducible example if possible
+
+---
+
+# Feature Requests
+
+RailsIAM aims to remain simple, predictable, and database-driven.
+
+If you'd like to propose a new feature:
+
+1. Open an issue describing the problem you're trying to solve.
+2. Explain your proposed solution.
+3. Wait for discussion before starting implementation.
+
+Features that increase complexity without broad usefulness may not be accepted.
+
+---
+
+# Documentation
+
+Documentation improvements are always welcome.
+
+This includes:
+
+- README improvements
+- Wiki pages
+- API examples
+- Typo fixes
+- Better explanations
+- Additional authorization examples
+
+---
+
+# Development
+
+Clone the repository:
+
+```bash
+git clone https://github.com/salmanx/rails_iam.git
+cd rails_iam
+```
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+Please ensure all tests pass before submitting a Pull Request.
+
+---
+
+# Pull Requests
+
+Please follow these guidelines:
+
+- Create a new branch from `main`
+- Keep Pull Requests focused on a single change
+- Follow the existing coding style
+- Add or update tests when applicable
+- Update documentation when behavior changes
+- Update the CHANGELOG for user-facing changes
+- Keep commit messages clear and descriptive
+
+Example:
+
+```
+Add support for custom authorization strategies
+```
+
+---
+
+# Code Style
+
+Please follow the existing project conventions:
+
+- Follow Ruby and Rails style guidelines
+- Prefer small, focused classes
+- Keep public APIs backward compatible whenever possible
+- Write expressive, readable code
+
+---
+
+# Testing
+
+Every new feature or bug fix should include appropriate tests whenever possible.
+
+RailsIAM uses RSpec for testing.
+
+---
+
+# Versioning
+
+Please do **not** update the gem version in your Pull Request.
+
+Version numbers are managed by the project maintainers during release.
+
+---
+
+# Questions
+
+If something isn't clear, feel free to open a GitHub Discussion or Issue.
+
+Constructive feedback and questions are always welcome.
+
+---
+
+Thank you for helping make RailsIAM better! 🚀

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright Salman Mahmud
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,192 @@
+# RailsIAM
+
+JWT • RBAC • PBAC • IAM • Roles • Permissions
+
+RailsIAM is a database-driven Identity & Access Management (IAM) engine for your Rails applications. It follows an endpoint-first authorization model where permissions are treated as data, not code. Roles and permission assignments are stored in the database, allowing access control to evolve without changing authorization logic. RailsIAM includes an optional JWT authentication implementation for applications that need it, while its authorization layer works with Devise or any authentication system capable of providing the authenticated user.
+
+## Why RailsIAM exists?
+
+RailsIAM is not trying to reinvent authentication or authorization.
+
+The Rails ecosystem already has excellent solutions for these problems. You can build authentication yourself, use Devise, write your own authorization layer, or choose from several existing gems.
+
+RailsIAM exists for a different reason: **to save your time from rebuilding the same foundation every time.**
+
+Every Rails application eventually needs the same building blocks:
+
+- Who is the authenticated user?
+- What roles does this user have?
+- What permissions should they have?
+- Which controller actions can they access?
+- How do we manage access changes without touching application code or redeploying the application?
+- Who gives permissions to whom?
+
+RailsIAM gives you that foundation out of the box, so team can focus on building business features instead of spending **_another sprint works_** wiring authentication, roles, permissions, database relationships, authorization checks, auditing and error handling.
+
+## How to use it?
+
+Most Rails applications eventually need to answer one important question:
+
+> **_"Is this authenticated user allowed to perform this action?"_**
+
+With RailsIAM, authorization is declared at the point where requests enter application — controller actions. There are no policy classes to maintain, no authorization logic scattered across models, and no condition-heavy permission checks inside controllers.
+
+Once roles and permissions are stored in the database, protecting an action becomes as simple as declaring who can access it.
+
+Whether team building an API-only application or a traditional Rails application with server-rendered views, RailsIAM keeps authorization rules explicit, centralized, and independent from authentication strategy.
+
+### Role-based authorization
+
+Allow administrators to access every action in the controller.
+
+```ruby
+class UsersController < ApplicationController
+
+  # admin role can access to *all* the actions
+  authorize roles: :admin
+
+end
+```
+
+---
+
+### Permission-based authorization
+
+Protect a single endpoint using a permission stored in the database. No matter what your role is.
+
+```ruby
+class UsersController < ApplicationController
+
+  # people who has "user:show" permission can access to show action
+  authorize permissions: "user:show", only: :show
+
+  def show; end
+end
+```
+
+Some endpoints should remain publicly accessible while the rest of the controller requires authorization.
+
+```ruby
+class ProductsController < ApplicationController
+
+  authorize permissions: "product:manage", except: [:index, :show]
+
+  def index; end      # Public
+  def show; end       # Public
+  def create; end     # Requires product:manage
+end
+```
+
+---
+
+### Role + Permission
+
+Require both a specific role **and** a permission.
+
+This is useful when only members of a department should be able to perform an operation, even if another role happens to own the same permission.
+
+```ruby
+class UsersController < ApplicationController
+  # admin and manager roles can access to all the action
+  authorize roles: [:admin, :manager]
+  # sales role can only access to :show
+  authorize roles: :sales, permissions: "user:show", only: :show
+
+  def show; end
+end
+```
+
+---
+
+### Convention over configuration
+
+Rails IAM can infer the required permission directly from the controller and action.
+
+```ruby
+class UsersController < ApplicationController
+
+  authorize_resource
+end
+```
+
+The following permissions will automatically be checked:
+
+```
+| Controller Action | Required Permission |
+  (UsersController) |
+| ----------------- | ------------------- |
+| index             | user:index          |
+| show              | user:show           |
+| create            | user:create         |
+| update            | user:update         |
+| destroy           | user:destroy        |
+| send_invite       | user:send_invite    |
+```
+
+Namespaced controllers are also supported.
+
+```text
+Admin::Users::CustomersController#show -> admin_users_customer:show
+```
+
+---
+
+### Skip authorization
+
+Skip authorization for an entire controller.
+
+```ruby
+skip_authorization
+```
+
+Or only for selected actions.
+
+```ruby
+skip_authorization only: :sign_up
+```
+
+More example [here](https://github.com/salmanx/rails_iam/wiki/Authorization-Rules).
+
+---
+
+That's it.
+
+👉 No policy objects.
+
+👉 No permission checks inside your controller actions.
+
+👉 No authorization logic inside models.
+
+Our controllers and models stay focused on handling requests and business logic of our application, while RailsIAM takes care of deciding **who is allowed to access them**.
+
+## So what RailsIAM brings to us?
+
+- **Production-ready out of the box** — Install a single gem to get jwt based authentication and authorization with Role-Based Access Control (RBAC) and Permission-Based Access Control (PBAC).
+
+- **Authorization where it belongs** — Declare access rules at the controller level, where requests enter application. Keep controllers focused on business logic and models focused on persistence.
+
+- **No authorization logic scattered across your application** — No policy classes, no permission checks inside controller actions, and no complex conditional logic in models.
+
+- **Permissions are data, not code** — Roles and permissions live in the database, allowing administrators to grant, revoke, or reorganize access without changing application code.
+
+- **Change permissions without deployments** — Updating who can access an endpoint doesn't require modifying Ruby files or redeploying the application.
+
+- **Convention over configuration** — Automatically infer permissions from controller and action names with `authorize_resource`, while still allowing explicit rules whenever needed.
+
+- **Authentication is optional** — Use the built-in JWT authentication for API applications, or keep your existing authentication solution such as Devise. RailsIAM's authorization layer works independently and supports both API-only and traditional Rails (ERB/HTML) applications.
+
+- **Highly configurable** — Customize model names, current user methods, JWT settings, cookies, cache, localization, error messages, and other behaviors to fit your application's conventions.
+
+## Continue Reading
+
+- [Getting Started](https://github.com/salmanx/rails_iam/wiki)
+- [Authentication](https://github.com/salmanx/rails_iam/wiki/Authentication)
+- [Authorization](https://github.com/salmanx/rails_iam/wiki/Authorization)
+- [Authorization Rules](https://github.com/salmanx/rails_iam/wiki/Authorization-Rules)
+- [Configuration](https://github.com/salmanx/rails_iam/wiki/Configuration)
+- [Testing Controller and Request Authorization](https://github.com/salmanx/rails_iam/wiki/Testing-Controller-and-Request-Authorization)
+- [With devise and traditional rails](https://github.com/salmanx/rails_iam/wiki/With-devise-and-traditional-rails)
+
+## Contributing
+
+Please read the [Contributing Guidelines](https://github.com/salmanx/rails_iam/blob/main/CONTRIBUTING.md).

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+# load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec

data/app/controllers/concerns/rails_iam/auth_concern.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module RailsIam
+  module AuthConcern
+    extend ActiveSupport::Concern
+
+    def extract_refresh_token_from_header
+      header_key = "HTTP_#{refresh_token_key.upcase}"
+
+      request.get_header(header_key)
+    end
+
+    def extract_refresh_token_from_cookie
+      request.cookie_jar.encrypted[refresh_token_key]
+    end
+
+    def current_refresh_token
+      return unless (refresh_token = extract_refresh_token)
+
+      digest = Digest::SHA256.hexdigest(refresh_token)
+      RailsIam::RefreshToken.find_by(token_digest: digest)
+    end
+
+    def extract_refresh_token
+      if authentication_strategies.include?(:cookie)
+        token = extract_refresh_token_from_cookie
+        return token if token.present?
+      end
+
+      case refresh_token_transport
+      when :header
+        extract_refresh_token_from_header
+
+      when :request_body
+        params[:refresh_token]
+
+      else
+        raise RailsIam::Authentication::Exceptions::AuthenticationError, refresh_token_transport_error
+      end
+    end
+
+    def render_rails_iam_authorization_error(exception)
+      render json: {
+        message: exception.message,
+        code: "forbidden".upcase,
+        status: 403,
+        url: request.original_fullpath,
+      }, status: :forbidden
+    end
+
+    def render_rails_iam_authentication_error(exception)
+      render json: {
+        message: exception.message,
+        code: "unauthorized".upcase,
+        status: 401,
+        url: request.original_fullpath,
+      }, status: :unauthorized
+    end
+  end
+end

data/app/controllers/concerns/rails_iam/authentication/authenticatable.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RailsIam
+  module Authentication
+    module Authenticatable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :skip_authentication_rules, instance_accessor: false, default: []
+
+        before_action :authenticate!
+      end
+
+      class_methods do
+        def skip_authentication(only: nil, except: nil)
+          self.skip_authentication_rules += [
+            RailsIam::Authentication::SkipAuthenticationRule.new(
+              only: only,
+              except: except,
+            ),
+          ]
+        end
+      end
+
+      def current_user
+        RailsIam::Authentication::Current.user
+      end
+
+      private
+
+      def authenticate!
+        return if skip_authentication?
+
+        RailsIam::Authentication::Current.user = RailsIam::Authentication::Authenticator.call(request)
+      end
+
+      def skip_authentication?
+        self.class.skip_authentication_rules.any? do |rule|
+          rule.matches?(action_name)
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/rails_iam/authorization/authorizable.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module RailsIam
+  module Authorization
+    module Authorizable
+      extend ActiveSupport::Concern
+      include RailsIam::AuthConcern
+      include RailsIam::ConfigLoader
+
+      included do
+        class_attribute :authorization_rules, instance_accessor: false, default: []
+        class_attribute :skip_authorization_rules, instance_accessor: false, default: []
+        class_attribute :resource_authorization_enabled, instance_accessor: false, default: false
+        before_action :run_authorization!
+        rescue_from RailsIam::Authorization::Exceptions::AuthorizationError, with: :render_rails_iam_authorization_error
+        rescue_from RailsIam::Authentication::Exceptions::AuthenticationError, with: :render_rails_iam_authentication_error
+      end
+
+      class_methods do
+        def authorize_resource
+          self.resource_authorization_enabled = true
+        end
+
+        def authorize(
+          roles: [],
+          permissions: [],
+          role_match: :any,
+          permission_match: :all,
+          only: nil,
+          except: nil
+        )
+          self.authorization_rules += [
+            RailsIam::Authorization::AuthorizationRule.new(
+              roles: Array(roles),
+              permissions: Array(permissions),
+              role_match: role_match,
+              permission_match: permission_match,
+              only: only,
+              except: except,
+            ),
+          ]
+        end
+
+        def skip_authorization(only: nil, except: nil)
+          self.skip_authorization_rules += [
+            RailsIam::Authorization::SkipAuthorizationRule.new(
+              only: only,
+              except: except,
+            ),
+          ]
+        end
+      end
+
+      private
+
+      def run_authorization!
+        return if skip_authorization?
+
+        user = current_authenticated_user
+
+        authorize_any!(authorization_rules!, user)
+      end
+
+      def authorize_any!(rules, user)
+        last_error = nil
+
+        rules.each do |rule|
+          authorize!(
+            **rule.authorizer_arguments(
+              inferred_permission: inferred_permission_for(rule),
+            ),
+            user: user,
+          )
+
+          return true
+        rescue RailsIam::Authorization::Exceptions::AuthorizationError => e
+          last_error = e
+        end
+
+        raise(last_error || RailsIam::Authorization::Exceptions::AuthorizationError.new)
+      end
+
+      def current_authenticated_user
+        user_method = RailsIam.configuration.current_user_method
+
+        raise RailsIam::Authentication::Exceptions::AuthenticationError, token_error unless respond_to?(user_method, true)
+
+        user = public_send(user_method)
+
+        raise RailsIam::Authentication::Exceptions::AuthenticationError, token_error if user.nil?
+
+        RailsIam::Authentication::Current.user ||= user
+      end
+
+      def authorization_rules!
+        rules = authorization_rules.select(&:valid?)
+
+        rules << inferred_authorization_rule if self.class.resource_authorization_enabled
+
+        return rules if rules.any?
+
+        raise RailsIam::Authorization::Exceptions::AuthorizationError,
+              authorization_rule_error
+      end
+
+      def authorize!(
+        user:, required_roles: [],
+        required_permissions: [],
+        role_match: :any,
+        permission_match: :all,
+        inferred_permission: nil
+      )
+        RailsIam::Authorization::Authorizer.call(
+          user: user,
+          required_roles: required_roles,
+          required_permissions: required_permissions,
+          inferred_permission: inferred_permission,
+          role_match: role_match,
+          permission_match: permission_match,
+        )
+      end
+
+      def authorization_rules
+        self.class.authorization_rules.select do |rule|
+          rule.matches?(action_name)
+        end
+      end
+
+      def skip_authorization?
+        excluded_controller? || skipped_action?
+      end
+
+      def skipped_action?
+        self.class.skip_authorization_rules.any? do |rule|
+          rule.matches?(action_name)
+        end
+      end
+
+      def excluded_controller?
+        (excluded_controller_patterns || []).any? do |pattern|
+          self.class.name.match?(pattern)
+        end
+      end
+
+      def inferred_authorization_rule
+        RailsIam::Authorization::AuthorizationRule.new(
+          roles: [],
+          permissions: [inferred_permission],
+          role_match: :any,
+          permission_match: :all,
+          only: nil,
+          except: nil,
+        )
+      end
+
+      def inferred_permission
+        resource =
+          self.class.controller_path
+              .tr("/", "_")
+              .singularize
+
+        "#{resource}:#{action_name}"
+      end
+
+      def inferred_permission_for(rule)
+        rule.permissions.any? ? nil : inferred_permission
+      end
+    end
+  end
+end

data/app/controllers/rails_iam/application_controller.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RailsIam
+  # or ActionController::Base
+  class ApplicationController < ActionController::API
+  end
+end