rom-ldap 0.2.2

data/lib/rom/ldap/directory/capabilities.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module ROM
+  module LDAP
+    class Directory
+
+      #
+      # Convenience predicates
+      #
+      module Capabilities
+        # Named capabilities
+        #
+        # @see rom/ldap/constants.rb
+        #
+        # @return [Array<Symbol>]
+        #
+        # @api public
+        def capabilities
+          @capabilities ||= OID.invert.values_at(*supported_controls).compact.freeze
+        end
+
+        # Is the server able to order the entries.
+        #
+        # @return [Boolean]
+        #
+        # @api public
+        def sortable?
+          capabilities.include?(:sort_response)
+        end
+
+        # @return [Boolean]
+        #
+        # @api public
+        def pageable?
+          capabilities.include?(:paged_results)
+        end
+
+        # @return [Boolean]
+        #
+        # @api public
+        def chainable?
+          capabilities.include?(:matching_rule_in_chain)
+        end
+
+        # @return [Boolean]
+        #
+        # @api public
+        def pruneable?
+          capabilities.include?(:delete_tree)
+        end
+
+        # @return [Boolean]
+        #
+        # @api public
+        def bitwise?
+          capabilities.include?(:matching_rule_bit_and) &&
+            capabilities.include?(:matching_rule_bit_or)
+        end
+
+        # @return [Boolean]
+        #
+        # @api public
+        def i18n?
+          capabilities.include?(:language_tag_options) &&
+            capabilities.include?(:language_range_options)
+        end
+      end
+
+    end
+  end
+end

