active_security 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,4 @@
1
1
  module ActiveSecurity
2
- # @guide begin
3
- #
4
2
  # ## Setting Up ActiveSecurity in Your Model
5
3
  #
6
4
  # To use ActiveSecurity in your ActiveRecord models, you must first either extend or
@@ -10,7 +8,7 @@ module ActiveSecurity
10
8
  #
11
9
  # class Foo < ActiveRecord::Base
12
10
  # include ActiveSecurity
13
- # active_security :use => [:finders, :scoped], scope: :bar_id
11
+ # active_security :use => {finders: {default_finders: :restricted}, scoped: {scope: :bar_id}}
14
12
  # end
15
13
  #
16
14
  # The most important option is `:use`, which you use to tell ActiveSecurity which
@@ -22,9 +20,12 @@ module ActiveSecurity
22
20
  # *all classes that participate in STI, both your parent classes and their*
23
21
  # *children.*
24
22
  #
25
- # ### The Default Setup: Simple Models
23
+ # ### The Basic Setup: Simple Models
26
24
  #
27
- # The simplest way to use ActiveSecurity is to have it ensure that finds are executed within a scope:
25
+ # By default the `:restricted` plugin is the only one configured, and the `restricted`
26
+ # scope must be explicitly added to every query.
27
+ # This is the simplest way to use ActiveSecurity. But it is messy, and laborious.
28
+ # It will ensure that finds are executed within a `where` scope:
28
29
  #
29
30
  # class User < ActiveRecord::Base
30
31
  # extend ActiveSecurity
@@ -33,7 +34,7 @@ module ActiveSecurity
33
34
  # User.restricted.find(1) # blows up, because no scope
34
35
  # User.where(...).restricted.find(1) # returns the user
35
36
  #
36
- # ### The Strict Setup: Simple Models
37
+ # ### The Strict Setup: Magic Finders
37
38
  #
38
39
  # The problem with the above approach is that a naked find (`User.find(1)`)
39
40
  # still works, and is just as insecure as before. The `:finders` plugin fixes
@@ -44,10 +45,9 @@ module ActiveSecurity
44
45
  # active_security use: {finders: {default_finders: :restricted}}
45
46
  # end
46
47
  #
47
- # User.find(1) # blows up, because no scope
48
- # User.where(...).find(1) # returns the user
49
- #
50
- # @guide end
48
+ # User.find(1) # blows up, because no scope
49
+ # User.where(...).find(1) # returns the user
50
+ # User.where(...).restricted.find(1) # also returns the user
51
51
  module Base
52
52
  # Configure ActiveSecurity's behavior in a model.
53
53
  #
@@ -99,7 +99,24 @@ module ActiveSecurity
99
99
  # ### Order Method Calls in a Block vs Ordering Options
100
100
  #
101
101
  # When calling this method without a block, you may set the hash options in
102
- # any order.
102
+ # any order, so long as they either have no dependencies, or are coupled with
103
+ # their respective module.
104
+ #
105
+ # Here's an example that configures every plugin:
106
+ #
107
+ # class Person < ActiveRecord::Base
108
+ # active_security use: {
109
+ # finders: {default_finders: :restricted},
110
+ # scoped: {scope: :name},
111
+ # privileged: {}
112
+ # }
113
+ # end
114
+ #
115
+ # Person.find(1) # blows up, because no scope
116
+ # Person.where(name: "Bart").find(1) # returns the person
117
+ # Person.where(age: 29).find(1) # blows up, because name scope wasn't used
118
+ # Person.where(age: 29).privileged.find(1) # returns the person, because privileged
119
+ # Person.where(name: "Bart").restricted.find(1) # also returns the person, because name scope used
103
120
  #
104
121
  # However, when using block-style invocation, be sure to call
105
122
  # ActiveSecurity::Configuration's {ActiveSecurity::Configuration#use use} method
@@ -128,8 +145,8 @@ module ActiveSecurity
128
145
  # Because :use can accept a name or a Module, {ActiveSecurity.defaults defaults}
129
146
  # can be a convenient place to set up behavior common to all classes using
130
147
  # ActiveSecurity. You can include any module, or more conveniently, define one
131
- # on-the-fly. For example, let's say you want to override the error that is
132
- # raised when no scope is used:
148
+ # on-the-fly. For example, let's say you want to globally override the error
149
+ # that is raised when no scope is used:
133
150
  #
134
151
  # ActiveSecurity.defaults do |config|
135
152
  # config.use :finders
@@ -153,16 +170,39 @@ module ActiveSecurity
153
170
  # }
154
171
  # end
155
172
  #
156
- #
157
- # @option options [Symbol,Module] :use The addon or name of an addon to use.
173
+ # @option options [Symbol, Module] :use The addon or name of an addon to use.
158
174
  # By default, ActiveSecurity provides {ActiveSecurity::Finders :finders},
