Katrix Biometrics 🛡️🔑

Una biblioteca agnóstica al framework para facilitar el registro y la autenticación biométrica utilizando la API nativa de WebAuthn / FIDO2 en el navegador.

Ideada para ser sencilla, ligera, segura y fácil de integrar en cualquier aplicación web moderna (Angular, React, Vue, Svelte o JS Vanilla).

Características

• 🔒 Seguro por Defecto: Utiliza criptografía de llave pública asimétrica respaldada por hardware.
• ⚡ Agnóstico al Framework: Sin dependencias de terceros, funciona en cualquier entorno web.
• 💾 Adaptadores de Almacenamiento: Incluye soporte listo para usar con localStorage y memoria virtual (MemoryStorageAdapter), con soporte para adaptadores personalizados.
• 🛠️ Fácil de Depurar: Manejo estructurado de errores (BiometricErrorDetail) para mapear con precisión las excepciones nativas de WebAuthn.

Estructura del Proyecto

katrix-biometrics/
├── src/
│   ├── types.ts          # Definiciones de tipos e interfaces
│   ├── storage.ts        # Adaptadores de persistencia (Local y Memory)
│   ├── biometrics.ts     # Lógica central de KatrixBiometrics
│   ├── index.ts          # Punto de entrada y exportación de la biblioteca
│   └── demo.ts           # Script interactivo del panel de prueba
├── index.html            # Panel de control de pruebas interactivo
├── tsconfig.json         # Configuración del compilador TypeScript
├── tsconfig.esm.json     # Configuración para salida ESM
└── package.json          # Configuración del paquete y dependencias

Instalación y Compilación

1. Instalar dependencias:

   npm install

2. Compilar para producción (Genera salida CommonJS en dist/ y ESM en dist/esm/ junto con declaraciones .d.ts de TypeScript):

   npm run build

3. Ejecutar la Demo Interactiva en Local:

   npm run dev

   Nota: Abre el navegador en la URL indicada (usualmente http://localhost:5173 o similar) para experimentar con la interfaz de pruebas.

Uso Básico

1. Inicializar la biblioteca

import { KatrixBiometrics } from 'katrix-biometrics';

const biometrics = new KatrixBiometrics({
  appName: 'Mi Aplicación Web',
  userId: 'usr_123456',
  userName: '[email protected]',
  userDisplayName: 'Juan Pérez'
});

2. Registrar/Vincular un dispositivo (Registro)

Este proceso crea una nueva credencial WebAuthn en el dispositivo del usuario y guarda la referencia localmente.

const result = await biometrics.register();

if (result.success) {
  console.log("¡Dispositivo vinculado con éxito!");
} else {
  console.error(`Error en registro [${result.error.code}]: ${result.error.message}`);
}

3. Verificar/Iniciar Sesión (Autenticación)

Verifica al usuario solicitando la verificación biométrica del sistema operativo (TouchID, FaceID, Windows Hello, etc.).

const result = await biometrics.authenticate();

if (result.success) {
  console.log("¡Autenticación exitosa!");
} else {
  console.error(`Error de autenticación [${result.error.code}]: ${result.error.message}`);
}

4. Consultar Estado y Desvincular

// Consultar estado de compatibilidad y vinculación
const status = biometrics.getStatus();
console.log(status); 
// { available: true, linked: true, credentialId: "..." }

// Desvincular localmente el dispositivo
biometrics.unlink();

Configuración Avanzada: Adaptador de Almacenamiento Personalizado

Puedes proveer tu propio adaptador si deseas guardar el credentialId o estado en una base de datos o almacenamiento alternativo:

import { KatrixBiometrics, StorageAdapter } from 'katrix-biometrics';

const customStorage: StorageAdapter = {
  get(key) {
    // Tu lógica para recuperar la clave (ej. cookies cifradas o API)
    return myCustomCookieGetter(key);
  },
  set(key, value) {
    // Tu lógica para persistir la clave
    myCustomCookieSetter(key, value);
  },
  remove(key) {
    myCustomCookieRemover(key);
  }
};

const biometrics = new KatrixBiometrics({
  appName: 'App Con Almacenamiento Especial',
  userId: 'user_999',
  userName: '[email protected]',
  storage: customStorage
});

Licencia

Este proyecto está bajo la Licencia MIT.