verifica 1.0.0

data/lib/verifica/acl.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "set"
+require_relative "ace"
+require_relative "acl_builder"
+
+module Verifica
+  # Access Control List (ACL)
+  #
+  # Access Control List consists of Access Control Entities (ACEs) and defines which
+  # actions are allowed or denied for particular Security Identifiers (SIDs).
+  #
+  # ACL is typically associated with a resource (e.g. Post, Comment, Order) and specifies
+  # which users (or external services, or API clients) are allowed to do what actions on the given resource.
+  #
+  # @see Ace
+  # @see Sid
+  #
+  # @api public
+  class Acl
+    # Creates a new {AclBuilder} and yields it to the given block.
+    #
+    # @example
+    #   acl = Verifica::Acl.build do |acl|
+    #     acl.allow "anonymous", [:read]
+    #     acl.allow "authenticated", [:read, :comment]
+    #     acl.deny "country:US", [:read, :comment]
+    #   end
+    #
+    # @return [Acl] Access Control List created by builder
+    #
+    # @api public
+    def self.build
+      builder = AclBuilder.new
+      yield builder
+      builder.build
+    end
+
+    attr_reader :aces
+    protected :aces
+
+    # Creates a new Access Control List with immutable state.
+    # @note Use {.build} instead of this constructor directly.
+    #
+    # @param aces [Array<Ace>] list of Access Control Entries
+    #
+    # @api public
+    def initialize(aces)
+      @aces = Set.new(aces).freeze
+      @allow_deny_by_action = prepare_index.freeze
+      @allowed_actions = Set.new
+      @allow_deny_by_action.each do |action, allow_deny|
+        @allowed_actions.add(action) unless allow_deny[:allowed_sids].empty?
+
+        allow_deny[:allowed_sids].freeze
+        allow_deny[:denied_sids].freeze
+        allow_deny.freeze
+      end
+
+      @allowed_actions.freeze
+      freeze
+    end
+
+    # Checks whether the action is allowed for given Security Identifiers.
+    # For action to be allowed all 3 conditions should be met:
+    #
+    # * ACL and SIDs are not empty
+    # * ACL contains at least one entry that allow given action for any of the SIDs
+    # * ACL contains no entries that deny given action for any of the SIDs
+    #
+    # @param action [Symbol, String] action to check
+    # @param sids [Array<String>, Set<String>] list of Security Identifiers to match for
+    #
+    # @return [Boolean] true if action is allowed
+    #
+    # @api public
+    def action_allowed?(action, sids)
+      return false if empty? || sids.empty?
+
+      action = action.to_sym
+      allow_deny = @allow_deny_by_action[action]
+
+      return false if allow_deny.nil? || !@allowed_actions.include?(action)
+
+      sids = sids.to_set
+      allow_deny[:allowed_sids].intersect?(sids) && !allow_deny[:denied_sids].intersect?(sids)
+    end
+
+    # The opposite of {#action_allowed?}
+    #
+    # @api public
+    def action_denied?(action, sids)
+      !action_allowed?(action, sids)
+    end
+
+    # @note Checking allowed SIDs isn't enough to determine whether the action is allowed.
+    #   You need to always check {#denied_sids} as well.
+    #
+    # @param action (see #action_allowed?)
+    #
+    # @return [Array<String>] array of Security Identifiers allowed for a given action or empty array if none
+    #
+    # @api public
+    def allowed_sids(action)
+      sids = @allow_deny_by_action.dig(action.to_sym, :allowed_sids)
+      sids.nil? ? EMPTY_ARRAY : sids.to_a
+    end
+
+    # @note Checking denied SIDs isn't enough to determine whether the action is allowed.
+    #   You need to always check {#allowed_sids} as well.
+    #
+    # @param action (see #action_allowed?)
+    #
+    # @return [Array<String>] array of Security Identifiers denied for a given action or empty array if none
+    #
+    # @api public
+    def denied_sids(action)
+      sids = @allow_deny_by_action.dig(action.to_sym, :denied_sids)
+      sids.nil? ? EMPTY_ARRAY : sids.to_a
+    end
+
+    # @param sids (see #action_allowed?)
+    #
+    # @return [Array<Symbol>] array of actions allowed for given Security Identifiers or empty array if none
+    #
+    # @api public
+    def allowed_actions(sids)
+      return EMPTY_ARRAY if sids.empty?
+
+      @allowed_actions.select { |action| action_allowed?(action, sids) }
+    end
+
+    # Creates a new {AclBuilder}, adds existing entries to it and yields it to the given block.
+    # Use this method to extend an existing ACL with additional entries
+    #
+    # @example
+    #   base_acl = Verifica::Acl.build do |acl|
+    #     acl.allow "superuser", [:read, :write, :delete]
+    #   end
+    #
+    #   extended_acl = base_acl.build do |acl|
+    #     acl.allow "anonymous", [:read]
+    #     acl.allow "authenticated", [:read, :comment]
+    #   end
+    #
+    # @return [Acl] new Access Control List created by builder
+    #
+    # @api public
+    def build
+      builder = AclBuilder.new(to_a)
+      yield builder
+      builder.build
+    end
+
+    # @example
+    #   acl = Verifica::Acl.build { |acl| acl.allow "root", [:read, :write] }
+    #   acl.to_a.map(:to_h)
+    #   # => [{:sid=>"root", :action=>:read, :allow=>true}, {:sid=>"root", :action=>:write, :allow=>true}]
+    #
+    # @return [Array<Ace>] a new array representing +self+
+    #
+    # @api public
+    def to_a
+      @aces.to_a
+    end
+
+    # @return [Boolean] true if there are no entries in +self+
+    #
+    # @api public
+    def empty?
+      @aces.empty?
+    end
+
+    # @return [Integer] the count of entries in +self+
+    #
+    # @api public
+    def length
+      @aces.length
+    end
+    alias_method :size, :length
+
+    def to_s
+      @aces.map(&:to_h).to_s
+    end
+
+    def ==(other)
+      eql?(other)
+    end
+
+    def eql?(other)
+      self.class == other.class &&
+        @aces == other.aces
+    end
+
+    def hash
+      [self.class, @aces].hash
+    end
+
+    private def prepare_index
+      @aces.each_with_object({}) do |ace, index|
+        action = ace.action
+        allow_deny = index.fetch(action) { {allowed_sids: Set.new, denied_sids: Set.new}.freeze }
+        allow_deny[ace.allow? ? :allowed_sids : :denied_sids].add(ace.sid)
+        index[action] = allow_deny
+      end
+    end
+  end
+end

