entitlements 0.1.7

data/lib/entitlements/extras/orgchart/person_methods.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+require "yaml"
+
+module Entitlements
+  module Extras
+    class Orgchart
+      class PersonMethods < Entitlements::Extras::Orgchart::Base
+        include ::Contracts::Core
+        C = ::Contracts
+
+        # This method might be used within Entitlements::Models::Person to determine
+        # the manager for a given person based on the organization chart.
+        #
+        # person - Reference to Entitlements::Models::Person object calling this method
+        #
+        # Returns a String with the distinguished name of the person's manager.
+        Contract Entitlements::Models::Person => String
+        def self.manager(person)
+          # User to manager map is assumed to be stored in a YAML file wherein the key is the
+          # username and the value is a hash. The value contains a key "manager" with the username
+          # of the manager.
+          @user_to_manager_map ||= begin
+            unless config["manager_map_file"]
+              raise ArgumentError, "To use #{self}, `manager_map_file` must be defined in the configuration!"
+            end
+
+            manager_map_file = Entitlements::Util::Util.absolute_path(config["manager_map_file"])
+
+            unless File.file?(manager_map_file)
+              raise Errno::ENOENT, "The `manager_map_file` #{manager_map_file} does not exist!"
+            end
+
+            YAML.load(File.read(manager_map_file))
+          end
+
+          u = person.uid.downcase
+          unless @user_to_manager_map.key?(u)
+            raise "User #{u} is not included in manager map data!"
+          end
+          unless @user_to_manager_map[u]["manager"]
+            raise "User #{u} does not have a manager listed in manager map data!"
+          end
+          @user_to_manager_map[u]["manager"]
+        end
+
+        def self.reset!
+          @user_to_manager_map = nil
+          @extra_config = nil
+        end
+      end
+    end
+  end
+end

