pundit 2.1.0 → 2.5.0

data/lib/pundit/authorization.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module Pundit
+  # Pundit DSL to include in your controllers to provide authorization helpers.
+  #
+  # @example
+  #   class ApplicationController < ActionController::Base
+  #     include Pundit::Authorization
+  #   end
+  # @see #pundit
+  # @api public
+  module Authorization
+    extend ActiveSupport::Concern
+
+    included do
+      helper Helper if respond_to?(:helper)
+      if respond_to?(:helper_method)
+        helper_method :policy
+        helper_method :pundit_policy_scope
+        helper_method :pundit_user
+      end
+    end
+
+    protected
+
+    # An instance of {Pundit::Context} initialized with the current user.
+    #
+    # @note this method is memoized and will return the same instance during the request.
+    # @api public
+    # @return [Pundit::Context]
+    # @see #pundit_user
+    # @see #policies
+    def pundit
+      @pundit ||= Pundit::Context.new(
+        user: pundit_user,
+        policy_cache: Pundit::CacheStore::LegacyStore.new(policies)
+      )
+    end
+
+    # Hook method which allows customizing which user is passed to policies and
+    # scopes initialized by {#authorize}, {#policy} and {#policy_scope}.
+    #
+    # @note Make sure to call `pundit_reset!` if this changes during a request.
+    # @see https://github.com/varvet/pundit#customize-pundit-user
+    # @see #pundit
+    # @see #pundit_reset!
+    # @return [Object] the user object to be used with pundit
+    def pundit_user
+      current_user
+    end
+
+    # Clears the cached Pundit authorization data.
+    #
+    # This method should be called when the pundit_user is changed,
+    # such as during user switching, to ensure that stale authorization
+    # data is not used. Pundit caches authorization policies and scopes
+    # for the pundit_user, so calling this method will reset those
+    # caches and ensure that the next authorization checks are performed
+    # with the correct context for the new pundit_user.
+    #
+    # @return [void]
+    def pundit_reset!
+      @pundit = nil
+      @_pundit_policies = nil
+      @_pundit_policy_scopes = nil
+      @_pundit_policy_authorized = nil
+      @_pundit_policy_scoped = nil
+    end
+
+    # @!group Policies
+
+    # Retrieves the policy for the given record, initializing it with the record
+    # and current user and finally throwing an error if the user is not
+    # authorized to perform the given action.
+    #
+    # @param record [Object, Array] the object we're checking permissions of
+    # @param query [Symbol, String] the predicate method to check on the policy (e.g. `:show?`).
+    #   If omitted then this defaults to the Rails controller action name.
+    # @param policy_class [Class] the policy class we want to force use of
+    # @raise [NotAuthorizedError] if the given query method returned false
+    # @return [record] Always returns the passed object record
+    # @see Pundit::Context#authorize
+    # @see #verify_authorized
+    def authorize(record, query = nil, policy_class: nil)
+      query ||= "#{action_name}?"
+
+      @_pundit_policy_authorized = true
+
+      pundit.authorize(record, query: query, policy_class: policy_class)
+    end
+
+    # Allow this action not to perform authorization.
+    #
+    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
+    # @return [void]
+    # @see #verify_authorized
+    def skip_authorization
+      @_pundit_policy_authorized = :skipped
+    end
+
+    # @return [Boolean] wether or not authorization has been performed
+    # @see #authorize
+    # @see #skip_authorization
+    def pundit_policy_authorized?
+      !!@_pundit_policy_authorized
+    end
+
+    # Raises an error if authorization has not been performed.
+    #
+    # Usually used as an `after_action` filter to prevent programmer error in
+    # forgetting to call {#authorize} or {#skip_authorization}.
+    #
+    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
+    # @raise [AuthorizationNotPerformedError] if authorization has not been performed
+    # @return [void]
+    # @see #authorize
+    # @see #skip_authorization
+    def verify_authorized
+      raise AuthorizationNotPerformedError, self.class unless pundit_policy_authorized?
+    end
+
+    # rubocop:disable Naming/MemoizedInstanceVariableName
+
+    # Cache of policies. You should not rely on this method.
+    #
+    # @api private
+    def policies
+      @_pundit_policies ||= {}
+    end
+
+    # rubocop:enable Naming/MemoizedInstanceVariableName
+
+    # @!endgroup
+
+    # Retrieves the policy for the given record.
+    #
+    # @see https://github.com/varvet/pundit#policies
+    # @param record [Object] the object we're retrieving the policy for
+    # @return [Object] instance of policy class with query methods
+    def policy(record)
+      pundit.policy!(record)
+    end
+
+    # @!group Policy Scopes
+
+    # Retrieves the policy scope for the given record.
+    #
+    # @see https://github.com/varvet/pundit#scopes
+    # @param scope [Object] the object we're retrieving the policy scope for
+    # @param policy_scope_class [#resolve] the policy scope class we want to force use of
+    # @return [#resolve, nil] instance of scope class which can resolve to a scope
+    def policy_scope(scope, policy_scope_class: nil)
+      @_pundit_policy_scoped = true
+      policy_scope_class ? policy_scope_class.new(pundit_user, scope).resolve : pundit_policy_scope(scope)
+    end
+
+    # Allow this action not to perform policy scoping.
+    #
+    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
+    # @return [void]
+    # @see #verify_policy_scoped
+    def skip_policy_scope
+      @_pundit_policy_scoped = :skipped
+    end
+
+    # @return [Boolean] wether or not policy scoping has been performed
+    # @see #policy_scope
+    # @see #skip_policy_scope
+    def pundit_policy_scoped?
+      !!@_pundit_policy_scoped
+    end
+
+    # Raises an error if policy scoping has not been performed.
+    #
+    # Usually used as an `after_action` filter to prevent programmer error in
+    # forgetting to call {#policy_scope} or {#skip_policy_scope} in index
+    # actions.
+    #
+    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
+    # @raise [AuthorizationNotPerformedError] if policy scoping has not been performed
+    # @return [void]
+    # @see #policy_scope
+    # @see #skip_policy_scope
+    def verify_policy_scoped
+      raise PolicyScopingNotPerformedError, self.class unless pundit_policy_scoped?
+    end
+
+    # rubocop:disable Naming/MemoizedInstanceVariableName
+
+    # Cache of policy scope. You should not rely on this method.
+    #
+    # @api private
+    def policy_scopes
+      @_pundit_policy_scopes ||= {}
+    end
+
+    # rubocop:enable Naming/MemoizedInstanceVariableName
+
+    # This was added to allow calling `policy_scope!` without flipping the
+    # `pundit_policy_scoped?` flag.
+    #
+    # It's used internally by `policy_scope`, as well as from the views
+    # when they call `policy_scope`. It works because views get their helper
+    # from {Pundit::Helper}.
+    #
+    # @note This also memoizes the instance with `scope` as the key.
+    # @see Pundit::Helper#policy_scope
+    # @api private
+    def pundit_policy_scope(scope)
+      policy_scopes[scope] ||= pundit.policy_scope!(scope)
+    end
+    private :pundit_policy_scope
+
+    # @!endgroup
+
+    # @!group Strong Parameters
+
+    # Retrieves a set of permitted attributes from the policy.
+    #
+    # Done by instantiating the policy class for the given record and calling
+    # `permitted_attributes` on it, or `permitted_attributes_for_{action}` if
+    # `action` is defined. It then infers what key the record should have in the
+    # params hash and retrieves the permitted attributes from the params hash
+    # under that key.
+    #
+    # @see https://github.com/varvet/pundit#strong-parameters
+    # @param record [Object] the object we're retrieving permitted attributes for
+    # @param action [Symbol, String] the name of the action being performed on the record (e.g. `:update`).
+    #   If omitted then this defaults to the Rails controller action name.
+    # @return [Hash{String => Object}] the permitted attributes
+    def permitted_attributes(record, action = action_name)
+      policy = policy(record)
+      method_name = if policy.respond_to?("permitted_attributes_for_#{action}")
+        "permitted_attributes_for_#{action}"
+      else
+        "permitted_attributes"
+      end
+      pundit_params_for(record).permit(*policy.public_send(method_name))
+    end
+
+    # Retrieves the params for the given record.
+    #
+    # @param record [Object] the object we're retrieving params for
+    # @return [ActionController::Parameters] the params
+    def pundit_params_for(record)
+      params.require(PolicyFinder.new(record).param_key)
+    end
+
+    # @!endgroup
+  end
+end

