sequel-privacy 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 644015302ea6057f9b102b24803bafb4c67059e51a6a66c02d825216404ae05f
-  data.tar.gz: 8504cb1ca168b0f34b2fa7705a782ca74567aa1839d4f13816f69aaa5e27546e
+  metadata.gz: 04b5728dab12a15490535725e9458d1039e17049f47e839e724b5464b1e39ee5
+  data.tar.gz: ddb26ed4c76c15b672043d2ac32ff4573b791befc8c9f3b1d0405e0c4ddcd6ba
 SHA512:
-  metadata.gz: 8a714fa412538a84dbed42f938eb419a85c626a045a5fc6fa8865014b039bc49eee75eb429c5adeb6d946908ab3e09c04bf5b8240c231090e955b6f8dbed5d4c
-  data.tar.gz: d82cd3eaf425d213c12d99a813a6de7656b377241a64c0c82bd6ba098e42e69334567f8b1e03d8e1ff209932b4e8b0310725b57be0a91eb720d30b752e63ca06
+  metadata.gz: 1b235a397d24fbfea16f557628554b5e64352a2872b54d9b51b36e81d13fe659be3b1a011e256626db7025dc7527b33e891866c116e4a1dbe4a03821209401c6
+  data.tar.gz: 105bb81dc55bb0970a224682c7ab30117758e882db8acac968802da1ed0fa06bd29145350d9de196dda2f6b5d0f81b7c58433e1107317ab8f4b7d297a5ee2c53

data/README.md

@@ -58,6 +58,9 @@ end
 ```ruby
 class Member < Sequel::Model
   plugin :privacy
+  
+  # Include this module if this model can be used to create a viewer context.  
+  include Sequel::Privacy::IActor
 
   privacy do
     # Define who can view this model; be strategic about the order of your policies so that You
@@ -77,29 +80,36 @@ The `privacy` block provides:
 - `field :name, *policies` - Protect a field (auto-creates `:view_#{field}` policy)
 - `finalize!` - Prevent further modifications to privacy settings
 
-`AlwaysDeny` is automatically appended to all policy chains (fail-secure by default).
+`AlwaysDeny` is automatically appended to all policy chains if you don't include it, but it's better to add it explictly.
+This behavior may change. 
 
 ### 3. Query with Privacy Enforcement
 
 ```ruby
-# Create a viewer context
-vc = Sequel::Privacy::ViewerContext.for_actor(current_user)
+# Create a viewer context; one viewer context for each request.
+# In a Roda app, you could do this at the top of your routing tree,
+# in Sinatra you could do this in a `before` filter. See the dedicated
+# section below for more information about VCs.
+current_vc = Sequel::Privacy::ViewerContext.for_actor(current_user)
 
-# Query - results are automatically filtered by :view policy
-members = Member.for_vc(vc).where(org_id: 1).all
+# Results will filter out records that your VC can't see.
+members = Member.for_vc(vc).where(org_id: current_user.org_id).all
 
-# Check permissions explicitly
-member.allow?(vc, :view)  # => true/false
-member.allow?(vc, :edit)  # => true/false
+# But DON'T rely on the privacy checker in place of refining your query
+# with privacy/permissions in-mind.
+my_groups = Group.for_vc(vc).all # DONT: This results on tons of records being returned, processed and filtered for no reason.
+my_groups = Group.for_vc(vc).where(creator: current_user).all # DO
 
-# Protected fields return nil if denied
+# Field-level privacy policies will be enforced on access. 
 member.email  # => nil if :view_email denies
 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. Policies accept up to three parameters: `actor`, `subject` & `actor` or `subject`, `actor` and `direct_object`.
+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 accept up to three parameters: `actor`, `subject` & `actor` or `subject`, `actor` and `direct_object`. 
 
 
 ```ruby
@@ -114,24 +124,34 @@ policy :AllowAdmins, ->(_subject, actor) {
   allow if actor.is_role?(:admin)
 }
 