data/lib/entitlements/extras/orgchart/rules/direct_report.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+# Is someone in a direct report of the listed manager?
+
+module Entitlements
+  module Extras
+    class Orgchart
+      class Rules
+        class DirectReport < Entitlements::Data::Groups::Calculated::Rules::Base
+          include ::Contracts::Core
+          C = ::Contracts
+
+          # Interface method: Get a Set[Entitlements::Models::Person] matching this condition.
+          #
+          # value  - The value to match.
+          # filename - Name of the file resulting in this rule being called
+          # options  - Optional hash of additional method-specific options
+          #
+          # Returns a Set[Entitlements::Models::Person].
+          Contract C::KeywordArgs[
+            value: String,
+            filename: C::Maybe[String],
+            options: C::Optional[C::HashOf[Symbol => C::Any]]
+          ] => C::SetOf[Entitlements::Models::Person]
+          def self.matches(value:, filename: nil, options: {})
+            # Construct the manager's DN and object.
+            manager_uid = value.downcase
+
+            begin
+              manager = Entitlements.cache[:people_obj].read(manager_uid)
+            rescue Entitlements::Data::People::NoSuchPersonError
+              # This is fatal. If this defines a team by a manager who is no longer in LDAP then the
+              # entry needs to be corrected because those people have to report to someone...
+              Entitlements.logger.fatal "Manager #{manager_uid} does not exist for file #{filename}!"
+              raise "Manager #{manager_uid} does not exist!"
+            end
+
+            # Call all_reports which will return the set of all direct and indirect reports.
+            # This is evaluated once per run of the program.
+            Entitlements.cache[:management_obj] ||= begin
+              Entitlements::Extras::Orgchart::Logic.new(people: Entitlements.cache.fetch(:people_obj).read)
+            end
+
+            # This is fatal. If this defines a manager who has nobody reporting to them, then they
+            # aren't a manager at all. The entry should be changed to "username" or otherwise the
+            # proper manager should be filled in.
+            if Entitlements.cache[:management_obj].direct_reports(manager).empty?
+              Entitlements.logger.fatal "Manager #{manager_uid} has no reports for file #{filename}!"
+              raise "Manager #{manager_uid} has no reports!"
+            end
+
+            # Most of the time, people will expect "direct_report: xyz" to include xyz and anyone who
+            # reports to them. Technically, xyz doesn't report to themself, but we'll hack it in here
+            # because it's least surprise. If someone really wants "xyz's reports but not xyz" they
+            # can use the "not" in conjunction.
+            result = Set.new([manager])
+            result.merge Entitlements.cache[:management_obj].direct_reports(manager)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/entitlements/extras/orgchart/rules/management.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+# Is someone in a management chain?
+
+module Entitlements
+  module Extras
+    class Orgchart
+      class Rules
+        class Management < Entitlements::Data::Groups::Calculated::Rules::Base
+          include ::Contracts::Core
+          C = ::Contracts
+
+          # Interface method: Get a Set[Entitlements::Models::Person] matching this condition.
+          #
+          # value  - The value to match.
+          # filename - Name of the file resulting in this rule being called
+          # options  - Optional hash of additional method-specific options
+          #
+          # Returns a Set[Entitlements::Models::Person].
+          Contract C::KeywordArgs[
+            value: String,
+            filename: C::Maybe[String],
+            options: C::Optional[C::HashOf[Symbol => C::Any]]
+          ] => C::SetOf[Entitlements::Models::Person]
+          def self.matches(value:, filename: nil, options: {})
+            begin
+              manager = Entitlements.cache[:people_obj].read(value)
+            rescue Entitlements::Data::People::NoSuchPersonError
+              # This is fatal. If this defines a team by a manager who is no longer in LDAP then the
+              # entry needs to be corrected because those people have to report to someone...
+              Entitlements.logger.fatal "Manager #{value} does not exist for file #{filename}!"
+              raise "Manager #{value} does not exist!"
+            end
+
+            # Call all_reports which will return the set of all direct and indirect reports.
+            # This is evaluated once per run of the program.
+            Entitlements.cache[:management_obj] ||= begin
+              Entitlements::Extras::Orgchart::Logic.new(people: Entitlements.cache.fetch(:people_obj).read)
+            end
+
+            # This is fatal. If this defines a manager who has nobody reporting to them, then they
+            # aren't a manager at all. The entry should be changed to "username" or otherwise the
+            # proper manager should be filled in.
+            if Entitlements.cache[:management_obj].all_reports(manager).empty?
+              Entitlements.logger.fatal "Manager #{value} has no reports for file #{filename}!"
+              raise "Manager #{value} has no reports!"
+            end
+
+            # Most of the time, people will expect "management: xyz" to include xyz and anyone who
+            # reports to them. Technically, xyz doesn't report to themself, but we'll hack it in here
+            # because it's least surprise. If someone really wants "xyz's reports but not xyz" they
+            # can use the "not" in conjunction.
+            result = Set.new([manager])
+            result.merge Entitlements.cache[:management_obj].all_reports(manager)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/entitlements/extras.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# Loads extras either in this directory structure or elsewhere as specified by the end-user.
+
+module Entitlements
+  module Extras
+    include ::Contracts::Core
+    C = ::Contracts
+
+    # Load and initialize extra functionality, whether in the `lib/extras` directory or in
+    # some other place provided by the user.
+    #
+    # namespace - String with the namespace in Entitlements::Extras to be loaded
+    # path      - Optionally, a String with the directory where the Entitlements::Extras::<Namespace>::Base class can be found
+    #
+    # Returns the Class object for the base of the extra.
+    Contract String, C::Maybe[String] => Class
+    def self.load_extra(namespace, path = nil)
+      path ||= File.expand_path("./extras", __dir__)
+      unless File.file?(File.join(path, namespace, "base.rb"))
+        raise Errno::ENOENT, "Error loading #{namespace}: There is no file `base.rb` in directory `#{path}/#{namespace}`."
+      end
+
+      require File.join(path, namespace, "base.rb")
+      class_name = ["Entitlements", "Extras", Entitlements::Util::Util.camelize(namespace), "Base"].join("::")
+      clazz = Kernel.const_get(class_name)
+      clazz.init
+
+      # Register any rules defined by this class with the handler
+      register_rules(clazz)
+
+      # Register any additional methods on Entitlements::Models::Person
+      register_person_extra_methods(clazz)
+
+      # Record this extra's class as having been loaded.
+      Entitlements.record_loaded_extra(clazz)
+
+      # Contract return
+      @namespace_class ||= {}
+      @namespace_class[namespace] ||= clazz
+    end
+
+    # Register rules contained in this extra with a mapping of rules maintained by
+    # Entitlements::Data::Groups::Calculated::Base.
+    #
+    # clazz - Initialized Entitlements::Extras::<Namespace>::Base object
+    #
+    # Returns nothing.
+    Contract Class => nil
+    def self.register_rules(clazz)
+      return unless clazz.respond_to?(:rules)
+
+      clazz.rules.each do |rule_name|
+        rule_class_name = [clazz.to_s.sub(/::Base\z/, "::Rules"), Entitlements::Util::Util.camelize(rule_name)].join("::")
+        rule_class = Kernel.const_get(rule_class_name)
+        Entitlements::Data::Groups::Calculated.register_rule(rule_name, rule_class)
+      end
+
+      nil
+    end
+
+    # Register methods for Entitlements::Models::Person that are contained in this extra
+    # with the Entitlements class.
+    #
+    # clazz - Initialized Entitlements::Extras::<Namespace>::Base object
+    #
+    # Returns nothing.
+    Contract Class => nil
+    def self.register_person_extra_methods(clazz)
+      return unless clazz.respond_to?(:person_methods)
+
+      clazz.person_methods.each do |method_name|
+        clazz_without_base = clazz.to_s.split("::")[0..-2]
+        method_class_name = [clazz_without_base, "PersonMethods"].join("::")
+        method_class = Kernel.const_get(method_class_name)
+        Entitlements.register_person_extra_method(method_name, method_class)
+      end
+
+      nil
+    end
+  end
+end

