origin_crypto_sdk/lib.rs
1// SPDX-License-Identifier: Apache-2.0
2#![cfg_attr(docsrs, warn(missing_docs))]
3
4//! Origin Crypto SDK — Post-quantum and classical cryptographic primitives.
5//!
6//! A standalone Rust SDK for signing, encryption, key derivation, and
7//! key encapsulation, with first-class support for both classical
8//! (Ed25519, X25519) and post-quantum (Falcon-1024, SLH-DSA, ML-DSA,
9//! NTRU Prime, Curve41417) primitives.
10//!
11//! # Quick start
12//!
13//! For most users, importing the [`prelude`] gives you everything:
14//!
15//! ```rust
16//! use origin_crypto_sdk::prelude::*;
17//!
18//! // Hybrid Ed25519 + Falcon-1024 signature (recommended default)
19//! let master_seed = [0x42u8; 32];
20//! let bundle = HybridSigningKeyBundle::from_seed(&master_seed, "my-app")
21//! .expect("valid seed");
22//! let msg = b"sign this";
23//! let sig = bundle.sign_hybrid(msg);
24//! // sig is an Ed25519 + Falcon-1024 hybrid signature
25//! ```
26//!
27//! For users who only need a single primitive:
28//!
29//! ```rust
30//! use origin_crypto_sdk::signing::classical::Ed25519Signer;
31//! use origin_crypto_sdk::signing::postquantum::Falcon1024Signer;
32//!
33//! // Just Ed25519
34//! let ed = Ed25519Signer::from_seed(&[1u8; 32]); // from_seed returns Self
35//! let sig = ed.sign(b"hello");
36//! assert!(ed.verify(b"hello", &sig));
37//!
38//! // Just Falcon-1024
39//! let falcon = Falcon1024Signer::from_seed(&[1u8; 32]).expect("valid seed");
40//! let sig = falcon.sign(b"hello").expect("Falcon sign");
41//! assert!(falcon.verify(b"hello", &sig));
42//! ```
43//!
44//! # Module organization
45//!
46//! - [`signing`] — Direct access to signing primitives, organized by family:
47//! - [`signing::classical`] — Ed25519 (no PQ dependencies)
48//! - [`signing::postquantum`] — Falcon-512/1024, SLH-DSA, ML-DSA
49//! - [`signing::hybrid`] — Recommended default. Ed25519 + PQ combined.
50//! - [`aead`] / [`chacha20_blake3`] — Symmetric encryption (committing & non-committing)
51//! - [`kdf`] — Key derivation (Argon2id, HKDF-SHA3-256)
52//! - [`pqc`] — Raw post-quantum primitives (advanced use)
53//! - [`ec_schnorr`] — secp256k1 Schnorr signatures (native, no external deps)
54//! - [`prelude`] — One-line import for common types
55//!
56//! # Security defaults
57//!
58//! - For **signatures**: use the hybrid (Ed25519 + PQ) — see [`signing::hybrid`].
59//! Both must verify, so a vulnerability in one primitive does not break security.
60//! - For **encryption**: prefer [`chacha20_blake3`] (committing AEAD).
61//! Avoid XChaCha20-Poly1305 unless you specifically need the smaller tag
62//! and accept the partitioning-oracle risk.
63//! - For **key derivation**: use Argon2id (memory-hard) for password-based KDF,
64//! HKDF-SHA3-256 for HKDF-style derivation.
65//!
66//! # Cargo features
67//!
68//! | Feature | Enables | Default |
69//! |-----------|----------------------------------------|---------|
70//! | `parallel` | Rayon-based parallel processing | **yes** |
71//! | `slh-dsa` | SLH-DSA / SPHINCS+ signatures (FIPS 205) | no |
72//! | `ml-dsa` | ML-DSA / Dilithium signatures (FIPS 204) | no |
73//! | `pqc-simd` | SIMD acceleration for NTRU Prime | no |
74//!
75//! Low-level PQC primitives are always available through their modules
76//! (`pqc::falcon1024`, `pqc::ed448`, etc.) — the features only gate the
77//! optional FIPS schemes that pull in extra dependencies.
78
79//! # Threat modeling for application authors
80//!
81//! For applications that wrap this SDK and serve users facing legal
82//! compulsion or physical coercion (journalists, dissidents, civil-society
83//! organizers), see the application-level guidance in
84//! <https://github.com/KidIkaros/OriginSDK/blob/HEAD/docs/duress-pattern.md>.
85//! **The SDK deliberately ships no duress or self-destruct primitive**;
86//! applications compose existing primitives (`create_blob`, `recover_seed`,
87//! `SeedHandle::with_tier`, `MemoryTier::Standard`/`Sovereign`) following
88//! the patterns documented there.
89//!
90//! See also `SECURITY.md` for the implementation source table.
91
92#![doc(html_root_url = "https://docs.rs/origin-crypto-sdk/0.4.0")]
93#![allow(clippy::result_large_err)]
94
95// ──────────────────────────────────────────────────────────────────────
96// Public modules (matching the README map exactly)
97// ──────────────────────────────────────────────────────────────────────
98
99pub mod error;
100/// Error types and `Result` alias.
101pub mod types;
102pub use error::{CryptoError, Result};
103
104/// Test utilities for downstream users.
105///
106/// **Feature-gated** — enable with `features = ["test-utils"]`.
107///
108/// Provides deterministic seeds, keys, nonces, and byte generators so
109/// users can write tests against the SDK without hitting real randomness.
110///
111/// # Example
112///
113/// ```ignore
114/// use origin_crypto_sdk::test_utils::deterministic_seed;
115/// let seed = deterministic_seed(42);
116/// ```
117#[cfg(feature = "test-utils")]
118pub mod test_utils;
119
120/// Prelude — re-exports common types for `use origin_crypto_sdk::prelude::*`.
121pub mod prelude;
122
123// ── Symmetric encryption ──
124pub mod aead;
125pub mod chacha20_blake3;
126
127// ── Hashing & KDF ──
128pub mod kdf;
129
130// ── Signatures ──
131pub mod ec_schnorr;
132pub mod pqc;
133/// Signing primitives: classical, post-quantum, and hybrid.
134///
135/// **Recommended**: use [`signing::hybrid::HybridSigningKeyBundle`] for
136/// new applications. It pairs Ed25519 with a post-quantum primitive so
137/// the signature remains unforgeable even if one primitive is broken.
138pub mod signing;
139
140// ── Randomness & DRBG ──
141pub mod drbg;
142
143// ── Recovery phrases ──
144///
145/// BIP-39-shaped Unicode recovery phrases. NOT BIP-39-compatible —
146/// uses a curated Unicode codepoint wordlist and SHA-3-256 (not
147/// SHA-256). For interop with other wallets, use the `bip39` crate.
148pub mod recovery;
149
150// ── Utility modules (hidden from docs) ──
151/// Entropy analysis — internal utility.
152#[doc(hidden)]
153pub mod entropy;
154
155/// Seed handling with TTL and memory security.
156pub mod seed;
157
158/// Merkle Mountain Range — internal utility.
159#[doc(hidden)]
160pub mod mmr;
161
162/// Stealth address primitives (KDF + PoW).
163pub mod stealth;
164
165/// Error correction codes — internal utility.
166#[doc(hidden)]
167pub mod error_correction;
168
169/// Low-level cryptographic primitives (hashes, ciphers, etc.).
170///
171/// **Internal use only.** Application code should use the higher-level
172/// modules ([`chacha20_blake3`], [`kdf`], etc.) instead.
173#[doc(hidden)]
174pub mod primitives;
175
176/// SipHash keyed hash — internal utility.
177#[doc(hidden)]
178pub mod siphash;
179
180/// Compression utility — internal.
181#[doc(hidden)]
182pub mod compression;
183
184/// Blob storage — internal utility.
185#[doc(hidden)]
186pub mod blob;
187
188// ──────────────────────────────────────────────────────────────────────
189// Internal modules (not part of public API; use at your own risk)
190// ──────────────────────────────────────────────────────────────────────
191#[doc(hidden)]
192pub mod internal;
193
194// ──────────────────────────────────────────────────────────────────────
195// Re-exports at crate root for convenience
196// ──────────────────────────────────────────────────────────────────────
197
198// Errors
199pub use error::{CryptoError as Error, Result as StdResult};
200
201// Encryption
202pub use aead::XChaCha20Poly1305;
203
204// KDF
205pub use kdf::hkdf::{derive_subkeys, hkdf_sha3_256};
206pub use kdf::Argon2id;
207
208// MAC
209pub use kdf::mac::hmac_sha3_256;
210
211// DRBG
212pub use drbg::ChaCha20Drbg;
213
214// Seed handling
215pub use seed::{derive_child_seed, derive_signing_keys, derive_verifying_keys, SeedHandle};
216
217// Hybrid bundle (canonical PQ-hybrid signing)
218pub use signing::hybrid::falcon1024_keygen;
219pub use signing::hybrid::HybridSigningKeyBundle;
220pub use signing::hybrid::{skein1024, skein512};
221
222// PQC direct access — use `pqc::{falcon1024, falcon512, ed448, ...}::module` for raw types.
223// Re-exports at crate root are intentionally omitted to keep the surface clean.
224// Advanced users access via `origin_crypto_sdk::pqc::falcon1024::FalconPrivateKey` etc.
225
226// Ed448 — RFC 8032 signature scheme on the 448-bit Goldilocks curve.
227// Exposed at `origin_crypto_sdk::pqc::ed448`.
228// Ed41417 — Daniel J. Bernstein's signature scheme on curve41417.
229// pub use pqc::curve41417::ed41417 as ed41417_raw; // intentionally not re-exported
230
231// SLH-DSA direct access (feature-gated)
232#[cfg(feature = "slh-dsa")]
233pub use pqc::slhdsa::{
234 sign as slhdsa_sign, verify as slhdsa_verify, SlhDsaPrivateKey, SlhDsaPublicKey,
235};
236
237// ML-DSA direct access (feature-gated)
238#[cfg(feature = "ml-dsa")]
239pub use pqc::mldsa::{MldsaPrivateKey, MldsaPublicKey};