dig-session 0.9.1

DIG session/keystore layer: unlock identity signing keys and inject signing primitives. Composes dig-keystore (encrypted key storage) + dig-identity (canonical BLS identity derivation) behind one curated, custody-safe facade.
Documentation
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
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
# dig-session — normative specification

`dig-session` is the DIG **session / keystore layer**. It composes
[`dig-keystore`] (encrypted secret-key storage) and [`dig-identity`] (canonical
BLS identity derivation) into one curated, custody-safe facade for turning
stored key material into a live signer and injecting a bare signing primitive
into downstream consumers. It performs **no cryptography of its own** — every
cryptographic operation is delegated to those two crates.

This document is normative: an independent reimplementation MUST satisfy every
MUST/MUST NOT below.

## 1. Scope

- **In scope:** unlock an existing key, enroll a new identity, sign, inject a
  signing primitive, and enroll/unlock a DIG account root (BIP-39 entropy) that
  exposes the expanded master HD seed as a primitive, the 24-word recovery
  phrase, and the seed-derived identity key and DEK.
- **Out of scope:** recipient message encryption (seal / decap). That
  composition lives in `dig-message` (same crate level). Implementations of
  `dig-session` MUST NOT add seal/decap; doing so would duplicate a cross-repo
  contract and invite byte-drift.

## 2. Dependencies and layering

- `dig-session` MUST depend only on crates at a strictly lower level:
  `dig-keystore`, `dig-identity`, and `dig-constants` (level 00 foundation), plus
  `chia-bls`, `bip39`, `zeroize`, `hkdf`, `sha2`, and `thiserror`. It MUST NOT depend on
  any same-level (10) or higher crate.
- **`dig-session` MUST NOT depend on `dig-wallet-backend` (a level-20 crate) and
  MUST NOT return a wallet-backend type (e.g. `MasterKey`).** That would be an
  illegal upward `@10 -> @20` edge (CI-lint-forbidden). The master-seed path
  therefore exposes the seed as PRIMITIVE bytes only; the app-tier consumer
  (dig-app) constructs `MasterKey::from_seed_bytes(handle.master_seed())` itself.
- Dependencies MUST be crates.io versions, never `git = …` deps.
- Required published minimums: `dig-keystore >= 0.8`, `dig-identity >= 0.6`,
  `dig-constants >= 0.10`.
