aria2-rpc 0.3.2

Remote control server for aria2-rust: aria2-compatible JSON-RPC 2.0, XML-RPC, and WebSocket download management
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
//! RPC authentication: token + basic-auth configuration and middleware.

use crate::json_rpc::JsonRpcError;
use base64::Engine;
use hmac::{Hmac, Mac};
use rand::RngCore;
use sha2::Sha256;

#[derive(Debug, Clone, Default)]
pub struct AuthConfig {
    pub token: Option<String>,
    pub username: Option<String>,
    pub password: Option<String>,
}

impl AuthConfig {
    pub fn with_token(mut self, token: impl Into<String>) -> Self {
        self.token = Some(token.into());
        self
    }
    pub fn with_basic_auth(mut self, user: impl Into<String>, pass: impl Into<String>) -> Self {
        self.username = Some(user.into());
        let password = pass.into();
        // aria2_original resets its password verifier when --rpc-passwd is
        // empty, so an empty password means username-only authentication.
        self.password = (!password.is_empty()).then_some(password);
        self
    }

    pub fn has_token(&self) -> bool {
        self.token.is_some()
    }
    pub fn has_basic(&self) -> bool {
        self.username
            .as_deref()
            .is_some_and(|username| !username.is_empty())
    }

    pub fn verify_token(&self, provided: &str) -> bool {
        match &self.token {
            None => true,
            Some(t) => constant_time_eq(t, provided),
        }
    }

    pub fn verify_basic(&self, encoded: &str) -> bool {
        let decoded = base64_decode(encoded).unwrap_or_default();
        let Some((user, pass)) = decoded.split_once(':') else {
            return false;
        };

        let username_matches = self
            .username
            .as_deref()
            .is_some_and(|expected| constant_time_eq(expected, user));
        let password_matches = match self.password.as_deref() {
            Some(expected) if !expected.is_empty() => constant_time_eq(expected, pass),
            // aria2 accepts username-only Basic Auth when --rpc-passwd is not
            // configured. An explicitly empty password has the same meaning
            // because the original option handler treats it as unset.
            None => true,
            Some(_) => true,
        };
        username_matches && password_matches
    }

    /// Validate an HTTP `Authorization` header using aria2's Basic scheme.
    ///
    /// The authentication scheme is case-insensitive per HTTP, while the
    /// base64 payload is decoded strictly using the standard alphabet.
    pub fn verify_authorization(&self, header: Option<&str>) -> bool {
        let Some(header) = header else {
            return false;
        };
        let Some((scheme, encoded)) = header.trim().split_once(' ') else {
            return false;
        };
        scheme.eq_ignore_ascii_case("Basic") && self.verify_basic(encoded.trim())
    }
}

fn base64_decode(s: &str) -> Result<String, String> {
    let bytes = base64::engine::general_purpose::STANDARD
        .decode(s)
        .map_err(|error| error.to_string())?;
    String::from_utf8(bytes).map_err(|error| error.to_string())
}

/// Constant-time string equality check (mitigates timing side-channels).
///
/// Used to compare secret values such as the RPC token (`rpc-secret`) against
/// user-supplied input. Unlike `a == b` — which short-circuits on the first
/// differing byte and whose timing therefore reveals the match position — this
/// always iterates over `max(a.len(), b.len())` bytes and accumulates the XOR
/// of every byte pair, so the timing is independent of *where* the first
/// mismatch occurs.
///
/// # Limitations
///
/// Length differences are still observable (a shorter/longer token completes
/// the loop in fewer/more iterations). This is an accepted trade-off: the
/// length of an `rpc-secret` is not high-value entropy, and an
/// attacker-controlled length probe is mitigated by the constant per-byte
/// cost. If length privacy is ever required, the secret must be hashed first.
fn constant_time_eq_bytes(a: &[u8], b: &[u8]) -> bool {
    let mut diff = a.len() ^ b.len();
    for i in 0..a.len().max(b.len()) {
        diff |= usize::from(a.get(i).copied().unwrap_or(0) ^ b.get(i).copied().unwrap_or(0));
    }
    diff == 0
}

fn constant_time_eq(a: &str, b: &str) -> bool {
    let a = a.as_bytes();
    let b = b.as_bytes();
    // 0 iff lengths are equal; stays 0 iff every byte pair XORs to 0.
    let mut diff = a.len() ^ b.len();
    for i in 0..a.len().max(b.len()) {
        let ai = *a.get(i).unwrap_or(&0u8);
        let bi = *b.get(i).unwrap_or(&0u8);
        diff |= usize::from(ai ^ bi);
    }
    diff == 0
}

// =========================================================================
// RPC Authentication Middleware (G4 Part B)
// =========================================================================

/// Middleware for token-based RPC authorization.
///
/// Validates that incoming JSON-RPC requests include a valid secret token
/// when `rpc-secret` is configured. An empty/absent secret means auth is
/// disabled and all requests are accepted.
///
/// The token is extracted from the `token` parameter in each request's params.
type RpcHmac = Hmac<Sha256>;

