rbacan 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 066e77f9b2f426249a569e679c9c1348e28b2f3af5f19f480a9059ce237b5258
-  data.tar.gz: 83cb20bd2b2e97c558f0f97f2c0452417f01668f73cc3bccbf48eddde3e7cd81
+  metadata.gz: d73e61377cfc8c44c60d79857c8a5c09be75ddd8c7e6bd1547895dc11f03a673
+  data.tar.gz: 7027bf24c300f0996fd12cb94875bfb16ab24f0119b4442547da1ea054fb365b
 SHA512:
-  metadata.gz: 5b2c8e3ac69a2fc9ea125022eb1d8ac2fd63ee702c2b6e8b1300e6c5dc317ae9db8b5dc1fd96167ea418b1a1cded3f2b7282edd6f09a2ec4fd19783556b4eb4d
-  data.tar.gz: f1a0312c57018c184383266dfeab2b9c2fe216431e63558996d14162e1c56291c85edee0ab00bab716498da4bd34f7d3dd56232ded31e48947b1c932078ac72a
+  metadata.gz: 5363d5c569e9b65c754066baac8407b7d4047b9ecb11c5ba81ac66cec9f2fe2096837feb4e1ce3940cf53374fddeaa0feea034553917285e1871c0f6f968f2b7
+  data.tar.gz: ac1e65f2064108e82a9686b895b1ae1ea6f7badc9a49b3bcdc5e299f861413b9aaedc0bc3ad17605c0cbd10ea95ca5abf2872abaa23af9067bf7480dd0692a8a

data/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.0] - 2026-09-12
+
+### Added
+
+- Host-owned authorization through immutable, value-based `Rbacan::AuthorizationContext` and pluggable authorization/assignment adapters.
+- Association-free `Rbacan::Authorizable` concern for applications that own their RBAC schema and lifecycle.
+- Explicit user and context resolvers for hardened route constraints.
+- Stable denial codes on `Rbacan::NotAuthorized` for host-side localization.
+- Configurable `role_key` and `permission_key` columns.
+- Deeply immutable JSON-like authorization metadata and copied immutable target codes.
+
+### Changed
+
+- Hardened mode is the default. Authorization requires an explicit context and fails closed without a host adapter.
+- Destructive/unscoped `Rbacan::Permittable`, catalog, role-permission, and seed-helper APIs require explicit `legacy_mode = true` opt-in.
+- Authorization contexts require a tenant and snapshot/freeze JSON-like tenant, property, vertical, and subject identifiers plus their timestamp.
+- Controller and view authorization use the host adapter in hardened mode.
+- Hardened redirect denials resolve their stable code through the host I18n backend.
+- Assignment dispatch rejects missing users or blank roles before invoking the host adapter.
+- Gem packaging uses an explicit runtime/documentation allowlist and excludes repository-only files.
+
+### Compatibility
+
+- Applications using the generated 0.4 schema must consciously enable legacy mode while migrating.
+
 ## [0.4.0] - 2026-04-13
 
 ### Added

data/README.md

@@ -38,6 +38,60 @@ bundle install
 
 ## Setup
 
