active_security 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c68226e5113d5925222d0e456dfbccac3866b3d526d35a018a52a4a8f2aa476
-  data.tar.gz: 5590c5054131249ee7fa5fa3875a3fe64440154f37f7614d7c6fce0a4807b25f
+  metadata.gz: 2322b02db484fe2c369a43418f4e423714925bef1b9bc0ce6373f9813165fb43
+  data.tar.gz: 1bca4956c77105fae796d3c7b9b97780900c8d0727ca2578f2cfc3244cfe3d72
 SHA512:
-  metadata.gz: aa9c8e50b69b7427a4f769da3132324c3c0d5fa8f6ba5a1d78955194573e7c84accfebb1666cf144520cb9fb90c3b553f23501ee3657f8841ed53553312e690d
-  data.tar.gz: 961dd3238ba102b5b5b7100a88a080d1f42b62c619e16fbeafa25469c5d090d38c23b33bdafd032631cda644f4c6dfdcdca0d3817f4890870667ae1c2cc2ee1c
+  metadata.gz: 6e1e66f6d0d4e0ccfc24e5f5df8d4e652674e94a27241b4af29d0936258238e9d601e9c556f232299b40015aee24d377f3dca49391aad992ba325f41975b0262
+  data.tar.gz: 8319888c2fa8d89b67ab8547d861c344f6913c13ee5e5a7ea374e9e7cccf5d9d1c273867edc55d8ff5ffb008adf25c196a185c8e721f1afb48d56463e76f8365

data/CHANGELOG.md

@@ -1,5 +1,25 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+Since version 2.0.0, the format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## [Unreleased]
+### Added
+### Changed
+### Fixed
+### Removed
 
-## [1.0.0] - 2024-07-04
+## [1.0.1] - 2024-07-05
+### Added
+- Documentation
 
+## [1.0.0] - 2024-07-05
+### Added
 - Initial release
+
+[Unreleased]: https://github.com/pboling/sanitize_email/compare/v1.0.1...HEAD
+[1.0.1]: https://github.com/pboling/sanitize_email/compare/v1.0.0...v1.0.1
+[1.0.1t]: https://github.com/pboling/sanitize_email/tags/v1.0.1
+[1.0.0]: https://github.com/pboling/sanitize_email/compare/9caac884909193326b3f3318ad3db00ca754fabd...v1.0.0
+[1.0.0t]: https://github.com/pboling/sanitize_email/tags/v1.0.0

data/README.md

@@ -182,8 +182,199 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Documentation
 
-All documentation is in the source for now, but there is a lot of it.
-If you'd like to help add documentation to this readme, please submit a pull request.
+All documentation is in the source so check there if the following is not enough.
+
+### 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:
+
+```ruby
+class Foo < ActiveRecord::Base
+  include ActiveSecurity
+  active_security :use => {finders: {default_finders: :restricted}, 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 Basic Setup: Simple Models
+
+By default the `:restricted` plugin is the only one configured, and the `restricted`
+scope must be explicitly added to every query.
+This is the simplest way to use ActiveSecurity.  But it is messy, and laborious.
+It will ensure that finds are executed within a `where` scope:
+
+```ruby
+class User < ActiveRecord::Base
+  extend ActiveSecurity
+end
+
+User.restricted.find(1)                       # blows up, because no scope
+User.where(name: "Bart").restricted.find(1)   # returns the user
+```
+
+#### The Strict Setup: Magic Finders
+
+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.
+
+```ruby
+class User < ActiveRecord::Base
+  extend ActiveSecurity
+  active_security use: {finders: {default_finders: :restricted}}
+end
+
+User.find(1)                                 # blows up, because no scope
+User.where(name: "Bart").find(1)             # returns the user
+User.where(name: "Bart").restricted.find(1)  # also returns the user
+```
+
+### Configuration: ActiveSecurity's behavior in a model
+
+Here's a basic config.
+
+```ruby
+class Post < ActiveRecord::Base
+  extend ActiveSecurity
+  active_security use: :finders
+end
+```
+
+Now let's get crazy secure!
+
+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:
+
+```ruby
+$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:
+
+```ruby
+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, so long as they either have no dependencies, or are coupled with
+their respective module.
+
+Here's an example that configures every plugin:
+```ruby
+class Person < ActiveRecord::Base
+  active_security use: {
+    finders: {default_finders: :restricted},
+    scoped: {scope: :name},
+    privileged: {}
+  }
+end
+
+Person.find(1)                                 # blows up, because no scope
+Person.where(name: "Bart").find(1)             # returns the person
+Person.where(age: 29).find(1)                  # blows up, because name scope wasn't used
+Person.where(age: 29).privileged.find(1)       # returns the person, because privileged
+Person.where(name: "Bart").restricted.find(1)  # also returns the person, because name scope used
+```
+
+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:
+
+```ruby
+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 globally override the error
+that is raised when no scope is used:
+
+```ruby
+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
+```
 
 ## Running Specs
 

