passwordstate 0.0.4 → 0.1.0

data/lib/passwordstate/resource.rb

@@ -1,57 +1,79 @@
+# frozen_string_literal: true
+
 module Passwordstate
-  # A simple resource DSL
+  # A simple resource DSL helper
+  #
+  # rubocop:disable Metrics/ClassLength This DSL class will be large
   class Resource
     attr_reader :client
 
-    def get(query = {})
-      set! self.class.get(client, send(self.class.index_field), query)
+    # Update the object based off of up-to-date upstream data
+    # @return [Resource] self
+    def get(**query)
+      set! self.class.get(client, send(self.class.index_field), **query)
     end
 
-    def put(body = {}, query = {})
+    # Push any unapplied changes to the object
+    # @return [Resource] self
+    def put(body = {}, **query)
       to_send = modified.merge(self.class.index_field => send(self.class.index_field))
-      set! self.class.put(client, to_send.merge(body), query).first
+      set! self.class.put(client, to_send.merge(body), **query).first
     end
 
-    def post(body = {}, query = {})
-      set! self.class.post(client, attributes.merge(body), query)
+    # Create the object based off of provided information
+    # @return [Resource] self
+    def post(body = {}, **query)
+      set! self.class.post(client, attributes.merge(body), **query)
     end
 
-    def delete(query = {})
-      self.class.delete(client, send(self.class.index_field), query)
+    # Delete the object
+    # @return [Resource] self
+    def delete(**query)
+      self.class.delete(client, send(self.class.index_field), **query)
     end
 
     def initialize(data)
       @client = data.delete :_client
-      set! data, false
+      set! data, store_old: false
       old
     end
 
+    # Is the object stored on the Passwordstate server
     def stored?
       !send(self.class.index_field).nil?
     end
 
+    # Check if the resource type is available on the connected Passwordstate server
     def self.available?(_client)
       true
     end
 
-    def self.all(client, query = {})
+    # Retrieve all accessible instances of the resource type, requires the method :get
+    def self.all(client, **query)
+      raise NotAcceptableError, "Read is not implemented for #{self}" unless acceptable_methods.include? :get
+
       path = query.fetch(:_api_path, api_path)
+      reason = query.delete(:_reason)
       query = passwordstateify_hash query.reject { |k| k.to_s.start_with? '_' }
 
-      [client.request(:get, path, query: query)].flatten.map do |object|
+      [client.request(:get, path, query: query, reason: reason)].flatten.map do |object|
         new object.merge(_client: client)
       end
     end
 
-    def self.get(client, object, query = {})
+    # Retrieve a specific instance of the resource type, requires the method :get
+    def self.get(client, object, **query)
+      raise NotAcceptableError, "Read is not implemented for #{self}" unless acceptable_methods.include? :get
+
       object = object.send(object.class.send(index_field)) if object.is_a? Resource
 
       return new _client: client, index_field => object if query[:_bare]
 
       path = query.fetch(:_api_path, api_path)
+      reason = query.delete(:_reason)
       query = passwordstateify_hash query.reject { |k| k.to_s.start_with? '_' }
 
-      resp = client.request(:get, "#{path}/#{object}", query: query).map do |data|
+      resp = client.request(:get, "#{path}/#{object}", query: query, reason: reason).map do |data|
         new data.merge(_client: client)
       end
       return resp.first if resp.one? || resp.empty?
@@ -59,56 +81,82 @@ module Passwordstate
       resp
     end
 
-    def self.post(client, data, query = {})
+    # Create a new instance of the resource type, requires the method :post
+    def self.post(client, data, **query)
+      raise NotAcceptableError, "Create is not implemented for #{self}" unless acceptable_methods.include? :post
+
       path = query.fetch(:_api_path, api_path)
+      reason = query.delete(:_reason)
       data = passwordstateify_hash data
       query = passwordstateify_hash query.reject { |k| k.to_s.start_with? '_' }
 
-      new [client.request(:post, path, body: data, query: query)].flatten.first.merge(_client: client)
+      new [client.request(:post, path, body: data, query: query, reason: reason)].flatten.first.merge(_client: client)
     end
 
-    def self.put(client, data, query = {})
+    # Push new data to an instance of the resource type, requires the method :put
+    def self.put(client, data, **query)
+      raise NotAcceptableError, "Update is not implemented for #{self}" unless acceptable_methods.include? :put
+
       path = query.fetch(:_api_path, api_path)
