active_security 1.0.0

data/lib/active_security/base.rb

@@ -0,0 +1,194 @@
+module ActiveSecurity
+  # @guide begin
+  #
+  # ## Setting Up ActiveSecurity in Your Model
+  #
+  # To use ActiveSecurity in your ActiveRecord models, you must first either extend or
+  # include the ActiveSecurity module (it makes no difference), then invoke the
+  # {ActiveSecurity::Base#active_security active_security} method to configure your desired
+  # options:
+  #
+  #     class Foo < ActiveRecord::Base
+  #       include ActiveSecurity
+  #       active_security :use => [:finders, :scoped], scope: :bar_id
+  #     end
+  #
+  # The most important option is `:use`, which you use to tell ActiveSecurity which
+  # addons it should use. See the documentation for {ActiveSecurity::Base#active_security} for a list of all
+  # available addons, or skim through the rest of the docs to get a high-level
+  # overview.
+  #
+  # *A note about single table inheritance (STI): you must extend ActiveSecurity in*
+  # *all classes that participate in STI, both your parent classes and their*
+  # *children.*
+  #
+  # ### The Default Setup: Simple Models
+  #
+  # The simplest way to use ActiveSecurity is to have it ensure that finds are executed within a scope:
+  #
+  #     class User < ActiveRecord::Base
+  #       extend ActiveSecurity
+  #     end
+  #
+  #     User.restricted.find(1)             # blows up, because no scope
+  #     User.where(...).restricted.find(1)  # returns the user
+  #
+  # ### The Strict Setup: Simple Models
+  #
+  # The problem with the above approach is that a naked find (`User.find(1)`)
+  # still works, and is just as insecure as before. The `:finders` plugin fixes
+  # this problem, so you don't need to add `restricted` everywhere.
+  #
+  #     class User < ActiveRecord::Base
+  #       extend ActiveSecurity
+  #       active_security use: {finders: {default_finders: :restricted}}
+  #     end
+  #
+  #     User.find(1)             # blows up, because no scope
+  #     User.where(...).find(1)  # returns the user
+  #
+  # @guide end
+  module Base
+    # Configure ActiveSecurity's behavior in a model.
+    #
+    #     class Post < ActiveRecord::Base
+    #       extend ActiveSecurity
+    #       active_security use: :finders
+    #     end
+    #
+    # When given the optional block, this method will yield the class's instance
+    # of {ActiveSecurity::Configuration} to the block before evaluating other
+    # arguments, so configuration values set in the block may be overwritten by
+    # the arguments. This order was chosen to allow passing the same proc to
+    # multiple models, while being able to override the values it sets. Here is
+    # a contrived example:
+    #
+    #     $active_security_config_proc = Proc.new do |config|
+    #       config.use :finders
+    #     end
+    #
+    #     class Foo < ActiveRecord::Base
+    #       extend ActiveSecurity
+    #       active_security &$active_security_config_proc
+    #     end
+    #
+    #     class Bar < ActiveRecord::Base
+    #       extend ActiveSecurity
+    #       active_security &$active_security_config_proc
+    #     end
+    #
+    # However, it's usually better to use {ActiveSecurity.defaults} for this:
+    #
+    #     ActiveSecurity.defaults do |config|
+    #       config.use :finders, default_finders: :restricted
+    #     end
+    #
+    #     class Foo < ActiveRecord::Base
+    #       extend ActiveSecurity
+    #     end
+    #
+    #     class Bar < ActiveRecord::Base
+    #       extend ActiveSecurity
+    #     end
+    #
+    # In general you should use the block syntax either because of your personal
+    # aesthetic preference, or because you need to share some functionality
+    # between multiple models that can't be well encapsulated by
+    # {ActiveSecurity.defaults}.
+    #
+    # ### Order Method Calls in a Block vs Ordering Options
+    #
+    # When calling this method without a block, you may set the hash options in
+    # any order.
+    #
+    # However, when using block-style invocation, be sure to call
+    # ActiveSecurity::Configuration's {ActiveSecurity::Configuration#use use} method
+    # *prior* to the associated configuration options, because it will include
+    # modules into your class, and these modules in turn may add required
+    # configuration options to the `@active_security_configuration`'s class:
+    #
+    #     class Person < ActiveRecord::Base
+    #       active_security do |config|
+    #         # This will work
+    #         config.use :scoped
+    #         config.scope = "family_id"
+    #       end
+    #     end
+    #
+    #     class Person < ActiveRecord::Base
+    #       active_security do |config|
+    #         # This will fail
+    #         config.scope = "family_id"
+    #         config.use :scoped
+    #       end
+    #     end
+    #
+    # ### Including Your Own Modules
+    #
+    # Because :use can accept a name or a Module, {ActiveSecurity.defaults defaults}
+    # can be a convenient place to set up behavior common to all classes using
+    # ActiveSecurity. You can include any module, or more conveniently, define one
+    # on-the-fly. For example, let's say you want to override the error that is
+    # raised when no scope is used:
+    #
+    #     ActiveSecurity.defaults do |config|
+    #       config.use :finders
+    #       config.use Module.new {
+    #         def self.setup(model_class)
+    #           model_class.instance_eval do
+    #             relation.class.send(:prepend, RaiseOverride)
+    #             model_class.singleton_class.send(:prepend, RaiseOverride)
+    #           end
+    #
+    #           association_relation_delegate_class = model_class.relation_delegate_class(::ActiveRecord::AssociationRelation)
+    #           association_relation_delegate_class.send(:prepend, RaiseOverride)
+    #         end
+    #
+    #         module RaiseOverride
+    #           def raise_if_not_scoped
+    #             puts "My errors are better than yours"
+    #             raise StandardError, "Calm Down"
+    #           end
+    #         end
+    #       }
+    #     end
+    #
+    #
+    # @option options [Symbol,Module] :use The addon or name of an addon to use.
+    #   By default, ActiveSecurity provides {ActiveSecurity::Finders :finders},
+    #   {ActiveSecurity::Restricted :restricted}, {ActiveSecurity::Privileged :privileged},
+    #   and {ActiveSecurity::Scoped :scoped}.
+    #
+    # @option options [Symbol] :scope Available when using `:scoped`.
+    #   Sets the relation or column which will be considered a required scope.
+    #   This option has no default value.
+    #
+    # @yield Provides access to the model class's active_security_config, which
+    #   allows an alternate configuration syntax, and conditional configuration
+    #   logic.
+    #
+    # @yieldparam config The model class's {ActiveSecurity::Configuration active_security_config}.
+    def active_security(options = {}, &block)
+      yield active_security_config if block
+      use_mods = options.delete(:use)
+      if use_mods
+        active_security_config.use(use_mods) do |config|
+          config.send(:set, options)
+        end
+      else
+        active_security_config.send(:set, options)
+      end
+    end
+
+    # Returns the model class's {ActiveSecurity::Configuration active_security_config}.
+    # @note In the case of Single Table Inheritance (STI), this method will
+    #   duplicate the parent class's ActiveSecurity::Configuration and relation class
+    #   on first access. If you're concerned about thread safety, then be sure
+    #   to invoke {#active_security} in your class for each model.
+    def active_security_config
+      @active_security_config ||= base_class.active_security_config.dup.tap do |config|
+        config.model_class = self
+      end
+    end
+  end
+end