159
175
  # {ActiveSecurity::Restricted :restricted}, {ActiveSecurity::Privileged :privileged},
160
- # and {ActiveSecurity::Scoped :scoped}.
176
+ # and {ActiveSecurity::Scoped :scoped}, or a hash where the keys are the symbolized
177
+ # module names just mentioned, and the values are hashes of options to set for each
178
+ # module.
161
179
  #
162
- # @option options [Symbol] :scope Available when using `:scoped`.
163
- # Sets the relation or column which will be considered a required scope.
180
+ # @option options [Symbol, Array[Symbol]] :scope Available when using `:scoped`.
181
+ # Sets the relation(s) or column(s) which will be considered a required scope.
164
182
  # This option has no default value.
165
183
  #
184
+ # @option options [Symbol] :default_finders Available when using `:finders`.
185
+ # Sets the type of scope enforcement to use. Must be one of :restricted or
186
+ # :privileged. Default value is :restricted.
187
+ #
188
+ # @option options [Module] :privileged_hooks Available when using `:privileged`.
189
+ # Sets the Module which defines the necessary hooks for the Privileged behavior.
190
+ # Default value is {ActiveSecurity::PrivilegedHooks}
191
+ #
192
+ # @option options [Module] :restricted_hooks Available when using `:restricted`.
193
+ # Sets the Module which defines the necessary hooks for the Restricted behavior.
194
+ # Default value is {ActiveSecurity::RestrictedHooks}
195
+ #
196
+ # @option options [Symbol, #call] :on_restricted_no_scope Available when using `:restricted`.
197
+ # Sets the Restricted behavior when the expected scope is not found. Must be one of
198
+ # the following [#call, :log, :log_and_raise, :raise].
199
+ # Default value is :log_and_raise.
200
+ #
201
+ # @option options [Symbol, #call] :on_restricted_unhandled_predicate Available when using `:restricted`.
202
+ # Sets the Restricted behavior when the scopes Arel Node has no defined handling. Must be one of
203
+ # the following [#call, :log, :log_and_raise, :raise].
204
+ # Default value is :log_and_raise.
205
+ #
166
206
  # @yield Provides access to the model class's active_security_config, which
167
207
  # allows an alternate configuration syntax, and conditional configuration
168
208
  # logic.
File without changes
File without changes
@@ -1,6 +1,4 @@
1
1
  module ActiveSecurity
2
- # @guide begin
3
- #
4
2
  # ## Performing Finds with ActiveSecurity
5
3
  #
6
4
  # ActiveSecurity offers enhanced finders which will search for your record while
@@ -22,7 +20,7 @@ module ActiveSecurity
22
20
  #
23
21
  # scope :active, -> {where(active: true)}
24
22
  #
25
- # active_security use: [:finders]
23
+ # active_security use: :finders
26
24
  # end
27
25
  #
28
26
  # Restaurant.restricted.find(23) #=> blows up, because no scope!
@@ -55,8 +53,6 @@ module ActiveSecurity
55
53
  # scoped_collection.restricted.find(params[:id])
56
54
  # end
57
55
  # end
58
- #
59
- # @guide end
60
56
  module Finders
61
57
  class << self
62
58
  # ActiveSecurity::Config.use will invoke this method when present, to allow
@@ -31,7 +31,7 @@ module ActiveSecurity
31
31
  def privileged
32
32
  all.extending(
33
33
  active_security_config.finder_methods,
34
- active_security_config.privileged_hooks,
34
+ active_security_config.privileged_hooks
35
35
  )
36
36
  end
37
37
  end
@@ -3,7 +3,7 @@ module ActiveSecurity
3
3
  extend ActiveSupport::Concern
4
4
 
5
5
  def _active_security_not_scoped_handler
6
- active_security_config.logger.warn("[Privileged] #{_active_security_name_for} does not have secure scope: #{respond_to?(:to_sql) ? to_sql : ""}")
6
+ active_security_config.logger.warn("[Privileged] #{_active_security_name_for} does not have secure scope: #{to_sql if respond_to?(:to_sql)}")
7
7
  end
8
8
 
9
9
  def _active_security_unhandled_predicate(predicate)
@@ -63,7 +63,7 @@ module ActiveSecurity
63
63
  # of the problem - in Rails - because it would benefit more people.
64
64
  all.extending(
65
65
  active_security_config.finder_methods,
66
- active_security_config.restricted_hooks,
66
+ active_security_config.restricted_hooks
67
67
  )
68
68
  end
69
69
  end
@@ -8,11 +8,11 @@ module ActiveSecurity
8
8
  return active_security_config.on_restricted_no_scope.call(active_security_config) if active_security_config.on_restricted_no_scope.respond_to?(:call)
