action_controller-stashed_redirects 0.1.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57726ac99490f85375fd07300740792ad9ce85efda8c4eb728794c4243391636
-  data.tar.gz: 2a3059590ed5e4032477d5600304668a5af6c4b4b55a51a31a3246a59be64e5e
+  metadata.gz: cf64ad8ee2fb60526d8517bb26be521de7952bcfd87ed860bfe5ce2fe8a0deb0
+  data.tar.gz: ce4550656d8f30fc4629f72329229542c457403e95803177260fbe575e9ab51a
 SHA512:
-  metadata.gz: bf260715badd07d6a091254fecbc3890ff21b69317fd0c05c8d50971a18f47be87a182da0f9ea6ffe2c4140d71b101f30003c24fe4ab28feb8671945aa260def
-  data.tar.gz: 949bf794275255b14aeb5b7e46e6f0558218cf736eb7a1b686063c02af2c545128e8dc55f2e0984a097b844bb8f0dcc7ea89575e67181b1a06793f239d40294a
+  metadata.gz: f4188865c205f58bf080d879f50ad818716bac84145b568db85324ea5cbb1aa0f2afe1df87a8e9f2cb29be276ed66dfdceb9ca359e58292e7f11cfff5163c76e
+  data.tar.gz: 2ab7965676ca7d50f881f26ae8fb5bdac89624a02642303feeab5db5191065d73aa7af578533d98fa7b61eb72f8d34c33e8c2f6ad686aaf2a44d07ba32659f75

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [0.2.0] - 2022-04-21
+
+- `stash_redirect_for` raises `ArgumentError` on invalid redirect URL
+
+   Protects against storing a URL that `redirect_to` can't redirect to later.
+
+- `redirect_from_stashed` raises `ActionController::StashedRedirects::MissingRedirectError`
+
+  Useful to add a specific general fallback:
+
+  ```ruby
+  class ApplicationController < ActionController::Base
+    rescue_from(ActionController::StashedRedirects::MissingRedirectError) { redirect_to root_url }
+  end
+  ```
+
 ## [0.1.0] - 2022-04-21
 
 - Initial release

data/Gemfile

@@ -8,5 +8,5 @@ gemspec
 gem "rake", "~> 13.0"
 
 gem "debug"
-gem "minitest", "~> 5.0"
+gem "minitest"
 gem "railties"

data/Gemfile.lock

@@ -1,89 +1,119 @@
 PATH
   remote: .
   specs:
-    action_controller-stashed_redirects (0.1.0)
+    action_controller-stashed_redirects (0.2.2)
       actionpack (>= 7.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actionpack (7.0.2.3)
-      actionview (= 7.0.2.3)
-      activesupport (= 7.0.2.3)
-      rack (~> 2.0, >= 2.2.0)
+    actionpack (7.1.3.4)
+      actionview (= 7.1.3.4)
+      activesupport (= 7.1.3.4)
+      nokogiri (>= 1.8.5)
+      racc
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
       rack-test (>= 0.6.3)
-      rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.0, >= 1.2.0)
-    actionview (7.0.2.3)
-      activesupport (= 7.0.2.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    actionview (7.1.3.4)
+      activesupport (= 7.1.3.4)
       builder (~> 3.1)
-      erubi (~> 1.4)
-      rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.1, >= 1.2.0)
-    activesupport (7.0.2.3)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activesupport (7.1.3.4)
+      base64
+      bigdecimal
       concurrent-ruby (~> 1.0, >= 1.0.2)
+      connection_pool (>= 2.2.5)
+      drb
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
+      mutex_m
       tzinfo (~> 2.0)
-    builder (3.2.4)
-    concurrent-ruby (1.1.10)
+    base64 (0.2.0)
+    bigdecimal (3.1.8)
+    builder (3.3.0)
+    concurrent-ruby (1.3.3)
+    connection_pool (2.4.1)
     crass (1.0.6)
