sequel-privacy 0.5.3 → 0.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f2538fcf5aee16c7b624701e81d936df211b20fa007cf9fa1fffc893bda0105
-  data.tar.gz: e1df8a2b58c2e6851447e2874c837a865641be73ed0adc25c255bcb9076d4087
+  metadata.gz: 7dd8660d0cc93e21c96080ba66f777e9b39f00ec7a5ca4f8fa211739a97dbe62
+  data.tar.gz: 85952e038e33a535adf8adaed566c08310e003f2540a406457029d678e889009
 SHA512:
-  metadata.gz: 68996d09fde85691254e51d6edb40f4a32007c07a232b768a705d29b7b4ea37ebe95a2ac092c18f201a7516b53108d4a8ff8356a0f860c288a18903648b5c1b6
-  data.tar.gz: d1b9364e64145dbe2993c18bb8db458826b2480e9e827f589ed6cecefdbb1e2c82e0c2fdd72a3542946fb4bea70e2d58c37f81889067b3b5e7c5ce7912032477
+  metadata.gz: 9276223bd19d31daaabbaa34076e15c6dce4ce2439daadc30bee5e021fc7a88571323ce213ab2840afbe533b53d73129625817177a44b7a178f1fc93b6f21c37
+  data.tar.gz: d6c2e72d8eea11c83b42be27a64dd5076e0e320a7d15efe7a6092ca543714203cf643ad14eee190b986eda570a331fca2b8d519126494ff35d5caef421f2fb9a

data/README.md

@@ -110,13 +110,12 @@ member.phone  # => nil if :view_phone denies
 
 ## Policy Definition
 
-Policies are lambdas that execute in the context of an `Actions` struct, giving access to `allow`, `deny`, and `pass` outcome methods, as well as the `all` combinator. `allow` and `deny` will end evaluation of the chain of policies, whereas `pass` will continue to the next policy in the chain.
+Policies are lambdas that execute in the context of an `Actions` class, giving access to `allow`, `deny`, and `pass` outcome methods, as well as the `all` combinator. `allow` and `deny` will end evaluation of the chain of policies, whereas `pass` will continue to the next policy in the chain.
 
-Policies are **actor-first**. Arities map to:
 - 0 args — global decision (`-> { allow if Time.now.sunday? }`)
-- 1 arg  — `(actor)`: role / identity checks
-- 2 args — `(actor, subject)`: ownership, membership
-- 3 args — `(actor, subject, direct_object)`: "can actor do X to subject with direct_object?"
+- 1 arg  — `(actor)`: Useful for role / identity checks
+- 2 args — `(actor, subject)`: General purpose relationship checks
+- 3 args — `(actor, subject, direct_object)`: "Allow members to remove themselves from a group they're in"
 
 Policies of arity ≥ 1 auto-deny for anonymous viewers (nil actor). Use `allow_anonymous: true` to opt out — meant for state-gate policies that examine only the subject.
 
@@ -175,7 +174,7 @@ policy :MyPolicy, ->() { ... },
 
 **`cacheable: true`** (default): Results are cached for the duration of the request, keyed by policy + arguments. Use for policies that don't depend on mutable state.
 
-**`single_match: true`**: Optimization for policies for which there is only one matching Actor possible for a given Subject. For example in `AllowAuthors`, since a `Post` can have only one other, it's not worth a potentially expensive check on other combinations once you've found the winner.
+**`single_match: true`**: Optimization for policies for which there is only one matching Actor possible for a given Subject. For example in `AllowAuthors`, since a `Post` can have only one author, it's not worth a potentially expensive check on other combinations once you've found the winner.
 
 **`cache_by:`** (Symbol or Array of `:actor`, `:subject`, `:direct_object`): Override the cache-key dimensions. By default the key uses every input the policy receives. Pass a subset when the policy ignores some of its inputs — e.g. `AllowAdmins` takes `(actor, subject)` but only examines actor, so `cache_by: :actor` shares one entry across subjects.
 
@@ -217,9 +216,28 @@ All-Powerful VCs bypass all privacy checks and are used in situations where the
 to models. In a production setting, your application should prohibit raw Database access outside of the privacy-aware
 system, so these VCs give you an escape hatch for things like scripts while also keeping an audit trail. 
 
