Modulo de Autenticacion y Seguridad
1. Historial de Versiones
2. Proposito
- 2.1. Arquitectura V1.0: Firebase Authentication
- 2.2. Metodos de Autenticacion Soportados
3. Actores y Roles
4. Precondiciones y Postcondiciones
- 4.1. Precondiciones para Autenticacion
- 4.2. Postcondiciones de Autenticacion Exitosa
5. Flujos de Autenticacion
6. Seguridad de Credenciales
7. Gestion de Sesiones
8. Autorizacion y Permisos
9. Recuperacion de Cuenta
10. Auditoria y Logs de Seguridad
- 10.1. Eventos Auditados
- 10.2. Alertas de Seguridad
11. Integracion con Otros Modulos
- 11.1. Dependencias
- 11.2. APIs Expuestas
12. Requisitos Regulatorios
- 12.1. Cumplimiento de Normativas
- 12.2. Referencias Cruzadas
13. Criterios de Aceptacion
14. Glosario

Modulo de Autenticacion y Seguridad¶

Identificador: MTS-AUTH-001 Version: 2.5.0 Fecha de ultima actualizacion: 2025-12-05 Estado: Aprobado Autor: SpecQueen Revisores: Director del Proyecto

1. Historial de Versiones¶

Version	Fecha	Autor	Cambios
2.5.0	2025-12-05	SpecQueen	CRITICO: Email/Password NO disponible V1.0 - solo auth social (Google/Apple)
2.4.0	2025-12-05	SpecQueen	OBS-058: V1.0 solo Firebase Auth, 4 roles claros, cuidadores siempre Free, flujos sin ambiguedad
2.3.0	2025-12-05	SpecQueen	Iteracion 13: ACL diferenciados por tier, correcciones de coherencia
2.2.0	2025-12-04	SpecQueen	Iteracion 12: MFA diferenciado por tier, recuperacion diferenciada
2.1.0	2025-12-03	SpecQueen	Iteracion 11: Roles y tiers correctamente documentados
2.0.0	2025-12-01	SpecQueen	Reestructuracion completa con 4 roles y 3 tiers

2. Proposito¶

Este modulo especifica los mecanismos de autenticacion, autorizacion y seguridad de acceso para MedTime V1.0. Define como los usuarios se autentican, como se protegen sus credenciales, y como se gestionan las sesiones de forma segura.

2.1. Arquitectura V1.0: Firebase Authentication¶

IMPORTANTE: MedTime V1.0 utilizaexclusivamente Firebase Authentication como proveedor de identidad. No existe backend propio para autenticacion en V1.0.

ARQUITECTURA DE AUTENTICACION V1.0:

+------------------+     +------------------+     +------------------+
|   APP MOVIL      |     |  FIREBASE AUTH   |     |  FIREBASE        |
|   (Cliente)      |     |  (Proveedor ID)  |     |  (Storage/DB)    |
+------------------+     +------------------+     +------------------+
|                  |     |                  |     |                  |
| - UI Login       |<--->| - Google Sign-In |     | - Firestore      |
| - SDK Firebase   |     | - Apple Sign-In  |     | - Cloud Storage  |
| - Clave local    |     | - Email/Password |     | - Blobs cifrados |
|                  |     | - MFA (TOTP)     |     |                  |
+------------------+     +------------------+     +------------------+

FLUJO:
1. Usuario inicia sesion via Firebase Auth (Google/Apple)
2. Firebase devuelve JWT token
3. App usa token para acceder a Firestore/Storage
4. Datos sensibles se cifran/descifran LOCALMENTE con clave derivada
5. Firebase NUNCA ve datos en claro (Zero-Knowledge)

2.2. Metodos de Autenticacion Soportados¶

Metodo	Tier Free	Tier Pro	Tier Perfect	Notas
Google Sign-In	Si	Si	Si	OAuth 2.0 via Firebase
Apple Sign-In	Si	Si	Si	Sign in with Apple via Firebase
Email/Password	No	No	No	NO disponible V1.0 (planificado v1.5+)
MFA (TOTP)	No	Opcional	Obligatorio	Google Authenticator, Authy

