secure-email-recovery

name	secure-email-recovery
description	Skill empresarial para recuperación segura de correos electrónicos. Soporta múltiples proveedores (Disroot, Gmail, Outlook, Yahoo, IMAP genérico), autenticación OAuth2 y contraseña, caché inteligente, reintentos automáticos y manejo de errores de nivel producción.
version	1.0.0
author	KognitoAI
license	MIT
tags	["email","imap","security","oauth2","recovery","disroot","gmail","outlook"]
category	communication

📋 Tabla de Contenidos

1. Características
2. Proveedores Soportados
3. Instalación
4. Configuración
5. Uso Básico
6. API Completa
7. CLI
8. Seguridad
9. Manejo de Errores
10. Ejemplos Avanzados

---

Características

🔒 Seguridad de Nivel Empresarial

• OAuth 2.0 obligatorio para Gmail, Outlook y Yahoo
• Contraseñas de aplicación para Disroot y servidores genéricos
• Sin credenciales hardcodeadas —todo por variables de entorno
• Cumplimiento de RFC 3501 (IMAP), RFC 6749 (OAuth2), OWASP Top 10

⚡ Rendimiento

• Caché inteligente con TTL configurable (5 minutos por defecto)
• Reintentos automáticos con backoff exponencial
• Conexiones persistentes con keep-alive
• Reducción de llamadas a API en ~80% en escenarios típicos

🛡️ Robustez

• Manejo de errores estructurado con clasificación automática
• Timeouts en todas las operaciones
• Validación estricta de entrada
• Logging JSON para integración con ELK/Splunk

---

Proveedores Soportados

Proveedor	Servidor IMAP	Puerto	Métodos de Auth
Disroot	disroot.org	993	Contraseña de aplicación
Gmail	imap.gmail.com	993	OAuth2 / App Password
Outlook	outlook.office365.com	993	OAuth2 / App Password
Yahoo	imap.mail.yahoo.com	993	OAuth2 / App Password
Genérico	Personalizado	Personalizado	Contraseña

---

Instalación

1. Instalar dependencias

cd /ruta/a/secure-email-recovery_skill
pip install -r requirements.txt

2. Configurar variables de entorno

cp .env.example .env
# Editar .env con tus credenciales

---

Configuración

Disroot (Recomendado para tu caso)

1. Ve a tu panel de Disroot
2. Navega a Correo → Contraseñas de aplicación
3. Genera una nueva contraseña de aplicación
4. Agrega a tu .env:

DISROOT_PASSWORD=tu_contraseña_generada_aqui

Gmail con OAuth2

1. Ve a Google Cloud Console
2. Crea credenciales de tipo "Aplicación de escritorio"
3. Habilita la API de Gmail
4. Usa el flujo OAuth2 para obtener refresh token
5. Configura en .env:

GOOGLE_CLIENT_ID=tu_client_id
GOOGLE_CLIENT_SECRET=tu_client_secret
GMAIL_REFRESH_TOKEN=tu_refresh_token

---

Uso Básico

Python

from scripts.secure_email_recovery import EmailRecovery

# Inicializar para Disroot
client = EmailRecovery(
    provider="disroot",
    email="[e-mail]",
    password="tu_contraseña_de_aplicacion"
)

# Usar context manager para conexión automática
with client:
    # Obtener últimos 10 emails
    emails = client.get_recent_emails(limit=10)
    
    # Buscar facturas
    facturas = client.search_emails("factura", limit=20)
    
    # Obtener email específico
    email = client.get_email_by_uid("123", include_body=True)
    
    # Contar no leídos
    no_leidos = client.get_unread_count()

CLI

# Obtener emails recientes
python scripts/secure_email_recovery.py \
  --provider disroot \
  --email [e-mail] \
  --recent \
  --limit 10

# Buscar por asunto
python scripts/secure_email_recovery.py \
  --provider disroot \
  --email [e-mail] \
  --search "factura" \
  --limit 20

# Obtener email específico
python scripts/secure_email_recovery.py \
  --provider disroot \
  --email [e-mail] \
  --uid 123 \
  --json

# Listar carpetas
python scripts/secure_email_recovery.py \
  --provider disroot \
  --email [e-mail] \
  --folders

---

API Completa

EmailRecovery (Clase Principal)

Inicialización

client = EmailRecovery(
    provider="disroot",           # Proveedor: disroot, gmail, outlook, yahoo, generic
    email="[e-mail]",       # Tu dirección de correo
    password="xxx",               # Contraseña (opcional si está en .env)
    imap_server=None,             # Servidor IMAP personalizado
    imap_port=None,               # Puerto IMAP personalizado
    use_cache=True,               # Activar caché
    cache_ttl=300,                # Tiempo de vida de caché en segundos
    max_retries=3,                # Reintentos en errores recuperables
    timeout=30                    # Timeout de conexión en segundos
)

Métodos