data/lib/active_security/configuration.rb

@@ -0,0 +1,107 @@
+module ActiveSecurity
+  # The configuration parameters passed to {Base#active_security} will be stored in
+  # this object.
+  class Configuration
+    # The default configuration options.
+    attr_reader :defaults
+
+    # The modules in use
+    attr_reader :modules
+
+    # The model class that this configuration belongs to.
+    # @return ActiveRecord::Base
+    attr_accessor :model_class
+
+    # The module to use for finders
+    attr_accessor :finder_methods
+
+    # Where logs will be sent
+    attr_accessor :logger
+
+    def initialize(model_class, values = nil)
+      @model_class = model_class
+      @defaults = {}
+      @logger = ActiveRecord::Base.logger
+      @modules = []
+      @finder_methods = ActiveSecurity::FinderMethods
+      set(values)
+    end
+
+    # Lets you specify the addon modules to use with ActiveSecurity.
+    #
+    # This method is invoked by {ActiveSecurity::Base#active_security active_security} when
+    # passing the `:use` option, or when using {ActiveSecurity::Base#active_security
+    # active_security} with a block.
+    #
+    # @example
+    #   class Book < ActiveRecord::Base
+    #     extend ActiveSecurity
+    #     active_security use: :finders
+    #   end
+    #
+    # @param [#to_s, Module, Hash[[#to_s, Module], Array[Hash[#to_s, any]]]] modules
+    #   Arguments should be Modules, or symbols or
+    #   strings that correspond with the name of an addon to use with ActiveSecurity,
+    #   or a hash/array of hashes where the keys are Modules, symbols, or strings corresponding as previously described, and
+    #   the values are the Hashes of key value pairs of configuration attributes and their assigned values.
+    #   By default ActiveSecurity provides `:finders`, `:privileged`, `:restricted` and `:scoped`.
+    def use(*modules, &block)
+      mods = modules.to_a.compact
+      mods.map.with_index do |object, idx|
+        case object
+        when Array
+          object.each do |obj|
+            if obj.is_a?(Hash)
+              _handle_hash(obj)
+            else
+              mod = get_module(obj)
+              _use(mod, idx, &block)
+            end
+          end
+        when Hash
+          _handle_hash(object)
+        when String, Symbol, Module
+          mod = get_module(object)
+          _use(mod, idx, &block)
+        else
+          raise InvalidConfig, "Unknown Argument Type #{object.class}: #{object.inspect}"
+        end
+      end
+    end
+
+    def _handle_hash(hash)
+      hash.each do |mod_key, attrs|
+        mod = get_module(mod_key)
+        _use(mod, 0) do |config|
+          config.send(:set, attrs)
+        end
+      end
+    end
+
+    def _use(mod, idx, &block)
+      mod.setup(@model_class) if mod.respond_to?(:setup)
+      @model_class.send(:include, mod) unless uses?(mod)
+      # Only yield on the first module, so as to not run the block multiple times,
+      # and because later modules may require the attributes of a prior module to exist.
+      # The block structure won't work for more complex config than that.
+      # For more complex configuration pass a Hash where the keys are the "modules"
+      yield self if block_given? && idx.zero?
+      mod.after_config(@model_class) if mod.respond_to?(:after_config)
+    end
+
+    # Returns whether the given module is in use.
+    def uses?(mod)
+      @model_class < get_module(mod)
+    end
+
+    private
+
+    def get_module(object)
+      (Module === object) ? object : ActiveSecurity.const_get(object.to_s.titleize.camelize.gsub(/\s+/, ""))
+    end
+
+    def set(values)
+      values&.each { |name, value| send(:"#{name}=", value) }
+    end
+  end
+end

