@parselo/scanner-core 0.2.0 → 0.3.0

package/README.md

@@ -1,9 +1,10 @@
 # @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.
+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.
 
@@ -14,6 +15,7 @@ No Capacitor dependency — fully testable in Node.
 | 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.
 
@@ -86,12 +88,75 @@ resident travel documents (`PR`), and foreign passports. The parser cross-refere
 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" | "unknown";
-  jurisdiction: string;   // "CA-QC", "CA-BC", "CA", "MEX", …
+  documentType: "drivers_license" | "id_card" | "passport" | "ine" | "unknown";
+  jurisdiction: string;   // "CA-QC", "CA-BC", "CA", "MEX", "MX", …
   fields: {
     // All document types
     firstName?:         Field;
@@ -107,12 +172,18 @@ interface CanonicalDocument {
     addressRegion?:     Field;
     addressPostalCode?: Field;
     vehicleClass?:      Field;
-    // Passports / travel documents
-    country?:           Field;  // ICAO 3-char issuing country
+    // Passports / travel documents / INE
+    country?:           Field;  // ICAO 3-char issuing country, "MEX" for INE
   };
-  raw?: Record<string, string>;
+  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
@@ -132,6 +203,7 @@ interface ScanResult {
 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";
 ```
@@ -160,6 +232,30 @@ locally and flush in batches. Force a flush with:
 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,13 +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;
@@ -32,3 +33,4 @@ export interface CanonicalDocument {
 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

@@ -94,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

@@ -4,6 +4,7 @@ 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";
@@ -24,7 +25,7 @@ export interface ScannerConfig {
     mrzNative?: MrzNative;
     deviceModel: string;
 }
-export type ScanError = "license_malformed" | "license_unknown_key" | "license_bad_signature" | "license_expired" | "license_bundle_mismatch" | "no_barcode" | "not_aamva" | "no_mrz";
+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;
@@ -41,6 +42,18 @@ export declare class Scanner {
     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;

package/dist/index.js

@@ -8,12 +8,14 @@
 import { parseAamva } from "./aamva";
 import { parseMagstripe } from "./magstripe";
 import { parseMrz } from "./mrz";
-import { toCanonical, magstripeToCanonical, mrzToCanonical } from "./canonical";
+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";
@@ -104,6 +106,45 @@ export class Scanner {
         // (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 };
+    }
     /** Flush buffered analytics (e.g. on app foreground/background). */
     async flushAnalytics() {
         await this.analytics.flush();

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/package.json

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