data/lib/entitlements/models/action.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Entitlements
+  class Models
+    class Action
+      include ::Contracts::Core
+      C = ::Contracts
+
+      # Constructor.
+      #
+      # dn       - Distinguished name of action.
+      # existing - Current data according to data source.
+      # updated  - Current data according to entitlements.
+      # ou       - String with the OU as per entitlements.
+      # ignored_users - Optionally, a set of strings with users to ignore
+      Contract String, C::Or[nil, Entitlements::Models::Group, :none], C::Or[nil, Entitlements::Models::Group, Entitlements::Models::Person], String, C::KeywordArgs[ignored_users: C::Maybe[C::SetOf[String]]] => C::Any
+      def initialize(dn, existing, updated, ou, ignored_users: Set.new)
+        @dn = dn
+        @existing = existing
+        @updated = updated
+        @ou = ou
+        @implementation = nil
+        @ignored_users = ignored_users
+      end
+
+      # Element readers.
+      attr_reader :dn, :existing, :updated, :ou, :implementation, :ignored_users
+
+      # Determine if the change type is add, delete, or update.
+      Contract C::None => Symbol
+      def change_type
+        return :add if existing.nil?
+        return :delete if updated.nil?
+        :update
+      end
+
+      # Get the configuration for the OU holding the group.
+      #
+      # Takes no arguments.
+      #
+      # Returns a configuration hash.
+      Contract C::None => C::HashOf[String => C::Any]
+      def config
+        Entitlements.config["groups"].fetch(ou)
+      end
+
+      # Determine the type of the OU (defaults to ldap if undefined).
+      #
+      # Takes no arguments.
+      #
+      # Returns a string with the configuration type.
+      Contract C::None => String
+      def ou_type
+        config["type"] || "ldap"
+      end
+
+      # Determine the short name of the DN.
+      #
+      # Takes no arguments.
+      #
+      # Returns a string with the short name of the DN.
+      Contract C::None => String
+      def short_name
+        dn =~ /\A(\w+)=(.+?),/ ? Regexp.last_match(2) : dn
+      end
+
+      # Add an implementation. This is for providers and services that do not have a 1:1 mapping
+      # between entitlements groups and implementing changes on the back end.
+      #
+      # data - Hash of Symbols with information that is meaningful to the back end.
+      #
+      # Returns nothing.
+      # :nocov:
+      Contract C::HashOf[Symbol => C::Any] => C::Any
+      def add_implementation(data)
+        @implementation ||= []
+        @implementation << data
+      end
+      # :nocov:
+    end
+  end
+end

