petergate 3.1.1 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acd5072223d85700246df5acd1445b292a918cf85a3b51b4ee42ae03c3648630
-  data.tar.gz: d084364761c8234ac5db4cc4434e88337913f07dea42cf7d2d3fdc15b3b8261d
+  metadata.gz: 1e7b356d1fe3ebefd2d991eb56b317cb6eca56f6840107598fd3a5fa6eac33d4
+  data.tar.gz: 2d63adb685f6dd63476e21a7f51fa52f10687e87be3155b010c629503bb48619
 SHA512:
-  metadata.gz: ffef6582b1bcd3d55d01c4655dff65a7d12ee47fbefeb32ba2339911db89827923a05e876396261c00849f966ecb36b3470247c057eb99dc60cf0822c8ee26f5
-  data.tar.gz: 9c4e7e84b9e07811651f6cd172f4b32b92540bd47a24a2ec986f028d64b7a3786d3a800aefe879f9d81f04700360a05f007d36148a22dea8b80b5456cc2d938e
+  metadata.gz: b23d89a01df2e68c8257b2e3380703617afb3d13fff7703e3f32de2ac2d34c0c148103af0c12185cc5041d10f90717aa5fa9193ad58352af76e5b9ad663c8dc5
+  data.tar.gz: 5e16dde928a7581e4b5123c23639fde74a773473ff976559317732552adad7c99bcbe22e6ebc0e397e91673b2a41c62da7e6f8958e5752a5bf569e1668c30f90

data/.ruby-version

@@ -1 +1 @@
-3.2.0
+4.0.6

data/CHANGELOG.md

