soulprint-verify 0.1.0

package/dist/document/cedula-validator.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Validador de Cédula de Ciudadanía colombiana
+ *
+ * La cédula colombiana tiene:
+ * - 5 a 10 dígitos numéricos
+ * - Emitida por Registraduría Nacional del Estado Civil
+ * - Serie por región/año: rangos conocidos
+ * - Dígito de verificación implícito en la secuencia
+ */
+export interface DocumentValidationResult {
+    valid: boolean;
+    cedula_number?: string;
+    nombre?: string;
+    fecha_nacimiento?: string;
+    sexo?: "M" | "F";
+    errors: string[];
+    raw_ocr?: string;
+}
+export declare function validateCedulaNumber(cedula: string): {
+    valid: boolean;
+    error?: string;
+};
+export declare function parseCedulaOCR(ocrText: string): DocumentValidationResult;
+/**
+ * Parsea el MRZ TD1 del reverso de la cédula colombiana digital.
+ * Formato: 3 líneas de 30 caracteres cada una.
+ *
+ * Línea 2: DDMMYYCSEXEXPIRYNATCHECKNUMDOC<CHECK
+ *   - [0-5]   = fecha nacimiento YYMMDD
+ *   - [6]     = dígito verificador
+ *   - [7]     = sexo M/F
+ *   - [8-13]  = fecha expiración YYMMDD
+ *   - [14]    = dígito verificador
+ *   - [15-17] = código país (COL)
+ *   - [18-28] = número documento (cédula)
+ *
+ * Línea 3: APELLIDOS<<NOMBRES<<<...
+ */
+export declare function parseMRZ(mrzText: string): DocumentValidationResult;