data/lib/entitlements/models/group.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+module Entitlements
+  class Models
+    class Group
+      include ::Contracts::Core
+      C = ::Contracts
+
+      class NoMembers < RuntimeError; end
+      class NoMetadata < RuntimeError; end
+
+      attr_reader :dn
+
+      # ------------------------------------------------------
+      # Constructor
+      # ------------------------------------------------------
+
+      # Constructor.
+      #
+      # dn          - A String with the DN of the group
+      # members     - A Set of Strings with the user IDs, or Entitlements::Models::Person, of the members
+      # description - Optionally, a String with a description
+      # metadata    - Optionally, a Hash with [String => Object] metadata
+      Contract C::KeywordArgs[
+        dn: String,
+        members: C::SetOf[C::Or[Entitlements::Models::Person, String]],
+        description: C::Maybe[String],
+        metadata: C::Maybe[C::HashOf[String => C::Any]]
+      ] => C::Any
+      def initialize(dn:, members:, description: nil, metadata: nil)
+        @dn = dn
+        set_members(members)
+        @description = description == [] ? "" : description
+        @metadata = metadata
+      end
+
+      # Constructor to copy another group object with a different DN.
+      #
+      # dn - The DN for the new group (must be != the DN for the source group)
+      #
+      # Returns Entitlements::Models::Group object.
+      Contract String => Entitlements::Models::Group
+      def copy_of(dn)
+        self.class.new(dn: dn, members: members.dup, description: description, metadata: metadata.dup)
+      end
+
+      # ------------------------------------------------------
+      # Tell us more about this group
+      # ------------------------------------------------------
+
+      # Description must be a string and cannot be empty. If description is empty just return
+      # the cn instead.
+      #
+      # Takes no arguments.
+      #
+      # Returns a non-empty string with the description.
+      Contract C::None => String
+      def description
+        return cn if @description.nil? || @description.empty?
+        @description
+      end
+
+      # Retrieve the members as a consistent object type (we'll pick Entitlements::Models::Person).
+      #
+      # people_obj  - Entitlements::Data::People::* Object (required if not initialized with Entitlements::Models::Person's)
+      #
+      # Returns Set[Entitlements::Models::Person].
+      Contract C::KeywordArgs[
+        people_obj: C::Maybe[C::Any]
+      ] => C::SetOf[Entitlements::Models::Person]
+      def members(people_obj: nil)
+        result = Set.new(
+          @members.map do |member|
+            if member.is_a?(Entitlements::Models::Person)
+              member
+            elsif people_obj.nil?
+              nil
+            elsif people_obj.read.key?(member)
+              people_obj.read(member)
+            else
+              nil
+            end
+          end.compact
+        )
+
+        return result if result.any? || no_members_ok?
+        raise NoMembers, "The group #{dn} has no members!"
+      end
+
+      # Retrieve the members as a string of DNs. This is a way to avoid converting to person objects if
+      # we don't need to do that anyway.
+      #
+      # Takes no arguments.
+      #
+      # Returns Set[String].
+      Contract C::None => C::SetOf[String]
+      def member_strings
+        @member_strings ||= begin
+          result = Set.new(@members.map { |member| member.is_a?(Entitlements::Models::Person) ? member.uid : member })
+          if result.empty? && !no_members_ok?
+            raise NoMembers, "The group #{dn} has no members!"
+          end
+          result
+        end
+      end
+
+      # Retrieve the members as a string of DNs, case-insensitive.
+      #
+      # Takes no arguments.
+      #
+      # Returns Set[String].
+      def member_strings_insensitive
+        @member_strings_insensitive ||= Set.new(member_strings.map(&:downcase))
+      end
+
+      # Determine if the given person is a member of the group.
+      #
+      # person - A Entitlements::Models::Person object
+      #
+      # Returns true if the person is a direct member of the group, false otherwise.
+      Contract C::Or[String, Entitlements::Models::Person] => C::Bool
+      def member?(person)
+        member_strings_insensitive.member?(any_to_uid(person).downcase)
+      end
+
+      # Get the CN of the group (extracted from the DN).
+      #
+      # Takes no arguments.
+      #
+      # Returns a String with the CN.
+      Contract C::None => String
+      def cn
+        return Regexp.last_match(1) if dn =~ /\Acn=(.+?),/
+        raise "Could not determine CN from group DN #{dn.inspect}!"
+      end
+
+      # Retrieve the metadata, raising an error if no metadata was set.
+      #
+      # Takes no arguments.
+      #
+      # Returns a Hash with the metadata.
+      Contract C::None => C::HashOf[String => C::Any]
+      def metadata
+        return @metadata if @metadata
+        raise NoMetadata, "Group #{dn} was not constructed with metadata!"
+      end
+
+      # Determine if this group is equal to another Entitlements::Models::Group object.
+      #
+      # other_group - An Entitlements::Models::Group that is being evaluated against this one.
+      #
+      # Return true if the contents are equivalent, false otherwise.
+      Contract C::Or[Entitlements::Models::Person, Entitlements::Models::Group, :none] => C::Bool
+      def equals?(other_group)
+        unless other_group.is_a?(Entitlements::Models::Group)
+          return false
+        end
+
+        unless dn == other_group.dn
+          return false
+        end
+
+        unless description == other_group.description
+          return false
+        end
+
+        unless member_strings == other_group.member_strings
+          return false
+        end
+
+        true
+      end
+
+      alias_method :==, :equals?
+
+      # Retrieve a key from the metadata if the metadata is defined. Return nil if
+      # metadata wasn't defined. Don't raise an error.
+      #
+      # key - A String with the metadata key to retrieve.
+      #
+      # Returns the value of the metadata key or nil.
+      Contract String => C::Any
+      def metadata_fetch_if_exists(key)
+        return unless @metadata.is_a?(Hash)
+        @metadata[key]
+      end
+
+      # Determine if it's OK for the group to have no members. This is based on metadata, and defaults
+      # to true (it's OK to have no members). This can be overridden by setting metadata to false explicitly.
+      #
+      # Takes no arguments.
+      #
+      # Returns false if no_members_ok is explicitly set to false. Returns true otherwise.
+      Contract C::None => C::Bool
+      def no_members_ok?
+        ![false, "false"].include?(metadata_fetch_if_exists("no_members_ok"))
+      end
+
+      # Directly manipulate members. This sets the group membership directly to the specified value with no
+      # verification or validation. Be very careful!
+      #
+      # members - A Set of Strings with the DNs, or Entitlements::Models::Person, of the members
+      #
+      # Returns nothing.
+      Contract C::SetOf[C::Or[Entitlements::Models::Person, String]] => nil
+      def set_members(members)
+        @members = members
+        @member_strings = nil
+        @member_strings_insensitive = nil
+      end
+
+      # Add a person to the member list of the group.
+      #
+      # person - Entitlements::Models::Person object.
+      #
+      # Returns nothing.
+      Contract C::Or[String, Entitlements::Models::Person] => nil
+      def add_member(person)
+        @members.add(person)
+
+        # Clear these so they will be recomputed
+        @member_strings = nil
+        @member_strings_insensitive = nil
+      end
+
+      # Remove a person from the member list of the group. This can act either on a person object
+      # or a distinguished name.
+      #
+      # person - Entitlements::Models::Person object or String with distinguished name.
+      #
+      # Returns nothing.
+      Contract C::Or[Entitlements::Models::Person, String] => nil
+      def remove_member(person)
+        person_uid = any_to_uid(person).downcase
+        @members.delete_if { |member| any_to_uid(member).downcase == person_uid }
+
+        # Clear these so they will be recomputed
+        @member_strings = nil
+        @member_strings_insensitive = nil
+      end
+
+      # Update the case of a member's distinguished name, if that person is a member of this group.
+      #
+      # person - Entitlements::Models::Person object or String with distinguished name (with the desired case).
+      #
+      # Returns true if a change was made, false if not. (Also returns false if the member isn't in the group.)
+      Contract C::Or[Entitlements::Models::Person, String] => C::Bool
+      def update_case(person)
+        person_uid = any_to_uid(person)
+        downcased_dn = person_uid.downcase
+
+        the_member = @members.find { |member| any_to_uid(member).downcase == downcased_dn }
+        return false unless the_member
+        return false if any_to_uid(the_member) == person_uid
+
+        remove_member(person_uid)
+        add_member(person_uid)
+        true
+      end
+
+      private
+
+      # Get a distinguished name from a String or an Entitlements::Models::Person object.
+      #
+      # obj - A String (with DN) or Entitlements::Models::Person
+      #
+      # Returns a String with the distinguished name.
+      Contract C::Any => String
+      def any_to_uid(obj)
+        if obj.is_a?(String)
+          return obj
+        elsif obj.is_a?(Entitlements::Models::Person)
+          return obj.uid
+        else
+          raise ArgumentError, "any_to_uid cannot handle #{obj.class}"
+        end
+      end
+    end
+  end
+end