fix: accept TD1 alternative check digit computation variant when embedded in optional1 (#70)

Some TD1 issuers embed the document number check digit inside optional1 when the check-digit slot is `<`. In some older authentic documents (like PRT and BEL ID cards), the `<` character is included to compute the check digit, which is not complying with ICAO specs. We now check both variants and consider the check digit valid if either matches the check digit number.

This is related to #66.

Author: uwolfer

src/parse/__tests__/td1.test.ts

@@ -515,4 +515,40 @@ describe('parse TD1', () => {
       ],
     ]);
   });
+
+  it('Belgium ID BEL-BO-03003 with embedded document check digit', () => {
+    // source: https://www.consilium.europa.eu/prado/en/BEL-BO-03003/index.html
+    // This Belgian ID has the document number check digit embedded in optional1
+    const MRZ = [
+      'IDBEL000590240<6013<<<<<<<<<<<',
+      '8512017F1311048BEL851201002007',
+      'REINARTZ<<ULRIKE<KATIA<E<<<<<<',
+    ];
+
+    const result = parse(MRZ);
+
+    expect(result).toMatchObject({
+      format: 'TD1',
+      valid: true,
+      documentNumber: result.fields.documentNumber,
+    });
+
+    expect(result.fields).toStrictEqual({
+      documentCode: 'ID',
+      issuingState: 'BEL',
+      documentNumber: '000590240601',
+      documentNumberCheckDigit: '3',
+      birthDate: '851201',
+      birthDateCheckDigit: '7',
+      sex: 'female',
+      expirationDate: '131104',
+      expirationDateCheckDigit: '8',
+      nationality: 'BEL',
+      optional1: '6013',
+      optional2: '85120100200',
+      compositeCheckDigit: '7',
+      lastName: 'REINARTZ',
+      firstName: 'ULRIKE KATIA E',
+    });
+  });
 });

src/parsers/__tests__/check.test.ts

@@ -1,6 +1,6 @@
 import { expect, test } from 'vitest';
 
-import { check } from '../check.ts';
+import { check, computeCheckDigit } from '../check.ts';
 
 test('check digits', () => {
   expect(() => check('592166117<231', 8)).not.toThrow();
@@ -11,3 +11,8 @@ test('check digits', () => {
   expect(() => check('600001795015', 2)).not.toThrow();
   expect(() => check('592166111<773', 4)).toThrow(/invalid check digit/);
 });
+
+test('compute embedded TD1 check digit', () => {
+  expect(computeCheckDigit('123456789AAB')).toBe(8);
+  expect(computeCheckDigit('123456789<AAB')).toBe(4);
+});

src/parsers/check.ts

@@ -1,4 +1,4 @@
-export function check(string: string, value: string | number) {
+export function computeCheckDigit(string: string) {
   let code = 0;
   const factors = [7, 3, 1];
   for (let i = 0; i < string.length; i++) {
@@ -10,7 +10,11 @@ export function check(string: string, value: string | number) {
     charCode *= factors[i % 3];
     code += charCode;
   }
-  code %= 10;
+  return code % 10;
+}
+
+export function check(string: string, value: string | number) {
+  const code = computeCheckDigit(string);
   if (code !== Number(value)) {
     throw new Error(`invalid check digit: ${value}. Must be ${code}`);
   }

src/parsers/parseDocumentNumberCheckDigit.ts

@@ -1,4 +1,4 @@
-import { check } from './check.ts';
+import { check, computeCheckDigit } from './check.ts';
 
 export default function parseDocumentNumberCheckDigit(
   checkDigit: string,
@@ -8,8 +8,23 @@ export default function parseDocumentNumberCheckDigit(
   if (checkDigit === '<' && optional) {
     const firstFiller = optional.indexOf('<');
     const tail = optional.slice(0, firstFiller - 1);
-    source = `${source}${tail}`;
-    checkDigit = optional.charAt(firstFiller - 1);
+    // Handle older non-compliant documents (e.g., PRT and BEL IDs) where the check digit
+    // is embedded in optional1 instead of following the document number directly.
+    // According to ICAO Doc 9303 Part 11 (https://www.icao.int/sites/default/files/publications/DocSeries/9303_p11_cons_en.pdf)
+    // page 88, the check digit should be calculated on the document number including
+    // any additional characters from optional1 up to (but not including) the embedded check digit.
+    const embeddedDigit = optional.charAt(firstFiller - 1);
+    const embeddedValid =
+      computeCheckDigit(`${source}${tail}`) === Number(embeddedDigit);
+    if (embeddedValid) {
+      return {
+        value: embeddedDigit,
+        start: firstFiller,
+        end: firstFiller + 1,
+      };
+    }
+    source = `${source}<${tail}`;
+    checkDigit = embeddedDigit;
     check(source, checkDigit);
     return {
       value: checkDigit,