petergate 3.1.1 → 4.0.0

data/lib/petergate/rule.rb

@@ -0,0 +1,34 @@
+module Petergate
+  # One `access` declaration: the scope it authorizes against, the role => actions
+  # rules, and the denial message set alongside them.
+  #
+  # `scope` is the value as written -- a Class for `access Employee`, a Symbol
+  # for `access :member`. It is deliberately not resolved to a Devise scope
+  # here: under STI several classes resolve to the same Devise scope, and rules
+  # are keyed by what was declared so they stay distinct.
+  #
+  # `defaulted` marks a rule that named no scope, so it follows whatever
+  # `petergate_scope` the controller reading it has. That is what makes
+  # `petergate_scope` in a base controller govern rules declared above it, and
+  # it is why the scope is resolved when rules are read rather than written --
+  # rewriting the key at declaration time cannot see the subclasses to come, and
+  # cannot tell a defaulted :user from one someone asked for by name.
+  Rule = Struct.new(:scope, :rules, :message, :defaulted, keyword_init: true) do
+    # The scope this rule authorizes against, for the controller reading it.
+    def scope_for(controller_class)
+      defaulted ? controller_class.petergate_scope : scope
+    end
+  end
+
+  # The hash key a defaulted rule is filed under. A sentinel rather than the
+  # current default, so it stays distinct from `access :user, ...` and cannot
+  # collide with a rule declared for a named scope.
+  DEFAULT_SCOPE = :"petergate.default_scope"
+
+  # Raised when a declared scope has no authentication helper behind it, which
+  # nearly always means a missing `devise_for` or a typo.
+  #
+  # StandardError rather than NameError: applications rescue NameError around
+  # autoloading and would swallow this.
+  class MissingScopeError < StandardError; end
+end

data/lib/petergate/version.rb

@@ -1,3 +1,3 @@
 module Petergate
-  VERSION = "3.1.1"
+  VERSION = "4.0.0"
 end

data/lib/petergate.rb

@@ -1,8 +1,109 @@
 require "petergate/version"
 require "petergate/railtie"
+require "petergate/rule"
 require 'petergate/action_controller/base'
 require 'petergate/active_record/base'
 
 module Petergate
+  # The Devise scope a declared petergate scope resolves to.
+  #
+  # A Symbol is taken at face value: it names the Devise mapping (or, without
+  # Devise, whatever `current_<name>` the application provides). A Class is
+  # looked up in Devise's mappings -- an exact match first, so a model with its
+  # own `devise_for` wins over an ancestor's, which is what `find_scope!` alone
+  # gets wrong for STI. A class with no mapping of its own resolves to its
+  # nearest mapped ancestor: under STI that is the parent's scope, which is
+  # correct, because there is only one login.
+  #
+  # Devise.mappings is read lazily, never at boot: on Rails 8 it calls
+  # reload_routes_unless_loaded.
+  def self.devise_scope_for(declared)
+    return declared unless declared.is_a?(Class)
+    return derived_scope_for(declared) unless defined?(::Devise) && ::Devise.respond_to?(:mappings)
 
