@parselo/scanner-core 0.0.1 → 0.2.0

package/README.md

@@ -0,0 +1,165 @@
+# @parselo/scanner-core
+
+Platform-agnostic core for the Parselo Canadian ID scanning SDK. Parses AAMVA
+PDF417 barcodes, magnetic-stripe tracks, and ICAO 9303 MRZ from passports and
+travel documents into a unified canonical document shape. Includes offline
+ES256 license enforcement and PII-free usage analytics.
+
+No Capacitor dependency — fully testable in Node.
+
+## What it parses
+
+| Document type | Format | Notes |
+|---|---|---|
+| Canadian / US driver's licences & ID cards | PDF417 (AAMVA) | All provinces; dates normalised to ISO |
+| BC / ON / AB licences (older stock) | Magnetic-stripe tracks encoded in PDF417 | Three-track `%…?` format |
+| Passports, emergency travel docs, PR cards | ICAO 9303 TD3 MRZ (2 × 44 chars) | Five check digits validated; VIZ cross-reference corrects `<` OCR corruption |
+
+All document types produce the same `CanonicalDocument` shape with identical field names and ISO `YYYY-MM-DD` dates.
+
+## Install
+
+```bash
+npm install @parselo/scanner-core
+```
+
+A native capture plugin is required for on-device use:
+
+| Use case | Plugin |
+|---|---|
+| Driver's licence / barcode | [`@parselo/capacitor-pdf417`](https://www.npmjs.com/package/@parselo/capacitor-pdf417) |
+| Passport / travel document | [`@parselo/capacitor-mrz`](https://www.npmjs.com/package/@parselo/capacitor-mrz) |
+
+## Scanning a driver's licence
+
+```ts
+import { Scanner, type BarcodeNative } from "@parselo/scanner-core";
+import { Pdf417 } from "@parselo/capacitor-pdf417";
+
+const native: BarcodeNative = {
+  captureAndDecodePdf417: async () => {
+    const { raw } = await Pdf417.decodePdf417({ image: dataUrl });
+    return raw; // null if no barcode found
+  },
+};
+
+const scanner = new Scanner({ license, analytics, native });
+await scanner.init();
+
+const result = await scanner.scan();
+if (result.ok && result.document) {
+  const { fields, jurisdiction } = result.document;
+  console.log(fields.firstName?.value, fields.lastName?.value);
+  console.log(fields.dateOfBirth?.value);   // "1985-03-12"
+  console.log(jurisdiction);               // "CA-QC"
+}
+```
+
+## Scanning a passport or travel document
+
+```ts
+import { Scanner, type MrzNative } from "@parselo/scanner-core";
+import { Mrz } from "@parselo/capacitor-mrz";
+
+const mrzNative: MrzNative = {
+  captureAndRecognizeMrz: async () => {
+    const { lines } = await Mrz.recognizeText({ image: dataUrl });
+    return lines; // string[] of OCR observations
+  },
+};
+
+const scanner = new Scanner({ license, analytics, native, mrzNative });
+await scanner.init();
+
+const result = await scanner.scanPassport();
+if (result.ok && result.document) {
+  const { fields, jurisdiction } = result.document;
+  console.log(fields.firstName?.value, fields.lastName?.value);
+  console.log(fields.dateOfBirth?.value);  // "1978-11-28"
+  console.log(fields.country?.value);      // "MEX" (ICAO 3-char)
+  console.log(jurisdiction);              // "CA" for Canadian-issued docs
+}
+```
+
+Handles standard passports (`P<`), emergency travel documents (`PU`), permanent
+resident travel documents (`PR`), and foreign passports. The parser cross-references
+Vision's biographical-zone OCR lines to recover names even when the OCR-B `<` fill
+character is misread.
+
+## Canonical document shape
+
+```ts
+interface CanonicalDocument {
+  documentType: "drivers_license" | "id_card" | "passport" | "unknown";
+  jurisdiction: string;   // "CA-QC", "CA-BC", "CA", "MEX", …
+  fields: {
+    // All document types
+    firstName?:         Field;
+    lastName?:          Field;
+    middleName?:        Field;
+    dateOfBirth?:       Field;  // ISO YYYY-MM-DD
+    expiryDate?:        Field;  // ISO YYYY-MM-DD
+    documentNumber?:    Field;
+    sex?:               Field;
+    // Driver's licences
+    addressStreet?:     Field;
+    addressCity?:       Field;
+    addressRegion?:     Field;
+    addressPostalCode?: Field;
+    vehicleClass?:      Field;
+    // Passports / travel documents
+    country?:           Field;  // ICAO 3-char issuing country
+  };
+  raw?: Record<string, string>;
+}
+
+interface Field {
+  value:      string;
+  confidence: number;               // 0–1
+  source:     "barcode" | "mrz";
+}
+```
+
+## Scan result
+
+```ts
+interface ScanResult {
+  ok:        boolean;
+  document?: CanonicalDocument;
+  error?:    ScanError;
+}
+
+type ScanError =
+  | "no_barcode" | "not_aamva"        // barcode path
+  | "no_mrz"                          // passport path
+  | "license_expired" | "license_bundle_mismatch"
+  | "license_bad_signature" | "license_unknown_key" | "license_malformed";
+```
+
+## License enforcement
+
+Tokens are ES256 JWTs signed by AWS KMS. `scanner.init()` verifies the
+signature offline against the embedded public key — no network call required.
+Each token encodes an expiry date, an allowed bundle ID list, and a scan quota.
+
+```ts
+const { valid, reason, claims } = await scanner.init();
+if (!valid) {
+  // reason: "expired" | "bundle_mismatch" | "bad_signature"
+  //       | "unknown_key" | "malformed"
+}
+```
+
+## Analytics
+
+One PII-free event per scan (document type, jurisdiction, success/fail,
+confidence bucket, device model — never document field values). Events buffer
+locally and flush in batches. Force a flush with:
+
+```ts
+await scanner.flushAnalytics();
+```
+
+## License
+
+MIT

package/dist/canonical.d.ts

@@ -1,4 +1,6 @@
 import type { AamvaResult } from "./aamva";
+import type { MagstripeResult } from "./magstripe";
+import type { MrzResult } from "./mrz";
 export type FieldSource = "barcode" | "ocr" | "mrz";
 export interface CanonicalField {
     value: string;
@@ -27,4 +29,6 @@ export interface CanonicalDocument {
     };
     raw: Record<string, string>;
 }
+export declare function mrzToCanonical(m: MrzResult): CanonicalDocument;
+export declare function magstripeToCanonical(m: MagstripeResult, confidence?: number): CanonicalDocument;
 export declare function toCanonical(a: AamvaResult, confidence?: number): CanonicalDocument;

package/dist/canonical.js

@@ -2,6 +2,64 @@
 // One stable output shape every document maps into, regardless of source
 // (barcode now; OCR/MRZ later). Each field carries its value, a confidence,
 // and which path produced it, so the future merge step can prefer ground truth.
+// Minimal ICAO 3-char → ISO 3166-1 alpha-2 map for jurisdiction derivation.
+const ICAO_ISO2 = {
+    CAN: "CA", USA: "US", GBR: "GB", FRA: "FR", DEU: "DE", AUS: "AU",
+    NZL: "NZ", JPN: "JP", CHN: "CN", IND: "IN", BRA: "BR", MEX: "MX",
+    ITA: "IT", ESP: "ES", PRT: "PT", NLD: "NL", BEL: "BE", CHE: "CH",
+    AUT: "AT", SWE: "SE", NOR: "NO", DNK: "DK", FIN: "FI", IRL: "IE",
+    POL: "PL", CZE: "CZ", HUN: "HU", HRV: "HR", ROU: "RO", UKR: "UA",
+    RUS: "RU", TUR: "TR", ISR: "IL", ZAF: "ZA", KOR: "KR", SGP: "SG",
+    MYS: "MY", THA: "TH", IDN: "ID", PHL: "PH", PAK: "PK", EGY: "EG",
+};
+export function mrzToCanonical(m) {
+    const c = m.confidence;
+    const field = (value) => value !== undefined ? { value, confidence: c, source: "mrz" } : undefined;
+    const iso2 = m.issuingCountry ? (ICAO_ISO2[m.issuingCountry] ?? m.issuingCountry) : "unknown";
+    return {
+        documentType: "passport",
+        jurisdiction: iso2,
+        fields: {
+            firstName: field(m.firstName),
+            lastName: field(m.lastName),
+            documentNumber: field(m.documentNumber),
+            dateOfBirth: field(m.dateOfBirth),
+            expiryDate: field(m.expiryDate),
+            sex: field(m.sex),
+            country: field(m.issuingCountry),
+        },
+        raw: {
+            line1: m.raw.line1,
+            line2: m.raw.line2,
+        },
+    };
+}
+export function magstripeToCanonical(m, confidence = 1.0) {
+    const field = (value) => value !== undefined ? { value, confidence, source: "barcode" } : undefined;
+    const province = m.jurisdiction ?? m.addressRegion ?? "";
+    const jurisdiction = province ? `CA-${province}` : "CA";
+    return {
+        documentType: "drivers_license",
+        jurisdiction,
+        fields: {
+            firstName: field(m.firstName),
+            lastName: field(m.lastName),
+            dateOfBirth: field(m.dateOfBirth),
+            expiryDate: field(m.expiryDate),
+            documentNumber: field(m.documentNumber),
+            sex: field(m.sex),
+            addressStreet: field(m.addressStreet),
+            addressCity: field(m.addressCity),
+            addressRegion: field(m.addressRegion),
+            addressPostalCode: field(m.addressPostalCode),
+        },
+        raw: {
+            track1: m.raw.track1 ?? "",
+            track2: m.raw.track2 ?? "",
+            track3: m.raw.track3 ?? "",
+        },
+    };
+}
 export function toCanonical(a, confidence = 1.0) {
     const e = a.elements;
     const field = (code) => e[code] !== undefined ? { value: e[code], confidence, source: "barcode" } : undefined;

package/dist/index.d.ts

@@ -2,12 +2,17 @@ import { type CanonicalDocument } from "./canonical";
 import { type LicenseResult } from "./license";
 import { type AnalyticsConfig } from "./analytics";
 export * from "./aamva";
+export * from "./magstripe";
+export * from "./mrz";
 export * from "./canonical";
 export * from "./license";
 export * from "./analytics";
 export interface BarcodeNative {
     captureAndDecodePdf417(): Promise<string | null>;
 }
+export interface MrzNative {
+    captureAndRecognizeMrz(): Promise<string[] | null>;
+}
 export interface ScannerConfig {
     license: {
         token: string;
@@ -16,9 +21,10 @@ export interface ScannerConfig {
     };
     analytics: AnalyticsConfig;
     native: BarcodeNative;
+    mrzNative?: MrzNative;
     deviceModel: string;
 }
-export type ScanError = "license_malformed" | "license_unknown_key" | "license_bad_signature" | "license_expired" | "license_bundle_mismatch" | "no_barcode" | "not_aamva";
+export type ScanError = "license_malformed" | "license_unknown_key" | "license_bad_signature" | "license_expired" | "license_bundle_mismatch" | "no_barcode" | "not_aamva" | "no_mrz";
 export interface ScanResult {
     ok: boolean;
     document?: CanonicalDocument;
@@ -31,8 +37,12 @@ export declare class Scanner {
     constructor(cfg: ScannerConfig);
     /** Verify the signature once, up front. Call on plugin init. */
     init(): Promise<LicenseResult>;
+    /** Scan a driver's licence or provincial ID card via PDF417 barcode. */
     scan(): Promise<ScanResult>;
+    /** Scan a passport via on-device MRZ text recognition. */
+    scanPassport(): Promise<ScanResult>;
     /** Flush buffered analytics (e.g. on app foreground/background). */
     flushAnalytics(): Promise<void>;
+    private checkLicense;
     private emit;
 }

package/dist/index.js

@@ -1,14 +1,19 @@
 // index.ts
 // Ties the core together and shows the wrap points explicitly:
-//   verify license (gate)  ->  native decode  ->  parse  ->  canonical  ->  emit analytics
+//   verify license (gate)  ->  native capture  ->  parse  ->  canonical  ->  emit analytics
 //
-// The native PDF417 decode is supplied by the plugin's Swift/Kotlin bridge via
-// the BarcodeNative interface, so this orchestration is platform-agnostic.
+// Supports two scan paths:
+//   scan()         — PDF417 barcode (driver's licences)
+//   scanPassport() — MRZ text recognition (passports)
 import { parseAamva } from "./aamva";
-import { toCanonical } from "./canonical";
+import { parseMagstripe } from "./magstripe";
+import { parseMrz } from "./mrz";
+import { toCanonical, magstripeToCanonical, mrzToCanonical } from "./canonical";
 import { verifyLicense, isExpired } from "./license";
 import { ScanAnalytics } from "./analytics";
 export * from "./aamva";
+export * from "./magstripe";
+export * from "./mrz";
 export * from "./canonical";
 export * from "./license";
 export * from "./analytics";
@@ -31,33 +36,71 @@ export class Scanner {
             this.claims = result.claims;
         return result;
     }
+    /** Scan a driver's licence or provincial ID card via PDF417 barcode. */
     async scan() {
         // (1) LICENSE GATE -----------------------------------------------------
-        if (!this.claims) {
-            const result = await this.init();
-            if (!result.valid)
-                return { ok: false, error: `license_${result.reason}` };
-        }
-        // cheap per-scan expiry re-check (no crypto) so a long session can't outlive the token
-        if (!this.claims || isExpired(this.claims)) {
-            return { ok: false, error: "license_expired" };
-        }
+        const licenseError = await this.checkLicense();
+        if (licenseError)
+            return { ok: false, error: licenseError };
         // (2) NATIVE DECODE ----------------------------------------------------
         const raw = await this.cfg.native.captureAndDecodePdf417();
         if (!raw) {
             await this.emit("unknown", "", false, "low");
             return { ok: false, error: "no_barcode" };
         }
-        // (3) PARSE ------------------------------------------------------------
-        const aamva = parseAamva(raw);
-        if (!aamva.isAamva) {
+        // (3) PARSE — route to the correct parser based on format signature ------
+        const trimmedRaw = raw.replace(/^[\x00-\x1f\s]+/, "");
+        let document;
+        if (trimmedRaw.startsWith("@") || raw.includes("ANSI ")) {
+            const aamva = parseAamva(raw);
+            if (!aamva.isAamva) {
+                await this.emit("unknown", "", false, "low");
+                return { ok: false, error: "not_aamva" };
+            }
+            document = toCanonical(aamva);
+        }
+        else if (trimmedRaw.startsWith("%")) {
+            const ms = parseMagstripe(raw);
+            if (!ms.isMagstripe) {
+                await this.emit("unknown", "", false, "low");
+                return { ok: false, error: "not_aamva" };
+            }
+            document = magstripeToCanonical(ms);
+        }
+        else {
             await this.emit("unknown", "", false, "low");
             return { ok: false, error: "not_aamva" };
         }
+        // (4) ANALYTICS (PII-FREE) --------------------------------------------
+        await this.emit(document.documentType, document.jurisdiction, true, "high");
+        // (5) RETURN -----------------------------------------------------------
+        return { ok: true, document };
+    }
+    /** Scan a passport via on-device MRZ text recognition. */
+    async scanPassport() {
+        // (1) LICENSE GATE -----------------------------------------------------
+        const licenseError = await this.checkLicense();
+        if (licenseError)
+            return { ok: false, error: licenseError };
+        // (2) NATIVE TEXT RECOGNITION ------------------------------------------
+        if (!this.cfg.mrzNative)
+            return { ok: false, error: "no_mrz" };
+        const lines = await this.cfg.mrzNative.captureAndRecognizeMrz();
+        if (!lines || lines.length === 0) {
+            await this.emit("unknown", "", false, "low", "mrz");
+            return { ok: false, error: "no_mrz" };
+        }
+        // (3) PARSE ------------------------------------------------------------
+        const mrz = parseMrz(lines);
+        if (!mrz.isMrz || mrz.confidence === 0) {
+            await this.emit("unknown", "", false, "low", "mrz");
+            return { ok: false, error: "no_mrz" };
+        }
         // (4) CANONICAL --------------------------------------------------------
-        const document = toCanonical(aamva);
+        const document = mrzToCanonical(mrz);
         // (5) ANALYTICS (PII-FREE) --------------------------------------------
-        await this.emit(document.documentType, document.jurisdiction, true, "high");
+        const bucket = mrz.confidence >= 0.8 ? "high" : mrz.confidence >= 0.6 ? "medium" : "low";
+        await this.emit(document.documentType, document.jurisdiction, true, bucket, "mrz");
         // (6) RETURN -----------------------------------------------------------
         return { ok: true, document };
     }
@@ -65,13 +108,25 @@ export class Scanner {
     async flushAnalytics() {
         await this.analytics.flush();
     }
-    async emit(documentType, jurisdiction, success, confidenceBucket) {
+    // ─── Private helpers ──────────────────────────────────────────────────────
+    async checkLicense() {
+        if (!this.claims) {
+            const result = await this.init();
+            if (!result.valid)
+                return `license_${result.reason}`;
+        }
+        // Cheap per-scan expiry re-check (no crypto) so a long session can't outlive the token.
+        if (!this.claims || isExpired(this.claims))
+            return "license_expired";
+        return null;
+    }
+    async emit(documentType, jurisdiction, success, confidenceBucket, source = "barcode") {
         await this.analytics.record({
             jti: this.claims?.jti ?? "unknown",
             ts: new Date().toISOString(),
             documentType,
             jurisdiction,
-            source: "barcode",
+            source,
             success,
             confidenceBucket,
             deviceModel: this.cfg.deviceModel,

package/dist/magstripe.d.ts

@@ -0,0 +1,21 @@
+export interface MagstripeResult {
+    isMagstripe: boolean;
+    jurisdiction?: string;
+    iin?: string;
+    lastName?: string;
+    firstName?: string;
+    dateOfBirth?: string;
+    expiryDate?: string;
+    documentNumber?: string;
+    sex?: string;
+    addressStreet?: string;
+    addressCity?: string;
+    addressRegion?: string;
+    addressPostalCode?: string;
+    raw: {
+        track1?: string;
+        track2?: string;
+        track3?: string;
+    };
+}
+export declare function parseMagstripe(raw: string): MagstripeResult;

package/dist/magstripe.js

@@ -0,0 +1,133 @@
+// magstripe.ts
+// Parser for the AAMVA magnetic-stripe track format used by some Canadian provinces
+// (confirmed BC; likely ON/AB). Three tracks concatenated in one PDF417 payload:
+//   Track 1  %...?   jurisdiction + name + address
+//   Track 2  ;...?   IIN + document number + expiry (YYMM) + DOB (CCYYMMDD)
+//   Track 3  ...?    postal code + physical description (layout varies by jurisdiction)
+//
+// Reference: AAMVA DL/ID Card Design Standard, magnetic-stripe annex.
+// Returns the last calendar day of a 1-based month in the given year.
+function lastDayOfMonth(year, month) {
+    // Date(y, m, 0) with 0-indexed month m = last day of month (m-1); passing 1-based month directly works.
+    return new Date(year, month, 0).getDate();
+}
+function applyTrack1(out, t1) {
+    // Format: jurisdiction(2) + city + ^ + SURNAME[,]$GIVEN NAMES + ^ + STREET$CITY PROVINCE
+    const parts = t1.split("^");
+    if (parts.length < 2)
+        return;
+    out.jurisdiction = parts[0].slice(0, 2);
+    const namePart = parts[1];
+    const dollar = namePart.indexOf("$");
+    if (dollar !== -1) {
+        out.lastName = namePart.slice(0, dollar).replace(/,+$/, "").trim();
+        out.firstName = namePart.slice(dollar + 1).trim();
+    }
+    else {
+        out.lastName = namePart.replace(/,+$/, "").trim();
+    }
+    if (parts.length < 3)
+        return;
+    const addrPart = parts[2].trim();
+    const addrDollar = addrPart.indexOf("$");
+    if (addrDollar === -1) {
+        out.addressStreet = addrPart;
+        return;
+    }
+    out.addressStreet = addrPart.slice(0, addrDollar).trim();
+    const cityProv = addrPart.slice(addrDollar + 1).trim();
+    // Province is the trailing space-separated token (always 2 chars); city is the rest.
+    const lastSpace = cityProv.lastIndexOf(" ");
+    if (lastSpace !== -1) {
+        out.addressCity = cityProv.slice(0, lastSpace).trim();
+        out.addressRegion = cityProv.slice(lastSpace + 1).trim();
+    }
+    else if (cityProv.length >= 2) {
+        out.addressRegion = cityProv.slice(-2);
+        out.addressCity = cityProv.slice(0, -2).trim();
+    }
+}
+function applyTrack2(out, t2) {
+    // Format: IIN(6) + document-number + = + expiry-YYMM(4) + DOB-CCYYMMDD(8) + = + [discretionary]
+    if (t2.length < 7)
+        return;
+    out.iin = t2.slice(0, 6);
+    const eq1 = t2.indexOf("=");
+    if (eq1 === -1)
+        return;
+    out.documentNumber = t2.slice(6, eq1);
+    const after = t2.slice(eq1 + 1);
+    if (after.length < 12)
+        return;
+    const expiryYYMM = after.slice(0, 4);
+    const dobCCYYMMDD = after.slice(4, 12);
+    if (/^\d{4}$/.test(expiryYYMM)) {
+        const yy = parseInt(expiryYYMM.slice(0, 2), 10);
+        const mm = parseInt(expiryYYMM.slice(2, 4), 10);
+        const year = yy < 70 ? 2000 + yy : 1900 + yy;
+        const day = lastDayOfMonth(year, mm);
+        out.expiryDate = `${year}-${String(mm).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+    }
+    if (/^\d{8}$/.test(dobCCYYMMDD)) {
+        out.dateOfBirth =
+            `${dobCCYYMMDD.slice(0, 4)}-${dobCCYYMMDD.slice(4, 6)}-${dobCCYYMMDD.slice(6, 8)}`;
+    }
+}
+function applyTrack3(out, t3) {
+    // Track 3 layout varies by jurisdiction — extract only what we can identify reliably.
+    // Canadian postal code: letter-digit-letter-digit-letter-digit (no space in raw)
+    const postalMatch = t3.match(/([A-Z]\d[A-Z]\d[A-Z]\d)/);
+    if (postalMatch) {
+        const p = postalMatch[1];
+        out.addressPostalCode = `${p.slice(0, 3)} ${p.slice(3)}`;
+    }
+    // Sex: M or F immediately followed by 3 digits (height in cm)
+    const physMatch = t3.match(/([MF])(\d{3})/);
+    if (physMatch)
+        out.sex = physMatch[1];
+}
+export function parseMagstripe(raw) {
+    const out = { isMagstripe: false, raw: {} };
+    // Strip leading control/whitespace for format detection; keep raw intact for track extraction.
+    const s = raw.replace(/^[\x00-\x1f\s]+/, "");
+    if (!s.startsWith("%"))
+        return out;
+    // Track 1: % sentinel to first ?
+    const t1End = s.indexOf("?");
+    if (t1End === -1)
+        return out;
+    const t1 = s.slice(1, t1End);
+    if (!t1.includes("^"))
+        return out; // must have the field-separator to be a DL track 1
+    out.isMagstripe = true;
+    out.raw.track1 = t1;
+    applyTrack1(out, t1);
+    // Track 2: ; sentinel somewhere after track 1
+    const after1 = s.slice(t1End + 1);
+    const t2SentinelPos = after1.indexOf(";");
+    if (t2SentinelPos === -1)
+        return out;
+    const t2ContentStart = t2SentinelPos + 1;
+    const t2End = after1.indexOf("?", t2ContentStart);
+    if (t2End === -1)
+        return out;
+    const t2 = after1.slice(t2ContentStart, t2End);
+    out.raw.track2 = t2;
+    applyTrack2(out, t2);
+    // Track 3: everything after track 2's ? up to the last ? in the string.
+    // Inter-track bytes (e.g. "_%0A" — an underscore + percent-encoded LF) are stripped.
+    const afterT2 = after1.slice(t2End + 1);
+    const t3LastQ = afterT2.lastIndexOf("?");
+    if (t3LastQ > 0) {
+        const t3Section = afterT2.slice(0, t3LastQ);
+        // Decode any percent-encoded sequences in the inter-track gap, then strip
+        // leading non-uppercase chars (underscores, decoded control chars, etc.).
+        const t3Decoded = t3Section.replace(/%([0-9A-Fa-f]{2})/g, (_, h) => String.fromCharCode(parseInt(h, 16)));
+        const t3 = t3Decoded.replace(/^[^A-Z]+/, "");
+        if (t3.length > 0) {
+            out.raw.track3 = t3;
+            applyTrack3(out, t3);
+        }
+    }
+    return out;
+}

package/dist/mrz.d.ts

@@ -0,0 +1,30 @@
+export interface MrzResult {
+    isMrz: boolean;
+    documentType?: string;
+    issuingCountry?: string;
+    lastName?: string;
+    firstName?: string;
+    documentNumber?: string;
+    nationality?: string;
+    dateOfBirth?: string;
+    sex?: string;
+    expiryDate?: string;
+    personalNumber?: string;
+    confidence: number;
+    checksumFailures: string[];
+    raw: {
+        line1: string;
+        line2: string;
+    };
+}
+/**
+ * Find and parse a TD3 MRZ from an array of OCR-recognised text lines.
+ * Handles passports (P<), emergency travel documents (PU), permanent resident
+ * travel documents (PR), and any other ICAO TD3 document type starting with P.
+ *
+ * Lines are normalised (spaces stripped, uppercased) before matching; lines
+ * within ±1 char of the required 44 are accepted with padding/trimming.
+ * Each element may also contain newline-separated sub-lines (some OCR engines
+ * return both MRZ rows as one observation).
+ */
+export declare function parseMrz(lines: string[]): MrzResult;

package/dist/mrz.js

@@ -0,0 +1,240 @@
+// mrz.ts
+// ICAO 9303 TD3 two-line × 44-char MRZ parser with full check-digit validation.
+// TD1/TD2 (ID-card) formats are out of scope and left for future work.
+//
+// Usage from scanner-core:
+//   parseMrz(lines)  — pass all OCR lines; function locates the TD3 pair.
+// ─── ICAO 7-3-1 check-digit algorithm ────────────────────────────────────────
+const WEIGHT = [7, 3, 1];
+function charValue(c) {
+    if (c === "<")
+        return 0;
+    const code = c.charCodeAt(0);
+    if (code >= 48 && code <= 57)
+        return code - 48; // '0'–'9'
+    if (code >= 65 && code <= 90)
+        return code - 55; // 'A'–'Z' → 10–35
+    return 0;
+}
+function checkDigit(s) {
+    let sum = 0;
+    for (let i = 0; i < s.length; i++)
+        sum += charValue(s[i]) * WEIGHT[i % 3];
+    return sum % 10;
+}
+// ─── 2-digit year resolution ─────────────────────────────────────────────────
+function resolveYear(yy, mustBePast) {
+    const now = new Date().getFullYear();
+    const century = Math.floor(now / 100) * 100;
+    const candidate = century + yy;
+    // DOB must be in the past; if the candidate is a future year, step back a century.
+    if (mustBePast && candidate > now)
+        return candidate - 100;
+    // Expiry/issue: if candidate is implausibly far in the past (> 50 years ago),
+    // step forward a century — handles the century rollover for long-lived documents.
+    if (!mustBePast && candidate < now - 50)
+        return candidate + 100;
+    return candidate;
+}
+function parseMrzDate(yymmdd, mustBePast) {
+    if (!/^\d{6}$/.test(yymmdd))
+        return undefined;
+    const yy = parseInt(yymmdd.slice(0, 2), 10);
+    const mm = yymmdd.slice(2, 4);
+    const dd = yymmdd.slice(4, 6);
+    return `${resolveYear(yy, mustBePast)}-${mm}-${dd}`;
+}
+// ─── Name parsing ─────────────────────────────────────────────────────────────
+function parseName(field) {
+    // SURNAME<<GIVEN<NAMES<<…  — primary and secondary identifiers split by <<
+    const idx = field.indexOf("<<");
+    if (idx === -1)
+        return { lastName: field.replace(/</g, " ").trim(), firstName: "" };
+    const lastName = field.slice(0, idx).replace(/</g, " ").trim();
+    const firstName = field.slice(idx + 2).replace(/</g, " ").trim();
+    return { lastName, firstName };
+}
+// ─── Core TD3 parser (expects exactly two 44-char lines) ──────────────────────
+function parseTd3(l1, l2) {
+    const failures = [];
+    const verify = (label, data, expectedChar) => {
+        const expected = parseInt(expectedChar, 10);
+        if (isNaN(expected) || checkDigit(data) !== expected)
+            failures.push(label);
+    };
+    // ── Line 1 ──────────────────────────────────────────
+    const documentType = l1[0];
+    const issuingCountry = l1.slice(2, 5).replace(/</g, "");
+    const { lastName, firstName } = parseName(l1.slice(5, 44));
+    // ── Line 2 ──────────────────────────────────────────
+    const docNumField = l2.slice(0, 9);
+    const docNumCheck = l2[9];
+    const nationality = l2.slice(10, 13).replace(/</g, "");
+    const dobField = l2.slice(13, 19);
+    const dobCheck = l2[19];
+    const sexChar = l2[20];
+    const expField = l2.slice(21, 27);
+    const expCheck = l2[27];
+    const persField = l2.slice(28, 42);
+    const persCheck = l2[42];
+    const composite = l2[43];
+    // ── Check digits ─────────────────────────────────────
+    verify("documentNumber", docNumField, docNumCheck);
+    verify("dateOfBirth", dobField, dobCheck);
+    verify("expiryDate", expField, expCheck);
+    // Personal-number check: ICAO allows "<" when the field is unused/absent.
+    let totalChecks = 4; // docNum + DOB + expiry + composite
+    if (persCheck !== "<") {
+        verify("personalNumber", persField, persCheck);
+        totalChecks = 5;
+    }
+    // Composite covers positions 1–10, 14–20, 22–43 of line 2 (0-based: [0:10],[13:20],[21:43])
+    verify("composite", l2.slice(0, 10) + l2.slice(13, 20) + l2.slice(21, 43), composite);
+    const passed = totalChecks - failures.length;
+    const confidence = Math.max(0, passed / totalChecks);
+    return {
+        isMrz: true,
+        documentType,
+        issuingCountry: issuingCountry || undefined,
+        lastName: lastName || undefined,
+        firstName: firstName || undefined,
+        documentNumber: docNumField.replace(/</g, "") || undefined,
+        nationality: nationality || undefined,
+        dateOfBirth: parseMrzDate(dobField, true),
+        sex: (sexChar && sexChar !== "<") ? sexChar : undefined,
+        expiryDate: parseMrzDate(expField, false),
+        personalNumber: persField.replace(/</g, "") || undefined,
+        confidence,
+        checksumFailures: failures,
+        raw: { line1: l1, line2: l2 },
+    };
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+// ─── VIZ (biographical zone) name cross-reference ────────────────────────────
+//
+// The OCR-B MRZ font encodes word separators as "<".  Vision and ML Kit
+// frequently misread "<" as "C", "S", "K", "@", "&", "/" etc., making the
+// MRZ name field unreliable.  However, Vision also reads the standard-font
+// biographical zone above the MRZ (surname row, given-names row) with high
+// accuracy because that zone uses a regular typeface with no fill characters.
+//
+// Strategy:
+//   1. After parseTd3 produces a (possibly garbled) name, scan all non-MRZ
+//      Vision lines for "name candidates" – short all-Latin-letter lines
+//      whose uppercase tokens ALL appear verbatim in the raw 39-char MRZ
+//      name field.
+//   2. Sort candidates by their earliest token position in the name field:
+//      the surname always starts before the given names in TD3.
+//   3. Override lastName / firstName with the clean biographical-zone values.
+// Words that commonly appear in Vision results as standalone lines but are
+// NOT personal name components.
+const VIZ_SKIP_TOKENS = new Set([
+    "PASSPORT", "PASAPORTE", "TRAVEL", "DOCUMENT", "EMERGENCY", "CANADA", "MEXICO",
+    "MEXICANA", "MEXICANO", "CANADIAN", "CANADIENNE", "NATIONALITY", "NATIONAL",
+    "RESIDENCE", "RESIDENT", "PERMANENT", "SURNAME", "GIVEN", "NAMES", "DATE", "BIRTH",
+    "EXPIRY", "ISSUED", "AUTHORITY", "SIGNATURE", "SEX", "SEXE", "TYPE", "ISSUING",
+    "FEDERAL", "REPUBLIC", "OFFICIAL", "HOLDER", "OTTAWA", "GATINEAU", "GOVERNMENT",
+    "UNITED", "STATES", "KINGDOM", "COMMONWEALTH", "FOREIGN", "AFFAIRS", "INTERIOR",
+]);
+function isVizNameCandidate(line) {
+    if (/\d/.test(line))
+        return false; // rejects dates, IDs, etc.
+    const up = line.replace(/\s/g, "").toUpperCase();
+    if (!/^[A-Z]+$/.test(up))
+        return false; // must be pure ASCII uppercase after removing spaces
+    const words = line.trim().toUpperCase().split(/\s+/).filter(w => w.length >= 2);
+    if (words.length === 0 || words.length > 4)
+        return false;
+    return !words.some(w => VIZ_SKIP_TOKENS.has(w));
+}
+function vizNameTokens(s) {
+    return (s.toUpperCase().match(/[A-Z]{3,}/g) ?? []);
+}
+function refineNamesFromViz(result, flat, mrzIdx) {
+    if (!result.isMrz)
+        return;
+    // The raw 39-char name field from line 1 may contain OCR-corrupted separators.
+    const rawName = result.raw.line1.slice(5, 44).toUpperCase();
+    const nonMrz = flat.filter((_, i) => i !== mrzIdx && i !== mrzIdx + 1);
+    const candidates = [];
+    for (const line of nonMrz) {
+        if (!isVizNameCandidate(line))
+            continue;
+        const clean = line.trim().toUpperCase().replace(/\s+/g, " ");
+        const tokens = vizNameTokens(clean).filter(t => t.length >= 3);
+        if (tokens.length === 0)
+            continue;
+        // Every token of this Vision line must appear somewhere in the raw MRZ name field.
+        const hits = tokens.filter(t => rawName.includes(t));
+        if (hits.length < tokens.length)
+            continue;
+        const firstPos = Math.min(...tokens.map(t => rawName.indexOf(t)).filter(p => p >= 0));
+        if (!candidates.some(c => c.clean === clean)) {
+            candidates.push({ clean, firstPos });
+        }
+    }
+    if (candidates.length === 0)
+        return;
+    // Surname always starts at or near position 0 in the name field;
+    // given names follow the "<<" separator (position ≥ ~10).
+    candidates.sort((a, b) => a.firstPos - b.firstPos);
+    const first = candidates[0];
+    const second = candidates[1];
+    if (first.firstPos <= 5) {
+        result.lastName = first.clean;
+        if (second)
+            result.firstName = second.clean;
+    }
+    else {
+        // Only given names were recoverable from VIZ (surname was too corrupted).
+        result.firstName = first.clean;
+    }
+}
+// Normalise an OCR line to exactly 44 chars for TD3:
+// - Strip whitespace (Vision / ML Kit insert spaces in OCR-B)
+// - Uppercase
+// - If 43 chars: pad with "<" (OCR commonly drops a trailing filler char)
+// - If 45 chars: trim to 44 (OCR occasionally adds one)
+// - Otherwise return null (too far off to be a TD3 line)
+function toTd3Line(raw) {
+    const s = raw.replace(/\s/g, "").toUpperCase();
+    if (s.length === 44)
+        return s;
+    if (s.length === 43)
+        return s + "<";
+    if (s.length === 45)
+        return s.slice(0, 44);
+    return null;
+}
+/**
+ * Find and parse a TD3 MRZ from an array of OCR-recognised text lines.
+ * Handles passports (P<), emergency travel documents (PU), permanent resident
+ * travel documents (PR), and any other ICAO TD3 document type starting with P.
+ *
+ * Lines are normalised (spaces stripped, uppercased) before matching; lines
+ * within ±1 char of the required 44 are accepted with padding/trimming.
+ * Each element may also contain newline-separated sub-lines (some OCR engines
+ * return both MRZ rows as one observation).
+ */
+export function parseMrz(lines) {
+    const empty = {
+        isMrz: false, confidence: 0, checksumFailures: [], raw: { line1: "", line2: "" },
+    };
+    // Flatten: split on newlines in case the OCR engine joined both MRZ rows.
+    const flat = lines.flatMap(l => l.split(/\n/));
+    console.log("[parseMrz] input lines:", flat.length, flat.map(l => `"${l.replace(/\s/g, "").slice(0, 10)}…(${l.replace(/\s/g, "").length})"`));
+    for (let i = 0; i < flat.length - 1; i++) {
+        const l1 = toTd3Line(flat[i]);
+        const l2 = toTd3Line(flat[i + 1]);
+        if (!l1 || !l2)
+            continue;
+        if (/^P[A-Z<]/.test(l1)) {
+            console.log("[parseMrz] TD3 pair found at index", i, "→ parsing");
+            const result = parseTd3(l1, l2);
+            refineNamesFromViz(result, flat, i);
+            return result;
+        }
+    }
+    console.log("[parseMrz] no TD3 pair found in", flat.length, "lines");
+    return empty;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parselo/scanner-core",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/parselo-io/parselo-sdk.git",