sequel-privacy 0.2.1 → 0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04b5728dab12a15490535725e9458d1039e17049f47e839e724b5464b1e39ee5
-  data.tar.gz: ddb26ed4c76c15b672043d2ac32ff4573b791befc8c9f3b1d0405e0c4ddcd6ba
+  metadata.gz: 651aa5392073590a594f91df25458c4e2594ae6de3d8157b53525bfe210ebeef
+  data.tar.gz: 6addd80f151b6a1b272e5f70376ac41e18fd84e7a60cc77d68017d3c6b646dc6
 SHA512:
-  metadata.gz: 1b235a397d24fbfea16f557628554b5e64352a2872b54d9b51b36e81d13fe659be3b1a011e256626db7025dc7527b33e891866c116e4a1dbe4a03821209401c6
-  data.tar.gz: 105bb81dc55bb0970a224682c7ab30117758e882db8acac968802da1ed0fa06bd29145350d9de196dda2f6b5d0f81b7c58433e1107317ab8f4b7d297a5ee2c53
+  metadata.gz: cb083193065e4d0929beb64dc3f51029e375861d42f5800da2218a3699b1adcd37c16aea5dc55f3cce0d250322967bed98f3c2e53119a693d8e7e9f0111bdab6
+  data.tar.gz: 83840dfe5cded9036995df6371c083c9ab72e983f0c3de1eee69ff7a6b56b0b4e00c3ede0c6225e71669ce3bb14d981f08095c49153c5e75bacf6ee6896c072f

data/README.md

@@ -31,23 +31,26 @@ module P
   AlwaysAllow = Sequel::Privacy::BuiltInPolicies::AlwaysAllow
   PassAndLog = Sequel::Privacy::BuiltInPolicies::PassAndLog
 
-  policy :AllowIfPublished, ->(subject) {
+  # State-gate policies examine only the subject. Declare
+  # `allow_anonymous: true` so logged-out viewers can still pass.
+  policy :AllowIfPublished, ->(_actor, subject) {
     allow if subject.published
-  }
+  }, allow_anonymous: true, cache_by: :subject
 
