permission_forge 0.14.1

data/lib/permission_forge/services/permission_hash_builder.rb

@@ -0,0 +1,305 @@
+module PermissionForge
+  module Services
+    # Builds a merged permission hash for a user across multiple permission sets.
+    # Uses most-permissive-wins logic for CRUD/boolean flags and AND logic for masks.
+    # Muting permission sets subtract permissions after granting sets are merged.
+    # Field rows are merged by {FieldPermissionMerger}; the implicit entries of
+    # extra (virtual) fields are added by {ExtraFieldDefaults}.
+    #
+    # Every row a build reads is loaded up front, one query per table
+    # (#load_permission_rows): the sets' resources with their fields, actions
+    # and rules, active or not, and the user's assignment of each set with
+    # the people who granted and last changed it. Inactive rows are skipped in
+    # Ruby (`select(&:is_active)`) — the `active` scope would query again, per
+    # resource. Each holder of a set rebuilds after any edit to it, so a
+    # build must not cost a query per resource.
+    #
+    # @example
+    #   data = PermissionHashBuilder.call(user: user, permission_sets: user.permission_sets.active)
+    #   # => { resources: { Customer: { permissions: { read_access: true, ... }, fields: {...}, ... } } }
+    #
+    # @api public
+    class PermissionHashBuilder
+      RESOURCE_PERMISSION_OPTIONS = %i[read_access create_access edit_access delete_access view_all modify_all].freeze
+      # The rows each resource brings into the hash (#load_permission_rows).
+      RESOURCE_ROWS = %i[resource_fields resource_actions permission_set_rules].freeze
+      # The columns naming who granted and last changed an assignment (HasAuditTrail).
+      GRANTOR_KEYS = %w[created_by_id updated_by_id].freeze
+
+      # Resources and their rows in id order, in place. The database returns
+      # them in whatever order its plan gives, and order decides: the first row
+      # of a name wins a tie (two fields mapping to one variant — "first
+      # mask_strategy wins"), and rules and actions keep it in the hash. The one
+      # definition: Admin::EffectiveAccess sorts the rows it shows with it. An
+      # unsaved row (no id yet) sorts first.
+      def self.sort_rows(permission_set)
+        resources = sorted(permission_set.association(:resources))
+        resources.each { |resource| RESOURCE_ROWS.each { |rows| sorted(resource.association(rows)) } }
+      end
+
+      def self.sorted(association)
+        association.target.sort_by! { |row| row.id.to_i }
+      end
+      private_class_method :sorted
+
+      # Builds a user's permission hash from their permission sets.
+      # @param user [Object]
+      # @param permission_sets [Enumerable<PermissionSet>]
+      # @return [Hash]
+      def self.call(user:, permission_sets:)
+        new(user: user, permission_sets: permission_sets).call
+      end
+
+      def initialize(user:, permission_sets:)
+        @user = user
+        @permission_sets = permission_sets
+      end
+
+      # @return [Hash] the permission hash (the format is in the architecture guide)
+      def call
+        data = { resources: {} }
+        load_permission_rows
+
+        granting_sets, muting_sets = partition_permission_sets
+
+        granting_sets.each { |ps| process_permission_set(data, ps) }
+        add_extra_field_defaults(data)
+        muting_sets.each { |ps| apply_muting_permission_set(data, ps) }
+
+        data
+      end
+
+      private
+
+      def partition_permission_sets
+        @permission_sets.partition { |ps| !ps.is_muting }
+      end
+
+      # --- Loading (every row of the build, one query per table) ---
+
+      # The sets in the order given (created_at, id: "first mask_strategy
+      # wins" depends on it), each with its resources and their rows loaded.
+      def load_permission_rows
+        @permission_sets = @permission_sets.to_a
+        preload(@permission_sets, resources: RESOURCE_ROWS)
+        @permission_sets.each { |permission_set| self.class.sort_rows(permission_set) }
+        @assignments = assignments_by_set
+      end
+
+      # The user's assignment of each set (any row of the pair, as find_by
+      # would answer), with its grantors.
+      def assignments_by_set
+        return {} if @permission_sets.empty?
+
+        assignments = PermissionForge::PermissionSetUser.where(user_id: @user.id, permission_set_id: @permission_sets.map(&:id)).to_a
+        preload_grantors(assignments)
+        assignments.each_with_object({}) { |assignment, by_set| by_set[assignment.permission_set_id] ||= assignment }
+      end
+
+      # Only where an assignment names one: preloading builds the user
+      # model's scope — its default scopes run — even for no id at all, which
+      # the association readers never did.
+      def preload_grantors(assignments)
+        stamped = assignments.select { |assignment| GRANTOR_KEYS.any? { |key| assignment[key] } }
+        preload(stamped, %i[created_by updated_by]) if stamped.any?
+      end
+
+      def preload(records, associations)
+        ActiveRecord::Associations::Preloader.new(records: records, associations: associations).call
+      end
+
+      # --- Granting logic (additive, most-permissive-wins) ---
+
+      def process_permission_set(data, permission_set)
+        permission_set.resources.select(&:is_active).each do |resource|
+          process_resource(data, permission_set, resource)
+        end
+      end
+
+      def process_resource(data, permission_set, resource)
+        return unless resource.is_active
+
+        resource_data = init_resource_data(data, resource.name)
+
+        add_source_permission_set(resource_data[:source_permission_sets], permission_set)
+        merge_resource_permissions(resource_data[:permissions], resource)
+        FieldPermissionMerger.call(fields: resource_data[:fields], resource: resource)
+        merge_resource_actions(resource_data[:actions], resource)
+        merge_permission_set_rules(resource_data[:permission_set_rules], resource)
+      end
+
+      # Once per resource, after every granting set and before muting: a
+      # ResourceField row in any of the user's sets wins over the implicit
+      # grant, whichever set is older, and the grant follows the resource's
+      # merged read and edit.
+      def add_extra_field_defaults(data)
+        data[:resources].each do |name, resource_data|
+          ExtraFieldDefaults.call(entry: resource_data, resource_name: name)
+        end
+      end
+
+      def init_resource_data(data, name)
+        data[:resources][name] ||= {
+          permissions: {},
+          fields: {},
+          actions: {},
+          source_permission_sets: [],
+          permission_set_rules: []
+        }
+      end
+
+      def add_source_permission_set(source_permission_sets, permission_set)
+        permission_set_user = @assignments[permission_set.id]
+
+        source_permission_sets << {
+          uuid: permission_set.uuid,
+          name: permission_set.name,
+          is_muting: permission_set.is_muting,
+          permission_set_granted_by: user_reference(permission_set_user&.created_by),
+          permission_set_granted_updated_by: user_reference(permission_set_user&.updated_by),
+          permission_set_granted_at: permission_set_user&.created_at,
+          permission_set_granted_updated_at: permission_set_user&.updated_at
+        }
+      end
+
+      # Who granted or last changed an assignment: the person's uuid when the
+      # audit user model has one, else their id. Nothing asks a host user
+      # model for a uuid column.
+      def user_reference(user)
+        return unless user
+
+        user.respond_to?(:uuid) ? user.uuid : user.id
+      end
+
+      def merge_resource_permissions(permissions, resource)
+        RESOURCE_PERMISSION_OPTIONS.each do |action|
+          permissions[action] ||= resource.send(action)
+        end
+      end
+
+      def merge_resource_actions(actions, resource)
+        resource.resource_actions.select(&:is_active).each do |action|
+          key = action.name.to_sym
+          if actions.key?(key)
+            actions[key][:is_permitted] ||= action.is_permitted
+          else
+            actions[key] = { is_permitted: action.is_permitted }
+          end
+        end
+      end
+
+      def merge_permission_set_rules(permission_set_rules, resource)
+        resource.permission_set_rules.select(&:is_active).each do |rule|
+          permission_set_rules << {
+            name: rule.name,
+            failure_message: rule.failure_message,
+            join_type: rule.join_type,
+            field_name: rule.field_name,
+            field_value: rule.field_value,
+            field_accessor_path: rule.field_accessor_path,
+            operator: rule.operator,
+            include_nulls: rule.include_nulls
+          }
+        end
+      end
+
+      # --- Muting logic (subtractive, deny overrides allow) ---
+
+      # A muting resource reaches every entry whose resource chain names it
+      # (ResourceChain): the entry of its own name and, when it names a
+      # model, the entries of that model's STI subclasses. A subclass can
+      # only be narrower than its base, and the CRUD flags, the bypasses and
+      # the actions are read from one entry (can_*?, the controller guard):
+      # a muted base that left the subclass entry whole let the subclass
+      # controller destroy the row the admin believed muted, while the rows
+      # and fields, composed along the chain, were already closed. A muting
+      # row naming a subclass reaches that subclass alone.
+      def apply_muting_permission_set(data, permission_set)
+        permission_set.resources.select(&:is_active).each do |resource|
+          entries_under(data, resource.name).each do |resource_data|
+            apply_muting_resource(resource_data, permission_set, resource)
+          end
+        end
+      end
+
+      # The entries whose chain includes the resource name, in hash order;
+      # each entry's chain is worked out once per build.
+      def entries_under(data, name)
+        muted = name.to_sym
+        @entry_chains ||= {}
+        data[:resources].filter_map do |entry_name, resource_data|
+          chain = (@entry_chains[entry_name] ||= PermissionForge::ResourceChain.names_for(entry_name))
+          resource_data if chain.include?(muted)
+        end
+      end
+
+      # The set is listed once per entry: one with rows for a base and its
+      # subclass reaches the subclass entry twice.
+      def apply_muting_resource(resource_data, permission_set, resource)
+        sources = resource_data[:source_permission_sets]
+        add_source_permission_set(sources, permission_set) if sources.none? { |source| source[:uuid] == permission_set.uuid }
+        mute_resource_permissions(resource_data[:permissions], resource)
+        mute_field_permissions(resource_data[:fields], resource)
+        mute_fields_of_resource(resource_data[:fields], resource)
+        mute_resource_actions(resource_data[:actions], resource)
+      end
+
+      def mute_resource_permissions(permissions, resource)
+        RESOURCE_PERMISSION_OPTIONS.each do |action|
+          permissions[action] = false if resource.send(action)
+        end
+      end
+
+      # A muting set that revokes the resource's read revokes read and edit on
+      # every field of the resource; variants and implicit extra fields are
+      # entries too. Field enforcement (getters, as_json, the filters) reads
+      # the field entries only, so muting the resource used to protect less
+      # than never granting it. Read only: PermitsAttributes filters creates
+      # too, so the same cascade on edit would block a user who may create but
+      # not change ("can submit, cannot edit afterwards"). Granting sets are
+      # left to their field rows, as before.
+      def mute_fields_of_resource(fields, resource)
+        return unless resource.read_access
+
+        fields.each_value do |entry|
+          entry[:read_access] = false
+          entry[:edit_access] = false
+        end
+      end
+
+      def mute_field_permissions(fields, resource)
+        resource.resource_fields.select(&:is_active).each do |field|
+          next unless field.is_active
+
+          # Mute the base field AND every configured variant (_uuid, base name for
+          # _cents, etc.), matching the variants the granting phase writes — otherwise
+          # a muting set that revokes `user_id` would leave `user_uuid` readable.
+          mute_single_field(fields, field.name, field)
+          PermissionForge.configuration.field_variants_for(field.name).each do |variant|
+            mute_single_field(fields, variant, field)
+          end
+        end
+      end
+
+      # A row that mutes read mutes edit too: a field nobody may read is not
+      # one they may write (the admin UI's Hide writes both flags; the API
+      # and code can write read alone, which left the field writable through
+      # PermitsAttributes). Admin::EffectiveFields#mute_field says the same.
+      def mute_single_field(fields, field_name, field)
+        entry = fields[field_name]
+        return unless entry
+
+        entry[:read_access] = false if field.read_access
+        entry[:edit_access] = false if field.read_access || field.edit_access
+        entry[:mask_access] = true if field.mask_access
+      end
+
+      def mute_resource_actions(actions, resource)
+        resource.resource_actions.select(&:is_active).each do |action|
+          key = action.name.to_sym
+          actions[key][:is_permitted] = false if actions.key?(key) && action.is_permitted
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/services/permission_rule_applier.rb

