@parselo/scanner-core 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,261 @@
+# @parselo/scanner-core
+
+Platform-agnostic core for the Parselo ID scanning SDK. Parses AAMVA PDF417
+barcodes, magnetic-stripe tracks, ICAO 9303 MRZ from passports and travel
+documents, and Mexican INE (Credencial para Votar) credentials 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 |
+| Mexican INE (Credencial para Votar), models D–J | ICAO 9303 TD1 MRZ (3 × 30 chars) | Extraction + offline integrity only — see "INE offline integrity" below. Validated on 2 real cards on-device; models D onward carry the MRZ, models A–C predate it and are detected and rejected cleanly (`no_ine`) rather than crashing. PDF417 (proprietary/undocumented) is stubbed pending real sample payloads. |
+
+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.
+
+## Scanning a Mexican INE (Credencial para Votar)
+
+```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;
+  },
+};
+
+const scanner = new Scanner({ license, analytics, native, mrzNative });
+await scanner.init();
+
+const result = await scanner.scanIne();
+if (result.ok && result.document) {
+  const { fields } = result.document;
+  console.log(fields.firstName?.value, fields.lastName?.value); // given names, paternal surname
+  console.log(fields.dateOfBirth?.value);
+}
+```
+
+Reuses the same `mrzNative` capture as `scanPassport()` — INE cards from model D
+onward carry a 3-line, 30-char ICAO 9303 TD1 MRZ on the back, located and
+validated the same way the TD3 passport MRZ is. `parseIneMrz()` implements the
+generic TD1 structure with no per-model branching, so it should apply uniformly
+across models D–J; validated so far against 2 real cards on-device (see the root
+README's Development notes for what that validation caught — a real MRZ sex-field
+convention neither the original implementation nor any public spec we had access
+to got right on the first try). Models A–C predate the MRZ and have no
+on-device-extractable structured data via this path; those, and any non-INE MRZ
+input, are rejected cleanly (`error: "no_ine"`) rather than producing garbage output.
+
+**INE offline integrity — read this before using these fields in a product decision.**
+`buildIneCredential()` (re-exported from this package) produces an `integrity` block:
+
+```ts
+interface IneIntegrity {
+  mrzCheckDigitsValid: boolean;
+  curpCheckDigitValid: boolean;
+  claveElectorStructureValid: boolean;
+  crossFieldConsistent: boolean;   // DOB/sex agree across every source present
+  overall: "consistent" | "inconsistent" | "insufficient_data";
+}
+```
+
+This proves internal consistency only — check digits, structural shape, and
+agreement between the MRZ, CURP, and Clave de Elector when more than one is
+present. **It does not prove the card is genuine, current, or registered with
+INE.** Only INE's own (off-device, consent-gated) Lista Nominal verification
+service can do that, and this SDK deliberately does not call it — see the root
+README for why. Never surface `overall === "consistent"` to an end user as
+"verified" or "valid credential".
+
+The MRZ alone does not carry a CURP or Clave de Elector (INE's PDF417 might, but
+its encoding is proprietary/undocumented and is currently stubbed — see `ine.ts`).
+Until that's implemented from real sample payloads, `curp` and `claveElector` are
+only populated if you pass them into `buildIneCredential()` yourself from another
+source, and `integrity.overall` correctly reports `"insufficient_data"` when no
+identifiers besides the MRZ were available to cross-check.
+
+## Canonical document shape
+
+```ts
+interface CanonicalDocument {
+  documentType: "drivers_license" | "id_card" | "passport" | "ine" | "unknown";
+  jurisdiction: string;   // "CA-QC", "CA-BC", "CA", "MEX", "MX", …
+  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 / INE
+    country?:           Field;  // ICAO 3-char issuing country, "MEX" for INE
+  };
+  raw?: Record<string, string>;   // INE also carries raw.curp / raw.claveElector when present
+}
+```
+
+Mexican naming has two surnames with no dedicated canonical slot: INE maps
+`lastName` to the paternal surname and `middleName` to the maternal surname
+(same "reuse the generic shape" approach every document type here takes).
+
+```ts
+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
+  | "no_ine"                          // INE 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();
+```
+
+## Design notes
+
+- **Every parser file (`aamva.ts`, `magstripe.ts`, `mrz.ts`, `ine.ts`) is fully
+  self-contained** — none of them import from each other at the value level,
+  even where the logic genuinely overlaps (`ine.ts` has its own internal copy
+  of the ICAO 7-3-1 check-digit algorithm and 2-digit-year resolution that
+  `mrz.ts` also implements). This is deliberate, not an oversight: `src/test.ts`
+  runs every parser directly through Node's ESM loader
+  (`node --experimental-strip-types`), which requires exact-extension relative
+  specifiers (`./mrz.ts`); the real `tsc` build targets bundler-style module
+  resolution and expects extension-less specifiers (`./mrz`) for downstream
+  Vite/Capacitor consumers. A single cross-file import statement can't satisfy
+  both resolution modes, so `ine.ts` duplicates the ~20 lines of shared
+  algorithm rather than importing them — consistent with how every other
+  parser file in this package was already structured before INE existed.
+- **`ine.ts` implements the generic ICAO 9303 TD1 structure, not a per-model
+  INE format.** There's no model-letter detection or branching anywhere in it.
+  INE cards from model D onward all carry a standard TD1 MRZ; models A–C
+  predate it and simply have nothing for this path to extract. This has been
+  validated on 2 real cards (see root README's Development notes for a bug
+  that validation caught: INE's MRZ sex field is the literal Spanish `H`/`M`
+  character, not an ICAO M/F code needing translation — an assumption that
+  looked reasonable by analogy to the TD3 passport parser and was wrong).
+
+## License
+
+MIT

