access_grant 1.0.0

data/lib/access_grant/recovery.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module AccessGrant
+  # Ops lockout recovery used by +rake access_grant:grant_role+.
+  #
+  # Override via {AccessGrant::Configuration#recover_access}.
+  module Recovery
+    module_function
+
+    # Grant a named role (or Owner) to a user by id.
+    #
+    # When +role_name+ matches {AccessGrant::Configuration#owner_role_name}
+    # (case-insensitive) and Owner is enabled, delegates to
+    # {AccessGrant::Owner.grant_owner!}.
+    #
+    # @param role_name [String, Symbol]
+    # @param user_id [Integer]
+    # @param tenant_id [Integer, nil] required in multi-tenant mode
+    # @return [AccessGrant::Role]
+    # @raise [AccessGrant::Error]
+    def grant_role!(role_name:, user_id:, tenant_id: nil)
+      user = user_class.find(user_id)
+
+      if owner_role_request?(role_name)
+        tenant = resolve_tenant_for_owner!(tenant_id)
+        return Owner.grant_owner!(user, tenant: tenant)
+      end
+
+      ensure_tenant_id_for_role!(tenant_id)
+      role = find_role!(role_name, tenant_id: tenant_id)
+      user.roles << role unless user.roles.exists?(id: role.id)
+      role
+    end
+
+    def owner_role_request?(role_name)
+      return false if AccessGrant.config.owner_role == :none
+
+      role_name.to_s.casecmp?(AccessGrant.config.owner_role_name.to_s)
+    end
+    private_class_method :owner_role_request?
+
+    def user_class
+      AccessGrant.config.user_class.constantize
+    end
+    private_class_method :user_class
+
+    def resolve_tenant_for_owner!(tenant_id)
+      if multi_tenant?
+        raise Error, "tenant_id is required in multi-tenant mode" if tenant_id.nil?
+
+        tenant_class.find(tenant_id)
+      else
+        raise Error, "tenant_id must not be supplied in single-tenant mode" unless tenant_id.nil?
+
+        nil
+      end
+    end
+    private_class_method :resolve_tenant_for_owner!
+
+    def ensure_tenant_id_for_role!(tenant_id)
+      if multi_tenant?
+        raise Error, "tenant_id is required in multi-tenant mode" if tenant_id.nil?
+      else
+        raise Error, "tenant_id must not be supplied in single-tenant mode" unless tenant_id.nil?
+      end
+    end
+    private_class_method :ensure_tenant_id_for_role!
+
+    def find_role!(role_name, tenant_id:)
+      role = Role.where(tenant_id: tenant_id)
+                 .where("LOWER(name) = ?", role_name.to_s.downcase)
+                 .first
+      raise Error, "Role not found: #{role_name.inspect}" unless role
+
+      role
+    end
+    private_class_method :find_role!
+
+    def multi_tenant?
+      tenant_class_name = AccessGrant.config.tenant_class
+      !(tenant_class_name.nil? || tenant_class_name.to_s.empty?)
+    end
+    private_class_method :multi_tenant?
+
+    def tenant_class
+      AccessGrant.config.tenant_class.constantize
+    end
+    private_class_method :tenant_class
+  end
+end

data/lib/access_grant/sync.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module AccessGrant
+  # Upserts the in-memory catalog into the permissions table.
+  #
+  # Never deletes orphaned DB keys. For +:protected+ / +:both+, re-attaches
+  # every permission key to Owner-named roles.
+  #
+  # Invoked by +rake access_grant:sync_permissions+.
+  class Sync
+    # @api private
+    REATTACH_OWNER_MODES = %i[protected both].freeze
+
+    # Persist catalog entries (description/category) and optionally reattach
+    # Owner permissions.
+    #
+    # @param catalog [AccessGrant::Catalog]
+    # @return [void]
+    def self.call(catalog: AccessGrant.catalog)
+      ActiveRecord::Base.transaction do
+        catalog.entries.each do |entry|
+          permission = Permission.find_or_initialize_by(key: entry.fetch(:key))
+          permission.description = entry[:description]
+          permission.category = entry[:category]
+          permission.save!
+        end
+
+        reattach_owner_permissions! if reattach_owner?
+      end
+    end
+
+    # @api private
+    def self.replace_role_permissions!(role, keys)
+      normalized = Array(keys).map { |key| PermissionKey.normalize!(key) }
+
+      Role.transaction do
+        resolved = resolve_permissions!(normalized)
+        role.role_permissions.delete_all
+        resolved.each do |permission|
+          RolePermission.create!(role_id: role.id, permission_id: permission.id)
+        end
+      end
+    end
+    private_class_method :replace_role_permissions!
+
+    def self.resolve_permissions!(keys)
+      keys.map do |key|
+        Permission.find_by(key: key) || raise(Error, "Unknown permission key: #{key.inspect}")
+      end
+    end
+    private_class_method :resolve_permissions!
+
+    def self.reattach_owner?
+      REATTACH_OWNER_MODES.include?(AccessGrant.config.owner_role)
+    end
+    private_class_method :reattach_owner?
+
+    def self.reattach_owner_permissions!
+      owner_name = AccessGrant.config.owner_role_name.to_s
+      keys = Permission.pluck(:key)
+
+      Role.where("LOWER(name) = ?", owner_name.downcase).find_each do |role|
+        replace_role_permissions!(role, keys)
+      end
+    end
+    private_class_method :reattach_owner_permissions!
+  end
+end