Nota V1.0: Solo autenticacion social (Google Sign-In, Apple Sign-In) esta disponible en V1.0 por decision del Director. Email/password se implementara en v1.5+.

Nota: En V1.0 no hay autenticacion biometrica para login. La biometria se usa solo para desbloqueo local de la app (ver seccion 5.3).

3. Actores y Roles¶

3.1. Los 4 Roles de MedTime¶

MedTime define exactamente 4 roles de usuario, cada uno con caracteristicas especificas:

Rol	Codigo	Titular de Cuenta	Selecciona Tier	Descripcion
Paciente Independiente	PI	Si	Si (Free/Pro/Perfect)	Adulto que gestiona su propia medicacion
Paciente Dependiente	PD	No	No (hereda del CR)	Menor o persona bajo tutela, gestionado por CR
Cuidador Solidario	CS	Si	No (siempre Free)	Voluntario que apoya a un PI
Cuidador Responsable	CR	Si	Si (Free/Pro/Perfect)	Responsable legal de uno o mas PD

3.2. Matriz de Roles y Tiers¶

                    +------------------+------------------+------------------+
                    |     FREE         |      PRO         |     PERFECT      |
+-------------------+------------------+------------------+------------------+
| Paciente          | PI-Free          | PI-Pro           | PI-Perfect       |
| Independiente     | Cuenta local     | Cloud sync       | Cloud premium    |
|                   | Sin verificacion | Email verificado | MFA obligatorio  |
+-------------------+------------------+------------------+------------------+
| Cuidador          | CR-Free          | CR-Pro           | CR-Perfect       |
| Responsable       | 1 dependiente    | 5 dependientes   | 10 dependientes  |
|                   | Cuenta local     | Cloud sync       | Cloud premium    |
+-------------------+------------------+------------------+------------------+
| Cuidador          | CS-Free UNICO    | N/A              | N/A              |
| Solidario         | Siempre Free     | (no disponible)  | (no disponible)  |
|                   | Vinculado a PI   |                  |                  |
+-------------------+------------------+------------------+------------------+
| Paciente          | PD (hereda tier) | PD (hereda tier) | PD (hereda tier) |
| Dependiente       | Sin cuenta propia| Sin cuenta propia| Sin cuenta propia|
|                   | Perfil en CR     | Perfil en CR     | Perfil en CR     |
+-------------------+------------------+------------------+------------------+

3.3. Reglas de Negocio para Roles¶

Regla	Descripcion
RN-AUTH-001	Un CSsiempre tiene tier Free, independientemente del tier del PI que lo invito
RN-AUTH-002	Un PDno tiene cuenta propia; su perfil existe dentro de la cuenta del CR
RN-AUTH-003	Un PI puede tener multiples CS vinculados (segun limite de su tier)
RN-AUTH-004	Un CR puede gestionar multiples PD (segun limite de su tier: Free=1, Pro=5, Perfect=10)
RN-AUTH-005	Un usuario no puede ser simultaneamente PI y CR con la misma cuenta
RN-AUTH-006	Un CS puede estar vinculado a multiples PI (sin limite)

4. Precondiciones y Postcondiciones¶

4.1. Precondiciones para Autenticacion¶

Rol	Precondiciones
PI/CR	Dispositivo con acceso a Internet (primera vez), app instalada
CS	Invitacion recibida de un PI, dispositivo con app instalada
PD	Perfil creado por CR, sin precondiciones propias

4.2. Postcondiciones de Autenticacion Exitosa¶

Condicion	Descripcion
Token valido	Firebase JWT activo con claims de rol y tier
Sesion local	Datos de sesion almacenados de forma segura
Clave derivada	Master key disponible para cifrado/descifrado
Sincronizacion	Datos locales sincronizados con cloud (Pro/Perfect)

5. Flujos de Autenticacion¶

5.1. Flujo: Registro de Paciente Independiente (PI)¶

