banken 1.0.3 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 4faea250e6de5c7022b73be747b18978e4569a1e
-  data.tar.gz: fe8b0f64b93b370f9beaa04ea581180a4d2b3760
+SHA256:
+  metadata.gz: 76fb7526d0910217060fb72f1c1fa941bc7d8afe4a92a9f1ee08ab7ef3d8d3d1
+  data.tar.gz: 57d909cf4bc3337d62fc2f8c944abc06f5256fde7604bf55d02d261c2e9a0219
 SHA512:
-  metadata.gz: 49a1116ac331febca898385de35fcd0c518840cb3eab76cca7e266c99832f19572063573d8f6d3b9f18c97271885091d636594429d1ffbcbb22d44c82cfb1ae7
-  data.tar.gz: 711723dd4d3c2118624d7dca4bcaaeddef0bf203c30c063d18833df70644495634984da76196bddd6c68b685c5f7e3a232e55c808c0e5f9c672e9e6414fa6c64
+  metadata.gz: e8840887cc92393a79b1ba6b6dcac8e31fddd330bc54bb3c6d8be0b28666db791244ada3e391e429f8a064a28536d5f19bb3fd860bbb736248d0eacdc036f509
+  data.tar.gz: dfdab031e56c3fd23213c6f2e72ae9dccd8f19b379a82d292869b40e82fb044ea37cda788bb02b0bc3cfc9d9f8cf8c8ec22d64ee2f4d017e4a79615cc3f292dc

data/CHANGELOG.md

