Struct fxa_client::FirefoxAccount

pub struct FirefoxAccount {
    client: Arc<dyn FxAClient + Sync + Send>,
    state: StateV2,
    flow_store: HashMap<String, OAuthFlow>,
    attached_clients_cache: Option<CachedResponse<Vec<GetAttachedClientResponse>>>,
    devices_cache: Option<CachedResponse<Vec<GetDeviceResponse>>>,
    auth_circuit_breaker: AuthCircuitBreaker,
    telemetry: RefCell<FxaTelemetry>,
}

Fields

client: Arc<dyn FxAClient + Sync + Send>

state: StateV2

flow_store: HashMap<String, OAuthFlow>

attached_clients_cache: Option<CachedResponse<Vec<GetAttachedClientResponse>>>

devices_cache: Option<CachedResponse<Vec<GetDeviceResponse>>>

auth_circuit_breaker: AuthCircuitBreaker

telemetry: RefCell<FxaTelemetry>

Implementations

impl FirefoxAccount

pub fn get_devices(&mut self, ignore_cache: bool) -> Result<Vec<Device>>

Fetches the list of devices from the current account including the current one.

• ignore_cache - If set to true, bypass the in-memory cache and fetch devices from the server.

pub fn get_current_device(&mut self) -> Result<Option<Device>>

fn register_capabilities(
    &mut self,
    capabilities: &[Capability]
) -> Result<HashMap<String, String>>

Replaces the internal set of "tracked" device capabilities by re-registering new capabilities and returns a set of device commands to register with the server.

pub fn initialize_device(
    &mut self,
    name: &str,
    device_type: Type,
    capabilities: &[Capability]
) -> Result<()>

Initalizes our own device, most of the time this will be called right after logging-in for the first time.

💾 This method alters the persisted account state.

pub fn ensure_capabilities(&mut self, capabilities: &[Capability]) -> Result<()>

Register a set of device capabilities against the current device.

As the only capability is Send Tab now, its command is registered with the server. Don't forget to also call this if the Sync Keys change as they encrypt the Send Tab command data.

💾 This method alters the persisted account state.

pub(crate) fn reregister_current_capabilities(&mut self) -> Result<()>

Re-register the device capabilities, this should only be used internally.

pub(crate) fn invoke_command(
    &self,
    command: &str,
    target: &Device,
    payload: &Value
) -> Result<()>

pub fn poll_device_commands(
    &mut self,
    reason: CommandFetchReason
) -> Result<Vec<IncomingDeviceCommand>>

Poll and parse any pending available command for our device. This should be called semi-regularly as the main method of commands delivery (push) can sometimes be unreliable on mobile devices. Typically called even when a push notification is received, so that any prior messages for which a push didn't arrive are still handled.

💾 This method alters the persisted account state.

pub fn ios_fetch_device_command(
    &mut self,
    index: u64
) -> Result<IncomingDeviceCommand>

Retrieve and parse a specific command designated by its index.

💾 This method alters the persisted account state.

Note that this should not be used if possible, as it does not correctly handle missed messages. It's currently used only on iOS due to platform restrictions (but we should still try and work out how to correctly handle missed messages within those restrictions) (What's wrong: if we get a push for tab-1 and a push for tab-3, and between them I've never explicitly polled, I'll miss tab-2, even if I try polling now)

fn fetch_and_parse_commands(
    &mut self,
    index: u64,
    limit: Option<u64>,
    reason: CommandFetchReason
) -> Result<Vec<IncomingDeviceCommand>>

fn parse_commands_messages(
    &mut self,
    messages: Vec<PendingCommand>,
    reason: CommandFetchReason
) -> Result<Vec<IncomingDeviceCommand>>

fn parse_command(
    &mut self,
    command: PendingCommand,
    devices: &[Device],
    reason: CommandFetchReason
) -> Result<IncomingDeviceCommand>

pub fn set_device_name(&mut self, name: &str) -> Result<DeviceResponseCommon>

pub fn clear_device_name(&mut self) -> Result<DeviceResponseCommon>

pub fn set_push_subscription(
    &mut self,
    push_subscription: &PushSubscription
) -> Result<DeviceResponseCommon>

pub(crate) fn register_command(
    &mut self,
    command: &str,
    value: &str
) -> Result<DeviceResponseCommon>

pub(crate) fn unregister_command(
    &mut self,
    _: &str
) -> Result<DeviceResponseCommon>

pub(crate) fn clear_commands(&mut self) -> Result<DeviceResponseCommon>

pub(crate) fn replace_device(
    &mut self,
    display_name: &str,
    device_type: &Type,
    push_subscription: &Option<PushSubscription>,
    commands: &HashMap<String, String>
) -> Result<DeviceResponseCommon>

fn update_device(
    &mut self,
    update: DeviceUpdateRequest<'_>
) -> Result<DeviceResponseCommon>

pub fn get_current_device_id(&mut self) -> Result<String>

Retrieve the current device id from state

impl FirefoxAccount

