comet_backup_ruby_sdk 1.7.0 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5978dc4b2eb4c0001eb7a7c44b3a215450fcbdc9ad7e639c75ba4b9b023b9ac5
-  data.tar.gz: 8bfd3b9417fefa6bde04316a2fbd6917ded287594e42cc64d989f56be52a6af4
+  metadata.gz: 6d320abff24079c6c63042f2319ab6bf85895df807ae4e3c64e28f124931439d
+  data.tar.gz: 54992cd97acfdea46b281ec833bd6b42a5ee56968ca0f6a9a59a2dfaee4ee97b
 SHA512:
-  metadata.gz: 7bf9d9f36941632b74473ab2d6aeb6d0252951bdcf9be1b6f9ef9b1e595bc2cd91ee813f689d9e84c0b08442378799c8e6fd563c43aef40fd75f23b57d33d5bc
-  data.tar.gz: 859734f1a066f09426fb736ab83e28fa1b829ed795db56ed403622825fdf701723e25465f511be44e9316876d5d5f9e2a5f3904569005b1930db78aca3773a8c
+  metadata.gz: 3554197606a2d10499e981d642f7b2ad5645b2a424f13be88cf0be3d118da6c6df0caf9a784cc1d0c2536f9b591ef8320b1a04e46fffe0e42c4372c677dafa87
+  data.tar.gz: '0921fc302340b38c77bb6f7733c447d274347dc7379a8916b7f5a4fea0b97c666cdc126d793075be180ea40d431db1449659f279779bf965513c7e5af1235cb2'

data/.gitignore

@@ -0,0 +1 @@
+*.gem

data/CHANGELOG.md

@@ -1,4 +1,31 @@
 # CHANGELOG
+
+## 2021-12-22 v1.11.0
+- Based on 21.12.1
+- Add `AdminAccountWebauthnRegistration` endpoint for new webauthn support.
+- Deprecate `AdminACcountU2fSubmitChallenge` as U2F is ending browser support in February 2022.
+
+## 2021-11-24 v1.10.0
+- Based on 21.9.12
+- Add support for Thai and Danish localizations
+- Add From and To fields to the EmailReportGenerated API
+- Add `AdminDispatcherEmailPreview` api method for requesting the HTML content of an email
+- Add `ImageEtag` field to the response of the ServerMetaBrandingProperties endpoint.
+- Add support for new engine properties on the Office365 backup type.
+- Add `AdminDispatcherOffice365ListVirtualAccounts` api method for requesting Objects that Office365 is capable of backing up.
+
+## 2021-10-21 1.9.0
+- Based on 21.9.7
+- Add Support for `HideFiles` parameter in B2 Destination Locations
+- Add support for `RegistrationTime` to `DeviceConfig`
+- Upgrade MYSQL to support new TLS connection options
+- Add support for new API: `AdminMetaReadAllLogsRequest` and `AdminDispatcherRequestWindiskSnapshot`
+
+## 2021-09-14 1.8.0
+- Based on Comet 21.9.2
+- Support new `custom_headers` field on the `WebhookOption` class for specifying custom HTTP headers
+  to be sent in webhook POST requests from Comet Server
+
 ## 2021-09-08 v1.7.0
 - Based on Comet 21.9.1
 - Support new `device_timezone` field on the `DeviceConfig` class. 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    comet_backup_ruby_sdk (1.7.0)
+    comet_backup_ruby_sdk (1.10.0)
 
 GEM
   remote: https://rubygems.org/
@@ -33,11 +33,11 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  bundler (~> 1.17)
+  bundler (~> 2.1.4)
   comet_backup_ruby_sdk!
   minitest (~> 5.14)
   rake (~> 13.0)
   rubocop (~> 0.88)
 
 BUNDLED WITH
-   1.17.2
+   2.1.4

data/README.md