@@ -1,3 +1,185 @@
+## 1.1.0 (2026-10-26)
+
+Requires Ruby >= 3.3 and Rails >= 7.1. No public methods or constants were removed. CI covers
+Ruby 3.3 / 3.4 / 4.0 x Rails 7.1 / 7.2 / 8.0 / 8.1.
+
+### Upgrading from 1.0.x
+
+No breaking changes to the public API: no method, constant or argument was removed or changed
+its signature, `include Banken` keeps working unchanged (`include Banken::Authorization` is the
+recommended form from now on), and an application that upgrades without touching its code keeps
+authorizing the same requests. What follows are behaviour changes, most of them closing security
+gaps or replacing confusing errors with clear ones, that can affect code or tests relying on the
+old behaviour. Details in the sections below.
+
+* The default `Banken::NotAuthorizedError` message changed from
+  `not allowed to update? of posts by #<PostsLoyalty ...>` to
+  `not allowed to PostsLoyalty#update? on posts`. Code or tests matching on the message text
+  must change; the `controller`, `query` and `loyalty` attributes are unchanged.
+* A query the loyalty does not define raises `Banken::QueryNotDefinedError` (a subclass of
+  `NotDefinedError`) instead of `NoMethodError`; code rescuing or asserting `NoMethodError` there
+  must change, and a `rescue_from Banken::NotDefinedError` now also catches it. Queries inherited
+  from `Object` (an action named `present` or `duplicable`) and private queries raise it too.
+* Anonymous controllers (`controller_path` nil) raise `NotDefinedError` from `authorize!` and
+  `loyalty`; pass the controller name explicitly (`loyalty(record, :posts)`). On a Rails controller
+  `params[:controller]` / `params[:action]` are never consulted any more.
+* Banken's helpers (`authorize!`, `loyalty`, `skip_authorization`, `verify_authorized`,
+  `banken_user`, `permitted_attributes`, `banken_authorization_performed?`,
+  `banken_loyalty_authorized?`) are no longer routable actions, and neither is an application
+  action that carries one of those names.
+* The `Banken::AuthorizationNotPerformedError` message changed from the bare class name to
+  `PostsController#update did not call authorize! or skip_authorization`.
+* `NotAuthorizedError#controller` (and the messages) carry `controller_path`, which differs from
+  the old `params[:controller]` when the controller overrides `self.controller_path` or when the
+  route name does not round-trip through camelize/underscore (`users_2fa` -> `Users2faController`
+  -> `users2fa`). The loyalty resolved is the same.
+* `permitted_attributes`: a scalar or array params value raises `ActionController::ParameterMissing`
+  (400) instead of `NoMethodError` (500); `nil` and anonymous classes raise `ArgumentError`; the
+  params key is derived from the class's `name` (no longer `to_s`), which matters only for classes
+  overriding one of them.
+* Errors raised while a loyalty file loads now propagate instead of becoming
+  `Banken::NotDefinedError`; a `rescue_from Banken::NotDefinedError` no longer catches them.
+* The controller `loyalty` helper no longer calls `Banken.loyalty!`; stubs on `Banken.loyalty!`
+  stop intercepting controller lookups (stub `Banken::LoyaltyFinder` instead). The memoized loyalty
+  class is kept in `@_banken_loyalty_classes`, which shows up in `view_assigns` / `assigns` next to
+  the existing `@_banken_authorization_performed`.
+* `config.action_dispatch.rescue_responses` matches exact class names (Rails behaviour): a mapping
+  for `Banken::NotDefinedError` does not cover `Banken::QueryNotDefinedError`.
+* `rails g banken:loyalty` no longer invokes a `test_framework` generator; a custom
+  `test_unit:loyalty` / `rspec:loyalty` generator must be invoked directly.
+* Ruby < 3.3 and Rails < 7.1 are no longer supported; such environments keep resolving 1.0.3.
+
+### Requirements
+
+* Ruby >= 3.3 and Rails (Active Support) >= 7.1. Supported matrix: Ruby 3.3 / 3.4 / 4.0 x Rails
+  7.1 / 7.2 / 8.0 / 8.1. Environments below these floors keep resolving 1.0.3.
+
+### Security
+
+* The default `Banken::NotAuthorizedError` message no longer embeds `loyalty.inspect`, which
+  included the inspected user and record (every instance variable of plain Ruby objects; for Active
+  Record models every attribute not covered by `filter_attributes`) and reached logs, error trackers
+  and any `flash` built from the message. The message is now `not allowed to PostsLoyalty#update? on
+  posts`. The `controller`, `query` and `loyalty` attributes are unchanged.
+* `authorize!` only consults queries defined by the loyalty itself (or a module or superclass below
+  `Object`). ActiveSupport defines `present?` and `duplicable?` on every object and both return
+  `true`, so an action named `present` or `duplicable` passed `authorize!` with a loyalty that
+  defined nothing. Such queries, undefined queries and private queries now raise
+  `Banken::QueryNotDefinedError`; queries answered through `method_missing` keep working.
+* For routes that target an endpoint directly (`get "/x" => PostsController.action(:destroy)`,
+  `mount`), the path parameters carry no controller or action, so the previous inference read them
+  from the query string and a request could pick which loyalty and query were checked. The loyalty
+  and query now come from the controller class and the dispatched action.
+* On a Rails controller, `params[:controller]` / `params[:action]` are never consulted any more.
+  Anonymous controllers (`controller_path` nil) used to fall back to `params[:controller]`, which
+  comes from the query string there, letting a request choose the loyalty. They now raise
+  `NotDefinedError`; pass the controller name to `loyalty` explicitly.
+* Banken's helpers are excluded from the controller's `action_methods`, so routes with a dynamic
+  `:action` segment can no longer dispatch to `skip_authorization`, `verify_authorized` and the
+  others. Same as Pundit #269 / #357.
+
+### Added
+
+* `Banken::Authorization`, the controller mixin. Prefer `include Banken::Authorization` over
+  `include Banken`: including the top-level module also makes every constant under `Banken` (`Error`,
+  `VERSION`, `LoyaltyFinder`, `Railtie`, ...) resolvable inside the controller, shadowing application
+  constants of the same name. `include Banken` keeps working (it includes `Banken::Authorization`)
+  and will be deprecated in 2.0. Same motivation as Pundit 2.2.0's `Pundit::Authorization`.
+* `Banken::QueryNotDefinedError < Banken::NotDefinedError`, raised when the loyalty exists but the
+  query is undefined, private or inherited from `Object`.
+* `Banken.deprecator`, an `ActiveSupport::Deprecation` instance, and `Banken::Railtie`, which
+  registers it with `Rails.application.deprecators` so `config.active_support.deprecation` applies
+  to Banken (its `:notify` events are published as `deprecation.banken`). If banken is required
+  after Rails has initialized (for example `require: false` plus a later `require`), register it
+  yourself with `Rails.application.deprecators[:banken] = Banken.deprecator`.
+* Two private hooks overridable in the controller: `banken_param_key(record)` (defaults to the
+  demodulized, underscored class name) and `banken_params_for(record)` (defaults to
+  `params.require(banken_param_key(record))`).
+* `permitted_attributes` accepts a class or a Symbol as the record (`permitted_attributes(Post)` and
+  `permitted_attributes(:post)` both read `params[:post]`).
+
+### Fixed
+
+* `banken_loyalty_authorized?` raised `NoMethodError` on Rails >= 7.2 because it called the
+  removed `ActiveSupport::Deprecation` singleton. It now warns through `Banken.deprecator`.
+* Errors raised while a loyalty file loads (for example a `NoMethodError` from a typo in the class
+  body, or a `NameError` for an unrelated constant) now propagate instead of being reported as
+  `Banken::NotDefinedError`. `LoyaltyFinder` uses `safe_constantize`, so only `NameError`s that name
+  the loyalty constant or one of its namespaces (including Zeitwerk's "expected file to define
+  constant" error for a file that defines the wrong constant name) still surface as `NotDefinedError`.
+  The `NotDefinedError` message now also names the file expected to define the loyalty.
+* `permitted_attributes(Post)` reads `params[:post]` (it used to read `params[:class]`); a scalar or
+  array value raises `ActionController::ParameterMissing` (400) instead of `NoMethodError` (500);
+  `nil` raises `ArgumentError` instead of reading `params[:nil_class]`; an anonymous class raises
+  `ArgumentError`.
+* `verify_authorized` says which controller and action forgot to authorize
+  (`PostsController#update did not call authorize! or skip_authorization`).
+* An empty controller name no longer resolves a top-level `Loyalty` constant; `Banken.loyalty!(nil, ...)`
+  raises `NotDefinedError` ("no controller name was given").
+* `Banken::NotAuthorizedError.new` accepts any non-Hash argument as the message (e.g. `nil` or a
+  Symbol) instead of raising `NoMethodError`.
+* `rails g banken:loyalty` no longer prints `error  test_unit [not found]` (or `rspec [not found]`):
+  the generator asked the configured test framework for a `loyalty` generator that Banken never
+  shipped. It now only creates the loyalty file; a `--test-framework` option is ignored if passed.
+
+### Changed
+
+* The loyalty and the query are inferred from `controller_path` and `action_name` instead of
+  `params[:controller]` / `params[:action]`; params are read only on hosts that provide neither
+  (plain Ruby objects). Routed requests resolve the same loyalty as before; `NotAuthorizedError#controller`
+  is now `controller_path`, which differs from `params[:controller]` when the controller overrides
+  `self.controller_path` (the loyalty is then looked up from the overridden value) or when the route
+  name does not round-trip through camelize/underscore (`users_2fa` -> `users2fa`). `authorize!` and
+  `loyalty` now also work when a controller is dispatched directly
+  (`PostsController.action(:index).call(env)`), and `loyalty` resolves inside
+  `ActionController::Renderer` (there is no action there, so `authorize!` raises a `Banken::Error`
+  explaining that instead of a `NoMethodError` for `?`).
+* `loyalty` resolves the loyalty class once per controller instance (per request) instead of on
+  every call; loyalty instances are still created fresh for each record and the current
+  `banken_user`. The controller helper no longer goes through `Banken.loyalty!` (which is unchanged).
+* `permitted_attributes` derives the params key from the class's `name` instead of `record.class.to_s`.
+
+### Deprecated (removal planned for 2.0)
+
+* `include Banken` in controllers (use `include Banken::Authorization`); no warning is emitted yet.
+* `banken_loyalty_authorized?` (use `banken_authorization_performed?`); it now warns through
+  `Banken.deprecator`.
+* `Banken::LoyaltyScopingNotPerformedError`, which nothing raises.
+
+### Packaging and documentation
+
+* The gem ships only `lib/`, README, CHANGELOG, LICENSE and SECURITY.md (no more Gemfile, Rakefile,
+  gemfiles/ or CI config); `rubygems_mfa_required` is set, so publishing needs MFA; banken no longer
+  requires `active_support/core_ext/module/introspection`, which it never used. Generator templates
+  are shipped as `.rb.tt` files, the Rails convention.
+* README rewritten for Rails 7.1+ (`update` instead of `update_attributes`, no Rails 4 /
+  strong_parameters notes), the `rescue_from` examples use
+  `redirect_back_or_to(root_path, allow_other_host: false)` instead of redirecting to the `Referer`
+  header (an open redirect or an `UnsafeRedirectError`, depending on the app's open-redirect
+  configuration), `rescue_responses` documented as an alternative, inference from `controller_path` /
+  `action_name` explained, naming caveat for an action called `loyalty`, `Banken.loyalty!` for use
+  outside controllers, `after_action :verify_authorized` without `except: :index` (Banken has no
+  scopes), the `UserContext` example returns nil for anonymous requests so a "must be logged in"
+  guard still works, queries must return booleans, `permitted_attributes` uses the current
+  controller's loyalty, never pass request data as the controller name to `loyalty`. Added SECURITY.md.
+
 ## 1.0.3 (2019-01-14)
 
-* Renamed `banken_loyalty_authorized?` to `banken_authorization_performed?` (okuramasafumi)
+* Renamed `banken_loyalty_authorized?` to `banken_authorization_performed?`; the old name emits a
+  deprecation warning (okuramasafumi)
+* README: how to call a namespaced loyalty from a view (`loyalty(@post, 'admin/posts')`)
+
+## 1.0.2 (2016-01-30)
+
+* Removed the loyalty cache and the public `loyalties` method; `loyalty` builds a new instance on every
+  call (the 1.0.1 cache ignored the controller name)
+
+## 1.0.1 (2016-01-30)
+
+* Fixed `loyalty` returning the same instance for different records: the cache, keyed per controller
+  since 1.0.0, is now keyed by record (#1, tkawa)
+
+## 1.0.0 (2015-12-05)
+
+* First stable release: `authorize!`, `loyalty`, `permitted_attributes`, `verify_authorized`,
+  `skip_authorization`, `banken_user`, `banken:install` and `banken:loyalty` generators

data/README.md

@@ -1,39 +1,51 @@
 <img width="350" src="https://raw.github.com/wiki/kyuden/banken/images/banken.png">
 
-[![Build Status](https://img.shields.io/travis/kyuden/banken/master.svg)](https://travis-ci.org/kyuden/banken)
-[![Code Climate](https://codeclimate.com/github/kyuden/banken/badges/gpa.svg)](https://codeclimate.com/github/kyuden/banken)
+[![CI](https://github.com/kyuden/banken/actions/workflows/ci.yml/badge.svg)](https://github.com/kyuden/banken/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/banken.svg)](https://badge.fury.io/rb/banken)
 
 Simple and lightweight authorization library for Rails inspired by Pundit.
 Banken provides a set of helpers which restricts what resources
 a given user is allowed to access.
 
-In first, Look this tutorial:
+Start with the tutorial:
  - [Tutorial](https://github.com/kyuden/banken/wiki/Tutorial)
  - [Tutorial (Japanese)](https://github.com/kyuden/banken/wiki/Tutorial-(japanese))
 
-========
 ## What's the difference between Banken and Pundit?
  - [The difference between Banken and Pundit](https://github.com/kyuden/banken/wiki/The-difference-between-Banken-and-Pundit)
  - [The difference between Banken and Pundit (Japanese)](https://github.com/kyuden/banken/wiki/The-difference-between-Banken-and-Pundit-(Japanese))
 
- 
 ## Installation
 
 ``` ruby
 gem "banken"
 ```
 
-Include Banken in your application controller:
+Supported versions (tested in CI):
+
+| Ruby | Rails |
+|---|---|
+| 3.3, 3.4, 4.0 | 7.1, 7.2, 8.0, 8.1 |
+
+Ruby versions follow the official end-of-life schedule; Rails versions that
+reached end-of-life are dropped gradually as applications move on. Environments
+below these floors stay on banken 1.0.3, which works on Rails 7.1 and older.
+
+Include `Banken::Authorization` in your application controller
+(`ActionController::API` works too):
 
 ``` ruby
 # app/controllers/application_controller.rb
 class ApplicationController < ActionController::Base
-  include Banken
-  protect_from_forgery
+  include Banken::Authorization
 end
 ```
 
+`include Banken` (the pre-1.1 form) still works and will be deprecated in 2.0.
+Avoid it: it also brings every constant under the `Banken` namespace (`Error`,
+`VERSION`, `LoyaltyFinder`, ...) into the controller's constant lookup, where it
+shadows application constants of the same name.
+
 Optionally, you can run the generator, which will set up an application loyalty
 with some useful defaults for you:
 
@@ -107,7 +119,7 @@ class PostsController < ApplicationController
     if @post.update(post_params)
       redirect_to @post
     else
-      render :edit
+      render :edit, status: 422
     end
   end
 end
@@ -123,8 +135,8 @@ and the given optional object. It then infers from the action name, that it shou
 raise "not authorized" unless PostsLoyalty.new(current_user, @post).update?
 ```
 
-If you don't have an optional object for the first argument to `authorize!`, then you can pass
-the class. For example:
+If there is no record to check, call `authorize!` without an argument (the
+loyalty then receives `nil` as its record), or pass the class. For example:
 
 Loyalty:
 ```ruby
@@ -157,9 +169,15 @@ conditionally showing links or buttons in the view:
 <% end %>
 ```
 
-If you are using namespace in your controller and policy,
-you can access the policy passing string like 'admin/posts' as a second argument.
-Below calls Admin::PostsLoyalty.
+Banken infers the loyalty from the controller path (`controller_path`) and the
+query from the action name (`action_name`). A namespaced controller such as
+`Admin::PostsController` (controller path `admin/posts`) therefore uses
+`Admin::PostsLoyalty`, which lives in `app/loyalties/admin/posts_loyalty.rb`.
+The same applies to controllers inside Rails engines: `Blorgh::PostsController`
+uses `Blorgh::PostsLoyalty`. There is no fallback to a top-level loyalty.
+
+To use another controller's loyalty, pass its controller path as the second
+argument. Below calls `Admin::PostsLoyalty`:
 
 ``` erb
 <% if loyalty(@post, 'admin/posts').update? %>
@@ -167,6 +185,35 @@ Below calls Admin::PostsLoyalty.
 <% end %>
 ```
 
+Banken also works for controllers dispatched without the router
+(`PostsController.action(:index).call(env)`). In templates rendered through
+`ActionController::Renderer` (`PostsController.render ...`), `loyalty` infers
+the loyalty from the controller the renderer was called on; `authorize!` cannot
+be used there because no action is running.
+
+A query is only consulted if the loyalty (or a module or superclass of it)
+defines it (`method_missing` counts); methods every Ruby object has, such as
+`present?`, do not, and an undefined or private query raises
+`Banken::QueryNotDefinedError`, a subclass of `NotDefinedError`. Return `true` or `false`
+from queries: any truthy value authorizes.
+
+The second argument of `loyalty` must come from your code, never from the
+request: it selects which loyalty class is instantiated.
+
+**Naming caveat:** `loyalty` is a public method on your controllers. Do not
+define a controller action named `loyalty`, or it will shadow the helper. The
+helper is scheduled to be renamed to `banken_loyalty` (with `loyalty` kept as an
+alias) in 2.0.
+
+## Using loyalties outside controllers
+
+`Banken.loyalty!` builds a loyalty from a controller path, a user and a record,
+for jobs, GraphQL resolvers or anywhere there is no controller:
+
+``` ruby
+Banken.loyalty!('admin/posts', user, post).update?
+```
+
 ## Ensuring loyalties are used
 
 Banken adds a method called `verify_authorized` to your controllers. This
@@ -177,10 +224,15 @@ forgotten to authorize the action. For example:
 ``` ruby
 # app/controllers/application_controller.rb
 class ApplicationController < ActionController::Base
-  after_action :verify_authorized, except: :index
+  after_action :verify_authorized
 end
 ```
 
+`verify_authorized` runs after the action, so it is a development-time safety
+net that turns a forgotten `authorize!` into an error; it does not stop the
+action from running. Do not exempt `index`: Banken has no scope feature, so an
+index action needs `authorize!` like any other.
+
 
 If you're using `verify_authorized` in your controllers but need to
 conditionally bypass verification, you can use `skip_authorization`.
@@ -202,8 +254,8 @@ end
 ```
 
 If you need to perform some more sophisticated logic or you want to raise a custom
-exception you can use the two lower level method `banken_authorization_performed?` which
-return `true` or `false` depending on whether `authorize!` have been called, respectively.
+exception you can use the lower-level method `banken_authorization_performed?`, which
+returns `true` or `false` depending on whether `authorize!` (or `skip_authorization`) has been called.
 
 ## Just plain old Ruby
 
@@ -253,15 +305,14 @@ end
 ## Rescuing a denied Authorization in Rails
 
 Banken raises a `Banken::NotAuthorizedError` you can
-[rescue_from](http://guides.rubyonrails.org/action_controller_overview.html#rescue-from)
+[rescue_from](https://guides.rubyonrails.org/action_controller_overview.html#rescue-from)
 in your `ApplicationController`. You can customize the `user_not_authorized`
 method in every controller.
 
 ```ruby
 # app/controllers/application_controller.rb
 class ApplicationController < ActionController::Base
-  protect_from_forgery
-  include Banken
+  include Banken::Authorization
 
   rescue_from Banken::NotAuthorizedError, with: :user_not_authorized
 
@@ -269,44 +320,63 @@ class ApplicationController < ActionController::Base
 
   def user_not_authorized
     flash[:alert] = "You are not authorized to perform this action."
-    redirect_to(request.referrer || root_path)
+    redirect_back_or_to(root_path, allow_other_host: false)
   end
 end
 ```
 
+Do not redirect to `request.referrer`: the `Referer` header is controlled by
+the client. Depending on your open-redirect configuration that either sends the
+user to another site or raises `ActionController::Redirecting::UnsafeRedirectError`.
+`redirect_back_or_to` falls back to `root_path` when there is no referrer, and
+`allow_other_host: false` makes it fall back for off-site referrers too,
+whatever `raise_on_open_redirects` / `action_on_open_redirect` are set to.
+
+If you only need the status code, map the error to 403 and let Rails render it:
+
+```ruby
+# config/application.rb
+config.action_dispatch.rescue_responses["Banken::NotAuthorizedError"] = :forbidden
+```
+
+Without either, an unrescued `NotAuthorizedError` is a 500. `rescue_responses`
+matches exact class names, so a mapping for `Banken::NotDefinedError` does not
+cover `Banken::QueryNotDefinedError`; `rescue_from Banken::NotDefinedError` does.
+
 ## Creating custom error messages
 
-`NotAuthorizedError`s provide information on what query (e.g. `:create?`), what
-controller (e.g. `PostsController`), and what loyalty (e.g. an instance of
-`PostsLoyalty`) caused the error to be raised.
+`NotAuthorizedError`s provide information on what query (e.g. `"create?"`), what
+controller (the controller path, e.g. `"posts"` or `"admin/posts"`), and what
+loyalty (e.g. an instance of `PostsLoyalty`) caused the error to be raised. The
+default message names only these, never the user or the record.
 
-One way to use these `query`, `record`, and `loyalty` properties is to connect
+One way to use these `query`, `controller`, and `loyalty` properties is to connect
 them with `I18n` to generate error messages. Here's how you might go about doing
 that.
 
 ```ruby
 # app/controllers/application_controller.rb
 class ApplicationController < ActionController::Base
- rescue_from Banken::NotAuthorizedError, with: :user_not_authorized
+  rescue_from Banken::NotAuthorizedError, with: :user_not_authorized
 
- private
+  private
 
- def user_not_authorized(exception)
-   loyalty_name = exception.loyalty.class.to_s.underscore
+  def user_not_authorized(exception)
+    loyalty_name = exception.loyalty.class.to_s.underscore
 
-   flash[:error] = t "#{loyalty_name}.#{exception.query}", scope: "banken", default: :default
-   redirect_to(request.referrer || root_path)
- end
+    flash[:error] = t "#{loyalty_name}.#{exception.query}", scope: "banken", default: :default
+    redirect_back_or_to(root_path, allow_other_host: false)
+  end
 end
 ```
 
 ```yaml
 en:
- banken:
-   default: 'You cannot perform this action.'
-   posts_loyalty:
-     update?: 'You cannot edit this post!'
-     create?: 'You cannot create posts!'
+  banken:
+    default: 'You cannot perform this action.'
+    posts_loyalty:
+      update?: 'You cannot edit this post!'
+      create?: 'You cannot create posts!'
 ```
 
 Of course, this is just an example. Banken is agnostic as to how you implement
@@ -316,14 +386,46 @@ your error messaging.
 
 In some cases your controller might not have access to `current_user`, or your
 `current_user` is not the method that should be invoked by Banken. Simply
-define a method in your controller called `banken_user`.
+define a method in your controller called `banken_user`. The Rails 8
+authentication generator, for example, exposes the user as `Current.user` and
+defines no `current_user`:
 
 ```ruby
-def banken_user
-  User.find_by_other_means
+class ApplicationController < ActionController::Base
+  include Banken::Authorization
+
+  private
+    def banken_user
+      Current.user
+    end
 end
 ```
 
+Define `banken_user` in the controller class itself (or in a module included
+*after* `Banken::Authorization`): a module included before it is shadowed by
+Banken's default, which silently keeps calling `current_user`. The loyalty is
+built fresh with the current `banken_user` on every call, so changing the user
+mid-request needs no reset.
+
+Banken keeps its own helpers (`authorize!`, `loyalty`, `banken_user`,
+`skip_authorization`, `verify_authorized`, `permitted_attributes`, ...) out of
+the controller's `action_methods`, so a wildcard route cannot dispatch to them
+even though they are public; a `banken_user` override is covered by that too.
+
+## Deprecation warnings
+
+Banken reports its own deprecations through `Banken.deprecator`, an
+`ActiveSupport::Deprecation` instance. When banken is loaded by Bundler in the
+usual way (after `require "rails/all"`), `Banken::Railtie` registers it with
+`Rails.application.deprecators`, so `config.active_support.deprecation` and
+`config.active_support.report_deprecations` apply to Banken as well (with the
+`:notify` behaviour the events are published as `deprecation.banken`). If you
+require banken only after Rails has initialized, register it yourself:
+
+```ruby
+Rails.application.deprecators[:banken] = Banken.deprecator
+```
+
 ## Additional context
 
 Banken strongly encourages you to model your application in such a way that the
@@ -352,28 +454,31 @@ class UserContext
 end
 
 # app/controllers/application_controller.rb
-class ApplicationController
-  include Banken
+class ApplicationController < ActionController::Base
+  include Banken::Authorization
 
-  def banken_user
-    UserContext.new(current_user, request.ip)
-  end
+  private
+    # Return nil when nobody is signed in, so a "must be logged in" guard in
+    # ApplicationLoyalty#initialize keeps working; inside loyalties check
+    # `user.user`, not `user`, which is the wrapper.
+    def banken_user
+      UserContext.new(current_user, request.remote_ip) if current_user
+    end
 end
 ```
 
 ## Strong parameters
 
-In Rails 4 (or Rails 3.2 with the
-[strong_parameters](https://github.com/rails/strong_parameters) gem),
-mass-assignment protection is handled in the controller. With Banken you can
-control which attributes a user has access to update via your loyalties. You can
-set up a `permitted_attributes` method in your loyalty like this:
+Mass-assignment protection is handled in the controller with strong
+parameters. With Banken you can control which attributes a user has access to
+update via your loyalties. You can set up a `permitted_attributes` method in
+your loyalty like this:
 
 ```ruby
 # app/loyalties/posts_loyalty.rb
 class PostsLoyalty < ApplicationLoyalty
   def permitted_attributes
-    if user.admin? || user.owner_of?(post)
+    if user.admin? || user.owner_of?(record)
       [:title, :body, :tag_list]
     else
       [:tag_list]
@@ -389,10 +494,10 @@ You can now retrieve these attributes from the loyalty:
 class PostsController < ApplicationController
   def update
     @post = Post.find(params[:id])
-    if @post.update_attributes(post_params)
+    if @post.update(post_params)
       redirect_to @post
     else
-      render :edit
+      render :edit, status: 422
     end
   end
 
@@ -404,22 +509,63 @@ class PostsController < ApplicationController
 end
 ```
 
-However, this is a bit cumbersome, so Banken provides a convenient helper method:
+However, this is a bit cumbersome, so Banken provides a convenient helper method.
+The record may be an instance or a class (`permitted_attributes(Post)` on create):
 
 ```ruby
 # app/controllers/posts_controller.rb
 class PostsController < ApplicationController
   def update
     @post = Post.find(params[:id])
-    if @post.update_attributes(permitted_attributes(@post))
+    if @post.update(permitted_attributes(@post))
       redirect_to @post
     else
-      render :edit
+      render :edit, status: 422
     end
   end
 end
 ```
 
-# License
+Attributes that the loyalty does not list are dropped like any other
+unpermitted parameter. With `config.action_controller.action_on_unpermitted_parameters = :raise`
+they raise `ActionController::UnpermittedParameters`, which Rails reports as a 500
+unless you map it in `rescue_responses`.
+
+`permitted_attributes(record)` always uses the current controller's loyalty
+(`PostsLoyalty` inside `PostsController`, even for `permitted_attributes(@comment)`)
+and expects `params[<key>]` to be a hash of attributes; a scalar or array value is
+rejected with `ActionController::ParameterMissing` (400).
+
+The list may contain hash filters for arrays and nested attributes, exactly as
+`permit` accepts them: `[:title, { tags: [] }, { meta: [:key] }]`.
+
+`permitted_attributes` reads `params[<key>]`, where the key is the demodulized,
+underscored class name (`Post` and `Admin::Post` both give `post`). Rails forms
+use `model_name.param_key` instead, so a namespaced model (`Admin::Post` is
+posted as `params[:admin_post]`) or a model overriding `model_name` needs the
+`banken_param_key` override below, or every submit ends in
+`ActionController::ParameterMissing`. To change the key, override one of these
+hooks in your controller. **Define the override under `private` (or
+`protected`)**: a public method on a controller is a routable action.
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Banken::Authorization
+
+  private
+    # Use the key Rails forms generate (Admin::Post -> "admin_post");
+    # model_name works on ActiveModel classes and instances alike
+    def banken_param_key(record)
+      record.respond_to?(:model_name) ? record.model_name.param_key : super
+    end
+
+    # Or take the attributes from somewhere else entirely
+    def banken_params_for(record)
+      params.require(:payload)
+    end
+end
+```
+
+## License
 
 Licensed under the MIT license, see the separate LICENSE.txt file.

data/SECURITY.md

@@ -0,0 +1,19 @@
+# Security Policy
+
+## Supported versions
+
+Only the most recent minor release receives security fixes. The supported Ruby
+and Rails versions are listed in the README.
+
+## Reporting a vulnerability
+
+Please do not open a public issue or pull request for a security problem.
+
+Report it privately through
+[GitHub Security Advisories](https://github.com/kyuden/banken/security/advisories/new).
+If that page is unavailable, email the maintainer listed in the gemspec
+(msmsms.um@gmail.com). You will get an acknowledgement within seven days, and
+a fix will be released together with a CHANGELOG entry marked "Security" and an
+advisory once it is available.
+
+Thank you for helping keep Banken's users safe.