sequel-privacy 0.5.1 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af7fc02c1fb57d47ba358babdebb3289c2d8eb6ec43d2fce25a2c3477a3f2ccc
-  data.tar.gz: a18b09c73b5b03540d2a74f985d32c99b6b2a090a714346f2c87ef5a2997252c
+  metadata.gz: 2f2538fcf5aee16c7b624701e81d936df211b20fa007cf9fa1fffc893bda0105
+  data.tar.gz: e1df8a2b58c2e6851447e2874c837a865641be73ed0adc25c255bcb9076d4087
 SHA512:
-  metadata.gz: 9f46a3f0f253061be75dcd2fb80cf797c1be229d5fd83b1c9f1c86860621dae4536ea60b06df4e38d2d6b1e66f0e90533f0d3a75dddc48be388898ac1d8517d4
-  data.tar.gz: f4aee413ab143a08366b223e2c34d62165c69f1e63871eee400d6f82af3c096266e0646f3b4d3d4649a761c913e2c07cef8f852586f0c535d0af3daf1d02f9a6
+  metadata.gz: 68996d09fde85691254e51d6edb40f4a32007c07a232b768a705d29b7b4ea37ebe95a2ac092c18f201a7516b53108d4a8ff8356a0f860c288a18903648b5c1b6
+  data.tar.gz: d1b9364e64145dbe2993c18bb8db458826b2480e9e827f589ed6cecefdbb1e2c82e0c2fdd72a3542946fb4bea70e2d58c37f81889067b3b5e7c5ce7912032477

data/README.md

@@ -221,56 +221,34 @@ system, so these VCs give you an escape hatch for things like scripts while also
 You could also create lint rules that prevent the casual creation of these viewer contexts.
 
 ```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 
+  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))
+end
+
+def current_vc
+  current_user&.vc || Sequel::Privacy::ViewerContext.anonymous()
+end
+
 # Standard viewer (most common)
-current_vc = Sequel::Privacy::ViewerContext.for_actor(current_user)
 users_groups = Group.for_vc(current_vc).where(creator: current_user).all
 
-# API-specific (can be distinguished in policies)
-vc = Sequel::Privacy::ViewerContext.for_api_actor(current_user)
-
 # Anonymous viewer (logged-out users)
 logged_out_vc = Sequel::Privacy::ViewerContext.anonymous
 posts = Post.for_vc(logged_out_vc).where(published: true).all
 
-# Omniscient VCs can read any object in the system, but are incapable of writes.
-# Dispose of these ViewerContexts quickly. 
-current_user = Sequel::Privacy::ViewerContext.omniscient(:login).then {|vc| User.for_vc(vc)[authenticated_user_id] }
-current_vc = Sequel::Privacy::ViewerContext.for_actor(current_user)
-
 # All-powerful ViewerContexts dangerously bypass all read and write checks.
 admin_vc = Sequel::Privacy::ViewerContext.all_powerful(:admin_migration)
 ```
 
-### A Note Login & Authenticated Users
-
-If your User or equivalent model is privacy-aware *and* is protected by 
-policies that would complicating fetching (or login), then you will have
-trouble creating a `current_user` for an `ActorVC`.
-
-In both cases you can use an `OmniscientVC` to make your initial User query.
-
-```ruby
-before do
-  if session[:user_id]
-    current_user = Sequel::Privacy::ViewerContext.omniscient(:session).then {|vc| User.for_vc(vc)[session[:user_id]] }
-    current_vc = Sequel::Privacy::ViewerContext.for_actor(current_user)
-  else
-    current_user = nil
-    current_vc = Sequel::Privacy::ViewerContext.anonymous
-  end
-end
-
-post '/auth/password' do
-  user = Sequel::Privacy::ViewerContext.omniscient(:login).then {|vc| User.for_vc(vc).first(email: params[:email]) }  
-  
-  pass unless user
-  pass unless user.password == params[:password]
-  
-  session[:user_id] = user.id
-  redirect '/'
-end
-```
-
 ## Mutation Enforcement
 
 When a viewer context is attached, mutations are automatically checked:

data/lib/sequel/plugins/privacy.rb

@@ -36,7 +36,6 @@ module Sequel
     module Privacy
       extend T::Sig
 
-      # Called once when plugin first loads on a model
       sig { params(model: T.class_of(Sequel::Model), _opts: T::Hash[Symbol, T.untyped]).void }
       def self.apply(model, _opts = {})
         model.instance_variable_set(:@privacy_policies, {})
@@ -46,13 +45,9 @@ module Sequel
         model.instance_variable_set(:@allow_unsafe_access, false)
       end
 
-      # Called every time plugin loads (for per-model configuration)
       sig { params(model: T.class_of(Sequel::Model), opts: T::Hash[Symbol, T.untyped]).void }
-      def self.configure(model, opts = {})
-        # Currently no per-model configuration needed
-      end
+      def self.configure(model, opts = {}); end
 
-      # DSL class for defining association-level privacy policies
       class AssociationPrivacyDSL
         extend T::Sig
 
@@ -67,7 +62,6 @@ module Sequel
           @pending_policies = T.let({}, T::Hash[Symbol, T::Array[T.untyped]])
         end
 