data/lib/active_security/base.rb

@@ -10,7 +10,7 @@ module ActiveSecurity
   #
   #     class Foo < ActiveRecord::Base
   #       include ActiveSecurity
-  #       active_security :use => [:finders, :scoped], scope: :bar_id
+  #       active_security :use => {finders: {default_finders: :restricted}, scoped: {scope: :bar_id}}
   #     end
   #
   # The most important option is `:use`, which you use to tell ActiveSecurity which
@@ -22,9 +22,12 @@ module ActiveSecurity
   # *all classes that participate in STI, both your parent classes and their*
   # *children.*
   #
-  # ### The Default Setup: Simple Models
+  # ### The Basic Setup: Simple Models
   #
-  # The simplest way to use ActiveSecurity is to have it ensure that finds are executed within a scope:
+  # By default the `:restricted` plugin is the only one configured, and the `restricted`
+  # scope must be explicitly added to every query.
+  # This is the simplest way to use ActiveSecurity.  But it is messy, and laborious.
+  # It will ensure that finds are executed within a `where` scope:
   #
   #     class User < ActiveRecord::Base
   #       extend ActiveSecurity
@@ -33,7 +36,7 @@ module ActiveSecurity
   #     User.restricted.find(1)             # blows up, because no scope
   #     User.where(...).restricted.find(1)  # returns the user
   #
-  # ### The Strict Setup: Simple Models
+  # ### The Strict Setup: Magic Finders
   #
   # 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
@@ -44,8 +47,9 @@ module ActiveSecurity
   #       active_security use: {finders: {default_finders: :restricted}}
   #     end
   #
-  #     User.find(1)             # blows up, because no scope
-  #     User.where(...).find(1)  # returns the user
+  #     User.find(1)                        # blows up, because no scope
+  #     User.where(...).find(1)             # returns the user
+  #     User.where(...).restricted.find(1)  # also returns the user
   #
   # @guide end
   module Base
@@ -99,7 +103,24 @@ module ActiveSecurity
     # ### 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.
+    # any order, so long as they either have no dependencies, or are coupled with
+    # their respective module.
+    #
+    # Here's an example that configures every plugin:
+    #
+    #     class Person < ActiveRecord::Base
+    #       active_security use: {
+    #         finders: {default_finders: :restricted},
+    #         scoped: {scope: :name},
+    #         privileged: {}
+    #       }
+    #     end
+    #
+    #     Person.find(1)                                 # blows up, because no scope
+    #     Person.where(name: "Bart").find(1)             # returns the person
+    #     Person.where(age: 29).find(1)                  # blows up, because name scope wasn't used
+    #     Person.where(age: 29).privileged.find(1)       # returns the person, because privileged
+    #     Person.where(name: "Bart").restricted.find(1)  # also returns the person, because name scope used
     #
     # However, when using block-style invocation, be sure to call
     # ActiveSecurity::Configuration's {ActiveSecurity::Configuration#use use} method
