fxa_client.udl

// # Firefox Accounts Client
//
// The fxa-client component lets applications integrate with the
// [Firefox Accounts](https://mozilla.github.io/ecosystem-platform/docs/features/firefox-accounts/fxa-overview)
// identity service. The shape of a typical integration would look
// something like:
//
// * Out-of-band, register your application with the Firefox Accounts service,
//   providing an OAuth `redirect_uri` controlled by your application and
//   obtaining an OAuth `client_id`.
//
// * On application startup, create a [`FirefoxAccount`] object to represent the
//   signed-in state of the application.
//     * On first startup, a new [`FirefoxAccount`] can be created by calling
//       [`FirefoxAccount::new`] and passing the application's `client_id`.
//     * For subsequent startups the object can be persisted using the
//       [`to_json`](FirefoxAccount::to_json) method and re-created by
//       calling [`FirefoxAccount::from_json`].
//
// * When the user wants to sign in to your application, direct them through
//   a web-based OAuth flow using [`begin_oauth_flow`](FirefoxAccount::begin_oauth_flow)
//   or [`begin_pairing_flow`](FirefoxAccount::begin_pairing_flow); when they return
//   to your registered `redirect_uri`, pass the resulting authorization state back to
//   [`complete_oauth_flow`](FirefoxAccount::complete_oauth_flow) to sign them in.
//
// * Display information about the signed-in user by using the data from
//   [`get_profile`](FirefoxAccount::get_profile).
//
// * Access account-related services on behalf of the user by obtaining OAuth
//   access tokens via [`get_access_token`](FirefoxAccount::get_access_token).
//
// * If the user opts to sign out of the application, calling [`disconnect`](FirefoxAccount::disconnect)
//   and then discarding any persisted account data.

namespace fxa_client {
    
};



// Generic error type thrown by many [`FirefoxAccount`] operations.
//
// Precise details of the error are hidden from consumers, mostly due to limitations of
// how we expose this API to other languages. The type of the error indicates how the
// calling code should respond.
//
[Error]
enum FxaError {

  // Thrown when there was a problem with the authentication status of the account,
  // such as an expired token. The application should [check its authorization status](
  // FirefoxAccount::check_authorization_status) to see whether it has been disconnected,
  // or retry the operation with a freshly-generated token.
  "Authentication",

  // Thrown if an operation fails due to network access problems.
  // The application may retry at a later time once connectivity is restored.
  "Network",

  // Thrown if the application attempts to complete an OAuth flow when no OAuth flow
  // has been initiated. This may indicate a user who navigated directly to the OAuth
  // `redirect_uri` for the application.
  //
  // **Note:** This error is currently only thrown in the Swift language bindings.
  "NoExistingAuthFlow",

  // Thrown if the application attempts to complete an OAuth flow, but the state
  // tokens returned from the Firefox Account server do not match with the ones
  // expected by the client.
  // This may indicate a stale OAuth flow, or potentially an attempted hijacking
  // of the flow by an attacker. The signin attempt cannot be completed.
  //
  // **Note:** This error is currently only thrown in the Swift language bindings.
  "WrongAuthFlow",

  // Thrown if there is a panic in the underlying Rust code.
  //
  // **Note:** This error is currently only thrown in the Kotlin language bindings.
  "Panic",

  // A catch-all for other unspecified errors.
  "Other",
};



// Object representing the signed-in state of an application.
//
// The `FirefoxAccount` object is the main interface provided by this crate.
// It represents the signed-in state of an application that may be connected to
// user's Firefox Account, and provides methods for inspecting the state of the
// account and accessing other services on behalf of the user.
//
interface FirefoxAccount {

  // Create a new [`FirefoxAccount`] instance, not connected to any account.
  //
  // **💾 This method alters the persisted account state.**
  //
  // This method constructs as new [`FirefoxAccount`] instance configured to connect
  // the application to a user's account.
  //
  // # Arguments
  //
  //   - `content_url` - the URL of the Firefox Accounts server to use
  //       - For example, use `https://accounts.firefox.com` for the main
  //         Mozilla-hosted service.
  //   - `client_id` - the registered OAuth client id of the application.
  //   - `redirect_uri` - the registered OAuth redirect URI of the application.
  //   - `token_server_url_override`: optionally, URL for the user's Sync Tokenserver.
  //        - This can be used to support users who self-host their sync data.
  //          If `None` then it will default to the Mozilla-hosted Sync server.
  //
  