-        # Define policies for association actions (:add, :remove, :remove_all)
         sig { params(action: Symbol, policies: T.untyped).void }
         def can(action, *policies)
           unless %i[add remove remove_all].include?(action)
@@ -80,17 +74,15 @@ module Sequel
           T.must(@pending_policies[action]).concat(resolved)
         end
 
-        # Called after the association block is evaluated to register all policies at once
         sig { void }
         def finalize_association!
           @pending_policies.each do |action, policies|
-            @model_class.register_association_policies(@assoc_name, action, policies, defer_setup: true)
+            @model_class.register_association_policies(@assoc_name, action, policies)
           end
           @model_class.setup_association_privacy(@assoc_name)
         end
       end
 
-      # DSL class for defining privacy policies in a block
       class PrivacyDSL
         extend T::Sig
 
@@ -99,14 +91,12 @@ module Sequel
           @model_class = model_class
         end
 
-        # Define policies for an action
         sig { params(action: Symbol, policies: T.untyped).void }
         def can(action, *policies)
           resolved = resolve_policies(policies)
           @model_class.register_policies(action, resolved)
         end
 
-        # Define a protected field with its policies
         sig { params(name: Symbol, policies: T.untyped).void }
         def field(name, *policies)
           resolved = resolve_policies(policies)
@@ -115,14 +105,6 @@ module Sequel
           @model_class.register_protected_field(name, policy_name)
         end
 
-        # Define policies for an association
-        #
-        # Example:
-        #   association :members do
-        #     can :add, AllowGroupAdmin, AllowSelfJoin
-        #     can :remove, AllowGroupAdmin, AllowSelfRemove
-        #     can :remove_all, AllowGroupAdmin
-        #   end
         sig { params(name: Symbol, block: T.proc.bind(AssociationPrivacyDSL).void).void }
         def association(name, &block)
           resolver = ->(policies) { resolve_policies(policies) }
@@ -131,7 +113,6 @@ module Sequel
           dsl.finalize_association!
         end
 
-        # Finalize privacy settings (no more changes allowed)
         sig { void }
         def finalize!
           @model_class.finalize_privacy!
@@ -158,7 +139,6 @@ module Sequel
 
         requires_ancestor { T.class_of(Sequel::Model) }
 
-        # Register inherited instance variables for proper subclass handling
         Sequel::Plugins.inherited_instance_variables(
           self,
           :@privacy_policies => :dup,
@@ -168,12 +148,8 @@ module Sequel
           :@allow_unsafe_access => nil
         )
 
-        # ─────────────────────────────────────────────────────────────────────
-        # Strict Mode Enforcement
-        # ─────────────────────────────────────────────────────────────────────
-
-        # Allow this model to be accessed without a ViewerContext.
-        # Use during migration to gradually enable strict mode.
+        # 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!
           @allow_unsafe_access = T.let(true, T.nilable(T::Boolean))
@@ -185,20 +161,15 @@ module Sequel
           @allow_unsafe_access == true
         end
 
-        # Thread-local key for storing the current ViewerContext during row processing
+        # Per-class thread-local key carrying the current VC during row
+        # materialization.
         sig { returns(Symbol) }
         def privacy_vc_key
           :"#{self}_privacy_vc"
         end
 
-        # Override Sequel's call method to act as a strict-mode gate.
-        # Every database-loaded record flows through here (Model[id],
-        # Model.first, Model.all, associations, ...). This checks that a
-        # VC is in scope (or that the class opted out via
-        # allow_unsafe_access!) and defers VC attachment and :view
-        # filtering to DatasetMethods#row_proc — those are per-row
-        # concerns and have context-dependent bypasses (policy
-        # evaluation, eager-load attachment) that don't belong here.
+        # The primary integration point; every Sequel::Model materialization
+        # flows through here.
         sig { params(values: T.untyped).returns(T.nilable(Sequel::Model)) }
         def call(values)
           vc = Thread.current[privacy_vc_key]
@@ -211,10 +182,6 @@ module Sequel
           super
         end
 
-        # ─────────────────────────────────────────────────────────────────────
-        # Policy Definition DSL
-        # ─────────────────────────────────────────────────────────────────────
-
         sig { returns(T::Hash[Symbol, T::Array[T.untyped]]) }
         def privacy_policies
           @privacy_policies ||= T.let({}, T.nilable(T::Hash[Symbol, T::Array[T.untyped]]))
@@ -225,7 +192,6 @@ module Sequel
           @privacy_fields ||= T.let({}, T.nilable(T::Hash[Symbol, Symbol]))
         end
 
-        # Returns association policies: { assoc_name => { action => [policies] } }
         sig { returns(T::Hash[Symbol, T::Hash[Symbol, T::Array[T.untyped]]]) }
         def privacy_association_policies
           @privacy_association_policies ||= T.let({}, T.nilable(T::Hash[Symbol, T::Hash[Symbol, T::Array[T.untyped]]]))
@@ -236,11 +202,9 @@ module Sequel
           @privacy_finalized == true
         end
 
-        # DSL entry point for defining privacy policies
-        #
-        # @yield Block evaluated in context of PrivacyDSL
+        # Entry point for the privacy DSL. The block is evaluated in the
+        # context of a `PrivacyDSL` instance:
         #
