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(
159                "Check your passphrase and try again. Set AUTHS_PASSPHRASE for automation, or run `auths agent start` for session caching",
160            ),
161            Self::MissingPassphrase => {
162                Some("Provide a passphrase with --passphrase or set AUTHS_PASSPHRASE")
163            }
164            Self::BackendUnavailable { .. } => {
165                Some("Run `auths doctor` to diagnose keychain issues")
166            }
167            Self::StorageLocked => Some("Authenticate with your platform keychain"),
168            Self::BackendInitFailed { .. } => {
169                Some("Run `auths doctor` to diagnose keychain issues")
170            }
171            Self::GitError(_) => Some("Ensure you're in a Git repository"),
172            Self::AgentLocked => {
173                Some("Run `auths agent unlock` or restart with `auths agent start`")
174            }
175            Self::UserInputCancelled => {
176                Some("Run the command again and provide the required input")
177            }
178            Self::StorageError(_) => Some("Check file permissions and disk space"),
179            Self::SecurityError(_) => Some(
180                "Run `auths doctor` to check system keychain access and security configuration",
181            ),
182            Self::CryptoError(_) => {
183                Some("A cryptographic operation failed; check key material with `auths key list`")
184            }
185            Self::KeyDeserializationError(_) => {
186                Some("The stored key is corrupted; re-import with `auths key import`")
187            }
188            Self::SigningFailed(_) => Some(
189                "The signing operation failed; verify your key is accessible with `auths key list`",
190            ),
191            Self::Proto(_) => Some(
192                "A protocol error occurred; check that both sides are running compatible versions",
193            ),
194            Self::IO(_) => Some("Check file permissions and that the filesystem is not read-only"),
195            Self::InvalidInput(_) => Some("Check the command arguments and try again"),
196            Self::MutexError(_) => Some("A concurrency error occurred; restart the operation"),
197            Self::CredentialTooLarge { .. } => Some(
198                "Reduce the credential size or use file-based storage with AUTHS_KEYCHAIN_BACKEND=file",
199            ),
200            Self::WeakPassphrase(_) => {
201                Some("Use at least 12 characters with uppercase, lowercase, and a digit or symbol")
202            }
203            Self::HsmPinLocked => Some("Reset the HSM PIN using your HSM vendor's admin tools"),
204            Self::HsmDeviceRemoved => Some("Reconnect the HSM device and try again"),
205            Self::HsmSessionExpired => Some("Retry the operation — a new session will be opened"),
206            Self::HsmUnsupportedMechanism(_) => {
207                Some("Check that your HSM supports Ed25519 (CKM_EDDSA)")
208            }
209        }
210    }
211}
212
213/// Errors from trust resolution and identity pinning.
214#[derive(Debug, Error)]
215#[non_exhaustive]
216pub enum TrustError {
217    /// An I/O error occurred.
218    #[error("I/O error: {0}")]
219    Io(#[from] std::io::Error),
220    /// Invalid data encountered (corrupt pin, bad hex, wrong format).
221    #[error("{0}")]
222    InvalidData(String),
223    /// A required resource was not found.
224    #[error("not found: {0}")]
225    NotFound(String),
226    /// JSON serialization/deserialization failed.
227    #[error("serialization error: {0}")]
228    Serialization(#[from] serde_json::Error),
229    /// Attempted to create something that already exists.
230    #[error("already exists: {0}")]
231    AlreadyExists(String),
232    /// Advisory file lock could not be acquired.
233    #[error("lock acquisition failed: {0}")]
234    Lock(String),
235    /// Trust policy rejected the identity.
236    #[error("policy rejected: {0}")]
237    PolicyRejected(String),
238}
239
240impl AuthsErrorInfo for TrustError {
241    fn error_code(&self) -> &'static str {
242        match self {
243            Self::Io(_) => "AUTHS-E3101",
244            Self::InvalidData(_) => "AUTHS-E3102",
245            Self::NotFound(_) => "AUTHS-E3103",
246            Self::Serialization(_) => "AUTHS-E3104",
247            Self::AlreadyExists(_) => "AUTHS-E3105",
248            Self::Lock(_) => "AUTHS-E3106",
249            Self::PolicyRejected(_) => "AUTHS-E3107",
250        }
251    }
252
253    fn suggestion(&self) -> Option<&'static str> {
254        match self {
255            Self::NotFound(_) => Some("Run `auths trust list` to see pinned identities"),
256            Self::PolicyRejected(_) => Some("Run `auths trust add` to pin this identity"),
257            Self::Lock(_) => Some("Check file permissions and try again"),
258            Self::Io(_) => Some("Check disk space and file permissions"),
259            Self::AlreadyExists(_) => Some("Run `auths trust list` to see existing entries"),
260            Self::InvalidData(_) => {
261                Some("The trust store may be corrupted; delete and re-pin with `auths trust add`")
262            }
263            Self::Serialization(_) => {
264                Some("The trust store data is corrupted; delete and re-pin with `auths trust add`")
265            }
266        }
267    }
268}
269
270impl From<AgentError> for ssh_agent_lib::error::AgentError {
271    fn from(err: AgentError) -> Self {
272        match err {
273            AgentError::KeyNotFound => Self::Failure,
274            AgentError::IncorrectPassphrase => Self::Failure,
275            _ => Self::Failure,
276        }
277    }
278}
auths_core/error.rs

auths_core/
error.rs