-    debug (1.5.0)
-      irb (>= 1.3.6)
-      reline (>= 0.2.7)
-    erubi (1.10.0)
-    i18n (1.10.0)
+    debug (1.9.2)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    drb (2.2.1)
+    erubi (1.13.0)
+    i18n (1.14.5)
       concurrent-ruby (~> 1.0)
-    io-console (0.5.11)
-    irb (1.4.1)
-      reline (>= 0.3.0)
-    loofah (2.16.0)
+    io-console (0.7.2)
+    irb (1.13.2)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    loofah (2.22.0)
       crass (~> 1.0.2)
-      nokogiri (>= 1.5.9)
-    method_source (1.0.0)
-    minitest (5.15.0)
-    nokogiri (1.13.4-aarch64-linux)
+      nokogiri (>= 1.12.0)
+    minitest (5.24.1)
+    mutex_m (0.2.0)
+    nokogiri (1.16.6-aarch64-linux)
       racc (~> 1.4)
-    nokogiri (1.13.4-arm64-darwin)
+    nokogiri (1.16.6-arm-linux)
       racc (~> 1.4)
-    nokogiri (1.13.4-x86-linux)
+    nokogiri (1.16.6-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.13.4-x86_64-linux)
+    nokogiri (1.16.6-x86-linux)
       racc (~> 1.4)
-    racc (1.6.0)
-    rack (2.2.3)
-    rack-test (1.1.0)
-      rack (>= 1.0, < 3)
-    rails-dom-testing (2.0.3)
-      activesupport (>= 4.2.0)
+    nokogiri (1.16.6-x86_64-linux)
+      racc (~> 1.4)
+    psych (5.1.2)
+      stringio
+    racc (1.8.0)
+    rack (3.1.6)
+    rack-session (2.0.0)
+      rack (>= 3.0.0)
+    rack-test (2.1.0)
+      rack (>= 1.3)
+    rackup (2.1.0)
+      rack (>= 3)
+      webrick (~> 1.8)
+    rails-dom-testing (2.2.0)
+      activesupport (>= 5.0.0)
+      minitest
       nokogiri (>= 1.6)
-    rails-html-sanitizer (1.4.2)
-      loofah (~> 2.3)
-    railties (7.0.2.3)
-      actionpack (= 7.0.2.3)
-      activesupport (= 7.0.2.3)
-      method_source
+    rails-html-sanitizer (1.6.0)
+      loofah (~> 2.21)
+      nokogiri (~> 1.14)
+    railties (7.1.3.4)
+      actionpack (= 7.1.3.4)
+      activesupport (= 7.1.3.4)
+      irb
+      rackup (>= 1.0.0)
       rake (>= 12.2)
-      thor (~> 1.0)
-      zeitwerk (~> 2.5)
-    rake (13.0.6)
-    reline (0.3.1)
+      thor (~> 1.0, >= 1.2.2)
+      zeitwerk (~> 2.6)
+    rake (13.2.1)
+    rdoc (6.7.0)
+      psych (>= 4.0.0)
+    reline (0.5.9)
       io-console (~> 0.5)
-    thor (1.2.1)
-    tzinfo (2.0.4)
+    stringio (3.1.1)
+    thor (1.3.1)
+    tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    zeitwerk (2.5.4)
+    webrick (1.8.1)
+    zeitwerk (2.6.16)
 
 PLATFORMS
   arm64-darwin-20
+  arm64-darwin-23
   linux
 
 DEPENDENCIES
   action_controller-stashed_redirects!
   debug
-  minitest (~> 5.0)
+  minitest
   railties
   rake (~> 13.0)
 
 BUNDLED WITH
-   2.3.11
+   2.5.14

data/README.md

@@ -12,13 +12,14 @@ class ApplicationController < ActionController::Base
 
   private
     def authenticate
-      redirect_to new_session_url unless Current.user
+      # Pass `redirect_url:` to pass the URL we're currently on.
+      redirect_to new_session_url(redirect_url: request.url) unless Current.user
     end
 end
 
 class SessionsController < ApplicationController
   # Stash a redirect at the start of the session authentication flow,