@@ -0,0 +1,142 @@
+# Changelog
+
+## 4.0.0
+
+### Breaking
+
+Three things behave differently for code that already exists, which is what
+makes this 4.0.0 rather than a point release.
+
+All three can only take access away, never grant it, and each fails visibly
+when it bites -- a denial, not a silently widened door. An upgrade cannot
+quietly let someone in who was previously refused, which is the direction an
+authorization library should fail in. That is worth knowing before upgrading,
+but it describes the shape of the risk rather than making the release a
+smaller one than it is.
+
+- **An application whose stored roles have drifted from its declared ones will
+  see those roles stop granting access.** That means a role left behind by an
+  STI `type` change, or one removed from a `petergate` declaration while rows
+  still carry it. See `roles` under Changed.
+
+  Roles written through `roles=` or `role=` are unaffected. Reaching this needs
+  a value the setter never wrote -- from `update_column`, raw SQL, a fixture or
+  an import.
+
+- **A subclass that declares `access` now runs petergate's check at its own
+  position in the callback chain**, not the parent's. Work in a `before_action`
+  declared above it now runs before the denial rather than after. See
+  `petergate_check_access!` under Changed.
+
+- **`:all` and `except:` cover fewer methods**, because `all_actions` no longer
+  counts things that were never actions. An application whose rules were
+  granting one of those was granting a method nobody can route to. See
+  `all_actions` under Changed.
+
+### Added
+
+- `access` can authorize against a model other than `User`. A controller names
+  the model with `petergate_scope`, inherited by its subclasses, or a single
+  rule set names one as `access`'s first argument:
+
+  ```ruby
+  class Staff::BaseController < ApplicationController
+    petergate_scope Employee
+  end
+
+  class InvoicesController < ApplicationController
+    access Vendor, supplier: :all
+    access Employee, admin: [:index]
+  end
+  ```
+
+  One declaration covers both ways an application has several kinds of user:
+  a subclass sharing one login through single table inheritance, and a
+  separately authenticated model with a login of its own. Which one is in play
+  is resolved from Devise's mappings at request time rather than configured.
+
+  Several `access` calls in one class body are OR'd -- whichever scope is
+  satisfied grants the action. A subclass declaring `access` replaces everything
+  it inherited, exactly as before, so narrowing a parent's rules in a subclass
+  still narrows them rather than adding an alternative way in.
+
+  Type matching is exact: `access Employee` does not admit a `Manager < Employee`.
+
+- The denial message can be given as a string before the rules --
+  `access "Staff only", admin: :all` -- so it too is out of the rules hash.
+
+- `logged_in?` and `user_logged_in?` take a `scope:` keyword. Both default to
+  the controller's own scope.
+
+- The install generator takes a model name: `rails g petergate:install Employee`,
+  with an optional `--table-name`. With no argument its output is unchanged.
+
+- `Petergate::MissingScopeError`, raised when a declared scope has no
+  authentication helper behind it, rather than failing quietly.
+
+### Changed
+
+- **`roles` now returns only roles the record's own class defines.** `roles=`
+  has always filtered against `available_roles`, but the reader did not, so a
+  role left in the column by an STI `type` change -- or by a role being dropped
+  from a `petergate` declaration -- kept authorizing. This closes that without a
+  migration. Each ignored role is warned about once, naming the class and the
+  role.
+
+  Roles set through `roles=` or `role=` are unaffected, in either storage mode.
+  A multi-role column holding *strings* rather than symbols is rejected rather
+  than normalized, so this cannot start granting a role that previously matched
+  nothing -- see Breaking.
+
+- `all_actions` returns only actions. Rails' `action_methods` includes public
+  methods inherited from a concrete superclass, so overriding `current_user` in
+  `ApplicationController` -- or using `devise_group` -- put those names into
+  `:all` and `except:` rules as though they were actions. It is now memoized
+  against Rails' own `action_methods`, making it faster than before the fix.
+
+- **petergate's check runs at the position of the `access` call that declared
+  the rules**, for every class that declares them, and there is now exactly one
+  callback however many times `access` is called.
+
+  On 3.1.1 a parent and a subclass each declaring `access` registered two, and
+  the parent's ran first -- so a request was refused before any `before_action`
+  the subclass declared had run. That made `access` unusable in a subclass that
+  has to set its own authentication up first:
+
+  ```ruby
+  class Api::BaseController < ApplicationController
+    before_action :authenticate_from_token
+    access admin: :all                      # now runs after the token lookup
+  end
+  ```
+
+  An application relying on the old ordering -- an early filter written knowing
+  petergate had already refused anonymous requests -- should move that filter
+  below the `access` call. The callback is a named method rather than a block,
+  so `skip_before_action :petergate_check_access!` can also reach it, which it
+  could not before.
+
+### Deprecated
+
+- `controller_rules` and `controller_message` as a way to reach the rules.
+  petergate's own callback no longer calls either, and neither can describe a
+  controller with more than one scope: `controller_rules` returns a single
+  rule's hash, so an application still calling
+  `permissions(self.class.controller_rules)` from its own filter checks one
+  scope of several without saying so. Declare the rules with `access` and let
+  petergate evaluate them.
+
+- `message:` inside the `access` rules hash. Pass the message as a string before
+  the rules instead. The key still works, though a positional string wins when
+  both are given, but it warns, naming the file and line to change.
+
+### Fixed
+
+- `user_logged_in?` is registered as a view helper. It has always been
+  documented as one, but calling it from a view raised `NoMethodError`.
+
+- The install generator no longer sleeps for a second per run.
+
+## 3.1.1 and earlier
+
+Not recorded here; see the commit history.

data/Gemfile

@@ -10,6 +10,18 @@ gem "rails",   "~> 8.1"
 gem "sqlite3", "~> 2.0"
 gem "rake",    ">= 13.0"
 
+# json 3.0 (released 2026-09-07) made JSON.parse's options keyword-only, while
+# ActiveSupport 8.1's ActiveSupport::JSON.decode still passes them positionally
+# -- which breaks encrypted cookies with metadata, and so any test that reads a
+# flash message. Only Rails 8.1 reaches that path.
+#
+# Remove once activesupport ships the fix. What to check is one line --
+# activesupport/lib/active_support/json/decoding.rb: 8.1.3.1 has
+# `::JSON.parse(json, options)`, and the fix reads `::JSON.parse(json, **options)`,
+# which is already what rails main carries:
+# https://github.com/rails/rails/blob/main/activesupport/lib/active_support/json/decoding.rb
+gem "json", "< 3"
+
 # Devise is not a dependency of the gem -- petergate only needs the three
 # authentication methods the README documents. It is here so one test can prove
 # a real Devise app satisfies that contract.

data/README.md

@@ -11,9 +11,13 @@
 
 Requirements
 ------
-Rails 7.1 through 8.1 on Ruby 3.2 through 3.4 are covered by CI. Older Rails
+Rails 7.1 through 8.1 on Ruby 3.2 through 4.0 are covered by CI. Older Rails
 versions are permitted by the gemspec but are not verified.
 