9
9
 
10
10
  unless VALID_CONFIG_VALUES.include?(active_security_config.on_restricted_no_scope)
11
- raise InvalidConfig, "on_restricted_no_scope must either be set to a (callable lambda/proc) or one of [:log, :log_and_raise, :raise]"
11
+ raise InvalidConfig, "on_restricted_no_scope must either be set to a callable lambda/proc or one of [:log, :log_and_raise, :raise]"
12
12
  end
13
13
 
14
14
  if /log/.match?(active_security_config.on_restricted_no_scope)
15
- active_security_config.logger.error("#{_active_security_name_for} does not have secure scope: #{respond_to?(:to_sql) ? to_sql : ""}")
15
+ active_security_config.logger.error("#{_active_security_name_for} does not have secure scope: #{to_sql if respond_to?(:to_sql)}")
16
16
  end
17
17
 
18
18
  if /raise/.match?(active_security_config.on_restricted_no_scope)
@@ -24,7 +24,7 @@ module ActiveSecurity
24
24
  return active_security_config.on_restricted_unhandled_predicate.call(active_security_config) if active_security_config.on_restricted_unhandled_predicate.respond_to?(:call)
25
25
 
26
26
  unless VALID_CONFIG_VALUES.include?(active_security_config.on_restricted_unhandled_predicate)
27
- raise InvalidConfig, "on_restricted_unhandled_predicate must either be set to a (callable lambda/proc) or one of [:log, :log_and_raise, :raise]"
27
+ raise InvalidConfig, "on_restricted_unhandled_predicate must either be set to a callable lambda/proc or one of [:log, :log_and_raise, :raise]"
28
28
  end
29
29
 
30
30
  if /log/.match?(active_security_config.on_restricted_unhandled_predicate)
@@ -33,7 +33,7 @@ module ActiveSecurity
33
33
 
34
34
  if /raise/.match?(active_security_config.on_restricted_unhandled_predicate)
35
35
  raise UnhandledArelPredicateError.new(
36
- "#{_active_security_name_for} predicate type #{predicate.class.name} is unhandled; See: https://www.rubydoc.info/github/rails/rails/Arel/Nodes",
36
+ "#{_active_security_name_for} predicate type #{predicate.class.name} is unhandled; See: https://www.rubydoc.info/github/rails/rails/Arel/Nodes"
37
37
  )
38
38
  end
39
39
  end
@@ -1,6 +1,4 @@
1
1
  module ActiveSecurity
2
- # @guide begin
3
- #
4
2
  # ## Required Scope
5
3
  #
6
4
  # The {ActiveSecurity::Scoped} module allows ActiveSecurity to enforce querying
@@ -54,8 +52,6 @@ module ActiveSecurity
54
52
  # Alternatively, you could pass the scope value as a query parameter:
55
53
  #
56
54
  # Restaurant.where(city_id: @city.id).restricted.find(23)
57
- #
58
- # @guide end
59
55
  module Scoped
60
56
  class << self
61
57
  # Sets up behavior and configuration options for scoped feature.
@@ -1,7 +1,11 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module ActiveSecurity
4
+ # Version namespace for this gem.
4
5
  module Version
5
- VERSION = "1.0.0"
6
+ # Current gem version.
7
+ VERSION = "1.0.2"
6
8
  end
9
+ # Current gem version exposed at the traditional constant location.
10
+ VERSION = Version::VERSION # Traditional Constant Location
7
11
  end
@@ -6,12 +6,12 @@ require "active_record"
6
6
  require "active_support"
7
7
 
8
8
  # This library
9
- require_relative "active_security/version"
10
9
  require_relative "active_security/base"
11
10
  require_relative "active_security/configuration"
12
11
  require_relative "active_security/finder_methods"
13
12
  require_relative "active_security/privileged_hooks"
14
13
  require_relative "active_security/restricted_hooks"
14
+ require_relative "active_security/version"
15
15
 
16
16
  module ActiveSecurity
17
17
  class RestrictedAccessError < RuntimeError; end
@@ -52,6 +52,7 @@ module ActiveSecurity
52
52
  end
53
53
  model_class.class_eval do
54
54
  extend(Base)
55
+
55
56
  @active_security_config = Class.new(Configuration).new(self) # rubocop:disable ThreadSafety/InstanceVariableInClassMethod
56
57
  ActiveSecurity.defaults.call(@active_security_config) # rubocop:disable ThreadSafety/InstanceVariableInClassMethod
57
58
  end
@@ -0,0 +1,7 @@
1
+ module ActiveSecurity
2
+ VERSION: String
3
+ module Version
4
+ VERSION: String
5
+ end
6
+ # See the writing guide of rbs: https://github.com/ruby/rbs#guides
7
+ end
data.tar.gz.sig CHANGED
Binary file