Skip to main content

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>;