access_grant 1.0.0

data/lib/access_grant/catalog.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "active_support/inflector"
+require "set"
+require_relative "catalog/dsl"
+
+module AccessGrant
+  # In-memory permission catalog built from {AccessGrant.permissions}.
+  #
+  # Entries are hashes with keys +:key+, +:description+, +:category+.
+  # Persist them with {AccessGrant::Sync.call}.
+  class Catalog
+    # Default description templates for built-in actions (+%<resources>s+ /
+    # +%<resource>s+ filled from the pluralized resource segment).
+    DEFAULT_TEMPLATES = {
+      "index" => "Can view list of %<resources>s",
+      "show" => "Can view details of a %<resource>s",
+      "create" => "Can create a new %<resource>s",
+      "update" => "Can update an existing %<resource>s",
+      "destroy" => "Can delete an existing %<resource>s"
+    }.freeze
+
+    def initialize
+      @entries = {}
+    end
+
+    # @return [Array<Hash>] catalog entries sorted by +:key+
+    def entries
+      @entries.values.sort_by { |entry| entry[:key] }
+    end
+
+    # Remove all entries.
+    #
+    # @return [void]
+    def clear!
+      @entries.clear
+    end
+
+    # Clear and evaluate a {DSL} block (replace semantics).
+    #
+    # @yield DSL
+    # @return [void]
+    def replace(&)
+      clear!
+      DSL.new(self).instance_eval(&)
+    end
+
+    # Insert or override one catalog entry.
+    #
+    # @param key [String, Symbol] +resource.action+
+    # @param description [String]
+    # @param category [String] grouping label (often the resource name)
+    # @param override [Boolean] when true, replace an existing key instead of raising
+    # @return [void]
+    # @raise [AccessGrant::Error] invalid or duplicate key (when +override+ is false)
+    def add(key, description:, category:, override: false)
+      normalized = PermissionKey.normalize!(key)
+
+      raise Error, "Duplicate permission key: #{normalized}" if @entries.key?(normalized) && !override
+
+      @entries[normalized] = { key: normalized, description: description, category: category }
+    end
+
+    # Render a {DEFAULT_TEMPLATES} description for +action+ / resource segment.
+    #
+    # @param action [String, Symbol]
+    # @param resource_segment [String] plural resource name (e.g. +"invoices"+)
+    # @return [String]
+    def template_description(action, resource_segment)
+      template = DEFAULT_TEMPLATES.fetch(action.to_s)
+      singular = resource_segment.singularize
+
+      format(template, resources: resource_segment, resource: singular)
+    end
+  end
+end

data/lib/access_grant/configuration.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module AccessGrant
+  # Host-facing settings for AccessGrant. Set via {AccessGrant.configure}.
+  #
+  # Defaults match the architecture configuration reference; the setup
+  # generator writes a fully commented initializer covering every option.
+  class Configuration
+    # @return [String, nil] Host tenant model (e.g. +"Organization"+); +nil+ = single-tenant
+    attr_accessor :tenant_class
+
+    # @return [String] Host user model that receives roles (default: +"User"+)
+    attr_accessor :user_class
+
+    # @return [Symbol] Owner mechanism: +:protected+, +:bypass+, +:both+, or +:none+ (default: +:protected+)
+    attr_accessor :owner_role
+
+    # @return [String] Reserved Owner role name, case-insensitive (default: +"Owner"+)
+    attr_accessor :owner_role_name
+
+    # @return [Hash{Symbol=>String}] Physical table names (+:roles+, +:permissions+, +:role_permissions+, +:user_roles+)
+    attr_accessor :tables
+
+    # @return [Array<String>] Actions emitted for each catalog +resource+ (default: CRUD + index/show)
+    attr_accessor :default_permission_actions
+
+    # @return [Symbol] Controller method for the acting user (default: +:current_user+)
+    attr_accessor :current_user_method
+
+    # @return [Symbol] Controller method for the tenant in multi-tenant mode (default: +:current_tenant+)
+    attr_accessor :current_tenant_method
+
+    # @return [Proc, nil] Called after tenant create; seed default roles (not Owner assignment)
+    attr_accessor :on_tenant_created
+
+    # @return [Proc, nil] Ops lockout recovery; +nil+ uses {AccessGrant::Recovery.grant_role!}
+    attr_accessor :recover_access
+
+    # Build a configuration with architecture defaults.
+    def initialize
+      @user_class = "User"
+      @owner_role = :protected
+      @owner_role_name = "Owner"
+      @default_permission_actions = %w[index show create update destroy]
+      @current_user_method = :current_user
+      @current_tenant_method = :current_tenant
+      @tables = {
+        roles: "roles",
+        permissions: "permissions",
+        role_permissions: "role_permissions",
+        user_roles: "user_roles"
+      }
+    end
+  end
+end

