1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
//! The master-SEED unlock path: an unlocked handle over the raw master HD seed.
//!
//! # Why this exists (the impedance mismatch it closes)
//!
//! The 0.2.0 identity path ([`crate::UnlockedIdentity`]) unlocks to the *derived
//! identity scalar* only — it stores `derive_identity_sk(master).to_bytes()` and
//! can never reconstruct the master seed. But `dig-wallet-backend`'s
//! `MasterKey::from_seed_bytes` (the master-HD model, dig_ecosystem #997) needs
//! the **master seed** to derive every profile's wallet keys. The identity
//! scalar cannot reconstruct the seed, so a consumer that wants BOTH the
//! dig-identity key AND a wallet `MasterKey` must persist the seed itself.
//!
//! [`UnlockedMasterSeed`] is that path: it persists the raw 32-byte master seed
//! (encrypted at rest) and, on unlock, exposes ALL of:
//!
//! - [`master_seed`](UnlockedMasterSeed::master_seed) — the raw seed bytes as a
//! primitive `Zeroizing<[u8; SEED_LEN]>`, ready to feed to wallet-backend's
//! `MasterKey::from_seed_bytes` (see the layering note below);
//! - [`sign`](UnlockedMasterSeed::sign) /
//! [`public_key`](UnlockedMasterSeed::public_key) — the dig-identity key
//! derived from the seed at the canonical path, byte-identical to the 0.2.0
//! identity path for the same seed;
//! - [`derive_symmetric_key`](UnlockedMasterSeed::derive_symmetric_key) — the
//! per-profile DEK, **byte-identical** to
//! [`crate::UnlockedIdentity::derive_symmetric_key`] (§5.1 at-rest back-compat).
//!
//! # Layering (@10 reference-DOWN-only, HARD RULE)
//!
//! dig-session is a `10-primitives` crate; `MasterKey` is a `20-domain`
//! (`dig-wallet-backend`) type. This module therefore **must not** depend on
//! dig-wallet-backend or return a wallet-backend type — that would be an illegal
//! upward `@10 -> @20` edge. The seed is exposed as PRIMITIVE bytes only; the
//! app-tier consumer (dig-app) constructs the `MasterKey` itself via
//! `MasterKey::from_seed_bytes(handle.master_seed())`.
//!
//! # Why the seed round-trips to the SAME master key everywhere
//!
//! Both dig-identity's `master_secret_key_from_seed(seed)` and wallet-backend's
//! `MasterKey::from_seed_bytes(seed)` reduce to `chia_bls::SecretKey::from_seed(seed)`
//! (EIP-2333 KeyGen). Handing the identical seed bytes to both therefore yields
//! the identical master key — which is exactly why the seed (not the derived
//! scalar) is the value that must be persisted and exposed.
//!
//! # Storage scheme
//!
//! The seed is stored under [`dig_keystore::BlsSigning`] purely as a 32-byte
//! encrypted-at-rest byte vault: that scheme persists exactly its 32 secret
//! bytes verbatim and returns them via `expose_secret()`. This path never uses
//! the `BlsSigning` handle's own `sign`/`public_key` (which would derive the
//! *master* key via `from_seed`); the dig-identity key is derived in this crate
//! instead. The `L1WalletBls` scheme is unsuitable here because it stores an
//! already-derived *scalar* (`from_bytes`), not a *seed*.
use Arc;
use SYMMETRIC_KEY_LEN;
use ;
use ;
use Zeroizing;
use cratederive_symmetric_key_from_scalar;
/// The number of bytes in a DIG master HD seed.
///
/// Fixed at 32 to match dig-app's master-seed model (`SCALAR_LEN`, a 32-byte
/// entropy seed drawn from the CSPRNG) and the `BlsSigning` storage scheme's
/// `SECRET_LEN`. The seed is fed to `chia_bls::SecretKey::from_seed`, which
/// accepts any length ≥ 32; 32 bytes is the DIG canonical size.
pub const SEED_LEN: usize = 32;
/// The number of bytes in a compressed BLS12-381 **G1** identity public key.
pub const IDENTITY_PUBLIC_KEY_LEN: usize = 48;
/// The number of bytes in a BLS12-381 **G2** AugScheme signature.
pub const IDENTITY_SIGNATURE_LEN: usize = 96;
/// A standalone identity-signing primitive: a plain callable mapping a message to
/// a 96-byte G2 signature, carrying no dig-session or dig-identity type.
///
/// This is the bare shape [`UnlockedMasterSeed::signing_fn`] hands a downstream so
/// it can sign while staying identity-agnostic (dig_ecosystem #908). It mirrors
/// [`crate::SigningFn`] but is expressed over raw byte arrays because the
/// master-seed path derives the identity key itself rather than exposing a
/// scheme-parameterized `SignerHandle`.
pub type IdentitySigningFn = ;
/// A live, in-memory master HD seed whose bytes have been decrypted and are
/// ready to (a) reconstruct the wallet `MasterKey` app-side and (b) derive the
/// dig-identity signing key + profile DEK in-crate.
///
/// Obtained from [`crate::Session::enroll_master_seed`] or
/// [`crate::Session::unlock_master_seed`]. The seed lives inside the wrapped
/// [`SignerHandle`], which stores it in a `Zeroizing` buffer and wipes it when
/// this value is dropped. The type deliberately does not implement `Clone` and
/// its `Debug` impl redacts the secret.
///
/// # Boundaries
///
/// An `UnlockedMasterSeed` must never cross an IPC boundary: it holds the root
/// wallet seed and belongs solely to the user-app process that owns the identity
/// (dig_ecosystem #908). The seed stays user-side; this crate crosses no
/// engine/IPC boundary.
/// Redacting `Debug`: shows the type name only, never the seed.