+RBACan 0.5 has two explicit integration modes:
+
+- **Host-owned mode (recommended):** the application owns schema, tenancy, scopes, assignment history,
+  and record policies. Include `Rbacan::Authorizable` and configure adapters. Do not run the generator.
+- **Legacy generated-schema mode:** preserves the 0.4 Active Record API only after conscious
+  `config.legacy_mode = true` opt-in. Its removal methods delete join rows and are unsuitable for
+  immutable assignment-history requirements.
+
+### Host-owned mode
+
+```ruby
+class User < ApplicationRecord
+  include Rbacan::Authorizable
+end
+
+Rbacan.configure do |config|
+  config.role_class = 'Role'
+  config.role_key = :code
+  config.permission_class = 'Permission'
+  config.permission_key = :code
+  config.authorization_adapter = MyAuthorizationAdapter.new
+  config.assignment_adapter = MyAssignmentAdapter.new
+end
+```
+
+Every check receives an explicit immutable value context. Pass stable identifiers or JSON-like
+references, not live Active Record objects:
+
+```ruby
+context = Rbacan::AuthorizationContext.new(
+  tenant: current_tenant.id,
+  property: current_property.id,
+  vertical: current_property.property_type.to_s,
+  subject: { type: reservation.class.name, id: reservation.id },
+  at: Time.current
+)
+
+current_user.can?(:hotel_reservations_read, context: context)
+```
+
+The tenant identifier is required and cannot be nil, boolean, or empty. Tenant, property, vertical,
+subject, metadata, and timestamp values are copied
+and frozen when the context is created. Context identifiers must come from records already loaded
+through the host application's authenticated scope; the authorization adapter resolves and validates
+their relationships under the host's tenancy/RLS rules. The request's `user` remains the live host
+principal object.
+
+Adapters receive one request object. Authorization adapters respond to `allowed?(request)` or `call`;
+assignment adapters respond to `assign(request)` and `revoke(request)`. RBACan never prescribes deletion
+or caching in host-owned mode. Optional context metadata is deeply copied and frozen and accepts only
+hashes, arrays, strings, finite integers/floats, booleans, nil, and symbols.
+
+### Legacy generated-schema mode
+
 **1. Run the generator**
 
 ```bash
@@ -72,13 +126,21 @@ rails db:seed
 
 ## Configuration
 
-The generator creates `config/initializers/rbacan.rb`. All options are optional — the defaults work for a standard Devise setup.
+The generator creates `config/initializers/rbacan.rb`. Generated-schema applications must explicitly
+enable legacy mode; the remaining defaults then work for a standard Devise setup.
 
 ```ruby
 Rbacan.configure do |config|
+  # Conscious opt-in required for the destructive/unscoped 0.4 API while migrating.
+  config.legacy_mode = true
+
   # Your user model name (default: "User")
   config.permittable_class = "User"
 
+  # Host key columns default to :name.
+  # config.role_key = :code
+  # config.permission_key = :code
+
   # Override model class names if you have custom implementations
   # config.role_class             = "Rbacan::Role"
   # config.permission_class       = "Rbacan::Permission"
@@ -107,7 +169,7 @@ end
 
 ## Defining Roles and Permissions
 
-Use the `Rbacan::RolesAndPermissions` module in your seeds. All methods are idempotent — safe to run multiple times.
+In legacy mode, use the `Rbacan::RolesAndPermissions` module in your seeds. All methods are idempotent — safe to run multiple times. Hardened mode rejects these unscoped helpers; host-owned applications must seed their own scoped authorization records.
 
 ```ruby
 # db/seeds.rb
@@ -201,9 +263,20 @@ Include `Rbacan::Authorization` in your `ApplicationController` (or any specific
 ```ruby
 class ApplicationController < ActionController::Base
   include Rbacan::Authorization
+  helper_method :rbacan_authorization_context
+
+  private
+
+  def rbacan_authorization_context
+    AuthorizationContextResolver.call(request: request, user: current_user, subject: @post)
+  end
 end
 ```
 
+The host resolver must build the immutable identifier context only after authenticating the user and
+loading tenant, property, and optional subject records through the authorized scope.
+`AuthorizationContextResolver` is application-defined; RBACan does not infer these values.
+
 Then use `authorize!` or `authorize_role!` as `before_action` callbacks:
 
 ```ruby