  constructor([ByRef] string content_url, [ByRef] string client_id, [ByRef] string redirect_uri, [ByRef] string? token_server_url_override );
  

  // Restore a [`FirefoxAccount`] instance from serialized state.
  //
  // Given a JSON string previously obtained from [`FirefoxAccount::to_json`], this
  // method will deserialize it and return a live [`FirefoxAccount`] instance.
  //
  // **⚠️ Warning:** since the serialized state contains access tokens, you should
  // not call `from_json` multiple times on the same data. This would result
  // in multiple live objects sharing the same access tokens and is likely to
  // produce unexpected behaviour.
  //
  [Throws=FxaError,Name=from_json]
  constructor([ByRef] string data );
  

  // Save current state to a JSON string.
  //
  // This method serializes the current account state into a JSON string, which
  // the application can use to persist the user's signed-in state across restarts.
  // The application should call this method and update its persisted state after
  // any potentially-state-changing operation.
  //
  // **⚠️ Warning:** the serialized state may contain encryption keys and access
  // tokens that let anyone holding them access the user's data in Firefox Sync
  // and/or other FxA services. Applications should take care to store the resulting
  // data in a secure fashion, as appropriate for their target platform.
  //
  [Throws=FxaError]
  string to_json();
  

  // Initiate a web-based OAuth sign-in flow.
  //
  // This method initializes some internal state and then returns a URL at which the
  // user may perform a web-based authorization flow to connect the application to
  // their account. The application should direct the user to the provided URL.
  //
  // When the resulting OAuth flow redirects back to the configured `redirect_uri`,
  // the query parameters should be extracting from the URL and passed to the
  // [`complete_oauth_flow`](FirefoxAccount::complete_oauth_flow) method to finalize
  // the signin.
  //
  // # Arguments
  //
  //   - `scopes` - list of OAuth scopes to request.
  //       - The requested scopes will determine what account-related data
  //         the application is able to access.
  //   - `entrypoint` - metrics identifier for UX entrypoint.
  //       - This parameter is used for metrics purposes, to identify the
  //         UX entrypoint from which the user triggered the signin request.
  //         For example, the application toolbar, on the onboarding flow.
  //   - `metrics` - optionally, additional metrics tracking paramters.
  //       - These will be included as query parameters in the resulting URL.
  //
  [Throws=FxaError]
  string begin_oauth_flow([ByRef] sequence<string> scopes, [ByRef] string entrypoint,  MetricsParams? metrics );
  

  // Get the URL at which to begin a device-pairing signin flow.
  //
  // If the user wants to sign in using device pairing, call this method and then
  // direct them to visit the resulting URL on an already-signed-in device. Doing
  // so will trigger the other device to show a QR code to be scanned, and the result
  // from said QR code can be passed to [`begin_pairing_flow`](FirefoxAccount::begin_pairing_flow).
  //
  [Throws=FxaError]
  string get_pairing_authority_url();
  

  // Initiate a device-pairing sign-in flow.
  //
  // Once the user has scanned a pairing QR code, pass the scanned value to this
  // method. It will return a URL to which the application should redirect the user
  // in order to continue the sign-in flow.
  //
  // When the resulting flow redirects back to the configured `redirect_uri`,
  // the resulting OAuth parameters should be extracting from the URL and passed
  // to [`complete_oauth_flow`](FirefoxAccount::complete_oauth_flow) to finalize
  // the signin.
  //
  // # Arguments
  //
  //   - `pairing_url` - the URL scanned from a QR code on another device.
  //   - `scopes` - list of OAuth scopes to request.
  //       - The requested scopes will determine what account-related data
  //         the application is able to access.
  //   - `entrypoint` - metrics identifier for UX entrypoint.
  //       - This parameter is used for metrics purposes, to identify the
  //         UX entrypoint from which the user triggered the signin request.
  //         For example, the application toolbar, on the onboarding flow.
  //   - `metrics` - optionally, additional metrics tracking paramters.
  //       - These will be included as query parameters in the resulting URL.
  //
  [Throws=FxaError]
  string begin_pairing_flow([ByRef] string pairing_url, [ByRef] sequence<string> scopes, [ByRef] string entrypoint,  MetricsParams? metrics );
  

