Crate bitwarden_core 

Bitwarden Core

Core infrastructure crate providing the base Client type - a container for runtime persistent data and shared infrastructure that feature crates extend via extension traits. For an introduction to the SDK architecture, see the SDK Architecture documentation.

Do not add business logic or feature-specific functionality to this crate. Use feature crates instead.

Client structure

The Client type serves as a container for runtime persistent data, which is intended to persist for the lifetime of the SDK instance. Think of this as “dependency injection” for the SDK instance. It should only contain:

1. User identity:
   • UserId - Ensures each client is immutably associated with one user
2. Security state:
   • KeyStore - Secure in-memory key management
3. Network state:
   • ApiClient/ApiConfigurations - HTTP client initialized once and reused
   • Tokens enum - Includes ClientManagedTokens trait and SdkManagedTokens struct for access token management
4. Storage state:
   • Database/state repository registration

Plain data (tokens, flags, login info, profile data) should be accessed through Repository implementations, not stored directly in Client. Historical fields exist due to incremental migration - they will be moved to repositories over time.

Client vs InternalClient

• Client is a lightweight wrapper around Arc<InternalClient>
• Arc enables cheap cloning for FFI bindings (owned copies point to same underlying instance)
• InternalClient originally hid internal APIs from Secrets Manager, but this separation becomes less important as functionality moves to feature crates

Extension pattern

Feature crates extend Client via extension traits. This allows the underlying implementation to be internal to the crate with only the public API exposed through the Client struct. Below is an example of a generator extension for the Client struct.

IMPORTANT: Do not add feature functionality to Client itself.

use bitwarden_core::Client;
#[cfg(feature = "wasm")]
use wasm_bindgen::prelude::*;

/// Generator extension client that wraps the base Client
#[cfg_attr(feature = "wasm", wasm_bindgen)]
pub struct GeneratorClient {
    client: Client,
}

#[cfg_attr(feature = "wasm", wasm_bindgen)]
impl GeneratorClient {
    fn new(client: Client) -> Self {
        Self { client }
    }

    /// Example method that uses the underlying Client
    pub fn password(&self, input: PasswordGeneratorRequest) -> Result<String, PasswordError> {
        // Implementation details...
        self.client.internal.do_something(input)
    }
}

/// Extension trait which exposes `generator()` method on the `Client` struct
pub trait GeneratorClientsExt {
    fn generator(&self) -> GeneratorClient;
}

impl GeneratorClientsExt for Client {
    fn generator(&self) -> GeneratorClient {
        GeneratorClient::new(self.clone())
    }
}

// Usage:
// let password = client.generator().password(request)?;

API requests

One of the responsibilities of the Client is managing and exposing the ApiClient instances for our API and Identity back-end services, which should be used to make HTTP requests.

These ApiClients should be accessed through the ApiConfigurations struct that is returned from the get_api_configurations() function. get_api_configurations() also refreshes the authentication token if required.

// Example API call
let api_config = client.internal.get_api_configurations().await;
let response = api_config.api_client.ciphers_api().get_all().await?;

Need to update bindings for an API request? See documentation for instructions.

Features

• internal - Internal unstable APIs that should only be consumed by internal Bitwarden clients.
• no-memory-hardening - Disables bitwarden-crypto memory hardening.
• secrets - Secrets Manager specific functionality.
• uniffi - Mobile bindings.
• wasm - WebAssembly bindings.

Re-exports

pub use client::Client;

pub use client::ClientSettings;

pub use client::DeviceType;

Modules

auth

Authentication module

client

Bitwarden SDK Client

error 🔒

Errors that can occur when using this SDK

ids 🔒

key_management

This module contains the definition for the key identifiers used by the rest of the crates. Any code that needs to interact with the [KeyStore] should use these types.

mobile

Mobile specific functionality.

platform

Platform code

secrets_manager

Secrets Manager specific code.

uniffi_support 🔒

This module contains custom type converters for Uniffi.

Macros

require

This macro is used to require that a value is present or return an error otherwise. It is equivalent to using val.ok_or(Error::MissingFields)?, but easier to use and with a more descriptive error message. Note that this macro will return early from the function if the value is not present.

Structs

MissingFieldError

Missing required field.

MissingPrivateKeyError

Missing private key.

NotAuthenticatedError

Client is not authenticated or the session has expired.

OrganizationId

NewType wrapper for OrganizationId

UserId

NewType wrapper for UserId

WrongPasswordError

Wrong password.

ZeroizingAllocator

Allocator wrapper that zeros on free

Enums

ApiError

Errors from performing network requests.

Constants

UNIFFI_META_CONST_NAMESPACE_BITWARDEN_CORE 🔒

Export namespace metadata.