#[cfg(feature = "serde")]
use serde::{Deserialize, Serialize};
#[cfg(feature = "zeroize")]
use zeroize::ZeroizeOnDrop;
mod checksum;
mod countries;
mod dates;
mod emit;
mod parser;
pub use checksum::{check_digit, verify};
pub use countries::{code_for_name, country_name};
pub use dates::{expand_date, expand_date_with_pivot, Date, DateValidity, CURRENT_YY};
pub use emit::{format_td1, format_td2, format_td3, Td1Fields, Td2Fields, Td3Fields};
pub use parser::{find_and_parse, parse_mrv_a, parse_mrv_b, parse_td1, parse_td2, parse_td3};
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct Checks {
pub document_number: bool,
pub date_of_birth: bool,
pub date_of_expiry: bool,
pub personal_number: bool,
pub composite: bool,
}
impl Checks {
pub fn all_valid(&self) -> bool {
self.document_number
&& self.date_of_birth
&& self.date_of_expiry
&& self.personal_number
&& self.composite
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum Format {
Td3,
Td2,
Td1,
MrvA,
MrvB,
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "zeroize", derive(ZeroizeOnDrop))]
pub struct MrzData {
#[cfg_attr(feature = "zeroize", zeroize(skip))]
pub format: Format,
pub document_type: String,
pub issuing_country: String,
pub document_number: String,
pub surname: String,
pub given_names: String,
pub nationality: String,
pub date_of_birth: String,
pub sex: String,
pub date_of_expiry: String,
pub personal_number: Option<String>,
pub mrz_lines: String,
#[cfg_attr(feature = "zeroize", zeroize(skip))]
pub checks: Checks,
}
impl MrzData {
pub fn valid(&self) -> bool {
self.checks.all_valid()
}
pub fn issuing_country_name(&self) -> Option<&'static str> {
country_name(&self.issuing_country)
}
pub fn nationality_name(&self) -> Option<&'static str> {
country_name(&self.nationality)
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum MrzError {
BadLength { expected: usize, got: usize },
BadCharacter(char),
BadDocumentCode(String),
NotFound,
}
impl core::fmt::Display for MrzError {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
match self {
Self::BadLength { expected, got } => {
write!(f, "bad MRZ line length: expected {expected}, got {got}")
}
Self::BadCharacter(c) => write!(f, "invalid MRZ character: {c:?}"),
Self::BadDocumentCode(c) => write!(f, "unrecognized document code: {c:?}"),
Self::NotFound => write!(f, "no MRZ found in text"),
}
}
}
impl std::error::Error for MrzError {}
#[cfg(test)]
mod tests {
use super::*;
const TD3_L1: &str = "P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<";
const TD3_L2: &str = "L898902C36UTO7408122F1204159ZE184226B<<<<<10";
#[test]
fn td3_specimen_fully_valid() {
let d = parse_td3(TD3_L1, TD3_L2).unwrap();
assert!(d.valid(), "checks: {:?}", d.checks);
assert_eq!(d.document_type, "P");
assert_eq!(d.issuing_country, "UTO");
assert_eq!(d.surname, "ERIKSSON");
assert_eq!(d.given_names, "ANNA MARIA");
assert_eq!(d.document_number, "L898902C3");
assert_eq!(d.nationality, "UTO");
assert_eq!(d.date_of_birth, "1974-08-12");
assert_eq!(d.sex, "F");
assert_eq!(d.date_of_expiry, "2012-04-15");
assert_eq!(d.personal_number.as_deref(), Some("ZE184226B"));
}
#[test]
fn td3_tampered_dob_fails_checksum() {
let tampered = TD3_L2.replacen("740812", "750812", 1);
let d = parse_td3(TD3_L1, &tampered).unwrap();
assert!(!d.checks.date_of_birth);
assert!(!d.checks.composite);
assert!(!d.valid());
}
#[test]
fn td3_empty_personal_number_with_filler_check() {
let l2 = "L898902C36UTO7408122F1204159<<<<<<<<<<<<<<06";
let d = parse_td3(TD3_L1, l2).unwrap();
assert!(d.checks.personal_number);
assert_eq!(d.personal_number, None);
}
const TD1_L1: &str = "I<UTOD231458907<<<<<<<<<<<<<<<";
const TD1_L2: &str = "7408122F1204159UTO<<<<<<<<<<<6";
const TD1_L3: &str = "ERIKSSON<<ANNA<MARIA<<<<<<<<<<";
#[test]
fn td1_specimen_fully_valid() {
let d = parse_td1(TD1_L1, TD1_L2, TD1_L3).unwrap();
assert!(d.valid(), "checks: {:?}", d.checks);
assert_eq!(d.format, Format::Td1);
assert_eq!(d.document_type, "I");
assert_eq!(d.document_number, "D23145890");
assert_eq!(d.surname, "ERIKSSON");
assert_eq!(d.given_names, "ANNA MARIA");
assert_eq!(d.date_of_birth, "1974-08-12");
assert_eq!(d.date_of_expiry, "2012-04-15");
}
const TD2_L1: &str = "I<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<";
const TD2_L2: &str = "D231458907UTO7408122F1204159<<<<<<<6";
#[test]
fn td2_specimen_fully_valid() {
let d = parse_td2(TD2_L1, TD2_L2).unwrap();
assert!(d.valid(), "checks: {:?}", d.checks);
assert_eq!(d.format, Format::Td2);
assert_eq!(d.document_type, "I");
assert_eq!(d.issuing_country, "UTO");
assert_eq!(d.document_number, "D23145890");
assert_eq!(d.surname, "ERIKSSON");
assert_eq!(d.given_names, "ANNA MARIA");
assert_eq!(d.nationality, "UTO");
assert_eq!(d.date_of_birth, "1974-08-12");
assert_eq!(d.sex, "F");
assert_eq!(d.date_of_expiry, "2012-04-15");
}
#[test]
fn td2_tampered_expiry_fails_checksum() {
let tampered = TD2_L2.replacen("120415", "120416", 1);
let d = parse_td2(TD2_L1, &tampered).unwrap();
assert!(!d.checks.date_of_expiry);
assert!(!d.checks.composite);
assert!(!d.valid());
}
#[test]
fn td2_found_in_ocr_text() {
let text = format!("## IDENTITY CARD\n\nnoise\n\n{TD2_L1}\n{TD2_L2}\n\nfooter");
let d = find_and_parse(&text).unwrap();
assert!(d.valid(), "checks: {:?}", d.checks);
assert_eq!(d.format, Format::Td2);
assert_eq!(d.surname, "ERIKSSON");
assert_eq!(d.document_number, "D23145890");
}
#[test]
fn find_in_ocr_noise() {
let text = format!(
"## REPUBLIC OF UTOPIA\n\nSome OCR noise here\n\n{}\n{}\n\nfooter",
"p<utoeriksson«anna<maria<<<<<<<<<<<<<<<<<",
"L898902C36UTO7408122F1204159ZE184226B<<<<<10"
);
let d = find_and_parse(&text).unwrap();
assert!(d.valid());
assert_eq!(d.surname, "ERIKSSON");
}
#[test]
fn find_html_escaped_and_merged_lines() {
let text = "## PUTOVNICA\n\nP<HRVSPECIMEN<<SPECIMEN<<<<<<<<<<<<<<<<<<<<< 0070070071HRV8212258F1407019<<<<<<<<<<<<<<06\n";
let d = find_and_parse(text).unwrap();
assert_eq!(d.surname, "SPECIMEN");
assert_eq!(d.document_number, "007007007");
assert_eq!(d.issuing_country, "HRV");
assert!(d.checks.document_number);
assert!(d.checks.date_of_birth);
assert!(d.checks.date_of_expiry);
}
#[test]
fn checksum_verified_ocr_repair() {
let text = "I 01072009 PUJZAGREB 0\n\nBIDFD WH5SS A 2\n\n01072014\nP<HRVSPECIMEN<<SPECIMEN<KLLLLLLLLLLLLLLLLLKLKL\n10070070071HRVB212258F1407019<<<<<<<<<<<<<<06\n";
let d = find_and_parse(text).unwrap();
assert!(d.valid(), "checks: {:?}", d.checks);
assert_eq!(d.surname, "SPECIMEN");
assert_eq!(d.given_names, "SPECIMEN");
assert_eq!(d.document_number, "007007007");
assert_eq!(d.date_of_birth, "1982-12-25");
}
#[test]
fn ocr_repair_dropped_filler_mid_line() {
let text = "RF 01072009 PUZAGREB\n01072014\nP<HRVSPECIMEN<<SPECIMEN<<K<KLLLLLLLLLLLLLLLLKLKL\n0070070071HRVB212258F1407019<<<<LLLLLLL<<06\n";
let d = find_and_parse(text).unwrap();
assert!(d.valid(), "checks: {:?}", d.checks);
assert_eq!(d.surname, "SPECIMEN");
assert_eq!(d.document_number, "007007007");
assert_eq!(d.personal_number, None);
}
#[test]
fn td1_from_single_docling_line_with_k_misreads() {
let text = "1F9874543\n\nIKSVNIE987654302806985505145K< 8506287F3203282SVN<<<<<<<<<<<2 VZORECKKJANAKKKKKKKKK<<KK";
let d = find_and_parse(text).unwrap();
assert!(d.valid(), "checks: {:?}", d.checks);
assert_eq!(d.format, Format::Td1);
assert_eq!(d.document_type, "I");
assert_eq!(d.issuing_country, "SVN");
assert_eq!(d.document_number, "IE9876543");
assert_eq!(d.surname, "VZOREC");
assert_eq!(d.given_names, "JANA");
assert_eq!(d.date_of_birth, "1985-06-28");
assert_eq!(d.date_of_expiry, "2032-03-28");
assert_eq!(d.personal_number.as_deref(), Some("2806985505145"));
}
#[test]
fn ocr_repair_deeply_truncated_name_line() {
let text = "PUTOVNICA\nPKHRVSPECIMEN<<SPECIMEN<<<<<<<<<<<<\n0070070071HRV8212258F1407019<<<<<<<<<<<<<<06\n";
let d = find_and_parse(text).unwrap();
assert!(d.valid(), "checks: {:?}", d.checks);
assert_eq!(d.surname, "SPECIMEN");
assert_eq!(d.given_names, "SPECIMEN");
assert_eq!(d.document_number, "007007007");
}
#[test]
fn invalid_checksums_still_reported() {
let tampered = TD3_L2.replacen("740812", "750812", 1);
let text = format!("{TD3_L1}\n{tampered}");
let d = find_and_parse(&text).unwrap();
assert!(!d.valid());
assert!(!d.checks.date_of_birth);
}
#[test]
fn find_nothing_in_plain_text() {
assert_eq!(
find_and_parse("just a regular paragraph\nwith two lines"),
Err(MrzError::NotFound)
);
}
const MRV_A_L1: &str = "V<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<";
const MRV_A_L2: &str = "XK93054875BRA8502212F2703143R5T6U7V8W9<<<<<<";
#[test]
fn mrv_a_specimen_fully_valid() {
let d = parse_mrv_a(MRV_A_L1, MRV_A_L2).unwrap();
assert!(d.valid(), "checks: {:?}", d.checks);
assert_eq!(d.format, Format::MrvA);
assert_eq!(d.document_type, "V");
assert_eq!(d.issuing_country, "UTO");
assert_eq!(d.surname, "ERIKSSON");
assert_eq!(d.given_names, "ANNA MARIA");
assert_eq!(d.nationality, "BRA");
assert_eq!(d.date_of_birth, "1985-02-21");
assert_eq!(d.sex, "F");
assert_eq!(d.date_of_expiry, "2027-03-14");
assert_eq!(d.document_number, "XK9305487");
assert_eq!(d.personal_number.as_deref(), Some("R5T6U7V8W9"));
}
const MRV_B_L1: &str = "V<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<";
const MRV_B_L2: &str = "L234567897DEU9201017F2706306QW12ER34";
#[test]
fn mrv_b_specimen_fully_valid() {
let d = parse_mrv_b(MRV_B_L1, MRV_B_L2).unwrap();
assert!(d.valid(), "checks: {:?}", d.checks);
assert_eq!(d.format, Format::MrvB);
assert_eq!(d.nationality, "DEU");
assert_eq!(d.date_of_birth, "1992-01-01");
assert_eq!(d.date_of_expiry, "2027-06-30");
assert_eq!(d.document_number, "L23456789");
assert_eq!(d.personal_number.as_deref(), Some("QW12ER34"));
}
#[test]
fn mrv_a_tampered_dob_fails_checksum() {
let tampered = MRV_A_L2.replacen("850221", "860221", 1);
let d = parse_mrv_a(MRV_A_L1, &tampered).unwrap();
assert!(!d.checks.date_of_birth);
assert!(!d.valid());
}
#[test]
fn mrv_rejects_non_v_document_code() {
let line1 = "P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<";
let result = parse_mrv_a(line1, MRV_A_L2);
assert!(matches!(result, Err(MrzError::BadDocumentCode(_))));
}
#[test]
fn country_names_surface_on_mrzdata() {
let d = parse_td1(TD1_L1, TD1_L2, TD1_L3).unwrap();
assert_eq!(d.issuing_country_name(), Some("Utopia (ICAO specimen)"));
assert_eq!(d.nationality_name(), Some("Utopia (ICAO specimen)"));
}
}