  // Complete an OAuth flow.
  //
  // **💾 This method alters the persisted account state.**
  //
  // At the conclusion of an OAuth flow, the user will be redirect to the
  // application's registered `redirect_uri`. It should extract the `code`
  // and `state` parameters from the resulting URL and pass them to this
  // method in order to complete the sign-in.
  //
  // # Arguments
  //
  //   - `code` - the OAuth authorization code obtained from the redirect URI.
  //   - `state` - the OAuth state parameter obtained from the redirect URI.
  //
  [Throws=FxaError]
  void complete_oauth_flow([ByRef] string code, [ByRef] string state );
  

  // Check authorization status for this application.
  //
  // **💾 This method alters the persisted account state.**
  //
  // Applications may call this method to check with the FxA server about the status
  // of their authentication tokens. It returns an [`AuthorizationInfo`] struct
  // with details about whether the tokens are still active.
  //
  [Throws=FxaError]
  AuthorizationInfo check_authorization_status();
  

  // Disconnect from the user's account.
  //
  // **💾 This method alters the persisted account state.**
  //
  // This method destroys any tokens held by the client, effectively disconnecting
  // from the user's account. Applications should call this when the user opts to
  // sign out.
  //
  // The persisted account state after calling this method will contain only the
  // user's last-seen profile information, if any. This may be useful in helping
  // the user to reconnnect to their account. If reconnecting to the same account
  // is not desired then the application should discard the persisted account state.
  //
  void disconnect();
  

  // Get profile information for the signed-in user, if any.
  //
  // **💾 This method alters the persisted account state.**
  //
  // This method fetches a [`Profile`] struct with information about the currently-signed-in
  // user, either by using locally-cached profile information or by fetching fresh data from
  // the server.
  //
  // # Arguments
  //
  //    - `ignore_cache` - if true, always hit the server for fresh profile information.
  //
  // # Notes
  //
  //    - Profile information is only available to applications that have been
  //      granted the `profile` scope.
  //    - There is currently no API for fetching cached profile information without
  //      potentially hitting the server.
  //    - If there is no signed-in user, this method will throw an
  //      [`Authentication`](FxaError::Authentication) error.
  //
  [Throws=FxaError]
  Profile get_profile( boolean ignore_cache );
  

  // Create a new device record for this application.
  //
  // **💾 This method alters the persisted account state.**
  //
  // This method registed a device record for the application, providing basic metadata for
  // the device along with a list of supported [Device Capabilities](DeviceCapability) for
  // participating in the "device commands" ecosystem.
  //
  // Applications should call this method soon after a successful sign-in, to ensure
  // they they appear correctly in the user's account-management pages and when discovered
  // by other devices connected to the account.
  //
  // # Arguments
  //
  //    - `name` - human-readable display name to use for this application
  //    - `device_type` - the [type](DeviceType) of device the application is installed on
  //    - `supported_capabilities` - the set of [capabilities](DeviceCapability) to register
  //       for this device in the "device commands" ecosystem.
  //
  // # Notes
  //
  //    - Device registration is only available to applications that have been
  //      granted the `https://identity.mozilla.com/apps/oldsync` scope.
  //
  [Throws=FxaError]
  void initialize_device([ByRef] string name,  DeviceType device_type,  sequence<DeviceCapability> supported_capabilities );
  

  // Get the device id registered for this application.
  //
  // # Notes
  //
  //    - If the application has not registered a device record, this method will
  //      throw an [`Other`](FxaError::Other) error.
  //        - (Yeah...sorry. This should be changed to do something better.)
  //    - Device metadata is only visible to applications that have been
  //      granted the `https://identity.mozilla.com/apps/oldsync` scope.
  //
  [Throws=FxaError]
  string get_current_device_id();
  

  // Get the list of devices registered on the user's account.
  //
  // **💾 This method alters the persisted account state.**
  //
  // This method returns a list of [`Device`] structs representing all the devices
  // currently attached to the user's account (including the current device).
  // The application might use this information to e.g. display a list of appropriate
  // send-tab targets.
  //
  // # Arguments
  //
  //    - `ignore_cache` - if true, always hit the server for fresh profile information.
  //
  // # Notes
  //
  //    - Device metadata is only visible to applications that have been
  //      granted the `https://identity.mozilla.com/apps/oldsync` scope.
  //
  [Throws=FxaError]
  sequence<Device> get_devices( boolean ignore_cache );
  