package/dist/canonical.d.ts

@@ -1,12 +1,14 @@
 import type { AamvaResult } from "./aamva";
 import type { MagstripeResult } from "./magstripe";
+import type { MrzResult } from "./mrz";
+import type { IneCredential } from "./ine";
 export type FieldSource = "barcode" | "ocr" | "mrz";
 export interface CanonicalField {
     value: string;
     confidence: number;
     source: FieldSource;
 }
-export type DocumentType = "drivers_license" | "id_card" | "passport" | "unknown";
+export type DocumentType = "drivers_license" | "id_card" | "passport" | "ine" | "unknown";
 export interface CanonicalDocument {
     documentType: DocumentType;
     jurisdiction: string;
@@ -28,5 +30,7 @@ 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;
+export declare function ineToCanonical(i: IneCredential): CanonicalDocument;

package/dist/canonical.js

@@ -2,6 +2,38 @@
 // 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 ?? "";
@@ -62,3 +94,48 @@ export function toCanonical(a, confidence = 1.0) {
         raw: e,
     };
 }
+// Mexican naming has two surnames; there is no dedicated canonical slot for
+// that, so paternal maps to lastName and maternal to middleName (same
+// reuse-the-generic-shape approach as every other document type here).
+// documentNumber prefers the CIC (from MRZ) since OCR/emissionNumber are not
+// populated by the MRZ-only path this SDK currently implements.
+export function ineToCanonical(i) {
+    const source = i.source === "MRZ" ? "mrz" : "barcode";
+    const confidence = i.source === "MRZ" ? 1.0 : 0.5; // PDF417 is best-effort/unimplemented today
+    const field = (value) => value !== undefined ? { value, confidence, source } : undefined;
+    // integrity.* is stuffed into raw (stringified) rather than added as a typed
+    // CanonicalDocument field, since raw is already documented as "every parsed
+    // element, for debugging/QA" and every other document type keeps
+    // format-specific data out of the shared `fields` shape. Never rename these
+    // keys to imply "verified"/"valid" — see ine.ts's integrity boundary comment.
+    const raw = {
+        integrityOverall: i.integrity.overall,
+        mrzCheckDigitsValid: String(i.integrity.mrzCheckDigitsValid),
+        curpCheckDigitValid: String(i.integrity.curpCheckDigitValid),
+        claveElectorStructureValid: String(i.integrity.claveElectorStructureValid),
+        crossFieldConsistent: String(i.integrity.crossFieldConsistent),
+    };
+    if (i.mrzLines) {
+        raw.mz1 = i.mrzLines.mz1;
+        raw.mz2 = i.mrzLines.mz2;
+        raw.mz3 = i.mrzLines.mz3;
+    }
+    if (i.curp)
+        raw.curp = i.curp.value;
+    if (i.claveElector)
+        raw.claveElector = i.claveElector.value;
+    return {
+        documentType: "ine",
+        jurisdiction: "MX",
+        fields: {
+            firstName: field(i.givenNames),
+            lastName: field(i.surnamePaternal),
+            middleName: field(i.surnameMaternal),
+            dateOfBirth: field(i.dateOfBirth),
+            sex: field(i.sex),
+            documentNumber: field(i.cic ?? i.ocr),
+            country: field("MEX"),
+        },
+        raw,
+    };
+}

