sequel-privacy 0.5.2 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e415c08d25c658e76c101a7c7ccbdbb791ef1f00deb6a81481ada2044a2b779
-  data.tar.gz: 819dfce705006ad300e092650cd2014944989c6bec4baefb6bdd5a0fe1bd6bc1
+  metadata.gz: 54198780e9744c541e3915d3ac5722ccb16b119a77729b5013b854e698604511
+  data.tar.gz: 5219bec34c9542ce88f928bc39c1998586e6ed2c15637296dead03d958e12db1
 SHA512:
-  metadata.gz: b875efc8f711c1403eb90e8ebc6ca5071b325c3e6e7856cc7c43f4dc43f5edb4add75a6081db527d30a184c856719a1461da50a2e6a754567a8a5886567daea8
-  data.tar.gz: b1c2f4a0525b3d4232f4f369d483affbf3bcc84235602d116f2d8a40d80c686e5bd8a677e1367bbc53012b8341a63e787b7d502377b2322f63afdbf5f10518ec
+  metadata.gz: 8673ccf1e4e6cb592299c9a930ee7ff779e0343e66753a245f71f4aa26d21906c486dc1435d55af53c1c8b09c8166f24fec2e8036ce3f962598df4d8a29cadf9
+  data.tar.gz: 34bc11e989421e4cd7d5207fc531d7bcf17cf681c8b10c3104918c12d5d2a9eb8cdf68274dd64397c8b49ba51b6c59b3de4fd4ef73e8acbf06b1fdd671039cce

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

@@ -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/cache.rb

@@ -3,8 +3,8 @@
 
 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
 
@@ -13,15 +13,13 @@ module Sequel
         @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

@@ -16,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
@@ -28,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,
@@ -48,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
@@ -66,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
@@ -148,7 +141,6 @@ module Sequel
         :pass
       end
 
-      # Evaluate a single policy and return its result
       sig do
         params(
           uncasted_policy: T.any(TPolicy, Proc),
@@ -164,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
@@ -173,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
@@ -181,20 +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
         result = evaluate_child_policies(result, subject, actor, viewer_context, direct_object) if result.is_a?(Array)
 
-        # Cache result
         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
@@ -215,10 +200,9 @@ 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).
+        # 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

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.2'
+    VERSION = '0.5.4'
   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.2
+  version: 0.5.4
 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:
   - - ">="