sequenceDiagram
    participant U as Usuario
    participant A as App MedTime
    participant F as Firebase Auth
    participant FS as Firestore

    U->>A: Abrir app primera vez
    A->>U: Mostrar pantalla de bienvenida
    U->>A: Seleccionar "Soy Paciente"
    A->>U: Mostrar opciones de tier (Free/Pro/Perfect)

    alt Tier Free
        U->>A: Seleccionar Free
        A->>U: Solicitar PIN local (4-6 digitos)
        U->>A: Crear PIN
        A->>A: Generar Master Key local
        A->>A: Almacenar en Keychain/Keystore
        A->>U: Registro completado (offline-first)
    else Tier Pro/Perfect
        U->>A: Seleccionar Pro o Perfect
        A->>U: Mostrar opciones de login
        U->>A: Seleccionar Google/Apple/Email
        A->>F: Iniciar OAuth flow
        F->>U: Pantalla de autenticacion Google/Apple
        U->>F: Autenticar
        F->>A: Devolver JWT token
        A->>A: Generar Master Key
        A->>FS: Crear perfil usuario (metadata)

        alt Tier Perfect
            A->>U: Configurar MFA obligatorio
            U->>A: Escanear QR TOTP
            U->>A: Verificar codigo TOTP
            A->>F: Registrar segundo factor
        end

        A->>U: Registro completado
    end

5.2. Flujo: Registro de Cuidador Responsable (CR)¶

sequenceDiagram
    participant U as Usuario
    participant A as App MedTime
    participant F as Firebase Auth
    participant FS as Firestore

    U->>A: Abrir app primera vez
    A->>U: Mostrar pantalla de bienvenida
    U->>A: Seleccionar "Soy Cuidador Responsable"
    A->>U: Mostrar opciones de tier (Free/Pro/Perfect)

    U->>A: Seleccionar tier

    Note over A,U: Flujo de autenticacion igual que PI

    A->>U: Mostrar declaracion de tutela
    U->>A: Aceptar declaracion jurada
    A->>U: Solicitar datos del primer dependiente
    U->>A: Ingresar datos del PD
    A->>FS: Crear perfil PD vinculado a CR
    A->>U: Registro completado

5.3. Flujo: Registro de Cuidador Solidario (CS)¶

IMPORTANTE: El CSsiempre es tier Free, independientemente del tier del PI que lo invita.

sequenceDiagram
    participant PI as Paciente (PI)
    participant A1 as App PI
    participant E as Email/SMS
    participant CS as Cuidador Solidario
    participant A2 as App CS
    participant F as Firebase Auth
    participant FS as Firestore

    PI->>A1: Ir a "Mis Cuidadores"
    A1->>PI: Mostrar opcion "Invitar Cuidador"
    PI->>A1: Ingresar email/telefono del CS
    A1->>A1: Generar token de invitacion
    A1->>FS: Guardar invitacion pendiente
    A1->>E: Enviar invitacion

    E->>CS: Recibir invitacion con link
    CS->>A2: Abrir link / instalar app
    A2->>FS: Verificar token de invitacion
    FS->>A2: Invitacion valida

    A2->>CS: Mostrar detalles de invitacion
    Note over A2,CS: "Juan te invita como cuidador solidario"

    alt CS no tiene cuenta
        CS->>A2: Crear cuenta
        A2->>CS: Solicitar datos basicos
        CS->>A2: Ingresar nombre y PIN
        Note over A2: Cuenta CS siempre Free
        A2->>F: Crear cuenta Firebase (opcional email)
        A2->>A2: Generar Master Key local
    else CS ya tiene cuenta
        CS->>A2: Iniciar sesion
        A2->>F: Autenticar
    end

    A2->>CS: Mostrar permisos ofrecidos
    CS->>A2: Aceptar vinculacion
    A2->>FS: Crear relacion CS-PI
    A2->>CS: Vinculacion completada
    A1->>PI: Notificar aceptacion

sequenceDiagram
    participant U as Usuario
    participant A as App MedTime
    participant F as Firebase Auth
    participant FS as Firestore

    U->>A: Abrir app
    A->>A: Verificar sesion local

    alt Sesion local valida
        A->>U: Solicitar PIN/biometria
        U->>A: Ingresar PIN o usar biometria
        A->>A: Desbloquear Master Key
        A->>U: Acceso concedido
    else Sesion expirada (Pro/Perfect)
        A->>U: Mostrar pantalla login
        U->>A: Seleccionar Google/Apple/Email
        A->>F: Autenticar
        F->>A: JWT token

        alt Usuario tiene MFA (Perfect)
            A->>U: Solicitar codigo TOTP
            U->>A: Ingresar codigo
            A->>F: Verificar segundo factor
        end

        A->>FS: Obtener perfil usuario
        A->>A: Restaurar Master Key
        A->>U: Acceso concedido
    end