data/lib/active_security/finder_methods.rb

@@ -0,0 +1,64 @@
+module ActiveSecurity
+  module FinderMethods
+    # Finds a record using the given id.
+    # Because this is injected into the Model as well as the relation,
+    # we need handling for both.
+    def find(*args)
+      if is_a?(ActiveRecord::Relation)
+        _active_security_enforce_if_not_scoped
+      else
+        _active_security_not_scoped_handler
+      end
+
+      super
+    end
+
+    private
+
+    def _active_security_enforce_if_not_scoped
+      scoped_securely =
+        if active_security_config.respond_to?(:scope_columns)
+          values[:where].present? && active_security_config.scope_columns.all? do |scope_column|
+            predicates = values[:where].send(:predicates)
+            _active_security_check_predicates_for_scope(predicates, scope_column)
+          end
+        else
+          # If we don't have a specific scope requirement, then just ensure there is some scope.
+          values[:where].present?
+        end
+      _active_security_not_scoped_handler unless scoped_securely
+    end
+
+    def _active_security_check_predicates_for_scope(predicates, scope_column)
+      predicates.detect do |predicate|
+        # Consider alternative...
+        # comp =
+        #   case predicate
+        #   when Arel::Nodes::HomogeneousIn
+        #     predicate.attribute.name
+        #   when Arel::Nodes::Equality
+        #     predicate.right.name
+        #   end
+        comp =
+          if predicate.respond_to?(:attribute) && predicate.attribute.respond_to?(:name)
+            # Handles Arel::Nodes::HomogeneousIn
+            predicate.attribute.name
+          elsif predicate.respond_to?(:right) && predicate.right.respond_to?(:name)
+            # Handles Arel::Nodes::Equality
+            predicate.right.name
+          else
+            _active_security_unhandled_predicate(predicate)
+          end
+        comp == scope_column
+      end
+    end
+
+    def _active_security_name_for
+      if respond_to?(name)
+        "(#{name})"
+      else
+        "(#{(self.class.name == "Class") ? to_s : self.class.name})"
+      end
+    end
+  end
+end

