sequel-privacy 0.6 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6aa19c5eda5b7d5be5a491fd8aa877037c1b79014245d2a400f647fb7aa2d174
-  data.tar.gz: f29f6df4a6418febe64508727df1cb8e2e611b31ea02ae3b8dda9516cdc5fd90
+  metadata.gz: c7ef079bb3498aa1006aa327a138bcb1735b78ae02a65b11d2ee4976d9871978
+  data.tar.gz: 95000199db0cbb08908c1a261152c641b71ceb7898875a9f732936662df9334e
 SHA512:
-  metadata.gz: 9a466793f9a3ddb2c3938f6434a56a7262569820ae3a9c8fb752c0f7d163f3b8bdfad3d09f9750fe4771d28fbb8171a780e9569963429dda2edc5e0f2b2ac68a
-  data.tar.gz: bf7059897a808ff8466b2054f632a682bbf5e8201995760999259baaac3753d7116f6fe1159ec868ca1dfc40d5166697982a47f4b8dc494615c0337fdad14f2f
+  metadata.gz: 6ea2e6410976a3e325264faa698a2faaf323c1aafdfe9eb3444c8cc18f51c887155227a1fe68ec119408d9679b1c4a39cc70e69611db4e6ed94edf9b93857ef2
+  data.tar.gz: 0271f5b12a6d376e04b5feae0eb9ee604da1258871092578878571c877b86b9ef388a60441962b31b36588c9c3e4fc9642c9b71cd0f90a8890030903e2a1bb21

data/CHANGELOG.md

@@ -1,13 +1,14 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
-
-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]
 
-## [0.1.0] - 2024-01-24
+## [0.7.0] – 2026-08-26
+- Removed `#for_vc` on `Sequel::Model` instances. Instead, call `#reset_viewer_context(vc, reason)`.
+- Removed `#viewer_context=` from `Sequel::Model` instances.
+- Added `#use(&block)` to Omniscient and AllPowerful viewer contexts. The block receives the viewer context and the reason it was created.
+
+## [0.1.0]
 
 ### Added
 - Initial release

data/README.md

@@ -260,31 +260,35 @@ 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. 
+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.
 
 ```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.
-def current_user 
+def current_user
   return @current_user if @current_user
-  login_vc = Sequel::Privacy::ViewerContext.omniscient(:login)
-  user = User.for_vc(login_vc)[session_user_id]
-  return nil unless user
 
-  # Attach an ActorVC to the loaded user so that future calls to its fields and 
-  # associations respect privacy .
-  @current_user ||= user.for_vc(Sequel::Privacy::ViewerContext.for_actor(user))
+  @current_user = Sequel::Privacy::ViewerContext.omniscient(:login).use do |vc, reason|
+    user = User.for_vc(vc)[session_user_id]
+    next nil unless user
+
+    # Give the row its own ActorVC, so its fields and associations respect
+    # privacy from here on — and so it can be written to. An OmniscientVC reads
+    # anything but refuses to mutate.
+    user.reset_viewer_context(Sequel::Privacy::ViewerContext.for_actor(user), reason)
+  end
 end
 
 def current_vc
   current_user&.viewer_context || Sequel::Privacy::ViewerContext.anonymous()
 end
-
 ```
 
+*Warning:* Skipping the reset leaves you holding an object that cannot be
+saved, but any association or field reads on it will be allowed. So you should always
+discard the OmniVC / APVCs used for things like this and call `reset_viewer_context` 
+with a more appropriate one as soon as you can.
+
 ## Mutation Enforcement
 
 When a viewer context is attached, mutations are automatically checked:

data/lib/sequel/plugins/privacy.rb

@@ -371,13 +371,13 @@ module Sequel
 
         sig { params(original: T.untyped).returns(Proc) }
         def _privacy_eager_block(original)
-          wrapped = proc do |ds|
-            ds = original.call(ds) if original
+          wrapped = proc do |dataset|
+            dataset = original.call(dataset) if original
             vc = Thread.current[DatasetMethods::EAGER_VC_KEY]