data/lib/access_grant/tenant.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module AccessGrant
+  # Mixed into the host tenant model via +access_grant :tenant+.
+  #
+  # Provides +has_many :roles+, {#grant_owner!}, {#revoke_owner!}, and
+  # optional {AccessGrant::Configuration#on_tenant_created} after create.
+  module Tenant
+    # @api private
+    def self.included(base)
+      base.has_many :roles,
+                    class_name: "AccessGrant::Role",
+                    foreign_key: :tenant_id,
+                    dependent: :destroy,
+                    inverse_of: :tenant
+
+      base.after_create :access_grant_invoke_on_tenant_created
+    end
+
+    # Grant the Owner role for this tenant to +user+.
+    #
+    # @param user [Object] host user with +access_grant :user+
+    # @return [AccessGrant::Role]
+    # @raise [AccessGrant::Error]
+    # @see AccessGrant::Owner.grant_owner!
+    def grant_owner!(user)
+      Owner.grant_owner!(user, tenant: self)
+    end
+
+    # Revoke Owner from +user+ for this tenant.
+    #
+    # @param user [Object]
+    # @return [void]
+    # @raise [AccessGrant::Error] last Owner cannot be revoked
+    # @see AccessGrant::Owner.revoke_owner!
+    def revoke_owner!(user)
+      Owner.revoke_owner!(user, tenant: self)
+    end
+
+    private
+
+    def access_grant_invoke_on_tenant_created
+      callback = AccessGrant.config.on_tenant_created
+      callback&.call(self)
+    end
+  end
+end

data/lib/access_grant/user.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module AccessGrant
+  # Mixed into the host user model via +access_grant :user+.
+  #
+  # Provides HABTM +:roles+ and {#permitted?}.
+  module User
+    # @api private
+    def self.included(base)
+      configure_roles_association(base)
+      base.class_eval do
+        private
+
+        def access_grant_ensure_can_remove_role(role)
+          AccessGrant::Owner.ensure_can_remove_assignment!(role)
+        end
+      end
+    end
+
+    def self.configure_roles_association(base)
+      base.has_and_belongs_to_many :roles,
+                                   class_name: "AccessGrant::Role",
+                                   join_table: AccessGrant.config.tables.fetch(:user_roles),
+                                   foreign_key: :user_id,
+                                   association_foreign_key: :role_id,
+                                   before_remove: :access_grant_ensure_can_remove_role
+    end
+    private_class_method :configure_roles_association
+
+    # Capability check: does this user have +key+ via any role in scope?
+    #
+    # Multi-tenant (+tenant_class+ set): +tenant:+ is required.
+    # Single-tenant: omit +tenant:+ (raises if supplied).
+    #
+    # Unknown or malformed keys raise in all Owner modes (including bypass).
+    # With +:bypass+ / +:both+, having the Owner role short-circuits to +true+
+    # after the key is validated.
+    #
+    # @param key [String, Symbol] +resource.action+
+    # @param tenant [Object, nil] tenant record responding to +id+
+    # @return [Boolean]
+    # @raise [AccessGrant::Error] malformed key, unknown key, or bad tenant args
+    def permitted?(key, tenant: nil)
+      normalized = PermissionKey.normalize!(key)
+
+      raise Error, "Unknown permission key: #{normalized.inspect}" unless Permission.exists?(key: normalized)
+
+      scoped_roles = roles_for_tenant(tenant)
+      return true if owner_bypass?(scoped_roles)
+
+      scoped_roles.joins(:permissions).merge(Permission.where(key: normalized)).exists?
+    end
+
+    private
+
+    def roles_for_tenant(tenant)
+      if multi_tenant?
+        raise Error, "tenant: is required in multi-tenant mode" if tenant.nil?
+
+        roles.where(tenant_id: tenant.id)
+      else
+        raise Error, "tenant: must not be supplied in single-tenant mode" unless tenant.nil?
+
+        roles.where(tenant_id: nil)
+      end
+    end
+
+    def owner_bypass?(scoped_roles)
+      mode = AccessGrant.config.owner_role
+      return false unless %i[bypass both].include?(mode)
+
+      owner_name = AccessGrant.config.owner_role_name.to_s
+      scoped_roles.where("LOWER(name) = ?", owner_name.downcase).exists?
+    end
+
+    def multi_tenant?
+      tenant_class = AccessGrant.config.tenant_class
+      !(tenant_class.nil? || tenant_class.to_s.empty?)
+    end
+  end
+
+  # Extends +ActiveRecord::Base+ with {#access_grant}.
+  module ModelDsl
+    # Declare participation in AccessGrant.
+    #
+    # @param role [Symbol] +:user+ or +:tenant+
+    # @return [void]
+    # @raise [ArgumentError]
+    def access_grant(role)
+      case role
+      when :user
+        include AccessGrant::User
+      when :tenant
+        include AccessGrant::Tenant
+      else
+        raise ArgumentError, "Unknown access_grant role: #{role.inspect}"
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.extend(AccessGrant::ModelDsl)

