ruby-jss 1.2.10 → 1.5.2

data/lib/jss/composer.rb

@@ -147,7 +147,7 @@ module JSS
 
       ### now build the pkg
       begin
-        it_built = system "#{PKGBUILD} --identifier '#{pkg_id}' --version '#{version}' --ownership #{pkg_ownership} --install-location / --root '#{root}' #{signing} #{comp_plist_arg} '#{pkg_out}' "
+        it_built = system "#{PKGBUILD} --identifier '#{pkg_id}' --version '#{version}' --ownership #{pkg_ownership} --install-location / --root '#{root}' #{signing} #{comp_plist_arg} '#{pkg_out}'"
 
         raise 'There was an error building the .pkg' unless it_built
       ensure

data/lib/jss/exceptions.rb

@@ -87,6 +87,9 @@ module JSS
   ###
   class AuthenticationError < RuntimeError; end
 
+  ###
+  class AuthorizationError < RuntimeError ; end
+
   ### ConflictError - raise this when
   ### attempts to PUT or PUSH to the API
   ### result in a 409 Conflict http error.

data/lib/jss/server.rb

@@ -110,6 +110,21 @@ module JSS
       @act_code_data[:code]
     end
 
+    # Update the activation code and organization name for this server
+    #
+    # @param org: [String] the organization to which the server is licensed
+    # @param code: [String ]  the activation code for the server licence
+    #
+    # @return [void]
+    def update_activation_code(org:, code:)
+      xml = REXML::Document.new JSS::APIConnection::XML_HEADER
+      acode = xml.add_element ACTIVATION_CODE_KEY.to_s
+      acode.add_element('organization_name').text = org
+      acode.add_element('code').text = code
+
+      @api.put_rsrc ACTIVATION_CODE_RSRC, xml.to_s
+    end
+
     # Remove the api object from
     # the instance_variables used to create
     # pretty-print (pp) output.

data/lib/jss/utility.rb

@@ -23,73 +23,157 @@
 #
 #
 
-#
 module JSS
 
   # A collection of useful utility methods. Mostly for
   # converting values between formats, parsing data, and
   # user interaction.
 
-  # Converts an OS Version into an Array of higher OS versions.
+  # Hash of 'minor' => 'maint'
+  # The maximum maint release for macOS 10.minor.maint
+  # e.g the highest release of 10.6 was 10.6.8, the highest release of
+  # 10.15 was 10.15.7
+  #
+  # 12 is the default for the current OS and higher
+  # (and hoping apple doesn't release 10.16.13)
+  OS_TEN_MAXS = {
+      2 => 8,
+      3 => 9,
+      4 => 11,
+      5 => 8,
+      6 => 8,
+      7 => 5,
+      8 => 5,
+      9 => 5,
+      10 => 5,
+      11 => 6,
+      12 => 6,
+      13 => 6,
+      14 => 6,
+      15 => 7,
+      16 => 12
+    }
+
+  # Hash of 'major' => 'minor'
+  # The maximum minor release for macOS major.minor
+  # e.g. the highest release of 11 is 11.12
+  #
+  # 12 is the default for the current OS and higher
+  # (and hoping apple doesn't release 11.13)
+  MAC_OS_MAXS = {
+    11 => 12,
+    12 => 12,
+    13 => 12,
+    14 => 12,
+    15 => 12,
+    16 => 12,
+    17 => 12,
+    18 => 12,
+    19 => 12,
+    20 => 12
+  }
+
+  # Converts an OS Version into an Array of equal or higher OS versions, up to
+  # some non-existant max, hopefully far in the future, currently 20.12
+  #
+  # This array can then be joined with commas and used as the value of the
+  # os_requirements for Packages and Scripts.
+  #
+  # It's unlikely that this method, as written, will still be in use by
+  # the release of macOS 20.12, but currently thats the upper limit.
+  #
+  # Hopefully well before then JAMF will implement a "minimum OS" in Jamf Pro
+  # itself, then we could avoid the inherant limitations in using a method like
+  # this.
   #
-  # It's unlikely that this library will still be in use as-is by the release of OS X 10.19.15.
-  # Hopefully well before then JAMF will implement a "minimum OS" in the JSS itself.
+  # When the highest maint. release of an OS version is not known, because its
+  # the currently released OS version or higher, then this method assumes '12'
+  # e.g. '10.16.12', '11.12', '12.12', etc.
   #
-  # @param min_os [String] the mimimum OS version to expand, e.g. ">=10.6.7"  or "10.6.7"
+  # Apple has never released more than 11 updates to a version of macOS
+  # (that being 10.4), so hopefully 12 is enough
   #
-  # @return [Array] Nearly all potential OS versions from the minimum to 10.19.x.
+  # Since Big Sur might report itself as either '10.16.x' or '11.x', this method
+  # will allow for both possibilities, and the array will contain whatever
+  # iterations needed for both version numbers
+  #
+  # @param min_os [String] the mimimum OS version to expand, e.g. ">=10.9.4"  or "11.1"
+  #
+  # @return [Array] Nearly all potential OS versions from the minimum to 20.12
   #
   # @example
