bitwarden_core/client/
builder.rs

1#[cfg(feature = "internal")]
2use std::sync::RwLock;
3use std::sync::{Arc, OnceLock};
4
5use bitwarden_api_base::new_http_client_builder;
6use bitwarden_crypto::KeyStore;
7use bitwarden_state::registry::StateRegistry;
8use reqwest::header::{self, HeaderValue};
9
10#[cfg(feature = "internal")]
11use crate::key_management::state_bridge::StateBridge;
12use crate::{
13    auth::auth_tokens::{NoopTokenHandler, TokenHandler},
14    client::{
15        client::Client,
16        client_settings::{ClientName, ClientSettings, HostPlatformInfo},
17        internal::{ApiConfigurations, InternalClient},
18    },
19};
20
21/// Builder for constructing [`Client`] instances with custom configuration.
22pub struct ClientBuilder {
23    settings: Option<ClientSettings>,
24    token_handler: Arc<dyn TokenHandler>,
25    state_registry: Option<StateRegistry>,
26    middleware: Vec<Arc<dyn reqwest_middleware::Middleware>>,
27}
28
29impl ClientBuilder {
30    /// Creates a new [`ClientBuilder`] with default settings.
31    pub fn new() -> Self {
32        Self {
33            settings: None,
34            token_handler: Arc::new(NoopTokenHandler),
35            state_registry: None,
36            middleware: Vec::new(),
37        }
38    }
39
40    /// Sets the [`ClientSettings`] for the client being built.
41    pub fn with_settings(mut self, settings: ClientSettings) -> Self {
42        self.settings = Some(settings);
43        self
44    }
45
46    /// Sets a custom [`TokenHandler`] for managing authentication tokens.
47    pub fn with_token_handler(mut self, token_handler: Arc<dyn TokenHandler>) -> Self {
48        self.token_handler = token_handler;
49        self
50    }
51
52    /// Sets additional middleware to be chained outermost (before auth middleware).
53    pub fn with_middleware(
54        mut self,
55        middleware: Vec<Arc<dyn reqwest_middleware::Middleware>>,
56    ) -> Self {
57        self.middleware = middleware;
58        self
59    }
60
61    /// Sets a custom [`StateRegistry`] for the client being built.
62    /// If not set, defaults to [`StateRegistry::new_with_memory_db`].
63    pub fn with_state(mut self, state_registry: StateRegistry) -> Self {
64        self.state_registry = Some(state_registry);
65        self
66    }
67
68    /// Consumes the builder and constructs a [`Client`].
69    pub fn build(self) -> Client {
70        let settings = self.settings.unwrap_or_default();
71
72        let external_http_client = new_http_client_builder()
73            .build()
74            .expect("External HTTP Client build should not fail");
75
76        let headers = build_default_headers(&HostPlatformInfo::from(&settings));
77
78        let key_store = KeyStore::default();
79        let state_registry = self
80            .state_registry
81            .unwrap_or_else(StateRegistry::new_with_memory_db);
82
83        // Create the HTTP client for the Identity service, without authentication middleware.
84        let identity_http_client = new_http_client_builder()
85            .default_headers(headers.clone())
86            .build()
87            .expect("Bw HTTP Client build should not fail");
88        let identity = bitwarden_api_identity::Configuration {
89            base_path: settings.identity_url,
90            client: identity_http_client.into(),
91        };
92
93        // Create the client for the API service, with authentication middleware.
94        let auth_middleware = self.token_handler.initialize_middleware(
95            &state_registry,
96            identity.clone(),
97            key_store.clone(),
98        );
99
100        // Build the API HTTP client conditionally: disable auto-redirect when additional
101        // middleware is present so the outermost middleware can observe raw 3xx responses.
102        // reqwest::redirect is not available on wasm32 targets; on WASM the middleware uses
103        // a proactive cookie strategy instead of reactive 302/307 detection.
104        #[cfg(not(target_arch = "wasm32"))]
105        let api_http_client = if self.middleware.is_empty() {
106            new_http_client_builder()
107                .default_headers(headers)
108                .build()
109                .expect("Bw HTTP Client build should not fail")
110        } else {
111            new_http_client_builder()
112                .default_headers(headers)
113                .redirect(reqwest::redirect::Policy::none())
114                .build()
115                .expect("Bw HTTP Client (no redirect) build should not fail")
116        };
117
118        #[cfg(target_arch = "wasm32")]
119        let api_http_client = new_http_client_builder()
120            .default_headers(headers)
121            .build()
122            .expect("Bw HTTP Client build should not fail");
123
124        // Chain additional middleware outermost, then auth middleware innermost.
125        let mut middleware_builder = reqwest_middleware::ClientBuilder::new(api_http_client);
126        for mw in self.middleware {
127            middleware_builder = middleware_builder.with_arc(mw);
128        }
129        let bw_http_client = middleware_builder.with_arc(auth_middleware).build();
130        let api = bitwarden_api_api::Configuration {
131            base_path: settings.api_url,
132            client: bw_http_client,
133        };
134
135        Client {
136            internal: Arc::new(InternalClient {
137                user_id: OnceLock::new(),
138                token_handler: self.token_handler,
139                api_configurations: ApiConfigurations::new(identity, api, settings.device_type),
140                external_http_client,
141                key_store,
142                #[cfg(feature = "internal")]
143                security_state: RwLock::new(None),
144                #[cfg(feature = "internal")]
145                state_bridge: StateBridge::new(),
146                state_registry,
147            }),
148        }
149    }
150}
151
152impl Default for ClientBuilder {
153    fn default() -> Self {
154        Self::new()
155    }
156}
157
158/// Build default headers for Bitwarden HttpClient
159pub(crate) fn build_default_headers(info: &HostPlatformInfo) -> header::HeaderMap {
160    let mut headers = header::HeaderMap::new();
161
162    // Handle optional headers
163
164    if let Some(device_identifier) = &info.device_identifier {
165        headers.append(
166            "Device-Identifier",
167            HeaderValue::from_str(device_identifier)
168                .expect("Device identifier should be a valid header value"),
169        );
170    }
171
172    if let Some(client_type) = Into::<Option<ClientName>>::into(info.device_type) {
173        headers.append(
174            "Bitwarden-Client-Name",
175            HeaderValue::from_str(&client_type.to_string())
176                .expect("All ASCII strings are valid header values"),
177        );
178    }
179
180    if let Some(version) = &info.bitwarden_client_version {
181        headers.append(
182            "Bitwarden-Client-Version",
183            HeaderValue::from_str(version).expect("Version should be a valid header value"),
184        );
185    }
186
187    if let Some(package_type) = &info.bitwarden_package_type {
188        headers.append(
189            "Bitwarden-Package-Type",
190            HeaderValue::from_str(package_type)
191                .expect("Package type should be a valid header value"),
192        );
193    }
194
195    // Handle required headers
196
197    headers.append(
198        "Device-Type",
199        HeaderValue::from_str(&(info.device_type as u8).to_string())
200            .expect("All numbers are valid ASCII"),
201    );
202
203    headers.append(
204        reqwest::header::USER_AGENT,
205        HeaderValue::from_str(&info.user_agent).expect("User agent should be a valid header value"),
206    );
207
208    headers
209}
210
211#[cfg(test)]
212mod tests {
213    use super::*;
214
215    #[test]
216    fn test_client_builder_default_builds() {
217        let _client = ClientBuilder::new().build();
218    }
219
220    #[test]
221    fn test_client_builder_with_settings_builds() {
222        let settings = ClientSettings::default();
223        let _client = ClientBuilder::new().with_settings(settings).build();
224    }
225
226    #[test]
227    fn test_client_builder_with_token_handler_builds() {
228        let handler: Arc<dyn TokenHandler> = Arc::new(NoopTokenHandler);
229        let _client = ClientBuilder::new().with_token_handler(handler).build();
230    }
231
232    #[test]
233    fn test_client_builder_chain_order_independence() {
234        let _a = ClientBuilder::new()
235            .with_settings(ClientSettings::default())
236            .with_token_handler(Arc::new(NoopTokenHandler) as Arc<dyn TokenHandler>)
237            .build();
238        let _b = ClientBuilder::new()
239            .with_token_handler(Arc::new(NoopTokenHandler) as Arc<dyn TokenHandler>)
240            .with_settings(ClientSettings::default())
241            .build();
242    }
243
244    #[test]
245    fn test_client_builder_with_state_builds() {
246        use bitwarden_state::registry::StateRegistry;
247        let registry = StateRegistry::new_with_memory_db();
248        let _client = ClientBuilder::new().with_state(registry).build();
249    }
250
251    #[test]
252    fn test_client_builder_with_state_in_chain() {
253        use bitwarden_state::registry::StateRegistry;
254        let registry = StateRegistry::new_with_memory_db();
255        let _client = ClientBuilder::new()
256            .with_settings(ClientSettings::default())
257            .with_state(registry)
258            .build();
259    }
260
261    #[test]
262    fn test_client_builder_with_middleware_compiles() {
263        struct StubMiddleware;
264
265        #[async_trait::async_trait]
266        impl reqwest_middleware::Middleware for StubMiddleware {
267            async fn handle(
268                &self,
269                req: reqwest::Request,
270                extensions: &mut http::Extensions,
271                next: reqwest_middleware::Next<'_>,
272            ) -> reqwest_middleware::Result<reqwest::Response> {
273                next.run(req, extensions).await
274            }
275        }
276
277        let arc_middleware: Arc<dyn reqwest_middleware::Middleware> = Arc::new(StubMiddleware);
278        let _client = ClientBuilder::new()
279            .with_middleware(vec![arc_middleware])
280            .build();
281    }
282}
bitwarden_core/client/builder.rs

bitwarden_core/client/
builder.rs