+The gemspec requires Ruby 3.2, which is the floor Rails 8.0 sets. `.ruby-version`
+names the newest covered Ruby rather than the oldest, so development happens on
+the version most likely to surface a deprecation first.
+
 Installation
 ------
 ##### Get the gem
@@ -31,9 +35,6 @@ Or install it yourself as:
 
 ##### Prerequisites: Setup Authentication (Devise)
 
-The generator writes into `app/models/user.rb`, so a model named `User` is the
-supported setup.
-
 If you're using [devise](https://github.com/heartcombo/devise) you're in luck,
 otherwise you'll have to add the following methods to your project:
 
@@ -51,6 +52,12 @@ there.
 
 This will add a migration and insert petergate into your User model.
 
+The model defaults to `User`; pass another to configure it instead. The model
+has to exist already.
+
+    rails g petergate:install Employee            # app/models/employee.rb
+    rails g petergate:install Employee --table-name=staff
+
 Usage
 ------
 #### User Model
@@ -114,8 +121,38 @@ visitors who aren't signed in. The value is one of:
 | `:all` | every action on the controller |
 | `{except: [:destroy]}` | every action except those |
 
-`:root_admin` is not a rule you write -- a user holding it bypasses the rules
-entirely.
+##### The `:root_admin` role
+
+`:root_admin` is the one role name petergate treats specially. It is checked
+before any rule, so a user holding it reaches every action on every controller
+that uses `access`, and no rule ever names it:
+
+```ruby
+class ArticlesController < ApplicationController
+  access all: [:index, :show], editor: :all
+end
+```
+
+An `:editor` gets what the rule says. A `:root_admin` gets all of it too,
+without appearing in the rule at all.
+
+It is not automatic, though. Like any other role it has to be declared before
+anyone can hold it, because `roles=` drops anything the model does not define:
+
+```ruby
+petergate(roles: [:root_admin, :editor], multiple: true)
+```
+
+An application that never declares it has no such bypass, which is a reasonable
+choice -- it exists for the account that must never be locked out of its own
+admin area, not as a convenience for ordinary administrators. Prefer a normal
+role you grant explicitly; reach for `:root_admin` when you specifically want an
+account no `access` rule can shut out.
+
+Two limits. It only applies where `access` is used: a controller with no rules
+has nothing to bypass. And with several authentication scopes on one controller
+it counts only within the scopes that controller declares, so a `:root_admin` in
+one scope cannot walk into a controller whose rules are all about another.
 
 Rules declared on a parent controller are inherited by its subclasses, so a
 single `access` line on `ApplicationController` can cover a whole app.
@@ -124,6 +161,74 @@ single `access` line on `ApplicationController` can cover a whole app.
 refused request answers with a bare `403`, and an unauthenticated one with
 `401`, instead of redirecting.
 
