// 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.identity.authentication;

/// The maximum length of the (UTF-8 encoded) password used in the temporary
/// methods to support an initial prototype of password-based encryption.
@deprecated
const MAX_PASSWORD_SIZE uint32 = 128;

/// AccountManager manages the overall state of system accounts and personae on
/// a Fuchsia device. The AccountManager is the most powerful protocol in the
/// account system and is intended only for use by the most trusted parts of the
/// system.
@discoverable
closed protocol AccountManager {
    /// Returns a vector of all accounts provisioned on the device.
    strict GetAccountIds() -> (struct {
        account_ids vector<AccountId>:MAX_ACCOUNTS_PER_DEVICE;
    });

    /// Returns the metadata for a single account.
    ///
    /// `id` The account's identifier as returned by GetAccountIds()
    strict GetAccountMetadata(struct {
        id AccountId;
    }) -> (struct {
        metadata AccountMetadata;
    }) 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` [required] The account's identifier as returned by GetAccountIds()
    /// `interaction` An `Interaction` channel enabling the user to complete
    ///               authentication challenges if these are necessary.
    /// `account` [required] The server end of an `Account` channel
    ///
    /// Fails with:
    /// - `INVALID_REQUEST` if the `id` does not exist.
    /// - `FAILED_PRECONDITION` if the account is locked but no `interaction`
    ///   channel was supplied to perform authentication.
    /// - `ABORTED` if the client closes the `interaction` channel.
    strict GetAccount(resource table {
        1: id AccountId;
        2: interaction server_end:fuchsia.identity.authentication.Interaction;
        // 3 is reserved for auto_lock in a near-future CL.
        4: account server_end:Account;
    }) -> () error Error;

    /// Connects a channel to read properties of and perform operations on
    /// one account. If the account is locked, the supplied password will be
    /// used to attempt authentication.
    ///
    /// This is a temporary method used for an initial prototype of
    /// password-based encryption. Its usage will be replaced by the
    /// `GetAccount` method where the hardcoded authentication=password
    /// assumption is replaced by a channel that can support different
    /// authentication mechanisms.
    ///
    /// `id` The account's identifier as returned by GetAccountIds()
    /// `password` The account's password
    /// `account` The server end of an `Account` channel
    ///
    /// Fails with `FAILED_AUTHENTICATION` if the password was not correct.
    @deprecated
    strict DeprecatedGetAccount(resource struct {
        id AccountId;
        password string:MAX_PASSWORD_SIZE;
        account server_end:Account;
    }) -> () error Error;

    /// 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` [required] The client end of an `AccountListener` channel
    /// `initial_state` If true, the listener will receive an event containing
    ///                 the initial state for all accounts.
    /// `add_account` If true, the listener will receive events when a new
    ///               account is added to the device.
    /// `remove_account` If true, the listener will receive events when an
    ///                  account is removed from the device.
    /// `granularity` An `AuthChangeGranularity` expressing the magnitude of
    ///               change in authentication state that will lead to
    ///               AuthStateChange events. If absent, AuthStateChange events
    ///               will not be sent.
    strict RegisterAccountListener(resource table {
        1: listener client_end:AccountListener;
        2: initial_state bool;
        3: add_account bool;
        4: remove_account bool;
        5: granularity AuthChangeGranularity;
    }) -> () error Error;

    /// Removes an account from the device.
    ///
    /// `id` The account's identifier as returned by GetAccountIds()
    strict RemoveAccount(struct {
        id AccountId;
    }) -> () error Error;

    /// Adds a new account to the device. If this operation if successful the
    /// newly created account will be unlocked and may be accessed using
    /// `GetAccount` without further authentication.
    ///
    /// `lifetime` [required] The lifetime of the account
    /// `metadata` [required] Metadata for the new account
    /// `interaction` An `Interaction` channel enabling the user to select and
    ///               enroll authentication mechanisms for the new account.
    ///
    /// Returns: `account_id` The identifier of the newly added account
    ///
    /// Fails with:
    /// - `INVALID_REQUEST` if policy requires authentication factors for the
    ///    new account but no `interaction` channel was supplied.
    /// - `ABORTED` if the client closes the `interaction` channel.
    strict ProvisionNewAccount(resource table {
        1: lifetime Lifetime;
        2: metadata AccountMetadata;
        3: interaction server_end:fuchsia.identity.authentication.Interaction;
    }) -> (struct {
        account_id AccountId;
    }) error Error;

    /// Adds a new system account to the device using the supplied password
    /// as the only authentication mechanism. The account is automatically
    /// unlocked and the supplied channel is connected to read properties of
    /// and perform operations on the account.
    ///
    /// This is a temporary method used for an initial prototype of
    /// password-based encryption. Its usage will be replaced by the
    /// `ProvisionNewAccount` method where the hardcoded
    /// authentication=password assumption is replaced by a channel
    /// that can support different authentication mechanisms.
    ///
    /// `password` The password to be used for the new account
    /// `metadata` Metadata for the new account
    /// `account` The server end of an `Account` channel
    ///
    /// Fails with `INVALID_REQUEST` if the password does not meet
    /// minimum strength requirements.
    @deprecated
    strict DeprecatedProvisionNewAccount(resource struct {
        password string:MAX_PASSWORD_SIZE;
        metadata AccountMetadata;
        account server_end:Account;
    }) -> () error Error;
};

/// An `AuthState` along with the system account that it applies to.
type AccountAuthState = struct {
    /// A unique identifier for the account.
    account_id AccountId;
    /// An authentication state for the account.
    auth_state AuthState;
};

/// 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.
closed 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.
    strict OnInitialize(struct {
        account_states vector<AccountAuthState>:MAX_ACCOUNTS_PER_DEVICE;
    }) -> ();

    /// 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.
    strict OnAccountAdded(struct {
        account_state AccountAuthState;
    }) -> ();

    /// 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.
    strict OnAccountRemoved(struct {
        account_id AccountId;
    }) -> ();

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