lexe_node_client/

credentials.rs

//! Client credentials for authentication with Lexe services.

use std::{fmt, str::FromStr, sync::Arc};

use anyhow::{Context, anyhow};
use base64::Engine;
use lexe_api::auth::BearerAuthenticator;
use lexe_common::{
    api::{
        auth::{BearerAuthToken, LexeScope},
        revocable_clients::CreateRevocableClientResponse,
        user::UserPk,
    },
    env::DeployEnv,
    root_seed::RootSeed,
};
#[cfg(any(test, feature = "test-utils"))]
use lexe_crypto::rng::FastRng;
use lexe_crypto::{ed25519, rng::Crng};
#[cfg(any(test, feature = "test-utils"))]
use lexe_tls::shared_seed::certs::{
    EphemeralIssuingCaCert, RevocableClientCert, RevocableIssuingCaCert,
};
use lexe_tls::{
    rustls, shared_seed,
    types::{LxCertificateDer, LxPrivatePkcs8KeyDer},
};
#[cfg(any(test, feature = "test-utils"))]
use proptest::{
    prelude::{Arbitrary, any},
    strategy::{BoxedStrategy, Strategy},
};
use serde::{Deserialize, Serialize};

/// Credentials used to authenticate with a Lexe user node.
//
// Required to connect to a user node via mTLS.
pub enum Credentials {
    /// Using a [`RootSeed`]. Ex: app.
    RootSeed(RootSeed),
    /// Using a revocable client cert. Ex: SDK sidecar.
    ClientCredentials(ClientCredentials),
}

/// Borrowed version of [`Credentials`].
#[derive(Copy, Clone)]
pub enum CredentialsRef<'a> {
    /// Using a [`RootSeed`]. Ex: app.
    RootSeed(&'a RootSeed),
    /// Using a revocable client cert. Ex: SDK sidecar.
    ClientCredentials(&'a ClientCredentials),
}

/// All secrets required for an SDK client to authenticate with a user's node.
/// Encoded as a base64 JSON blob for easy transport (e.g. via env var or
/// config file).
#[derive(Clone, Serialize, Deserialize)]
#[cfg_attr(any(test, feature = "test-utils"), derive(Eq, PartialEq))]
pub struct ClientCredentials {
    /// The user public key.
    ///
    /// Always `Some(_)` if the credentials were created by `node-v0.8.11+`.
    #[serde(skip_serializing_if = "Option::is_none")]
    // #[cfg_attr(
    //     any(test, feature = "test-utils"),
    //     proptest(strategy = "any::<UserPk>().prop_map(Some)")
    // )]
    pub user_pk: Option<UserPk>,
    /// The hex-encoded client public key.
    pub client_pk: ed25519::PublicKey,
    /// The DER-encoded client key.
    pub rev_client_key_der: LxPrivatePkcs8KeyDer,
    /// The DER-encoded cert of the revocable client.
    pub rev_client_cert_der: LxCertificateDer,
    /// The DER-encoded cert of the ephemeral issuing CA.
    pub eph_ca_cert_der: LxCertificateDer,
    /// The long-lived [`LexeScope::GatewayProxy`] token for connecting to the
    /// user's node. Always `Some` for user nodes.
    // compat: Alias added in lexe-node-client-v0.1.16
    #[serde(
        rename = "lexe_auth_token",
        alias = "gateway_proxy_token",
        skip_serializing_if = "Option::is_none"
    )]
    pub gateway_proxy_token: Option<BearerAuthToken>,
}

// --- impl Credentials / CredentialsRef --- //

impl Credentials {
    pub fn as_ref(&self) -> CredentialsRef<'_> {
        match self {
            Credentials::RootSeed(root_seed) =>
                CredentialsRef::RootSeed(root_seed),
            Credentials::ClientCredentials(client_credentials) =>
                CredentialsRef::ClientCredentials(client_credentials),
        }
    }
}

impl From<RootSeed> for Credentials {
    fn from(root_seed: RootSeed) -> Self {
        Credentials::RootSeed(root_seed)
    }
}

impl From<ClientCredentials> for Credentials {
    fn from(client_credentials: ClientCredentials) -> Self {
        Credentials::ClientCredentials(client_credentials)
    }
}