  // Get the list of all client applications attached to the user's account.
  //
  // This method returns a list of [`AttachedClient`] structs representing all the applications
  // connected to the user's acount. This includes applications that are registered as a device
  // as well as server-side services that the user has connected.
  //
  // This information is really only useful for targetted messaging or marketing purposes,
  // e.g. if the application wants to advertize a related product, but first wants to check
  // whether the user is already using that product.
  //
  // # Notes
  //
  //    - Attached client metadata is only visible to applications that have been
  //      granted the `https://identity.mozilla.com/apps/oldsync` scope.
  //
  [Throws=FxaError]
  sequence<AttachedClient> get_attached_clients();
  

  // Update the display name used for this application instance.
  //
  // **💾 This method alters the persisted account state.**
  //
  // This method modifies the name of the current application's device record, as seen by
  // other applications and in the user's account management pages.
  //
  // # Arguments
  //
  //    - `display_name` - the new name for the current device.
  //
  // # Notes
  //
  //    - Device registration is only available to applications that have been
  //      granted the `https://identity.mozilla.com/apps/oldsync` scope.
  //
  [Throws=FxaError]
  void set_device_name([ByRef] string display_name );
  

  // Clear any custom display name used for this application instance.
  //
  // **💾 This method alters the persisted account state.**
  //
  // This method clears the name of the current application's device record, causing other
  // applications or the user's account management pages to have to fill in some sort of
  // default name when displaying this device.
  //
  // # Notes
  //
  //    - Device registration is only available to applications that have been
  //      granted the `https://identity.mozilla.com/apps/oldsync` scope.
  //
  [Throws=FxaError]
  void clear_device_name();
  

  // Ensure that the device record has a specific set of capabilities.
  //
  // **💾 This method alters the persisted account state.**
  //
  // This method checks that the currently-registred device record is advertising the
  // given set of capabilities in the FxA "device commands" ecosystem. If not, then it
  // updates the device record to do so.
  //
  // Applications should call this method on each startup as a way to ensure that their
  // expected set of capabilities is being accurately reflected on the FxA server, and
  // to handle the rollout of new capabilities over time.
  //
  // # Arguments
  //
  //    - `supported_capabilities` - the set of [capabilities](DeviceCapability) to register
  //       for this device in the "device commands" ecosystem.
  //
  // # Notes
  //
  //    - Device registration is only available to applications that have been
  //      granted the `https://identity.mozilla.com/apps/oldsync` scope.
  //
  [Throws=FxaError]
  void ensure_capabilities( sequence<DeviceCapability> supported_capabilities );
  

  // Set or update a push subscription endpoint for this device.
  //
  // **💾 This method alters the persisted account state.**
  //
  // This method registers the given webpush subscription with the FxA server, requesting
  // that is send notifications in the event of any significant changes to the user's
  // account. When the application receives a push message at the registered subscription
  // endpoint, it should decrypt the payload and pass it to the [`handle_push_message`](
  // FirefoxAccount::handle_push_message) method for processing.
  //
  // # Arguments
  //
  //    - `subscription` - the [`DevicePushSubscription`] details to register with the server.
  //
  // # Notes
  //
  //    - Device registration is only available to applications that have been
  //      granted the `https://identity.mozilla.com/apps/oldsync` scope.
  //
  [Throws=FxaError]
  void set_push_subscription( DevicePushSubscription subscription );
  

  // Process and respond to server-delivered account update messages.
  //
  // **💾 This method alters the persisted account state.**
  //
  // Applications should call this method whenever they receive a push notiication on subscription
  // endpoint previously registered with the Firefox Accounts server. Such messages typically indicate
  // a noteworthy change of state on the user's account, such as an update to their profile information
  // or the disconnection of a client. The [`FirefoxAccount`] struct will update its internl state
  // accordingly and return a list of [`AccountEvent`] structs describing the events, which the application
  // may use for further processing.
  //
  [Throws=FxaError]
  sequence<AccountEvent> handle_push_message([ByRef] string payload );
  

  // Poll the server for any pending device commands.
  //
  // **💾 This method alters the persisted account state.**
  //
  // Applications that have registered one or more [`DeviceCapability`]s with the server can use
  // this method to check whether other devices on the account have sent them any commands.
  // It will return a list of [`IncomingDeviceCommand`] structs for the application to process.
  //
  // # Notes
  //
  //    - Device commands are typically delivered via push message and the [`CommandReceived`](
  //      AccountEvent::CommandReceived) event. Polling should only be used as a backup delivery
  //      mechanism, f the application has reason to believe that push messages may have been missed.
  //    - Device commands functionality is only available to applications that have been
  //      granted the `https://identity.mozilla.com/apps/oldsync` scope.
  //
  [Throws=FxaError]
  sequence<IncomingDeviceCommand> poll_device_commands();
  

