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
//! The versioned at-rest envelope for stored master-seed material.
//!
//! # Why an envelope exists at all
//!
//! Two DIG generations store **32 bytes** under the same account path, and the
//! bytes are byte-for-byte indistinguishable:
//!
//! | generation | the 32 bytes are | fed to `SecretKey::from_seed` as |
//! |---|---|---|
//! | legacy (≤ dig-session 0.4) | a raw CSPRNG master seed | themselves |
//! | current | BIP-39 **entropy** | `mnemonic.to_seed("")` (64 bytes) |
//!
//! Reinterpreting one as the other does not fail — it silently derives a
//! *different but perfectly plausible* wallet. A user would see an empty
//! account with no error. So the stored blob must **declare** which it is, and
//! a legacy declaration must **fail closed** (see [`Kind`]).
//!
//! # Why `dig_keystore::opaque` rather than a new `KeyScheme`
//!
//! A [`dig_keystore::KeyScheme`] pins a fixed `SECRET_LEN`, so a
//! version-tagged payload does not fit one, and `dig_keystore::format`'s
//! magic allow-list is closed — a scheme defined outside dig-keystore could
//! not be decoded. [`dig_keystore::opaque`] is the sanctioned
//! arbitrary-length door into the *same* audited container (Argon2id +
//! AES-256-GCM + CRC-32, magic `DIGOP1`), so this module gets a versioned
//! payload without changing a foundation crate.
//!
//! # Wire layout of the sealed plaintext
//!
//! ```text
//! byte 0 1 2 .. 34
//! ┌────────┬────────┬──────────────────┐
//! │version │ kind │ 32 secret bytes │
//! └────────┴────────┴──────────────────┘
//! ```
//!
//! Additive-only, per §5.1: a future kind (say a 64-byte seed imported from
//! elsewhere) takes a new [`Kind`] discriminant; existing kinds keep their
//! meaning forever.
use ;
use Zeroizing;
use crateENTROPY_LEN;
use crate::;
/// Current envelope version. Bumped only for a layout change, never for a new
/// [`Kind`].
const VERSION_V1: u8 = 0x01;
/// Total sealed-plaintext length: `version || kind || entropy`.
const ENVELOPE_LEN: usize = 2 + ENTROPY_LEN;
/// What the 32 stored bytes MEAN.
///
/// The discriminant is the whole point of the envelope: the bytes alone cannot
/// tell you, and guessing wrong derives the wrong wallet in silence.
/// Seal `entropy` into a versioned envelope and establish it at `path`.
///
/// This is an *establish*, never an *update*: an existing blob at `path` yields
/// [`KeystoreError::AlreadyExists`] and is left byte-for-byte intact, matching
/// `dig_keystore::Keystore::create`.
///
/// # Why `write_new` and not `exists` then `write`
///
/// The two-call form is not one step. A second enrolment beginning inside that
/// window observes an absence, seals, and — because `write` replaces — destroys
/// the established root rather than landing beside it. The caller who was told
/// "enrolled" is then holding a recovery phrase that opens nothing, and for an
/// account root there is by construction no other copy.
///
/// [`KeychainBackend::write_new`] makes the backend the single authority on
/// whether the key was already there. On a backend reporting
/// [`Exclusivity::Atomic`](dig_keystore::Exclusivity::Atomic) — `FileBackend`
/// and `MemoryBackend` — that authority is indivisible and the loss is
/// unreachable. `OsKeychainBackend` reports
/// [`BestEffort`](dig_keystore::Exclusivity::BestEffort), because its
/// credential store offers no create-if-absent primitive; a caller minting
/// concurrently against it must still serialise the mint itself.
///
/// One visible consequence: a colliding enrolment now pays the Argon2id
/// derivation before it is refused, since the collision is detected by the
/// write rather than by a pre-check. That is the cost of having one authority
/// instead of two readings, and it is paid only on the failing path.
pub
/// Read, decrypt and validate the envelope at `path`, returning the BIP-39
/// entropy it declares.
///
/// # Errors
///
/// - [`SessionError::LegacySeedFormat`] if the blob is a pre-envelope raw-seed
/// keystore file. **The bytes are never reinterpreted as entropy** — the
/// caller is told to re-enrol from a phrase instead.
/// - [`SessionError::UnsupportedEnvelopeVersion`] /
/// [`SessionError::UnsupportedSeedKind`] for a blob written by a newer build.
/// - [`SessionError::Keystore`] for a missing file, wrong password, tampered
/// ciphertext, or a foreign container.
pub