@@ -255,7 +328,9 @@ config.unauthorized_handler = ->(controller, permission:, role:) {
 
 ## View Helpers
 
-`Rbacan::ViewHelpers` is automatically included in all views. Use `authorized?` to conditionally render content:
+`Rbacan::ViewHelpers` is automatically included in all views. In host-owned mode the host must expose
+`current_user` and `rbacan_authorization_context` to the view. Use `authorized?` to conditionally
+render content:
 
 ```erb
 <% authorized?(:delete_post) do %>
@@ -267,40 +342,47 @@ config.unauthorized_handler = ->(controller, permission:, role:) {
 <% end %>
 ```
 
-You can also use `has_role?` and `has_any_role?` directly in views since they are instance methods on the user:
+You can also use `has_role?` directly in views through the host-owned concern:
 
 ```erb
-<% if current_user.has_role?(:admin) %>
+<% if current_user.has_role?(:admin, context: rbacan_authorization_context) %>
   <%= link_to "Admin Panel", admin_root_path %>
 <% end %>
-
-<% if current_user.has_any_role?(:admin, :moderator) %>
-  <%= link_to "Moderation Queue", moderation_path %>
-<% end %>
 ```
 
 ---
 
 ## Route Constraints
 
-Restrict access to entire route namespaces based on role or permission. Add constraints in `config/routes.rb`:
+Restrict access to entire route namespaces based on role or permission. Hardened mode requires explicit
+request resolvers:
 
 ```ruby
-# Restrict by role
-constraints Rbacan::RouteConstraint.new(role: :admin) do
+resolve_user = ->(request) { CurrentSessionResolver.call(request) }
+resolve_context = ->(request) { AuthorizationContextResolver.call(request) }
+
+constraints Rbacan::RouteConstraint.new(
+  role: :admin,
+  user_resolver: resolve_user,
+  context_resolver: resolve_context
+) do
   namespace :admin do
     resources :users
     resources :roles
   end
 end
 
-# Restrict by permission
-constraints Rbacan::RouteConstraint.new(permission: :access_dashboard) do
+constraints Rbacan::RouteConstraint.new(
+  permission: :access_dashboard,
+  user_resolver: resolve_user,
+  context_resolver: resolve_context
+) do
   get "/dashboard", to: "dashboard#index"
 end
 ```
 
-The constraint reads the current user from the Warden session (used by Devise). For apps using a manual session, it falls back to looking up `session[:user_id]`.
+Without both resolvers hardened constraints fail closed. In explicitly enabled legacy mode only, the
+constraint retains the 0.4 behavior of reading Warden or `session[:user_id]`.
 
 ---
 

data/lib/generators/install/templates/rbacan.rb

@@ -1,31 +1,38 @@
 Rbacan.configure do |config|
-  # The name of your user model (default: "User")
+  # Hardened host-owned mode is the default. The generated 0.4-style schema remains
+  # inactive until the host consciously opts into its destructive/unscoped APIs:
+  # config.legacy_mode = true
+
+  # Name of your user model (default: "User")
   # config.permittable_class = "User"
 
-  # Override AR model class names if you have custom models
-  # config.role_class             = "Rbacan::Role"
-  # config.permission_class       = "Rbacan::Permission"
-  # config.user_role_class        = "Rbacan::UserRole"
-  # config.role_permission_class  = "Rbacan::RolePermission"
+  # Override ActiveRecord model class names if you use custom models
+  # config.role_class = "Rbacan::Role"
+  # config.permission_class = "Rbacan::Permission"
+  # config.user_role_class = "Rbacan::UserRole"
+  # config.role_permission_class = "Rbacan::RolePermission"
+
+  # Host role/permission lookup columns (default: :name)
+  # config.role_key = :code
+  # config.permission_key = :code
 
   # Override table names if needed
-  # config.role_table             = "roles"
-  # config.permission_table       = "permissions"
-  # config.user_role_table        = "user_roles"
-  # config.role_permission_table  = "role_permissions"
-
-  # Primary key type for generated migrations.
-  # Set to :uuid if your app uses UUID primary keys.
-  # When nil, auto-detects from your Rails generator config (primary_key_type).
+  # config.role_table = "roles"
+  # config.permission_table = "permissions"
+  # config.user_role_table = "user_roles"
+  # config.role_permission_table = "role_permissions"
+
+  # Primary key type for migrations.
+  # Set :uuid if your app uses UUID primary keys.
+  # When nil, auto-detects Rails generator config (primary_key_type).
   # config.primary_key_type = :uuid
 
   # Enable tenant scoping for roles and user_roles.
-  # When true, adds tenant_id to the roles and user_roles tables,
-  # allowing tenant-specific roles and role assignments.
-  # Permissions always remain global regardless of this setting.
+  # When true, adds tenant_id to roles and user_roles.
+  # Permissions remain global regardless of this setting.
   # config.tenant_scoped = false
 
-  # The name of your tenant model class (default: "Tenant").
+  # Name of your tenant model class (default: "Tenant").
   # Only used when tenant_scoped is true.
   # config.tenant_class = "Tenant"
 
@@ -33,13 +40,6 @@ Rbacan.configure do |config|
   #   :raise    — raises Rbacan::NotAuthorized (default)
   #   :redirect — redirects to unauthorized_redirect_path
   #   lambda    — called with (controller, permission:, role:)
-  #
   # config.unauthorized_handler = :raise
-  # config.unauthorized_handler = :redirect
-  # config.unauthorized_handler = ->(controller, permission:, role:) {
-  #   controller.render plain: "Forbidden", status: :forbidden
-  # }
-
-  # Path to redirect to when unauthorized_handler is :redirect
   # config.unauthorized_redirect_path = "/"
 end

data/lib/rbacan/authorizable.rb

@@ -0,0 +1,15 @@
+require 'active_support/concern'
+
+module Rbacan
+  module Authorizable
+    extend ActiveSupport::Concern
+
+    def can?(permission, context:)
+      Rbacan.authorized?(user: self, permission: permission, context: context)
+    end
+
+    def has_role?(role, context:)
+      Rbacan.authorized?(user: self, role: role, context: context)
+    end
+  end
+end

data/lib/rbacan/authorization.rb

@@ -1,29 +1,51 @@
 require 'active_support/concern'
+require 'i18n'
 
 module Rbacan
   module Authorization
     extend ActiveSupport::Concern
 
-    included do
-      helper_method :authorized? if respond_to?(:helper_method)
-    end
-
     # Calls the unauthorized handler if current_user lacks the given permission.
-    def authorize!(permission)
-      unless current_user&.can?(permission.to_s)
+    def authorize!(permission, context: nil)
+      allowed = if Rbacan.legacy_mode
+                  current_user&.can?(permission.to_s)
+                else
+                  Rbacan.authorized?(
+                    user: current_user,
+                    permission: permission,
+                    context: context || rbacan_authorization_context
+                  )
+                end
+
+      unless allowed
         _handle_unauthorized(permission: permission.to_s)
       end
     end
 
     # Calls the unauthorized handler if current_user lacks the given role.
-    def authorize_role!(role)
-      unless current_user&.has_role?(role.to_s)
+    def authorize_role!(role, context: nil)
+      allowed = if Rbacan.legacy_mode
+                  current_user&.has_role?(role.to_s)
+                else
+                  Rbacan.authorized?(
+                    user: current_user,
+                    role: role,
+                    context: context || rbacan_authorization_context
+                  )
+                end
+
+      unless allowed
         _handle_unauthorized(role: role.to_s)
       end
     end
 
     private
 
+    def rbacan_authorization_context
+      raise Rbacan::ConfigurationError,
+            'authorization context is required; define rbacan_authorization_context in the host controller'
+    end
+
     def _handle_unauthorized(permission: nil, role: nil)
       handler = Rbacan.unauthorized_handler
 
@@ -31,8 +53,14 @@ module Rbacan
       when :raise
         raise Rbacan::NotAuthorized.new(nil, permission: permission, role: role)
       when :redirect
+        error = Rbacan::NotAuthorized.new(nil, permission: permission, role: role)
+        alert = if Rbacan.legacy_mode
+                  error.message
+                else
+                  I18n.t(error.code, permission: permission, role: role, raise: true)
+                end
         redirect_to Rbacan.unauthorized_redirect_path,
-                    alert: Rbacan::NotAuthorized.new(nil, permission: permission, role: role).message
+                    alert: alert
       else
         if handler.respond_to?(:call)
           handler.call(self, permission: permission, role: role)

data/lib/rbacan/host_authorization.rb

@@ -0,0 +1,165 @@
+module Rbacan
+  class ConfigurationError < StandardError; end
+  class UnsafeLegacyApi < StandardError; end
+
+  class AuthorizationContext
+    ATTRIBUTES = %i[tenant property vertical subject at metadata].freeze
+
+    attr_reader(*ATTRIBUTES)
+
+    def initialize(tenant:, property: nil, vertical: nil, subject: nil, at: Time.now, metadata: {})
+      raise ArgumentError, 'authorization tenant must identify a tenant' unless identifying_tenant?(tenant)
+
+      @tenant = deep_copy_and_freeze(tenant, label: 'authorization tenant')
+      @property = deep_copy_and_freeze(property, label: 'authorization property')
+      @vertical = deep_copy_and_freeze(vertical, label: 'authorization vertical')
+      @subject = deep_copy_and_freeze(subject, label: 'authorization subject')
+      @at = copy_and_freeze_time(at)
+      @metadata = deep_copy_and_freeze(metadata, label: 'authorization metadata')
+      freeze
+    end
+
+    private
+
+    def deep_copy_and_freeze(value, label:)
+      copy = case value
+             when Hash
+               value.to_h do |key, item|
+                 [ deep_copy_and_freeze(key, label: label), deep_copy_and_freeze(item, label: label) ]
+               end
+             when Array
+               value.map { |item| deep_copy_and_freeze(item, label: label) }
+             when String
+               value.dup
+             when Integer
+               value
+             when Float
+               raise ArgumentError, "#{label} supports only finite JSON numbers" unless value.finite?
+
+               value
+             when NilClass, TrueClass, FalseClass, Symbol
+               value
+             else
+               raise ArgumentError,
+                     "#{label} supports only hashes, arrays, strings, numbers, booleans, nil, and symbols"
+             end
+      copy.freeze
+    end
+
+    def copy_and_freeze_time(value)
+      time = value.to_time if value.respond_to?(:to_time)
+      raise ArgumentError, 'authorization timestamp must be time-like' unless time.is_a?(Time)
+
+      time.dup.freeze
+    end
+
+    def identifying_tenant?(value)
+      case value
+      when String, Array, Hash
+        !value.empty?
+      when Integer
+        true
+      when Float
+        value.finite?
+      when Symbol
+        !value.to_s.empty?
+      else
+        false
+      end
+    end
+  end
+
+  class AuthorizationRequest
+    attr_reader :user, :permission, :role, :context
+
+    def initialize(user:, permission:, role:, context:)
+      @user = user
+      @permission = permission&.to_s&.dup&.freeze
+      @role = role&.to_s&.dup&.freeze
+      @context = context
+      freeze
+    end
+  end
+
+  class AssignmentRequest
+    attr_reader :user, :role, :context
+
+    def initialize(user:, role:, context:)
+      @user = user
+      @role = role.to_s.dup.freeze
+      @context = context
+      freeze
+    end
+  end
+
+  class << self
+    def ensure_legacy_mode!(method_name)
+      return if legacy_mode
+
+      raise UnsafeLegacyApi,
+            "#{method_name} is a legacy unscoped API; set Rbacan.legacy_mode = true to opt in"
+    end
+
+    def authorized?(user:, permission: nil, role: nil, context:)
+      validate_authorization_target!(permission, role)
+      validate_context!(context)
+      return false unless user && authorization_adapter
+
+      request = AuthorizationRequest.new(
+        user: user,
+        permission: permission&.to_s,
+        role: role&.to_s,
+        context: context
+      )
+
+      !!call_authorization_adapter(request)
+    end
+
+    def assign_role(user:, role:, context:)
+      call_assignment_adapter(:assign, user: user, role: role, context: context)
+    end
+
+    def revoke_role(user:, role:, context:)
+      call_assignment_adapter(:revoke, user: user, role: role, context: context)
+    end
+
+    private
+
+    def validate_authorization_target!(permission, role)
+      if permission.nil? ^ role.nil?
+        target = permission || role
+        raise ArgumentError, 'authorization permission or role cannot be blank' if target.to_s.empty?
+
+        return
+      end
+
+      raise ArgumentError, 'Provide exactly one permission or role'
+    end
+
+    def validate_context!(context)
+      raise ArgumentError, 'authorization context is required' unless context.is_a?(AuthorizationContext)
+    end
+
+    def call_authorization_adapter(request)
+      if authorization_adapter.respond_to?(:allowed?)
+        authorization_adapter.allowed?(request)
+      elsif authorization_adapter.respond_to?(:call)
+        authorization_adapter.call(request)
+      else
+        raise ConfigurationError, 'authorization adapter must respond to allowed? or call'
+      end
+    end
+
+    def call_assignment_adapter(action, user:, role:, context:)
+      validate_context!(context)
+      raise ArgumentError, 'assignment user is required' unless user
+      raise ArgumentError, 'assignment role is required' if role.nil? || role.to_s.empty?
+      unless assignment_adapter&.respond_to?(action)
+        raise ConfigurationError, "assignment adapter must respond to #{action}"
+      end
+
+      request = AssignmentRequest.new(user: user, role: role.to_s, context: context)
+      assignment_adapter.public_send(action, request)
+    end
+  end
+end

data/lib/rbacan/not_authorized.rb

@@ -1,10 +1,17 @@
 module Rbacan
   class NotAuthorized < StandardError
-    attr_reader :permission, :role
+    attr_reader :permission, :role, :code
 
     def initialize(message = nil, permission: nil, role: nil)
       @permission = permission
-      @role       = role
+      @role = role
+      @code = if permission
+                'rbacan.not_authorized.permission'
+              elsif role
+                'rbacan.not_authorized.role'
+              else
+                'rbacan.not_authorized'
+              end
       super(message || default_message)
     end
 
@@ -16,7 +23,7 @@ module Rbacan
       elsif role
         "Not authorized: missing role '#{role}'"
       else
-        "Not authorized"
+        'Not authorized'
       end
     end
   end