Skip to main content

yaiko_core/
api_keys.rs

1//! Scoped API keys and signed-request authentication primitives.
2
3use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
4use hmac::{Hmac, Mac};
5use sha2::{Digest, Sha256};
6use std::collections::BTreeSet;
7use std::sync::{Arc, Mutex};
8use std::time::{Duration, SystemTime, UNIX_EPOCH};
9use uuid::Uuid;
10
11type HmacSha256 = Hmac<Sha256>;
12
13#[derive(Debug, Clone, PartialEq, Eq)]
14pub struct IssuedApiKey {
15    pub id: String,
16    pub secret: String,
17}
18
19#[derive(Debug, Clone)]
20struct ApiKeyRecord {
21    secret_digest: Vec<u8>,
22    scopes: BTreeSet<String>,
23    active: bool,
24    expires_at: Option<u64>,
25}
26
27#[derive(Debug, Clone, PartialEq, Eq)]
28pub enum ApiKeyError {
29    Invalid,
30    NotFound,
31    Inactive,
32    Expired,
33    MissingScope,
34    InvalidSignature,
35    StaleRequest,
36}
37
38#[derive(Clone, Default)]
39pub struct ApiKeyStore {
40    keys: Arc<Mutex<std::collections::BTreeMap<String, ApiKeyRecord>>>,
41}
42
43impl ApiKeyStore {
44    pub fn new() -> Self {
45        Self::default()
46    }
47
48    pub fn issue(&self, scopes: Vec<String>, ttl: Option<Duration>) -> IssuedApiKey {
49        let id = Uuid::new_v4().to_string();
50        let secret = Uuid::new_v4().to_string() + &Uuid::new_v4().to_string();
51        let expires_at = ttl.map(|duration| now().saturating_add(duration.as_secs()));
52        let record = ApiKeyRecord {
53            secret_digest: digest_secret(&secret),
54            scopes: scopes.into_iter().collect(),
55            active: true,
56            expires_at,
57        };
58        self.keys
59            .lock()
60            .expect("api-key store poisoned")
61            .insert(id.clone(), record);
62        IssuedApiKey { id, secret }
63    }
64
65    pub fn revoke(&self, id: &str) -> Result<(), ApiKeyError> {
66        let mut keys = self.keys.lock().expect("api-key store poisoned");
67        let record = keys.get_mut(id).ok_or(ApiKeyError::NotFound)?;
68        record.active = false;
69        Ok(())
70    }
71
72    pub fn rotate(&self, id: &str, ttl: Option<Duration>) -> Result<IssuedApiKey, ApiKeyError> {
73        self.revoke(id)?;
74        Ok(self.issue(Vec::new(), ttl))
75    }
76
77    pub fn authenticate(
78        &self,
79        id: &str,
80        secret: &str,
81        scope: Option<&str>,
82    ) -> Result<(), ApiKeyError> {
83        let keys = self.keys.lock().expect("api-key store poisoned");
84        let record = keys.get(id).ok_or(ApiKeyError::NotFound)?;
85        if !record.active {
86            return Err(ApiKeyError::Inactive);
87        }
88        if record
89            .expires_at
90            .map(|expires| now() >= expires)
91            .unwrap_or(false)
92        {
93            return Err(ApiKeyError::Expired);
94        }
95        verify_digest(&record.secret_digest, secret)
96            .then_some(())
97            .ok_or(ApiKeyError::Invalid)?;
98        if scope
99            .map(|scope| !record.scopes.contains(scope))
100            .unwrap_or(false)
101        {
102            return Err(ApiKeyError::MissingScope);
103        }
104        Ok(())
105    }
106}
107
108pub fn sign_request(secret: &str, timestamp: u64, method: &str, path: &str, body: &[u8]) -> String {
109    let mut mac =
110        HmacSha256::new_from_slice(secret.as_bytes()).expect("HMAC accepts arbitrary key sizes");
111    mac.update(format!("{}.{}.{}.", timestamp, method.to_ascii_uppercase(), path).as_bytes());
112    mac.update(&Sha256::digest(body));
113    URL_SAFE_NO_PAD.encode(mac.finalize().into_bytes())
114}
115
116pub fn verify_request_signature(
117    secret: &str,
118    timestamp: u64,
119    signature: &str,
120    method: &str,
121    path: &str,
122    body: &[u8],
123    tolerance: Duration,
124) -> Result<(), ApiKeyError> {
125    if now().abs_diff(timestamp) > tolerance.as_secs() {
126        return Err(ApiKeyError::StaleRequest);
127    }
128    let expected = sign_request(secret, timestamp, method, path, body);
129    let mut mac =
130        HmacSha256::new_from_slice(secret.as_bytes()).expect("HMAC accepts arbitrary key sizes");
131    mac.update(format!("{}.{}.{}.", timestamp, method.to_ascii_uppercase(), path).as_bytes());
132    mac.update(&Sha256::digest(body));
133    mac.verify_slice(
134        &URL_SAFE_NO_PAD
135            .decode(signature)
136            .map_err(|_| ApiKeyError::InvalidSignature)?,
137    )
138    .map_err(|_| {
139        let _ = expected;
140        ApiKeyError::InvalidSignature
141    })
142}
143
144fn digest_secret(secret: &str) -> Vec<u8> {
145    let mut mac = HmacSha256::new_from_slice(b"yaiko-api-key-digest")
146        .expect("HMAC accepts arbitrary key sizes");
147    mac.update(secret.as_bytes());
148    mac.finalize().into_bytes().to_vec()
149}
150
151fn verify_digest(expected: &[u8], secret: &str) -> bool {
152    let mut mac = HmacSha256::new_from_slice(b"yaiko-api-key-digest")
153        .expect("HMAC accepts arbitrary key sizes");
154    mac.update(secret.as_bytes());
155    mac.verify_slice(expected).is_ok()
156}
157
158fn now() -> u64 {
159    SystemTime::now()
160        .duration_since(UNIX_EPOCH)
161        .unwrap_or_default()
162        .as_secs()
163}
164
165#[cfg(test)]
166mod tests {
167    use super::*;
168
169    #[test]
170    fn issues_scoped_keys_and_rejects_wrong_scope_or_secret() {
171        let store = ApiKeyStore::new();
172        let key = store.issue(vec!["video:read".to_string()], None);
173        assert!(store
174            .authenticate(&key.id, &key.secret, Some("video:read"))
175            .is_ok());
176        assert_eq!(
177            store.authenticate(&key.id, &key.secret, Some("video:write")),
178            Err(ApiKeyError::MissingScope)
179        );
180        assert_eq!(
181            store.authenticate(&key.id, "wrong", None),
182            Err(ApiKeyError::Invalid)
183        );
184    }
185
186    #[test]
187    fn revocation_and_rotation_invalidate_old_credentials() {
188        let store = ApiKeyStore::new();
189        let key = store.issue(Vec::new(), None);
190        store.revoke(&key.id).unwrap();
191        assert_eq!(
192            store.authenticate(&key.id, &key.secret, None),
193            Err(ApiKeyError::Inactive)
194        );
195        let rotated = store.rotate(&key.id, None).unwrap();
196        assert_ne!(key.secret, rotated.secret);
197        assert!(store
198            .authenticate(&rotated.id, &rotated.secret, None)
199            .is_ok());
200    }
201
202    #[test]
203    fn signs_and_verifies_requests_with_timestamp_tolerance() {
204        let timestamp = now();
205        let signature = sign_request("secret", timestamp, "post", "/videos", b"payload");
206        assert!(verify_request_signature(
207            "secret",
208            timestamp,
209            &signature,
210            "POST",
211            "/videos",
212            b"payload",
213            Duration::from_secs(30)
214        )
215        .is_ok());
216        assert_eq!(
217            verify_request_signature(
218                "secret",
219                timestamp,
220                "00",
221                "POST",
222                "/videos",
223                b"payload",
224                Duration::from_secs(30)
225            ),
226            Err(ApiKeyError::InvalidSignature)
227        );
228        assert_eq!(
229            verify_request_signature(
230                "secret",
231                timestamp.saturating_sub(100),
232                &signature,
233                "POST",
234                "/videos",
235                b"payload",
236                Duration::from_secs(30)
237            ),
238            Err(ApiKeyError::StaleRequest)
239        );
240    }
241}