@@ -0,0 +1,192 @@
+module PermissionForge
+  module Services
+    # Applies row-level permission rules to build a scoped ActiveRecord query.
+    # Extracted from PermissionScopedFindable for SRP and testability.
+    #
+    # Column references are quoted with the connection's real identifier quoting
+    # (quote_table_name / quote_column_name) rather than string interpolation, so
+    # a malformed field_name can never reach SQL as a literal even if a rule was
+    # created through a path that bypasses model validation.
+    #
+    # @api private
+    class PermissionRuleApplier
+      # join_type => the relation method that makes the join. The model
+      # validates join_type, but a rule row can be written past the model (the
+      # tables are shared with other applications): the value is looked up
+      # here, never sent to the relation, and anything else raises.
+      JOIN_METHODS = {
+        PermissionForge::Operators::Constants::JOINS => :joins,
+        PermissionForge::Operators::Constants::LEFT_JOINS => :left_joins,
+        PermissionForge::Operators::Constants::LEFT_OUTER_JOINS => :left_outer_joins
+      }.freeze
+
+      def self.call(model_class:, rules:, args:, current_user: PermissionForge.current_user,
+                    operator_registry: PermissionForge::Operators::Registry)
+        new(model_class:, rules:, args:, current_user:, operator_registry:).call
+      end
+
+      # Builds the rule-constrained relation without evaluating a specific record
+      # or computing failure messages. Used by the `permission_scoped` relation
+      # API so callers can chain further `.where`, `.first`, `.find`, etc.
+      #
+      # @return [ActiveRecord::Relation]
+      def self.scope(model_class:, rules:, current_user: PermissionForge.current_user,
+                     operator_registry: PermissionForge::Operators::Registry)
+        new(model_class:, rules:, args: nil, current_user:, operator_registry:).scoped_relation
+      end
+
+      # @return [ActiveRecord::Relation] all rules applied, no args/denial check
+      def scoped_relation
+        report_no_rules if @rules.empty?
+        @rules.reduce(@model_class.where(nil)) { |q, rule| build_rule_query(q, rule) }
+      end
+
+      def initialize(model_class:, rules:, args:, current_user:, operator_registry:)
+        @model_class = model_class
+        @rules = rules
+        @args = args
+        @current_user = current_user
+        @operator_registry = operator_registry
+      end
+
+      # @return [Array(ActiveRecord::Relation, Array<String>)] query and failure messages
+      def call
+        report_no_rules if @rules.empty?
+        query = @rules.reduce(@model_class.where(nil)) { |q, rule| build_rule_query(q, rule) }
+
+        # Happy path is a single existence check: rule constraints are monotonic
+        # (each only removes rows), so if the fully-constrained query still matches
+        # the target, no individual rule denied it.
+        return [query, []] if @rules.empty? || query.where(*@args).exists?
+
+        # Denial path only: attribute the denial to specific rules for the error
+        # message. The extra per-rule queries here run solely when access is denied.
+        [query, denial_messages]
+      end
+
+      private
+
+      # Called with no rules (the gem's own callers check first; a host app
+      # calling the applier directly may not): rule.bypassed, no_rules.
+      def report_no_rules
+        PermissionForge::Audit::Runtime.bypassed(:no_rules, model: @model_class, via: 'rule_applier', user: @current_user)
+      end
+
+      def rule_failure_message(rule)
+        "[Forbidden by Rule: #{rule[:name]}] with message: #{rule[:failure_message]}"
+      end
+
+      # Rebuilds the query rule-by-rule, blaming each rule whose addition removes
+      # the target from the result set (the first denying rule and every rule
+      # after it, matching the original cumulative semantics).
+      def denial_messages
+        messages = []
+        @rules.reduce(@model_class.where(nil)) do |q, rule|
+          next_query = build_rule_query(q, rule)
+          messages << rule_failure_message(rule) unless next_query.where(*@args).exists?
+          next_query
+        end
+        messages
+      end
+
+      def build_rule_query(query, rule)
+        join_type = rule[:join_type].to_s
+        return apply_filter(query, rule) if PermissionForge::PermissionSetRule.filter_join_type?(join_type)
+
+        apply_join(query, rule, join_method(join_type))
+      end
+
+      # @raise [PermissionForge::ConfigurationError] for a join_type that is not one
+      def join_method(join_type)
+        JOIN_METHODS.fetch(join_type) do
+          raise PermissionForge::ConfigurationError,
+                "Rule join_type #{join_type.inspect} is not a join type. Allowed: #{JOIN_METHODS.keys.join(', ')}"
+        end
+      end
+
+      def apply_filter(query, rule)
+        column = quoted_column(@model_class.table_name, rule[:field_name])
+        build_query(query, column, rule, [@model_class])
+      end
+
+      # A path that cannot be followed leaves no model to type by: the value
+      # goes as it is, and ActiveRecord raises for the join when the query is built.
+      def apply_join(query, rule, join_method)
+        query, models = resolve_join(query, rule, join_method)
+        column = quoted_column((models.last || @model_class).table_name, rule[:field_name])
+        build_query(query, column, rule, models)
+      end
+
+      # Quotes a column reference with the connection's identifier quoting.
+      # A dotted field_name is treated as already-qualified path segments and
+      # each segment is quoted independently.
+      def quoted_column(table, field_name)
+        conn = @model_class.connection
+        name = field_name.to_s
+        return name.split('.').map { |seg| conn.quote_column_name(seg) }.join('.') if name.include?('.')
+
+        "#{conn.quote_table_name(table)}.#{conn.quote_column_name(name)}"
+      end
+
+      def resolve_join(query, rule, join_method)
+        return [query, [@model_class]] if rule[:field_accessor_path].blank?
+
+        association_chain = rule[:field_accessor_path].split('.')
+        query = apply_join_to_query(query, join_method, association_chain)
+
+        [query, PermissionForge::Operators::RuleColumn.models_along(@model_class, association_chain)]
+      end
+
+      # @param join_method [Symbol] one of JOIN_METHODS — never a rule's own text
+      def apply_join_to_query(query, join_method, association_chain)
+        if association_chain.size > 1
+          query.public_send(join_method, build_nested_joins_structure(association_chain))
+        else
+          query.public_send(join_method, association_chain.first.to_sym)
+        end
+      end
+
+      def build_nested_joins_structure(association_chain)
+        structure = {}
+        current = structure
+
+        association_chain.each_with_index do |assoc, index|
+          current[assoc.to_sym] = {}
+          current = current[assoc.to_sym] unless index == association_chain.length - 1
+        end
+
+        structure
+      end
+
+      # A built-in operator gets its value in the type of the column it is
+      # compared with (see Operators::ValueTyping). A value that cannot be one
+      # of that column makes the rule match nothing, whatever the database
+      # would have made of the comparison. A custom operator's value is passed
+      # as it is and its strategy runs. A field_name that is not a name
+      # (Operators::RuleColumn.name?) matches nothing under any operator.
+      def build_query(query, quoted_column, rule, models)
+        operator = rule[:operator]
+        strategy = @operator_registry.fetch(operator)
+        target = PermissionForge::Operators::RuleColumn.find(rule[:field_name], models)
+        value = PermissionForge::Operators::ValueTyping.call(operator, formatted_field_value(rule), target)
+        return query.none if value.equal?(PermissionForge::Operators::ValueTyping::UNUSABLE)
+
+        strategy.call(query, quoted_column, rule, value)
+      end
+
+      # The only magic value is 'current_user', substituted with the current
+      # user's id where one value is compared (in a list it is an element like
+      # any other). Every other field_value reaches ValueTyping as it is
+      # written, and what comes back is quoted by the adapter — rule text is
+      # never interpolated into SQL.
+      def formatted_field_value(rule)
+        value = rule[:field_value]
+        return value unless PermissionForge::Operators::ValueTyping.current_user?(rule[:operator], value)
+
+        raise ArgumentError, 'current_user is nil but rule requires current_user substitution' unless @current_user
+
+        @current_user.id
+      end
+    end
+  end
+end

