sequel-privacy 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 627da75fe2db0e41382bd4b6a6e44cf85bb01a3a52aef9c1c16df85b0b4af5d8
-  data.tar.gz: e0cfd6b79e35d81a51d6897fa37f9130e5fb567f3422c0014500be6bb0d95183
+  metadata.gz: c7ef079bb3498aa1006aa327a138bcb1735b78ae02a65b11d2ee4976d9871978
+  data.tar.gz: 95000199db0cbb08908c1a261152c641b71ceb7898875a9f732936662df9334e
 SHA512:
-  metadata.gz: c1450ee72abf6ef060a7d2f8d541f3d418724cca9650370746e996427d4da438e93fa96410b47b6606ab4a41542d014b46dbf97a08e3e4623cf120b419736372
-  data.tar.gz: 5ccadc4dfb1b84fb7ab9d3beefb2b396b2b1302239c0b63fc97a2c34a6fb9b5a025857542814167e007326a17e08e1697d56731cdff690a5c9d72d850cb96529
+  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

@@ -639,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

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.1'
+    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.1
+  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: []