-  # from either params[:redirect_url] or request.referer in that order.
+  # from `params[:redirect_url]` automatically.
   stash_redirect_for :sign_in, on: :new
 
   def new
@@ -28,6 +29,8 @@ class SessionsController < ApplicationController
     if User.authenticate_by(session_params)
       # On success, redirect the user back to where they first tried to access before being authenticated.
       redirect_from_stashed :sign_in
+    else
+      render :new, status: :unprocessable_entity
     end
   end
 end
@@ -37,6 +40,107 @@ See the internal documentation for more usage information.
 
 Only internal redirects are allowed, so attackers can't pass an external `redirect_url`.
 
+### Making a sudo authentication system
+
+Consider a flow where you want to require super-user, or sudo, privileges for a given action, e.g. type in your password before you can change your credit card.
+
+We'll make a `require_sudo` API that we can annotate our controller with like this:
+
+```ruby
+class Billing::CreditCardsController < ApplicationController
+  require_sudo # Require sudo on all actions in this controller.
+  # require_sudo_on :edit, :update # Or just for some actions.
+
+  def edit
+  end
+
+  def update
+    Current.user.billing.credit_cards.find(params[:id]).update!(credit_card_params)
+  end
+end
+```
+
+`require_sudo` or `require_sudo_on` can come from a controller concern like this:
+
+```ruby
+# app/controllers/concerns/sudo/examination.rb
+module Sudo::Examination
+  def self.included(klass) = klass.singleton_class.class_eval do
+    def require_sudo_on(*actions, **) = require_sudo(only: *actions, **)
+    def require_sudo(...) = before_action(:require_sudo, ...)
+  end
+
+  private
+    def require_sudo
+      if sudo.exam_needed?
+        raise "Non-get: can't redirect back here, make sure you do …something with an interstitial page?" unless request.get?
+        redirect_to new_sudo_exams_url(redirect_url: request.url)
+      end
+    end
+
+    def sudo = Sudo.new(session)
+end
+
+# Which we include in ApplicationController:
+class ApplicationController < ActionController::Base
+  include Sudo::Examination
+end
+```
+
+Notice how in `redirect_to new_sudo_exams_url(redirect_url: request.url)` we're passing the `redirect_url:` along that `ActionController::StashedRedirects` will need.
+It's pointing back to the page we're on, which required sudo authentication, so we can redirect back to it after the sudo exam has been passed.
+
+Next up, we can add an in-memory PORO model to give the behavior some better names:
+
+```ruby
+# app/models/sudo.rb
+class Sudo < Data.define(:store)
+  def passed!
+    store[:sudo_expires_at] = 15.minutes.from_now
+  end
+
+  def exam_needed?
+    expires_at = store[:sudo_expires_at]
+    expires_at.nil? || Time.parse(expires_at).past?
+  end
+end
+```
+
+Next, we can add the authenticating sudo controller itself, where `stash_redirect_for` will use the `redirect_url:` from earlier:
+
+```ruby
+# app/controllers/sudo/exams_controller.rb
+class Sudo::ExamsController < ApplicationController
+  stash_redirect_for :sudo, on: :new
+
+  def new
+    redirect_from_stashed :sudo unless sudo.exam_needed?
+  end
+
+  def create
+    if pass_sudo_exam?
+      sudo.passed!
+      redirect_from_stashed :sudo
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+  private def pass_sudo_exam? = Current.user.authenticate_password(params[:password])
+end
+```
+
+Finally, we mount the routes for the controller:
+
+```ruby
+# config/routes.rb
+namespace :sudo do
+  resources :exams
+end
+```
+
+Users can now fill-in their password, which will hit `sudo/exams#create` and redirect them back to the edit form on the
+credit cards flow if it's the correct password.
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -55,7 +159,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/action_controller-stashed_redirects.
+Bug reports and pull requests are welcome on GitHub at https://github.com/kaspth/action_controller-stashed_redirects.
 
 ## License
 

data/Rakefile

@@ -1,12 +1,3 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "rake/testtask"
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/test_*.rb"]
-end
-
-task default: :test

