kdk_entropy/
lib.rs

1// SPDX-License-Identifier: MIT
2
3//! Origin-tagged entropy primitives for KDK. Every entropy buffer
4//! carries a phantom marker that records *where the bytes came from*.
5//!
6//! Distinct sources are distinct types at compile time — `DiceEntropy<6, 16>`
7//! cannot be handed to a function expecting `DiceEntropy<20, 16>`.
8//!
9//! # Security
10//!
11//! Entropy buffers wrap [`kdk_zeroize::SensitiveBytes`]. Anything that crate
12//! guarantees, this one inherits.
13
14#![no_std]
15#![doc(html_logo_url = "https://qlrd.github.io/kdk/logo.png")]
16
17use kdk_zeroize::SensitiveBytes;
18
19/// Origin marker for coin-flip entropy. A coin always has 2 sides.
20pub enum Coin {}
21
22/// Origin arker for dice entropy. `FACES` is the die geometry — e.g.
23/// `Dice<6>` for a d6, `Dice<20>` for a d20. Distinct values yield
24/// distinct types at compile time.
25pub enum Dice<const FACES: u8> {}
26
27/// Origin marker for card-deck entropy. `CARDS` is the deck size; the
28/// entropy a full shuffle delivers is `log₂(CARDS!)` bits.
29///
30/// - `Deck<32>` — Skat. ~118 bits, **too small for BIP39**.
31/// - `Deck<40>` — Spanish baraja, stripped. ~159 bits, 12-word only.
32/// - `Deck<48>` — Pinochle / Spanish baraja (full). ~202 bits, 12-word only.
33/// - `Deck<52>` — standard poker / playing cards. ~226 bits, 12-word only;
34///   **never** use for 24-word mnemonics.
35/// - `Deck<58>` — smallest deck that clears 256 bits (~260). First size
36///   that supports 24-word mnemonics.
37/// - `Deck<78>` — Tarot. ~380 bits, 12- or 24-word.
38/// - `Deck<108>` — UNO (pre-2018). ~575 bits, 12- or 24-word.
39/// - `Deck<112>` — UNO (2018+). ~599 bits, 12- or 24-word.
40///
41/// Greater the deck, fewer the draws, but the harder the UX.
42pub enum Deck<const CARDS: u8> {}
43
44/// Coin-flip entropy. `N` is the buffer length in bytes.
45pub type CoinEntropy<const N: usize> = SensitiveBytes<N, Coin>;
46
47/// Dice-origin entropy. `FACES` is the die geometry, `N` the buffer length in bytes.
48pub type DiceEntropy<const FACES: u8, const N: usize> = SensitiveBytes<N, Dice<FACES>>;
49
50/// Deck-origin entropy. `CARDS` is the card set game, `N` the buffer length in bytes.
51pub type DeckEntropy<const CARDS: u8, const N: usize> = SensitiveBytes<N, Deck<CARDS>>;
52
53mod coin;
54mod deck;
55mod dice;
56mod error;
57mod utils;
58
59pub use coin::{coin_to_entropy, max_flips, min_flips};
60pub use deck::{deck_to_entropy, max_draws, min_draws};
61pub use dice::{dice_to_entropy, max_rolls, min_rolls};
62pub use error::EntropyError;
kdk_entropy/lib.rs

kdk_entropy/
lib.rs
