// Copyright 2020 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module blink.mojom;

import "mojo/public/mojom/base/time.mojom";
import "mojo/public/mojom/base/values.mojom";
import "third_party/blink/public/mojom/credentialmanagement/credential_manager.mojom";
import "url/mojom/origin.mojom";
import "url/mojom/url.mojom";

// Implementation of the FedCM API.
// See also: https://fedidcg.github.io/FedCM/

// Represents the fetch result from a federated token request. It is
// used to determine whether a JavaScript exception should be thrown, and what
// the error message of such exception should say. This enum is a subset of
// FederatedRequestResult in
// third_party/blink/public/mojom/devtools/inspector_issue.mojom.
enum RequestTokenStatus {
  kSuccess,
  kErrorTooManyRequests,
  kErrorCanceled,
  kError,
};

// Represents the fetch result from a federated user info request. It is
// used to determine whether a JavaScript exception should be thrown.
enum RequestUserInfoStatus {
  kSuccess,
  kError,
};

// Represents the fetch result from a IdentityProvider.disconnect() request.
// It is used to determine whether a JavaScript exception should be
// thrown, and what the error message of such exception should say.
enum DisconnectStatus {
  kSuccess,
  kErrorTooManyRequests,
  kError,
};

enum IdpSigninStatus {
  kSignedIn,
  kSignedOut,
};

// Don't change the meaning or the order of these values because they are
// being recorded in metrics and in sync with the counterpart in enums.xml.
// LINT.IfChange(RpContext)

enum RpContext {
  kSignIn = 0,
  kSignUp = 1,
  kUse = 2,
  kContinue = 3,
};

// LINT.ThenChange(//tools/metrics/histograms/metadata/blink/enums.xml:FedCmRpContext)

// Don't change the meaning or the order of these values because they are
// being recorded in metrics and in sync with the counterpart in enums.xml.
// LINT.IfChange(RpMode)

enum RpMode {
  kActive = 0,
  kPassive = 1,
};

// LINT.ThenChange(//tools/metrics/histograms/metadata/blink/enums.xml:FedCmRpMode)

// The result of a call to IdentityProvider.register().
enum RegisterIdpStatus {
  kSuccess,
  kErrorFeatureDisabled,
  kErrorCrossOriginConfig,
  kErrorNoTransientActivation,
  kErrorDeclined,
  kErrorInvalidConfig,
};

// The details of a federated identity provider.
struct IdentityProviderConfig {
  // Explicitly references a specific provider by a Config URL.
  url.mojom.Url config_url;

  // Whether this config comes from the IDP registration API.
  bool from_idp_registration_api;

  // When using registered IDPs, this contains the type of IDP requested.
  string? type;

  // Can be an empty string to be omitted in the request sent to the provider.
  string client_id;
};

// The format of the token that the relying party is requesting.
// The browser currently only supports SD-JWTs and opaque tokens,
// typically a OIDC JWT or SAML response.
// We expect to add support for different token formats that may have
// different privacy properties (such as BBS) as well as different
// ergonomic properties (e.g. ISO MDocs).
enum Format {
  kSdJwt,
};

// The parameters for a GET redirect.
struct RedirectGetParams {
  url.mojom.Url url;
};

// The parameters for a POST redirect.
struct RedirectPostParams {
  url.mojom.Url url;
  string request_body;
};

// Whether to load the redirect URL with a GET or POST HTTP method.
union RedirectParams {
  RedirectGetParams get;
  RedirectPostParams post;
};

// The parameters for a ResolveTokenRequest call.
union ResolveTokenParams {
  mojo_base.mojom.Value token;
  RedirectParams redirect_to;
};

// The request parameters for a navigator.credentials.get() FedCM call.
struct IdentityProviderRequestOptions {
  IdentityProviderConfig config;

  // Can be an empty string to be omitted in the request sent to the provider.
  string nonce;

  // The login hint for this identity provider. Used by the relying party to
  // specify which user account they would like to show in the FedCM dialog.
  // This field is not sent to the provider, but rather used by the user agent.
  string login_hint;

  // The domain hint for this identity provider. Used by the relying party to
  // specify the domain hint they require an account to belong to. The field
  // is not sent to the provider, but rather used by the user agent.
  string domain_hint;

  // Profile fields that the RP is requesting access for, such as "name",
  // "email" or "picture".
  array<string>? fields;

  // Additional parameters that the relying party can send to the IdP after
  // the user's permission has been gathered.
  // null if not provided by the JS caller.
  string? params_json;