@@ -128,8 +149,8 @@ module ActiveSecurity
     # 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:
+    # on-the-fly. For example, let's say you want to globally override the error
+    # that is raised when no scope is used:
     #
     #     ActiveSecurity.defaults do |config|
     #       config.use :finders
@@ -153,16 +174,39 @@ module ActiveSecurity
     #       }
     #     end
     #
-    #
-    # @option options [Symbol,Module] :use The addon or name of an addon to use.
+    # @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}.
+    #   and {ActiveSecurity::Scoped :scoped}, or a hash where the keys are the symbolized
+    #   module names just mentioned, and the values are hashes of options to set for each
+    #   module.
     #
-    # @option options [Symbol] :scope Available when using `:scoped`.
-    #   Sets the relation or column which will be considered a required scope.
+    # @option options [Symbol, Array[Symbol]] :scope Available when using `:scoped`.
+    #   Sets the relation(s) or column(s) which will be considered a required scope.
     #   This option has no default value.
     #
+    # @option options [Symbol] :default_finders Available when using `:finders`.
+    #   Sets the type of scope enforcement to use. Must be one of :restricted or
+    #   :privileged. Default value is :restricted.
+    #
+    # @option options [Module] :privileged_hooks Available when using `:privileged`.
+    #   Sets the Module which defines the necessary hooks for the Privileged behavior.
+    #   Default value is {ActiveSecurity::PrivilegedHooks}
+    #
+    # @option options [Module] :restricted_hooks Available when using `:restricted`.
+    #   Sets the Module which defines the necessary hooks for the Restricted behavior.
+    #   Default value is {ActiveSecurity::RestrictedHooks}
+    #
+    # @option options [Symbol, #call] :on_restricted_no_scope Available when using `:restricted`.
+    #   Sets the Restricted behavior when the expected scope is not found. Must be one of
+    #   the following [#call, :log, :log_and_raise, :raise].
+    #   Default value is :log_and_raise.
+    #
+    # @option options [Symbol, #call] :on_restricted_unhandled_predicate Available when using `:restricted`.
+    #   Sets the Restricted behavior when the scopes Arel Node has no defined handling. Must be one of
+    #   the following [#call, :log, :log_and_raise, :raise].
+    #   Default value is :log_and_raise.
+    #
     # @yield Provides access to the model class's active_security_config, which
     #   allows an alternate configuration syntax, and conditional configuration
     #   logic.

data/lib/active_security/finders.rb

@@ -22,7 +22,7 @@ module ActiveSecurity
   #
   #       scope :active, -> {where(active: true)}
   #
-  #       active_security use: [:finders]
+  #       active_security use: :finders
   #     end
   #
   #     Restaurant.restricted.find(23)          #=> blows up, because no scope!

data/lib/active_security/restricted_hooks.rb

@@ -8,7 +8,7 @@ module ActiveSecurity
       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]"
+        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)
@@ -24,7 +24,7 @@ module ActiveSecurity
       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]"
+        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)

data/lib/active_security/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveSecurity
   module Version
-    VERSION = "1.0.0"
+    VERSION = "1.0.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_security
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Peter Boling
@@ -365,10 +365,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/pboling/active_security
-  source_code_uri: https://github.com/pboling/active_security/tree/v1.0.0
-  changelog_uri: https://github.com/pboling/active_security/blob/v1.0.0/CHANGELOG.md
+  source_code_uri: https://github.com/pboling/active_security/tree/v1.0.1
+  changelog_uri: https://github.com/pboling/active_security/blob/v1.0.1/CHANGELOG.md
   bug_tracker_uri: https://github.com/pboling/active_security/issues
-  documentation_uri: https://www.rubydoc.info/gems/active_security/1.0.0
+  documentation_uri: https://www.rubydoc.info/gems/active_security/1.0.1
   wiki_uri: https://github.com/pboling/active_security/wiki
   funding_uri: https://liberapay.com/pboling
   rubygems_mfa_required: 'true'