package/dist/index.d.ts

@@ -3,12 +3,17 @@ import { type LicenseResult } from "./license";
 import { type AnalyticsConfig } from "./analytics";
 export * from "./aamva";
 export * from "./magstripe";
+export * from "./mrz";
+export * from "./ine";
 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;
@@ -17,9 +22,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" | "no_ine";
 export interface ScanResult {
     ok: boolean;
     document?: CanonicalDocument;
@@ -32,8 +38,24 @@ 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>;
+    /**
+     * Scan a Mexican INE (Credencial para Votar) via on-device MRZ text
+     * recognition. Reuses the same mrzNative capture used by scanPassport() —
+     * no new native path required, since native code only does OCR and all
+     * parsing stays in this package.
+     *
+     * This produces extraction + offline integrity signals only. It does NOT
+     * verify the credential against INE's Lista Nominal registry — that is an
+     * off-device, consent-gated service and is explicitly out of scope (see
+     * README). Do not present `document`'s presence as proof of authenticity.
+     */
+    scanIne(): Promise<ScanResult>;
     /** Flush buffered analytics (e.g. on app foreground/background). */
     flushAnalytics(): Promise<void>;
+    private checkLicense;
     private emit;
 }

package/dist/index.js

@@ -1,16 +1,21 @@
 // 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 { parseMagstripe } from "./magstripe";
-import { toCanonical, magstripeToCanonical } from "./canonical";
+import { parseMrz } from "./mrz";
+import { parseIneMrz, buildIneCredential } from "./ine";
+import { toCanonical, magstripeToCanonical, mrzToCanonical, ineToCanonical } from "./canonical";
 import { verifyLicense, isExpired } from "./license";
 import { ScanAnalytics } from "./analytics";
 export * from "./aamva";
 export * from "./magstripe";
+export * from "./mrz";
+export * from "./ine";
 export * from "./canonical";
 export * from "./license";
 export * from "./analytics";
@@ -33,17 +38,12 @@ 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) {
@@ -73,9 +73,75 @@ export class Scanner {
             await this.emit("unknown", "", false, "low");
             return { ok: false, error: "not_aamva" };
         }
-        // (4) CANONICAL already set above --------------------------------------
-        // (5) ANALYTICS (PII-FREE) --------------------------------------------
+        // (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 = mrzToCanonical(mrz);
+        // (5) ANALYTICS (PII-FREE) --------------------------------------------
+        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 };
+    }
+    /**
+     * Scan a Mexican INE (Credencial para Votar) via on-device MRZ text
+     * recognition. Reuses the same mrzNative capture used by scanPassport() —
+     * no new native path required, since native code only does OCR and all
+     * parsing stays in this package.
+     *
+     * This produces extraction + offline integrity signals only. It does NOT
+     * verify the credential against INE's Lista Nominal registry — that is an
+     * off-device, consent-gated service and is explicitly out of scope (see
+     * README). Do not present `document`'s presence as proof of authenticity.
+     */
+    async scanIne() {
+        // (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_ine" };
+        const lines = await this.cfg.mrzNative.captureAndRecognizeMrz();
+        if (!lines || lines.length === 0) {
+            await this.emit("unknown", "", false, "low", "mrz");
+            return { ok: false, error: "no_ine" };
+        }
+        // (3) PARSE — TD1 MRZ only today; PDF417 is stubbed (see ine.ts) -------
+        const mrz = parseIneMrz(lines);
+        if (!mrz.isIne || mrz.confidence === 0) {
+            await this.emit("unknown", "", false, "low", "mrz");
+            return { ok: false, error: "no_ine" };
+        }
+        // (4) CREDENTIAL + CANONICAL ---------------------------------------------
+        const credential = buildIneCredential({ mrz, source: "MRZ" });
+        const document = ineToCanonical(credential);
+        // (5) ANALYTICS (PII-FREE) --------------------------------------------
+        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 };
     }
@@ -83,13 +149,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/ine.d.ts

