Building

CoreCrypto uses GNU Make as the top-level build orchestrator. Each platform has a dedicated Make target that compiles the Rust FFI library, generates language bindings, and assembles the final artifact.

General requirements

All platforms require the following baseline tools.

Tool	Version	Install
Rust	`1.94.0` (pinned in `rust-toolchain.toml`)	rustup.rs
GNU Make	≥ 4.3	gnu.org/software/make
cargo-nextest	latest	`cargo install --locked cargo-nextest`

The rust-toolchain.toml file at the repository root pins the exact toolchain version. Running any cargo or make command inside the repo will cause rustup to install 1.94.0 automatically if it is not already present.

Pre-commit hooks

Install the pre-commit framework

Follow the instructions at pre-commit.com for your OS.

Initialise the hooks

pre-commit install

Platforms

TypeScript / WASM
Kotlin / JVM
Android
Swift / iOS
Rust (native)

Prerequisites

Add the WASM Rust target

rustup target add wasm32-unknown-unknown

Install Node.js

The recommended way is via Volta. Any method that puts a recent node on your PATH works.

Install Bun

Follow the instructions on bun.sh.

Install wasm-bindgen-cli

The CLI version must exactly match the wasm-bindgen crate version recorded in Cargo.lock.

wasm_bindgen_version="$(
  cargo metadata --format-version 1 |
  jq -r '.packages[] | select (.name == "wasm-bindgen") | .version'
)"
cargo install wasm-bindgen-cli --version $wasm_bindgen_version

A version mismatch between wasm-bindgen-cli and the wasm-bindgen crate in Cargo.lock will cause test failures. Always derive the version from Cargo.lock as shown above.

Install chromedriver for tests

bunx @puppeteer/browsers install --path ~/bin chrome-headless-shell
bunx @puppeteer/browsers install --path ~/bin chromedriver

Build

make ts

This builds the WASM binary and the TypeScript wrapper for the browser target.

Test

make ts-test

Tests run via WebdriverIO against a headless Chrome instance, plus Bun’s built-in test runner for the native target.

Use the CC_TEST_LOG_LEVEL environment variable to control log verbosity during tests:

CC_TEST_LOG_LEVEL=1 — emit browser console logs
CC_TEST_LOG_LEVEL=2 — emit browser console logs and CoreCrypto internal logs

To run a specific test by name:

make ts-test TEST="<test name or regex>"

Prerequisites

Install SDKMAN!

curl -s "https://get.sdkman.io" | bash

Install Java 17

sdk install java 17.0.17-tem

Install Kotlin

sdk install kotlin

Build

make jvm

Automatically selects aarch64-apple-darwin on macOS or x86_64-unknown-linux-gnu on Linux.

Test

make jvm-test

Prerequisites

Install Android SDK and Build-Tools

Install Android Studio. Ensure Build-Tools for API level 30 or higher are present.

On macOS, you must set ANDROID_SDK_ROOT manually:

export ANDROID_SDK_ROOT=~/Android/Sdk

Install the Android NDK

Install the NDK from Android Studio (SDK Manager → SDK Tools → NDK). Then set ANDROID_NDK_HOME to the NDK path:

export ANDROID_NDK_HOME="$ANDROID_SDK_ROOT/ndk/<version>"

Add Android Rust targets

rustup target add x86_64-linux-android aarch64-linux-android armv7-linux-androideabi

Build

make android

Builds libcore_crypto_ffi.so for all three Android ABIs (ARMv7, AArch64, x86_64), generates the Kotlin UniFFI bindings, and assembles the AAR via Gradle.

Test

make android-test

On Linux the x86_64 target is used; on macOS the AArch64 target is used.

Swift and iOS builds are only supported on macOS.

Prerequisites

Install Xcode and command-line tools

Install Xcode from developer.apple.com/xcode and accept the license. Then install the command-line tools:

xcode-select --install

Add iOS Rust targets

rustup target add aarch64-apple-ios aarch64-apple-ios-sim

Build

make ios

Builds libcore_crypto_ffi for the physical device target (aarch64-apple-ios) and the simulator target (aarch64-apple-ios-sim), then generates Swift UniFFI bindings.

XCFramework

To produce the distributable .xcframework bundles:

make ios-create-xcframework

This runs xcodebuild archive for both device and simulator slices, then calls xcodebuild -create-xcframework to merge them. The output is two zip archives:

WireCoreCrypto.xcframework.zip
WireCoreCryptoUniffi.xcframework.zip

Test

make ios-test

Runs the Swift test suite in the iOS simulator. macOS only.

Build

cargo build

For a release build:

cargo build --release

You can also pass RELEASE=1 to any Make target to enable release mode across the whole build:

make ts RELEASE=1

Test

cargo nextest run

Feature flags

Flag	Description
`proteus`	Enable Proteus session support
`test-all-cipher`	Run tests against all MLS ciphersuites (slow)

# Run tests against all ciphersuites (takes a long time)
cargo nextest run --features test-all-cipher

Running specific tests

Pass a test filter to nextest:

cargo nextest run <filter>

For example, to run all tests whose name contains mls_create:

cargo nextest run mls_create

Keystore WASM tests

To run keystore unit tests on the wasm32-unknown-unknown target (requires the WASM build prerequisites above):

cargo test --target wasm32-unknown-unknown -p core-crypto-keystore