impl<'a> From<&'a RootSeed> for CredentialsRef<'a> {
    fn from(root_seed: &'a RootSeed) -> Self {
        CredentialsRef::RootSeed(root_seed)
    }
}

impl<'a> From<&'a ClientCredentials> for CredentialsRef<'a> {
    fn from(client_credentials: &'a ClientCredentials) -> Self {
        CredentialsRef::ClientCredentials(client_credentials)
    }
}

impl<'a> CredentialsRef<'a> {
    /// Returns the user public key.
    ///
    /// Always `Some(_)` if the credentials were created by `node-v0.8.11+`.
    pub fn user_pk(&self) -> Option<UserPk> {
        match self {
            Self::RootSeed(root_seed) => Some(root_seed.derive_user_pk()),
            Self::ClientCredentials(cc) => cc.user_pk,
        }
    }

    /// Create a [`BearerAuthenticator`] appropriate for the given credentials.
    ///
    /// Errors if these credentials are [`ClientCredentials`] and are missing a
    /// [`LexeScope::GatewayProxy`] token.
    pub fn bearer_authenticator(
        &self,
    ) -> anyhow::Result<Arc<BearerAuthenticator>> {
        match self {
            // A root seed can mint tokens of any scope on demand.
            Self::RootSeed(root_seed) => Ok(Arc::new(
                BearerAuthenticator::new(root_seed.derive_user_key_pair()),
            )),
            // A client credential holds a single long-lived `GatewayProxy`
            // token, good only for connecting to the user's node.
            Self::ClientCredentials(client_credentials) => {
                let gateway_proxy_token =
                    client_credentials.gateway_proxy_token.clone().context(
                        "Cannot connect to note; exported client credentials \
                         are missing a gateway proxy token.",
                    )?;
                Ok(Arc::new(BearerAuthenticator::new_static_token(
                    gateway_proxy_token,
                    LexeScope::GatewayProxy,
                )))
            }
        }
    }

    /// Build a TLS client config appropriate for the given credentials.
    pub fn tls_config(
        &self,
        rng: &mut impl Crng,
        deploy_env: DeployEnv,
    ) -> anyhow::Result<rustls::ClientConfig> {
        match self {
            Self::RootSeed(root_seed) =>
                shared_seed::app_node_run_client_config(
                    rng, deploy_env, root_seed,
                )
                .context("Failed to build RootSeed TLS client config"),
            Self::ClientCredentials(client_credentials) =>
                shared_seed::sdk_node_run_client_config(
                    deploy_env,
                    &client_credentials.eph_ca_cert_der,
                    client_credentials.rev_client_cert_der.clone(),
                    client_credentials.rev_client_key_der.clone(),
                )
                .context("Failed to build revocable client TLS config"),
        }
    }
}

// --- impl ClientCredentials --- //

impl fmt::Debug for ClientCredentials {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("ClientCredentials(..)")
    }
}

impl FromStr for ClientCredentials {
    type Err = anyhow::Error;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Self::try_from_base64_blob(s)
    }
}

impl From<CreateRevocableClientResponse> for ClientCredentials {
    fn from(resp: CreateRevocableClientResponse) -> Self {
        ClientCredentials {
            user_pk: resp.user_pk,
            client_pk: resp.pubkey,
            rev_client_key_der: LxPrivatePkcs8KeyDer(
                resp.rev_client_cert_key_der,
            ),
            rev_client_cert_der: LxCertificateDer(resp.rev_client_cert_der),
            eph_ca_cert_der: LxCertificateDer(resp.eph_ca_cert_der),
            gateway_proxy_token: resp.gateway_proxy_token,
        }
    }
}

impl ClientCredentials {
    /// Encodes a [`ClientCredentials`] to a base64 blob using
    /// [`base64::engine::general_purpose::STANDARD_NO_PAD`].
    //
    // We use `STANDARD_NO_PAD` because trailing `=`s cause problems with
    // autocomplete on iPhone. For example, if the base64 string ends with:
    //
    // - `NzB2mIn0=`
    // - `NzBm2In0=`
    //
    // the iPhone autocompletes it to the following respectively when pasted
    // into iMessage, even if you 'tap away' to reject the suggestion:
    //
    // - `NzB2mIn0=120 secs`
    // - `NzBm2In0=0 in`
    pub fn to_base64_blob(&self) -> String {
        let json_str =
            serde_json::to_string(self).expect("Failed to JSON serialize");
        base64::engine::general_purpose::STANDARD_NO_PAD
            .encode(json_str.as_bytes())
    }