data/lib/permission_forge/services/permission_set_cloner.rb

@@ -0,0 +1,89 @@
+module PermissionForge
+  module Services
+    # Deep-copies a Permission Set: its resources with their fields, actions
+    # and rules — never its assignments. Every copied row is created by an
+    # audited save credited to whoever makes the copy (Clonable), and the copy
+    # records `permission_set.cloned` naming its source; all of it shares one
+    # correlation id (an enclosing Audit.correlate block's, if any).
+    #
+    #   PermissionSetCloner.call(permission_set: set, attrs: { name: 'Copy' })
+    #   PermissionSetCloner.call(permission_set: set, attrs: { name: 'Copy' }, unlock: true) # every row editable
+    #
+    # @api public
+    class PermissionSetCloner
+      include Clonable
+
+      # @param permission_set [PermissionSet] the source
+      # @param attrs [Hash] attributes of the copy of the set itself
+      # @param unlock [Boolean] create every copied row editable
+      #   (`is_editable: true`) instead of keeping the source's locks
+      # @return [PermissionSet] the copy
+      def self.call(permission_set:, attrs: {}, unlock: false)
+        new(permission_set, attrs, unlock: unlock).call
+      end
+
+      def initialize(permission_set, attrs, unlock: false)
+        @permission_set = permission_set
+        @attrs = attrs
+        @unlock = unlock
+      end
+
+      # @return [PermissionSet] the copy
+      def call
+        PermissionForge::Audit.correlate do
+          @permission_set.class.transaction do
+            cloned = copy(@permission_set, **@attrs)
+            clone_resources(cloned)
+            record_clone(cloned)
+            cloned
+          end
+        end
+      end
+
+      private
+
+      def clone_resources(target_set)
+        @permission_set.resources.includes(:resource_fields, :resource_actions, :permission_set_rules).find_each do |resource|
+          clone_resource(target_set, resource)
+        end
+      end
+
+      def clone_resource(target_set, resource)
+        cloned_resource = copy(resource, permission_set: target_set)
+
+        resource.resource_fields.each { |field| copy(field, resource: cloned_resource) }
+        clone_actions(resource, cloned_resource)
+        resource.permission_set_rules.each { |rule| copy(rule, permission_set: target_set, resource: cloned_resource) }
+      end
+
+      # One copy per action name. Rows that share a name (possible only on a
+      # table without the unique index) are OR-ed when permissions are built,
+      # so the copy is the single row they amount to.
+      def clone_actions(resource, cloned_resource)
+        resource.resource_actions.group_by(&:name).each_value do |rows|
+          copy(rows.first, resource: cloned_resource, **combined_action_flags(rows))
+        end
+      end
+
+      def combined_action_flags(rows)
+        return {} if rows.one?
+
+        active = rows.select(&:is_active)
+        { is_active: active.any?, is_permitted: (active.presence || rows).any?(&:is_permitted) }
+      end
+
+      # The lock is set before the first save, so the row's create event
+      # holds it: there is no second, unaudited write.
+      def copy(record, **attrs)
+        attrs = { is_editable: true }.merge(attrs) if @unlock && record.has_attribute?(:is_editable)
+        duplicate_record(record, **attrs)
+      end
+
+      def record_clone(cloned)
+        PermissionForge::Audit.record('permission_set.cloned', record: cloned,
+                                                               data: { 'source_uuid' => @permission_set.uuid,
+                                                                       'source_name' => @permission_set.name })
+      end
+    end
+  end
+end

