AKD (Auditable Key Directory)

The repository is organized into several key packages:

The WhatsApp Key Transparency Auditor is a tool for verifying WhatsApp key transparency audit proofs. It fetches published proofs from WhatsApp's CloudFront storage and uses the akd library to cryptographically verify the append-only proofs for each epoch.

By default, the auditor targets the v2 log (the current, actively published log). To audit the legacy v1 log, you must provide the --log v1 flag.

# Audit the latest epoch (v2 log)
cargo run -p examples --release -- whatsapp-kt-auditor -l

# Audit a specific epoch (v2 log)
cargo run -p examples --release -- whatsapp-kt-auditor -e 722610

# Audit the latest epoch in the legacy log (v1)
cargo run -p examples --release -- whatsapp-kt-auditor --log v1 -l

To create a lightweight WASM library for client-side proof verification, target the akd_core crate instead of the full akd crate. Because akd_core has fewer dependencies, the resulting WASM binary will be significantly smaller.

Example bindings for a client verifying server-generated proofs can be found in the wasm_client/ sub-directory.

The akd library provides a stateless API for an auditable key directory (also known as a verifiable registry or authenticated dictionary).

Because the API is stateless, consumers of the library are responsible for providing their own storage solution for the directory entries.

Key components include:

• akd: The main implementation intended for service providers managing an underlying directory.
• akd_core: A minimal library containing the core operations of the AKD protocol.

Integration tests in AKD are located in the integration_tests folder and run end-to-end tests against real storage implementations.

• Structure: They use the #[tokio::test] attribute and follow a common structure defined by directory_test_suite in integration_tests/src/test_util.rs. This utility requires a database, a number of users, and a VRF signing function.
• Adding a new data-layer: To add a new storage implementation to the integration suite, add it as a dev-dependency in the akd_integration_tests crate, create a new <storage>_tests.rs file, and reference it in integration_tests/src/lib.rs.

The poc application is a command-line REPL used to interact directly with an AKD instance in various configurations. It is useful for manual verification of the system.

Common Flags and Subcommands:

• -d, --debug: Activate debugging mode.
• --memory: Use the memory-based database implementation.
• -l, --log_level <LEVEL>: Adjust console log level (Default: Info. Options: Error, Warn, Info, Debug, Trace).
• -m, --multirow_size <SIZE>: MySQL multi-row insert size (Default: 100).
• bench-db-insert: Benchmark database insertion.
• bench-lookup: Benchmark lookup API.
• bench-publish: Benchmark publish API.
• drop: Drop existing database tables.
• flush: Flush data from database tables.

# Example: Run the POC app with help
cargo run -- --help

You can run tests using standard Cargo commands from the root of the repository.

• Run all tests: cargo test (runs all tests across all crates with default features).
• Run tests for a specific crate: cargo test --package akd (useful to isolate tests, especially since some integration tests require Docker).
• Run tests with specific features: To test the akd crate without the VRF (Verifiable Random Function) implementation, use:

  cargo test --package akd --no-default-features --features public_tests

# Run all tests
cargo test

# Run tests for the akd package only
cargo test --package akd

# Run akd tests without default features (e.g., disabling vrf)
cargo test --package akd --no-default-features --features public_tests

You can run the auditor using several modes depending on whether you want to verify the most recent state or a specific point in time.

Audit the latest epoch

Use the -l flag to audit the most recent epoch available in the log.

Audit a specific epoch

Use the -e <epoch_number> flag to audit a specific epoch.

Interactive mode

Use the -i flag to load all available epochs and select which one to audit via an interactive prompt.

# Audit latest
cargo run -p examples --release -- whatsapp-kt-auditor -l

# Audit specific epoch
cargo run -p examples --release -- whatsapp-kt-auditor -e 722610

# Interactive mode
cargo run -p examples --release -- whatsapp-kt-auditor -i

To use the akd library in your Rust project, add it to your Cargo.toml dependencies. Ensure your environment meets the minimum supported Rust version requirement.

akd = "0.13.0"

AKD uses standard Rust testing practices. When writing unit tests, follow these guidelines:

1. Async Tests: If your test requires calling asynchronous code, use the #[tokio::test] attribute instead of the standard #[test].
2. Organization: Use the #[cfg(test)] attribute on test or tests sub-modules to ensure test code is only included during test compilation.
3. Logging: To enable log messages when tests fail, use a global startup constructor with the ctor crate. This ensures your crate benefits from centralized log management.

Example of async vs sync tests:

#[test]
fn my_test() {
  panic!("boom");
}

#[tokio::test]
async fn my_async_test() {
  panic!("async boom!");
}

#[cfg(test)]
#[ctor::ctor]
fn test_start() {
    init_logger(Level::Info);
}