-`omniscient` and `all_powerful` require a reason (symbol) for audit logging.
+`omniscient` and `all_powerful` require a reason, given as a Symbol, for audit logging.
 You could also create lint rules that prevent the casual creation of these viewer contexts.
 
+```ruby
+# Standard viewer (most common)
+users_groups = Group.for_vc(current_vc).where(creator: current_user).all
+
+# Anonymous viewer (logged-out users)
+logged_out_vc = Sequel::Privacy::ViewerContext.anonymous
+posts = Post.for_vc(logged_out_vc).where(published: true).all
+
+# All-powerful ViewerContexts dangerously bypass all read and write checks.
+admin_vc = Sequel::Privacy::ViewerContext.all_powerful(:admin_migration)
+```
+
+### Login, Sessions & `current_user` and `current_vc`
+
+Unless you allow unsafe access to your User (or equivalent) model, you will need 
+a way to load it and create a ViewerContext for them. An Omniscient ViewerContext 
+is useful for this. Be sure to properly set to an Actor VC after you've logged-in 
+or materialized a user from the session. 
+
 ```ruby
 # You can use an omniscient viewer context to load the user from a session
 # or however you store them. Discard this viewer context when you're done with it.
@@ -235,18 +253,9 @@ def current_user
 end
 
 def current_vc
-  current_user&.vc || Sequel::Privacy::ViewerContext.anonymous()
+  current_user&.viewer_context || Sequel::Privacy::ViewerContext.anonymous()
 end
 
-# Standard viewer (most common)
-users_groups = Group.for_vc(current_vc).where(creator: current_user).all
-
-# Anonymous viewer (logged-out users)
-logged_out_vc = Sequel::Privacy::ViewerContext.anonymous
-posts = Post.for_vc(logged_out_vc).where(published: true).all
-
-# All-powerful ViewerContexts dangerously bypass all read and write checks.
-admin_vc = Sequel::Privacy::ViewerContext.all_powerful(:admin_migration)
 ```
 
 ## Mutation Enforcement
@@ -378,11 +387,10 @@ class PrivacyCacheMiddleware
 end
 ```
 
-Or manually:
+Or somewhere manually, like at the top of your Roda or Sinatra app:
 
 ```ruby