-            if vc && T.unsafe(ds).model.respond_to?(:privacy_vc_key)
-              T.unsafe(ds).for_vc(vc)
+            if vc && T.unsafe(dataset).model.respond_to?(:privacy_vc_key)
+              T.unsafe(dataset).for_vc(vc).clone(privacy_eager_load: true)
             else
-              ds
+              dataset
             end
           end
           wrapped
@@ -385,6 +385,16 @@ module Sequel
 
         private
 
+        sig { returns(T::Module[T.anything]) }
+        def privacy_association_wrapper
+          wrapper = @privacy_association_wrapper ||= T.let(
+            Module.new,
+            T.nilable(T::Module[T.anything])
+          )
+          prepend(wrapper) unless ancestors.include?(wrapper)
+          wrapper
+        end
+
         sig { params(type: Symbol, name: Symbol, inject_eager_block: T::Boolean).void }
         def _setup_privacy_association_readers(type, name, inject_eager_block)
           reflection = association_reflection(name)
@@ -419,12 +429,11 @@ module Sequel
           dataset_method = :"#{name}_dataset"
           return unless method_defined?(dataset_method)
 
-          original = instance_method(dataset_method)
           assoc_reflection = association_reflection(name)
           assoc_class = T.let(nil, T.nilable(T.class_of(Sequel::Model)))
 
-          define_method(dataset_method) do |*args|
-            ds = original.bind(self).(*args)
+          privacy_association_wrapper.define_method(dataset_method) do |*args, &block|
+            ds = super(*args, &block)
             vc = instance_variable_get(:@viewer_context)
             return ds unless vc
 
@@ -439,12 +448,11 @@ module Sequel
 
         sig { params(name: Symbol).void }
         def _override_singular_association(name)
-          original = instance_method(name)
           assoc_reflection = association_reflection(name)
           # Resolve lazily to handle forward references between models.
           assoc_class = T.let(nil, T.nilable(T.class_of(Sequel::Model)))
 
-          define_method(name) do
+          privacy_association_wrapper.define_method(name) do |*args, &block|
             vc = instance_variable_get(:@viewer_context)
 
             if vc.nil? && !T.unsafe(self.class).allow_unsafe_access?(name)
@@ -459,12 +467,12 @@ module Sequel
                     old_vc = Thread.current[vc_key]
                     Thread.current[vc_key] = vc
                     begin
-                      original.bind(self).()
+                      super(*args, &block)
                     ensure
                       Thread.current[vc_key] = old_vc
                     end
                   else
-                    original.bind(self).()
+                    super(*args, &block)
                   end
 
             return nil unless obj
@@ -484,11 +492,10 @@ module Sequel
 
         sig { params(name: Symbol).void }
         def _override_plural_association(name)
-          original = instance_method(name)
           assoc_reflection = association_reflection(name)
           assoc_class = T.let(nil, T.nilable(T.class_of(Sequel::Model)))
 
-          define_method(name) do
+          privacy_association_wrapper.define_method(name) do |*args, &block|
             vc = instance_variable_get(:@viewer_context)
 
             if vc.nil? && !T.unsafe(self.class).allow_unsafe_access?(name)
@@ -503,12 +510,12 @@ module Sequel
                      old_vc = Thread.current[vc_key]
                      Thread.current[vc_key] = vc
                      begin
-                       original.bind(self).()
+                       super(*args, &block)
                      ensure
                        Thread.current[vc_key] = old_vc
                      end
                    else
-                     original.bind(self).()
+                     super(*args, &block)
                    end
 
             return objs unless vc
@@ -530,13 +537,13 @@ module Sequel
         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)
 
-          define_method(method_name) do |obj|
+          privacy_association_wrapper.define_method(method_name) do |*args, &block|
+            obj = args.first
             vc = instance_variable_get(:@viewer_context)
 
             unless vc
-              return original.bind(self).(obj) if T.unsafe(self.class).allow_unsafe_access?(assoc_name)
+              return super(*args, &block) if T.unsafe(self.class).allow_unsafe_access?(assoc_name)
 
               Kernel.raise Sequel::Privacy::MissingViewerContext,
                            "Cannot #{method_name} without a viewer context"