-  policy :AllowAdmins, ->(_subject, actor) {
+  # Actor-only role checks — cheap because they cache per-actor.
+  policy :AllowAdmins, ->(actor) {
     allow if actor.is_role?(:admin)
   }, 'Allow admin users', cacheable: true
-  
-  policy :AllowMembers, ->(_subject, actor) {
+
+  policy :AllowMembers, ->(actor) {
     allow if actor.is_role?(:member)
   }, cacheable: true
 
-  policy :AllowSelf, ->(subject, actor) {
+  policy :AllowSelf, ->(actor, subject) {
     allow if subject == actor
-  }, 'Allow if subject is the actor', single_match: true  
-  
-  policy :AllowFriendsOfSubject, ->(subject, actor) {
+  }, 'Allow if subject is the actor', single_match: true
+
+  policy :AllowFriendsOfSubject, ->(actor, subject) {
     allow if subject.includes_friend?(actor)
   }
 end
@@ -107,28 +110,34 @@ 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` 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 **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?"
 
-Policies accept up to three parameters: `actor`, `subject` & `actor` or `subject`, `actor` and `direct_object`. 
+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.
 
 
 ```ruby
 
 policy :AlwaysAllow, -> { allow }
 
-policy :AllowIfPublished, ->(subject) {
+policy :AllowIfPublished, ->(_actor, subject) {
   allow if subject.published
-}
+}, allow_anonymous: true, cache_by: :subject
 
-policy :AllowAdmins, ->(_subject, actor) {
+policy :AllowAdmins, ->(actor) {
   allow if actor.is_role?(:admin)
 }
 
-policy :AllowOwner, ->(_subject, actor) {
+policy :AllowOwner, ->(actor, subject) {
   allow if subject.owner_id == actor.id
 }
 
-policy :AllowIfDirectObjectIsActor, ->(_subject, actor, direct_object) {
+policy :AllowIfDirectObjectIsActor, ->(actor, _subject, direct_object) {
   allow if actor.id == direct_object.id
 }
 
@@ -141,14 +150,14 @@ different modules.
 module P
   module Groups
     extend Sequel::Privacy::PolicyDSL
-    
-    policy :AllowIfOpen, -> (subject, _actor) {
+
+    policy :AllowIfOpen, ->(_actor, subject) {
       allow if subject.open?
-    }
-    
-    policy :AllowIfMember, -> (subject, actor) {
+    }, allow_anonymous: true, cache_by: :subject
+
+    policy :AllowIfMember, ->(actor, subject) {
       allow if subject.includes_member? actor
-    }      
+    }
   end
 end
 ```
@@ -159,25 +168,31 @@ end
 policy :MyPolicy, ->() { ... },
   'Human-readable description',  # For logging
   cacheable: true,               # Cache results (default: true)
-  single_match: false            # Only one subject can match
+  single_match: false,           # Only one subject can match
+  cache_by: :actor,              # Override cache-key dimensions
+  allow_anonymous: false         # Allow nil actor (opts out of auto-deny)
 ```
 
 **`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 other, 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.
+
+**`allow_anonymous: true`**: Skip the auto-deny for nil actor. Use for state-gate policies that examine only the subject (e.g. "post is published").
 
 ### Policy Combinators
 
 Use `all()` to require multiple conditions:
 
 ```ruby
-policy :AllowAddSelfToOpenGroup, ->(subject, actor, direct_object) {
+policy :AllowAddSelfToOpenGroup, ->(actor, subject, direct_object) {
   all(
-    P::AllowIfGroupIsOpen    
+    P::AllowIfGroupIsOpen,
     P::AllowIfDirectObjectIsActor
   )
 }
-policy :AllowRemoveSelf, ->(subject, actor, direct_object) {
+policy :AllowRemoveSelf, ->(actor, subject, direct_object) {
   all(
     P::AllowIfIncludesMember,
     P::AllowIfDirectObjectIsActor
@@ -308,25 +323,25 @@ 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 receive `(subject, actor, direct_object)`:
-- `subject` - The model instance (e.g., the group)
+Association policies receive `(actor, subject, direct_object)`:
 - `actor` - The current user from the viewer context
+- `subject` - The model instance (e.g., the group)
 - `direct_object` - The object being added/removed (e.g., the user being added to the group)
 
 For `remove_all`, the direct object is `nil` since there's no specific target.
 
 ```ruby
 # Allow users to add/remove themselves
-policy :AllowSelfJoin, ->(_subject, actor, direct_object) {
+policy :AllowSelfJoin, ->(actor, _subject, direct_object) {
   allow if actor.id == direct_object.id
 }, single_match: true
 
-policy :AllowSelfRemove, ->(_subject, actor, direct_object) {
+policy :AllowSelfRemove, ->(actor, _subject, direct_object) {
   allow if actor.id == direct_object.id
 }, single_match: true
 
 # Allow group admins to add/remove anyone
-policy :AllowGroupAdmin, ->(subject, actor, direct_object) {
+policy :AllowGroupAdmin, ->(actor, subject, _direct_object) {
   allow if subject.includes_admin?(actor)
 }
 ```

data/lib/sequel/plugins/privacy.rb

@@ -302,6 +302,8 @@ module Sequel
             vc = instance_variable_get(:@viewer_context)
 
             unless vc
+              return original_method.bind(self).() if T.unsafe(self.class).allow_unsafe_access?
+
               Kernel.raise Sequel::Privacy::MissingViewerContext,
                            "#{self.class}##{field} requires a ViewerContext"
             end
@@ -518,6 +520,8 @@ module Sequel
             vc = instance_variable_get(:@viewer_context)
 
             unless vc
+              return original.bind(self).(obj) if T.unsafe(self.class).allow_unsafe_access?
+
               Kernel.raise Sequel::Privacy::MissingViewerContext,
                            "Cannot #{method_name} without a viewer context"
             end
@@ -548,6 +552,8 @@ module Sequel
             vc = instance_variable_get(:@viewer_context)
 
             unless vc
+              return original.bind(self).(obj) if T.unsafe(self.class).allow_unsafe_access?
+
               Kernel.raise Sequel::Privacy::MissingViewerContext,
                            "Cannot #{method_name} without a viewer context"
             end
@@ -578,6 +584,8 @@ module Sequel
             vc = instance_variable_get(:@viewer_context)
 
             unless vc
+              return original.bind(self).() if T.unsafe(self.class).allow_unsafe_access?
+
               Kernel.raise Sequel::Privacy::MissingViewerContext,
                            "Cannot #{method_name} without a viewer context"
             end

data/lib/sequel/privacy/built_in_policies.rb

@@ -25,7 +25,7 @@ module Sequel
       # Pass and log - useful for debugging policy chains.
       PassAndLog = Policy.create(
         :PassAndLog,
-        ->(subject, actor) {
+        ->(actor, subject) {
           Sequel::Privacy::Enforcer.logger&.info("PassAndLog: #{subject.class} for actor #{actor.id}")
           :pass
         },

data/lib/sequel/privacy/enforcer.rb

@@ -97,15 +97,27 @@ module Sequel
         ).returns(Integer)
       end
       def self.compute_cache_key(policy, subject, actor, viewer_context, direct_object)
+        if (keys = policy.cache_by)
+          parts = T.let([policy, viewer_context], T::Array[T.untyped])
+          keys.each do |k|
+            parts << case k
+                     when :actor then actor
+                     when :subject then subject
+                     when :direct_object then direct_object
+                     end
+          end
+          return parts.hash
+        end
+
         case policy.arity
         when 0
           [policy, viewer_context].hash
         when 1
-          [policy, subject, viewer_context].hash
+          [policy, actor, viewer_context].hash
         when 2
-          [policy, subject, actor, viewer_context].hash
+          [policy, actor, subject, viewer_context].hash
         else
-          [policy, subject, actor, direct_object, viewer_context].hash
+          [policy, actor, subject, direct_object, viewer_context].hash
         end
       end
 
@@ -211,8 +223,11 @@ module Sequel
         ).returns(T.untyped)
       end
       def self.execute_policy(policy, subject, actor, direct_object)
-        # 2+ arity policies require actor - auto-deny for anonymous
-        if !actor && policy.arity >= 2
+        # 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
 
@@ -220,11 +235,11 @@ module Sequel
         when 0
           Actions.evaluate(&policy)
         when 1
-          Actions.evaluate(subject, &policy)
+          Actions.evaluate(actor, &policy)
         when 2
-          Actions.evaluate(subject, T.must(actor), &policy)
+          Actions.evaluate(actor, subject, &policy)
         else
-          Actions.evaluate(subject, T.must(actor), direct_object, &policy)
+          Actions.evaluate(actor, subject, direct_object, &policy)
         end
       end
 

data/lib/sequel/privacy/policy.rb

@@ -5,11 +5,15 @@ module Sequel
   module Privacy
     # A Policy wraps a Proc/lambda with metadata about how it should be evaluated.
     #
-    # Policies take 0-3 arguments depending on what context they need:
-    # - 0 args: -> { allow }  # Global decision
+    # Policies are actor-first. Arities map to:
+    # - 0 args: -> { allow if Time.now.sunday? }     # Global decision
     # - 1 arg:  ->(actor) { allow if actor.is_role?(:admin) }
-    # - 2 args: ->(subject, actor) { allow if subject.owner_id == actor.id }
-    # - 3 args: ->(subject, actor, direct_object) { ... }
+    # - 2 args: ->(actor, subject) { allow if subject.owner_id == actor.id }
+    # - 3 args: ->(actor, subject, direct_object) { ... }
+    #
+    # Any policy with arity >= 1 auto-denies for anonymous viewers (nil actor)
+    # unless declared with `allow_anonymous: true`. That flag is for state-gate
+    # policies that deliberately ignore actor — e.g. "post is published."
     #
     # Policies must return :allow, :deny, :pass, or an array of policies (for combinators).
     class Policy < Proc
@@ -21,6 +25,8 @@ module Sequel
       sig { returns(T.nilable(String)) }
       attr_reader :comment
 
+      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
@@ -29,15 +35,20 @@ module Sequel
           lam: Proc,
           comment: T.nilable(String),
           cacheable: T::Boolean,
-          single_match: T::Boolean
+          single_match: T::Boolean,
+          cache_by: T.nilable(T.any(Symbol, T::Array[Symbol])),
+          allow_anonymous: T::Boolean
         ).returns(T.self_type)
       end
-      def self.create(policy_name, lam, comment = nil, cacheable: true, single_match: false)
+      def self.create(policy_name, lam, comment = nil, cacheable: true, single_match: false, cache_by: nil,
+                      allow_anonymous: false)
         new(&lam).setup(
           policy_name: policy_name,
           comment: comment,
           cacheable: cacheable,
-          single_match: single_match
+          single_match: single_match,
+          cache_by: cache_by,
+          allow_anonymous: allow_anonymous
         )
       end
 
@@ -47,7 +58,20 @@ module Sequel
       # @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)
-      def setup(policy_name: nil, comment: nil, cacheable: true, single_match: 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
+      #   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.
+      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
 
         @cacheable = cacheable
@@ -55,6 +79,8 @@ module Sequel
         @comment = comment
         @frozen = true
         @single_match = single_match
+        @cache_by = normalize_cache_by(cache_by)
+        @allow_anonymous = allow_anonymous
         self
       end
 
@@ -69,6 +95,32 @@ module Sequel
       def single_match?
         @single_match || false
       end
+
+      sig { returns(T.nilable(T::Array[Symbol])) }
+      def cache_by
+        @cache_by
+      end
+
+      sig { returns(T::Boolean) }
+      def allow_anonymous?
+        @allow_anonymous || false
+      end
+
+      private
+
+      sig { params(val: T.nilable(T.any(Symbol, T::Array[Symbol]))).returns(T.nilable(T::Array[Symbol])) }
+      def normalize_cache_by(val)
+        return nil if val.nil?
+
+        keys = Array(val).map(&:to_sym)
+        invalid = keys - VALID_CACHE_BY
+        unless invalid.empty?
+          raise ArgumentError,
+                "Invalid cache_by key(s): #{invalid.inspect}. Valid keys: #{VALID_CACHE_BY.inspect}"
+        end
+
+        keys
+      end
     end
   end
 end

data/lib/sequel/privacy/policy_dsl.rb

@@ -31,21 +31,30 @@ 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)
+      # @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.
       sig do
         params(
           name: Symbol,
           lam: Proc,
           comment: T.nilable(String),
           cacheable: T::Boolean,
-          single_match: T::Boolean
+          single_match: T::Boolean,
+          cache_by: T.nilable(T.any(Symbol, T::Array[Symbol])),
+          allow_anonymous: T::Boolean
         ).void
       end
-      def policy(name, lam, comment = nil, cacheable: true, single_match: false)
+      def policy(name, lam, comment = nil, cacheable: true, single_match: false, cache_by: nil,
+                 allow_anonymous: false)
         p = Policy.new(&lam).setup(
           policy_name: name,
           comment: comment,
           cacheable: cacheable,
-          single_match: single_match
+          single_match: single_match,
+          cache_by: cache_by,
+          allow_anonymous: allow_anonymous
         )
         const_set(name, p)
       end

data/lib/sequel/privacy/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sequel-privacy
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: '0.4'
 platform: ruby
 authors:
 - Austin Bales