+#### Multiple authentication models
+
+By default every rule is about `current_user`. An application with more than one
+kind of signed-in person can say which one a rule means: `petergate_scope` sets
+it for a whole controller tree, and `access` takes it as a first argument for a
+single rule set.
+
+```ruby
+class Staff::BaseController < ApplicationController
+  petergate_scope Employee     # every controller below this authorizes employees
+end
+
+class Staff::PayrollController < Staff::BaseController
+  access admin: :all, support: [:index, :show]
+end
+
+class InvoicesController < ApplicationController
+  access Vendor, supplier: :all
+  access Employee, admin: [:index]
+end
+```
+
+The same declaration covers both ways of having several kinds of user, because
+petergate reads which one you have off Devise's mappings:
+
+| Declared | Resolves to | Reads |
+| --- | --- | --- |
+| an STI subclass, e.g. `Employee < User` | the parent's scope | `current_user`, required to be exactly an `Employee` |
+| a separately mapped model, e.g. `Vendor` | its own scope | `current_vendor` |
+
+Matching is exact: `access Employee` does not admit a `Manager < Employee`, so
+each kind names itself. A Symbol scope -- `access :member, ...` -- names a Devise
+mapping directly and does no type check, which is what you want for
+`devise_for :users, singular: :member`, where no class carries the name.
+
+Several `access` calls in one class body are **OR**'d: whichever scope is
+satisfied grants the action. A subclass declaring `access` replaces everything it
+inherited, so narrowing a parent's rules in a subclass still narrows them rather
+than adding another way in.
+
+The denial message is positional too -- `access Employee, "Staff only",
+support: :all` -- so the rules hash holds nothing but roles, and no name is
+reserved.
+
+##### Which login a refused person sees
+
+petergate works this out rather than asking you to configure it:
+
+| | |
+| --- | --- |
+| the scope holds nobody | `unauthorized!` -- that scope's `authenticate_*!` |
+| the scope holds someone of the wrong kind | `forbidden!` |
+
+So a customer who reaches an employee-only page under STI is refused outright:
+there is one login and they are already through it. A customer who reaches a
+`Vendor` page is sent to the vendor login instead, because that scope really is
+empty -- and with Devise they can sign in there without losing the session they
+already have, since Warden keys sessions per scope.
+
+With several scopes declared and nobody signed in to any of them, the login
+comes from `petergate_scope`, or from the first scope declared if the controller
+has no `petergate_scope` of its own.
+
+If a scope has no `current_*` behind it at all, petergate raises
+`Petergate::MissingScopeError` rather than failing quietly. The message says
+whether the class needs a `devise_for` of its own, shares a login with a parent
+class, or is not an authenticatable model at all.
+
 Inside your views you can use logged_in?(:admin, :customer, :etc) to show or hide content.
 
 ```erb
@@ -133,6 +238,15 @@ Inside your views you can use logged_in?(:admin, :customer, :etc) to show or hid
 `logged_in?` tests roles. To ask only whether anyone is signed in, without
 caring which role they hold, use `user_logged_in?`.
 
+Both resolve against the controller's own scope, and both take a `scope:` to ask
+about another one. Both are type-exact, so under `petergate_scope Employee` a
+signed-in `Manager < Employee` answers `false` -- it asks "is an Employee signed
+in", not "is anybody":
+
+```erb
+<%= link_to "Payroll", payroll_path if logged_in?(:admin, scope: Employee) %>
+```
+
 If you need to access available roles within your project you can by calling:
 
 ```ruby
@@ -141,7 +255,27 @@ User.first.available_roles # the same list, from an instance
 ```
 
 `ROLES` is a constant on the model, so it is also reachable from your own
-instance methods. A subclass shares its parent's roles.
+instance methods. A subclass shares its parent's roles unless it calls
+`petergate` itself, which gives it a vocabulary of its own -- useful with single
+table inheritance, where each kind of user needs different roles:
+
+```ruby
+class User < ApplicationRecord
+  petergate(roles: [:customer], multiple: true)
+end
+
+class Employee < User
+  petergate(roles: [:admin, :support], multiple: true)
+end
+
+Employee::ROLES # => [:admin, :support, :user]
+```
+
+`roles` only ever returns roles the record's own class defines. A role in the
+column that the class does not define is ignored, and warned about once. This
+matters when a record's `type` changes, or when a role is dropped from a
+`petergate` declaration: the column outlives whatever wrote it, and a leftover
+role must not keep granting access.
 
 #### Denying access yourself
 
@@ -169,21 +303,28 @@ which has no format negotiation to offer.
 ##### The denial message
 
 `forbidden!` takes one for a single call, and `access` sets a default for the
-whole controller:
+whole controller -- as a string before the rules:
 
 ```ruby
 forbidden! "Your account is suspended"
 
