fxa_client.udl

[External="sync15"]
typedef extern DeviceType;

/// # 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 for that state.
  /// This may indicate a user who navigated directly to the OAuth `redirect_uri` for the application.
  "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",

  /// Origin mismatch when handling a pairing flow
  ///
  /// The most likely cause of this is that a user tried to pair together two firefox instances
  /// that are configured to use different servers.
  "OriginMismatch",

  /// The sync scoped key was missing in the server response
  "SyncScopedKeyMissingInServerResponse",

  /// 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",
};


/// The result of invoking a "close tabs" command.
///
/// If [`FirefoxAccount::close_tabs`] is called with more URLs than can fit
/// into a single command payload, the URLs will be chunked and sent in
/// multiple commands.
///
/// Chunking breaks the atomicity of a "close tabs" command, but
/// reduces the number of these commands that FxA sends to other devices.
/// This is critical for platforms like iOS, where every command triggers a
/// push message that must show a user-visible notification.
[Enum]
interface CloseTabsResult {
  /// All URLs passed to [`FirefoxAccount::close_tabs`] were chunked and sent
  /// in one or more device commands.
  Ok();

  /// One or more URLs passed to [`FirefoxAccount::close_tabs`] couldn't be sent
  /// in a device command. The caller can assume that:
  ///
  /// 1. Any URL in the returned list of `urls` was not sent, and
  ///    should be retried.
  /// 2. All other URLs that were passed to [`FirefoxAccount::close_tabs`], and
  ///    that are _not_ in the list of `urls`, were chunked and sent.
  TabsNotClosed(sequence<string> urls);
};


/// 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.
  constructor(FxaConfig config);

  /// 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();
  
  /// Sets the users information based on the web content's login information
  /// This is intended to only be used by user agents (eg: Firefox) to set the users
  /// session token and tie it to the refresh token that will be issued at the end of the
  /// oauth flow.
  void set_user_data(UserData user_data);

  /// 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 parameters.
  ///       - These will be included as query parameters in the resulting URL.
  ///
  [Throws=FxaError]
  string begin_oauth_flow([ByRef] sequence<string> scopes, [ByRef] string entrypoint);
  

  /// 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 parameters.
  ///       - 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);
  

  /// 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();

  /// Update the state based on authentication issues.
  ///
  /// **💾 This method alters the persisted account state.**
  ///
  /// Call this if you know there's an authentication / authorization issue that requires the
  /// user to re-authenticated.  It transitions the user to the [FxaRustAuthState.AuthIssues] state.
  void on_auth_issues();

  /// Get the high-level authentication state of the client
  ///
  /// Deprecated: Use get_state() instead
  FxaRustAuthState get_auth_state();

  /// Get the current state
  FxaState get_state();

  /// Process an event (login, logout, etc).
  ///
  /// On success, update the current state and return it.
  /// On error, the current state will remain the same.
  [Throws=FxaError]
  FxaState process_event(FxaEvent event);

  /// 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 registered 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]
  LocalDevice 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 account. 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 targeted 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]
  LocalDevice 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-registered 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]
  LocalDevice 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]
  LocalDevice set_push_subscription( DevicePushSubscription subscription );


  /// Process and respond to a server-delivered account update message
  ///
  /// **💾 This method alters the persisted account state.**
  ///
  /// Applications should call this method whenever they receive a push notification from 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 internal state
  /// accordingly and return an individual [`AccountEvent`] struct describing the event, which the application
  /// may use for further processing.
  ///
  /// It's important to note if the event is [`AccountEvent::CommandReceived`], the caller should call
  /// [`FirefoxAccount::poll_device_commands`]
  ///
  [Throws=FxaError]
  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 );


  /// Use device commands to close one or more tabs on another device.
  ///
  /// **💾 This method alters the persisted account state.**
  ///
  /// If a device on the account has registered the [`CloseTabs`](DeviceCapability::CloseTabs)
  /// capability, this method can be used to close its tabs.
  [Throws=FxaError]
  CloseTabsResult close_tabs([ByRef] string target_device_id, sequence<string> urls);


  /// 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,  optional i64? ttl = null);

  /// 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 retrieve
  /// 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 incoming and outgoing device commands.
  ///
  /// Applications that have registered one or more [`DeviceCapability`]s
  /// 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();

  /// Used by the application to test auth token issues
  void simulate_network_error();

  /// Used by the application to test auth token issues
  void simulate_temporary_auth_token_issue();

  /// Used by the application to test auth token issues
  void simulate_permanent_auth_token_issue();
};

