Skip to main content

bitwarden_core/client/
builder.rs

1use std::sync::{Arc, OnceLock, RwLock};
2
3use bitwarden_api_base::new_http_client_builder;
4use bitwarden_crypto::KeyStore;
5use bitwarden_managed_settings_types::ManagementProfile;
6use bitwarden_state::registry::StateRegistry;
7use reqwest::header::{self, HeaderValue};
8
9#[cfg(feature = "internal")]
10use crate::key_management::{CryptoSettings, state_bridge::StateBridge};
11use crate::{
12    auth::auth_tokens::{NoopTokenHandler, TokenHandler},
13    client::{
14        client::Client,
15        client_settings::{ClientName, ClientSettings, HostPlatformInfo},
16        internal::{ApiConfigurations, InternalClient},
17    },
18};
19
20/// Builder for constructing [`Client`] instances with custom configuration.
21pub struct ClientBuilder {
22    settings: Option<ClientSettings>,
23    token_handler: Arc<dyn TokenHandler>,
24    state_registry: Option<StateRegistry>,
25    middleware: Vec<Arc<dyn reqwest_middleware::Middleware>>,
26    managed_profile: Option<Arc<RwLock<Option<ManagementProfile>>>>,
27    #[cfg(feature = "test-fixtures")]
28    api_configurations: Option<Arc<ApiConfigurations>>,
29}
30
31impl ClientBuilder {
32    /// Creates a new [`ClientBuilder`] with default settings.
33    pub fn new() -> Self {
34        Self {
35            settings: None,
36            token_handler: Arc::new(NoopTokenHandler),
37            state_registry: None,
38            middleware: Vec::new(),
39            managed_profile: None,
40            #[cfg(feature = "test-fixtures")]
41            api_configurations: None,
42        }
43    }
44
45    /// Overrides the [`ApiConfigurations`] used by the client being built, allowing tests to inject
46    /// a mocked [`bitwarden_api_api::apis::ApiClient`] via
47    /// [`ApiConfigurations::from_api_client`]. Only available for testing.
48    #[cfg(feature = "test-fixtures")]
49    pub fn with_api_configurations(mut self, api_configurations: Arc<ApiConfigurations>) -> Self {
50        self.api_configurations = Some(api_configurations);
51        self
52    }
53
54    /// Sets the [`ClientSettings`] for the client being built.
55    pub fn with_settings(mut self, settings: ClientSettings) -> Self {
56        self.settings = Some(settings);
57        self
58    }
59
60    /// Sets a custom [`TokenHandler`] for managing authentication tokens.
61    pub fn with_token_handler(mut self, token_handler: Arc<dyn TokenHandler>) -> Self {
62        self.token_handler = token_handler;
63        self
64    }
65
66    /// Sets additional middleware to be chained outermost (before auth middleware).
67    pub fn with_middleware(
68        mut self,
69        middleware: Vec<Arc<dyn reqwest_middleware::Middleware>>,
70    ) -> Self {
71        self.middleware = middleware;
72        self
73    }
74
75    /// Sets a custom [`StateRegistry`] for the client being built.
76    /// If not set, defaults to [`StateRegistry::new_with_memory_db`].
77    pub fn with_state(mut self, state_registry: StateRegistry) -> Self {
78        self.state_registry = Some(state_registry);
79        self
80    }
81
82    /// Low-level hook to store a managed-settings profile cell, shared with the host application
83    /// that pushes profiles into it. Defaults to a fresh empty cell when not set.
84    ///
85    /// The `ManagedSettingsClient` in `bitwarden-managed-settings` supplies the cell. Instantiate
86    /// the client through that crate instead of calling this directly.
87    pub fn with_managed_profile(mut self, cell: Arc<RwLock<Option<ManagementProfile>>>) -> Self {
88        self.managed_profile = Some(cell);
89        self
90    }
91
92    /// Consumes the builder and constructs a [`Client`].
93    pub fn build(self) -> Client {
94        let settings = self.settings.unwrap_or_default();
95
96        let external_http_client = new_http_client_builder()
97            .build()
98            .expect("External HTTP Client build should not fail");
99
100        let headers = build_default_headers(&HostPlatformInfo::from(&settings));
101
102        let key_store = KeyStore::default();
103        let state_registry = self
104            .state_registry
105            .unwrap_or_else(StateRegistry::new_with_memory_db);
106
107        // Create the HTTP client for the Identity service, without authentication middleware.
108        let identity_http_client = new_http_client_builder()
109            .default_headers(headers.clone())
110            .build()
111            .expect("Bw HTTP Client build should not fail");
112        let identity = bitwarden_api_identity::Configuration {
113            base_path: settings.identity_url,
114            client: identity_http_client.into(),
115        };
116
117        // Create the client for the API service, with authentication middleware.
118        let auth_middleware = self.token_handler.initialize_middleware(
119            &state_registry,
120            identity.clone(),
121            key_store.clone(),
122        );
123
124        // Build the API HTTP client conditionally: disable auto-redirect when additional
125        // middleware is present so the outermost middleware can observe raw 3xx responses.
126        // reqwest::redirect is not available on wasm32 targets; on WASM the middleware uses
127        // a proactive cookie strategy instead of reactive 302/307 detection.
128        #[cfg(not(target_arch = "wasm32"))]
129        let api_http_client = if self.middleware.is_empty() {
130            new_http_client_builder()
131                .default_headers(headers)
132                .build()
133                .expect("Bw HTTP Client build should not fail")
134        } else {
135            new_http_client_builder()
136                .default_headers(headers)
137                .redirect(reqwest::redirect::Policy::none())
138                .build()
139                .expect("Bw HTTP Client (no redirect) build should not fail")
140        };
141
142        #[cfg(target_arch = "wasm32")]
143        let api_http_client = new_http_client_builder()
144            .default_headers(headers)
145            .build()
146            .expect("Bw HTTP Client build should not fail");
147
148        // Chain additional middleware outermost, then auth middleware innermost.
149        let mut middleware_builder = reqwest_middleware::ClientBuilder::new(api_http_client);
150        for mw in self.middleware {
151            middleware_builder = middleware_builder.with_arc(mw);
152        }
153        let bw_http_client = middleware_builder.with_arc(auth_middleware).build();
154        let api = bitwarden_api_api::Configuration {
155            base_path: settings.api_url,
156            client: bw_http_client,
157        };
158
159        #[cfg(feature = "test-fixtures")]
160        let api_configurations = self
161            .api_configurations
162            .unwrap_or_else(|| ApiConfigurations::new(identity, api, settings.device_type));
163        #[cfg(not(feature = "test-fixtures"))]
164        let api_configurations = ApiConfigurations::new(identity, api, settings.device_type);
165
166        let managed_profile = self
167            .managed_profile
168            .unwrap_or_else(|| Arc::new(RwLock::new(None)));
169
170        let client = Client {
171            internal: Arc::new(InternalClient {
172                user_id: OnceLock::new(),
173                token_handler: self.token_handler,
174                api_configurations,
175                external_http_client,
176                key_store,
177                #[cfg(feature = "internal")]
178                security_state: RwLock::new(None),
179                #[cfg(feature = "internal")]
180                state_bridge: StateBridge::new(),
181                #[cfg(feature = "internal")]
182                crypto_settings: CryptoSettings::new(),
183                state_registry: Arc::new(state_registry),
184                managed_profile,
185            }),
186        };
187
188        // Configure the key store's cipher suite from the client's deployment, so all crypto
189        // operations (e.g. the KDF for a new account) pick compliant algorithms.
190        let cipher_suite = client.internal.deployment_type().cipher_suite();
191        client
192            .internal
193            .get_key_store()
194            .set_cipher_suite(cipher_suite);
195
196        client
197    }
198}
199
200impl Default for ClientBuilder {
201    fn default() -> Self {
202        Self::new()
203    }
204}
205
206/// Build default headers for Bitwarden HttpClient
207pub(crate) fn build_default_headers(info: &HostPlatformInfo) -> header::HeaderMap {
208    let mut headers = header::HeaderMap::new();
209
210    // Handle optional headers
211
212    if let Some(device_identifier) = &info.device_identifier {
213        headers.append(
214            "Device-Identifier",
215            HeaderValue::from_str(device_identifier)
216                .expect("Device identifier should be a valid header value"),
217        );
218    }
219
220    if let Some(client_type) = Into::<Option<ClientName>>::into(info.device_type) {
221        headers.append(
222            "Bitwarden-Client-Name",
223            HeaderValue::from_str(&client_type.to_string())
224                .expect("All ASCII strings are valid header values"),
225        );
226    }
227
228    if let Some(version) = &info.bitwarden_client_version {
229        headers.append(
230            "Bitwarden-Client-Version",
231            HeaderValue::from_str(version).expect("Version should be a valid header value"),
232        );
233    }
234
235    if let Some(package_type) = &info.bitwarden_package_type {
236        headers.append(
237            "Bitwarden-Package-Type",
238            HeaderValue::from_str(package_type)
239                .expect("Package type should be a valid header value"),
240        );
241    }
242
243    // Handle required headers
244
245    headers.append(
246        "Device-Type",
247        HeaderValue::from_str(&(info.device_type as u8).to_string())
248            .expect("All numbers are valid ASCII"),
249    );
250
251    headers.append(
252        reqwest::header::USER_AGENT,
253        HeaderValue::from_str(&info.user_agent).expect("User agent should be a valid header value"),
254    );
255
256    headers
257}
258
259#[cfg(test)]
260mod tests {
261    use super::*;
262
263    #[test]
264    fn test_client_builder_default_builds() {
265        let _client = ClientBuilder::new().build();
266    }
267
268    #[test]
269    fn test_client_builder_with_settings_builds() {
270        let settings = ClientSettings::default();
271        let _client = ClientBuilder::new().with_settings(settings).build();
272    }
273
274    #[test]
275    fn test_client_builder_with_token_handler_builds() {
276        let handler: Arc<dyn TokenHandler> = Arc::new(NoopTokenHandler);
277        let _client = ClientBuilder::new().with_token_handler(handler).build();
278    }
279
280    #[test]
281    fn test_client_builder_chain_order_independence() {
282        let _a = ClientBuilder::new()
283            .with_settings(ClientSettings::default())
284            .with_token_handler(Arc::new(NoopTokenHandler) as Arc<dyn TokenHandler>)
285            .build();
286        let _b = ClientBuilder::new()
287            .with_token_handler(Arc::new(NoopTokenHandler) as Arc<dyn TokenHandler>)
288            .with_settings(ClientSettings::default())
289            .build();
290    }
291
292    #[test]
293    fn test_client_builder_with_state_builds() {
294        use bitwarden_state::registry::StateRegistry;
295        let registry = StateRegistry::new_with_memory_db();
296        let _client = ClientBuilder::new().with_state(registry).build();
297    }
298
299    #[test]
300    fn test_client_builder_with_state_in_chain() {
301        use bitwarden_state::registry::StateRegistry;
302        let registry = StateRegistry::new_with_memory_db();
303        let _client = ClientBuilder::new()
304            .with_settings(ClientSettings::default())
305            .with_state(registry)
306            .build();
307    }
308
309    #[test]
310    fn test_client_builder_defaults_to_an_empty_managed_profile() {
311        let client = ClientBuilder::new().build();
312
313        let handle = client.internal.managed_profile_handle();
314        assert!(
315            handle
316                .read()
317                .expect("cell should not be poisoned")
318                .is_none()
319        );
320    }
321
322    #[test]
323    fn test_client_builder_with_managed_profile_shares_the_cell() {
324        let cell = Arc::new(RwLock::new(Some(ManagementProfile::empty())));
325        let client = ClientBuilder::new()
326            .with_managed_profile(cell.clone())
327            .build();
328
329        *cell.write().expect("cell should not be poisoned") = None;
330
331        let handle = client.internal.managed_profile_handle();
332        assert!(
333            handle
334                .read()
335                .expect("cell should not be poisoned")
336                .is_none()
337        );
338    }
339
340    #[test]
341    fn test_client_builder_with_middleware_compiles() {
342        struct StubMiddleware;
343
344        #[async_trait::async_trait]
345        impl reqwest_middleware::Middleware for StubMiddleware {
346            async fn handle(
347                &self,
348                req: reqwest::Request,
349                extensions: &mut http::Extensions,
350                next: reqwest_middleware::Next<'_>,
351            ) -> reqwest_middleware::Result<reqwest::Response> {
352                next.run(req, extensions).await
353            }
354        }
355
356        let arc_middleware: Arc<dyn reqwest_middleware::Middleware> = Arc::new(StubMiddleware);
357        let _client = ClientBuilder::new()
358            .with_middleware(vec![arc_middleware])
359            .build();
360    }
361}