data/lib/access_grant/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AccessGrant
+  VERSION = "1.0.0"
+end

data/lib/access_grant.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+require_relative "access_grant/version"
+require_relative "access_grant/configuration"
+require_relative "access_grant/permission_key"
+require_relative "access_grant/catalog"
+require_relative "access_grant/sync"
+require_relative "access_grant/owner"
+require_relative "access_grant/recovery"
+require_relative "access_grant/tenant"
+require_relative "access_grant/user"
+require_relative "access_grant/controller_methods"
+
+# Database-backed, per-tenant roles and permissions for Rails.
+#
+# Configure once in an initializer, declare a permission catalog in code,
+# sync into the DB, then check capabilities with {AccessGrant::User#permitted?}.
+#
+# @example Boot configuration
+#   AccessGrant.configure do |config|
+#     config.tenant_class = "Organization"
+#     config.user_class = "User"
+#     config.owner_role = :protected
+#   end
+#
+# @see AccessGrant::Configuration
+# @see docs/architecture.md
+module AccessGrant
+  # Base error for gem failures (unknown keys, Owner rules, etc.).
+  class Error < StandardError; end
+
+  # Raised by the controller authorize hook when the request is denied
+  # (or when +permitted?+ fails with {Error} at the HTTP edge).
+  class NotAuthorizedError < Error; end
+
+  # @return [AccessGrant::Configuration] shared configuration singleton
+  def self.config = @config ||= Configuration.new
+
+  # Yields {#config}, then applies table names / tenant association.
+  #
+  # @yieldparam config [AccessGrant::Configuration]
+  # @return [void]
+  def self.configure
+    yield(config)
+    apply_configuration!
+  end
+
+  # Replace configuration with defaults and re-apply model wiring.
+  # Intended for tests.
+  #
+  # @return [AccessGrant::Configuration]
+  def self.reset_config!
+    @config = Configuration.new
+    apply_configuration!
+  end
+
+  # @return [AccessGrant::Catalog] in-memory permission catalog
+  def self.catalog = @catalog ||= Catalog.new
+
+  # Clear the in-memory catalog (tests).
+  #
+  # @return [AccessGrant::Catalog]
+  def self.reset_catalog! = @catalog = Catalog.new
+
+  # Replace the catalog by evaluating a DSL block (typically from
+  # +config/access_grant/permissions.rb+).
+  #
+  # @yield DSL methods such as +resource+, +action+, +category+, +permission+
+  # @return [void]
+  # @see AccessGrant::Catalog::DSL
+  def self.permissions(&) = catalog.replace(&)
+
+  # Grant the Owner role (single-tenant or with +tenant:+). Prefer
+  # +tenant.grant_owner!(user)+ in multi-tenant apps.
+  #
+  # @param user [Object] host user record with +access_grant :user+
+  # @param tenant [Object, nil] required when +tenant_class+ is set
+  # @return [AccessGrant::Role] the Owner role
+  # @raise [AccessGrant::Error] when Owner is +:none+ or tenant args are wrong
+  def self.grant_owner!(user, tenant: nil)
+    Owner.grant_owner!(user, tenant: tenant)
+  end
+
+  # Revoke the Owner role from +user+. Fails if this would remove the last
+  # Owner assignment for the scope.
+  #
+  # @param user [Object]
+  # @param tenant [Object, nil]
+  # @return [void]
+  # @raise [AccessGrant::Error]
+  def self.revoke_owner!(user, tenant: nil)
+    Owner.revoke_owner!(user, tenant: tenant)
+  end
+
+  # Sync model +table_name+ values and optional +Role.belongs_to :tenant+
+  # from the current {#config}. Called automatically from {#configure}.
+  #
+  # @return [void]
+  def self.apply_configuration!
+    Permission.table_name = config.tables.fetch(:permissions)
+    Role.table_name = config.tables.fetch(:roles)
+    RolePermission.table_name = config.tables.fetch(:role_permissions)
+
+    tenant_class = config.tenant_class
+
+    if tenant_class.nil? || tenant_class.to_s.empty?
+      Role._reflections.delete(:tenant)
+      Role.clear_reflections_cache
+    else
+      Role.belongs_to :tenant,
+                      class_name: tenant_class.to_s,
+                      foreign_key: :tenant_id,
+                      optional: true,
+                      inverse_of: :roles
+    end
+  end
+end
+
+require_relative "access_grant/models/permission"
+require_relative "access_grant/models/role_permission"
+require_relative "access_grant/models/role"
+
+require_relative "access_grant/railtie" if defined?(Rails::Railtie)