@@ -0,0 +1,95 @@
+export interface IneMrzResult {
+    isIne: boolean;
+    documentCode?: string;
+    issuingCountry?: string;
+    documentNumber?: string;
+    optionalData1?: string;
+    dateOfBirth?: string;
+    sex?: string;
+    expiryDate?: string;
+    nationality?: string;
+    optionalData2?: string;
+    surnamePaternal?: string;
+    surnameMaternal?: string;
+    givenNames?: string;
+    confidence: number;
+    checksumFailures: string[];
+    raw: {
+        line1: string;
+        line2: string;
+        line3: string;
+    };
+}
+/**
+ * Find and parse an INE TD1 MRZ from an array of OCR-recognised text lines.
+ * Mirrors parseMrz()'s tolerant line-location strategy, but for the 3×30-char
+ * TD1 shape instead of TD3's 2×44. Requires a Mexico-issued ID-class document
+ * code (documentCode starting "I", issuingCountry "MEX") so this never
+ * collides with a Canadian/US TD1 or a TD3 passport pair.
+ */
+export declare function parseIneMrz(lines: string[]): IneMrzResult;
+/** Compute the expected 18th (check) digit for a CURP, or undefined if malformed. */
+export declare function curpCheckDigit(curp: string): number | undefined;
+/** Validate a CURP's check digit. Does not confirm the CURP exists in RENAPO's registry. */
+export declare function isCurpCheckDigitValid(curp: string): boolean;
+export declare function claveElectorStructureValid(clave: string, cross?: {
+    dateOfBirth?: string;
+    sex?: string;
+}): boolean;
+export interface IneBarcodeResult {
+    supported: false;
+    reason: "unsupported_format";
+}
+export declare function parseInePdf417(_raw: string): IneBarcodeResult;
+export interface IneIntegrity {
+    mrzCheckDigitsValid: boolean;
+    curpCheckDigitValid: boolean;
+    claveElectorStructureValid: boolean;
+    crossFieldConsistent: boolean;
+    overall: "consistent" | "inconsistent" | "insufficient_data";
+}
+export interface IneCredential {
+    documentType: "MX_INE";
+    model: string;
+    surnamePaternal?: string;
+    surnameMaternal?: string;
+    givenNames?: string;
+    fullNameRaw?: string;
+    dateOfBirth?: string;
+    sex?: string;
+    claveElector?: {
+        value: string;
+        structureValid: boolean;
+    };
+    curp?: {
+        value: string;
+        checkDigitValid: boolean;
+    };
+    seccion?: string;
+    expiryYear?: string;
+    registrationYear?: string;
+    emissionNumber?: string;
+    ocr?: string;
+    cic?: string;
+    mrzLines?: {
+        mz1: string;
+        mz2: string;
+        mz3: string;
+    };
+    source: "MRZ" | "PDF417";
+    integrity: IneIntegrity;
+}
+/**
+ * Assemble a typed IneCredential + honest offline-integrity signal from
+ * whatever sources decoded successfully. `curp`/`claveElector` are optional
+ * because today only the MRZ path is implemented (PDF417 is stubbed above,
+ * pending real samples) and the MRZ does not carry either identifier — pass
+ * them in once a future source (PDF417 or OCR) can supply them.
+ */
+export declare function buildIneCredential(input: {
+    mrz?: IneMrzResult;
+    curp?: string;
+    claveElector?: string;
+    model?: string;
+    source?: "MRZ" | "PDF417";
+}): IneCredential;

package/dist/ine.js