-        # Example:
         #   privacy do
         #     can :view, P::AllowMembers
         #     can :edit, P::AllowSelf, P::AllowAdmins
@@ -256,7 +220,6 @@ module Sequel
           dsl.instance_eval(&block)
         end
 
-        # Register policies for an action (called by PrivacyDSL)
         sig { params(action: Symbol, policies: T::Array[T.untyped]).void }
         def register_policies(action, policies)
           if privacy_finalized?
@@ -267,7 +230,6 @@ module Sequel
           T.must(privacy_policies[action]).concat(policies)
         end
 
-        # Register a protected field (called by PrivacyDSL)
         sig { params(field: Symbol, policy_name: Symbol).void }
         def register_protected_field(field, policy_name)
           if privacy_finalized?
@@ -276,13 +238,9 @@ module Sequel
 
           privacy_fields[field] = policy_name
 
-          # Store original method
           original_method = instance_method(field)
 
-          # Override the field getter
           define_method(field) do
-            # During nested policy evaluation, return raw value without
-            # checking the field's view policy.
             return original_method.bind(self).() if Sequel::Privacy::Enforcer.in_policy_eval?
 
             vc = instance_variable_get(:@viewer_context)
@@ -301,23 +259,20 @@ module Sequel
           end
         end
 
-        # Register association policies (called by AssociationPrivacyDSL)
-        # @param defer_setup [Boolean] If true, don't set up wrappers yet (caller will call setup_association_privacy)
-        sig { params(assoc_name: Symbol, action: Symbol, policies: T::Array[T.untyped], defer_setup: T::Boolean).void }
-        def register_association_policies(assoc_name, action, policies, defer_setup: false)
+        # The caller is responsible for invoking `setup_association_privacy`
+        # once all actions have been registered.
+        sig { params(assoc_name: Symbol, action: Symbol, policies: T::Array[T.untyped]).void }
+        def register_association_policies(assoc_name, action, policies)
           Kernel.raise "Privacy policies have been finalized for #{self}" if privacy_finalized?
 
           privacy_association_policies[assoc_name] ||= {}
           assoc_hash = T.must(privacy_association_policies[assoc_name])
           assoc_hash[action] ||= []
           T.must(assoc_hash[action]).concat(policies)
-
-          # Set up the association method overrides if the association exists (unless deferred)
-          setup_association_privacy(assoc_name) if !defer_setup && association_reflection(assoc_name)
         end
 
-        # Set up privacy-wrapped add_*/remove_*/remove_all_* methods for an association
-        # This is called after all policies for an association have been registered
+        # Wraps add_*/remove_*/remove_all_* methods on an association
+        # with privacy checks. Idempotent.
         sig { params(assoc_name: Symbol).void }
         def setup_association_privacy(assoc_name)
           assoc_policies = privacy_association_policies[assoc_name]
@@ -326,47 +281,40 @@ module Sequel
           reflection = association_reflection(assoc_name)
           return unless reflection
 
-          # Track which associations have been wrapped to avoid double-wrapping
           @_wrapped_associations ||= T.let({}, T.nilable(T::Hash[Symbol, T::Boolean]))
           return if @_wrapped_associations[assoc_name]
 
           @_wrapped_associations[assoc_name] = true
 
-          # Determine the singular name for method naming
-          # For many_to_many :members, methods are add_member, remove_member
-          # For one_to_many :memberships, methods are add_membership, remove_membership
+          # Sequel derives mutator names by stripping a trailing 's' from
+          # the association name: many_to_many :members → add_member,
+          # one_to_many :memberships → add_membership.
+          #
+          # TODO: I'm not sure if this will break sometimes.
           singular_name = reflection[:name].to_s.chomp('s').to_sym
 
-          # Wrap add_* method if :add policy exists
           add_policies = assoc_policies[:add]
           if add_policies && method_defined?(:"add_#{singular_name}")
             _wrap_association_add(assoc_name, singular_name, add_policies)
           end
 
-          # Wrap remove_* method if :remove policy exists
           remove_policies = assoc_policies[:remove]
           if remove_policies && method_defined?(:"remove_#{singular_name}")
             _wrap_association_remove(assoc_name, singular_name, remove_policies)
           end
 
-          # Wrap remove_all_* method if :remove_all policy exists
           remove_all_policies = assoc_policies[:remove_all]
           return unless remove_all_policies && method_defined?(:"remove_all_#{reflection[:name]}")
 
           _wrap_association_remove_all(assoc_name, reflection[:name], remove_all_policies)
         end
 
-        # Finalize privacy settings (no more changes allowed)
-        # TODO: Explore automatic finalization on first query
+        # TODO: explore automatic finalization on first query.
         sig { void }
         def finalize_privacy!
           @privacy_finalized = T.let(true, T.nilable(T::Boolean))
         end
 
-        # ─────────────────────────────────────────────────────────────────────
-        # Deprecated Methods (for backwards compatibility)
-        # ─────────────────────────────────────────────────────────────────────
-
         # @deprecated Use `privacy do; can :action, ...; end` instead
         sig { params(action: Symbol, policy_chain: T.untyped).void }
         def policies(action, *policy_chain)
