ruby-jss 1.6.4 → 2.0.0b1

data/lib/jss/validate.rb

@@ -1,248 +0,0 @@
-# Copyright 2020 Pixar
-#
-#    Licensed under the Apache License, Version 2.0 (the "Apache License")
-#    with the following modification; you may not use this file except in
-#    compliance with the Apache License and the following modification to it:
-#    Section 6. Trademarks. is deleted and replaced with:
-#
-#    6. Trademarks. This License does not grant permission to use the trade
-#       names, trademarks, service marks, or product names of the Licensor
-#       and its affiliates, except as required to comply with Section 4(c) of
-#       the License and to reproduce the content of the NOTICE file.
-#
-#    You may obtain a copy of the Apache License at
-#
-#        http://www.apache.org/licenses/LICENSE-2.0
-#
-#    Unless required by applicable law or agreed to in writing, software
-#    distributed under the Apache License with the above modification is
-#    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-#    KIND, either express or implied. See the Apache License for the specific
-#    language governing permissions and limitations under the Apache License.
-#
-#
-
-module JSS
-
-  # A collection of methods for validating values. Mostly for
-  # ensuring the validity of data being set as attributes of APIObject
-  # subclass instances.
-  #
-  # Some of these methods can take multiple input types, such as a String
-  # or an Array.  All of them will either raise an exception
-  # if the value isn't valid, or will return a standardized form of the input
-  # (e.g. an Array, even if given a String)
-  #
-  module Validate
-
-    # The regular expression that matches a valid MAC address.
-    MAC_ADDR_RE = /^[a-f0-9]{2}(:[a-f0-9]{2}){5}$/i
-
-    # Validate the format and content of a MAC address
-    #
-    # @param val[String] The value to validate
-    #
-    # @param msg[String] A custom error message when the value is invalid
-    #
-    # @return [String] The valid value
-    #
-    def self.mac_address(val, msg = nil)
-      msg ||= "Not a valid MAC address: '#{val}'"
-      raise JSS::InvalidDataError, msg unless val =~ MAC_ADDR_RE
-
-      val
-    end
-
-    # Segments of a valid IPv4 address are integers in this range.
-    IP_SEGMENT_RANGE = 0..255
-
-    # Validate the format and content of an IPv4 address
-    #
-    # @param val[String] The value to validate
-    #
-    # @param msg[String] A custom error message when the value is invalid
-    #
-    # @return [String] The valid value
-    #
-    def self.ip_address(val, msg = nil)
-      msg ||= "Not a valid IPv4 address: '#{val}'"
-      ok = true
-      parts = val.strip.split '.'
-      ok = false unless parts.size == 4
-      parts.each { |p| ok = false unless p.jss_integer? && IP_SEGMENT_RANGE.include?(p.to_i) }
-      raise JSS::InvalidDataError, msg unless ok
-
-      val
-    end
-
-    # Validate that a value doesn't already exist for a given identifier of a
-    # given class
-    #
-    # e.g. when klass = JSS::Computer, identifier = :name, and val = 'foo'
-    # will raise an error when a computer named 'foo' exists
-    #
-    # Otherwise returns val.
-    #
-    # @param klass[JSS::APIObject] A subclass of JSS::APIObject, e.g. JSS::Computer
-    #
-    # @param identifier[Symbol] One of the keys of an Item of the class's #all Array
-    #
-    # @param val[Object] The value to check for uniqueness
-    #
-    # @param msg[String] A custom error message when the value is invalid
-    #
-    # @param api[JSS::APIConnection] The api connection to use for validation
-    #
-    # @return [Object] the validated unique value
-    #
-    def self.doesnt_already_exist(klass, identifier, val, msg = nil, api: JSS.api)
-      msg ||= "A #{klass} already exists with #{identifier} '#{val}'"
-      return val unless klass.all(:refresh, api: api).map { |i| i[identifier] }.include? val
-
-      key = klass.real_lookup_key identifier
-
-      # use map_all_ids_to cuz it works with any identifer, even non-existing
-      existing_values = klass.map_all_ids_to( key, api: api).values
-      matches = existing_values.select { |existing_val| existing_val.casecmp? val }
-      return val if matches.empty?
-
-      raise JSS::AlreadyExistsError, msg
-    end
-
-    # Confirm that the given value is a boolean value, accepting
-    # strings and symbols and returning real booleans as needed
-    # Accepts: true, false, 'true', 'false', 'yes', 'no', 't','f', 'y', or 'n'
-    # as strings or symbols, case insensitive
-    #
-    # TODO: use this throughout ruby-jss
-    #
-    # @param bool [Boolean,String,Symbol] The value to validate
-    #
-    # @param msg[String] A custom error message when the value is invalid
-    #
-    # @return [Boolean] the valid boolean
-    #
-    def self.boolean(bool, msg = nil)
-      return bool if JSS::TRUE_FALSE.include? bool
-      return true if bool.to_s =~ /^(t(rue)?|y(es)?)$/i
-      return false if bool.to_s =~ /^(f(alse)?|no?)$/i
-
-      msg ||= 'Value must be boolean true or false, or an equivalent string or symbol'
-      raise JSS::InvalidDataError, msg
-    end
-
-    # Confirm that a value is an integer or a string representation of an
-    # integer. Return the integer, or raise an error
-    #
-    # TODO: use this throughout ruby-jss
-    #
-    # @param val[Object] the value to validate
-    #
-    # @param msg[String] A custom error message when the value is invalid
-    #
-    # @return [void]
-    #
-    def self.integer(val, msg = nil)
-      msg ||= 'Value must be an integer'
-      val = val.to_i if val.is_a?(String) && val.jss_integer?
-      raise JSS::InvalidDataError, msg unless val.is_a? Integer
-
-      val
-    end
-
-    # validate that the given value is a non-empty string
-    #
-    # @param val [Object] the thing to validate
-    #
-    # @param msg[String] A custom error message when the value is invalid
-    #
-    # @return [String] the valid non-empty string
-    #
-    def self.non_empty_string(val, msg = nil)
-      msg ||= 'value must be a non-empty String'
-      raise JSS::InvalidDataError, msg unless val.is_a?(String) && !val.empty?
-
-      val
-    end
-
-    UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.freeze
-
-    # validate that the given value is a valid uuid string
-    #
-    # @param val [Object] the thing to validate
-    #
-    # @param msg[String] A custom error message when the value is invalid
-    #
-    # @return [String] the valid uuid string
-    #
-    def self.uuid(val, msg = nil)
-      return val if val.is_a?(String) && val =~ UUID_RE
-
-      msg ||= 'value must be valid uuid'
-      raise JSS::InvalidDataError, msg
-    end
-
-    # validate that the given value is an integer in the JSS::IBeacon::MAJOR_MINOR_RANGE
-    #
-    # @param val [Object] the thing to validate
-    #
-    # @param msg[String] A custom error message when the value is invalid
-    #
-    # @return [String] the valid integer
-    #
-    def self.ibeacon_major_minor(val, msg = nil)
-      val = val.to_i if val.is_a?(String) && val.jss_integer?
-      ok = val.is_a? Integer
-      ok = JSS::IBeacon::MAJOR_MINOR_RANGE.include? val if ok
-      return val if ok
-
-      msg ||= "value must be an integer in the range #{JSS::IBeacon::MAJOR_MINOR_RANGE}"
-      raise JSS::InvalidDataError, msg unless ok
-    end
-
-    # validate a country name or code from JSS::APP_STORE_COUNTRY_CODES
-    # returning the validated code, or raising an error
-    #
-    # @param country[String] The country name or code
-    #
-    # @param msg[String] A custom error message when the value is invalid
-    #
-    # @return [String] the valid two-letter country code
-    #
-    def self.app_store_country_code(country, msg = nil)
-      country = country.to_s.upcase
-      return country if JSS::APP_STORE_COUNTRY_CODES.value? country
-
-      JSS::APP_STORE_COUNTRY_CODES.each do |name, code|
-        return code if name.upcase == country
-      end
-
-      msg ||= 'Unknown country name or code. See JSS::APP_STORE_COUNTRY_CODES or JSS.country_code_match(str)'
-      raise JSS::InvalidDataError, msg
-    end
-
-    # validate an email address - must match the RegEx /^\S+@\S+\.\S+$/
-    # i.e.:
-    #  1 or more non-whitespace chars, followed by
-    #  an @ character, followed by
-    #  1 or more non-whitespace chars, followed by
-    #  a dot, followed by
-    #  1 or more non-whitespace chars
-    #
-    # @param email[String] The email address
-    #
-    # @param msg[String] A custom error message when the value is invalid
-    #
-    # @return [String] the validly formatted email address
-    #
-    def self.email_address(email, msg = nil)
-      msg ||= "'#{email}' is not formatted as a valid email address"
-      email = email.to_s
-      return email if email =~ /^\S+@\S+\.\S+$/
-
-      raise JSS::InvalidDataError, msg
-    end
-
-  end # module validate
-
-end # module JSS