  // Use device commands to send a single tab to another device.
  //
  // **💾 This method alters the persisted account state.**
  //
  // If a device on the account has registered the [`SendTab`](DeviceCapability::SendTab)
  // capability, this method can be used to send it a tab.
  //
  // # Notes
  //
  //    - If the given device id does not existing or is not capable of receiving tabs,
  //      this method will throw an [`Other`](FxaError::Other) error.
  //        - (Yeah...sorry. This should be changed to do something better.)
  //    - It is not currently possible to send a full [`SendTabPayload`] to another device,
  //      but that's purely an API limitation that should go away in future.
  //    - Device commands functionality is only available to applications that have been
  //      granted the `https://identity.mozilla.com/apps/oldsync` scope.
  //
  [Throws=FxaError]
  void send_single_tab([ByRef] string target_device_id, [ByRef] string title, [ByRef] string url );
  

  // Get the URL at which to access the user's sync data.
  //
  // **💾 This method alters the persisted account state.**
  //
  [Throws=FxaError]
  string get_token_server_endpoint_url();
  

  // Get a URL which shows a "successfully connceted!" message.
  //
  // **💾 This method alters the persisted account state.**
  //
  // Applications can use this method after a successful signin, to redirect the
  // user to a success message displayed in web content rather than having to
  // implement their own native success UI.
  //
  [Throws=FxaError]
  string get_connection_success_url();
  

  // Get a URL at which the user can manage their account and profile data.
  //
  // **💾 This method alters the persisted account state.**
  //
  // Applications should link the user out to this URL from an appropriate place
  // in their signed-in settings UI.
  //
  // # Arguments
  //
  //   - `entrypoint` - metrics identifier for UX entrypoint.
  //       - This parameter is used for metrics purposes, to identify the
  //         UX entrypoint from which the user followed the link.
  //
  [Throws=FxaError]
  string get_manage_account_url([ByRef] string entrypoint );
  

  // Get a URL at which the user can manage the devices connected to their account.
  //
  // **💾 This method alters the persisted account state.**
  //
  // Applications should link the user out to this URL from an appropriate place
  // in their signed-in settings UI. For example, "Manage your devices..." may be
  // a useful link to place somewhere near the device list in the send-tab UI.
  //
  // # Arguments
  //
  //   - `entrypoint` - metrics identifier for UX entrypoint.
  //       - This parameter is used for metrics purposes, to identify the
  //         UX entrypoint from which the user followed the link.
  //
  [Throws=FxaError]
  string get_manage_devices_url([ByRef] string entrypoint );
  

  // Get a short-lived OAuth access token for the user's account.
  //
  // **💾 This method alters the persisted account state.**
  //
  // Applications that need to access resources on behalf of the user must obtain an
  // `access_token` in order to do so. For example, an access token is required when
  // fetching the user's profile data, or when accessing their data stored in Firefox Sync.
  //
  // This method will obtain and return an access token bearing the requested scopes, either
  // from a local cache of previously-issued tokens, or by creating a new one from the server.
  //
  // # Arguments
  //
  //    - `scope` - the OAuth scope to be granted by the token.
  //        - This must be one of the scopes requested during the signin flow.
  //        - Only a single scope is supported; for multiple scopes request multiple tokens.
  //    - `ttl` - optionally, the time for which the token should be valid, in seconds.
  //
  // # Notes
  //
  //    - If the application receives an authorization error when trying to use the resulting
  //      token, it should call [`clear_access_token_cache`](FirefoxAccount::clear_access_token_cache)
  //      before requesting a fresh token.
  //
  [Throws=FxaError]
  AccessTokenInfo get_access_token([ByRef] string scope,  i64? ttl );
  

  // Get the session token for the user's account, if one is available.
  //
  // **💾 This method alters the persisted account state.**
  //
  // Applications that function as a web browser may need to hold on to a session token
  // on behalf of Firefox Accounts web content. This method exists so that they can retreive
  // it an pass it back to said web content when required.
  //
  // # Notes
  //
  //    - Please do not attempt to use the resulting token to directly make calls to the
  //      Firefox Accounts servers! All account management functionality should be performed
  //      in web content.
  //    - A session token is only available to applications that have requested the
  //      `https://identity.mozilla.com/tokens/session` scope.
  //
  [Throws=FxaError]
  string get_session_token();
  

