Skip to main content

auth_framework/protocols/
siwe.rs

1//! Sign-In with Ethereum (SIWE / ERC-4361) support.
2//!
3//! Provides message construction, parsing, and validation for the
4//! ERC-4361 standard which allows Ethereum account holders to authenticate
5//! with off-chain services by signing a structured message.
6//!
7//! # References
8//!
9//! - [ERC-4361: Sign-In with Ethereum](https://eips.ethereum.org/EIPS/eip-4361)
10
11use crate::errors::{AuthError, Result};
12use chrono::{DateTime, Utc};
13use serde::{Deserialize, Serialize};
14use sha2::{Digest, Sha256};
15
16/// A SIWE message conforming to ERC-4361.
17#[derive(Debug, Clone, Serialize, Deserialize)]
18pub struct SiweMessage {
19    /// RFC 4501 `dns` authority (e.g., "example.com").
20    pub domain: String,
21    /// Ethereum address performing the signing (EIP-55 mixed-case).
22    pub address: String,
23    /// Human-readable statement (optional).
24    pub statement: Option<String>,
25    /// RFC 3986 URI for the signing request.
26    pub uri: String,
27    /// EIP-155 Chain ID (1 = mainnet).
28    pub chain_id: u64,
29    /// Random nonce to prevent replay attacks.
30    pub nonce: String,
31    /// ISO 8601 datetime when the message was issued.
32    pub issued_at: DateTime<Utc>,
33    /// ISO 8601 datetime when the message expires (optional).
34    pub expiration_time: Option<DateTime<Utc>>,
35    /// ISO 8601 datetime before which the message is not valid (optional).
36    pub not_before: Option<DateTime<Utc>>,
37    /// System-specific request ID (optional).
38    pub request_id: Option<String>,
39    /// List of resources the user wishes to access (optional).
40    pub resources: Vec<String>,
41    /// ERC-4361 version ("1").
42    pub version: String,
43}
44
45impl SiweMessage {
46    /// Create a new SIWE message with required fields.
47    pub fn new(domain: &str, address: &str, uri: &str, chain_id: u64) -> Result<Self> {
48        validate_address(address)?;
49        if domain.is_empty() {
50            return Err(AuthError::validation("Domain cannot be empty"));
51        }
52        if uri.is_empty() {
53            return Err(AuthError::validation("URI cannot be empty"));
54        }
55        let nonce = generate_nonce()?;
56        Ok(Self {
57            domain: domain.to_string(),
58            address: address.to_string(),
59            statement: None,
60            uri: uri.to_string(),
61            chain_id,
62            nonce,
63            issued_at: Utc::now(),
64            expiration_time: None,
65            not_before: None,
66            request_id: None,
67            resources: Vec::new(),
68            version: "1".to_string(),
69        })
70    }
71
72    /// Render the SIWE message to the ERC-4361 plaintext signing format.
73    pub fn to_message_string(&self) -> String {
74        let mut msg = format!(
75            "{domain} wants you to sign in with your Ethereum account:\n\
76             {address}\n",
77            domain = self.domain,
78            address = self.address,
79        );
80
81        if let Some(ref stmt) = self.statement {
82            msg.push('\n');
83            msg.push_str(stmt);
84            msg.push('\n');
85        }
86
87        msg.push_str(&format!(
88            "\nURI: {uri}\n\
89             Version: {ver}\n\
90             Chain ID: {chain}\n\
91             Nonce: {nonce}\n\
92             Issued At: {iat}",
93            uri = self.uri,
94            ver = self.version,
95            chain = self.chain_id,
96            nonce = self.nonce,
97            iat = self.issued_at.to_rfc3339(),
98        ));
99
100        if let Some(ref exp) = self.expiration_time {
101            msg.push_str(&format!("\nExpiration Time: {}", exp.to_rfc3339()));
102        }
103        if let Some(ref nb) = self.not_before {
104            msg.push_str(&format!("\nNot Before: {}", nb.to_rfc3339()));
105        }
106        if let Some(ref rid) = self.request_id {
107            msg.push_str(&format!("\nRequest ID: {}", rid));
108        }
109        if !self.resources.is_empty() {
110            msg.push_str("\nResources:");
111            for r in &self.resources {
112                msg.push_str(&format!("\n- {}", r));
113            }
114        }
115
116        msg
117    }
118
119    /// Compute the EIP-191 hash of the message (SHA-256 for verification).
120    pub fn message_hash(&self) -> [u8; 32] {
121        let msg = self.to_message_string();
122        let prefixed = format!("\x19Ethereum Signed Message:\n{}{}", msg.len(), msg);
123        Sha256::digest(prefixed.as_bytes()).into()
124    }
125}
126
127/// Parse a SIWE plaintext message string back into a `SiweMessage`.
128pub fn parse_siwe_message(text: &str) -> Result<SiweMessage> {
129    let lines: Vec<&str> = text.lines().collect();
130
131    if lines.len() < 7 {
132        return Err(AuthError::validation("SIWE message has too few lines"));
133    }
134
135    // Line 0: "{domain} wants you to sign in with your Ethereum account:"
136    let domain = lines[0]
137        .strip_suffix(" wants you to sign in with your Ethereum account:")
138        .ok_or_else(|| AuthError::validation("Missing SIWE preamble"))?
139        .to_string();
140
141    // Line 1: address
142    let address = lines[1].trim().to_string();
143    validate_address(&address)?;
144
145    // Find field lines
146    let mut statement = None;
147    let mut uri = String::new();
148    let mut version = String::new();
149    let mut chain_id: u64 = 1;
150    let mut nonce = String::new();
151    let mut issued_at = Utc::now();
152    let mut expiration_time = None;
153    let mut not_before = None;
154    let mut request_id = None;
155    let mut resources = Vec::new();
156    let mut in_resources = false;
157
158    for line in &lines[2..] {
159        let line = line.trim();
160        if line.is_empty() {
161            continue;
162        }
163        if in_resources {
164            if let Some(r) = line.strip_prefix("- ") {
165                resources.push(r.to_string());
166                continue;
167            }
168            in_resources = false;
169        }
170
171        if let Some(v) = line.strip_prefix("URI: ") {
172            uri = v.to_string();
173        } else if let Some(v) = line.strip_prefix("Version: ") {
174            version = v.to_string();
175        } else if let Some(v) = line.strip_prefix("Chain ID: ") {
176            chain_id = v.parse().unwrap_or(1);
177        } else if let Some(v) = line.strip_prefix("Nonce: ") {
178            nonce = v.to_string();
179        } else if let Some(v) = line.strip_prefix("Issued At: ") {
180            issued_at = DateTime::parse_from_rfc3339(v)
181                .map(|dt| dt.with_timezone(&Utc))
182                .unwrap_or_else(|_| Utc::now());
183        } else if let Some(v) = line.strip_prefix("Expiration Time: ") {
184            expiration_time = DateTime::parse_from_rfc3339(v)
185                .map(|dt| dt.with_timezone(&Utc))
186                .ok();
187        } else if let Some(v) = line.strip_prefix("Not Before: ") {
188            not_before = DateTime::parse_from_rfc3339(v)
189                .map(|dt| dt.with_timezone(&Utc))
190                .ok();
191        } else if let Some(v) = line.strip_prefix("Request ID: ") {
192            request_id = Some(v.to_string());
193        } else if line == "Resources:" {
194            in_resources = true;
195        } else if statement.is_none() && !line.starts_with("URI:") && !line.starts_with("Version:")
196        {
197            statement = Some(line.to_string());
198        }
199    }
200
201    Ok(SiweMessage {
202        domain,
203        address,
204        statement,
205        uri,
206        chain_id,
207        nonce,
208        issued_at,
209        expiration_time,
210        not_before,
211        request_id,
212        resources,
213        version,
214    })
215}
216
217/// Verify the SIWE message fields are valid (time constraints, nonce, etc.).
218///
219/// **Note:** Signature verification against the Ethereum address requires
220/// an ECC library (secp256k1). This function validates the message structure
221/// and time windows only.
222pub fn verify_siwe_message(
223    msg: &SiweMessage,
224    expected_domain: &str,
225    expected_nonce: Option<&str>,
226) -> Result<()> {
227    if msg.domain != expected_domain {
228        return Err(AuthError::validation("Domain mismatch"));
229    }
230
231    if let Some(expected) = expected_nonce
232        && msg.nonce != expected
233    {
234        return Err(AuthError::validation("Nonce mismatch"));
235    }
236
237    let now = Utc::now();
238    if let Some(ref exp) = msg.expiration_time
239        && &now > exp
240    {
241        return Err(AuthError::validation("SIWE message has expired"));
242    }
243    if let Some(ref nb) = msg.not_before
244        && &now < nb
245    {
246        return Err(AuthError::validation("SIWE message is not yet valid"));
247    }
248
249    validate_address(&msg.address)?;
250
251    Ok(())
252}
253
254/// Basic Ethereum address validation (EIP-55 format: 0x + 40 hex chars).
255fn validate_address(address: &str) -> Result<()> {
256    if !address.starts_with("0x") || address.len() != 42 {
257        return Err(AuthError::validation(
258            "Invalid Ethereum address: must be 0x followed by 40 hex characters",
259        ));
260    }
261    if !address[2..].chars().all(|c| c.is_ascii_hexdigit()) {
262        return Err(AuthError::validation(
263            "Invalid Ethereum address: contains non-hex characters",
264        ));
265    }
266    Ok(())
267}
268
269/// Generate a cryptographically random 16-byte nonce (hex-encoded).
270fn generate_nonce() -> Result<String> {
271    use ring::rand::{SecureRandom, SystemRandom};
272    let rng = SystemRandom::new();
273    let mut buf = [0u8; 16];
274    rng.fill(&mut buf)
275        .map_err(|_| AuthError::crypto("Failed to generate nonce".to_string()))?;
276    Ok(hex::encode(buf))
277}
278
279#[cfg(test)]
280mod tests {
281    use super::*;
282    use chrono::Duration;
283
284    const TEST_ADDR: &str = "0xAb5801a7D398351b8bE11C439e05C5b3259aec9B";
285
286    #[test]
287    fn test_create_siwe_message() {
288        let msg =
289            SiweMessage::new("example.com", TEST_ADDR, "https://example.com/login", 1).unwrap();
290        assert_eq!(msg.domain, "example.com");
291        assert_eq!(msg.address, TEST_ADDR);
292        assert_eq!(msg.version, "1");
293        assert_eq!(msg.chain_id, 1);
294        assert!(!msg.nonce.is_empty());
295    }
296
297    #[test]
298    fn test_empty_domain_rejected() {
299        assert!(SiweMessage::new("", TEST_ADDR, "https://example.com", 1).is_err());
300    }
301
302    #[test]
303    fn test_invalid_address_rejected() {
304        assert!(
305            SiweMessage::new("example.com", "not-an-address", "https://example.com", 1).is_err()
306        );
307        assert!(SiweMessage::new("example.com", "0xZZZZ", "https://example.com", 1).is_err());
308    }
309
310    #[test]
311    fn test_message_string_format() {
312        let msg =
313            SiweMessage::new("example.com", TEST_ADDR, "https://example.com/login", 1).unwrap();
314        let text = msg.to_message_string();
315        assert!(text.contains("example.com wants you to sign in with your Ethereum account:"));
316        assert!(text.contains(TEST_ADDR));
317        assert!(text.contains("URI: https://example.com/login"));
318        assert!(text.contains("Version: 1"));
319        assert!(text.contains("Chain ID: 1"));
320        assert!(text.contains("Nonce: "));
321    }
322
323    #[test]
324    fn test_message_string_with_statement() {
325        let mut msg = SiweMessage::new("example.com", TEST_ADDR, "https://example.com", 1).unwrap();
326        msg.statement = Some("I accept the Terms of Service".to_string());
327        let text = msg.to_message_string();
328        assert!(text.contains("I accept the Terms of Service"));
329    }
330
331    #[test]
332    fn test_message_string_with_resources() {
333        let mut msg = SiweMessage::new("example.com", TEST_ADDR, "https://example.com", 1).unwrap();
334        msg.resources = vec![
335            "https://example.com/resource1".to_string(),
336            "https://example.com/resource2".to_string(),
337        ];
338        let text = msg.to_message_string();
339        assert!(text.contains("Resources:"));
340        assert!(text.contains("- https://example.com/resource1"));
341        assert!(text.contains("- https://example.com/resource2"));
342    }
343
344    #[test]
345    fn test_parse_siwe_message_roundtrip() {
346        let msg =
347            SiweMessage::new("example.com", TEST_ADDR, "https://example.com/login", 1).unwrap();
348        let text = msg.to_message_string();
349        let parsed = parse_siwe_message(&text).unwrap();
350        assert_eq!(parsed.domain, "example.com");
351        assert_eq!(parsed.address, TEST_ADDR);
352        assert_eq!(parsed.uri, "https://example.com/login");
353        assert_eq!(parsed.chain_id, 1);
354        assert_eq!(parsed.nonce, msg.nonce);
355    }
356
357    #[test]
358    fn test_verify_valid_message() {
359        let msg = SiweMessage::new("example.com", TEST_ADDR, "https://example.com", 1).unwrap();
360        let nonce = msg.nonce.clone();
361        verify_siwe_message(&msg, "example.com", Some(&nonce)).unwrap();
362    }
363
364    #[test]
365    fn test_verify_domain_mismatch() {
366        let msg = SiweMessage::new("example.com", TEST_ADDR, "https://example.com", 1).unwrap();
367        assert!(verify_siwe_message(&msg, "other.com", None).is_err());
368    }
369
370    #[test]
371    fn test_verify_nonce_mismatch() {
372        let msg = SiweMessage::new("example.com", TEST_ADDR, "https://example.com", 1).unwrap();
373        assert!(verify_siwe_message(&msg, "example.com", Some("wrong-nonce")).is_err());
374    }
375
376    #[test]
377    fn test_verify_expired_message() {
378        let mut msg = SiweMessage::new("example.com", TEST_ADDR, "https://example.com", 1).unwrap();
379        msg.expiration_time = Some(Utc::now() - Duration::hours(1));
380        assert!(verify_siwe_message(&msg, "example.com", None).is_err());
381    }
382
383    #[test]
384    fn test_verify_not_yet_valid() {
385        let mut msg = SiweMessage::new("example.com", TEST_ADDR, "https://example.com", 1).unwrap();
386        msg.not_before = Some(Utc::now() + Duration::hours(1));
387        assert!(verify_siwe_message(&msg, "example.com", None).is_err());
388    }
389
390    #[test]
391    fn test_message_hash_deterministic() {
392        let msg = SiweMessage::new("example.com", TEST_ADDR, "https://example.com", 1).unwrap();
393        let h1 = msg.message_hash();
394        let h2 = msg.message_hash();
395        assert_eq!(h1, h2);
396    }
397
398    #[test]
399    fn test_validate_address_formats() {
400        assert!(validate_address("0xAb5801a7D398351b8bE11C439e05C5b3259aec9B").is_ok());
401        assert!(validate_address("0x0000000000000000000000000000000000000000").is_ok());
402        assert!(validate_address("Ab5801a7D398351b8bE11C439e05C5b3259aec9B").is_err()); // missing 0x
403        assert!(validate_address("0xAb5801").is_err()); // too short
404    }
405}