data/action_controller-stashed_redirects.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.summary  = "Embed a controller flow within another by stashing the final redirect upfront and performing it after completing."
   spec.homepage = "https://github.com/kaspth/action_controller-stashed_redirects"
   spec.license  = "MIT"
-  spec.required_ruby_version = ">= 2.7.0"
+  spec.required_ruby_version = ">= 3.0.0"
 
   spec.metadata["homepage_uri"]    = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage

data/lib/action_controller/stashed_redirects/version.rb

@@ -2,6 +2,6 @@
 
 module ActionController
   module StashedRedirects
-    VERSION = "0.1.0"
+    VERSION = "0.2.2"
   end
 end

data/lib/action_controller/stashed_redirects.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "active_support"
-require_relative "stashed_redirects/version"
 
 # Pass between different controller flows via stashed redirects
 #
@@ -9,67 +8,99 @@ require_relative "stashed_redirects/version"
 module ActionController::StashedRedirects
   extend ActiveSupport::Concern
 
-  class_methods do
-    # Adds a before_action to stash a redirect for a given `on:` action.
-    #
-    #   stash_redirect_for :sudo_authentication, on: :new
-    #   stash_redirect_for :sign_in, from: :referer, on: :new
-    #   stash_redirect_for :sign_in, from: -> { update_post_path(@post) }
-    def stash_redirect_for(purpose, on:, from: nil)
-      before_action(-> { stash_redirect_for(purpose, from: from.respond_to?(:call) ? instance_exec(&from) : from) }, only: on)
+  autoload :VERSION, "action_controller/stashed_redirects/version"
+
+  # Allow a general `rescue ActionController::StashedRedirects::Error`.
+  Error = Module.new
+
+  class MissingRedirectError < StandardError
+    include Error
+
+    attr_reader :purpose
+
+    def initialize(purpose)
+      super "can't extract a stashed redirect_url to redirect_to"
+      @purpose = purpose
     end
   end
 
-  # Stashes a redirect URL in the `session` under the given +purpose+.
-  #
-  # An explicit +redirect_url+ can be passsed, otherwise the redirect URL is
-  # derived from `params[:redirect_url]` then falling back to `request.referer`.
-  #
-  #   stash_redirect_for :sign_in
-  #   stash_redirect_for :sign_in, from: url_from(params[:redirect_url]) || root_url
-  #   stash_redirect_for :sign_in, from: :param   # Only derive the redirect URL from `params[:redirect_url]`.
-  #   stash_redirect_for :sign_in, from: :referer # Only derive the redirect URL from `request.referer`.
-  def stash_redirect_for(purpose, from: nil)
-    if url = derive_stash_redirect_url_from(from)
-      session[KEY_GENERATOR.(purpose)] = url
-    else
-      raise ArgumentError, "missing a redirect_url to stash, pass one via from: or via a redirect_url URL param"
+  class_methods do
+    # Adds a `before_action` to stash a redirect in a given `on:` action.
+    #
+    #   stash_redirect_for :sign_in, on: :new
+    #   stash_redirect_for :sign_in, on: %i[ new edit ]
+    #   stash_redirect_for :sign_in, on: :new, url: -> { update_post_path(@post) }
+    def stash_redirect_for(purpose, on:, url: DEFAULT_URL)
+      before_action(-> { stash_redirect_for(purpose, url: url) }, only: on)
     end
   end
 