+      reason = query.delete(:_reason)
       data = passwordstateify_hash data
       query = passwordstateify_hash query.reject { |k| k.to_s.start_with? '_' }
 
-      client.request :put, path, body: data, query: query
+      client.request :put, path, body: data, query: query, reason: reason
     end
 
-    def self.delete(client, object, query = {})
+    # Delete an instance of the resource type, requires the method :delete
+    def self.delete(client, object, **query)
+      raise NotAcceptableError, "Delete is not implemented for #{self}" unless acceptable_methods.include? :delete
+
       path = query.fetch(:_api_path, api_path)
+      reason = query.delete(:_reason)
       query = passwordstateify_hash query.reject { |k| k.to_s.start_with? '_' }
 
       object = object.send(object.class.send(index_field)) if object.is_a? Resource
-      client.request :delete, "#{path}/#{object}", query: query
-    end
-
-    def self.passwordstateify_hash(hash)
-      Hash[hash.map  { |k, v| [ruby_to_passwordstate_field(k), v] }]
-    end
-
-    def api_path
-      self.class.instance_variable_get :@api_path
+      client.request :delete, "#{path}/#{object}", query: query, reason: reason
     end
 
-    def attributes(opts = {})
-      ignore_redact = opts.fetch(:ignore_redact, true)
+    # Get a hash of all active attributes on the resource instance
+    #
+    # @param ignore_redact [Boolean] Should any normally redacted fields be displayed in clear-text
+    # @param atify [Boolean] Should the resulting hash be returned with instance variable names ('@'-prefixed)
+    # @option opts nil_as_string [Boolean] (resource dependent) Should nil values be treated as the empty string
+    def attributes(ignore_redact: true, atify: false, **opts)
       nil_as_string = opts.fetch(:nil_as_string, self.class.nil_as_string)
-      Hash[(self.class.send(:accessor_field_names) + self.class.send(:read_field_names) + self.class.send(:write_field_names)).map do |field|
+      (self.class.send(:accessor_field_names) + self.class.send(:read_field_names) + self.class.send(:write_field_names)).to_h do |field|
         redact = self.class.send(:field_options)[field]&.fetch(:redact, false) && !ignore_redact
-        value = instance_variable_get("@#{field}".to_sym) unless redact
+        at_field = "@#{field}".to_sym
+        field = at_field if atify
+        value = instance_variable_get(at_field) unless redact
         value = '[ REDACTED ]' if redact
         value = '' if value.nil? && nil_as_string
         [field, value]
-      end].reject { |_k, v| v.nil? }
+      end.compact
     end
 
-    def inspect
-      "#{to_s[0..-2]} #{attributes(nil_as_string: false, ignore_redact: false).reject { |_k, v| v.nil? }.map { |k, v| "@#{k}=#{v.inspect}" }.join(', ')}>"
+    def pretty_print(pp)
+      pp.object_address_group(self) do
+        attrs = attributes(atify: true, nil_as_string: false, ignore_redact: false).compact
+        pp.seplist(attrs.keys.sort, -> { pp.text ',' }) do |v|
+          pp.breakable
+          v = v.to_s if v.is_a? Symbol
+          pp.text v
+          pp.text '='
+          pp.group(1) do
+            pp.breakable ''
+            pp.pp(attrs[v.to_sym])
+          end
+        end
+      end
     end
 
     protected
 
+    def api_path
+      self.class.instance_variable_get :@api_path
+    end
+
     def modified
       attribs = attributes
       attribs.reject { |field| old[field] == attribs[field] }
@@ -122,7 +170,7 @@ module Passwordstate
       @old ||= attributes.dup
     end
 
-    def set!(data, store_old = true)
+    def set!(data, store_old: true)
       @old = attributes.dup if store_old
       data = data.attributes if data.is_a? Passwordstate::Resource
       data.each do |key, value|
@@ -133,8 +181,11 @@ module Passwordstate
 
         if !value.nil? && opts&.key?(:is)
           klass = opts.fetch(:is)
-          parsed_value = klass.send :parse, value rescue nil if klass.respond_to? :parse
-          parsed_value ||= klass.send :new, value rescue nil if klass.respond_to? :new
+          parsed_value = klass.send :parse, value rescue nil if klass.respond_to?(:parse)
+          parsed_value ||= klass.send :new, value rescue nil if klass.respond_to?(:new) && !klass.respond_to?(:parse)
+        elsif !value.nil? && opts&.key?(:convert)
+          convert = opts.fetch(:convert)
+          parsed_value = convert.call(value, direction: :from)
         end
 
         instance_variable_set "@#{field}".to_sym, parsed_value || value