  // Optionally, the format of the token that the RP is requesting.
  // When undefined, the token is expected to have an opaque format for
  // the browser (typically an OAuth access token, id token or a SAML
  // response).
  Format? format;
};

// The information passed in an IdentityProvider.disconnect() call.
struct IdentityCredentialDisconnectOptions {
  IdentityProviderConfig config;

  // The account hint for which the disconnect ought to happen.
  string account_hint;
};

// The list of user information that can be returned to an identity provider
// during a UserInfo API call.
struct IdentityUserInfo {
  string email;
  string given_name;
  string name;
  string picture;
};

// Cached user information from a Login Status API call.
struct LoginStatusAccount {
  string id;
  string email;
  string name;
  string? given_name;
  url.mojom.Url? picture;
};

// List of accounts and the expiration date thereof for a Login Status API call.
struct LoginStatusOptions {
  array<LoginStatusAccount> accounts;
  mojo_base.mojom.TimeDelta? expiration;
};

// The parameters for a get call for identity provider(s).
struct IdentityProviderGetParameters {
  // Details of identity provider(s).
  array<IdentityProviderRequestOptions> providers;

  // Controls the wording of the FedCM prompt.
  RpContext context;

  // Controls the UX of the FedCM prompt: modality, behavior when the
  // user is signed-out, etc.
  RpMode mode;
};

// Represents the error when a federated token request fails.
struct TokenError {
  // Type of error which resulted in an IdentityCredential not being created.
  string? code;

  // URL where the user can learn more information about the error.
  url.mojom.Url? url;
};

// The information returned upon a successful token request.
struct TokenRequestSuccess {
  url.mojom.Url selected_idp_config_url;
  mojo_base.mojom.Value? token;
  bool is_auto_selected;
};

// The information returned upon a failed token request.
struct TokenRequestFailure {
  RequestTokenStatus status;
  TokenError? error;
};

// Represents an active federated sign-in request session. Lifetime is bound to
// the lifecycle of a single token request session.
interface FederatedRequest {
  // Aborts the ongoing federated identity request.
  Abort();
};

// Represents the result of a federated user info request.
union RequestUserInfoResult {
  // TODO(https://crbug.com/519217823): Change this to a more specific error
  // enum once the legacy FederatedAuthRequest::RequestUserInfo is removed and
  // RequestUserInfoStatus is deleted.
  RequestUserInfoStatus status;
  array<IdentityUserInfo> user_info;
};

// Manages federated identity request sessions. Implemented by the browser
// process via content::webid::RequestService, and invoked from the renderer
// process.
interface FederatedRequestService {
  // Requests a token to be retrieved, given an array of
  // IdentityProviderGetParameters.
  StartTokenRequest(array<IdentityProviderGetParameters> idp_get_params,
                    CredentialMediationRequirement requirement,
                    pending_receiver<FederatedRequest> request_receiver)
      => result<TokenRequestSuccess, TokenRequestFailure>;

  // Registers the url as an IdP's configURL of the user's preference.
  RegisterIdP(url.mojom.Url url) => (RegisterIdpStatus status);

  // Unregisters the url as an IdP's configURL of the user's preference.
  UnregisterIdP(url.mojom.Url url) => (bool success);

  // Closes the modal dialog view.
  CloseModalDialogView();

  // Require user mediation with navigator.credentials.preventSilentAccess() as
  // defined in
  // https://w3c.github.io/webappsec-credential-management/#user-mediation
  PreventSilentAccess() => ();

  // Requests user info.
  RequestUserInfo(IdentityProviderConfig provider)
      => (RequestUserInfoResult result);

  // Disconnects an account for the given IdP.
  Disconnect(IdentityCredentialDisconnectOptions options)
      => (DisconnectStatus status);

  // Resolve the token request from a JS call from a WebView dialog,
  // when the id_assertion_endpoint returns a continue_on rather than the
  // actual token.
  // If `params` specifies a redirect, that URL is loaded in the context that
  // triggered the FedCM call using the HTTP method and request body (if any)
  // specified in the redirect parameters.
  // If no account ID is provided, the account ID of the account that was
  // selected in the account chooser will be used.
  ResolveTokenRequest(string? account_id, ResolveTokenParams params)
      => (bool success);

  // Marks the user as logged in/out to the IDP on this origin.
  SetIdpSigninStatus(url.mojom.Origin origin,
                     IdpSigninStatus status,
                     LoginStatusOptions? options) => ();
};