chromeos/crosapi/mojom/account_manager.mojom

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

// The Mojo interfaces and enums contained in this file use a file-global
// versioning scheme, as opposed to individual interface / enum level
// versioning. Bump this value before making a change to any of the following
// interfaces / enums.
//
// Next MinVersion: 13

module crosapi.mojom;

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

// Types of accounts which can be stored in Account Manager.
// This must be kept in sync with
// //components/account_manager_core/chromeos/tokens.proto.
//
// The enums values should match the aforementioned proto too.
[Stable, Extensible]
enum AccountType {
  [Default] kUnspecified = 0,
  kGaia = 1,
  kActiveDirectory = 2,
};

// Uniquely identifies an account in Account Manager.
//
// Next id: 2
[Stable]
struct AccountKey {
  // `id` is obfuscated Gaia id for Gaia accounts.
  // `id` is the object GUID for Microsoft Active Directory accounts.
  string id@0;

  // Type of the account - such as Gaia, or Microsoft Active Directory.
  AccountType account_type@1;
};

// Information about an account in Account Manager.
//
// Next id: 2
[Stable]
struct Account {
  // A unique identifier for this account.
  AccountKey key@0;

  // The raw, un-canonicalized email id (The.Rock@gmail.com, as opposed to
  // therock@gmail.com) for this account.
  string raw_email@1;
};

// See google_apis/gaia/google_service_auth_error.h
//
// IMPORTANT: Do NOT send these values from Lacros to Ash without thinking about
// version skew. Specifically, newer Lacros versions may send values which are
// unknown to Ash. See the implementation of
// `account_manager::FromMojoGoogleServiceAuthError`.
// Note while fixing this - this enum needs to be trivially compatible with
// google_apis/gaia/google_service_auth_error.h - which does not have an
// "unknown" value.
//
// Next id: 4
[Stable]
struct GoogleServiceAuthError {
  // Next value: 15
  [Stable, Extensible]
  enum State {
    kNone = 0,
    kInvalidGaiaCredentials = 1,
    kUserNotSignedUp = 2,
    kConnectionFailed = 3,
    // DEPRECATED kCaptchaRequired = 4,
    // DEPRECATED kAccountDeleted = 5,
    // DEPRECATED kAccountDisabled = 6,
    kServiceUnavailable = 7,
    // DEPRECATED kTwoFactor = 8,
    kRequestCanceled = 9,
    // DEPRECATED kHostedNotAllowedDeprecated = 10,
    kUnexpectedServiceResponse = 11,
    kServiceError = 12,
    // DEPRECATED kWebLoginRequired = 13,
    [MinVersion=10] kScopeLimitedUnrecoverableError = 14,
  };

  // Next value: 4
  [Stable, Extensible]
  enum InvalidGaiaCredentialsReason {
    [Default] kUnknown = 0,
    kCredentialsRejectedByServer = 1,
    kCredentialsRejectedByClient = 2,
    kCredentialsMissing = 3,
  };

  State state@0;
  // Network error is set only if `state` is set to `kConnectionFailed`.
  // In case of no network error, `network_error` is set to 0.
  int64 network_error@1;
  string error_message@2;
  InvalidGaiaCredentialsReason invalid_gaia_credentials_reason@3;
};

// See components/account_manager_core/account_addition_options.h
//
// Next id: 2
[Stable]
struct AccountAdditionOptions {
  bool is_available_in_arc@0;
  bool show_arc_availability_picker@1;
};

// Next id: 3
[Stable]
struct AccountAdditionResult {
  // The result of account addition request, sent from Ash to Lacros.
  // Note: The default value of this enum is `kUnexpectedResponse = 4`, not
  // `kSuccess = 0`. This was changed in MinVersion 11.
  //
  // Next value: 6
  [Stable, Extensible]
  enum Status {
    kSuccess = 0,
    kAlreadyInProgress = 1,
    kCancelledByUser = 2,
    kNetworkError = 3,
    [Default] kUnexpectedResponse = 4,
    [MinVersion = 9] kBlockedByPolicy = 5,
  };

  Status status@0;
  // The account that was added.
  Account? account@1;
  // The error is set only if `status` is set to `kNetworkError`.
  GoogleServiceAuthError? error@2;
};

// Next id: 3
[Stable]
struct AccessTokenInfo {
  // OAuth2 access token.
  string access_token@0;

  // Expiration time of `access_token`. This value has a built-in safety margin
  // so it can be used as-is.
  mojo_base.mojom.Time expiration_time@1;

  // Contains extra information regarding the user's currently registered
  // services.
  string id_token@2;
};

[Stable]
union AccessTokenResult {
  AccessTokenInfo access_token_info;
  GoogleServiceAuthError error;
};

// Interface for observers of Chrome OS Account Manager.
// This interface is implemented by lacros-chrome, and is used by ash-chrome to
// send account update notifications.
//
// Next id: 4
[Stable, Uuid="f75c4963-497b-411f-97ab-c53c7f6b46ed"]
interface AccountManagerObserver {
  // Called when the token for `account` is updated/inserted.
  // Note: Observers which register with `AccountManager` before its
  // initialization is complete will get notified when `AccountManager` is fully
  // initialized.
  // Note: Observers which register with `AccountManager` after its
  // initialization is complete will not get an immediate
  // notification-on-registration.
  OnTokenUpserted@0(Account account);