-access user: [:show, :index], message: "You shall not pass"
+access "You shall not pass", user: [:show, :index]
+access Employee, "Staff only", support: :all
 ```
 
+Like the scope, it sits outside the rules hash so it cannot be confused with a
+role.
+
+The `message:` key is deprecated. It still works and a positional string wins if
+both are given, but it warns, naming the file and line to change.
+
 The message is resolved in this order, first match winning:
 
 | | Source |
 | --- | --- |
 | 1 | the argument passed to `forbidden!` |
 | 2 | an `msg` request header |
-| 3 | the `message:` option on `access` |
+| 3 | the message given to `access` (or the deprecated `message:` key) |
 | 4 | `"Permission Denied"` |
 
 Note the second entry: the `msg` header is read off the request, so a caller

data/lib/generators/petergate/install_generator.rb

@@ -7,19 +7,34 @@ module Petergate
       source_root File.expand_path("../templates", __FILE__)
 
       desc "Sets up rails project for Petergate Authorizations"
-      def self.next_migration_number(path)
-        sleep 1
-        Time.now.utc.strftime("%Y%m%d%H%M%S")
+
+      argument :model_name, type: :string, default: "User", banner: "ModelName"
+      class_option :table_name, type: :string,
+                   desc: "Table to add the roles column to (defaults to the model's table)"
+
+      # Rails' own idiom: a bare timestamp collides when the generator runs
+      # twice inside one second, which the old code papered over with a
+      # `sleep 1` on every run.
+      def self.next_migration_number(dirname)
+        # ::ActiveRecord -- inside module Petergate the bare name finds
+        # Petergate::ActiveRecord, the mixin namespace.
+        ::ActiveRecord::Migration.next_migration_number(current_migration_number(dirname) + 1)
       end
 
       def insert_into_user_model
-        inject_into_file "app/models/user.rb", after: /^class\sUser < ActiveRecord::Base|^class User < ApplicationRecord/ do
+        unless File.exist?(File.join(destination_root, model_path))
+          raise Thor::Error, "#{model_path} does not exist. Generate the model first, " \
+                             "or pass the name of one that does."
+        end
+
+        inject_into_file model_path, after: model_declaration_pattern do
           <<-'RUBY'
 
   ############################################################################################
   ## PeterGate Roles                                                                        ##
   ## The :user role is added by default and shouldn't be included in this list.             ##
-  ## The :root_admin can access any page regardless of access settings. Use with caution!   ##
+  ## Add :root_admin to this list for a role that reaches every action whatever             ##
+  ## the access rules say. Nobody can hold it until it is declared here.                    ##
   ## The multiple option can be set to true if you need users to have multiple roles.       ##
   petergate(roles: [:admin, :editor], multiple: false)                                      ##
   ############################################################################################ 
@@ -38,12 +53,46 @@ module Petergate
   #       end
   #     end
 
+      # The destination filename is the only thing that sets a migration's class
+      # name -- Rails derives @migration_class_name from it -- so it has to
+      # carry the table name rather than being copied from the template's own.
       def create_migrations
-        Dir["#{self.class.source_root}/migrations/*.rb"].sort.each do |filepath|
-          name = File.basename(filepath)
-          migration_template "migrations/#{name}", "db/migrate/#{name}"
-        end
+        migration_template "migrations/add_roles_to_users.rb",
+                           "db/migrate/add_roles_to_#{roles_table_name}.rb"
       end
+
+      private
+        def model_class_name
+          model_name.camelize
+        end
+
+        # `class Admin::User < ...` declares the demodulized name.
+        def bare_class_name
+          model_class_name.split("::").last
+        end
+
+        def model_path
+          File.join("app/models", "#{model_class_name.underscore}.rb")
+        end
+
+        # Rails writes a namespaced model either compactly --
+        # `class Admin::User < ApplicationRecord` -- or nested inside
+        # `module Admin`, where the line reads `class User < ...`. Match both.
+        def model_declaration_pattern
+          names = [model_class_name, bare_class_name].uniq.map { |n| Regexp.escape(n) }
+          /^\s*class\s+(?:#{names.join("|")})\s+<\s+\S+.*$/
+        end
+
+        # Ask the model where it actually lives. `Admin::User` is `users` unless
+        # the namespace defines a table_name_prefix, and only the class knows
+        # which -- `tableize` would guess `admin_users` either way.
+        def roles_table_name
+          return options[:table_name] if options[:table_name]
+
+          model_class_name.constantize.table_name
+        rescue StandardError
+          model_class_name.demodulize.tableize
+        end
     end
   end
 end

data/lib/generators/petergate/templates/migrations/add_roles_to_users.rb

@@ -1,5 +1,5 @@
-class AddRolesToUsers < ActiveRecord::Migration<%= Rails::VERSION::MAJOR >= 5 ? "[#{Rails.version.to_f}]" : "" %>
+class <%= migration_class_name %> < ActiveRecord::Migration<%= Rails::VERSION::MAJOR >= 5 ? "[#{Rails.version.to_f}]" : "" %>
   def change
-    add_column :users, :roles, :string
+    add_column :<%= roles_table_name %>, :roles, :string
   end
 end