nautilus_coinbase/common/
credential.rs1use 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#[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#[derive(Clone, Zeroize, ZeroizeOnDrop)]
47pub struct CoinbaseCredential {
48 api_key: String,
49 api_secret: String,
50}
51
52impl CoinbaseCredential {
53 pub fn new(api_key: String, api_secret: String) -> Self {
55 Self {
56 api_key,
57 api_secret,
58 }
59 }
60
61 #[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 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 pub fn api_key(&self) -> &str {
93 &self.api_key
94 }
95
96 pub fn api_secret(&self) -> &str {
98 &self.api_secret
99 }
100
101 pub fn build_rest_jwt(&self, uri: &str) -> Result<SecretString> {
106 self.build_jwt(Some(uri))
107 }
108
109 pub fn build_ws_jwt(&self) -> Result<SecretString> {
111 self.build_jwt(None)
112 }
113
114 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 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 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 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 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 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 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 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}