5.5. Flujo: Upgrade de Tier (Free a Pro/Perfect)¶

sequenceDiagram
    participant U as Usuario (PI o CR)
    participant A as App MedTime
    participant F as Firebase Auth
    participant FS as Firestore
    participant P as Procesador Pago

    Note over U: Usuario actualmente Free

    U->>A: Ir a Configuracion > Mi Plan
    A->>U: Mostrar comparativa de tiers
    U->>A: Seleccionar Pro o Perfect

    alt Usuario Free sin cuenta Firebase
        A->>U: Requiere crear cuenta para sincronizar
        U->>A: Seleccionar Google/Apple/Email
        A->>F: Crear cuenta Firebase
        F->>A: JWT token
    end

    A->>P: Iniciar proceso de pago
    P->>U: Mostrar opciones de pago
    U->>P: Completar pago
    P->>A: Confirmar pago exitoso

    A->>FS: Actualizar tier del usuario

    alt Upgrade a Perfect
        A->>U: Configurar MFA obligatorio
        U->>A: Escanear QR TOTP
        U->>A: Verificar codigo
        A->>F: Registrar segundo factor
    end

    A->>A: Migrar datos locales a cloud
    A->>U: Upgrade completado

6. Seguridad de Credenciales¶

6.1. Almacenamiento Seguro de Master Key¶

Plataforma	Metodo de Almacenamiento	Proteccion
iOS	Keychain Services	Secure Enclave, Face ID/Touch ID
Android	Android Keystore	Hardware-backed, Biometric

GENERACION DE MASTER KEY:

1. Usuario crea PIN o se autentica via Firebase
2. App genera salt aleatorio (32 bytes)
3. Deriva Master Key usando Argon2id:
   - PIN/password + salt
   - Parametros: memory=64MB, iterations=3, parallelism=4
4. Master Key se almacena cifrada en Keychain/Keystore
5. Salt se almacena junto con datos cifrados

6.2. Proteccion de PIN Local¶

Aspecto	Implementacion
Longitud	4-6 digitos
Intentos maximos	5 intentos antes de bloqueo
Bloqueo progresivo	1 min, 5 min, 15 min, 1 hora
Datos derivados	PIN nunca se almacena, solo se usa para derivar clave

6.3. Desbloqueo Biometrico (Opcional)¶

Nota: La biometria se usa solo para desbloquear la app localmente, NO para autenticacion en Firebase.

Caracteristica	Descripcion
Face ID / Touch ID (iOS)	Opcional, configurable por usuario
Fingerprint / Face (Android)	Opcional, configurable por usuario
Fallback	Siempre solicita PIN si biometria falla 3 veces
Master Key	Biometria desbloquea acceso a Master Key en Keychain

7. Gestion de Sesiones¶

7.1. Duracion de Sesiones por Tier¶

Tier	Sesion Local	Sesion Firebase	Reautenticacion
Free	Indefinida	N/A (sin cloud)	Solo PIN/biometria
Pro	30 dias	30 dias	Requiere login Firebase
Perfect	7 dias	7 dias	Requiere login + MFA

7.2. Politica de Sesiones Multidispositivo¶

Tier	Dispositivos Simultaneos	Comportamiento
Free	1 (datos locales)	N/A - sin sincronizacion
Pro	3	Sesiones independientes, sync automatico
Perfect	5	Sesiones independientes, control desde panel

7.3. Revocacion de Sesiones¶

Evento	Accion
Usuario cierra sesion	Invalida sesion actual, mantiene datos locales cifrados
Cambio de password	Invalida todas las sesiones excepto actual
Upgrade/Downgrade tier	Mantiene sesion, actualiza permisos
Cuenta eliminada	Invalida todas las sesiones, elimina datos cloud

8. Autorizacion y Permisos¶