dictionary FxaConfig {
    /// FxaServer to connect with
    FxaServer server;
    /// Registered OAuth client id of the application.
    string client_id;
    /// `redirect_uri` - the registered OAuth redirect URI of the application.
    string redirect_uri;
    ///  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.
    string? token_server_url_override = null;
};

/// FxA server to connect to
[Enum]
interface FxaServer {
    Release();
    Stable();
    Stage();
    China();
    LocalDev();
    Custom(string url);
};

/// 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;
};

/// 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 cryptographic 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;
};

/// Device configuration
dictionary DeviceConfig {
  string name;
  DeviceType device_type;
  sequence<DeviceCapability> capabilities;
};

/// Local device that's connecting to FxA
///
/// This is returned by the device update methods and represents the server's view of the local
/// device.
dictionary LocalDevice {
  string id;
  string display_name;
  DeviceType device_type;
  sequence<DeviceCapability> capabilities;
  DevicePushSubscription? push_subscription;
  boolean push_endpoint_expired;
};

/// 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 = "";
};

/// The payload sent when invoking a "close tabs" command.
///
dictionary CloseTabsPayload {

  /// The URLs of the tabs to close.
  sequence<string> urls;
};

/// 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 targeted 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;
};

[Enum]
interface FxaState {
  Uninitialized();
  Disconnected();
  Authenticating(string oauth_url);
  Connected();
  AuthIssues();
};

[Enum]
interface FxaEvent {
  Initialize(DeviceConfig device_config);
  BeginOAuthFlow(sequence<string> scopes, string entrypoint);
  BeginPairingFlow(string pairing_url, sequence<string> scopes, string entrypoint);
  CompleteOAuthFlow(string code, string state);
  CancelOAuthFlow();
  CheckAuthorizationStatus();
  Disconnect();
  CallGetProfile();
};

enum FxaRustAuthState {
  "Disconnected",
  "Connected",
  "AuthIssues",
};

/// 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.
///
enum DeviceCapability {
  "SendTab",
  "CloseTabs",
};


/// 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 );

  /// An unknown event, most likely an event the client doesn't support yet.
  ///
  /// When receiving this event, the application should gracefully ignore it.
  Unknown();
};


/// 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 );

  /// Indicates that the sender wants to close one or more tabs on this device.
  TabsClosed(Device? sender, CloseTabsPayload payload);
};

/// Machinery for dry-run testing of FxaAuthStateMachine
///
/// Remove this once we've migrated the firefox-android and firefox-ios code to using FxaAuthStateMachine
/// https:///bugzilla.mozilla.org/show_bug.cgi?id=1867793

interface FxaStateMachineChecker {
  constructor();

  void handle_public_event(FxaEvent event);
  void handle_internal_event(FxaStateCheckerEvent event);
  void check_public_state(FxaState state);
  void check_internal_state(FxaStateCheckerState state);
};

[Enum]
interface FxaStateCheckerEvent {
  GetAuthStateSuccess(FxaRustAuthState auth_state);
  BeginOAuthFlowSuccess(string oauth_url);
  BeginPairingFlowSuccess(string oauth_url);
  CompleteOAuthFlowSuccess();
  InitializeDeviceSuccess();
  EnsureDeviceCapabilitiesSuccess();
  CheckAuthorizationStatusSuccess(boolean active);
  DisconnectSuccess();
  GetProfileSuccess();
  CallError();
  EnsureCapabilitiesAuthError();
};

[Enum]
interface FxaStateCheckerState {
  GetAuthState();
  BeginOAuthFlow(sequence<string> scopes, string entrypoint);
  BeginPairingFlow(string pairing_url, sequence<string> scopes, string entrypoint);
  CompleteOAuthFlow(string code, string state);
  InitializeDevice();
  EnsureDeviceCapabilities();
  CheckAuthorizationStatus();
  Disconnect();
  GetProfile();
  Complete(FxaState new_state);
  Cancel();
};

dictionary UserData {
  string session_token;
  string uid;
  string email;
  boolean verified;
};