@@ -554,20 +561,20 @@ module Sequel
                            "Cannot #{method_name} on #{self.class}"
             end
 
-            original.bind(self).(obj)
+            super(*args, &block)
           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)
           method_name = :"remove_#{singular_name}"
-          original = instance_method(method_name)
 
-          define_method(method_name) do |obj|
+          privacy_association_wrapper.define_method(method_name) do |*args, &block|
+            obj = args.first
             vc = instance_variable_get(:@viewer_context)
 
             unless vc
-              return original.bind(self).(obj) if T.unsafe(self.class).allow_unsafe_access?(assoc_name)
+              return super(*args, &block) if T.unsafe(self.class).allow_unsafe_access?(assoc_name)
 
               Kernel.raise Sequel::Privacy::MissingViewerContext,
                            "Cannot #{method_name} without a viewer context"
@@ -585,20 +592,19 @@ module Sequel
                            "Cannot #{method_name} on #{self.class}"
             end
 
-            original.bind(self).(obj)
+            super(*args, &block)
           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)
           method_name = :"remove_all_#{plural_name}"
-          original = instance_method(method_name)
 
-          define_method(method_name) do
+          privacy_association_wrapper.define_method(method_name) do |*args, &block|
             vc = instance_variable_get(:@viewer_context)
 
             unless vc
-              return original.bind(self).() if T.unsafe(self.class).allow_unsafe_access?(assoc_name)
+              return super(*args, &block) if T.unsafe(self.class).allow_unsafe_access?(assoc_name)
 
               Kernel.raise Sequel::Privacy::MissingViewerContext,
                            "Cannot #{method_name} without a viewer context"
@@ -616,7 +622,7 @@ module Sequel
                            "Cannot #{method_name} on #{self.class}"
             end
 
-            original.bind(self).()
+            super(*args, &block)
           end
         end
       end
@@ -633,13 +639,12 @@ module Sequel
           @viewer_context = T.let(@viewer_context, T.nilable(Sequel::Privacy::ViewerContext))
         end
 
-        sig { params(vc: T.nilable(Sequel::Privacy::ViewerContext)).returns(T.nilable(Sequel::Privacy::ViewerContext)) }
-        def viewer_context=(vc)
-          @viewer_context = T.let(vc, T.nilable(Sequel::Privacy::ViewerContext))
-        end
 
-        sig { params(vc: Sequel::Privacy::ViewerContext).returns(T.self_type) }
-        def for_vc(vc)
+        sig { params(vc: Sequel::Privacy::ViewerContext, reason: Symbol).returns(T.self_type) }
+        def reset_viewer_context(vc, reason)
+          Sequel::Privacy.logger&.debug do
+            "Resetting viewer context on #{self.class}[#{pk}] to #{vc.class.name.to_s.split('::').last} (#{reason})"
+          end
           @viewer_context = T.let(vc, T.nilable(Sequel::Privacy::ViewerContext))
           self
         end
@@ -747,8 +752,9 @@ module Sequel
         # can retreive. Materializes the model, and then checks the view
         # policy. If the model is being materialized within the context of
         # checking a policy this is bypassed, because policies often need to
-        # check data that a VC might not have permission to see. The check is also
-        # bypassed for eager loads, and checked on the association.
+        # check data that a VC might not have permission to see. For eager
+        # association loads, enforcement is deferred until association access so
+        # Sequel can finish attachment and populate reciprocal caches first.
         sig { returns(T.untyped) }
         def row_proc
           vc = opts[:viewer_context]
@@ -768,8 +774,8 @@ module Sequel
             next nil if instance.nil?
 
             instance.instance_variable_set(:@viewer_context, vc)
+            next instance if opts[:privacy_eager_load]
             next instance if Sequel::Privacy::Enforcer.in_policy_eval?
-            next instance if Thread.current[EAGER_VC_KEY]
 
             if T.cast(instance, InstanceMethods).allow?(vc, :view)
               instance

data/lib/sequel/privacy/enforcer.rb