data/lib/verifica/acl_builder.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Verifica
+  # Builder that holds mutable list of Access Control Entries and methods to add new entries
+  #
+  # @see Acl.build Usage examples
+  #
+  # @api public
+  class AclBuilder
+    # @note Use {Acl.build} or {Acl#build} instead of this constructor directly
+    #
+    # @api public
+    def initialize(initial_aces = EMPTY_ARRAY)
+      @aces = initial_aces.dup
+      freeze
+    end
+
+    # Add Access Control Entries that allow particular actions for the given Security Identifier
+    #
+    # @example
+    #   builder = AclBuilder.new
+    #     .allow("anonymous", [:read])
+    #     .allow("root", [:read, :write, :delete])
+    #   acl = builder.build
+    #
+    # @param sid [String] Security Identifier
+    # @param actions [Enumerable<Symbol>, Enumerable<String>] list of actions allowed for the given SID
+    #
+    # @return [self]
+    #
+    # @api public
+    def allow(sid, actions)
+      @aces.concat(actions.map { |action| Ace.new(sid, action, true) })
+      self
+    end
+
+    # Add Access Control Entries that deny particular actions for the given Security Identifier
+    #
+    # @example
+    #   builder = Verifica::AclBuilder.new
+    #     .deny("country:US", [:read, :comment])
+    #     .deny("country:CA", [:read, :comment])
+    #   acl = builder.build
+    #
+    # @param sid [String] Security Identifier
+    # @param actions [Enumerable<Symbol>, Enumerable<String>] list of actions denied for the given SID
+    #
+    # @return [self]
+    #
+    # @api public
+    def deny(sid, actions)
+      @aces.concat(actions.map { |action| Ace.new(sid, action, false) })
+      self
+    end
+
+    # @return [Acl] a new, immutable Access Control List
+    #
+    # @api public
+    def build
+      Acl.new(@aces)
+    end
+  end
+end

