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

using fuchsia.ui.views;

// This file defines an auth provider service that can be used by Garnet's
// Token Manager service to mint oauth tokens for clients such as Framework,
// Ledger, gmail or chat module.

/// Specifies the success/failure status from auth provider.
enum AuthProviderStatus {
    OK = 0;
    BAD_REQUEST = 1;
    BAD_RESPONSE = 2;
    OAUTH_SERVER_ERROR = 3;
    USER_CANCELLED = 4;
    REAUTH_REQUIRED = 5;
    NETWORK_ERROR = 6;
    UNSUPPORTED_PROVIDER = 7;
    INTERNAL_ERROR = 8;
    UNKNOWN_ERROR = 9;
};

/// The type of token returned.
enum TokenType {
    ACCESS_TOKEN = 0;
    ID_TOKEN = 1;
};

/// OAuth token response populated after parsing JSON object that contains
/// short-lived access token or id token returned by the auth provider.
struct AuthToken {
    /// Type of token.
    TokenType token_type;

    /// Contains access token or a JWT identity token.
    string token;

    /// The remaining lifetime of the token in seconds.
    uint64 expires_in;
};

/// Stores attributes related to a firebase auth token for a given firebase api
/// key.
///
/// These tokens are minted by Firebase Auth server and are meant to be used for
/// authorizing users into Firebase services such as DB and storage.
struct FirebaseToken {
    /// Use this as the auth token in firebase database and storage requests.
    string id_token;

    /// Use this to uniquely identify users.
    string? local_id;

    /// Use this to uniquely identify user's email address provided by the
    /// Auth Provider Firebase server.
    string? email;

    /// The remaining lifetime of the token in seconds.
    uint64 expires_in;
};

/// Challenge response returned by the auth provider during remote attestation
/// based authentication.
struct AuthChallenge {
    /// The value of nonce to be used for the next token refresh request
    string challenge;

    /// The lifetime of `challenge` in seconds.
    uint64 expires_in;
};

/// Stores Elliptic Curve public key parameters of the credential key.
struct CredentialECKey {
    /// Supported elliptic curve value used in JWT attestation. Refer to Section
    /// 6.2.1.1 of RFC7518 for the canonical list of supported elliptic curves.
    /// For example:(P-256,P-384,P-521)
    string curve;

    /// Value of x of the generated EC key
    string key_x_val;

    /// Value of y of the generated EC key
    string key_y_val;

    /// Base64 encoded SHA256 hash of the EC public key
    string fingerprint_sha_256;
};

/// Contains parameters required by the auth provider component to build
/// attestation JWTs.
struct AttestationJWTParams {
    /// Contains the ephemeral Elliptic curve credential public key which will be
    /// bound to the newly generated refresh token grant.
    CredentialECKey credential_eckey;

    /// The full chain of certificates from the device attestation certificate
    /// to the root certificate that was registered on the OAuth client id.
    /// Each string should be base64-encoded DER PKIX certificate value.
    vector<string> certificate_chain;

    /// OAuth authorization code bound to the given user and device
    string auth_code;
};

/// Contains parameters required by the auth provider to build assertion JWTs.
struct AssertionJWTParams {
    /// Contains Elliptic curve credential public key which is bound to existing
    /// refresh token.
    CredentialECKey credential_eckey;

    /// An optional challenge that could be used for the next token refresh request
    string? challenge;
};

/// User attributes returned to callers on authorizing a new user at any auth
/// provider. These attributes are generated by calling the auth provider's
/// user profile apis.
struct UserProfileInfo {
    /// User identifier returned by the backend identity provider server to
    /// identify the user after successful authorization. Some identity providers
    /// send verified email address as the identifier, and some send an opaque
    /// string as the user identifier.
    string id;

    /// The name that is displayed on the base shell while logging in. Display
    /// name is fetched from user profile attributes as configured by the user at
    /// the given identity provider.
    string? display_name;

    /// User's profile url that is used by the base shell while logging in.
    /// Profile url is fetched from user profile attributes as configured by the
    /// user at the given identity provider.
    string? url;

    /// User's profile image url that is used by the base shell while logging in.
    /// Profile image url is fetched from user profile attributes as configured by
    /// the user at the given identity provider.
    string? image_url;
};

/// This interface is implemented by base shell. It is used to notify the
/// base shell that a view for login needs to be started / stopped.
protocol AuthenticationUIContext {
    /// Requests base shell to display `view_holder_token` for authentication.
    /// Another call to StartOverlay() will not be made until StopOverlay()
    /// has been called.
    StartOverlay(fuchsia.ui.views.ViewHolderToken view_holder_token);

    /// Requests base shell to stop displaying the auth view.
    StopOverlay();
};