data/lib/active_security/finders.rb

@@ -0,0 +1,118 @@
+module ActiveSecurity
+  # @guide begin
+  #
+  # ## Performing Finds with ActiveSecurity
+  #
+  # ActiveSecurity offers enhanced finders which will search for your record while
+  # ensuring that a particular scope is present. This makes it easy
+  # to add ActiveSecurity to an existing application with minimal code modification.
+  #
+  # By default, these enhanced finders are available only on the `restricted` scope:
+  #
+  #     Restaurant.restricted.find(23)          #=> Will blow up, because no scope!
+  #     Restaurant.find(23)                     #=> works
+  #
+  # ActiveSecurity overrides the default finder methods to perform
+  # secure finds all the time. This requires modifying parts of Rails that do
+  # not have a public API, which is hard to maintain and may cause
+  # compatibility issues.
+  #
+  #     class Restaurant < ActiveRecord::Base
+  #       extend ActiveSecurity
+  #
+  #       scope :active, -> {where(active: true)}
+  #
+  #       active_security use: [:finders]
+  #     end
+  #
+  #     Restaurant.restricted.find(23)          #=> blows up, because no scope!
+  #     Restaurant.find(23)                     #=> also blows up, because no scope!
+  #     Restaurant.active.find(23)              #=> works, because scoped!
+  #     Restaurant.active.restricted.find(23)   #=> also works, because scoped!
+  #
+  # ### Updating your application to use ActiveSecurity's finders
+  #
+  # Unless you've chosen to use the `:finders` addon, be sure to modify the finders
+  # in your controllers to use the `restricted` scope. For example:
+  #
+  #     # before
+  #     def set_restaurant
+  #       @restaurant = Restaurant.find(params[:id])
+  #     end
+  #
+  #     # after
+  #     def set_restaurant
+  #       @restaurant = Restaurant.restricted.find(params[:id])
+  #     end
+  #
+  # #### Active Admin
+  #
+  # Unless you use the `:finders` addon, you should modify your admin controllers
+  # for models that use ActiveSecurity with something similar to the following:
+  #
+  #     controller do
+  #       def find_resource
+  #         scoped_collection.restricted.find(params[:id])
+  #       end
+  #     end
+  #
+  # @guide end
+  module Finders
+    class << self
+      # ActiveSecurity::Config.use will invoke this method when present, to allow
+      # loading dependent modules prior to overriding them when necessary.
+      def setup(model_class)
+        model_class.class_eval do
+          relation.class.send(:include, active_security_config.finder_methods)
+          extend(active_security_config.finder_methods)
+        end
+
+        association_relation_delegate_class = model_class.relation_delegate_class(::ActiveRecord::AssociationRelation)
+        association_relation_delegate_class.send(:include, model_class.active_security_config.finder_methods)
+      end
+
+      # Sets up behavior and configuration options for finders feature.
+      def included(model_class)
+        model_class.active_security_config.instance_eval do
+          self.class.send(:include, Configuration)
+          defaults[:default_finders] ||= :restricted
+        end
+      end
+
+      # Sets up behavior and that depends on configuration
+      def after_config(model_class)
+        raise InvalidConfig, ":finders plugin must be used with default_finders set to one of :privileged, or :restricted" unless %i[restricted privileged].include?(model_class.active_security_config.default_finders)
+
+        model_class.active_security_config.use(model_class.active_security_config.default_finders)
+        model_class.class_eval do
+          if active_security_config.default_finders == :privileged
+            relation.class.send(:include, active_security_config.privileged_hooks)
+            send(:extend, active_security_config.privileged_hooks)
+          else
+            relation.class.send(:include, active_security_config.restricted_hooks)
+            send(:extend, active_security_config.restricted_hooks)
+          end
+        end
+        association_relation_delegate_class = model_class.relation_delegate_class(::ActiveRecord::AssociationRelation)
+        if model_class.active_security_config.default_finders == :privileged
+          association_relation_delegate_class.send(:include, model_class.active_security_config.privileged_hooks)
+        else
+          model_class.active_security_config.default_finders
+          association_relation_delegate_class.send(:include, model_class.active_security_config.restricted_hooks)
+        end
+      end
+    end
+
+    # This module adds the `:default_finders` configuration option to
+    # {ActiveSecurity::Configuration ActiveSecurity::Configuration}.
+    module Configuration
+      # Gets the default_finders value.
+      #
+      # When setting this value, the argument should be a symbol, either
+      # :restricted or :privileged.  Default is :restricted.
+      #
+      # @return Symbol The default_finders value
+      attr_accessor :default_finders
+    end
+  end
+end