- **`dig-keystore` MUST be taken with the `custody` and `hd-derivation` features.**
  From 0.8 that crate gates its user-key surface behind `custody` (`Keystore`,
  `SignerHandle`, `scheme::*`) and gates `SignerHandle::expose_secret` behind
  `hd-derivation`, so that the node can link `dig-keystore` without naming a
  user-key API (dig_ecosystem #908). `dig-session` IS the user-side facade and
  requires both: `custody` for the whole composed flow, and `hd-derivation`
  because `derive_symmetric_key` reaches the identity scalar that is the frozen
  DEK's IKM (§3.2). Consumers of `dig-session` inherit both transitively and
  MUST NOT be asked to enable them.
- **The `chia-bls` graph is intentionally split and MUST stay byte-mediated.**
  `dig-keystore` 0.8 is on `chia-bls` 0.26 while `dig-identity` 0.6 is on 0.36,
  so the two resolve as distinct, non-unifiable types in one build. Every value
  crossing between them MUST cross as canonical BYTES (`SecretKey::to_bytes`,
  `public_key_bytes`, a `[u8; 96]` signature) and MUST NOT cross as a `chia-bls`
  type. The re-exports in §3 (`PublicKey`, `SecretKey`, `Signature`) are
  `dig-keystore`'s 0.26 types; a caller mixing them with a `dig-identity` value
  MUST convert through bytes.

## 3. Public API surface

The crate exposes exactly the following curated facade (plus re-exports of the
storage/scheme types a caller needs, so a consumer depends on JUST
`dig-session`):

### 3.1 `Session`

A stateless namespace. All methods are associated functions.

- `Session::unlock::<K: KeyScheme>(backend, path, password) -> Result<UnlockedIdentity<K>>`
  - MUST load the keystore file at `path` via `dig_keystore::Keystore::<K>::load`
    and unlock it with `password` via `Keystore::unlock`, returning the
    resulting `SignerHandle<K>` wrapped in an `UnlockedIdentity<K>`.
  - MUST be generic over the scheme `K`. `L1WalletBls` is used for stored,
    already-derived keys (identity signing key, wallet keys); `BlsSigning` for
    seed-derived validator keys.
  - MUST surface a scheme mismatch, wrong password, missing file, or tampered
    ciphertext as `SessionError::Keystore`.

- `Session::enroll_identity(backend, path, password, seed) -> Result<UnlockedIdentity<L1WalletBls>>`
  - MUST reject empty `seed` with `SessionError::EmptySeed`.
  - MUST derive the identity signing key EXACTLY ONCE, as
    `derive_identity_sk(master_secret_key_from_seed(seed))` — i.e. the hardened
    dig-identity path `m/12381'/8444'/9'/0'`.
  - MUST persist the derived secret key's canonical bytes
    (`chia_bls::SecretKey::to_bytes`) under the **`L1WalletBls`** scheme via
    `dig_keystore::Keystore::create`, so a later `unlock` reconstructs the key
    byte-identically via `chia_bls::SecretKey::from_bytes`.
  - MUST NOT store the derived key under `BlsSigning`. `BlsSigning` treats its
    stored bytes as a *seed* and re-derives via `chia_bls::SecretKey::from_seed`
    on unlock, which would produce a DIFFERENT key (dig_ecosystem #64/#57) whose
    public key does not match the DID-anchored identity key.
  - The returned identity's public key MUST equal
    `dig_identity::public_key_bytes(derive_identity_sk(master_secret_key_from_seed(seed)))`.

- `Session::enroll_master_seed(backend, path, password, entropy: &[u8; ENTROPY_LEN]) -> Result<UnlockedMasterSeed>`
  - MUST treat `entropy` as **BIP-39 entropy**, never as an HD seed. Any
    `ENTROPY_LEN` CSPRNG bytes are valid entropy, so a caller MAY pass fresh
    randomness directly.
  - MUST persist the `ENTROPY_LEN` bytes inside the versioned seed envelope
    (§3.4), encrypted under `password`, and return the account unlocked.
  - MUST refuse to overwrite an existing blob at `path`, surfacing
    `SessionError::Keystore(KeystoreError::AlreadyExists)` and leaving the
    established blob byte-for-byte intact.
  - MUST establish the blob through `KeychainBackend::write_new`, so the
    backend is the sole authority on whether `path` was occupied. A check
    followed by a write does NOT satisfy this clause: an enrolment beginning
    between the two calls observes an absence and replaces the established
    root, destroying the only copy of a custody seed.
  - The refusal is therefore indivisible on a backend reporting
    `Exclusivity::Atomic` (`FileBackend`, `MemoryBackend`). On a backend
    reporting `Exclusivity::BestEffort` (`OsKeychainBackend`, whose credential
    store has no create-if-absent primitive) a residual race remains and the
    caller MUST serialise concurrent enrolments itself.

- `Session::enroll_from_recovery_phrase(backend, path, password, phrase: &str) -> Result<UnlockedMasterSeed>`
  - MUST parse `phrase` as a `RECOVERY_PHRASE_WORDS`-word **English** BIP-39
    mnemonic and enroll the entropy it encodes, so that restoring a phrase
    reproduces the identical account (same wallet addresses, same identity key,
    same per-profile DEKs).
  - MUST accept any capitalisation and any run of whitespace between words
    (including newlines), normalising before parsing. Rejecting a correct phrase
    over a capital letter is a usability trap, and lowercasing cannot change
    which English BIP-39 word a token is.
  - MUST reject an unknown word, a failed checksum, or a wrong word count with
    `SessionError::InvalidRecoveryPhrase`, whose message MUST NOT contain any
    word of the phrase.

- `Session::unlock_master_seed(backend, path, password) -> Result<UnlockedMasterSeed>`
  - MUST read the versioned envelope (§3.4) and return the account unlocked.
  - MUST reject a pre-envelope legacy blob with `SessionError::LegacySeedFormat`
    and MUST NOT reinterpret its bytes as BIP-39 entropy (§3.4).
  - MUST reject an unrecognised envelope version or kind with
    `SessionError::UnsupportedEnvelopeVersion` / `SessionError::UnsupportedSeedKind`.
  - MUST surface a missing blob, wrong password, or tampered ciphertext as
    `SessionError::Keystore`.

### 3.2 `UnlockedIdentity<K>`

A live, in-memory identity holding a decrypted `SignerHandle<K>`.

- `public_key(&self) -> &K::PublicKey` — the identity's public key.
- `sign(&self, msg: &[u8]) -> K::Signature` — sign a message.
- `signing_fn(&self) -> SigningFn<K>` — a standalone signing primitive owning
  its own zeroizing copy of the secret; MUST remain usable after the handle is
  dropped.
- `inject_into<T>(&self, consumer: impl FnOnce(SigningFn<K>) -> T) -> T` — hand a
  consumer ONLY a `SigningFn` primitive; the consumer's API MUST NOT mention any
  `dig-session` or `dig-identity` type. This is what keeps a downstream (e.g.
  `dig-wallet-backend`) identity-agnostic (dig_ecosystem #908).

- `derive_symmetric_key(&self, label: &[u8]) -> Zeroizing<[u8; 32]>` — derive a
  per-profile symmetric key (a data-encryption key, "DEK") bound to `label` from
  the unlocked identity. The DEK is returned; the identity scalar MUST NOT leave
  the facade (dig_ecosystem #908 — only the derived key by `label` is exposed).
  - **Construction (frozen, MUST be byte-identical).** The DEK MUST be
    `HKDF-SHA256(salt = "dig-app:dek-salt:v1", IKM = 0x02 || identity_scalar,
    info = label)` expanded to 32 bytes (RFC 5869; `hkdf` 0.12 + `sha2` 0.10):
    - hash: SHA-256;
    - IKM: the byte `0x02` followed by the 32-byte canonical identity scalar
      (`derive_identity_sk(master).to_bytes()`) — i.e. the versioned at-rest
      layout `SEALED_IDENTITY_VERSION || scalar`, NOT the bare scalar;
    - salt: the ASCII bytes `dig-app:dek-salt:v1`;
    - info: `label`, verbatim;
    - output length: 32 bytes.
  - **Source of truth: `dig-constants`.** The salt, IKM version byte, default
    label, and output length above are not local literals — they are the
    `dig-constants` crate's frozen "Profile DEK at-rest byte contract"
    (`DEK_SALT`, `IDENTITY_IKM_VERSION`, `PROFILE_DEK_LABEL`,
    `SYMMETRIC_KEY_LEN`), the single source both this crate and dig-app's
    `dig-app-core/src/keystore/secrets.rs` consume them from (dig_ecosystem
    §4.1/§5.1/NC-5). This crate depends on `dig-constants` from crates.io and
    imports the constants directly rather than redefining them.
  - **Byte-identity invariant (§5.1 at-rest back-compat).** With
    `label = dig_constants::PROFILE_DEK_LABEL` (`b"dig-app:profile-dek:v2"`)
    the result MUST be byte-identical to the DEK dig-app's
    `dig-app-core/src/keystore/secrets.rs` (`dek_password`,
    `seal_data`/`open_data`) already uses to seal every profile blob at rest.
    Any change to the hash, IKM (including the `0x02` version prefix), salt, info
    encoding, or output length would derive a different DEK and make already-sealed
    profile data permanently unreadable, and is therefore FORBIDDEN. Covered by a
    frozen golden vector (C-9, C-10).
  - The DEK and all intermediates MUST be wrapped in `Zeroizing` and wiped on drop.

### 3.3 `UnlockedMasterSeed`

A live, in-memory DIG account root: the decrypted BIP-39 entropy, exposing the
expanded master HD seed as a primitive, the recovery phrase, and the
seed-derived identity key and DEK. Obtained from
`Session::enroll_master_seed`, `Session::enroll_from_recovery_phrase` or
`Session::unlock_master_seed`. The entropy lives in a `Zeroizing` buffer and is
wiped on drop; the type MUST NOT implement `Clone` and its `Debug` impl MUST
redact the secret.

#### 3.3.0 The root is BIP-39 entropy; the seed is EXPANDED from it (normative)

A 24-word BIP-39 phrase carries an implicit promise that any conforming wallet
restores it. Standard Chia wallets (Sage, the reference client,
`chia-wallet-sdk`) honour it as

```text
phrase -> 32-byte entropy -> PBKDF2-HMAC-SHA512("mnemonic", 2048) -> 64-byte seed -> EIP-2333
```

- The stored secret MUST be the `ENTROPY_LEN`-byte BIP-39 **entropy**.
- Every derivation — identity, per-profile identity, per-profile DEK, and the
  seed handed to a wallet — MUST read the seed produced by expanding that
  entropy: `entropy -> mnemonic -> to_seed("")`. Implementations MUST NOT feed
  the entropy to `chia_bls::SecretKey::from_seed` directly; that skips PBKDF2
  and silently derives a different, plausible wallet, so a user restoring a DIG
  phrase in another wallet would see an empty account with no error at all
  (dig_ecosystem #1759).
- The BIP-39 passphrase MUST be the **empty string**, matching Chia. A non-empty
  passphrase forks the account from every standard client.
- Because one expanded seed feeds every derivation, no two derivations can
  disagree about the account root.

##### Legacy accounts EXIST, and adopting this version REQUIRES a re-enrolment path (normative)

Changing the root also changed, for a given 32 stored bytes, the identity public key and the
per-profile DEK. That is a §5.1-class change to a stored-secret derivation. It is sound for **one
specific reason, and it is not the absence of accounts**:

- **Legacy account blobs DO exist in the field.** The published `dig-session` 0.4 line auto-enrolled an
  account at first boot with no user action, so every installed consumer that has booted once holds a
  pre-envelope `DIGVK1` blob. This has been verified on a real host. Any statement that the exposed
  population is zero is FALSE and MUST NOT be relied on.
- **What is actually absent is any sealed ARTIFACT keyed by the old derivation** — no sealed profile
  blobs, no wallet store, no funded account (the money path is unmerged). So nothing that was
  *encrypted* under the old DEK becomes unreadable, and nothing on chain moves. That, and only that,
  is why the DEK golden vectors were re-pinned rather than migrated.
- A **further** change to any stored-secret derivation MUST ship a migration path, not a re-pin.

Consequently, a consumer adopting this version MUST implement a legacy-detection-and-re-enrolment
path. A legacy account is **WEDGED**: `unlock_master_seed` returns
[`SessionError::LegacySeedFormat`] and never a handle, and `enroll_master_seed` at the same key
returns `AlreadyExists` because enrolment refuses to overwrite a custody root, so there is no
in-crate route back. The consumer MUST:

1. detect `LegacySeedFormat` **specifically** — a catch-all log line is a defect, because it leaves
   the account permanently and silently without a signer;
2. **preserve** the existing blob rather than deleting it. It is password-sealed, its password may
   live in an OS credential store this crate cannot read, and a balance therefore cannot be ruled
   out — deleting it can destroy the only copy of a funded key;
3. surface the situation **in the UI**, stating that the account must be re-created and that the
   preserved file is the only copy of the old key;
4. re-enrol (at a fresh key, or after moving the old blob aside) and show the new recovery phrase.

Shipping this version without that path is a regression for every already-enrolled install.

- `ENTROPY_LEN: usize = 32` — the stored BIP-39 entropy length. 32 bytes is
  exactly the entropy of a 24-word English mnemonic, so entropy and phrase
  convert both ways losslessly.
- `MASTER_SEED_LEN: usize = 64` — the expanded seed length, fixed by BIP-39.
- `RECOVERY_PHRASE_WORDS: usize = 24`.
- `master_seed(&self) -> Zeroizing<[u8; MASTER_SEED_LEN]>` — the EXPANDED master
  HD seed, a PRIMITIVE. This is the value an app-tier consumer feeds to
  `MasterKey::from_seed_bytes(handle.master_seed().to_vec())`. It MUST be
  returned as a `Zeroizing` byte array, never a wallet-backend type (see §2
  layering).
- `recovery_phrase(&self) -> Zeroizing<String>` — the `RECOVERY_PHRASE_WORDS`
  words, lowercase and single-space separated. It MUST take `&self`: showing a
  user their phrase MUST NOT consume or invalidate the handle. The returned
  string MUST be `Zeroizing`, and implementations MUST NOT log it.
- `public_key(&self) -> [u8; 48]` — the 48-byte compressed BLS12-381 G1
  dig-identity key derived from the EXPANDED seed. It MUST equal
  `dig_identity::public_key_bytes(derive_identity_sk(master_secret_key_from_seed(master_seed)))`.
- `sign(&self, msg: &[u8]) -> [u8; 96]` — sign with the seed-derived identity key;
  the 96-byte G2 signature MUST verify under `public_key()`.
- `signing_fn(&self) -> Arc<dyn Fn(&[u8]) -> [u8; 96] + Send + Sync>` — a
  standalone signing primitive owning its own zeroizing copy of the root; MUST
  remain usable after the handle is dropped.
- `derive_symmetric_key(&self, label: &[u8]) -> Zeroizing<[u8; 32]>` — the
  per-profile DEK. The identity scalar MUST be derived from the EXPANDED seed and
  fed to the SAME frozen HKDF construction as `UnlockedIdentity::derive_symmetric_key`
  (§3.2), so all paths stay byte-compatible for one root.

#### 3.3.1 Per-profile methods (0.4.0, ADDITIVE)

The master-seed handle additionally exposes per-profile identity operations
derived from the SAME master seed at the hardened path
`m/12381'/8444'/9'/{profile_ix}'` via `dig_identity::derive_identity_sk_at`
(dig-identity 0.5.0). These are a pure additive generalization of the default
methods (§5.1): the default methods ARE profile 0.

- `profile_public_key(&self, profile_ix: u32) -> [u8; 48]` — the 48-byte
  compressed BLS12-381 G1 identity key for `profile_ix`. It MUST equal
  `dig_identity::public_key_bytes(derive_identity_sk_at(master_secret_key_from_seed(seed), profile_ix))`.
- `profile_sign(&self, profile_ix: u32, msg: &[u8]) -> [u8; 96]` — sign with
  `profile_ix`'s derived key; the signature MUST verify under
  `profile_public_key(profile_ix)`.
- `profile_derive_symmetric_key(&self, profile_ix: u32, label: &[u8]) -> Zeroizing<[u8; 32]>`
  — `profile_ix`'s per-profile DEK. The profile scalar is derived via
  `derive_identity_sk_at` and fed to the SAME frozen HKDF construction
  (`derive_symmetric_key_from_scalar`) — the HKDF is NOT duplicated.

**`profile_ix == 0` byte-identity invariant (MUST, §5.1).** Because
`derive_identity_sk_at(master, 0) == derive_identity_sk(master)`, for every seed,
message, and label:
`profile_public_key(0) == public_key()`,
`profile_sign(0, msg) == sign(msg)`, and
`profile_derive_symmetric_key(0, label) == derive_symmetric_key(label)` —
byte-for-byte. Each distinct `profile_ix` yields a distinct, deterministic key
and DEK.

### 3.4 The versioned seed envelope (at-rest format)

The stored account root MUST be sealed in a versioned envelope, because the two
DIG generations of stored bytes are byte-for-byte **indistinguishable**: a legacy
blob's 32 bytes are a raw master seed, a current blob's are BIP-39 entropy.
Reinterpreting one as the other does not fail — it derives a different but
entirely plausible wallet, silently.

- The sealed plaintext MUST be `version:u8 || kind:u8 || secret`, sealed with
  `dig_keystore::opaque::seal` (magic `DIGOP1`) — the same audited container
  (Argon2id + AES-256-GCM + CRC-32) every `Keystore<K>` file uses.
- The current layout version is `0x01`; the only kind this crate WRITES is
  `0x01` = BIP-39 entropy for a 24-word English mnemonic.
- `kind` values are **append-only** (§5.1): a new kind takes a new discriminant
  and existing kinds keep their meaning forever.
- A reader MUST detect a pre-envelope legacy blob — a typed `BlsSigning` keystore
  file, identified by its `DIGVK1` magic — **before** decryption and MUST fail
  with `SessionError::LegacySeedFormat`. It MUST NOT reinterpret those bytes as
  entropy under any circumstance. The account is recovered by re-enrolling from
  its recovery phrase.
- A reader MUST reject an unrecognised `version` or `kind` rather than guessing.

### 3.5 `SigningFn<K>`

`Arc<dyn Fn(&[u8]) -> K::Signature + Send + Sync>` — the injected primitive.

### 3.6 `SessionError` / `Result<T>`

- `SessionError::Keystore(dig_keystore::KeystoreError)` — transparent wrap.
- `SessionError::EmptySeed` — enrollment given empty seed material.
- `SessionError::LegacySeedFormat` — the stored blob predates the versioned
  envelope; its bytes MUST NOT be reinterpreted (§3.4).
- `SessionError::UnsupportedEnvelopeVersion(u8)` / `SessionError::UnsupportedSeedKind(u8)`
  — an envelope written by a newer build.
- `SessionError::InvalidRecoveryPhrase` — not a valid 24-word English BIP-39
  mnemonic. Its message MUST NOT contain any word of the phrase.

## 4. Custody invariants (MUST)

- **Secret zeroization.** An `UnlockedIdentity` holds its secret inside the
  wrapped `SignerHandle`'s `Zeroizing` buffer; the secret MUST be wiped when the
  handle (and any injected `SigningFn` copy) is dropped.
- **Enrollment-derivation hygiene.** During `enroll_identity`, every secret byte
  buffer the crate OWNS (the derived key's canonical bytes and the transient
  32-byte `to_bytes()` extraction) MUST be wrapped in `Zeroizing` so it is wiped
  on drop. The transient `chia_bls::SecretKey` scalars returned by dig-identity's
  derivation are a foreign type with no `Zeroize`/`Drop` impl (true even at the
  latest chia-bls 0.46) and cannot be wiped in place; they MUST instead be
  confined to the narrowest scope and dropped immediately after byte extraction.
  Fully wiping those scalars is RELIED UPON from upstream (tracked: request
  `Zeroize` on `chia_bls::SecretKey`), not delivered by this crate.
- **No secret in debug output.** `UnlockedIdentity` MUST NOT derive `Debug`; its
  `Debug` impl MUST redact the secret. It MUST NOT implement `Clone`.
- **No IPC crossing.** An `UnlockedIdentity` MUST NOT cross an IPC boundary; it
  belongs solely to the user-app process that owns the identity (dig_ecosystem
  #908). Downstreams receive a `SigningFn`, never the handle.
- **No secret in an error message.** A `SessionError` MUST NOT carry secret
  material. In particular `InvalidRecoveryPhrase` MUST NOT echo any submitted
  word, since a phrase is the whole account.
- **Never log a recovery phrase.** `recovery_phrase()` returns `Zeroizing<String>`
  and MUST NOT be logged. `dig-logging`'s BIP-39 wordlist redactor is a backstop,
  not a licence.
- **No unsafe.** The crate MUST forbid `unsafe` code (`#![forbid(unsafe_code)]`).

## 5. Conformance tests

An implementation MUST ship tests proving:

- `enroll_identity` then `unlock` reconstruct the same public key. (C-1)
- The enrolled public key equals the dig-identity canonical key — the regression
  guarding against a revert to `BlsSigning`/`from_seed`. (C-2)
- A produced signature verifies against the public key via `chia_bls::verify`. (C-3)
- An injected `SigningFn` still signs after the handle is dropped. (C-4)
- Unlock with the wrong password fails with `SessionError::Keystore`. (C-5)
- Enroll with empty seed fails with `SessionError::EmptySeed`. (C-6)
- `unlock` works generically for `BlsSigning`. (C-7)
- `Debug` output contains no secret material. (C-8)
- `derive_symmetric_key(b"dig-app:profile-dek:v2")` is byte-identical to dig-app's
  independently-reconstructed profile DEK for the same identity scalar. (C-9)
- `derive_symmetric_key` matches a frozen golden vector (fixed scalar + fixed
  label → exact DEK bytes); distinct labels derive distinct keys and the same
  label is deterministic. (C-10)

The master-seed path (§3.3) additionally MUST prove:

- `master_seed()` returns the `MASTER_SEED_LEN`-byte EXPANDED seed — equal to an
  independently computed `entropy -> mnemonic -> to_seed("")` and NOT the stored
  entropy. (MS-1)
- The seed-derived public key equals the dig-identity canonical key for the
  EXPANDED seed AND the identity-scalar path's public key for that seed. (MS-2)
- `derive_symmetric_key` on the master-seed path is byte-identical to the
  identity-scalar path (and to dig-app's reference DEK) for the same seed and
  label, incl. a frozen golden vector. (MS-3)
- A produced signature verifies against `public_key()`. (MS-4)
- An injected signing primitive still signs after the handle is dropped. (MS-5)
- `enroll_master_seed` then `unlock_master_seed` reproduce the same seed and key. (MS-6)
- `unlock_master_seed` with the wrong password fails with `SessionError::Keystore`. (MS-7)
- `Debug` output contains no seed material. (MS-8)

The per-profile methods (§3.3.1, 0.4.0) additionally MUST prove:

- `profile_public_key(0) == public_key()`, `profile_sign(0, m) == sign(m)`, and
  `profile_derive_symmetric_key(0, label) == derive_symmetric_key(label)`,
  byte-for-byte. (PROF-1, PROF-2, PROF-3)
- `profile_public_key(profile_ix)` equals dig-identity's canonical
  `public_key_bytes(derive_identity_sk_at(master, profile_ix))`. (PROF-4)
- A non-zero profile is distinct from profile 0 and deterministic across handles
  for the same seed. (PROF-5)
- A profile signature verifies under that profile's public key and NOT under
  another profile's. (PROF-6)
- A frozen golden vector for a non-zero profile (fixed seed + profile 1 + fixed
  label → exact DEK bytes over `derive_identity_sk_at`). (PROF-7)

[`dig-keystore`]: https://crates.io/crates/dig-keystore
[`dig-identity`]: https://crates.io/crates/dig-identity

The Chia-conformant derivation (§3.3.0) and the envelope (§3.4) additionally
MUST prove:

- A fixed public 24-word phrase resolves to a **hardcoded literal** bech32m
  address produced independently via `chia-wallet-sdk` — the same address a
  standard Chia wallet shows for those words. Both sides MUST NOT be computed
  live, or a dependency bump could move them together and mask a regression.
  (CONF-1)
- The entropy-as-seed derivation is **no longer reachable**: the fixture still
  reproduces the pre-#1759 address literal (proving the test discriminates), and
  the crate does not. (CONF-2)
- A pre-envelope legacy blob FAILS CLOSED with `SessionError::LegacySeedFormat`
  and yields no handle and no address. (CONF-3)
- A phrase round-trips to an identical account — wallet address AND identity key,
  which derive through different paths. (CONF-4)
- Using **two accounts with different entropy**, each account's reported phrase
  restores THAT account's frozen address and identity key. A single-account
  round-trip is blind here: a `recovery_phrase()` that ignored the live root would
  return a self-consistent phrase for the WRONG account. (CONF-4b)
- `recovery_phrase()` does not consume the handle, and the handle still signs
  afterwards. (CONF-5)
- The identity key and the DEK derive from the EXPANDED seed, asserted against
  the expanded-seed value AND rejecting the entropy-derived value — the two
  placements are otherwise indistinguishable. (CONF-6)
- An invalid phrase (short, bad checksum, unknown word) is rejected with
  `InvalidRecoveryPhrase` and the message echoes no submitted word. (CONF-7)
- A phrase is accepted with mixed case and irregular whitespace. (CONF-8)
- Re-enrolling over an existing account is refused. (CONF-9)
- An unrecognised envelope version or kind is refused. (CONF-10)
- `bip39::Mnemonic` is `ZeroizeOnDrop` — a COMPILE-TIME assertion that the `zeroize` feature is
  enabled. `expand_entropy` builds a `Mnemonic` on every derivation and its word indices are a
  complete copy of the account root, so without the feature un-wiped copies of the root accumulate
  in memory while every behavioural test stays green. (CONF-11)
- A VALID BIP-39 phrase of a shorter supported length (12/15/18/21 words) is REJECTED with
  `InvalidRecoveryPhrase`, never a panic. Malformed phrases fail inside bip39 and never reach the
  length guard, so only a valid-but-shorter phrase exercises it — without this case, deleting the
  guard leaves the suite green while making a legitimate user input a `copy_from_slice` panic on the
  restore path. (CONF-12)