+    mappings = ::Devise.mappings
+    exact = mappings.each_value.find { |mapping| mapping.to == declared }
+    return exact.name if exact
+
+    # The ancestor walk find_scope! does internally, minus the raise -- so no
+    # rescue is needed to turn "no mapping" into the fallback.
+    #
+    # A method-level `rescue StandardError` here used to cover ::Devise.mappings
+    # above as well, and reading that loads routes on Rails 8. A NameError in
+    # routes.rb came back as a MissingScopeError naming the scope, which sends
+    # whoever reads it after the wrong bug. A routes error now surfaces as
+    # itself.
+    #
+    # Falling through means Devise is installed but covers nothing this class
+    # descends from, so authentication for it is hand-rolled -- which the README
+    # supports. Fall back to the class's own name.
+    mappings.each_value.find { |mapping| declared <= mapping.to }&.name ||
+      derived_scope_for(declared)
+  end
+
+  # Roles already warned about, and the lock guarding it. Created at load time:
+  # a lazy `||=` would itself race on the authorization path.
+  @warned_roles      = {}
+  @warned_roles_lock = Mutex.new
+
+  # Reports a stored role that the record's own class does not define.
+  #
+  # Once per class and role: this is read on every authorization check, and a
+  # warning per request would be noise rather than a signal. Kernel#warn rather
+  # than ActiveSupport::Deprecation -- nothing is deprecated, and the data is
+  # wrong now.
+  def self.warn_about_unavailable_roles(klass, rejected)
+    rejected.each do |role|
+      key = [klass.name, role]
+
+      # Read before locking. #roles is read once per declared rule on every
+      # request, so for an application whose data has drifted -- exactly the
+      # audience this warning is for -- taking the mutex unconditionally would
+      # serialize every thread on it forever, long after the warning had been
+      # printed. The lock guards the write only, and losing the race costs one
+      # duplicate line.
+      next if @warned_roles.key?(key)
+
+      # Reached from the authorization path of every request, so without this
+      # concurrent threads could mutate the hash while another iterates it.
+      first_time = @warned_roles_lock.synchronize do
+        next false if @warned_roles.key?(key)
+
+        @warned_roles[key] = true
+      end
+      next unless first_time
+
+      warn "petergate: #{klass.name} is ignoring the stored role #{role.inspect}. " +
+           if role.is_a?(String) && klass::ROLES.include?(role.to_sym)
+             "#{klass.name} declares #{role.to_sym.inspect}, but the column holds it as a " \
+             "string. petergate stores roles as symbols, so this row was written by something " \
+             "other than `roles=` -- raw SQL, update_column, or an import."
+           else
+             "#{klass.name} does not declare it; #{klass.name}::ROLES is #{klass::ROLES.inspect}. " \
+             "A record whose type changed, or a role removed from a petergate declaration, " \
+             "leaves roles behind in the column."
+           end
+    end
+  end
+
+  # The scope name a class implies when Devise cannot answer.
+  #
+  # Derived from the STI *base* class, so subclasses sharing one table share one
+  # scope -- `Employee < User` asks `current_user`, which is the whole point of
+  # STI -- while an independent model gets a scope of its own.
+  def self.derived_scope_for(klass)
+    base = klass.respond_to?(:base_class) ? klass.base_class : klass
+    base.model_name.singular_route_key.to_sym
+  rescue StandardError
+    :user
+  end
+
+  # The scope name this class would have entirely on its own, ignoring any
+  # hierarchy. Used only to tell "resolved to something else's login" from
+  # "resolved to its own", which the missing-scope message reports differently.
+  def self.own_scope_name_for(klass)
+    klass.model_name.singular_route_key.to_sym
+  rescue StandardError
+    nil
+  end
 end

data/petergate.gemspec

@@ -24,7 +24,25 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files -z`.split("\x0").reject { |p| p.start_with?("test/", "gemfiles/", ".github/", "assets/") }
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
-  spec.post_install_message = "NOTICE: As of version 1.5.0, the :admin role has been changed to :root_admin."
+
+  # The floor Rails 8.0 and 8.1 already set, so this takes nothing away that
+  # the dependencies below did not. Ruby 4.0 is covered by CI as well; nothing
+  # here is pinned to a major.
+  spec.required_ruby_version = ">= 3.2.0"
+  spec.post_install_message = <<~NOTICE
+    NOTICE: 4.0.0 has three breaking changes. All of them can only take access
+    away, never grant it.
+
+      * `roles` returns only roles the record's own class defines. A role left in
+        the column by a `type` change, or by being dropped from a petergate
+        declaration, no longer grants. Roles set through `roles=` are unaffected.
+      * A subclass declaring `access` now runs the check at its own position in
+        the callback chain, so filters declared above it run before the denial.
+      * `:all` and `except:` cover fewer methods: `all_actions` no longer counts
+        methods that were never actions.
+
+    See CHANGELOG.md.
+  NOTICE
 
   spec.add_development_dependency "bundler", "> 1.7"
   spec.add_development_dependency "rake", ">= 12.3"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: petergate
 version: !ruby/object:Gem::Version
-  version: 3.1.1
+  version: 4.0.0
 platform: ruby
 authors:
 - Isaac Sloan
@@ -104,6 +104,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".ruby-version"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -114,6 +115,7 @@ files:
 - lib/petergate/action_controller/base.rb
 - lib/petergate/active_record/base.rb
 - lib/petergate/railtie.rb
+- lib/petergate/rule.rb
 - lib/petergate/version.rb
 - lib/templates/rails/scaffold_controller/controller.rb
 - petergate.gemspec
@@ -123,8 +125,19 @@ licenses:
 metadata:
   source_code_uri: https://github.com/elorest/petergate
   bug_tracker_uri: https://github.com/elorest/petergate/issues
-post_install_message: 'NOTICE: As of version 1.5.0, the :admin role has been changed
-  to :root_admin.'
+post_install_message: |
+  NOTICE: 4.0.0 has three breaking changes. All of them can only take access
+  away, never grant it.
+
+    * `roles` returns only roles the record's own class defines. A role left in
+      the column by a `type` change, or by being dropped from a petergate
+      declaration, no longer grants. Roles set through `roles=` are unaffected.
+    * A subclass declaring `access` now runs the check at its own position in
+      the callback chain, so filters declared above it run before the denial.
+    * `:all` and `except:` cover fewer methods: `all_actions` no longer counts
+      methods that were never actions.
+
+  See CHANGELOG.md.
 rdoc_options: []
 require_paths:
 - lib
@@ -132,14 +145,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Authorization system allowing verbose easy read controller syntax.
 test_files: []