    /// Decodes a [`ClientCredentials`] from a base64 blob encoded with either
    /// [`base64::engine::general_purpose::STANDARD`] or
    /// [`base64::engine::general_purpose::STANDARD_NO_PAD`].
    //
    // NOTE: This function accepts `STANDARD` encodings because historical
    // client credentials were encoded with the `STANDARD` engine until we
    // discovered that iPhones interpret the trailing `=` as part of a unit
    // conversion, resulting in unintended autocompletions.
    pub fn try_from_base64_blob(s: &str) -> anyhow::Result<Self> {
        let s = s.trim().trim_end_matches('=');
        let bytes = base64::engine::general_purpose::STANDARD_NO_PAD
            .decode(s)
            .context("String is not valid base64")?;
        let string =
            String::from_utf8(bytes).context("String is not valid UTF-8")?;
        let cc = serde_json::from_str::<ClientCredentials>(&string)
            .context("Failed to deserialize")?;

        // Check that the deserialized ClientCredentials are well formed;
        // ensure that private and public keys are consistent.
        let rev_client_keypair = ed25519::KeyPair::deserialize_pkcs8_der(
            cc.rev_client_key_der.as_bytes(),
        )
        .map_err(|_| anyhow!("Client key is invalid or corrupted"))?;
        if rev_client_keypair.public_key() != &cc.client_pk {
            return Err(anyhow!("Client key does not match client public key"));
        }

        Ok(cc)
    }
}

/// Arbitrary ClientCredentials should be self-consistent
#[cfg(any(test, feature = "test-utils"))]
impl Arbitrary for ClientCredentials {
    type Parameters = ();
    type Strategy = BoxedStrategy<ClientCredentials>;
    fn arbitrary_with((): Self::Parameters) -> Self::Strategy {
        let root_seed = any::<RootSeed>();
        let rng = any::<FastRng>();
        let gateway_proxy_token = any::<Option<BearerAuthToken>>();
        let has_user_pk = any::<bool>();

        (root_seed, rng, gateway_proxy_token, has_user_pk)
            .prop_map(
                |(root_seed, mut rng, gateway_proxy_token, has_user_pk)| {
                    // Derive intermediaries
                    let eph_ca_cert =
                        EphemeralIssuingCaCert::from_root_seed(&root_seed);
                    let rev_ca_cert =
                        RevocableIssuingCaCert::from_root_seed(&root_seed);
                    let rev_client_cert =
                        RevocableClientCert::generate_from_rng(&mut rng);

                    // Derive fields
                    let user_pk =
                        has_user_pk.then(|| root_seed.derive_user_pk());
                    let client_pk = rev_client_cert.public_key().to_owned();
                    let rev_client_key_der =
                        rev_client_cert.serialize_key_der();
                    let rev_client_cert_der = rev_client_cert
                        .serialize_der_ca_signed(&rev_ca_cert)
                        .unwrap();
                    let eph_ca_cert_der =
                        eph_ca_cert.serialize_der_self_signed().unwrap();

                    ClientCredentials {
                        user_pk,
                        client_pk,
                        rev_client_key_der,
                        rev_client_cert_der,
                        eph_ca_cert_der,
                        gateway_proxy_token,
                    }
                },
            )
            .boxed()
    }
}

#[cfg(test)]
mod test {
    use std::fs;

    use lexe_common::{
        byte_str::ByteStr,
        test_utils::{arbitrary, snapshot},
    };
    use lexe_crypto::rng::FastRng;
    use lexe_tls::shared_seed::certs::{
        EphemeralIssuingCaCert, RevocableIssuingCaCert,
    };
    use proptest::{prelude::any, prop_assert_eq, proptest};

    use super::*;