data/lib/access_grant/controller_methods.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/inflector"
+
+module AccessGrant
+  # Optional controller authorize hook (not a second Pundit).
+  #
+  # Maps +controller_name+ + +action_name+ → +resource.action+, then calls
+  # {AccessGrant::User#permitted?} using configured current-user / tenant
+  # methods. Include automatically via {AccessGrant::Railtie}.
+  #
+  # @example
+  #   class ApplicationController < ActionController::Base
+  #     access_grant_authorize!
+  #     skip_access_grant_authorize! if: :devise_controller?
+  #     rescue_from AccessGrant::NotAuthorizedError, with: :deny
+  #   end
+  module ControllerMethods
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Install a +before_action+ that runs {#access_grant_authorize_request!}.
+      #
+      # @param options [Hash] forwarded to +before_action+ (e.g. +only:+, +except:+)
+      # @return [void]
+      def access_grant_authorize!(**options)
+        if respond_to?(:before_action)
+          before_action :access_grant_authorize_request!, **options
+        else
+          access_grant_authorize_callbacks << [:access_grant_authorize_request!, options]
+        end
+      end
+
+      # Skip the authorize before_action.
+      #
+      # @param options [Hash] forwarded to +skip_before_action+
+      # @return [void]
+      def skip_access_grant_authorize!(**options)
+        if respond_to?(:skip_before_action)
+          skip_before_action :access_grant_authorize_request!, **options
+        else
+          access_grant_skip_authorize_callbacks << [:access_grant_authorize_request!, options]
+        end
+      end
+
+      # @api private
+      def access_grant_authorize_callbacks
+        @access_grant_authorize_callbacks ||= []
+      end
+
+      # @api private
+      def access_grant_skip_authorize_callbacks
+        @access_grant_skip_authorize_callbacks ||= []
+      end
+    end
+
+    # Authorize the current request. Raises {AccessGrant::NotAuthorizedError}
+    # on deny, missing user, or {AccessGrant::Error} from +permitted?+.
+    #
+    # @return [void]
+    # @raise [AccessGrant::NotAuthorizedError]
+    def access_grant_authorize_request!
+      user = send(AccessGrant.config.current_user_method)
+      raise NotAuthorizedError, "No current user (#{AccessGrant.config.current_user_method})" if user.nil?
+
+      key = access_grant_permission_key
+      allowed =
+        begin
+          if access_grant_multi_tenant?
+            tenant = send(AccessGrant.config.current_tenant_method)
+            user.permitted?(key, tenant: tenant)
+          else
+            user.permitted?(key)
+          end
+        rescue Error => e
+          raise NotAuthorizedError.new(e.message), cause: e
+        end
+
+      raise NotAuthorizedError, "Not authorized for #{key}" unless allowed
+    end
+
+    private
+
+    def access_grant_permission_key
+      "#{access_grant_resource_name}.#{action_name}"
+    end
+
+    def access_grant_resource_name
+      name =
+        if respond_to?(:controller_name) && !controller_name.nil?
+          controller_name.to_s
+        else
+          self.class.name.demodulize.underscore.sub(/_controller\z/, "")
+        end
+      name.pluralize
+    end
+
+    def access_grant_multi_tenant?
+      tenant_class = AccessGrant.config.tenant_class
+      !(tenant_class.nil? || tenant_class.to_s.empty?)
+    end
+  end
+end

data/lib/access_grant/models/permission.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module AccessGrant
+  # Catalog permission row (+key+, +description+, +category+).
+  #
+  # Metadata is owned by sync/code; admins select keys but do not invent them.
+  class Permission < ActiveRecord::Base
+    self.table_name = AccessGrant.config.tables.fetch(:permissions)
+
+    validates :key, presence: true, uniqueness: true
+    validate :key_must_be_valid_permission_key
+
+    # Permissions for one model/controller grouping label (default = resource
+    # name, e.g. +"invoices"+). Uses index on +(category, key)+.
+    #
+    # @param category [String, Symbol]
+    # @return [ActiveRecord::Relation]
+    scope :by_category, lambda { |category|
+      where(category: category.to_s).order(:key)
+    }
+
+    # Full catalog ordered for admin UIs (group by category, then key).
+    #
+    # @return [ActiveRecord::Relation]
+    scope :ordered_for_ui, -> { order(:category, :key) }
+
+    private
+
+    def key_must_be_valid_permission_key
+      return if key.blank?
+      return if PermissionKey.valid?(key)
+
+      errors.add(:key, "is invalid")
+    end
+  end
+end

data/lib/access_grant/models/role.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module AccessGrant
+  # Named role within a tenant (or global when +tenant_id+ is +nil+).
+  #
+  # Assign permissions with {#permission_keys=}. Owner roles are reserved and
+  # protected according to {AccessGrant::Configuration#owner_role}.
+  class Role < ActiveRecord::Base
+    self.table_name = AccessGrant.config.tables.fetch(:roles)
+
+    has_many :role_permissions, class_name: "AccessGrant::RolePermission", dependent: :destroy,
+                                inverse_of: :role,
+                                before_add: :prevent_protected_owner_permission_change,
+                                before_remove: :prevent_protected_owner_permission_change
+    has_many :permissions, through: :role_permissions, class_name: "AccessGrant::Permission",
+                           before_add: :prevent_protected_owner_permission_change,
+                           before_remove: :prevent_protected_owner_permission_change
+
+    validates :name, presence: true,
+                     uniqueness: { scope: :tenant_id, case_sensitive: false }
+    validate :name_not_reserved_owner
+    before_destroy :prevent_protected_owner_destroy, prepend: true
+
+    # @return [Array<String>] permission keys currently granted
+    def permission_keys
+      permissions.pluck(:key)
+    end
+
+    # Atomically replace the full permission set. Unknown/malformed keys raise
+    # and leave the previous set intact.
+    #
+    # @param keys [Array<String, Symbol>]
+    # @return [Array<AccessGrant::Permission>]
+    # @raise [AccessGrant::Error] protected Owner, unknown key, or malformed key
+    def permission_keys=(keys)
+      raise Error, "Cannot modify permissions on protected Owner role" if protected_owner_role?
+
+      normalized = Array(keys).map { |key| PermissionKey.normalize!(key) }
+
+      transaction do
+        resolved = normalized.map do |key|
+          Permission.find_by(key: key) ||
+            raise(Error, "Unknown permission key: #{key.inspect}")
+        end
+
+        self.permissions = resolved
+      end
+    end
+
+    # @return [Boolean] true when this is the Owner role under +:protected+ / +:both+
+    def protected_owner_role?
+      return false unless %i[protected both].include?(AccessGrant.config.owner_role)
+
+      owner_named?
+    end
+
+    # @return [Boolean] name matches configured Owner name (case-insensitive)
+    def owner_named?
+      name.to_s.downcase == AccessGrant.config.owner_role_name.to_s.downcase
+    end
+
+    # Create-only: for each name => permission keys, creates the role when missing
+    # under +tenant+ (or +tenant_id+ nil when +tenant+ is nil) and assigns keys.
+    # Existing roles are left unchanged.
+    #
+    # @param tenant [Object, nil] tenant record responding to +id+, or nil (single-tenant)
+    # @param defaults [Hash] role name => array of permission key strings/symbols
+    # @return [void]
+    def self.ensure_defaults_for!(tenant, defaults)
+      tenant_id = tenant&.id
+      defaults.each do |role_name, keys|
+        next if exists?(name: role_name.to_s, tenant_id: tenant_id)
+
+        role = create!(name: role_name.to_s, tenant_id: tenant_id)
+        role.permission_keys = keys
+      end
+    end
+
+    # Starting-point roles derived from synced permissions, grouped by +category+
+    # (resource / model name). Create-only; safe to call on every tenant create.
+    #
+    # For category +"invoices"+ with keys +invoices.index+, +invoices.show+, …:
+    # - +"Invoices Viewer"+ — actions in +viewer_actions+ that exist
+    # - +"Invoices Manager"+ — all keys in that category
+    #
+    # Requires a prior +access_grant:sync_permissions+ so Permission rows exist.
+    # Hosts customize or replace this from +config/access_grant/roles.rb+.
+    #
+    # @param tenant [Object, nil]
+    # @param viewer_actions [Array<String>] action suffixes for Viewer roles
+    # @return [void]
+    def self.ensure_resource_defaults_for!(tenant, viewer_actions: %w[index show])
+      viewer_actions = viewer_actions.map(&:to_s)
+      defaults = resource_default_role_map(viewer_actions)
+      ensure_defaults_for!(tenant, defaults)
+    end
+
+    def self.resource_default_role_map(viewer_actions)
+      defaults = {}
+      permissions_by_category.each do |category, permissions|
+        label = humanize_category(category)
+        keys = permissions.map(&:key)
+        viewer_keys = keys.select { |key| viewer_actions.include?(key.split(".", 2).last) }
+
+        defaults["#{label} Viewer"] = viewer_keys if viewer_keys.any?
+        defaults["#{label} Manager"] = keys if keys.any?
+      end
+      defaults
+    end
+    private_class_method :resource_default_role_map
+
+    def self.permissions_by_category
+      grouped = Hash.new { |hash, key| hash[key] = [] }
+      Permission.select(:id, :key, :category).find_each do |permission|
+        category = permission.category.presence || permission.key.split(".", 2).first
+        grouped[category] << permission
+      end
+      grouped
+    end
+    private_class_method :permissions_by_category
+
+    def self.humanize_category(category)
+      category.to_s.tr("_", " ").split.map(&:capitalize).join(" ")
+    end
+    private_class_method :humanize_category
+
+    private
+
+    def name_not_reserved_owner
+      return if Owner.__send__(:owner_role_creation?)
+      return if AccessGrant.config.owner_role == :none
+      return unless owner_named?
+
+      errors.add(:name, "is reserved for the Owner role")
+    end
+
+    def prevent_protected_owner_destroy
+      return unless protected_owner_role?
+      return if destroyed_by_association # tenant/org cascading destroy
+
+      errors.add(:base, "Cannot destroy protected Owner role")
+      throw(:abort)
+    end
+
+    def prevent_protected_owner_permission_change(_record)
+      return unless protected_owner_role?
+      return if destroyed_by_association # tenant/org cascading destroy
+
+      raise Error, "Cannot modify permissions on protected Owner role"
+    end
+  end
+end

data/lib/access_grant/models/role_permission.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module AccessGrant
+  # Join between {Role} and {Permission}.
+  class RolePermission < ActiveRecord::Base
+    self.table_name = AccessGrant.config.tables.fetch(:role_permissions)
+
+    belongs_to :role, class_name: "AccessGrant::Role"
+    belongs_to :permission, class_name: "AccessGrant::Permission"
+  end
+end

data/lib/access_grant/owner.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module AccessGrant
+  # Owner role grant/revoke and last-Owner assignment guards.
+  #
+  # Prefer +tenant.grant_owner!(user)+ / +tenant.revoke_owner!(user)+ when
+  # multi-tenant; use {AccessGrant.grant_owner!} in single-tenant mode.
+  module Owner
+    # @api private
+    OWNER_ROLE_CREATION_KEY = :access_grant_owner_role_creation
+
+    module_function
+
+    # @api private
+    def with_owner_role_creation
+      previous = Thread.current[OWNER_ROLE_CREATION_KEY]
+      Thread.current[OWNER_ROLE_CREATION_KEY] = true
+      yield
+    ensure
+      Thread.current[OWNER_ROLE_CREATION_KEY] = previous
+    end
+    private_class_method :with_owner_role_creation
+
+    # @api private
+    def owner_role_creation?
+      Thread.current[OWNER_ROLE_CREATION_KEY] == true
+    end
+    private_class_method :owner_role_creation?
+
+    # Find or create the Owner role for the scope, attach catalog keys when
+    # mode is +:protected+ / +:both+, and assign +user+.
+    #
+    # @param user [Object] host user with +access_grant :user+
+    # @param tenant [Object, nil] required in multi-tenant mode
+    # @return [AccessGrant::Role]
+    # @raise [AccessGrant::Error]
+    def grant_owner!(user, tenant: nil)
+      ensure_owner_enabled!
+      ensure_tenant_arg!(tenant)
+
+      role = find_or_create_owner_role!(tenant_id_for(tenant))
+      attach_owner_permissions!(role) if attach_owner_permissions?
+
+      user.roles << role unless user.roles.exists?(id: role.id)
+      role
+    end
+
+    # Remove Owner from +user+. Raises if this is the last Owner assignment
+    # for the scope (also enforced on HABTM +roles.delete+).
+    #
+    # @param user [Object]
+    # @param tenant [Object, nil]
+    # @return [void]
+    # @raise [AccessGrant::Error]
+    def revoke_owner!(user, tenant: nil)
+      ensure_owner_enabled!
+      ensure_tenant_arg!(tenant)
+
+      role = find_owner_role(tenant_id_for(tenant))
+      return unless role && user.roles.exists?(id: role.id)
+
+      Role.transaction do
+        user.roles.delete(role)
+      end
+    end
+
+    # Guard used by HABTM +before_remove+ and revoke paths.
+    #
+    # @param role [AccessGrant::Role]
+    # @return [void]
+    # @raise [AccessGrant::Error] when removing the last Owner assignment
+    def ensure_can_remove_assignment!(role)
+      return if AccessGrant.config.owner_role == :none
+      return unless role.owner_named?
+
+      role.lock!
+      return if assignment_count(role) > 1
+
+      raise Error, "Cannot revoke the last Owner for this scope"
+    end
+
+    def ensure_owner_enabled!
+      return unless AccessGrant.config.owner_role == :none
+
+      raise Error, "Owner is disabled (owner_role: :none)"
+    end
+    private_class_method :ensure_owner_enabled!
+
+    def ensure_tenant_arg!(tenant)
+      if multi_tenant?
+        raise Error, "tenant: is required in multi-tenant mode" if tenant.nil?
+      else
+        raise Error, "tenant: must not be supplied in single-tenant mode" unless tenant.nil?
+      end
+    end
+    private_class_method :ensure_tenant_arg!
+
+    def tenant_id_for(tenant)
+      tenant&.id
+    end
+    private_class_method :tenant_id_for
+
+    def multi_tenant?
+      tenant_class = AccessGrant.config.tenant_class
+      !(tenant_class.nil? || tenant_class.to_s.empty?)
+    end
+    private_class_method :multi_tenant?
+
+    def attach_owner_permissions?
+      %i[protected both].include?(AccessGrant.config.owner_role)
+    end
+    private_class_method :attach_owner_permissions?
+
+    def attach_owner_permissions!(role)
+      Sync.__send__(:replace_role_permissions!, role, Permission.pluck(:key))
+    end
+    private_class_method :attach_owner_permissions!
+
+    def find_or_create_owner_role!(tenant_id)
+      existing = find_owner_role(tenant_id)
+      return existing if existing
+
+      with_owner_role_creation do
+        Role.create!(name: AccessGrant.config.owner_role_name.to_s, tenant_id: tenant_id)
+      end
+    end
+    private_class_method :find_or_create_owner_role!
+
+    def find_owner_role(tenant_id)
+      owner_name = AccessGrant.config.owner_role_name.to_s
+      Role.where(tenant_id: tenant_id).where("LOWER(name) = ?", owner_name.downcase).first
+    end
+    private_class_method :find_owner_role
+
+    def assignment_count(role)
+      join_table = AccessGrant.config.tables.fetch(:user_roles)
+      sql = ActiveRecord::Base.sanitize_sql_array(
+        ["SELECT COUNT(*) FROM #{join_table} WHERE role_id = ?", role.id]
+      )
+      ActiveRecord::Base.connection.select_value(sql).to_i
+    end
+    private_class_method :assignment_count
+  end
+end

data/lib/access_grant/permission_key.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module AccessGrant
+  # Validates and normalizes permission keys in +resource.action+ form.
+  #
+  # Pattern: +/\A[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*\z/+
+  class PermissionKey
+    # @return [Regexp] enforced key shape
+    PATTERN = /\A[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*\z/
+
+    # @param key [String, Symbol]
+    # @return [Boolean]
+    def self.valid?(key)
+      PATTERN.match?(key.to_s)
+    end
+
+    # Coerce to String and validate.
+    #
+    # @param key [String, Symbol]
+    # @return [String] normalized key
+    # @raise [AccessGrant::Error] when the key is malformed
+    def self.normalize!(key)
+      normalized = key.to_s
+      raise Error, "Invalid permission key: #{key.inspect}" unless valid?(normalized)
+
+      normalized
+    end
+  end
+end

data/lib/access_grant/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module AccessGrant
+  # Rails integration: loads rake tasks and includes {ControllerMethods} on
+  # Action Controller.
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path("../tasks/access_grant_tasks.rake", __dir__)
+    end
+
+    initializer "access_grant.action_controller" do
+      ActiveSupport.on_load(:action_controller) do
+        include AccessGrant::ControllerMethods
+      end
+    end
+  end
+end