data/lib/rom/ldap/directory/entry.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require 'dry/core/cache'
+require 'dry/equalizer'
+require 'rom/initializer'
+require 'rom/support/memoizable'
+require 'rom/ldap/functions'
+
+module ROM
+  module LDAP
+    class Directory
+
+      # A Hash-like object wrapping the DN and attributes returned by the server.
+      # Contains the canonical attributes hash and a formatted version.
+      # BER format converted to primitive String ensures clean output in #to_yaml.
+      # Accessed when iterating over dataset during #modify and #delete.
+      # Exposes methods #fetch, #first, #each_value and #include?.
+      # All other method calls are forwarded to the formatted tuple.
+      #
+      # @see Directory#query
+      #
+      # @api public
+      class Entry
+
+        extend Initializer
+        extend Dry::Core::Cache
+
+        # Uses Dry::Equalizer
+        # @!parse
+        #   include Dry::Equalizer
+        include Dry::Equalizer(:dn, :attributes, :canonical, :formatted)
+
+        include Memoizable
+
+        # @see Dataset::Persistence
+        #
+        # @!attribute [r] dn
+        #   @return [String] Distinguished Name
+        #
+        #   @api public
+        param :dn, proc(&:to_s), type: Types::Strict::String
+
+        # @!attribute [r] attributes
+        #   @return [Array<Array>]
+        #
+        #   @api private
+        param :attributes, type: Types::Strict::Array, reader: :private
+
+        # Retrieve values for a given attribute.
+        #
+        # @see Directory::Root
+        #
+        # @return [Array<String>]
+        #
+        # @param key [String, Symbol]
+        #
+        def fetch(key)
+          formatted.fetch(rename(key), canonical[key])
+        end
+        alias_method :[], :fetch
+
+        # Find the first (only) value for an attribute.
+        #
+        # @see Directory::Root
+        #
+        # @param [Symbol, String] key Attribute name.
+        #
+        # @return [String]
+        #
+        def first(key)
+          fetch(key)&.first
+        end
+
+        # Iterate over the values of a given attribute.
+        #
+        # @param key [Symbol] canonical attribute name
+        #
+        # @example
+        #
+        #   entry.each_value(:object_class, &:to_sym)
+        #   entry.each_value(:object_class) { |o| o.to_sym }
+        #
+        def each_value(key, &block)
+          fetch(key).map(&block)
+        end
+
+        # Mostly used by the test suite.
+        #
+        # @example
+        #
+        #   expect(relation.first).to include(attr: %w[val1 val2])
+        #
+        # @param tuple [Hash] keys and array of values
+        #
+        # @return [Boolean]
+        #
+        def include?(tuple)
+          tuple.flat_map { |attr, vals| vals.map { |v| fetch(attr).include?(v) } }.all?
+        rescue NoMethodError
+          false
+        end
+
+        # Compatibility method with Ruby < 2.5
+        #
+        # @see Relation::Reading#pluck
+        #
+        # @return [Hash]
+        #
+        def slice(*keys)
+          formatted.select { |k, _v| keys.include?(k) }
+        end
+
+        # Defer to enumerable hash methods before entry values.
+        #
+        def method_missing(meth, *args, &block)
+          formatted.send(meth, *args, &block) if formatted.respond_to?(meth) || super
+        end
+
+        # @return [String]
+        #
+        def inspect
+          %(#<#{self.class} #{dn.empty? ? 'rootDSE' : dn} />)
+        end
+
+        private
+
+        # @param meth [Symbol]
+        #
+        # @return [Boolean]
+        #
+        # @api private
+        def respond_to_missing?(meth, include_private = false)
+          formatted.respond_to?(meth) || super
+        end
+
+        # Cache renamed key to improve performance two fold in benchmarks.
+        #
+        # @param key [String, Symbol]
+        #
+        # @api private
+        def rename(key)
+          fetch_or_store(key) { LDAP.formatter[key] }
+        end
+
+        # Convert keys of the canonical tuple using the chosen formatting proc.
+        #
+        # @api private
+        def formatted
+          Functions[:map_keys, LDAP.formatter][canonical]
+        end
+
+        # DN combined with attributes array
+        #
+        # @return [Array]
+        #
+        # @api private
+        def with_dn
+          attributes.dup.sort.unshift(['dn', dn])
+        end
+
+        # Create canonical tuple
+        #
+        # @example
+        #
+        #   # => { 'dn' => [''], 'objectClass' => ['', ''] }
+        #
+        # @return [Hash] canonical camelCase keys ordered alphabetically
+        #
+        # @see Dataset#export
+        #
+        # @api private
+        def canonical
+          stringify_keys[stringify_values[with_dn]]
+        end
+
+        # Covert hash keys to strings.
+        #
+        # @return [Proc]
+        #
+        # @api private
+        def stringify_keys
+          Functions[:map_keys, Functions[:to_string]]
+        end
+
+        # Convert hash whose values are arrays of strings.
+        #
+        # @return [Proc]
+        #
+        # @api private
+        def stringify_values
+          Functions[:map_values, Functions[:map_array, Functions[:to_string]]]
+        end
+
+        memoize :canonical, :formatted
+
+      end
+
+    end
+  end
+end

data/lib/rom/ldap/directory/env.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'rom/initializer'
+require 'uri'
+
+module ROM
+  module LDAP
+    class Directory
+
+      # Parse uri and options received by the gateway configuration.
+      #
+      # @example
+      #   scheme:// binddn : passwd @ host : port / base
+      #   ldap://uid=admin,ou=system:secret@localhost:1389/ou=users,dc=rom,dc=ldap
+      #
+      # @see https://ldapwiki.com/wiki/LDAP%20URL
+      # @see https://docs.oracle.com/cd/E19957-01/816-6402-10/url.htm
+      #
+      # rubocop:disable Lint/UriEscapeUnescape
+      #
+      # @api private
+      class ENV
+
+        extend Initializer
+
+        param :connection,
+              reader: true,
+              type: Types::URI,
+              default: -> { ::ENV.fetch('LDAPURI', default_connection) }
+
+        param :config,
+              reader: :private,
+              type: Types::Strict::Hash,
+              default: -> { EMPTY_OPTS }
+
+        # Build LDAP URL with encoded spaces.
+        #
+        # @return [URI::LDAP, URI::LDAPS]
+        #
+        # @raise URI::InvalidURIError
+        def uri
+          URI(connection.gsub(SPACE, PERCENT_SPACE))
+        end
+
+        # Global search base. The value is derived in this order:
+        #   1. Gateway Options
+        #   2. ENVs
+        #   3. URI (unless this is a socket) defaults ""
+        #   4. an empty string
+        #
+        # @example
+        #   'ldap://localhost/ou=users,dc=rom,dc=ldap' => ou=users,dc=rom,dc=ldap
+        #
+        # @return [String]
+        #
+        def base
+          config.fetch(:base) do
+            ::ENV['LDAPBASE'] || (path ? EMPTY_STRING : uri.dn.to_s)
+          end
+        end
+
+        # Username and password.
+        #
+        # @return [Hash, NilClass]
+        #
+        def auth
+          { username: bind_dn, password: bind_pw } if bind_dn
+        end
+
+        # @return [Hash, NilClass]
+        #
+        def ssl
+          config[:ssl] if uri.scheme.eql?('ldaps')
+        end
+
+        # @return [Hash]
+        #
+        def to_h
+          { host: host, port: port, path: path, ssl: ssl, auth: auth }
+        end
+
+        # @return [String]
+        #
+        def inspect
+          "<#{self.class.name} #{connection} />"
+        end
+
+        private
+
+        # @return [String, NilClass]
+        #
+        def path
+          uri.path unless uri.host
+        end
+
+        # @return [String, NilClass]
+        #
+        def host
+          uri.host unless path
+        end
+
+        # @return [Integer, NilClass]
+        #
+        def port
+          uri.port unless path
+        end
+
+        # Override LDAPURI user with options or LDAPBINDDN.
+        # Percent decode the URI's user value.
+        #
+        # @return [String, NilClass]
+        #
+        def bind_dn
+          dn = config.fetch(:username, ::ENV['LDAPBINDDN']) || uri.user
+          dn.gsub(PERCENT_SPACE, SPACE) if dn
+        end
+        # rubocop:enable Lint/UriEscapeUnescape
+
+        # Override LDAPURI password with options or LDAPBINDPW
+        #
+        # @return [String, NilClass]
+        #
+        def bind_pw
+          config.fetch(:password, ::ENV['LDAPBINDPW']) || uri.password
+        end
+
+        # LDAPHOST or localhost
+        #
+        # @return [String]
+        #
+        def default_host
+          ::ENV.fetch('LDAPHOST', 'localhost')
+        end
+
+        # LDAPPORT or 389
+        #
+        # @return [Integer]
+        #
+        def default_port
+          ::ENV.fetch('LDAPPORT', 389)
+        end
+
+        # Fallback connection scheme is "ldap://"
+        #
+        # @return [String]
+        #
+        def default_connection
+          "ldap://#{default_host}:#{default_port}"
+        end
+
+      end
+
+    end
+  end
+end

data/lib/rom/ldap/directory/operations.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require 'dry/core/cache'
+
+module ROM
+  module LDAP
+    class Directory
+
+      module Operations
+        def self.included(klass)
+          klass.class_eval do
+            extend Dry::Core::Cache
+          end
+        end
+
+        # Use connection to communicate with server.
+        # If :base is passed, it overwrites the default base keyword.
+        #
+        # @option :filter [String, Array] AST or LDAP string.
+        #   Defaults to class attribute.
+        #
+        # @param options [Hash] @see Connection::SearchRequest
+        #
+        # @return [Array<Entry>] Formatted hash like objects.
+        #
+        # @api public
+        #
+        def query(filter: DEFAULT_FILTER, **options)
+          set, counter = [], 0
+
+          # TODO: pageable and search referrals
+          params = {
+            base: base,
+            expression: to_expression(filter),
+            **options
+            # paged: pageable?
+
+            # return_refs: true
+            # https://tools.ietf.org/html/rfc4511#section-4.5.3
+          }
+
+          # pdu = client.search(params) do |search_referrals: |
+          pdu = client.search(params) do |dn, attributes|
+            counter += 1
+            logger.debug("#{counter}: #{dn}") if ::ENV['DEBUG']
+
+            set << entity = Entry.new(dn, attributes)
+            yield(entity) if block_given?
+          end
+
+          debug(pdu)
+
+          set
+        end
+
+        def debug(pdu)
+          return unless ::ENV['DEBUG']
+
+          logger.debug(pdu.advice) if pdu&.advice
+          logger.debug(pdu.message) if pdu&.message
+          logger.debug(pdu.info) if pdu&.failure?
+        end
+
+        # Return all attributes for a distinguished name.
+        #
+        # @param dn [String]
+        #
+        # @return [Array<Entry>]
+        #
+        # @api public
+        def by_dn(dn)
+          raise(DistinguishedNameError, 'DN is required') unless dn
+
+          query(base: dn, max: 1, attributes: ALL_ATTRS)
+        end
+
+        #
+        #
+        # @option :filter [String]
+        # @option :password [String]
+        #
+        # @return [Boolean]
+        #
+        # @api public
+        def bind_as(filter:, password:)
+          if (entity = query(filter: filter, max: 1).first)
+            password = password.call if password.respond_to?(:call)
+
+            pdu = client.bind(username: entity.dn, password: password)
+            pdu.success?
+          else
+            false
+          end
+        rescue BindError
+          false
+        end
+
+        # Used by gateway[filter] to infer schema at boot.
+        #   Limited to 1000 and cached.
+        #
+        # @param filter [String] dataset schema filter
+        #
+        # @return [Array<Entry>]
+        #
+        # @api public
+        def query_attributes(filter)
+          fetch_or_store(base, filter) do
+            query(
+              filter: filter,
+              base: base,
+              max: 1_000, # attribute sample size
+              attributes_only: true
+              # paged: false
+            )
+          end
+        end
+
+        # Count all entries under the search base.
+        #
+        # @return [Integer]
+        #
+        # @api public
+        def base_total
+          query(base: base, attributes: %w[objectClass], attributes_only: true).count
+        end
+
+        #
+        # @param tuple [Hash] tuple using formatted attribute names.
+        #
+        # @return [Entry, FalseClass] created LDAP entry or false.
+        #
+        # @api public
+        def add(tuple)
+          dn    = tuple.delete(:dn)
+          attrs = canonicalise(tuple)
+          raise(DistinguishedNameError, 'DN is required') unless dn
+
+          log(__callee__, dn)
+
+          pdu = client.add(dn: dn, attrs: attrs)
+
+          pdu.success? ? find(dn) : pdu.success?
+        end
+
+        # client#rename > client#password_modify > client#update
+        #
+        # @param dn [String] distinguished name.
+        #
+        # @param tuple [Hash] tuple using formatted attribute names.
+        #
+        # @return [Entry, FalseClass] updated LDAP entry or false.
+        #
+        # @api public
+        def modify(dn, tuple)
+          log(__callee__, dn)
+
+          # entry = find(dn)
+
+          new_dn = tuple.delete(:dn)
+          attrs  = canonicalise(tuple)
+
+          rdn_attr, rdn_val = get_rdn(dn).split('=')
+
+          # 1. Move rename
+          if new_dn
+            new_rdn = get_rdn(new_dn)
+            parent  = get_parent_dn(new_dn)
+
+            new_rdn_attr, new_rdn_val = new_rdn.split('=')
+
+            replace = rdn_attr.eql?(new_rdn_attr)
+
+            pdu = client.rename(dn: dn, rdn: new_rdn, replace: replace, superior: parent)
+
+            if pdu.success?
+              dn, rdn_attr, rdn_val = new_dn, new_rdn_attr, new_rdn_val
+            end
+          end
+
+          # 2. Change password
+          if attrs.key?('userPassword')
+            new_pwd = attrs.delete('userPassword')
+            entry   = find(dn)
+            old_pwd = entry['userPassword']
+
+            pdu = client.password_modify(dn, old_pwd: old_pwd, new_pwd: new_pwd)
+          end
+
+          # 3. Edit attributes
+          unless attrs.empty?
+
+            # Adding to RDN values?
+            if attrs.key?(rdn_attr) && !attrs.key?(rdn_val)
+              attrs[rdn_attr] = Array(attrs[rdn_attr]).unshift(rdn_val)
+            end
+
+            pdu = client.update(dn: dn, ops: attrs.to_a)
+          end
+
+          pdu.success? ? find(dn) : pdu.success?
+        end
+
+        # Tuple(s) by dn
+        #
+        # @param dn [String] distinguished name
+        #
+        # @return [Array<Hash>,Hash]
+        #
+        # @raise [DistinguishedNameError] DN not found
+        #
+        def find(dn)
+          entry = by_dn(dn)
+          raise(DistinguishedNameError, 'DN not found') unless entry
+
+          entry.one? ? entry.first : entry
+        end
+
+        #
+        # @param dn [String] distinguished name.
+        #
+        # @return [Entry, FalseClass] deleted LDAP entry or false.
+        #
+        # @api public
+        def delete(dn)
+          log(__callee__, dn)
+          entry = find(dn)
+
+          pdu = if pruneable?
+                  controls = [OID[:delete_tree]]
+                  client.delete(dn: dn, controls: controls)
+                else
+                  client.delete(dn: dn)
+                end
+
+          pdu.success? ? entry : pdu.success?
+        end
+
+        private
+
+        # RDN - relative distinguished name
+        #
+        # @return [String]
+        #
+        # @api private
+        def get_rdn(dn)
+          dn.split(',')[0]
+        end
+
+        # Parent DN
+        #
+        # @return [String]
+        #
+        # @api private
+        def get_parent_dn(dn)
+          dn.split(',')[1..-1].join(',')
+        end
+
+        # Log operation attempt
+        #
+        def log(method, dn)
+          logger.debug("#{self.class}##{method} '#{dn}'")
+        end
+
+        # Rename the formatted keys of the incoming tuple to their original
+        #   server-side format.
+        #
+        # @note Used by Directory#add and Directory#modify
+        #
+        # @param tuple [Hash]
+        #
+        # @example
+        #   # => canonicalise(population_count: 0) => { 'populationCount' => 0 }
+        #
+        # @api private
+        def canonicalise(tuple)
+          Functions[:tuplify].call(tuple, key_map)
+        end
+      end
+
+    end
+  end
+end