@@ -145,26 +196,52 @@ module Passwordstate
     class << self
       alias search all
 
+      # Get/Set the API path for the resource type
       def api_path(path = nil)
         @api_path = path unless path.nil?
         @api_path
       end
 
+      # Get/Set the index field for the resource type
       def index_field(field = nil)
         @index_field = field unless field.nil?
         @index_field
       end
 
+      # Get/Set whether the resource type requires nil values to be handled as the empty string
       def nil_as_string(opt = nil)
         @nil_as_string = opt unless opt.nil?
         @nil_as_string
       end
 
+      # Get/Set acceptable CRUD methods for the resource type
+      def acceptable_methods(*meths)
+        if meths.empty?
+          @acceptable_methods || %i[post get put delete]
+        elsif meths.count == 1 && meths.to_s.upcase == meths.to_s
+          @acceptable_methods = []
+          meths = meths.first.to_s
+          @acceptable_methods << :post if meths.include? 'C'
+          @acceptable_methods << :get if meths.include? 'R'
+          @acceptable_methods << :put if meths.include? 'U'
+          @acceptable_methods << :delete if meths.include? 'D'
+        else
+          @acceptable_methods = meths
+        end
+      end
+
+      # Convert a hash from Ruby syntax to Passwordstate syntax
+      def passwordstateify_hash(hash)
+        hash.transform_keys { |k| ruby_to_passwordstate_field(k) }
+      end
+
+      # Convert a Passwordstate field name into Ruby syntax
       def passwordstate_to_ruby_field(field)
         opts = send(:field_options).find { |(_k, v)| v[:name] == field }
         opts&.first || field.to_s.snake_case.to_sym
       end
 
+      # Convert a Ruby field name into Passwordstate syntax
       def ruby_to_passwordstate_field(field)
         send(:field_options)[field]&.[](:name) || field.to_s.camel_case
       end
@@ -225,18 +302,23 @@ module Passwordstate
       end
     end
   end
+  # rubocop:enable Metrics/ClassLength
 
   module Resources
-    autoload :Document,               'passwordstate/resources/document'
-    autoload :Folder,                 'passwordstate/resources/folder'
-    autoload :FolderPermission,       'passwordstate/resources/folder'
-    autoload :Host,                   'passwordstate/resources/host'
-    autoload :PasswordList,           'passwordstate/resources/password_list'
-    autoload :PasswordListPermission, 'passwordstate/resources/password_list'
-    autoload :Password,               'passwordstate/resources/password'
-    autoload :PasswordHistory,        'passwordstate/resources/password'
-    autoload :PasswordPermission,     'passwordstate/resources/password_list'
-    autoload :Permission,             'passwordstate/resources/permission'
-    autoload :Report,                 'passwordstate/resources/report'
+    autoload :ActiveDirectory,             'passwordstate/resources/active_directory'
+    autoload :AddressBook,                 'passwordstate/resources/address_book'
+    autoload :Document,                    'passwordstate/resources/document'
+    autoload :Folder,                      'passwordstate/resources/folder'
+    autoload :FolderPermission,            'passwordstate/resources/folder'
+    autoload :Host,                        'passwordstate/resources/host'
+    autoload :Password,                    'passwordstate/resources/password'
+    autoload :PasswordList,                'passwordstate/resources/password_list'
+    autoload :PasswordListPermission,      'passwordstate/resources/password_list'
+    autoload :PasswordHistory,             'passwordstate/resources/password'
+    autoload :PasswordPermission,          'passwordstate/resources/password_list'
+    autoload :PrivilegedAccount,           'passwordstate/resources/privileged_account'
+    autoload :PrivilegedAccountPermission, 'passwordstate/resources/privileged_account'
+    autoload :Permission,                  'passwordstate/resources/permission'
+    autoload :Report,                      'passwordstate/resources/report'
   end
 end

data/lib/passwordstate/resource_list.rb

@@ -1,45 +1,49 @@
-module Passwordstate
-  class ResourceList < Array
-    Array.public_instance_methods(false).each do |method|
-      next if %i[reject select slice clear inspect].include?(method.to_sym)
-
-      class_eval <<-EVAL, __FILE__, __LINE__ + 1
-        def #{method}(*args)
-          lazy_load unless @loaded
-          super
-        end
-      EVAL
-    end
+# frozen_string_literal: true
 