data/lib/verifica/authorization_result.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Verifica
+  # Outcome of the authorization, either successful or failed.
+  # Memoizes the state of variables that affected the decision. Could show why the authorization
+  # was successful or failed even if the concerned objects have changed.
+  #
+  # @see Authorizer#authorize
+  #
+  # @api public
+  class AuthorizationResult
+    # @return [Object] subject of the authorization (e.g. current user, external service)
+    #
+    # @api public
+    attr_reader :subject
+
+    # @return [Object] subject ID returned by +subject.subject_id+
+    #
+    # @api public
+    attr_reader :subject_id
+
+    # @return [Symbol, nil] subject type returned by +subject.subject_type+
+    #
+    # @api public
+    attr_reader :subject_type
+
+    # @return [Array<String>] array of subject Security Identifiers returned by +subject.subject_sids+
+    #
+    # @api public
+    attr_reader :subject_sids
+
+    # @return [Object] resource on which {#subject} attempted to perform {#action}
+    #
+    # @api public
+    attr_reader :resource
+
+    # @return [Object] resource ID returned by +resource.resource_id+
+    #
+    # @api public
+    attr_reader :resource_id
+
+    # @return [Symbol] resource type returned by resource#resource_type
+    #
+    # @api public
+    attr_reader :resource_type
+
+    # @return [Symbol] action that {#subject} attempted to perform on the {#resource}
+    #
+    # @api public
+    attr_reader :action
+
+    # @return [Acl] Access Control List returned by ACL provider registered for this {#resource_type} in {Authorizer}
+    #
+    # @api public
+    attr_reader :acl
+
+    # @return [Hash] any additional keyword arguments that have been passed to the authorization call
+    #
+    # @see Authorizer#authorize
+    #
+    # @api public
+    attr_reader :context
+
+    # @api private
+    def initialize(subject, resource, action, acl, **context)
+      @subject = subject
+      sids = Verifica.subject_sids(subject, **context)
+      @subject_sids = sids.map { _1.dup.freeze }.freeze
+      @subject_id = subject.subject_id.dup.freeze
+      @subject_type = subject.subject_type&.to_sym
+      @resource = resource
+      @resource_id = resource.resource_id.dup.freeze
+      @resource_type = resource.resource_type.to_sym
+      @action = action
+      @acl = acl
+      @context = context
+      @success = acl.action_allowed?(action, @subject_sids)
+      freeze
+    end
+
+    # @return [Boolean] true if given {#action} is allowed for given {#subject}
+    #
+    # @api public
+    def success?
+      @success
+    end
+
+    # @return [Boolean] true if given {#action} is denied for given {#subject}
+    #
+    # @api public
+    def failure?
+      !success?
+    end
+
+    # @see Acl#allowed_actions
+    #
+    # @return [Array<Symbol>] array of actions allowed for given {#subject} or empty array if none
+    #
+    # @api public
+    def allowed_actions
+      acl.allowed_actions(subject_sids)
+    end
+
+    # @return [String] human-readable description of authorization result. Includes subject, resource, and outcome
+    #
+    # @api public
+    def message
+      status = success? ? "SUCCESS" : "FAILURE"
+      "Authorization #{status}. Subject '#{subject_type}' id='#{subject_id}'. Resource '#{resource_type}' " \
+        "id='#{resource_id}'. Action '#{action}'"
+    end
+
+    # @return [String] detailed, human-readable description of authorization result.
+    #   Includes subject, resource, resource ACL, and explains the reason why authorization was successful or failed.
+    #   Extremely useful for debugging.
+    #
+    # @api public
+    def explain
+      <<~MESSAGE
+        #{message}
+
+        \s\sSubject SIDs (#{subject_sids.empty? ? "empty" : subject_sids.size}):
+        \s\s\s\s#{subject_sids}
+
+        \s\sContext:
+        \s\s\s\s#{context}
+
+        \s\sResource ACL (#{acl.empty? ? "empty" : acl.size}):
+        #{acl.to_a.map { "\s\s\s\s#{_1}" }.join("\n")}
+
+        Reason: #{reason_message}
+      MESSAGE
+    end
+
+    private def reason_message
+      if success?
+        sids = acl.allowed_sids(action).intersection(subject_sids).to_a
+        return "subject SID(s) #{sids} allowed for '#{action}' action. No SIDs denied among subject SIDs"
+      end
+
+      return "resource ACL is empty, no actions allowed for any subject" if acl.empty?
+      return "subject SIDs are empty, no actions allowed for any resource" if subject_sids.empty?
+
+      denied = acl.denied_sids(action).intersection(subject_sids).to_a
+      if denied.empty?
+        "among #{subject_sids.size} subject SID(s), none is listed as allowed for '#{action}' action"
+      else
+        "subject SID(s) #{denied} denied for '#{action}' action. Denied SIDs always win regardless of allowed SIDs"
+      end
+    end
+  end
+end

data/lib/verifica/authorizer.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Verifica
+  # @api private
+  def self.subject_sids(subject, **context)
+    if subject.nil?
+      raise Error, "Subject should not be nil"
+    end
+
+    sids = subject.subject_sids(**context)
+    unless sids.is_a?(Array) || sids.is_a?(Set)
+      raise Error, "Expected subject to respond to #subject_sids with Array or Set of SIDs but got '#{sids.class}'"
+    end
+
+    sids
+  end
+
+  # Authorizer is the heart of Verifica. It's an isolated container with no global state
+  # which has a list of resource types registered with their companion AclProviders.
+  #
+  # Authorizer pairs great with Dependency Injection or can be configured and passed in a way that is compatible with your framework.
+  #
+  # @example (see Verifica)
+  #
+  # @see Verifica.authorizer
+  # @see Configuration
+  # @see ResourceConfiguration
+  #
+  # @api public
+  class Authorizer
+    # @note Use {Verifica.authorizer} instead of this constructor directly
+    #
+    # @api public
+    def initialize(resource_configs)
+      @resources = index_resources(resource_configs).freeze
+      freeze
+    end
+
+    # Checks the authorization of a subject to perform an action on a resource
+    #
+    # * The +subject+ is asked for its Security Identifiers (SIDs) by +subject.subject_sids+
+    # * The +resource+ is asked for its type by +resource.resource_type+
+    # * ACL provider registered for this resource type is asked for {Acl} by +#call(resource, **context)+
+    # * ACL is checked whether the +action+ is allowed for the subject SIDs
+    #
+    # @example
+    #   def show
+    #     post = Post.find(params[:id])
+    #     authorizer.authorize(current_user, post, :read)
+    #
+    #     render json: post
+    #   end
+    #
+    # @param subject [Object] subject of the authorization (e.g. current user, external service)
+    # @param resource [Object] resource to authorize for, should respond to +#resource_type+
+    # @param action [Symbol, String] action that +subject+ attempts to perform on the +resource+
+    # @param context [Hash] arbitrary keyword arguments to forward to +subject.subject_sids+ and +acl_provider.call+
+    #
+    # @return [AuthorizationResult] authorization result with all details if authorization is successful
+    # @raise [AuthorizationError] if +subject+ isn't authorized to perform +action+ on the given +resource+
+    # @raise [Error] if +resource.resource_type+ isn't registered in +self+
+    #
+    # @see Acl#action_allowed? How ACL is checked whether the action is allowed
+    # @see Configuration#register_resource
+    #
+    # @api public
+    def authorize(subject, resource, action, **context)
+      result = authorization_result(subject, resource, action, **context)
+      raise AuthorizationError, result if result.failure?
+
+      result
+    end
+
+    # The same as {#authorize} but returns true/false instead of rising an exception
+    #
+    # @return [Boolean] true if +action+ on +resource+ is authorized for +subject+
+    # @raise [Error] if +resource.resource_type+ isn't registered in +self+
+    #
+    # @api public
+    def authorized?(subject, resource, action, **context)
+      authorization_result(subject, resource, action, **context).success?
+    end
+
+    # @param subject [Object] subject of the authorization (e.g. current user, external service)
+    # @param resource [Object] resource to get allowed actions for, should respond to +#resource_type+
+    # @param **context (see #authorize)
+    #
+    # @return [Array<Symbol>] array of actions allowed for +subject+ or empty array if none
+    # @raise [Error] if +resource.resource_type+ isn't registered in +self+
+    #
+    # @see Configuration#register_resource
+    # @see Acl#allowed_actions
+    #
+    # @api public
+    def allowed_actions(subject, resource, **context)
+      acl = resource_acl(resource, **context)
+      sids = Verifica.subject_sids(subject)
+      acl.allowed_actions(sids)
+    end
+
+    # @param resource_type [Symbol, String] type of the resource
+    #
+    # @return [ResourceConfiguration] configuration for +resource_type+
+    # @raise [Error] if +resource_type+ isn't registered in +self+
+    #
+    # @see resource_type?
+    # @see Configuration#register_resource
+    #
+    # @api public
+    def resource_config(resource_type)
+      resource_type = resource_type.to_sym
+      config = @resources[resource_type]
+      if config.nil?
+        raise Error, "Unknown resource '#{resource_type}'. Did you forget to register this resource type?"
+      end
+
+      config
+    end
+
+    # @param resource_type (see #resource_config)
+    #
+    # @return [Boolean] true if +resource_type+ is registered in +self+
+    #
+    # @see Configuration#register_resource
+    #
+    # @api public
+    def resource_type?(resource_type)
+      @resources.key?(resource_type.to_sym)
+    end
+
+    # @param resource [Object] resource to get ACL for, should respond to +#resource_type+
+    # @param context [Hash] arbitrary keyword arguments to forward to +acl_provider.call+
+    #
+    # @return [Acl] Access Control List for +resource+
+    # @raise [Error] if +resource_type+ isn't registered in +self+
+    # @raise [Error] if ACL provider for this resource type doesn't respond to +#call(resource, **)+ with {Acl} object
+    #
+    # @see Configuration#register_resource
+    #
+    # @api public
+    def resource_acl(resource, **context)
+      config = config_by_resource(resource)
+      acl = config.acl_provider.call(resource, **context)
+      unless acl.is_a?(Verifica::Acl)
+        type = resource.resource_type
+        raise Error, "'#{type}' resource acl_provider should respond to #call with Acl object but got '#{acl.class}'"
+      end
+
+      acl
+    end
+
+    private def index_resources(resource_configs)
+      resource_configs.each_with_object({}) do |config, by_type|
+        type = config.resource_type
+        if by_type.key?(type)
+          raise Error, "'#{type}' resource registered multiple times. Probably code copy-paste and a bug?"
+        end
+
+        by_type[type] = config
+      end
+    end
+
+    private def config_by_resource(resource)
+      if resource.nil?
+        raise Error, "Resource should not be nil"
+      end
+
+      type = resource.resource_type
+      if type.nil?
+        raise Error, "Resource should respond to #resource_type with non-nil type"
+      end
+
+      resource_config(type)
+    end
+
+    private def authorization_result(subject, resource, action, **context)
+      action = action.to_sym
+      possible_actions = config_by_resource(resource).possible_actions
+      unless possible_actions.include?(action)
+        raise Error, "'#{action}' action is not registered as possible for '#{resource.resource_type}' resource"
+      end
+
+      acl = resource_acl(resource, **context)
+      AuthorizationResult.new(subject, resource, action, acl, **context)
+    end
+  end
+end

data/lib/verifica/configuration.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "resource_configuration"
+
+module Verifica
+  # Configuration object for {Authorizer}, holds list of registered resources and other params
+  #
+  # @see Verifica.authorizer Usage examples
+  #
+  # @api public
+  class Configuration
+    # @return [Array<ResourceConfiguration>] array of registered resources
+    #
+    # @api public
+    attr_reader :resources
+
+    # @note Use {Verifica.authorizer} instead of this constructor directly
+    #
+    # @api public
+    def initialize
+      @resources = []
+    end
+
+    # Register a new resource supported by {Authorizer}
+    #
+    # @see Verifica.authorizer Usage examples
+    #
+    # @param type [Symbol, String] type of the resource
+    # @param possible_actions [Enumerable<Symbol>, Enumerable<String>] list of actions possible for this resource type
+    # @param acl_provider [#call] Access Control List provider for this resource type.
+    #   Could be any object that responds to +#call(resource, **)+ and returns {Acl}
+    #
+    # @return [self]
+    #
+    # @api public
+    def register_resource(type, possible_actions, acl_provider)
+      resources << ResourceConfiguration.new(type, possible_actions, acl_provider)
+      self
+    end
+  end
+end