// Copyright 2015 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.

[DartPackage="mojo_services", JavaPackage="org.chromium.mojo.authentication"]
module authentication;

// Interface to handle user identity and authentication tokens.
// TODO(qsr): This API only handles google accounts at this time. It will need
//            to be extended to allow generic account manager on the platform.
[ServiceName="authentication::AuthenticationService"]
interface AuthenticationService {
  // Requests a Google account to use. In case of success, error will be null.
  // In case of error, username will be null and error will contain a
  // description of the error. If |return_last_selected| is true and the client
  // application already selected an account, the same account will be returned
  // without user intervention.
  SelectAccount(bool return_last_selected) => (string? username, string? error);

  // Requests an oauth2 token for the given Google account with the given
  // scopes.  In case of error, token will be null and error will contain a
  // description of the error.
  GetOAuth2Token(string username, array<string> scopes) =>
      (string? token, string? error);

  // Requests to clear a previously acquired token. This should be called when a
  // token is refused by a server component before requesting a new token to
  // clear the token from any cache.
  ClearOAuth2Token(string token);

  // Requests an oauth2 device code response for the given set of scopes. In
  // case of error, all response parameters other than error, namely
  // verifcation_url, device_code and user_code will be null and error will
  // contain a description of the error. To provision FNL like systems with
  // Google account credentials, invoke GetOAuth2DeviceCode() method followed by
  // AddAccount() instead of using SelectAccount(), which only works for
  // Android.
  GetOAuth2DeviceCode(array<string> scopes) => (string? verification_url,
                                                string? device_code,
                                                string? user_code,
                                                string? error);

  // Exchanges an oauth2 device code to a refresh token for the granted user,
  // and stores it locally in a secure storage location on FNL. For future
  // GetOAuth2Token requests, a new access token is minted from this refresh
  // token and returned to the calling mojo app.
  AddAccount(string device_code) => (string? username, string? error);
};