gix_credentials/protocol/
mod.rs

1use bstr::BString;
2
3use crate::helper;
4
5/// The outcome of the credentials top-level functions to obtain a complete identity.
6#[derive(Debug, Clone, Eq, PartialEq)]
7pub struct Outcome {
8    /// The identity provide by the helper.
9    pub identity: gix_sec::identity::Account,
10    /// A handle to the action to perform next in another call to [`helper::invoke()`][crate::helper::invoke()].
11    pub next: helper::NextAction,
12}
13
14/// The Result type used in credentials top-level functions to obtain a complete identity.
15pub type Result = std::result::Result<Option<Outcome>, Error>;
16
17/// The error returned top-level credential functions.
18#[derive(Debug, thiserror::Error)]
19#[allow(missing_docs)]
20pub enum Error {
21    #[error(transparent)]
22    UrlParse(#[from] gix_url::parse::Error),
23    #[error("Either 'url' field or both 'protocol' and 'host' fields must be provided")]
24    UrlMissing,
25    #[error(transparent)]
26    ContextDecode(#[from] context::decode::Error),
27    #[error(transparent)]
28    InvokeHelper(#[from] helper::Error),
29    #[error("Could not configure credential helpers")]
30    ConfigureCredentialHelpers {
31        #[source]
32        source: Box<dyn std::error::Error + Send + Sync + 'static>,
33    },
34    #[error("Could not obtain identity for context: {}", { let mut buf = Vec::<u8>::new(); context.write_to(&mut buf).ok(); String::from_utf8_lossy(&buf).into_owned() })]
35    IdentityMissing { context: Context },
36    #[error("The handler asked to stop trying to obtain credentials")]
37    Quit,
38    #[error("Couldn't obtain {prompt}")]
39    Prompt { prompt: String, source: gix_prompt::Error },
40}
41
42/// Additional context to be passed to the credentials helper.
43#[derive(Debug, Default, Clone, Eq, PartialEq)]
44pub struct Context {
45    /// The protocol over which the credential will be used (e.g., https).
46    pub protocol: Option<String>,
47    /// The remote hostname for a network credential. This includes the port number if one was specified (e.g., "example.com:8088").
48    pub host: Option<String>,
49    /// The path with which the credential will be used. E.g., for accessing a remote https repository, this will be the repository’s path on the server.
50    /// It can also be a path on the file system.
51    pub path: Option<BString>,
52    /// The credential’s username, if we already have one (e.g., from a URL, the configuration, the user, or from a previously run helper).
53    pub username: Option<String>,
54    /// The credential’s password, if we are asking it to be stored.
55    pub password: Option<String>,
56    /// An OAuth refresh token that may accompany a password. It is to be treated confidentially, just like the password.
57    pub oauth_refresh_token: Option<String>,
58    /// The expiry date of OAuth tokens as seconds from Unix epoch.
59    pub password_expiry_utc: Option<gix_date::SecondsSinceUnixEpoch>,
60    /// When this special attribute is read by git credential, the value is parsed as a URL and treated as if its constituent
61    /// parts were read (e.g., url=<https://example.com> would behave as if
62    /// protocol=https and host=example.com had been provided). This can help callers avoid parsing URLs themselves.
63    pub url: Option<BString>,
64    /// If true, the caller should stop asking for credentials immediately without calling more credential helpers in the chain.
65    pub quit: Option<bool>,
66}
67
68/// Convert the outcome of a helper invocation to a helper result, assuring that the identity is complete in the process.
69#[allow(clippy::result_large_err)]
70pub fn helper_outcome_to_result(outcome: Option<helper::Outcome>, action: helper::Action) -> Result {
71    match (action, outcome) {
72        (helper::Action::Get(ctx), None) => Err(Error::IdentityMissing {
73            context: ctx.redacted(),
74        }),
75        (helper::Action::Get(ctx), Some(mut outcome)) => match outcome.consume_identity() {
76            Some(identity) => Ok(Some(Outcome {
77                identity,
78                next: outcome.next,
79            })),
80            None => Err(if outcome.quit {
81                Error::Quit
82            } else {
83                Error::IdentityMissing {
84                    context: ctx.redacted(),
85                }
86            }),
87        },
88        (helper::Action::Store(_) | helper::Action::Erase(_), _ignore) => Ok(None),
89    }
90}
91
92///
93pub mod context;
gix_credentials/protocol/mod.rs

gix_credentials/protocol/
mod.rs
