fxa_client/
lib.rs

1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
4
5//! # Firefox Accounts Client
6//!
7//! The fxa-client component lets applications integrate with the
8//! [Firefox Accounts](https://mozilla.github.io/ecosystem-platform/docs/features/firefox-accounts/fxa-overview)
9//! identity service. The shape of a typical integration would look
10//! something like:
11//!
12//! * Out-of-band, register your application with the Firefox Accounts service,
13//!   providing an OAuth `redirect_uri` controlled by your application and
14//!   obtaining an OAuth `client_id`.
15//!
16//! * On application startup, create a [`FirefoxAccount`] object to represent the
17//!   signed-in state of the application.
18//!     * On first startup, a new [`FirefoxAccount`] can be created by calling
19//!       [`FirefoxAccount::new`] and passing the application's `client_id`.
20//!     * For subsequent startups the object can be persisted using the
21//!       [`to_json`](FirefoxAccount::to_json) method and re-created by
22//!       calling [`FirefoxAccount::from_json`].
23//!
24//! * When the user wants to sign in to your application, direct them through
25//!   a web-based OAuth flow using [`begin_oauth_flow`](FirefoxAccount::begin_oauth_flow)
26//!   or [`begin_pairing_flow`](FirefoxAccount::begin_pairing_flow); when they return
27//!   to your registered `redirect_uri`, pass the resulting authorization state back to
28//!   [`complete_oauth_flow`](FirefoxAccount::complete_oauth_flow) to sign them in.
29//!
30//! * Display information about the signed-in user by using the data from
31//!   [`get_profile`](FirefoxAccount::get_profile).
32//!
33//! * Access account-related services on behalf of the user by obtaining OAuth
34//!   access tokens via [`get_access_token`](FirefoxAccount::get_access_token).
35//!
36//! * If the user opts to sign out of the application, calling [`disconnect`](FirefoxAccount::disconnect)
37//!   and then discarding any persisted account data.
38
39mod account;
40mod auth;
41mod device;
42mod error;
43mod internal;
44mod profile;
45mod push;
46mod state_machine;
47mod storage;
48mod telemetry;
49mod token;
50
51use std::fmt;
52
53pub use sync15::DeviceType;
54use url::Url;
55
56pub use auth::{AuthorizationInfo, FxaEvent, FxaRustAuthState, FxaState, UserData};
57pub use device::{
58    AttachedClient, CloseTabsResult, Device, DeviceCapability, DeviceConfig, LocalDevice,
59};
60pub use error::{Error, FxaError};
61// reexport logging helpers.
62pub use error_support::{debug, error, info, trace, warn};
63
64use parking_lot::Mutex;
65pub use profile::Profile;
66pub use push::{
67    AccountEvent, CloseTabsPayload, DevicePushSubscription, IncomingDeviceCommand, SendTabPayload,
68    TabHistoryEntry,
69};
70pub use token::{AccessTokenInfo, AuthorizationParameters, ScopedKey};
71
72/// Result returned by internal functions
73pub type Result<T> = std::result::Result<T, Error>;
74/// Result returned by public-facing API functions
75pub type ApiResult<T> = std::result::Result<T, FxaError>;
76
77/// Object representing the signed-in state of an application.
78///
79/// The `FirefoxAccount` object is the main interface provided by this crate.
80/// It represents the signed-in state of an application that may be connected to
81/// user's Firefox Account, and provides methods for inspecting the state of the
82/// account and accessing other services on behalf of the user.
83///
84pub struct FirefoxAccount {
85    // For now, we serialize all access on a single `Mutex` for thread safety across
86    // the FFI. We should make the locking more granular in future.
87    internal: Mutex<internal::FirefoxAccount>,
88}
89
90impl FirefoxAccount {
91    /// Create a new [`FirefoxAccount`] instance, not connected to any account.
92    ///
93    /// **💾 This method alters the persisted account state.**
94    ///
95    /// This method constructs as new [`FirefoxAccount`] instance configured to connect
96    /// the application to a user's account.
97    pub fn new(config: FxaConfig) -> FirefoxAccount {
98        FirefoxAccount {
99            internal: Mutex::new(internal::FirefoxAccount::new(config)),
100        }
101    }
102
103    /// Used by the application to test auth token issues
104    pub fn simulate_network_error(&self) {
105        self.internal.lock().simulate_network_error()
106    }
107}
108
109#[derive(Clone, Debug)]
110pub struct FxaConfig {
111    /// FxaServer to connect with
112    pub server: FxaServer,
113    /// registered OAuth client id of the application.
114    pub client_id: String,
115    /// `redirect_uri` - the registered OAuth redirect URI of the application.
116    pub redirect_uri: String,
117    ///  URL for the user's Sync Tokenserver. This can be used to support users who self-host their
118    ///  sync data. If `None` then it will default to the Mozilla-hosted Sync server.
119    ///
120    ///  Note: this lives here for historical reasons, but probably shouldn't.  Applications pass
121    ///  the token server URL they get from `fxa-client` to `SyncManager`.  It would be simpler to
122    ///  cut out `fxa-client` out of the middle and have applications send the overridden URL
123    ///  directly to `SyncManager`.
124    pub token_server_url_override: Option<String>,
125}
126
127#[derive(Clone, Debug, PartialEq, Eq)]
128pub enum FxaServer {
129    Release,
130    Stable,
131    Stage,
132    China,
133    LocalDev,
134    Custom { url: String },
135}
136
137impl FxaServer {
138    fn content_url(&self) -> &str {
139        match self {
140            Self::Release | Self::China => "https://accounts.firefox.com",
141            Self::Stable => "https://stable.dev.lcip.org",
142            Self::Stage => "https://accounts.stage.mozaws.net",
143            Self::LocalDev => "http://127.0.0.1:3030",
144            Self::Custom { url } => url,
145        }
146    }
147}
148
149impl From<&Url> for FxaServer {
150    fn from(url: &Url) -> Self {
151        let origin = url.origin();
152        // Note: we can call unwrap() below because parsing content_url for known servers should
153        // never fail and `test_from_url` tests this.
154        if origin == Url::parse(Self::Release.content_url()).unwrap().origin() {
155            Self::Release
156        } else if origin == Url::parse(Self::Stable.content_url()).unwrap().origin() {
157            Self::Stable
158        } else if origin == Url::parse(Self::Stage.content_url()).unwrap().origin() {
159            Self::Stage
160        } else if origin
161            == Url::parse("https://accounts.firefox.com.cn")
162                .unwrap()
163                .origin()
164        {
165            // FxaServer::China is now the same as FxaServer::Release, but we may still end up being passed the old .cn domain.
166            // This is a little odd as we will not correctly round-trip in this scenario, but it seems better than the
167            // .cn domain being treated as `Self::Custom`.
168            Self::Release
169        } else if origin == Url::parse(Self::LocalDev.content_url()).unwrap().origin() {
170            Self::LocalDev
171        } else {
172            Self::Custom {
173                url: origin.ascii_serialization(),
174            }
175        }
176    }
177}
178
179/// Display impl
180///
181/// This identifies the variant, without recording the URL for custom servers.  It's good for
182/// Sentry reports when we don't want to give away any PII.
183impl fmt::Display for FxaServer {
184    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
185        let variant_name = match self {
186            Self::Release => "Release",
187            Self::Stable => "Stable",
188            Self::Stage => "Stage",
189            Self::China => "China",
190            Self::LocalDev => "LocalDev",
191            Self::Custom { .. } => "Custom",
192        };
193        write!(f, "{variant_name}")
194    }
195}
196
197impl FxaConfig {
198    pub fn release(client_id: impl ToString, redirect_uri: impl ToString) -> Self {
199        Self {
200            server: FxaServer::Release,
201            client_id: client_id.to_string(),
202            redirect_uri: redirect_uri.to_string(),
203            token_server_url_override: None,
204        }
205    }
206
207    pub fn stable(client_id: impl ToString, redirect_uri: impl ToString) -> Self {
208        Self {
209            server: FxaServer::Stable,
210            client_id: client_id.to_string(),
211            redirect_uri: redirect_uri.to_string(),
212            token_server_url_override: None,
213        }
214    }
215
216    pub fn stage(client_id: impl ToString, redirect_uri: impl ToString) -> Self {
217        Self {
218            server: FxaServer::Stage,
219            client_id: client_id.to_string(),
220            redirect_uri: redirect_uri.to_string(),
221            token_server_url_override: None,
222        }
223    }
224
225    pub fn dev(client_id: impl ToString, redirect_uri: impl ToString) -> Self {
226        Self {
227            server: FxaServer::LocalDev,
228            client_id: client_id.to_string(),
229            redirect_uri: redirect_uri.to_string(),
230            token_server_url_override: None,
231        }
232    }
233}
234
235uniffi::include_scaffolding!("fxa_client");
236
237#[cfg(test)]
238mod tests {
239    use super::*;
240
241    #[test]
242    fn test_from_url() {
243        let test_cases = [
244            ("https://accounts.firefox.com", FxaServer::Release),
245            ("https://stable.dev.lcip.org", FxaServer::Stable),
246            ("https://accounts.stage.mozaws.net", FxaServer::Stage),
247            ("https://accounts.firefox.com.cn", FxaServer::Release),
248            ("http://127.0.0.1:3030", FxaServer::LocalDev),
249            (
250                "http://my-fxa-server.com",
251                FxaServer::Custom {
252                    url: "http://my-fxa-server.com".to_owned(),
253                },
254            ),
255        ];
256        for (content_url, expected_result) in test_cases {
257            let url = Url::parse(content_url).unwrap();
258            assert_eq!(FxaServer::from(&url), expected_result);
259        }
260    }
261}
fxa_client/lib.rs

fxa_client/
lib.rs
