|
| 1 | +//! Shared pure contracts for relay invite links. |
| 2 | +//! |
| 3 | +//! The relay transport and database persistence layers both depend on |
| 4 | +//! `buzz-core`. Protocol constants and deterministic v2 code operations live |
| 5 | +//! here so neither layer becomes the accidental source of truth. |
| 6 | +
|
| 7 | +use base64::engine::general_purpose::URL_SAFE_NO_PAD; |
| 8 | +use base64::Engine as _; |
| 9 | +use sha2::{Digest, Sha256}; |
| 10 | + |
| 11 | +/// Minimum invite lifetime accepted by the mint API: 60 seconds. |
| 12 | +pub const MIN_INVITE_TTL_SECS: u64 = 60; |
| 13 | + |
| 14 | +/// Default invite lifetime when the mint request omits `ttl_secs`: 72 hours. |
| 15 | +pub const DEFAULT_INVITE_TTL_SECS: u64 = 72 * 60 * 60; |
| 16 | + |
| 17 | +/// Maximum invite lifetime accepted by the mint API: 30 days. |
| 18 | +pub const MAX_INVITE_TTL_SECS: u64 = 30 * 24 * 60 * 60; |
| 19 | + |
| 20 | +/// Maximum supported `max_uses` value. Matches the database constraint. |
| 21 | +pub const MAX_INVITE_USES: i32 = 10_000; |
| 22 | + |
| 23 | +/// Prefix that distinguishes v2 opaque database-backed codes from v1 tokens. |
| 24 | +pub const V2_PREFIX: &str = "v2."; |
| 25 | + |
| 26 | +/// Number of random bytes encoded in a v2 invite code. |
| 27 | +pub const V2_SECRET_LEN: usize = 32; |
| 28 | + |
| 29 | +/// A malformed v2 opaque invite code. |
| 30 | +#[derive(Debug, Clone, Copy, PartialEq, Eq)] |
| 31 | +pub struct InvalidV2InviteCode; |
| 32 | + |
| 33 | +/// Build a canonical v2 code from its random secret. |
| 34 | +pub fn encode_v2_code(secret: &[u8; V2_SECRET_LEN]) -> String { |
| 35 | + format!("{V2_PREFIX}{}", URL_SAFE_NO_PAD.encode(secret)) |
| 36 | +} |
| 37 | + |
| 38 | +/// Validate the canonical v2 opaque-code shape without consulting storage. |
| 39 | +/// |
| 40 | +/// A valid code is exactly `v2.` followed by the unpadded base64url encoding |
| 41 | +/// of a 32-byte secret. The decode/re-encode comparison rejects aliases such |
| 42 | +/// as padded or otherwise non-canonical encodings. |
| 43 | +pub fn validate_v2_code(code: &str) -> Result<(), InvalidV2InviteCode> { |
| 44 | + let encoded = code.strip_prefix(V2_PREFIX).ok_or(InvalidV2InviteCode)?; |
| 45 | + let secret = URL_SAFE_NO_PAD |
| 46 | + .decode(encoded) |
| 47 | + .map_err(|_| InvalidV2InviteCode)?; |
| 48 | + if secret.len() != V2_SECRET_LEN || URL_SAFE_NO_PAD.encode(&secret) != encoded { |
| 49 | + return Err(InvalidV2InviteCode); |
| 50 | + } |
| 51 | + Ok(()) |
| 52 | +} |
| 53 | + |
| 54 | +/// Hash the complete v2 code to the digest persisted by the database. |
| 55 | +pub fn hash_v2_code(code: &str) -> [u8; 32] { |
| 56 | + Sha256::digest(code.as_bytes()).into() |
| 57 | +} |
| 58 | + |
| 59 | +#[cfg(test)] |
| 60 | +mod tests { |
| 61 | + use super::*; |
| 62 | + |
| 63 | + #[test] |
| 64 | + fn v2_code_round_trip_is_canonical() { |
| 65 | + let secret = [7_u8; V2_SECRET_LEN]; |
| 66 | + let code = encode_v2_code(&secret); |
| 67 | + |
| 68 | + assert_eq!(validate_v2_code(&code), Ok(())); |
| 69 | + assert_eq!( |
| 70 | + code, |
| 71 | + format!("{V2_PREFIX}{}", URL_SAFE_NO_PAD.encode(secret)) |
| 72 | + ); |
| 73 | + } |
| 74 | + |
| 75 | + #[test] |
| 76 | + fn v2_validation_rejects_malformed_and_noncanonical_codes() { |
| 77 | + let valid = encode_v2_code(&[7_u8; V2_SECRET_LEN]); |
| 78 | + let short = format!( |
| 79 | + "{V2_PREFIX}{}", |
| 80 | + URL_SAFE_NO_PAD.encode([7_u8; V2_SECRET_LEN - 1]) |
| 81 | + ); |
| 82 | + |
| 83 | + for malformed in [ |
| 84 | + "v2.", |
| 85 | + "v2.not-base64!", |
| 86 | + short.as_str(), |
| 87 | + &format!("{valid}="), |
| 88 | + ] { |
| 89 | + assert_eq!( |
| 90 | + validate_v2_code(malformed), |
| 91 | + Err(InvalidV2InviteCode), |
| 92 | + "accepted malformed v2 code: {malformed}" |
| 93 | + ); |
| 94 | + } |
| 95 | + } |
| 96 | + |
| 97 | + #[test] |
| 98 | + fn v2_hash_covers_the_complete_code() { |
| 99 | + let code = encode_v2_code(&[7_u8; V2_SECRET_LEN]); |
| 100 | + |
| 101 | + let expected: [u8; 32] = Sha256::digest(code.as_bytes()).into(); |
| 102 | + |
| 103 | + assert_eq!(hash_v2_code(&code), expected); |
| 104 | + assert_ne!( |
| 105 | + hash_v2_code(&code), |
| 106 | + hash_v2_code(code.trim_start_matches(V2_PREFIX)) |
| 107 | + ); |
| 108 | + } |
| 109 | +} |
0 commit comments