chromeos/services/device_sync/public/mojom/device_sync.mojom

// Copyright 2017 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module chromeos.device_sync.mojom;

import "mojo/public/mojom/base/time.mojom";

// Enumeration of software features which can be enabled/disabled for a given
// device. Each feature has a host and client portion; here, "host" refers to
// the associated phone which provides the feature (at most one host per
// account), and "client" refers to the Chromebook which consumes the feature
// (multiple clients allowed per account).
enum SoftwareFeature {
  // The Better Together (MultiDevice) setup flow feature allows users to go
  // through a unified setup flow which enrolls the device for all multi-device
  // features.
  BETTER_TOGETHER_HOST = 1,
  BETTER_TOGETHER_CLIENT = 2,

  // EasyUnlock gives users the ability to unlock their Chromebooks with their
  // phone instead of by typing a password.
  EASY_UNLOCK_HOST = 3,
  EASY_UNLOCK_CLIENT = 4,

  // Magic Tether (Instant Tethering) gives users the ability to use their
  // phone's Internet connectivity on their Chromebooks via an automated flow
  // which does not require any phone-side interaction.
  MAGIC_TETHER_HOST = 5,
  MAGIC_TETHER_CLIENT = 6,

  // SMS Connect gives users the ability to read and reply to their text
  // messages from their Chromebooks.
  SMS_CONNECT_HOST = 7,
  SMS_CONNECT_CLIENT = 8
};

// Enumeration of what value a SoftwareFeature can be.
enum SoftwareFeatureState {
  kNotSupported,
  kSupported,
  kEnabled
};

enum NetworkRequestResult {
  // Successful network request.
  kSuccess,

  // The network request itself was successful, but it did not produce the
  // expected result (e.g., called SetSoftwareFeatureState(), but the call did
  // not result in the feature state changing).
  kRequestSucceededButUnexpectedResult,

  // Service was not yet initialized; could not complete request.
  kServiceNotYetInitialized,

  // Request could not be completed because the device is offline or has issues
  // sending the HTTP request.
  kOffline,

  // Server endpoint could not be found.
  kEndpointNotFound,

  // Authentication error contacting back-end.
  kAuthenticationError,

  // Request was invalid.
  kBadRequest,

  // The server responded, but the response was not formatted correctly.
  kResponseMalformed,

  // Internal server error.
  kInternalServerError,

  // Unknown result.
  kUnknown
};

// Used to generate rotating BLE advertisement data, which is necessary to
// establish a BLE communication channel between two devices. To
// create the BLE channel, both devices must possess the other's BeaconSeeds.
struct BeaconSeed {
  string data;
  mojo_base.mojom.Time start_time;
  mojo_base.mojom.Time end_time;
};

// Metadata describing a remote device with which the current device can
// communicate.
struct RemoteDevice {
  // Unique identifier of the device. Unlike |public_key|, this field is
  // guaranteed to be human-readable (i.e., it does not contain non-ASCII
  // characters).
  string device_id;

  // Identifier for the user to whom this device is registered.
  string user_id;

  // Human-readable device name; by default, this is the name of the device
  // model, but this value is editable.
  string device_name;

  // Encryption key used for communication with this device.
  string persistent_symmetric_key;

  // The time at which this device's metadata was last updated on the CryptAuth
  // back-end.
  mojo_base.mojom.Time last_update_time;

  // The features which this device either does not support, supports, or has
  // enabled.
  map<SoftwareFeature, SoftwareFeatureState> software_features;

  // Seeds belonging to the device. Each seed has start and end timestamps which
  // indicate how long the seed is valid, and each device has enough associated
  // seeds to keep the device connectable for over 30 days. If no new device
  // metadata synced for over 30 days, it is possible that a connection will not
  // be able to be established over BLE.
  array<BeaconSeed> beacon_seeds;
};

struct FindEligibleDevicesResponse {
  array<RemoteDevice> eligible_devices;
  array<RemoteDevice> ineligible_devices;
};

