cgd 0.1.0-alpha.2

Official command-line interface for Coragrid source-linked private-market data infrastructure
Documentation
use std::fmt;
use std::str::FromStr;

use keyring::{Entry, Error as KeyringError};
use serde::{Deserialize, Serialize};
use zeroize::Zeroize;

use crate::config::{Credential, CredentialKind, CredentialSource};
use crate::error::CgdError;

const REFERENCE_PREFIX: &str = "os-keyring:cgd/";
const KEYRING_SERVICE: &str = "com.coragrid.cgd";
const STORED_CREDENTIAL_VERSION: u8 = 1;

/// A non-secret reference to one credential in the platform credential store.
///
/// References are intentionally constrained to Coragrid's own namespace. This
/// prevents a configuration file from turning `cgd` into a reader for
/// arbitrary entries owned by other applications.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CredentialReference {
    account: String,
}

impl CredentialReference {
    pub fn for_profile(profile: &str) -> Result<Self, CgdError> {
        Self::from_str(&format!("{REFERENCE_PREFIX}{profile}"))
    }

    fn keyring_user(&self) -> String {
        format!("cgd/{}", self.account)
    }
}

impl fmt::Display for CredentialReference {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(formatter, "{REFERENCE_PREFIX}{}", self.account)
    }
}

impl FromStr for CredentialReference {
    type Err = CgdError;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        let account = value.trim().strip_prefix(REFERENCE_PREFIX).ok_or_else(|| {
            CgdError::Configuration(format!("credential_ref must use {REFERENCE_PREFIX}<name>"))
        })?;
        if account.is_empty()
            || account.len() > 64
            || !account.chars().all(|character| {
                character.is_ascii_alphanumeric() || matches!(character, '-' | '_')
            })
        {
            return Err(CgdError::Configuration(
                "credential_ref names may contain only 1-64 ASCII letters, digits, '-' or '_'"
                    .to_owned(),
            ));
        }
        Ok(Self {
            account: account.to_owned(),
        })
    }
}

pub trait CredentialStore {
    fn get(&self, reference: &CredentialReference) -> Result<Option<Credential>, CgdError>;

    fn put(
        &self,
        _reference: &CredentialReference,
        _credential: &Credential,
    ) -> Result<(), CgdError> {
        Err(CgdError::Internal(
            "credential store is read-only in this context".to_owned(),
        ))
    }

    fn delete(&self, _reference: &CredentialReference) -> Result<bool, CgdError> {
        Err(CgdError::Internal(
            "credential store is read-only in this context".to_owned(),
        ))
    }
}

pub struct OsCredentialStore;

impl CredentialStore for OsCredentialStore {
    fn get(&self, reference: &CredentialReference) -> Result<Option<Credential>, CgdError> {
        let entry = Entry::new(KEYRING_SERVICE, &reference.keyring_user()).map_err(|_| {
            CgdError::Unavailable(format!(
                "cannot initialize the OS credential store for {reference}"
            ))
        })?;
        let mut encoded = match entry.get_password() {
            Ok(encoded) => encoded,
            Err(KeyringError::NoEntry) => return Ok(None),
            Err(_) => {
                return Err(CgdError::Unavailable(format!(
                    "cannot read {reference}; the OS credential store may be locked or unavailable"
                )));
            }
        };
        let decoded = serde_json::from_str::<StoredCredential>(&encoded);
        encoded.zeroize();
        let mut decoded = decoded.map_err(|_| {
            CgdError::Configuration(format!(
                "{reference} does not contain a supported Coragrid credential"
            ))
        })?;
        if decoded.version != STORED_CREDENTIAL_VERSION {
            decoded.secret.zeroize();
            return Err(CgdError::Configuration(format!(
                "{reference} uses an unsupported credential format version"
            )));
        }
        Credential::new(
            decoded.kind,
            CredentialSource::OsCredentialStore,
            std::mem::take(&mut decoded.secret),
            "stored OS credential",
        )
        .map(Some)
    }

    fn put(
        &self,
        reference: &CredentialReference,
        credential: &Credential,
    ) -> Result<(), CgdError> {
        let entry = entry(reference)?;
        let mut encoded = serde_json::to_string(&StoredCredentialRef {
            version: STORED_CREDENTIAL_VERSION,
            kind: credential.kind(),
            secret: credential.bearer(),
        })
        .map_err(|_| CgdError::Internal("cannot encode the Coragrid credential".to_owned()))?;
        let result = entry.set_password(&encoded);
        encoded.zeroize();
        result.map_err(|_| {
            CgdError::Unavailable(format!(
                "cannot write {reference}; the OS credential store may be locked or unavailable"
            ))
        })
    }

    fn delete(&self, reference: &CredentialReference) -> Result<bool, CgdError> {
        let entry = entry(reference)?;
        match entry.delete_credential() {
            Ok(()) => Ok(true),
            Err(KeyringError::NoEntry) => Ok(false),
            Err(_) => Err(CgdError::Unavailable(format!(
                "cannot delete {reference}; the OS credential store may be locked or unavailable"
            ))),
        }
    }
}

fn entry(reference: &CredentialReference) -> Result<Entry, CgdError> {
    Entry::new(KEYRING_SERVICE, &reference.keyring_user()).map_err(|_| {
        CgdError::Unavailable(format!(
            "cannot initialize the OS credential store for {reference}"
        ))
    })
}

#[derive(Serialize, Deserialize)]
struct StoredCredential {
    version: u8,
    kind: CredentialKind,
    secret: String,
}

#[derive(Serialize)]
struct StoredCredentialRef<'a> {
    version: u8,
    kind: CredentialKind,
    secret: &'a str,
}

impl Drop for StoredCredential {
    fn drop(&mut self) {
        self.secret.zeroize();
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn references_are_canonical_and_confined_to_the_cgd_namespace() {
        let reference = CredentialReference::from_str("os-keyring:cgd/team_alpha").unwrap();
        assert_eq!(reference.to_string(), "os-keyring:cgd/team_alpha");
        assert_eq!(reference.keyring_user(), "cgd/team_alpha");

        for invalid in [
            "keyring:cgd/default",
            "os-keyring:other/default",
            "os-keyring:cgd/",
            "os-keyring:cgd/../../other",
            "os-keyring:cgd/name with spaces",
        ] {
            assert!(
                CredentialReference::from_str(invalid).is_err(),
                "accepted {invalid}"
            );
        }
    }
}