package/dist/document/cedula-validator.js

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * Validador de Cédula de Ciudadanía colombiana
+ *
+ * La cédula colombiana tiene:
+ * - 5 a 10 dígitos numéricos
+ * - Emitida por Registraduría Nacional del Estado Civil
+ * - Serie por región/año: rangos conocidos
+ * - Dígito de verificación implícito en la secuencia
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateCedulaNumber = validateCedulaNumber;
+exports.parseCedulaOCR = parseCedulaOCR;
+exports.parseMRZ = parseMRZ;
+// ── Rangos válidos de cédulas colombianas ─────────────────────────────────────
+// Fuente: Registraduría Nacional — rangos históricos por décadas
+const CEDULA_RANGES = [
+    [1_000_000, 9_999_999], // primeras series (7 dígitos)
+    [10_000_000, 99_999_999], // series modernas (8 dígitos)
+    [100_000_000, 999_999_999], // series recientes (9 dígitos)
+    [1_000_000_000, 1_299_999_999], // series nuevas (10 dígitos)
+];
+function validateCedulaNumber(cedula) {
+    // Limpiar espacios y guiones
+    const clean = cedula.replace(/[\s\-\.]/g, "");
+    // Solo dígitos
+    if (!/^\d+$/.test(clean)) {
+        return { valid: false, error: "La cédula solo debe contener números" };
+    }
+    const num = parseInt(clean, 10);
+    // Longitud válida: 5-10 dígitos
+    if (clean.length < 5 || clean.length > 10) {
+        return { valid: false, error: `Longitud inválida: ${clean.length} dígitos (debe ser 5-10)` };
+    }
+    // No puede ser todo el mismo dígito (111111111, 000000000, etc.)
+    if (/^(\d)\1+$/.test(clean)) {
+        return { valid: false, error: "Número de cédula inválido (dígitos repetidos)" };
+    }
+    // Verificar que esté en un rango conocido (para cédulas de 7+ dígitos)
+    if (clean.length >= 7) {
+        const inRange = CEDULA_RANGES.some(([min, max]) => num >= min && num <= max);
+        if (!inRange) {
+            return { valid: false, error: "Número fuera de rangos válidos de Registraduría" };
+        }
+    }
+    return { valid: true };
+}
+// ── Parser de texto OCR de cédula colombiana ──────────────────────────────────
+function parseCedulaOCR(ocrText) {
+    const errors = [];
+    const text = ocrText.toUpperCase().replace(/\s+/g, " ").trim();
+    // ── Extraer número de cédula ───────────────────────────────────────────────
+    // Patrones en cédulas colombianas:
+    // "C.C. 12.345.678" | "CC 12345678" | "1.234.567.890"
+    let cedula_number;
+    const cedulaPatterns = [
+        /NUIP\s*([0-9][0-9.\s]{6,14})/, // "NUIP1.234.567.890" — primero
+        /C\.?C\.?\s*([0-9][0-9.\s]{4,12})/, // "CC 12.345.678"
+        /CÉDULA[^0-9]*([0-9][0-9.\s]{4,12})/, // "CÉDULA DE CIUDADANÍA 12345678"
+        /CIUDADANÍA[^0-9]*([0-9][0-9.\s]{4,12})/,
+        /N[UÚ]MERO[^0-9]*([0-9][0-9.\s]{4,12})/,
+        /(?<![0-9])(\d{1,3}(?:\.\d{3}){2,3})(?![0-9])/, // "1.234.567.890" con puntos
+        /(?<![0-9])(\d{7,10})(?![0-9])/, // número largo sin formato
+    ];
+    for (const pattern of cedulaPatterns) {
+        const m = text.match(pattern);
+        if (m) {
+            const candidate = m[1].replace(/[\.\s]/g, "");
+            const validation = validateCedulaNumber(candidate);
+            if (validation.valid) {
+                cedula_number = candidate;
+                break;
+            }
+        }
+    }
+    if (!cedula_number) {
+        errors.push("No se pudo extraer un número de cédula válido del documento");
+    }
+    // ── Extraer nombre ─────────────────────────────────────────────────────────
+    let nombre;
+    // La cédula tiene: apellidos en una línea, nombres en la siguiente
+    const nombrePatterns = [
+        /APELLIDOS[:\s]+([A-ZÁÉÍÓÚÑ\s]+)\s*NOMBRES?[:\s]+([A-ZÁÉÍÓÚÑ\s]+)/,
+        /NOMBRES?[:\s]+([A-ZÁÉÍÓÚÑ\s]{5,50})/,
+    ];
+    for (const pattern of nombrePatterns) {
+        const m = text.match(pattern);
+        if (m) {
+            nombre = m[2] ? `${m[2].trim()} ${m[1].trim()}` : m[1].trim();
+            nombre = nombre.replace(/\s+/g, " ").trim();
+            break;
+        }
+    }
+    // ── Extraer fecha de nacimiento ────────────────────────────────────────────
+    let fecha_nacimiento;
+    const fechaPatterns = [
+        /FECHA\s+(?:DE\s+)?NACIMIENTO[:\s]+(\d{1,2}[\-\/]\d{1,2}[\-\/]\d{4})/,
+        /NACIMIENTO[:\s]+(\d{1,2}[\-\/]\d{1,2}[\-\/]\d{4})/,
+        /(\d{2}[\-\/]\d{2}[\-\/]\d{4})/, // DD/MM/YYYY o DD-MM-YYYY
+        /(\d{4}[\-\/]\d{2}[\-\/]\d{2})/, // YYYY-MM-DD
+    ];
+    for (const pattern of fechaPatterns) {
+        const m = text.match(pattern);
+        if (m) {
+            fecha_nacimiento = normalizeFecha(m[1]);
+            break;
+        }
+    }
+    // ── Extraer sexo ───────────────────────────────────────────────────────────
+    let sexo;
+    if (/\bSEXO\s*[:\s]\s*M\b/.test(text) || /\bMASCULINO\b/.test(text))
+        sexo = "M";
+    if (/\bSEXO\s*[:\s]\s*F\b/.test(text) || /\bFEMENINO\b/.test(text))
+        sexo = "F";
+    // ── Verificar que es una cédula colombiana ─────────────────────────────────
+    const esCedula = /COLOMBIA|REGISTRADURÍA|REPÚBLICA|CIUDADANÍA|C\.C\.|CÉDULA/i.test(text);
+    if (!esCedula) {
+        errors.push("El documento no parece ser una cédula colombiana");
+    }
+    return {
+        valid: errors.length === 0 && !!cedula_number,
+        cedula_number,
+        nombre,
+        fecha_nacimiento,
+        sexo,
+        errors,
+        raw_ocr: ocrText,
+    };
+}
+// ── MRZ TD1 parser (reverso cédula digital colombiana) ────────────────────────
+/**
+ * Parsea el MRZ TD1 del reverso de la cédula colombiana digital.
+ * Formato: 3 líneas de 30 caracteres cada una.
+ *
+ * Línea 2: DDMMYYCSEXEXPIRYNATCHECKNUMDOC<CHECK
+ *   - [0-5]   = fecha nacimiento YYMMDD
+ *   - [6]     = dígito verificador
+ *   - [7]     = sexo M/F
+ *   - [8-13]  = fecha expiración YYMMDD
+ *   - [14]    = dígito verificador
+ *   - [15-17] = código país (COL)
+ *   - [18-28] = número documento (cédula)
+ *
+ * Línea 3: APELLIDOS<<NOMBRES<<<...
+ */
+function parseMRZ(mrzText) {
+    const errors = [];
+    // Limpiar y encontrar líneas MRZ
+    const allLines = mrzText
+        .split("\n")
+        .map(l => l.replace(/[^A-Z0-9<]/gi, "").toUpperCase())
+        .filter(l => l.length >= 10);
+    const lines = allLines.filter(l => l.length >= 28);
+    if (lines.length < 2) {
+        return { valid: false, errors: ["MRZ incompleto — se necesitan al menos 2 líneas"] };
+    }
+    // Línea 2: datos biográficos
+    const line2 = lines.find(l => /^\d{6}[0-9<][MF<]/.test(l));
+    if (!line2) {
+        return { valid: false, errors: ["No se encontró línea MRZ con datos biográficos"] };
+    }
+    const yy = line2.slice(0, 2);
+    const mm = line2.slice(2, 4);
+    const dd = line2.slice(4, 6);
+    const sex = line2[7];
+    // Inferir siglo (si YY > 24 → 19xx, si <= 24 → 20xx)
+    const century = parseInt(yy) > 24 ? "19" : "20";
+    const fecha_nacimiento = `${century}${yy}-${mm}-${dd}`;
+    // Número de cédula: aparece en línea 2 posición 18-27 (o en línea 1)
+    const docNumRaw = line2.slice(18, 29).replace(/</g, "").trim();
+    const docNum = docNumRaw.replace(/^0+/, ""); // quitar ceros a la izquierda
+    const numValidation = validateCedulaNumber(docNum);
+    // Línea 3: nombre — buscar en TODAS las líneas (puede ser más corta)
+    const line3 = allLines.find(l => l.includes("<<") &&
+        !/^\d{6}/.test(l) &&
+        /^[A-Z]{3,}<</.test(l));
+    let nombre;
+    if (line3) {
+        const parts = line3.split("<<");
+        const apellido = parts[0]?.replace(/</g, " ").trim();
+        const nombres = parts.slice(1).join(" ").replace(/</g, " ").replace(/\s+/g, " ").trim();
+        nombre = nombres && apellido ? `${nombres} ${apellido}`.trim() : (apellido || nombres);
+    }
+    if (!numValidation.valid) {
+        errors.push(`Número en MRZ inválido: ${numValidation.error}`);
+    }
+    return {
+        valid: errors.length === 0,
+        cedula_number: numValidation.valid ? docNum : undefined,
+        nombre,
+        fecha_nacimiento,
+        sexo: sex === "M" || sex === "F" ? sex : undefined,
+        errors,
+        raw_ocr: mrzText,
+    };
+}
+function normalizeFecha(fecha) {
+    // Normalizar a YYYY-MM-DD
+    const clean = fecha.replace(/\//g, "-");
+    const parts = clean.split("-");
+    if (parts.length !== 3)
+        return fecha;
+    if (parts[0].length === 4) {
+        // YYYY-MM-DD
+        return clean;
+    }
+    else {
+        // DD-MM-YYYY → YYYY-MM-DD
+        const [d, m, y] = parts;
+        return `${y}-${m.padStart(2, "0")}-${d.padStart(2, "0")}`;
+    }
+}

package/dist/document/ocr.d.ts

@@ -0,0 +1,20 @@
+import { DocumentValidationResult } from "./cedula-validator.js";
+export interface OCROptions {
+    lang?: string;
+    verbose?: boolean;
+}
+/**
+ * Extrae y valida datos de una cédula colombiana desde una imagen.
+ *
+ * On-demand: Tesseract.js carga el worker solo cuando se llama,
+ * y se termina al final. No hay proceso persistente.
+ */
+export declare function ocrCedula(imagePath: string, opts?: OCROptions): Promise<DocumentValidationResult>;
+/**
+ * Valida que la imagen parece ser una cédula antes de hacer OCR completo.
+ * Revisión superficial de dimensiones y tamaño — no carga Tesseract.
+ */
+export declare function quickValidateImage(imagePath: string): Promise<{
+    valid: boolean;
+    error?: string;
+}>;

package/dist/document/ocr.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ocrCedula = ocrCedula;
+exports.quickValidateImage = quickValidateImage;
+const tesseract_js_1 = __importDefault(require("tesseract.js"));
+const cedula_validator_js_1 = require("./cedula-validator.js");
+/**
+ * Extrae y valida datos de una cédula colombiana desde una imagen.
+ *
+ * On-demand: Tesseract.js carga el worker solo cuando se llama,
+ * y se termina al final. No hay proceso persistente.
+ */
+async function ocrCedula(imagePath, opts = {}) {
+    const lang = opts.lang ?? "spa";
+    // Tesseract carga on-demand, se termina después de extraer
+    const { data: { text } } = await tesseract_js_1.default.recognize(imagePath, lang, {
+        logger: opts.verbose
+            ? (m) => process.stderr.write(`[OCR] ${m.status} ${Math.round((m.progress ?? 0) * 100)}%\r`)
+            : undefined,
+    });
+    if (opts.verbose)
+        process.stderr.write("\n");
+    return (0, cedula_validator_js_1.parseCedulaOCR)(text);
+}
+/**
+ * Valida que la imagen parece ser una cédula antes de hacer OCR completo.
+ * Revisión superficial de dimensiones y tamaño — no carga Tesseract.
+ */
+async function quickValidateImage(imagePath) {
+    try {
+        // Dynamic import de sharp para no cargar si no es necesario
+        const sharp = (await import("sharp")).default;
+        const meta = await sharp(imagePath).metadata();
+        if (!meta.width || !meta.height) {
+            return { valid: false, error: "No se pudo leer las dimensiones de la imagen" };
+        }
+        // Cédula colombiana: proporción ~1.59:1 (85.6mm × 53.98mm, formato ID-1 ISO 7810)
+        const ratio = meta.width / meta.height;
+        const isLandscape = meta.width > meta.height;
+        if (!isLandscape) {
+            return { valid: false, error: "La imagen debe estar en horizontal (la cédula es apaisada)" };
+        }
+        if (ratio < 1.2 || ratio > 2.0) {
+            return { valid: false, error: `Proporción de imagen inusual (${ratio.toFixed(2)}). Asegúrate de fotografiar solo la cédula` };
+        }
+        // Mínimo 400x250 para OCR confiable
+        if (meta.width < 400 || meta.height < 250) {
+            return { valid: false, error: "Imagen muy pequeña. Usa al menos 400×250 píxeles" };
+        }
+        return { valid: true };
+    }
+    catch (e) {
+        return { valid: false, error: `Error leyendo imagen: ${e.message}` };
+    }
+}

package/dist/face/face-match.d.ts

@@ -0,0 +1,25 @@
+export interface FaceMatchResult {
+    match: boolean;
+    similarity: number;
+    embedding?: number[];
+    liveness?: boolean;
+    errors: string[];
+}
+export interface FaceMatchOptions {
+    minSimilarity?: number;
+    checkLiveness?: boolean;
+    verbose?: boolean;
+}
+/**
+ * Compara la cara de un selfie con la foto del documento de identidad.
+ *
+ * ARQUITECTURA ON-DEMAND:
+ * - Lanza un subprocess Python con InsightFace
+ * - InsightFace (~500MB) se carga SOLO durante esta llamada
+ * - El proceso termina al final → memoria completamente liberada
+ * - En reposo: 0MB de modelos ML en memoria
+ *
+ * @param selfiePhoto    Path a la foto selfie
+ * @param documentPhoto  Path a la foto del documento (cédula)
+ */
+export declare function matchFaceWithDocument(selfiePhoto: string, documentPhoto: string, opts?: FaceMatchOptions): Promise<FaceMatchResult>;

package/dist/face/face-match.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchFaceWithDocument = matchFaceWithDocument;
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+// Path al script Python que corre on-demand
+const PYTHON_SCRIPT = (0, node_path_1.join)(__dirname, "face_match.py");
+/**
+ * Compara la cara de un selfie con la foto del documento de identidad.
+ *
+ * ARQUITECTURA ON-DEMAND:
+ * - Lanza un subprocess Python con InsightFace
+ * - InsightFace (~500MB) se carga SOLO durante esta llamada
+ * - El proceso termina al final → memoria completamente liberada
+ * - En reposo: 0MB de modelos ML en memoria
+ *
+ * @param selfiePhoto    Path a la foto selfie
+ * @param documentPhoto  Path a la foto del documento (cédula)
+ */
+async function matchFaceWithDocument(selfiePhoto, documentPhoto, opts = {}) {
+    const minSim = opts.minSimilarity ?? 0.65;
+    // Verificar que existe el script Python
+    if (!(0, node_fs_1.existsSync)(PYTHON_SCRIPT)) {
+        return {
+            match: false,
+            similarity: 0,
+            errors: [`Script Python no encontrado: ${PYTHON_SCRIPT}. Ejecuta: soulprint install-deps`],
+        };
+    }
+    // Verificar que Python e InsightFace están disponibles
+    const pythonCheck = await checkPythonDeps();
+    if (!pythonCheck.ok) {
+        return {
+            match: false,
+            similarity: 0,
+            errors: [pythonCheck.error],
+        };
+    }
+    return new Promise((resolve) => {
+        const args = [
+            PYTHON_SCRIPT,
+            "--selfie", selfiePhoto,
+            "--document", documentPhoto,
+            "--min-sim", String(minSim),
+        ];
+        if (opts.checkLiveness)
+            args.push("--liveness");
+        // Lanzar subprocess — muere solo cuando termina
+        const proc = (0, node_child_process_1.spawn)("python3", args, {
+            stdio: ["ignore", "pipe", opts.verbose ? "inherit" : "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        proc.stdout?.on("data", (d) => stdout += d.toString());
+        if (!opts.verbose && proc.stderr) {
+            proc.stderr.on("data", (d) => stderr += d.toString());
+        }
+        proc.on("close", (code) => {
+            if (code !== 0) {
+                resolve({
+                    match: false,
+                    similarity: 0,
+                    errors: [`Proceso de verificación falló (código ${code}): ${stderr.slice(0, 200)}`],
+                });
+                return;
+            }
+            try {
+                const result = JSON.parse(stdout.trim());
+                resolve({
+                    match: result.match ?? false,
+                    similarity: result.similarity ?? 0,
+                    embedding: result.embedding,
+                    liveness: result.liveness,
+                    errors: result.errors ?? [],
+                });
+            }
+            catch {
+                resolve({
+                    match: false,
+                    similarity: 0,
+                    errors: ["Error parseando resultado de verificación facial"],
+                });
+            }
+        });
+        proc.on("error", (err) => {
+            resolve({
+                match: false,
+                similarity: 0,
+                errors: [`No se pudo lanzar Python: ${err.message}. Instala Python 3.8+`],
+            });
+        });
+    });
+}
+// ── Verificar dependencias Python ─────────────────────────────────────────────
+async function checkPythonDeps() {
+    return new Promise((resolve) => {
+        const proc = (0, node_child_process_1.spawn)("python3", ["-c", "import insightface; import cv2; print('ok')"], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let out = "";
+        proc.stdout.on("data", (d) => out += d.toString());
+        proc.on("close", (code) => {
+            if (code === 0 && out.includes("ok")) {
+                resolve({ ok: true });
+            }
+            else {
+                resolve({
+                    ok: false,
+                    error: "InsightFace no instalado. Ejecuta: pip install insightface opencv-python-headless",
+                });
+            }
+        });
+        proc.on("error", () => resolve({
+            ok: false,
+            error: "Python3 no encontrado. Instala Python 3.8+ para verificación facial.",
+        }));
+    });
+}

package/dist/face/face_match.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""
+face_match.py — Soulprint on-demand face verification
+
+Este script:
+1. Se lanza como subprocess desde TypeScript
+2. Carga InsightFace (500MB, ~4s)
+3. Compara selfie vs foto de documento
+4. Imprime resultado JSON por stdout
+5. TERMINA — la memoria se libera completamente
+
+No hay proceso persistente. Cada verificación es un proceso nuevo.
+"""
+
+import sys
+import json
+import argparse
+import os
+
+# Silenciar warnings de TensorFlow/ONNX antes de importar
+os.environ["TF_CPP_MIN_LOG_LEVEL"] = "3"
+os.environ["ONNXRUNTIME_LOG_LEVEL"] = "3"
+
+
+def eprint(*args):
+    """Logs al stderr para no contaminar stdout (que es el canal JSON)"""
+    print(*args, file=sys.stderr)
+
+
+def load_models():
+    """Carga InsightFace on-demand. Solo se llama una vez por proceso."""
+    try:
+        import insightface
+        from insightface.app import FaceAnalysis
+
+        eprint("[soulprint] Cargando modelo de reconocimiento facial...")
+        app = FaceAnalysis(
+            name="buffalo_sc",        # modelo ligero (~50MB vs buffalo_l 500MB)
+            providers=["CPUExecutionProvider"],
+            allowed_modules=["detection", "recognition"],
+        )
+        app.prepare(ctx_id=0, det_size=(320, 320))  # resolución reducida = más rápido
+        eprint("[soulprint] Modelo listo")
+        return app
+    except ImportError as e:
+        print(json.dumps({
+            "match": False,
+            "similarity": 0,
+            "errors": [f"InsightFace no disponible: {e}. Instala con: pip install insightface"],
+        }))
+        sys.exit(1)
+
+
+def get_face_embedding(app, image_path: str):
+    """Extrae el embedding de la cara principal en una imagen."""
+    import cv2
+    import numpy as np
+
+    img = cv2.imread(image_path)
+    if img is None:
+        return None, f"No se pudo leer la imagen: {image_path}"
+
+    faces = app.get(img)
+    if not faces:
+        return None, "No se detectó ninguna cara en la imagen"
+
+    # Tomar la cara más grande (la principal)
+    face = max(faces, key=lambda f: (f.bbox[2] - f.bbox[0]) * (f.bbox[3] - f.bbox[1]))
+
+    return face.embedding, None
+
+
+def cosine_similarity(a, b) -> float:
+    """Similitud coseno entre dos embeddings. Rango: -1 a 1."""
+    import numpy as np
+    a = a / (np.linalg.norm(a) + 1e-8)
+    b = b / (np.linalg.norm(b) + 1e-8)
+    return float(np.dot(a, b))
+
+
+def quantize_embedding(embedding, precision: int = 2):
+    """
+    Cuantiza el embedding para derivar nullifier determinístico.
+    Misma cara en diferentes fotos → mismo embedding cuantizado.
+    """
+    import numpy as np
+    factor = 10 ** precision
+    return (np.round(embedding * factor) / factor).tolist()
+
+
+def check_liveness(app, image_path: str) -> bool:
+    """
+    Detección básica de 'foto de foto':
+    - Verifica que el contraste y nitidez son de foto real
+    - No es antispoof completo, pero filtra ataques básicos
+    """
+    import cv2
+    import numpy as np
+
+    img = cv2.imread(image_path)
+    if img is None:
+        return False
+
+    gray     = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    laplacian = cv2.Laplacian(gray, cv2.CV_64F).var()
+
+    # Fotos de pantalla tienen banding y menor nitidez
+    # Umbral empírico — ajustar con más datos reales
+    return laplacian > 80.0
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Soulprint face match")
+    parser.add_argument("--selfie",    required=True, help="Path selfie del usuario")
+    parser.add_argument("--document",  required=True, help="Path foto del documento")
+    parser.add_argument("--min-sim",   type=float, default=0.65, help="Similitud mínima")
+    parser.add_argument("--liveness",  action="store_true", help="Verificar liveness")
+    args = parser.parse_args()
+
+    # Verificar que los archivos existen
+    for path in [args.selfie, args.document]:
+        if not os.path.exists(path):
+            print(json.dumps({
+                "match": False, "similarity": 0,
+                "errors": [f"Archivo no encontrado: {path}"]
+            }))
+            sys.exit(0)
+
+    # Cargar modelo (on-demand, solo este proceso)
+    app = load_models()
+
+    # Extraer embeddings
+    selfie_emb, err1 = get_face_embedding(app, args.selfie)
+    if err1:
+        print(json.dumps({"match": False, "similarity": 0, "errors": [f"Selfie: {err1}"]}))
+        sys.exit(0)
+
+    doc_emb, err2 = get_face_embedding(app, args.document)
+    if err2:
+        print(json.dumps({"match": False, "similarity": 0, "errors": [f"Documento: {err2}"]}))
+        sys.exit(0)
+
+    # Calcular similitud
+    similarity = cosine_similarity(selfie_emb, doc_emb)
+    match      = similarity >= args.min_sim
+
+    # Liveness check (opcional)
+    liveness = None
+    if args.liveness:
+        liveness = check_liveness(app, args.selfie)
+
+    # Embedding cuantizado para derivar nullifier (determinístico)
+    quantized = quantize_embedding(selfie_emb, precision=2)
+
+    result = {
+        "match":      match,
+        "similarity": round(similarity, 4),
+        "embedding":  quantized,   # para nullifier — NO es el embedding raw
+        "errors":     [],
+    }
+
+    if liveness is not None:
+        result["liveness"] = liveness
+
+    if not match:
+        result["errors"].append(
+            f"Similitud insuficiente ({similarity:.2f} < {args.min_sim}). "
+            "Usa una foto clara de frente con buena iluminación."
+        )
+
+    # Imprimir resultado por stdout (único canal con el proceso padre)
+    print(json.dumps(result))
+
+    # El proceso termina aquí → InsightFace se descarga de memoria automáticamente
+
+
+if __name__ == "__main__":
+    main()

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+export interface VerificationOptions {
+    selfiePhoto: string;
+    documentPhoto: string;
+    verbose?: boolean;
+    minFaceSim?: number;
+    checkLiveness?: boolean;
+    withZKP?: boolean;
+}
+export interface VerificationResult {
+    success: boolean;
+    token?: string;
+    zkProof?: string;
+    nullifier?: string;
+    did?: string;
+    score?: number;
+    errors: string[];
+    steps: {
+        image_check: "ok" | "fail" | "skip";
+        ocr: "ok" | "fail" | "skip";
+        face_match: "ok" | "fail" | "skip";
+        nullifier_derived: "ok" | "fail" | "skip";
+        zk_proof: "ok" | "fail" | "skip";
+        token_created: "ok" | "fail" | "skip";
+    };
+}
+export declare function verifyIdentity(opts: VerificationOptions): Promise<VerificationResult>;
+export { ocrCedula, quickValidateImage } from "./document/ocr.js";
+export { matchFaceWithDocument } from "./face/face-match.js";
+export { validateCedulaNumber, parseCedulaOCR } from "./document/cedula-validator.js";

package/dist/index.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCedulaOCR = exports.validateCedulaNumber = exports.matchFaceWithDocument = exports.quickValidateImage = exports.ocrCedula = void 0;
+exports.verifyIdentity = verifyIdentity;
+const soulprint_core_1 = require("soulprint-core");
+const ocr_js_1 = require("./document/ocr.js");
+const face_match_js_1 = require("./face/face-match.js");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const SOULPRINT_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".soulprint");
+const KEYPAIR_FILE = (0, node_path_1.join)(SOULPRINT_DIR, "identity.json");
+async function verifyIdentity(opts) {
+    const errors = [];
+    const steps = {
+        image_check: "skip",
+        ocr: "skip",
+        face_match: "skip",
+        nullifier_derived: "skip",
+        zk_proof: "skip",
+        token_created: "skip",
+    };
+    const log = (msg) => opts.verbose && process.stderr.write(`[soulprint] ${msg}\n`);
+    // ── PASO 1: Validar imágenes ───────────────────────────────────────────────
+    log("Validando imágenes...");
+    const selfieCheck = await (0, ocr_js_1.quickValidateImage)(opts.selfiePhoto);
+    const docCheck = await (0, ocr_js_1.quickValidateImage)(opts.documentPhoto);
+    if (!selfieCheck.valid) {
+        errors.push(`Selfie: ${selfieCheck.error}`);
+        steps.image_check = "fail";
+        return { success: false, errors, steps };
+    }
+    if (!docCheck.valid) {
+        errors.push(`Documento: ${docCheck.error}`);
+        steps.image_check = "fail";
+        return { success: false, errors, steps };
+    }
+    steps.image_check = "ok";
+    // ── PASO 2: OCR de cédula ─────────────────────────────────────────────────
+    log("Extrayendo datos del documento...");
+    const docResult = await (0, ocr_js_1.ocrCedula)(opts.documentPhoto, { verbose: opts.verbose });
+    if (!docResult.valid || !docResult.cedula_number) {
+        errors.push(...docResult.errors);
+        steps.ocr = "fail";
+        return { success: false, errors, steps };
+    }
+    steps.ocr = "ok";
+    log(`✓ Cédula: ${docResult.cedula_number}`);
+    // ── PASO 3: Face match (subprocess Python on-demand) ──────────────────────
+    log("Verificando coincidencia facial (iniciando proceso de IA)...");
+    const faceResult = await (0, face_match_js_1.matchFaceWithDocument)(opts.selfiePhoto, opts.documentPhoto, { minSimilarity: opts.minFaceSim ?? 0.65, checkLiveness: opts.checkLiveness, verbose: opts.verbose });
+    if (!faceResult.match) {
+        errors.push(...faceResult.errors);
+        steps.face_match = "fail";
+        return { success: false, errors, steps };
+    }
+    steps.face_match = "ok";
+    log(`✓ Cara coincide (similitud: ${(faceResult.similarity * 100).toFixed(1)}%)`);
+    // ── PASO 4: Derivar nullifier ──────────────────────────────────────────────
+    log("Derivando nullifier único...");
+    let nullifier;
+    try {
+        const embedding = new Float32Array(faceResult.embedding);
+        nullifier = (0, soulprint_core_1.deriveNullifier)(docResult.cedula_number, docResult.fecha_nacimiento ?? "0000-00-00", embedding);
+        steps.nullifier_derived = "ok";
+        log(`✓ Nullifier: ${nullifier.slice(0, 18)}...`);
+    }
+    catch (e) {
+        errors.push(`Error derivando nullifier: ${e.message}`);
+        steps.nullifier_derived = "fail";
+        return { success: false, errors, steps };
+    }
+    // ── PASO 5: ZK Proof (opcional, si soulprint-zkp está disponible) ─────────
+    let zkProofSerialized;
+    const withZKP = opts.withZKP !== false; // default: true
+    if (withZKP) {
+        log("Generando ZK proof...");
+        try {
+            // Importar dinámicamente para no fallar si no está compilado el circuito
+            const zkp = await import("soulprint-zkp");
+            const cedula_num = zkp.cedulaToBigInt(docResult.cedula_number);
+            const fecha_nac = zkp.fechaToBigInt(docResult.fecha_nacimiento ?? "19000101");
+            const face_key = await zkp.faceEmbeddingToKey(Array.from(faceResult.embedding));
+            const salt = BigInt(Math.floor(Math.random() * Number.MAX_SAFE_INTEGER));
+            const context = BigInt(0);
+            const zkProof = await zkp.generateProof({ cedula_num, fecha_nac, face_key, salt, context_tag: context });
+            zkProofSerialized = zkp.serializeProof(zkProof);
+            steps.zk_proof = "ok";
+            log(`✓ ZK proof generado — nullifier (ZK): ${zkProof.nullifier.slice(0, 18)}...`);
+        }
+        catch (zkErr) {
+            // ZK proof es opcional — si falla (circuito no compilado), continuar sin él
+            steps.zk_proof = "skip";
+            log(`⚠ ZK proof omitido: ${zkErr.message?.split("\n")[0]}`);
+        }
+    }
+    // ── PASO 6: Crear keypair y emitir SPT ────────────────────────────────────
+    log("Generando token Soulprint...");
+    const keypair = loadOrCreateKeypair();
+    const credentials = ["DocumentVerified", "FaceMatch"];
+    if (opts.checkLiveness && faceResult.liveness)
+        credentials.push("BiometricBound");
+    const token = (0, soulprint_core_1.createToken)(keypair, nullifier, credentials, {
+        country: "CO",
+        zkProof: zkProofSerialized,
+    });
+    steps.token_created = "ok";
+    log(`✓ Token — DID: ${keypair.did}`);
+    log("✅ Verificación completa. Datos biométricos eliminados de memoria.");
+    return {
+        success: true,
+        token,
+        zkProof: zkProofSerialized,
+        nullifier,
+        did: keypair.did,
+        score: calcScore(credentials),
+        errors: [],
+        steps,
+    };
+}
+function loadOrCreateKeypair() {
+    if (!(0, node_fs_1.existsSync)(SOULPRINT_DIR))
+        (0, node_fs_1.mkdirSync)(SOULPRINT_DIR, { recursive: true, mode: 0o700 });
+    if ((0, node_fs_1.existsSync)(KEYPAIR_FILE)) {
+        const stored = JSON.parse((0, node_fs_1.readFileSync)(KEYPAIR_FILE, "utf8"));
+        const { keypairFromPrivateKey } = require("soulprint-core");
+        return keypairFromPrivateKey(new Uint8Array(Buffer.from(stored.privateKey, "hex")));
+    }
+    const keypair = (0, soulprint_core_1.generateKeypair)();
+    (0, node_fs_1.writeFileSync)(KEYPAIR_FILE, JSON.stringify({
+        did: keypair.did,
+        privateKey: Buffer.from(keypair.privateKey).toString("hex"),
+        created: new Date().toISOString(),
+    }), { mode: 0o600 });
+    return keypair;
+}
+function calcScore(credentials) {
+    const s = {
+        EmailVerified: 10, PhoneVerified: 15, GitHubLinked: 20,
+        DocumentVerified: 25, FaceMatch: 20, BiometricBound: 10,
+    };
+    return credentials.reduce((acc, c) => acc + (s[c] ?? 0), 0);
+}
+var ocr_js_2 = require("./document/ocr.js");
+Object.defineProperty(exports, "ocrCedula", { enumerable: true, get: function () { return ocr_js_2.ocrCedula; } });
+Object.defineProperty(exports, "quickValidateImage", { enumerable: true, get: function () { return ocr_js_2.quickValidateImage; } });
+var face_match_js_2 = require("./face/face-match.js");
+Object.defineProperty(exports, "matchFaceWithDocument", { enumerable: true, get: function () { return face_match_js_2.matchFaceWithDocument; } });
+var cedula_validator_js_1 = require("./document/cedula-validator.js");
+Object.defineProperty(exports, "validateCedulaNumber", { enumerable: true, get: function () { return cedula_validator_js_1.validateCedulaNumber; } });
+Object.defineProperty(exports, "parseCedulaOCR", { enumerable: true, get: function () { return cedula_validator_js_1.parseCedulaOCR; } });

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "soulprint-verify",
+  "version": "0.1.0",
+  "description": "Soulprint local verification — on-demand cedula OCR + InsightFace match, zero persistent memory",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src/face/face_match.py",
+    "spa.traineddata",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/manuelariasfz/soulprint",
+    "directory": "packages/verify-local"
+  },
+  "homepage": "https://github.com/manuelariasfz/soulprint#readme",
+  "keywords": [
+    "soulprint",
+    "kyc",
+    "face-recognition",
+    "ocr",
+    "cedula",
+    "colombia",
+    "insightface",
+    "tesseract"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "tesseract.js": "^5.1.0",
+    "sharp": "^0.33.3",
+    "@noble/hashes": "^1.4.0",
+    "soulprint-core": "0.1.0",
+    "soulprint-zkp": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "postbuild": "mkdir -p dist/face && cp src/face/face_match.py dist/face/"
+  }
+}

package/src/face/face_match.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""
+face_match.py — Soulprint on-demand face verification
+
+Este script:
+1. Se lanza como subprocess desde TypeScript
+2. Carga InsightFace (500MB, ~4s)
+3. Compara selfie vs foto de documento
+4. Imprime resultado JSON por stdout
+5. TERMINA — la memoria se libera completamente
+
+No hay proceso persistente. Cada verificación es un proceso nuevo.
+"""
+
+import sys
+import json
+import argparse
+import os
+
+# Silenciar warnings de TensorFlow/ONNX antes de importar
+os.environ["TF_CPP_MIN_LOG_LEVEL"] = "3"
+os.environ["ONNXRUNTIME_LOG_LEVEL"] = "3"
+
+
+def eprint(*args):
+    """Logs al stderr para no contaminar stdout (que es el canal JSON)"""
+    print(*args, file=sys.stderr)
+
+
+def load_models():
+    """Carga InsightFace on-demand. Solo se llama una vez por proceso."""
+    try:
+        import insightface
+        from insightface.app import FaceAnalysis
+
+        eprint("[soulprint] Cargando modelo de reconocimiento facial...")
+        app = FaceAnalysis(
+            name="buffalo_sc",        # modelo ligero (~50MB vs buffalo_l 500MB)
+            providers=["CPUExecutionProvider"],
+            allowed_modules=["detection", "recognition"],
+        )
+        app.prepare(ctx_id=0, det_size=(320, 320))  # resolución reducida = más rápido
+        eprint("[soulprint] Modelo listo")
+        return app
+    except ImportError as e:
+        print(json.dumps({
+            "match": False,
+            "similarity": 0,
+            "errors": [f"InsightFace no disponible: {e}. Instala con: pip install insightface"],
+        }))
+        sys.exit(1)
+
+
+def get_face_embedding(app, image_path: str):
+    """Extrae el embedding de la cara principal en una imagen."""
+    import cv2
+    import numpy as np
+
+    img = cv2.imread(image_path)
+    if img is None:
+        return None, f"No se pudo leer la imagen: {image_path}"
+
+    faces = app.get(img)
+    if not faces:
+        return None, "No se detectó ninguna cara en la imagen"
+
+    # Tomar la cara más grande (la principal)
+    face = max(faces, key=lambda f: (f.bbox[2] - f.bbox[0]) * (f.bbox[3] - f.bbox[1]))
+
+    return face.embedding, None
+
+
+def cosine_similarity(a, b) -> float:
+    """Similitud coseno entre dos embeddings. Rango: -1 a 1."""
+    import numpy as np
+    a = a / (np.linalg.norm(a) + 1e-8)
+    b = b / (np.linalg.norm(b) + 1e-8)
+    return float(np.dot(a, b))
+
+
+def quantize_embedding(embedding, precision: int = 2):
+    """
+    Cuantiza el embedding para derivar nullifier determinístico.
+    Misma cara en diferentes fotos → mismo embedding cuantizado.
+    """
+    import numpy as np
+    factor = 10 ** precision
+    return (np.round(embedding * factor) / factor).tolist()
+
+
+def check_liveness(app, image_path: str) -> bool:
+    """
+    Detección básica de 'foto de foto':
+    - Verifica que el contraste y nitidez son de foto real
+    - No es antispoof completo, pero filtra ataques básicos
+    """
+    import cv2
+    import numpy as np
+
+    img = cv2.imread(image_path)
+    if img is None:
+        return False
+
+    gray     = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    laplacian = cv2.Laplacian(gray, cv2.CV_64F).var()
+
+    # Fotos de pantalla tienen banding y menor nitidez
+    # Umbral empírico — ajustar con más datos reales
+    return laplacian > 80.0
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Soulprint face match")
+    parser.add_argument("--selfie",    required=True, help="Path selfie del usuario")
+    parser.add_argument("--document",  required=True, help="Path foto del documento")
+    parser.add_argument("--min-sim",   type=float, default=0.65, help="Similitud mínima")
+    parser.add_argument("--liveness",  action="store_true", help="Verificar liveness")
+    args = parser.parse_args()
+
+    # Verificar que los archivos existen
+    for path in [args.selfie, args.document]:
+        if not os.path.exists(path):
+            print(json.dumps({
+                "match": False, "similarity": 0,
+                "errors": [f"Archivo no encontrado: {path}"]
+            }))
+            sys.exit(0)
+
+    # Cargar modelo (on-demand, solo este proceso)
+    app = load_models()
+
+    # Extraer embeddings
+    selfie_emb, err1 = get_face_embedding(app, args.selfie)
+    if err1:
+        print(json.dumps({"match": False, "similarity": 0, "errors": [f"Selfie: {err1}"]}))
+        sys.exit(0)
+
+    doc_emb, err2 = get_face_embedding(app, args.document)
+    if err2:
+        print(json.dumps({"match": False, "similarity": 0, "errors": [f"Documento: {err2}"]}))
+        sys.exit(0)
+
+    # Calcular similitud
+    similarity = cosine_similarity(selfie_emb, doc_emb)
+    match      = similarity >= args.min_sim
+
+    # Liveness check (opcional)
+    liveness = None
+    if args.liveness:
+        liveness = check_liveness(app, args.selfie)
+
+    # Embedding cuantizado para derivar nullifier (determinístico)
+    quantized = quantize_embedding(selfie_emb, precision=2)
+
+    result = {
+        "match":      match,
+        "similarity": round(similarity, 4),
+        "embedding":  quantized,   # para nullifier — NO es el embedding raw
+        "errors":     [],
+    }
+
+    if liveness is not None:
+        result["liveness"] = liveness
+
+    if not match:
+        result["errors"].append(
+            f"Similitud insuficiente ({similarity:.2f} < {args.min_sim}). "
+            "Usa una foto clara de frente con buena iluminación."
+        )
+
+    # Imprimir resultado por stdout (único canal con el proceso padre)
+    print(json.dumps(result))
+
+    # El proceso termina aquí → InsightFace se descarga de memoria automáticamente
+
+
+if __name__ == "__main__":
+    main()