data/test/README.md

@@ -1,147 +0,0 @@
-# About the ruby-jss test suite
-
-For years, I've attempted to use some ruby testing framework to automate testing of ruby-jss.
-
-Every time I've run into walls because unit testing suites are designed for unit testing, and that's not really what we need to do. Yes we need to test individual methods of classes and so on, but when working with a REST API, there's a lot of
-scaffolding that needs to happen before tests can even start - and that scaffolding itself is testing the code. And the details of the scaffolding will vary in different environments. We need to run integration tests.
-
-For example, the tests *must* be very interactive from the start - you have to tell them what server to connect with, what credentials to use, and so on.
-
-Once connected, objects have to be created before they can be listed, fetched, updated, or deleted - so test order matters.
-
-Also, you need to be able to have later tests refer to the same objects you created in earlier tests. Once I've tested that I can create an object on the server and re-fetch it once, I should be able to use that object for all future tests without fetching every time, much less re-creating it every time!
-
-Reading most tutorials about ruby testing just leads you in circles when you consider needs such as these.
-
-Many propnents of unit testing might find this suite odd.  Thats ok. Any functional testing suite is better than none and I'm open to suggestions for improvement.
-
-### Here's how to use it:
-
-tldr:
-
-  `/path/to/your/ruby-jss/gem/installation/test/bin/runtests --server myjss.company.com --user myjssusername`
-
-Must be run on a mac, it uses your keychain to store connection data and credentials, so you only have to provide them the first time or when changing them.
-
-See below for the help output
-
-### Here's how this thing works:
-
- - The tests are ultimatly MiniTest::Spec specifications, defined in files in the 'specs' folder.
-   - See http://ruby-doc.org/stdlib-2.0.0/libdoc/minitest/rdoc/MiniTest.html
-   - also, google around for help with minitest specs
-
-
- - They do NOT use minitest/autorun. Instead, the 'runtests' executable handles loading and running them
-   - See below for the help output
-
-
- - The runtests command, via methods in the JSSTestHelper module, handles connecting to servers.
-   - it takes options to define connection parameters.
-     - At the moment they are limited to user, hostname and port, but will be expanded eventually
-   - it prompts for passwords as needed
-   - it must be run on a Mac! It stores connection parameters in your keychain.
-   - it uses connection parameters from your keychain if they are present. meaning after the first use,
-     it will connect to the same server as the same user with no commandline options.
-   - If any commandline options are different from whats in the keychain, the keychain will be updated,
-     prompting for new passwords if needed.
-
--  The JSSTestHelper module also provides ways for tests to share data.
-
- - The runtests command will run the spec files listed on the command line, or all of them if none are listed.
- - The tests are run verbosely, so you can see what tests are being run.
- - Some tests are interactive - they will ask you to make choices about what's happening.
-
-WARNING: **Be very careful about running these tests on your production JSS !!!**
-
-These tests create and delete objects in the JSS. While they _shouldn't_ hurt any of the existing data - we cannot make any guarantees that they won't hurt something you care about.
-
-As the license text for ruby-jss states, ruby-jss is...
-
-```
-    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-    KIND, either express or implied.
-```
-
-As a reminder, if you connect to the same server that's listed in your /etc/ruby-jss.conf, you'll be asked for confirmation before the tests are run.
-
-
- ### The Spec Files
-
- Each spec file defines one or more MiniTest::Spec's, each one being a 'describe SomeClass' block, containing methods and individual tests in 'it' blocks.
-
- If you plan to write any tests, please read up on how to write MiniTest Specs.
-
- However, here's some info that wasn't obvious when I first started, and makes life much easier when writing specs:
-
- - the 'describe' blocks eventually become classes
-   - you can do anything inside them that you would do in a class definition.
- - the 'it' blocks become methods in the class defined by the 'describe' block.
- - the 'it' blocks are run one at a time, each in a separate instance of the class defined by the 'describe' block.
- - by default, the 'it' blocks are run in a random order. See below if you need them to run in the defined order.
-
- All of the above means that you can use constants, class methods, class-instance variables and instance methods in concert for processing and passing things between the individual tests.
-
-### Running tests in order
-
-The individual spec files are run in the order given on the command line. If none are given on the command line, all files are run in alphabetical order.
-
-If you define multiple 'describe' blocks in a file, they will be run in random order.
-
-The individual tests in a describe block are also run in random order, by default.
-
-If you need the tests to run in order within a 'describe' block, then define this class method somewhere inside it:
-
-       def self.test_order
-         :alpha
-       end
-
-The presence of that method will cause MiniTest to run them in the order defined.
-
-### Help output from 'runtests -H'
-
-
-```
-   Usage: runtests [options] [spec [spec ...]]
-
-   Runs one or more specification tests of ruby-jss.
-
-   The specifications are files in the directory:
-       /Users/chrisl/git/gemdev/ruby-jss/test/specs
-
-   The files must have a _spec.rb suffix, however you need not use the suffix when
-   listing tests to run on the command line, e.g. 'patch_source' will run
-   'patch_source_spec.rb'
-
-   If no specs files are listed on the command line, all will be run, in
-   alphabetical order.
-
-   By default, JSS connection settings are used from your /etc/ruby-jss.conf file
-   and/or ~/.ruby-jss.conf. Connection settings from the command line will be used
-   if provided.
-
-   WARNING: These tests create, modify, and delete objects in the JSS.
-     While no existing objects should be changed, * Be Careful * running them on
-     a production server.
-     If the server you're connecting to matches one defined in /etc/ruby-jss.conf
-     you will be asked for confirmation before proceding.
-
-   The first time you connect from this machine to a given server, you must provide
-   a username for the connection with --user, and will be prompted for the password.
-   Once authenticated, credentials for the server are saved in your keychain, and
-   future connections to that server will read the user & password from there.
-   If a different user is later specified for that server, you'll be prompted again
-   for a password, and the keychain will be updated.
-
-   Options
-     --server, -s <host>         the hostname for the JSS API connection
-     --port, -p <port>           the port for the API connection
-     --user, -u <user>           the API username for the connection
-                                   NOTE: must have permissions to perform the tests!
-     --db-server, -S <host>      the hostname for the JSS API connection
-     --db-port, -P <port>        the port for the API connectino
-     --db-user, -U <user>        the API username for the connection
-     --gem-dir, -g, -i <path>    the path from which to require ruby-jss
-                                   (sets GEM_HOME to this path before requiring)
-     --help, -h, -H              show this help
-```