@@ -0,0 +1,301 @@
+// ine.ts
+// Mexican INE ("Credencial para Votar") — MRZ (ICAO 9303 TD1) parser, CURP /
+// Clave de Elector offline integrity checks, and a stubbed PDF417 path.
+//
+// INE cards issued 2014+ carry a 3-line, 30-char-per-line TD1 MRZ. The line
+// segmentation and check-digit algorithm below are the same ICAO 7-3-1
+// scheme mrz.ts uses for TD3 passports, duplicated rather than imported:
+// every parser file in this package is self-contained (no cross-parser
+// imports anywhere) because src/test.ts runs each file directly through
+// Node's ESM loader with no bundler, which requires exact-extension
+// specifiers on relative imports — the opposite of the extension-less
+// specifiers the tsc "Bundler" resolution mode expects for the real build.
+// Keeping parser files standalone avoids straddling both requirements.
+//
+// IMPORTANT — what this module does NOT do:
+// It does not verify the card against INE's Lista Nominal registry (that is
+// an off-device service requiring a convenio with INE, explicit cardholder
+// consent, and a paid aggregator; it is out of scope — see root README).
+// Everything here runs on-device, offline, and proves only internal
+// consistency ("does this look like a well-formed, non-garbled, non-typo'd
+// card"), never document authenticity. Do not relabel `integrity.overall` as
+// "valid" or "verified" anywhere downstream — that would misrepresent what
+// an offline check can prove.
+// ─── ICAO 7-3-1 check-digit algorithm (see mrz.ts header comment above) ──────
+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;
+}
+function resolveYear(yy, mustBePast) {
+    const now = new Date().getFullYear();
+    const century = Math.floor(now / 100) * 100;
+    const candidate = century + yy;
+    if (mustBePast && candidate > now)
+        return candidate - 100;
+    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}`;
+}
+// ─── TD1 line location & normalisation ───────────────────────────────────────
+// Normalise an OCR line to exactly 30 chars for TD1 (mirrors toTd3Line in mrz.ts,
+// tolerant of the same +/-1 char OCR drop/add errors).
+function toTd1Line(raw) {
+    const s = raw.replace(/\s/g, "").toUpperCase();
+    if (s.length === 30)
+        return s;
+    if (s.length === 29)
+        return s + "<";
+    if (s.length === 31)
+        return s.slice(0, 30);
+    return null;
+}
+// ICAO 9303 reserves this slot for the English M/F sex code, so it would be
+// reasonable to assume INE follows suit and translates to its own H (Hombre)
+// / M (Mujer) convention. It does not: confirmed against a real card, INE
+// writes the Spanish letter directly into this MRZ position with no ICAO
+// translation — raw 'M' here already means Mujer, not "male". Pass it
+// through verbatim; do not "normalise" it against the ICAO convention.
+function readIneSex(c) {
+    return c === "H" || c === "M" ? c : undefined;
+}
+function parseIneName(field) {
+    const idx = field.indexOf("<<");
+    const primary = idx === -1 ? field : field.slice(0, idx);
+    const secondary = idx === -1 ? "" : field.slice(idx + 2);
+    const [paternal, maternal] = primary.split("<").map(s => s.trim()).filter(Boolean);
+    const givenNames = secondary.replace(/</g, " ").trim();
+    return {
+        surnamePaternal: paternal || undefined,
+        surnameMaternal: maternal || undefined,
+        givenNames: givenNames || undefined,
+    };
+}
+function parseTd1(l1, l2, l3) {
+    const failures = [];
+    const verify = (label, data, expectedChar) => {
+        const expected = parseInt(expectedChar, 10);
+        if (isNaN(expected) || checkDigit(data) !== expected)
+            failures.push(label);
+    };
+    // ── Line 1 (document code, issuing country, document number) ──────────
+    const documentCode = l1.slice(0, 2);
+    const issuingCountry = l1.slice(2, 5).replace(/</g, "");
+    const docNumField = l1.slice(5, 14);
+    const docNumCheck = l1[14];
+    const optionalData1 = l1.slice(15, 30);
+    // ── Line 2 (biographic data) ────────────────────────────────────────────
+    const dobField = l2.slice(0, 6);
+    const dobCheck = l2[6];
+    const sexChar = l2[7];
+    const expField = l2.slice(8, 14);
+    const expCheck = l2[14];
+    const nationality = l2.slice(15, 18).replace(/</g, "");
+    const optionalData2 = l2.slice(18, 29);
+    const composite = l2[29];
+    verify("documentNumber", docNumField, docNumCheck);
+    verify("dateOfBirth", dobField, dobCheck);
+    verify("expiryDate", expField, expCheck);
+    // ICAO 9303-5 TD1 composite: docNumber+check, optionalData1, DOB+check,
+    // expiry+check, optionalData2 (50 chars total), checked against line2[29].
+    verify("composite", docNumField + docNumCheck + optionalData1 + dobField + dobCheck + expField + expCheck + optionalData2, composite);
+    const totalChecks = 4;
+    const passed = totalChecks - failures.length;
+    const confidence = Math.max(0, passed / totalChecks);
+    const { surnamePaternal, surnameMaternal, givenNames } = parseIneName(l3);
+    return {
+        isIne: true,
+        documentCode,
+        issuingCountry: issuingCountry || undefined,
+        documentNumber: docNumField.replace(/</g, "") || undefined,
+        optionalData1: optionalData1.replace(/</g, "") || undefined,
+        dateOfBirth: parseMrzDate(dobField, true),
+        sex: readIneSex(sexChar),
+        expiryDate: parseMrzDate(expField, false),
+        nationality: nationality || undefined,
+        optionalData2: optionalData2.replace(/</g, "") || undefined,
+        surnamePaternal,
+        surnameMaternal,
+        givenNames,
+        confidence,
+        checksumFailures: failures,
+        raw: { line1: l1, line2: l2, line3: l3 },
+    };
+}
+/**
+ * Find and parse an INE TD1 MRZ from an array of OCR-recognised text lines.
+ * Mirrors parseMrz()'s tolerant line-location strategy, but for the 3×30-char
+ * TD1 shape instead of TD3's 2×44. Requires a Mexico-issued ID-class document
+ * code (documentCode starting "I", issuingCountry "MEX") so this never
+ * collides with a Canadian/US TD1 or a TD3 passport pair.
+ */
+export function parseIneMrz(lines) {
+    const empty = {
+        isIne: false, confidence: 0, checksumFailures: [],
+        raw: { line1: "", line2: "", line3: "" },
+    };
+    const flat = lines.flatMap(l => l.split(/\n/));
+    for (let i = 0; i < flat.length - 2; i++) {
+        const l1 = toTd1Line(flat[i]);
+        const l2 = toTd1Line(flat[i + 1]);
+        const l3 = toTd1Line(flat[i + 2]);
+        if (!l1 || !l2 || !l3)
+            continue;
+        if (/^I[A-Z<]MEX/.test(l1))
+            return parseTd1(l1, l2, l3);
+    }
+    return empty;
+}
+// ─── CURP check-digit validation ─────────────────────────────────────────────
+// Implements the published SAT/RENAPO CURP check-digit formula: a weighted
+// sum over positions 1-17 against a fixed 37-character alphabet, weight =
+// (18 - position). This is the same algorithm used for the Mexican RFC.
+// Structural positions (letters/digits/H|M) are NOT re-derived here beyond
+// what the check-digit computation itself requires — see claveElectorStructureValid
+// for the fuller positional validation pattern this mirrors.
+const CURP_ALPHABET = "0123456789ABCDEFGHIJKLMNÑOPQRSTUVWXYZ";
+/** Compute the expected 18th (check) digit for a CURP, or undefined if malformed. */
+export function curpCheckDigit(curp) {
+    if (!/^[A-ZÑ0-9]{17}/.test(curp))
+        return undefined;
+    let sum = 0;
+    for (let i = 0; i < 17; i++) {
+        const value = CURP_ALPHABET.indexOf(curp[i]);
+        if (value === -1)
+            return undefined;
+        sum += value * (18 - i);
+    }
+    return (10 - (sum % 10)) % 10;
+}
+/** Validate a CURP's check digit. Does not confirm the CURP exists in RENAPO's registry. */
+export function isCurpCheckDigitValid(curp) {
+    if (curp.length !== 18)
+        return false;
+    const expected = curpCheckDigit(curp);
+    return expected !== undefined && String(expected) === curp[17];
+}
+// ─── Clave de Elector structural validation ──────────────────────────────────
+// No published checksum exists for the Clave de Elector, so this validates
+// character-class structure, a plausible entidad (state) code, and — when a
+// DOB/sex from another source is supplied — cross-field agreement only.
+// Structure: 6 letters (name-derived) + 6 digits (DOB, YYMMDD) +
+// 2 digits (entidad code, 01-32) + "H"|"M" (sex) + 3 digits (homonymy).
+const CLAVE_ELECTOR_RE = /^[A-Z]{6}(\d{6})(\d{2})([HM])(\d{3})$/;
+export function claveElectorStructureValid(clave, cross) {
+    const m = CLAVE_ELECTOR_RE.exec(clave);
+    if (!m)
+        return false;
+    const [, dobYyMmDd, entidad, sex] = m;
+    const entidadCode = parseInt(entidad, 10);
+    if (entidadCode < 1 || entidadCode > 32)
+        return false;
+    if (cross?.dateOfBirth) {
+        const expected = yyMmDdFromIso(cross.dateOfBirth);
+        if (expected && expected !== dobYyMmDd)
+            return false;
+    }
+    if (cross?.sex && cross.sex !== sex)
+        return false;
+    return true;
+}
+// ─── Cross-field consistency (DOB/sex must agree across every source present) ─
+function yyMmDdFromIso(iso) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso);
+    return m ? m[1].slice(2) + m[2] + m[3] : undefined;
+}
+function crossFieldConsistent(mrz, curp, claveElector) {
+    const dobCandidates = [];
+    const sexCandidates = [];
+    const mrzDob = mrz?.dateOfBirth ? yyMmDdFromIso(mrz.dateOfBirth) : undefined;
+    if (mrzDob)
+        dobCandidates.push(mrzDob);
+    if (mrz?.sex)
+        sexCandidates.push(mrz.sex);
+    if (curp && curp.length === 18) {
+        dobCandidates.push(curp.slice(4, 10)); // CURP: 4 letters, then DOB YYMMDD
+        const curpSex = curp[10]; // "H" | "M"
+        if (curpSex === "H" || curpSex === "M")
+            sexCandidates.push(curpSex);
+    }
+    const claveMatch = claveElector ? CLAVE_ELECTOR_RE.exec(claveElector) : null;
+    if (claveMatch) {
+        dobCandidates.push(claveMatch[1]);
+        sexCandidates.push(claveMatch[3]);
+    }
+    const dobAgree = dobCandidates.every(d => d === dobCandidates[0]);
+    const sexAgree = sexCandidates.every(s => s === sexCandidates[0]);
+    return dobAgree && sexAgree;
+}
+export function parseInePdf417(_raw) {
+    return { supported: false, reason: "unsupported_format" };
+}
+function computeOverall(mrzPresent, curpPresent, clavePresent, mrzOk, curpOk, claveOk, crossOk) {
+    if (!mrzPresent && !curpPresent && !clavePresent)
+        return "insufficient_data";
+    const anyFailure = (mrzPresent && !mrzOk) || (curpPresent && !curpOk) || (clavePresent && !claveOk) || !crossOk;
+    return anyFailure ? "inconsistent" : "consistent";
+}
+/**
+ * Assemble a typed IneCredential + honest offline-integrity signal from
+ * whatever sources decoded successfully. `curp`/`claveElector` are optional
+ * because today only the MRZ path is implemented (PDF417 is stubbed above,
+ * pending real samples) and the MRZ does not carry either identifier — pass
+ * them in once a future source (PDF417 or OCR) can supply them.
+ */
+export function buildIneCredential(input) {
+    const mrz = input.mrz?.isIne ? input.mrz : undefined;
+    const mrzCheckDigitsValid = mrz ? mrz.checksumFailures.length === 0 : false;
+    const curpOk = input.curp !== undefined ? isCurpCheckDigitValid(input.curp) : false;
+    const claveOk = input.claveElector !== undefined
+        ? claveElectorStructureValid(input.claveElector, { dateOfBirth: mrz?.dateOfBirth, sex: mrz?.sex })
+        : false;
+    const crossOk = crossFieldConsistent(mrz, input.curp, input.claveElector);
+    const overall = computeOverall(!!mrz, input.curp !== undefined, input.claveElector !== undefined, mrzCheckDigitsValid, curpOk, claveOk, crossOk);
+    return {
+        documentType: "MX_INE",
+        model: input.model ?? "unknown",
+        surnamePaternal: mrz?.surnamePaternal,
+        surnameMaternal: mrz?.surnameMaternal,
+        givenNames: mrz?.givenNames,
+        fullNameRaw: mrz?.raw.line3,
+        dateOfBirth: mrz?.dateOfBirth,
+        sex: mrz?.sex,
+        claveElector: input.claveElector !== undefined
+            ? { value: input.claveElector, structureValid: claveOk }
+            : undefined,
+        curp: input.curp !== undefined
+            ? { value: input.curp, checkDigitValid: curpOk }
+            : undefined,
+        expiryYear: mrz?.expiryDate?.slice(0, 4),
+        cic: mrz?.documentNumber,
+        mrzLines: mrz ? { mz1: mrz.raw.line1, mz2: mrz.raw.line2, mz3: mrz.raw.line3 } : undefined,
+        source: input.source ?? (mrz ? "MRZ" : "PDF417"),
+        integrity: {
+            mrzCheckDigitsValid,
+            curpCheckDigitValid: curpOk,
+            claveElectorStructureValid: claveOk,
+            crossFieldConsistent: crossOk,
+            overall,
+        },
+    };
+}

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.1.0",
+  "version": "0.3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/parselo-io/parselo-sdk.git",