8.1. Permisos por Rol¶

Permiso	PI	PD	CS	CR
Ver mis medicamentos	Si	Lectura*	No	No
Editar mis medicamentos	Si	No	No	No
Ver medicamentos de paciente	-	-	Si (asignados)	Si (dependientes)
Editar medicamentos de paciente	-	-	No	Si
Confirmar toma propia	Si	Si*	No	No
Confirmar toma de paciente	-	-	Si (si autorizado)	Si
Ver estadisticas propias	Si	No	No	No
Ver estadisticas de paciente	-	-	Si (si autorizado)	Si
Invitar cuidador	Si (Pro/Perfect)	No	No	Si (Pro/Perfect)
Agregar dependiente	No	No	No	Si

*PD: Acceso opcional controlado por CR segun edad (ver MTS-ONB-001)

8.2. Matriz de Permisos CS (Granular)¶

El PI define que permisos otorga a cada CS:

Permiso	Codigo	Descripcion	Default
Ver medicamentos	`ver_medicamentos`	Ver lista de medicamentos del PI	Si
Ver adherencia	`ver_adherencia`	Ver estadisticas de tomas	Si
Registrar tomas	`registrar_tomas`	Confirmar toma en nombre del PI	No
Recibir alertas de omision	`recibir_alertas_tomas`	Notificacion si PI omite toma	Si
Ver recetas	`ver_recetas`	Acceso a recetas digitalizadas	No
Ver citas	`ver_citas`	Ver agenda de citas medicas	No
Ver analisis	`ver_analisis`	Ver resultados de laboratorio	No

8.3. Reglas de Autorizacion¶

Regla	Descripcion
RN-AUTH-010	Un CS solo ve datos del PI si tiene permisos activos
RN-AUTH-011	Un CR tiene acceso completo a todos los datos de sus PD
RN-AUTH-012	Un PD mayor de 13 puede solicitar acceso lectura a su perfil
RN-AUTH-013	Al cumplir 18, un PD debe migrar a cuenta PI autonoma
RN-AUTH-014	Un PI puede revocar permisos de CS en cualquier momento

9. Recuperacion de Cuenta¶

9.1. Escenarios de Recuperacion por Tier¶

Escenario	Free	Pro	Perfect
Olvido de PIN	Reinicio local (pierde datos)	Recuperacion via Firebase	Recuperacion via Firebase + MFA
Perdida de dispositivo	Datos perdidos	Restaurar desde cloud	Restaurar desde cloud
Olvido de email/password	N/A	Reset via Firebase	Reset via Firebase + verificacion

9.2. Flujo: Recuperacion Tier Free (Reinicio Local)¶

ADVERTENCIA: En tier Free, olvidar el PIN implica perder todos los datos locales.

sequenceDiagram
    participant U as Usuario
    participant A as App MedTime

    U->>A: Olvide mi PIN
    A->>U: Advertencia: Reiniciar borrara todos los datos
    U->>A: Confirmar reinicio
    A->>A: Eliminar todos los datos locales
    A->>A: Eliminar Master Key
    A->>U: App reiniciada
    A->>U: Iniciar onboarding como usuario nuevo

9.3. Flujo: Recuperacion Tier Pro/Perfect¶

sequenceDiagram
    participant U as Usuario
    participant A as App MedTime
    participant F as Firebase Auth
    participant FS as Firestore

    U->>A: No puedo acceder a mi cuenta
    A->>U: Opciones de recuperacion

    alt Olvido password
        U->>A: Olvide mi password
        A->>F: Solicitar reset de password
        F->>U: Email con link de reset
        U->>F: Crear nuevo password
        F->>A: Confirmar reset
    end

    A->>U: Iniciar sesion con nuevas credenciales
    U->>A: Autenticar
    A->>F: Verificar credenciales

    alt Tier Perfect
        A->>U: Verificar MFA
        U->>A: Codigo TOTP
        A->>F: Verificar segundo factor
    end

    A->>FS: Obtener perfil y datos
    A->>A: Re-derivar Master Key
    A->>U: Cuenta recuperada

9.4. Recovery Key (Perfect)¶