-  # Finds and deletes the redirect stashed in `session` under the given +purpose+, then redirects.
-  #
-  #   redirect_from_stashed :login
-  #
-  # Raises if no stashed redirect is found under the given +purpose+.
-  #
-  # Relies on +redirect_to+'s open redirect protection, see it's documentation for more.
-  def redirect_from_stashed(purpose)
-    redirect_to stashed_redirect_url_for(purpose)
-  end
+  private
+    # Stashes a redirect URL in the `session` under the given +purpose+.
+    #
+    # An explicit +redirect_url+ can be passed in `from:`, otherwise the redirect URL is
+    # derived from `params[:redirect_url]` then falling back to `request.referer` on GET requests.
+    #
+    #   stash_redirect_for :sign_in
+    #   stash_redirect_for :sign_in, from: url_from(params[:redirect_url]) || root_url
+    #   stash_redirect_for :sign_in, from: :param   # Only derive the redirect URL from `params[:redirect_url]`.
+    #   stash_redirect_for :sign_in, from: :referer # Only derive the redirect URL from `request.referer`.
+    def stash_redirect_for(purpose, url: DEFAULT_URL)
+      if url = derive_stash_redirect_url_from(url)
+        session[KEY_GENERATOR.(purpose)] = url
+      else
+        raise ArgumentError, "missing a redirect_url to stash, pass one via from: or via a redirect_url URL param"
+      end
+    end
 
-  # Deletes the redirect stashed in the `session` under the given +purpose+ and returns it if any.
-  #
-  #   discard_stashed_redirect_for :login # => the login redirect URL or nil.
-  def discard_stashed_redirect_for(purpose)
-    session.delete(KEY_GENERATOR.(purpose))
-  end
+    # Finds and deletes the redirect stashed in `session` under the given +purpose+, then redirects.
+    #
+    #   redirect_from_stashed :sign_in
+    #
+    # Raises if no stashed redirect is found under the given +purpose+.
+    #
+    # Relies on +redirect_to+'s open redirect protection, see it's documentation for more.
+    def redirect_from_stashed(purpose)
+      redirect_to stashed_redirect_url_for(purpose)
+    end
 
-  private
-    KEY_GENERATOR = ->(purpose) { "__url_stash_#{purpose}" }
-    private_constant :KEY_GENERATOR
+    # Deletes and returns the redirect stashed in the `session` under the given +purpose+ if any.
+    #
+    #   discard_stashed_redirect_for :sign_in # => the sign_in redirect URL or nil.
+    def discard_stashed_redirect_for(purpose)
+      session.delete(KEY_GENERATOR.(purpose))
+    end
 
     def stashed_redirect_url_for(purpose)
-      raise ArgumentError, "can't extract a stashed redirect_url from session, none found" \
-        unless redirect_url = discard_stashed_redirect_for(purpose)
+      url_from(discard_stashed_redirect_for(purpose)) or raise MissingRedirectError, purpose
+    end
 
-      url_from(redirect_url)
+    def derive_stash_redirect_url_from(url)
+      case url
+      when DEFAULT_URL  then redirect_url
+      when String       then url_from url
+      when Symbol, Proc then url_from instance_exec(self, &url)
+      end
     end
 
-    def derive_stash_redirect_url_from(from)
-      from ||= %i[ param referer ]
-      { param: params[:redirect_url], referer: request.get? && request.referer }.values_at(*from).find(&:present?) || from
+    # Syntactic sugar for redirecting to `redirect_url` with a fallback.
+    #
+    #   redirect_forward_or_to root_url # => redirect_to redirect_url || root_url
+    def redirect_forward_or_to(fallback_url)
+      redirect_to redirect_url || fallback_url
     end
+
+    # Looks up a redirect URL from `params[:redirect_url]` using
+    # Rails' `url_from` as the protection mechanism to ensure it's a valid internal redirect.
+    # See the `url_from` docs: https://api.rubyonrails.org/classes/ActionController/Redirecting.html#method-i-url_from
+    #
+    # You probably want to use `redirect_forward_or_to`.
+    def redirect_url = url_from(params[:redirect_url])
+
+    DEFAULT_URL = Object.new
+
+    KEY_GENERATOR = ->(purpose) { "__url_stash_#{purpose}" }
+    private_constant :KEY_GENERATOR
 end
 
 ActiveSupport.on_load(:action_controller) { include ActionController::StashedRedirects }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: action_controller-stashed_redirects
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Kasper Timm Hansen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-04-21 00:00:00.000000000 Z
+date: 2024-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -55,14 +55,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.11
+rubygems_version: 3.5.10
 signing_key:
 specification_version: 4
 summary: Embed a controller flow within another by stashing the final redirect upfront