-  #   JSS.expand_min_os ">=10.6.7" # => returns this array
-  #    # ["10.6.7",
-  #    #  "10.6.8",
-  #    #  "10.6.9",
-  #    #  "10.6.10",
-  #    #  "10.6.11",
-  #    #  "10.6.12",
-  #    #  "10.6.13",
-  #    #  "10.6.14",
-  #    #  "10.6.15",
-  #    #  "10.7.x",
-  #    #  "10.8.x",
-  #    #  "10.9.x",
-  #    #  "10.10.x",
-  #    #  "10.11.x",
-  #    #  "10.12.x",
-  #    #  "10.13.x",
-  #    #  "10.14.x",
-  #    #  "10.15.x",
+  #   JSS.expand_min_os ">=10.9.4" # => returns this array
+  #    # ["10.9.4",
+  #    #  "10.9.5",
+  #    #  "10.10.x"
+  #    #  ...
   #    #  "10.16.x",
-  #    #  "10.17.x",
-  #    #  "10.18.x",
-  #    #  "10.19.x"]
+  #    #  "11.x",
+  #    #  "12.x",
+  #    #  ...
+  #    #  "20.x"]
   #
   #
   def self.expand_min_os(min_os)
     min_os = min_os.delete '>='
 
     # split the version into major, minor and maintenance release numbers
-    (maj, min, maint) = min_os.split('.')
+    major, minor, maint = min_os.split('.')
     maint = 'x' if maint.nil? || maint == '0'
 
-    # if the maint release number is an "x" just start the list of OK OS's with it
-    if maint == 'x'
-      ok_oses = [maj + '.' + min.to_s + '.x']
+    ok_oses = []
+
+    # if major == 11 e.g. big sur, e.g. 10.16,
+    # reset major & min so that we get coverage for both
+    # 10.16 and 11, since clients may report it as either
+    if major == '11'
+      major = '10'
+      maint = minor
+      minor = '16'
+    end
+
+    # Deal with 10.x.x up to 10.16
+    if major == '10'
+      # if the maint release number is an "x" just start the list of OK OS's with it
+      if maint == 'x'
+        ok_oses << min_os
+
+      # otherwise, start with it and explicitly add all maint releases for
+      # that maint version. if unknown because its a current or future OS,
+      # go as h
+      else
+        max_maint_for_minor = OS_TEN_MAXS[minor.to_i]
+        (maint.to_i..max_maint_for_minor).each do |m|
+          ok_oses << "#{major}.#{minor}.#{m}"
+        end # each m
+      end
+
+      # now account for all macOS versions starting with 10.
+      # up to 10.16.x
+      ((minor.to_i + 1)..16).each do |v|
+        ok_oses << "#{major}.#{v}.x"
+      end # each v
+
+      # now reset major to 11, so we can continue with BigSur and up
+      major = '11'
+      minor = minor == '16' ? maint : 'x'
+    end # if major == 10
 
-    # otherwise, start with it and explicitly add all maint releases up to 15
-    # (and hope apple doesn't do more than 15 maint releases for an OS)
+    # Now deal with Big Sur and higher, macOS 10.16/11
+    if minor == 'x'
+      ok_oses << "#{major}.#{minor}"
     else
-      ok_oses = []
-      (maint.to_i..15).each do |m|
-        ok_oses << maj + '.' + min + '.' + m.to_s
+      max_minor_for_major = MAC_OS_MAXS[major.to_i]
+      (minor.to_i..max_minor_for_major).each do |m|
+        ok_oses << "#{major}.#{m}"
       end # each m
-    end
+    end # if minor == x
 
-    # now account for all OS X versions starting with 10.
-    # up to at least 10.19.x
-    ((min.to_i + 1)..19).each do |v|
-      ok_oses << maj + '.' + v.to_s + '.x'
+    # now account for all macOS versions 11 and up
+    ((major.to_i + 1)..MAC_OS_MAXS.keys.max).each do |v|
+      ok_oses << "#{v}.x"
     end # each v
+
     ok_oses
   end
 
@@ -109,6 +193,7 @@ module JSS
   #
   def self.processor_ok?(requirement, processor = nil)
     return true if requirement.to_s.empty? || requirement =~ /none/i
+
     processor ||= `/usr/bin/uname -p`
     requirement == (processor.to_s.include?('86') ? 'x86' : 'ppc')
   end
@@ -129,6 +214,7 @@ module JSS
   def self.os_ok?(requirement, os_to_check = nil)
     return true if requirement.to_s =~ /none/i
     return true if requirement.to_s == 'n'
+
     requirement = JSS.to_s_and_a(requirement)[:arrayform]
     return true if requirement.empty?
 
@@ -201,6 +287,7 @@ module JSS
     case plist
     when String
       return Plist.parse_xml plist if plist.include? '</plist>'
+
       plist = Pathname.new plist
     when Pathname
       true
@@ -237,9 +324,7 @@ module JSS
 
     # if the UTC offset of the datetime is zero, make a new one with the correct local offset
     # (which might also be zero if we happen to be in GMT)