@@ -379,7 +327,6 @@ module Sequel
         def protect_field(field, policy: nil)
           Kernel.warn "DEPRECATED: #{self}.protect_field is deprecated. Use `privacy do; field :#{field}, ...; end` instead"
           policy_name = policy || :"view_#{field}"
-          # Need to also register the policy if not already defined
           register_protected_field(field, policy_name)
         end
 
@@ -389,19 +336,11 @@ module Sequel
           dataset.for_vc(vc)
         end
 
-        # ─────────────────────────────────────────────────────────────────────
-        # Association Privacy (hooks into association creation)
-        # ─────────────────────────────────────────────────────────────────────
-
-        # Override Sequel's associate method to wrap associations with privacy checks
         sig { params(type: Symbol, name: Symbol, opts: T.untyped, block: T.untyped).returns(T.untyped) }
         def associate(type, name, opts = {}, &block)
           opts = _inject_privacy_eager_block(opts)
-
-          # Call original to create the association
           result = super
 
-          # Wrap the association method with privacy checks
           case type
           when :many_to_one, :one_to_one
             _override_singular_association(name)
@@ -409,18 +348,15 @@ module Sequel
           when :one_to_many, :many_to_many
             _override_plural_association(name)
             _override_association_dataset(name)
-            # Check if there are already privacy policies defined for this association
             setup_association_privacy(name) if privacy_association_policies[name]
           end
 
           result
         end
 