-Sequel::Privacy.cache.clear
-Sequel::Privacy.single_matches.clear
+Sequel::Privacy.clear_cache!
 ```
 
 ## Actor Interface

data/lib/sequel/plugins/privacy.rb

@@ -148,17 +148,24 @@ module Sequel
           :@allow_unsafe_access => nil
         )
 
-        # Allows the model to be accessed without a ViewerContext,
-        # useful when you're migrating an existing codebase or adopting gradually.
-        sig { void }
-        def allow_unsafe_access!
+        # Allows the model to be accessed without a ViewerContext, useful when
+        # you're migrating an existing codebase or adopting gradually.
+        # You can prevent this from applying to certain fields or associations by
+        # passing `except:`.
+        sig { params(except: T::Array[Symbol]).void }
+        def allow_unsafe_access!(except: [])
           @allow_unsafe_access = T.let(true, T.nilable(T::Boolean))
+          @unsafe_access_except = T.let(except.map(&:to_sym), T.nilable(T::Array[Symbol]))
           Sequel::Privacy.logger&.warn("#{self} allows unsafe access - migrate to use for_vc()")
         end
 
-        sig { returns(T::Boolean) }
-        def allow_unsafe_access?
-          @allow_unsafe_access == true
+        # Checks if the model or a field/association allows unsafe access.
+        sig { params(name: T.nilable(Symbol)).returns(T::Boolean) }
+        def allow_unsafe_access?(name = nil)
+          return false unless @allow_unsafe_access == true
+          return true if name.nil?
+
+          !(@unsafe_access_except || []).include?(name)
         end
 
         # Per-class thread-local key carrying the current VC during row
@@ -246,7 +253,7 @@ module Sequel
             vc = instance_variable_get(:@viewer_context)
 
             unless vc
-              return original_method.bind(self).() if T.unsafe(self.class).allow_unsafe_access?
+              return original_method.bind(self).() if T.unsafe(self.class).allow_unsafe_access?(field)
 
               Kernel.raise Sequel::Privacy::MissingViewerContext,
                            "#{self.class}##{field} requires a ViewerContext"
@@ -406,6 +413,12 @@ module Sequel
 
           define_method(name) do
             vc = instance_variable_get(:@viewer_context)
+
+            if vc.nil? && !T.unsafe(self.class).allow_unsafe_access?(name)
+              Kernel.raise Sequel::Privacy::MissingViewerContext,
+                           "#{self.class}##{name} requires a ViewerContext"
+            end
+
             assoc_class ||= assoc_reflection.associated_class
 
             obj = if vc && assoc_class.respond_to?(:privacy_vc_key)
@@ -444,6 +457,12 @@ module Sequel
 
           define_method(name) do
             vc = instance_variable_get(:@viewer_context)
+
+            if vc.nil? && !T.unsafe(self.class).allow_unsafe_access?(name)
+              Kernel.raise Sequel::Privacy::MissingViewerContext,
+                           "#{self.class}##{name} requires a ViewerContext"
+            end
+
             assoc_class ||= assoc_reflection.associated_class
 
             objs = if vc && assoc_class.respond_to?(:privacy_vc_key)
@@ -475,8 +494,8 @@ module Sequel
           end
         end
 
-        sig { params(_assoc_name: Symbol, singular_name: Symbol, policies: T::Array[T.untyped]).void }
-        def _wrap_association_add(_assoc_name, singular_name, policies)
+        sig { params(assoc_name: Symbol, singular_name: Symbol, policies: T::Array[T.untyped]).void }
+        def _wrap_association_add(assoc_name, singular_name, policies)
           method_name = :"add_#{singular_name}"
           original = instance_method(method_name)
 
@@ -484,7 +503,7 @@ module Sequel
             vc = instance_variable_get(:@viewer_context)
 
             unless vc
-              return original.bind(self).(obj) if T.unsafe(self.class).allow_unsafe_access?
+              return original.bind(self).(obj) if T.unsafe(self.class).allow_unsafe_access?(assoc_name)
 
               Kernel.raise Sequel::Privacy::MissingViewerContext,
                            "Cannot #{method_name} without a viewer context"
@@ -506,8 +525,8 @@ module Sequel
           end
         end
 
-        sig { params(_assoc_name: Symbol, singular_name: Symbol, policies: T::Array[T.untyped]).void }
-        def _wrap_association_remove(_assoc_name, singular_name, policies)
+        sig { params(assoc_name: Symbol, singular_name: Symbol, policies: T::Array[T.untyped]).void }
+        def _wrap_association_remove(assoc_name, singular_name, policies)
           method_name = :"remove_#{singular_name}"
           original = instance_method(method_name)
 
@@ -515,7 +534,7 @@ module Sequel
             vc = instance_variable_get(:@viewer_context)
 
             unless vc
-              return original.bind(self).(obj) if T.unsafe(self.class).allow_unsafe_access?
+              return original.bind(self).(obj) if T.unsafe(self.class).allow_unsafe_access?(assoc_name)
 
               Kernel.raise Sequel::Privacy::MissingViewerContext,
                            "Cannot #{method_name} without a viewer context"
@@ -537,8 +556,8 @@ module Sequel
           end
         end
 
-        sig { params(_assoc_name: Symbol, plural_name: Symbol, policies: T::Array[T.untyped]).void }
-        def _wrap_association_remove_all(_assoc_name, plural_name, policies)
+        sig { params(assoc_name: Symbol, plural_name: Symbol, policies: T::Array[T.untyped]).void }
+        def _wrap_association_remove_all(assoc_name, plural_name, policies)
           method_name = :"remove_all_#{plural_name}"
           original = instance_method(method_name)
 
@@ -546,7 +565,7 @@ module Sequel
             vc = instance_variable_get(:@viewer_context)
 
             unless vc
-              return original.bind(self).() if T.unsafe(self.class).allow_unsafe_access?
+              return original.bind(self).() if T.unsafe(self.class).allow_unsafe_access?(assoc_name)
 
               Kernel.raise Sequel::Privacy::MissingViewerContext,
                            "Cannot #{method_name} without a viewer context"

data/lib/sequel/privacy/version.rb

@@ -3,6 +3,6 @@
 
 module Sequel
   module Privacy
-    VERSION = '0.5.3'
+    VERSION = '0.5.5'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sequel-privacy
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.5.5
 platform: ruby
 authors:
 - Austin Bales