auths-keri

KERI CESR translation layer for Auths. Converts between Auths' internal JSON event representation and spec-compliant CESR streams (Trust over IP KERI v0.9).

Why a separate crate?

The KERI specification is still a draft under active revision at Trust over IP. The core Auths crates (auths-id, auths-verifier, auths-core) use KERI-inspired concepts (key event logs, pre-rotation, SAIDs) but with a Git-native JSON storage format that prioritizes developer ergonomics over wire-level spec compliance.

This crate exists to isolate CESR-specific logic and dependencies (notably cesride) from the core stack:

• Spec volatility: KERI field names, counter codes, and serialization rules may change before the spec is finalized. Changes here don't ripple through the identity or verification layers.
• Dependency isolation: cesride (the Rust CESR code table implementation) is a substantial dependency. Crates like auths-verifier are designed for minimal-dependency embedding (FFI, WASM) and should not pull in CESR code tables.
• Opt-in interoperability: Most Auths users never need CESR. The translation layer is only needed when exchanging key event logs with external KERI implementations (keripy, keriox, etc.).

The core codebase remains untouched. Git-native JSON storage remains the primary format. This crate wraps existing types for export/import without replacing them.

How it fits in the architecture

auths-cli / auths-sdk (unchanged)
  |
  +-- auths-id (unchanged -- internal JSON events, Git storage)
  |     |
  |     +-- KelPort trait (returns Vec<Event>)
  |
  +-- auths-keri (THIS CRATE -- opt-in translation layer)
        |
        +-- codec.rs     -- CesrCodec trait + CesrV1Codec backed by cesride
        +-- said.rs      -- Spec-compliant SAID with # placeholder
        +-- version.rs   -- Dynamic KERI10JSON{size}_ version strings
        +-- event.rs     -- Detached-signature event serialization
        +-- stream.rs    -- Full CESR stream assembly (events + attachments)
        +-- roundtrip.rs -- Export auths KEL -> CESR, import CESR -> auths types

Dependency direction: auths-keri depends on auths-verifier and auths-crypto. It never flows the other way. The core crates have no knowledge of this crate's existence.

Usage

Export a key event log as CESR

use auths_keri::{CesrV1Codec, export_kel_as_cesr};

let codec = CesrV1Codec::new();
let stream = export_kel_as_cesr(&codec, &events)?;
std::fs::write("identity.cesr", &stream.bytes)?;

Import a CESR stream back to Auths events

use auths_keri::{CesrV1Codec, import_cesr_to_events};

let codec = CesrV1Codec::new();
let cesr_bytes = std::fs::read("identity.cesr")?;
let events = import_cesr_to_events(&codec, &cesr_bytes)?;

Encode/decode individual CESR primitives

use auths_keri::{CesrV1Codec, CesrCodec, KeyType};

let codec = CesrV1Codec::new();
let qualified = codec.encode_pubkey(&key_bytes, KeyType::Ed25519)?;
// "D..." (44 chars)

What this crate does differently from the internal format

Future directions

Once the KERI specification exits draft status and stabilizes, several extensions become viable:

• Binary-domain CESR: Currently text-domain only (qb64). Binary domain (qb2) is more compact for network transport and could be added as an alternative stream format.
• CBOR/MessagePack serialization: KERI supports multiple serialization formats beyond JSON. The version string protocol (KERI10CBOR, KERI10MGPK) already accommodates this.
• Delegation events (dip/drt): Delegated inception and rotation for hierarchical identity structures.
• Multi-sig support: Weighted threshold signatures (kt > 1) with multiple indexed signatures per event.
• OOBI generation: Out-of-Band Introductions for discovering and bootstrapping trust with other KERI identities.
• TEL/ACDC integration: Transaction Event Logs and Authentic Chained Data Containers for verifiable credentials anchored to KERI identities.
• Cross-implementation validation: Automated test suite that validates output against keripy (Python reference implementation) and keriox (Rust alternative).
• Native CESR storage: If CESR stabilizes, a future option would be storing CESR streams directly in Git refs alongside (or instead of) JSON, reducing the translation overhead for interop-heavy deployments.