dig_session/error.rs
1//! Error type for the session facade.
2
3use thiserror::Error;
4
5/// Errors returned by [`crate::Session`] operations.
6///
7/// Wraps the underlying [`dig_keystore`] failure verbatim (via `#[from]`) so a
8/// caller can match on the concrete storage/crypto error without dig-session
9/// inventing a parallel error taxonomy, plus the small number of failures that
10/// are specific to session enrollment.
11#[derive(Debug, Error)]
12pub enum SessionError {
13 /// A key-storage or decryption failure surfaced by [`dig_keystore`]
14 /// (missing file, wrong password, tampered ciphertext, scheme mismatch, …).
15 #[error(transparent)]
16 Keystore(#[from] dig_keystore::KeystoreError),
17
18 /// Enrollment was asked to derive an identity from empty seed material.
19 ///
20 /// A caller must supply real BIP-39 seed bytes; deriving an identity key
21 /// from an empty seed would silently produce a fixed, guessable key.
22 #[error("seed material must be non-empty")]
23 EmptySeed,
24
25 /// The stored blob predates the versioned seed envelope: its 32 bytes are a
26 /// **raw** master seed, not BIP-39 entropy.
27 ///
28 /// This fails CLOSED on purpose. The two encodings are byte-for-byte
29 /// indistinguishable, so reinterpreting the old bytes as entropy would
30 /// derive a different, entirely plausible wallet with no error at all — the
31 /// user would simply see the wrong (empty) account.
32 ///
33 /// # A consumer MUST handle this variant explicitly (HARD REQUIREMENT)
34 ///
35 /// A legacy account is **WEDGED**, not merely unreadable, and no amount of
36 /// retrying changes that:
37 ///
38 /// - [`Session::unlock_master_seed`](crate::Session::unlock_master_seed)
39 /// returns this error and never a handle;
40 /// - [`Session::enroll_master_seed`](crate::Session::enroll_master_seed) at
41 /// the same key returns `AlreadyExists`, because enrolment refuses to
42 /// overwrite a custody root;
43 /// - the pre-envelope releases exposed no `recovery_phrase()`, so the user
44 /// was never shown 24 words, and a legacy raw seed has no phrase that
45 /// means anything under the current scheme.
46 ///
47 /// So a consumer that merely logs this error leaves the account permanently
48 /// and silently without a signer. The required remediation, which the
49 /// consumer owns because only it has a UI:
50 ///
51 /// 1. **Detect** this variant specifically — never a catch-all log line.
52 /// 2. **Preserve** the existing blob (copy it aside; do NOT delete it). It
53 /// is password-sealed and may hold value, and its password may live in an
54 /// OS credential store this crate cannot read. Discarding it can destroy
55 /// the only copy of a funded key.
56 /// 3. **Tell the user, in the UI**, that the account must be re-created, and
57 /// that the preserved file is their only copy of the old key.
58 /// 4. **Re-enrol** at a fresh key (or after moving the old blob aside) via
59 /// [`enroll_master_seed`](crate::Session::enroll_master_seed) or
60 /// [`enroll_from_recovery_phrase`](crate::Session::enroll_from_recovery_phrase),
61 /// then show the new recovery phrase.
62 ///
63 /// Adopting this version WITHOUT that path is a regression for every
64 /// already-enrolled install (dig_ecosystem #1759).
65 #[error(
66 "this account was stored under the legacy raw-seed format and cannot be \
67 read as BIP-39 entropy; re-enrol it from its 24-word recovery phrase"
68 )]
69 LegacySeedFormat,
70
71 /// The stored seed envelope declares a layout version this build does not
72 /// know. Written by a newer dig-session; refuse rather than guess.
73 #[error("unsupported seed-envelope version {0:#04x}; this build is too old to read it")]
74 UnsupportedEnvelopeVersion(u8),
75
76 /// The stored seed envelope declares a secret KIND this build does not know.
77 /// Refuse rather than fall back to an interpretation that could be wrong.
78 #[error("unsupported stored seed kind {0:#04x}; this build is too old to read it")]
79 UnsupportedSeedKind(u8),
80
81 /// A supplied recovery phrase is not a valid 24-word English BIP-39
82 /// mnemonic (unknown word, failed checksum, or wrong word count).
83 ///
84 /// The message names only the SHAPE of the failure — never a word of the
85 /// phrase, which is secret material.
86 #[error(
87 "not a valid 24-word English BIP-39 recovery phrase (check the word \
88 count, spelling, and order)"
89 )]
90 InvalidRecoveryPhrase,
91}
92
93/// Convenience alias for `Result<T, SessionError>`.
94pub type Result<T> = std::result::Result<T, SessionError>;