sequel-privacy 0.1.0

data/lib/sequel/privacy/actions.rb

@@ -0,0 +1,40 @@
+# typed: ignore
+# 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,
+    # 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
+
+        sig { returns(Symbol) }
+        def allow
+          :allow
+        end
+
+        sig { returns(Symbol) }
+        def deny
+          :deny
+        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
+  end
+end

data/lib/sequel/privacy/built_in_policies.rb

@@ -0,0 +1,37 @@
+# typed: false
+# frozen_string_literal: true
+
+module Sequel
+  module Privacy
+    # Built-in policies that ship with the gem.
+    # Applications should define their own policies using PolicyDSL.
+    module BuiltInPolicies
+      # Always deny access. Should be the last policy in every chain (fail-secure).
+      AlwaysDeny = Policy.create(
+        :AlwaysDeny,
+        -> { :deny },
+        'In the absence of other rules, this content is hidden.',
+        cacheable: true
+      )
+
+      # Always allow access. Use sparingly.
+      AlwaysAllow = Policy.create(
+        :AlwaysAllow,
+        -> { :allow },
+        'Always allow access.',
+        cacheable: true
+      )
+
+      # Pass and log - useful for debugging policy chains.
+      PassAndLog = Policy.create(
+        :PassAndLog,
+        ->(subject, actor) {
+          Sequel::Privacy::Enforcer.logger&.info("PassAndLog: #{subject.class} for actor #{actor.id}")
+          :pass
+        },
+        'Log and pass to next policy.',
+        cacheable: false
+      )
+    end
+  end
+end

data/lib/sequel/privacy/cache.rb

@@ -0,0 +1,33 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Sequel
+  module Privacy
+    # In-memory cache for policy evaluation results.
+    # Should be cleared between requests (e.g., via Rack middleware).
+    class << self
+      extend T::Sig
+
+      # Returns the in-memory cache Hash for policy results.
+      sig { returns(T::Hash[Integer, Symbol]) }
+      def cache
+        @cache ||= T.let({}, T.nilable(T::Hash[Integer, Symbol]))
+      end
+
+      # Returns the hash tracking single-match optimizations.
+      # Key: [policy, actor, viewer_context].hash
+      # Value: subject.hash that matched
+      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 = {}
+        @single_matches = {}
+      end
+    end
+  end
+end

data/lib/sequel/privacy/enforcer.rb