  // Update the stored session token for the user's account.
  //
  // **💾 This method alters the persisted account state.**
  //
  // Applications that function as a web browser may need to hold on to a session token
  // on behalf of Firefox Accounts web content. This method exists so that said web content
  // signals that it has generated a new session token, the stored value can be updated
  // to match.
  //
  // # Arguments
  //
  //    - `session_token` - the new session token value provided from web content.
  //
  [Throws=FxaError]
  void handle_session_token_change([ByRef] string session_token );
  

  // Create a new OAuth authorization code using the stored session token.
  //
  // When a signed-in application receives an incoming device pairing request, it can
  // use this method to grant the request and generate a corresponding OAuth authorization
  // code. This code would then be passed back to the connecting device over the
  // pairing channel (a process which is not currently supported by any code in this
  // component).
  //
  // # Arguments
  //
  //    - `params` - the OAuth parameters from the incoming authorization request
  //
  [Throws=FxaError]
  string authorize_code_using_session_token( AuthorizationParameters params );
  

  // Clear the access token cache in response to an auth failure.
  //
  // **💾 This method alters the persisted account state.**
  //
  // Applications that receive an authentication error when trying to use an access token,
  // should call this method before creating a new token and retrying the failed operation.
  // It ensures that the expired token is removed and a fresh one generated.
  //
  void clear_access_token_cache();
  

  // Collect and return telemetry about send-tab attempts.
  //
  // Applications that register the [`SendTab`](DeviceCapability::SendTab) capability
  // should also arrange to submit "sync ping" telemetry. Calling this method will
  // return a JSON string of telemetry data that can be incorporated into that ping.
  //
  // Sorry, this is not particularly carefully documented because it is intended
  // as a stop-gap until we get native Glean support. If you know how to submit
  // a sync ping, you'll know what to do with the contents of the JSON string.
  //
  [Throws=FxaError]
  string gather_telemetry();
  

  // Sign in by using legacy session-token state.
  //
  // **💾 This method alters the persisted account state.**
  //
  // When migrating to use the FxA client component, create a [`FirefoxAccount`] instance
  // and then pass any legacy sign-in state to this method. It will attempt to use the
  // session token to bootstrap a full internal state of OAuth tokens, and will store the
  // provided credentials internally in case it needs to retry after e.g. a network failure.
  //
  // # Arguments
  //
  //    - `session_token` - the session token from legacy sign-in state
  //    - `k_sync` - the Firefox Sync encryption key from legacy sign-in state
  //    - `k_xcs` - the Firefox Sync "X-Client-State: value from legacy sign-in state
  //    - `copy_session_token` - if true, copy the given session token rather than using it directly
  //
  // # Notes
  //
  //    - If successful, this method will return an [`FxAMigrationResult`] with some statistics
  //      about the migration process.
  //    - If unsuccessful this method will throw an error, but you may be able to retry the
  //      migration again at a later time.
  //    - Use [is_in_migration_state](FirefoxAccount::is_in_migration_state) to check whether the
  //      persisted account state includes a a pending migration that can be retried.
  //
  [Throws=FxaError]
  FxAMigrationResult migrate_from_session_token([ByRef] string session_token, [ByRef] string k_sync, [ByRef] string k_xcs,  boolean copy_session_token );
  

  // Retry a previously failed migration from legacy session-token state.
  //
  // **💾 This method alters the persisted account state.**
  //
  // If an earlier call to [`migrate_from_session_token`](FirefoxAccount::migrate_from_session_token)
  // failed, it may have stored the provided state for retrying at a later time. Call this method
  // in order to execute such a retry.
  //
  [Throws=FxaError]
  FxAMigrationResult retry_migrate_from_session_token();
  

  // Check for a previously failed migration from legacy session-token state.
  //
  // If an earlier call to [`migrate_from_session_token`](FirefoxAccount::migrate_from_session_token)
  // failed, it may have stored the provided state for retrying at a later time. Call this method
  // in check whether such state exists, then retry at an appropriate time.
  //
  MigrationState is_in_migration_state();
  
};

// Information about the authorization state of the application.
//
// This struct represents metadata about whether the application is currently
// connected to the user's account.
//
dictionary AuthorizationInfo {
  boolean active;
};

// Additional metrics tracking parameters to include in an OAuth request.
//
dictionary MetricsParams {
  record<DOMString, string> parameters;
};