data/lib/permission_forge/services/permission_set_condition_evaluator.rb

@@ -0,0 +1,102 @@
+require 'ipaddr'
+
+module PermissionForge
+  module Services
+    # Evaluates activation conditions on a permission set against a request context.
+    # Returns true if the set is active for the given context (all conditions pass).
+    # A nil/blank condition always passes (unconditional).
+    #
+    # @example
+    #   PermissionSetConditionEvaluator.call(
+    #     permission_set: ps,
+    #     context: { ip: '192.168.1.5', session_flags: ['mfa_verified'], time: Time.current }
+    #   )
+    #   # => true or false
+    #
+    # @api public
+    class PermissionSetConditionEvaluator
+      # @param permission_set [PermissionSet]
+      # @param context [Hash] `ip:`, `session_flags:` and `time:` of the request
+      # @return [Boolean]
+      def self.call(permission_set:, context:)
+        new(permission_set, context).call
+      end
+
+      # Whether a condition of the set cannot be judged in `context`: it
+      # restricts the IP and the context has none, or it requires a session
+      # flag and the context says nothing about flags (no :session_flags at
+      # all — an empty list is an answer). The hours are always judged (the
+      # time defaults to now). Under config.conditional_sets_strict_mode a
+      # conditional muting set applies then (ConditionalSets#passing).
+      #
+      # @return [Boolean]
+      def self.unjudgeable?(permission_set:, context:)
+        context ||= {}
+        (permission_set.allowed_ips.present? && context[:ip].blank?) ||
+          (permission_set.requires_session_flag.present? && context[:session_flags].nil?)
+      end
+
+      def initialize(permission_set, context)
+        @permission_set = permission_set
+        @context = context || {}
+      end
+
+      # @return [Boolean] whether every condition of the set passes in the context
+      def call
+        session_flag_passes? && ip_passes? && hours_pass?
+      end
+
+      private
+
+      # Session flag: set only active when context includes the required flag.
+      def session_flag_passes?
+        flag = @permission_set.requires_session_flag
+        return true if flag.blank?
+
+        Array(@context[:session_flags]).include?(flag)
+      end
+
+      # IP restriction: set only active when request IP matches allowed CIDRs.
+      # The IP may be a String or an IPAddr; anything that is not an address
+      # fails the condition.
+      def ip_passes?
+        allowed = @permission_set.allowed_ips
+        return true if allowed.blank?
+
+        request_ip = @context[:ip]
+        return false if request_ip.blank?
+
+        address = request_ip.is_a?(IPAddr) ? request_ip : IPAddr.new(request_ip.to_s)
+        parse_ip_ranges(allowed).any? { |range| range.include?(address) }
+      rescue IPAddr::Error
+        false
+      end
+
+      # Login hours: set only active during allowed hour window.
+      def hours_pass?
+        start_hour = @permission_set.allowed_hours_start
+        end_hour = @permission_set.allowed_hours_end
+        return true if start_hour.nil? || end_hour.nil?
+
+        hour_in_range?((@context[:time] || Time.current).hour, start_hour, end_hour)
+      end
+
+      def hour_in_range?(hour, start_hour, end_hour)
+        if start_hour <= end_hour
+          hour >= start_hour && hour < end_hour
+        else
+          # Wraps midnight (e.g., 22-06 means 22:00 to 05:59)
+          hour >= start_hour || hour < end_hour
+        end
+      end
+
+      def parse_ip_ranges(allowed_ips)
+        allowed_ips.split(',').filter_map do |cidr|
+          IPAddr.new(cidr.strip)
+        rescue IPAddr::Error
+          nil
+        end
+      end
+    end
+  end
+end