data/lib/pundit/cache_store/legacy_store.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Pundit
+  module CacheStore
+    # A cache store that uses only the record as a cache key, and ignores the user.
+    #
+    # The original cache mechanism used by Pundit.
+    #
+    # @api private
+    class LegacyStore
+      def initialize(hash = {})
+        @store = hash
+      end
+
+      # A cache store that uses only the record as a cache key, and ignores the user.
+      #
+      # @note `nil` results are not cached.
+      def fetch(user:, record:)
+        _ = user
+        @store[record] ||= yield
+      end
+    end
+  end
+end

data/lib/pundit/cache_store/null_store.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Pundit
+  module CacheStore
+    # A cache store that does not cache anything.
+    #
+    # Use `NullStore.instance` to get the singleton instance, it is thread-safe.
+    #
+    # @see Pundit::Context#initialize
+    # @api private
+    class NullStore
+      @instance = new
+
+      class << self
+        # @return [NullStore] the singleton instance
+        attr_reader :instance
+      end
+
+      # Always yields, does not cache anything.
+      # @yield
+      # @return [any] whatever the block returns.
+      def fetch(*, **)
+        yield
+      end
+    end
+  end
+end

data/lib/pundit/cache_store.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Pundit
+  # Namespace for cache store implementations.
+  #
+  # Cache stores are used to cache policy lookups, so you get the same policy
+  # instance for the same record.
+  module CacheStore
+    # @!group Cache Store Interface
+
+    # @!method fetch(user:, record:, &block)
+    #   Looks up a stored policy or generate a new one.
+    #
+    #   @note This is a method template, but the method does not exist in this module.
+    #   @param user [Object]  the user that initiated the action
+    #   @param record [Object] the object being accessed
+    #   @param block [Proc] the block to execute if missing
+    #   @return [Object] the policy
+
+    # @!endgroup
+  end
+end

