// Copyright 2017 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.modular.auth;

// Authentication errors returned by AccountProvider. It contains error status
// code along with a detailed error message.
struct AuthErr {
    Status status;
    string message;
};

// Specifies the success/failure status.
enum Status {
    // Success
    OK = 0;
    // A problem with client configuration such as invalid_client, missing params
    // etc. This should happen only in development not at run-time, unless
    // user/developer changes any of this config. No retry is required.
    BAD_REQUEST = 1;
    // Unable to parse the server side response. Retry is optional, this error
    // should be extremely rare.
    BAD_RESPONSE = 2;
    // Server is reachable and propagated an error returned by OAuth Server
    // backends.  That kind of error cannot be fixed on retries, and has some
    // root cause that needs to be addressed either in the client's configuration
    // or because the user explicitly revoked access to the client app.  For
    // instance: invalid_token, expired_token, invalid_client_id, invalid_user,
    // invalid_args, etc.
    OAUTH_SERVER_ERROR = 3;
    // User cancelled the flow, no need to retry.
    USER_CANCELLED = 4;
    // Network error, eg. unreachable. This may be temporary, a retry is
    // recommended.
    NETWORK_ERROR = 5;
    // Internal error. Retry is optional, this error should be rare.
    INTERNAL_ERROR = 6;
};

// An interface that allows the Framework to talk to the token manager service
// to add new accounts and be able to mint the corresponding |TokenManager|
// specialized instances for thid party agents and first party ledger client.
//
// This is only meant to be used by the Framework and will be replaced with
// |AccountManager| in the near future.
[Discoverable]
protocol AccountProvider {
    // Adds a new user account. This involves talking to the identity provider and
    // fetching profile attributes.
    AddAccount(IdentityProvider identity_provider)
        -> (Account? account, string? error_code);

    // Removes an existing user account. This involves talking to account's
    // identity provider and revoking user credentials both locally and remotely.
    // This operation also deletes cached tokens for the given account.
    //
    // TODO(ukode): Modify this api to take account_id and IDP as input once the
    // Account struct is cleaned up.
    //
    // If |revoke_all| is set to true, then all device credentials are revoked
    // both locally and remotely on the backend server and user is logged out from
    // all devices. If |revoke_all| is set to false, then credentials stored
    // locally are wiped. This includes cached tokens such as access/id and
    // firebase tokens and the locally persisted refresh token. By default,
    // |revoke_all| is set to false and deletes account only from that given
    // device.
    RemoveAccount(Account account, bool revoke_all) -> (AuthErr status);

    // This signals |AccountProvider| to teardown itself. After the
    // AccountProvider responds by closing its handle, the caller may terminate
    // the |AccountProvider| application if it hasn't already exited.
    Terminate();
};