data/lib/generators/access_grant/install/install_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module AccessGrant
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Creates AccessGrant core tables migration (short default names)"
+
+      def copy_migration
+        migration_template(
+          "create_access_grant_tables.rb.tt",
+          File.join(db_migrate_path, "create_access_grant_tables.rb")
+        )
+      end
+    end
+  end
+end

data/lib/generators/access_grant/install/templates/create_access_grant_tables.rb.tt

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    # Short default names. If setup chose access_grant_* tables, edit these
+    # names to match config.tables before migrating.
+    create_table :permissions do |t|
+      t.string :key, null: false
+      t.text :description
+      t.string :category
+      t.timestamps
+    end
+    # permitted? / sync upsert by key
+    add_index :permissions, :key, unique: true
+    # Search/group by model/controller (category defaults to resource name,
+    # e.g. "invoices") — Permission.by_category / ordered_for_ui
+    add_index :permissions, %i[category key]
+
+    create_table :roles do |t|
+      t.string :name, null: false
+      t.text :description
+      t.bigint :tenant_id # nullable for single-tenant / global roles
+      t.timestamps
+    end
+    # list roles for a tenant + unique name per tenant (case-sensitive at DB;
+    # AR validates case-insensitively — expression unique index is adapter-specific)
+    add_index :roles, %i[tenant_id name], unique: true
+    # Owner / Recovery lookups: WHERE tenant_id = ? AND LOWER(name) = ?
+    add_index :roles, :name
+
+    create_table :role_permissions do |t|
+      t.references :role, null: false, foreign_key: { to_table: :roles }
+      t.references :permission, null: false, foreign_key: { to_table: :permissions }
+      t.timestamps
+    end
+    # t.references already indexes role_id and permission_id individually
+    add_index :role_permissions, %i[role_id permission_id], unique: true
+  end
+end

