auths_core/
error.rs

1//! Error types for agent and core operations.
2
3use thiserror::Error;
4
5pub use auths_crypto::AuthsErrorInfo;
6
7/// Errors from the Auths agent and core operations.
8#[derive(Debug, Error)]
9#[non_exhaustive]
10pub enum AgentError {
11    /// The requested key was not found.
12    #[error("Key not found")]
13    KeyNotFound,
14
15    /// The provided passphrase is incorrect.
16    #[error("Incorrect passphrase")]
17    IncorrectPassphrase,
18
19    /// A passphrase is required but was not provided.
20    #[error("Missing Passphrase")]
21    MissingPassphrase,
22
23    /// A platform security framework error occurred.
24    #[error("Security error: {0}")]
25    SecurityError(String),
26
27    /// A cryptographic operation failed.
28    #[error("Crypto error: {0}")]
29    CryptoError(String),
30
31    /// Failed to deserialize a key.
32    #[error("Key deserialization error: {0}")]
33    KeyDeserializationError(String),
34
35    /// Signing operation failed.
36    #[error("Signing failed: {0}")]
37    SigningFailed(String),
38
39    /// A protocol error occurred.
40    #[error("Protocol error: {0}")]
41    Proto(String),
42
43    /// An I/O error occurred.
44    #[error("IO error: {0}")]
45    IO(#[from] std::io::Error),
46
47    /// A Git operation failed.
48    #[error("git error: {0}")]
49    GitError(String),
50
51    /// Invalid input was provided.
52    #[error("Invalid input: {0}")]
53    InvalidInput(String),
54
55    /// A mutex lock was poisoned.
56    #[error("Mutex lock poisoned: {0}")]
57    MutexError(String),
58
59    /// A storage operation failed.
60    #[error("Storage error: {0}")]
61    StorageError(String),
62
63    /// The user cancelled an interactive prompt.
64    #[error("User input cancelled")]
65    UserInputCancelled,
66
67    // --- Platform backend errors ---
68    /// Backend is not available on this platform or configuration
69    #[error("Keychain backend unavailable: {backend} - {reason}")]
70    BackendUnavailable {
71        /// Name of the failing backend.
72        backend: &'static str,
73        /// Reason the backend is unavailable.
74        reason: String,
75    },
76
77    /// Storage is locked and requires authentication
78    #[error("Storage is locked, authentication required")]
79    StorageLocked,
80
81    /// Backend initialization failed
82    #[error("Failed to initialize keychain backend: {backend} - {error}")]
83    BackendInitFailed {
84        /// Name of the failing backend.
85        backend: &'static str,
86        /// Initialization error message.
87        error: String,
88    },
89
90    /// Credential size exceeds platform limit
91    #[error("Credential too large for backend (max {max_bytes} bytes, got {actual_bytes})")]
92    CredentialTooLarge {
93        /// Maximum credential size in bytes.
94        max_bytes: usize,
95        /// Actual credential size in bytes.
96        actual_bytes: usize,
97    },
98
99    /// Agent is locked due to idle timeout
100    #[error("Agent is locked. Unlock with 'auths agent unlock' or restart the agent.")]
101    AgentLocked,
102
103    /// The passphrase does not meet strength requirements.
104    #[error("Passphrase too weak: {0}")]
105    WeakPassphrase(String),
106
107    // --- HSM / PKCS#11 errors ---
108    /// HSM PIN is locked after too many failed attempts.
109    #[error("HSM PIN is locked — reset required")]
110    HsmPinLocked,
111
112    /// HSM device was removed during operation.
113    #[error("HSM device removed")]
114    HsmDeviceRemoved,
115
116    /// HSM session expired or was closed unexpectedly.
117    #[error("HSM session expired")]
118    HsmSessionExpired,
119
120    /// HSM does not support the requested cryptographic mechanism.
121    #[error("HSM does not support mechanism: {0}")]
122    HsmUnsupportedMechanism(String),
123}
124
125impl AuthsErrorInfo for AgentError {
126    fn error_code(&self) -> &'static str {
127        match self {
128            Self::KeyNotFound => "AUTHS-E3001",
129            Self::IncorrectPassphrase => "AUTHS-E3002",
130            Self::MissingPassphrase => "AUTHS-E3003",
131            Self::SecurityError(_) => "AUTHS-E3004",
132            Self::CryptoError(_) => "AUTHS-E3005",
133            Self::KeyDeserializationError(_) => "AUTHS-E3006",
134            Self::SigningFailed(_) => "AUTHS-E3007",
135            Self::Proto(_) => "AUTHS-E3008",
136            Self::IO(_) => "AUTHS-E3009",
137            Self::GitError(_) => "AUTHS-E3010",
138            Self::InvalidInput(_) => "AUTHS-E3011",
139            Self::MutexError(_) => "AUTHS-E3012",
140            Self::StorageError(_) => "AUTHS-E3013",
141            Self::UserInputCancelled => "AUTHS-E3014",
142            Self::BackendUnavailable { .. } => "AUTHS-E3015",
143            Self::StorageLocked => "AUTHS-E3016",
144            Self::BackendInitFailed { .. } => "AUTHS-E3017",
145            Self::CredentialTooLarge { .. } => "AUTHS-E3018",
146            Self::AgentLocked => "AUTHS-E3019",
147            Self::WeakPassphrase(_) => "AUTHS-E3020",
148            Self::HsmPinLocked => "AUTHS-E3021",
149            Self::HsmDeviceRemoved => "AUTHS-E3022",
150            Self::HsmSessionExpired => "AUTHS-E3023",
151            Self::HsmUnsupportedMechanism(_) => "AUTHS-E3024",
152        }
153    }
154
155    fn suggestion(&self) -> Option<&'static str> {
156        match self {
157            Self::KeyNotFound => Some("Run `auths key list` to see available keys"),
158            Self::IncorrectPassphrase => Some("Check your passphrase and try again"),
159            Self::MissingPassphrase => {
160                Some("Provide a passphrase with --passphrase or set AUTHS_PASSPHRASE")
161            }
162            Self::BackendUnavailable { .. } => {
163                Some("Run `auths doctor` to diagnose keychain issues")
164            }
165            Self::StorageLocked => Some("Authenticate with your platform keychain"),
166            Self::BackendInitFailed { .. } => {
167                Some("Run `auths doctor` to diagnose keychain issues")
168            }
169            Self::GitError(_) => Some("Ensure you're in a Git repository"),
170            Self::AgentLocked => {
171                Some("Run `auths agent unlock` or restart with `auths agent start`")
172            }
173            Self::UserInputCancelled => {
174                Some("Run the command again and provide the required input")
175            }
176            Self::StorageError(_) => Some("Check file permissions and disk space"),
177            Self::SecurityError(_) => Some(
178                "Run `auths doctor` to check system keychain access and security configuration",
179            ),
180            Self::CryptoError(_) => {
181                Some("A cryptographic operation failed; check key material with `auths key list`")
182            }
183            Self::KeyDeserializationError(_) => {
184                Some("The stored key is corrupted; re-import with `auths key import`")
185            }
186            Self::SigningFailed(_) => Some(
187                "The signing operation failed; verify your key is accessible with `auths key list`",
188            ),
189            Self::Proto(_) => Some(
190                "A protocol error occurred; check that both sides are running compatible versions",
191            ),
192            Self::IO(_) => Some("Check file permissions and that the filesystem is not read-only"),
193            Self::InvalidInput(_) => Some("Check the command arguments and try again"),
194            Self::MutexError(_) => Some("A concurrency error occurred; restart the operation"),
195            Self::CredentialTooLarge { .. } => Some(
196                "Reduce the credential size or use file-based storage with AUTHS_KEYCHAIN_BACKEND=file",
197            ),
198            Self::WeakPassphrase(_) => {
199                Some("Use at least 12 characters with uppercase, lowercase, and a digit or symbol")
200            }
201            Self::HsmPinLocked => Some("Reset the HSM PIN using your HSM vendor's admin tools"),
202            Self::HsmDeviceRemoved => Some("Reconnect the HSM device and try again"),
203            Self::HsmSessionExpired => Some("Retry the operation — a new session will be opened"),
204            Self::HsmUnsupportedMechanism(_) => {
205                Some("Check that your HSM supports Ed25519 (CKM_EDDSA)")
206            }
207        }
208    }
209}
210
211/// Errors from trust resolution and identity pinning.
212#[derive(Debug, Error)]
213#[non_exhaustive]
214pub enum TrustError {
215    /// An I/O error occurred.
216    #[error("I/O error: {0}")]
217    Io(#[from] std::io::Error),
218    /// Invalid data encountered (corrupt pin, bad hex, wrong format).
219    #[error("{0}")]
220    InvalidData(String),
221    /// A required resource was not found.
222    #[error("not found: {0}")]
223    NotFound(String),
224    /// JSON serialization/deserialization failed.
225    #[error("serialization error: {0}")]
226    Serialization(#[from] serde_json::Error),
227    /// Attempted to create something that already exists.
228    #[error("already exists: {0}")]
229    AlreadyExists(String),
230    /// Advisory file lock could not be acquired.
231    #[error("lock acquisition failed: {0}")]
232    Lock(String),
233    /// Trust policy rejected the identity.
234    #[error("policy rejected: {0}")]
235    PolicyRejected(String),
236}
237
238impl AuthsErrorInfo for TrustError {
239    fn error_code(&self) -> &'static str {
240        match self {
241            Self::Io(_) => "AUTHS-E3101",
242            Self::InvalidData(_) => "AUTHS-E3102",
243            Self::NotFound(_) => "AUTHS-E3103",
244            Self::Serialization(_) => "AUTHS-E3104",
245            Self::AlreadyExists(_) => "AUTHS-E3105",
246            Self::Lock(_) => "AUTHS-E3106",
247            Self::PolicyRejected(_) => "AUTHS-E3107",
248        }
249    }
250
251    fn suggestion(&self) -> Option<&'static str> {
252        match self {
253            Self::NotFound(_) => Some("Run `auths trust list` to see pinned identities"),
254            Self::PolicyRejected(_) => Some("Run `auths trust add` to pin this identity"),
255            Self::Lock(_) => Some("Check file permissions and try again"),
256            Self::Io(_) => Some("Check disk space and file permissions"),
257            Self::AlreadyExists(_) => Some("Run `auths trust list` to see existing entries"),
258            Self::InvalidData(_) => {
259                Some("The trust store may be corrupted; delete and re-pin with `auths trust add`")
260            }
261            Self::Serialization(_) => {
262                Some("The trust store data is corrupted; delete and re-pin with `auths trust add`")
263            }
264        }
265    }
266}
267
268impl From<AgentError> for ssh_agent_lib::error::AgentError {
269    fn from(err: AgentError) -> Self {
270        match err {
271            AgentError::KeyNotFound => Self::Failure,
272            AgentError::IncorrectPassphrase => Self::Failure,
273            _ => Self::Failure,
274        }
275    }
276}
auths_core/error.rs

auths_core/
error.rs