pub struct RpcAuthMiddleware {
    /// Secret token for authorization. Empty string = no auth required.
    secret: String,
    /// Random HMAC key and digest of the configured secret, matching C++.
    hmac_key: Option<Vec<u8>>,
    expected: Option<Vec<u8>>,
}

impl RpcAuthMiddleware {
    /// Create a new authentication middleware with the given secret.
    ///
    /// # Arguments
    ///
    /// * `secret` - The RPC secret token. Pass empty string to disable auth.
    pub fn new(secret: &str) -> Self {
        let (hmac_key, expected) = if secret.is_empty() {
            (None, None)
        } else {
            let mut key = vec![0u8; 32];
            rand::thread_rng().fill_bytes(&mut key);
            let mut mac =
                RpcHmac::new_from_slice(&key).expect("HMAC-SHA256 accepts keys of every length");
            mac.update(secret.as_bytes());
            (Some(key), Some(mac.finalize().into_bytes().to_vec()))
        };
        Self {
            secret: secret.to_string(),
            hmac_key,
            expected,
        }
    }

    /// Validate a JSON-RPC request's token parameter.
    ///
    /// Returns `Ok(())` if authentication passes, `Err(JsonRpcError::Unauthorized)` if it fails.
    ///
    /// # Behavior
    ///
    /// - If no secret is configured (empty string) → always returns `Ok(())`
    /// - If token matches the secret → returns `Ok(())`
    /// - If token is provided but wrong → returns `Err(Unauthorized("Invalid token"))`
    /// - If no token provided but secret is set → returns `Err(Unauthorized("Token required"))`
    pub fn validate(&self, token: Option<&str>) -> Result<(), JsonRpcError> {
        // No auth configured — accept all requests
        if self.secret.is_empty() {
            return Ok(());
        }
        match token {
            Some(t) if self.verify_hmac(t) => Ok(()),
            Some(_) => Err(JsonRpcError::Unauthorized("Invalid token".to_string())),
            None => Err(JsonRpcError::Unauthorized(
                "Token required (set rpc-secret)".to_string(),
            )),
        }
    }

    fn verify_hmac(&self, token: &str) -> bool {
        let (Some(key), Some(expected)) = (&self.hmac_key, &self.expected) else {
            return false;
        };
        let mut mac = RpcHmac::new_from_slice(key).expect("valid HMAC key");
        mac.update(token.as_bytes());
        constant_time_eq_bytes(expected, mac.finalize().into_bytes().as_ref())
    }

    /// Returns true if authentication is enabled (non-empty secret).
    pub fn is_auth_enabled(&self) -> bool {
        !self.secret.is_empty()
    }

    /// Returns a reference to the configured secret (for testing/debugging only).
    #[allow(dead_code)] // Testing/debugging accessor; used in tests only
    pub fn secret(&self) -> &str {
        &self.secret
    }
}