-    %w[reject select slice].each do |method|
-      class_eval <<-EVAL, __FILE__, __LINE__ + 1
-        def #{method}(*args)
-          lazy_load unless @loaded
-          data = super
-          self.clone.clear.concat(data)
-        end
-      EVAL
-    end
-
-    def inspect
-      lazy_load unless @loaded
-      super
-    end
+module Passwordstate
+  class ResourceList
+    include Enumerable
 
     attr_reader :client, :resource, :options
 
-    def initialize(client, resource, options = {})
+    def initialize(resource, client:, **options)
       @client = client
       @resource = resource
       @loaded = false
       @options = options
+      @data = []
 
       options[:only] = [options[:only]].flatten if options.key? :only
       options[:except] = [options[:except]].flatten if options.key? :except
     end
 
+    def pretty_print_instance_variables
+      instance_variables.reject { |k| %i[@client @data].include? k }.sort
+    end
+
+    def pretty_print(pp)
+      return pp.pp self if respond_to? :mocha_inspect
+
+      pp.pp_object(self)
+    end
+
+    alias inspect pretty_print_inspect
+
+    def each(&block)
+      lazy_load unless @loaded
+
+      return to_enum(__method__) { @data.size } unless block_given?
+
+      @data.each(&block)
+    end
+
+    def [](index)
+      @data[index]
+    end
+
     def clear
-      @loaded = super
+      @data = []
+      @loaded = false
     end
 
     def reload
@@ -48,9 +52,12 @@ module Passwordstate
     end
 
     def load(entries)
-      clear && entries.tap do |loaded|
+      clear
+      entries.tap do |loaded|
         loaded.sort! { |a, b| a.send(a.class.index_field) <=> b.send(b.class.index_field) } if options.fetch(:sort, true)
-      end.each { |obj| self << obj }
+      end
+      entries.each { |obj| @data << obj }
+      @loaded = true
       self
     end
 
@@ -74,58 +81,65 @@ module Passwordstate
       obj
     end
 
-    def search(query = {})
+    def search(**query)
       raise 'Operation not supported' unless operation_supported?(:search)
 
       api_path = options.fetch(:search_path, resource.api_path)
       query = options.fetch(:search_query, {}).merge(query)
 
-      resource.search(client, query.merge(_api_path: api_path))
+      resource.search(client, **query.merge(_api_path: api_path))
     end
 
-    def all(query = {})
+    def all(**query)
       raise 'Operation not supported' unless operation_supported?(:all)
 
       api_path = options.fetch(:all_path, resource.api_path)
       query = options.fetch(:all_query, {}).merge(query)
 
-      load resource.all(client, query.merge(_api_path: api_path))
+      load resource.all(client, **query.merge(_api_path: api_path))
     end
 
-    def get(id, query = {})
+    def get(id, **query)
       raise 'Operation not supported' unless operation_supported?(:get)
 
+      if query.empty? && !@data.empty?
+        existing = @data.find do |entry|
+          entry.send(entry.class.index_field) == id
+        end
+        return existing if existing
+      end
+
       api_path = options.fetch(:get_path, resource.api_path)
       query = options.fetch(:get_query, {}).merge(query)
 
-      resource.get(client, id, query.merge(_api_path: api_path))
+      resource.get(client, id, **query.merge(_api_path: api_path))
     end
 
-    def post(data, query = {})
+    def post(data, **query)
       raise 'Operation not supported' unless operation_supported?(:post)
 
       api_path = options.fetch(:post_path, resource.api_path)
       query = options.fetch(:post_query, {}).merge(query)
 
-      resource.post(client, data, query.merge(_api_path: api_path))
+      resource.post(client, data, **query.merge(_api_path: api_path))
     end
 
-    def put(data, query = {})
+    def put(data, **query)
       raise 'Operation not supported' unless operation_supported?(:put)
 
       api_path = options.fetch(:put_path, resource.api_path)
       query = options.fetch(:put_query, {}).merge(query)
 
-      resource.put(client, data, query.merge(_api_path: api_path))
+      resource.put(client, data, **query.merge(_api_path: api_path))
     end
 
-    def delete(id, query = {})
+    def delete(id, **query)
       raise 'Operation not supported' unless operation_supported?(:delete)
 
       api_path = options.fetch(:delete_path, resource.api_path)
       query = options.fetch(:delete_query, {}).merge(query)
 