-        # Wrap the association's eager-load dataset with for_vc() so the
-        # child rows are materialized with the current viewer context.
-        # The VC is propagated via a thread-local set by DatasetMethods#all
-        # so that it's only applied during eager loading, not during the
-        # lazy association reader path (which has its own handling).
+        # Inject an :eager_block that wraps the eager-load dataset with
+        # `for_vc` when a VC is propagated via EAGER_VC_KEY (see
+        # DatasetMethods#post_load). Preserves any user-supplied block.
         sig { params(opts: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
         def _inject_privacy_eager_block(opts)
           original = opts[:eager_block]
@@ -465,15 +401,13 @@ module Sequel
         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
             vc = instance_variable_get(:@viewer_context)
-
-            # Determine associated class (lazily, to handle forward references)
             assoc_class ||= assoc_reflection.associated_class
 
-            # Load association with VC context set if available
             obj = if vc && assoc_class.respond_to?(:privacy_vc_key)
                     vc_key = assoc_class.privacy_vc_key
                     old_vc = Thread.current[vc_key]
@@ -510,11 +444,8 @@ module Sequel
 
           define_method(name) do
             vc = instance_variable_get(:@viewer_context)
-
-            # Determine associated class (lazily, to handle forward references)
             assoc_class ||= assoc_reflection.associated_class
 
-            # Load association with VC context set if available
             objs = if vc && assoc_class.respond_to?(:privacy_vc_key)
                      vc_key = assoc_class.privacy_vc_key
                      old_vc = Thread.current[vc_key]
@@ -564,7 +495,6 @@ module Sequel
                            "Cannot #{method_name} with OmniscientVC"
             end
 
-            # Check policy with 3-arity: (subject=self, actor, direct_object=obj)
             allowed = Sequel::Privacy::Enforcer.enforce(policies, self, vc, obj)
 
             unless allowed
@@ -596,7 +526,6 @@ module Sequel
                            "Cannot #{method_name} with OmniscientVC"
             end
 
-            # Check policy with 3-arity: (subject=self, actor, direct_object=obj)
             allowed = Sequel::Privacy::Enforcer.enforce(policies, self, vc, obj)
 
             unless allowed
@@ -628,7 +557,6 @@ module Sequel
                            "Cannot #{method_name} with OmniscientVC"
             end
 
-            # Check policy with 2-arity: (subject=self, actor) - no direct object for remove_all
             allowed = Sequel::Privacy::Enforcer.enforce(policies, self, vc)
 
             unless allowed
@@ -658,19 +586,12 @@ module Sequel
           @viewer_context = T.let(vc, T.nilable(Sequel::Privacy::ViewerContext))
         end
 
-        # Attach a viewer context to this model instance
         sig { params(vc: Sequel::Privacy::ViewerContext).returns(T.self_type) }
         def for_vc(vc)
           @viewer_context = T.let(vc, T.nilable(Sequel::Privacy::ViewerContext))
           self
         end
 
-        # Check if the viewer is allowed to perform an action.
-        #
-        # @param vc [ViewerContext] The viewer context
-        # @param action [Symbol] The action to check (:view, :edit, :create, etc.)
-        # @param direct_object [Sequel::Model, nil] Optional additional context
-        # @return [Boolean]
         sig do
           params(
             vc: Sequel::Privacy::ViewerContext,
@@ -688,7 +609,6 @@ module Sequel
           Sequel::Privacy::Enforcer.enforce(policies, self, vc, direct_object)
         end
 
-        # Override save to check privacy policies
         sig { params(opts: T.untyped).returns(T.nilable(T.self_type)) }
         def save(*opts)
           vc = viewer_context
@@ -716,7 +636,6 @@ module Sequel
           super
         end
 
-        # Override update to check privacy policies
         sig { params(hash: T::Hash[Symbol, T.untyped]).returns(T.self_type) }
         def update(hash)
           vc = viewer_context
@@ -739,15 +658,13 @@ module Sequel
 
         private
 
-        # Typed view of the model class for accessing methods mixed in by the
-        # privacy plugin. The cast is sound because every class that includes
-        # InstanceMethods also extends ClassMethods (via mixes_in_class_methods).
+        # Every class that includes InstanceMethods also extends ClassMethods
+        # via `mixes_in_class_methods`, so this should always work.
         sig { returns(ClassMethods) }
         def _privacy_class
           T.cast(self.class, ClassMethods)
         end
 
-        # Override delete to block OmniscientVC
         sig { returns(T.self_type) }
         def delete
           if viewer_context.is_a?(Sequel::Privacy::OmniscientVC)
@@ -769,23 +686,17 @@ module Sequel
         # datasets via the :eager_block injected in ClassMethods#associate.
         EAGER_VC_KEY = :sequel_privacy_eager_vc
 
-        # Attach viewer context to dataset for privacy enforcement on materialization
         sig { params(vc: Sequel::Privacy::ViewerContext).returns(Sequel::Dataset) }
         def for_vc(vc)
           clone(viewer_context: vc)
         end
 
-        # Override row_proc to wrap Model.call with the full per-row
-        # privacy pipeline: set the thread-local VC so Model.call's
-        # strict-mode gate passes, attach the VC to the instance, and
-        # apply the :view filter — with two bypasses for materialization
-        # contexts where filtering would be wrong or break callers:
-        #   - in_policy_eval?: policies that traverse protected data
-        #     need raw rows so their checks (e.g. membership) aren't
-        #     short-circuited by recursive :view filtering.
-        #   - EAGER_VC_KEY: Sequel's eager-load attachment block
-        #     dereferences each record to bucket by FK and would crash
-        #     on nils; the association reader filters at read time.
+        # Stores the ViewerContext in a Thread-local that Model.call
+        # 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.
         sig { returns(T.untyped) }
         def row_proc
           vc = opts[:viewer_context]
@@ -817,25 +728,18 @@ module Sequel
           end
         end
 
-        # Override all to filter out nil results from privacy checks
         sig { returns(T::Array[T.attached_class]) }
         def all
           results = super
           opts[:viewer_context] ? results.compact : results
         end
 
-        # Sequel calls post_load after rows are fetched but before any
-        # user block. Model's override of post_load triggers eager_load
-        # here. Set the thread-local VC around that call so each
-        # association's injected :eager_block can wrap its child dataset
-        # with for_vc. Children are then materialized with VC attached
-        # but without :view filtering (see Model.call), so Sequel's
-        # attachment block doesn't choke on nils; the accessor wrapper
-        # filters at read time.
-        #
-        # Parents filtered to nil by the :view policy must be dropped
-        # before eager_load runs — its attachment code dereferences each
-        # record, which nil would break.
+        # Sequel's Model#post_load triggers eager_load. We expose the VC
+        # via EAGER_VC_KEY around that call so the :eager_block injected
+        # in ClassMethods#associate can wrap each child dataset with
+        # for_vc. Parents already filtered to nil by row_proc must be
+        # compacted first — eager_load's attachment code can't handle
+        # nil records.
         sig { params(all_records: T.untyped).returns(T.untyped) }
         def post_load(all_records)
           vc = opts[:viewer_context]
@@ -852,7 +756,6 @@ module Sequel
           end
         end
 
-        # Create a new model instance with the viewer context attached
         sig { params(values: T::Hash[Symbol, T.untyped]).returns(T.attached_class) }
         def new(values = {})
           instance = T.unsafe(model).new(values)
@@ -862,7 +765,6 @@ module Sequel
           instance
         end
 
-        # Create and save a new model instance with the viewer context attached
         sig { params(values: T::Hash[Symbol, T.untyped]).returns(T.attached_class) }
         def create(values = {})
           T.cast(new(values), Sequel::Model).save

data/lib/sequel/privacy/built_in_policies.rb

@@ -3,10 +3,9 @@
 
 module Sequel
   module Privacy
-    # Built-in policies that ship with the gem.
-    # Applications should define their own policies using PolicyDSL.
     module BuiltInPolicies
-      # Always deny access. Should be the last policy in every chain (fail-secure).
+      # Always deny access. You should specify this policy at the end of every chain, but the framework
+      # currently appends it. This could change; I'm not sure about this yet.
       AlwaysDeny = Policy.create(
         :AlwaysDeny,
         -> { :deny },
@@ -14,7 +13,6 @@ module Sequel
         cacheable: true
       )
 
-      # Always allow access. Use sparingly.
       AlwaysAllow = Policy.create(
         :AlwaysAllow,
         -> { :allow },

data/lib/sequel/privacy/cache.rb

@@ -3,26 +3,23 @@
 
 module Sequel
   module Privacy
-    # In-memory cache for policy evaluation results.
-    # Should be cleared between requests (e.g., via Rack middleware).
+    # In-memory cache for policy evaluation results. Clear between
+    # requests (e.g. via Rack middleware).
     class << self
       extend T::Sig
 
-      # Returns the in-memory cache Hash for policy results.
       sig { returns(T::Hash[Integer, Symbol]) }
       def cache
         @cache ||= T.let({}, T.nilable(T::Hash[Integer, Symbol]))
       end
 
-      # Returns the hash tracking single-match optimizations.
-      # Key: [policy, actor, viewer_context].hash
-      # Value: subject.hash that matched
+      # Tracks single-match optimization state.
+      # Key: [policy, actor, viewer_context].hash → Value: subject.hash
       sig { returns(T::Hash[Integer, Integer]) }
       def single_matches
         @single_matches ||= T.let({}, T.nilable(T::Hash[Integer, Integer]))
       end
 
-      # Clear all caches. Call this between requests.
       sig { void }
       def clear_cache!
         @cache = {}

data/lib/sequel/privacy/enforcer.rb

@@ -3,8 +3,6 @@
 
 module Sequel
   module Privacy
-    # The Enforcer evaluates policy chains to determine if an action is allowed.
-    # It handles caching, single-match optimization, and policy combinators.
     module Enforcer
       extend T::Sig
 
@@ -18,7 +16,6 @@ module Sequel
       class << self
         extend T::Sig
 
-        # Returns the centralized logger from Sequel::Privacy.logger
         sig { returns(T.untyped) }
         def logger
           Sequel::Privacy.logger
@@ -30,13 +27,8 @@ module Sequel
         Thread.current[EVAL_KEY] == true
       end
 
-      # Main entry point for policy evaluation.
-      #
-      # @param policies [Array<Policy, Proc>] The policy chain to evaluate
-      # @param subject [Sequel::Model] The object being accessed
-      # @param viewer_context [ViewerContext] Who is accessing the object
-      # @param direct_object [Sequel::Model, nil] Optional additional context object
-      # @return [Boolean] true if access is allowed, false otherwise
+      # Evaluates a policy chain against (subject, viewer_context, direct_object)
+      # and returns whether access is allowed.
       sig do
         params(
           policies: TPolicyArray,
@@ -50,7 +42,6 @@ module Sequel
         Thread.current[EVAL_KEY] = true
 
         begin
-          # All-powerful and omniscient contexts bypass all checks
           if viewer_context.is_a?(AllPowerfulVC)
             logger&.warn('BYPASS: All-powerful viewer context bypasses all privacy rules.')
             return true
@@ -68,7 +59,7 @@ module Sequel
             policies = [BuiltInPolicies::AlwaysDeny]
           end
 
-          # Ensure policy chain ends with AlwaysDeny (fail-secure)
+          # Fail-secure: every chain ends with AlwaysDeny.
           unless policies.last == BuiltInPolicies::AlwaysDeny
             logger&.warn { 'Policy chain should end with AlwaysDeny. Appending it.' }
             policies = policies.dup << BuiltInPolicies::AlwaysDeny
@@ -138,9 +129,7 @@ module Sequel
         ).returns(Symbol)
       end
       def self.evaluate_child_policies(child_policies, subject, actor, viewer_context, direct_object)
-        unless child_policies.all? { |c| c.is_a?(Proc) }
-          Kernel.raise "Policy combinator contains non-policy members"
-        end
+        Kernel.raise 'Policy combinator contains non-policy members' unless child_policies.all? { |c| c.is_a?(Proc) }
 
         results = child_policies.map do |child_policy|
           policy_result(child_policy, subject, actor, viewer_context, direct_object)
@@ -152,7 +141,6 @@ module Sequel
         :pass
       end
 
-      # Evaluate a single policy and return its result
       sig do
         params(
           uncasted_policy: T.any(TPolicy, Proc),
@@ -168,7 +156,6 @@ module Sequel
 
         policy = T.cast(uncasted_policy, TPolicy, checked: false)
 
-        # Single-match optimization
         if policy.single_match?
           match_key = [policy, actor, viewer_context].hash
           if (matched = Sequel::Privacy.single_matches[match_key]) && matched != subject.hash
@@ -177,7 +164,6 @@ module Sequel
           end
         end
 
-        # Check cache
         cache_key = compute_cache_key(policy, subject, actor, viewer_context, direct_object)
         if !skipped_from_single_match && policy.cacheable? && Sequel::Privacy.cache.key?(cache_key)
           from_cache = true
@@ -185,24 +171,15 @@ module Sequel
           Kernel.raise InvalidPolicyOutcomeError unless result && valid_outcome?(result)
         end
 
-        # Execute policy if not cached
         result ||= execute_policy(policy, subject, actor, direct_object)
         result ||= :pass
 
-        # Handle combinator results
-        if result.is_a?(Array)
-          result = evaluate_child_policies(result, subject, actor, viewer_context, direct_object)
-        end
+        result = evaluate_child_policies(result, subject, actor, viewer_context, direct_object) if result.is_a?(Array)
 
-        # Cache result
-        if policy.cacheable? && !from_cache
-          Sequel::Privacy.cache[cache_key] = result
-        end
+        Sequel::Privacy.cache[cache_key] = result if policy.cacheable? && !from_cache
 
-        # Log result
         log_result(policy, result, actor, subject, from_cache, skipped_from_single_match)
 
-        # Record single-match
         if policy.single_match? && result == :allow
           Sequel::Privacy.single_matches[[policy, actor, viewer_context].hash] = subject.hash
         end
@@ -223,13 +200,10 @@ module Sequel
         ).returns(T.untyped)
       end
       def self.execute_policy(policy, subject, actor, direct_object)
-        # Policies with arity >= 1 expect an actor as the first arg.
-        # Anonymous viewers (no actor) auto-deny unless the policy opts in
-        # with allow_anonymous: true (for state-gate policies that examine
-        # only the subject).
-        if !actor && policy.arity >= 1 && !policy.allow_anonymous?
-          return :deny
-        end
+        # Arity ≥ 1 policies expect an actor as the first arg; an
+        # anonymous viewer auto-denies unless the policy opts in with
+        # `allow_anonymous: true` (for subject-only state gates).
+        return :deny if !actor && policy.arity >= 1 && !policy.allow_anonymous?
 
         case policy.arity
         when 0
@@ -259,14 +233,14 @@ module Sequel
         actor_id = actor ? actor.id : 'anonymous'
         logger.debug do
           msg = "#{result.to_s.upcase}: #{policy.policy_name || 'anonymous'} for actor[#{actor_id}] on #{subject.class}[#{subject_id(subject)}]"
-          msg += " (cached)" if from_cache
-          msg += " (skipped: single_match)" if skipped
+          msg += ' (cached)' if from_cache
+          msg += ' (skipped: single_match)' if skipped
           msg
         end
 
-        if policy.comment && %i[deny allow].include?(result)
-          logger.debug { " ⮑  #{policy.comment}" }
-        end
+        return unless policy.comment && %i[deny allow].include?(result)
+
+        logger.debug { " ⮑  #{policy.comment}" }
       end
 
       sig { params(subject: TPolicySubject).returns(T.untyped) }

data/lib/sequel/privacy/i_actor.rb

@@ -3,8 +3,7 @@
 
 module Sequel
   module Privacy
-    # Interface that actors (typically User/Member models) must implement
-    # to be used with the privacy system.
+    # Interface for actors used in viewer contexts (typically User/Member).
     module IActor
       extend T::Sig
       extend T::Helpers

data/lib/sequel/privacy/policy.rb

@@ -27,8 +27,6 @@ module Sequel
 
       VALID_CACHE_BY = T.let(%i[actor subject direct_object].freeze, T::Array[Symbol])
 
-      # Factory method for creating policies. Accepts procs of any arity
-      # (0–3 args) returning :allow, :deny, :pass, or an Array of policies.
       sig do
         params(
           policy_name: Symbol,
@@ -52,24 +50,23 @@ module Sequel
         )
       end
 
-      # Configure the policy after creation
+      # Configure the policy after creation, normally done with the shorthand `policy` call.
       #
       # @param policy_name [Symbol, nil] Human-readable name for logging
       # @param comment [String, nil] Description of what this policy does
       # @param cacheable [Boolean] Whether results can be cached (default: true)
       # @param single_match [Boolean] Whether only one subject/actor pair can match (default: false)
       # @param cache_by [Symbol, Array<Symbol>, nil] Override the cache-key
-      #   dimensions. By default the key is derived from the policy's arity
-      #   (all inputs the policy receives). Pass a subset of
-      #   `:actor, :subject, :direct_object` to cache by only those — useful
-      #   when the policy ignores inputs it nominally receives (e.g. an
-      #   "is-admin" check that takes `(actor, subject)` but only examines
+      #   dimensions. By default the key is derived from the policy's arity,
+      #   but you might want to pass a subset of `:actor, :subject, :direct_object` 
+      #   to cache by only those; useful when the policy ignores inputs (e.g. an
+      #   "is-admin" check that takes `(actor, subject)` but only looks at
       #   actor should use `cache_by: :actor` to share a single entry across
       #   subjects).
       # @param allow_anonymous [Boolean] If true, skip the auto-deny that
       #   normally fires when a policy of arity >= 1 is evaluated for an
-      #   anonymous viewer (nil actor). Use for state-gate policies that
-      #   ignore the actor and decide purely on subject state.
+      #   anonymous viewer (nil actor). This is a bit inelegant; it'd be great
+      #   if we could tell that an argument isn't used at all. 
       def setup(policy_name: nil, comment: nil, cacheable: true, single_match: false, cache_by: nil,
                 allow_anonymous: false)
         raise 'Privacy Policy is frozen' if @frozen
@@ -89,8 +86,9 @@ module Sequel
         @cacheable || false
       end
 
-      # Single-match optimization: when true, once a policy allows for a subject/actor pair,
-      # skip evaluation for other subjects (e.g., AllowIfActorIsSelf - only one subject matches)
+      # When set, once the policy allows for a given actor it short-circuits
+      # to :pass on every other subject — useful when only one subject can
+      # ever match (e.g. AllowSelf).
       sig { returns(T::Boolean) }
       def single_match?
         @single_match || false
@@ -125,7 +123,6 @@ module Sequel
   end
 end
 
-# Type aliases for use throughout the gem
 module Sequel
   module Privacy
     TPolicy = T.type_alias { Sequel::Privacy::Policy }

data/lib/sequel/privacy/policy_dsl.rb

@@ -20,21 +20,13 @@ module Sequel
       extend T::Sig
       extend T::Helpers
 
-      # PolicyDSL is meant to be `extend`ed onto another Module, so `self`
-      # at runtime is always a Module that responds to `const_set`.
+      # `extend`ed onto another Module, so `self` at runtime is always a
+      # Module that responds to `const_set`.
       requires_ancestor { Module }
 
-      # Define a new policy constant on the extending module.
-      #
-      # @param name [Symbol] The policy name (will become a constant)
-      # @param lam [Proc] The policy lambda (0-3 args: actor, subject, direct_object)
-      # @param comment [String, nil] Human-readable description
-      # @param cacheable [Boolean] Whether results can be cached (default: true)
-      # @param single_match [Boolean] Whether only one subject/actor can match (default: false)
-      # @param cache_by [Symbol, Array<Symbol>, nil] Override cache-key
-      #   dimensions. See Sequel::Privacy::Policy#setup for details.
-      # @param allow_anonymous [Boolean] Skip auto-deny for nil actor.
-      #   See Sequel::Privacy::Policy#setup for details.
+      # Define a policy constant on the extending module. See
+      # `Sequel::Privacy::Policy#setup` for the meaning of `cacheable`,
+      # `single_match`, `cache_by`, and `allow_anonymous`.
       sig do
         params(
           name: Symbol,

data/lib/sequel/privacy/version.rb

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

data/lib/sequel/privacy/viewer_context.rb

@@ -3,43 +3,40 @@
 
 module Sequel
   module Privacy
-    # ViewerContext represents who is viewing/accessing data.
-    # All privacy checks require a viewer context to determine what the viewer can see.
+    # Represents who is viewing/accessing data. All privacy checks require
+    # a ViewerContext.
     class ViewerContext
       extend T::Sig
       extend T::Helpers
       abstract!
 
-      # Create a standard viewer context for an actor
       sig { params(actor: IActor).returns(ActorVC) }
       def self.for_actor(actor)
         ActorVC.new(actor)
       end
 
-      # Create an API-specific viewer context
       sig { params(actor: IActor).returns(APIVC) }
       def self.for_api_actor(actor)
         APIVC.new(actor)
       end
 
-      # Create an all-powerful viewer context that bypasses all privacy checks.
-      # Use sparingly and always provide a reason for audit logging.
+      # Bypasses all privacy checks; requires a reason for audit logging.
+      # Use sparingly.
       sig { params(reason: Symbol).returns(AllPowerfulVC) }
       def self.all_powerful(reason)
         Sequel::Privacy.logger&.info("Creating all-powerful viewer context: #{reason}")
         AllPowerfulVC.new(reason)
       end
 
-      # Create an omniscient viewer context that can see everything but cannot mutate.
-      # Used for system operations like authentication lookups.
+      # Reads any record but cannot mutate. For system operations like
+      # authentication lookups.
       sig { params(reason: Symbol).returns(OmniscientVC) }
       def self.omniscient(reason)
         Sequel::Privacy.logger&.debug("Creating omniscient viewer context: #{reason}")
         OmniscientVC.new(reason)
       end
 
-      # Create an anonymous viewer context for logged-out users.
-      # Subject to normal policy evaluation with no actor.
+      # No actor; subject to normal policy evaluation. For logged-out users.
       sig { returns(AnonymousVC) }
       def self.anonymous
         AnonymousVC.new
@@ -94,8 +91,6 @@ module Sequel
       attr_reader :reason
     end
 
-    # Anonymous viewer context for logged-out users.
-    # Has no actor - policies with arity >= 1 will auto-deny.
     class AnonymousVC < ViewerContext
       extend T::Sig
 
@@ -105,7 +100,6 @@ module Sequel
       end
     end
 
-    # Type alias for viewer contexts
     TViewerContext = T.type_alias { ViewerContext }
   end
 end

data/lib/sequel-privacy.rb

@@ -9,15 +9,13 @@ module Sequel
     class << self
       extend T::Sig
 
-      # Configurable logger for privacy enforcement.
-      # Set this to your application's logger (e.g., SemanticLogger).
+      # Set this to your application's logger (e.g. SemanticLogger).
       sig { returns(T.untyped) }
       attr_accessor :logger
     end
   end
 end
 
-# Core privacy infrastructure
 require_relative 'sequel/privacy/version'
 require_relative 'sequel/privacy/errors'
 require_relative 'sequel/privacy/i_actor'
@@ -29,5 +27,5 @@ require_relative 'sequel/privacy/enforcer'
 require_relative 'sequel/privacy/built_in_policies'
 require_relative 'sequel/privacy/policy_dsl'
 
-# The plugin is auto-loaded by Sequel when you call `plugin :privacy`
-# from lib/sequel/plugins/privacy.rb
+# The plugin itself lives in lib/sequel/plugins/privacy.rb and is
+# auto-loaded by Sequel on `plugin :privacy`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sequel-privacy
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.3
 platform: ruby
 authors:
 - Austin Bales
@@ -130,7 +130,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="