@@ -0,0 +1,246 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Sequel
+  module Privacy
+    # The Enforcer evaluates policy chains to determine if an action is allowed.
+    # It handles caching, single-match optimization, and policy combinators.
+    module Enforcer
+      extend T::Sig
+
+      class << self
+        extend T::Sig
+
+        # Returns the centralized logger from Sequel::Privacy.logger
+        sig { returns(T.untyped) }
+        def logger
+          Sequel::Privacy.logger
+        end
+      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
+      sig do
+        params(
+          policies: TPolicyArray,
+          subject: TPolicySubject,
+          viewer_context: TViewerContext,
+          direct_object: T.nilable(Sequel::Model)
+        ).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
+
+        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
+
+        # 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
+
+        # 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
+
+        false
+      end
+
+      # Compute cache key based on policy arity
+      sig do
+        params(
+          policy: Policy,
+          subject: TPolicySubject,
+          actor: T.nilable(IActor),
+          viewer_context: ViewerContext,
+          direct_object: T.nilable(Sequel::Model)
+        ).returns(Integer)
+      end
+      def self.compute_cache_key(policy, subject, actor, viewer_context, direct_object)
+        case policy.arity
+        when 0
+          [policy, viewer_context].hash
+        when 1
+          [policy, subject, viewer_context].hash
+        when 2
+          [policy, subject, actor, viewer_context].hash
+        else
+          [policy, subject, actor, direct_object, viewer_context].hash
+        end
+      end
+
+      sig { params(outcome: Symbol).returns(T::Boolean) }
+      def self.valid_outcome?(outcome)
+        %i[allow pass deny].include?(outcome)
+      end
+
+      # Evaluate a combinator (array of policies returned by `all()`)
+      # All must allow for the result to be :allow, any :deny results in :deny
+      sig do
+        params(
+          child_policies: TPolicyArray,
+          subject: TPolicySubject,
+          actor: T.nilable(IActor),
+          viewer_context: ViewerContext,
+          direct_object: T.nilable(Sequel::Model)
+        ).returns(Symbol)
+      end
+      def self.evaluate_child_policies(child_policies, subject, actor, viewer_context, direct_object)
+        unless child_policies.all? { |c| c.is_a?(Proc) }
+          Kernel.raise "Policy combinator contains non-policy members"
+        end
+
+        results = child_policies.map do |child_policy|
+          policy_result(child_policy, subject, actor, viewer_context, direct_object)
+        end
+
+        return :deny if results.include?(:deny)
+        return :allow if results.all? { |r| r == :allow }
+
+        :pass
+      end
+
+      # Evaluate a single policy and return its result
+      sig do
+        params(
+          uncasted_policy: T.any(TPolicy, Proc),
+          subject: TPolicySubject,
+          actor: T.nilable(IActor),
+          viewer_context: ViewerContext,
+          direct_object: T.nilable(Sequel::Model)
+        ).returns(Symbol)
+      end
+      def self.policy_result(uncasted_policy, subject, actor, viewer_context, direct_object)
+        from_cache = false
+        skipped_from_single_match = false
+
+        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
+            skipped_from_single_match = true
+            result = :pass
+          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
+          result = Sequel::Privacy.cache[cache_key]
+          Kernel.raise InvalidPolicyOutcomeError unless result && valid_outcome?(result)
+        end
+
+        # Execute policy if not cached
+        result ||= execute_policy(policy, subject, actor, direct_object)
+        result ||= :pass
+
+        # Handle combinator results
+        if result.is_a?(Array)
+          result = evaluate_child_policies(result, subject, actor, viewer_context, direct_object)
+        end
+
+        # Cache result
+        if policy.cacheable? && !from_cache
+          Sequel::Privacy.cache[cache_key] = result
+        end
+
+        # 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
+
+        unless valid_outcome?(result)
+          Kernel.raise InvalidPolicyOutcomeError, "Policy returned #{result.inspect}, expected :allow, :deny, or :pass"
+        end
+
+        result
+      end
+
+      sig do
+        params(
+          policy: Policy,
+          subject: TPolicySubject,
+          actor: T.nilable(IActor),
+          direct_object: T.nilable(Sequel::Model)
+        ).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
+          return :deny
+        end
+
+        case policy.arity
+        when 0
+          Actions.instance_exec(&policy)
+        when 1
+          Actions.instance_exec(subject, &policy)
+        when 2
+          Actions.instance_exec(subject, T.must(actor), &policy)
+        else
+          Actions.instance_exec(subject, T.must(actor), direct_object, &policy)
+        end
+      end
+
+      sig do
+        params(
+          policy: Policy,
+          result: Symbol,
+          actor: T.nilable(IActor),
+          subject: TPolicySubject,
+          from_cache: T::Boolean,
+          skipped: T::Boolean
+        ).void
+      end
+      def self.log_result(policy, result, actor, subject, from_cache, skipped)
+        return unless logger
+
+        actor_id = actor ? actor.id : 'anonymous'
+        logger.debug do
+          msg = "#{result.to_s.upcase}: #{policy.policy_name || 'anonymous'} for actor[#{actor_id}] on #{subject.class}[#{subject_id(subject)}]"
+          msg += " (cached)" if from_cache
+          msg += " (skipped: single_match)" if skipped
+          msg
+        end
+
+        if policy.comment && %i[deny allow].include?(result)
+          logger.debug { " ⮑  #{policy.comment}" }
+        end
+      end
+
+      sig { params(subject: TPolicySubject).returns(T.untyped) }
+      def self.subject_id(subject)
+        subject.respond_to?(:pk) ? subject.pk : subject.object_id
+      end
+    end
+  end
+end

data/lib/sequel/privacy/errors.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Sequel
+  module Privacy
+    # Raised when a viewer is not authorized to perform an action (view, edit, create)
+    class Unauthorized < StandardError; end
+
+    # Raised when a viewer is not authorized to access or modify a specific field
+    class FieldUnauthorized < StandardError; end
+
+    # Raised when a policy returns an invalid outcome
+    class InvalidPolicyOutcomeError < StandardError; end
+
+    # Raised when an invalid viewer context is used
+    class InvalidViewerContextError < StandardError; end
+
+    class MissingViewerContext < StandardError; end
+
+    # Raised when attempting to modify privacy settings after finalization
+    class PrivacyAlreadyFinalizedError < StandardError; end
+  end
+end

data/lib/sequel/privacy/i_actor.rb

@@ -0,0 +1,17 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Sequel
+  module Privacy
+    # Interface that actors (typically User/Member models) must implement
+    # to be used with the privacy system.
+    module IActor
+      extend T::Sig
+      extend T::Helpers
+      interface!
+
+      sig { abstract.returns(Integer) }
+      def id; end
+    end
+  end
+end

data/lib/sequel/privacy/policy.rb