data/lib/pundit/context.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Pundit
+  # {Pundit::Context} is intended to be created once per request and user, and
+  # it is then used to perform authorization checks throughout the request.
+  #
+  # @example Using Sinatra
+  #   helpers do
+  #     def current_user = ...
+  #
+  #     def pundit
+  #       @pundit ||= Pundit::Context.new(user: current_user)
+  #     end
+  #   end
+  #
+  #   get "/posts/:id" do |id|
+  #     pundit.authorize(Post.find(id), query: :show?)
+  #   end
+  #
+  # @example Using [Roda](https://roda.jeremyevans.net/index.html)
+  #   route do |r|
+  #     context = Pundit::Context.new(user:)
+  #
+  #     r.get "posts", Integer do |id|
+  #       context.authorize(Post.find(id), query: :show?)
+  #     end
+  #   end
+  class Context
+    # @see Pundit::Authorization#pundit
+    # @param user later passed to policies and scopes
+    # @param policy_cache [#fetch] cache store for policies (see e.g. {CacheStore::NullStore})
+    def initialize(user:, policy_cache: CacheStore::NullStore.instance)
+      @user = user
+      @policy_cache = policy_cache
+    end
+
+    # @api public
+    # @see #initialize
+    attr_reader :user
+
+    # @api private
+    # @see #initialize
+    attr_reader :policy_cache
+
+    # @!group Policies
+
+    # Retrieves the policy for the given record, initializing it with the
+    # record and user and finally throwing an error if the user is not
+    # authorized to perform the given action.
+    #
+    # @param possibly_namespaced_record [Object, Array] the object we're checking permissions of
+    # @param query [Symbol, String] the predicate method to check on the policy (e.g. `:show?`)
+    # @param policy_class [Class] the policy class we want to force use of
+    # @raise [NotAuthorizedError] if the given query method returned false
+    # @return [Object] Always returns the passed object record
+    def authorize(possibly_namespaced_record, query:, policy_class:)
+      record = pundit_model(possibly_namespaced_record)
+      policy = if policy_class
+        policy_class.new(user, record)
+      else
+        policy!(possibly_namespaced_record)
+      end
+
+      raise NotAuthorizedError, query: query, record: record, policy: policy unless policy.public_send(query)
+
+      record
+    end
+
+    # Retrieves the policy for the given record.
+    #
+    # @see https://github.com/varvet/pundit#policies
+    # @param record [Object] the object we're retrieving the policy for
+    # @raise [InvalidConstructorError] if the policy constructor called incorrectly
+    # @return [Object, nil] instance of policy class with query methods
+    def policy(record)
+      cached_find(record, &:policy)
+    end
+
+    # Retrieves the policy for the given record, or raises if not found.
+    #
+    # @see https://github.com/varvet/pundit#policies
+    # @param record [Object] the object we're retrieving the policy for
+    # @raise [NotDefinedError] if the policy cannot be found
+    # @raise [InvalidConstructorError] if the policy constructor called incorrectly
+    # @return [Object] instance of policy class with query methods
+    def policy!(record)
+      cached_find(record, &:policy!)
+    end
+
+    # @!endgroup
+
+    # @!group Scopes
+
+    # Retrieves the policy scope for the given record.
+    #
+    # @see https://github.com/varvet/pundit#scopes
+    # @param scope [Object] the object we're retrieving the policy scope for
+    # @raise [InvalidConstructorError] if the policy constructor called incorrectly
+    # @return [Scope{#resolve}, nil] instance of scope class which can resolve to a scope
+    def policy_scope(scope)
+      policy_scope_class = policy_finder(scope).scope
+      return unless policy_scope_class
+
+      begin
+        policy_scope = policy_scope_class.new(user, pundit_model(scope))
+      rescue ArgumentError
+        raise InvalidConstructorError, "Invalid #<#{policy_scope_class}> constructor is called"
+      end
+
+      policy_scope.resolve
+    end
+
+    # Retrieves the policy scope for the given record. Raises if not found.
+    #
+    # @see https://github.com/varvet/pundit#scopes
+    # @param scope [Object] the object we're retrieving the policy scope for
+    # @raise [NotDefinedError] if the policy scope cannot be found
+    # @raise [InvalidConstructorError] if the policy constructor called incorrectly
+    # @return [Scope{#resolve}] instance of scope class which can resolve to a scope
+    def policy_scope!(scope)
+      policy_scope_class = policy_finder(scope).scope!
+
+      begin
+        policy_scope = policy_scope_class.new(user, pundit_model(scope))
+      rescue ArgumentError
+        raise InvalidConstructorError, "Invalid #<#{policy_scope_class}> constructor is called"
+      end
+
+      policy_scope.resolve
+    end
+
+    # @!endgroup
+
+    private
+
+    # @!group Private Helpers
+
+    # Finds a cached policy for the given record, or yields to find one.
+    #
+    # @api private
+    # @param record [Object] the object we're retrieving the policy for
+    # @yield a policy finder if no policy was cached
+    # @yieldparam [PolicyFinder] policy_finder
+    # @yieldreturn [#new(user, model)]
+    # @return [Policy, nil] an instantiated policy
+    # @raise [InvalidConstructorError] if policy can't be instantated
+    def cached_find(record)
+      policy_cache.fetch(user: user, record: record) do
+        klass = yield policy_finder(record)
+        next unless klass
+
+        model = pundit_model(record)
+
+        begin
+          klass.new(user, model)
+        rescue ArgumentError
+          raise InvalidConstructorError, "Invalid #<#{klass}> constructor is called"
+        end
+      end
+    end
+
+    # Return a policy finder for the given record.
+    #
+    # @api private
+    # @return [PolicyFinder]
+    def policy_finder(record)
+      PolicyFinder.new(record)
+    end
+
+    # Given a possibly namespaced record, return the actual record.
+    #
+    # @api private
+    def pundit_model(record)
+      record.is_a?(Array) ? record.last : record
+    end
+  end
+end