cargo-nextest does not work reliably with the WASM test runner; use cargo test for WASM keystore tests.

Interop testing

The interop test suite verifies that all binding layers can exchange MLS messages with each other. It is a superset of the per-platform test requirements.

Run all per-platform test suites

Complete the TypeScript, Kotlin/JVM, Android, and (on macOS) Swift/iOS test runs first. The interop test relies on the build artifacts produced by those steps.

Install Chrome and chromedriver

Follow the same chromedriver setup described in the TypeScript/WASM tab above.

Run the interop tests

make interop-test

End-to-end identity (E2EI) testing

E2EI tests verify the full OIDC certificate flow and require a running container runtime (Docker or Podman).

Prepare the container runtime

Linux — Docker
Linux — Podman
macOS — Docker
macOS — Podman

systemctl start docker.service

# Start socket activation
systemctl --user start podman.socket

# Verify
podman version

# If the above fails, point DOCKER_HOST at Podman's socket
export DOCKER_HOST=unix:///run/user/$UID/podman/podman.sock

# Install Docker and Docker Desktop
brew install docker docker-desktop

# Launch Docker Desktop as a GUI application, then verify:
docker version

brew install podman

sudo podman-mac-helper install

# Create a VM using a known-good image version
podman machine init --image docker://quay.io/podman/machine-os:5.5

podman machine start

# Verify (should print 5.5.x)
podman version

# Symlink docker → podman (test scripts expect the `docker` command)
ln -s /opt/homebrew/bin/podman /opt/homebrew/bin/docker

Choose the OIDC identity provider

Set the TEST_IDP environment variable before running tests:

# Use Keycloak
export TEST_IDP=keycloak

# Or use Authelia
export TEST_IDP=authelia

Run all E2EI tests

bash scripts/run-e2ei-tests.sh

The script starts the required containers, runs all tests, and cleans up containers and processes on exit.

Run specific E2EI tests

Arguments after the script name are forwarded to cargo nextest:

bash scripts/run-e2ei-tests.sh alg::p256

Manually invoke tests

For finer control, start test-wire-server manually:

Start test-wire-server

cargo run --locked --bin test-wire-server

Note the address printed on stdout, for example 127.0.0.1:20530.

Export the server address

export TEST_WIRE_SERVER_ADDR=127.0.0.1:20530

Run a specific test

cargo nextest run --locked --ignore-default-filter -p wire-e2e-identity alg::p256

Clean up containers

# If using Keycloak
docker kill keycloak && docker rm keycloak

# If using Authelia
docker kill authelia.local && docker rm authelia.local

Also terminate the test-wire-server process.

Formatting and linting

All languages are covered by top-level Make targets:

make fmt    # Format all files
make check  # Lint all files

Individual targets are available if you only need one language:

Target	Language	Tool
`make rust-fmt` / `make rust-check`	Rust	`cargo +nightly fmt`, `cargo clippy`
`make swift-fmt` / `make swift-check`	Swift	`swift-format`, `swiftlint`
`make kotlin-fmt` / `make kotlin-check`	Kotlin	`ktlint`
`make ts-fmt` / `make ts-check`	TypeScript	`eslint`, `tsc`

Per-language tool installation

Swift
Kotlin
Markdown
TOML

Formatter: swift-format
Linter: SwiftLint

Both tools are available via Homebrew:

brew install swift-format swiftlint

Formatter and linter: ktlint

Install via Homebrew or from the ktlint GitHub releases page:

brew install ktlint

Markdown files are formatted with mdformat and the following extensions:

pip install mdformat mdformat-gfm mdformat-frontmatter mdformat-footnote mdformat-gfm-alerts mdformat-toc

TOML files are formatted with taplo:

cargo install taplo-cli

API Reference

FFI & Bindings

General requirements

Pre-commit hooks

Platforms

Prerequisites

Build

Test

Prerequisites

Build

Test

Prerequisites

Build

Test

Prerequisites

Build

XCFramework

Test

Build

Test

Feature flags

Running specific tests

Keystore WASM tests

Interop testing

End-to-end identity (E2EI) testing

Prepare the container runtime

Choose the OIDC identity provider

Run all E2EI tests

Run specific E2EI tests

Manually invoke tests

Formatting and linting

Per-language tool installation

Build docs developers (and LLMs) love

API Reference

FFI & Bindings

​General requirements

​Pre-commit hooks

​Platforms

​Prerequisites

​Build

​Test

​Prerequisites

​Build

​Test

​Prerequisites

​Build

​Test

​Prerequisites

​Build

​XCFramework

​Test

​Build

​Test

​Feature flags

​Running specific tests

​Keystore WASM tests

​Interop testing

​End-to-end identity (E2EI) testing

​Prepare the container runtime

​Choose the OIDC identity provider

​Run all E2EI tests

​Run specific E2EI tests

​Manually invoke tests

​Formatting and linting

​Per-language tool installation

Build docs developers (and LLMs) love

General requirements

Pre-commit hooks

Platforms

Prerequisites

Build

Test

Prerequisites

Build

Test

Prerequisites

Build

Test

Prerequisites

Build

XCFramework

Test

Build

Test

Feature flags

Running specific tests

Keystore WASM tests

Interop testing

End-to-end identity (E2EI) testing

Prepare the container runtime

Choose the OIDC identity provider

Run all E2EI tests

Run specific E2EI tests

Manually invoke tests

Formatting and linting

Per-language tool installation