data/lib/generators/access_grant/setup/setup_generator.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module AccessGrant
+  module Generators
+    class SetupGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Configures AccessGrant (initializer, catalog, user_roles, model patches)"
+
+      class_option :multi_tenant, type: :boolean, default: nil,
+                                  desc: "Multi-tenant install (roles scoped by tenant)"
+      class_option :single_tenant, type: :boolean, default: nil,
+                                   desc: "Single-tenant install (no tenant_class)"
+      class_option :tenant, type: :string, default: "Organization",
+                            desc: "Tenant model class name"
+      class_option :user, type: :string, default: "User",
+                          desc: "User model class name"
+      class_option :owner_role, type: :string, default: "protected",
+                                desc: "Owner mode: protected, bypass, both, or none"
+      class_option :tables, type: :string, default: "auto",
+                            desc: "Table naming: auto, simple, or prefixed"
+
+      SHORT_TABLES = {
+        roles: "roles",
+        permissions: "permissions",
+        role_permissions: "role_permissions",
+        user_roles: "user_roles"
+      }.freeze
+
+      PREFIXED_TABLES = {
+        roles: "access_grant_roles",
+        permissions: "access_grant_permissions",
+        role_permissions: "access_grant_role_permissions",
+        user_roles: "access_grant_user_roles"
+      }.freeze
+
+      def resolve_options!
+        @multi_tenant = multi_tenant_install?
+        @tenant_class = @multi_tenant ? options[:tenant] : nil
+        @user_class = options[:user]
+        @owner_role = options[:owner_role].to_sym
+        @tables = resolve_tables!
+      end
+
+      def create_initializer
+        template "access_grant.rb.tt", "config/initializers/access_grant.rb"
+      end
+
+      def create_permissions_catalog
+        template "permissions.rb.tt", "config/access_grant/permissions.rb"
+      end
+
+      def create_roles_config
+        template "roles.rb.tt", "config/access_grant/roles.rb"
+      end
+
+      def create_user_roles_migration
+        @user_roles_table = @tables.fetch(:user_roles)
+        @roles_table = @tables.fetch(:roles)
+        migration_template(
+          "create_access_grant_user_roles.rb.tt",
+          File.join(db_migrate_path, "create_access_grant_user_roles.rb")
+        )
+      end
+
+      def patch_models
+        inject_access_grant(@tenant_class, :tenant) if @multi_tenant
+        inject_access_grant(@user_class, :user)
+      end
+
+      def print_deploy_reminder
+        say ""
+        say "IMPORTANT — catalog sync is not a migration.", :yellow
+        say "After migrate, and on every deploy that may change permissions.rb, run:"
+        say "  bundle exec rake access_grant:sync_permissions", :green
+        say "Wire this into your release process (Kamal / Heroku release / Capistrano)."
+        say ""
+        return unless @tables != SHORT_TABLES
+
+        say "Table names differ from access_grant:install defaults (short names).", :yellow
+        say "Edit the install migration's table names to match config.tables before db:migrate.", :yellow
+        say ""
+      end
+
+      private
+
+      def multi_tenant_install?
+        return true if options[:multi_tenant]
+        return false if options[:single_tenant]
+        return yes?("Multi-tenant install? (y/n)") if options[:multi_tenant].nil? && options[:single_tenant].nil?
+
+        false
+      end
+
+      def resolve_tables!
+        strategy = options[:tables].to_s
+        case strategy
+        when "prefixed"
+          PREFIXED_TABLES.dup
+        when "simple"
+          fail_if_short_taken!
+          SHORT_TABLES.dup
+        when "auto"
+          if short_names_taken?
+            say_status :collision, "short table/model names taken → access_grant_*", :yellow
+            PREFIXED_TABLES.dup
+          else
+            unless connection_available?
+              say_status :info,
+                         "no DB connection — assuming short table names are free " \
+                         "(--tables=auto); use --tables=prefixed if they may collide",
+                         :blue
+            end
+            SHORT_TABLES.dup
+          end
+        else
+          raise Thor::Error, "Unknown --tables=#{strategy.inspect} (use auto|simple|prefixed)"
+        end
+      end
+
+      def short_names_taken?
+        SHORT_TABLES.each_value.any? { |name| table_exists_safe?(name) } ||
+          %w[Role Permission].any? { |const| Object.const_defined?(const, false) }
+      end
+
+      def fail_if_short_taken!
+        return unless short_names_taken?
+
+        raise Thor::Error,
+              "Short table/model names are taken (roles/permissions/role_permissions/" \
+              "user_roles or top-level Role/Permission). " \
+              "Use --tables=auto or --tables=prefixed instead of --tables=simple."
+      end
+
+      def connection_available?
+        defined?(ActiveRecord::Base) &&
+          ActiveRecord::Base.connected? &&
+          ActiveRecord::Base.connection
+      rescue StandardError
+        false
+      end
+
+      def table_exists_safe?(name)
+        return false unless connection_available?
+
+        ActiveRecord::Base.connection.table_exists?(name)
+      rescue StandardError
+        false
+      end
+
+      def inject_access_grant(class_name, role)
+        path = model_path_for(class_name)
+        unless path && File.exist?(path)
+          say_status :warn, "could not find model file for #{class_name} — add `access_grant :#{role}` manually",
+                     :yellow
+          return
+        end
+
+        marker = "access_grant :#{role}"
+        if File.read(path).include?(marker)
+          say_status :identical, "#{path} already has #{marker}", :blue
+          return
+        end
+
+        inject_into_class(path, class_name.to_s.demodulize, "  #{marker}\n")
+      end
+
+      def model_path_for(class_name)
+        return nil if class_name.nil? || class_name.to_s.empty?
+
+        relative = class_name.to_s.underscore
+        candidates = [
+          File.join(destination_root, "app/models/#{relative}.rb"),
+          File.join(destination_root, "app/models/#{relative.split('/').last}.rb")
+        ]
+        candidates.find { |p| File.exist?(p) }
+      end
+
+      # Template helpers
+      def multi_tenant? = @multi_tenant
+      attr_reader :tenant_class, :user_class, :owner_role, :tables
+    end
+  end
+end