data/lib/active_security/privileged.rb

@@ -0,0 +1,39 @@
+module ActiveSecurity
+  module Privileged
+    class << self
+      # Sets up behavior and configuration options for privileged feature.
+      def included(model_class)
+        model_class.active_security_config.instance_eval do
+          self.class.send(:include, Configuration)
+          defaults[:privileged_hooks] ||= ActiveSecurity::PrivilegedHooks
+        end
+        model_class.class_eval do
+          extend(PrivilegedScope)
+        end
+      end
+    end
+
+    # This module adds `:privileged_hooks` to
+    # {ActiveSecurity::Configuration ActiveSecurity::Configuration}.
+    module Configuration
+      attr_writer :privileged_hooks
+
+      def privileged_hooks
+        @privileged_hooks ||= defaults[:privileged_hooks]
+      end
+    end
+
+    module PrivilegedScope
+      # Returns a scope that is allowed to not require the secure scope, but will
+      # be logged.
+      # @see ActiveSecurity::FinderMethods
+      # @see ActiveSecurity::Privileged
+      def privileged
+        all.extending(
+          active_security_config.finder_methods,
+          active_security_config.privileged_hooks,
+        )
+      end
+    end
+  end
+end

data/lib/active_security/privileged_hooks.rb

@@ -0,0 +1,13 @@
+module ActiveSecurity
+  module PrivilegedHooks
+    extend ActiveSupport::Concern
+
+    def _active_security_not_scoped_handler
+      active_security_config.logger.warn("[Privileged] #{_active_security_name_for} does not have secure scope: #{respond_to?(:to_sql) ? to_sql : ""}")
+    end
+
+    def _active_security_unhandled_predicate(predicate)
+      active_security_config.logger.error("[Privileged] #{_active_security_name_for} predicate type #{predicate.class.name} is unhandled; See: https://www.rubydoc.info/github/rails/rails/Arel/Nodes")
+    end
+  end
+end

data/lib/active_security/restricted.rb