// An OAuth access token, with its associated keys and metadata.
//
// This struct represents an FxA OAuth access token, which can be used to access a resource
// or service on behalf of the user. For example, accessing the user's data in Firefox Sync
// an access token for the scope `https://identity.mozilla.com/apps/sync` along with the
// associated encryption key.
//
dictionary AccessTokenInfo {

  // The scope of access granted by token.
  string scope;

  // The access token itself.
  //
  // This is the value that should be included in the `Authorization` header when
  // accessing an OAuth protected resource on behalf of the user.
  string token;

  // The client-side encryption key associated with this scope.
  //
  // **⚠️ Warning:** the value of this field should never be revealed outside of the
  // application. For example, it should never to sent to a server or logged in a log file.
  ScopedKey? key;

  // The expiry time of the token, in seconds.
  //
  // This is the timestamp at which the token is set to expire, in seconds since
  // unix epoch. Note that it is a signed integer, for compatibility with languages
  // that do not have an unsigned integer type.
  //
  // This timestamp is for guidance only. Access tokens are not guaranteed to remain
  // value for any particular lengthof time, and consumers should be prepared to handle
  // auth failures even if the token has not yet expired.
  i64 expires_at;
};

// A cryptograpic key associated with an OAuth scope.
//
// Some OAuth scopes have a corresponding client-side encryption key that is required
// in order to access protected data. This struct represents such key material in a
// format compatible with the common "JWK" standard.
//
dictionary ScopedKey {

  // The type of key.
  //
  // In practice for FxA, this will always be string string "oct" (short for "octal")
  // to represent a raw symmetric key.
  string kty;

  // The OAuth scope with which this key is associated.
  string scope;

  // The key material, as base64-url-encoded bytes.
  //
  // **⚠️ Warning:** the value of this field should never be revealed outside of the
  // application. For example, it should never to sent to a server or logged in a log file.
  string k;

  // An opaque unique identifier for this key.
  //
  // Unlike the `k` field, this value is not secret and may be revealed to the server.
  string kid;
};

// Parameters provided in an incoming OAuth request.
//
// This struct represents parameters obtained from an incoming OAuth request - that is,
// the values that an OAuth client would append to the authorization URL when initiating
// an OAuth sign-in flow.
//
dictionary AuthorizationParameters {
  string client_id;
  sequence<string> scope;
  string state;
  string access_type;
  string? code_challenge;
  string? code_challenge_method;
  string? keys_jwk;
};

// A device connected to the user's account.
//
// This struct provides metadata about a device connected to the user's account.
// This data would typically be used to display e.g. the list of candidate devices
// in a "send tab" menu.
//
dictionary Device {
  string id;
  string display_name;
  DeviceType device_type;
  sequence<DeviceCapability> capabilities;
  DevicePushSubscription? push_subscription;
  boolean push_endpoint_expired;
  boolean is_current_device;
  i64? last_access_time;
};

// Details of a web-push subscription endpoint.
//
// This struct encapsulates the details of a web-push subscription endpoint,
// including all the information necessary to send a notification to its owner.
// Devices attached to the user's account may register one of these in order
// to receive timely updates about account-related events.
//
// Managing a web-push subscription is outside of the scope of this component.
//
dictionary DevicePushSubscription {
  string endpoint;
  string public_key;
  string auth_key;
};

// The payload sent when invoking a "send tab" command.
//
dictionary SendTabPayload {

  // The navigation history of the sent tab.
  //
  // The last item in this list represents the page to be displayed,
  // while earlier items may be included in the navigation history
  // as a convenience to the user.
  sequence<TabHistoryEntry> entries;

  // A unique identifier to be included in send-tab metrics.
  //
  // The application should treat this as opaque.
  string flow_id;

  // A unique identifier to be included in send-tab metrics.
  //
  // The application should treat this as opaque.
  string stream_id;
};

// An individual entry in the navigation history of a sent tab.
//
dictionary TabHistoryEntry {
  string title;
  string url;
};

// A client connected to the user's account.
//
// This struct provides metadata about a client connected to the user's account.
// Unlike the [`Device`] struct, "clients" encompasses both client-side and server-side
// applications - basically anything where the user is able to sign in with their
// Firefox Account.
//
//
// This data would typically be used for targetted messaging purposes, catering the
// contents of the message to what other applications the user has on their account.
//
dictionary AttachedClient {
  string? client_id;
  string? device_id;
  DeviceType? device_type;
  boolean is_current_session;
  string? name;
  i64? created_time;
  i64? last_access_time;
  sequence<string>? scope;
};

