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

library fuchsia.identity.account;

using fuchsia.auth;

/// AccountManager manages the overall state of Fuchsia accounts and personae on
/// a Fuchsia device, installation of the AuthProviders that are used to obtain
/// authentication tokens for these accounts, and access to TokenManagers for
/// these accounts.
///
/// The AccountManager is the most powerful protocol in the authentication
/// system and is intended only for use by the most trusted parts of the system.
[Discoverable]
protocol AccountManager {
    /// Returns a vector of all accounts provisioned on the current device.
    GetAccountIds()
        -> (vector<LocalAccountId>:MAX_ACCOUNTS_PER_DEVICE account_ids);

    /// Returns a vector of all accounts provisioned on the current
    /// device and the current authentication state for each.
    ///
    /// `scenario` The scenario to produce authentication states for.
    ///
    /// Returns: `account_auth_states` The current authentication state for each
    ///                                account given the provided scenario.
    GetAccountAuthStates(Scenario scenario)
        -> (vector<AccountAuthState>:MAX_ACCOUNTS_PER_DEVICE
            account_auth_states) error Error;

    /// Connects a channel to read properties of and perform operations on
    /// one account. If the account is locked, an interactive authentication
    /// attempt will be invoked as part of this call.
    ///
    /// `id` The account's identifier as returned by GetAccountIds()
    /// `context_provider` An `AuthenticationContextProvider` capable of
    ///                    supplying UI contexts used for interactive
    ///                    authentication on this account
    /// `account` The server end of an `Account` channel
    GetAccount(
        LocalAccountId id,
        fuchsia.auth.AuthenticationContextProvider context_provider,
        request<Account> account)
        -> () error Error;

    // TODO(dnordstrom): Add option to retrieve an account non-interactively.

    /// Connects a channel that will receive changes in the provisioned
    /// accounts and their authentication state. Optionally this channel will
    /// also receive the initial set of accounts and authentication states onto
    /// which changes may be applied.
    ///
    /// `listener` The client end of an `AccountListener` channel
    /// `options` An `AccountListenerOptions` that defines the set of events to
    ///           be sent to the listener.
    RegisterAccountListener(
        AccountListener listener,
        AccountListenerOptions options)
        -> () error Error;

    // TODO(fxbug.dev/561): Define methods to managed locked accounts, i.e. those
    // where data decryption keys are not currently available.

    /// Removes a provisioned Fuchsia account from the current device, revoking
    /// any credentials that are held for the account.
    ///
    /// `id` The account's identifier as returned by GetAccountIds()
    /// `force` If true, continues removing the account even if revocation of
    ///         credentials fails. If false, any revocation failure will result
    ///         in an error and the account will remain. In this case, a subset
    ///         of the credentials may have been deleted.
    RemoveAccount(LocalAccountId id, bool force) -> () error Error;

    /// Adds a Fuchsia account to the current device based on authenticating
    /// to a service provider (such as Google). If the service provider account
    /// is not already a recovery account for any Fuchsia account, a new Fuchsia
    /// account will be created with its recovery account set to the service
    /// provider account. If a storage unlock-capable authentication mechanism
    /// is provided, a single enrollment will be created of that mecahnism.
    ///
    /// `auth_context_provider` An `AuthenticationContextProvider` capable of
    ///                         supplying UI contexts used for interactive
    ///                         authentication
    /// `auth_provider_type` A unique identifier for an installed `AuthProvider`
    ///                      that should be used to authenticate with the
    ///                      service provider
    /// `lifetime` The lifetime of the account
    /// `auth_mechanism_id` An `AuthMechanismId` for a storage
    ///                     unlock-capable authentication mechanism. If
    ///                     provided, a single enrollment of that
    ///                     mechanism will be created for storage
    ///                     unlock.
    ///
    /// Returns: `account_id` The identifier of the newly added account
    ProvisionFromAuthProvider(
        fuchsia.auth.AuthenticationContextProvider auth_context_provider,
        string:MAX_AUTH_PROVIDER_TYPE_SIZE auth_provider_type,
        Lifetime lifetime,
        AuthMechanismId? auth_mechanism_id)
        -> (LocalAccountId account_id) error Error;