  // Called when an account has been removed from Account Manager.
  // Note: Observers that may have cached access tokens for `account` must clear
  // their cache entry for this `account` on receiving this callback.
  OnAccountRemoved@1(Account account);

  // Called when an `account`'s `error` status changes. See `ReportAuthError` in
  // `AccountManager` interface for details.
  // Note: Observers that may have cached access tokens for `account` must clear
  // their cache entries for this `account` on receiving this callback. They may
  // short-circuit future access token requests with an immediate `error` for a
  // given `account` as appropriate (e.g. if the error is a non-transient
  // error).
  // Note: Observers must reset their cached error states (if any) for
  // `account` - if the `state` of `error` is `kNone`.
  [MinVersion = 1]
  OnAuthErrorChanged@2(AccountKey account, GoogleServiceAuthError error);

  // Called when Ash's signin dialog is closed, regardless of the reason, e.g.:
  // - For account additions as well as re-authentication.
  // - For successful completion of the flow, as well as cancellation by the
  //   user. etc.
  [MinVersion = 12]
  OnSigninDialogClosed@3();
};

// Interface for Chrome OS Account Manager.
// Chrome OS Account Manager is the source of truth for accounts on Chrome OS -
// including ARC, and Chrome content area. It supports Google accounts and
// Microsoft Active Directory accounts, as of this writing.
// This interface is implemented by ash-chrome, and is used by lacros-chrome to
// query accounts residing in the Chrome OS Account Manager.
// ARC++ uses components/arc/mojom/auth.mojom to talk to the Chrome OS Account
// Manager.
//
// Next id: 9
[Stable, Uuid="85b9a674-9d8e-497f-98d5-22c8dca6f2b8"]
interface AccountManager {
  // Returns `true` if Chrome OS Account Manager has been fully initialized, and
  // `false` otherwise.
  IsInitialized@0() => (bool is_initialized);

  // Creates and returns a new receiver for `AccountManagerObserver`.
  // This API is supposed to be called by lacros-chrome, fairly early during its
  // initialization, to receive updates related to accounts stored in Account
  // Manager.
  // The connection, and the corresponding remote, is destroyed when `receiver`
  // is destroyed. This will happen automatically when lacros is shut down.
  [MinVersion = 1]
  AddObserver@1() => (pending_receiver<AccountManagerObserver> receiver);

  // Returns the list of accounts in AccountManager. Can be invoked before the
  // initialization is completed (in this case the callback will be invoked
  // after the initialization is done).
  [MinVersion = 2]
  GetAccounts@2() => (array<Account> accounts);

  // Launches account addition dialog and returns `result` with the added
  // account.
  [MinVersion = 3]
  ShowAddAccountDialog@3(
    [MinVersion=8] AccountAdditionOptions? add_account_options) =>
    (AccountAdditionResult result);

  // Launches account reauthentication dialog for provided `email`.
  [MinVersion = 3]
  ShowReauthAccountDialog@4(string email) => ();

  // Launches OS Settings > Accounts.
  [MinVersion = 4]
  ShowManageAccountsSettings@5();

  // Returns a persistent error state for `account`. If `account` doesn't have
  // a persistent error or AccountManager doesn't have such an account -
  // `GoogleServiceAuthError` with `kNone` state will be returned.
  [MinVersion = 5]
  GetPersistentErrorForAccount@6(AccountKey account) =>
      (GoogleServiceAuthError error);

  // Returns a remote to an interface to fetch an access token for
  // `account_key`, to be used by `oauth_consumer_name` OAuth2 client.
  // `account_key` must be a Gaia account. If `account_key` is invalid or not
  // known to Chrome OS Account Manager, fetching an access token via
  // `AccessTokenFetcher` will result in an error (`kUserNotSignedUp`). If the
  // account's refresh token is no longer valid, it will result in
  // `kInvalidGaiaCredentials` error. See `GoogleServiceAuthError` for all error
  // types.
  [MinVersion = 6]
  CreateAccessTokenFetcher@7(AccountKey account_key,
      string oauth_consumer_name) =>
          (pending_remote<AccessTokenFetcher> access_token_fetcher);

  // Reports an `error` for `account`.
  // The implementation uses a pubsub model to propagate errors for accounts.
  // Any application can report (Publish) account errors. These errors will be
  // fanned out to `AccountManagerObserver`s (Subscribers).
  // A typical use-case is sharing of account error information between Ash and
  // Lacros. Since these errors are OAuth errors, they can be discovered by any
  // application (or the OS) - and must be communicated to other applications
  // (or the OS).
  // `account` must be a valid account known to Account Manager.
  // Setting the error `state` as `kNone` resets the error state for `account`.
  // Note: Transient errors (`GoogleServiceAuthError::IsTransientError()`)
  // reported through this API will be silently ignored.
  [MinVersion = 9]
  ReportAuthError@8(AccountKey account, GoogleServiceAuthError error);
};

// Interface for fetching OAuth2 access tokens.
//
// Next id: 1
[Stable, Uuid="71476f25-fb77-414f-848e-3e5368a9ee35"]
interface AccessTokenFetcher {
  // Starts the request for fetching an access token with the provided `scopes`.
  // If `scopes` is empty, `access_token` will have the same scope as the
  // underlying refresh token - login scope.
  // Don't call this method multiple times - create a new `AccessTokenFetcher`
  // instead.
  Start@0(array<string> scopes) => (AccessTokenResult result);
};