pub fn migrate_from_session_token(
    &mut self,
    session_token: &str,
    k_sync: &str,
    k_xcs: &str,
    copy_session_token: bool
) -> Result<FxAMigrationResult>

Migrate from a logged-in with a sessionToken Firefox Account.

• session_token - Hex-formatted session token.
• k_xcs - Hex-formatted kXCS.
• k_sync - Hex-formatted kSync.
• copy_session_token - If true then the provided 'session_token' will be duplicated and the resulting session will use a new session token. If false, the provided token will be reused.

This method remembers the provided token details and may persist them in the account state if it encounters a temporary failure such as a network error. Calling code is expected to store the updated state even if an error is thrown.

💾 This method alters the persisted account state.

pub fn is_in_migration_state(&self) -> MigrationState

Check if the client is in a pending migration state

pub fn try_migration(&mut self) -> Result<FxAMigrationResult>

fn network_migration(&mut self) -> Result<()>

impl FirefoxAccount

pub fn get_attached_clients(&mut self) -> Result<Vec<AttachedClient>>

Fetches the list of attached clients connected to the current account.

impl FirefoxAccount

pub fn get_access_token(
    &mut self,
    scope: &str,
    ttl: Option<u64>
) -> Result<AccessTokenInfo>

Fetch a short-lived access token using the saved refresh token. If there is no refresh token held or if it is not authorized for some of the requested scopes, this method will error-out and a login flow will need to be initiated using begin_oauth_flow.

• scopes - Space-separated list of requested scopes.
• ttl - the ttl in seconds of the token requested from the server.

💾 This method may alter the persisted account state.

pub fn get_session_token(&self) -> Result<String>

Retrieve the current session token from state

pub fn check_authorization_status(&mut self) -> Result<IntrospectInfo>

Check whether user is authorized using our refresh token.

pub fn begin_pairing_flow(
    &mut self,
    pairing_url: &str,
    scopes: &[&str],
    entrypoint: &str,
    metrics: Option<MetricsParams>
) -> Result<String>

Initiate a pairing flow and return a URL that should be navigated to.

• pairing_url - A pairing URL obtained by scanning a QR code produced by the pairing authority.
• scopes - Space-separated list of requested scopes by the pairing supplicant.
• entrypoint - The entrypoint to be used for data collection
• metrics - Optional parameters for metrics

pub fn begin_oauth_flow(
    &mut self,
    scopes: &[&str],
    entrypoint: &str,
    metrics: Option<MetricsParams>
) -> Result<String>

Initiate an OAuth login flow and return a URL that should be navigated to.

• scopes - Space-separated list of requested scopes.
• entrypoint - The entrypoint to be used for metrics
• metrics - Optional metrics parameters

pub fn authorize_code_using_session_token(
    &self,
    auth_params: AuthorizationParameters
) -> Result<String>

Fetch an OAuth code for a particular client using a session token from the account state.

• auth_params Authorization parameters which includes:
  • client_id - OAuth client id.
  • scope - list of requested scopes.
  • state - OAuth state.
  • access_type - Type of OAuth access, can be "offline" and "online"
  • pkce_params - Optional PKCE parameters for public clients (code_challenge and code_challenge_method)
  • keys_jwk - Optional JWK used to encrypt scoped keys

fn oauth_flow(&mut self, url: Url, scopes: &[&str]) -> Result<String>

pub fn complete_oauth_flow(&mut self, code: &str, state: &str) -> Result<()>

Complete an OAuth flow initiated in begin_oauth_flow or begin_pairing_flow. The code and state parameters can be obtained by parsing out the redirect URL after a successful login.

💾 This method alters the persisted account state.

pub(crate) fn handle_oauth_response(
    &mut self,
    resp: OAuthTokenResponse,
    scoped_keys_flow: Option<ScopedKeysFlow>
) -> Result<()>

pub fn handle_session_token_change(&mut self, session_token: &str) -> Result<()>

Typically called during a password change flow. Invalidates all tokens and fetches a new refresh token. Because the old refresh token is not valid anymore, we can't do like handle_oauth_response and re-create the device, so it is the responsibility of the caller to do so after we're done.

💾 This method alters the persisted account state.

pub fn clear_access_token_cache(&mut self)

💾 This method may alter the persisted account state.

pub fn new_logged_in(
    config: Config,
    session_token: &str,
    scoped_keys: HashMap<String, ScopedKey>
) -> Self

impl FirefoxAccount

pub fn get_profile(&mut self, ignore_cache: bool) -> Result<Profile>

Fetch the profile for the user. This method will error-out if the profile scope is not authorized for the current refresh token or or if we do not have a valid refresh token.

• ignore_cache - If set to true, bypass the in-memory cache and fetch the entire profile data from the server.

💾 This method alters the persisted account state.

fn get_profile_helper(&mut self, ignore_cache: bool) -> Result<Profile>

impl FirefoxAccount

pub fn handle_push_message(
    &mut self,
    payload: &str
) -> Result<Vec<AccountEvent>>

Handle any incoming push message payload coming from the Firefox Accounts servers that has been decrypted and authenticated by the Push crate.