-    if the_dt.offset.zero?
-      the_dt = DateTime.new(the_dt.year, the_dt.month, the_dt.day, the_dt.hour, the_dt.min, the_dt.sec, JSS::TIME_ZONE_OFFSET)
-    end
+    the_dt = DateTime.new(the_dt.year, the_dt.month, the_dt.day, the_dt.hour, the_dt.min, the_dt.sec, JSS::TIME_ZONE_OFFSET) if the_dt.offset.zero?
     # now convert it to a Time and return it
     Time.at the_dt.strftime('%s').to_i, usec
   end # parse_time
@@ -261,6 +346,7 @@ module JSS
   #
   def self.epoch_to_time(epoch)
     return nil if NIL_DATES.include? epoch
+
     Time.at(epoch.to_i / 1000.0)
   end # parse_date
 
@@ -280,6 +366,7 @@ module JSS
   def self.api_object_class(name)
     klass = api_object_names[name.downcase.to_sym]
     raise JSS::InvalidDataError, "Unknown API Object Class: #{name}" unless klass
+
     klass
   end
 
@@ -297,11 +384,13 @@ module JSS
   #
   def self.api_object_names
     return @api_object_names if @api_object_names
+
     @api_object_names ||= {}
     JSS.constants.each do |const|
       klass = JSS.const_get const
       next unless klass.is_a? Class
       next unless klass.ancestors.include? JSS::APIObject
+
       @api_object_names[klass.const_get(:RSRC_LIST_KEY).to_sym] = klass if klass.constants.include? :RSRC_LIST_KEY
       @api_object_names[klass.const_get(:RSRC_OBJECT_KEY).to_sym] = klass if klass.constants.include? :RSRC_OBJECT_KEY
     end
@@ -338,6 +427,7 @@ module JSS
   #
   def self.array_to_rexml_array(element, list)
     raise JSS::InvalidDataError, 'Arg. must be an Array.' unless list.is_a? Array
+
     element = element.to_s
     list.map do |v|
       e = REXML::Element.new(element)
@@ -364,6 +454,7 @@ module JSS
   #
   def self.hash_to_rexml_array(hash)
     raise InvalidDataError, 'Arg. must be a Hash.' unless hash.is_a? Hash
+
     ary = []
     hash.each_pair do |k, v|
       el = REXML::Element.new k.to_s
@@ -442,11 +533,11 @@ module JSS
 
     {
       major: major.to_i,
-      minor:  minor.to_i,
-      revision:  revision.to_i,
-      maint:  revision.to_i,
-      patch:  revision.to_i,
-      build:  build,
+      minor: minor.to_i,
+      revision: revision.to_i,
+      maint: revision.to_i,
+      patch: revision.to_i,
+      build: build,
       version: Gem::Version.new("#{major}.#{minor}.#{revision}")
     }
   end
@@ -471,6 +562,7 @@ module JSS
     @stdin_lines ||= ($stdin.tty? ? [] : $stdin.read.lines.map { |l| l.chomp("\n") })
 
     return @stdin_lines.join("\n") if line <= 0
+
     idx = line - 1
     @stdin_lines[idx]
   end
@@ -503,10 +595,9 @@ module JSS
   # @return [Boolean] The new state of devmode
   #
   def self.devmode(setting)
-    @devmode = setting == :on ? true : false
+    @devmode = setting == :on
   end
 
-
   # is devmode currently on?
   #
   # @return [Boolean]

data/lib/jss/validate.rb

@@ -111,8 +111,8 @@ module JSS
 
     # Confirm that the given value is a boolean value, accepting
     # strings and symbols and returning real booleans as needed
-    # Accepts: true, false, 'true', 'false', :true, :false, 'yes', 'no', :yes,
-    # or :no (all Strings and Symbols are case insensitive)
+    # Accepts: true, false, 'true', 'false', 'yes', 'no', 't','f', 'y', or 'n'
+    # as strings or symbols, case insensitive
     #
     # TODO: use this throughout ruby-jss
     #
@@ -123,11 +123,11 @@ module JSS
     # @return [Boolean] the valid boolean
     #
     def self.boolean(bool, msg = nil)
-      msg ||= 'Value must be boolean true or false'
       return bool if JSS::TRUE_FALSE.include? bool
-      return true if bool.to_s =~ /^(true|yes)$/i
-      return false if bool.to_s =~ /^(false|no)$/i
+      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
 
@@ -176,10 +176,10 @@ module JSS
     # @return [String] the valid uuid string
     #
     def self.uuid(val, msg = nil)
-      msg ||= 'value must be valid uuid'
-      raise JSS::InvalidDataError, msg unless val.is_a?(String) && val =~ UUID_RE
+      return val if val.is_a?(String) && val =~ UUID_RE
 
-      val
+      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
@@ -191,13 +191,56 @@ module JSS
     # @return [String] the valid integer
     #
     def self.ibeacon_major_minor(val, msg = nil)
-      msg ||= "value must be an integer in the range #{JSS::IBeacon::MAJOR_MINOR_RANGE}"
       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
 
-      val
+    # 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