@@ -84,7 +84,7 @@ end
 ```ruby
 bundle exec rake rubocop
 
-COMETSERVER_ADDRESS='http://127.0.0.1:8060' \
+  COMETSERVER_ADDRESS='http://127.0.0.1:8060' \
 	COMETSERVER_ADMINUSER=admin \
 	COMETSERVER_ADMINPASS=admin \
 	bundle exec rake test

data/RELEASING.md

@@ -1,5 +1,6 @@
 # Procedure for releasing gem package updates
 
+0. As a cygwin user, with docker installed; `docker run -it -v "c://cygwin64/$PWD":/app -w /app ruby:2.7 bash` will get you with a suitable ruby environment for testing/building and releasing this package9.
 1. All tests passing
 2. Update changelog in `CHANGELOG.md`
 3. Update version number in `comet_backup_ruby_sdk.gemspec`

data/comet_backup_ruby_sdk.gemspec

@@ -12,7 +12,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
   spec.name          = 'comet_backup_ruby_sdk'
-  spec.version       = '1.7.0'
+  spec.version       = '1.11.0'
   spec.authors       = ['Comet Licensing Ltd.']
   spec.email         = ['hello@cometbackup.com']
 
@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
   end
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1.17'
+  spec.add_development_dependency 'bundler', '~> 2.1.4'
   spec.add_development_dependency 'minitest', '~> 5.14'
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rubocop', '~> 0.88'

data/lib/comet/comet_server.rb

@@ -96,7 +96,7 @@ module Comet
     #
     # You must supply administrator authentication credentials to use this API.
     #
-    # @param [String] self_address (Optional) External URL of this server (used for U2F AppID)
+    # @param [String] self_address (Optional) External URL of this server
     # @return [Comet::SessionKeyRegeneratedResponse]
     def admin_account_session_start(self_address = nil)
       submit_params = {}
@@ -166,6 +166,9 @@ module Comet
     # AdminAccountU2fRequestRegistrationChallenge
     #
     # Register a new FIDO U2F token.
+    # Browser support for U2F is ending in February 2022. WebAuthn is backwards
+    # compatible with U2F keys, and Comet will automatically migrate existing U2F keys
+    # to allow their use with the WebAuthn endpoints.
     #
     # You must supply administrator authentication credentials to use this API.
     #
@@ -188,6 +191,9 @@ module Comet
     # AdminAccountU2fSubmitChallengeResponse
     #
     # Register a new FIDO U2F token.
+    # Browser support for U2F is ending in February 2022. WebAuthn is backwards
+    # compatible with U2F keys, and Comet will automatically migrate existing U2F keys
+    # to allow their use with the WebAuthn endpoints.
     #
     # You must supply administrator authentication credentials to use this API.
     #
@@ -245,6 +251,58 @@ module Comet
       ret
     end
 
+    # AdminAccountWebauthnRequestRegistrationChallenge
+    #
+    # Register a new FIDO2 WebAuthn token.
+    #
+    # You must supply administrator authentication credentials to use this API.
+    #
+    # @param [String] self_address External URL of this server, used as WebAuthn ID
+    # @return [Comet::WebAuthnRegistrationChallengeResponse]
+    def admin_account_webauthn_request_registration_challenge(self_address)
+      submit_params = {}
+      raise TypeError, "'self_address' expected String, got #{self_address.class}" unless self_address.is_a? String
+
+      submit_params['SelfAddress'] = self_address
+
+      body = perform_request('api/v1/admin/account/webauthn/request-registration-challenge', submit_params)
+      json_body = JSON.parse body
+      check_status json_body
+      ret = Comet::WebAuthnRegistrationChallengeResponse.new
+      ret.from_hash(json_body)
+      ret
+    end
+
+    # AdminAccountWebauthnSubmitChallengeResponse
+    #
+    # Register a new FIDO2 WebAuthn token.
+    #
+    # You must supply administrator authentication credentials to use this API.
+    #
+    # @param [String] self_address External URL of this server, used as WebAuthn ID
+    # @param [String] challenge_id Associated value from AdminAccountWebAuthnRequestRegistrationChallenge API
+    # @param [String] credential JSON-encoded credential
+    # @return [Comet::CometAPIResponseMessage]
+    def admin_account_webauthn_submit_challenge_response(self_address, challenge_id, credential)
+      submit_params = {}
+      raise TypeError, "'self_address' expected String, got #{self_address.class}" unless self_address.is_a? String
+
+      submit_params['SelfAddress'] = self_address
+      raise TypeError, "'challenge_id' expected String, got #{challenge_id.class}" unless challenge_id.is_a? String
+
+      submit_params['ChallengeID'] = challenge_id
+      raise TypeError, "'credential' expected String, got #{credential.class}" unless credential.is_a? String
+
+      submit_params['Credential'] = credential
+
+      body = perform_request('api/v1/admin/account/webauthn/submit-challenge-response', submit_params)
+      json_body = JSON.parse body
+      check_status json_body
+      ret = Comet::CometAPIResponseMessage.new
+      ret.from_hash(json_body)
+      ret
+    end
+
     # AdminAddUser
     #
     # Add a new user account.
@@ -1001,6 +1059,42 @@ module Comet
       ret
     end
 
+    # AdminDispatcherEmailPreview
+    #
+    # Request HTML content of an email.
+    # The remote device must have given consent for an MSP to browse their mail
+    #
+    # You must supply administrator authentication credentials to use this API.
+    # This API requires the Auth Role to be enabled.
+    #
+    # @param [String] target_id The live connection GUID
+    # @param [String] snapshot where the email belongs to
+    # @param [String] destination The Storage Vault ID
+    # @param [String] path of the email to view
+    # @return [Comet::EmailReportGeneratedPreview]
+    def admin_dispatcher_email_preview(target_id, snapshot, destination, path)
+      submit_params = {}
+      raise TypeError, "'target_id' expected String, got #{target_id.class}" unless target_id.is_a? String
+
+      submit_params['TargetID'] = target_id
+      raise TypeError, "'snapshot' expected String, got #{snapshot.class}" unless snapshot.is_a? String
+
+      submit_params['Snapshot'] = snapshot
+      raise TypeError, "'destination' expected String, got #{destination.class}" unless destination.is_a? String
+
+      submit_params['Destination'] = destination
+      raise TypeError, "'path' expected String, got #{path.class}" unless path.is_a? String
+
+      submit_params['Path'] = path
+
+      body = perform_request('api/v1/admin/dispatcher/email-preview', submit_params)
+      json_body = JSON.parse body
+      check_status json_body
+      ret = Comet::EmailReportGeneratedPreview.new
+      ret.from_hash(json_body)
+      ret
+    end
+
     # AdminDispatcherImportApply
     #
     # Instruct a live connected device to import settings from an installed product.
@@ -1077,6 +1171,34 @@ module Comet
       ret
     end
 
+    # AdminDispatcherOffice365ListVirtualAccounts
+    #
+    # Request a list of Office365 Resources (groups, sites, teams groups and users).
+    # The remote device must have given consent for an MSP to browse their files.
+    #
+    # You must supply administrator authentication credentials to use this API.
+    # This API requires the Auth Role to be enabled.
+    #
+    # @param [String] target_id The live connection GUID
+    # @param [Comet::Office365Credential] credentials The Office365 account credential
+    # @return [Comet::BrowseOffice365ListVirtualAccountsResponse]
+    def admin_dispatcher_office_365list_virtual_accounts(target_id, credentials)
+      submit_params = {}
+      raise TypeError, "'target_id' expected String, got #{target_id.class}" unless target_id.is_a? String
+
+      submit_params['TargetID'] = target_id
+      raise TypeError, "'credentials' expected Comet::Office365Credential, got #{credentials.class}" unless credentials.is_a? Comet::Office365Credential
+
+      submit_params['Credentials'] = credentials.to_json
+
+      body = perform_request('api/v1/admin/dispatcher/office365-list-virtual-accounts', submit_params)
+      json_body = JSON.parse body
+      check_status json_body
+      ret = Comet::BrowseOffice365ListVirtualAccountsResponse.new
+      ret.from_hash(json_body)
+      ret
+    end
+
     # AdminDispatcherPingDestination
     #
     # Test the connection to the storage bucket.
@@ -1563,6 +1685,37 @@ module Comet
       ret
     end
 
+    # AdminDispatcherRequestWindiskSnapshot
+    #
+    # Request a Disk Image snapshot with the windiskbrowse-style from a live connected device.
+    #
+    # You must supply administrator authentication credentials to use this API.
+    # This API requires the Auth Role to be enabled.
+    #
+    # @param [String] target_id The live connection GUID
+    # @param [String] destination The Storage Vault ID
+    # @param [String] snapshot_id The Snapshot ID
+    # @return [Comet::DispatcherWindiskSnapshotResponse]
+    def admin_dispatcher_request_windisk_snapshot(target_id, destination, snapshot_id)
+      submit_params = {}
+      raise TypeError, "'target_id' expected String, got #{target_id.class}" unless target_id.is_a? String
+
+      submit_params['TargetID'] = target_id
+      raise TypeError, "'destination' expected String, got #{destination.class}" unless destination.is_a? String
+
+      submit_params['Destination'] = destination
+      raise TypeError, "'snapshot_id' expected String, got #{snapshot_id.class}" unless snapshot_id.is_a? String
+
+      submit_params['SnapshotID'] = snapshot_id
+
+      body = perform_request('api/v1/admin/dispatcher/request-windisk-snapshot', submit_params)
+      json_body = JSON.parse body
+      check_status json_body
+      ret = Comet::DispatcherWindiskSnapshotResponse.new
+      ret.from_hash(json_body)
+      ret
+    end
+
     # AdminDispatcherRunBackup
     #
     # Instruct a live connected device to run a scheduled backup.
@@ -2139,6 +2292,7 @@ module Comet
     # Cancel a running job.
     # A request is sent to the live-connected device, asking it to cancel the operation. This may fail if there is no live-connection.
     # Only jobs from Comet 18.3.5 or newer can be cancelled. A job can only be cancelled if it has a non-empty CancellationID field in its properties.
+    # If the device is running Comet 21.9.5 or later, this API will wait up to ten seconds for a confirmation from the client.
     #
     # You must supply administrator authentication credentials to use this API.
     # This API requires the Auth Role to be enabled.
@@ -2318,6 +2472,20 @@ module Comet
       ret
     end
 
+    # AdminMetaReadAllLogs
+    #
+    # Get a ZIP file of all of the server's log files.
+    # On non-Windows platforms, log content uses LF line endings. On Windows, Comet changed from LF to CRLF line endings in 18.3.2.
+    # This API does not automatically convert line endings; around the 18.3.2 timeframe, log content may even contain mixed line-endings.
+    #
+    # You must supply administrator authentication credentials to use this API.
+    # This API is only available for administrator accounts in the top-level Organization, not in any other Organization.
+    #
+    # @return [String]
+    def admin_meta_read_all_logs
+      perform_request('api/v1/admin/meta/read-all-logs')
+    end
+
     # AdminMetaReadLogs
     #
     # Get log file content.
@@ -3483,7 +3651,7 @@ module Comet
 
       ret_error = Comet::CometAPIResponseMessage.new
       ret_error.from_hash(obj)
-      raise Comet::APIResponseError.new(ret_error), 'Comet API response status was not OK'
+      raise Comet::APIResponseError.new(ret_error)
     end
 
     # Perform a synchronous HTTP request.
@@ -3520,7 +3688,7 @@ module Comet
 
       form_params = []
       params.each do |k, v|
-        form_params.append [k, v, { :filename => k }]
+        form_params.append [k, v, {:filename => k}]
       end
       req.set_form(form_params, 'multipart/form-data')
 

data/lib/comet/definitions.rb

@@ -155,6 +155,24 @@ module Comet
 
   MONGODB_DEFAULT_PORT = 27_017
 
+  SERVICE_CALENDAR = 1
+
+  SERVICE_CONTACT = 2
+
+  SERVICE_MAIL = 4
+
+  SERVICE_SHAREPOINT = 8
+
+  SERVICE_ONEDRIVE = 16
+
+  MIXED_VIRTUAL_ACCOUNT_TYPE_USER = 1
+
+  MIXED_VIRTUAL_ACCOUNT_TYPE_GROUP = 2
+
+  MIXED_VIRTUAL_ACCOUNT_TYPE_TEAM_GROUP = 3
+
+  MIXED_VIRTUAL_ACCOUNT_TYPE_SHAREPOINT_ONLY = 4
+
   # RestoreType:
   RESTORETYPE_INVALID = -1
 
@@ -412,11 +430,11 @@ module Comet
 
   DEFAULT_TIMEZONE = 'UTC'
 
-  APPLICATION_VERSION = '21.9.1'
+  APPLICATION_VERSION = '21.12.1'
 
   APPLICATION_VERSION_MAJOR = 21
 
-  APPLICATION_VERSION_MINOR = 9
+  APPLICATION_VERSION_MINOR = 12
 
   APPLICATION_VERSION_REVISION = 1
 
@@ -591,6 +609,9 @@ module Comet
   # MacOSCodesignLevel:
   MACOSCODESIGN_LEVEL_SIGN_NOTARISE_STAPLE = 2
 
+  # StreamableEventType:
+  SEVT__MIN = 4000
+
   # StreamableEventType: Event is emitted when the webhook is registered, or when the server starts up. The Data associated is ServerMetaVersionInfo
   SEVT_META_HELLO = 4000
 
@@ -612,6 +633,9 @@ module Comet
   # StreamableEventType: Data is the string bucket ref
   SEVT_BUCKET_NEW = 4300
 
+  # StreamableEventType:
+  SEVT__MAX = 4999
+
   OFFICE365_REGION_PUBLIC = 'GlobalPublicCloud'
 
   OFFICE365_REGION_CHINA = 'ChinaCloud'

data/lib/comet/models/admin_security_options.rb

@@ -29,9 +29,15 @@ module Comet
     # @type [Boolean] allow_password_and_u2flogin
     attr_accessor :allow_password_and_u2flogin
 
+    # @type [Boolean] allow_password_and_web_authn_login
+    attr_accessor :allow_password_and_web_authn_login
+
     # @type [Array<Comet::AdminU2FRegistration>] u2fregistrations
     attr_accessor :u2fregistrations
 
+    # @type [Array<Comet::AdminWebAuthnRegistration>] web_authn_registrations
+    attr_accessor :web_authn_registrations
+
     # @type [Number] totpkey_encryption_format
     attr_accessor :totpkey_encryption_format
 
@@ -52,6 +58,7 @@ module Comet
       @password_format = 0
       @password = ''
       @u2fregistrations = []
+      @web_authn_registrations = []
       @totpkey_encryption_format = 0
       @totpkey = ''
       @ipwhitelist = ''
@@ -85,6 +92,8 @@ module Comet
           @allow_password_and_totplogin = v
         when 'AllowPasswordAndU2FLogin'
           @allow_password_and_u2flogin = v
+        when 'AllowPasswordAndWebAuthnLogin'
+          @allow_password_and_web_authn_login = v
         when 'U2FRegistrations'
           if v.nil?
             @u2fregistrations = []
@@ -95,6 +104,16 @@ module Comet
               @u2fregistrations[i1].from_hash(v1)
             end
           end
+        when 'WebAuthnRegistrations'
+          if v.nil?
+            @web_authn_registrations = []
+          else
+            @web_authn_registrations = Array.new(v.length)
+            v.each_with_index do |v1, i1|
+              @web_authn_registrations[i1] = Comet::AdminWebAuthnRegistration.new
+              @web_authn_registrations[i1].from_hash(v1)
+            end
+          end
         when 'TOTPKeyEncryptionFormat'
           raise TypeError, "'v' expected Numeric, got #{v.class}" unless v.is_a? Numeric
 
@@ -121,9 +140,13 @@ module Comet
       ret['AllowPasswordLogin'] = @allow_password_login
       ret['AllowPasswordAndTOTPLogin'] = @allow_password_and_totplogin
       ret['AllowPasswordAndU2FLogin'] = @allow_password_and_u2flogin
+      ret['AllowPasswordAndWebAuthnLogin'] = @allow_password_and_web_authn_login
       unless @u2fregistrations.nil?
         ret['U2FRegistrations'] = @u2fregistrations
       end
+      unless @web_authn_registrations.nil?
+        ret['WebAuthnRegistrations'] = @web_authn_registrations
+      end
       unless @totpkey_encryption_format.nil?
         ret['TOTPKeyEncryptionFormat'] = @totpkey_encryption_format
       end

data/lib/comet/models/admin_web_authn_registration.rb

@@ -0,0 +1,112 @@
+#!/usr/bin/env ruby --enable-frozen-string-literal
+#
+# Copyright (c) 2020-2021 Comet Licensing Ltd.
+# Please see the LICENSE file for usage information.
+#
+# SPDX-License-Identifier: MIT
+#
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+
+module Comet
+
+  # AdminWebAuthnRegistration is a typed class wrapper around the underlying Comet Server API data structure.
+  class AdminWebAuthnRegistration
+
+    # @type [String] description
+    attr_accessor :description
+
+    # @type [Number] register_time
+    attr_accessor :register_time
+
+    # @type [Boolean] is_legacy_u2f
+    attr_accessor :is_legacy_u2f
+
+    # @type [Array<Object>] id
+    attr_accessor :id
+
+    # @type [Comet::WebAuthnCredential] credential
+    attr_accessor :credential
+
+    # @type [Hash] Hidden storage to preserve future properties for non-destructive roundtrip operations
+    attr_accessor :unknown_json_fields
+
+    def initialize
+      clear
+    end
+
+    def clear
+      @description = ''
+      @register_time = 0
+      @id = []
+      @credential = Comet::WebAuthnCredential.new
+      @unknown_json_fields = {}
+    end
+
+    # @param [String] json_string The complete object in JSON format
+    def from_json(json_string)
+      raise TypeError, "'json_string' expected String, got #{json_string.class}" unless json_string.is_a? String
+
+      from_hash(JSON.parse(json_string))
+    end
+
+    # @param [Hash] obj The complete object as a Ruby hash
+    def from_hash(obj)
+      raise TypeError, "'obj' expected Hash, got #{obj.class}" unless obj.is_a? Hash
+
+      obj.each do |k, v|
+        case k
+        when 'Description'
+          raise TypeError, "'v' expected String, got #{v.class}" unless v.is_a? String
+
+          @description = v
+        when 'RegisterTime'
+          raise TypeError, "'v' expected Numeric, got #{v.class}" unless v.is_a? Numeric
+
+          @register_time = v
+        when 'IsLegacyU2F'
+          @is_legacy_u2f = v
+        when 'ID'
+          @id = Base64.decode64(v)
+        when 'Credential'
+          @credential = Comet::WebAuthnCredential.new
+          @credential.from_hash(v)
+        else
+          @unknown_json_fields[k] = v
+        end
+      end
+    end
+
+    # @return [Hash] The complete object as a Ruby hash
+    def to_hash
+      ret = {}
+      ret['Description'] = @description
+      ret['RegisterTime'] = @register_time
+      unless @is_legacy_u2f.nil?
+        ret['IsLegacyU2F'] = @is_legacy_u2f
+      end
+      unless @id.nil?
+        ret['ID'] = @id
+      end
+      unless @credential.nil?
+        ret['Credential'] = @credential
+      end
+      @unknown_json_fields.each do |k, v|
+        ret[k] = v
+      end
+      ret
+    end
+
+    # @return [Hash] The complete object as a Ruby hash
+    def to_h
+      to_hash
+    end
+
+    # @return [String] The complete object as a JSON string
+    def to_json(options = {})
+      to_hash.to_json(options)
+    end
+  end
+end