Due to iOS platform restrictions, a push notification must always show UI. Since FxA sends one push notification per command received, we must only retrieve 1 command per push message, otherwise we risk receiving push messages for which the UI has already been shown. However, note that this means iOS currently risks losing messages for which a push notification doesn't arrive.

💾 This method alters the persisted account state.

impl FirefoxAccount

pub(crate) fn get_scoped_key(&self, scope: &str) -> Result<&ScopedKey>

impl FirefoxAccount

pub(crate) fn generate_send_tab_command_data(&mut self) -> Result<String>

Generate the Send Tab command to be registered with the server.

💾 This method alters the persisted account state.

fn load_or_generate_keys(&mut self) -> Result<PrivateSendTabKeysV1>

pub fn send_tab(
    &mut self,
    target_device_id: &str,
    title: &str,
    url: &str
) -> Result<()>

Send a single tab to another device designated by its device ID. XXX - We need a new send_tabs_to_devices() so we can correctly record telemetry for these cases. This probably requires a new "Tab" struct with the title and url. android-components has SendToAllUseCase(), so this isn't just theoretical. See https://github.com/mozilla/application-services/issues/3402

pub(crate) fn handle_send_tab_command(
    &mut self,
    sender: Option<GetDeviceResponse>,
    payload: Value,
    reason: ReceivedReason
) -> Result<IncomingDeviceCommand>

fn diagnose_remote_keys(
    &mut self,
    local_send_tab_key: PrivateSendTabKeysV1
) -> Result<()>

impl FirefoxAccount

pub fn get_ecosystem_anon_id(&mut self) -> Result<String>

Get the ecosystem anon id, generating it if necessary.

💾 This method alters the persisted account state.

fn get_ecosystem_anon_id_helper(
    &mut self,
    generate_placeholder: bool
) -> Result<String>

fn fetch_random_ecosystem_anon_id_key(&self) -> Result<Jwk>

pub fn gather_telemetry(&mut self) -> Result<String>

Gathers and resets telemetry for this account instance. This should be considered a short-term solution to telemetry gathering and should called whenever consumers expect there might be telemetry, and it should submit the telemetry to whatever telemetry system is in use (probably glean).

The data is returned as a JSON string, which consumers should parse forgivingly (eg, be tolerant of things not existing) to try and avoid too many changes as telemetry comes and goes.

impl FirefoxAccount

fn from_state(state: StateV2) -> Self

pub fn with_config(config: Config) -> Self

Create a new FirefoxAccount instance using a Config.

💾 This method alters the persisted account state.

pub fn new(
    content_url: &str,
    client_id: &str,
    redirect_uri: &str,
    token_server_url_override: Option<&str>
) -> Self

Create a new FirefoxAccount instance.

• content_url - The Firefox Account content server URL.
• client_id - The OAuth client_id.
• redirect_uri - The OAuth redirect_uri.
• token_server_url_override - Override the Token Server URL provided by the FxA's autoconfig endpoint.

💾 This method alters the persisted account state.

pub fn from_json(data: &str) -> Result<Self>

Restore a FirefoxAccount instance from a serialized state created using to_json.

pub fn to_json(&self) -> Result<String>

Serialize a FirefoxAccount instance internal state to be restored later using from_json.

pub fn clear_devices_and_attached_clients_cache(&mut self)

Clear the attached clients and devices cache

pub fn start_over(&mut self)

Clear the whole persisted/cached state of the account, but keep just enough information to eventually reconnect to the same user account later.

pub fn get_token_server_endpoint_url(&self) -> Result<Url>

Get the Sync Token Server endpoint URL.

pub fn get_pairing_authority_url(&self) -> Result<Url>

Get the pairing URL to navigate to on the Auth side (typically a computer).

pub fn get_connection_success_url(&self) -> Result<Url>

Get the "connection succeeded" page URL. It is typically used to redirect the user after having intercepted the OAuth login-flow state/code redirection.

pub fn get_manage_account_url(&mut self, entrypoint: &str) -> Result<Url>

Get the "manage account" page URL. It is typically used in the application's account status UI, to link the user out to a webpage where they can manage all the details of their account.

• entrypoint - Application-provided string identifying the UI touchpoint through which the page was accessed, for metrics purposes.

pub fn get_manage_devices_url(&mut self, entrypoint: &str) -> Result<Url>

Get the "manage devices" page URL. It is typically used in the application's account status UI, to link the user out to a webpage where they can manage the devices connected to their account.

• entrypoint - Application-provided string identifying the UI touchpoint through which the page was accessed, for metrics purposes.

fn add_account_identifiers_to_url(&mut self, url: Url) -> Result<Url>

fn get_refresh_token(&self) -> Result<&str>

pub fn disconnect(&mut self)

Disconnect from the account and optionally destroy our device record. This will leave the account object in a state where it can eventually reconnect to the same user. This is a "best effort" infallible method: e.g. if the network is unreachable, the device could still be in the FxA devices manager.

💾 This method alters the persisted account state.