@@ -0,0 +1,71 @@
+module ActiveSecurity
+  module Restricted
+    class << self
+      # Sets up behavior and configuration options for restricted feature.
+      def included(model_class)
+        model_class.active_security_config.instance_eval do
+          self.class.send(:include, Configuration)
+          defaults[:restricted_hooks] ||= ActiveSecurity::RestrictedHooks
+          defaults[:on_restricted_no_scope] ||= :log_and_raise
+          defaults[:on_restricted_unhandled_predicate] ||= :log_and_raise
+        end
+        model_class.class_eval do
+          extend(RestrictedScope)
+        end
+      end
+    end
+
+    # This module adds `:restricted_hooks`, `:on_restricted_no_scope`
+    # and `:on_restricted_unhandled_predicate` configuration options to
+    # {ActiveSecurity::Configuration ActiveSecurity::Configuration}.
+    module Configuration
+      attr_writer :restricted_hooks
+      # Gets the on_restricted_no_scope value.
+      #
+      # When setting this value, the argument should either be a callable lambda/proc,
+      # or one of :log, :log_and_raise, :raise.
+      attr_writer :on_restricted_no_scope
+
+      # Gets the on_restricted_unhandled_predicate value.
+      #
+      # When setting this value, the argument should either be a callable lambda/proc,
+      # or one of :log, :log_and_raise, :raise.
+      attr_writer :on_restricted_unhandled_predicate
+
+      # @return Module The module to use for restricted_hooks
+      def restricted_hooks
+        @restricted_hooks ||= defaults[:restricted_hooks]
+      end
+
+      # @return Symbol The on_restricted_no_scope value
+      def on_restricted_no_scope
+        @on_restricted_no_scope ||= defaults[:on_restricted_no_scope]
+      end
+
+      # @return Symbol The on_restricted_unhandled_predicate value
+      def on_restricted_unhandled_predicate
+        @on_restricted_unhandled_predicate ||= defaults[:on_restricted_unhandled_predicate]
+      end
+    end
+
+    module RestrictedScope
+      # Returns a scope that includes the active_security restricted hooks.
+      # @see ActiveSecurity::FinderMethods
+      # @see ActiveSecurity::RestrictedHooks
+      def restricted
+        # Guess what? This causes Rails to invoke `extend` on the scope, which has
+        # the well-known effect of blowing away Ruby's method cache. It would be
+        # possible to make this more performant by subclassing the model's
+        # relation class, extending that, and returning an instance of it in this
+        # method. However, using Rails' public API improves compatibility
+        # and maintainability. If you'd like to improve the performance, your
+        # efforts would be best directed at improving it at the root cause
+        # of the problem - in Rails - because it would benefit more people.
+        all.extending(
+          active_security_config.finder_methods,
+          active_security_config.restricted_hooks,
+        )
+      end
+    end
+  end
+end

data/lib/active_security/restricted_hooks.rb

@@ -0,0 +1,41 @@
+module ActiveSecurity
+  module RestrictedHooks
+    extend ActiveSupport::Concern
+
+    VALID_CONFIG_VALUES = %i[log log_and_raise raise]
+
+    def _active_security_not_scoped_handler
+      return active_security_config.on_restricted_no_scope.call(active_security_config) if active_security_config.on_restricted_no_scope.respond_to?(:call)
+
+      unless VALID_CONFIG_VALUES.include?(active_security_config.on_restricted_no_scope)
+        raise InvalidConfig, "on_restricted_no_scope must either be set to a (callable lambda/proc) or one of [:log, :log_and_raise, :raise]"
+      end
+
+      if /log/.match?(active_security_config.on_restricted_no_scope)
+        active_security_config.logger.error("#{_active_security_name_for} does not have secure scope: #{respond_to?(:to_sql) ? to_sql : ""}")
+      end
+
+      if /raise/.match?(active_security_config.on_restricted_no_scope)
+        raise RestrictedAccessError.new("prevented query without a secure scope #{_active_security_name_for}")
+      end
+    end
+
+    def _active_security_unhandled_predicate(predicate)
+      return active_security_config.on_restricted_unhandled_predicate.call(active_security_config) if active_security_config.on_restricted_unhandled_predicate.respond_to?(:call)
+
+      unless VALID_CONFIG_VALUES.include?(active_security_config.on_restricted_unhandled_predicate)
+        raise InvalidConfig, "on_restricted_unhandled_predicate must either be set to a (callable lambda/proc) or one of [:log, :log_and_raise, :raise]"
+      end
+
+      if /log/.match?(active_security_config.on_restricted_unhandled_predicate)
+        active_security_config.logger.error("#{_active_security_name_for} predicate type #{predicate.class.name} is unhandled; See: https://www.rubydoc.info/github/rails/rails/Arel/Nodes")
+      end
+
+      if /raise/.match?(active_security_config.on_restricted_unhandled_predicate)
+        raise UnhandledArelPredicateError.new(
+          "#{_active_security_name_for} predicate type #{predicate.class.name} is unhandled; See: https://www.rubydoc.info/github/rails/rails/Arel/Nodes",
+        )
+      end
+    end
+  end
+end