// Information about the user that controls a Firefox Account.
//
// This struct represents details about the user themselves, and would typically be
// used to customize account-related UI in the browser so that it is personalize
// for the current user.
//
dictionary Profile {

  // The user's account uid
  //
  // This is an opaque immutable unique identifier for their account.
  string uid;

  // The user's current primary email address.
  //
  // Note that unlike the `uid` field, the email address may change over time.
  string email;

  // The user's preferred textual display name.
  string? display_name;

  // The URL of a profile picture representing the user.
  //
  // All accounts have a corresponding profile picture. If the user has not
  // provided one then a default image is used.
  string avatar;

  // Whether the `avatar` URL represents the default avatar image.
  boolean is_default_avatar;
};

// Statistics about the completion of a migration from legacy sign-in data.
//
// Applications migrating from legacy sign-in data would typically want to
// report telemetry about whether and how that succeeded, and can use the
// results reported in this struct to help do so.
//
dictionary FxAMigrationResult {

  // The time taken to migrate, in milliseconds.
  //
  // Note that this is a signed integer, for compatibility with languages
  // that do not have unsigned integers.
  i64 total_duration;
};



// Enumeration for the different types of device.
//
// Firefox Accounts seprates devices into broad categories for display purposes,
// such as distinguishing a desktop PC from a mobile phone. Upon signin, the
// application should inspect the device it is running on and select an appropriate
// [`DeviceType`] to include in its device registration record.
//
enum DeviceType {
  "Desktop",
  "Mobile",
  "Tablet",
  "VR",
  "TV",
  "Unknown",
};


// A "capability" offered by a device.
//
// In the FxA ecosystem, connected devices may advertize their ability to respond
// to various "commands" that can be invoked by other devices. The details of
// executing these commands are encapsulated as part of the FxA Client component,
// so consumers simply need to select which ones they want to support, and can
// use the variants of this enum to do so.
//
// In practice, the only currently-supported command is the ability to receive a tab.
//
enum DeviceCapability {
  "SendTab",
};


// An event that happened on the user's account.
//
// If the application has registered a [`DevicePushSubscription`] as part of its
// device record, then the Firefox Accounts server can send push notifications
// about important events that happen on the user's account. This enum represents
// the different kinds of event that can occur.
//
[Enum]
interface AccountEvent {

  // Sent when another device has invoked a command for this device to execute.
  //
  // When receiving this event, the application should inspect the contained
  // command and react appropriately.
  CommandReceived(IncomingDeviceCommand command );

  // Sent when the user has modified their account profile information.
  //
  // When receiving this event, the application should request fresh profile
  // information by calling [`get_profile`](FirefoxAccount::get_profile) with
  // `ignore_cache` set to true, and update any profile information displayed
  // in its UI.
  //
  ProfileUpdated();

  // Sent when when there has been a change in authorization status.
  //
  // When receiving this event, the application should check whether it is
  // still connected to the user's account by calling [`check_authorization_status`](
  // FirefoxAccount::check_authorization_status), and updating its UI as appropriate.
  //
  AccountAuthStateChanged();

  // Sent when the user deletes their Firefox Account.
  //
  // When receiving this event, the application should act as though the user had
  // signed out, discarding any persisted account state.
  AccountDestroyed();

  // Sent when a new device connects to the user's account.
  //
  // When receiving this event, the application may use it to trigger an update
  // of any UI that shows the list of connected devices. It may also show the
  // user an informational notice about the new device, as a security measure.
  DeviceConnected(string device_name );

  // Sent when a device disconnects from the user's account.
  //
  // When receiving this event, the application may use it to trigger an update
  // of any UI that shows the list of connected devices.
  DeviceDisconnected(string device_id, boolean is_local_device );
};


// A command invoked by another device.
//
// This enum represents all possible commands that can be invoked on
// the device. It is the responsibility of the application to interpret
// each command.
//
[Enum]
interface IncomingDeviceCommand {

  // Indicates that a tab has been sent to this device.
  TabReceived(Device? sender, SendTabPayload payload );
};


// The current state migration from legacy sign-in data.
//
// This enum distinguishes the different states of a potential in-flight
// migration from legacy sign-in data. A value other than [`None`](MigrationState::None)
// indicates that there was a previously-failed migration that should be
// retried.
//
enum MigrationState {

  // No in-flight migration.
  "None",

  // An in-flight migration that will copy the sessionToken.
  "CopySessionToken",

  // An in-flight migration that will re-use the sessionToken.
  "ReuseSessionToken",
};