Los usuarios Perfect tienen acceso a una Recovery Key para emergencias:

Caracteristica	Descripcion
Generacion	Durante setup inicial de MFA
Formato	24 palabras BIP-39
Uso	Recuperar acceso si pierde dispositivo MFA
Almacenamiento	Usuario debe guardar offline (papel, caja fuerte)

10. Auditoria y Logs de Seguridad¶

10.1. Eventos Auditados¶

Evento	Datos Registrados	Retencion
Login exitoso	user_hash, timestamp, device, IP_hash	90 dias
Login fallido	user_hash (si existe), timestamp, IP_hash	90 dias
Cambio de password	user_hash, timestamp	5 anos
Activacion MFA	user_hash, timestamp, metodo	5 anos
Sesion revocada	user_hash, session_id, razon	90 dias
Upgrade/Downgrade tier	user_hash, tier_anterior, tier_nuevo	5 anos

10.2. Alertas de Seguridad¶

Condicion	Accion
5 intentos fallidos de login	Bloqueo temporal + notificacion al usuario
Login desde nuevo dispositivo	Notificacion push al dispositivo conocido
Login desde nueva ubicacion	Email de verificacion (Pro/Perfect)
Cambio de password	Email de confirmacion

11. Integracion con Otros Modulos¶

11.1. Dependencias¶

Modulo	Tipo	Descripcion
MTS-PRI-001	Requiere	Consentimientos para tratamiento de datos
MTS-ONB-001	Requiere	Flujos de onboarding por rol y tier
MTS-BCK-001	Requiere	Backup de claves cifradas
MTS-SEC-001	Requiere	Cifrado E2E y zero-knowledge

11.2. APIs Expuestas¶

Endpoint Conceptual	Descripcion	Autenticacion
auth/register	Registro de nuevo usuario	Ninguna
auth/login	Inicio de sesion	Firebase Auth
auth/mfa/setup	Configurar segundo factor	Firebase Auth + Perfect
auth/mfa/verify	Verificar codigo TOTP	Firebase Auth
auth/session/revoke	Revocar sesion	Firebase Auth
auth/password/reset	Solicitar reset	Email verificado

12. Requisitos Regulatorios¶

12.1. Cumplimiento de Normativas¶

Normativa	Requisito	Implementacion
LFPDPPP (Mexico)	Consentimiento para datos sensibles	Flujo explicito en onboarding
LGPD (Brasil)	Base legal para tratamiento	Consentimiento y contrato
HIPAA (USA)	Control de acceso	RBAC, MFA, audit logs
FDA 21 CFR Part 11	Firmas electronicas	Hash de consentimientos

12.2. Referencias Cruzadas¶

Ver MTS-PRI-001 para detalles de consentimiento
Ver INV-009 para analisis LFPDPPP
Ver INV-011 para auditoria

13. Criterios de Aceptacion¶

13.1. Autenticacion¶

Usuario puede registrarse como PI seleccionando tier
Usuario puede registrarse como CR y agregar dependientes
CS puede aceptar invitacion y crear cuenta Free
Login con Google/Apple funciona correctamente
MFA es obligatorio para tier Perfect
MFA es opcional para tier Pro

13.2. Seguridad¶

Master Key se almacena en Keychain/Keystore
PIN se valida con limite de intentos
Biometria desbloquea app correctamente
Sesiones expiran segun tier

13.3. Recuperacion¶

Usuario Free puede reiniciar app (perdiendo datos)
Usuario Pro puede recuperar via Firebase
Usuario Perfect puede recuperar con Recovery Key

14. Glosario¶

Termino	Definicion
Master Key	Clave criptografica derivada de credenciales, usada para cifrado E2E
Firebase Auth	Servicio de Google para autenticacion de usuarios
JWT	JSON Web Token, formato de token de autenticacion
TOTP	Time-based One-Time Password, algoritmo para MFA
Keychain	Sistema de almacenamiento seguro de iOS
Keystore	Sistema de almacenamiento seguro de Android
Zero-Knowledge	Arquitectura donde el servidor no puede ver datos en claro

Documento generado por SpecQueen - "La autenticacion es la puerta de entrada. Esta especificacion es la llave perfecta."