struct DebugInfo {
  // Enrollment stats:
  mojo_base.mojom.Time last_enrollment_time;
  mojo_base.mojom.TimeDelta time_to_next_enrollment_attempt;
  bool is_recovering_from_enrollment_failure;
  bool is_enrollment_in_progress;

  // Sync stats:
  mojo_base.mojom.Time last_sync_time;
  mojo_base.mojom.TimeDelta time_to_next_sync_attempt;
  bool is_recovering_from_sync_failure;
  bool is_sync_in_progress;
};

interface DeviceSyncObserver {
  // Invoked when the current device has successfully completed enrollment. Note
  // that enrollment occurs once when the device first starts up, then the
  // device re-enrolls periodically (and on-command when ForceEnrollmentNow() is
  // called).
  OnEnrollmentFinished();

  // Invoked when new devices have been synced from the server. Note that this
  // function is not invoked if a device sync failed or if a device sync
  // succeeded but did not result in a change of devices.
  OnNewDevicesSynced();
};

// TODO(khorimoto): Flesh out API.
interface DeviceSync {
  // Adds an Observer of this API.
  AddObserver(DeviceSyncObserver observer) => ();

  // Triggers an enrollment; result is relayed via the OnEnrollmentFinished()
  // observer function. Returns whether the call could be completed
  // successfully. If the function returns false, this means that the device has
  // not yet completed registration with the back-end; clients should observe
  // this service and wait for an OnEnrollmentFinished() callback before
  // retrying.
  [Sync]
  ForceEnrollmentNow() => (bool success);

  // Triggers a device sync; result is relayed via the OnDevicesSynced()
  // observer function. Returns whether the call could be completed
  // successfully. If the function returns false, this means that the device has
  // not yet completed registration with the back-end; clients should observe
  // this service and wait for an OnEnrollmentFinished() callback before
  // retrying.
  [Sync]
  ForceSyncNow() => (bool success);

  // Returns all synced devices associated with the primary account. If this
  // device has not yet registered with the back-end, no list is provided.
  GetSyncedDevices() => (array<RemoteDevice>? devices);

  // Returns the RemoteDevice object associated with this device. If this device
  // has not yet registered with the back-end, no device is provided.
  GetLocalDeviceMetadata() => (RemoteDevice? local_device);

  // Enables or disables the given software feature for the device with the
  // given public key. If |enabled| and |is_exclusive| are both true, this
  // function will enable the feature for the given device and disable the
  // feature for any other device which currently has that feature enabled.
  // |is_exclusive| is ignored if |enabled| is false.
  //
  // On success, this function returns a null error_code to the callback; on
  // error, it returns a valid error_code string indicating the reason for
  // failure.
  //
  // Note: In the special case of passing |software_feature| =
  // SoftwareFeature::EASY_UNLOCK_HOST and |enabled| = false, |public_key| is
  // ignored, because that combination of arguments disables EASY_UNLOCK_HOST on
  // all of the user's devices.
  SetSoftwareFeatureState(
      string device_public_key,
      SoftwareFeature software_feature,
      bool enabled,
      bool is_exclusive) => (NetworkRequestResult result_code);

  // Finds devices which are eligible for the given feature. When this function
  // is invoked, a network request will be sent to each eligible device which
  // instructs that device to enable BLE advertising; thus, this function can be
  // used to bootstrap connections to these devices.
  //
  // On success, this function returns a null error_code with a valid response
  // to the callback; on error, it returns a valid error_code string indicating
  // the reason for failure along with a null response.
  FindEligibleDevices(SoftwareFeature software_feature) =>
      (NetworkRequestResult result_code, FindEligibleDevicesResponse? response);

  // Functions below are implemented for chrome://proximity-auth page, which is
  // intended for debugging purposes only.
  // TODO(khorimoto): Determine whether a new, debug-only interface should be
  //                  refactored out of DeviceSync.
  GetDebugInfo() => (DebugInfo? debug_info);
};