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    ///
16    /// `#[error(transparent)]` is load-bearing: `KeystoreError` is
17    /// `#[non_exhaustive]` and its catalog grows, so forwarding the inner
18    /// `Display` verbatim is what keeps a NEW refusal legible to a caller that
19    /// only prints the error. dig-keystore 0.9 added two such refusals, both
20    /// fail-closed on the keystore ROOT directory rather than on any one key:
21    /// `InsecurePermissions` (the root is group- or world-accessible, which on a
22    /// mode-ignoring mount — WSL2 `/mnt/c`, CIFS/SMB, FAT32/exFAT, NFS without
23    /// POSIX modes, a Windows/macOS-hosted container bind mount — is reported as
24    /// mode `511` and cannot be tightened by `chmod`) and `UnsafeRoot` (the root
25    /// is a symlink, so the path that was checked is not the path written to).
26    /// Neither is recoverable in place: the remedy is a root on a filesystem
27    /// that honours Unix modes, and `InsecurePermissions`' own `Display` names
28    /// it. A caller MUST NOT retry these, and MUST NOT fold them into a generic
29    /// storage-failure branch.
30    #[error(transparent)]
31    Keystore(#[from] dig_keystore::KeystoreError),
32
33    /// Enrollment was asked to derive an identity from empty seed material.
34    ///
35    /// A caller must supply real BIP-39 seed bytes; deriving an identity key
36    /// from an empty seed would silently produce a fixed, guessable key.
37    #[error("seed material must be non-empty")]
38    EmptySeed,
39
40    /// The stored blob predates the versioned seed envelope: its 32 bytes are a
41    /// **raw** master seed, not BIP-39 entropy.
42    ///
43    /// This fails CLOSED on purpose. The two encodings are byte-for-byte
44    /// indistinguishable, so reinterpreting the old bytes as entropy would
45    /// derive a different, entirely plausible wallet with no error at all — the
46    /// user would simply see the wrong (empty) account.
47    ///
48    /// # A consumer MUST handle this variant explicitly (HARD REQUIREMENT)
49    ///
50    /// A legacy account is **WEDGED**, not merely unreadable, and no amount of
51    /// retrying changes that:
52    ///
53    /// - [`Session::unlock_master_seed`](crate::Session::unlock_master_seed)
54    ///   returns this error and never a handle;
55    /// - [`Session::enroll_master_seed`](crate::Session::enroll_master_seed) at
56    ///   the same key returns `AlreadyExists`, because enrolment refuses to
57    ///   overwrite a custody root;
58    /// - the pre-envelope releases exposed no `recovery_phrase()`, so the user
59    ///   was never shown 24 words, and a legacy raw seed has no phrase that
60    ///   means anything under the current scheme.
61    ///
62    /// So a consumer that merely logs this error leaves the account permanently
63    /// and silently without a signer. The required remediation, which the
64    /// consumer owns because only it has a UI:
65    ///
66    /// 1. **Detect** this variant specifically — never a catch-all log line.
67    /// 2. **Preserve** the existing blob (copy it aside; do NOT delete it). It
68    ///    is password-sealed and may hold value, and its password may live in an
69    ///    OS credential store this crate cannot read. Discarding it can destroy
70    ///    the only copy of a funded key.
71    /// 3. **Tell the user, in the UI**, that the account must be re-created, and
72    ///    that the preserved file is their only copy of the old key.
73    /// 4. **Re-enrol** at a fresh key (or after moving the old blob aside) via
74    ///    [`enroll_master_seed`](crate::Session::enroll_master_seed) or
75    ///    [`enroll_from_recovery_phrase`](crate::Session::enroll_from_recovery_phrase),
76    ///    then show the new recovery phrase.
77    ///
78    /// Adopting this version WITHOUT that path is a regression for every
79    /// already-enrolled install (dig_ecosystem #1759).
80    #[error(
81        "this account was stored under the legacy raw-seed format and cannot be \
82         read as BIP-39 entropy; re-enrol it from its 24-word recovery phrase"
83    )]
84    LegacySeedFormat,
85
86    /// The stored seed envelope declares a layout version this build does not
87    /// know. Written by a newer dig-session; refuse rather than guess.
88    #[error("unsupported seed-envelope version {0:#04x}; this build is too old to read it")]
89    UnsupportedEnvelopeVersion(u8),
90
91    /// The stored seed envelope declares a secret KIND this build does not know.
92    /// Refuse rather than fall back to an interpretation that could be wrong.
93    #[error("unsupported stored seed kind {0:#04x}; this build is too old to read it")]
94    UnsupportedSeedKind(u8),
95
96    /// A supplied recovery phrase is not a valid 24-word English BIP-39
97    /// mnemonic (unknown word, failed checksum, or wrong word count).
98    ///
99    /// The message names only the SHAPE of the failure — never a word of the
100    /// phrase, which is secret material.
101    #[error(
102        "not a valid 24-word English BIP-39 recovery phrase (check the word \
103         count, spelling, and order)"
104    )]
105    InvalidRecoveryPhrase,
106}
107
108/// Convenience alias for `Result<T, SessionError>`.
109pub type Result<T> = std::result::Result<T, SessionError>;