Skip to main content

nautilus_coinbase/common/
credential.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16use std::fmt::{Debug, Display};
17
18use aws_lc_rs::{
19    rand as lc_rand,
20    signature::{ECDSA_P256_SHA256_FIXED_SIGNING, EcdsaKeyPair},
21};
22use base64::prelude::*;
23use nautilus_core::{
24    env::resolve_env_var_pair,
25    string::secret::{REDACTED, SecretString},
26};
27use serde_json::json;
28use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing};
29
30use crate::{
31    common::consts::{JWT_EXPIRY_SECS, JWT_ISSUER},
32    http::error::{Error, Result},
33};
34
35/// Returns the `(api_key, api_secret)` environment variable names.
36#[must_use]
37pub fn credential_env_vars() -> (&'static str, &'static str) {
38    ("COINBASE_API_KEY", "COINBASE_API_SECRET")
39}
40
41fn base64url_encode(data: &[u8]) -> String {
42    BASE64_URL_SAFE_NO_PAD.encode(data)
43}
44
45/// CDP API key pair with zeroization on drop.
46#[derive(Clone, Zeroize, ZeroizeOnDrop)]
47pub struct CoinbaseCredential {
48    api_key: String,
49    api_secret: String,
50}
51
52impl CoinbaseCredential {
53    /// Creates a new [`CoinbaseCredential`] instance.
54    pub fn new(api_key: String, api_secret: String) -> Self {
55        Self {
56            api_key,
57            api_secret,
58        }
59    }
60
61    /// Resolves credentials from provided values or [`credential_env_vars`],
62    /// returning `None` when neither yields a complete pair.
63    #[must_use]
64    pub fn resolve(api_key: Option<&str>, api_secret: Option<&str>) -> Option<Self> {
65        let (key_var, secret_var) = credential_env_vars();
66        let (key, secret) = resolve_env_var_pair(
67            api_key.filter(|s| !s.trim().is_empty()).map(String::from),
68            api_secret
69                .filter(|s| !s.trim().is_empty())
70                .map(String::from),
71            key_var,
72            secret_var,
73        )?;
74        Some(Self::new(key, secret))
75    }
76
77    /// Loads credentials from environment variables.
78    ///
79    /// # Errors
80    ///
81    /// Returns an error if the environment variables are unset or empty.
82    pub fn from_env() -> Result<Self> {
83        let (key_var, secret_var) = credential_env_vars();
84        Self::resolve(None, None).ok_or_else(|| {
85            Error::auth(format!(
86                "{key_var} and {secret_var} environment variables are required"
87            ))
88        })
89    }
90
91    /// Returns the API key name.
92    pub fn api_key(&self) -> &str {
93        &self.api_key
94    }
95
96    /// Returns the PEM-encoded API secret.
97    pub fn api_secret(&self) -> &str {
98        &self.api_secret
99    }
100
101    /// Generates a JWT for REST API authentication.
102    ///
103    /// The `uri` format is `"{METHOD} {host}{path}"`, e.g.
104    /// `"GET api.coinbase.com/api/v3/brokerage/accounts"`.
105    pub fn build_rest_jwt(&self, uri: &str) -> Result<SecretString> {
106        self.build_jwt(Some(uri))
107    }
108
109    /// Generates a JWT for WebSocket authentication (no URI claim).
110    pub fn build_ws_jwt(&self) -> Result<SecretString> {
111        self.build_jwt(None)
112    }
113
114    /// Generates an ES256 JWT signed with the PEM EC private key.
115    fn build_jwt(&self, uri: Option<&str>) -> Result<SecretString> {
116        let now = std::time::SystemTime::now()
117            .duration_since(std::time::UNIX_EPOCH)
118            .map_err(|e| Error::auth(format!("Failed to get system time: {e}")))?
119            .as_secs();
120
121        let nonce = {
122            let mut buf = [0u8; 16];
123            lc_rand::fill(&mut buf)
124                .map_err(|e| Error::auth(format!("Failed to generate nonce: {e}")))?;
125            nautilus_core::hex::encode(buf)
126        };
127
128        let header = json!({
129            "alg": "ES256",
130            "typ": "JWT",
131            "kid": self.api_key,
132            "nonce": nonce,
133        });
134
135        let mut payload = json!({
136            "sub": self.api_key,
137            "iss": JWT_ISSUER,
138            "nbf": now,
139            "exp": now + JWT_EXPIRY_SECS,
140        });
141
142        if let Some(uri) = uri {
143            payload["uri"] = serde_json::Value::String(uri.to_string());
144        }
145
146        let header_b64 = base64url_encode(header.to_string().as_bytes());
147        let payload_b64 = base64url_encode(payload.to_string().as_bytes());
148        let signing_input = format!("{header_b64}.{payload_b64}");
149
150        // Env vars and .env files often store PEM keys with literal `\n`
151        // instead of real newlines. Normalize before parsing.
152        let pem_str = Zeroizing::new(self.api_secret.trim().replace("\\n", "\n"));
153
154        let pem_obj = pem::parse(&pem_str).map_err(|_| Error::auth("Failed to parse PEM key"))?;
155
156        // Coinbase issues SEC1 (EC PRIVATE KEY) PEMs; from_private_key_der
157        // handles both SEC1 and PKCS#8 formats
158        let key_pair = EcdsaKeyPair::from_private_key_der(
159            &ECDSA_P256_SHA256_FIXED_SIGNING,
160            pem_obj.contents(),
161        )
162        .map_err(|e| Error::auth(format!("Failed to load EC private key: {e}")))?;
163
164        let rng = lc_rand::SystemRandom::new();
165        let sig = key_pair
166            .sign(&rng, signing_input.as_bytes())
167            .map_err(|e| Error::auth(format!("Failed to sign JWT: {e}")))?;
168
169        let sig_b64 = base64url_encode(sig.as_ref());
170
171        Ok(SecretString::from(format!("{signing_input}.{sig_b64}")))
172    }
173}
174
175impl Debug for CoinbaseCredential {
176    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
177        f.debug_struct(stringify!(CoinbaseCredential))
178            .field("api_key", &REDACTED)
179            .field("api_secret", &REDACTED)
180            .finish()
181    }
182}
183
184impl Display for CoinbaseCredential {
185    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
186        write!(f, "CoinbaseCredential({REDACTED})")
187    }
188}
189
190#[cfg(test)]
191mod tests {
192    use aws_lc_rs::encoding::AsDer;
193    use rstest::rstest;
194
195    use super::*;
196
197    const TEST_API_KEY: &str = "organizations/test-org/apiKeys/test-key-id";
198
199    /// Generates a SEC1 (RFC 5915) PEM key matching Coinbase's production format.
200    fn test_sec1_pem_key() -> String {
201        let rng = lc_rand::SystemRandom::new();
202        let pkcs8 = EcdsaKeyPair::generate_pkcs8(&ECDSA_P256_SHA256_FIXED_SIGNING, &rng).unwrap();
203        let key_pair =
204            EcdsaKeyPair::from_pkcs8(&ECDSA_P256_SHA256_FIXED_SIGNING, pkcs8.as_ref()).unwrap();
205        let sec1_der = key_pair.private_key().as_der().unwrap();
206        let pem_obj = pem::Pem::new("EC PRIVATE KEY", sec1_der.as_ref().to_vec());
207        pem::encode(&pem_obj)
208    }
209
210    /// Generates a PKCS#8 PEM key.
211    fn test_pkcs8_pem_key() -> String {
212        let rng = lc_rand::SystemRandom::new();
213        let pkcs8 = EcdsaKeyPair::generate_pkcs8(&ECDSA_P256_SHA256_FIXED_SIGNING, &rng).unwrap();
214        let pem_obj = pem::Pem::new("PRIVATE KEY", pkcs8.as_ref().to_vec());
215        pem::encode(&pem_obj)
216    }
217
218    #[rstest]
219    fn test_credential_debug_redacts_secret() {
220        let cred = CoinbaseCredential::new(TEST_API_KEY.to_string(), "my_secret_pem".to_string());
221        let debug = format!("{cred:?}");
222        assert_eq!(debug.matches(REDACTED).count(), 2);
223        assert!(!debug.contains(TEST_API_KEY));
224        assert!(!debug.contains("my_secret_pem"));
225    }
226
227    #[rstest]
228    fn test_credential_display_redacts_key() {
229        let cred = CoinbaseCredential::new(TEST_API_KEY.to_string(), "my_secret_pem".to_string());
230        let display = format!("{cred}");
231        assert_eq!(display, "CoinbaseCredential(<redacted>)");
232        assert!(!display.contains(TEST_API_KEY));
233        assert!(!display.contains("my_secret_pem"));
234    }
235
236    #[rstest]
237    fn test_build_rest_jwt() {
238        let pem_key = test_sec1_pem_key();
239        let cred = CoinbaseCredential::new(TEST_API_KEY.to_string(), pem_key);
240        let jwt = cred.build_rest_jwt("GET api.coinbase.com/api/v3/brokerage/accounts");
241        assert!(jwt.is_ok());
242
243        let token = jwt.unwrap();
244        let parts: Vec<&str> = token.expose_secret().split('.').collect();
245        assert_eq!(parts.len(), 3, "JWT must have 3 parts");
246
247        // Decode and verify header
248        let header_bytes = BASE64_URL_SAFE_NO_PAD.decode(parts[0]).unwrap();
249        let header: serde_json::Value = serde_json::from_slice(&header_bytes).unwrap();
250        assert_eq!(header["alg"], "ES256");
251        assert_eq!(header["typ"], "JWT");
252        assert_eq!(header["kid"], TEST_API_KEY);
253        assert!(header["nonce"].is_string());
254
255        // Decode and verify payload
256        let payload_bytes = BASE64_URL_SAFE_NO_PAD.decode(parts[1]).unwrap();
257        let payload: serde_json::Value = serde_json::from_slice(&payload_bytes).unwrap();
258        assert_eq!(payload["sub"], TEST_API_KEY);
259        assert_eq!(payload["iss"], "cdp");
260        assert!(payload["nbf"].is_number());
261        assert!(payload["exp"].is_number());
262        assert!(payload["uri"].is_string());
263    }
264
265    #[rstest]
266    fn test_build_ws_jwt_has_no_uri() {
267        let pem_key = test_sec1_pem_key();
268        let cred = CoinbaseCredential::new(TEST_API_KEY.to_string(), pem_key);
269        let jwt = cred.build_ws_jwt();
270        assert!(jwt.is_ok());
271
272        let token = jwt.unwrap();
273        let parts: Vec<&str> = token.expose_secret().split('.').collect();
274        let payload_bytes = BASE64_URL_SAFE_NO_PAD.decode(parts[1]).unwrap();
275        let payload: serde_json::Value = serde_json::from_slice(&payload_bytes).unwrap();
276        assert!(payload.get("uri").is_none());
277    }
278
279    #[rstest]
280    fn test_build_jwt_with_pkcs8_pem() {
281        let pem_key = test_pkcs8_pem_key();
282        let cred = CoinbaseCredential::new(TEST_API_KEY.to_string(), pem_key);
283        let jwt = cred.build_rest_jwt("GET api.coinbase.com/api/v3/brokerage/accounts");
284        assert!(jwt.is_ok());
285    }
286
287    #[rstest]
288    fn test_build_jwt_invalid_pem_fails() {
289        let cred = CoinbaseCredential::new(TEST_API_KEY.to_string(), "not-a-pem-key".to_string());
290        let result = cred.build_rest_jwt("GET api.coinbase.com/test");
291        assert!(result.is_err());
292        assert!(result.unwrap_err().is_auth_error());
293    }
294
295    #[rstest]
296    #[case::invalid_header(false)]
297    #[case::mismatched_tags(true)]
298    fn test_build_jwt_pem_error_redacts_secret(
299        #[case] mismatched_tags: bool,
300        #[values(false, true)] websocket: bool,
301    ) {
302        let pem_key = test_sec1_pem_key().replace("\r\n", "\n");
303        let key_line = pem_key.lines().nth(1).unwrap();
304        let malformed_pem = if mismatched_tags {
305            pem_key.replace("END EC PRIVATE KEY", &format!("END {key_line}"))
306        } else {
307            pem_key.replacen(key_line, &format!("{key_line}\n"), 1)
308        };
309
310        let cred = CoinbaseCredential::new(TEST_API_KEY.to_string(), malformed_pem);
311        let error = if websocket {
312            cred.build_ws_jwt()
313        } else {
314            cred.build_rest_jwt("GET api.coinbase.com/api/v3/brokerage/accounts")
315        }
316        .unwrap_err();
317
318        assert_eq!(error.to_string(), "auth error: Failed to parse PEM key");
319        assert_eq!(format!("{error:?}"), "Auth(\"Failed to parse PEM key\")");
320        assert!(std::error::Error::source(&error).is_none());
321    }
322
323    #[rstest]
324    fn test_build_jwt_with_escaped_newline_pem() {
325        let pem_key = test_sec1_pem_key();
326
327        // Simulate the common env-var / .env-file pattern where real newlines
328        // are stored as literal two-char `\n` sequences.
329        let escaped = pem_key.replace('\n', "\\n");
330        assert!(
331            escaped.contains("\\n"),
332            "test setup: must have literal backslash-n"
333        );
334
335        let cred = CoinbaseCredential::new(TEST_API_KEY.to_string(), escaped);
336        let result = cred.build_rest_jwt("GET api.coinbase.com/api/v3/brokerage/accounts");
337        assert!(
338            result.is_ok(),
339            "escaped-newline PEM must parse after normalization"
340        );
341    }
342
343    #[rstest]
344    fn test_base64url_encode() {
345        let encoded = base64url_encode(b"hello world");
346        assert!(!encoded.contains('='));
347        assert!(!encoded.contains('+'));
348        assert!(!encoded.contains('/'));
349    }
350
351    #[rstest]
352    fn test_credential_env_vars_returns_canonical_pair() {
353        assert_eq!(
354            credential_env_vars(),
355            ("COINBASE_API_KEY", "COINBASE_API_SECRET"),
356        );
357    }
358
359    #[rstest]
360    fn test_credential_resolve_with_explicit_values() {
361        let cred = CoinbaseCredential::resolve(Some("explicit-key"), Some("explicit-secret"))
362            .expect("both explicit values must resolve");
363        assert_eq!(cred.api_key(), "explicit-key");
364        assert_eq!(cred.api_secret(), "explicit-secret");
365    }
366}