@@ -0,0 +1,82 @@
+# typed: true
+# frozen_string_literal: true
+
+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
+    # - 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) { ... }
+    #
+    # Policies must return :allow, :deny, :pass, or an array of policies (for combinators).
+    class Policy < Proc
+      extend T::Sig
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :policy_name
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :comment
+
+      # Factory method for creating policies
+      sig do
+        params(
+          policy_name: Symbol,
+          lam: T.proc.returns(Symbol),
+          comment: T.nilable(String),
+          cacheable: T::Boolean,
+          single_match: T::Boolean
+        ).returns(T.self_type)
+      end
+      def self.create(policy_name, lam, comment = nil, cacheable: true, single_match: false)
+        new(&lam).setup(
+          policy_name: policy_name,
+          comment: comment,
+          cacheable: cacheable,
+          single_match: single_match
+        )
+      end
+
+      # Configure the policy after creation
+      #
+      # @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)
+      def setup(policy_name: nil, comment: nil, cacheable: true, single_match: false)
+        raise 'Privacy Policy is frozen' if @frozen
+
+        @cacheable = cacheable
+        @policy_name = policy_name.to_s
+        @comment = comment
+        @frozen = true
+        @single_match = single_match
+        self
+      end
+
+      sig { returns(T::Boolean) }
+      def cacheable?
+        @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)
+      sig { returns(T::Boolean) }
+      def single_match?
+        @single_match || false
+      end
+    end
+  end
+end
+
+# Type aliases for use throughout the gem
+module Sequel
+  module Privacy
+    TPolicy = T.type_alias { Sequel::Privacy::Policy }
+    TPolicyArray = T.type_alias { T::Array[T.any(TPolicy, Proc)] }
+    TPolicySubject = T.type_alias { T.any(Sequel::Model, T.untyped) }
+  end
+end

data/lib/sequel/privacy/policy_dsl.rb

@@ -0,0 +1,38 @@
+# typed: false
+# frozen_string_literal: true
+
+module Sequel
+  module Privacy
+    # DSL for defining custom policies.
+    # Extend your policy module with this to get the `policy` method.
+    #
+    # Example:
+    #   module P
+    #     extend Sequel::Privacy::PolicyDSL
+    #
+    #     AlwaysDeny = Sequel::Privacy::BuiltInPolicies::AlwaysDeny
+    #
+    #     policy :AllowAdmins, ->(actor) {
+    #       allow if actor.is_role?(:admin)
+    #     }, 'Allow admin users', cacheable: true
+    #   end
+    module PolicyDSL
+      # 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)
+      def policy(name, lam, comment = nil, cacheable: true, single_match: false)
+        p = Policy.new(&lam).setup(
+          policy_name: name,
+          comment: comment,
+          cacheable: cacheable,
+          single_match: single_match
+        )
+        const_set(name, p)
+      end
+    end
+  end
+end

data/lib/sequel/privacy/version.rb

@@ -0,0 +1,8 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Sequel
+  module Privacy
+    VERSION = '0.1.0'
+  end
+end

data/lib/sequel/privacy/viewer_context.rb

@@ -0,0 +1,127 @@
+# typed: strict
+# frozen_string_literal: true
+
+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.
+    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.
+      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.
+      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.
+      sig { returns(AnonymousVC) }
+      def self.anonymous
+        AnonymousVC.new
+      end
+    end
+
+    # Standard viewer context with an actor (user/member)
+    class ActorVC < ViewerContext
+      extend T::Sig
+
+      sig { params(actor: IActor).void }
+      def initialize(actor)
+        @actor = T.let(actor, IActor)
+        super()
+      end
+
+      sig { returns(IActor) }
+      attr_reader :actor
+    end
+
+    # API-specific viewer context (same as ActorVC but can be distinguished)
+    class APIVC < ActorVC; end
+
+    # All-powerful viewer context that bypasses all privacy checks.
+    # Used for admin operations, background jobs, etc.
+    # Requires a reason for audit logging.
+    class AllPowerfulVC < ViewerContext
+      extend T::Sig
+
+      sig { params(reason: Symbol).void }
+      def initialize(reason)
+        @reason = T.let(reason, Symbol)
+        super()
+      end
+
+      sig { returns(Symbol) }
+      attr_reader :reason
+    end
+
+    # Omniscient viewer context that can see everything but cannot mutate.
+    # Used for system operations like authentication lookups.
+    class OmniscientVC < ViewerContext
+      extend T::Sig
+
+      sig { params(reason: Symbol).void }
+      def initialize(reason)
+        @reason = T.let(reason, Symbol)
+        super()
+      end
+
+      sig { returns(Symbol) }
+      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
+
+      sig { void }
+      def initialize
+        super()
+      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
+end

data/lib/sequel-privacy.rb

@@ -0,0 +1,33 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sequel'
+require 'sorbet-runtime'
+
+module Sequel
+  module Privacy
+    class << self
+      extend T::Sig
+
+      # Configurable logger for privacy enforcement.
+      # 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'
+require_relative 'sequel/privacy/policy'
+require_relative 'sequel/privacy/cache'
+require_relative 'sequel/privacy/actions'
+require_relative 'sequel/privacy/viewer_context'
+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