subject.rs (20912B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2024, 2025, 2026 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 3, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 */ 16 17 use std::{ 18 fmt::{Debug, Write as _}, 19 str::FromStr, 20 }; 21 22 use aws_lc_rs::digest::{SHA256, digest}; 23 use compact_str::CompactString; 24 use taler_common::{ 25 api_common::{EddsaPublicKey, ShortHashCode}, 26 db::IncomingType, 27 encoding::base32::{Base32Error, CROCKFORD_ALPHABET}, 28 types::url, 29 }; 30 use url::Url; 31 32 #[derive(Debug, Clone, PartialEq, Eq)] 33 pub enum IncomingSubject { 34 Reserve(EddsaPublicKey), 35 Kyc(EddsaPublicKey), 36 Map(EddsaPublicKey), 37 AdminBalanceAdjust, 38 } 39 40 impl IncomingSubject { 41 pub fn ty(&self) -> IncomingType { 42 match self { 43 IncomingSubject::Reserve(_) => IncomingType::reserve, 44 IncomingSubject::Kyc(_) => IncomingType::kyc, 45 IncomingSubject::Map(_) => IncomingType::map, 46 IncomingSubject::AdminBalanceAdjust => panic!("Admin balance adjust"), 47 } 48 } 49 50 pub fn key(&self) -> &EddsaPublicKey { 51 match self { 52 IncomingSubject::Kyc(key) 53 | IncomingSubject::Reserve(key) 54 | IncomingSubject::Map(key) => key, 55 IncomingSubject::AdminBalanceAdjust => panic!("Admin balance adjust"), 56 } 57 } 58 } 59 60 #[derive(Debug, PartialEq, Eq)] 61 pub struct OutgoingSubject { 62 pub wtid: ShortHashCode, 63 pub exchange_base_url: Url, 64 pub metadata: Option<CompactString>, 65 } 66 67 impl OutgoingSubject { 68 /// Generate a random outgoing subject for https://exchange.test.com 69 pub fn rand() -> Self { 70 Self { 71 wtid: ShortHashCode::rand(), 72 exchange_base_url: url("https://exchange.test.com"), 73 metadata: None, 74 } 75 } 76 } 77 78 /** Base32 quality by proximity to spec and error probability */ 79 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)] 80 enum Base32Quality { 81 /// Both mixed casing and mixed characters, that's weird 82 Mixed, 83 /// Standard but use lowercase, maybe the client shown lowercase in the UI 84 Standard, 85 /// Uppercase but mixed characters, its common when making typos 86 Upper, 87 /// Both uppercase and use the standard alphabet as it should 88 UpperStandard, 89 } 90 91 impl Base32Quality { 92 pub fn measure(s: &str) -> Self { 93 let mut uppercase = true; 94 let mut standard = true; 95 for b in s.bytes() { 96 uppercase &= b.is_ascii_uppercase(); 97 standard &= CROCKFORD_ALPHABET.contains(&b) 98 } 99 match (uppercase, standard) { 100 (true, true) => Base32Quality::UpperStandard, 101 (true, false) => Base32Quality::Upper, 102 (false, true) => Base32Quality::Standard, 103 (false, false) => Base32Quality::Mixed, 104 } 105 } 106 } 107 108 #[derive(Debug)] 109 pub struct Candidate { 110 subject: IncomingSubject, 111 quality: Base32Quality, 112 } 113 114 #[derive(Debug, PartialEq, Eq)] 115 pub enum IncomingSubjectResult { 116 Success(IncomingSubject), 117 Ambiguous, 118 } 119 120 #[derive(Debug, PartialEq, Eq, thiserror::Error)] 121 pub enum IncomingSubjectErr { 122 #[error("found multiple public keys")] 123 Ambiguous, 124 #[error("missing reserve public key")] 125 Missing, 126 } 127 128 #[derive(Debug, thiserror::Error)] 129 pub enum OutgoingSubjectErr { 130 #[error("missing parts")] 131 MissingParts, 132 #[error("malformed wtid: {0}")] 133 Wtid(#[from] Base32Error<32>), 134 #[error("malformed exchange url: {0}")] 135 Url(#[from] url::ParseError), 136 } 137 138 /// Parse a talerable outgoing transfer subject 139 pub fn parse_outgoing(subject: &str) -> Result<OutgoingSubject, OutgoingSubjectErr> { 140 let mut parts = subject.split(' '); 141 let first = parts.next().ok_or(OutgoingSubjectErr::MissingParts)?; 142 let second = parts.next().ok_or(OutgoingSubjectErr::MissingParts)?; 143 Ok(if let Some(third) = parts.next() { 144 OutgoingSubject { 145 wtid: second.parse()?, 146 exchange_base_url: third.parse()?, 147 metadata: Some(first.into()), 148 } 149 } else { 150 OutgoingSubject { 151 wtid: first.parse()?, 152 exchange_base_url: second.parse()?, 153 metadata: None, 154 } 155 }) 156 } 157 158 /// Format an outgoing subject 159 pub fn fmt_out_subject(wtid: &ShortHashCode, url: &Url, metadata: Option<&str>) -> String { 160 let mut buf = String::new(); 161 if let Some(metadata) = metadata { 162 buf.push_str(metadata); 163 buf.push(' '); 164 } 165 write!(&mut buf, "{wtid} {url}").unwrap(); 166 buf 167 } 168 169 /// Format an incoming subject 170 pub fn fmt_in_subject(ty: IncomingType, key: &EddsaPublicKey) -> String { 171 match ty { 172 IncomingType::reserve => format!("{key}"), 173 IncomingType::kyc => format!("KYC:{key}"), 174 IncomingType::map => format!("MAP:{key}"), 175 } 176 } 177 178 /** 179 * Extract the public key from an unstructured incoming transfer subject. 180 * 181 * When a user enters the transfer object in an unstructured way, for ex in 182 * their banking UI, they may mistakenly enter separators such as ' \n-+' and 183 * make typos. 184 * To parse them while ignoring user errors, we reconstruct valid keys from key 185 * parts, resolving ambiguities where possible. 186 **/ 187 pub fn parse_incoming_unstructured(subject: &str) -> Result<IncomingSubject, IncomingSubjectErr> { 188 // We expect subject to be less than 65KB 189 assert!(subject.len() <= u16::MAX as usize); 190 191 const KEY_SIZE: usize = 52; 192 const PREFIXED_SIZE: usize = KEY_SIZE + 3; 193 const ADMIN_BALANCE_ADJUST: &str = "ADMINBALANCEADJUST"; 194 195 /** Parse an incoming subject */ 196 #[inline] 197 fn parse_single(str: &str) -> Option<Candidate> { 198 if str == ADMIN_BALANCE_ADJUST { 199 return Some(Candidate { 200 subject: IncomingSubject::AdminBalanceAdjust, 201 quality: Base32Quality::UpperStandard, 202 }); 203 } 204 // Check key type 205 let (ty, raw) = match str.len() { 206 KEY_SIZE => (IncomingType::reserve, str), 207 PREFIXED_SIZE => { 208 if let Some(key) = str.strip_prefix("KYC") { 209 (IncomingType::kyc, key) 210 } else if let Some(key) = str.strip_prefix("MAP") { 211 (IncomingType::map, key) 212 } else { 213 return None; 214 } 215 } 216 _ => return None, 217 }; 218 219 // Check key validity 220 let key = EddsaPublicKey::from_str(raw).ok()?; 221 222 let quality = Base32Quality::measure(raw); 223 Some(Candidate { 224 subject: match ty { 225 IncomingType::reserve => IncomingSubject::Reserve(key), 226 IncomingType::kyc => IncomingSubject::Kyc(key), 227 IncomingType::map => IncomingSubject::Map(key), 228 }, 229 quality, 230 }) 231 } 232 233 // Find and concatenate valid parts of a keys 234 let (parts, concatenated) = { 235 let mut parts = Vec::with_capacity(4); 236 let mut concatenated = String::with_capacity(subject.len().min(PREFIXED_SIZE + 10)); 237 parts.push(0u16); 238 for part in subject.as_bytes().split(|b| !b.is_ascii_alphanumeric()) { 239 // SAFETY: part are all valid ASCII alphanumeric 240 concatenated.push_str(unsafe { std::str::from_utf8_unchecked(part) }); 241 parts.push(concatenated.len() as u16); 242 } 243 (parts, concatenated) 244 }; 245 246 // Find best candidates 247 let mut best: Option<Candidate> = None; 248 // For each part as a starting point 249 for (i, &start) in parts.iter().enumerate() { 250 // Use progressively longer concatenation 251 for &end in parts[i..].iter().skip(1) { 252 let len = (end - start) as usize; 253 // Until they are to long to be a key 254 if len > PREFIXED_SIZE { 255 break; 256 } else if len != KEY_SIZE && len != PREFIXED_SIZE && len != ADMIN_BALANCE_ADJUST.len() { 257 continue; 258 } 259 260 // Parse the concatenated parts 261 // SAFETY: we now end.end <= concatenated.len 262 let slice = unsafe { &concatenated.get_unchecked(start as usize..end as usize) }; 263 if let Some(other) = parse_single(slice) { 264 // On success update best candidate 265 match &mut best { 266 Some(best) => { 267 if other.quality > best.quality // We prefer high quality keys 268 || matches!( // We prefer prefixed keys over reserve keys 269 (&best.subject.ty(), &other.subject.ty()), 270 (IncomingType::reserve, IncomingType::kyc | IncomingType::map) 271 ) 272 { 273 *best = other 274 } else if best.subject.key() != other.subject.key() // If keys are different 275 && best.quality == other.quality // Of same quality 276 && !matches!( // And prefixing is different 277 (&best.subject.ty(), &other.subject.ty()), 278 (IncomingType::kyc | IncomingType::map, IncomingType::reserve) 279 ) 280 { 281 return Err(IncomingSubjectErr::Ambiguous); 282 } 283 } 284 None => best = Some(other), 285 } 286 } 287 } 288 } 289 290 if let Some(it) = best { 291 Ok(it.subject) 292 } else { 293 Err(IncomingSubjectErr::Missing) 294 } 295 } 296 297 // Modulo 10 Recursive 298 fn mod10_recursive(bytes: &[u8]) -> u8 { 299 const LOOKUP_TABLE: [u8; 10] = [0, 9, 4, 6, 8, 2, 7, 1, 3, 5]; 300 // Modulo 10 Recursive calculation 301 let mut carry = 0u8; 302 for &b in bytes { 303 // ASCII '0'-'9' is 0x30-0x39. Subtracting b'0' (48) gives the integer. 304 let digit = b - b'0'; 305 carry = LOOKUP_TABLE[((carry + digit) % 10) as usize]; 306 } 307 carry 308 } 309 310 /// Encode a public key as a QR-Bill reference 311 pub fn subject_fmt_qr_bill(key_bytes: &[u8]) -> String { 312 // High-Entropy Hash (SHA-256) to ensure even distribution 313 let hash = digest(&SHA256, key_bytes); 314 315 // Compute hash % 10^26 316 let hash_mod = hash.as_ref().chunks(3).fold(0u128, |rem, chunk| { 317 chunk.iter().fold(rem, |r, &b| r * 256 + b as u128) % 10u128.pow(26) 318 }); 319 320 // Format to 26 digits with leading zeros 321 let reference_base = format!("{:0>26}", hash_mod); 322 323 // Modulo 10 Recursive calculation 324 let carry = mod10_recursive(reference_base.as_bytes()); 325 let checksum = (10 - carry) % 10; 326 327 // Combine base (26) + checksum (1) = 27 characters 328 format!("{}{}", reference_base, checksum) 329 } 330 331 /// Check if a string is a valid QR-Bill reference 332 pub fn subject_is_qr_bill(reference: &str) -> bool { 333 // Quick length and numeric check 334 if reference.len() != 27 || !reference.chars().all(|c| c.is_ascii_digit()) { 335 return false; 336 } 337 338 // If the check digit is correct, the final carry will be 0 339 mod10_recursive(reference.as_bytes()) == 0 340 } 341 342 #[cfg(test)] 343 mod test { 344 use std::str::FromStr as _; 345 346 use taler_common::{ 347 api_common::{EddsaPublicKey, ShortHashCode}, 348 db::IncomingType, 349 types::url, 350 }; 351 352 use crate::subject::{ 353 IncomingSubject, IncomingSubjectErr, OutgoingSubject, fmt_out_subject, mod10_recursive, 354 parse_incoming_unstructured, parse_outgoing, subject_fmt_qr_bill, subject_is_qr_bill, 355 }; 356 357 #[test] 358 fn qrbill() { 359 let reference = "210000000003139471430009017"; 360 361 let input = "21000000000313947143000901"; 362 let carry = mod10_recursive(input.as_bytes()); 363 let checksum = (10 - carry) % 10; 364 assert_eq!(checksum, 7); 365 366 assert_eq!(mod10_recursive(reference.as_bytes()), 0); 367 assert!(subject_is_qr_bill(reference)); 368 assert!(!subject_is_qr_bill(input)); 369 assert!(!subject_is_qr_bill("")); 370 assert!(!subject_is_qr_bill("210000000003139471430009019")); 371 assert!(!subject_is_qr_bill("21000000000313947143000901A")); 372 373 let key = "4MZT6RS3RVB3B0E2RDMYW0YRA3Y0VPHYV0CYDE6XBB0YMPFXCEG0"; 374 let key = EddsaPublicKey::from_str(key).unwrap(); 375 assert_eq!( 376 subject_fmt_qr_bill(key.as_ref()), 377 "442862674560948379842733643" 378 ); 379 } 380 381 #[test] 382 /** Test parsing logic */ 383 fn incoming_parse() { 384 let key = "4MZT6RS3RVB3B0E2RDMYW0YRA3Y0VPHYV0CYDE6XBB0YMPFXCEG0"; 385 let other = "00Q979QSMJ29S7BJT3DDAVC5A0DR5Z05B7N0QT1RCBQ8FXJPZ6RG"; 386 387 // Common checks 388 for ty in [IncomingType::reserve, IncomingType::kyc, IncomingType::map] { 389 let prefix = match ty { 390 IncomingType::reserve => "", 391 IncomingType::kyc => "KYC", 392 IncomingType::map => "MAP", 393 }; 394 let standard = &format!("{prefix}{key}"); 395 let (standard_l, standard_r) = standard.split_at(standard.len() / 2); 396 let mixed = &format!("{prefix}4mzt6RS3rvb3b0e2rdmyw0yra3y0vphyv0cyde6xbb0ympfxceg0"); 397 let (mixed_l, mixed_r) = mixed.split_at(mixed.len() / 2); 398 let other_standard = &format!("{prefix}{other}"); 399 let other_mixed = 400 &format!("{prefix}TEGY6d9mh9pgwvwpgs0z0095z854xegfy7jj202yd0esp8p0za60"); 401 let key = EddsaPublicKey::from_str(key).unwrap(); 402 let result = Ok(match ty { 403 IncomingType::reserve => IncomingSubject::Reserve(key), 404 IncomingType::kyc => IncomingSubject::Kyc(key), 405 IncomingType::map => IncomingSubject::Map(key), 406 }); 407 408 // Check succeed if standard or mixed 409 for case in [standard, mixed] { 410 for test in [ 411 format!("noise {case} noise"), 412 format!("{case} noise to the right"), 413 format!("noise to the left {case}"), 414 format!(" {case} "), 415 format!("noise\n{case}\nnoise"), 416 format!("Test+{case}"), 417 ] { 418 assert_eq!(parse_incoming_unstructured(&test), result); 419 } 420 } 421 422 // Check succeed if standard or mixed and split 423 for (l, r) in [(standard_l, standard_r), (mixed_l, mixed_r)] { 424 for case in [ 425 format!("left {l}{r} right"), 426 format!("left {l} {r} right"), 427 format!("left {l}-{r} right"), 428 format!("left {l}+{r} right"), 429 format!("left {l}\n{r} right"), 430 format!("left {l}-+\n{r} right"), 431 format!("left {l} - {r} right"), 432 format!("left {l} + {r} right"), 433 format!("left {l} \n {r} right"), 434 format!("left {l} - + \n {r} right"), 435 ] { 436 assert_eq!(parse_incoming_unstructured(&case), result); 437 } 438 } 439 440 // Check concat parts 441 for chunk_size in 1..standard.len() { 442 let chunked: String = standard 443 .as_bytes() 444 .chunks(chunk_size) 445 .flat_map(|c| [std::str::from_utf8(c).unwrap(), " "]) 446 .collect(); 447 for case in [chunked.clone(), format!("left {chunked} right")] { 448 assert_eq!(parse_incoming_unstructured(&case), result); 449 } 450 } 451 452 // Check failed when multiple key 453 for case in [ 454 format!("{standard} {other_standard}"), 455 format!("{mixed} {other_mixed}"), 456 ] { 457 assert_eq!( 458 parse_incoming_unstructured(&case), 459 Err(IncomingSubjectErr::Ambiguous) 460 ); 461 } 462 463 // Check accept redundant key 464 for case in [ 465 format!("{standard} {standard} {mixed} {mixed}"), // Accept redundant key 466 format!("{standard} {other_mixed}"), // Prefer high quality 467 ] { 468 assert_eq!(parse_incoming_unstructured(&case), result); 469 } 470 471 // Check prefer prefixed over simple 472 for case in [format!("{mixed_l}-{mixed_r} {standard_l}-{standard_r}")] { 473 let res = parse_incoming_unstructured(&case); 474 if ty == IncomingType::reserve { 475 assert_eq!(res, Err(IncomingSubjectErr::Ambiguous)); 476 } else { 477 assert_eq!(res, result); 478 } 479 } 480 481 // Check failure if malformed or missing 482 for case in [ 483 "does not contain any reserve", // Check fail if none 484 &standard[1..], // Check fail if missing char 485 //"2MZT6RS3RVB3B0E2RDMYW0YRA3Y0VPHYV0CYDE6XBB0YMPFXCEG0", // Check fail if not a valid key 486 ] { 487 assert_eq!( 488 parse_incoming_unstructured(case), 489 Err(IncomingSubjectErr::Missing) 490 ); 491 } 492 493 if ty == IncomingType::kyc || ty == IncomingType::map { 494 // Prefer prefixed over unprefixed 495 for case in [format!("{other} {standard}"), format!("{other} {mixed}")] { 496 assert_eq!(parse_incoming_unstructured(&case), result); 497 } 498 } 499 } 500 } 501 502 #[test] 503 /** Test parsing logic using real cases */ 504 fn real() { 505 // Good reserve case 506 for (subject, key) in [ 507 ( 508 "Taler TEGY6d9mh9pgwvwpgs0z0095z854xegfy7j j202yd0esp8p0za60", 509 "TEGY6d9mh9pgwvwpgs0z0095z854xegfy7jj202yd0esp8p0za60", 510 ), 511 ( 512 "00Q979QSMJ29S7BJT3DDAVC5A0DR5Z05B7N 0QT1RCBQ8FXJPZ6RG", 513 "00Q979QSMJ29S7BJT3DDAVC5A0DR5Z05B7N0QT1RCBQ8FXJPZ6RG", 514 ), 515 ( 516 "Taler NDDCAM9XN4HJZFTBD8V6FNE2FJE8G Y734PJ5AGQMY06C8D4HB3Z0", 517 "NDDCAM9XN4HJZFTBD8V6FNE2FJE8GY734PJ5AGQMY06C8D4HB3Z0", 518 ), 519 ( 520 "KYCVEEXTBXBEMCS5R64C24GFNQVWBN5R2F9QSQ7PN8QXAP1NG4NG", 521 "KYCVEEXTBXBEMCS5R64C24GFNQVWBN5R2F9QSQ7PN8QXAP1NG4NG", 522 ), 523 ] { 524 assert_eq!( 525 Ok(IncomingSubject::Reserve( 526 EddsaPublicKey::from_str(key).unwrap(), 527 )), 528 parse_incoming_unstructured(subject) 529 ) 530 } 531 // Good kyc case 532 for (subject, key) in [( 533 "KYC JW398X85FWPKKMS0EYB6TQ1799RMY5DDXTZ FPW4YC3WJ2DWSJT70", 534 "JW398X85FWPKKMS0EYB6TQ1799RMY5DDXTZFPW4YC3WJ2DWSJT70", 535 )] { 536 assert_eq!( 537 Ok(IncomingSubject::Kyc(EddsaPublicKey::from_str(key).unwrap(),)), 538 parse_incoming_unstructured(subject) 539 ) 540 } 541 } 542 543 #[test] 544 fn outgoing() { 545 let key = ShortHashCode::rand(); 546 547 // Without metadata 548 let subject = format!("{key} http://exchange.example.com/"); 549 let parsed = parse_outgoing(&subject).unwrap(); 550 assert_eq!( 551 parsed, 552 OutgoingSubject { 553 wtid: key.clone(), 554 exchange_base_url: url("http://exchange.example.com/"), 555 metadata: None 556 } 557 ); 558 assert_eq!( 559 subject, 560 fmt_out_subject( 561 &parsed.wtid, 562 &parsed.exchange_base_url, 563 parsed.metadata.as_deref() 564 ) 565 ); 566 567 // With metadata 568 let subject = format!("Accounting:id.4 {key} http://exchange.example.com/"); 569 let parsed = parse_outgoing(&subject).unwrap(); 570 assert_eq!( 571 parsed, 572 OutgoingSubject { 573 wtid: key.clone(), 574 exchange_base_url: url("http://exchange.example.com/"), 575 metadata: Some("Accounting:id.4".into()) 576 } 577 ); 578 assert_eq!( 579 subject, 580 fmt_out_subject( 581 &parsed.wtid, 582 &parsed.exchange_base_url, 583 parsed.metadata.as_deref() 584 ) 585 ); 586 } 587 }