    /// Adds a new, initially empty, Fuchsia account to the current device. If a
    /// storage unlock-capable authentication mechanism is provided, a single
    /// enrollment will be created of that mecahnism.
    ///
    /// `lifetime` The lifetime of the account
    /// `auth_mechanism_id` An `AuthMechanismId` for a storage
    ///                     unlock-capable authentication mechanism. If
    ///                     provided, a single enrollment of that
    ///                     mechanism will be created for storage
    ///                     unlock.
    ///
    /// Returns: `account_id` The identifier of the newly added account
    ProvisionNewAccount(
        Lifetime lifetime,
        AuthMechanismId? auth_mechanism_id)
        -> (LocalAccountId account_id) error Error;

    /// Returns all available authentication mechanisms.
    GetAuthenticationMechanisms()
        -> (vector<AuthMechanismProperties>:MAX_AUTH_MECHANISMS auth_mechanisms) error Error;
};

/// An `AuthState` along with the account that it applies to.
[MaxHandles = "0"]
struct AccountAuthState {
    /// A unique identifier for the Fuchsia account on the current device.
    LocalAccountId account_id;
    /// An authentication state for the Fuchsia account.
    AuthState auth_state;
};

/// The initial state of an account, reported through an `AccountListener`.
[MaxHandles = "0"]
struct InitialAccountState {
    /// A unique identifier for the Fuchsia account on the current device.
    LocalAccountId account_id;
    /// An authentication state for the Fuchsia account. It is only populated if
    /// `AccountListenerOptions.scenario` was specified when the listener was
    /// created.
    AuthState? auth_state;
};

/// The configuration for an AccountListener, defining the set of events that it
/// will receive.
[MaxHandles = "0"]
struct AccountListenerOptions {
    /// If true, the listener will receive an event containing the initial state
    /// for all accounts. The initial auth states will be populated in this
    /// event iff the scenario option is set.
    bool initial_state;
    /// If true, the listener will receive events when a new account is added
    /// to the device.
    bool add_account;
    /// If true, the listener will receive events when an account is removed
    /// from the device.
    bool remove_account;
    /// The scenario to use for all AuthState data sent to the listener. If
    /// scenario is not supplied no AuthState data will be populated.
    Scenario? scenario;
    /// An `AuthChangeGranularity` expressing the magnitude of change in
    /// authentication state that will lead to AuthStateChange events.
    /// If granularity is not populated AuthStateChange events will not be
    /// sent. May only be populated if a scenario is provided.
    AuthChangeGranularity? granularity;
};

/// A protocol to receive events when the set of accounts on a device or the
/// authentication states of these accounts change.
///
/// AccountListeners may be registered through the AccountManager protocol
/// and this registration also defines which types of event should be sent to
/// the listener. Optionally, the AccountListener will receive an initial state
/// event onto which the change events may be safely accumulated.
///
/// All methods include an empty response to follow the "Throttle push using
/// acknowledgements" FIDL design pattern.
protocol AccountListener {
    /// A method that is called to communicate the initial set of accounts and
    /// their authentication states. OnInitialize is called exactly once if and
    /// only if AccountListenerOptions.initial_state was set when creating the
    /// AccountListener. When called, it will always be the first call on the
    /// channel. If no accounts are present on the device the vector will be
    /// empty.
    ///
    /// `account_states` The set of initial states.
    OnInitialize(
        vector<InitialAccountState>:MAX_ACCOUNTS_PER_DEVICE account_states)
        -> ();

    /// A method that is called when a new account is added to the device.
    /// This method is only called if AccountListenerOptions.add_account was
    /// set when creating the AccountListener.
    ///
    /// `account_state` The initial state for the newly added account.
    OnAccountAdded(InitialAccountState account_state) -> ();

    /// A method that is called when a provisioned account is removed.
    /// This method is only called if AccountListenerOptions.remove_account was
    /// set when creating the AccountListener.
    OnAccountRemoved(LocalAccountId account_id) -> ();

    /// A method that is called when the authentication state of any provisioned
    /// account changes.
    OnAuthStateChanged(AccountAuthState account_auth_state) -> ();
};