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