-policy :AllowOwner, ->(subject, actor) {
+policy :AllowOwner, ->(_subject, actor) {
   allow if subject.owner_id == actor.id
 }
 
-policy :AllowSelfJoin, ->(_group, actor, target_user) {
-  allow if actor.id == target_user.id
+policy :AllowIfDirectObjectIsActor, ->(_subject, actor, direct_object) {
+  allow if actor.id == direct_object.id
 }
 
-policy :AllowSelfRemove, ->(_group, actor, target_user) {
-  allow if actor.id == target_user.id
-}
 ```
 
-### Policy Return Values
+If you have lots of different objects and want to make your policies more specific, you can define policies in 
+different modules.
 
-- `allow` - Permits the action, stops evaluation
-- `deny` - Rejects the action, stops evaluation
-- `pass` (or no explicit return) - Continues to the next policy in the chain
+```ruby
+module P
+  module Groups
+    extend Sequel::Privacy::PolicyDSL
+    
+    policy :AllowIfOpen, -> (subject, _actor) {
+      allow if subject.open?
+    }
+    
+    policy :AllowIfMember, -> (subject, actor) {
+      allow if subject.includes_member? actor
+    }      
+  end
+end
+```
 
 ### Policy Options
 
@@ -151,7 +171,13 @@ policy :MyPolicy, ->() { ... },
 Use `all()` to require multiple conditions:
 
 ```ruby
-policy :AllowMemberToRemoveSelf, ->(subject, actor, direct_object) {
+policy :AllowAddSelfToOpenGroup, ->(subject, actor, direct_object) {
+  all(
+    P::AllowIfGroupIsOpen    
+    P::AllowIfDirectObjectIsActor
+  )
+}
+policy :AllowRemoveSelf, ->(subject, actor, direct_object) {
   all(
     P::AllowIfIncludesMember,
     P::AllowIfDirectObjectIsActor
@@ -170,13 +196,14 @@ Anonymous VCs are useful for logged out users, and can check that their access i
 that are meant to be fully public.
 
 Omniscient VCs are most useful when your application needs to see an object that a user cannot for some reason.
-Handle them with care. Login is the most salient example. 
+Handle them with care. Login is the most salient example (see note below for more detail). 
 
 All-Powerful VCs bypass all privacy checks and are used in situations where the system needs unfettered access
 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.
+You could also create lint rules that prevent the casual creation of these viewer contexts.
 
 ```ruby
 # Standard viewer (most common)
@@ -199,6 +226,36 @@ current_vc = Sequel::Privacy::ViewerContext.for_actor(current_user)
 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:
@@ -251,7 +308,7 @@ The `association` block supports three actions:
 - `:remove` - Wraps `remove_*` method (e.g., `remove_member`)
 - `:remove_all` - Wraps `remove_all_*` method (e.g., `remove_all_members`)
 
-Association policies use 3-arity, receiving `(subject, actor, direct_object)`:
+Association policies receive `(subject, actor, direct_object)`:
 - `subject` - The model instance (e.g., the group)
 - `actor` - The current user from the viewer context
 - `direct_object` - The object being added/removed (e.g., the user being added to the group)
@@ -260,17 +317,17 @@ For `remove_all`, the direct object is `nil` since there's no specific target.
 
 ```ruby
 # Allow users to add/remove themselves
-policy :AllowSelfJoin, ->(_group, actor, target_user) {
-  allow if actor.id == target_user.id
+policy :AllowSelfJoin, ->(_subject, actor, direct_object) {
+  allow if actor.id == direct_object.id
 }, single_match: true
 
-policy :AllowSelfRemove, ->(_group, actor, target_user) {
-  allow if actor.id == target_user.id
+policy :AllowSelfRemove, ->(_subject, actor, direct_object) {
+  allow if actor.id == direct_object.id
 }, single_match: true
 
 # Allow group admins to add/remove anyone
-policy :AllowGroupAdmin, ->(group, actor, _target_user) {
-  allow if GroupAdmin.where(group_id: group.id, user_id: actor.id).exists?
+policy :AllowGroupAdmin, ->(subject, actor, direct_object) {
+  allow if subject.includes_admin?(actor)
 }
 ```
 
@@ -292,11 +349,6 @@ group.remove_all_members
 group.add_member(other_user)  # Raises Sequel::Privacy::Unauthorized
 ```
 
-Association privacy methods:
-- Require a viewer context (raises `MissingViewerContext` if missing)
-- Deny operations with `OmniscientVC` (read-only context cannot mutate)
-- Work with both `one_to_many` and `many_to_many` associations
-
 ### Exception Types
 
 - `Sequel::Privacy::Unauthorized` - Action denied at the record level
@@ -305,7 +357,9 @@ Association privacy methods:
 
 ## Logging
 
-Configure a logger to see policy evaluation:
+Configure a logger to see policy evaluation. It will show the evaluation results
+(ALLOW, DENY, PASS) as well as cache hits/optimizations and note when privacy
+is bypassed by an APVC or an OmniVC. 
 
 ```ruby
 Sequel::Privacy.logger = Logger.new(STDOUT)
@@ -313,12 +367,6 @@ Sequel::Privacy.logger = Logger.new(STDOUT)
 Sequel::Privacy.logger = SemanticLogger['Privacy']
 ```
 
-Log output shows:
-- Policy evaluation results (ALLOW/DENY/PASS)
-- Cache hits
-- Single-match optimizations
-- All-powerful/omniscient context bypasses
-
 ## Cache Management
 
 Policy results are cached per-request to avoid redundant evaluation. Clear between requests:
@@ -346,7 +394,8 @@ Sequel::Privacy.single_matches.clear
 
 ## Actor Interface
 
-Your user/member model must implement `Sequel::Privacy::IActor`:
+Your user/member model must include and implement `Sequel::Privacy::IActor`. 
+This will be runtime checked by Sorbet. 
 
 ```ruby
 class Member < Sequel::Model
@@ -358,17 +407,13 @@ class Member < Sequel::Model
 end
 ```
 
-The interface requires:
-- `id` - Returns the actor's unique identifier
-
-You can add additional methods like `is_role?` for use in your policies, but they are not required by the interface.
-
 ## Policy Inheritance
 
 Child classes inherit privacy policies from their parents:
 
 ```ruby
 class User < Sequel::Model
+  include Sequel::Privacy::IActor
   plugin :privacy
 
   privacy do
@@ -386,14 +431,25 @@ end
 
 ## Built-in Policies
 
-- `Sequel::Privacy::BuiltInPolicies::AlwaysDeny` - Always denies (fail-secure default)
+- `Sequel::Privacy::BuiltInPolicies::AlwaysDeny` - Always denies; add it to the end of your policy chains.
 - `Sequel::Privacy::BuiltInPolicies::AlwaysAllow` - Always allows
 - `Sequel::Privacy::BuiltInPolicies::PassAndLog` - Passes with a log message (useful for debugging)
 
 
 ## Type Safety (Sorbet)
 
-The gem is mostly fully typed with Sorbet. Type definitions are provided for all public APIs.
+The gem is mostly fully typed with Sorbet. Type definitions are provided for all public APIs. To ensure 
+that Tapioca imports the required definitions, you may need to add this to your `sorbet/tapioca/require.rb`:
+
+```ruby
+require "sequel-privacy"
+require "sequel/plugins/privacy"
+
+# Force Tapioca to see the plugin modules by applying them to a dummy class
+Class.new(Sequel::Model) do
+  plugin :privacy
+end
+```
 
 ## AI Statement
 
@@ -401,12 +457,6 @@ The core of this project was written by me (arbales) over the course of 2025 for
 manages mailing lists and member information for a social group. Claude assisted substantially with
 extracting it into a Gem and wrote the tests in their entirety.
 
-## TODO
-
-I'd like to support generation of Sorbet signatures on models that use the plugin so that 
-Sorbet users don't have to shim their models to use it. In my own work, I've shimmed my 
-base model class, but this isn't ideal. 
-
 ## License
 
 MIT

data/lib/sequel/plugins/privacy.rb

@@ -37,8 +37,8 @@ module Sequel
       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 = {})
+      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, {})
         model.instance_variable_set(:@privacy_fields, {})
         model.instance_variable_set(:@privacy_association_policies, {})
@@ -56,7 +56,10 @@ module Sequel
       class AssociationPrivacyDSL
         extend T::Sig
 
-        sig { params(model_class: T.untyped, assoc_name: Symbol, policy_resolver: T.proc.params(policies: T::Array[T.untyped]).returns(T::Array[T.untyped])).void }
+        sig {
+          params(model_class: ClassMethods, assoc_name: Symbol,
+                 policy_resolver: T.proc.params(policies: T::Array[T.untyped]).returns(T::Array[T.untyped])).void
+        }
         def initialize(model_class, assoc_name, policy_resolver)
           @model_class = model_class
           @assoc_name = assoc_name
@@ -68,10 +71,11 @@ module Sequel
         sig { params(action: Symbol, policies: T.untyped).void }
         def can(action, *policies)
           unless %i[add remove remove_all].include?(action)
-            Kernel.raise ArgumentError, "Association action must be :add, :remove, or :remove_all, got #{action.inspect}"
+            Kernel.raise ArgumentError,
+                         "Association action must be :add, :remove, or :remove_all, got #{action.inspect}"
           end
 
-          resolved = @policy_resolver.call(policies)
+          resolved = @policy_resolver.(policies)
           @pending_policies[action] ||= []
           T.must(@pending_policies[action]).concat(resolved)
         end
@@ -80,10 +84,9 @@ module Sequel
         sig { void }
         def finalize_association!
           @pending_policies.each do |action, policies|
-            T.unsafe(@model_class).register_association_policies(@assoc_name, action, policies, defer_setup: true)
+            @model_class.register_association_policies(@assoc_name, action, policies, defer_setup: true)
           end
-          # Now set up the privacy wrappers after all policies are registered
-          T.unsafe(@model_class).setup_association_privacy(@assoc_name)
+          @model_class.setup_association_privacy(@assoc_name)
         end
       end
 
@@ -91,7 +94,7 @@ module Sequel
       class PrivacyDSL
         extend T::Sig
 
-        sig { params(model_class: T.untyped).void }
+        sig { params(model_class: ClassMethods).void }
         def initialize(model_class)
           @model_class = model_class
         end
@@ -100,7 +103,7 @@ module Sequel
         sig { params(action: Symbol, policies: T.untyped).void }
         def can(action, *policies)
           resolved = resolve_policies(policies)
-          T.unsafe(@model_class).register_policies(action, resolved)
+          @model_class.register_policies(action, resolved)
         end
 
         # Define a protected field with its policies
@@ -108,8 +111,8 @@ module Sequel
         def field(name, *policies)
           resolved = resolve_policies(policies)
           policy_name = :"view_#{name}"
-          T.unsafe(@model_class).register_policies(policy_name, resolved)
-          T.unsafe(@model_class).register_protected_field(name, policy_name)
+          @model_class.register_policies(policy_name, resolved)
+          @model_class.register_protected_field(name, policy_name)
         end
 
         # Define policies for an association
@@ -120,7 +123,7 @@ module Sequel
         #     can :remove, AllowGroupAdmin, AllowSelfRemove
         #     can :remove_all, AllowGroupAdmin
         #   end
-        sig { params(name: Symbol, block: T.proc.void).void }
+        sig { params(name: Symbol, block: T.proc.bind(AssociationPrivacyDSL).void).void }
         def association(name, &block)
           resolver = ->(policies) { resolve_policies(policies) }
           dsl = AssociationPrivacyDSL.new(@model_class, name, resolver)
@@ -131,7 +134,7 @@ module Sequel
         # Finalize privacy settings (no more changes allowed)
         sig { void }
         def finalize!
-          T.unsafe(@model_class).finalize_privacy!
+          @model_class.finalize_privacy!
         end
 
         private
@@ -198,7 +201,7 @@ module Sequel
 
           unless vc || allow_unsafe_access?
             Kernel.raise Sequel::Privacy::MissingViewerContext,
-              "#{self} requires a ViewerContext. Use #{self}.for_vc(vc) or call #{self}.allow_unsafe_access!"
+                         "#{self} requires a ViewerContext. Use #{self}.for_vc(vc) or call #{self}.allow_unsafe_access!"
           end
 
           # Create the instance via parent chain
@@ -208,12 +211,14 @@ module Sequel
           if vc && instance
             instance.instance_variable_set(:@viewer_context, vc)
 
-            # Check :view policy (skip for InternalPolicyEvaluationVC - used during policy evaluation)
-            unless vc.is_a?(Sequel::Privacy::InternalPolicyEvaluationVC)
-              unless instance.allow?(vc, :view)
-                Sequel::Privacy.logger&.debug { "Privacy denied :view on #{self}[#{instance.pk}]" }
-                return nil # Filtered out
-              end
+            # During nested policy evaluation, return raw rows so the outer
+            # policy can traverse data (e.g. checking membership) without
+            # recursive :view filtering.
+            return instance if Sequel::Privacy::Enforcer.in_policy_eval?
+
+            unless T.cast(instance, InstanceMethods).allow?(vc, :view)
+              Sequel::Privacy.logger&.debug { "Privacy denied :view on #{self}[#{instance.pk}]" }
+              return nil
             end
           end
 
@@ -255,7 +260,7 @@ module Sequel
         #     can :edit, P::AllowSelf, P::AllowAdmins
         #     field :email, P::AllowSelf
         #   end
-        sig { params(block: T.proc.void).void }
+        sig { params(block: T.proc.bind(PrivacyDSL).void).void }
         def privacy(&block)
           if privacy_finalized?
             Kernel.raise Sequel::Privacy::PrivacyAlreadyFinalizedError, "Privacy already finalized for #{self}"
@@ -290,25 +295,21 @@ module Sequel
 
           # 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)
 
-            # Require VC for protected field access
             unless vc
               Kernel.raise Sequel::Privacy::MissingViewerContext,
-                "#{self.class}##{field} requires a ViewerContext"
+                           "#{self.class}##{field} requires a ViewerContext"
             end
 
-            value = original_method.bind(self).call
+            value = original_method.bind(self).()
+            return unless T.cast(self, InstanceMethods).allow?(vc, policy_name)
 
-            # InternalPolicyEvaluationVC = return raw value (for policy checks)
-            return value if vc.is_a?(Sequel::Privacy::InternalPolicyEvaluationVC)
-
-            # Check privacy policy
-            if T.unsafe(self).allow?(vc, policy_name)
-              value
-            else
-              nil
-            end
+            value
           end
         end
 
@@ -316,9 +317,7 @@ module Sequel
         # @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)
-          if privacy_finalized?
-            Kernel.raise "Privacy policies have been finalized for #{self}"
-          end
+          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])
@@ -342,6 +341,7 @@ module Sequel
           # 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
@@ -363,9 +363,9 @@ module Sequel
 
           # Wrap remove_all_* method if :remove_all policy exists
           remove_all_policies = assoc_policies[:remove_all]
-          if remove_all_policies && method_defined?(:"remove_all_#{reflection[:name]}")
-            _wrap_association_remove_all(assoc_name, reflection[:name], remove_all_policies)
-          end
+          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)
@@ -440,30 +440,26 @@ module Sequel
 
             # 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]
-              Thread.current[vc_key] = vc
-              begin
-                original.bind(self).call
-              ensure
-                Thread.current[vc_key] = old_vc
-              end
-            else
-              original.bind(self).call
-            end
+                    vc_key = assoc_class.privacy_vc_key
+                    old_vc = Thread.current[vc_key]
+                    Thread.current[vc_key] = vc
+                    begin
+                      original.bind(self).()
+                    ensure
+                      Thread.current[vc_key] = old_vc
+                    end
+                  else
+                    original.bind(self).()
+                  end
 
             return nil unless obj
             return obj unless vc
+            return obj if Sequel::Privacy::Enforcer.in_policy_eval?
 
-            # InternalPolicyEvaluationVC = return raw data (for policy checks)
-            # This allows policies to access associations without filtering
-            return obj if vc.is_a?(Sequel::Privacy::InternalPolicyEvaluationVC)
-
-            # Attach viewer context to associated object
-            obj.instance_variable_set(:@viewer_context, vc) if obj.respond_to?(:allow?)
+            privacy_aware = obj.is_a?(Sequel::Model) && obj.class.respond_to?(:privacy_vc_key)
+            obj.instance_variable_set(:@viewer_context, vc) if privacy_aware
 
-            # Check :view policy on associated object
-            if obj.respond_to?(:allow?) && !obj.allow?(vc, :view)
+            if privacy_aware && !T.cast(obj, InstanceMethods).allow?(vc, :view)
               nil
             else
               obj
@@ -485,29 +481,26 @@ module Sequel
 
             # 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]
-              Thread.current[vc_key] = vc
-              begin
-                original.bind(self).call
-              ensure
-                Thread.current[vc_key] = old_vc
-              end
-            else
-              original.bind(self).call
-            end
+                     vc_key = assoc_class.privacy_vc_key
+                     old_vc = Thread.current[vc_key]
+                     Thread.current[vc_key] = vc
+                     begin
+                       original.bind(self).()
+                     ensure
+                       Thread.current[vc_key] = old_vc
+                     end
+                   else
+                     original.bind(self).()
+                   end
 
             return objs unless vc
+            return objs if Sequel::Privacy::Enforcer.in_policy_eval?
 
-            # InternalPolicyEvaluationVC = return raw data (for policy checks like includes_member?)
-            # This allows policies to access associations without filtering
-            return objs if vc.is_a?(Sequel::Privacy::InternalPolicyEvaluationVC)
-
-            # Filter array, attaching VC and checking :view policy
             objs.filter_map do |obj|
-              obj.instance_variable_set(:@viewer_context, vc) if obj.respond_to?(:allow?)
+              privacy_aware = obj.is_a?(Sequel::Model) && obj.class.respond_to?(:privacy_vc_key)
+              obj.instance_variable_set(:@viewer_context, vc) if privacy_aware
 
-              if obj.respond_to?(:allow?) && !obj.allow?(vc, :view)
+              if privacy_aware && !T.cast(obj, InstanceMethods).allow?(vc, :view)
                 nil
               else
                 obj
@@ -516,8 +509,8 @@ module Sequel
           end
         end
 
-        sig { params(assoc_name: Symbol, singular_name: Symbol, policies: T::Array[T.untyped]).void }
-        def _wrap_association_add(assoc_name, singular_name, policies)
+        sig { params(_assoc_name: Symbol, singular_name: Symbol, policies: T::Array[T.untyped]).void }
+        def _wrap_association_add(_assoc_name, singular_name, policies)
           method_name = :"add_#{singular_name}"
           original = instance_method(method_name)
 
@@ -526,12 +519,12 @@ module Sequel
 
             unless vc
               Kernel.raise Sequel::Privacy::MissingViewerContext,
-                "Cannot #{method_name} without a viewer context"
+                           "Cannot #{method_name} without a viewer context"
             end
 
             if vc.is_a?(Sequel::Privacy::OmniscientVC)
               Kernel.raise Sequel::Privacy::Unauthorized,
-                "Cannot #{method_name} with OmniscientVC"
+                           "Cannot #{method_name} with OmniscientVC"
             end
 
             # Check policy with 3-arity: (subject=self, actor, direct_object=obj)
@@ -539,15 +532,15 @@ module Sequel
 
             unless allowed
               Kernel.raise Sequel::Privacy::Unauthorized,
-                "Cannot #{method_name} on #{self.class}"
+                           "Cannot #{method_name} on #{self.class}"
             end
 
-            original.bind(self).call(obj)
+            original.bind(self).(obj)
           end
         end
 
-        sig { params(assoc_name: Symbol, singular_name: Symbol, policies: T::Array[T.untyped]).void }
-        def _wrap_association_remove(assoc_name, singular_name, policies)
+        sig { params(_assoc_name: Symbol, singular_name: Symbol, policies: T::Array[T.untyped]).void }
+        def _wrap_association_remove(_assoc_name, singular_name, policies)
           method_name = :"remove_#{singular_name}"
           original = instance_method(method_name)
 
@@ -556,12 +549,12 @@ module Sequel
 
             unless vc
               Kernel.raise Sequel::Privacy::MissingViewerContext,
-                "Cannot #{method_name} without a viewer context"
+                           "Cannot #{method_name} without a viewer context"
             end
 
             if vc.is_a?(Sequel::Privacy::OmniscientVC)
               Kernel.raise Sequel::Privacy::Unauthorized,
-                "Cannot #{method_name} with OmniscientVC"
+                           "Cannot #{method_name} with OmniscientVC"
             end
 
             # Check policy with 3-arity: (subject=self, actor, direct_object=obj)
@@ -569,15 +562,15 @@ module Sequel
 
             unless allowed
               Kernel.raise Sequel::Privacy::Unauthorized,
-                "Cannot #{method_name} on #{self.class}"
+                           "Cannot #{method_name} on #{self.class}"
             end
 
-            original.bind(self).call(obj)
+            original.bind(self).(obj)
           end
         end
 
-        sig { params(assoc_name: Symbol, plural_name: Symbol, policies: T::Array[T.untyped]).void }
-        def _wrap_association_remove_all(assoc_name, plural_name, policies)
+        sig { params(_assoc_name: Symbol, plural_name: Symbol, policies: T::Array[T.untyped]).void }
+        def _wrap_association_remove_all(_assoc_name, plural_name, policies)
           method_name = :"remove_all_#{plural_name}"
           original = instance_method(method_name)
 
@@ -586,23 +579,23 @@ module Sequel
 
             unless vc
               Kernel.raise Sequel::Privacy::MissingViewerContext,
-                "Cannot #{method_name} without a viewer context"
+                           "Cannot #{method_name} without a viewer context"
             end
 
             if vc.is_a?(Sequel::Privacy::OmniscientVC)
               Kernel.raise Sequel::Privacy::Unauthorized,
-                "Cannot #{method_name} with OmniscientVC"
+                           "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, nil)
+            allowed = Sequel::Privacy::Enforcer.enforce(policies, self, vc)
 
             unless allowed
               Kernel.raise Sequel::Privacy::Unauthorized,
-                "Cannot #{method_name} on #{self.class}"
+                           "Cannot #{method_name} on #{self.class}"
             end
 
-            original.bind(self).call
+            original.bind(self).()
           end
         end
       end
@@ -614,21 +607,20 @@ module Sequel
         requires_ancestor { Sequel::Model }
         mixes_in_class_methods(ClassMethods)
 
-
         sig { returns(T.nilable(Sequel::Privacy::ViewerContext)) }
         def viewer_context
-          @viewer_context
+          @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 = vc
+          @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 = vc
+          @viewer_context = T.let(vc, T.nilable(Sequel::Privacy::ViewerContext))
           self
         end
 
@@ -646,45 +638,31 @@ module Sequel
           ).returns(T::Boolean)
         end
         def allow?(vc, action, direct_object = nil)
-          policies = T.unsafe(self.class).privacy_policies[action]
+          policies = _privacy_class.privacy_policies[action]
           unless policies
             Sequel::Privacy.logger&.error("No policies defined for :#{action} on #{self.class}")
             return false
           end
 
-          # Use InternalPolicyEvaluationVC during policy evaluation.
-          # This signals to association wrappers that they should return raw data
-          # without filtering, allowing policies to check things like "is actor a
-          # member of this list?" by accessing list.members without recursively
-          # checking each member's :view policy.
-          saved_vc = @viewer_context
-          @viewer_context = Sequel::Privacy::InternalPolicyEvaluationVC.new
-          begin
-            Sequel::Privacy::Enforcer.enforce(policies, self, vc, direct_object)
-          ensure
-            @viewer_context = saved_vc
-          end
+          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
+          vc = viewer_context
 
           if vc.is_a?(Sequel::Privacy::OmniscientVC)
-            Kernel.raise Sequel::Privacy::Unauthorized, "Cannot mutate with OmniscientVC"
+            Kernel.raise Sequel::Privacy::Unauthorized, 'Cannot mutate with OmniscientVC'
           end
 
           if vc
             action = new? ? :create : :edit
 
-            unless allow?(vc, action)
-              Kernel.raise Sequel::Privacy::Unauthorized, "Cannot #{action} #{self.class}"
-            end
+            Kernel.raise Sequel::Privacy::Unauthorized, "Cannot #{action} #{self.class}" unless allow?(vc, action)
 
-            # Check field-level policies on changed fields
             changed_columns.each do |field|
-              policy = T.unsafe(self.class).privacy_fields[field]
+              policy = _privacy_class.privacy_fields[field]
               next unless policy
 
               unless allow?(vc, policy)
@@ -700,14 +678,12 @@ module Sequel
         # Override update to check privacy policies
         sig { params(hash: T::Hash[Symbol, T.untyped]).returns(T.self_type) }
         def update(hash)
-          vc = @viewer_context
+          vc = viewer_context
           if vc
-            unless allow?(vc, :edit)
-              Kernel.raise Sequel::Privacy::Unauthorized, "Cannot edit #{self.class}"
-            end
+            Kernel.raise Sequel::Privacy::Unauthorized, "Cannot edit #{self.class}" unless allow?(vc, :edit)
 
             hash.each_key do |field|
-              policy = T.unsafe(self.class).privacy_fields[field]
+              policy = _privacy_class.privacy_fields[field]
               next unless policy
 
               unless allow?(vc, policy)
@@ -720,11 +696,21 @@ module Sequel
           super
         end
 
+        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).
+        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)
-            Kernel.raise Sequel::Privacy::Unauthorized, "Cannot delete with OmniscientVC"
+          if viewer_context.is_a?(Sequel::Privacy::OmniscientVC)
+            Kernel.raise Sequel::Privacy::Unauthorized, 'Cannot delete with OmniscientVC'
           end
           super
         end
@@ -751,13 +737,13 @@ module Sequel
           vc = opts[:viewer_context]
           return super unless vc
 
-          model_class = T.unsafe(model)
+          model_class = T.cast(model, ClassMethods)
           vc_key = model_class.privacy_vc_key
           proc do |values|
             old_vc = Thread.current[vc_key]
             Thread.current[vc_key] = vc
             begin
-              model_class.call(values)
+              model_class.(values)
             ensure
               Thread.current[vc_key] = old_vc
             end

data/lib/sequel/privacy/actions.rb

@@ -1,40 +1,50 @@
-# typed: ignore
+# typed: true
 # frozen_string_literal: true
 
 module Sequel
   module Privacy
     # Actions provides the DSL methods available inside policy lambdas.
-    # When policies are evaluated, they execute in the context of this struct,
+    # When policies are evaluated, they execute in the context of this object,
     # giving them access to allow, deny, pass, and all methods.
     #
     # Example:
     #   policy :AllowAdmins, ->(actor) {
     #     allow if actor.is_role?(:admin)
     #   }
-    Actions = (Struct.new do
-        extend T::Sig
+    class ActionsClass
+      extend T::Sig
 
-        sig { returns(Symbol) }
-        def allow
-          :allow
-        end
+      sig { returns(Symbol) }
+      def allow
+        :allow
+      end
 
-        sig { returns(Symbol) }
-        def deny
-          :deny
-        end
+      sig { returns(Symbol) }
+      def deny
+        :deny
+      end
 
-        sig { returns(Symbol) }
-        def pass
-          :pass
-        end
+      sig { returns(Symbol) }
+      def pass
+        :pass
+      end
 
-        # Combine multiple policies - all must allow for the result to allow.
-        # Any deny results in deny. Otherwise passes.
-        sig { params(policies: T.untyped).returns(T::Array[T.untyped]) }
-        def all(*policies)
-          policies
-        end
-      end).new
+      # Combine multiple policies - all must allow for the result to allow.
+      # Any deny results in deny. Otherwise passes.
+      sig { params(policies: T.untyped).returns(T::Array[T.untyped]) }
+      def all(*policies)
+        policies
+      end
+
+      # Evaluate a policy lambda in the DSL context. Wraps instance_exec so
+      # callers don't have to fight Sorbet's strict block-shape signatures
+      # for arbitrary-arity policies.
+      sig { params(args: T.untyped, blk: Proc).returns(T.untyped) }
+      def evaluate(*args, &blk)
+        T.unsafe(self).instance_exec(*args, &blk)
+      end
+    end
+
+    Actions = T.let(ActionsClass.new, ActionsClass)
   end
 end

data/lib/sequel/privacy/built_in_policies.rb

@@ -1,4 +1,4 @@
-# typed: false
+# typed: true
 # frozen_string_literal: true
 
 module Sequel

data/lib/sequel/privacy/enforcer.rb

@@ -8,6 +8,13 @@ module Sequel
     module Enforcer
       extend T::Sig
 
+      # Thread-local flag set while a policy chain is being evaluated.
+      # Implicit :view enforcement (Model.call, field readers, association
+      # readers) checks this flag and returns raw data when set, so policies
+      # can traverse protected fields and associations without recursive
+      # filtering. Explicit `allow?` calls always run regardless.
+      EVAL_KEY = :sequel_privacy_in_policy_eval
+
       class << self
         extend T::Sig
 
@@ -18,6 +25,11 @@ module Sequel
         end
       end
 
+      sig { returns(T::Boolean) }
+      def self.in_policy_eval?
+        Thread.current[EVAL_KEY] == true
+      end
+
       # Main entry point for policy evaluation.
       #
       # @param policies [Array<Policy, Proc>] The policy chain to evaluate
@@ -34,39 +46,44 @@ module Sequel
         ).returns(T::Boolean)
       end
       def self.enforce(policies, subject, viewer_context, direct_object = nil)
-        # 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
-        end
+        saved = Thread.current[EVAL_KEY]
+        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
+          end
 
-        if viewer_context.is_a?(OmniscientVC)
-          logger&.debug { "BYPASS: Omniscient viewer context (#{viewer_context.reason})" }
-          return true
-        end
+          if viewer_context.is_a?(OmniscientVC)
+            logger&.debug { "BYPASS: Omniscient viewer context (#{viewer_context.reason})" }
+            return true
+          end
 
-        actor = viewer_context.is_a?(ActorVC) ? viewer_context.actor : nil
+          actor = viewer_context.is_a?(ActorVC) ? viewer_context.actor : nil
 
-        # Ensure we have policies to evaluate
-        if policies.empty?
-          logger&.error { "No policies for #{subject.class}[#{subject_id(subject)}]. Denying by default." }
-          policies = [BuiltInPolicies::AlwaysDeny]
-        end
+          if policies.empty?
+            logger&.error { "No policies for #{subject.class}[#{subject_id(subject)}]. Denying by default." }
+            policies = [BuiltInPolicies::AlwaysDeny]
+          end
 
-        # Ensure policy chain ends with AlwaysDeny (fail-secure)
-        unless policies.last == BuiltInPolicies::AlwaysDeny
-          logger&.warn { 'Policy chain should end with AlwaysDeny. Appending it.' }
-          policies = policies.dup << BuiltInPolicies::AlwaysDeny
-        end
+          # Ensure policy chain ends with AlwaysDeny (fail-secure)
+          unless policies.last == BuiltInPolicies::AlwaysDeny
+            logger&.warn { 'Policy chain should end with AlwaysDeny. Appending it.' }
+            policies = policies.dup << BuiltInPolicies::AlwaysDeny
+          end
 
-        # Evaluate policies in order
-        policies.each do |uncasted_policy|
-          result = policy_result(uncasted_policy, subject, actor, viewer_context, direct_object)
-          return true if result == :allow
-          return false if result == :deny
-        end
+          policies.each do |uncasted_policy|
+            result = policy_result(uncasted_policy, subject, actor, viewer_context, direct_object)
+            return true if result == :allow
+            return false if result == :deny
+          end
 
-        false
+          false
+        ensure
+          Thread.current[EVAL_KEY] = saved
+        end
       end
 
       # Compute cache key based on policy arity
@@ -201,13 +218,13 @@ module Sequel
 
         case policy.arity
         when 0
-          Actions.instance_exec(&policy)
+          Actions.evaluate(&policy)
         when 1
-          Actions.instance_exec(subject, &policy)
+          Actions.evaluate(subject, &policy)
         when 2
-          Actions.instance_exec(subject, T.must(actor), &policy)
+          Actions.evaluate(subject, T.must(actor), &policy)
         else
-          Actions.instance_exec(subject, T.must(actor), direct_object, &policy)
+          Actions.evaluate(subject, T.must(actor), direct_object, &policy)
         end
       end
 

data/lib/sequel/privacy/policy.rb

@@ -21,11 +21,12 @@ module Sequel
       sig { returns(T.nilable(String)) }
       attr_reader :comment
 
-      # Factory method for creating policies
+      # 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,
-          lam: T.proc.returns(Symbol),
+          lam: Proc,
           comment: T.nilable(String),
           cacheable: T::Boolean,
           single_match: T::Boolean

data/lib/sequel/privacy/policy_dsl.rb

@@ -1,4 +1,4 @@
-# typed: false
+# typed: true
 # frozen_string_literal: true
 
 module Sequel
@@ -17,6 +17,13 @@ module Sequel
     #     }, 'Allow admin users', cacheable: true
     #   end
     module PolicyDSL
+      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`.
+      requires_ancestor { Module }
+
       # Define a new policy constant on the extending module.
       #
       # @param name [Symbol] The policy name (will become a constant)
@@ -24,6 +31,15 @@ module Sequel
       # @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)
+      sig do
+        params(
+          name: Symbol,
+          lam: Proc,
+          comment: T.nilable(String),
+          cacheable: T::Boolean,
+          single_match: T::Boolean
+        ).void
+      end
       def policy(name, lam, comment = nil, cacheable: true, single_match: false)
         p = Policy.new(&lam).setup(
           policy_name: name,

data/lib/sequel/privacy/version.rb

@@ -3,6 +3,6 @@
 
 module Sequel
   module Privacy
-    VERSION = '0.1.0'
+    VERSION = '0.2.1'
   end
 end

data/lib/sequel/privacy/viewer_context.rb

@@ -105,22 +105,6 @@ module Sequel
       end
     end
 
-    # Internal policy evaluation viewer context.
-    # Used internally during policy evaluation to allow raw association access
-    # without triggering recursive privacy checks. For example, when checking
-    # "is actor a member of this list?", we need to access list.members without
-    # filtering those members by their own :view policies.
-    #
-    # This class is internal to the privacy plugin and should not be used directly.
-    class InternalPolicyEvaluationVC < ViewerContext
-      extend T::Sig
-
-      sig { void }
-      def initialize
-        super()
-      end
-    end
-
     # Type alias for viewer contexts
     TViewerContext = T.type_alias { ViewerContext }
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sequel-privacy
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Austin Bales
@@ -116,7 +116,6 @@ files:
 - lib/sequel/privacy/policy_dsl.rb
 - lib/sequel/privacy/version.rb
 - lib/sequel/privacy/viewer_context.rb
-- rbi/sequel_privacy.rbi
 homepage: https://github.com/arbales/sequel-privacy
 licenses:
 - MIT

data/rbi/sequel_privacy.rbi

@@ -1,66 +0,0 @@
-# typed: true
-
-module Sequel
-  module Privacy
-    # Actions is a Struct instance used as the binding context for policy
-    # evaluation via instance_exec. Defined in actions.rb (typed: ignore).
-    class Actions
-      extend T::Sig
-
-      sig { returns(Symbol) }
-      def allow; end
-
-      sig { returns(Symbol) }
-      def deny; end
-
-      sig { returns(Symbol) }
-      def pass; end
-
-      sig { params(policies: T.untyped).returns(T::Array[T.untyped]) }
-      def all(*policies); end
-
-      sig {
-        params(
-          args: T.untyped,
-          block: Policy
-        ).returns(T.untyped)
-      }
-      def self.instance_exec(*args, &block); end
-    end
-
-    class PrivacyDSL
-      extend T::Sig
-
-      sig { params(action: Symbol, policies: T.untyped).void }
-      def can(action, *policies); end
-
-      sig { params(field_name: Symbol, policies: T.untyped).void }
-      def field(field_name, *policies); end
-
-      sig { params(association_name: Symbol, blk: T.proc.void).void }
-      def association(association_name, &blk); end
-    end
-  end
-
-  module Plugins
-    module Privacy
-      module ClassMethods
-        # The privacy block is evaluated in the context of PrivacyDSL
-        sig { params(blk: T.proc.bind(Sequel::Privacy::PrivacyDSL).void).void }
-        def privacy(&blk); end
-      end
-
-      module InstanceMethods
-        # Declare the @viewer_context instance variable for the mixin
-        sig { returns(T.nilable(Sequel::Privacy::ViewerContext)) }
-        attr_accessor :viewer_context
-      end
-
-      module DatasetMethods
-        # model is inherited from Sequel::Dataset but not visible to Sorbet
-        sig { returns(T.class_of(Sequel::Model)) }
-        def model; end
-      end
-    end
-  end
-end