auths_sdk/domains/agents/
error.rs

1use auths_core::error::AuthsErrorInfo;
2use thiserror::Error;
3
4/// Errors from agent delegation operations (`agents::add` and friends).
5///
6/// An agent is a KERI `dip`-delegated identifier of a root/org identity — the same
7/// engine devices use. These errors mirror the device delegation surface.
8///
9/// Usage:
10/// ```ignore
11/// match agents::add(&ctx, &root_alias, &agent_alias, curve) {
12///     Err(AgentError::AlreadyDelegated { alias }) => { /* key in use */ }
13///     Err(e) => return Err(e.into()),
14///     Ok(result) => { /* agent did:keri */ }
15/// }
16/// ```
17#[derive(Debug, Error)]
18#[non_exhaustive]
19pub enum AgentError {
20    /// The delegating (root/org) identity could not be found in storage.
21    #[error("identity not found: {did}")]
22    IdentityNotFound {
23        /// The DID (or load context) that was not found.
24        did: String,
25    },
26
27    /// A key already exists under the requested agent alias — re-delegating it
28    /// would clobber an existing agent. Choose a fresh `--label`/alias.
29    #[error("an agent key already exists under alias '{alias}'")]
30    AlreadyDelegated {
31        /// The keychain alias already in use.
32        alias: String,
33    },
34
35    /// No agent delegated by this root matches the given DID (or its key is
36    /// missing from the keychain).
37    #[error("agent not found: {did}")]
38    AgentNotFound {
39        /// The agent DID that could not be resolved.
40        did: String,
41    },
42
43    /// The agent has been revoked by the delegator and cannot be rotated.
44    #[error("agent {did} is revoked")]
45    Revoked {
46        /// The revoked agent's DID.
47        did: String,
48    },
49
50    /// The requested agent scope exceeds the delegator's own scope — a delegate's
51    /// authority can only narrow, never widen (subset rule).
52    #[error("requested capability '{capability}' exceeds the delegator's scope")]
53    OutsideDelegatorScope {
54        /// The capability that the delegator does not itself hold.
55        capability: String,
56    },
57
58    /// A cryptographic operation failed (e.g. resolving the root's curve).
59    #[error("crypto error: {0}")]
60    CryptoError(#[source] auths_core::AgentError),
61
62    /// Authoring or anchoring the delegated agent identifier failed.
63    #[error("agent delegation failed: {0}")]
64    DelegationError(#[source] auths_id::error::InitError),
65
66    /// Creating the signed delegation attestation (the chain link issued by the
67    /// delegator over the agent's key) failed.
68    #[error("agent delegation attestation failed: {0}")]
69    AttestationError(#[source] auths_verifier::error::AttestationError),
70
71    /// Persisting or KEL-anchoring the delegation attestation failed.
72    #[error("agent delegation attestation anchoring failed: {0}")]
73    AnchorError(#[source] auths_id::keri::AnchorError),
74}
75
76impl From<auths_core::AgentError> for AgentError {
77    fn from(err: auths_core::AgentError) -> Self {
78        AgentError::CryptoError(err)
79    }
80}
81
82impl AuthsErrorInfo for AgentError {
83    fn error_code(&self) -> &'static str {
84        match self {
85            Self::IdentityNotFound { .. } => "AUTHS-E5311",
86            Self::AlreadyDelegated { .. } => "AUTHS-E5312",
87            Self::CryptoError(e) => e.error_code(),
88            Self::DelegationError(_) => "AUTHS-E5313",
89            Self::AgentNotFound { .. } => "AUTHS-E5314",
90            Self::Revoked { .. } => "AUTHS-E5315",
91            Self::OutsideDelegatorScope { .. } => "AUTHS-E5316",
92            Self::AttestationError(_) => "AUTHS-E5317",
93            Self::AnchorError(_) => "AUTHS-E5318",
94        }
95    }
96
97    fn suggestion(&self) -> Option<&'static str> {
98        match self {
99            Self::IdentityNotFound { .. } => {
100                Some("Run `auths init` to create a root identity first")
101            }
102            Self::AlreadyDelegated { .. } => {
103                Some("Choose a different --label; run `auths id agent list` to see existing agents")
104            }
105            Self::CryptoError(e) => e.suggestion(),
106            Self::DelegationError(_) => Some(
107                "The agent delegation could not be authored or anchored; check the root identity",
108            ),
109            Self::AgentNotFound { .. } => {
110                Some("Run `auths id agent list` to see the agents this identity has delegated")
111            }
112            Self::Revoked { .. } => {
113                Some("This agent was revoked and cannot be rotated; delegate a new agent instead")
114            }
115            Self::OutsideDelegatorScope { .. } => {
116                Some("Narrow the agent's --scope to a subset of the delegator's own capabilities")
117            }
118            Self::AttestationError(_) => {
119                Some("The delegation attestation could not be signed; check the keychain aliases")
120            }
121            Self::AnchorError(_) => Some(
122                "The delegation attestation could not be anchored; check the root identity's KEL",
123            ),
124        }
125    }
126}
auths_sdk/domains/agents/error.rs

auths_sdk/domains/agents/
error.rs
