# Biometrics Module

## Descripcion

Modulo de autenticacion biometrica para dispositivos moviles y web. Soporta fingerprint, Face ID, reconocimiento facial y escaneo de iris. Gestiona dispositivos registrados, credenciales biometricas (WebAuthn/FIDO2), sesiones y log de actividad.

**Arquitectura:** Este modulo implementa un **servicio de solo lectura**. La funcionalidad de escritura (crear, modificar, eliminar dispositivos y credenciales) se maneja desde el modulo `auth`.

## Entidades

| Entidad | Schema | Descripcion |
|---------|--------|-------------|
| `Device` | auth.devices | Dispositivos registrados con informacion de plataforma, biometricos y ubicacion |
| `BiometricCredential` | auth.biometric_credentials | Credenciales WebAuthn/FIDO2 vinculadas a dispositivos |
| `DeviceSession` | auth.device_sessions | Sesiones activas por dispositivo con tokens y metodo de autenticacion |
| `DeviceActivityLog` | auth.device_activity_log | Log de actividad: logins, autenticaciones biometricas, ubicaciones |

## Servicios

### BiometricsService

Servicio de solo lectura que proporciona metodos para consultar:

- **Dispositivos:** `findDevicesByUserId`, `findDeviceById`, `findDeviceByUuid`
- **Credenciales:** `findCredentialsByUserId`, `findCredentialsByDeviceId`, `findCredentialById`
- **Enrollment:** `getEnrollmentStatus`
- **Sesiones:** `findSessionsByUserId`, `findActiveSessionsByUserId`, `countActiveSessions`
- **Actividad:** `findActivityByUserId`, `findActivityByDeviceId`, `getVerificationStats`

## Endpoints (Solo lectura)

Los endpoints exponen funcionalidad GET para consultar datos biometricos:

| Method | Path | Descripcion |
|--------|------|-------------|
| GET | `/api/v1/biometrics/devices` | Lista dispositivos del usuario |
| GET | `/api/v1/biometrics/devices/:deviceId` | Obtiene dispositivo por ID |
| GET | `/api/v1/biometrics/credentials` | Lista credenciales biometricas |
| GET | `/api/v1/biometrics/credentials/:credentialId` | Obtiene credencial por ID |
| GET | `/api/v1/biometrics/enrollment/status` | Estado de enrollment biometrico |
| GET | `/api/v1/biometrics/sessions` | Lista sesiones del usuario |
| GET | `/api/v1/biometrics/sessions/active` | Sesiones activas |
| GET | `/api/v1/biometrics/activity` | Log de actividad |
| GET | `/api/v1/biometrics/activity/stats` | Estadisticas de verificacion |

### Query Parameters

| Endpoint | Parametros |
|----------|------------|
| `/devices` | `platform`, `isActive`, `biometricEnabled`, `page`, `limit` |
| `/credentials` | `biometricType`, `isActive`, `page`, `limit` |
| `/sessions` | `isActive`, `page`, `limit` |
| `/activity` | `activityType`, `activityStatus`, `startDate`, `endDate`, `page`, `limit` |
| `/activity/stats` | `startDate`, `endDate` |

## Endpoints de Escritura (en modulo `auth`)

La funcionalidad de escritura se expone a traves del modulo `auth`:

| Method | Path | Descripcion |
|--------|------|-------------|
| POST | `/auth/devices/register` | Registra nuevo dispositivo |
| DELETE | `/auth/devices/:id` | Elimina dispositivo |
| POST | `/auth/biometric/register` | Registra credencial biometrica |
| POST | `/auth/biometric/authenticate` | Autentica con biometrico |
| DELETE | `/auth/biometric/:id` | Elimina credencial biometrica |

## Dependencias

- `auth` - Modulo de autenticacion principal (escritura)
- `typeorm` - ORM para acceso a datos
- WebAuthn/FIDO2 library (configurado en auth)

## Configuracion

| Variable | Descripcion | Requerida |
|----------|-------------|-----------|
| `WEBAUTHN_RP_ID` | Relying Party ID (dominio) | Si |
| `WEBAUTHN_RP_NAME` | Nombre de la aplicacion | Si |
| `WEBAUTHN_ORIGIN` | Origen permitido | Si |

## Tipos Biometricos Soportados

| Tipo | Descripcion | Plataformas |
|------|-------------|-------------|
| `fingerprint` | Huella dactilar | iOS, Android, Windows Hello |
| `face_id` | Face ID de Apple | iOS |
| `face_recognition` | Reconocimiento facial | Android, Windows Hello |
| `iris` | Escaneo de iris | Dispositivos especializados |

## Plataformas Soportadas

| Plataforma | Descripcion |
|------------|-------------|
| `ios` | iPhone/iPad |
| `android` | Dispositivos Android |
| `web` | Navegadores con WebAuthn |
| `desktop` | Aplicaciones de escritorio |

## Niveles de Confianza

| Nivel | Valor | Descripcion |
|-------|-------|-------------|
| None | 0 | Dispositivo nuevo/no verificado |
| Low | 1 | Primera autenticacion biometrica |
| Medium | 2 | Uso regular sin incidentes |
| High | 3 | Dispositivo de confianza establecida |

## Seguridad

- Las credenciales biometricas usan algoritmo ES256 (ECDSA con SHA-256)
- Lock temporal despues de N intentos fallidos
- Registro de todas las actividades para auditoria
- Soporte para multiples credenciales por dispositivo

## Uso

```typescript
import { BiometricsModule } from './modules/biometrics';
import { DataSource } from 'typeorm';

// Inicializar modulo
const biometricsModule = new BiometricsModule({
  dataSource: myDataSource,
  basePath: '/biometrics',
});

// Usar en Express app
app.use('/api/v1', authMiddleware, biometricsModule.router);

// Acceder al servicio directamente
const enrollmentStatus = await biometricsModule.biometricsService.getEnrollmentStatus(userId);
```

## Estructura del Modulo

```
biometrics/
├── biometrics.controller.ts  # Controller con endpoints GET
├── biometrics.module.ts      # Configuracion del modulo
├── biometrics.routes.ts      # Definicion de rutas
├── index.ts                  # Exports publicos
├── README.md                 # Esta documentacion
├── dto/
│   ├── biometrics.dto.ts     # DTOs de query y response
│   └── index.ts
├── entities/
│   ├── device.entity.ts
│   ├── biometric-credential.entity.ts
│   ├── device-session.entity.ts
│   ├── device-activity-log.entity.ts
│   └── index.ts
└── services/
    ├── biometrics.service.ts # Servicio de solo lectura
    └── index.ts
```
