Skip to main content

Internal SDK

The Internal SDK is designed for internal use within Bitwarden and supports key functionality for managing encrypted data, vault access, and user authentication. Written in Rust, the SDK is versatile and provides bindings for a variety of platforms, including mobile clients (Kotlin and Swift) and web clients (JavaScript/TypeScript).

This section will provide guidance on developing with the SDK in a way that ensures compatibility across both mobile and web platforms. It will cover best practices for structuring code, addressing platform-specific challenges, and ensuring that your implementation works seamlessly across Bitwarden’s mobile and web applications.

Architecture​

The internal SDK is structured as a single Git repository with multiple internal crates. This document describes the general structure of the project. Please review the README in the repository for information about the specific crates or implementation details.

Crates in the project fall into one of these categories.

  • Bindings
  • Application Interfaces
  • Features
  • Core and Utility

We generally strive towards extracting features into separate crates to keep the bitwarden-core crate as lean as possible. This has multiple benefits such as faster compile-time and clear ownership of features.

This hierarchy winds up producing a structure that looks like:

plantuml

Prior to bitwarden/sdk-internal#468, the application interfaces had not been explicitly created.

plantuml

Bindings​

Bindings are those crates whose purpose is to provide bindings for other projects by targeting wasm, iOS, and Android. The two mobile targets are built using UniFFI. See below for more information.

Application Interfaces​

An application interface collects the various features relevant for a given Bitwarden product, e.g. Password Manager, or Secrets Manager, into a single easy-to-use crate for that particular product.

Core and Utility​

The bitwarden-core crate contains the underlying functionality of the SDK. This includes a Client struct.

There are a number of utility crates that provide a very narrow scope of functionality and do not necessarily correspond to a single domain, or may be shared across multiple domains. Examples include UUID handling and cryptographic primitives.

Features and Domains​

Feature and domain crates constitute the application business logic. Feature crates depend on bitwarden-core and provide extensions to the Client struct to implement specific domains.

Client Struct​

The Client struct is the main entry point for the SDK and represents a single account instance. Any action that needs to be performed on the account is generally done through the Client struct. This allows the internals to be hidden from the consumer and provides a clear API.

We can extend the Client struct using extension traits in feature crates. This allow 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.

/// Generator extension for the Client struct
#[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 }
    }

    /// Generates a password based on the provided request.
    pub fn password(&self, input: PasswordGeneratorRequest) -> Result<String, PasswordError> {
        password(input)
    }
}

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

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

Language bindings​

The internal SDK supports mobile and web platforms and uses UniFFI and wasm-bindgen to generate bindings for those targets.

Mobile bindings​

We use UniFFI to generate bindings for the mobile platforms, more specifically we publish Android and iOS libraries with Kotlin and Swift bindings, respectively. While UniFFI supports additional languages they typically lag a few releases behind the UniFFI core library.

The Android bindings are currently published on GitHub Packages in the SDK repository. The swift package is published in the sdk-swift repository.

Web bindings​

For the web bindings we use wasm-bindgen to generate a WebAssembly module that can be used in JavaScript / TypeScript. To ensure compatibility with browsers that do not support WebAssembly, we also generate a JavaScript module from the WebAssembly that can be used as a fallback.

The WebAssembly module is published on npm.

Adding New Functionality​

Considering adding to or moving code into the SDK? Review these questions to help come to a decision.

  • Does the functionality or service depend on other functionality that is not currently part of the SDK?
    • Moving that functionality to the SDK is not recommended at this time, but asking the team responsible for the other functionality to migrate that to the SDK is recommended.
  • Does the functionality require authenticated requests?
    • The autogenerated bindings can help with that. See bitwarden-vault as an example.
  • Does this functionality require persistent state?
  • Is the functionality only relevant for a single client?
    • There is likely not much chance of reusing that functionality, but it may still be added to the SDK.
  • Does the functionality need the SDK to produce an observable or reactive value?
    • The SDK does not support reactivity at this time. However we still encourage migrating the relevant business logic to the SDK and then building reactivity with that logic in TypeScript.