    /// Tests [`ClientCredentials`] roundtrip to/from base64.
    ///
    /// We also test compatibility: client credentials encoded with the old
    /// STANDARD engine can be decoded with the new try_from_base64_blob method
    /// which should accept both STANDARD and STANDARD_NO_PAD.
    #[test]
    fn prop_client_credentials_base64_roundtrip() {
        proptest!(|(creds1 in proptest::prelude::any::<ClientCredentials>())| {
            // Encode using `to_base64_blob` (STANDARD_NO_PAD).
            // Decode using `try_from_base64_blob`.
            {
                let new_base64_blob = creds1.to_base64_blob();

                let creds2 =
                    ClientCredentials::try_from_base64_blob(&new_base64_blob)
                        .expect("Failed to decode from new format");

                prop_assert_eq!(&creds1, &creds2);
            }

            // Compatibility test:
            // Encode using the engine used by old clients (STANDARD).
            // Decode using `try_from_base64_blob`.
            {
                let json_str = serde_json::to_string(&creds1)
                    .expect("Failed to JSON serialize");
                let old_base64_blob = base64::engine::general_purpose::STANDARD
                    .encode(json_str.as_bytes());
                let creds2 =
                    ClientCredentials::try_from_base64_blob(&old_base64_blob)
                        .expect("Failed to decode from old format");

                prop_assert_eq!(&creds1, &creds2);
            }
        });
    }

    /// Tests that the `STANDARD_NO_PAD` engine can decode any base64 string
    /// encoded with the `STANDARD` engine after removing trailing `=`s.
    #[test]
    fn prop_base64_pad_to_no_pad_compat() {
        proptest!(|(bytes1 in any::<Vec<u8>>())| {
            let string =
                base64::engine::general_purpose::STANDARD.encode(&bytes1);
            let trimmed = string.trim_end_matches('=');
            let bytes2 = base64::engine::general_purpose::STANDARD_NO_PAD
                .decode(trimmed)
                .expect("Failed to decode base64");
            prop_assert_eq!(bytes1, bytes2);
        })
    }

