derec_library/lib.rs
1// SPDX-License-Identifier: Apache-2.0
2// Copyright (c) 2026 DeRec Alliance. All rights reserved.
3
4//! # DeRec Library
5//!
6//! This crate provides an implementation of the **DeRec protocol**, a decentralized
7//! secret recovery mechanism that protects sensitive data by distributing shares
8//! of the secret among a set of Helpers.
9//!
10//! Instead of relying on a single backup location, DeRec uses **threshold secret
11//! sharing** so that a secret can be reconstructed only when a sufficient number
12//! of Helpers collaborate.
13//!
14//! ## Protocol flows
15//!
16//! The library implements the core protocol flows defined by DeRec:
17//!
18//! - [`primitives::pairing`] — establishes a secure communication channel
19//! between an Owner and a Helper
20//! - [`primitives::sharing`] — generates and distributes secret shares to
21//! Helpers
22//! - [`primitives::verification`] — periodically checks that Helpers are
23//! still storing the correct share
24//! - [`primitives::recovery`] — reconstructs the secret using shares
25//! retrieved from Helpers
26//!
27//! These flows correspond to the lifecycle of a protected secret:
28//!
29//! ```text
30//! Pairing → Sharing → Verification (periodic) → Recovery (if needed)
31//! ```
32//!
33//! ## Design
34//!
35//! The library provides a **high-level API** for implementing DeRec-compatible
36//! applications. Each flow is implemented as a separate module exposing the
37//! functions required to produce and process protocol messages.
38//!
39//! Protocol messages themselves are defined using **protobuf** and are exposed
40//! through the [`derec_proto`] crate. Most applications should interact with
41//! the higher-level APIs instead of manipulating protobuf messages directly.
42//!
43//! ## Error handling
44//!
45//! All public APIs return [`Result<T>`], which wraps the crate-wide [`Error`] type.
46//! This type aggregates errors originating from the individual protocol flows
47//! while preserving their specific error semantics.
48//!
49//! ## Target environments
50//!
51//! The library is designed to work in both:
52//!
53//! - native Rust environments
54//! - WebAssembly environments (via bindings exposed by individual modules)
55//!
56//! WebAssembly bindings are primarily intended for integration with TypeScript
57//! applications.
58
59pub mod derec_message;
60pub mod primitives;
61pub mod protocol;
62pub mod protocol_version;
63pub mod transport;
64pub mod types;
65mod utils;
66
67mod error;
68pub use error::Error;
69
70/// Generate a fresh **replica identity** using the OS CSPRNG.
71///
72/// Replica identities are per-device `u64` values that uniquely identify each
73/// participant in a replica group. The orchestrator auto-injects this id
74/// under the reserved `derec.replica_id` key in `CommunicationInfo` during
75/// replica-mode pairings (see
76/// [`protocol::DeRecProtocolBuilder::with_replica_id`]).
77///
78/// Persistence contract: the caller **must** persist the returned value once
79/// per device and pass the same id on every subsequent
80/// [`protocol::DeRecProtocolBuilder::with_replica_id`] call. A replica that
81/// changes its id between restarts cannot be re-identified by peers and will
82/// fail re-pairing / secret sync.
83///
84/// Apps that do not use replica flows do not need to call this.
85pub fn generate_replica_id() -> u64 {
86 rand::random()
87}
88
89#[cfg(all(not(target_arch = "wasm32"), feature = "ffi"))]
90mod ffi;
91
92#[cfg(target_arch = "wasm32")]
93pub mod wasm;
94
95pub type Result<T> = std::result::Result<T, Error>;