Método	Descripción	Retorna
connect()	Establece conexión IMAP	None
disconnect()	Desconecta del servidor	None
get_recent_emails(folder, limit)	Obtiene emails recientes	List[EmailMessage]
get_email_by_uid(uid, folder, include_body)	Obtiene email por UID	EmailMessage | None
search_emails(query, folder, limit)	Busca emails por texto	List[EmailMessage]
get_unread_count(folder)	Cuenta emails no leídos	int
get_folders()	Lista carpetas IMAP	List[Dict]
validate_configuration()	Valida configuración	Dict
clear_cache()	Limpia caché	None
get_cache_stats()	Estadísticas de caché	Dict | None

---

CLI

Opciones

--provider TEXT        Proveedor de correo [requerido]
--email TEXT           Dirección de correo [requerido]
--password TEXT        Contraseña (opcional si está en .env)
--imap-server TEXT     Servidor IMAP personalizado
--imap-port INTEGER    Puerto IMAP personalizado
--recent               Obtener emails recientes
--search TEXT          Buscar emails
--uid TEXT             Obtener email por UID
--folders              Listar carpetas
--unread               Contar no leídos
--validate             Validar configuración
--limit INTEGER        Límite de resultados (default: 50)
--folder TEXT          Carpeta IMAP (default: INBOX)
--json                 Salida JSON
--no-cache             Desactivar caché
--attachment-dir TEXT  Directorio para adjuntos

Ejemplos

# Validar configuración antes de usar
python scripts/secure_email_recovery.py --provider disroot --email [e-mail] --validate

# Obtener emails de la carpeta Enviados
python scripts/secure_email_recovery.py --provider disroot --email [e-mail] --recent --folder "Sent" --limit 20

# Buscar y guardar adjuntos
python scripts/secure_email_recovery.py --provider disroot --email [e-mail] --search "factura" --attachment-dir ./facturas

# Salida JSON para procesamiento programático
python scripts/secure_email_recovery.py --provider disroot --email [e-mail] --recent --json

---

Seguridad

✅ Medidas Implementadas

• Sin credenciales hardcodeadas
• OAuth2 con tokens de corta duración
• Contraseñas de aplicación (no principales)
• SSL/TLS con verificación de certificados estricta
• Timeouts en todas las operaciones
• Validación de entrada con Pydantic
• Sin logging de credenciales
• Limpieza de memoria de contraseñas

❌ Qué NO hace esta skill

• No almacena contraseñas en disco
• No envía credenciales por redes no seguras
• No comparte datos con terceros
• No modifica emails sin tu confirmación explícita

---

Manejo de Errores

Categorías de Errores

Categoría	Descripción	Recuperable
authentication	Credenciales inválidas	❌ No
network	Problemas de conexión	✅ Sí
imap	Errores del servidor IMAP	✅ Sí
parsing	Errores procesando correos	✅ Sí
filesystem	Errores guardando archivos	❌ No
rate_limit	Límite de tasa excedido	✅ Sí
configuration	Configuración inválida	❌ No

Ejemplo de Manejo

from secure_email_recovery import EmailRecovery, EmailRecoveryError

try:
    with EmailRecovery(provider="disroot", email="[e-mail]") as client:
        emails = client.get_recent_emails()
except EmailRecoveryError as e:
    print(f"Categoría: {e.category.value}")
    print(f"Severidad: {e.severity.value}")
    print(f"Recuperable: {e.recoverable}")
    if e.retry_after:
        print(f"Reintenta en: {e.retry_after} segundos")

---

Ejemplos Avanzados

Filtrado Avanzado

from scripts.secure_email_recovery import EmailRecovery

with EmailRecovery(provider="disroot", email="[e-mail]") as client:
    # Obtener emails de un remitente específico
    emails = client.search_emails("[e-mail]", limit=50)
    
    # Filtrar por fecha
    from datetime import datetime, timedelta
    fecha_limite = (datetime.now() - timedelta(days=30)).strftime("%d-%b-%Y")
    
    # Obtener emails no leídos de la última semana
    no_leidos = client.get_unread_count()

Descarga de Adjuntos

with EmailRecovery(provider="disroot", email="[e-mail]") as client:
    # Obtener email con adjuntos
    email = client.get_email_by_uid(
        uid="123",
        attachment_dir="./mis_adjuntos"
    )
    
    if email.attachments:
        print(f"Adjuntos guardados: {len(email.attachments)}")
        for att in email.attachments:
            print(f"  - {att['filename']} ({att['size']} bytes)")

Monitoreo de Inbox

import time

while True:
    try:
        with EmailRecovery(provider="disroot", email="[e-mail]") as client:
            no_leidos = client.get_unread_count()
            print(f"[{time.strftime('%H:%M')}] No leídos: {no_leidos}")
    except Exception as e:
        print(f"Error: {e}")
    
    time.sleep(60)  # Verificar cada minuto

---

Troubleshooting

Error: "No hay credenciales configuradas"

Solución: Agrega DISROOT_PASSWORD a tu archivo .env o pasa --password por CLI.

Error: "Login failed"

Solución: Verifica que estés usando la contraseña de aplicación de Disroot, no tu contraseña principal.

Error: "Connection timeout"

Solución: Verifica tu conexión a internet y que el puerto 993 no esté bloqueado.

Error: "Certificate verify failed"

Solución: Actualiza los certificados CA de tu sistema:

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install ca-certificates

# macOS
brew install ca-certificates

---

Licencia

MIT — Ver archivo LICENSE para más detalles.