impl Default for RpcAuthMiddleware {
    fn default() -> Self {
        Self::new("")
    }
}

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

    #[test]
    fn test_auth_config_default() {
        let auth = AuthConfig::default();
        assert!(!auth.has_token());
        assert!(!auth.has_basic());
        assert!(auth.verify_token(""));
    }

    #[test]
    fn test_auth_config_token() {
        let auth = AuthConfig::default().with_token("my-secret");
        assert!(auth.has_token());
        assert!(auth.verify_token("my-secret"));
        assert!(!auth.verify_token("wrong"));
    }

    #[test]
    fn test_constant_time_eq() {
        // Equal strings → true
        assert!(constant_time_eq("", ""));
        assert!(constant_time_eq("my-secret", "my-secret"));
        assert!(constant_time_eq(
            "rpc-secret-token-123",
            "rpc-secret-token-123"
        ));

        // Same-length, different bytes → false
        assert!(!constant_time_eq("secret", "secretX")); // no, lengths differ
        assert!(!constant_time_eq("aaaaaa", "aaaaba")); // last byte differs
        assert!(!constant_time_eq("baaaaa", "aaaaaa")); // first byte differs
        assert!(!constant_time_eq("abcdef", "fedcba"));

        // Different-length inputs → false (including prefix relations)
        assert!(!constant_time_eq("abc", "abcd"));
        assert!(!constant_time_eq("abcd", "abc"));
        assert!(!constant_time_eq("", "x"));
        assert!(!constant_time_eq("x", ""));
        assert!(!constant_time_eq("my-secret", "my-secret-extra"));
    }

    #[test]
    fn test_auth_config_token_constant_time() {
        let auth = AuthConfig::default().with_token("s3cr3t-tok3n");
        // Exact match → accept
        assert!(auth.verify_token("s3cr3t-tok3n"));
        // Same-length wrong token → reject
        assert!(!auth.verify_token("s3cr3t-tok3m"));
        assert!(!auth.verify_token("X3cr3t-tok3n"));
        // Different-length token → reject
        assert!(!auth.verify_token("s3cr3t"));
        assert!(!auth.verify_token("s3cr3t-tok3n-extra"));
        assert!(!auth.verify_token(""));
        // Unrelated
        assert!(!auth.verify_token("not-the-token"));
    }

    #[test]
    fn test_auth_config_basic() {
        let auth = AuthConfig::default().with_basic_auth("admin", "pass123");
        assert!(auth.has_basic());
        let encoded = base64::engine::general_purpose::STANDARD.encode(b"admin:pass123");
        assert!(auth.verify_basic(&encoded));
        assert!(auth.verify_authorization(Some(&format!("Basic {encoded}"))));
        assert!(auth.verify_authorization(Some(&format!("basic {encoded}"))));
        assert!(
            !auth.verify_basic(
                base64::engine::general_purpose::STANDARD
                    .encode(b"admin:wrong")
                    .as_str()
            )
        );
        assert!(!auth.verify_authorization(None));
        assert!(!auth.verify_authorization(Some("Bearer token")));
    }

    #[test]
    fn test_auth_config_username_only_basic_auth() {
        let auth = AuthConfig {
            username: Some("admin".into()),
            password: None,
            ..AuthConfig::default()
        };
        let encoded = base64::engine::general_purpose::STANDARD.encode(b"admin:anything");
        assert!(auth.has_basic());
        assert!(auth.verify_basic(&encoded));
    }

    #[test]
    fn test_auth_config_empty_password_matches_username_only_behavior() {
        let auth = AuthConfig::default().with_basic_auth("admin", "");
        assert!(auth.has_basic());
        assert!(auth.password.is_none());

        for credentials in ["admin:anything", "admin:"] {
            let encoded = base64::engine::general_purpose::STANDARD.encode(credentials);
            assert!(auth.verify_basic(&encoded), "credentials: {credentials}");
        }

        // Config structs can also be built directly; preserve the same
        // original semantics for an explicitly empty password field.
        let explicit_empty = AuthConfig {
            username: Some("admin".into()),
            password: Some(String::new()),
            ..AuthConfig::default()
        };
        let encoded = base64::engine::general_purpose::STANDARD.encode("admin:anything");
        assert!(explicit_empty.verify_basic(&encoded));
    }

    #[test]
    fn test_auth_valid_token_passes() {
        let middleware = RpcAuthMiddleware::new("my-secret-token");
        // Valid token should pass
        assert!(middleware.validate(Some("my-secret-token")).is_ok());
    }

    #[test]
    fn test_auth_wrong_token_rejected() {
        let middleware = RpcAuthMiddleware::new("my-secret-token");
        let result = middleware.validate(Some("wrong-token"));
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert_eq!(err.code(), 1);
        assert!(err.to_string().contains("Invalid token"));
    }

    #[test]
    fn test_auth_token_constant_time_validate() {
        let middleware = RpcAuthMiddleware::new("my-secret-token");
        // Exact match → accept
        assert!(middleware.validate(Some("my-secret-token")).is_ok());
        // Same-length wrong token → reject
        assert!(middleware.validate(Some("my-secret-tokem")).is_err());
        assert!(middleware.validate(Some("nY-secret-token")).is_err());
        // Different-length token → reject (shorter and longer)
        assert!(middleware.validate(Some("my-secret")).is_err());
        assert!(middleware.validate(Some("my-secret-token-extra")).is_err());
        assert!(middleware.validate(Some("")).is_err());
        // No token with a configured secret → reject with "Token required"
        let err = middleware.validate(None).unwrap_err();
        assert!(err.to_string().contains("Token required"));
    }

    #[test]
    fn test_auth_no_secret_configured_accepts_all() {
        let middleware = RpcAuthMiddleware::new(""); // Empty secret = no auth
        // All should pass when no secret is configured
        assert!(middleware.validate(None).is_ok());
        assert!(middleware.validate(Some("anything")).is_ok());
        assert!(middleware.validate(Some("")).is_ok());
        assert!(
            !middleware.is_auth_enabled(),
            "Auth should be disabled with empty secret"
        );
    }

    #[test]
    fn test_auth_token_required_when_secret_set() {
        let middleware = RpcAuthMiddleware::new("secret123");
        // No token provided but secret is set → should fail
        let result = middleware.validate(None);
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert_eq!(err.code(), 1);
        assert!(err.to_string().contains("Token required"));
        assert!(
            middleware.is_auth_enabled(),
            "Auth should be enabled with non-empty secret"
        );
    }

    #[test]
    fn test_auth_middleware_default() {
        let middleware = RpcAuthMiddleware::default();
        assert!(!middleware.is_auth_enabled());
        assert!(middleware.validate(None).is_ok());
        assert!(middleware.validate(Some("x")).is_ok());
    }

    #[test]
    fn test_auth_middleware_secret_accessor() {
        let middleware = RpcAuthMiddleware::new("test-secret");
        assert_eq!(middleware.secret(), "test-secret");
    }
}