data/test/lib/testhelper/auth.rb

@@ -1,275 +0,0 @@
-### Copyright 2020 Pixar
-
-###
-###    Licensed under the Apache License, Version 2.0 (the "Apache License")
-###    with the following modification; you may not use this file except in
-###    compliance with the Apache License and the following modification to it:
-###    Section 6. Trademarks. is deleted and replaced with:
-###
-###    6. Trademarks. This License does not grant permission to use the trade
-###       names, trademarks, service marks, or product names of the Licensor
-###       and its affiliates, except as required to comply with Section 4(c) of
-###       the License and to reproduce the content of the NOTICE file.
-###
-###    You may obtain a copy of the Apache License at
-###
-###        http://www.apache.org/licenses/LICENSE-2.0
-###
-###    Unless required by applicable law or agreed to in writing, software
-###    distributed under the Apache License with the above modification is
-###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-###    KIND, either express or implied. See the Apache License for the specific
-###    language governing permissions and limitations under the Apache License.
-###
-###
-
-module JSSTestHelper
-
-  # auth
-  module Auth
-
-    KEYCHAIN_LABEL_BASE = 'com.pixar.ruby-jss.testing'.freeze
-
-    KEYCHAIN_JSS_LABEL = KEYCHAIN_LABEL_BASE + '.api'
-    KEYCHAIN_DB_LABEL = KEYCHAIN_LABEL_BASE + '.db'
-    KEYCHAIN_DIST_LABEL = KEYCHAIN_LABEL_BASE + '.distribution'
-
-    KEYCHAIN_DIST_ACCT = 'From JSS'.freeze
-
-    KEYCHAIN_LABELS = {
-      jss: KEYCHAIN_JSS_LABEL,
-      db: KEYCHAIN_DB_LABEL,
-      dist: KEYCHAIN_DIST_LABEL
-    }.freeze
-
-    module_function
-
-    # return the user's API password, prompting for it if we don't already have
-    # it
-    #
-    def api_pw(server: nil, port: nil, user: nil)
-      return @api_pw if @api_pw
-      # If we're here, we need to get the pw via prompt
-      @api_pw = prompt_for_password prompt: "Enter the API password for #{user}@#{server}:#{port}" do |apw|
-        begin
-          JSS.api.disconnect
-          JSS.api.connect user: user, pw: apw, server: server, port: port
-          true
-        rescue JSS::AuthenticationError
-          false
-        end # begin
-      end # do apw
-      raise JSS::AuthenticationError, "Incorrect API password for #{user}@#{server}:#{port}" unless @api_pw
-      @api_pw
-    end
-
-    # return the server, port, and user, which we might have gotten fromthe keychain
-    def connect_to_api(server: nil, user: nil, port: nil, pw: nil)
-      return if JSS.api.connected?
-
-      JSS.api.connect server: server, port: port, user: user, pw: pw
-      @api_pw = pw
-      { server: JSS.api.hostname, port: JSS.api.port, user: JSS.api.jss_user }
-    rescue JSS::AuthenticationError
-      # If we're here, we need to prompt for the pw
-      pw = api_pw server: server, port: port, user: user
-    ensure
-      # store the pw
-      save_rw_credentials label: KEYCHAIN_JSS_LABEL, acct: JSS.api.jss_user, server: JSS.api.hostname, port: JSS.api.port, pw: pw if JSS.api.connected?
-    end
-
-    # TODO: update this as API above so there's only one per keychain.
-    def db_pw
-      return @db_pw if @db_pw
-
-      # If we're here, we need to get the passwd for the user
-      @db_pw = prompt_for_password prompt: "Enter the MySQL password for #{@db_user}@#{@db_server}" do |apw|
-        begin
-          JSS::DB_CNX.disconnect
-          JSS::DB_CNX.connect server: @db_server, user: @db_user, pw: apw
-          true
-        rescue Mysql::ServerError::AccessDeniedError
-          false
-        end # begin
-      end # do apw
-
-      raise JSS::AuthenticationError, "Incorrect MySQL password for #{@db_user}@#{@db_server}" unless @db_pw
-      @db_pw
-    end
-
-    # TODO: update this as API above so there's only one per keychain.
-    def connect_to_db(server: nil, user: nil)
-      return if JSS::DB_CNX.connected?
-      @db_server = server ? server : JSS::CONFIG.api_server_name
-      @db_user = user
-
-      raise 'No db_server_name defined in /etc/ruby-jss.conf. Please specify with --db-server' unless @db_server
-
-      # look in the keychain
-      keychain_creds = rw_credentials_from_keychain(:db, @db_server, @db_user)
-
-      # did we get a user/pw? Use it
-      if keychain_creds
-        @db_user ||= keychain_creds[:user]
-        begin
-          JSS::DB_CNX.connect server: @db_server, user: @db_user, pw: keychain_creds[:password]
-
-          return
-        rescue Mysql::ServerError::AccessDeniedError
-          # re-prompt if bad pw in keychain
-          say "Stored MySQL password for #{@db_user}@#{@db_server} is incorrect"
-        end # begin
-      else
-        # Couldn't find a stored user for server, and no user given on CLI - error.
-        raise "No user stored for MySQL server '#{@db_server}'. Please specify with --db-user" unless @db_user
-      end
-
-      # If we're here, we need to get the passwd for the user
-      pw = db_pw
-
-      # store the pw
-      save_rw_credentials KEYCHAIN_DB_LABEL, @db_user, @db_server, pw
-    end
-
-    # TODO: pass in the API server for which we want the dist point pw
-    # must be connected to api
-    # and make it like API connection above, 1 per keychain.
-    def dist_point_pw
-      keychain_creds = rw_credentials_from_keychain(:db, @api_server, KEYCHAIN_DIST_ACCT)
-      if keychain_creds
-        @distpw = keychain_creds[:password]
-        return @distpw if JSS::DistributionPoint.master_distribution_point.check_pw :rw, distpw
-      end
-
-      # if we're here, there was no stored pw or it was incorrect
-
-      # If we're here, we need to get the passwd for the master dist point
-      prmpt = "Enter the RW password for the Master Distribution Point on JSS #{@api_server}"
-      @distpw = prompt_for_password prompt: prmpt do |apw|
-        JSS::DistributionPoint.master_distribution_point.check_pw :rw, apw
-      end # do apw
-
-      raise JSS::AuthenticationError, "Incorrect RW password for the Master Distribution Point on JSS #{@api_server}" unless @distpw
-
-      # store the pw
-      save_rw_credentials KEYCHAIN_DIST_LABEL, KEYCHAIN_DIST_ACCT, @api_server, @distpw
-      @distpw
-    end
-
-    # Fetch read-write credentials from the login keychain
-    #
-    # If the login keychain is locked, the user will be prompted
-    # to unlock it in the GUI.
-    #
-    # @param kind[Symbol] which kind of credentials? :jss, :db, or :dist
-    #
-    # @return [Hash{Symbol => String}, nil] A Hash with :server, :user and :password
-    #   values, nil if no matching keychain item.
-    #
-    def rw_credentials_from_keychain(kind)
-      Keychain.user_interaction_allowed = true
-      unlock_keychain
-      label = KEYCHAIN_LABELS[kind]
-      raise JSS::InvalidDataError, "argument must be one of :#{RW_CREDENTIAL_KINDS.join ', :'}" unless label
-
-      pw_search = { label: label }
-      pw_item = Keychain.default.internet_passwords.where(pw_search).first
-
-      return nil unless pw_item
-
-      { server: pw_item.server, user: pw_item.account, pw: pw_item.password, port: pw_item.port }
-    end
-
-    # Save the credentials in the login keychain
-    #
-    # @param user[String] the username to save
-    #
-    # @param pw[String] the password to save with the username
-    #
-    # @return [void]
-    #
-    def save_rw_credentials(label: nil, acct: nil, server: nil, pw: nil, port: nil)
-      Keychain.default.internet_passwords.where(label: label).all.each(&:delete)
-      item = Keychain.default.internet_passwords.create label: label, account: acct, server: server, password: pw, port: port
-      item.save!
-    end
-
-    # Prompt the user to unlock the default keychain
-    #
-    # @return [void]
-    #
-    def unlock_keychain
-      return true unless Keychain.default.locked?
-      unlocked = prompt_for_password prompt: 'Enter your keychain password' do |pw|
-        begin
-          Keychain.default.unlock! pw
-          true
-        rescue Keychain::AuthFailedError
-          false
-        end # begin
-      end # prompt for pass
-      raise JSS::AuthenticationError, 'Failed to unlock default keychain' unless unlocked
-    end # unlock keychain
-
-    # Prompt the user for a password in the shell
-    # Returns:
-    #   - a valid password, or
-    #   - false if no valid password after the max number of tries
-    #
-    # Displays the provided promp. Passes what the user types to the block you
-    # provide, which must return a Boolean indicating if the password was correct.
-    #
-    # @param prompt[String] The message asking for the password
-    #
-    # @option max_tries[Integer] The max number of times to let the
-    #   user enter the passwd. Defaults to 3
-    #
-    # @option retry_msg[String] the text to display after a failure,
-    #   but before :max_tries failures. Defaults to "Try again: " followed
-    #   by the text arg.
-    #
-    # @option failed_msg[String] The message to display after :max_tries
-    #   failures. Defaults to  "Too many failed attempts"
-    #
-    # @yield The block should figure out if the user typed the correct password
-    #
-    # @yieldparam pw [String] The password typed by the user in the input field
-    #
-    # @yieldreturn [Boolean] Was the password correct?
-    #
-    # @return [String] The validated password
-    # @return [false] The user failed after max_tries: attempts.
-    #
-    #
-    def prompt_for_password(**options)
-      colon = ':'
-      # set defaults
-      options[:prompt] ||= 'Enter your password:'
-      options[:prompt] << colon unless options[:prompt].end_with? colon
-      options[:max_tries] ||= 3
-      options[:retry_msg] ||= "Try Again. #{options[:prompt]}"
-      options[:failed_msg] ||= 'Too many failed attempts'
-
-      tries = 0
-
-      prompt = options[:prompt]
-
-      while tries < options[:max_tries]
-        print "#{prompt} "
-        system 'stty -echo'
-        pw = $stdin.gets.chomp
-        puts
-        system 'stty echo'
-        return pw if yield pw
-        prompt = options[:retry_msg]
-        tries += 1
-      end
-      puts options[:failed_msg]
-      false
-    ensure # make sure terminal is usable at the end of this
-      system 'stty echo'
-    end # prompt_for_password
-
-  end # module auth
-
-end # module JSSTestHelper