dig_session/lib.rs
1//! # dig-session
2//!
3//! The DIG **session / keystore layer**: a small, custody-safe facade that
4//! turns stored, encrypted key material into a live signer and injects a bare
5//! signing primitive into downstream consumers.
6//!
7//! It composes two lower-level crates and adds no cryptography of its own:
8//!
9//! - [`dig_keystore`] — encrypted, per-scheme secret-key storage
10//! (`Keystore::<K>::load -> unlock -> SignerHandle<K>`, AES-256-GCM + Argon2id).
11//! - [`dig_identity`] — the canonical DIG BLS identity derivation
12//! (`master_secret_key_from_seed` then `derive_identity_sk` at the hardened
13//! path `m/12381'/8444'/9'/0'`).
14//!
15//! ## What this crate deliberately does NOT do
16//!
17//! There is **no seal / decap** (recipient message encryption) here. That
18//! composition belongs to `dig-message` (the same 10-primitives level); adding
19//! it here would duplicate a cross-repo contract and invite byte-drift. This
20//! crate's first cut is strictly **unlock / sign / inject**.
21//!
22//! ## Enrollment stores the derived key with `L1WalletBls`, not `BlsSigning`
23//!
24//! The identity signing key is a key that dig-identity has *already derived*
25//! (via EIP-2333 hardened steps). To reconstruct it on unlock byte-identically,
26//! storage must use a scheme that round-trips raw secret-key bytes through
27//! `chia_bls::SecretKey::from_bytes` — that is [`L1WalletBls`].
28//!
29//! [`BlsSigning`] instead treats its stored 32 bytes as a *seed* and runs them
30//! through `chia_bls::SecretKey::from_seed` on every unlock. Storing an
31//! already-derived key under `BlsSigning` would therefore re-derive a
32//! *different* key (the documented dig_ecosystem #64 / #57 pitfall), and the
33//! resulting public key would not match the DID-anchored identity key. So the
34//! identity path uses `L1WalletBls`; a regression test asserts the unlocked
35//! public key equals `dig_identity::public_key_bytes(derive_identity_sk(master))`.
36//!
37//! [`Session::unlock`] stays generic over the scheme, so `BlsSigning` is still
38//! available for seed-derived validator keys.
39//!
40//! ## Example
41//!
42//! ```no_run
43//! use std::sync::Arc;
44//! use dig_session::{Session, FileBackend, BackendKey, Password};
45//!
46//! # fn main() -> dig_session::Result<()> {
47//! let backend = Arc::new(FileBackend::new("/var/lib/dig/keys"));
48//! let identity = Session::enroll_identity(
49//! backend,
50//! BackendKey::new("identity"),
51//! Password::from("correct horse battery staple"),
52//! b"BIP-39 seed bytes go here",
53//! )?;
54//!
55//! // Hand a downstream a bare signing primitive — it never sees a session type.
56//! let sign = identity.signing_fn();
57//! let _sig = sign(b"message");
58//! # Ok(())
59//! # }
60//! ```
61
62#![forbid(unsafe_code)]
63#![warn(missing_docs)]
64
65mod envelope;
66mod error;
67mod master_seed;
68mod session;
69mod unlocked;
70
71pub use error::{Result, SessionError};
72pub use master_seed::{
73 IdentitySigningFn, UnlockedMasterSeed, ENTROPY_LEN, IDENTITY_PUBLIC_KEY_LEN,
74 IDENTITY_SIGNATURE_LEN, MASTER_SEED_LEN, RECOVERY_PHRASE_WORDS,
75};
76pub use session::Session;
77pub use unlocked::{SigningFn, UnlockedIdentity};
78
79// Re-export the storage/scheme types a caller needs, so a consumer depends on
80// JUST dig-session rather than reaching into dig-keystore directly.
81pub use dig_keystore::bls::{PublicKey, SecretKey, Signature};
82pub use dig_keystore::scheme::{BlsSigning, KeyScheme, L1WalletBls};
83pub use dig_keystore::{BackendKey, FileBackend, KeychainBackend, Password};