-      resource.delete(client, id, query.merge(_api_path: api_path))
+      resource.delete(client, id, **query.merge(_api_path: api_path))
     end
 
     private

data/lib/passwordstate/resources/active_directory.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Passwordstate
+  module Resources
+    class ActiveDirectory < Passwordstate::Resource
+      api_path 'activedirectory'
+
+      index_field :ad_domain_id
+
+      accessor_fields :ad_domain_netbios, { name: 'ADDomainNetBIOS' },
+                      :ad_domain_ldap, { name: 'ADDomainLDAP' },
+                      :fqdn, { name: 'FQDN' },
+                      :default_domain,
+                      :pa_read_id, { name: 'PAReadID' },
+                      :site_id, { name: 'SiteID' },
+                      :used_for_authentication,
+                      :protocol,
+                      :domain_controller_fqdn, { name: 'DomainControllerFQDN' }
+
+      read_fields :ad_domain_id, { name: 'ADDomainID' }
+    end
+  end
+end

data/lib/passwordstate/resources/address_book.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Passwordstate
+  module Resources
+    class AddressBook < Passwordstate::Resource
+      api_path 'addressbook'
+
+      index_field :address_book_id
+
+      accessor_fields :first_name,
+                      :surname,
+                      :email_adress,
+                      :company,
+                      :business_phone,
+                      :personal_phone,
+                      :street,
+                      :city,
+                      :state,
+                      :zipcode,
+                      :country,
+                      :notes,
+                      :pass_phrase,
+                      :global_contact
+
+      read_fields :address_book_id, { name: 'AddressBookID' }
+    end
+  end
+end

data/lib/passwordstate/resources/document.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Passwordstate
   module Resources
     class Document < Passwordstate::Resource
@@ -10,12 +12,39 @@ module Passwordstate
 
       alias title document_name
 
-      def self.search(client, store, options = {})
-        client.request :get, "#{api_path}/#{store}/", query: options
+      def self.all(client, store, **query)
+        super client, query.merge(_api_path: "#{api_path}/#{validate_store! store}")
+      end
+
+      def self.search(client, store, **options)
+        all client, store, **options
       end
 
       def self.get(client, store, object)
-        client.request :get, "#{api_path}/#{store}/#{object}"
+        super client, object, _api_path: "#{api_path}/#{validate_store! store}"
+      end
+
+      def self.post(client, store, data, **query)
+        super client, data, query.merge(_api_path: "#{api_path}/#{validate_store! store}")
+      end
+
+      def self.put(client, store, data, **query)
+        super client, data, query.merge(_api_path: "#{api_path}/#{validate_store! store}")
+      end
+
+      def self.delete(client, store, object, **query)
+        super client, object, query.merge(_api_path: "#{api_path}/#{validate_store! store}")
+      end
+
+      class << self
+        private
+
+        def validate_store!(store)
+          raise ArgumentError, 'Store must be one of password, passwordlist, folder' \
+            unless %i[password passwordlist folder].include?(store.to_s.downcase.to_sym)
+
+          store.to_s.downcase.to_sym
+        end
       end
     end
   end

data/lib/passwordstate/resources/folder.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Passwordstate
   module Resources
     class Folder < Passwordstate::Resource
@@ -16,7 +18,8 @@ module Passwordstate
       alias title folder_name
 
       def password_lists
-        Passwordstate::ResourceList.new client, Passwordstate::Resources::PasswordList,
+        Passwordstate::ResourceList.new Passwordstate::Resources::PasswordList,
+                                        client: client,
                                         search_query: { tree_path: tree_path },
                                         all_path: 'searchpasswordlists',
                                         all_query: { tree_path: tree_path },
@@ -28,7 +31,7 @@ module Passwordstate
         FolderPermission.new(_client: client, folder_id: folder_id)
       end
 
-      def full_path(unix = false)
+      def full_path(unix: false)
         return tree_path.tr('\\', '/') if unix
 
         tree_path
@@ -40,7 +43,7 @@ module Passwordstate
 
       index_field :folder_id
 
-      read_fields :folder_id, { name: 'FolderID' } # rubocop:disable Style/BracesAroundHashParameters
+      read_fields :folder_id, { name: 'FolderID' }
     end
   end
 end

data/lib/passwordstate/resources/host.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'ipaddr'
 
 module Passwordstate