/// OAuth identity service that provisions new users and provides authorization
/// tokens for the currently enrolled users. Some common Auth Providers are
/// Google, Facebook, Spotify and Twitter.
[Discoverable]
protocol AuthProvider {
    /// Authenticates and authorizes a user against an auth provider backend system
    /// using the OAuth protocol and returns the persistent credential such as
    /// Google's refresh token or Facebook's access token for this user. These
    /// persistent credentials are long lived and their expiration time is set by
    /// the identity provider, for example Google's refresh tokens are valid until
    /// the user changes their password or revokes access explicitly, whereas
    /// Facebook access tokens are valid for up to 60 days or until the user
    /// revokes access.
    ///
    /// During OAuth handshake, user needs to explicitly consent to the permissions
    /// as configured at the server. The consent is presented in a web_view using
    /// an `auth_ui_context` overlay provided by the base_shell.
    ///
    /// An optional `user_profile_id` is provided for simplifying reauthorization
    /// flow.
    GetPersistentCredential(AuthenticationUIContext? auth_ui_context,
                            string? user_profile_id)
        -> (AuthProviderStatus status, string? credential,
            UserProfileInfo? user_profile_info);

    /// Exchanges a persistent user `credential` for a short lived app specific
    /// OAuth access token for the specified `client_id` and `scopes`. The
    /// `credential` is a long lived OAuth token as generated by the external
    /// identity provider in the above GetPersistentCredential() call. If no
    /// client_id is specified a default will be used.
    ///
    /// Access tokens are used by applications to make API requests against
    /// services offered by the Auth Provider.
    ///
    /// Returns an `auth_token` response containing an access token, if successful.
    /// Otherwise, an error status is returned.
    GetAppAccessToken(string credential, string? client_id,
                      vector<string> scopes)
        -> (AuthProviderStatus status, AuthToken? auth_token);

    /// Exchanges a persistent user `credential` for an OAuth Identity token for
    /// the specified `audience`. The audience is the intended recipient of the
    /// id_token. The `credential` is a long lived OAuth token as generated by the
    /// external identity provider in the above GetPersistentCredential() call.
    ///
    /// OAuth Id tokens are JSON Web Tokens (JWT) that contains digitally signed
    /// identity information about the user for the intended recipient.
    ///
    /// Returns an `auth_token` response containing an id token, if successful.
    /// Otherwise, an error status is returned.
    GetAppIdToken(string credential, string? audience)
        -> (AuthProviderStatus status, AuthToken? auth_token);

    /// Gets a firebase auth token for the user identified by `id_token` and the
    /// requested |firebase_api key|. The `id_token` is a JWT Identity token
    /// returned from GetAppIdToken() call above.
    ///
    /// Returns a `firebase_token` from the server if successful. Otherwise, an
    /// error status is returned.
    GetAppFirebaseToken(string id_token, string firebase_api_key)
        -> (AuthProviderStatus status, FirebaseToken? firebase_token);

    /// Revokes user's grants at the Auth Provider by revoking a credential. The
    /// `credential` is either a long lived OAuth token as returned by the
    /// GetPersistentCredential() call or an app specific access token as returned
    /// by the GetAppAccessToken() call.
    RevokeAppOrPersistentCredential(string credential)
        -> (AuthProviderStatus status);

    /// Authenticates and authorizes a user against a remote attestation based
    /// auth provider backend system that mints bound persistent credentials.
    ///
    /// This method is capable of performing user authorization directly on the
    /// device or use the OAuth authorization code generated out-of-band on a
    /// secondary device that is sent over a secure channel to the target device.
    /// In the latter case, auth_code generated out-of-band is passed as an
    /// argument in the attestation `jwt_params`. Where as in the former case,
    /// user needs to explicitly consent to the permissions on the target device
    /// and the auth_code is returned to the device directly. The consent is
    /// presented in a web_view using an `auth_ui_context` overlay provided by the
    /// base_shell. An optional `user_profile_id` is provided for simplifying
    /// reauthorization flow.
    ///
    /// The authorization code is exchanged to a bound refresh token using an
    /// attestation JWT constructed from `jwt_params` and is signed by the
    /// `attestation_signer` component passed in the request.
    ///
    /// If the operation is successful, a long-lived `credential` that is bound to
    /// the originating device is returned along with an optional `auth_token`
    /// containing short-lived access token and an optional `nonce` that is used on
    /// next token exchange request. An optional `user_profile_info` containing
    /// user profile attributes is also returned if successful. Otherwise, an error
    /// status is returned.
    GetPersistentCredentialFromAttestationJWT(
        AttestationSigner attestation_signer, AttestationJWTParams jwt_params,
        AuthenticationUIContext? auth_ui_context,
        string? user_profile_id)
        -> (AuthProviderStatus status, string? credential, AuthToken? auth_token,
            AuthChallenge? auth_challenge, UserProfileInfo? user_profile_info);

    /// Exchanges a bound persistent user `credential` for a short lived app
    /// specific OAuth access token using the specified assertion JWT. The
    /// assertion JWT is constructed from `jwt_params` and is signed by the
    /// `attestation_signer` component passed in the request.
    ///
    /// Access tokens are used by applications to make API requests against
    /// services offered by the Auth Provider.
    ///
    /// Returns an `auth_token` response containing an access token and an optional
    /// `updated_credential` and `auth_challenge` to be used on next token refresh
    /// request, if successful. Otherwise, an error status is returned.
    GetAppAccessTokenFromAssertionJWT(AttestationSigner attestation_signer,
                                      AssertionJWTParams jwt_params, string credential,
                                      vector<string> scopes)
        -> (AuthProviderStatus status, string? updated_credential,
            AuthToken? auth_token, AuthChallenge? auth_challenge);

    // TODO(ukode): Add methods for bound IDToken and FirebaseToken.
};