data/lib/pundit/policy_finder.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# String#safe_constantize, String#demodulize, String#underscore, String#camelize
+require "active_support/core_ext/string/inflections"
+
 module Pundit
   # Finds policy and scope classes for given object.
   # @api public
@@ -10,10 +13,15 @@ module Pundit
   #   finder.scope #=> UserPolicy::Scope
   #
   class PolicyFinder
+    # A constant applied to the end of the class name to find the policy class.
+    #
+    # @api private
+    SUFFIX = "Policy"
+
+    # @see #initialize
     attr_reader :object
 
     # @param object [any] the object to find policy and scope classes for
-    #
     def initialize(object)
       @object = object
     end
@@ -56,7 +64,7 @@ module Pundit
 
     # @return [String] the name of the key this object would have in a params hash
     #
-    def param_key
+    def param_key # rubocop:disable Metrics/AbcSize
       model = object.is_a?(Array) ? object.last : object
 
       if model.respond_to?(:model_name)
@@ -68,8 +76,13 @@ module Pundit
       end
     end
 
-  private
+    private
 
+    # Given an object, find the policy class name.
+    #
+    # Uses recursion to handle namespaces.
+    #
+    # @return [String, Class] the policy class, or its name.
     def find(subject)
       if subject.is_a?(Array)
         modules = subject.dup
@@ -86,6 +99,14 @@ module Pundit
       end
     end
 
+    # Given an object, find its' class name.
+    #
+    # - Supports ActiveModel.
+    # - Supports regular classes.
+    # - Supports symbols.
+    # - Supports object instances.
+    #
+    # @return [String, Class] the class, or its name.
     def find_class_name(subject)
       if subject.respond_to?(:model_name)
         subject.model_name

data/lib/pundit/railtie.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Pundit
+  class Railtie < Rails::Railtie
+    if Rails.version.to_f >= 8.0
+      initializer "pundit.stats_directories" do
+        require "rails/code_statistics"
+
+        if Rails.root.join("app/policies").directory?
+          Rails::CodeStatistics.register_directory("Policies", "app/policies")
+        end
+
+        if Rails.root.join("test/policies").directory?
+          Rails::CodeStatistics.register_directory("Policy tests", "test/policies", test_directory: true)
+        end
+      end
+    end
+  end
+end