    #[test]
    fn test_client_auth_encoding() {
        let mut rng = FastRng::from_u64(202505121546);
        let root_seed = RootSeed::from_rng(&mut rng);

        let user_pk = root_seed.derive_user_pk();

        let eph_ca_cert = EphemeralIssuingCaCert::from_root_seed(&root_seed);
        let eph_ca_cert_der = eph_ca_cert.serialize_der_self_signed().unwrap();

        let rev_ca_cert = RevocableIssuingCaCert::from_root_seed(&root_seed);

        let rev_client_cert = RevocableClientCert::generate_from_rng(&mut rng);
        let rev_client_cert_der = rev_client_cert
            .serialize_der_ca_signed(&rev_ca_cert)
            .unwrap();
        let rev_client_key_der = rev_client_cert.serialize_key_der();
        let client_pk = rev_client_cert.public_key();

        let credentials = ClientCredentials {
            user_pk: Some(user_pk),
            client_pk: *client_pk,
            rev_client_key_der,
            rev_client_cert_der,
            eph_ca_cert_der,
            gateway_proxy_token: Some(BearerAuthToken(ByteStr::from_static(
                "9dTCUvC8y7qcNyUbqynz3nwIQQHbQqPVKeMhXUj1Afr-vgj9E217_2tCS1IQM7LFqfBUC8Ec9fcb-dQiCRy6ot2FN-kR60edRFJUztAa2Rxao1Q0BS1s6vE8grgfhMYIAJDLMWgAAAAASE4zaAAAAABpaWlpaWlpaWlpaWlpaWlpaWlpaWlpaWlpaWlpaWlpaQE",
            ))),
        };

        let credentials_str = credentials.to_base64_blob();

        // let json_len = serde_json::to_string(&credentials).unwrap().len();
        // let base64_len = credentials_str.len();
        // println!("json: {json_len}, base64: {base64_len}");

        // json: 2259 B, base64(json): 3012 B
        let expected_str = "eyJ1c2VyX3BrIjoiNmZkNzY0MTU2OTMwNTA5ZmFkNTM2MWQzYjIyYjYxZjc1YWE5MWVkNjQwMjE1YjJjNDFjMmZmODZiMmJmYzQ3MiIsImNsaWVudF9wayI6IjcwODhhZjFmYzEyYWIwNGFkNmRkMTY1YmMzYTNjNWViMzA2MmI0MTFhMmY1NWExNjZiMGU0MDBiMzkwZmU0ZGIiLCJyZXZfY2xpZW50X2tleV9kZXIiOiIzMDUxMDIwMTAxMzAwNTA2MDMyYjY1NzAwNDIyMDQyMDBmNTgwZDM0NjFjNGVhMGIzNmI4MzZkNDUxYzFjMTk5ZWUzZTA2NDZhZDBkNjQyMzUzNzk3MzlkNjg2OTkyODk4MTIxMDA3MDg4YWYxZmMxMmFiMDRhZDZkZDE2NWJjM2EzYzVlYjMwNjJiNDExYTJmNTVhMTY2YjBlNDAwYjM5MGZlNGRiIiwicmV2X2NsaWVudF9jZXJ0X2RlciI6IjMwODIwMTgzMzA4MjAxMzVhMDAzMDIwMTAyMDIxNDQwYmVkYzU2ZDAzZDZiNTJmMjg0MmQ2NGRmOTBkMDJkNmRhMzZhNWIzMDA1MDYwMzJiNjU3MDMwNTYzMTBiMzAwOTA2MDM1NTA0MDYwYzAyNTU1MzMxMGIzMDA5MDYwMzU1MDQwODBjMDI0MzQxMzExMTMwMGYwNjAzNTUwNDBhMGMwODZjNjU3ODY1MmQ2MTcwNzAzMTI3MzAyNTA2MDM1NTA0MDMwYzFlNGM2NTc4NjUyMDcyNjU3NjZmNjM2MTYyNmM2NTIwNjk3MzczNzU2OTZlNjcyMDQzNDEyMDYzNjU3Mjc0MzAyMDE3MGQzNzM1MzAzMTMwMzEzMDMwMzAzMDMwMzA1YTE4MGYzNDMwMzkzNjMwMzEzMDMxMzAzMDMwMzAzMDMwNWEzMDUyMzEwYjMwMDkwNjAzNTUwNDA2MGMwMjU1NTMzMTBiMzAwOTA2MDM1NTA0MDgwYzAyNDM0MTMxMTEzMDBmMDYwMzU1MDQwYTBjMDg2YzY1Nzg2NTJkNjE3MDcwMzEyMzMwMjEwNjAzNTUwNDAzMGMxYTRjNjU3ODY1MjA3MjY1NzY2ZjYzNjE2MjZjNjUyMDYzNmM2OTY1NmU3NDIwNjM2NTcyNzQzMDJhMzAwNTA2MDMyYjY1NzAwMzIxMDA3MDg4YWYxZmMxMmFiMDRhZDZkZDE2NWJjM2EzYzVlYjMwNjJiNDExYTJmNTVhMTY2YjBlNDAwYjM5MGZlNGRiYTMxNzMwMTUzMDEzMDYwMzU1MWQxMTA0MGMzMDBhODIwODZjNjU3ODY1MmU2MTcwNzAzMDA1MDYwMzJiNjU3MDAzNDEwMDdiMTdiYzk1MzgyNjdiMzU0ZjA3MjZkODljYjFlYzMxMGIxMDJlNDIyYWI5Njk2Yjg3ZDlhZTcwMGNlZjJlODNjMTM2NmQwYWQxOTAzNWQ5ZTNlZDA0Y2Y1ZjdmMDVkZWY2OGE3MWRlMjEyYjg5ODM0NDc3OTQyYWU3NjNhMjBmIiwiZXBoX2NhX2NlcnRfZGVyIjoiMzA4MjAxYWUzMDgyMDE2MGEwMDMwMjAxMDIwMjE0MTBjZDVjOTk4OWY5NjUyMDk0OWUwZTlhYjRjZTRkYmUxNDc2NjcxMDMwMDUwNjAzMmI2NTcwMzA1MDMxMGIzMDA5MDYwMzU1MDQwNjBjMDI1NTUzMzEwYjMwMDkwNjAzNTUwNDA4MGMwMjQzNDEzMTExMzAwZjA2MDM1NTA0MGEwYzA4NmM2NTc4NjUyZDYxNzA3MDMxMjEzMDFmMDYwMzU1MDQwMzBjMTg0YzY1Nzg2NTIwNzM2ODYxNzI2NTY0MjA3MzY1NjU2NDIwNDM0MTIwNjM2NTcyNzQzMDIwMTcwZDM3MzUzMDMxMzAzMTMwMzAzMDMwMzAzMDVhMTgwZjM0MzAzOTM2MzAzMTMwMzEzMDMwMzAzMDMwMzA1YTMwNTAzMTBiMzAwOTA2MDM1NTA0MDYwYzAyNTU1MzMxMGIzMDA5MDYwMzU1MDQwODBjMDI0MzQxMzExMTMwMGYwNjAzNTUwNDBhMGMwODZjNjU3ODY1MmQ2MTcwNzAzMTIxMzAxZjA2MDM1NTA0MDMwYzE4NGM2NTc4NjUyMDczNjg2MTcyNjU2NDIwNzM2NTY1NjQyMDQzNDEyMDYzNjU3Mjc0MzAyYTMwMDUwNjAzMmI2NTcwMDMyMTAwZWZlOWNlMWFiY2FlYWJjZWY4ZWEyZjU0YTU2OTU1MGRjZWQ0YThmM2E4Y2JiMDRjZDk0NWQxYjRlMjQ1ZjY4N2EzNGEzMDQ4MzAxMzA2MDM1NTFkMTEwNDBjMzAwYTgyMDg2YzY1Nzg2NTJlNjE3MDcwMzAxZDA2MDM1NTFkMGUwNDE2MDQxNDkwY2Q1Yzk5ODlmOTY1MjA5NDllMGU5YWI0Y2U0ZGJlMTQ3NjY3MTAzMDEyMDYwMzU1MWQxMzAxMDFmZjA0MDgzMDA2MDEwMWZmMDIwMTAwMzAwNTA2MDMyYjY1NzAwMzQxMDAzNzI1NDI5ZjViY2E4MDU2MjFjMmIyZGM0NDU4MDJlZDIxY2FiMjQ2YjQ1YWQxMjFkZDJhNDMyZWZhMmY5M2VmNzI1ZWZhMTc4MmU2NDEwOGQyMjk4ZTg2OTRmNDY4NmNlZDk4Y2U5MjgwZWQ3NDlkMGFkNGI0NGE0YTFjZWUwZCIsImxleGVfYXV0aF90b2tlbiI6IjlkVENVdkM4eTdxY055VWJxeW56M253SVFRSGJRcVBWS2VNaFhVajFBZnItdmdqOUUyMTdfMnRDUzFJUU03TEZxZkJVQzhFYzlmY2ItZFFpQ1J5Nm90MkZOLWtSNjBlZFJGSlV6dEFhMlJ4YW8xUTBCUzFzNnZFOGdyZ2ZoTVlJQUpETE1XZ0FBQUFBU0U0emFBQUFBQUJwYVdscGFXbHBhV2xwYVdscGFXbHBhV2xwYVdscGFXbHBhV2xwYVdscGFRRSJ9";
        assert_eq!(credentials_str, expected_str);

        let credentials2 =
            ClientCredentials::try_from_base64_blob(&credentials_str)
                .expect("Failed to decode ClientAuth");
        assert_eq!(credentials, credentials2);
    }

    /// Generate serialized `ClientCredentials` sample json data:
    ///
    /// ```bash
    /// $ cargo test -p lexe-node-client --lib -- take_client_credentials_snapshot --ignored --nocapture
    /// ```
    #[test]
    #[ignore]
    fn take_client_credentials_snapshot() {
        let mut rng = FastRng::from_u64(202512210138);
        const N: usize = 3;

        let samples: Vec<ClientCredentials> =
            arbitrary::gen_values(&mut rng, any::<ClientCredentials>(), N);

        for sample in samples {
            println!("{}", serde_json::to_string(&sample).unwrap());
        }
    }

    // NOTE: see `take_client_credentials_snapshot` to generate new sample data.
    #[test]
    fn client_credentials_deser_compat() {
        let snapshot =
            fs::read_to_string("test_data/client_credentials_snapshot.txt")
                .unwrap();

        for input in snapshot::parse_sample_data(&snapshot) {
            let value1: ClientCredentials =
                serde_json::from_str(input).unwrap();
            let output = serde_json::to_string(&value1).unwrap();
            let value2: ClientCredentials =
                serde_json::from_str(&output).unwrap();
            assert_eq!(value1, value2);
        }
    }
}