@@ -38,6 +38,8 @@ module Sequel
         ).returns(T::Boolean)
       end
       def self.enforce(policies, subject, viewer_context, direct_object = nil)
+        viewer_context.assert_usable!
+
         saved = Thread.current[EVAL_KEY]
         Thread.current[EVAL_KEY] = true
 

data/lib/sequel/privacy/errors.rb

@@ -15,6 +15,9 @@ module Sequel
     # Raised when an invalid viewer context is used
     class InvalidViewerContextError < StandardError; end
 
+    # Raised if #invalidates was called on this VC.
+    class InvalidatedViewerContext < InvalidViewerContextError; end
+
     class MissingViewerContext < StandardError; end
 
     # Raised when attempting to modify privacy settings after finalization

data/lib/sequel/privacy/version.rb

@@ -3,6 +3,6 @@
 
 module Sequel
   module Privacy
-    VERSION = '0.6'
+    VERSION = '0.7.0'
   end
 end

data/lib/sequel/privacy/viewer_context.rb

@@ -41,6 +41,54 @@ module Sequel
       def self.anonymous
         AnonymousVC.new
       end
+
+      sig { returns(T::Boolean) }
+      def invalidated?
+        @invalidated = T.let(@invalidated, T.nilable(T::Boolean))
+        @invalidated || false
+      end
+
+      sig { void }
+      def assert_usable!
+        return unless invalidated?
+
+        Kernel.raise InvalidatedViewerContext,
+                     "#{self.class.name.to_s.split('::').last} was invalidated and cannot be used again"
+      end
+    end
+
+    # Made available on OmniscientVC and AllPowerfulVCs. Transient contexts are
+    # invalidated when the use block exists. To help you keep these around for
+    # as short a time as possible.
+    module TransientViewerContext
+      extend T::Sig
+      extend T::Helpers
+
+      abstract!
+      requires_ancestor { ViewerContext }
+
+      sig { abstract.returns(Symbol) }
+      def reason; end
+
+      sig do
+        type_parameters(:U)
+          .params(block: T.proc.params(vc: T.untyped, reason: Symbol).returns(T.type_parameter(:U)))
+          .returns(T.type_parameter(:U))
+      end
+      def use(&block)
+        block.call(self, reason)
+      ensure
+        invalidate!
+      end
+
+      sig { returns(T.self_type) }
+      def invalidate!
+        unless invalidated?
+          Sequel::Privacy.logger&.debug("Invalidating viewer context: #{reason}")
+          @invalidated = T.let(true, T.nilable(T::Boolean))
+        end
+        self
+      end
     end
 
     # Standard viewer context with an actor (user/member)
@@ -65,6 +113,7 @@ module Sequel
     # Requires a reason for audit logging.
     class AllPowerfulVC < ViewerContext
       extend T::Sig
+      include TransientViewerContext
 
       sig { params(reason: Symbol).void }
       def initialize(reason)
@@ -72,7 +121,7 @@ module Sequel
         super()
       end
 
-      sig { returns(Symbol) }
+      sig { override.returns(Symbol) }
       attr_reader :reason
     end
 
@@ -80,6 +129,7 @@ module Sequel
     # Used for system operations like authentication lookups.
     class OmniscientVC < ViewerContext
       extend T::Sig
+      include TransientViewerContext
 
       sig { params(reason: Symbol).void }
       def initialize(reason)
@@ -87,7 +137,7 @@ module Sequel
         super()
       end
 
-      sig { returns(Symbol) }
+      sig { override.returns(Symbol) }
       attr_reader :reason
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sequel-privacy
 version: !ruby/object:Gem::Version
-  version: '0.6'
+  version: 0.7.0
 platform: ruby
 authors:
 - Austin Bales
@@ -93,6 +93,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.17'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A Sequel plugin that provides declarative privacy policies and automatic
   enforcement at field access and query boundaries.
 email:
@@ -138,7 +152,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.15
+rubygems_version: 4.0.14
 specification_version: 4
 summary: Privacy enforcement plugin for Sequel models
 test_files: []